From 7fab5325f7be758f8f69b10fbffbb6093adf3be0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 04:21:33 +0100 Subject: [PATCH 01/65] feat(client): add TypeScript SDK --- bun.lock | 91 +- config/biome.config.json | 1 + package.json | 8 +- packages/client/openapi-ts.config.ts | 13 + packages/client/package.json | 44 + packages/client/src/__tests__/client.test.ts | 132 ++ packages/client/src/client.ts | 28 + packages/client/src/errors.ts | 20 + packages/client/src/generated/client.gen.ts | 27 + .../client/src/generated/client/client.gen.ts | 268 ++++ packages/client/src/generated/client/index.ts | 26 + .../client/src/generated/client/types.gen.ts | 269 ++++ .../client/src/generated/client/utils.gen.ts | 337 +++++ .../client/src/generated/core/auth.gen.ts | 42 + .../src/generated/core/bodySerializer.gen.ts | 100 ++ .../client/src/generated/core/params.gen.ts | 176 +++ .../src/generated/core/pathSerializer.gen.ts | 180 +++ .../generated/core/queryKeySerializer.gen.ts | 136 ++ .../generated/core/serverSentEvents.gen.ts | 264 ++++ .../client/src/generated/core/types.gen.ts | 118 ++ .../client/src/generated/core/utils.gen.ts | 143 ++ packages/client/src/generated/index.ts | 4 + packages/client/src/generated/sdk.gen.ts | 631 +++++++++ packages/client/src/generated/types.gen.ts | 1208 +++++++++++++++++ packages/client/src/index.ts | 16 + packages/client/src/rest.ts | 177 +++ packages/client/src/session.ts | 40 + packages/client/src/types.ts | 79 ++ packages/client/tsconfig.json | 23 + release-please-config.json | 5 + scripts/bump-version.mjs | 1 + scripts/publish-packages.mjs | 1 + tsconfig.json | 3 + 33 files changed, 4597 insertions(+), 14 deletions(-) create mode 100644 packages/client/openapi-ts.config.ts create mode 100644 packages/client/package.json create mode 100644 packages/client/src/__tests__/client.test.ts create mode 100644 packages/client/src/client.ts create mode 100644 packages/client/src/errors.ts create mode 100644 packages/client/src/generated/client.gen.ts create mode 100644 packages/client/src/generated/client/client.gen.ts create mode 100644 packages/client/src/generated/client/index.ts create mode 100644 packages/client/src/generated/client/types.gen.ts create mode 100644 packages/client/src/generated/client/utils.gen.ts create mode 100644 packages/client/src/generated/core/auth.gen.ts create mode 100644 packages/client/src/generated/core/bodySerializer.gen.ts create mode 100644 packages/client/src/generated/core/params.gen.ts create mode 100644 packages/client/src/generated/core/pathSerializer.gen.ts create mode 100644 packages/client/src/generated/core/queryKeySerializer.gen.ts create mode 100644 packages/client/src/generated/core/serverSentEvents.gen.ts create mode 100644 packages/client/src/generated/core/types.gen.ts create mode 100644 packages/client/src/generated/core/utils.gen.ts create mode 100644 packages/client/src/generated/index.ts create mode 100644 packages/client/src/generated/sdk.gen.ts create mode 100644 packages/client/src/generated/types.gen.ts create mode 100644 packages/client/src/index.ts create mode 100644 packages/client/src/rest.ts create mode 100644 packages/client/src/session.ts create mode 100644 packages/client/src/types.ts create mode 100644 packages/client/tsconfig.json diff --git a/bun.lock b/bun.lock index 2bacef502..49965293f 100644 --- a/bun.lock +++ b/bun.lock @@ -17,7 +17,7 @@ }, "packages/agent-worker": { "name": "@lobu/worker", - "version": "9.1.0", + "version": "9.1.1", "bin": { "lobu-worker": "./dist/index.js", }, @@ -44,7 +44,7 @@ }, "packages/cli": { "name": "@lobu/cli", - "version": "9.1.0", + "version": "9.1.1", "bin": { "lobu": "bin/lobu.js", }, @@ -127,9 +127,20 @@ "isolated-vm": "^6.1.2", }, }, + "packages/client": { + "name": "@lobu/client", + "version": "9.1.1", + "dependencies": { + "@hey-api/client-fetch": "^0.13.1", + }, + "devDependencies": { + "@hey-api/openapi-ts": "^0.86.5", + "typescript": "^5.8.3", + }, + }, "packages/connector-sdk": { "name": "@lobu/connector-sdk", - "version": "9.1.0", + "version": "9.1.1", "dependencies": { "@lobu/core": "workspace:*", "@sinclair/typebox": "^0.34.41", @@ -153,7 +164,7 @@ }, "packages/connector-worker": { "name": "@lobu/connector-worker", - "version": "9.1.0", + "version": "9.1.1", "bin": { "connector-worker": "./dist/bin.js", }, @@ -176,7 +187,7 @@ }, "packages/connectors": { "name": "@lobu/connectors", - "version": "9.1.0", + "version": "9.1.1", "dependencies": { "@lobu/connector-sdk": "workspace:*", "baileys": "7.0.0-rc.9", @@ -190,7 +201,7 @@ }, "packages/core": { "name": "@lobu/core", - "version": "9.1.0", + "version": "9.1.1", "dependencies": { "@opentelemetry/api": "^1.9.0", "@opentelemetry/exporter-trace-otlp-grpc": "^0.57.0", @@ -209,7 +220,7 @@ }, "packages/embeddings": { "name": "@lobu/embeddings", - "version": "9.1.0", + "version": "9.1.1", "dependencies": { "@hono/node-server": "^1.13.7", "@xenova/transformers": "^2.17.2", @@ -241,7 +252,7 @@ }, "packages/openclaw-plugin": { "name": "@lobu/openclaw-plugin", - "version": "9.1.0", + "version": "9.1.1", "dependencies": { "@lobu/core": "workspace:*", }, @@ -326,7 +337,7 @@ }, "packages/pgvector-embedded": { "name": "@lobu/pgvector-embedded", - "version": "9.1.0", + "version": "9.1.1", "devDependencies": { "@types/node": "20.19.9", "typescript": "^5.7.2", @@ -334,7 +345,7 @@ }, "packages/promptfoo-provider": { "name": "@lobu/promptfoo-provider", - "version": "9.1.0", + "version": "9.1.1", "devDependencies": { "@types/node": "^20.10.0", "typescript": "^5.3.3", @@ -850,6 +861,14 @@ "@hexagon/base64": ["@hexagon/base64@1.1.28", "", {}, "sha512-lhqDEAvWixy3bZ+UOYbPwUbBkwBq5C1LAJ/xPC8Oi+lL54oyakv/npbA0aU2hgCsx/1NUd4IBvV03+aUBWxerw=="], + "@hey-api/client-fetch": ["@hey-api/client-fetch@0.13.1", "", { "peerDependencies": { "@hey-api/openapi-ts": "< 2" } }, "sha512-29jBRYNdxVGlx5oewFgOrkulZckpIpBIRHth3uHFn1PrL2ucMy52FvWOY3U3dVx2go1Z3kUmMi6lr07iOpUqqA=="], + + "@hey-api/codegen-core": ["@hey-api/codegen-core@0.3.3", "", { "peerDependencies": { "typescript": ">=5.5.3" } }, "sha512-vArVDtrvdzFewu1hnjUm4jX1NBITlSCeO81EdWq676MxQbyxsGcDPAgohaSA+Wvr4HjPSvsg2/1s2zYxUtXebg=="], + + "@hey-api/json-schema-ref-parser": ["@hey-api/json-schema-ref-parser@1.2.1", "", { "dependencies": { "@jsdevtools/ono": "^7.1.3", "@types/json-schema": "^7.0.15", "js-yaml": "^4.1.0", "lodash": "^4.17.21" } }, "sha512-inPeksRLq+j3ArnuGOzQPQE//YrhezQG0+9Y9yizScBN2qatJ78fIByhEgKdNAbtguDCn4RPxmEhcrePwHxs4A=="], + + "@hey-api/openapi-ts": ["@hey-api/openapi-ts@0.86.12", "", { "dependencies": { "@hey-api/codegen-core": "^0.3.3", "@hey-api/json-schema-ref-parser": "1.2.1", "ansi-colors": "4.1.3", "c12": "3.3.1", "color-support": "1.1.3", "commander": "14.0.1", "handlebars": "4.7.8", "open": "10.2.0", "semver": "7.7.2" }, "peerDependencies": { "typescript": ">=5.5.3" }, "bin": { "openapi-ts": "bin/run.js" } }, "sha512-ffESYyy6nyRS+8SWBdeAibHgQSM9IMlh04CtN/BTwDmgoeLwmfsHa+SBG3prbzSTaI2VAxpVM2dOqDEaqTL+tg=="], + "@hono/node-server": ["@hono/node-server@1.19.14", "", { "peerDependencies": { "hono": "^4" } }, "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw=="], "@hono/zod-openapi": ["@hono/zod-openapi@1.3.0", "", { "dependencies": { "@asteasolutions/zod-to-openapi": "^8.5.0", "@hono/zod-validator": "^0.7.6", "openapi3-ts": "^4.5.0" }, "peerDependencies": { "hono": ">=4.3.6", "zod": "^4.0.0" } }, "sha512-loDVevfMaaNa0slskhpMcqjSdidVXba2QJwNVmnS5Dp6L8AqSgtjJxWGJfRZtosyzYOb5gx4ZzXNCe+QhwY7xw=="], @@ -1046,6 +1065,8 @@ "@jscpd/tokenizer": ["@jscpd/tokenizer@4.0.5", "", { "dependencies": { "@jscpd/core": "4.0.5", "reprism": "^0.0.11", "spark-md5": "^3.0.2" } }, "sha512-WzRujQtN5WedxZVDKuoanxmKAFrxcLrHpcA6kaM4z8AhGtWXZ325yseqgL5TZ8OK7Auwu7kQLlqhfk05fGYG7A=="], + "@jsdevtools/ono": ["@jsdevtools/ono@7.1.3", "", {}, "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg=="], + "@jsonforms/core": ["@jsonforms/core@3.7.0", "", { "dependencies": { "@types/json-schema": "^7.0.3", "ajv": "^8.6.1", "ajv-formats": "^2.1.0", "lodash": "^4.17.21" } }, "sha512-CE9viWtwi9QWLqlWLeOul1/R1GRAyOA9y6OoUpsCc0FhyR+g5p29F3k0fUExHWxL0Sf4KHcXYkfhtqfRBPS8ww=="], "@jsonforms/react": ["@jsonforms/react@3.7.0", "", { "dependencies": { "lodash": "^4.17.21" }, "peerDependencies": { "@jsonforms/core": "3.7.0", "react": "^16.12.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-HkY7qAx8vW97wPEgZ7GxCB3iiXG1c95GuObxtcDHGPBJWMwnxWBnVYJmv5h7nthrInKsQKHZL5OusnC/sj/1GQ=="], @@ -1066,6 +1087,8 @@ "@lobu/cli": ["@lobu/cli@workspace:packages/cli"], + "@lobu/client": ["@lobu/client@workspace:packages/client"], + "@lobu/connector-sdk": ["@lobu/connector-sdk@workspace:packages/connector-sdk"], "@lobu/connector-worker": ["@lobu/connector-worker@workspace:packages/connector-worker"], @@ -2016,6 +2039,8 @@ "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="], + "ansi-colors": ["ansi-colors@4.1.3", "", {}, "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw=="], + "ansi-escapes": ["ansi-escapes@7.3.0", "", { "dependencies": { "environment": "^1.0.0" } }, "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg=="], "ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="], @@ -2168,6 +2193,8 @@ "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="], + "c12": ["c12@3.3.1", "", { "dependencies": { "chokidar": "^4.0.3", "confbox": "^0.2.2", "defu": "^6.1.4", "dotenv": "^17.2.3", "exsolve": "^1.0.7", "giget": "^2.0.0", "jiti": "^2.6.1", "ohash": "^2.0.11", "pathe": "^2.0.3", "perfect-debounce": "^2.0.0", "pkg-types": "^2.3.0", "rc9": "^2.1.2" }, "peerDependencies": { "magicast": "^0.3.5" }, "optionalPeers": ["magicast"] }, "sha512-LcWQ01LT9tkoUINHgpIOv3mMs+Abv7oVCrtpMRi1PaapVEpWoMga5WuT7/DqFTu7URP9ftbOmimNw1KNIGh9DQ=="], + "cac": ["cac@6.7.14", "", {}, "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ=="], "cacheable": ["cacheable@2.3.4", "", { "dependencies": { "@cacheable/memory": "^2.0.8", "@cacheable/utils": "^2.4.0", "hookified": "^1.15.0", "keyv": "^5.6.0", "qified": "^0.9.0" } }, "sha512-djgxybDbw9fL/ZWMI3+CE8ZilNxcwFkVtDc1gJ+IlOSSWkSMPQabhV/XCHTQ6pwwN6aivXPZ43omTooZiX06Ew=="], @@ -2210,6 +2237,8 @@ "ci-info": ["ci-info@4.4.0", "", {}, "sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg=="], + "citty": ["citty@0.1.6", "", { "dependencies": { "consola": "^3.2.3" } }, "sha512-tskPPKEs8D2KPafUypv2gxwJP8h/OaJmC82QQGGDQcHvXX43xF2VDACcJVmZ0EuSxkpO9Kc4MlrA3q0+FG58AQ=="], + "cjs-module-lexer": ["cjs-module-lexer@1.4.3", "", {}, "sha512-9z8TZaGM1pfswYeXrUpzPrkx8UnWYdhJclsiYMm6x/w5+nN+8Tf/LnAgfLGQCm59qAOxU8WwHEq2vNwF6i4j+Q=="], "class-variance-authority": ["class-variance-authority@0.7.1", "", { "dependencies": { "clsx": "^2.1.1" } }, "sha512-Ka+9Trutv7G8M6WT6SeiRWz792K5qEqIGEGzXKhAE6xOWAY6pPH8U+9IY3oCMv6kqTmLsv7Xh/2w2RigkePMsg=="], @@ -2244,6 +2273,8 @@ "color-string": ["color-string@1.9.1", "", { "dependencies": { "color-name": "^1.0.0", "simple-swizzle": "^0.2.2" } }, "sha512-shrVawQFojnZv6xM40anx4CkoDP+fZsw/ZerEMsW/pyzsRbElpsL/DBVW7q3ExxwusdNXI3lXpuhEZkzs8p5Eg=="], + "color-support": ["color-support@1.1.3", "", { "bin": { "color-support": "bin.js" } }, "sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg=="], + "colors": ["colors@1.4.0", "", {}, "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA=="], "combined-stream": ["combined-stream@1.0.8", "", { "dependencies": { "delayed-stream": "~1.0.0" } }, "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg=="], @@ -2256,6 +2287,10 @@ "common-ancestor-path": ["common-ancestor-path@2.0.0", "", {}, "sha512-dnN3ibLeoRf2HNC+OlCiNc5d2zxbLJXOtiZUudNFSXZrNSydxcCsSpRzXwfu7BBWCIfHPw+xTayeBvJCP/D8Ng=="], + "confbox": ["confbox@0.2.4", "", {}, "sha512-ysOGlgTFbN2/Y6Cg3Iye8YKulHw+R2fNXHrgSmXISQdMnomY6eNDprVdW9R5xBguEqI954+S6709UyiO7B+6OQ=="], + + "consola": ["consola@3.4.2", "", {}, "sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA=="], + "constantinople": ["constantinople@4.0.1", "", { "dependencies": { "@babel/parser": "^7.6.0", "@babel/types": "^7.6.1" } }, "sha512-vCrqcSIq4//Gx74TXXCGnHpulY1dskqLTFGDmhrGxzeXL8lF8kvXv6mpNWlJj1uD4DW23D4ljAqbY4RRaaUZIw=="], "content-disposition": ["content-disposition@1.1.0", "", {}, "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g=="], @@ -2492,6 +2527,8 @@ "expressive-code": ["expressive-code@0.41.7", "", { "dependencies": { "@expressive-code/core": "^0.41.7", "@expressive-code/plugin-frames": "^0.41.7", "@expressive-code/plugin-shiki": "^0.41.7", "@expressive-code/plugin-text-markers": "^0.41.7" } }, "sha512-2wZjC8OQ3TaVEMcBtYY4Va3lo6J+Ai9jf3d4dbhURMJcU4Pbqe6EcHe424MIZI0VHUA1bR6xdpoHYi3yxokWqA=="], + "exsolve": ["exsolve@1.0.8", "", {}, "sha512-LmDxfWXwcTArk8fUEnOfSZpHOJ6zOMUJKOtFLFqJLoKJetuQG874Uc7/Kki7zFLzYybmZhp1M7+98pfMqeX8yA=="], + "extend": ["extend@3.0.2", "", {}, "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="], "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="], @@ -2596,6 +2633,8 @@ "gifwrap": ["gifwrap@0.10.1", "", { "dependencies": { "image-q": "^4.0.0", "omggif": "^1.0.10" } }, "sha512-2760b1vpJHNmLzZ/ubTtNnEx5WApN/PYWJvXvgS+tL1egTTthayFYIQQNi136FLEDcN/IyEY2EcGpIITD6eYUw=="], + "giget": ["giget@2.0.0", "", { "dependencies": { "citty": "^0.1.6", "consola": "^3.4.0", "defu": "^6.1.4", "node-fetch-native": "^1.6.6", "nypm": "^0.6.0", "pathe": "^2.0.3" }, "bin": { "giget": "dist/cli.mjs" } }, "sha512-L5bGsVkxJbJgdnwyuheIunkGatUF/zssUoxxjACCseZYAVbaqdh9Tsmmlkl8vYan09H7sbvKt4pS8GqKLBrEzA=="], + "github-from-package": ["github-from-package@0.0.0", "", {}, "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw=="], "github-slugger": ["github-slugger@2.0.0", "", {}, "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw=="], @@ -3202,6 +3241,8 @@ "nth-check": ["nth-check@2.1.1", "", { "dependencies": { "boolbase": "^1.0.0" } }, "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w=="], + "nypm": ["nypm@0.6.6", "", { "dependencies": { "citty": "^0.2.2", "pathe": "^2.0.3", "tinyexec": "^1.1.1" }, "bin": { "nypm": "dist/cli.mjs" } }, "sha512-vRyr0r4cbBapw07Xw8xrj9Teq3o7MUD35rSaTcanDbW+aK2XHDgJFiU6ZTj2GBw7Q12ysdsyFss+Vdz4hQ0Y6Q=="], + "object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="], "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="], @@ -3310,6 +3351,8 @@ "peberminta": ["peberminta@0.9.0", "", {}, "sha512-XIxfHpEuSJbITd1H3EeQwpcZbTLHc+VVr8ANI9t5sit565tsI4/xK3KWTUFE2e6QiangUkh3B0jihzmGnNrRsQ=="], + "perfect-debounce": ["perfect-debounce@2.1.0", "", {}, "sha512-LjgdTytVFXeUgtHZr9WYViYSM/g8MkcTPYDlPa3cDqMirHjKiSZPYd6DoL7pK8AJQr+uWkQvCjHNdiMqsrJs+g=="], + "pg": ["pg@8.20.0", "", { "dependencies": { "pg-connection-string": "^2.12.0", "pg-pool": "^3.13.0", "pg-protocol": "^1.13.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.3.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-ldhMxz2r8fl/6QkXnBD3CR9/xg694oT6DZQ2s6c/RI28OjtSOpxnPrUCGOBJ46RCUxcWdx3p6kw/xnDHjKvaRA=="], "pg-cloudflare": ["pg-cloudflare@1.3.0", "", {}, "sha512-6lswVVSztmHiRtD6I8hw4qP/nDm1EJbKMRhf3HCYaqud7frGysPv7FYJ5noZQdhQtN2xJnimfMtvQq21pdbzyQ=="], @@ -3344,6 +3387,8 @@ "pkce-challenge": ["pkce-challenge@5.0.1", "", {}, "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ=="], + "pkg-types": ["pkg-types@2.3.1", "", { "dependencies": { "confbox": "^0.2.4", "exsolve": "^1.0.8", "pathe": "^2.0.3" } }, "sha512-y+ichcgc2LrADuhLNAx8DFjVfgz91pRxfZdI3UDhxHvcVEZsenLO+7XaU5vOp0u/7V/wZ+plyuQxtrDlZJ+yeg=="], + "platform": ["platform@1.3.6", "", {}, "sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg=="], "playwright": ["patchright@1.59.4", "", { "dependencies": { "patchright-core": "v1.59.4" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "patchright": "cli.js" } }, "sha512-RDZ40tBZHZtTAMoUoct/IpMA1wrozPZGU2RFk8NIDEndOEBbLxS0dH2fRLiwsNrgXgjZGA/3krrTlzK+uFGgoQ=="], @@ -3466,6 +3511,8 @@ "rc": ["rc@1.2.8", "", { "dependencies": { "deep-extend": "^0.6.0", "ini": "~1.3.0", "minimist": "^1.2.0", "strip-json-comments": "~2.0.1" }, "bin": { "rc": "./cli.js" } }, "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw=="], + "rc9": ["rc9@2.1.2", "", { "dependencies": { "defu": "^6.1.4", "destr": "^2.0.3" } }, "sha512-btXCnMmRIBINM2LDZoEmOogIZU7Qe7zn4BpomSKZ/ykbLObuBdvG+mFq11DL6fjH1DRwHhrlgtYWG96bJiC7Cg=="], + "re2js": ["re2js@1.4.0", "", {}, "sha512-KTOIcZTSOpOxbu3i0+T6mFQ6tkxXKlTxfcMFs1trQbsMnG84qNq+DjXr8Afu+FEFjvF1NNlldpC7roPyazFI8g=="], "react": ["react@19.2.5", "", {}, "sha512-llUJLzz1zTUBrskt2pwZgLq59AemifIftw4aB7JxOqf1HY2FDaGDxgwpAPVzHU1kdWabH7FauP4i1oEeer2WCA=="], @@ -4112,6 +4159,12 @@ "@grpc/proto-loader/long": ["long@5.3.2", "", {}, "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA=="], + "@hey-api/openapi-ts/commander": ["commander@14.0.1", "", {}, "sha512-2JkV3gUZUVrbNA+1sjBOYLsMZ5cEEl8GTFP2a4AVz5hvasAMCQ1D2l2le/cX+pV4N6ZU17zjUahLpIXRrnWL8A=="], + + "@hey-api/openapi-ts/handlebars": ["handlebars@4.7.8", "", { "dependencies": { "minimist": "^1.2.5", "neo-async": "^2.6.2", "source-map": "^0.6.1", "wordwrap": "^1.0.0" }, "optionalDependencies": { "uglify-js": "^3.1.4" }, "bin": { "handlebars": "bin/handlebars" } }, "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ=="], + + "@hey-api/openapi-ts/semver": ["semver@7.7.2", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA=="], + "@inquirer/core/signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="], "@instantdb/core/uuid": ["uuid@11.1.1", "", { "bin": { "uuid": "dist/esm/bin/uuid" } }, "sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ=="], @@ -4450,6 +4503,14 @@ "bl/readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="], + "c12/chokidar": ["chokidar@4.0.3", "", { "dependencies": { "readdirp": "^4.0.1" } }, "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA=="], + + "c12/dotenv": ["dotenv@17.4.2", "", {}, "sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw=="], + + "c12/jiti": ["jiti@2.7.0", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ=="], + + "c12/pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="], + "chokidar/fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="], "cli-highlight/chalk": ["chalk@4.1.2", "", { "dependencies": { "ansi-styles": "^4.1.0", "supports-color": "^7.1.0" } }, "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA=="], @@ -4490,6 +4551,8 @@ "foreground-child/signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="], + "giget/pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="], + "glob/minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="], "h3/cookie-es": ["cookie-es@1.2.3", "", {}, "sha512-lXVyvUvrNXblMqzIRrxHb57UUVmqsSWlxqt3XIjCkUP0wDAf6uicO6KMbEgYrMNtEvWgWHwe42CKxPu9MYAnWw=="], @@ -4536,6 +4599,10 @@ "node-liblzma/node-addon-api": ["node-addon-api@8.7.0", "", {}, "sha512-9MdFxmkKaOYVTV+XVRG8ArDwwQ77XIgIPyKASB1k3JPq3M8fGQQQE3YpMOrKm6g//Ktx8ivZr8xo1Qmtqub+GA=="], + "nypm/citty": ["citty@0.2.2", "", {}, "sha512-+6vJA3L98yv+IdfKGZHBNiGW5KHn22e/JwID0Strsz8h4S/csAu/OuICwxrg44k5MRiZHWIo8XXuJgQTriRP4w=="], + + "nypm/pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="], + "onnx-proto/protobufjs": ["protobufjs@6.11.5", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.2", "@protobufjs/base64": "^1.1.2", "@protobufjs/codegen": "^2.0.4", "@protobufjs/eventemitter": "^1.1.0", "@protobufjs/fetch": "^1.1.0", "@protobufjs/float": "^1.0.2", "@protobufjs/inquire": "^1.1.0", "@protobufjs/path": "^1.1.2", "@protobufjs/pool": "^1.1.0", "@protobufjs/utf8": "^1.1.0", "@types/long": "^4.0.1", "@types/node": ">=13.7.0", "long": "^4.0.0" }, "bin": { "pbjs": "bin/pbjs", "pbts": "bin/pbts" } }, "sha512-OKjVH3hDoXdIZ/s5MLv8O2X0s+wOxGfV7ar6WFSKGaSAxi/6gYn3px5POS4vi+mc/0zCOdL7Jkwrj0oT1Yst2A=="], "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="], @@ -4544,6 +4611,8 @@ "pixelmatch/pngjs": ["pngjs@6.0.0", "", {}, "sha512-TRzzuFRRmEoSW/p1KVAmiOgPco2Irlah+bGFCeNfJXxxYGwSw7YwAOAcd7X28K/m5bjBWKsC29KyoMfHbypayg=="], + "pkg-types/pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="], + "prebuild-install/tar-fs": ["tar-fs@2.1.4", "", { "dependencies": { "chownr": "^1.1.1", "mkdirp-classic": "^0.5.2", "pump": "^3.0.0", "tar-stream": "^2.1.4" } }, "sha512-mDAjwmZdh7LTT6pNleZ05Yt65HC3E+NiQzl672vQG38jIrehtJk/J3mNwIg+vShQPcLF/LV7CMnDW6vjj6sfYQ=="], "pretty-format/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], @@ -4954,6 +5023,8 @@ "baileys/pino/thread-stream": ["thread-stream@3.1.0", "", { "dependencies": { "real-require": "^0.2.0" } }, "sha512-OqyPZ9u96VohAyMfJykzmivOrY2wfMSf3C5TtFJVgN+Hm6aj+voFhlK+kZEIv2FBh1X6Xp3DlnCOfEQ3B2J86A=="], + "c12/chokidar/readdirp": ["readdirp@4.1.2", "", {}, "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg=="], + "cli-highlight/yargs/cliui": ["cliui@7.0.4", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.0", "wrap-ansi": "^7.0.0" } }, "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ=="], "cli-highlight/yargs/string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="], diff --git a/config/biome.config.json b/config/biome.config.json index f7a5b6517..cf42bfeaf 100644 --- a/config/biome.config.json +++ b/config/biome.config.json @@ -23,6 +23,7 @@ "!**/.connector-child-*.mjs", "!**/*.css", "!**/packages/server/**", + "!**/packages/client/src/generated/**", "!**/packages/connector-sdk/**", "!**/packages/openclaw-plugin/**", "!**/packages/connector-worker/**", diff --git a/package.json b/package.json index 896d8b46f..ba8cd164b 100644 --- a/package.json +++ b/package.json @@ -15,15 +15,15 @@ "check": "biome check --config-path config/biome.config.json .", "check:fix": "biome check --config-path config/biome.config.json --write .", "prepare": "husky || true", - "test": "bun test packages/core/src packages/agent-worker/src packages/landing/src", - "test:coverage": "bun test packages/core/src packages/agent-worker/src packages/landing/src --coverage", + "test": "bun test packages/core/src packages/client/src packages/agent-worker/src packages/landing/src", + "test:coverage": "bun test packages/core/src packages/client/src packages/agent-worker/src packages/landing/src --coverage", "typecheck": "tsc --noEmit", "dev": "./scripts/dev-native.sh", - "build:packages": "cd packages/core && bun run build && cd ../pgvector-embedded && bun run build && cd ../connector-sdk && bun run build && cd ../agent-worker && bun run build && cd ../openclaw-plugin && bun run build && cd ../embeddings && bun run build && cd ../connector-worker && bun run build && cd ../promptfoo-provider && bun run build && cd ../server && bun run build:server && cd .. && if [ -f owletto/package.json ]; then (cd owletto && bun run build); else echo '[build:packages] owletto submodule absent — CLI ships headless (API only)'; fi && cd cli && bun run build", + "build:packages": "cd packages/core && bun run build && cd ../pgvector-embedded && bun run build && cd ../connector-sdk && bun run build && cd ../client && bun run build && cd ../agent-worker && bun run build && cd ../openclaw-plugin && bun run build && cd ../embeddings && bun run build && cd ../connector-worker && bun run build && cd ../promptfoo-provider && bun run build && cd ../server && bun run build:server && cd .. && if [ -f owletto/package.json ]; then (cd owletto && bun run build); else echo '[build:packages] owletto submodule absent — CLI ships headless (API only)'; fi && cd cli && bun run build", "build:lobu": "cd packages/embeddings && bun run build && cd ../..", "watch:packages": "tsc -b --watch packages/core packages/agent-worker", "test:packages": "cd packages/core && bun run test && cd ../agent-worker && bun run test", - "typecheck:packages": "cd packages/core && bun run typecheck && cd ../agent-worker && bun run typecheck", + "typecheck:packages": "cd packages/core && bun run typecheck && cd ../client && bun run typecheck && cd ../agent-worker && bun run typecheck", "knip": "bunx knip --config config/knip.ts", "slack:manifest:print": "bun run scripts/slack-manifest.ts print", "slack:manifest:validate": "bun run scripts/slack-manifest.ts validate", diff --git a/packages/client/openapi-ts.config.ts b/packages/client/openapi-ts.config.ts new file mode 100644 index 000000000..1e68e0664 --- /dev/null +++ b/packages/client/openapi-ts.config.ts @@ -0,0 +1,13 @@ +import { defineConfig } from "@hey-api/openapi-ts"; + +export default defineConfig({ + input: + process.env.LOBU_OPENAPI_URL ?? + "http://localhost:8787/lobu/api/docs/openapi.json", + output: { + path: "src/generated", + format: "prettier", + importFileExtension: ".js", + }, + plugins: ["@hey-api/typescript", "@hey-api/sdk", "@hey-api/client-fetch"], +}); diff --git a/packages/client/package.json b/packages/client/package.json new file mode 100644 index 000000000..03c0bb819 --- /dev/null +++ b/packages/client/package.json @@ -0,0 +1,44 @@ +{ + "name": "@lobu/client", + "version": "9.1.1", + "description": "TypeScript client for the Lobu Agent API", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "files": [ + "dist" + ], + "scripts": { + "build": "tsc", + "typecheck": "tsc --noEmit", + "test": "bun test src", + "clean": "rm -rf dist", + "generate": "openapi-ts" + }, + "engines": { + "node": ">=18" + }, + "license": "Apache-2.0", + "publishConfig": { + "access": "public" + }, + "homepage": "https://github.com/lobu-ai/lobu", + "repository": { + "type": "git", + "url": "git+https://github.com/lobu-ai/lobu.git", + "directory": "packages/client" + }, + "dependencies": { + "@hey-api/client-fetch": "^0.13.1" + }, + "devDependencies": { + "@hey-api/openapi-ts": "^0.86.5", + "typescript": "^5.8.3" + } +} diff --git a/packages/client/src/__tests__/client.test.ts b/packages/client/src/__tests__/client.test.ts new file mode 100644 index 000000000..5efb187d0 --- /dev/null +++ b/packages/client/src/__tests__/client.test.ts @@ -0,0 +1,132 @@ +import { describe, expect, test } from "bun:test"; +import { Lobu } from "../client.js"; + +describe("Lobu", () => { + test("creates a session and sends with the session token", async () => { + const calls: Array<{ + url: string; + authorization: string | null; + body: string; + }> = []; + const fetchImpl = (async (input, init) => { + const request = await requestInfo(input, init); + calls.push(request); + + if (request.url.endsWith("/api/v1/agents")) { + return json( + { + success: true, + agentId: "support_user_1", + token: "session-token", + expiresAt: Date.now() + 60_000, + sseUrl: + "https://lobu.test/lobu/api/v1/agents/support_user_1/events", + messagesUrl: + "https://lobu.test/lobu/api/v1/agents/support_user_1/messages", + }, + 201 + ); + } + + return json({ + success: true, + messageId: "msg_1", + queued: true, + }); + }) as typeof fetch; + + const lobu = new Lobu({ + baseUrl: "https://lobu.test/lobu/", + token: "api-token", + fetch: fetchImpl, + }); + + const session = await lobu.sessions.create({ + agentId: "support", + userId: "user_1", + }); + const result = await session.send("hello", { messageId: "msg_1" }); + + expect(session.agentId).toBe("support_user_1"); + expect(result.queued).toBe(true); + expect(calls[0]).toMatchObject({ + url: "https://lobu.test/lobu/api/v1/agents", + authorization: "Bearer api-token", + }); + expect(calls[1]).toMatchObject({ + url: "https://lobu.test/lobu/api/v1/agents/support_user_1/messages", + authorization: "Bearer session-token", + body: JSON.stringify({ content: "hello", messageId: "msg_1" }), + }); + }); + + test("streams SSE events with authorization", async () => { + const fetchImpl = (async (input, init) => { + const request = await requestInfo(input, init); + if (request.url.endsWith("/api/v1/agents")) { + return json( + { + success: true, + agentId: "support_user_1", + token: "session-token", + expiresAt: Date.now() + 60_000, + sseUrl: + "https://lobu.test/lobu/api/v1/agents/support_user_1/events", + messagesUrl: + "https://lobu.test/lobu/api/v1/agents/support_user_1/messages", + }, + 201 + ); + } + + expect(request.authorization).toBe("Bearer session-token"); + return new Response( + new ReadableStream({ + start(controller) { + controller.enqueue( + new TextEncoder().encode( + 'event: connected\ndata: {"agentId":"support"}\n\nevent: text\ndata: "hi"\n\n' + ) + ); + controller.close(); + }, + }), + { status: 200, headers: { "content-type": "text/event-stream" } } + ); + }) as typeof fetch; + + const lobu = new Lobu({ + baseUrl: "https://lobu.test/lobu", + token: "api-token", + fetch: fetchImpl, + }); + const session = await lobu.sessions.create({}); + const events = []; + + for await (const event of session.events()) events.push(event); + + expect(events).toEqual([ + { event: "connected", data: { agentId: "support" }, retry: 3000 }, + { event: "text", data: "hi", retry: 3000 }, + ]); + }); +}); + +function json(body: unknown, status = 200): Response { + return new Response(JSON.stringify(body), { + status, + headers: { "content-type": "application/json" }, + }); +} + +async function requestInfo( + input: RequestInfo | URL, + init: RequestInit | undefined +) { + const request = input instanceof Request ? input : new Request(input, init); + return { + url: request.url, + authorization: request.headers.get("authorization"), + body: await request.clone().text(), + }; +} diff --git a/packages/client/src/client.ts b/packages/client/src/client.ts new file mode 100644 index 000000000..375d96a80 --- /dev/null +++ b/packages/client/src/client.ts @@ -0,0 +1,28 @@ +import { LobuRestClient } from "./rest.js"; +import { AgentSession } from "./session.js"; +import type { CreateSessionRequest, LobuClientOptions } from "./types.js"; + +export class Lobu { + readonly rest: LobuRestClient; + readonly sessions: { + create: (input: CreateSessionRequest) => Promise; + }; + + constructor(options: LobuClientOptions) { + this.rest = new LobuRestClient({ + baseUrl: options.baseUrl, + token: options.token, + fetch: options.fetch ?? globalThis.fetch.bind(globalThis), + headers: options.headers, + }); + this.sessions = { + create: (input) => this.createSession(input), + }; + } + + createSession(input: CreateSessionRequest): Promise { + return this.rest + .createSession(input) + .then((response) => new AgentSession(this.rest, response)); + } +} diff --git a/packages/client/src/errors.ts b/packages/client/src/errors.ts new file mode 100644 index 000000000..bce64edb8 --- /dev/null +++ b/packages/client/src/errors.ts @@ -0,0 +1,20 @@ +export class LobuApiError extends Error { + readonly status: number; + readonly body: unknown; + readonly response: Response; + + constructor(response: Response, body: unknown) { + const message = + typeof body === "object" && + body !== null && + "error" in body && + typeof body.error === "string" + ? body.error + : `Lobu API request failed with ${response.status}`; + super(message); + this.name = "LobuApiError"; + this.status = response.status; + this.body = body; + this.response = response; + } +} diff --git a/packages/client/src/generated/client.gen.ts b/packages/client/src/generated/client.gen.ts new file mode 100644 index 000000000..877b47719 --- /dev/null +++ b/packages/client/src/generated/client.gen.ts @@ -0,0 +1,27 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import { + type ClientOptions, + type Config, + createClient, + createConfig, +} from "./client/index.js"; +import type { ClientOptions as ClientOptions2 } from "./types.gen.js"; + +/** + * The `createClientConfig()` function will be called on client initialization + * and the returned object will become the client's initial configuration. + * + * You may want to initialize your client this way instead of calling + * `setConfig()`. This is useful for example if you're using Next.js + * to ensure your client always has the correct values. + */ +export type CreateClientConfig = ( + override?: Config, +) => Config & T>; + +export const client = createClient( + createConfig({ + baseUrl: "http://localhost:8787", + }), +); diff --git a/packages/client/src/generated/client/client.gen.ts b/packages/client/src/generated/client/client.gen.ts new file mode 100644 index 000000000..2f2023d95 --- /dev/null +++ b/packages/client/src/generated/client/client.gen.ts @@ -0,0 +1,268 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import { createSseClient } from "../core/serverSentEvents.gen.js"; +import type { HttpMethod } from "../core/types.gen.js"; +import { getValidRequestBody } from "../core/utils.gen.js"; +import type { + Client, + Config, + RequestOptions, + ResolvedRequestOptions, +} from "./types.gen.js"; +import { + buildUrl, + createConfig, + createInterceptors, + getParseAs, + mergeConfigs, + mergeHeaders, + setAuthParams, +} from "./utils.gen.js"; + +type ReqInit = Omit & { + body?: any; + headers: ReturnType; +}; + +export const createClient = (config: Config = {}): Client => { + let _config = mergeConfigs(createConfig(), config); + + const getConfig = (): Config => ({ ..._config }); + + const setConfig = (config: Config): Config => { + _config = mergeConfigs(_config, config); + return getConfig(); + }; + + const interceptors = createInterceptors< + Request, + Response, + unknown, + ResolvedRequestOptions + >(); + + const beforeRequest = async (options: RequestOptions) => { + const opts = { + ..._config, + ...options, + fetch: options.fetch ?? _config.fetch ?? globalThis.fetch, + headers: mergeHeaders(_config.headers, options.headers), + serializedBody: undefined, + }; + + if (opts.security) { + await setAuthParams({ + ...opts, + security: opts.security, + }); + } + + if (opts.requestValidator) { + await opts.requestValidator(opts); + } + + if (opts.body !== undefined && opts.bodySerializer) { + opts.serializedBody = opts.bodySerializer(opts.body); + } + + // remove Content-Type header if body is empty to avoid sending invalid requests + if (opts.body === undefined || opts.serializedBody === "") { + opts.headers.delete("Content-Type"); + } + + const url = buildUrl(opts); + + return { opts, url }; + }; + + const request: Client["request"] = async (options) => { + // @ts-expect-error + const { opts, url } = await beforeRequest(options); + const requestInit: ReqInit = { + redirect: "follow", + ...opts, + body: getValidRequestBody(opts), + }; + + let request = new Request(url, requestInit); + + for (const fn of interceptors.request.fns) { + if (fn) { + request = await fn(request, opts); + } + } + + // fetch must be assigned here, otherwise it would throw the error: + // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation + const _fetch = opts.fetch!; + let response = await _fetch(request); + + for (const fn of interceptors.response.fns) { + if (fn) { + response = await fn(response, request, opts); + } + } + + const result = { + request, + response, + }; + + if (response.ok) { + const parseAs = + (opts.parseAs === "auto" + ? getParseAs(response.headers.get("Content-Type")) + : opts.parseAs) ?? "json"; + + if ( + response.status === 204 || + response.headers.get("Content-Length") === "0" + ) { + let emptyData: any; + switch (parseAs) { + case "arrayBuffer": + case "blob": + case "text": + emptyData = await response[parseAs](); + break; + case "formData": + emptyData = new FormData(); + break; + case "stream": + emptyData = response.body; + break; + case "json": + default: + emptyData = {}; + break; + } + return opts.responseStyle === "data" + ? emptyData + : { + data: emptyData, + ...result, + }; + } + + let data: any; + switch (parseAs) { + case "arrayBuffer": + case "blob": + case "formData": + case "json": + case "text": + data = await response[parseAs](); + break; + case "stream": + return opts.responseStyle === "data" + ? response.body + : { + data: response.body, + ...result, + }; + } + + if (parseAs === "json") { + if (opts.responseValidator) { + await opts.responseValidator(data); + } + + if (opts.responseTransformer) { + data = await opts.responseTransformer(data); + } + } + + return opts.responseStyle === "data" + ? data + : { + data, + ...result, + }; + } + + const textError = await response.text(); + let jsonError: unknown; + + try { + jsonError = JSON.parse(textError); + } catch { + // noop + } + + const error = jsonError ?? textError; + let finalError = error; + + for (const fn of interceptors.error.fns) { + if (fn) { + finalError = (await fn(error, response, request, opts)) as string; + } + } + + finalError = finalError || ({} as string); + + if (opts.throwOnError) { + throw finalError; + } + + // TODO: we probably want to return error and improve types + return opts.responseStyle === "data" + ? undefined + : { + error: finalError, + ...result, + }; + }; + + const makeMethodFn = + (method: Uppercase) => (options: RequestOptions) => + request({ ...options, method }); + + const makeSseFn = + (method: Uppercase) => async (options: RequestOptions) => { + const { opts, url } = await beforeRequest(options); + return createSseClient({ + ...opts, + body: opts.body as BodyInit | null | undefined, + headers: opts.headers as unknown as Record, + method, + onRequest: async (url, init) => { + let request = new Request(url, init); + for (const fn of interceptors.request.fns) { + if (fn) { + request = await fn(request, opts); + } + } + return request; + }, + url, + }); + }; + + return { + buildUrl, + connect: makeMethodFn("CONNECT"), + delete: makeMethodFn("DELETE"), + get: makeMethodFn("GET"), + getConfig, + head: makeMethodFn("HEAD"), + interceptors, + options: makeMethodFn("OPTIONS"), + patch: makeMethodFn("PATCH"), + post: makeMethodFn("POST"), + put: makeMethodFn("PUT"), + request, + setConfig, + sse: { + connect: makeSseFn("CONNECT"), + delete: makeSseFn("DELETE"), + get: makeSseFn("GET"), + head: makeSseFn("HEAD"), + options: makeSseFn("OPTIONS"), + patch: makeSseFn("PATCH"), + post: makeSseFn("POST"), + put: makeSseFn("PUT"), + trace: makeSseFn("TRACE"), + }, + trace: makeMethodFn("TRACE"), + } as Client; +}; diff --git a/packages/client/src/generated/client/index.ts b/packages/client/src/generated/client/index.ts new file mode 100644 index 000000000..75d26de34 --- /dev/null +++ b/packages/client/src/generated/client/index.ts @@ -0,0 +1,26 @@ +// This file is auto-generated by @hey-api/openapi-ts + +export type { Auth } from "../core/auth.gen.js"; +export type { QuerySerializerOptions } from "../core/bodySerializer.gen.js"; +export { + formDataBodySerializer, + jsonBodySerializer, + urlSearchParamsBodySerializer, +} from "../core/bodySerializer.gen.js"; +export { buildClientParams } from "../core/params.gen.js"; +export { serializeQueryKeyValue } from "../core/queryKeySerializer.gen.js"; +export { createClient } from "./client.gen.js"; +export type { + Client, + ClientOptions, + Config, + CreateClientConfig, + Options, + OptionsLegacyParser, + RequestOptions, + RequestResult, + ResolvedRequestOptions, + ResponseStyle, + TDataShape, +} from "./types.gen.js"; +export { createConfig, mergeHeaders } from "./utils.gen.js"; diff --git a/packages/client/src/generated/client/types.gen.ts b/packages/client/src/generated/client/types.gen.ts new file mode 100644 index 000000000..2bff4252e --- /dev/null +++ b/packages/client/src/generated/client/types.gen.ts @@ -0,0 +1,269 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import type { Auth } from "../core/auth.gen.js"; +import type { + ServerSentEventsOptions, + ServerSentEventsResult, +} from "../core/serverSentEvents.gen.js"; +import type { + Client as CoreClient, + Config as CoreConfig, +} from "../core/types.gen.js"; +import type { Middleware } from "./utils.gen.js"; + +export type ResponseStyle = "data" | "fields"; + +export interface Config + extends Omit, CoreConfig { + /** + * Base URL for all requests made by this client. + */ + baseUrl?: T["baseUrl"]; + /** + * Fetch API implementation. You can use this option to provide a custom + * fetch instance. + * + * @default globalThis.fetch + */ + fetch?: typeof fetch; + /** + * Please don't use the Fetch client for Next.js applications. The `next` + * options won't have any effect. + * + * Install {@link https://www.npmjs.com/package/@hey-api/client-next `@hey-api/client-next`} instead. + */ + next?: never; + /** + * Return the response data parsed in a specified format. By default, `auto` + * will infer the appropriate method from the `Content-Type` response header. + * You can override this behavior with any of the {@link Body} methods. + * Select `stream` if you don't want to parse response data at all. + * + * @default 'auto' + */ + parseAs?: + | "arrayBuffer" + | "auto" + | "blob" + | "formData" + | "json" + | "stream" + | "text"; + /** + * Should we return only data or multiple fields (data, error, response, etc.)? + * + * @default 'fields' + */ + responseStyle?: ResponseStyle; + /** + * Throw an error instead of returning it in the response? + * + * @default false + */ + throwOnError?: T["throwOnError"]; +} + +export interface RequestOptions< + TData = unknown, + TResponseStyle extends ResponseStyle = "fields", + ThrowOnError extends boolean = boolean, + Url extends string = string, +> + extends + Config<{ + responseStyle: TResponseStyle; + throwOnError: ThrowOnError; + }>, + Pick< + ServerSentEventsOptions, + | "onSseError" + | "onSseEvent" + | "sseDefaultRetryDelay" + | "sseMaxRetryAttempts" + | "sseMaxRetryDelay" + > { + /** + * Any body that you want to add to your request. + * + * {@link https://developer.mozilla.org/docs/Web/API/fetch#body} + */ + body?: unknown; + path?: Record; + query?: Record; + /** + * Security mechanism(s) to use for the request. + */ + security?: ReadonlyArray; + url: Url; +} + +export interface ResolvedRequestOptions< + TResponseStyle extends ResponseStyle = "fields", + ThrowOnError extends boolean = boolean, + Url extends string = string, +> extends RequestOptions { + serializedBody?: string; +} + +export type RequestResult< + TData = unknown, + TError = unknown, + ThrowOnError extends boolean = boolean, + TResponseStyle extends ResponseStyle = "fields", +> = ThrowOnError extends true + ? Promise< + TResponseStyle extends "data" + ? TData extends Record + ? TData[keyof TData] + : TData + : { + data: TData extends Record + ? TData[keyof TData] + : TData; + request: Request; + response: Response; + } + > + : Promise< + TResponseStyle extends "data" + ? + | (TData extends Record + ? TData[keyof TData] + : TData) + | undefined + : ( + | { + data: TData extends Record + ? TData[keyof TData] + : TData; + error: undefined; + } + | { + data: undefined; + error: TError extends Record + ? TError[keyof TError] + : TError; + } + ) & { + request: Request; + response: Response; + } + >; + +export interface ClientOptions { + baseUrl?: string; + responseStyle?: ResponseStyle; + throwOnError?: boolean; +} + +type MethodFn = < + TData = unknown, + TError = unknown, + ThrowOnError extends boolean = false, + TResponseStyle extends ResponseStyle = "fields", +>( + options: Omit, "method">, +) => RequestResult; + +type SseFn = < + TData = unknown, + TError = unknown, + ThrowOnError extends boolean = false, + TResponseStyle extends ResponseStyle = "fields", +>( + options: Omit, "method">, +) => Promise>; + +type RequestFn = < + TData = unknown, + TError = unknown, + ThrowOnError extends boolean = false, + TResponseStyle extends ResponseStyle = "fields", +>( + options: Omit, "method"> & + Pick< + Required>, + "method" + >, +) => RequestResult; + +type BuildUrlFn = < + TData extends { + body?: unknown; + path?: Record; + query?: Record; + url: string; + }, +>( + options: TData & Options, +) => string; + +export type Client = CoreClient< + RequestFn, + Config, + MethodFn, + BuildUrlFn, + SseFn +> & { + interceptors: Middleware; +}; + +/** + * The `createClientConfig()` function will be called on client initialization + * and the returned object will become the client's initial configuration. + * + * You may want to initialize your client this way instead of calling + * `setConfig()`. This is useful for example if you're using Next.js + * to ensure your client always has the correct values. + */ +export type CreateClientConfig = ( + override?: Config, +) => Config & T>; + +export interface TDataShape { + body?: unknown; + headers?: unknown; + path?: unknown; + query?: unknown; + url: string; +} + +type OmitKeys = Pick>; + +export type Options< + TData extends TDataShape = TDataShape, + ThrowOnError extends boolean = boolean, + TResponse = unknown, + TResponseStyle extends ResponseStyle = "fields", +> = OmitKeys< + RequestOptions, + "body" | "path" | "query" | "url" +> & + ([TData] extends [never] ? unknown : Omit); + +export type OptionsLegacyParser< + TData = unknown, + ThrowOnError extends boolean = boolean, + TResponseStyle extends ResponseStyle = "fields", +> = TData extends { body?: any } + ? TData extends { headers?: any } + ? OmitKeys< + RequestOptions, + "body" | "headers" | "url" + > & + TData + : OmitKeys< + RequestOptions, + "body" | "url" + > & + TData & + Pick, "headers"> + : TData extends { headers?: any } + ? OmitKeys< + RequestOptions, + "headers" | "url" + > & + TData & + Pick, "body"> + : OmitKeys, "url"> & + TData; diff --git a/packages/client/src/generated/client/utils.gen.ts b/packages/client/src/generated/client/utils.gen.ts new file mode 100644 index 000000000..f6d0d28a1 --- /dev/null +++ b/packages/client/src/generated/client/utils.gen.ts @@ -0,0 +1,337 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import { getAuthToken } from "../core/auth.gen.js"; +import type { QuerySerializerOptions } from "../core/bodySerializer.gen.js"; +import { jsonBodySerializer } from "../core/bodySerializer.gen.js"; +import { + serializeArrayParam, + serializeObjectParam, + serializePrimitiveParam, +} from "../core/pathSerializer.gen.js"; +import { getUrl } from "../core/utils.gen.js"; +import type { + Client, + ClientOptions, + Config, + RequestOptions, +} from "./types.gen.js"; + +export const createQuerySerializer = ({ + parameters = {}, + ...args +}: QuerySerializerOptions = {}) => { + const querySerializer = (queryParams: T) => { + const search: string[] = []; + if (queryParams && typeof queryParams === "object") { + for (const name in queryParams) { + const value = queryParams[name]; + + if (value === undefined || value === null) { + continue; + } + + const options = parameters[name] || args; + + if (Array.isArray(value)) { + const serializedArray = serializeArrayParam({ + allowReserved: options.allowReserved, + explode: true, + name, + style: "form", + value, + ...options.array, + }); + if (serializedArray) search.push(serializedArray); + } else if (typeof value === "object") { + const serializedObject = serializeObjectParam({ + allowReserved: options.allowReserved, + explode: true, + name, + style: "deepObject", + value: value as Record, + ...options.object, + }); + if (serializedObject) search.push(serializedObject); + } else { + const serializedPrimitive = serializePrimitiveParam({ + allowReserved: options.allowReserved, + name, + value: value as string, + }); + if (serializedPrimitive) search.push(serializedPrimitive); + } + } + } + return search.join("&"); + }; + return querySerializer; +}; + +/** + * Infers parseAs value from provided Content-Type header. + */ +export const getParseAs = ( + contentType: string | null, +): Exclude => { + if (!contentType) { + // If no Content-Type header is provided, the best we can do is return the raw response body, + // which is effectively the same as the 'stream' option. + return "stream"; + } + + const cleanContent = contentType.split(";")[0]?.trim(); + + if (!cleanContent) { + return; + } + + if ( + cleanContent.startsWith("application/json") || + cleanContent.endsWith("+json") + ) { + return "json"; + } + + if (cleanContent === "multipart/form-data") { + return "formData"; + } + + if ( + ["application/", "audio/", "image/", "video/"].some((type) => + cleanContent.startsWith(type), + ) + ) { + return "blob"; + } + + if (cleanContent.startsWith("text/")) { + return "text"; + } + + return; +}; + +const checkForExistence = ( + options: Pick & { + headers: Headers; + }, + name?: string, +): boolean => { + if (!name) { + return false; + } + if ( + options.headers.has(name) || + options.query?.[name] || + options.headers.get("Cookie")?.includes(`${name}=`) + ) { + return true; + } + return false; +}; + +export const setAuthParams = async ({ + security, + ...options +}: Pick, "security"> & + Pick & { + headers: Headers; + }) => { + for (const auth of security) { + if (checkForExistence(options, auth.name)) { + continue; + } + + const token = await getAuthToken(auth, options.auth); + + if (!token) { + continue; + } + + const name = auth.name ?? "Authorization"; + + switch (auth.in) { + case "query": + if (!options.query) { + options.query = {}; + } + options.query[name] = token; + break; + case "cookie": + options.headers.append("Cookie", `${name}=${token}`); + break; + case "header": + default: + options.headers.set(name, token); + break; + } + } +}; + +export const buildUrl: Client["buildUrl"] = (options) => + getUrl({ + baseUrl: options.baseUrl as string, + path: options.path, + query: options.query, + querySerializer: + typeof options.querySerializer === "function" + ? options.querySerializer + : createQuerySerializer(options.querySerializer), + url: options.url, + }); + +export const mergeConfigs = (a: Config, b: Config): Config => { + const config = { ...a, ...b }; + if (config.baseUrl?.endsWith("/")) { + config.baseUrl = config.baseUrl.substring(0, config.baseUrl.length - 1); + } + config.headers = mergeHeaders(a.headers, b.headers); + return config; +}; + +const headersEntries = (headers: Headers): Array<[string, string]> => { + const entries: Array<[string, string]> = []; + headers.forEach((value, key) => { + entries.push([key, value]); + }); + return entries; +}; + +export const mergeHeaders = ( + ...headers: Array["headers"] | undefined> +): Headers => { + const mergedHeaders = new Headers(); + for (const header of headers) { + if (!header) { + continue; + } + + const iterator = + header instanceof Headers + ? headersEntries(header) + : Object.entries(header); + + for (const [key, value] of iterator) { + if (value === null) { + mergedHeaders.delete(key); + } else if (Array.isArray(value)) { + for (const v of value) { + mergedHeaders.append(key, v as string); + } + } else if (value !== undefined) { + // assume object headers are meant to be JSON stringified, i.e. their + // content value in OpenAPI specification is 'application/json' + mergedHeaders.set( + key, + typeof value === "object" ? JSON.stringify(value) : (value as string), + ); + } + } + } + return mergedHeaders; +}; + +type ErrInterceptor = ( + error: Err, + response: Res, + request: Req, + options: Options, +) => Err | Promise; + +type ReqInterceptor = ( + request: Req, + options: Options, +) => Req | Promise; + +type ResInterceptor = ( + response: Res, + request: Req, + options: Options, +) => Res | Promise; + +class Interceptors { + fns: Array = []; + + clear(): void { + this.fns = []; + } + + eject(id: number | Interceptor): void { + const index = this.getInterceptorIndex(id); + if (this.fns[index]) { + this.fns[index] = null; + } + } + + exists(id: number | Interceptor): boolean { + const index = this.getInterceptorIndex(id); + return Boolean(this.fns[index]); + } + + getInterceptorIndex(id: number | Interceptor): number { + if (typeof id === "number") { + return this.fns[id] ? id : -1; + } + return this.fns.indexOf(id); + } + + update( + id: number | Interceptor, + fn: Interceptor, + ): number | Interceptor | false { + const index = this.getInterceptorIndex(id); + if (this.fns[index]) { + this.fns[index] = fn; + return id; + } + return false; + } + + use(fn: Interceptor): number { + this.fns.push(fn); + return this.fns.length - 1; + } +} + +export interface Middleware { + error: Interceptors>; + request: Interceptors>; + response: Interceptors>; +} + +export const createInterceptors = (): Middleware< + Req, + Res, + Err, + Options +> => ({ + error: new Interceptors>(), + request: new Interceptors>(), + response: new Interceptors>(), +}); + +const defaultQuerySerializer = createQuerySerializer({ + allowReserved: false, + array: { + explode: true, + style: "form", + }, + object: { + explode: true, + style: "deepObject", + }, +}); + +const defaultHeaders = { + "Content-Type": "application/json", +}; + +export const createConfig = ( + override: Config & T> = {}, +): Config & T> => ({ + ...jsonBodySerializer, + headers: defaultHeaders, + parseAs: "auto", + querySerializer: defaultQuerySerializer, + ...override, +}); diff --git a/packages/client/src/generated/core/auth.gen.ts b/packages/client/src/generated/core/auth.gen.ts new file mode 100644 index 000000000..3d7411517 --- /dev/null +++ b/packages/client/src/generated/core/auth.gen.ts @@ -0,0 +1,42 @@ +// This file is auto-generated by @hey-api/openapi-ts + +export type AuthToken = string | undefined; + +export interface Auth { + /** + * Which part of the request do we use to send the auth? + * + * @default 'header' + */ + in?: "header" | "query" | "cookie"; + /** + * Header or query parameter name. + * + * @default 'Authorization' + */ + name?: string; + scheme?: "basic" | "bearer"; + type: "apiKey" | "http"; +} + +export const getAuthToken = async ( + auth: Auth, + callback: ((auth: Auth) => Promise | AuthToken) | AuthToken, +): Promise => { + const token = + typeof callback === "function" ? await callback(auth) : callback; + + if (!token) { + return; + } + + if (auth.scheme === "bearer") { + return `Bearer ${token}`; + } + + if (auth.scheme === "basic") { + return `Basic ${btoa(token)}`; + } + + return token; +}; diff --git a/packages/client/src/generated/core/bodySerializer.gen.ts b/packages/client/src/generated/core/bodySerializer.gen.ts new file mode 100644 index 000000000..75f192100 --- /dev/null +++ b/packages/client/src/generated/core/bodySerializer.gen.ts @@ -0,0 +1,100 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import type { + ArrayStyle, + ObjectStyle, + SerializerOptions, +} from "./pathSerializer.gen.js"; + +export type QuerySerializer = (query: Record) => string; + +export type BodySerializer = (body: any) => any; + +type QuerySerializerOptionsObject = { + allowReserved?: boolean; + array?: Partial>; + object?: Partial>; +}; + +export type QuerySerializerOptions = QuerySerializerOptionsObject & { + /** + * Per-parameter serialization overrides. When provided, these settings + * override the global array/object settings for specific parameter names. + */ + parameters?: Record; +}; + +const serializeFormDataPair = ( + data: FormData, + key: string, + value: unknown, +): void => { + if (typeof value === "string" || value instanceof Blob) { + data.append(key, value); + } else if (value instanceof Date) { + data.append(key, value.toISOString()); + } else { + data.append(key, JSON.stringify(value)); + } +}; + +const serializeUrlSearchParamsPair = ( + data: URLSearchParams, + key: string, + value: unknown, +): void => { + if (typeof value === "string") { + data.append(key, value); + } else { + data.append(key, JSON.stringify(value)); + } +}; + +export const formDataBodySerializer = { + bodySerializer: | Array>>( + body: T, + ): FormData => { + const data = new FormData(); + + Object.entries(body).forEach(([key, value]) => { + if (value === undefined || value === null) { + return; + } + if (Array.isArray(value)) { + value.forEach((v) => serializeFormDataPair(data, key, v)); + } else { + serializeFormDataPair(data, key, value); + } + }); + + return data; + }, +}; + +export const jsonBodySerializer = { + bodySerializer: (body: T): string => + JSON.stringify(body, (_key, value) => + typeof value === "bigint" ? value.toString() : value, + ), +}; + +export const urlSearchParamsBodySerializer = { + bodySerializer: | Array>>( + body: T, + ): string => { + const data = new URLSearchParams(); + + Object.entries(body).forEach(([key, value]) => { + if (value === undefined || value === null) { + return; + } + if (Array.isArray(value)) { + value.forEach((v) => serializeUrlSearchParamsPair(data, key, v)); + } else { + serializeUrlSearchParamsPair(data, key, value); + } + }); + + return data.toString(); + }, +}; diff --git a/packages/client/src/generated/core/params.gen.ts b/packages/client/src/generated/core/params.gen.ts new file mode 100644 index 000000000..fb9f992a6 --- /dev/null +++ b/packages/client/src/generated/core/params.gen.ts @@ -0,0 +1,176 @@ +// This file is auto-generated by @hey-api/openapi-ts + +type Slot = "body" | "headers" | "path" | "query"; + +export type Field = + | { + in: Exclude; + /** + * Field name. This is the name we want the user to see and use. + */ + key: string; + /** + * Field mapped name. This is the name we want to use in the request. + * If omitted, we use the same value as `key`. + */ + map?: string; + } + | { + in: Extract; + /** + * Key isn't required for bodies. + */ + key?: string; + map?: string; + } + | { + /** + * Field name. This is the name we want the user to see and use. + */ + key: string; + /** + * Field mapped name. This is the name we want to use in the request. + * If `in` is omitted, `map` aliases `key` to the transport layer. + */ + map: Slot; + }; + +export interface Fields { + allowExtra?: Partial>; + args?: ReadonlyArray; +} + +export type FieldsConfig = ReadonlyArray; + +const extraPrefixesMap: Record = { + $body_: "body", + $headers_: "headers", + $path_: "path", + $query_: "query", +}; +const extraPrefixes = Object.entries(extraPrefixesMap); + +type KeyMap = Map< + string, + | { + in: Slot; + map?: string; + } + | { + in?: never; + map: Slot; + } +>; + +const buildKeyMap = (fields: FieldsConfig, map?: KeyMap): KeyMap => { + if (!map) { + map = new Map(); + } + + for (const config of fields) { + if ("in" in config) { + if (config.key) { + map.set(config.key, { + in: config.in, + map: config.map, + }); + } + } else if ("key" in config) { + map.set(config.key, { + map: config.map, + }); + } else if (config.args) { + buildKeyMap(config.args, map); + } + } + + return map; +}; + +interface Params { + body: unknown; + headers: Record; + path: Record; + query: Record; +} + +const stripEmptySlots = (params: Params) => { + for (const [slot, value] of Object.entries(params)) { + if (value && typeof value === "object" && !Object.keys(value).length) { + delete params[slot as Slot]; + } + } +}; + +export const buildClientParams = ( + args: ReadonlyArray, + fields: FieldsConfig, +) => { + const params: Params = { + body: {}, + headers: {}, + path: {}, + query: {}, + }; + + const map = buildKeyMap(fields); + + let config: FieldsConfig[number] | undefined; + + for (const [index, arg] of args.entries()) { + if (fields[index]) { + config = fields[index]; + } + + if (!config) { + continue; + } + + if ("in" in config) { + if (config.key) { + const field = map.get(config.key)!; + const name = field.map || config.key; + if (field.in) { + (params[field.in] as Record)[name] = arg; + } + } else { + params.body = arg; + } + } else { + for (const [key, value] of Object.entries(arg ?? {})) { + const field = map.get(key); + + if (field) { + if (field.in) { + const name = field.map || key; + (params[field.in] as Record)[name] = value; + } else { + params[field.map] = value; + } + } else { + const extra = extraPrefixes.find(([prefix]) => + key.startsWith(prefix), + ); + + if (extra) { + const [prefix, slot] = extra; + (params[slot] as Record)[ + key.slice(prefix.length) + ] = value; + } else if ("allowExtra" in config && config.allowExtra) { + for (const [slot, allowed] of Object.entries(config.allowExtra)) { + if (allowed) { + (params[slot as Slot] as Record)[key] = value; + break; + } + } + } + } + } + } + } + + stripEmptySlots(params); + + return params; +}; diff --git a/packages/client/src/generated/core/pathSerializer.gen.ts b/packages/client/src/generated/core/pathSerializer.gen.ts new file mode 100644 index 000000000..52457e0c7 --- /dev/null +++ b/packages/client/src/generated/core/pathSerializer.gen.ts @@ -0,0 +1,180 @@ +// This file is auto-generated by @hey-api/openapi-ts + +interface SerializeOptions + extends SerializePrimitiveOptions, SerializerOptions {} + +interface SerializePrimitiveOptions { + allowReserved?: boolean; + name: string; +} + +export interface SerializerOptions { + /** + * @default true + */ + explode: boolean; + style: T; +} + +export type ArrayStyle = "form" | "spaceDelimited" | "pipeDelimited"; +export type ArraySeparatorStyle = ArrayStyle | MatrixStyle; +type MatrixStyle = "label" | "matrix" | "simple"; +export type ObjectStyle = "form" | "deepObject"; +type ObjectSeparatorStyle = ObjectStyle | MatrixStyle; + +interface SerializePrimitiveParam extends SerializePrimitiveOptions { + value: string; +} + +export const separatorArrayExplode = (style: ArraySeparatorStyle) => { + switch (style) { + case "label": + return "."; + case "matrix": + return ";"; + case "simple": + return ","; + default: + return "&"; + } +}; + +export const separatorArrayNoExplode = (style: ArraySeparatorStyle) => { + switch (style) { + case "form": + return ","; + case "pipeDelimited": + return "|"; + case "spaceDelimited": + return "%20"; + default: + return ","; + } +}; + +export const separatorObjectExplode = (style: ObjectSeparatorStyle) => { + switch (style) { + case "label": + return "."; + case "matrix": + return ";"; + case "simple": + return ","; + default: + return "&"; + } +}; + +export const serializeArrayParam = ({ + allowReserved, + explode, + name, + style, + value, +}: SerializeOptions & { + value: unknown[]; +}) => { + if (!explode) { + const joinedValues = ( + allowReserved ? value : value.map((v) => encodeURIComponent(v as string)) + ).join(separatorArrayNoExplode(style)); + switch (style) { + case "label": + return `.${joinedValues}`; + case "matrix": + return `;${name}=${joinedValues}`; + case "simple": + return joinedValues; + default: + return `${name}=${joinedValues}`; + } + } + + const separator = separatorArrayExplode(style); + const joinedValues = value + .map((v) => { + if (style === "label" || style === "simple") { + return allowReserved ? v : encodeURIComponent(v as string); + } + + return serializePrimitiveParam({ + allowReserved, + name, + value: v as string, + }); + }) + .join(separator); + return style === "label" || style === "matrix" + ? separator + joinedValues + : joinedValues; +}; + +export const serializePrimitiveParam = ({ + allowReserved, + name, + value, +}: SerializePrimitiveParam) => { + if (value === undefined || value === null) { + return ""; + } + + if (typeof value === "object") { + throw new Error( + "Deeply-nested arrays/objects aren’t supported. Provide your own `querySerializer()` to handle these.", + ); + } + + return `${name}=${allowReserved ? value : encodeURIComponent(value)}`; +}; + +export const serializeObjectParam = ({ + allowReserved, + explode, + name, + style, + value, + valueOnly, +}: SerializeOptions & { + value: Record | Date; + valueOnly?: boolean; +}) => { + if (value instanceof Date) { + return valueOnly ? value.toISOString() : `${name}=${value.toISOString()}`; + } + + if (style !== "deepObject" && !explode) { + let values: string[] = []; + Object.entries(value).forEach(([key, v]) => { + values = [ + ...values, + key, + allowReserved ? (v as string) : encodeURIComponent(v as string), + ]; + }); + const joinedValues = values.join(","); + switch (style) { + case "form": + return `${name}=${joinedValues}`; + case "label": + return `.${joinedValues}`; + case "matrix": + return `;${name}=${joinedValues}`; + default: + return joinedValues; + } + } + + const separator = separatorObjectExplode(style); + const joinedValues = Object.entries(value) + .map(([key, v]) => + serializePrimitiveParam({ + allowReserved, + name: style === "deepObject" ? `${name}[${key}]` : key, + value: v as string, + }), + ) + .join(separator); + return style === "label" || style === "matrix" + ? separator + joinedValues + : joinedValues; +}; diff --git a/packages/client/src/generated/core/queryKeySerializer.gen.ts b/packages/client/src/generated/core/queryKeySerializer.gen.ts new file mode 100644 index 000000000..0713164c5 --- /dev/null +++ b/packages/client/src/generated/core/queryKeySerializer.gen.ts @@ -0,0 +1,136 @@ +// This file is auto-generated by @hey-api/openapi-ts + +/** + * JSON-friendly union that mirrors what Pinia Colada can hash. + */ +export type JsonValue = + | null + | string + | number + | boolean + | JsonValue[] + | { [key: string]: JsonValue }; + +/** + * Replacer that converts non-JSON values (bigint, Date, etc.) to safe substitutes. + */ +export const queryKeyJsonReplacer = (_key: string, value: unknown) => { + if ( + value === undefined || + typeof value === "function" || + typeof value === "symbol" + ) { + return undefined; + } + if (typeof value === "bigint") { + return value.toString(); + } + if (value instanceof Date) { + return value.toISOString(); + } + return value; +}; + +/** + * Safely stringifies a value and parses it back into a JsonValue. + */ +export const stringifyToJsonValue = (input: unknown): JsonValue | undefined => { + try { + const json = JSON.stringify(input, queryKeyJsonReplacer); + if (json === undefined) { + return undefined; + } + return JSON.parse(json) as JsonValue; + } catch { + return undefined; + } +}; + +/** + * Detects plain objects (including objects with a null prototype). + */ +const isPlainObject = (value: unknown): value is Record => { + if (value === null || typeof value !== "object") { + return false; + } + const prototype = Object.getPrototypeOf(value as object); + return prototype === Object.prototype || prototype === null; +}; + +/** + * Turns URLSearchParams into a sorted JSON object for deterministic keys. + */ +const serializeSearchParams = (params: URLSearchParams): JsonValue => { + const entries = Array.from(params.entries()).sort(([a], [b]) => + a.localeCompare(b), + ); + const result: Record = {}; + + for (const [key, value] of entries) { + const existing = result[key]; + if (existing === undefined) { + result[key] = value; + continue; + } + + if (Array.isArray(existing)) { + (existing as string[]).push(value); + } else { + result[key] = [existing, value]; + } + } + + return result; +}; + +/** + * Normalizes any accepted value into a JSON-friendly shape for query keys. + */ +export const serializeQueryKeyValue = ( + value: unknown, +): JsonValue | undefined => { + if (value === null) { + return null; + } + + if ( + typeof value === "string" || + typeof value === "number" || + typeof value === "boolean" + ) { + return value; + } + + if ( + value === undefined || + typeof value === "function" || + typeof value === "symbol" + ) { + return undefined; + } + + if (typeof value === "bigint") { + return value.toString(); + } + + if (value instanceof Date) { + return value.toISOString(); + } + + if (Array.isArray(value)) { + return stringifyToJsonValue(value); + } + + if ( + typeof URLSearchParams !== "undefined" && + value instanceof URLSearchParams + ) { + return serializeSearchParams(value); + } + + if (isPlainObject(value)) { + return stringifyToJsonValue(value); + } + + return undefined; +}; diff --git a/packages/client/src/generated/core/serverSentEvents.gen.ts b/packages/client/src/generated/core/serverSentEvents.gen.ts new file mode 100644 index 000000000..801e79114 --- /dev/null +++ b/packages/client/src/generated/core/serverSentEvents.gen.ts @@ -0,0 +1,264 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import type { Config } from "./types.gen.js"; + +export type ServerSentEventsOptions = Omit< + RequestInit, + "method" +> & + Pick & { + /** + * Fetch API implementation. You can use this option to provide a custom + * fetch instance. + * + * @default globalThis.fetch + */ + fetch?: typeof fetch; + /** + * Implementing clients can call request interceptors inside this hook. + */ + onRequest?: (url: string, init: RequestInit) => Promise; + /** + * Callback invoked when a network or parsing error occurs during streaming. + * + * This option applies only if the endpoint returns a stream of events. + * + * @param error The error that occurred. + */ + onSseError?: (error: unknown) => void; + /** + * Callback invoked when an event is streamed from the server. + * + * This option applies only if the endpoint returns a stream of events. + * + * @param event Event streamed from the server. + * @returns Nothing (void). + */ + onSseEvent?: (event: StreamEvent) => void; + serializedBody?: RequestInit["body"]; + /** + * Default retry delay in milliseconds. + * + * This option applies only if the endpoint returns a stream of events. + * + * @default 3000 + */ + sseDefaultRetryDelay?: number; + /** + * Maximum number of retry attempts before giving up. + */ + sseMaxRetryAttempts?: number; + /** + * Maximum retry delay in milliseconds. + * + * Applies only when exponential backoff is used. + * + * This option applies only if the endpoint returns a stream of events. + * + * @default 30000 + */ + sseMaxRetryDelay?: number; + /** + * Optional sleep function for retry backoff. + * + * Defaults to using `setTimeout`. + */ + sseSleepFn?: (ms: number) => Promise; + url: string; + }; + +export interface StreamEvent { + data: TData; + event?: string; + id?: string; + retry?: number; +} + +export type ServerSentEventsResult< + TData = unknown, + TReturn = void, + TNext = unknown, +> = { + stream: AsyncGenerator< + TData extends Record ? TData[keyof TData] : TData, + TReturn, + TNext + >; +}; + +export const createSseClient = ({ + onRequest, + onSseError, + onSseEvent, + responseTransformer, + responseValidator, + sseDefaultRetryDelay, + sseMaxRetryAttempts, + sseMaxRetryDelay, + sseSleepFn, + url, + ...options +}: ServerSentEventsOptions): ServerSentEventsResult => { + let lastEventId: string | undefined; + + const sleep = + sseSleepFn ?? + ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms))); + + const createStream = async function* () { + let retryDelay: number = sseDefaultRetryDelay ?? 3000; + let attempt = 0; + const signal = options.signal ?? new AbortController().signal; + + while (true) { + if (signal.aborted) break; + + attempt++; + + const headers = + options.headers instanceof Headers + ? options.headers + : new Headers(options.headers as Record | undefined); + + if (lastEventId !== undefined) { + headers.set("Last-Event-ID", lastEventId); + } + + try { + const requestInit: RequestInit = { + redirect: "follow", + ...options, + body: options.serializedBody, + headers, + signal, + }; + let request = new Request(url, requestInit); + if (onRequest) { + request = await onRequest(url, requestInit); + } + // fetch must be assigned here, otherwise it would throw the error: + // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation + const _fetch = options.fetch ?? globalThis.fetch; + const response = await _fetch(request); + + if (!response.ok) + throw new Error( + `SSE failed: ${response.status} ${response.statusText}`, + ); + + if (!response.body) throw new Error("No body in SSE response"); + + const reader = response.body + .pipeThrough(new TextDecoderStream()) + .getReader(); + + let buffer = ""; + + const abortHandler = () => { + try { + reader.cancel(); + } catch { + // noop + } + }; + + signal.addEventListener("abort", abortHandler); + + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + buffer += value; + + const chunks = buffer.split("\n\n"); + buffer = chunks.pop() ?? ""; + + for (const chunk of chunks) { + const lines = chunk.split("\n"); + const dataLines: Array = []; + let eventName: string | undefined; + + for (const line of lines) { + if (line.startsWith("data:")) { + dataLines.push(line.replace(/^data:\s*/, "")); + } else if (line.startsWith("event:")) { + eventName = line.replace(/^event:\s*/, ""); + } else if (line.startsWith("id:")) { + lastEventId = line.replace(/^id:\s*/, ""); + } else if (line.startsWith("retry:")) { + const parsed = Number.parseInt( + line.replace(/^retry:\s*/, ""), + 10, + ); + if (!Number.isNaN(parsed)) { + retryDelay = parsed; + } + } + } + + let data: unknown; + let parsedJson = false; + + if (dataLines.length) { + const rawData = dataLines.join("\n"); + try { + data = JSON.parse(rawData); + parsedJson = true; + } catch { + data = rawData; + } + } + + if (parsedJson) { + if (responseValidator) { + await responseValidator(data); + } + + if (responseTransformer) { + data = await responseTransformer(data); + } + } + + onSseEvent?.({ + data, + event: eventName, + id: lastEventId, + retry: retryDelay, + }); + + if (dataLines.length) { + yield data as any; + } + } + } + } finally { + signal.removeEventListener("abort", abortHandler); + reader.releaseLock(); + } + + break; // exit loop on normal completion + } catch (error) { + // connection failed or aborted; retry after delay + onSseError?.(error); + + if ( + sseMaxRetryAttempts !== undefined && + attempt >= sseMaxRetryAttempts + ) { + break; // stop after firing error + } + + // exponential backoff: double retry each attempt, cap at 30s + const backoff = Math.min( + retryDelay * 2 ** (attempt - 1), + sseMaxRetryDelay ?? 30000, + ); + await sleep(backoff); + } + } + }; + + const stream = createStream(); + + return { stream }; +}; diff --git a/packages/client/src/generated/core/types.gen.ts b/packages/client/src/generated/core/types.gen.ts new file mode 100644 index 000000000..0956605a6 --- /dev/null +++ b/packages/client/src/generated/core/types.gen.ts @@ -0,0 +1,118 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import type { Auth, AuthToken } from "./auth.gen.js"; +import type { + BodySerializer, + QuerySerializer, + QuerySerializerOptions, +} from "./bodySerializer.gen.js"; + +export type HttpMethod = + | "connect" + | "delete" + | "get" + | "head" + | "options" + | "patch" + | "post" + | "put" + | "trace"; + +export type Client< + RequestFn = never, + Config = unknown, + MethodFn = never, + BuildUrlFn = never, + SseFn = never, +> = { + /** + * Returns the final request URL. + */ + buildUrl: BuildUrlFn; + getConfig: () => Config; + request: RequestFn; + setConfig: (config: Config) => Config; +} & { + [K in HttpMethod]: MethodFn; +} & ([SseFn] extends [never] + ? { sse?: never } + : { sse: { [K in HttpMethod]: SseFn } }); + +export interface Config { + /** + * Auth token or a function returning auth token. The resolved value will be + * added to the request payload as defined by its `security` array. + */ + auth?: ((auth: Auth) => Promise | AuthToken) | AuthToken; + /** + * A function for serializing request body parameter. By default, + * {@link JSON.stringify()} will be used. + */ + bodySerializer?: BodySerializer | null; + /** + * An object containing any HTTP headers that you want to pre-populate your + * `Headers` object with. + * + * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more} + */ + headers?: + | RequestInit["headers"] + | Record< + string, + | string + | number + | boolean + | (string | number | boolean)[] + | null + | undefined + | unknown + >; + /** + * The request method. + * + * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more} + */ + method?: Uppercase; + /** + * A function for serializing request query parameters. By default, arrays + * will be exploded in form style, objects will be exploded in deepObject + * style, and reserved characters are percent-encoded. + * + * This method will have no effect if the native `paramsSerializer()` Axios + * API function is used. + * + * {@link https://swagger.io/docs/specification/serialization/#query View examples} + */ + querySerializer?: QuerySerializer | QuerySerializerOptions; + /** + * A function validating request data. This is useful if you want to ensure + * the request conforms to the desired shape, so it can be safely sent to + * the server. + */ + requestValidator?: (data: unknown) => Promise; + /** + * A function transforming response data before it's returned. This is useful + * for post-processing data, e.g. converting ISO strings into Date objects. + */ + responseTransformer?: (data: unknown) => Promise; + /** + * A function validating response data. This is useful if you want to ensure + * the response conforms to the desired shape, so it can be safely passed to + * the transformers and returned to the user. + */ + responseValidator?: (data: unknown) => Promise; +} + +type IsExactlyNeverOrNeverUndefined = [T] extends [never] + ? true + : [T] extends [never | undefined] + ? [undefined] extends [T] + ? false + : true + : false; + +export type OmitNever> = { + [K in keyof T as IsExactlyNeverOrNeverUndefined extends true + ? never + : K]: T[K]; +}; diff --git a/packages/client/src/generated/core/utils.gen.ts b/packages/client/src/generated/core/utils.gen.ts new file mode 100644 index 000000000..ff02d8da8 --- /dev/null +++ b/packages/client/src/generated/core/utils.gen.ts @@ -0,0 +1,143 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import type { BodySerializer, QuerySerializer } from "./bodySerializer.gen.js"; +import { + type ArraySeparatorStyle, + serializeArrayParam, + serializeObjectParam, + serializePrimitiveParam, +} from "./pathSerializer.gen.js"; + +export interface PathSerializer { + path: Record; + url: string; +} + +export const PATH_PARAM_RE = /\{[^{}]+\}/g; + +export const defaultPathSerializer = ({ path, url: _url }: PathSerializer) => { + let url = _url; + const matches = _url.match(PATH_PARAM_RE); + if (matches) { + for (const match of matches) { + let explode = false; + let name = match.substring(1, match.length - 1); + let style: ArraySeparatorStyle = "simple"; + + if (name.endsWith("*")) { + explode = true; + name = name.substring(0, name.length - 1); + } + + if (name.startsWith(".")) { + name = name.substring(1); + style = "label"; + } else if (name.startsWith(";")) { + name = name.substring(1); + style = "matrix"; + } + + const value = path[name]; + + if (value === undefined || value === null) { + continue; + } + + if (Array.isArray(value)) { + url = url.replace( + match, + serializeArrayParam({ explode, name, style, value }), + ); + continue; + } + + if (typeof value === "object") { + url = url.replace( + match, + serializeObjectParam({ + explode, + name, + style, + value: value as Record, + valueOnly: true, + }), + ); + continue; + } + + if (style === "matrix") { + url = url.replace( + match, + `;${serializePrimitiveParam({ + name, + value: value as string, + })}`, + ); + continue; + } + + const replaceValue = encodeURIComponent( + style === "label" ? `.${value as string}` : (value as string), + ); + url = url.replace(match, replaceValue); + } + } + return url; +}; + +export const getUrl = ({ + baseUrl, + path, + query, + querySerializer, + url: _url, +}: { + baseUrl?: string; + path?: Record; + query?: Record; + querySerializer: QuerySerializer; + url: string; +}) => { + const pathUrl = _url.startsWith("/") ? _url : `/${_url}`; + let url = (baseUrl ?? "") + pathUrl; + if (path) { + url = defaultPathSerializer({ path, url }); + } + let search = query ? querySerializer(query) : ""; + if (search.startsWith("?")) { + search = search.substring(1); + } + if (search) { + url += `?${search}`; + } + return url; +}; + +export function getValidRequestBody(options: { + body?: unknown; + bodySerializer?: BodySerializer | null; + serializedBody?: unknown; +}) { + const hasBody = options.body !== undefined; + const isSerializedBody = hasBody && options.bodySerializer; + + if (isSerializedBody) { + if ("serializedBody" in options) { + const hasSerializedBody = + options.serializedBody !== undefined && options.serializedBody !== ""; + + return hasSerializedBody ? options.serializedBody : null; + } + + // not all clients implement a serializedBody property (i.e. client-axios) + return options.body !== "" ? options.body : null; + } + + // plain/text body + if (hasBody) { + return options.body; + } + + // no body was provided + return undefined; +} diff --git a/packages/client/src/generated/index.ts b/packages/client/src/generated/index.ts new file mode 100644 index 000000000..b21c06488 --- /dev/null +++ b/packages/client/src/generated/index.ts @@ -0,0 +1,4 @@ +// This file is auto-generated by @hey-api/openapi-ts + +export type * from "./types.gen.js"; +export * from "./sdk.gen.js"; diff --git a/packages/client/src/generated/sdk.gen.ts b/packages/client/src/generated/sdk.gen.ts new file mode 100644 index 000000000..e6a0c9073 --- /dev/null +++ b/packages/client/src/generated/sdk.gen.ts @@ -0,0 +1,631 @@ +// This file is auto-generated by @hey-api/openapi-ts + +import { client } from "./client.gen.js"; +import type { + Client, + Options as Options2, + TDataShape, +} from "./client/index.js"; +import type { + DeleteApiV1AgentsByAgentIdChannelsByPlatformByChannelIdData, + DeleteApiV1AgentsByAgentIdChannelsByPlatformByChannelIdResponses, + DeleteApiV1AgentsByAgentIdData, + DeleteApiV1AgentsByAgentIdErrors, + DeleteApiV1AgentsByAgentIdResponses, + GetApiBedrockHealthData, + GetApiBedrockHealthResponses, + GetApiBedrockOpenaiAByAgentIdV1ModelsData, + GetApiBedrockOpenaiAByAgentIdV1ModelsResponses, + GetApiV1AgentsByAgentIdChannelsData, + GetApiV1AgentsByAgentIdChannelsResponses, + GetApiV1AgentsByAgentIdConfigData, + GetApiV1AgentsByAgentIdConfigErrors, + GetApiV1AgentsByAgentIdConfigGrantsData, + GetApiV1AgentsByAgentIdConfigGrantsResponses, + GetApiV1AgentsByAgentIdConfigProvidersCatalogData, + GetApiV1AgentsByAgentIdConfigProvidersCatalogResponses, + GetApiV1AgentsByAgentIdConfigResponses, + GetApiV1AgentsByAgentIdData, + GetApiV1AgentsByAgentIdErrors, + GetApiV1AgentsByAgentIdEventsData, + GetApiV1AgentsByAgentIdEventsErrors, + GetApiV1AgentsByAgentIdEventsResponses, + GetApiV1AgentsByAgentIdHistorySessionMessagesData, + GetApiV1AgentsByAgentIdHistorySessionMessagesResponses, + GetApiV1AgentsByAgentIdHistorySessionStatsData, + GetApiV1AgentsByAgentIdHistorySessionStatsResponses, + GetApiV1AgentsByAgentIdHistoryStatusData, + GetApiV1AgentsByAgentIdHistoryStatusResponses, + GetApiV1AgentsByAgentIdResponses, + GetApiV1AgentsData, + GetApiV1AgentsResponses, + GetApiV1ConnectionsByIdData, + GetApiV1ConnectionsByIdErrors, + GetApiV1ConnectionsByIdResponses, + GetApiV1ConnectionsData, + GetApiV1ConnectionsErrors, + GetApiV1ConnectionsResponses, + GetApiV1FilesByArtifactIdData, + GetApiV1FilesByArtifactIdResponses, + GetConnectClaimData, + GetConnectClaimResponses, + PatchApiV1AgentsByAgentIdData, + PatchApiV1AgentsByAgentIdResponses, + PostApiBedrockOpenaiAByAgentIdV1ChatCompletionsData, + PostApiBedrockOpenaiAByAgentIdV1ChatCompletionsResponses, + PostApiV1AgentsApproveData, + PostApiV1AgentsApproveResponses, + PostApiV1AgentsByAgentIdChannelsData, + PostApiV1AgentsByAgentIdChannelsResponses, + PostApiV1AgentsByAgentIdMessagesData, + PostApiV1AgentsByAgentIdMessagesErrors, + PostApiV1AgentsByAgentIdMessagesResponses, + PostApiV1AgentsData, + PostApiV1AgentsErrors, + PostApiV1AgentsResponses, + PostApiV1AuthByProviderCodeData, + PostApiV1AuthByProviderCodeErrors, + PostApiV1AuthByProviderCodeResponses, + PostApiV1AuthByProviderLogoutData, + PostApiV1AuthByProviderLogoutResponses, + PostApiV1AuthByProviderPollData, + PostApiV1AuthByProviderPollResponses, + PostApiV1AuthByProviderSaveKeyData, + PostApiV1AuthByProviderSaveKeyResponses, + PostApiV1AuthByProviderStartData, + PostApiV1AuthByProviderStartResponses, +} from "./types.gen.js"; + +export type Options< + TData extends TDataShape = TDataShape, + ThrowOnError extends boolean = boolean, +> = Options2 & { + /** + * You can provide a client instance returned by `createClient()` instead of + * individual options. This might be also useful if you want to implement a + * custom client. + */ + client?: Client; + /** + * You can pass arbitrary values through the `meta` object. This can be + * used to access values that aren't defined as part of the SDK function. + */ + meta?: Record; +}; + +/** + * List user agents + */ +export const getApiV1Agents = ( + options?: Options, +) => { + return (options?.client ?? client).get< + GetApiV1AgentsResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents", + ...options, + }); +}; + +/** + * Create a new agent + * + * Creates a new agent session and returns authentication credentials + */ +export const postApiV1Agents = ( + options?: Options, +) => { + return (options?.client ?? client).post< + PostApiV1AgentsResponses, + PostApiV1AgentsErrors, + ThrowOnError + >({ + url: "/api/v1/agents", + ...options, + headers: { + "Content-Type": "application/json", + ...options?.headers, + }, + }); +}; + +/** + * Delete an agent + */ +export const deleteApiV1AgentsByAgentId = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).delete< + DeleteApiV1AgentsByAgentIdResponses, + DeleteApiV1AgentsByAgentIdErrors, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}", + ...options, + }); +}; + +/** + * Get agent status + */ +export const getApiV1AgentsByAgentId = ( + options: Options, +) => { + return (options.client ?? client).get< + GetApiV1AgentsByAgentIdResponses, + GetApiV1AgentsByAgentIdErrors, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}", + ...options, + }); +}; + +/** + * Update agent metadata + */ +export const patchApiV1AgentsByAgentId = ( + options: Options, +) => { + return (options.client ?? client).patch< + PatchApiV1AgentsByAgentIdResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}", + ...options, + }); +}; + +/** + * Subscribe to agent events (SSE) + * + * Server-Sent Events stream for real-time agent updates + */ +export const getApiV1AgentsByAgentIdEvents = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).sse.get< + GetApiV1AgentsByAgentIdEventsResponses, + GetApiV1AgentsByAgentIdEventsErrors, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/events", + ...options, + }); +}; + +/** + * Send a message to the agent + * + * Send a message to an agent. Supports JSON body or multipart form data for file uploads. When platform is specified, the message is routed through the platform adapter. + */ +export const postApiV1AgentsByAgentIdMessages = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).post< + PostApiV1AgentsByAgentIdMessagesResponses, + PostApiV1AgentsByAgentIdMessagesErrors, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/messages", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); +}; + +/** + * Get agent configuration + */ +export const getApiV1AgentsByAgentIdConfig = < + ThrowOnError extends boolean = false, +>( + options?: Options, +) => { + return (options?.client ?? client).get< + GetApiV1AgentsByAgentIdConfigResponses, + GetApiV1AgentsByAgentIdConfigErrors, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/config", + ...options, + }); +}; + +/** + * Exchange OAuth code for token + */ +export const postApiV1AuthByProviderCode = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).post< + PostApiV1AuthByProviderCodeResponses, + PostApiV1AuthByProviderCodeErrors, + ThrowOnError + >({ + url: "/api/v1/auth/{provider}/code", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); +}; + +/** + * List platform connections + * + * Lists Chat SDK-backed connections visible to the current settings session. + */ +export const getApiV1Connections = ( + options?: Options, +) => { + return (options?.client ?? client).get< + GetApiV1ConnectionsResponses, + GetApiV1ConnectionsErrors, + ThrowOnError + >({ + url: "/api/v1/connections", + ...options, + }); +}; + +/** + * Get a platform connection + */ +export const getApiV1ConnectionsById = ( + options: Options, +) => { + return (options.client ?? client).get< + GetApiV1ConnectionsByIdResponses, + GetApiV1ConnectionsByIdErrors, + ThrowOnError + >({ + url: "/api/v1/connections/{id}", + ...options, + }); +}; + +/** + * GET /api/bedrock/health + */ +export const getApiBedrockHealth = ( + options?: Options, +) => { + return (options?.client ?? client).get< + GetApiBedrockHealthResponses, + unknown, + ThrowOnError + >({ + url: "/api/bedrock/health", + ...options, + }); +}; + +/** + * GET /api/bedrock/openai/a/{agentId}/v1/models + */ +export const getApiBedrockOpenaiAByAgentIdV1Models = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).get< + GetApiBedrockOpenaiAByAgentIdV1ModelsResponses, + unknown, + ThrowOnError + >({ + url: "/api/bedrock/openai/a/{agentId}/v1/models", + ...options, + }); +}; + +/** + * POST /api/bedrock/openai/a/{agentId}/v1/chat/completions + */ +export const postApiBedrockOpenaiAByAgentIdV1ChatCompletions = < + ThrowOnError extends boolean = false, +>( + options: Options< + PostApiBedrockOpenaiAByAgentIdV1ChatCompletionsData, + ThrowOnError + >, +) => { + return (options.client ?? client).post< + PostApiBedrockOpenaiAByAgentIdV1ChatCompletionsResponses, + unknown, + ThrowOnError + >({ + url: "/api/bedrock/openai/a/{agentId}/v1/chat/completions", + ...options, + }); +}; + +/** + * GET /api/v1/files/{artifactId} + */ +export const getApiV1FilesByArtifactId = ( + options: Options, +) => { + return (options.client ?? client).get< + GetApiV1FilesByArtifactIdResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/files/{artifactId}", + ...options, + }); +}; + +/** + * POST /api/v1/agents/approve + */ +export const postApiV1AgentsApprove = ( + options?: Options, +) => { + return (options?.client ?? client).post< + PostApiV1AgentsApproveResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/approve", + ...options, + }); +}; + +/** + * GET /connect/claim + */ +export const getConnectClaim = ( + options?: Options, +) => { + return (options?.client ?? client).get< + GetConnectClaimResponses, + unknown, + ThrowOnError + >({ + url: "/connect/claim", + ...options, + }); +}; + +/** + * Get agent connection status + */ +export const getApiV1AgentsByAgentIdHistoryStatus = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).get< + GetApiV1AgentsByAgentIdHistoryStatusResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/history/status", + ...options, + }); +}; + +/** + * Get session messages + */ +export const getApiV1AgentsByAgentIdHistorySessionMessages = < + ThrowOnError extends boolean = false, +>( + options: Options< + GetApiV1AgentsByAgentIdHistorySessionMessagesData, + ThrowOnError + >, +) => { + return (options.client ?? client).get< + GetApiV1AgentsByAgentIdHistorySessionMessagesResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/history/session/messages", + ...options, + }); +}; + +/** + * Get session stats + */ +export const getApiV1AgentsByAgentIdHistorySessionStats = < + ThrowOnError extends boolean = false, +>( + options: Options< + GetApiV1AgentsByAgentIdHistorySessionStatsData, + ThrowOnError + >, +) => { + return (options.client ?? client).get< + GetApiV1AgentsByAgentIdHistorySessionStatsResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/history/session/stats", + ...options, + }); +}; + +/** + * List provider catalog + */ +export const getApiV1AgentsByAgentIdConfigProvidersCatalog = < + ThrowOnError extends boolean = false, +>( + options: Options< + GetApiV1AgentsByAgentIdConfigProvidersCatalogData, + ThrowOnError + >, +) => { + return (options.client ?? client).get< + GetApiV1AgentsByAgentIdConfigProvidersCatalogResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/config/providers/catalog", + ...options, + }); +}; + +/** + * List domain grants + */ +export const getApiV1AgentsByAgentIdConfigGrants = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).get< + GetApiV1AgentsByAgentIdConfigGrantsResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/config/grants", + ...options, + }); +}; + +/** + * POST /api/v1/auth/{provider}/save-key + */ +export const postApiV1AuthByProviderSaveKey = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).post< + PostApiV1AuthByProviderSaveKeyResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/auth/{provider}/save-key", + ...options, + }); +}; + +/** + * POST /api/v1/auth/{provider}/start + */ +export const postApiV1AuthByProviderStart = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).post< + PostApiV1AuthByProviderStartResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/auth/{provider}/start", + ...options, + }); +}; + +/** + * POST /api/v1/auth/{provider}/poll + */ +export const postApiV1AuthByProviderPoll = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).post< + PostApiV1AuthByProviderPollResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/auth/{provider}/poll", + ...options, + }); +}; + +/** + * POST /api/v1/auth/{provider}/logout + */ +export const postApiV1AuthByProviderLogout = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).post< + PostApiV1AuthByProviderLogoutResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/auth/{provider}/logout", + ...options, + }); +}; + +/** + * List channel bindings + */ +export const getApiV1AgentsByAgentIdChannels = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).get< + GetApiV1AgentsByAgentIdChannelsResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/channels", + ...options, + }); +}; + +/** + * Bind agent to channel + */ +export const postApiV1AgentsByAgentIdChannels = < + ThrowOnError extends boolean = false, +>( + options: Options, +) => { + return (options.client ?? client).post< + PostApiV1AgentsByAgentIdChannelsResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/channels", + ...options, + }); +}; + +/** + * Unbind agent from channel + */ +export const deleteApiV1AgentsByAgentIdChannelsByPlatformByChannelId = < + ThrowOnError extends boolean = false, +>( + options: Options< + DeleteApiV1AgentsByAgentIdChannelsByPlatformByChannelIdData, + ThrowOnError + >, +) => { + return (options.client ?? client).delete< + DeleteApiV1AgentsByAgentIdChannelsByPlatformByChannelIdResponses, + unknown, + ThrowOnError + >({ + url: "/api/v1/agents/{agentId}/channels/{platform}/{channelId}", + ...options, + }); +}; diff --git a/packages/client/src/generated/types.gen.ts b/packages/client/src/generated/types.gen.ts new file mode 100644 index 000000000..68c8ae618 --- /dev/null +++ b/packages/client/src/generated/types.gen.ts @@ -0,0 +1,1208 @@ +// This file is auto-generated by @hey-api/openapi-ts + +export type ClientOptions = { + baseUrl: "http://localhost:8787" | (string & {}); +}; + +export type GetApiV1AgentsData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/agents"; +}; + +export type GetApiV1AgentsResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type PostApiV1AgentsData = { + body?: { + provider?: string; + model?: string; + agentId?: string; + userId?: string; + thread?: string; + forceNew?: boolean; + dryRun?: boolean; + intent?: { + kind: "watcher_run"; + runId: number; + watcherId: number; + }; + networkConfig?: { + allowedDomains?: Array; + deniedDomains?: Array; + }; + mcpServers?: { + [key: string]: { + url?: string; + type?: "sse" | "streamable-http" | "stdio"; + command?: string; + args?: Array; + env?: { + [key: string]: string; + }; + headers?: { + [key: string]: string; + }; + description?: string; + }; + }; + nix?: { + flakeUrl?: string; + packages?: Array; + }; + }; + path?: never; + query?: never; + url: "/api/v1/agents"; +}; + +export type PostApiV1AgentsErrors = { + /** + * Invalid request + */ + 400: { + success: boolean; + error: string; + details?: string; + }; + /** + * Unauthorized + */ + 401: { + success: boolean; + error: string; + details?: string; + }; +}; + +export type PostApiV1AgentsError = + PostApiV1AgentsErrors[keyof PostApiV1AgentsErrors]; + +export type PostApiV1AgentsResponses = { + /** + * Agent created + */ + 201: { + success: boolean; + agentId: string; + token: string; + expiresAt: number; + sseUrl: string; + messagesUrl: string; + }; +}; + +export type PostApiV1AgentsResponse = + PostApiV1AgentsResponses[keyof PostApiV1AgentsResponses]; + +export type DeleteApiV1AgentsByAgentIdData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}"; +}; + +export type DeleteApiV1AgentsByAgentIdErrors = { + /** + * Unauthorized + */ + 401: { + success: boolean; + error: string; + details?: string; + }; + /** + * Not found + */ + 404: { + success: boolean; + error: string; + details?: string; + }; +}; + +export type DeleteApiV1AgentsByAgentIdError = + DeleteApiV1AgentsByAgentIdErrors[keyof DeleteApiV1AgentsByAgentIdErrors]; + +export type DeleteApiV1AgentsByAgentIdResponses = { + /** + * Agent deleted + */ + 200: { + success: boolean; + message?: string; + agentId?: string; + }; +}; + +export type DeleteApiV1AgentsByAgentIdResponse = + DeleteApiV1AgentsByAgentIdResponses[keyof DeleteApiV1AgentsByAgentIdResponses]; + +export type GetApiV1AgentsByAgentIdData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}"; +}; + +export type GetApiV1AgentsByAgentIdErrors = { + /** + * Unauthorized + */ + 401: { + success: boolean; + error: string; + details?: string; + }; + /** + * Not found + */ + 404: { + success: boolean; + error: string; + details?: string; + }; +}; + +export type GetApiV1AgentsByAgentIdError = + GetApiV1AgentsByAgentIdErrors[keyof GetApiV1AgentsByAgentIdErrors]; + +export type GetApiV1AgentsByAgentIdResponses = { + /** + * Agent status + */ + 200: { + success: boolean; + agent: { + agentId: string; + userId: string; + status: string; + createdAt: number; + lastActivity: number; + hasActiveConnection: boolean; + }; + }; +}; + +export type GetApiV1AgentsByAgentIdResponse = + GetApiV1AgentsByAgentIdResponses[keyof GetApiV1AgentsByAgentIdResponses]; + +export type PatchApiV1AgentsByAgentIdData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}"; +}; + +export type PatchApiV1AgentsByAgentIdResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiV1AgentsByAgentIdEventsData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/events"; +}; + +export type GetApiV1AgentsByAgentIdEventsErrors = { + /** + * Unauthorized + */ + 401: { + success: boolean; + error: string; + details?: string; + }; + /** + * Too many connections + */ + 429: { + success: boolean; + error: string; + details?: string; + }; +}; + +export type GetApiV1AgentsByAgentIdEventsError = + GetApiV1AgentsByAgentIdEventsErrors[keyof GetApiV1AgentsByAgentIdEventsErrors]; + +export type GetApiV1AgentsByAgentIdEventsResponses = { + /** + * SSE stream + */ + 200: string; +}; + +export type GetApiV1AgentsByAgentIdEventsResponse = + GetApiV1AgentsByAgentIdEventsResponses[keyof GetApiV1AgentsByAgentIdEventsResponses]; + +export type PostApiV1AgentsByAgentIdMessagesData = { + body?: { + /** + * Message content + */ + content?: string; + /** + * Message content (alias for content) + */ + message?: string; + messageId?: string; + /** + * Target platform (api, slack, telegram) + */ + platform?: string; + /** + * Slack-specific routing info (required when platform=slack) + */ + slack?: { + /** + * Slack channel ID + */ + channel: string; + /** + * Thread timestamp for replies + */ + thread?: string; + /** + * Slack team ID + */ + team?: string; + }; + [key: string]: + | unknown + | string + | { + /** + * Slack channel ID + */ + channel: string; + /** + * Thread timestamp for replies + */ + thread?: string; + /** + * Slack team ID + */ + team?: string; + } + | undefined; + }; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/messages"; +}; + +export type PostApiV1AgentsByAgentIdMessagesErrors = { + /** + * Invalid request + */ + 400: { + success: boolean; + error: string; + details?: string; + }; + /** + * Unauthorized + */ + 401: { + success: boolean; + error: string; + details?: string; + }; + /** + * Forbidden - worker tokens cannot route to platforms + */ + 403: { + success: boolean; + error: string; + details?: string; + }; + /** + * Agent not found + */ + 404: { + success: boolean; + error: string; + details?: string; + }; +}; + +export type PostApiV1AgentsByAgentIdMessagesError = + PostApiV1AgentsByAgentIdMessagesErrors[keyof PostApiV1AgentsByAgentIdMessagesErrors]; + +export type PostApiV1AgentsByAgentIdMessagesResponses = { + /** + * Message queued + */ + 200: { + success: boolean; + messageId: string; + agentId?: string; + jobId?: string; + eventsUrl?: string; + queued: boolean; + traceparent?: string; + }; +}; + +export type PostApiV1AgentsByAgentIdMessagesResponse = + PostApiV1AgentsByAgentIdMessagesResponses[keyof PostApiV1AgentsByAgentIdMessagesResponses]; + +export type GetApiV1AgentsByAgentIdConfigData = { + body?: never; + path?: never; + query?: { + token?: string; + }; + url: "/api/v1/agents/{agentId}/config"; +}; + +export type GetApiV1AgentsByAgentIdConfigErrors = { + /** + * Unauthorized + */ + 401: { + error: string; + }; +}; + +export type GetApiV1AgentsByAgentIdConfigError = + GetApiV1AgentsByAgentIdConfigErrors[keyof GetApiV1AgentsByAgentIdConfigErrors]; + +export type GetApiV1AgentsByAgentIdConfigResponses = { + /** + * Configuration + */ + 200: unknown; +}; + +export type PostApiV1AuthByProviderCodeData = { + body?: { + code: string; + }; + path: { + provider: string; + }; + query?: { + token?: string; + }; + url: "/api/v1/auth/{provider}/code"; +}; + +export type PostApiV1AuthByProviderCodeErrors = { + /** + * Invalid + */ + 400: { + error: string; + }; + /** + * Unauthorized + */ + 401: { + error: string; + }; +}; + +export type PostApiV1AuthByProviderCodeError = + PostApiV1AuthByProviderCodeErrors[keyof PostApiV1AuthByProviderCodeErrors]; + +export type PostApiV1AuthByProviderCodeResponses = { + /** + * Exchanged + */ + 200: { + success: boolean; + }; +}; + +export type PostApiV1AuthByProviderCodeResponse = + PostApiV1AuthByProviderCodeResponses[keyof PostApiV1AuthByProviderCodeResponses]; + +export type GetApiV1ConnectionsData = { + body?: never; + path?: never; + query?: { + platform?: + | "telegram" + | "slack" + | "discord" + | "whatsapp" + | "teams" + | "gchat"; + agentId?: string; + }; + url: "/api/v1/connections"; +}; + +export type GetApiV1ConnectionsErrors = { + /** + * Unauthorized + */ + 401: { + error: string; + }; + /** + * Forbidden + */ + 403: { + error: string; + }; +}; + +export type GetApiV1ConnectionsError = + GetApiV1ConnectionsErrors[keyof GetApiV1ConnectionsErrors]; + +export type GetApiV1ConnectionsResponses = { + /** + * Connections + */ + 200: { + connections: Array<{ + id: string; + platform: + | "telegram" + | "slack" + | "discord" + | "whatsapp" + | "teams" + | "gchat"; + agentId?: string; + config: + | { + platform: "telegram"; + /** + * Telegram bot token from BotFather. Falls back to TELEGRAM_BOT_TOKEN env var. + */ + botToken?: string; + /** + * Runtime mode: auto (default), webhook, or polling. + */ + mode?: "auto" | "webhook" | "polling"; + /** + * Webhook secret token for x-telegram-bot-api-secret-token verification. + */ + secretToken?: string; + /** + * Override bot username. + */ + userName?: string; + /** + * Custom Telegram API base URL. + */ + apiBaseUrl?: string; + } + | { + platform: "slack"; + /** + * Bot token (xoxb-...). Required for single-workspace mode. + */ + botToken?: string; + /** + * Bot user ID (fetched automatically if omitted). + */ + botUserId?: string; + /** + * Signing secret for webhook verification. + */ + signingSecret?: string; + /** + * Slack app client ID (required for OAuth / multi-workspace). + */ + clientId?: string; + /** + * Slack app client secret (required for OAuth / multi-workspace). + */ + clientSecret?: string; + /** + * Base64-encoded 32-byte AES-256-GCM key for encrypting stored bot tokens. + */ + encryptionKey?: string; + /** + * State key prefix for workspace installations (default: slack:installation). + */ + installationKeyPrefix?: string; + /** + * Override bot username. + */ + userName?: string; + } + | { + platform: "discord"; + /** + * Discord bot token. + */ + botToken?: string; + /** + * Discord application ID. + */ + applicationId?: string; + /** + * Application public key for webhook signature verification. + */ + publicKey?: string; + /** + * Role IDs that trigger mention handlers (in addition to direct mentions). + */ + mentionRoleIds?: Array; + /** + * Override bot username. + */ + userName?: string; + } + | { + platform: "whatsapp"; + /** + * System User access token for WhatsApp Cloud API. + */ + accessToken?: string; + /** + * WhatsApp Business phone number ID. + */ + phoneNumberId?: string; + /** + * Meta App Secret for webhook HMAC-SHA256 signature verification. + */ + appSecret?: string; + /** + * Verify token for webhook challenge-response. + */ + verifyToken?: string; + /** + * Meta Graph API version (default: v21.0). + */ + apiVersion?: string; + /** + * Bot display name. + */ + userName?: string; + } + | { + platform: "teams"; + /** + * Microsoft App ID. + */ + appId?: string; + /** + * Microsoft App Password. + */ + appPassword?: string; + /** + * Microsoft App Tenant ID. + */ + appTenantId?: string; + /** + * Microsoft App Type. + */ + appType?: "MultiTenant" | "SingleTenant"; + /** + * Override bot username. + */ + userName?: string; + } + | { + platform: "gchat"; + /** + * Service account credentials JSON string. Defaults to GOOGLE_CHAT_CREDENTIALS env var. + */ + credentials?: string; + /** + * Use Application Default Credentials (ADC) instead of service account JSON. + */ + useApplicationDefaultCredentials?: boolean; + /** + * HTTP endpoint URL for button click actions. Required for HTTP endpoint apps. + */ + endpointUrl?: string; + /** + * Google Cloud project number for verifying webhook JWTs. Defaults to GOOGLE_CHAT_PROJECT_NUMBER env var. + */ + googleChatProjectNumber?: string; + /** + * User email for domain-wide delegation. Defaults to GOOGLE_CHAT_IMPERSONATE_USER env var. + */ + impersonateUser?: string; + /** + * Expected audience for Pub/Sub push JWT verification. Defaults to GOOGLE_CHAT_PUBSUB_AUDIENCE env var. + */ + pubsubAudience?: string; + /** + * Override bot username. + */ + userName?: string; + }; + settings: { + /** + * User IDs allowed to interact with this connection. Omit to allow all; empty array blocks all. + */ + allowFrom?: Array; + /** + * Whether group messages are allowed (default true). + */ + allowGroups?: boolean; + /** + * Scopes that end users are allowed to customize. Empty = no restrictions. + */ + userConfigScopes?: Array< + | "model" + | "view-model" + | "system-prompt" + | "skills" + | "permissions" + | "packages" + >; + }; + metadata: { + [key: string]: unknown; + }; + status: "active" | "stopped" | "error"; + errorMessage?: string; + createdAt: number; + updatedAt: number; + }>; + }; +}; + +export type GetApiV1ConnectionsResponse = + GetApiV1ConnectionsResponses[keyof GetApiV1ConnectionsResponses]; + +export type GetApiV1ConnectionsByIdData = { + body?: never; + path: { + id: string; + }; + query?: never; + url: "/api/v1/connections/{id}"; +}; + +export type GetApiV1ConnectionsByIdErrors = { + /** + * Unauthorized + */ + 401: { + error: string; + }; + /** + * Forbidden + */ + 403: { + error: string; + }; + /** + * Connection not found + */ + 404: { + error: string; + }; +}; + +export type GetApiV1ConnectionsByIdError = + GetApiV1ConnectionsByIdErrors[keyof GetApiV1ConnectionsByIdErrors]; + +export type GetApiV1ConnectionsByIdResponses = { + /** + * Connection + */ + 200: { + id: string; + platform: "telegram" | "slack" | "discord" | "whatsapp" | "teams" | "gchat"; + agentId?: string; + config: + | { + platform: "telegram"; + /** + * Telegram bot token from BotFather. Falls back to TELEGRAM_BOT_TOKEN env var. + */ + botToken?: string; + /** + * Runtime mode: auto (default), webhook, or polling. + */ + mode?: "auto" | "webhook" | "polling"; + /** + * Webhook secret token for x-telegram-bot-api-secret-token verification. + */ + secretToken?: string; + /** + * Override bot username. + */ + userName?: string; + /** + * Custom Telegram API base URL. + */ + apiBaseUrl?: string; + } + | { + platform: "slack"; + /** + * Bot token (xoxb-...). Required for single-workspace mode. + */ + botToken?: string; + /** + * Bot user ID (fetched automatically if omitted). + */ + botUserId?: string; + /** + * Signing secret for webhook verification. + */ + signingSecret?: string; + /** + * Slack app client ID (required for OAuth / multi-workspace). + */ + clientId?: string; + /** + * Slack app client secret (required for OAuth / multi-workspace). + */ + clientSecret?: string; + /** + * Base64-encoded 32-byte AES-256-GCM key for encrypting stored bot tokens. + */ + encryptionKey?: string; + /** + * State key prefix for workspace installations (default: slack:installation). + */ + installationKeyPrefix?: string; + /** + * Override bot username. + */ + userName?: string; + } + | { + platform: "discord"; + /** + * Discord bot token. + */ + botToken?: string; + /** + * Discord application ID. + */ + applicationId?: string; + /** + * Application public key for webhook signature verification. + */ + publicKey?: string; + /** + * Role IDs that trigger mention handlers (in addition to direct mentions). + */ + mentionRoleIds?: Array; + /** + * Override bot username. + */ + userName?: string; + } + | { + platform: "whatsapp"; + /** + * System User access token for WhatsApp Cloud API. + */ + accessToken?: string; + /** + * WhatsApp Business phone number ID. + */ + phoneNumberId?: string; + /** + * Meta App Secret for webhook HMAC-SHA256 signature verification. + */ + appSecret?: string; + /** + * Verify token for webhook challenge-response. + */ + verifyToken?: string; + /** + * Meta Graph API version (default: v21.0). + */ + apiVersion?: string; + /** + * Bot display name. + */ + userName?: string; + } + | { + platform: "teams"; + /** + * Microsoft App ID. + */ + appId?: string; + /** + * Microsoft App Password. + */ + appPassword?: string; + /** + * Microsoft App Tenant ID. + */ + appTenantId?: string; + /** + * Microsoft App Type. + */ + appType?: "MultiTenant" | "SingleTenant"; + /** + * Override bot username. + */ + userName?: string; + } + | { + platform: "gchat"; + /** + * Service account credentials JSON string. Defaults to GOOGLE_CHAT_CREDENTIALS env var. + */ + credentials?: string; + /** + * Use Application Default Credentials (ADC) instead of service account JSON. + */ + useApplicationDefaultCredentials?: boolean; + /** + * HTTP endpoint URL for button click actions. Required for HTTP endpoint apps. + */ + endpointUrl?: string; + /** + * Google Cloud project number for verifying webhook JWTs. Defaults to GOOGLE_CHAT_PROJECT_NUMBER env var. + */ + googleChatProjectNumber?: string; + /** + * User email for domain-wide delegation. Defaults to GOOGLE_CHAT_IMPERSONATE_USER env var. + */ + impersonateUser?: string; + /** + * Expected audience for Pub/Sub push JWT verification. Defaults to GOOGLE_CHAT_PUBSUB_AUDIENCE env var. + */ + pubsubAudience?: string; + /** + * Override bot username. + */ + userName?: string; + }; + settings: { + /** + * User IDs allowed to interact with this connection. Omit to allow all; empty array blocks all. + */ + allowFrom?: Array; + /** + * Whether group messages are allowed (default true). + */ + allowGroups?: boolean; + /** + * Scopes that end users are allowed to customize. Empty = no restrictions. + */ + userConfigScopes?: Array< + | "model" + | "view-model" + | "system-prompt" + | "skills" + | "permissions" + | "packages" + >; + }; + metadata: { + [key: string]: unknown; + }; + status: "active" | "stopped" | "error"; + errorMessage?: string; + createdAt: number; + updatedAt: number; + }; +}; + +export type GetApiV1ConnectionsByIdResponse = + GetApiV1ConnectionsByIdResponses[keyof GetApiV1ConnectionsByIdResponses]; + +export type GetApiBedrockHealthData = { + body?: never; + path?: never; + query?: never; + url: "/api/bedrock/health"; +}; + +export type GetApiBedrockHealthResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiBedrockOpenaiAByAgentIdV1ModelsData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/bedrock/openai/a/{agentId}/v1/models"; +}; + +export type GetApiBedrockOpenaiAByAgentIdV1ModelsResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type PostApiBedrockOpenaiAByAgentIdV1ChatCompletionsData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/bedrock/openai/a/{agentId}/v1/chat/completions"; +}; + +export type PostApiBedrockOpenaiAByAgentIdV1ChatCompletionsResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiV1FilesByArtifactIdData = { + body?: never; + path: { + artifactId: string; + }; + query?: never; + url: "/api/v1/files/{artifactId}"; +}; + +export type GetApiV1FilesByArtifactIdResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type PostApiV1AgentsApproveData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/agents/approve"; +}; + +export type PostApiV1AgentsApproveResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetConnectClaimData = { + body?: never; + path?: never; + query?: never; + url: "/connect/claim"; +}; + +export type GetConnectClaimResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiV1AgentsByAgentIdHistoryStatusData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/history/status"; +}; + +export type GetApiV1AgentsByAgentIdHistoryStatusResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiV1AgentsByAgentIdHistorySessionMessagesData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/history/session/messages"; +}; + +export type GetApiV1AgentsByAgentIdHistorySessionMessagesResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiV1AgentsByAgentIdHistorySessionStatsData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/history/session/stats"; +}; + +export type GetApiV1AgentsByAgentIdHistorySessionStatsResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiV1AgentsByAgentIdConfigProvidersCatalogData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/config/providers/catalog"; +}; + +export type GetApiV1AgentsByAgentIdConfigProvidersCatalogResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiV1AgentsByAgentIdConfigGrantsData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/config/grants"; +}; + +export type GetApiV1AgentsByAgentIdConfigGrantsResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type PostApiV1AuthByProviderSaveKeyData = { + body?: never; + path: { + provider: string; + }; + query?: never; + url: "/api/v1/auth/{provider}/save-key"; +}; + +export type PostApiV1AuthByProviderSaveKeyResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type PostApiV1AuthByProviderStartData = { + body?: never; + path: { + provider: string; + }; + query?: never; + url: "/api/v1/auth/{provider}/start"; +}; + +export type PostApiV1AuthByProviderStartResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type PostApiV1AuthByProviderPollData = { + body?: never; + path: { + provider: string; + }; + query?: never; + url: "/api/v1/auth/{provider}/poll"; +}; + +export type PostApiV1AuthByProviderPollResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type PostApiV1AuthByProviderLogoutData = { + body?: never; + path: { + provider: string; + }; + query?: never; + url: "/api/v1/auth/{provider}/logout"; +}; + +export type PostApiV1AuthByProviderLogoutResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type GetApiV1AgentsByAgentIdChannelsData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/channels"; +}; + +export type GetApiV1AgentsByAgentIdChannelsResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type PostApiV1AgentsByAgentIdChannelsData = { + body?: never; + path: { + agentId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/channels"; +}; + +export type PostApiV1AgentsByAgentIdChannelsResponses = { + /** + * OK + */ + 200: unknown; +}; + +export type DeleteApiV1AgentsByAgentIdChannelsByPlatformByChannelIdData = { + body?: never; + path: { + agentId: string; + platform: string; + channelId: string; + }; + query?: never; + url: "/api/v1/agents/{agentId}/channels/{platform}/{channelId}"; +}; + +export type DeleteApiV1AgentsByAgentIdChannelsByPlatformByChannelIdResponses = { + /** + * OK + */ + 200: unknown; +}; diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts new file mode 100644 index 000000000..479731470 --- /dev/null +++ b/packages/client/src/index.ts @@ -0,0 +1,16 @@ +export * as generated from "./generated/index.js"; +export { Lobu } from "./client.js"; +export { LobuApiError } from "./errors.js"; +export { AgentSession } from "./session.js"; +export type { + CreateSessionRequest, + CreateSessionResponse, + LobuClientOptions, + LobuFetch, + LobuHeaders, + LobuSseEvent, + SendMessageOptions, + SendMessageResponse, + StreamEventsOptions, + TokenProvider, +} from "./types.js"; diff --git a/packages/client/src/rest.ts b/packages/client/src/rest.ts new file mode 100644 index 000000000..204205e6a --- /dev/null +++ b/packages/client/src/rest.ts @@ -0,0 +1,177 @@ +import { LobuApiError } from "./errors.js"; +import { + getApiV1AgentsByAgentIdEvents, + postApiV1Agents, + postApiV1AgentsByAgentIdMessages, +} from "./generated/sdk.gen.js"; +import { createClient, type Client } from "./generated/client/index.js"; +import type { + CreateSessionRequest, + CreateSessionResponse, + LobuFetch, + LobuHeaders, + LobuSseEvent, + SendMessageOptions, + SendMessageResponse, + StreamEventsOptions, + TokenProvider, +} from "./types.js"; + +export class LobuRestClient { + private readonly token: TokenProvider; + private readonly fetchImpl: LobuFetch; + private readonly headers: LobuHeaders | undefined; + private readonly client: Client; + + constructor(options: { + baseUrl: string; + token: TokenProvider; + fetch: LobuFetch; + headers?: LobuHeaders; + }) { + this.token = options.token; + this.fetchImpl = options.fetch; + this.headers = options.headers; + this.client = createClient({ + baseUrl: normalizeBaseUrl(options.baseUrl), + fetch: options.fetch, + }); + } + + async createSession( + input: CreateSessionRequest + ): Promise { + const result = await postApiV1Agents({ + client: this.client, + body: input, + headers: await this.authHeaders(), + }); + if (result.error) throw new LobuApiError(result.response, result.error); + return result.data; + } + + async sendMessage( + sessionId: string, + sessionToken: string, + content: string, + options: SendMessageOptions = {} + ): Promise { + const result = await postApiV1AgentsByAgentIdMessages({ + client: this.client, + path: { agentId: sessionId }, + body: { content, messageId: options.messageId }, + headers: this.authHeadersFor(sessionToken), + }); + if (result.error) throw new LobuApiError(result.response, result.error); + return result.data; + } + + async *streamEvents( + sessionId: string, + sessionToken: string, + options: StreamEventsOptions = {} + ): AsyncIterable> { + const controller = new AbortController(); + const abort = () => controller.abort(); + options.signal?.addEventListener("abort", abort, { once: true }); + if (options.signal?.aborted) controller.abort(); + + const queue: Array> = []; + let done = false; + let pumpError: unknown; + let wake: (() => void) | undefined; + + const wakeReader = () => { + wake?.(); + wake = undefined; + }; + + const result = await getApiV1AgentsByAgentIdEvents({ + client: this.client, + path: { agentId: sessionId }, + headers: { + ...this.authHeadersFor(sessionToken), + ...headersToRecord(options.headers), + }, + signal: controller.signal, + onSseEvent: (event) => { + queue.push({ + event: event.event ?? "message", + data: event.data as TData, + id: event.id, + retry: event.retry, + }); + wakeReader(); + }, + }); + + const pump = (async () => { + try { + for await (const _data of result.stream) { + // onSseEvent above preserves event names. The generated stream yields + // only data payloads, so the queue is the public SDK surface. + } + } catch (error) { + pumpError = error; + } finally { + done = true; + wakeReader(); + } + })(); + + try { + while (!done || queue.length > 0) { + const event = queue.shift(); + if (event) { + yield event; + continue; + } + if (pumpError) throw pumpError; + await new Promise((resolve) => { + wake = resolve; + }); + } + if (pumpError) throw pumpError; + } finally { + controller.abort(); + options.signal?.removeEventListener("abort", abort); + await pump; + } + } + + getFetch(): LobuFetch { + return this.fetchImpl; + } + + private async authHeaders(): Promise> { + return this.authHeadersFor(await resolveToken(this.token)); + } + + private authHeadersFor(token: string): Record { + return { + ...headersToRecord(this.headers), + Authorization: `Bearer ${token}`, + }; + } +} + +async function resolveToken(provider: TokenProvider): Promise { + return typeof provider === "function" ? provider() : provider; +} + +function normalizeBaseUrl(baseUrl: string): string { + const trimmed = baseUrl.trim().replace(/\/+$/, ""); + if (!trimmed) throw new Error("Lobu baseUrl is required"); + return trimmed; +} + +function headersToRecord( + headers: LobuHeaders | RequestInit["headers"] | undefined +): Record { + if (!headers) return {}; + if (headers instanceof Headers) return Object.fromEntries(headers.entries()); + if (Array.isArray(headers)) { + return Object.fromEntries(headers as Iterable); + } + return headers as Record; +} diff --git a/packages/client/src/session.ts b/packages/client/src/session.ts new file mode 100644 index 000000000..ee8269f2a --- /dev/null +++ b/packages/client/src/session.ts @@ -0,0 +1,40 @@ +import type { LobuRestClient } from "./rest.js"; +import type { + CreateSessionResponse, + LobuSseEvent, + SendMessageOptions, + SendMessageResponse, + StreamEventsOptions, +} from "./types.js"; + +export class AgentSession { + readonly agentId: string; + readonly token: string; + readonly expiresAt: number; + readonly sseUrl: string; + readonly messagesUrl: string; + + constructor( + private readonly rest: LobuRestClient, + response: CreateSessionResponse + ) { + this.agentId = response.agentId; + this.token = response.token; + this.expiresAt = response.expiresAt; + this.sseUrl = response.sseUrl; + this.messagesUrl = response.messagesUrl; + } + + send( + content: string, + options?: SendMessageOptions + ): Promise { + return this.rest.sendMessage(this.agentId, this.token, content, options); + } + + events( + options: StreamEventsOptions = {} + ): AsyncIterable> { + return this.rest.streamEvents(this.agentId, this.token, options); + } +} diff --git a/packages/client/src/types.ts b/packages/client/src/types.ts new file mode 100644 index 000000000..0fe8aef73 --- /dev/null +++ b/packages/client/src/types.ts @@ -0,0 +1,79 @@ +export type TokenProvider = string | (() => string | Promise); + +export type LobuFetch = typeof fetch; +export type LobuHeaders = + | Headers + | Record + | ReadonlyArray; + +export interface LobuClientOptions { + baseUrl: string; + token: TokenProvider; + fetch?: LobuFetch; + headers?: LobuHeaders; +} + +export interface CreateSessionRequest { + agentId?: string; + userId?: string; + thread?: string; + provider?: string; + model?: string; + forceNew?: boolean; + dryRun?: boolean; + networkConfig?: { + allowedDomains?: string[]; + deniedDomains?: string[]; + }; + mcpServers?: Record< + string, + { + url?: string; + type?: "sse" | "streamable-http" | "stdio"; + command?: string; + args?: string[]; + env?: Record; + headers?: Record; + description?: string; + } + >; + nix?: { + flakeUrl?: string; + packages?: string[]; + }; +} + +export interface CreateSessionResponse { + success: boolean; + agentId: string; + token: string; + expiresAt: number; + sseUrl: string; + messagesUrl: string; +} + +export interface SendMessageOptions { + messageId?: string; +} + +export interface SendMessageResponse { + success: boolean; + messageId: string; + agentId?: string; + jobId?: string; + eventsUrl?: string; + queued: boolean; + traceparent?: string; +} + +export interface LobuSseEvent { + event: string; + data: TData; + id?: string; + retry?: number; +} + +export interface StreamEventsOptions { + signal?: AbortSignal; + headers?: LobuHeaders; +} diff --git a/packages/client/tsconfig.json b/packages/client/tsconfig.json new file mode 100644 index 000000000..b2ced6da4 --- /dev/null +++ b/packages/client/tsconfig.json @@ -0,0 +1,23 @@ +{ + "compilerOptions": { + "outDir": "dist", + "rootDir": "src", + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "noEmit": false, + "module": "ES2022", + "moduleResolution": "bundler", + "target": "ES2022", + "lib": ["ES2022", "DOM", "DOM.Iterable"], + "strict": true, + "skipLibCheck": true, + "noFallthroughCasesInSwitch": true, + "noUncheckedIndexedAccess": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "verbatimModuleSyntax": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "src/__tests__/**/*"] +} diff --git a/release-please-config.json b/release-please-config.json index ef39a35e3..e0161ed93 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -36,6 +36,11 @@ "path": "packages/connector-sdk/package.json", "jsonpath": "$.version" }, + { + "type": "json", + "path": "packages/client/package.json", + "jsonpath": "$.version" + }, { "type": "json", "path": "packages/openclaw-plugin/package.json", diff --git a/scripts/bump-version.mjs b/scripts/bump-version.mjs index d3168a504..501f07872 100644 --- a/scripts/bump-version.mjs +++ b/scripts/bump-version.mjs @@ -8,6 +8,7 @@ const PACKAGES = [ "packages/agent-worker", "packages/cli", "packages/connector-sdk", + "packages/client", "packages/openclaw-plugin", "packages/connectors", "packages/connector-worker", diff --git a/scripts/publish-packages.mjs b/scripts/publish-packages.mjs index 08072a386..9462c2f0d 100644 --- a/scripts/publish-packages.mjs +++ b/scripts/publish-packages.mjs @@ -22,6 +22,7 @@ const REPO_ROOT = process.cwd(); const PACKAGES = [ { dir: "packages/core", transform: transformCorePublish }, { dir: "packages/connector-sdk", transform: rewriteWorkspaceRefs }, + { dir: "packages/client", transform: rewriteWorkspaceRefs }, { dir: "packages/agent-worker", transform: rewriteWorkspaceRefs }, { dir: "packages/embeddings", transform: rewriteWorkspaceRefs }, // @lobu/pgvector-embedded is NOT published: it's `private` and ships its diff --git a/tsconfig.json b/tsconfig.json index 5f14f9d6b..ee6610817 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -35,6 +35,8 @@ "@lobu/worker/*": ["packages/agent-worker/src/*"], "@lobu/connector-sdk": ["packages/connector-sdk/src/index.ts"], "@lobu/connector-sdk/*": ["packages/connector-sdk/src/*"], + "@lobu/client": ["packages/client/src/index.ts"], + "@lobu/client/*": ["packages/client/src/*"], "@lobu/openclaw-plugin": ["packages/openclaw-plugin/src/index.ts"], "@lobu/openclaw-plugin/*": ["packages/openclaw-plugin/src/*"], "@lobu/connector-worker/*": ["packages/connector-worker/src/*"], @@ -47,6 +49,7 @@ "node_modules", "packages/*/src/__tests__/**/*", "packages/cli/**/*", + "packages/client/**/*", "packages/landing/**/*", "packages/server/**/*", "packages/connector-sdk/**/*", From 065e72370c7a0dd641fbe88c03a7171aad3cff37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 16:59:36 +0100 Subject: [PATCH 02/65] feat(connector-sdk): add defineConnector functional authoring API Functional sugar over ConnectorRuntime: declare a connector as a spec with per-feed sync and per-action execute handlers (feed/action keys derived from the record keys). Lowers to a ConnectorRuntime subclass so connector-worker's child-runner runs it unchanged; handler closures are stripped from the serializable definition. Unit test mirrors child-runner's findRuntimeClass detection to prove a bundled default export is picked up unchanged. --- .../src/__tests__/define-connector.test.ts | 131 +++++++++++++++ .../connector-sdk/src/define-connector.ts | 158 ++++++++++++++++++ packages/connector-sdk/src/index.ts | 7 + 3 files changed, 296 insertions(+) create mode 100644 packages/connector-sdk/src/__tests__/define-connector.test.ts create mode 100644 packages/connector-sdk/src/define-connector.ts diff --git a/packages/connector-sdk/src/__tests__/define-connector.test.ts b/packages/connector-sdk/src/__tests__/define-connector.test.ts new file mode 100644 index 000000000..e76a681d4 --- /dev/null +++ b/packages/connector-sdk/src/__tests__/define-connector.test.ts @@ -0,0 +1,131 @@ +import { describe, expect, test } from "bun:test"; +import { ConnectorRuntime } from "../connector-runtime.js"; +import { defineConnector } from "../define-connector.js"; + +// Mirrors connector-worker/src/executor/child-runner.ts `findRuntimeClass`: a +// connector is detected by a constructor whose prototype has sync() + execute(). +// If this passes, an esbuild-bundled `export default defineConnector(...)` is +// picked up by the worker unchanged. +function isConnectorRuntimeClass(val: unknown): boolean { + return ( + typeof val === "function" && + !!(val as { prototype?: { sync?: unknown } }).prototype?.sync && + !!(val as { prototype?: { execute?: unknown } }).prototype?.execute + ); +} + +const Github = defineConnector({ + key: "github", + name: "GitHub", + version: "1.0.0", + feeds: { + stars: { + name: "Stars", + sync: async (ctx) => ({ + events: [ + { + origin_id: ctx.feedKey, + payload_text: "star", + occurred_at: new Date(), + }, + ], + checkpoint: { seen: 1 }, + }), + }, + }, + actions: { + star_repo: { + name: "Star repo", + execute: async (ctx) => ({ + success: true, + output: { repo: ctx.input.repo }, + }), + }, + }, +}); + +describe("defineConnector", () => { + test("returns a ConnectorRuntime subclass the worker can detect", () => { + expect(isConnectorRuntimeClass(Github)).toBe(true); + expect(new Github()).toBeInstanceOf(ConnectorRuntime); + }); + + test("lowers the spec to a ConnectorDefinition with keys from the record keys", () => { + const { definition } = new Github(); + expect(definition.key).toBe("github"); + expect(definition.version).toBe("1.0.0"); + expect(definition.feeds?.stars?.key).toBe("stars"); + expect(definition.feeds?.stars?.name).toBe("Stars"); + expect(definition.actions?.star_repo?.key).toBe("star_repo"); + // requiresApproval defaults to false + expect(definition.actions?.star_repo?.requiresApproval).toBe(false); + // handler closures must NOT leak into the serializable definition + expect( + (definition.feeds?.stars as Record).sync, + ).toBeUndefined(); + expect( + (definition.actions?.star_repo as Record).execute, + ).toBeUndefined(); + }); + + test("sync dispatches to the matching feed handler", async () => { + const res = await new Github().sync({ + feedKey: "stars", + config: {}, + checkpoint: null, + credentials: null, + entityIds: [], + }); + expect(res.events).toHaveLength(1); + expect(res.checkpoint).toEqual({ seen: 1 }); + }); + + test("sync throws for an unknown feed", () => { + expect( + new Github().sync({ + feedKey: "nope", + config: {}, + checkpoint: null, + credentials: null, + entityIds: [], + }), + ).rejects.toThrow(/no sync handler for feed 'nope'/); + }); + + test("execute dispatches to the matching action handler", async () => { + const res = await new Github().execute({ + actionKey: "star_repo", + input: { repo: "lobu-ai/lobu" }, + credentials: null, + config: {}, + }); + expect(res).toEqual({ success: true, output: { repo: "lobu-ai/lobu" } }); + }); + + test("execute returns an error result for an unknown action", async () => { + const res = await new Github().execute({ + actionKey: "nope", + input: {}, + credentials: null, + config: {}, + }); + expect(res.success).toBe(false); + expect(res.error).toMatch(/no action handler/); + }); + + test("a feeds-only connector still satisfies the worker contract", () => { + const ReadOnly = defineConnector({ + key: "ro", + name: "ReadOnly", + version: "0.0.1", + feeds: { + items: { + name: "Items", + sync: async () => ({ events: [], checkpoint: null }), + }, + }, + }); + expect(isConnectorRuntimeClass(ReadOnly)).toBe(true); + expect(new ReadOnly().definition.actions).toBeUndefined(); + }); +}); diff --git a/packages/connector-sdk/src/define-connector.ts b/packages/connector-sdk/src/define-connector.ts new file mode 100644 index 000000000..ac820eac7 --- /dev/null +++ b/packages/connector-sdk/src/define-connector.ts @@ -0,0 +1,158 @@ +/** + * defineConnector — functional authoring sugar over {@link ConnectorRuntime}. + * + * Lets a connector be declared as a plain spec with per-feed `sync` and + * per-action `execute` handlers, instead of hand-writing a class that switches + * on `ctx.feedKey` / `ctx.actionKey`. The feed/action keys are taken from the + * record keys, so they're never repeated. + * + * It LOWERS to a real `ConnectorRuntime` subclass so the existing + * connector-worker runs it unchanged: `child-runner` detects a connector by + * looking for a constructor whose prototype has `sync()` and `execute()`, then + * instantiates it and reads `instance.definition`. The class returned here + * satisfies that contract exactly. + * + * `@lobu/connector-sdk` is externalized at connector compile time, so this + * function ships as runtime-provided SDK code while the caller's handler + * closures get bundled into the connector — the spec object (with its + * `sync`/`execute` functions) is captured by the returned class. + * + * @example + * ```ts + * export default defineConnector({ + * key: 'github', name: 'GitHub', version: '1.0.0', + * feeds: { stars: { name: 'Stars', sync: async (ctx) => ({ events, checkpoint }) } }, + * actions: { star_repo: { name: 'Star', execute: async (ctx) => ({ success: true }) } }, + * }); + * ``` + */ + +import { ConnectorRuntime } from "./connector-runtime.js"; +import type { + ActionContext, + ActionDefinition, + ActionResult, + ConnectorDefinition, + FeedDefinition, + SyncContext, + SyncResult, +} from "./connector-types.js"; + +/** A feed's metadata (minus the record-derived `key`) plus its `sync` handler. */ +export interface ConnectorFeedSpec< + C = Record, + F = Record, +> extends Omit { + /** Ingest handler for this feed. Called by the worker for a `sync` run. */ + sync(ctx: SyncContext): Promise>; +} + +/** An action's metadata (minus `key`; `requiresApproval` defaults false) plus its `execute` handler. */ +export interface ConnectorActionSpec + extends Omit { + /** Whether the action needs human approval before execution. Defaults to `false`. */ + requiresApproval?: boolean; + /** Effect handler for this action. Called inline (low-risk) or by the worker. */ + execute(ctx: ActionContext): Promise; +} + +/** Functional connector spec: connector metadata plus handler-bearing feeds/actions. */ +export interface ConnectorSpec + extends Omit { + feeds?: Record; + actions?: Record; +} + +/** Constructor shape the connector-worker's `child-runner` detects and instantiates. */ +export type ConnectorClass = new () => ConnectorRuntime; + +/** Strip handler closures and derive `key` from the record key — keeps the definition serializable. */ +function buildDefinition(spec: ConnectorSpec): ConnectorDefinition { + const definition: ConnectorDefinition = { + key: spec.key, + name: spec.name, + version: spec.version, + description: spec.description, + authSchema: spec.authSchema, + optionsSchema: spec.optionsSchema, + faviconDomain: spec.faviconDomain, + mcpConfig: spec.mcpConfig, + openapiConfig: spec.openapiConfig, + requiredCapability: spec.requiredCapability, + runtime: spec.runtime, + }; + + if (spec.feeds) { + definition.feeds = Object.fromEntries( + Object.entries(spec.feeds).map( + ([key, feed]): [string, FeedDefinition] => [ + key, + { + key, + name: feed.name, + description: feed.description, + requiredScopes: feed.requiredScopes, + displayNameTemplate: feed.displayNameTemplate, + configSchema: feed.configSchema, + userManaged: feed.userManaged, + eventKinds: feed.eventKinds, + }, + ], + ), + ); + } + + if (spec.actions) { + definition.actions = Object.fromEntries( + Object.entries(spec.actions).map( + ([key, action]): [string, ActionDefinition] => [ + key, + { + key, + name: action.name, + description: action.description, + requiresApproval: action.requiresApproval ?? false, + annotations: action.annotations, + inputSchema: action.inputSchema, + outputSchema: action.outputSchema, + }, + ], + ), + ); + } + + return definition; +} + +/** + * Build a {@link ConnectorRuntime} subclass from a functional spec. The default + * export of a `.connector.ts` should be the returned class. + */ +export function defineConnector(spec: ConnectorSpec): ConnectorClass { + const definition = buildDefinition(spec); + + return class extends ConnectorRuntime { + readonly definition = definition; + + async sync(ctx: SyncContext): Promise { + const feed = spec.feeds?.[ctx.feedKey]; + if (!feed) { + throw new Error( + `Connector '${spec.key}' has no sync handler for feed '${ctx.feedKey}'`, + ); + } + return feed.sync(ctx); + } + + async execute(ctx: ActionContext): Promise { + const action = spec.actions?.[ctx.actionKey]; + if (!action) { + return { + success: false, + error: `Connector '${spec.key}' has no action handler for '${ctx.actionKey}'`, + }; + } + return action.execute(ctx); + } + }; +} diff --git a/packages/connector-sdk/src/index.ts b/packages/connector-sdk/src/index.ts index b9f922b75..c9a033ab6 100644 --- a/packages/connector-sdk/src/index.ts +++ b/packages/connector-sdk/src/index.ts @@ -10,6 +10,13 @@ export type { KyInstance, Options } from 'ky'; export { default as ky, HTTPError } from 'ky'; // Connector runtime & types (primary API) export { ConnectorRuntime } from './connector-runtime.js'; +export { defineConnector } from './define-connector.js'; +export type { + ConnectorActionSpec, + ConnectorClass, + ConnectorFeedSpec, + ConnectorSpec, +} from './define-connector.js'; export type { ActionContext, ActionDefinition, From 9f2155a78af8418366e023315e9fa198c36c04a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 17:10:22 +0100 Subject: [PATCH 03/65] feat(connector-sdk): support optional authenticate flow in defineConnector Adds an optional authenticate(ctx) hook to the functional spec, lowered to ConnectorRuntime.authenticate. When omitted, the connector inherits the base behavior (throws). Closes the gap where interactive-auth connectors required the class form, making defineConnector feature-complete vs the class. --- .../src/__tests__/define-connector.test.ts | 29 +++ .../connector-sdk/src/define-connector.ts | 207 ++++++++++-------- 2 files changed, 139 insertions(+), 97 deletions(-) diff --git a/packages/connector-sdk/src/__tests__/define-connector.test.ts b/packages/connector-sdk/src/__tests__/define-connector.test.ts index e76a681d4..dec0b4f98 100644 --- a/packages/connector-sdk/src/__tests__/define-connector.test.ts +++ b/packages/connector-sdk/src/__tests__/define-connector.test.ts @@ -128,4 +128,33 @@ describe("defineConnector", () => { expect(isConnectorRuntimeClass(ReadOnly)).toBe(true); expect(new ReadOnly().definition.actions).toBeUndefined(); }); + + const authCtx = () => ({ + config: {}, + previousCredentials: null, + emit: async () => {}, + awaitSignal: async () => ({}), + signal: new AbortController().signal, + }); + + test("authenticate dispatches to the spec handler when provided", async () => { + const WithAuth = defineConnector({ + key: "wa", + name: "WithAuth", + version: "0.0.1", + feeds: { + f: { name: "F", sync: async () => ({ events: [], checkpoint: null }) }, + }, + authenticate: async () => ({ credentials: { token: "t" } }), + }); + await expect(new WithAuth().authenticate(authCtx())).resolves.toEqual({ + credentials: { token: "t" }, + }); + }); + + test("authenticate throws by default when no handler is provided", () => { + expect(new Github().authenticate(authCtx())).rejects.toThrow( + /interactive authentication/, + ); + }); }); diff --git a/packages/connector-sdk/src/define-connector.ts b/packages/connector-sdk/src/define-connector.ts index ac820eac7..2fa618d47 100644 --- a/packages/connector-sdk/src/define-connector.ts +++ b/packages/connector-sdk/src/define-connector.ts @@ -2,9 +2,9 @@ * defineConnector — functional authoring sugar over {@link ConnectorRuntime}. * * Lets a connector be declared as a plain spec with per-feed `sync` and - * per-action `execute` handlers, instead of hand-writing a class that switches - * on `ctx.feedKey` / `ctx.actionKey`. The feed/action keys are taken from the - * record keys, so they're never repeated. + * per-action `execute` handlers (plus an optional `authenticate` flow), instead + * of hand-writing a class that switches on `ctx.feedKey` / `ctx.actionKey`. The + * feed/action keys are taken from the record keys, so they're never repeated. * * It LOWERS to a real `ConnectorRuntime` subclass so the existing * connector-worker runs it unchanged: `child-runner` detects a connector by @@ -15,7 +15,7 @@ * `@lobu/connector-sdk` is externalized at connector compile time, so this * function ships as runtime-provided SDK code while the caller's handler * closures get bundled into the connector — the spec object (with its - * `sync`/`execute` functions) is captured by the returned class. + * `sync`/`execute`/`authenticate` functions) is captured by the returned class. * * @example * ```ts @@ -29,38 +29,46 @@ import { ConnectorRuntime } from "./connector-runtime.js"; import type { - ActionContext, - ActionDefinition, - ActionResult, - ConnectorDefinition, - FeedDefinition, - SyncContext, - SyncResult, + ActionContext, + ActionDefinition, + ActionResult, + AuthContext, + AuthResult, + ConnectorDefinition, + FeedDefinition, + SyncContext, + SyncResult, } from "./connector-types.js"; /** A feed's metadata (minus the record-derived `key`) plus its `sync` handler. */ export interface ConnectorFeedSpec< - C = Record, - F = Record, + C = Record, + F = Record, > extends Omit { - /** Ingest handler for this feed. Called by the worker for a `sync` run. */ - sync(ctx: SyncContext): Promise>; + /** Ingest handler for this feed. Called by the worker for a `sync` run. */ + sync(ctx: SyncContext): Promise>; } /** An action's metadata (minus `key`; `requiresApproval` defaults false) plus its `execute` handler. */ export interface ConnectorActionSpec - extends Omit { - /** Whether the action needs human approval before execution. Defaults to `false`. */ - requiresApproval?: boolean; - /** Effect handler for this action. Called inline (low-risk) or by the worker. */ - execute(ctx: ActionContext): Promise; + extends Omit { + /** Whether the action needs human approval before execution. Defaults to `false`. */ + requiresApproval?: boolean; + /** Effect handler for this action. Called inline (low-risk) or by the worker. */ + execute(ctx: ActionContext): Promise; } /** Functional connector spec: connector metadata plus handler-bearing feeds/actions. */ export interface ConnectorSpec - extends Omit { - feeds?: Record; - actions?: Record; + extends Omit { + feeds?: Record; + actions?: Record; + /** + * Optional interactive auth flow. When provided, lowers to + * `ConnectorRuntime.authenticate`; when omitted, the connector inherits the + * base behavior (throws — non-interactive auth needs no handler). + */ + authenticate?(ctx: AuthContext): Promise; } /** Constructor shape the connector-worker's `child-runner` detects and instantiates. */ @@ -68,60 +76,58 @@ export type ConnectorClass = new () => ConnectorRuntime; /** Strip handler closures and derive `key` from the record key — keeps the definition serializable. */ function buildDefinition(spec: ConnectorSpec): ConnectorDefinition { - const definition: ConnectorDefinition = { - key: spec.key, - name: spec.name, - version: spec.version, - description: spec.description, - authSchema: spec.authSchema, - optionsSchema: spec.optionsSchema, - faviconDomain: spec.faviconDomain, - mcpConfig: spec.mcpConfig, - openapiConfig: spec.openapiConfig, - requiredCapability: spec.requiredCapability, - runtime: spec.runtime, - }; + const definition: ConnectorDefinition = { + key: spec.key, + name: spec.name, + version: spec.version, + description: spec.description, + authSchema: spec.authSchema, + optionsSchema: spec.optionsSchema, + faviconDomain: spec.faviconDomain, + mcpConfig: spec.mcpConfig, + openapiConfig: spec.openapiConfig, + requiredCapability: spec.requiredCapability, + runtime: spec.runtime, + }; - if (spec.feeds) { - definition.feeds = Object.fromEntries( - Object.entries(spec.feeds).map( - ([key, feed]): [string, FeedDefinition] => [ - key, - { - key, - name: feed.name, - description: feed.description, - requiredScopes: feed.requiredScopes, - displayNameTemplate: feed.displayNameTemplate, - configSchema: feed.configSchema, - userManaged: feed.userManaged, - eventKinds: feed.eventKinds, - }, - ], - ), - ); - } + if (spec.feeds) { + definition.feeds = Object.fromEntries( + Object.entries(spec.feeds).map(([key, feed]): [string, FeedDefinition] => [ + key, + { + key, + name: feed.name, + description: feed.description, + requiredScopes: feed.requiredScopes, + displayNameTemplate: feed.displayNameTemplate, + configSchema: feed.configSchema, + userManaged: feed.userManaged, + eventKinds: feed.eventKinds, + }, + ]), + ); + } - if (spec.actions) { - definition.actions = Object.fromEntries( - Object.entries(spec.actions).map( - ([key, action]): [string, ActionDefinition] => [ - key, - { - key, - name: action.name, - description: action.description, - requiresApproval: action.requiresApproval ?? false, - annotations: action.annotations, - inputSchema: action.inputSchema, - outputSchema: action.outputSchema, - }, - ], - ), - ); - } + if (spec.actions) { + definition.actions = Object.fromEntries( + Object.entries(spec.actions).map( + ([key, action]): [string, ActionDefinition] => [ + key, + { + key, + name: action.name, + description: action.description, + requiresApproval: action.requiresApproval ?? false, + annotations: action.annotations, + inputSchema: action.inputSchema, + outputSchema: action.outputSchema, + }, + ], + ), + ); + } - return definition; + return definition; } /** @@ -129,30 +135,37 @@ function buildDefinition(spec: ConnectorSpec): ConnectorDefinition { * export of a `.connector.ts` should be the returned class. */ export function defineConnector(spec: ConnectorSpec): ConnectorClass { - const definition = buildDefinition(spec); + const definition = buildDefinition(spec); - return class extends ConnectorRuntime { - readonly definition = definition; + return class extends ConnectorRuntime { + readonly definition = definition; - async sync(ctx: SyncContext): Promise { - const feed = spec.feeds?.[ctx.feedKey]; - if (!feed) { - throw new Error( - `Connector '${spec.key}' has no sync handler for feed '${ctx.feedKey}'`, - ); - } - return feed.sync(ctx); - } + async sync(ctx: SyncContext): Promise { + const feed = spec.feeds?.[ctx.feedKey]; + if (!feed) { + throw new Error( + `Connector '${spec.key}' has no sync handler for feed '${ctx.feedKey}'`, + ); + } + return feed.sync(ctx); + } - async execute(ctx: ActionContext): Promise { - const action = spec.actions?.[ctx.actionKey]; - if (!action) { - return { - success: false, - error: `Connector '${spec.key}' has no action handler for '${ctx.actionKey}'`, - }; - } - return action.execute(ctx); - } - }; + async execute(ctx: ActionContext): Promise { + const action = spec.actions?.[ctx.actionKey]; + if (!action) { + return { + success: false, + error: `Connector '${spec.key}' has no action handler for '${ctx.actionKey}'`, + }; + } + return action.execute(ctx); + } + + async authenticate(ctx: AuthContext): Promise { + if (!spec.authenticate) { + return super.authenticate(ctx); + } + return spec.authenticate(ctx); + } + }; } From a0bd4a8d56d17d2ad25c61adcc6ea993ef0c0e52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 17:17:29 +0100 Subject: [PATCH 04/65] feat(sdk): add @lobu/sdk authoring package (define* + secret) Scaffolds @lobu/sdk (Apache-2.0): defineConfig/defineAgent/defineEntityType/ defineRelationshipType/defineWatcher/defineConnection/defineAuthProfile + secret(), and re-exports defineConnector + TypeBox Type from connector-sdk so a project imports its whole authoring surface from one package. Producers are pure branded data with typed handles (EntityType -> relationship rules, Agent -> watcher); the CLI loader (next slice) maps them to DesiredState, which stays CLI-private per the apply-IR boundary. Excluded from root tsconfig like the other workspace packages (own tsconfig); wired into build:packages + root test. --- bun.lock | 13 ++ package.json | 4 +- packages/sdk/package.json | 45 +++++ packages/sdk/src/__tests__/define.test.ts | 87 ++++++++++ packages/sdk/src/define.ts | 199 ++++++++++++++++++++++ packages/sdk/src/index.ts | 19 +++ packages/sdk/src/secret.ts | 28 +++ packages/sdk/tsconfig.json | 20 +++ tsconfig.json | 1 + 9 files changed, 414 insertions(+), 2 deletions(-) create mode 100644 packages/sdk/package.json create mode 100644 packages/sdk/src/__tests__/define.test.ts create mode 100644 packages/sdk/src/define.ts create mode 100644 packages/sdk/src/index.ts create mode 100644 packages/sdk/src/secret.ts create mode 100644 packages/sdk/tsconfig.json diff --git a/bun.lock b/bun.lock index 49965293f..dffb7da4c 100644 --- a/bun.lock +++ b/bun.lock @@ -351,6 +351,17 @@ "typescript": "^5.3.3", }, }, + "packages/sdk": { + "name": "@lobu/sdk", + "version": "9.1.1", + "dependencies": { + "@lobu/connector-sdk": "workspace:*", + }, + "devDependencies": { + "@types/node": "^20.10.0", + "typescript": "^5.3.3", + }, + }, "packages/server": { "name": "@lobu/server", "version": "1.6.0", @@ -1109,6 +1120,8 @@ "@lobu/promptfoo-provider": ["@lobu/promptfoo-provider@workspace:packages/promptfoo-provider"], + "@lobu/sdk": ["@lobu/sdk@workspace:packages/sdk"], + "@lobu/server": ["@lobu/server@workspace:packages/server"], "@lobu/worker": ["@lobu/worker@workspace:packages/agent-worker"], diff --git a/package.json b/package.json index ba8cd164b..6fc2a16e5 100644 --- a/package.json +++ b/package.json @@ -15,11 +15,11 @@ "check": "biome check --config-path config/biome.config.json .", "check:fix": "biome check --config-path config/biome.config.json --write .", "prepare": "husky || true", - "test": "bun test packages/core/src packages/client/src packages/agent-worker/src packages/landing/src", + "test": "bun test packages/core/src packages/client/src packages/sdk/src packages/agent-worker/src packages/landing/src", "test:coverage": "bun test packages/core/src packages/client/src packages/agent-worker/src packages/landing/src --coverage", "typecheck": "tsc --noEmit", "dev": "./scripts/dev-native.sh", - "build:packages": "cd packages/core && bun run build && cd ../pgvector-embedded && bun run build && cd ../connector-sdk && bun run build && cd ../client && bun run build && cd ../agent-worker && bun run build && cd ../openclaw-plugin && bun run build && cd ../embeddings && bun run build && cd ../connector-worker && bun run build && cd ../promptfoo-provider && bun run build && cd ../server && bun run build:server && cd .. && if [ -f owletto/package.json ]; then (cd owletto && bun run build); else echo '[build:packages] owletto submodule absent — CLI ships headless (API only)'; fi && cd cli && bun run build", + "build:packages": "cd packages/core && bun run build && cd ../pgvector-embedded && bun run build && cd ../connector-sdk && bun run build && cd ../client && bun run build && cd ../sdk && bun run build && cd ../agent-worker && bun run build && cd ../openclaw-plugin && bun run build && cd ../embeddings && bun run build && cd ../connector-worker && bun run build && cd ../promptfoo-provider && bun run build && cd ../server && bun run build:server && cd .. && if [ -f owletto/package.json ]; then (cd owletto && bun run build); else echo '[build:packages] owletto submodule absent — CLI ships headless (API only)'; fi && cd cli && bun run build", "build:lobu": "cd packages/embeddings && bun run build && cd ../..", "watch:packages": "tsc -b --watch packages/core packages/agent-worker", "test:packages": "cd packages/core && bun run test && cd ../agent-worker && bun run test", diff --git a/packages/sdk/package.json b/packages/sdk/package.json new file mode 100644 index 000000000..99657a8b1 --- /dev/null +++ b/packages/sdk/package.json @@ -0,0 +1,45 @@ +{ + "name": "@lobu/sdk", + "version": "9.1.1", + "description": "Lobu authoring SDK — define agents, connectors, watchers, and connections in TypeScript", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": { + "import": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + } + }, + "files": [ + "dist" + ], + "scripts": { + "build": "tsc", + "typecheck": "tsc --noEmit", + "test": "bun test src", + "clean": "rm -rf dist" + }, + "dependencies": { + "@lobu/connector-sdk": "workspace:*" + }, + "devDependencies": { + "@types/node": "^20.10.0", + "typescript": "^5.3.3" + }, + "engines": { + "node": ">=18" + }, + "license": "Apache-2.0", + "publishConfig": { + "access": "public" + }, + "homepage": "https://github.com/lobu-ai/lobu", + "repository": { + "type": "git", + "url": "git+https://github.com/lobu-ai/lobu.git", + "directory": "packages/sdk" + } +} diff --git a/packages/sdk/src/__tests__/define.test.ts b/packages/sdk/src/__tests__/define.test.ts new file mode 100644 index 000000000..4bf67018e --- /dev/null +++ b/packages/sdk/src/__tests__/define.test.ts @@ -0,0 +1,87 @@ +import { describe, expect, test } from "bun:test"; +import { + type Agent, + type AuthProfile, + defineAgent, + defineAuthProfile, + defineConfig, + defineConnection, + defineEntityType, + defineRelationshipType, + defineWatcher, + type EntityType, +} from "../define.js"; +import { isSecretRef, secret } from "../secret.js"; + +describe("secret", () => { + test("builds a resolvable ref and narrows", () => { + const s = secret("GITHUB_TOKEN"); + expect(s).toEqual({ $secret: "GITHUB_TOKEN" }); + expect(isSecretRef(s)).toBe(true); + expect(isSecretRef({})).toBe(false); + expect(() => secret("")).toThrow(); + }); +}); + +describe("authoring producers", () => { + test("define* brand their output and preserve config", () => { + const person = defineEntityType({ key: "person", name: "Person" }); + expect(person.kind).toBe("entityType"); + expect(person.key).toBe("person"); + + const worksAt = defineRelationshipType({ + key: "works_at", + rules: [{ source: person, target: "org" }], + }); + expect(worksAt.kind).toBe("relationshipType"); + // typed handle: the EntityType object is usable as a rule source + expect((worksAt.rules?.[0]?.source as EntityType).key).toBe("person"); + }); + + test("agent + watcher use typed handles", () => { + const crm = defineAgent({ + id: "crm", + providers: [ + { model: "claude-sonnet-4-6", key: secret("ANTHROPIC_API_KEY") }, + ], + }); + expect(crm.kind).toBe("agent"); + expect(isSecretRef(crm.providers?.[0]?.key)).toBe(true); + + const w = defineWatcher({ + agent: crm, + slug: "health", + prompt: "assess", + extractionSchema: { type: "object" }, + }); + expect(w.kind).toBe("watcher"); + expect((w.agent as Agent).id).toBe("crm"); + }); + + test("connection + auth profile wire by handle", () => { + const auth = defineAuthProfile({ + slug: "gh-app", + connector: "github", + authKind: "oauth_app", + credentials: { clientSecret: secret("GH_SECRET") }, + }); + const conn = defineConnection({ + slug: "gh", + connector: "github", + authProfile: auth, + feeds: [{ feed: "stars", schedule: "0 */6 * * *" }], + }); + expect(conn.kind).toBe("connection"); + expect((conn.authProfile as AuthProfile).slug).toBe("gh-app"); + expect(isSecretRef(auth.credentials?.clientSecret)).toBe(true); + }); + + test("defineConfig aggregates the project manifest", () => { + const crm = defineAgent({ id: "crm" }); + const project = defineConfig({ org: "lobu-crm", agents: [crm] }); + expect(project.kind).toBe("project"); + expect(project.org).toBe("lobu-crm"); + expect(project.agents).toHaveLength(1); + expect(project.agents[0]?.id).toBe("crm"); + }); +}); diff --git a/packages/sdk/src/define.ts b/packages/sdk/src/define.ts new file mode 100644 index 000000000..0b0dcc2ca --- /dev/null +++ b/packages/sdk/src/define.ts @@ -0,0 +1,199 @@ +/** + * Declarative authoring API. Each `define*` returns a branded plain object that + * doubles as a typed handle (e.g. an {@link EntityType} can be passed to + * {@link defineRelationshipType}, an {@link Agent} to {@link defineWatcher}). + * + * These are pure data producers with no side effects — `lobu apply` imports the + * entrypoint, reads the {@link Project} default export, and maps it to the + * server's desired state. Executable handlers (connector `sync`/`execute`, + * watcher reactions) live in their own modules; these objects only declare + * config and references. + */ + +import type { ConnectorClass } from "@lobu/connector-sdk"; +import type { SecretRef } from "./secret.js"; + +/** A connector referenced by its key, or by the class produced by `defineConnector`. */ +export type ConnectorRef = string | ConnectorClass; + +// --------------------------------------------------------------------------- +// Memory schema +// --------------------------------------------------------------------------- + +export interface EntityType { + readonly kind: "entityType"; + /** Stable slug — diff key. */ + key: string; + name?: string; + description?: string; + /** Required property names for the entity's metadata. */ + required?: string[]; + /** JSON Schema properties for the entity's metadata. */ + properties?: Record; + metadata?: Record; +} + +export function defineEntityType(config: Omit): EntityType { + return { kind: "entityType", ...config }; +} + +export interface RelationshipType { + readonly kind: "relationshipType"; + key: string; + name?: string; + description?: string; + /** Allowed source/target entity types (handle or slug). */ + rules?: Array<{ source: EntityType | string; target: EntityType | string }>; + metadata?: Record; +} + +export function defineRelationshipType( + config: Omit +): RelationshipType { + return { kind: "relationshipType", ...config }; +} + +// --------------------------------------------------------------------------- +// Connections & auth profiles (code declares wiring; the UI performs OAuth) +// --------------------------------------------------------------------------- + +export type AuthProfileKind = + | "env" + | "oauth_app" + | "oauth_account" + | "browser_session"; + +export interface AuthProfile { + readonly kind: "authProfile"; + /** Stable slug — diff key. */ + slug: string; + connector: ConnectorRef; + authKind: AuthProfileKind; + name?: string; + /** + * Credential references. Values are `secret(...)` refs (or literal `$VAR` + * strings). Only meaningful for `env` / `oauth_app`; the OAuth grant for + * `oauth_account` / `browser_session` is performed at runtime in the UI. + */ + credentials?: Record; +} + +export function defineAuthProfile( + config: Omit +): AuthProfile { + return { kind: "authProfile", ...config }; +} + +export interface ConnectionFeed { + /** Feed key from the connector definition. */ + feed: string; + name?: string; + schedule?: string; + config?: Record; +} + +export interface Connection { + readonly kind: "connection"; + /** Stable slug — diff key. */ + slug: string; + connector: ConnectorRef; + name?: string; + /** Runtime/account auth profile (handle or slug). */ + authProfile?: AuthProfile | string; + /** OAuth-app auth profile (handle or slug). */ + appAuthProfile?: AuthProfile | string; + config?: Record; + /** UUID pinning syncs/actions to a specific device worker. */ + deviceWorkerId?: string; + feeds?: ConnectionFeed[]; +} + +export function defineConnection(config: Omit): Connection { + return { kind: "connection", ...config }; +} + +// --------------------------------------------------------------------------- +// Watchers (reaction handlers are wired in a later slice) +// --------------------------------------------------------------------------- + +export interface WatcherNotification { + channel?: "canvas" | "notification" | "both"; + priority?: "low" | "normal" | "high"; +} + +export interface Watcher { + readonly kind: "watcher"; + /** Stable slug — diff key. */ + slug: string; + /** Owning agent (handle or id). Every watcher belongs to exactly one agent. */ + agent: Agent | string; + name?: string; + description?: string; + schedule?: string; + prompt: string; + /** JSON Schema (or TypeBox schema) describing the LLM output. */ + extractionSchema: Record; + /** Named SQL data sources (`name` -> query). */ + sources?: Record; + notification?: WatcherNotification; + minCooldownSeconds?: number; + tags?: string[]; +} + +export function defineWatcher(config: Omit): Watcher { + return { kind: "watcher", ...config }; +} + +// --------------------------------------------------------------------------- +// Agents +// --------------------------------------------------------------------------- + +export interface ProviderConfig { + id?: string; + model: string; + key?: string | SecretRef; +} + +export interface NetworkConfig { + allowed?: string[]; + denied?: string[]; +} + +export interface Agent { + readonly kind: "agent"; + id: string; + name?: string; + description?: string; + providers?: ProviderConfig[]; + network?: NetworkConfig; + /** Connections this agent uses (handle or slug). */ + connections?: Array; + schema?: { + entities?: EntityType[]; + relationships?: RelationshipType[]; + }; +} + +export function defineAgent(config: Omit): Agent { + return { kind: "agent", ...config }; +} + +// --------------------------------------------------------------------------- +// Project (default export of lobu.config.ts) +// --------------------------------------------------------------------------- + +export interface Project { + readonly kind: "project"; + /** Lobu Cloud org slug this project applies to. */ + org?: string; + agents: Agent[]; + entities?: EntityType[]; + relationships?: RelationshipType[]; + connections?: Connection[]; + authProfiles?: AuthProfile[]; + watchers?: Watcher[]; +} + +export function defineConfig(config: Omit): Project { + return { kind: "project", ...config }; +} diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts new file mode 100644 index 000000000..0f6adc5eb --- /dev/null +++ b/packages/sdk/src/index.ts @@ -0,0 +1,19 @@ +// Lobu authoring SDK — define agents, connectors, watchers, and connections in +// TypeScript. `lobu apply` imports a project entrypoint (default export of +// `defineConfig`) and maps it to the server's desired state. + +// Connector authoring is re-exported from @lobu/connector-sdk so a project can +// import its whole authoring surface from a single package. +export { defineConnector } from "@lobu/connector-sdk"; +export type { + ConnectorActionSpec, + ConnectorClass, + ConnectorFeedSpec, + ConnectorSpec, +} from "@lobu/connector-sdk"; +// TypeBox schema authoring (extraction schemas, feed/action config schemas). +export { Type } from "@lobu/connector-sdk"; +export type { Static } from "@lobu/connector-sdk"; + +export * from "./define.js"; +export * from "./secret.js"; diff --git a/packages/sdk/src/secret.ts b/packages/sdk/src/secret.ts new file mode 100644 index 000000000..068958198 --- /dev/null +++ b/packages/sdk/src/secret.ts @@ -0,0 +1,28 @@ +/** + * A reference to a secret resolved at `lobu apply` time from the environment + * (`.env` / `process.env`). The real value is never embedded in committed code; + * `secret("GITHUB_TOKEN")` is the TypeScript spelling of TOML's `$GITHUB_TOKEN`. + * + * The apply loader resolves the reference to a `$NAME` placeholder, collects it + * into the required-secrets set, and pushes the resolved value to the server. + */ +export interface SecretRef { + readonly $secret: string; +} + +/** Reference an environment-provided secret by name (resolved at apply time). */ +export function secret(name: string): SecretRef { + if (!name) { + throw new Error("secret() requires a non-empty environment variable name"); + } + return { $secret: name }; +} + +/** Narrow an unknown value to a {@link SecretRef}. */ +export function isSecretRef(value: unknown): value is SecretRef { + return ( + typeof value === "object" && + value !== null && + typeof (value as SecretRef).$secret === "string" + ); +} diff --git a/packages/sdk/tsconfig.json b/packages/sdk/tsconfig.json new file mode 100644 index 000000000..0ea5b6081 --- /dev/null +++ b/packages/sdk/tsconfig.json @@ -0,0 +1,20 @@ +{ + "compilerOptions": { + "module": "ESNext", + "target": "ES2022", + "moduleResolution": "bundler", + "esModuleInterop": true, + "skipLibCheck": true, + "strict": true, + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "outDir": "./dist", + "resolveJsonModule": true, + "allowSyntheticDefaultImports": true, + "forceConsistentCasingInFileNames": true, + "emitDeclarationOnly": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/__tests__/**", "**/*.test.ts"] +} diff --git a/tsconfig.json b/tsconfig.json index ee6610817..1ad0747f9 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -53,6 +53,7 @@ "packages/landing/**/*", "packages/server/**/*", "packages/connector-sdk/**/*", + "packages/sdk/**/*", "packages/openclaw-plugin/**/*", "packages/connector-worker/**/*", "packages/connectors/**/*", From 9a7aef440a074bf602788420b08c111940ce2033 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 17:27:07 +0100 Subject: [PATCH 05/65] feat(cli): map @lobu/sdk authoring project to DesiredState MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds mapProjectToDesiredState — the single place that translates the public @lobu/sdk authoring objects (defineConfig default export) into the apply-private DesiredState IR. Maps agents (providers -> installedProviders/modelSelection, network, resolved provider keys), entity/relationship types (typed handles -> slugs), watchers (agent handle -> id, sources record -> array, notification), and connections/auth profiles (connector class -> key, secret() -> $VAR + required-secrets). The esbuild entrypoint loader + apply wiring follow next. --- bun.lock | 1 + packages/cli/package.json | 1 + .../_lib/apply/__tests__/map-config.test.ts | 155 ++++++++++ .../cli/src/commands/_lib/apply/map-config.ts | 284 ++++++++++++++++++ 4 files changed, 441 insertions(+) create mode 100644 packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts create mode 100644 packages/cli/src/commands/_lib/apply/map-config.ts diff --git a/bun.lock b/bun.lock index dffb7da4c..831c8a2da 100644 --- a/bun.lock +++ b/bun.lock @@ -67,6 +67,7 @@ "@lobu/connector-worker": "workspace:*", "@lobu/core": "workspace:*", "@lobu/embeddings": "workspace:*", + "@lobu/sdk": "workspace:*", "@lobu/worker": "workspace:*", "@mariozechner/pi-ai": "^0.51.6", "@modelcontextprotocol/sdk": "^1.27.1", diff --git a/packages/cli/package.json b/packages/cli/package.json index b2f81ec98..330a14ec2 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -43,6 +43,7 @@ "@lobu/connector-worker": "workspace:*", "@lobu/core": "workspace:*", "@lobu/embeddings": "workspace:*", + "@lobu/sdk": "workspace:*", "@lobu/worker": "workspace:*", "@mariozechner/pi-ai": "^0.51.6", "@modelcontextprotocol/sdk": "^1.27.1", diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts new file mode 100644 index 000000000..358e46dcc --- /dev/null +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -0,0 +1,155 @@ +import { describe, expect, test } from "bun:test"; +import { + defineAgent, + defineAuthProfile, + defineConfig, + defineConnection, + defineConnector, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; +import { mapProjectToDesiredState } from "../map-config.js"; + +const env: NodeJS.ProcessEnv = { + ANTHROPIC_API_KEY: "sk-test", + GH_SECRET: "ghs_test", +}; + +describe("mapProjectToDesiredState", () => { + test("maps agents: providers, network (deduped), resolved provider keys", () => { + const crm = defineAgent({ + id: "crm", + providers: [ + { + id: "anthropic", + model: "claude-sonnet-4-6", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { allowed: ["github.com", "github.com"], denied: ["evil.com"] }, + }); + const state = mapProjectToDesiredState( + defineConfig({ org: "o", agents: [crm] }), + env + ); + const agent = state.agents[0]; + expect(agent?.metadata.agentId).toBe("crm"); + expect(agent?.metadata.name).toBe("crm"); // defaults to id + expect(agent?.settings.installedProviders?.[0]?.providerId).toBe( + "anthropic" + ); + expect(agent?.settings.providerModelPreferences).toEqual({ + anthropic: "claude-sonnet-4-6", + }); + expect(agent?.settings.networkConfig?.allowedDomains).toEqual([ + "github.com", + ]); + expect(agent?.settings.networkConfig?.deniedDomains).toEqual(["evil.com"]); + expect(agent?.providerKeys).toEqual([ + { providerId: "anthropic", value: "sk-test" }, + ]); + expect(state.requiredSecrets).toContain("ANTHROPIC_API_KEY"); + expect(state.memory).toEqual({ org: "o" }); + }); + + test("maps entities + relationships with typed-handle slugs", () => { + const person = defineEntityType({ key: "person", name: "Person" }); + const org = defineEntityType({ key: "org" }); + const worksAt = defineRelationshipType({ + key: "works_at", + rules: [{ source: person, target: org }], + }); + const state = mapProjectToDesiredState( + defineConfig({ + agents: [], + entities: [person, org], + relationships: [worksAt], + }) + ); + expect(state.memorySchema.entityTypes.map((e) => e.slug)).toEqual([ + "person", + "org", + ]); + expect(state.memorySchema.relationshipTypes[0]?.rules).toEqual([ + { source: "person", target: "org" }, + ]); + }); + + test("maps watchers: agent handle, sources record, notification", () => { + const crm = defineAgent({ id: "crm" }); + const watcher = defineWatcher({ + agent: crm, + slug: "health", + prompt: "assess", + extractionSchema: { type: "object" }, + sources: { accounts: "SELECT 1" }, + schedule: "0 */12 * * *", + notification: { channel: "both", priority: "high" }, + minCooldownSeconds: 1800, + }); + const state = mapProjectToDesiredState( + defineConfig({ agents: [crm], watchers: [watcher] }) + ); + const dw = state.watchers[0]; + expect(dw?.agent).toBe("crm"); + expect(dw?.sources).toEqual([{ name: "accounts", query: "SELECT 1" }]); + expect(dw?.notificationChannel).toBe("both"); + expect(dw?.notificationPriority).toBe("high"); + expect(dw?.minCooldownSeconds).toBe(1800); + }); + + test("throws when a watcher names an unknown agent", () => { + const watcher = defineWatcher({ + agent: "ghost", + slug: "x", + prompt: "p", + extractionSchema: {}, + }); + expect(() => + mapProjectToDesiredState( + defineConfig({ agents: [], watchers: [watcher] }) + ) + ).toThrow(/ghost/); + }); + + test("maps connections + auth profiles; resolves connector class + secret creds", () => { + const github = defineConnector({ + key: "github", + name: "GitHub", + version: "1.0.0", + feeds: { + stars: { + name: "Stars", + sync: async () => ({ events: [], checkpoint: null }), + }, + }, + }); + const auth = defineAuthProfile({ + slug: "gh-app", + connector: github, + authKind: "oauth_app", + credentials: { clientSecret: secret("GH_SECRET") }, + }); + const conn = defineConnection({ + slug: "gh", + connector: github, + authProfile: auth, + feeds: [{ feed: "stars", schedule: "0 */6 * * *" }], + }); + const state = mapProjectToDesiredState( + defineConfig({ agents: [], authProfiles: [auth], connections: [conn] }), + env + ); + const ap = state.connectors.authProfiles[0]; + expect(ap?.connector).toBe("github"); // class resolved to its key + expect(ap?.kind).toBe("oauth_app"); + expect(ap?.credentials).toEqual({ clientSecret: "$GH_SECRET" }); + expect(state.requiredSecrets).toContain("GH_SECRET"); + const dc = state.connectors.connections[0]; + expect(dc?.connector).toBe("github"); + expect(dc?.authProfileSlug).toBe("gh-app"); + expect(dc?.feeds).toEqual([{ feedKey: "stars", schedule: "0 */6 * * *" }]); + }); +}); diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts new file mode 100644 index 000000000..9f5166e0a --- /dev/null +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -0,0 +1,284 @@ +/** + * Map a `@lobu/sdk` authoring project (the default export of `lobu.config.ts`, + * built by `defineConfig`) to the apply `DesiredState`. + * + * `DesiredState` is an apply-internal IR and stays CLI-private; this is the one + * place that translates the public authoring objects into it. The mapping is + * pure (modulo `installedAt` timestamps, matching the TOML loader) so it can be + * unit-tested without importing `lobu.config.ts`. + */ + +import type { AgentSettings } from "@lobu/core"; +import type { + Agent, + AuthProfile, + Connection, + ConnectorRef, + EntityType, + ProviderConfig, + Project, + RelationshipType, + Watcher, +} from "@lobu/sdk"; +import { isSecretRef } from "@lobu/sdk"; +import { ValidationError } from "../../memory/_lib/errors.js"; +import type { + DesiredAgent, + DesiredAgentMetadata, + DesiredAuthProfile, + DesiredConnection, + DesiredEntityType, + DesiredFeed, + DesiredRelationshipType, + DesiredState, + DesiredWatcher, +} from "./desired-state.js"; + +/** Source label recorded on connector docs (mirrors the YAML manifest path). */ +const CONFIG_SOURCE = "lobu.config.ts"; + +/** `"$NAME"` → `"NAME"`, else null. Mirrors the TOML loader's env-ref detection. */ +function envRefName(value: string): string | null { + const match = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value.trim()); + return match ? (match[1] ?? null) : null; +} + +/** Provider id used as the storage key; falls back to the model when omitted. */ +function providerId(provider: ProviderConfig): string { + return provider.id ?? provider.model; +} + +/** Resolve a connector reference (key string, or the class from `defineConnector`) to its key. */ +function connectorKey(ref: ConnectorRef): string { + if (typeof ref === "string") return ref; + return new ref().definition.key; +} + +function entitySlug(ref: EntityType | string): string { + return typeof ref === "string" ? ref : ref.key; +} + +function agentId(ref: Agent | string): string { + return typeof ref === "string" ? ref : ref.id; +} + +function authProfileSlug( + ref: AuthProfile | string | undefined +): string | undefined { + if (ref === undefined) return undefined; + return typeof ref === "string" ? ref : ref.slug; +} + +/** Credential value → `$VAR` string; collects the referenced secret name. */ +function credentialString( + value: string | { readonly $secret: string }, + required: Set +): string { + if (isSecretRef(value)) { + required.add(value.$secret); + return `$${value.$secret}`; + } + const ref = envRefName(value); + if (ref) required.add(ref); + return value; +} + +function mapAgent( + agent: Agent, + env: NodeJS.ProcessEnv, + required: Set +): DesiredAgent { + const settings: Partial = {}; + + if (agent.providers?.length) { + settings.installedProviders = agent.providers.map((p) => ({ + providerId: providerId(p), + installedAt: Date.now(), + })); + settings.modelSelection = { mode: "auto" }; + const preferences = Object.fromEntries( + agent.providers + .filter((p) => !!p.model?.trim()) + .map((p) => [providerId(p), p.model.trim()]) + ); + if (Object.keys(preferences).length > 0) { + settings.providerModelPreferences = preferences; + } + } + + const allowed = agent.network?.allowed ?? []; + const denied = agent.network?.denied ?? []; + if (allowed.length > 0 || denied.length > 0) { + settings.networkConfig = { + ...(allowed.length > 0 ? { allowedDomains: [...new Set(allowed)] } : {}), + ...(denied.length > 0 ? { deniedDomains: [...new Set(denied)] } : {}), + }; + } + + const providerKeys: { providerId: string; value: string }[] = []; + for (const provider of agent.providers ?? []) { + if (provider.key === undefined) continue; + if (isSecretRef(provider.key)) { + required.add(provider.key.$secret); + const value = env[provider.key.$secret]; + if (value) providerKeys.push({ providerId: providerId(provider), value }); + continue; + } + const ref = envRefName(provider.key); + if (ref) { + required.add(ref); + const value = env[ref]; + if (value) providerKeys.push({ providerId: providerId(provider), value }); + continue; + } + providerKeys.push({ + providerId: providerId(provider), + value: provider.key, + }); + } + + const metadata: DesiredAgentMetadata = { + agentId: agent.id, + name: agent.name ?? agent.id, + }; + if (agent.description) metadata.description = agent.description; + + return { metadata, settings, platforms: [], providerKeys }; +} + +function mapEntityType(entity: EntityType): DesiredEntityType { + return { + slug: entity.key, + ...(entity.name ? { name: entity.name } : {}), + ...(entity.description ? { description: entity.description } : {}), + ...(entity.required ? { required: entity.required } : {}), + ...(entity.properties ? { properties: entity.properties } : {}), + ...(entity.metadata ? { metadata: entity.metadata } : {}), + }; +} + +function mapRelationshipType(rel: RelationshipType): DesiredRelationshipType { + return { + slug: rel.key, + ...(rel.name ? { name: rel.name } : {}), + ...(rel.description ? { description: rel.description } : {}), + ...(rel.rules + ? { + rules: rel.rules.map((rule) => ({ + source: entitySlug(rule.source), + target: entitySlug(rule.target), + })), + } + : {}), + ...(rel.metadata ? { metadata: rel.metadata } : {}), + }; +} + +function mapWatcher(watcher: Watcher): DesiredWatcher { + const sources = watcher.sources + ? Object.entries(watcher.sources).map(([name, query]) => ({ name, query })) + : undefined; + return { + slug: watcher.slug, + agent: agentId(watcher.agent), + prompt: watcher.prompt, + extractionSchema: watcher.extractionSchema, + ...(watcher.name ? { name: watcher.name } : {}), + ...(watcher.description ? { description: watcher.description } : {}), + ...(watcher.schedule ? { schedule: watcher.schedule } : {}), + ...(sources ? { sources } : {}), + ...(watcher.notification?.channel + ? { notificationChannel: watcher.notification.channel } + : {}), + ...(watcher.notification?.priority + ? { notificationPriority: watcher.notification.priority } + : {}), + ...(watcher.minCooldownSeconds !== undefined + ? { minCooldownSeconds: watcher.minCooldownSeconds } + : {}), + ...(watcher.tags ? { tags: watcher.tags } : {}), + }; +} + +function mapAuthProfile( + profile: AuthProfile, + required: Set +): DesiredAuthProfile { + const credentials = profile.credentials + ? Object.fromEntries( + Object.entries(profile.credentials).map(([key, value]) => [ + key, + credentialString(value, required), + ]) + ) + : undefined; + return { + slug: profile.slug, + connector: connectorKey(profile.connector), + kind: profile.authKind, + sourceFile: CONFIG_SOURCE, + ...(profile.name ? { name: profile.name } : {}), + ...(credentials ? { credentials } : {}), + }; +} + +function mapConnection(connection: Connection): DesiredConnection { + const feeds: DesiredFeed[] = (connection.feeds ?? []).map((feed) => ({ + feedKey: feed.feed, + ...(feed.name ? { name: feed.name } : {}), + ...(feed.schedule ? { schedule: feed.schedule } : {}), + ...(feed.config ? { config: feed.config } : {}), + })); + const authSlug = authProfileSlug(connection.authProfile); + const appAuthSlug = authProfileSlug(connection.appAuthProfile); + return { + slug: connection.slug, + connector: connectorKey(connection.connector), + feeds, + sourceFile: CONFIG_SOURCE, + ...(connection.name ? { name: connection.name } : {}), + ...(authSlug ? { authProfileSlug: authSlug } : {}), + ...(appAuthSlug ? { appAuthProfileSlug: appAuthSlug } : {}), + ...(connection.config ? { config: connection.config } : {}), + ...(connection.deviceWorkerId + ? { deviceWorkerId: connection.deviceWorkerId } + : {}), + }; +} + +/** Translate a `@lobu/sdk` project into the apply `DesiredState`. */ +export function mapProjectToDesiredState( + project: Project, + env: NodeJS.ProcessEnv = process.env +): DesiredState { + const required = new Set(); + + const agents = project.agents.map((agent) => mapAgent(agent, env, required)); + const entityTypes = (project.entities ?? []).map(mapEntityType); + const relationshipTypes = (project.relationships ?? []).map( + mapRelationshipType + ); + const watchers = (project.watchers ?? []).map(mapWatcher); + const authProfiles = (project.authProfiles ?? []).map((profile) => + mapAuthProfile(profile, required) + ); + const connections = (project.connections ?? []).map(mapConnection); + + const agentIds = new Set(project.agents.map((agent) => agent.id)); + for (const watcher of watchers) { + if (!agentIds.has(watcher.agent)) { + throw new ValidationError( + `watcher "${watcher.slug}" names agent "${watcher.agent}", but no agent with that id is declared in lobu.config.ts` + ); + } + } + + return { + agents, + ...(project.org ? { memory: { org: project.org } } : {}), + memorySchema: { entityTypes, relationshipTypes }, + watchers, + connectors: { definitions: [], authProfiles, connections }, + requiredSecrets: [...required].sort(), + }; +} From 15b7f81f6539a435e16c9531288d2e9c7cf84517 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 17:31:10 +0100 Subject: [PATCH 06/65] feat(cli): load DesiredState from a lobu.config.ts entrypoint Adds loadDesiredStateFromConfig: esbuild-bundles lobu.config.ts (relative imports inlined; node_modules externalized so @lobu/sdk + @lobu/connector-sdk resolve from the project), imports the bundle to read the defineConfig() default export, and maps it via mapProjectToDesiredState. Dynamic imports are allow-listed in desired-state.ts (esbuild loaded lazily; bundle imported by URL). E2E test bundles a real fixture config end-to-end. Not yet wired into the apply command (next). --- .../_lib/apply/__tests__/load-config.test.ts | 57 +++++++++++++++++ .../src/commands/_lib/apply/desired-state.ts | 62 ++++++++++++++++++- 2 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts diff --git a/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts new file mode 100644 index 000000000..4be20804d --- /dev/null +++ b/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts @@ -0,0 +1,57 @@ +import { afterEach, describe, expect, test } from "bun:test"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { loadDesiredStateFromConfig } from "../desired-state.js"; + +// Fixtures live under the worktree (next to this test) so that the externalized +// `@lobu/sdk` import in the generated bundle resolves from node_modules. +describe("loadDesiredStateFromConfig", () => { + let dir = ""; + afterEach(() => { + if (dir) rmSync(dir, { recursive: true, force: true }); + dir = ""; + }); + + test("bundles + imports lobu.config.ts and maps it to DesiredState", async () => { + dir = mkdtempSync(join(import.meta.dir, "fixture-")); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig, defineEntityType } from "@lobu/sdk";`, + `const person = defineEntityType({ key: "person" });`, + `export default defineConfig({`, + ` org: "test-org",`, + ` agents: [defineAgent({ id: "crm" })],`, + ` entities: [person],`, + `});`, + ``, + ].join("\n") + ); + + const { state, configPath } = await loadDesiredStateFromConfig({ + cwd: dir, + }); + expect(configPath).toContain("lobu.config.ts"); + expect(state.memory).toEqual({ org: "test-org" }); + expect(state.agents[0]?.metadata.agentId).toBe("crm"); + expect(state.memorySchema.entityTypes[0]?.slug).toBe("person"); + }); + + test("rejects when no lobu.config.ts is present", async () => { + dir = mkdtempSync(join(import.meta.dir, "empty-")); + await expect(loadDesiredStateFromConfig({ cwd: dir })).rejects.toThrow( + /No lobu\.config\.ts/ + ); + }); + + test("rejects a config whose default export is not defineConfig()", async () => { + dir = mkdtempSync(join(import.meta.dir, "bad-")); + writeFileSync( + join(dir, "lobu.config.ts"), + `export default { nope: true };\n` + ); + await expect(loadDesiredStateFromConfig({ cwd: dir })).rejects.toThrow( + /defineConfig/ + ); + }); +}); diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index 9de42b06f..fd0f2e643 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -1,6 +1,9 @@ -import { existsSync, readdirSync, readFileSync } from "node:fs"; +import { randomBytes } from "node:crypto"; +import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs"; import { readdir, readFile, stat } from "node:fs/promises"; import { join, resolve } from "node:path"; +import { pathToFileURL } from "node:url"; +import type { Project } from "@lobu/sdk"; import type { ConnectorAuthSchema, ConnectorDefinition, @@ -22,6 +25,7 @@ import { isLoadError, loadConfig, } from "../../../config/loader.js"; +import { mapProjectToDesiredState } from "./map-config.js"; import { CronExpressionParser } from "cron-parser"; // ── Connector slug / schedule validators (round-2) ───────────────────────── @@ -2007,3 +2011,59 @@ export async function loadDesiredState( configPath, }; } + +/** + * Load desired state from a TypeScript entrypoint (`lobu.config.ts`) instead of + * `lobu.toml`. Bundles the entrypoint with esbuild (relative imports inlined; + * node_modules — including `@lobu/sdk` / `@lobu/connector-sdk` — externalized so + * they resolve from the project at import time), imports the bundle to read the + * `defineConfig()` default export, and maps it to `DesiredState`. + * + * The dynamic imports here are intentional and allow-listed (AGENTS.md): esbuild + * is loaded lazily so the TOML path doesn't pay for it, and the bundled config + * is a generated file imported by URL. + */ +export async function loadDesiredStateFromConfig( + opts: LoadDesiredStateOptions +): Promise<{ state: DesiredState; configPath: string }> { + const configPath = resolve(opts.cwd, "lobu.config.ts"); + if (!existsSync(configPath)) { + throw new ValidationError(`No lobu.config.ts found in ${opts.cwd}`); + } + const env = opts.env ?? process.env; + const { build } = await import("esbuild"); + const outFile = resolve( + opts.cwd, + `.lobu-config.${randomBytes(6).toString("hex")}.mjs` + ); + try { + await build({ + entryPoints: [configPath], + outfile: outFile, + bundle: true, + format: "esm", + platform: "node", + packages: "external", + logLevel: "silent", + }); + const mod = (await import(pathToFileURL(outFile).href)) as { + default?: unknown; + }; + const project = mod.default; + if ( + !project || + typeof project !== "object" || + (project as { kind?: unknown }).kind !== "project" + ) { + throw new ValidationError( + "lobu.config.ts must `export default defineConfig({ ... })`" + ); + } + return { + state: mapProjectToDesiredState(project as Project, env), + configPath, + }; + } finally { + rmSync(outFile, { force: true }); + } +} From e3e909ef82f89aa73325f76fb5062b94a26a8680 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 17:32:06 +0100 Subject: [PATCH 07/65] feat(cli): apply prefers lobu.config.ts over lobu.toml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit lobu apply now loads DesiredState from the TypeScript entrypoint when a lobu.config.ts is present, falling back to lobu.toml otherwise. Downstream apply logic (required-secrets gate, org resolution, diff, mutations) is source-agnostic — it operates on DesiredState. --- packages/cli/src/commands/_lib/apply/apply-cmd.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index e965b22a7..2f74c42ed 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -1,3 +1,4 @@ +import { existsSync } from "node:fs"; import { readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import chalk from "chalk"; @@ -25,6 +26,7 @@ import { type DesiredConnectorDefinition, type DesiredState, loadDesiredState, + loadDesiredStateFromConfig, resolveConnectorSchemas, validateAuthProfileAgainstConnector, validateConnectionAgainstConnector, @@ -1007,10 +1009,11 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { // `lobu dev` does. Existing process.env values win (don't clobber the shell). await loadProjectEnvFile(cwd); - const { state, configPath } = await loadDesiredState({ - cwd, - ...(opts.only ? { only: opts.only } : {}), - }); + // Prefer the TypeScript entrypoint (lobu.config.ts); fall back to lobu.toml. + const loadArgs = { cwd, ...(opts.only ? { only: opts.only } : {}) }; + const { state, configPath } = existsSync(join(cwd, "lobu.config.ts")) + ? await loadDesiredStateFromConfig(loadArgs) + : await loadDesiredState(loadArgs); printText(chalk.dim(`Config: ${configPath}`)); From 530cb0cc019fe28cea854e28def4bf6cf7740fa0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 17:45:30 +0100 Subject: [PATCH 08/65] fix(sdk,cli): address codex + pi review of the TS authoring path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - BLOCKER (#976): @lobu/sdk re-exported defineConnector/Type through connector-sdk's barrel, which flakily fails under bun's ESM linker and broke the cli unit suite. Source Type/Static from @sinclair/typebox directly and deep-import defineConnector via a new connector-sdk '/define-connector' subpath export (bypasses the barrel). Full cli suite now 320 pass, 0 fail. - Thread --only into the TS loader/mapper so 'apply --only agents' doesn't demand connector secrets (matches the TOML loader). - Port the TOML structural validations into the mapper: connection/auth-profile slug patterns, cron schedules, duplicate feed keys, and forbidding credentials on interactive (oauth_account/browser_session) auth kinds — fail loud in the CLI before any remote mutation. - Register @lobu/sdk in release-please-config, bump-version, and publish-packages so it versions and publishes. Deferred (task #7): local defineConnector definitions authored in lobu.config.ts are not yet uploaded (connectors.definitions stays []); needs connector file-discovery wired into the TS loader. --- bun.lock | 1 + .../_lib/apply/__tests__/map-config.test.ts | 79 ++++++++++++ .../src/commands/_lib/apply/desired-state.ts | 2 +- .../cli/src/commands/_lib/apply/map-config.ts | 114 +++++++++++++++--- packages/connector-sdk/package.json | 6 + packages/sdk/package.json | 3 +- packages/sdk/src/index.ts | 16 ++- release-please-config.json | 5 + scripts/bump-version.mjs | 1 + scripts/publish-packages.mjs | 1 + 10 files changed, 200 insertions(+), 28 deletions(-) diff --git a/bun.lock b/bun.lock index 831c8a2da..020296d46 100644 --- a/bun.lock +++ b/bun.lock @@ -357,6 +357,7 @@ "version": "9.1.1", "dependencies": { "@lobu/connector-sdk": "workspace:*", + "@sinclair/typebox": "^0.34.41", }, "devDependencies": { "@types/node": "^20.10.0", diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index 358e46dcc..e80ae8930 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -152,4 +152,83 @@ describe("mapProjectToDesiredState", () => { expect(dc?.authProfileSlug).toBe("gh-app"); expect(dc?.feeds).toEqual([{ feedKey: "stars", schedule: "0 */6 * * *" }]); }); + + test("rejects an invalid connection slug", () => { + const conn = defineConnection({ slug: "Bad_Slug", connector: "github" }); + expect(() => + mapProjectToDesiredState( + defineConfig({ agents: [], connections: [conn] }) + ) + ).toThrow(/connection slug/); + }); + + test("rejects an invalid cron schedule", () => { + const crm = defineAgent({ id: "crm" }); + const watcher = defineWatcher({ + agent: crm, + slug: "w", + prompt: "p", + extractionSchema: {}, + schedule: "not-a-cron", + }); + expect(() => + mapProjectToDesiredState( + defineConfig({ agents: [crm], watchers: [watcher] }) + ) + ).toThrow(/invalid schedule/); + }); + + test("rejects credentials on an interactive auth profile", () => { + const auth = defineAuthProfile({ + slug: "gh-acct", + connector: "github", + authKind: "oauth_account", + credentials: { token: secret("X") }, + }); + expect(() => + mapProjectToDesiredState( + defineConfig({ agents: [], authProfiles: [auth] }) + ) + ).toThrow(/credentials must not be set/); + }); + + test("rejects duplicate feed keys in a connection", () => { + const conn = defineConnection({ + slug: "gh", + connector: "github", + feeds: [{ feed: "stars" }, { feed: "stars" }], + }); + expect(() => + mapProjectToDesiredState( + defineConfig({ agents: [], connections: [conn] }) + ) + ).toThrow(/more than once/); + }); + + test("--only skips connectors and their secrets", () => { + const auth = defineAuthProfile({ + slug: "gh-app", + connector: "github", + authKind: "oauth_app", + credentials: { clientSecret: secret("GH_SECRET") }, + }); + const conn = defineConnection({ + slug: "gh", + connector: "github", + authProfile: auth, + }); + const state = mapProjectToDesiredState( + defineConfig({ + agents: [defineAgent({ id: "crm" })], + authProfiles: [auth], + connections: [conn], + }), + env, + "agents" + ); + expect(state.connectors.authProfiles).toEqual([]); + expect(state.connectors.connections).toEqual([]); + expect(state.requiredSecrets).not.toContain("GH_SECRET"); + expect(state.agents).toHaveLength(1); + }); }); diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index fd0f2e643..4691a87d3 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -2060,7 +2060,7 @@ export async function loadDesiredStateFromConfig( ); } return { - state: mapProjectToDesiredState(project as Project, env), + state: mapProjectToDesiredState(project as Project, env, opts.only), configPath, }; } finally { diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index 9f5166e0a..bb1a23832 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -21,6 +21,7 @@ import type { Watcher, } from "@lobu/sdk"; import { isSecretRef } from "@lobu/sdk"; +import { CronExpressionParser } from "cron-parser"; import { ValidationError } from "../../memory/_lib/errors.js"; import type { DesiredAgent, @@ -37,6 +38,21 @@ import type { /** Source label recorded on connector docs (mirrors the YAML manifest path). */ const CONFIG_SOURCE = "lobu.config.ts"; +// Mirror the TOML loader's structural validators so a malformed TS config fails +// loud in the CLI before any remote mutation, not with a confusing server 4xx. +const CONNECTION_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/; +const AUTH_PROFILE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,79}$/; + +/** Returns an error message if the cron schedule is invalid, else null. */ +function cronError(schedule: string): string | null { + try { + CronExpressionParser.parse(schedule); + return null; + } catch (err) { + return err instanceof Error ? err.message : String(err); + } +} + /** `"$NAME"` → `"NAME"`, else null. Mirrors the TOML loader's env-ref detection. */ function envRefName(value: string): string | null { const match = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value.trim()); @@ -175,6 +191,14 @@ function mapRelationshipType(rel: RelationshipType): DesiredRelationshipType { } function mapWatcher(watcher: Watcher): DesiredWatcher { + if (watcher.schedule) { + const err = cronError(watcher.schedule); + if (err) { + throw new ValidationError( + `watcher "${watcher.slug}" has an invalid schedule "${watcher.schedule}": ${err}` + ); + } + } const sources = watcher.sources ? Object.entries(watcher.sources).map(([name, query]) => ({ name, query })) : undefined; @@ -204,14 +228,32 @@ function mapAuthProfile( profile: AuthProfile, required: Set ): DesiredAuthProfile { - const credentials = profile.credentials - ? Object.fromEntries( - Object.entries(profile.credentials).map(([key, value]) => [ - key, - credentialString(value, required), - ]) - ) - : undefined; + if (!AUTH_PROFILE_SLUG_PATTERN.test(profile.slug)) { + throw new ValidationError( + `auth profile slug "${profile.slug}" must match /^[a-z0-9][a-z0-9-]{0,79}$/ (lowercase letters/digits/hyphens, no leading hyphen, ≤80 chars)` + ); + } + const interactive = + profile.authKind === "oauth_account" || + profile.authKind === "browser_session"; + if ( + interactive && + profile.credentials && + Object.keys(profile.credentials).length > 0 + ) { + throw new ValidationError( + `auth profile "${profile.slug}" has kind "${profile.authKind}" — credentials must not be set; lobu apply never writes interactive-auth tokens (complete auth via the connect URL)` + ); + } + const credentials = + profile.credentials && !interactive + ? Object.fromEntries( + Object.entries(profile.credentials).map(([key, value]) => [ + key, + credentialString(value, required), + ]) + ) + : undefined; return { slug: profile.slug, connector: connectorKey(profile.connector), @@ -223,12 +265,34 @@ function mapAuthProfile( } function mapConnection(connection: Connection): DesiredConnection { - const feeds: DesiredFeed[] = (connection.feeds ?? []).map((feed) => ({ - feedKey: feed.feed, - ...(feed.name ? { name: feed.name } : {}), - ...(feed.schedule ? { schedule: feed.schedule } : {}), - ...(feed.config ? { config: feed.config } : {}), - })); + if (!CONNECTION_SLUG_PATTERN.test(connection.slug)) { + throw new ValidationError( + `connection slug "${connection.slug}" must match /^[a-z0-9][a-z0-9-]{0,62}$/ (lowercase letters/digits/hyphens, no leading hyphen, ≤63 chars)` + ); + } + const seenFeeds = new Set(); + const feeds: DesiredFeed[] = (connection.feeds ?? []).map((feed) => { + if (seenFeeds.has(feed.feed)) { + throw new ValidationError( + `connection "${connection.slug}" declares feed "${feed.feed}" more than once` + ); + } + seenFeeds.add(feed.feed); + if (feed.schedule) { + const err = cronError(feed.schedule); + if (err) { + throw new ValidationError( + `connection "${connection.slug}" feed "${feed.feed}" has an invalid schedule "${feed.schedule}": ${err}` + ); + } + } + return { + feedKey: feed.feed, + ...(feed.name ? { name: feed.name } : {}), + ...(feed.schedule ? { schedule: feed.schedule } : {}), + ...(feed.config ? { config: feed.config } : {}), + }; + }); const authSlug = authProfileSlug(connection.authProfile); const appAuthSlug = authProfileSlug(connection.appAuthProfile); return { @@ -246,10 +310,16 @@ function mapConnection(connection: Connection): DesiredConnection { }; } -/** Translate a `@lobu/sdk` project into the apply `DesiredState`. */ +/** + * Translate a `@lobu/sdk` project into the apply `DesiredState`. When `only` is + * set, connector definitions/connections/auth-profiles are skipped (and their + * secrets not collected), matching the TOML loader's `--only` behavior so + * `lobu apply --only agents` doesn't demand connector secrets. + */ export function mapProjectToDesiredState( project: Project, - env: NodeJS.ProcessEnv = process.env + env: NodeJS.ProcessEnv = process.env, + only?: "agents" | "memory" ): DesiredState { const required = new Set(); @@ -259,10 +329,14 @@ export function mapProjectToDesiredState( mapRelationshipType ); const watchers = (project.watchers ?? []).map(mapWatcher); - const authProfiles = (project.authProfiles ?? []).map((profile) => - mapAuthProfile(profile, required) - ); - const connections = (project.connections ?? []).map(mapConnection); + const authProfiles = only + ? [] + : (project.authProfiles ?? []).map((profile) => + mapAuthProfile(profile, required) + ); + const connections = only + ? [] + : (project.connections ?? []).map(mapConnection); const agentIds = new Set(project.agents.map((agent) => agent.id)); for (const watcher of watchers) { diff --git a/packages/connector-sdk/package.json b/packages/connector-sdk/package.json index f52f9e7a1..0eef51a50 100644 --- a/packages/connector-sdk/package.json +++ b/packages/connector-sdk/package.json @@ -16,6 +16,12 @@ "default": "./dist/index.js" } }, + "./define-connector": { + "import": { + "types": "./dist/define-connector.d.ts", + "default": "./dist/define-connector.js" + } + }, "./identity-types": { "types": "./dist/identity-types.d.ts", "import": "./dist/identity-types.js" diff --git a/packages/sdk/package.json b/packages/sdk/package.json index 99657a8b1..cecdb2bca 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -23,7 +23,8 @@ "clean": "rm -rf dist" }, "dependencies": { - "@lobu/connector-sdk": "workspace:*" + "@lobu/connector-sdk": "workspace:*", + "@sinclair/typebox": "^0.34.41" }, "devDependencies": { "@types/node": "^20.10.0", diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts index 0f6adc5eb..9a6427e78 100644 --- a/packages/sdk/src/index.ts +++ b/packages/sdk/src/index.ts @@ -2,18 +2,22 @@ // TypeScript. `lobu apply` imports a project entrypoint (default export of // `defineConfig`) and maps it to the server's desired state. -// Connector authoring is re-exported from @lobu/connector-sdk so a project can -// import its whole authoring surface from a single package. -export { defineConnector } from "@lobu/connector-sdk"; +// Connector authoring is re-exported so a project imports its whole authoring +// surface from one package. Deep-imported from the `define-connector` subpath +// (not the package barrel) to avoid bun's ESM linker flakily failing to resolve +// names through connector-sdk's large re-export barrel (issue #976). +export { defineConnector } from "@lobu/connector-sdk/define-connector"; export type { ConnectorActionSpec, ConnectorClass, ConnectorFeedSpec, ConnectorSpec, -} from "@lobu/connector-sdk"; +} from "@lobu/connector-sdk/define-connector"; // TypeBox schema authoring (extraction schemas, feed/action config schemas). -export { Type } from "@lobu/connector-sdk"; -export type { Static } from "@lobu/connector-sdk"; +// Imported directly from @sinclair/typebox — re-exporting through +// connector-sdk's barrel flakily fails under bun's ESM linker (issue #976). +export { Type } from "@sinclair/typebox"; +export type { Static } from "@sinclair/typebox"; export * from "./define.js"; export * from "./secret.js"; diff --git a/release-please-config.json b/release-please-config.json index e0161ed93..099544f8c 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -41,6 +41,11 @@ "path": "packages/client/package.json", "jsonpath": "$.version" }, + { + "type": "json", + "path": "packages/sdk/package.json", + "jsonpath": "$.version" + }, { "type": "json", "path": "packages/openclaw-plugin/package.json", diff --git a/scripts/bump-version.mjs b/scripts/bump-version.mjs index 501f07872..a591b0af6 100644 --- a/scripts/bump-version.mjs +++ b/scripts/bump-version.mjs @@ -9,6 +9,7 @@ const PACKAGES = [ "packages/cli", "packages/connector-sdk", "packages/client", + "packages/sdk", "packages/openclaw-plugin", "packages/connectors", "packages/connector-worker", diff --git a/scripts/publish-packages.mjs b/scripts/publish-packages.mjs index 9462c2f0d..2b9d22d31 100644 --- a/scripts/publish-packages.mjs +++ b/scripts/publish-packages.mjs @@ -23,6 +23,7 @@ const PACKAGES = [ { dir: "packages/core", transform: transformCorePublish }, { dir: "packages/connector-sdk", transform: rewriteWorkspaceRefs }, { dir: "packages/client", transform: rewriteWorkspaceRefs }, + { dir: "packages/sdk", transform: rewriteWorkspaceRefs }, { dir: "packages/agent-worker", transform: rewriteWorkspaceRefs }, { dir: "packages/embeddings", transform: rewriteWorkspaceRefs }, // @lobu/pgvector-embedded is NOT published: it's `private` and ships its From ecf4f34ffc0e4005d40dfdb51cef18ce9b1919c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 17:48:43 +0100 Subject: [PATCH 09/65] fix(cli): enforce 1-minute minimum cron interval in TS config (TOML parity) cronError now rejects schedules firing more than once a minute, matching the TOML loader + server validation, so a sub-minute cron fails loud in the CLI instead of at server mutation. Closes the last codex parity gap (slice 3 now 93%). --- .../_lib/apply/__tests__/map-config.test.ts | 16 ++++++++++++++++ .../cli/src/commands/_lib/apply/map-config.ts | 12 +++++++++--- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index e80ae8930..9306e733f 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -178,6 +178,22 @@ describe("mapProjectToDesiredState", () => { ).toThrow(/invalid schedule/); }); + test("rejects a sub-minute cron schedule (parity with TOML/server)", () => { + const crm = defineAgent({ id: "crm" }); + const watcher = defineWatcher({ + agent: crm, + slug: "w", + prompt: "p", + extractionSchema: {}, + schedule: "*/30 * * * * *", + }); + expect(() => + mapProjectToDesiredState( + defineConfig({ agents: [crm], watchers: [watcher] }) + ) + ).toThrow(/too frequent/); + }); + test("rejects credentials on an interactive auth profile", () => { const auth = defineAuthProfile({ slug: "gh-acct", diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index bb1a23832..674eb0158 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -42,14 +42,20 @@ const CONFIG_SOURCE = "lobu.config.ts"; // loud in the CLI before any remote mutation, not with a confusing server 4xx. const CONNECTION_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/; const AUTH_PROFILE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,79}$/; +const MIN_CRON_INTERVAL_MS = 60_000; -/** Returns an error message if the cron schedule is invalid, else null. */ +/** Error message if the cron is invalid or fires more than once a minute, else null. */ function cronError(schedule: string): string | null { try { - CronExpressionParser.parse(schedule); + const it = CronExpressionParser.parse(schedule); + const first = it.next().toDate(); + const second = it.next().toDate(); + if (second.getTime() - first.getTime() < MIN_CRON_INTERVAL_MS) { + return `schedule "${schedule}" is too frequent (minimum interval is 1 minute)`; + } return null; } catch (err) { - return err instanceof Error ? err.message : String(err); + return `invalid cron expression "${schedule}" — ${err instanceof Error ? err.message : String(err)}`; } } From 99b2315c70e4504c0c5d1e17ac668f938be00897 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Thu, 21 May 2026 23:45:40 +0100 Subject: [PATCH 10/65] feat(cli): ship local connectors/*.connector.ts source from lobu.config.ts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The TypeScript apply path (loadDesiredStateFromConfig) always set connectors.definitions to []. A connector authored in ./connectors and referenced by a connection resolved to a key but its source was never uploaded, so apply failed "not installed". Discover ./connectors/*.connector.ts (non-recursive, sorted, files only) and ship each as a DesiredConnectorDefinition{ key: null, sourcePath, sourceCode } — the same key-null contract the YAML loader uses for auto-discovered connector files. apply-cmd then compiles each sourcePath on the CLI and uploads it via install_connector; the server resolves the real key. Skipped under --only agents|memory, matching the mapper. Key resolution is intentionally deferred to the server (no eager compile/instantiate at load time, which would force esbuild + installed deps + module side effects on every load, including --dry-run). --- .../_lib/apply/__tests__/load-config.test.ts | 117 +++++++++++++++++- .../src/commands/_lib/apply/desired-state.ts | 73 ++++++++++- 2 files changed, 185 insertions(+), 5 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts index 4be20804d..3f032a198 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts @@ -1,5 +1,5 @@ import { afterEach, describe, expect, test } from "bun:test"; -import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { loadDesiredStateFromConfig } from "../desired-state.js"; @@ -54,4 +54,119 @@ describe("loadDesiredStateFromConfig", () => { /defineConfig/ ); }); + + test("ships local connectors/*.connector.ts source referenced by a connection", async () => { + dir = mkdtempSync(join(import.meta.dir, "connector-")); + mkdirSync(join(dir, "connectors")); + writeFileSync( + join(dir, "connectors", "weather.connector.ts"), + [ + `import { defineConnector } from "@lobu/connector-sdk/define-connector";`, + `export default defineConnector({`, + ` key: "weather",`, + ` feeds: { current: { sync: async () => [] } },`, + `});`, + ``, + ].join("\n") + ); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig, defineConnection } from "@lobu/sdk";`, + `export default defineConfig({`, + ` agents: [defineAgent({ id: "crm" })],`, + ` connections: [defineConnection({ slug: "weather", connector: "weather" })],`, + `});`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + expect(state.connectors.definitions).toHaveLength(1); + const def = state.connectors.definitions[0]; + expect(def?.key).toBeNull(); + expect(def?.sourceFile).toBe("connectors/weather.connector.ts"); + expect(def?.sourcePath).toContain("weather.connector.ts"); + expect(def?.sourceCode).toContain("defineConnector"); + // The connection references the connector by key; the server resolves the + // null key when it compiles the shipped source. + expect(state.connectors.connections[0]?.connector).toBe("weather"); + }); + + test("--only agents skips local connector definitions", async () => { + dir = mkdtempSync(join(import.meta.dir, "only-")); + mkdirSync(join(dir, "connectors")); + writeFileSync( + join(dir, "connectors", "weather.connector.ts"), + [ + `import { defineConnector } from "@lobu/connector-sdk/define-connector";`, + `export default defineConnector({ key: "weather", feeds: { current: { sync: async () => [] } } });`, + ``, + ].join("\n") + ); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig } from "@lobu/sdk";`, + `export default defineConfig({ agents: [defineAgent({ id: "crm" })] });`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ + cwd: dir, + only: "agents", + }); + expect(state.connectors.definitions).toHaveLength(0); + }); + + test("discovers multiple .connector.ts files sorted, ignoring non-matching files and subdirs", async () => { + dir = mkdtempSync(join(import.meta.dir, "multi-")); + mkdirSync(join(dir, "connectors")); + const connectorSrc = `import { defineConnector } from "@lobu/connector-sdk/define-connector";\nexport default defineConnector({ key: "x", feeds: {} });\n`; + // Out-of-order on disk; result must be sorted by sourceFile. + writeFileSync(join(dir, "connectors", "beta.connector.ts"), connectorSrc); + writeFileSync(join(dir, "connectors", "alpha.connector.ts"), connectorSrc); + // Non-matching files are ignored. + writeFileSync( + join(dir, "connectors", "helper.ts"), + `export const x = 1;\n` + ); + writeFileSync(join(dir, "connectors", "README.md"), `# connectors\n`); + // Nested .connector.ts is ignored (scan is non-recursive). + mkdirSync(join(dir, "connectors", "nested")); + writeFileSync( + join(dir, "connectors", "nested", "deep.connector.ts"), + connectorSrc + ); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig } from "@lobu/sdk";`, + `export default defineConfig({ agents: [defineAgent({ id: "crm" })] });`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + expect(state.connectors.definitions.map((d) => d.sourceFile)).toEqual([ + "connectors/alpha.connector.ts", + "connectors/beta.connector.ts", + ]); + }); + + test("no connectors/ dir → no definitions", async () => { + dir = mkdtempSync(join(import.meta.dir, "nodir-")); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig } from "@lobu/sdk";`, + `export default defineConfig({ agents: [defineAgent({ id: "crm" })] });`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + expect(state.connectors.definitions).toHaveLength(0); + }); }); diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index 4691a87d3..f48b1511b 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -2012,6 +2012,66 @@ export async function loadDesiredState( }; } +/** + * Discover local connector definitions for the TypeScript config path. + * + * A `lobu.config.ts` references connectors by key (or via the class returned by + * `defineConnector`); the source the server compiles lives in + * `./connectors/*.connector.ts`. We ship each file's source with `key: null` — + * the server compiles it and resolves the real key, the same contract the YAML + * loader used for auto-discovered `.connector.ts` files. `apply-cmd` then + * compiles each `sourcePath` on the CLI (where the project's node_modules is + * available) and uploads it via `install_connector`. + * + * We intentionally do NOT compile/instantiate the connector here to resolve its + * key eagerly: that would force a full esbuild + module load (and installed + * project deps, and any module-load side effects) on every load — including + * `--dry-run` — for no benefit, since the server is the source of truth for the + * compiled key. The cost is deferred to post-confirmation install in apply-cmd. + * + * Caveat (shared with YAML auto-discovery, see `locallyDeclaredConnectorKeys`): + * because the shipped key is `null`, a connection's config is validated against + * the *fresh* catalog only after install, and a connection that references a + * connector by a bare *string* key relies on that string matching the file's + * compiled `definition.key`. Reference the connector by its `defineConnector` + * class instead (`connector: myConnector`) to make that match exact — the + * mapper resolves the key from `definition.key`, so a typo can't silently bind + * the connection to a different (bundled/remote) connector. + */ +async function discoverLocalConnectorDefinitions( + cwd: string +): Promise { + const dirPath = resolve(cwd, "connectors"); + let entries: string[]; + try { + entries = (await readdir(dirPath)).sort(); + } catch { + // No `./connectors` dir — a project may declare no local connectors. + return []; + } + + const defs: DesiredConnectorDefinition[] = []; + for (const entry of entries) { + if (!entry.endsWith(".connector.ts")) continue; + const entryPath = join(dirPath, entry); + let entryStat; + try { + entryStat = await stat(entryPath); + } catch { + continue; + } + if (!entryStat.isFile()) continue; + const sourceCode = await readFile(entryPath, "utf-8"); + defs.push({ + key: null, + sourcePath: entryPath, + sourceCode, + sourceFile: `connectors/${entry}`, + }); + } + return defs.sort((a, b) => a.sourceFile.localeCompare(b.sourceFile)); +} + /** * Load desired state from a TypeScript entrypoint (`lobu.config.ts`) instead of * `lobu.toml`. Bundles the entrypoint with esbuild (relative imports inlined; @@ -2059,10 +2119,15 @@ export async function loadDesiredStateFromConfig( "lobu.config.ts must `export default defineConfig({ ... })`" ); } - return { - state: mapProjectToDesiredState(project as Project, env, opts.only), - configPath, - }; + const state = mapProjectToDesiredState(project as Project, env, opts.only); + // `--only agents|memory` skips connectors (matching the mapper), so don't + // ship local connector source for those runs either. + if (!opts.only) { + state.connectors.definitions = await discoverLocalConnectorDefinitions( + opts.cwd + ); + } + return { state, configPath }; } finally { rmSync(outFile, { force: true }); } From edf0e26d99bacb1128fe14ac03ac1140578507d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 00:13:18 +0100 Subject: [PATCH 11/65] feat(sdk,cli): express full agent settings + org metadata in the TS config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The TS authoring path (defineAgent + mapProjectToDesiredState) only covered providers + network allowed/denied + the memory schema, while the TOML loader's buildAgentSettings lifts much more. Applying a migrated example would silently drop config (office-bot's egress judges, org metadata, etc.), blocking the TOML-deletion slice. Close that gap. defineAgent gains: network.judged + judges, egress, tools (preApproved/allowed/denied/strict), guardrails, nixPackages, mcpServers (typed type/authScope unions), plus preview and dir (consumed by a later `lobu run`/loader slice — not mapped into cloud settings; a test guards the preview non-leak). defineConfig gains orgName/orgDescription/organizationId. mapProjectToDesiredState now produces the same AgentSettings shape as buildAgentSettings: judgedDomains deduped by domain (last-wins), egressConfig, preApprovedTools + toolsConfig, guardrails, nixConfig, mcpServers (with the same loose cast for authScope/oauth), and collects $VAR/secret() refs from mcp headers/env + oauth clientId/clientSecret into the apply secrets gate. Org metadata maps into DesiredState.memory. Deferred to follow-ups: agent-dir SOUL/IDENTITY/USER markdown + skills/ loading (file IO + skill merge), platforms, dev.ts preview/dir wiring, example migration, TOML deletion. --- .../_lib/apply/__tests__/map-config.test.ts | 194 ++++++++++++++++++ .../cli/src/commands/_lib/apply/map-config.ts | 130 +++++++++++- packages/sdk/src/define.ts | 90 ++++++++ 3 files changed, 412 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index 9306e733f..1e2918ba7 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -247,4 +247,198 @@ describe("mapProjectToDesiredState", () => { expect(state.requiredSecrets).not.toContain("GH_SECRET"); expect(state.agents).toHaveLength(1); }); + + test("maps network judged domains + named judge policies", () => { + const agent = defineAgent({ + id: "ofc", + network: { + allowed: ["api.z.ai"], + judged: [ + { domain: "deliveroo.co.uk", judge: "deliveroo" }, + { domain: ".deliveroo.co.uk", judge: "deliveroo" }, + ], + judges: { deliveroo: "Allow reads; deny checkout." }, + }, + }); + const state = mapProjectToDesiredState( + defineConfig({ agents: [agent] }), + env + ); + const net = state.agents[0]?.settings.networkConfig; + expect(net?.allowedDomains).toEqual(["api.z.ai"]); + expect(net?.judgedDomains).toEqual([ + { domain: "deliveroo.co.uk", judge: "deliveroo" }, + { domain: ".deliveroo.co.uk", judge: "deliveroo" }, + ]); + expect(net?.judges).toEqual({ deliveroo: "Allow reads; deny checkout." }); + }); + + test("maps egress, tools, guardrails, nix packages", () => { + const agent = defineAgent({ + id: "a", + egress: { extraPolicy: "no payments", judgeModel: "haiku" }, + tools: { + preApproved: ["/mcp/gmail/tools/send_email"], + allowed: ["Bash", "Bash"], + denied: ["Delete"], + strict: true, + }, + guardrails: ["secret-scan", "secret-scan", "pii-scan"], + nixPackages: ["ffmpeg", "ffmpeg", "python311"], + }); + const settings = mapProjectToDesiredState( + defineConfig({ agents: [agent] }), + env + ).agents[0]?.settings; + expect(settings?.egressConfig).toEqual({ + extraPolicy: "no payments", + judgeModel: "haiku", + }); + expect(settings?.preApprovedTools).toEqual(["/mcp/gmail/tools/send_email"]); + expect(settings?.toolsConfig).toEqual({ + allowedTools: ["Bash"], + deniedTools: ["Delete"], + strictMode: true, + }); + expect(settings?.guardrails).toEqual(["secret-scan", "pii-scan"]); + expect(settings?.nixConfig).toEqual({ packages: ["ffmpeg", "python311"] }); + }); + + test("maps custom MCP servers and collects oauth/header secret refs", () => { + const agent = defineAgent({ + id: "a", + mcpServers: { + linear: { + url: "https://mcp.linear.app/sse", + type: "sse", + headers: { Authorization: "$LINEAR_TOKEN" }, + oauth: { + authUrl: "https://linear.app/oauth/authorize", + tokenUrl: "https://api.linear.app/oauth/token", + clientId: "cid", + clientSecret: secret("LINEAR_CLIENT_SECRET"), + scopes: ["read"], + }, + }, + }, + }); + const state = mapProjectToDesiredState( + defineConfig({ agents: [agent] }), + env + ); + const linear = state.agents[0]?.settings.mcpServers?.linear as + | Record + | undefined; + expect(linear?.url).toBe("https://mcp.linear.app/sse"); + expect(linear?.headers).toEqual({ Authorization: "$LINEAR_TOKEN" }); + expect(linear?.oauth).toEqual({ + authUrl: "https://linear.app/oauth/authorize", + tokenUrl: "https://api.linear.app/oauth/token", + clientId: "cid", + clientSecret: "$LINEAR_CLIENT_SECRET", + scopes: ["read"], + }); + expect(state.requiredSecrets).toEqual( + expect.arrayContaining(["LINEAR_TOKEN", "LINEAR_CLIENT_SECRET"]) + ); + }); + + test("maps org metadata into memory", () => { + const state = mapProjectToDesiredState( + defineConfig({ + org: "lobu-team", + orgName: "Lobu Team", + orgDescription: "Office-ops agents", + organizationId: "org_123", + agents: [defineAgent({ id: "a" })], + }) + ); + expect(state.memory).toEqual({ + org: "lobu-team", + name: "Lobu Team", + description: "Office-ops agents", + organizationId: "org_123", + }); + }); + + test("preview is authoring-only and not mapped into agent settings", () => { + const agent = defineAgent({ + id: "a", + preview: { slack: { enabled: true, surfaces: ["dm", "channel"] } }, + }); + const settings = mapProjectToDesiredState( + defineConfig({ agents: [agent] }), + env + ).agents[0]?.settings; + // preview drives `lobu run` only — it must not leak into cloud settings. + expect(settings).not.toHaveProperty("preview"); + }); + + test("dedups judged domains by domain (last wins), matching buildAgentSettings", () => { + const agent = defineAgent({ + id: "a", + network: { + judged: [ + { domain: "x.com", judge: "first" }, + { domain: "x.com", judge: "second" }, + { domain: "y.com" }, + ], + }, + }); + const net = mapProjectToDesiredState(defineConfig({ agents: [agent] }), env) + .agents[0]?.settings.networkConfig; + expect(net?.judgedDomains).toEqual([ + { domain: "x.com", judge: "second" }, + { domain: "y.com" }, + ]); + }); + + test("collects mcp env + oauth clientId/clientSecret $VAR refs (parity with collectEnvRefs)", () => { + const agent = defineAgent({ + id: "a", + mcpServers: { + svc: { + command: "node", + args: ["server.js"], + env: { TOKEN: "$SVC_TOKEN" }, + oauth: { + authUrl: "https://a", + tokenUrl: "https://t", + clientId: "$SVC_CLIENT_ID", + clientSecret: "$SVC_CLIENT_SECRET", + }, + }, + }, + }); + const state = mapProjectToDesiredState( + defineConfig({ agents: [agent] }), + env + ); + expect(state.requiredSecrets).toEqual( + expect.arrayContaining([ + "SVC_TOKEN", + "SVC_CLIENT_ID", + "SVC_CLIENT_SECRET", + ]) + ); + // A `$VAR`-string clientSecret is passed through verbatim. + const oauth = ( + state.agents[0]?.settings.mcpServers?.svc as Record + ).oauth as Record; + expect(oauth.clientSecret).toBe("$SVC_CLIENT_SECRET"); + }); + + test("omits absent agent settings (no empty config objects)", () => { + const settings = mapProjectToDesiredState( + defineConfig({ agents: [defineAgent({ id: "a" })] }), + env + ).agents[0]?.settings; + expect(settings).not.toHaveProperty("networkConfig"); + expect(settings).not.toHaveProperty("egressConfig"); + expect(settings).not.toHaveProperty("toolsConfig"); + expect(settings).not.toHaveProperty("preApprovedTools"); + expect(settings).not.toHaveProperty("guardrails"); + expect(settings).not.toHaveProperty("nixConfig"); + expect(settings).not.toHaveProperty("mcpServers"); + }); }); diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index 674eb0158..95bf456d7 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -15,6 +15,7 @@ import type { Connection, ConnectorRef, EntityType, + McpServer, ProviderConfig, Project, RelationshipType, @@ -105,6 +106,68 @@ function credentialString( return value; } +/** + * Map SDK MCP server config to the agent-settings shape. Mirrors the TOML + * loader, including the loose cast: `authScope`/`oauth` aren't on the typed + * `McpServerConfig`, but the server accepts them. `$VAR` refs in headers/env and + * a `secret()` (or `$VAR`) `clientSecret` are collected into `required` so the + * apply secrets gate fails loud, and passed through verbatim (the server/secret + * proxy resolves them) — matching `buildAgentSettings`. + */ +function mapMcpServers( + servers: Record, + required: Set +): NonNullable { + const out: Record> = {}; + for (const [id, mcp] of Object.entries(servers)) { + const mapped: Record = {}; + if (mcp.url) mapped.url = mcp.url; + // We DO map `type` (an intentional, more-correct improvement over the + // legacy agent-level TOML loader, which dropped it even though its + // skill-merge path kept it — and `McpServerConfig.type` is a real field). + if (mcp.type) mapped.type = mcp.type; + if (mcp.command) mapped.command = mcp.command; + if (mcp.args) mapped.args = mcp.args; + if (mcp.headers) { + for (const v of Object.values(mcp.headers)) { + const ref = envRefName(v); + if (ref) required.add(ref); + } + mapped.headers = { ...mcp.headers }; + } + if (mcp.env) { + for (const v of Object.values(mcp.env)) { + const ref = envRefName(v); + if (ref) required.add(ref); + } + mapped.env = { ...mcp.env }; + } + if (mcp.authScope) mapped.authScope = mcp.authScope; + if (mcp.oauth) { + // `client_id` may itself be a `$VAR` ref — collect it like the TOML + // loader's collectEnvRefs does (it's passed through verbatim). + if (mcp.oauth.clientId) { + const ref = envRefName(mcp.oauth.clientId); + if (ref) required.add(ref); + } + mapped.oauth = { + authUrl: mcp.oauth.authUrl, + tokenUrl: mcp.oauth.tokenUrl, + ...(mcp.oauth.clientId ? { clientId: mcp.oauth.clientId } : {}), + ...(mcp.oauth.clientSecret + ? { clientSecret: credentialString(mcp.oauth.clientSecret, required) } + : {}), + ...(mcp.oauth.scopes ? { scopes: mcp.oauth.scopes } : {}), + ...(mcp.oauth.tokenEndpointAuthMethod + ? { tokenEndpointAuthMethod: mcp.oauth.tokenEndpointAuthMethod } + : {}), + }; + } + out[id] = mapped; + } + return out as NonNullable; +} + function mapAgent( agent: Agent, env: NodeJS.ProcessEnv, @@ -130,13 +193,70 @@ function mapAgent( const allowed = agent.network?.allowed ?? []; const denied = agent.network?.denied ?? []; - if (allowed.length > 0 || denied.length > 0) { + const judges = agent.network?.judges ?? {}; + const hasJudges = Object.keys(judges).length > 0; + // Dedup judged rules by domain (last wins), matching buildAgentSettings. + const judgedByDomain = new Map(); + for (const rule of agent.network?.judged ?? []) { + judgedByDomain.set(rule.domain, { + domain: rule.domain, + ...(rule.judge ? { judge: rule.judge } : {}), + }); + } + const judgedDomains = [...judgedByDomain.values()]; + if ( + allowed.length > 0 || + denied.length > 0 || + judgedDomains.length > 0 || + hasJudges + ) { settings.networkConfig = { ...(allowed.length > 0 ? { allowedDomains: [...new Set(allowed)] } : {}), ...(denied.length > 0 ? { deniedDomains: [...new Set(denied)] } : {}), + ...(judgedDomains.length > 0 ? { judgedDomains } : {}), + ...(hasJudges ? { judges } : {}), }; } + if (agent.egress) { + const egressConfig: NonNullable = {}; + if (agent.egress.extraPolicy) { + egressConfig.extraPolicy = agent.egress.extraPolicy; + } + if (agent.egress.judgeModel) + egressConfig.judgeModel = agent.egress.judgeModel; + if (Object.keys(egressConfig).length > 0) + settings.egressConfig = egressConfig; + } + + if (agent.tools) { + if (agent.tools.preApproved?.length) { + settings.preApprovedTools = [...new Set(agent.tools.preApproved)]; + } + const toolsConfig: NonNullable = {}; + if (agent.tools.allowed?.length) { + toolsConfig.allowedTools = [...new Set(agent.tools.allowed)]; + } + if (agent.tools.denied?.length) { + toolsConfig.deniedTools = [...new Set(agent.tools.denied)]; + } + if (agent.tools.strict !== undefined) + toolsConfig.strictMode = agent.tools.strict; + if (Object.keys(toolsConfig).length > 0) settings.toolsConfig = toolsConfig; + } + + if (agent.guardrails?.length) { + settings.guardrails = [...new Set(agent.guardrails)]; + } + + if (agent.nixPackages?.length) { + settings.nixConfig = { packages: [...new Set(agent.nixPackages)] }; + } + + if (agent.mcpServers && Object.keys(agent.mcpServers).length > 0) { + settings.mcpServers = mapMcpServers(agent.mcpServers, required); + } + const providerKeys: { providerId: string; value: string }[] = []; for (const provider of agent.providers ?? []) { if (provider.key === undefined) continue; @@ -353,9 +473,15 @@ export function mapProjectToDesiredState( } } + const memory: NonNullable = {}; + if (project.org) memory.org = project.org; + if (project.orgName) memory.name = project.orgName; + if (project.orgDescription) memory.description = project.orgDescription; + if (project.organizationId) memory.organizationId = project.organizationId; + return { agents, - ...(project.org ? { memory: { org: project.org } } : {}), + ...(Object.keys(memory).length > 0 ? { memory } : {}), memorySchema: { entityTypes, relationshipTypes }, watchers, connectors: { definitions: [], authProfiles, connections }, diff --git a/packages/sdk/src/define.ts b/packages/sdk/src/define.ts index 0b0dcc2ca..4909c02d2 100644 --- a/packages/sdk/src/define.ts +++ b/packages/sdk/src/define.ts @@ -154,9 +154,74 @@ export interface ProviderConfig { key?: string | SecretRef; } +/** Per-domain egress-judge rule: route `domain` through the named judge policy. */ +export interface JudgedDomain { + domain: string; + /** Name of a policy declared in {@link NetworkConfig.judges}. */ + judge?: string; +} + export interface NetworkConfig { + /** Domains the worker may reach (exact or `.wildcard`). */ + allowed?: string[]; + /** Domains explicitly blocked (takes precedence over `allowed`). */ + denied?: string[]; + /** Domains routed through the LLM egress judge. */ + judged?: JudgedDomain[]; + /** Named judge policies (prompt text), referenced by `judged[].judge`. */ + judges?: Record; +} + +/** Operator-level overrides for the LLM egress judge. */ +export interface EgressConfig { + /** Extra instructions appended to the egress judge prompt. */ + extraPolicy?: string; + /** Override the model the egress judge runs on. */ + judgeModel?: string; +} + +/** Worker-side tool permissions. */ +export interface ToolsConfig { + /** + * MCP tool grant patterns pre-approved by the operator (e.g. + * `/mcp/gmail/tools/send_email`), bypassing the in-chat approval card. + */ + preApproved?: string[]; allowed?: string[]; denied?: string[]; + /** Reject tool calls that aren't in `allowed`. */ + strict?: boolean; +} + +/** OAuth flow for a custom MCP server. */ +export interface McpServerOAuth { + authUrl: string; + tokenUrl: string; + clientId?: string; + clientSecret?: string | SecretRef; + scopes?: string[]; + tokenEndpointAuthMethod?: string; +} + +/** A custom MCP server made available to the agent's worker. */ +export interface McpServer { + url?: string; + command?: string; + args?: string[]; + headers?: Record; + type?: "sse" | "streamable-http" | "stdio"; + authScope?: "user" | "channel"; + oauth?: McpServerOAuth; + env?: Record; +} + +/** Hosted "Lobu Developer" preview-bot config for one chat platform. */ +export interface PreviewConfig { + enabled?: boolean; + /** Surfaces a preview code can bind: a DM with the bot, or a channel. */ + surfaces?: Array<"dm" | "channel">; + /** Short-lived claim-code TTL (capped by the hosted preview API). */ + codeTtlMinutes?: number; } export interface Agent { @@ -164,8 +229,27 @@ export interface Agent { id: string; name?: string; description?: string; + /** + * Agent directory holding `SOUL.md` / `IDENTITY.md` / `USER.md` and a + * `skills/` folder. Relative to the config file; defaults to + * `./agents/`. + */ + dir?: string; providers?: ProviderConfig[]; network?: NetworkConfig; + egress?: EgressConfig; + tools?: ToolsConfig; + /** Guardrails enabled for this agent, by registered name. */ + guardrails?: string[]; + /** Nix packages provisioned into the worker environment. */ + nixPackages?: string[]; + /** Custom MCP servers, keyed by id. */ + mcpServers?: Record; + /** + * Hosted preview-bot config, keyed by chat platform (`slack`/`telegram`). + * Consumed by `lobu run` (dev-time only) — not part of cloud apply. + */ + preview?: Record; /** Connections this agent uses (handle or slug). */ connections?: Array; schema?: { @@ -186,6 +270,12 @@ export interface Project { readonly kind: "project"; /** Lobu Cloud org slug this project applies to. */ org?: string; + /** Display name used if `lobu apply` offers to provision the org. */ + orgName?: string; + /** Org description. */ + orgDescription?: string; + /** Resolved Lobu Cloud org id — `lobu apply` matches against it. */ + organizationId?: string; agents: Agent[]; entities?: EntityType[]; relationships?: RelationshipType[]; From f17c688e2bed49c97bca343d796586df16fe6a84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 00:24:29 +0100 Subject: [PATCH 12/65] feat(cli): load agent-dir markdown + skills in the TS config path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit buildAgentSettings lifts SOUL.md/IDENTITY.md/USER.md prompt markdown and local skills (project ./skills + per-agent /skills, with their network/nix/mcp declarations merged into agent settings); the TS config path did neither, so a migrated agent would lose its prompt files and skills. loadDesiredStateFromConfig now reads each agent's dir (defaulting to ./agents/, overridable via defineAgent.dir) using the existing readMarkdown/loadSkillFiles/buildLocalSkills helpers, and merges the result via a new pure mergeAgentDirArtifacts(settings, markdown, skills). The mapper stays file-IO-free (unit-testable); the merge mirrors buildAgentSettings exactly: agent-level network/nix/mcp first, skills on top — allowed/denied/nix unioned+deduped (skill "*" dropped), judged-domains + judges agent-wins on conflict, skill MCP servers add only ids the agent didn't define. --- .../_lib/apply/__tests__/load-config.test.ts | 114 ++++++++++++++++++ .../_lib/apply/__tests__/map-config.test.ts | 97 ++++++++++++++- .../src/commands/_lib/apply/desired-state.ts | 34 +++++- .../cli/src/commands/_lib/apply/map-config.ts | 104 ++++++++++++++++ 4 files changed, 346 insertions(+), 3 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts index 3f032a198..baf0fb093 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts @@ -155,6 +155,120 @@ describe("loadDesiredStateFromConfig", () => { ]); }); + test("loads agent-dir markdown + skills and merges skill network config", async () => { + dir = mkdtempSync(join(import.meta.dir, "agentdir-")); + const agentDir = join(dir, "agents", "crm"); + mkdirSync(join(agentDir, "skills", "crm-ops"), { recursive: true }); + writeFileSync(join(agentDir, "SOUL.md"), "You are the CRM agent.\n"); + writeFileSync(join(agentDir, "IDENTITY.md"), "CRM identity.\n"); + writeFileSync( + join(agentDir, "skills", "crm-ops", "SKILL.md"), + [ + `---`, + `name: crm-ops`, + `network:`, + ` allow: ["api.crm.com"]`, + `nixPackages: ["jq"]`, + `---`, + `Use the CRM API.`, + ``, + ].join("\n") + ); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig } from "@lobu/sdk";`, + `export default defineConfig({`, + ` agents: [defineAgent({ id: "crm", network: { allowed: ["github.com"] } })],`, + `});`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + const settings = state.agents[0]?.settings; + expect(settings?.soulMd).toBe("You are the CRM agent."); + expect(settings?.identityMd).toBe("CRM identity."); + expect(settings?.skillsConfig?.skills[0]?.name).toBe("crm-ops"); + // Agent + skill network domains are unioned. + expect(settings?.networkConfig?.allowedDomains).toEqual([ + "github.com", + "api.crm.com", + ]); + expect(settings?.nixConfig?.packages).toEqual(["jq"]); + }); + + test("two agents: custom + default dirs keep index alignment; project ./skills applies to all", async () => { + dir = mkdtempSync(join(import.meta.dir, "multiagent-")); + // Agent "a" uses a custom dir; agent "b" uses the default ./agents/b. + mkdirSync(join(dir, "custom-a"), { recursive: true }); + mkdirSync(join(dir, "agents", "b"), { recursive: true }); + writeFileSync(join(dir, "custom-a", "SOUL.md"), "Agent A soul.\n"); + writeFileSync(join(dir, "agents", "b", "SOUL.md"), "Agent B soul.\n"); + // Project-level shared skill (applies to every agent). + mkdirSync(join(dir, "skills", "shared"), { recursive: true }); + writeFileSync( + join(dir, "skills", "shared", "SKILL.md"), + "---\nname: shared\n---\nShared.\n" + ); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig } from "@lobu/sdk";`, + `export default defineConfig({`, + ` agents: [`, + ` defineAgent({ id: "a", dir: "./custom-a" }),`, + ` defineAgent({ id: "b" }),`, + ` ],`, + `});`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + // Index alignment: agents[0]=a (custom dir), agents[1]=b (default dir). + expect(state.agents[0]?.metadata.agentId).toBe("a"); + expect(state.agents[0]?.settings.soulMd).toBe("Agent A soul."); + expect(state.agents[1]?.metadata.agentId).toBe("b"); + expect(state.agents[1]?.settings.soulMd).toBe("Agent B soul."); + // The project-level skill is merged into both agents. + expect(state.agents[0]?.settings.skillsConfig?.skills[0]?.name).toBe( + "shared" + ); + expect(state.agents[1]?.settings.skillsConfig?.skills[0]?.name).toBe( + "shared" + ); + }); + + test("agent-dir skill overrides a project skill of the same name", async () => { + dir = mkdtempSync(join(import.meta.dir, "skilloverride-")); + mkdirSync(join(dir, "skills", "ops"), { recursive: true }); + mkdirSync(join(dir, "agents", "a", "skills", "ops"), { recursive: true }); + writeFileSync( + join(dir, "skills", "ops", "SKILL.md"), + "---\nname: ops\n---\nProject ops.\n" + ); + writeFileSync( + join(dir, "agents", "a", "skills", "ops", "SKILL.md"), + "---\nname: ops\n---\nAgent ops.\n" + ); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig } from "@lobu/sdk";`, + `export default defineConfig({ agents: [defineAgent({ id: "a" })] });`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + const skills = state.agents[0]?.settings.skillsConfig?.skills; + // loadSkillFiles reads [./skills, /skills] in order, deduping by + // name — the agent-dir skill (read last) wins. + expect(skills).toHaveLength(1); + expect(skills?.[0]?.content).toBe("Agent ops."); + }); + test("no connectors/ dir → no definitions", async () => { dir = mkdtempSync(join(import.meta.dir, "nodir-")); writeFileSync( diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index 1e2918ba7..c0d8bcdeb 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -10,7 +10,11 @@ import { defineWatcher, secret, } from "@lobu/sdk"; -import { mapProjectToDesiredState } from "../map-config.js"; +import { + mapProjectToDesiredState, + mergeAgentDirArtifacts, +} from "../map-config.js"; +import type { AgentSettings } from "@lobu/core"; const env: NodeJS.ProcessEnv = { ANTHROPIC_API_KEY: "sk-test", @@ -442,3 +446,94 @@ describe("mapProjectToDesiredState", () => { expect(settings).not.toHaveProperty("mcpServers"); }); }); + +describe("mergeAgentDirArtifacts", () => { + test("sets prompt markdown and skillsConfig", () => { + const settings: Partial = {}; + mergeAgentDirArtifacts( + settings, + { soulMd: "soul", identityMd: "id", userMd: "user" }, + [{ repo: "local/s", name: "s", content: "body", enabled: true }] + ); + expect(settings.soulMd).toBe("soul"); + expect(settings.identityMd).toBe("id"); + expect(settings.userMd).toBe("user"); + expect(settings.skillsConfig?.skills).toHaveLength(1); + expect(settings.skillsConfig?.skills[0]?.name).toBe("s"); + }); + + test("unions network allowed/denied/nix; agent wins on judged + judges", () => { + const settings: Partial = { + networkConfig: { + allowedDomains: ["agent.com"], + judgedDomains: [{ domain: "shared.com", judge: "agent-policy" }], + judges: { p: "agent prompt" }, + }, + nixConfig: { packages: ["ffmpeg"] }, + }; + mergeAgentDirArtifacts(settings, {}, [ + { + repo: "local/s", + name: "s", + content: "b", + enabled: true, + nixPackages: ["python311", "ffmpeg"], + networkConfig: { + allowedDomains: ["skill.com", "*"], + deniedDomains: ["bad.com"], + judgedDomains: [ + { domain: "shared.com", judge: "skill-policy" }, + { domain: "skill-only.com" }, + ], + judges: { p: "skill prompt", q: "skill q" }, + }, + }, + ]); + // "*" from a skill is dropped; agent + skill domains unioned + deduped. + expect(settings.networkConfig?.allowedDomains).toEqual([ + "agent.com", + "skill.com", + ]); + expect(settings.networkConfig?.deniedDomains).toEqual(["bad.com"]); + // Agent wins on the shared judged domain; skill-only domain kept. + expect(settings.networkConfig?.judgedDomains).toEqual([ + { domain: "shared.com", judge: "agent-policy" }, + { domain: "skill-only.com" }, + ]); + // Agent wins on the shared judge key; skill-only key kept. + expect(settings.networkConfig?.judges).toEqual({ + p: "agent prompt", + q: "skill q", + }); + expect(settings.nixConfig?.packages).toEqual(["ffmpeg", "python311"]); + }); + + test("agent MCP servers win; skills add only new ids", () => { + const settings: Partial = { + mcpServers: { gmail: { url: "https://agent" } }, + }; + mergeAgentDirArtifacts(settings, {}, [ + { + repo: "local/s", + name: "s", + content: "b", + enabled: true, + mcpServers: [ + { id: "gmail", url: "https://skill-should-not-win" }, + { id: "linear", url: "https://skill", type: "sse" }, + ], + }, + ]); + expect(settings.mcpServers?.gmail).toEqual({ url: "https://agent" }); + expect(settings.mcpServers?.linear).toEqual({ + url: "https://skill", + type: "sse", + }); + }); + + test("no markdown / no skills leaves settings untouched", () => { + const settings: Partial = {}; + mergeAgentDirArtifacts(settings, {}, []); + expect(settings).toEqual({}); + }); +}); diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index f48b1511b..10e70cc70 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -25,7 +25,10 @@ import { isLoadError, loadConfig, } from "../../../config/loader.js"; -import { mapProjectToDesiredState } from "./map-config.js"; +import { + mapProjectToDesiredState, + mergeAgentDirArtifacts, +} from "./map-config.js"; import { CronExpressionParser } from "cron-parser"; // ── Connector slug / schedule validators (round-2) ───────────────────────── @@ -2119,7 +2122,34 @@ export async function loadDesiredStateFromConfig( "lobu.config.ts must `export default defineConfig({ ... })`" ); } - const state = mapProjectToDesiredState(project as Project, env, opts.only); + const typedProject = project as Project; + const state = mapProjectToDesiredState(typedProject, env, opts.only); + + // Agent-directory artifacts: SOUL/IDENTITY/USER.md + local skills. The + // mapper stays pure (no file IO); we read the files here and merge them into + // each agent's settings, mirroring the TOML loader (project `./skills` + + // per-agent `/skills`; default dir `./agents/`). + await Promise.all( + typedProject.agents.map(async (agent, i) => { + const settings = state.agents[i]?.settings; + if (!settings) return; + const agentDir = resolve( + opts.cwd, + agent.dir ?? join("agents", agent.id) + ); + const markdown = await readMarkdown(agentDir); + const skillFiles = await loadSkillFiles([ + join(opts.cwd, "skills"), + join(agentDir, "skills"), + ]); + mergeAgentDirArtifacts( + settings, + markdown, + buildLocalSkills(skillFiles) + ); + }) + ); + // `--only agents|memory` skips connectors (matching the mapper), so don't // ship local connector source for those runs either. if (!opts.only) { diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index 95bf456d7..782881015 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -106,6 +106,110 @@ function credentialString( return value; } +/** Skill entries produced by `buildLocalSkills` (agent-dir + project `skills/`). */ +type LocalSkills = NonNullable["skills"]; + +/** Agent-dir prompt markdown (read by the loader from SOUL/IDENTITY/USER.md). */ +export interface AgentMarkdown { + soulMd?: string; + identityMd?: string; + userMd?: string; +} + +/** + * Merge agent-directory artifacts (prompt markdown + local skills) into the + * already-mapped agent settings. Pure (no file IO — the loader reads the files + * and passes the results in) so it can be unit-tested directly. + * + * Mirrors `buildAgentSettings`'s skill-merge semantics exactly: agent-level + * network/nix/mcp is laid down first (already in `settings`), then skills are + * merged on top — allowed/denied/nix are unioned (deduped), judged-domains and + * judges are skill-first with the AGENT WINNING on conflicts, and skill MCP + * servers add only ids the agent didn't already define. + */ +export function mergeAgentDirArtifacts( + settings: Partial, + markdown: AgentMarkdown, + localSkills: LocalSkills +): void { + if (markdown.soulMd) settings.soulMd = markdown.soulMd; + if (markdown.identityMd) settings.identityMd = markdown.identityMd; + if (markdown.userMd) settings.userMd = markdown.userMd; + + if (localSkills.length > 0) { + settings.skillsConfig = { skills: localSkills }; + } + + // Network merge — agent values are already in settings.networkConfig. + const allowed = [...(settings.networkConfig?.allowedDomains ?? [])]; + const denied = [...(settings.networkConfig?.deniedDomains ?? [])]; + const judgedByDomain = new Map(); + const judges: Record = {}; + // Skills first. + for (const skill of localSkills) { + const net = skill.networkConfig; + if (!net) continue; + if (net.allowedDomains?.length) { + allowed.push(...net.allowedDomains.filter((d) => d !== "*")); + } + if (net.deniedDomains?.length) denied.push(...net.deniedDomains); + for (const rule of net.judgedDomains ?? []) { + judgedByDomain.set(rule.domain, rule); + } + if (net.judges) Object.assign(judges, net.judges); + } + // Agent overrides skills on judged/judges. + for (const rule of settings.networkConfig?.judgedDomains ?? []) { + judgedByDomain.set(rule.domain, rule); + } + Object.assign(judges, settings.networkConfig?.judges ?? {}); + + const judgedDomains = [...judgedByDomain.values()]; + const hasJudges = Object.keys(judges).length > 0; + if ( + allowed.length > 0 || + denied.length > 0 || + judgedDomains.length > 0 || + hasJudges + ) { + settings.networkConfig = { + ...(allowed.length > 0 ? { allowedDomains: [...new Set(allowed)] } : {}), + ...(denied.length > 0 ? { deniedDomains: [...new Set(denied)] } : {}), + ...(judgedDomains.length > 0 ? { judgedDomains } : {}), + ...(hasJudges ? { judges } : {}), + }; + } + + // Nix merge — agent packages first, then skill packages, deduped. + const nixPackages = [ + ...(settings.nixConfig?.packages ?? []), + ...localSkills.flatMap((s) => s.nixPackages ?? []), + ]; + if (nixPackages.length > 0) { + settings.nixConfig = { + ...settings.nixConfig, + packages: [...new Set(nixPackages)], + }; + } + + // MCP merge — agent servers win; skills add only ids the agent didn't define. + const mcpServers: Record = { ...settings.mcpServers }; + for (const skill of localSkills) { + for (const mcp of skill.mcpServers ?? []) { + if (mcpServers[mcp.id]) continue; + mcpServers[mcp.id] = { + ...(mcp.url ? { url: mcp.url } : {}), + ...(mcp.type ? { type: mcp.type } : {}), + ...(mcp.command ? { command: mcp.command } : {}), + ...(mcp.args ? { args: mcp.args } : {}), + }; + } + } + if (Object.keys(mcpServers).length > 0) { + settings.mcpServers = mcpServers as AgentSettings["mcpServers"]; + } +} + /** * Map SDK MCP server config to the agent-settings shape. Mirrors the TOML * loader, including the loose cast: `authScope`/`oauth` aren't on the typed From 93f8895b462bd457b9e7f544536225b907ddd1e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 00:28:47 +0100 Subject: [PATCH 13/65] feat(sdk,cli): map watcher reactionsGuidance + agentKind These two DesiredWatcher fields are used by example watchers (8 and 2 uses respectively) but had no defineWatcher equivalent, so a migrated watcher would drop them. Add the SDK fields + mapper passthrough. The executable `reaction` (reaction_script) field still lands in the reactions slice. --- .../_lib/apply/__tests__/map-config.test.ts | 17 +++++++++++++++++ .../cli/src/commands/_lib/apply/map-config.ts | 4 ++++ packages/sdk/src/define.ts | 5 +++++ 3 files changed, 26 insertions(+) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index c0d8bcdeb..b982a6709 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -104,6 +104,23 @@ describe("mapProjectToDesiredState", () => { expect(dw?.minCooldownSeconds).toBe(1800); }); + test("maps watcher reactionsGuidance + agentKind", () => { + const crm = defineAgent({ id: "crm" }); + const watcher = defineWatcher({ + agent: crm, + slug: "w", + prompt: "p", + extractionSchema: {}, + reactionsGuidance: "Notify the account owner.", + agentKind: "notifier", + }); + const dw = mapProjectToDesiredState( + defineConfig({ agents: [crm], watchers: [watcher] }) + ).watchers[0]; + expect(dw?.reactionsGuidance).toBe("Notify the account owner."); + expect(dw?.agentKind).toBe("notifier"); + }); + test("throws when a watcher names an unknown agent", () => { const watcher = defineWatcher({ agent: "ghost", diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index 782881015..cd555be81 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -451,6 +451,10 @@ function mapWatcher(watcher: Watcher): DesiredWatcher { ? { minCooldownSeconds: watcher.minCooldownSeconds } : {}), ...(watcher.tags ? { tags: watcher.tags } : {}), + ...(watcher.reactionsGuidance + ? { reactionsGuidance: watcher.reactionsGuidance } + : {}), + ...(watcher.agentKind ? { agentKind: watcher.agentKind } : {}), }; } diff --git a/packages/sdk/src/define.ts b/packages/sdk/src/define.ts index 4909c02d2..b03a30f16 100644 --- a/packages/sdk/src/define.ts +++ b/packages/sdk/src/define.ts @@ -138,6 +138,11 @@ export interface Watcher { notification?: WatcherNotification; minCooldownSeconds?: number; tags?: string[]; + /** LLM guidance for the watcher's downstream reaction agent. */ + reactionsGuidance?: string; + /** Agent-kind override for firings (e.g. "background", "notifier"). */ + agentKind?: string; + // NOTE: the executable `reaction` (TS module) lands in the reactions slice. } export function defineWatcher(config: Omit): Watcher { From dc15904e2c358355edf59fa7a92e74aaf82e7476 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 00:41:28 +0100 Subject: [PATCH 14/65] fix(sdk): drop unwired Agent.connections + Agent.schema (pi review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit defineAgent() accepted `connections` and `schema` but mapProjectToDesiredState ignored them — a silent config drop. Connections and the memory schema are declared at the project level (defineConfig), matching the apply model (there is no agent-scoped association in DesiredState). Remove the dead fields rather than leave them silently ignored; project-level remains the wired path. --- packages/sdk/src/define.ts | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/packages/sdk/src/define.ts b/packages/sdk/src/define.ts index b03a30f16..707d58a94 100644 --- a/packages/sdk/src/define.ts +++ b/packages/sdk/src/define.ts @@ -255,12 +255,10 @@ export interface Agent { * Consumed by `lobu run` (dev-time only) — not part of cloud apply. */ preview?: Record; - /** Connections this agent uses (handle or slug). */ - connections?: Array; - schema?: { - entities?: EntityType[]; - relationships?: RelationshipType[]; - }; + // NOTE: connections and the memory schema are declared at the project level + // (`defineConfig({ connections, entities, relationships })`), matching the + // apply model — there is no agent-scoped association in DesiredState. Agent + // fields for them were removed rather than left silently ignored. } export function defineAgent(config: Omit): Agent { From 2236e5ad20a61133ff5a5dff88e9886ef943317b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 00:42:31 +0100 Subject: [PATCH 15/65] chore(client): move @hey-api/client-fetch to devDependencies (pi review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The generated client vendors its fetch runtime into src/generated/client/ — no runtime code imports the @hey-api/client-fetch npm package; it is used only by @hey-api/openapi-ts at generation time (openapi-ts.config.ts plugin). Move it to devDependencies so consumers of the published @lobu/client don't install it. --- bun.lock | 4 +--- packages/client/package.json | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/bun.lock b/bun.lock index 020296d46..a6996c1a4 100644 --- a/bun.lock +++ b/bun.lock @@ -131,10 +131,8 @@ "packages/client": { "name": "@lobu/client", "version": "9.1.1", - "dependencies": { - "@hey-api/client-fetch": "^0.13.1", - }, "devDependencies": { + "@hey-api/client-fetch": "^0.13.1", "@hey-api/openapi-ts": "^0.86.5", "typescript": "^5.8.3", }, diff --git a/packages/client/package.json b/packages/client/package.json index 03c0bb819..6229f2b71 100644 --- a/packages/client/package.json +++ b/packages/client/package.json @@ -34,10 +34,8 @@ "url": "git+https://github.com/lobu-ai/lobu.git", "directory": "packages/client" }, - "dependencies": { - "@hey-api/client-fetch": "^0.13.1" - }, "devDependencies": { + "@hey-api/client-fetch": "^0.13.1", "@hey-api/openapi-ts": "^0.86.5", "typescript": "^5.8.3" } From 1b52cc6f1917b84b9671b11c7ea8650c3fdf02ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 00:54:13 +0100 Subject: [PATCH 16/65] feat(sdk,cli): watcher reaction scripts in the TS config path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit defineWatcher gains `reaction?: string` — a relative POSIX path to a sibling .ts reaction script. loadDesiredStateFromConfig validates + reads it (raw source) and attaches it to DesiredWatcher.reactionScript; apply ships it via the existing setReactionScript and the server compiles it. Mirrors the TOML loader's parseWatcher exactly: relative-POSIX/.ts/no-`..`/under-config-dir/ 256KB checks, present-but-empty rejected (gate on absence, not truthiness), raw-source contract. mapWatcher stays pure; the loader zips project.watchers[i].reaction -> state.watchers[i].reactionScript. Unblocks the 6 example watchers that use reaction_script. (The runAction / operations typing on ReactionClient is a separate enhancement — no example reaction calls connector actions; they only use client.knowledge.) --- .../_lib/apply/__tests__/load-config.test.ts | 97 +++++++++++++++++++ .../src/commands/_lib/apply/desired-state.ts | 75 ++++++++++++++ packages/sdk/src/define.ts | 9 +- 3 files changed, 180 insertions(+), 1 deletion(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts index baf0fb093..20b694681 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/load-config.test.ts @@ -269,6 +269,103 @@ describe("loadDesiredStateFromConfig", () => { expect(skills?.[0]?.content).toBe("Agent ops."); }); + test("loads a watcher reaction script (raw source) referenced by path", async () => { + dir = mkdtempSync(join(import.meta.dir, "reaction-")); + mkdirSync(join(dir, "reactions")); + writeFileSync( + join(dir, "reactions", "health.reaction.ts"), + [ + `import type { ReactionContext, ReactionClient } from "@lobu/connector-sdk";`, + `export default async (ctx: ReactionContext, client: ReactionClient) => {`, + ` await client.knowledge.save({ content: "ok", semantic_type: "digest" });`, + `};`, + ``, + ].join("\n") + ); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig, defineWatcher } from "@lobu/sdk";`, + `const crm = defineAgent({ id: "crm" });`, + `export default defineConfig({`, + ` agents: [crm],`, + ` watchers: [defineWatcher({`, + ` agent: crm, slug: "health", prompt: "p", extractionSchema: { type: "object" },`, + ` reaction: "./reactions/health.reaction.ts",`, + ` })],`, + `});`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + const rs = state.watchers[0]?.reactionScript; + expect(rs?.sourcePath).toContain("health.reaction.ts"); + expect(rs?.sourceCode).toContain("client.knowledge.save"); + }); + + test("rejects a reaction path that escapes the config dir or is missing", async () => { + const write = (reaction: string) => { + dir = mkdtempSync(join(import.meta.dir, "badreaction-")); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig, defineWatcher } from "@lobu/sdk";`, + `const crm = defineAgent({ id: "crm" });`, + `export default defineConfig({ agents: [crm], watchers: [defineWatcher({`, + ` agent: crm, slug: "w", prompt: "p", extractionSchema: {}, reaction: ${JSON.stringify(reaction)},`, + `})] });`, + ``, + ].join("\n") + ); + return loadDesiredStateFromConfig({ cwd: dir }); + }; + await expect(write("../escape.reaction.ts")).rejects.toThrow(/\.\./); + rmSync(dir, { recursive: true, force: true }); + await expect(write("/abs/path.reaction.ts")).rejects.toThrow( + /relative POSIX path/ + ); + rmSync(dir, { recursive: true, force: true }); + await expect(write("./missing.reaction.ts")).rejects.toThrow( + /does not exist/ + ); + rmSync(dir, { recursive: true, force: true }); + // Present-but-empty must be rejected (not silently skipped) — parity with + // parseWatcher, which validates whenever the field is present. + await expect(write("")).rejects.toThrow(/sibling \.ts file/); + rmSync(dir, { recursive: true, force: true }); + await expect(write("./notes.md")).rejects.toThrow(/must end in `\.ts`/); + }); + + test("attaches the reaction to the right watcher when only one of several has one", async () => { + dir = mkdtempSync(join(import.meta.dir, "reactionidx-")); + mkdirSync(join(dir, "reactions")); + writeFileSync( + join(dir, "reactions", "second.reaction.ts"), + `export default async () => {};\n` + ); + writeFileSync( + join(dir, "lobu.config.ts"), + [ + `import { defineAgent, defineConfig, defineWatcher } from "@lobu/sdk";`, + `const a = defineAgent({ id: "a" });`, + `export default defineConfig({ agents: [a], watchers: [`, + ` defineWatcher({ agent: a, slug: "first", prompt: "p", extractionSchema: {} }),`, + ` defineWatcher({ agent: a, slug: "second", prompt: "p", extractionSchema: {}, reaction: "./reactions/second.reaction.ts" }),`, + `] });`, + ``, + ].join("\n") + ); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + expect(state.watchers[0]?.slug).toBe("first"); + expect(state.watchers[0]?.reactionScript).toBeUndefined(); + expect(state.watchers[1]?.slug).toBe("second"); + expect(state.watchers[1]?.reactionScript?.sourcePath).toContain( + "second.reaction.ts" + ); + }); + test("no connectors/ dir → no definitions", async () => { dir = mkdtempSync(join(import.meta.dir, "nodir-")); writeFileSync( diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index 10e70cc70..df9ccc5d6 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -2075,6 +2075,64 @@ async function discoverLocalConnectorDefinitions( return defs.sort((a, b) => a.sourceFile.localeCompare(b.sourceFile)); } +const REACTION_SCRIPT_MAX_BYTES = 256 * 1024; + +/** + * Resolve + read a watcher reaction script (`defineWatcher({ reaction })`) for + * the TS config path. Mirrors the TOML loader's `parseWatcher` validation: + * relative POSIX path under the config directory, ends in `.ts`, no `..` / + * absolute / backslash segments, ≤256KB. Ships RAW source — the server compiles + * it — exactly as the TOML path does via `set_reaction_script`. + */ +function resolveReactionScript( + cwd: string, + watcherSlug: string, + rel: string +): { sourcePath: string; sourceCode: string } { + const trimmed = rel.trim(); + if (!trimmed) { + throw new ValidationError( + `watcher "${watcherSlug}" \`reaction\` must be a path to a sibling .ts file (e.g. \`reaction: "./reactions/foo.reaction.ts"\`)` + ); + } + if (trimmed.startsWith("/") || trimmed.includes("\\")) { + throw new ValidationError( + `watcher "${watcherSlug}" \`reaction\` must be a relative POSIX path (./foo.reaction.ts) — absolute paths and backslashes are not allowed` + ); + } + if (trimmed.split("/").some((seg) => seg === "..")) { + throw new ValidationError( + `watcher "${watcherSlug}" \`reaction\` must not contain \`..\` segments — keep the script under the config directory` + ); + } + if (!trimmed.endsWith(".ts")) { + throw new ValidationError( + `watcher "${watcherSlug}" \`reaction\` must end in \`.ts\` (got ${JSON.stringify(trimmed)})` + ); + } + const baseDir = resolve(cwd); + const abs = resolve(baseDir, trimmed); + if (!abs.startsWith(`${baseDir}/`) && abs !== baseDir) { + throw new ValidationError( + `watcher "${watcherSlug}" \`reaction\` resolves outside the config directory (${abs})` + ); + } + let sourceCode: string; + try { + sourceCode = readFileSync(abs, "utf-8"); + } catch { + throw new ValidationError( + `watcher "${watcherSlug}" \`reaction\` ${trimmed} does not exist (resolved to ${abs})` + ); + } + if (Buffer.byteLength(sourceCode, "utf8") > REACTION_SCRIPT_MAX_BYTES) { + throw new ValidationError( + `watcher "${watcherSlug}" \`reaction\` exceeds the ${REACTION_SCRIPT_MAX_BYTES}-byte cap — reaction scripts should be a few hundred lines, not a vendored library` + ); + } + return { sourcePath: abs, sourceCode }; +} + /** * Load desired state from a TypeScript entrypoint (`lobu.config.ts`) instead of * `lobu.toml`. Bundles the entrypoint with esbuild (relative imports inlined; @@ -2150,6 +2208,23 @@ export async function loadDesiredStateFromConfig( }) ); + // Watcher reaction scripts: a sibling `.ts` file referenced by path. The + // mapper stays pure; resolve + read the source here (raw, server compiles + // it) and attach it. state.watchers[i] aligns with typedProject.watchers[i] + // (the mapper maps them in order). + (typedProject.watchers ?? []).forEach((watcher, i) => { + // Gate on absence, not truthiness — a present-but-empty `reaction: ""` + // must reach the validator (which rejects it), matching parseWatcher. + if (watcher.reaction === undefined) return; + const dw = state.watchers[i]; + if (!dw) return; + dw.reactionScript = resolveReactionScript( + opts.cwd, + watcher.slug, + watcher.reaction + ); + }); + // `--only agents|memory` skips connectors (matching the mapper), so don't // ship local connector source for those runs either. if (!opts.only) { diff --git a/packages/sdk/src/define.ts b/packages/sdk/src/define.ts index 707d58a94..1d3c08025 100644 --- a/packages/sdk/src/define.ts +++ b/packages/sdk/src/define.ts @@ -142,7 +142,14 @@ export interface Watcher { reactionsGuidance?: string; /** Agent-kind override for firings (e.g. "background", "notifier"). */ agentKind?: string; - // NOTE: the executable `reaction` (TS module) lands in the reactions slice. + /** + * Relative POSIX path to a sibling `.ts` reaction script + * (`./reactions/foo.reaction.ts`), compiled + run in a sandboxed isolate when + * the watcher fires. The script must `export default async (ctx, client) => + * …`. Kept in its own file (not inline) so your IDE type-checks it; the path + * must stay under the config directory. + */ + reaction?: string; } export function defineWatcher(config: Omit): Watcher { From 41bb04681631f4da26af17e10cb87c0976d594f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 01:16:58 +0100 Subject: [PATCH 17/65] fix(cli): resolve non-interactive auth-profile credentials to env values MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mapAuthProfile shipped the literal `$VAR` placeholder for env/oauth_app credentials, whereas the TOML loader (loadConnectors) resolves them to the real env value before pushing to the DB — so a TS-config auth profile would write "$GITHUB_CLIENT_SECRET" instead of the secret. Add resolveCredentialValue (mirrors loadConnectors): secret()/$VAR creds resolve against env, the ref is still collected for the apply secrets gate. mcp oauth client_secret keeps the literal pass-through (matching buildAgentSettings). Found migrating lobu-crm. --- .../_lib/apply/__tests__/map-config.test.ts | 4 ++- .../cli/src/commands/_lib/apply/map-config.ts | 32 +++++++++++++++++-- 2 files changed, 32 insertions(+), 4 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index b982a6709..42e95a05a 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -166,7 +166,9 @@ describe("mapProjectToDesiredState", () => { const ap = state.connectors.authProfiles[0]; expect(ap?.connector).toBe("github"); // class resolved to its key expect(ap?.kind).toBe("oauth_app"); - expect(ap?.credentials).toEqual({ clientSecret: "$GH_SECRET" }); + // Non-interactive auth-profile creds resolve to the REAL env value (apply + // pushes the value to the DB), matching the TOML loader — not the $VAR. + expect(ap?.credentials).toEqual({ clientSecret: "ghs_test" }); expect(state.requiredSecrets).toContain("GH_SECRET"); const dc = state.connectors.connections[0]; expect(dc?.connector).toBe("github"); diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index cd555be81..182172dfb 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -106,6 +106,31 @@ function credentialString( return value; } +/** + * Resolve a credential to its actual secret value, mirroring the TOML loader's + * connector-credential handling (`loadConnectors` in desired-state.ts): a + * `secret()` / `$VAR` ref resolves to its env value — apply pushes the REAL + * value to the DB, never the `$VAR` placeholder — and a literal passes through. + * The ref is collected so the apply secrets gate fails loud when it is unset + * (the placeholder is only returned as a safe fallback the gate then rejects). + */ +function resolveCredentialValue( + value: string | { readonly $secret: string }, + required: Set, + env: NodeJS.ProcessEnv +): string { + if (isSecretRef(value)) { + required.add(value.$secret); + return env[value.$secret] ?? `$${value.$secret}`; + } + const ref = envRefName(value); + if (ref) { + required.add(ref); + return env[ref] ?? value; + } + return value; +} + /** Skill entries produced by `buildLocalSkills` (agent-dir + project `skills/`). */ type LocalSkills = NonNullable["skills"]; @@ -460,7 +485,8 @@ function mapWatcher(watcher: Watcher): DesiredWatcher { function mapAuthProfile( profile: AuthProfile, - required: Set + required: Set, + env: NodeJS.ProcessEnv ): DesiredAuthProfile { if (!AUTH_PROFILE_SLUG_PATTERN.test(profile.slug)) { throw new ValidationError( @@ -484,7 +510,7 @@ function mapAuthProfile( ? Object.fromEntries( Object.entries(profile.credentials).map(([key, value]) => [ key, - credentialString(value, required), + resolveCredentialValue(value, required, env), ]) ) : undefined; @@ -566,7 +592,7 @@ export function mapProjectToDesiredState( const authProfiles = only ? [] : (project.authProfiles ?? []).map((profile) => - mapAuthProfile(profile, required) + mapAuthProfile(profile, required, env) ); const connections = only ? [] From 9d866be992e7f26b9d757fa64aa8fd5951d37523 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 01:17:13 +0100 Subject: [PATCH 18/65] feat(examples): author all 12 examples in lobu.config.ts (@lobu/sdk) Migrate every example from lobu.toml + models/*.yaml + connectors/*.yaml to a single TypeScript lobu.config.ts using the @lobu/sdk authoring API (define*). Each was verified to produce a DesiredState byte-identical to the legacy TOML loader (modulo object key order, installedAt timestamps, and the connector sourceFile error-label). Agent dirs, *.connector.ts, and *.reaction.ts files are unchanged (still file-based, referenced from the config). The old toml/yaml files remain for now; they are removed when the TOML loader is deleted in the next commit. --- examples/agent-community/lobu.config.ts | 183 +++ examples/atlas/lobu.config.ts | 238 ++++ examples/delivery/lobu.config.ts | 186 +++ examples/ecommerce/lobu.config.ts | 197 ++++ examples/finance/lobu.config.ts | 198 ++++ examples/leadership/lobu.config.ts | 216 ++++ examples/legal/lobu.config.ts | 207 ++++ examples/lobu-crm/lobu.config.ts | 395 +++++++ examples/market/lobu.config.ts | 617 ++++++++++ examples/office-bot/lobu.config.ts | 171 +++ examples/personal-finance/lobu.config.ts | 1308 ++++++++++++++++++++++ examples/sales/lobu.config.ts | 215 ++++ 12 files changed, 4131 insertions(+) create mode 100644 examples/agent-community/lobu.config.ts create mode 100644 examples/atlas/lobu.config.ts create mode 100644 examples/delivery/lobu.config.ts create mode 100644 examples/ecommerce/lobu.config.ts create mode 100644 examples/finance/lobu.config.ts create mode 100644 examples/leadership/lobu.config.ts create mode 100644 examples/legal/lobu.config.ts create mode 100644 examples/lobu-crm/lobu.config.ts create mode 100644 examples/market/lobu.config.ts create mode 100644 examples/office-bot/lobu.config.ts create mode 100644 examples/personal-finance/lobu.config.ts create mode 100644 examples/sales/lobu.config.ts diff --git a/examples/agent-community/lobu.config.ts b/examples/agent-community/lobu.config.ts new file mode 100644 index 000000000..68cfa18fa --- /dev/null +++ b/examples/agent-community/lobu.config.ts @@ -0,0 +1,183 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const agentCommunity = defineAgent({ + id: "agent-community", + name: "agent-community", + description: + "Discover aligned members, explain why they should meet, and draft warm introductions", + dir: "./agents/agent-community", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, +}); + +const match = defineEntityType({ + key: "match", + name: "Match", + description: + "A suggested introduction between two members with reasons and confidence", + properties: { + member_a: { + type: "string", + "x-table-label": "Member A", + "x-table-column": true, + }, + member_b: { + type: "string", + "x-table-label": "Member B", + "x-table-column": true, + }, + reason: { + type: "string", + "x-table-label": "Reason", + "x-table-column": true, + }, + status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + }, +}); + +const post = defineEntityType({ + key: "post", + name: "Post", + description: + "A blog post, newsletter, or public writing by a community member", + properties: { + title: { type: "string", "x-table-label": "Title", "x-table-column": true }, + source: { + type: "string", + "x-table-label": "Source", + "x-table-column": true, + }, + author: { + type: "string", + "x-table-label": "Author", + "x-table-column": true, + }, + topics: { + type: "string", + "x-table-label": "Topics", + "x-table-column": true, + }, + }, +}); + +const topic = defineEntityType({ + key: "topic", + name: "Topic", + description: + "A durable interest or subject area used for member matching and discovery", + properties: { + topic_name: { + type: "string", + "x-table-label": "Topic", + "x-table-column": true, + }, + evidence: { + type: "string", + "x-table-label": "Evidence", + "x-table-column": true, + }, + member_count: { + type: "string", + "x-table-label": "Members", + "x-table-column": true, + }, + relevance: { type: "string", "x-table-label": "Relevance" }, + }, +}); + +const interestedIn = defineRelationshipType({ + key: "interested-in", + name: "Interested In", + description: + "Store durable interests and goals that can be reused across matching and introductions.", +}); + +const introducedTo = defineRelationshipType({ + key: "introduced-to", + name: "Introduced To", + description: + "Track completed introductions so the system avoids duplicate outreach and preserves relationship history.", +}); + +const matchesWith = defineRelationshipType({ + key: "matches-with", + name: "Matches With", + description: + "Represent suggested introductions with reasons and confidence so outreach history is auditable.", +}); + +const writesAbout = defineRelationshipType({ + key: "writes-about", + name: "Writes About", + description: + "Capture blog posts, newsletters, and public writing so matching includes current thinking, not just static bios.", +}); + +const opportunityMatcher = defineWatcher({ + agent: agentCommunity, + slug: "opportunity-matcher", + name: "Opportunity matcher", + schedule: "0 */12 * * *", + notification: { priority: "normal" }, + tags: ["community", "matching"], + minCooldownSeconds: 300, + reaction: "./models/reactions/opportunity-matcher.reaction.ts", + prompt: + "Monitor connected profiles, newsletters, websites, and member updates for new launches, posts, hiring signals, funding news, and project changes. Identify which members are likely to care, explain why, and queue approved intro or outreach drafts.\n", + extractionSchema: { + type: "object", + required: ["signals"], + properties: { + signals: { + type: "array", + items: { + type: "object", + properties: { + type: { type: "string" }, + source: { type: "string" }, + related_topics: { type: "array", items: { type: "string" } }, + interested_members: { type: "array", items: { type: "string" } }, + reason: { type: "string" }, + suggested_action: { type: "string" }, + }, + }, + }, + }, + }, +}); + +export default defineConfig({ + org: "market", + orgName: "Agent Community", + orgDescription: + "Discover aligned members, explain why they should meet, and draft warm introductions", + agents: [agentCommunity], + entities: [match, post, topic], + relationships: [interestedIn, introducedTo, matchesWith, writesAbout], + watchers: [opportunityMatcher], +}); diff --git a/examples/atlas/lobu.config.ts b/examples/atlas/lobu.config.ts new file mode 100644 index 000000000..47a9d2dda --- /dev/null +++ b/examples/atlas/lobu.config.ts @@ -0,0 +1,238 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const atlasCurator = defineAgent({ + id: "atlas-curator", + name: "atlas-curator", + description: + "Curate Atlas reference data — countries, cities, regions, industries, technologies, universities", + dir: "./agents/atlas-curator", + providers: [ + { + id: "z-ai", + model: "z-ai/glm-4.7", + key: secret("Z_AI_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "api.z.ai", + ".z.ai", + ], + }, +}); + +const city = defineEntityType({ + key: "city", + name: "City", + description: "Populated place (city, town, metro area)", + properties: { + country_id: { + type: "integer", + description: "FK to atlas.country", + "x-table-column": true, + "x-table-label": "Country", + "x-link-entity-type": "country", + }, + region_id: { + type: "integer", + description: + "FK to atlas.region (optional — not every city is region-tagged)", + "x-table-column": true, + "x-table-label": "Region", + "x-link-entity-type": "region", + }, + latitude: { type: "number", description: "Decimal degrees, WGS84" }, + longitude: { type: "number", description: "Decimal degrees, WGS84" }, + population: { + type: "integer", + description: "City proper population (latest available estimate)", + }, + }, +}); + +const country = defineEntityType({ + key: "country", + name: "Country", + description: "Sovereign country (ISO 3166-1)", + properties: { + iso2: { + type: "string", + minLength: 2, + maxLength: 2, + "x-table-column": true, + "x-table-label": "ISO2", + }, + iso3: { + type: "string", + minLength: 3, + maxLength: 3, + "x-table-column": true, + "x-table-label": "ISO3", + }, + currency: { + type: "string", + description: "ISO 4217 currency code (e.g. USD, EUR, GBP)", + "x-table-column": true, + "x-table-label": "Currency", + }, + region: { + type: "string", + description: + "UN macro region (e.g. Europe, Africa, Asia, Americas, Oceania)", + "x-table-column": true, + "x-table-label": "Region", + }, + population: { + type: "integer", + description: "Approximate population (latest available estimate)", + }, + }, +}); + +const industry = defineEntityType({ + key: "industry", + name: "Industry", + description: "Industry / sector taxonomy node (NAICS, BICS, or custom)", + properties: { + parent_id: { + type: "integer", + description: "FK to parent atlas.industry (self-reference for hierarchy)", + "x-table-column": true, + "x-table-label": "Parent", + "x-link-entity-type": "industry", + }, + taxonomy_source: { + type: "string", + enum: ["NAICS", "BICS", "custom"], + "x-table-column": true, + "x-table-label": "Source", + }, + code: { + type: "string", + description: "Taxonomy code (e.g. NAICS 541512)", + "x-table-column": true, + "x-table-label": "Code", + }, + }, +}); + +const region = defineEntityType({ + key: "region", + name: "Region", + description: + "First-level administrative region (state, province, etc.) within a country", + properties: { + country_id: { + type: "integer", + description: "FK to atlas.country", + "x-table-column": true, + "x-table-label": "Country", + "x-link-entity-type": "country", + }, + iso_3166_2: { + type: "string", + description: "ISO 3166-2 code (e.g. US-CA, GB-LND)", + "x-table-column": true, + "x-table-label": "ISO 3166-2", + }, + }, +}); + +const technology = defineEntityType({ + key: "technology", + name: "Technology", + description: "Technology, framework, library, platform, or developer tool", + properties: { + category: { + type: "string", + description: + "Coarse category (e.g. database, frontend-framework, observability)", + "x-table-column": true, + "x-table-label": "Category", + }, + homepage_url: { + type: "string", + format: "uri", + "x-table-column": true, + "x-table-label": "Homepage", + }, + }, +}); + +const university = defineEntityType({ + key: "university", + name: "University", + description: "Higher-education institution", + properties: { + country_id: { + type: "integer", + description: "FK to atlas.country", + "x-table-column": true, + "x-table-label": "Country", + "x-link-entity-type": "country", + }, + city_id: { + type: "integer", + description: "FK to atlas.city (optional)", + "x-table-column": true, + "x-table-label": "City", + "x-link-entity-type": "city", + }, + founded_year: { + type: "integer", + "x-table-column": true, + "x-table-label": "Founded", + }, + homepage_url: { type: "string", format: "uri" }, + }, +}); + +const catalogStalenessChecker = defineWatcher({ + agent: atlasCurator, + slug: "catalog-staleness-checker", + name: "Catalog staleness checker", + schedule: "0 4 * * 1", + notification: { priority: "low" }, + tags: ["atlas", "reference", "weekly"], + minCooldownSeconds: 3600, + reaction: "./models/reactions/catalog-staleness-checker.reaction.ts", + prompt: + 'Sweep the atlas reference catalog for entries that haven\'t been\nupdated in 90+ days. List the stalest 10 across cities, countries,\nindustries, technologies, and universities. Suggest a re-verification\naction for each (e.g. "country/PL: confirm population from latest census").\n', + extractionSchema: { + type: "object", + required: ["stale_entries"], + properties: { + stale_entries: { + type: "array", + items: { + type: "object", + properties: { + entity_type: { type: "string" }, + slug: { type: "string" }, + last_updated: { type: "string" }, + suggested_action: { type: "string" }, + }, + }, + }, + total_stale_count: { type: "integer" }, + }, + }, +}); + +export default defineConfig({ + org: "atlas", + orgName: "Atlas", + orgDescription: "Public reference catalog — places, taxonomies, institutions", + agents: [atlasCurator], + entities: [city, country, industry, region, technology, university], + watchers: [catalogStalenessChecker], +}); diff --git a/examples/delivery/lobu.config.ts b/examples/delivery/lobu.config.ts new file mode 100644 index 000000000..8a9e488c5 --- /dev/null +++ b/examples/delivery/lobu.config.ts @@ -0,0 +1,186 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const delivery = defineAgent({ + id: "delivery", + name: "delivery", + description: + "Help delivery teams keep milestones, blockers, owners, and artifacts aligned", + dir: "./agents/delivery", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, +}); + +const blocker = defineEntityType({ + key: "blocker", + name: "Blocker", + description: "A dependency or issue that is blocking project progress", + properties: { + blocker_description: { + type: "string", + "x-table-label": "Blocker", + "x-table-column": true, + }, + owned_by: { + type: "string", + "x-table-label": "Owner", + "x-table-column": true, + }, + impact: { + type: "string", + "x-table-label": "Impact", + "x-table-column": true, + }, + status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + }, +}); + +const document = defineEntityType({ + key: "document", + name: "Document", + description: "A project artifact, review, or reference document", + properties: { + document_name: { + type: "string", + "x-table-label": "Document", + "x-table-column": true, + }, + document_type: { + type: "string", + "x-table-label": "Type", + "x-table-column": true, + }, + linked_project: { + type: "string", + "x-table-label": "Project", + "x-table-column": true, + }, + last_updated: { + type: "string", + "x-table-label": "Updated", + "x-table-column": true, + }, + }, +}); + +const milestone = defineEntityType({ + key: "milestone", + name: "Milestone", + description: "A key deliverable or phase gate within a project", + properties: { + milestone_name: { + type: "string", + "x-table-label": "Milestone", + "x-table-column": true, + }, + lifecycle_state: { + type: "string", + "x-table-label": "State", + "x-table-column": true, + }, + target_date: { + type: "string", + "x-table-label": "Target Date", + "x-table-column": true, + }, + parent_project: { + type: "string", + "x-table-label": "Project", + "x-table-column": true, + }, + }, +}); + +const stakeholder = defineEntityType({ + key: "stakeholder", + name: "Stakeholder", + description: "A person who owns or is responsible for part of a project", + properties: { + name: { type: "string", "x-table-label": "Name", "x-table-column": true }, + role: { type: "string", "x-table-label": "Role", "x-table-column": true }, + owns: { type: "string", "x-table-label": "Owns", "x-table-column": true }, + contact: { type: "string", "x-table-label": "Contact" }, + }, +}); + +const blockedBy = defineRelationshipType({ + key: "blocked-by", + name: "Blocked By", + description: + "Tie blockers directly to the project and milestone they threaten.", +}); + +const documentedIn = defineRelationshipType({ + key: "documented-in", + name: "Documented In", + description: + "Preserve the source documents and reviews behind key project state.", +}); + +const ownedBy = defineRelationshipType({ + key: "owned-by", + name: "Owned By", + description: "Keep project ownership queryable across updates and artifacts.", +}); + +const phoenixRolloutTracker = defineWatcher({ + agent: delivery, + slug: "phoenix-rollout-tracker", + name: "Phoenix rollout tracker", + schedule: "0 9 * * 1", + notification: { priority: "high", channel: "both" }, + tags: ["delivery", "weekly", "rollout"], + minCooldownSeconds: 3600, + prompt: + "Check project blockers, milestone progress, and generate the weekly risk summary for leadership.\n", + extractionSchema: { + type: "object", + required: [ + "blockers_resolved", + "milestone_state", + "new_risks", + "risk_summary", + ], + properties: { + blockers_resolved: { type: "array", items: { type: "string" } }, + milestone_state: { type: "string" }, + new_risks: { type: "array", items: { type: "string" } }, + risk_summary: { type: "string" }, + }, + }, +}); + +export default defineConfig({ + org: "delivery", + orgName: "Delivery", + orgDescription: + "Help delivery teams keep milestones, blockers, owners, and artifacts aligned", + agents: [delivery], + entities: [blocker, document, milestone, stakeholder], + relationships: [blockedBy, documentedIn, ownedBy], + watchers: [phoenixRolloutTracker], +}); diff --git a/examples/ecommerce/lobu.config.ts b/examples/ecommerce/lobu.config.ts new file mode 100644 index 000000000..114470922 --- /dev/null +++ b/examples/ecommerce/lobu.config.ts @@ -0,0 +1,197 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const ecommerceOps = defineAgent({ + id: "ecommerce-ops", + name: "ecommerce-ops", + description: + "Manage subscriptions, process order changes, and resolve customer requests", + dir: "./agents/ecommerce-ops", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, +}); + +const customer = defineEntityType({ + key: "customer", + name: "Customer", + description: + "A customer with subscriptions, orders, and communication preferences", + properties: { + full_name: { + type: "string", + "x-table-label": "Name", + "x-table-column": true, + }, + status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + plan: { type: "string", "x-table-label": "Plan", "x-table-column": true }, + communication_preference: { + type: "string", + "x-table-label": "Preference", + "x-table-column": true, + }, + }, +}); + +const order = defineEntityType({ + key: "order", + name: "Order", + description: "A customer order with fulfillment status and delivery details", + properties: { + order_number: { + type: "string", + "x-table-label": "Order", + "x-table-column": true, + }, + product: { + type: "string", + "x-table-label": "Product", + "x-table-column": true, + }, + fulfillment_status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + customer: { + type: "string", + "x-table-label": "Customer", + "x-table-column": true, + }, + }, +}); + +const product = defineEntityType({ + key: "product", + name: "Product", + description: "A product in the catalog linked to subscriptions and orders", + properties: { + product_name: { + type: "string", + "x-table-label": "Product", + "x-table-column": true, + }, + plan_tier: { + type: "string", + "x-table-label": "Tier", + "x-table-column": true, + }, + delivery_frequency: { + type: "string", + "x-table-label": "Delivery", + "x-table-column": true, + }, + price: { type: "string", "x-table-label": "Price", "x-table-column": true }, + }, +}); + +const subscription = defineEntityType({ + key: "subscription", + name: "Subscription", + description: + "A recurring subscription plan with billing cycle and pending changes", + properties: { + plan_name: { + type: "string", + "x-table-label": "Plan", + "x-table-column": true, + }, + frequency: { + type: "string", + "x-table-label": "Frequency", + "x-table-column": true, + }, + status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + pending_changes: { + type: "string", + "x-table-label": "Pending", + "x-table-column": true, + }, + }, +}); + +const hasPreference = defineRelationshipType({ + key: "has-preference", + name: "Has Preference", + description: + "Persist communication and delivery preferences across interactions.", +}); + +const placedOrder = defineRelationshipType({ + key: "placed-order", + name: "Placed Order", + description: "Link orders to customers so purchase history stays queryable.", +}); + +const subscribedTo = defineRelationshipType({ + key: "subscribed-to", + name: "Subscribed To", + description: "Track which plans and products each customer subscribes to.", +}); + +const customerActivityTracker = defineWatcher({ + agent: ecommerceOps, + slug: "customer-activity-tracker", + name: "Customer activity tracker", + schedule: "0 */6 * * *", + notification: { priority: "normal" }, + tags: ["ecommerce", "customer-ops"], + minCooldownSeconds: 300, + prompt: + "Monitor customers for new orders, subscription changes, delivery requests, and support interactions.\n", + extractionSchema: { + type: "object", + required: [ + "subscription_status", + "pending_changes", + "recent_orders", + "communication_preferences", + "open_requests", + ], + properties: { + subscription_status: { type: "string" }, + pending_changes: { type: "array", items: { type: "string" } }, + recent_orders: { type: "array", items: { type: "string" } }, + communication_preferences: { type: "string" }, + open_requests: { type: "array", items: { type: "string" } }, + }, + }, +}); + +export default defineConfig({ + org: "ecommerce", + orgName: "Ecommerce", + orgDescription: + "Manage subscriptions, process order changes, and resolve customer requests", + agents: [ecommerceOps], + entities: [customer, order, product, subscription], + relationships: [hasPreference, placedOrder, subscribedTo], + watchers: [customerActivityTracker], +}); diff --git a/examples/finance/lobu.config.ts b/examples/finance/lobu.config.ts new file mode 100644 index 000000000..1d026ff6c --- /dev/null +++ b/examples/finance/lobu.config.ts @@ -0,0 +1,198 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const finance = defineAgent({ + id: "finance", + name: "finance", + description: + "Help finance teams reconcile data, explain variance, and prepare reporting runs", + dir: "./agents/finance", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, +}); + +const account = defineEntityType({ + key: "account", + name: "Account", + description: + "A financial account that holds balances, transactions, and reconciliation state", + properties: { + account_name: { + type: "string", + "x-table-label": "Account", + "x-table-column": true, + }, + account_type: { + type: "string", + "x-table-label": "Type", + "x-table-column": true, + }, + balance: { + type: "string", + "x-table-label": "Balance", + "x-table-column": true, + }, + reconciliation_status: { + type: "string", + "x-table-label": "Reconciliation", + "x-table-column": true, + }, + }, +}); + +const report = defineEntityType({ + key: "report", + name: "Report", + description: + "A financial report or summary generated from account and transaction data", + properties: { + report_name: { + type: "string", + "x-table-label": "Report", + "x-table-column": true, + }, + period: { + type: "string", + "x-table-label": "Period", + "x-table-column": true, + }, + status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + exceptions_count: { + type: "string", + "x-table-label": "Exceptions", + "x-table-column": true, + }, + }, +}); + +const transaction = defineEntityType({ + key: "transaction", + name: "Transaction", + description: "A financial transaction that affects account balances", + properties: { + description: { + type: "string", + "x-table-label": "Description", + "x-table-column": true, + }, + amount: { + type: "string", + "x-table-label": "Amount", + "x-table-column": true, + }, + date: { type: "string", "x-table-label": "Date", "x-table-column": true }, + category: { + type: "string", + "x-table-label": "Category", + "x-table-column": true, + }, + }, +}); + +const variance = defineEntityType({ + key: "variance", + name: "Variance", + description: + "A discrepancy or anomaly identified during reconciliation or reporting", + properties: { + variance_type: { + type: "string", + "x-table-label": "Type", + "x-table-column": true, + }, + amount: { + type: "string", + "x-table-label": "Amount", + "x-table-column": true, + }, + source_account: { + type: "string", + "x-table-label": "Account", + "x-table-column": true, + }, + explanation: { + type: "string", + "x-table-label": "Explanation", + "x-table-column": true, + }, + }, +}); + +const createsVariance = defineRelationshipType({ + key: "creates-variance", + name: "Creates Variance", + description: + "Keep anomalies attached to the source records that produced them.", +}); + +const reconcilesTo = defineRelationshipType({ + key: "reconciles-to", + name: "Reconciles To", + description: + "Tie transactions and balances back to the accounts they roll into.", +}); + +const summarizedIn = defineRelationshipType({ + key: "summarized-in", + name: "Summarized In", + description: + "Let agents trace reporting outputs back to the supporting data.", +}); + +const reconciliationMonitor = defineWatcher({ + agent: finance, + slug: "reconciliation-monitor", + name: "Reconciliation monitor", + schedule: "0 6 * * 1-5", + notification: { priority: "high", channel: "both" }, + tags: ["finance", "reconciliation", "daily"], + minCooldownSeconds: 3600, + reaction: "./models/reactions/reconciliation-monitor.reaction.ts", + prompt: + "Check accounts for unreconciled transactions, new variances, and approaching reporting deadlines. Lead with exceptions that need review.\n", + extractionSchema: { + type: "object", + required: ["unreconciled_count", "new_variances", "approaching_deadlines"], + properties: { + unreconciled_count: { type: "integer" }, + new_variances: { type: "array", items: { type: "string" } }, + approaching_deadlines: { type: "array", items: { type: "string" } }, + payment_risks: { type: "array", items: { type: "string" } }, + }, + }, +}); + +export default defineConfig({ + org: "finance", + orgName: "Finance", + orgDescription: + "Help finance teams reconcile data, explain variance, and prepare reporting runs", + agents: [finance], + entities: [account, report, transaction, variance], + relationships: [createsVariance, reconcilesTo, summarizedIn], + watchers: [reconciliationMonitor], +}); diff --git a/examples/leadership/lobu.config.ts b/examples/leadership/lobu.config.ts new file mode 100644 index 000000000..ff026b65b --- /dev/null +++ b/examples/leadership/lobu.config.ts @@ -0,0 +1,216 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const leadership = defineAgent({ + id: "leadership", + name: "leadership", + description: + "Help leadership teams turn memos, decisions, and board materials into reusable operating context", + dir: "./agents/leadership", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, +}); + +const decision = defineEntityType({ + key: "decision", + name: "Decision", + description: + "A leadership decision extracted from a document with its approval status", + properties: { + subject: { + type: "string", + "x-table-label": "Subject", + "x-table-column": true, + }, + status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + source_document: { + type: "string", + "x-table-label": "Source", + "x-table-column": true, + }, + decision_date: { + type: "string", + "x-table-label": "Date", + "x-table-column": true, + }, + }, +}); + +const document = defineEntityType({ + key: "document", + name: "Document", + description: + "A source document such as a board memo, strategy brief, or executive report", + properties: { + document_name: { + type: "string", + "x-table-label": "Document", + "x-table-column": true, + }, + document_type: { + type: "string", + "x-table-label": "Type", + "x-table-column": true, + }, + date: { type: "string", "x-table-label": "Date", "x-table-column": true }, + decisions_count: { + type: "string", + "x-table-label": "Decisions", + "x-table-column": true, + }, + }, +}); + +const region = defineEntityType({ + key: "region", + name: "Region", + description: + "A geographic region referenced in strategic decisions or expansion plans", + properties: { + region_name: { + type: "string", + "x-table-label": "Region", + "x-table-column": true, + }, + decision_context: { + type: "string", + "x-table-label": "Context", + "x-table-column": true, + }, + status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + budget_approved: { type: "string", "x-table-label": "Budget" }, + }, +}); + +const risk = defineEntityType({ + key: "risk", + name: "Risk", + description: + "A blocker or dependency that is holding up a decision or initiative", + properties: { + blocker: { + type: "string", + "x-table-label": "Blocker", + "x-table-column": true, + }, + affects: { + type: "string", + "x-table-label": "Affects", + "x-table-column": true, + }, + state: { type: "string", "x-table-label": "State", "x-table-column": true }, + owner: { type: "string", "x-table-label": "Owner", "x-table-column": true }, + }, +}); + +const task = defineEntityType({ + key: "task", + name: "Task", + description: + "An assigned follow-up action extracted from a leadership document or meeting", + properties: { + action: { + type: "string", + "x-table-label": "Action", + "x-table-column": true, + }, + owner: { type: "string", "x-table-label": "Owner", "x-table-column": true }, + deadline: { + type: "string", + "x-table-label": "Deadline", + "x-table-column": true, + }, + source: { + type: "string", + "x-table-label": "Source", + "x-table-column": true, + }, + }, +}); + +const approved = defineRelationshipType({ + key: "approved", + name: "Approved", + description: + "Keep approved decisions queryable without re-reading the whole source memo.", +}); + +const assigned = defineRelationshipType({ + key: "assigned", + name: "Assigned", + description: + "Turn follow-up work into durable ownership instead of transient notes.", +}); + +const blockedBy = defineRelationshipType({ + key: "blocked-by", + name: "Blocked By", + description: + "Attach blocked decisions to the dependency that is holding them up.", +}); + +const boardActionTracker = defineWatcher({ + agent: leadership, + slug: "board-action-tracker", + name: "Board action tracker", + schedule: "0 8 * * *", + notification: { priority: "high", channel: "both" }, + tags: ["leadership", "daily", "board"], + agentKind: "notifier", + prompt: + "Track board action items: check task delivery status, blocker resolution progress, and approaching deadlines for the next board packet.\n", + extractionSchema: { + type: "object", + required: [ + "action_items", + "blocked_items", + "deadlines_approaching", + "completion_status", + ], + properties: { + action_items: { type: "array", items: { type: "string" } }, + blocked_items: { type: "array", items: { type: "string" } }, + deadlines_approaching: { type: "array", items: { type: "string" } }, + completion_status: { type: "string" }, + }, + }, +}); + +export default defineConfig({ + org: "leadership", + orgName: "Leadership", + orgDescription: + "Turn memos, decisions, and board materials into reusable operating context", + agents: [leadership], + entities: [decision, document, region, risk, task], + relationships: [approved, assigned, blockedBy], + watchers: [boardActionTracker], +}); diff --git a/examples/legal/lobu.config.ts b/examples/legal/lobu.config.ts new file mode 100644 index 000000000..0733f17b1 --- /dev/null +++ b/examples/legal/lobu.config.ts @@ -0,0 +1,207 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const legalReview = defineAgent({ + id: "legal-review", + name: "legal-review", + description: + "Review contracts, summarize risk, and surface missing protections", + dir: "./agents/legal", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, +}); + +const clause = defineEntityType({ + key: "clause", + name: "Clause", + description: + "A specific provision or section within a contract that defines terms or obligations", + properties: { + clause_type: { + type: "string", + "x-table-label": "Type", + "x-table-column": true, + }, + section: { + type: "string", + "x-table-label": "Section", + "x-table-column": true, + }, + risk_level: { + type: "string", + "x-table-label": "Risk Level", + "x-table-column": true, + }, + language_summary: { + type: "string", + "x-table-label": "Summary", + "x-table-column": true, + }, + }, +}); + +const contract = defineEntityType({ + key: "contract", + name: "Contract", + description: + "A legal agreement between parties with defined terms, obligations, and conditions", + properties: { + contract_type: { + type: "string", + "x-table-label": "Type", + "x-table-column": true, + }, + status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + effective_date: { + type: "string", + "x-table-label": "Effective Date", + "x-table-column": true, + }, + counterparty_name: { + type: "string", + "x-table-label": "Counterparty", + "x-table-column": true, + }, + governing_law: { type: "string", "x-table-label": "Governing Law" }, + }, +}); + +const counterparty = defineEntityType({ + key: "counterparty", + name: "Counterparty", + description: "An external party involved in a contract or legal agreement", + properties: { + organization_name: { + type: "string", + "x-table-label": "Organization", + "x-table-column": true, + }, + jurisdiction: { + type: "string", + "x-table-label": "Jurisdiction", + "x-table-column": true, + }, + contact_person: { + type: "string", + "x-table-label": "Contact", + "x-table-column": true, + }, + relationship_status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + }, +}); + +const risk = defineEntityType({ + key: "risk", + name: "Risk", + description: + "A legal risk identified in a contract or clause that requires attention or mitigation", + properties: { + severity: { + type: "string", + "x-table-label": "Severity", + "x-table-column": true, + }, + category: { + type: "string", + "x-table-label": "Category", + "x-table-column": true, + }, + mitigation: { + type: "string", + "x-table-label": "Mitigation", + "x-table-column": true, + }, + source_clause: { + type: "string", + "x-table-label": "Source Clause", + "x-table-column": true, + }, + }, +}); + +const belongsToCounterparty = defineRelationshipType({ + key: "belongs-to-counterparty", + name: "Belongs to Counterparty", + description: + "Tie agreements and negotiation context back to the right external party.", +}); + +const containsClause = defineRelationshipType({ + key: "contains-clause", + name: "Contains Clause", + description: + "Represent how a contract is composed so risky language stays attached to the right section.", +}); + +const createsRisk = defineRelationshipType({ + key: "creates-risk", + name: "Creates Risk", + description: "Keep legal risk linked to the clause or term that caused it.", +}); + +const contractReviewTracker = defineWatcher({ + agent: legalReview, + slug: "contract-review-tracker", + name: "Contract review tracker", + schedule: "0 8 * * 1-5", + notification: { priority: "high" }, + tags: ["legal", "contract", "daily"], + minCooldownSeconds: 1800, + reactionsGuidance: + "For any contract with `status: needs_counsel`, route an entity-scoped event\nto the assigned reviewer. For contracts >90 days unsigned, escalate to the\ncounterparty owner; never auto-resolve risk items.\n", + prompt: + "Review active contracts for approaching deadlines, unsigned agreements, and unresolved risk items. Flag any clauses that still need counsel approval.\n", + extractionSchema: { + type: "object", + required: [ + "pending_contracts", + "unresolved_risks", + "approaching_deadlines", + ], + properties: { + pending_contracts: { type: "array", items: { type: "string" } }, + unresolved_risks: { type: "array", items: { type: "string" } }, + approaching_deadlines: { type: "array", items: { type: "string" } }, + flagged_clauses: { type: "array", items: { type: "string" } }, + }, + }, +}); + +export default defineConfig({ + org: "legal-review", + orgName: "Legal", + orgDescription: + "Review contracts, summarize risk, and surface missing protections", + agents: [legalReview], + entities: [clause, contract, counterparty, risk], + relationships: [belongsToCounterparty, containsClause, createsRisk], + watchers: [contractReviewTracker], +}); diff --git a/examples/lobu-crm/lobu.config.ts b/examples/lobu-crm/lobu.config.ts new file mode 100644 index 000000000..90ae49c73 --- /dev/null +++ b/examples/lobu-crm/lobu.config.ts @@ -0,0 +1,395 @@ +import { + defineAgent, + defineAuthProfile, + defineConfig, + defineConnection, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const crm = defineAgent({ + id: "crm", + name: "crm", + description: + "Maintains Lobu's funnel CRM — leads, pilots, inbound triage, weekly digest", + providers: [ + { + id: "z-ai", + model: "z-ai/glm-4.7", + key: secret("Z_AI_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + "api.github.com", + ".githubusercontent.com", + "x.com", + "api.x.com", + "twitter.com", + "news.ycombinator.com", + "hn.algolia.com", + "api.producthunt.com", + "api.z.ai", + ".z.ai", + "lobu.ai", + ".dust.tt", + ".glean.com", + ], + }, +}); + +const lead = defineEntityType({ + key: "lead", + name: "Lead", + description: + "A person who has shown a signal toward Lobu — starred, engaged, asked, or talked to us", + required: ["name", "source", "stage"], + properties: { + name: { type: "string", "x-table-label": "Name", "x-table-column": true }, + company: { + type: "string", + "x-table-label": "Company", + "x-table-column": true, + }, + stage: { + type: "string", + enum: ["signal", "trial", "conversation", "pilot", "customer", "cold"], + "x-table-label": "Stage", + "x-table-column": true, + }, + source: { + type: "string", + description: + 'Where they first showed up — "github:stargazer", "x:mention", "github:issue-comment", "demo-form", "intro", etc.', + "x-table-label": "Source", + "x-table-column": true, + }, + github_handle: { + type: "string", + "x-table-label": "GitHub", + "x-table-column": true, + }, + x_handle: { type: "string", "x-table-label": "X" }, + email: { type: "string", "x-table-label": "Email" }, + last_touch: { + type: "string", + description: "ISO date of the most recent interaction", + "x-table-label": "Last touch", + "x-table-column": true, + }, + next_action: { + type: "string", + "x-table-label": "Next action", + "x-table-column": true, + }, + notes: { type: "string" }, + }, +}); + +const pilot = defineEntityType({ + key: "pilot", + name: "Pilot", + description: + "A paid pilot — a company running Lobu for their team under a time-boxed agreement", + required: ["company", "status"], + properties: { + company: { + type: "string", + "x-table-label": "Company", + "x-table-column": true, + }, + status: { + type: "string", + enum: ["active", "won", "lost", "paused"], + "x-table-label": "Status", + "x-table-column": true, + }, + seats: { + type: "integer", + "x-table-label": "Seats", + "x-table-column": true, + }, + mrr: { + type: "string", + description: 'Monthly recurring revenue for the pilot, e.g. "$750"', + "x-table-label": "MRR", + "x-table-column": true, + }, + start_date: { + type: "string", + "x-table-label": "Start", + "x-table-column": true, + }, + success_metric: { + type: "string", + description: "The one metric agreed up front that defines pilot success", + "x-table-label": "Success metric", + "x-table-column": true, + }, + lead_id: { + type: "string", + description: "The lead entity this pilot converted from", + }, + }, +}); + +const converted_to = defineRelationshipType({ + key: "converted-to", + name: "Converted To", + description: + "Links a lead to the pilot it became, so the path from first signal to paying pilot stays explicit.", +}); + +const funnel_digestWatcher = defineWatcher({ + agent: crm, + slug: "funnel-digest", + name: "Weekly funnel digest", + schedule: "0 9 * * 1", + notification: { channel: "both", priority: "high" }, + minCooldownSeconds: 3600, + tags: ["crm", "weekly"], + reaction: "./models/reactions/funnel-digest.reaction.ts", + prompt: + 'Produce the weekly funnel digest and post it to Slack. Keep it short.\n\n1. The single recommended action for the week, on the first line. Pick the\n move that does the most to get pilot #1 closer (almost always: follow up\n with the warmest lead in "conversation", or progress whichever pilot\n conversation is furthest along).\n2. Funnel snapshot: count of `lead` entities per stage; what moved since the\n last digest (new leads, stage changes, new/updated `pilot` entities).\n3. Top-of-funnel since last digest: new GitHub stars, X mentions/replies,\n HN/PH activity.\n4. Stale: any lead in `conversation` with no `lead:interaction` in 7+ days —\n list them for follow-up.\n5. One gap callout if there is one (e.g. "18 new stars, 0 became leads —\n is inbound-triage catching the right signal?").\n\nTone: a checklist a busy founder reads in 30 seconds. End on the next action,\nnot the status. Remember: the metric that matters is customer conversations\nthis week — if that number is below 3, say so plainly.\n', + extractionSchema: { + type: "object", + required: [ + "top_action", + "stage_counts", + "moved", + "top_of_funnel", + "stale_leads", + ], + properties: { + top_action: { type: "string" }, + stage_counts: { type: "object" }, + moved: { + type: "object", + properties: { + new_leads: { type: "integer" }, + stage_changes: { type: "integer" }, + pilot_updates: { type: "integer" }, + }, + }, + top_of_funnel: { + type: "object", + properties: { + stars: { type: "integer" }, + x_mentions: { type: "integer" }, + hn_ph_activity: { type: "integer" }, + }, + }, + stale_leads: { type: "array", items: { type: "string" } }, + gap: { type: "string" }, + conversations_this_week: { type: "integer" }, + }, + }, +}); + +const inbound_triageWatcher = defineWatcher({ + agent: crm, + slug: "inbound-triage", + name: "Inbound triage", + schedule: "0 8-22/2 * * *", + notification: { priority: "normal" }, + minCooldownSeconds: 300, + tags: ["crm", "triage"], + reaction: "./models/reactions/inbound-triage.reaction.ts", + prompt: + 'Look for new top-of-funnel signals since the last run, across the connectors\nin this org:\n - GitHub: new stargazers on lobu-ai/lobu; new issues / issue comments /\n PR comments — especially anything with deployment, self-host, multi-tenant,\n "how do I", or evaluation language.\n - X: new @-mentions of Lobu, replies to Burak\'s Lobu threads, quote-tweets.\n - Hacker News / Product Hunt: new comments or posts mentioning Lobu or OpenClaw.\n\nFor each signal that looks like a real person (not a bot, not a casual star):\n 1. search_memory for an existing `lead` (match github handle / x handle / email).\n 2. If none, create a `lead` entity at the lowest stage the evidence supports\n (a bare star → "signal"; a deployment-flavored issue comment or a\n "how do I deploy this for my team" mention → "trial" or "conversation"),\n with source set to where it came from, and entity_ids linking to the\n source event. Then save a `lead:created` event.\n 3. If a lead exists, enrich it (add the handle, bump the stage if the new\n signal warrants it, update last_touch) and save a `lead:interaction` or\n `lead:stage_changed` event as appropriate.\n\nThen post to Slack: the new/updated leads, ranked by closeness-to-a-paying-pilot,\neach with a one-line recommended next action (e.g. "reply on the issue and offer\na 20-min call"). If nothing notable, post nothing — don\'t manufacture noise.\n', + extractionSchema: { + type: "object", + required: ["new_leads", "enriched_leads", "recommended_actions"], + properties: { + new_leads: { + type: "array", + items: { + type: "object", + properties: { + name: { type: "string" }, + handle: { type: "string" }, + source: { type: "string" }, + stage: { type: "string" }, + why: { type: "string" }, + }, + }, + }, + enriched_leads: { + type: "array", + items: { + type: "object", + properties: { name: { type: "string" }, change: { type: "string" } }, + }, + }, + recommended_actions: { type: "array", items: { type: "string" } }, + notable: { type: "boolean" }, + }, + }, +}); + +const github_accountAuth = defineAuthProfile({ + slug: "github-account", + connector: "github", + authKind: "oauth_account", + name: "GitHub — lobu-ai", +}); + +const github_appAuth = defineAuthProfile({ + slug: "github-app", + connector: "github", + authKind: "oauth_app", + name: "GitHub OAuth App", + credentials: { + GITHUB_CLIENT_ID: secret("GITHUB_CLIENT_ID"), + GITHUB_CLIENT_SECRET: secret("GITHUB_CLIENT_SECRET"), + }, +}); + +const x_accountAuth = defineAuthProfile({ + slug: "x-account", + connector: "x", + authKind: "oauth_account", + name: "X — @lobu", +}); + +const competitor_changelogsConn = defineConnection({ + slug: "competitor-changelogs", + connector: "website", + name: "Competitor changelogs", + config: { + urls: [ + "https://lobu.ai/changelog", + "https://docs.dust.tt/changelog", + "https://www.glean.com/release-notes", + ], + max_pages: 10, + }, + feeds: [ + { + feed: "pages", + name: "Changelog pages", + schedule: "0 7 * * *", + config: { + urls: [ + "https://lobu.ai/changelog", + "https://docs.dust.tt/changelog", + "https://www.glean.com/release-notes", + ], + max_pages: 10, + parse_sections: false, + }, + }, + ], +}); + +const funnel_form_submissionsConn = defineConnection({ + slug: "funnel-form-submissions", + connector: "funnel-form", + name: "Demo-request form submissions", + config: { endpoint: "https://lobu.ai/api/demo-requests" }, + feeds: [ + { + feed: "submissions", + name: "Form submissions", + schedule: "*/15 * * * *", + config: { endpoint: "https://lobu.ai/api/demo-requests" }, + }, + ], +}); + +const github_lobuConn = defineConnection({ + slug: "github-lobu", + connector: "github", + name: "GitHub — lobu-ai/lobu", + authProfile: github_accountAuth, + appAuthProfile: github_appAuth, + config: { repo_owner: "lobu-ai", repo_name: "lobu" }, + feeds: [ + { + feed: "stargazers", + name: "Stars — lobu-ai/lobu", + schedule: "0 */6 * * *", + config: { repo_owner: "lobu-ai", repo_name: "lobu" }, + }, + { + feed: "issues", + name: "Issues — lobu-ai/lobu", + schedule: "15 */6 * * *", + config: { repo_owner: "lobu-ai", repo_name: "lobu", lookback_days: 90 }, + }, + { + feed: "issue_comments", + name: "Issue comments — lobu-ai/lobu", + schedule: "30 */6 * * *", + config: { repo_owner: "lobu-ai", repo_name: "lobu", lookback_days: 90 }, + }, + { + feed: "pr_comments", + name: "PR comments — lobu-ai/lobu", + schedule: "45 */6 * * *", + config: { repo_owner: "lobu-ai", repo_name: "lobu", lookback_days: 90 }, + }, + ], +}); + +const hn_lobuConn = defineConnection({ + slug: "hn-lobu", + connector: "hackernews", + name: "Hacker News — lobu", + config: { search_query: "lobu", lookback_days: 180 }, + feeds: [ + { + feed: "stories", + name: "HN stories — lobu", + schedule: "0 */4 * * *", + config: { search_query: "lobu", lookback_days: 180 }, + }, + ], +}); + +const x_mentionsConn = defineConnection({ + slug: "x-mentions", + connector: "x", + name: "X — @lobu mentions & replies", + authProfile: x_accountAuth, + config: { + search_query: "@lobu OR lobu.ai", + search_filter: "live", + max_scrolls: 10, + }, + feeds: [ + { + feed: "tweets", + name: "X mentions — @lobu", + schedule: "0 */3 * * *", + config: { + search_query: "@lobu OR lobu.ai", + search_filter: "live", + max_scrolls: 10, + }, + }, + ], +}); + +export default defineConfig({ + org: "lobu-crm", + orgName: "Lobu CRM", + orgDescription: + "Funnel CRM for Lobu — leads, pilots, conversations, launch signals", + agents: [crm], + entities: [lead, pilot], + relationships: [converted_to], + connections: [ + competitor_changelogsConn, + funnel_form_submissionsConn, + github_lobuConn, + hn_lobuConn, + x_mentionsConn, + ], + authProfiles: [github_accountAuth, github_appAuth, x_accountAuth], + watchers: [funnel_digestWatcher, inbound_triageWatcher], +}); diff --git a/examples/market/lobu.config.ts b/examples/market/lobu.config.ts new file mode 100644 index 000000000..9a6603145 --- /dev/null +++ b/examples/market/lobu.config.ts @@ -0,0 +1,617 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const SECTOR_ENUM = ["bio-health", "ai", "fintech", "crypto", "consumer"]; + +const vcTracking = defineAgent({ + id: "vc-tracking", + name: "vc-tracking", + description: + "Track companies, founders, and investment opportunities for venture firms", + dir: "./agents/vc-tracking", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, +}); + +const company = defineEntityType({ + key: "company", + name: "Company", + description: "Portfolio company or deal pipeline company", + properties: { + market: { + type: "string", + "x-table-column": true, + "x-table-label": "Market", + }, + sector: { + type: "string", + enum: SECTOR_ENUM, + "x-table-column": true, + "x-table-label": "Sector", + }, + category: { + type: "string", + enum: ["portfolio", "recruiter", "prospect"], + "x-table-column": true, + "x-table-label": "Category", + }, + location: { + type: "string", + "x-table-column": true, + "x-table-label": "Location", + }, + domain: { + type: "string", + description: + "Normalized company domain used by identity-engine hosted_domain facts", + "x-identity-namespace": { + namespace: "hosted_domain", + normalize: "lowercase", + }, + "x-table-column": true, + "x-table-label": "Domain", + }, + one_liner: { type: "string" }, + team_size: { type: "integer" }, + founding_year: { type: "integer" }, + funding_raised: { type: "string" }, + valuation: { type: "string" }, + revenue: { type: "string" }, + growth_rate: { type: "string" }, + traction_score: { type: "number" }, + thesis: { type: "string" }, + stage: { + type: "string", + enum: [ + "idea", + "pre-seed", + "seed", + "series-a", + "series-b", + "series-c", + "growth", + "public", + ], + }, + linkedin_url: { type: "string", format: "uri" }, + logo_url: { type: "string", format: "uri", description: "Brand logo URL" }, + tagline: { type: "string", description: "One-line brand tagline" }, + brand_voice: { + type: "string", + description: "Brand voice / tone-of-voice notes", + }, + social_handles: { + type: "object", + description: + "Brand social handles by platform (twitter, linkedin, github, …)", + properties: { + twitter: { type: "string" }, + linkedin: { type: "string" }, + github: { type: "string" }, + youtube: { type: "string" }, + instagram: { type: "string" }, + tiktok: { type: "string" }, + }, + additionalProperties: { type: "string" }, + }, + }, +}); + +const founder = defineEntityType({ + key: "founder", + name: "Founder", + description: "Company founder or co-founder", + properties: { + role: { type: "string", "x-table-column": true, "x-table-label": "Role" }, + sector: { + type: "string", + enum: SECTOR_ENUM, + "x-table-column": true, + "x-table-label": "Sector", + }, + location: { + type: "string", + "x-table-column": true, + "x-table-label": "Location", + }, + specialties: { + type: "array", + items: { type: "string" }, + "x-table-column": true, + "x-table-label": "Specialties", + }, + background: { type: "string" }, + linkedin_url: { type: "string", format: "uri" }, + twitter_handle: { type: "string" }, + education: { type: "string" }, + career_history: { + type: "array", + items: { + type: "object", + properties: { + title: { type: "string" }, + company: { type: "string" }, + start: { type: "string" }, + end: { type: "string" }, + }, + }, + }, + notable_exits: { type: "array", items: { type: "string" } }, + provenance: { + type: "string", + enum: ["inbound", "outbound", "referral", "event", "portfolio"], + }, + }, +}); + +const fundRound = defineEntityType({ + key: "fund-round", + name: "Fund Round", + description: "Investment round (seed, series A, etc.)", + properties: { + round_type: { + type: "string", + enum: [ + "preseed", + "seed", + "series_a", + "series_b", + "series_c", + "series_d", + "growth", + "ipo", + ], + "x-table-column": true, + "x-table-label": "Round Type", + }, + amount_usd: { + type: "number", + "x-table-column": true, + "x-table-label": "Amount (USD)", + }, + date: { + type: "string", + format: "date", + "x-table-column": true, + "x-table-label": "Date", + }, + lead_investor_slug: { + type: "string", + "x-table-column": true, + "x-table-label": "Lead Investor", + "x-link-entity-type": "investor", + "x-link-lookup-field": "slug", + }, + post_money_usd: { type: "number" }, + participants: { type: "array", items: { type: "string" } }, + }, +}); + +const investor = defineEntityType({ + key: "investor", + name: "Investor", + description: "VC firm, angel investor, or fund", + properties: { + investor_type: { + type: "string", + enum: [ + "vc_firm", + "angel", + "corporate", + "accelerator", + "family_office", + "partner", + ], + "x-table-column": true, + "x-table-label": "Type", + }, + sector_focus: { + type: "array", + items: { type: "string" }, + "x-table-column": true, + "x-table-label": "Sector Focus", + }, + website: { + type: "string", + format: "uri", + "x-table-column": true, + "x-table-label": "Website", + }, + sector: { + type: "string", + enum: SECTOR_ENUM, + "x-table-column": true, + "x-table-label": "Sector", + }, + bio: { type: "string" }, + fund_size: { type: "string" }, + stage_focus: { type: "array", items: { type: "string" } }, + linkedin_url: { type: "string", format: "uri" }, + portfolio_url: { type: "string", format: "uri" }, + typical_check_size: { type: "string" }, + }, +}); + +const jobPosting = defineEntityType({ + key: "job-posting", + name: "Job Posting", + description: "Open role at a market.company", + properties: { + role: { type: "string", "x-table-column": true, "x-table-label": "Role" }, + title: { type: "string", "x-table-column": true, "x-table-label": "Title" }, + company_id: { + type: "integer", + description: "FK to market.company", + "x-table-column": true, + "x-table-label": "Company", + "x-link-entity-type": "company", + }, + posted_by_founder_id: { + type: "integer", + description: "FK to market.founder if posted by a verified founder", + "x-link-entity-type": "founder", + }, + posted_by_member_id: { + type: "integer", + description: + "FK to market.$member if posted by an authorized member who isn't a founder", + "x-link-entity-type": "$member", + }, + city_id: { + type: "integer", + description: "FK to atlas.city (cross-org reference, optional)", + "x-table-column": true, + "x-table-label": "City", + }, + description: { type: "string" }, + status: { + type: "string", + enum: ["open", "filled", "closed"], + "x-table-column": true, + "x-table-label": "Status", + }, + posted_at: { type: "string", format: "date-time" }, + expires_at: { type: "string", format: "date-time" }, + }, +}); + +const product = defineEntityType({ + key: "product", + name: "Product", + description: "Company product tracked for reviews and market signals", + properties: { + tagline: { + type: "string", + "x-table-column": true, + "x-table-label": "Tagline", + }, + target_audience: { + type: "string", + "x-table-column": true, + "x-table-label": "Target Audience", + }, + value_proposition: { + type: "string", + "x-table-column": true, + "x-table-label": "Value Proposition", + }, + key_features: { type: "array", items: { type: "string" } }, + differentiators: { type: "string" }, + }, +}); + +const sector = defineEntityType({ + key: "sector", + name: "Sector", + description: "Investment thesis / practice area", + properties: { + sector_key: { + type: "string", + enum: SECTOR_ENUM, + "x-table-column": true, + "x-table-label": "Sector Key", + }, + description: { + type: "string", + "x-table-column": true, + "x-table-label": "Description", + }, + lead_partner_slug: { + type: "string", + "x-table-column": true, + "x-table-label": "Lead Partner", + "x-link-entity-type": "investor", + "x-link-lookup-field": "slug", + }, + color: { type: "string" }, + }, +}); + +const educatedAt = defineRelationshipType({ + key: "educated_at", + name: "Educated At", + description: + "Founder was educated at a university (cross-org reference into atlas.university)", + rules: [{ source: "founder", target: "university" }], +}); + +const foundedBy = defineRelationshipType({ + key: "founded_by", + name: "Founded By", + description: "Company was founded by this person", +}); + +const headquarteredIn = defineRelationshipType({ + key: "headquartered_in", + name: "Headquartered In", + description: + "Company is headquartered in a city (cross-org reference into atlas.city)", + rules: [{ source: "company", target: "city" }], +}); + +const inIndustry = defineRelationshipType({ + key: "in_industry", + name: "In Industry", + description: + "Company is in an industry (cross-org reference into atlas.industry)", + rules: [{ source: "company", target: "industry" }], +}); + +const inSector = defineRelationshipType({ + key: "in_sector", + name: "In Sector", +}); + +const investedIn = defineRelationshipType({ + key: "invested_in", + name: "Invested In", + description: "Investor has invested in this company", +}); + +const mentions = defineRelationshipType({ + key: "mentions", + name: "Mentions", + description: + "Loose reference — one entity is mentioned in the context of another", +}); + +const operatesIn = defineRelationshipType({ + key: "operates_in", + name: "Operates In", + description: + "Company operates in a country or region (cross-org reference into atlas.country or atlas.region)", + rules: [ + { source: "company", target: "country" }, + { source: "company", target: "region" }, + ], +}); + +const previouslyAt = defineRelationshipType({ + key: "previously_at", + name: "Previously At", +}); + +const primaryRelationshipOwner = defineRelationshipType({ + key: "primary_relationship_owner", + name: "Primary Relationship Owner", +}); + +const roundLedBy = defineRelationshipType({ + key: "round_led_by", + name: "Round Led By", +}); + +const roundOf = defineRelationshipType({ + key: "round_of", + name: "Round Of", +}); + +const sourcedBy = defineRelationshipType({ + key: "sourced_by", + name: "Sourced By", +}); + +const usesTechnology = defineRelationshipType({ + key: "uses_technology", + name: "Uses Technology", + description: + "Company uses a technology in its stack (cross-org reference into atlas.technology)", + rules: [{ source: "company", target: "technology" }], +}); + +const worksAt = defineRelationshipType({ + key: "works_at", + name: "Works At", + rules: [ + { source: "$member", target: "company" }, + { source: "founder", target: "company" }, + ], +}); + +const founderActivityTracker = defineWatcher({ + agent: vcTracking, + slug: "founder-activity-tracker", + name: "Founder Activity Tracker", + schedule: "0 10 * * *", + notification: { priority: "normal" }, + tags: ["vc", "founders", "daily"], + minCooldownSeconds: 600, + reaction: "./models/reactions/founder-activity-tracker.reaction.ts", + prompt: + "You are a venture capital analyst tracking the public activity of startup founders in your portfolio.\n\n## Founders\n{{#each entities}}\n- {{name}} ({{entity_type}}, ID: {{id}})\n{{/each}}\n\n## Recent Founder Activity\n{{#if sources.founder_posts}}\n{{sources.founder_posts}}\n{{/if}}\n\n---\n\nProduce a structured founder activity report:\n1. **Executive Summary**: 2-3 sentence overview of founder activity and signals.\n2. **Per-Founder Analysis**: For each active founder, summarize their messaging themes, engagement level, and signals about company direction.\n3. **Cross-Portfolio Patterns**: Themes multiple founders discuss.\n4. **Notable Signals**: Flag potential announcements, strategic shifts, or concerns.\n\nBe specific and cite actual tweets/posts as evidence.\n", + sources: { + founder_posts: + "SELECT id, title, payload_text, author_name, source_url, occurred_at, score, origin_type, connector_key FROM events WHERE connector_key IN ('x') AND origin_type IN ('tweet', 'reply') ORDER BY occurred_at DESC LIMIT 300\n", + }, + reactionsGuidance: + "When a founder signals hiring activity, fundraising, or pivots, flag for the investment team.\nTrack founders going quiet as a potential concern.\nAlert on any public statements about competitors or market conditions.\n", + extractionSchema: { + type: "object", + required: ["summary", "founders", "notable_signals"], + properties: { + summary: { type: "string" }, + founders: { + type: "array", + items: { + type: "object", + required: ["name", "company", "activity_level", "themes"], + properties: { + name: { type: "string" }, + company: { type: "string" }, + activity_level: { + type: "string", + enum: ["high", "medium", "low", "inactive"], + }, + themes: { type: "array", items: { type: "string" } }, + sentiment: { + type: "string", + enum: ["bullish", "neutral", "cautious", "concerned"], + }, + signals: { type: "array", items: { type: "string" } }, + notable_posts: { type: "array", items: { type: "string" } }, + }, + }, + }, + cross_patterns: { + type: "array", + items: { + type: "object", + properties: { + theme: { type: "string" }, + founders_involved: { type: "array", items: { type: "string" } }, + }, + }, + }, + notable_signals: { + type: "array", + items: { + type: "object", + required: ["signal", "founder", "impact"], + properties: { + signal: { type: "string" }, + founder: { type: "string" }, + impact: { type: "string", enum: ["high", "medium", "low"] }, + }, + }, + }, + }, + }, +}); + +const opportunityMatcher = defineWatcher({ + agent: vcTracking, + slug: "opportunity-matcher", + name: "Opportunity Matcher", + schedule: "0 */12 * * *", + notification: { priority: "normal" }, + tags: ["vc", "matching"], + minCooldownSeconds: 600, + prompt: + 'You are a community intelligence agent for a private founder community managed by a venture capital fund.\nYour job is to monitor founder activity and identify high-quality introduction opportunities between portfolio founders.\n\n## Community Members\n{{#each entities}}\n**{{name}}** ({{entity_type}})\n{{#if metadata.title}} — {{metadata.title}}{{/if}}\n{{#if metadata.role}} — {{metadata.role}}{{/if}}\n{{/each}}\n\n## Recent Activity\n{{#if sources.content}}\n{{sources.content}}\n{{/if}}\n\n## Instructions\n1. Scan all new content for signals: launches, posts, hiring announcements, funding news, project updates, and collaboration signals.\n2. For each signal, identify which other community founders are likely to care and explain why.\n3. Suggest a concrete action: warm intro draft, shared-interest notification, or flagging for community ops review.\n4. Only suggest introductions where there is a clear, specific overlap — not generic "both work in tech" matches.\n5. Rate each signal\'s strength (high/medium/low) based on timeliness and relevance.\n', + sources: { + content: + "SELECT id, title, payload_text, author_name, source_url, occurred_at, score, origin_type, connector_key FROM events WHERE entity_id IN (SELECT id FROM entities WHERE entity_type = 'founder') ORDER BY occurred_at DESC LIMIT 300\n", + }, + extractionSchema: { + type: "object", + required: ["signals", "intro_recommendations", "summary"], + properties: { + signals: { + type: "array", + items: { + type: "object", + required: [ + "type", + "source", + "summary", + "strength", + "related_topics", + "interested_members", + "reason", + "suggested_action", + ], + properties: { + type: { type: "string" }, + source: { type: "string" }, + summary: { type: "string" }, + strength: { type: "string", enum: ["high", "medium", "low"] }, + related_topics: { type: "array", items: { type: "string" } }, + interested_members: { type: "array", items: { type: "string" } }, + reason: { type: "string" }, + suggested_action: { type: "string" }, + }, + }, + }, + intro_recommendations: { + type: "array", + items: { + type: "object", + required: ["member_a", "member_b", "overlap", "confidence"], + properties: { + member_a: { type: "string" }, + member_b: { type: "string" }, + overlap: { type: "string" }, + draft_intro: { type: "string" }, + confidence: { type: "string", enum: ["high", "medium"] }, + }, + }, + }, + summary: { type: "string" }, + }, + }, +}); + +export default defineConfig({ + org: "market", + orgName: "Market", + orgDescription: + "Track companies, founders, and investment opportunities for venture firms", + agents: [vcTracking], + entities: [ + company, + founder, + fundRound, + investor, + jobPosting, + product, + sector, + ], + relationships: [ + educatedAt, + foundedBy, + headquarteredIn, + inIndustry, + inSector, + investedIn, + mentions, + operatesIn, + previouslyAt, + primaryRelationshipOwner, + roundLedBy, + roundOf, + sourcedBy, + usesTechnology, + worksAt, + ], + watchers: [founderActivityTracker, opportunityMatcher], +}); diff --git a/examples/office-bot/lobu.config.ts b/examples/office-bot/lobu.config.ts new file mode 100644 index 000000000..a5b73f60d --- /dev/null +++ b/examples/office-bot/lobu.config.ts @@ -0,0 +1,171 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const DELIVEROO_JUDGE = + "Allow GET requests that read restaurant listings, menus, item details, and the\ncurrent basket. Allow POST/PUT requests whose effect is limited to building or\nmodifying a basket / group order (adding, removing, changing quantity of items;\ncreating a shareable group-order link). DENY anything that completes checkout,\nsubmits payment, reads or writes saved payment methods, changes the delivery\naddress, or modifies the account profile. If the request's effect is unclear,\nfail closed and deny with a reason.\n"; + +const foodOrdering = defineAgent({ + id: "food-ordering", + name: "food-ordering", + description: + "Runs the office lunch order — presence check, recommendations, options poll, order collection, Deliveroo basket handoff", + dir: "./agents/food-ordering", + providers: [ + { + id: "z-ai", + model: "z-ai/glm-4.7", + key: secret("Z_AI_API_KEY"), + }, + ], + preview: { + slack: { enabled: true, surfaces: ["dm", "channel"], codeTtlMinutes: 15 }, + }, + network: { + allowed: [ + "api.z.ai", + ".z.ai", + "registry.npmjs.org", + ".npmjs.org", + "playwright.azureedge.net", + "cdn.playwright.dev", + ], + judged: [ + { domain: "deliveroo.co.uk", judge: "deliveroo" }, + { domain: ".deliveroo.co.uk", judge: "deliveroo" }, + { domain: "deliveroo.com", judge: "deliveroo" }, + { domain: ".deliveroo.com", judge: "deliveroo" }, + ], + judges: { deliveroo: DELIVEROO_JUDGE }, + }, +}); + +const lunchRun = defineEntityType({ + key: "lunch-run", + name: "Lunch run", + description: + "One day's office lunch order — who's in, what they ordered, the restaurant, the basket link, and where it ended up", + required: ["date", "channel", "status"], + properties: { + date: { + type: "string", + description: "ISO date of the run (one run per day)", + "x-table-label": "Date", + "x-table-column": true, + }, + channel: { + type: "string", + description: "The chat channel/conversation the run happened in", + "x-table-label": "Channel", + }, + status: { + type: "string", + enum: ["collecting", "done", "cancelled"], + "x-table-label": "Status", + "x-table-column": true, + }, + restaurant: { + type: "string", + "x-table-label": "Restaurant", + "x-table-column": true, + }, + thread_ref: { + type: "string", + description: + "Reference to the thread/message where the run is happening — lunch-finalize uses this to find the conversation", + }, + items: { + type: "array", + description: "Per-person order lines", + items: { + type: "object", + properties: { + person: { type: "string" }, + item: { type: "string" }, + price: { type: "number" }, + notes: { type: "string" }, + }, + }, + }, + subtotal: { + type: "number", + "x-table-label": "Subtotal", + "x-table-column": true, + }, + basket_url: { + type: "string", + description: + "Deliveroo group-order / basket link handed to a human, or null if placed manually", + }, + notes: { type: "string" }, + }, +}); + +const lunchOpen = defineWatcher({ + agent: foodOrdering, + slug: "lunch-open", + name: "Open the lunch run", + schedule: "0 11 * * 1-5", + notification: { priority: "high", channel: "both" }, + tags: ["lunch", "daily"], + minCooldownSeconds: 600, + prompt: + "Open today's office lunch run (step 1 in your instructions):\n\n1. Check memory for a `lunch-run` entity dated today — if one exists and isn't\n cancelled, stop (don't open a second one).\n2. Guess who's in from recent chat activity and past `lunch-run` entities.\n3. Post the lunch call in the channel: react 🍕 / \"+1\" to join, drop restaurant\n recommendations, options coming ~11:35, targeting ~12:30 delivery. @-mention\n the people you think are in, but make clear anyone can join or skip.\n4. Open a thread off that message.\n5. Save a `lunch-run` entity {date, channel, status: \"collecting\", thread_ref,\n restaurant: null, items: []} and a `lunch:opened` event linked to it.\n\nThen end — the lunch-finalize watcher takes it from here. Keep it to one short\nmessage in the channel.\n", + extractionSchema: { + type: "object", + required: ["opened"], + properties: { + opened: { + type: "boolean", + description: + "true if a new run was opened, false if one already existed", + }, + in_office_guess: { type: "array", items: { type: "string" } }, + thread_ref: { type: "string" }, + }, + }, +}); + +const lunchFinalize = defineWatcher({ + agent: foodOrdering, + slug: "lunch-finalize", + name: "Collect orders and hand off", + schedule: "35 11 * * 1-5", + notification: { priority: "high" }, + tags: ["lunch", "daily"], + minCooldownSeconds: 600, + reactionsGuidance: + "When the run ends in `placed` or `manual`, store the basket link + per-head cost\nback into a `lunch:placed` event on the lunch-run entity so the next day's\nlunch-open can read the most-recent restaurant.\n", + prompt: + 'Finalize today\'s office lunch run (step 2 in your instructions):\n\n1. Find today\'s `lunch-run` entity (status "collecting"). If there isn\'t one,\n open one (step 1) and stop. If it\'s already "done"/"cancelled", do nothing.\n2. Read the run\'s thread — work out who\'s in (🍕 / "+1" / put in an order) and\n any restaurant recommendations. If nobody\'s in: post a "skipping today 👋"\n note, set the run to "cancelled", save a `lunch:cancelled` event, stop.\n3. Pick the restaurant (a clear thread recommendation, else a usual spot from\n USER.md, biased away from the last couple of runs).\n4. Post the options — if the deliveroo-order skill can scrape the menu, a\n numbered shortlist of ~5–8 popular items with prices; otherwise just name\n the restaurant (a link to its Deliveroo page is fine). Always accept\n free-text orders.\n5. Collect orders from replies + number reactions into items: [{person, item,\n price?, notes}]. Ask directly about anything ambiguous — don\'t guess silently.\n6. Build the Deliveroo basket via the deliveroo-order skill (login with stored\n cookies → add items → group-order/basket link + subtotal). If it fails for\n any reason, fall back: basket_url = null, continue.\n7. Post the summary in the thread: restaurant; per-person list (@person — item\n (notes)); subtotal + per-head (flag if well over budget); the basket link if\n you have one; and the next action — "@here someone hit checkout & pay:\n " or, with no link, "@here someone needs to place this manually".\n8. Update the `lunch-run` entity (status "done", restaurant, items, subtotal,\n basket_url) and save a `lunch:placed` event linked to it.\n\nNever complete checkout or pay. A run with no basket automation is still a\nsuccess if the order list got collected and handed off cleanly.\n', + extractionSchema: { + type: "object", + required: ["outcome"], + properties: { + outcome: { + type: "string", + enum: ["placed", "manual", "cancelled", "no-run"], + description: + "placed = basket link handed off; manual = order list handed off without a link; cancelled = nobody in; no-run = no run existed to finalize", + }, + restaurant: { type: "string" }, + headcount: { type: "integer" }, + subtotal: { type: "number" }, + basket_url: { type: "string" }, + }, + }, +}); + +export default defineConfig({ + org: "lobu-team", + orgName: "Lobu Team", + orgDescription: "Office-ops agents — first up: the weekday lunch order", + organizationId: "UdNAH1bb3csC842vhOgxAHVcfX4tYU5A", + agents: [foodOrdering], + entities: [lunchRun], + watchers: [lunchOpen, lunchFinalize], +}); diff --git a/examples/personal-finance/lobu.config.ts b/examples/personal-finance/lobu.config.ts new file mode 100644 index 000000000..b1e9cd0ad --- /dev/null +++ b/examples/personal-finance/lobu.config.ts @@ -0,0 +1,1308 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const personal_finance = defineAgent({ + id: "personal-finance", + name: "personal-finance", + description: + "Help individuals capture wages, expenses, savings, dividends, capital gains and pension contributions across the tax year and assemble a UK Self Assessment (SA100) return.", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + ".gov.uk", + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, + nixPackages: ["poppler_utils", "csvtk"], +}); + +const account = defineEntityType({ + key: "account", + name: "Account", + description: + "A bank, savings, brokerage, pension, mortgage, or business account. Owner is always set via the owned_by relationship (or co_owned_by for joint accounts) — never inferred from context.", + required: ["provider", "wrapper"], + properties: { + provider: { + type: "string", + description: 'Bank or broker name (e.g. "Monzo", "Hargreaves Lansdown")', + "x-table-label": "Provider", + "x-table-column": true, + }, + wrapper: { + type: "string", + enum: [ + "current", + "savings", + "business_current", + "business_savings", + "ISA", + "LISA", + "JISA", + "SIPP", + "workplace_pension", + "GIA", + "mortgage", + "credit_card", + "loan", + "other", + ], + description: + "Account class. Drives tax treatment (ISA = no SA reporting, GIA = CGT applies, etc.).", + "x-table-label": "Wrapper", + "x-table-column": true, + }, + currency: { + type: "string", + description: "ISO 4217 currency code", + default: "GBP", + "x-table-label": "Ccy", + "x-table-column": true, + }, + account_number_last4: { + type: "string", + description: "Last 4 digits, for matching against statements", + }, + sort_code: { type: "string" }, + iban: { + type: "string", + description: + "For non-UK accounts; preferred over sort_code+account_number when known", + }, + opening_balance: { + type: "string", + description: 'Decimal string, e.g. "1234.56"', + }, + closing_balance: { type: "string" }, + notes: { type: "string" }, + }, +}); + +const allowance_window = defineEntityType({ + key: "allowance_window", + name: "Allowance Window", + description: + 'A materialized accumulator for one tax allowance over one tax year. Lets the agent answer "how much ISA budget left this year?" or "how much pension annual allowance can I still use?" instantly without recomputing across all underlying transactions/contributions every time.', + required: ["kind", "cap", "used"], + properties: { + kind: { + type: "string", + enum: [ + "isa_subscription", + "dividend_allowance", + "personal_savings_allowance", + "cgt_annual_exempt", + "pension_annual_allowance", + "property_income_allowance", + "trading_allowance", + "personal_allowance", + ], + description: "Which HMRC-defined allowance this window tracks", + "x-table-label": "Allowance", + "x-table-column": true, + }, + cap: { + type: "string", + description: + 'Decimal GBP. The statutory limit for this allowance in this year (e.g. "20000" for ISA, "60000" for pension AA).', + "x-table-label": "Cap", + "x-table-column": true, + }, + used: { + type: "string", + description: + "Decimal GBP consumed so far. Updated on every relevant transaction/contribution write.", + "x-table-label": "Used", + "x-table-column": true, + }, + remaining: { + type: "string", + description: + "Decimal GBP. cap minus used minus carry_forward used. May go negative if a tapered allowance applies (the agent surfaces this).", + "x-table-label": "Remaining", + "x-table-column": true, + }, + carry_forward_in: { + type: "string", + description: + "For pension AA — unused allowance carried in from the prior 3 years.", + }, + carry_forward_out: { + type: "string", + description: + "Unused this year, available to carry forward (subject to the allowance's rules).", + }, + last_recomputed_at: { + type: "string", + format: "date-time", + description: + "When the agent last recomputed used/remaining from underlying entities.", + }, + }, +}); + +const asset_lot = defineEntityType({ + key: "asset_lot", + name: "Asset Lot", + description: + "An acquisition lot used for s.104 share-pool / matching rules. One lot per buy event.", + required: ["acquisition_date", "quantity", "cost_basis"], + properties: { + pool_id: { + type: "string", + description: "Identifier for the s.104 pool (typically the ticker/ISIN)", + "x-table-label": "Pool", + "x-table-column": true, + }, + acquisition_date: { + type: "string", + format: "date", + "x-table-label": "Acquired", + "x-table-column": true, + }, + quantity: { + type: "string", + "x-table-label": "Quantity", + "x-table-column": true, + }, + cost_basis: { + type: "string", + description: "Total cost for this lot, decimal GBP", + "x-table-label": "Cost", + "x-table-column": true, + }, + quantity_remaining: { + type: "string", + description: "After partial disposals", + }, + }, +}); + +const cgt_event = defineEntityType({ + key: "cgt_event", + name: "CGT Event", + description: + "A capital-gains disposal — sale, gift, or other event triggering CGT (SA108).", + required: [ + "asset_description", + "asset_class", + "disposal_date", + "disposal_proceeds", + ], + properties: { + asset_description: { + type: "string", + "x-table-label": "Asset", + "x-table-column": true, + }, + asset_class: { + type: "string", + enum: [ + "listed_shares", + "unlisted_shares", + "residential_property", + "other_property", + "crypto", + "other", + ], + "x-table-label": "Class", + "x-table-column": true, + }, + acquisition_date: { type: "string", format: "date" }, + acquisition_cost: { + type: "string", + description: "Total acquisition cost, decimal string GBP", + }, + disposal_date: { + type: "string", + format: "date", + "x-table-label": "Disposal", + "x-table-column": true, + }, + disposal_proceeds: { + type: "string", + description: "Total proceeds, decimal string GBP", + "x-table-label": "Proceeds", + "x-table-column": true, + }, + incidental_costs: { + type: "string", + description: "Legal, broker, SDLT on acquisition, enhancement", + }, + relief_claimed: { + type: "string", + enum: [ + "none", + "PRR", + "BADR", + "investors_relief", + "gift_holdover", + "EIS_deferral", + "SEIS_deferral", + ], + default: "none", + "x-table-label": "Relief", + "x-table-column": true, + }, + residential_60day_return_ref: { + type: "string", + description: + "HMRC reference if a 60-day residential CGT return was already filed", + }, + }, +}); + +const company = defineEntityType({ + key: "company", + name: "Company", + description: + "A legal entity that can hold accounts, file tax returns, employ people, or be owned. Covers Ltd, PLC, LLP, sole-trader, partnership, trust, and charity. Discriminate by company_type.", + required: ["legal_name", "company_type"], + properties: { + legal_name: { + type: "string", + "x-table-label": "Name", + "x-table-column": true, + }, + company_type: { + type: "string", + enum: [ + "ltd", + "plc", + "llp", + "sole_trader", + "partnership", + "trust", + "charity", + "foreign", + ], + "x-table-label": "Type", + "x-table-column": true, + }, + incorporation_date: { type: "string", format: "date" }, + registered_address: { type: "string" }, + accounting_period_start: { + type: "string", + format: "date", + description: + "Start of the company's accounting reference period (CT600 / SA800 anchor)", + }, + accounting_period_end: { type: "string", format: "date" }, + vat_registered: { + type: "boolean", + default: false, + "x-table-label": "VAT", + "x-table-column": true, + }, + vat_scheme: { + type: "string", + enum: [ + "standard", + "flat_rate", + "cash_accounting", + "annual_accounting", + "none", + ], + default: "none", + }, + is_personal_service_company: { + type: "boolean", + default: false, + description: "Marks PSCs (relevant for IR35 / off-payroll-working rules)", + }, + dormant_flag: { type: "boolean", default: false }, + ceased_date: { type: "string", format: "date" }, + notes: { type: "string" }, + }, +}); + +const contribution = defineEntityType({ + key: "contribution", + name: "Contribution", + description: + "A pension or charitable contribution affecting tax (Gift Aid, SIPP, etc.).", + required: ["scheme", "mechanism", "amount", "date"], + properties: { + scheme: { + type: "string", + description: "Provider/charity name", + "x-table-label": "Scheme", + "x-table-column": true, + }, + mechanism: { + type: "string", + enum: ["relief_at_source", "net_pay", "salary_sacrifice", "gift_aid"], + description: + "Pension relief mechanism, or gift_aid for charitable donations", + "x-table-label": "Mechanism", + "x-table-column": true, + }, + amount: { + type: "string", + description: "Net amount paid, decimal GBP", + "x-table-label": "Amount", + "x-table-column": true, + }, + date: { + type: "string", + format: "date", + "x-table-label": "Date", + "x-table-column": true, + }, + carry_back_to_prior_year: { + type: "boolean", + default: false, + description: "Gift Aid carry-back election", + }, + }, +}); + +const document = defineEntityType({ + key: "document", + name: "Document", + description: + "A source document — P60, P45, P11D, SA302, broker contract note, mortgage statement, bank statement — that other entities are parsed from.", + required: ["doc_type", "source"], + properties: { + doc_type: { + type: "string", + enum: [ + "P60", + "P45", + "P11D", + "SA302", + "bank_statement", + "savings_statement", + "broker_statement", + "contract_note", + "dividend_voucher", + "mortgage_statement", + "rental_agreement", + "receipt", + "other", + ], + "x-table-label": "Type", + "x-table-column": true, + }, + source: { + type: "string", + enum: ["gmail", "whatsapp_upload", "manual"], + "x-table-label": "Source", + "x-table-column": true, + }, + download_url: { + type: "string", + format: "uri", + description: "Signed gateway artifact URL", + }, + payer_or_employer: { + type: "string", + description: "Counterparty named on the document", + }, + captured_at: { type: "string", format: "date-time" }, + }, +}); + +const expense = defineEntityType({ + key: "expense", + name: "Expense", + description: "An allowable expense against a trade or property.", + required: ["category", "amount", "date"], + properties: { + category: { + type: "string", + enum: [ + "cost_of_goods", + "travel", + "premises", + "repairs", + "admin", + "advertising", + "interest_finance", + "professional_fees", + "wages", + "utilities", + "insurance", + "agent_fees", + "other", + ], + "x-table-label": "Category", + "x-table-column": true, + }, + amount: { + type: "string", + description: "Decimal GBP", + "x-table-label": "Amount", + "x-table-column": true, + }, + date: { + type: "string", + format: "date", + "x-table-label": "Date", + "x-table-column": true, + }, + notes: { type: "string" }, + is_capital: { + type: "boolean", + default: false, + description: + "Capital vs revenue (capital expenses go to capital_allowances, not expenses)", + }, + }, +}); + +const filing_obligation = defineEntityType({ + key: "filing_obligation", + name: "Filing Obligation", + description: + "A required tax return or filing the user (or one of their companies) must submit by a deadline. Captures SA100, CT600, SA800, SA900, VAT101, P11D, etc. Lets the agent surface deadlines proactively and reconcile against actual filings.", + required: [ + "return_form", + "period_start", + "period_end", + "deadline_type", + "due_date", + ], + properties: { + return_form: { + type: "string", + enum: [ + "SA100", + "SA800", + "SA900", + "CT600", + "VAT101", + "P11D", + "PAYE_RTI", + "confirmation_statement", + ], + "x-table-label": "Form", + "x-table-column": true, + }, + period_start: { type: "string", format: "date" }, + period_end: { type: "string", format: "date" }, + deadline_type: { + type: "string", + enum: [ + "paper_filing", + "online_filing", + "balancing_payment", + "poa1", + "poa2", + "corp_tax_payment", + "corp_tax_filing", + "vat_payment", + "registration", + ], + "x-table-label": "Deadline", + "x-table-column": true, + }, + due_date: { + type: "string", + format: "date", + "x-table-label": "Due", + "x-table-column": true, + }, + status: { + type: "string", + enum: ["upcoming", "reminded", "overdue", "filed", "paid", "waived"], + default: "upcoming", + "x-table-label": "Status", + "x-table-column": true, + }, + completed_date: { type: "string", format: "date" }, + hmrc_reference: { + type: "string", + description: "HMRC submission receipt or reference number, once filed.", + }, + }, +}); + +const goal = defineEntityType({ + key: "goal", + name: "Goal", + description: + "A personal financial goal (emergency fund, deposit, retirement target, etc.).", + required: ["name", "target_amount", "category"], + properties: { + name: { type: "string", "x-table-label": "Goal", "x-table-column": true }, + target_amount: { + type: "string", + description: "Decimal GBP", + "x-table-label": "Target", + "x-table-column": true, + }, + target_date: { + type: "string", + format: "date", + "x-table-label": "By", + "x-table-column": true, + }, + category: { + type: "string", + enum: ["emergency_fund", "deposit", "retirement", "debt_payoff", "other"], + "x-table-label": "Category", + "x-table-column": true, + }, + current_amount: { + type: "string", + description: "Optional snapshot, decimal GBP", + }, + }, +}); + +const holding = defineEntityType({ + key: "holding", + name: "Holding", + description: "A current security position in a brokerage account.", + required: ["ticker", "quantity", "as_of_date"], + properties: { + ticker: { + type: "string", + "x-table-label": "Ticker", + "x-table-column": true, + }, + isin: { type: "string" }, + quantity: { + type: "string", + description: "Decimal string", + "x-table-label": "Quantity", + "x-table-column": true, + }, + avg_cost: { + type: "string", + description: "Average cost per unit (s.104 pool), decimal string", + }, + currency: { type: "string", default: "GBP" }, + as_of_date: { + type: "string", + format: "date", + "x-table-label": "As of", + "x-table-column": true, + }, + }, +}); + +const income_source = defineEntityType({ + key: "income_source", + name: "Income Source", + description: + "A recurring origin of income (employer, trade, dividend payer, interest payer, rental property, pension, foreign source).", + required: ["type"], + properties: { + type: { + type: "string", + enum: [ + "employment", + "self_employment", + "dividend", + "interest", + "rental", + "pension", + "foreign", + ], + "x-table-label": "Type", + "x-table-column": true, + }, + payer_name: { + type: "string", + "x-table-label": "Payer", + "x-table-column": true, + }, + country: { + type: "string", + description: "ISO 3166-1 alpha-2; non-GB triggers SA106", + }, + foreign_tax_paid: { + type: "string", + description: + "Decimal — total foreign tax withheld at source for the tax year, in foreign_tax_currency. Drives Foreign Tax Credit Relief (FTCR) on SA106.", + }, + foreign_tax_currency: { + type: "string", + description: + "ISO 4217 of the foreign_tax_paid amount. Usually matches the income currency.", + }, + withholding_jurisdiction: { + type: "string", + description: + "ISO 3166-1 alpha-2 of the country that withheld the tax. May differ from `country` (e.g. US dividends paid via a UK broker — withheld in US, paid to UK).", + }, + treaty_rate_applied: { + type: "string", + description: + 'Decimal — treaty withholding rate already applied at source (e.g. "0.15" for the 15% US/UK treaty rate on dividends). Used to flag over-withholding that may be recoverable from the source country.', + }, + notes: { type: "string" }, + }, +}); + +const payment = defineEntityType({ + key: "payment", + name: "Payment", + description: + "A payment to or from HMRC — balancing payments, payments on account, corporation tax, VAT remittances, refunds. Distinct from generic transactions because it ties to filing_obligation and tax_assessment for reconciliation.", + required: ["amount", "currency", "date", "direction", "kind"], + properties: { + amount: { + type: "string", + description: "Decimal — always positive", + "x-table-label": "Amount", + "x-table-column": true, + }, + currency: { type: "string", default: "GBP" }, + date: { + type: "string", + format: "date", + "x-table-label": "Date", + "x-table-column": true, + }, + direction: { + type: "string", + enum: ["to_hmrc", "from_hmrc"], + "x-table-label": "Direction", + "x-table-column": true, + }, + kind: { + type: "string", + enum: [ + "balancing_payment", + "poa1", + "poa2", + "corp_tax", + "vat", + "paye_nic", + "refund", + "penalty", + "interest", + ], + "x-table-label": "Kind", + "x-table-column": true, + }, + reference: { + type: "string", + description: + "HMRC payment reference (UTR + K, or CT-specific accounting reference)", + }, + method: { + type: "string", + enum: [ + "bank_transfer", + "direct_debit", + "debit_card", + "cheque", + "paye_coding", + ], + }, + }, +}); + +const property = defineEntityType({ + key: "property", + name: "Property", + description: + "Real estate. Use for primary residences (PRR on disposal), let properties (SA105/SA106), holiday lets (FHL), and commercial real estate. Owner is set via owned_by or co_owned_by; never put owner in metadata.", + required: ["address", "type", "use"], + properties: { + address: { + type: "string", + "x-table-label": "Address", + "x-table-column": true, + }, + type: { + type: "string", + enum: ["residential", "commercial", "mixed_use", "land"], + "x-table-label": "Type", + "x-table-column": true, + }, + use: { + type: "string", + description: + "How the property is used. Drives tax treatment more than physical type does.", + enum: [ + "primary_residence", + "let", + "FHL", + "commercial_let", + "mixed_use", + "investment_held", + ], + "x-table-label": "Use", + "x-table-column": true, + }, + country: { + type: "string", + description: "ISO 3166-1 alpha-2; non-GB triggers SA106", + default: "GB", + }, + rental_income_allowance_claimed: { + type: "boolean", + default: false, + description: "£1,000 property income allowance flag", + }, + purchase_date: { type: "string", format: "date" }, + purchase_cost: { + type: "string", + description: + "Decimal GBP — useful for PRR calculation on eventual disposal", + }, + }, +}); + +const relief_claim = defineEntityType({ + key: "relief_claim", + name: "Relief Claim", + description: + "A tax relief or allowance claim (Gift Aid, marriage allowance, EIS/SEIS, BADR, PRR).", + required: ["type"], + properties: { + type: { + type: "string", + enum: [ + "gift_aid", + "marriage_allowance", + "EIS", + "SEIS", + "BADR", + "PRR", + "investors_relief", + "foreign_tax_credit", + ], + "x-table-label": "Type", + "x-table-column": true, + }, + amount: { + type: "string", + description: "Decimal GBP if applicable", + "x-table-label": "Amount", + "x-table-column": true, + }, + notes: { type: "string" }, + }, +}); + +const tax_assessment = defineEntityType({ + key: "tax_assessment", + name: "Tax Assessment", + description: + "A computed or HMRC-issued tax position for one tax year, one subject. Captures SA302 outputs (HMRC's view) + agent-computed projections (our view) so we can reconcile and surface differences.", + required: ["source", "total_tax_due", "computed_at"], + properties: { + source: { + type: "string", + enum: [ + "agent_projection", + "hmrc_sa302", + "hmrc_ct600_acknowledgement", + "manual", + ], + description: + "Where this assessment came from. agent_projection = our running estimate; hmrc_* = the authority's number.", + "x-table-label": "Source", + "x-table-column": true, + }, + total_income: { + type: "string", + description: "Decimal GBP — sum of all income sources before allowances", + }, + total_tax_due: { + type: "string", + description: "Decimal GBP — final tax liability for the year", + "x-table-label": "Tax due", + "x-table-column": true, + }, + tax_paid_at_source: { + type: "string", + description: "PAYE + dividend tax withheld + foreign tax credit", + }, + balancing_owed: { + type: "string", + description: "total_tax_due - tax_paid_at_source - poa_paid", + }, + allowances_used: { + type: "object", + description: + "Per-allowance breakdown (personal_allowance, dividend_allowance, psa, cgt_aea, etc.)", + }, + computed_at: { type: "string", format: "date-time" }, + hmrc_reference: { type: "string" }, + }, +}); + +const tax_year = defineEntityType({ + key: "tax_year", + name: "Tax Year", + description: + "A UK fiscal year (6 April to 5 April) — the container all reportable activity is anchored to.", + required: ["year_label", "start", "end"], + properties: { + year_label: { + type: "string", + description: 'Year label, e.g. "2025-26"', + "x-table-label": "Year", + "x-table-column": true, + }, + start: { + type: "string", + format: "date", + description: "Inclusive start, e.g. 2025-04-06", + }, + end: { + type: "string", + format: "date", + description: "Inclusive end, e.g. 2026-04-05", + }, + filing_status: { + type: "string", + enum: ["in_progress", "assembled", "filed"], + description: "Where the user is in the cycle", + "x-table-label": "Status", + "x-table-column": true, + }, + filed_at: { type: "string", format: "date-time" }, + residence_status: { + type: "string", + enum: [ + "uk_resident", + "non_resident", + "split_year_arriver", + "split_year_leaver", + "dual_resident", + ], + description: + "UK tax residence for THIS year. Recorded per-tax_year because residence\ncan change (someone moving in/out of the UK has different status year\nto year). Drives SA109 routing.\n", + "x-table-label": "Residence", + "x-table-column": true, + }, + arrival_date: { + type: "string", + format: "date", + description: "For split-year arrivers — date residence began", + }, + departure_date: { + type: "string", + format: "date", + description: "For split-year leavers — date residence ended", + }, + }, +}); + +const transaction = defineEntityType({ + key: "transaction", + name: "Transaction", + description: "A single debit or credit on an account.", + required: ["date", "amount", "currency"], + properties: { + date: { + type: "string", + format: "date", + "x-table-label": "Date", + "x-table-column": true, + }, + amount: { + type: "string", + description: "Decimal string. Positive = credit, negative = debit.", + "x-table-label": "Amount", + "x-table-column": true, + }, + currency: { type: "string", default: "GBP" }, + description: { + type: "string", + "x-table-label": "Description", + "x-table-column": true, + }, + merchant_raw: { + type: "string", + description: + "Verbatim merchant text from the statement; resolved/categorised later.", + }, + tax_relevance: { + type: "string", + enum: ["none", "income", "expense", "cgt"], + description: "Whether this transaction matters for the SA return.", + "x-table-label": "Tax", + "x-table-column": true, + }, + expense_category: { + type: "string", + description: + "HMRC-aligned category for allowable expenses (cost_of_goods, travel, premises, repairs, admin, advertising, interest, professional_fees, wages, other).", + }, + is_personal: { type: "boolean", default: true }, + native_amount: { + type: "string", + description: + "Decimal amount in the foreign currency, when currency != GBP. Keep alongside `amount` so the agent can show both numbers and recompute if rates need correcting.", + }, + native_currency: { + type: "string", + description: + 'ISO 4217 currency code of native_amount (e.g. "USD", "EUR"). When set, the `currency` field on this transaction is GBP and native_currency is the original.', + }, + fx_rate_to_gbp: { + type: "string", + description: + "Decimal — the FX rate snapshot used to convert native_amount to amount (GBP). Source the rate from the transaction date. Required when native_currency is set so HMRC-aligned conversion is auditable.", + }, + fx_rate_source: { + type: "string", + description: + 'Where the FX rate came from (e.g. "hmrc_monthly", "broker_statement", "ecb_daily"). Helps reconcile if HMRC\'s published rate differs.', + }, + }, +}); + +const account_contains = defineRelationshipType({ + key: "account_contains", + name: "Account Contains", + description: "An account contains a transaction or holding.", +}); + +const accountant_for = defineRelationshipType({ + key: "accountant_for", + name: "Accountant For", + description: + "One subject acts as accountant or agent for another. Lets a hired accountant Lobu user be granted access to a client's $member or company entity later. Source can be either $member or company; target can be either.", +}); + +const accumulates_in = defineRelationshipType({ + key: "accumulates_in", + name: "Accumulates In", + description: + "A transaction or contribution counts toward an allowance window. E.g. an ISA deposit accumulates_in the year's isa_subscription window; a pension contribution accumulates_in the year's pension_annual_allowance window.", +}); + +const assessment_for = defineRelationshipType({ + key: "assessment_for", + name: "Assessment For", + description: + "A tax_assessment is for a particular tax_year and subject. Used to anchor agent projections and HMRC SA302 outputs to the same year + filer so they can be compared.", +}); + +const co_owned_by = defineRelationshipType({ + key: "co_owned_by", + name: "Co-owned By", + description: + "An asset is jointly owned by multiple subjects. One row per co-owner. Sum of share_pct across all co-owners should equal 100.", +}); + +const controls = defineRelationshipType({ + key: "controls", + name: "Controls", + description: + "A person or company exercises significant control over a company (PSC register entry under the Companies Act). Source can be $member or company.", +}); + +const director_of = defineRelationshipType({ + key: "director_of", + name: "Director Of", + description: "A person is a registered director of a company.", +}); + +const disposal_of = defineRelationshipType({ + key: "disposal_of", + name: "Disposal Of", + description: "A CGT event disposes of (all or part of) an asset lot.", +}); + +const employed_by = defineRelationshipType({ + key: "employed_by", + name: "Employed By", + description: + "An employment-type income source flows from a particular employer (a company entity). Pairs with employee_of when the agent has the direct subject-to-subject employment fact.", +}); + +const employee_of = defineRelationshipType({ + key: "employee_of", + name: "Employee Of", + description: + "A person is employed by a company. Replaces the older `employed_by` indirection through `income_source` for direct subject-to-subject employment facts.", +}); + +const expense_of = defineRelationshipType({ + key: "expense_of", + name: "Expense Of", + description: + "An expense is incurred against a subject — a $member (personal allowable expense), a property (SA105/SA106), or a company (operating cost on the business books).", +}); + +const for_tax_year = defineRelationshipType({ + key: "for_tax_year", + name: "For Tax Year", + description: + "An entity (transaction, cgt_event, contribution, relief_claim, expense) is recorded against a particular tax year.", +}); + +const income_from = defineRelationshipType({ + key: "income_from", + name: "Income From", + description: + "A transaction is income from a particular source (employer, dividend payer, interest payer, rental, etc.).", +}); + +const obligation_for = defineRelationshipType({ + key: "obligation_for", + name: "Obligation For", + description: + 'A filing_obligation belongs to a tax_year and a subject ($member or company). The same SA100 obligation is "for" the user\'s $member and "for" their tax_year.', +}); + +const owned_by = defineRelationshipType({ + key: "owned_by", + name: "Owned By", + description: + "An asset (account, holding, asset_lot, property) is owned by a subject ($member or company). Use co_owned_by instead when ownership is shared.", +}); + +const parsed_from = defineRelationshipType({ + key: "parsed_from", + name: "Parsed From", + description: + "An entity (transaction, cgt_event, holding, etc.) was parsed from a source document — provenance link.", +}); + +const partner_in = defineRelationshipType({ + key: "partner_in", + name: "Partner In", + description: + "A person is a partner in an LLP or partnership. Drives SA104 routing for partnership income.", +}); + +const settles = defineRelationshipType({ + key: "settles", + name: "Settles", + description: + "A payment settles part or all of a filing_obligation (e.g. balancing_payment settles SA100 balancing). One filing_obligation may be settled by multiple payments.", +}); + +const shareholder_of = defineRelationshipType({ + key: "shareholder_of", + name: "Shareholder Of", + description: + "A person or company holds shares in a company. Source can be either $member or company (companies can own other companies).", +}); + +const spouse_of = defineRelationshipType({ + key: "spouse_of", + name: "Spouse Of", + description: + "Marriage or civil partnership. Symmetric. Relevant for marriage allowance, jointly held assets, and inheritance planning.", +}); + +const transfer_pair = defineRelationshipType({ + key: "transfer_pair", + name: "Transfer Pair", + description: + "Two transactions are the two legs of an internal transfer between accounts the same subject controls (e.g. Jane's current → Jane's savings). Salary or distributions crossing subject boundaries (Ltd current → Jane personal) are NOT internal transfers and must not be linked here. Symmetric. When this link exists, neither side counts as taxable income or as an allowable expense.", +}); + +const gmail_txWatcher = defineWatcher({ + agent: personal_finance, + slug: "gmail-tx", + name: "Gmail financial-event extractor", + schedule: "*/30 * * * *", + notification: { priority: "low" }, + minCooldownSeconds: 300, + tags: ["personal-finance", "gmail", "ingestion"], + reactionsGuidance: + 'After extracting:\n1. Resolve or create the active `tax_year` entity from the user\'s profile. Each new transaction / cgt_event / contribution must be linked to it via `for_tax_year`.\n2. For each `documents[]` entry, create a `document` entity (source="gmail") and use it as the `parsed_from` target for the transactions / cgt_events / dividends extracted from that same gmail_message_id.\n3. For each `transactions[]` entry, resolve or create the `account` from `account_hint` and link via `account_contains`. If income, create or resolve an `income_source` and link via `income_from`.\n4. For `cgt_events[]`, look up matching `asset_lot` rows in the same `pool_id` and link via `disposal_of`. If acquisition data is missing, save a note flagging the gap rather than guessing.\n5. For `dividends[]`, create a `transaction(tax_relevance=income)` linked to an `income_source(type=dividend, payer_name, country)`.\n6. Never overwrite a user-edited entity. If a duplicate is suspected (same date + amount + account), surface it as a question instead of writing.\n', + sources: { + gmail_messages: + "SELECT id, title, payload_text, payload_html, occurred_at FROM events WHERE connector_key = 'google.gmail' ORDER BY occurred_at DESC LIMIT 200\n", + }, + prompt: + 'You are a private financial accountant scanning the user\'s forwarded Gmail messages for events that matter to a UK Self Assessment return.\n\n## Recent emails\n{{#if sources.gmail_messages}}\n{{sources.gmail_messages}}\n{{else}}\nNo new messages this window.\n{{/if}}\n\n## Active tax year\n{{#if entities}}\n{{#each entities}}\n- {{name}} ({{entity_type}}, ID: {{id}})\n{{/each}}\n{{else}}\nNo tax year context provided.\n{{/if}}\n\n---\n\nIdentify and extract financial events. Each email may yield zero, one, or many events. Be conservative: skip noise (marketing, password resets, etc.).\n\nCategories to extract:\n- **transactions** — deposits, debits, transfers, salary credits, dividend payments hitting an account\n- **cgt_events** — broker contract notes for sells/disposals, gifts, transfers out of a GIA\n- **dividends** — UK or foreign dividend notifications (gross + currency)\n- **documents** — P60/P45/P11D/SA302/contract notes/mortgage statements arriving as attachments or linked PDFs\n\nFor each item, include the source `gmail_message_id` so we can link provenance. Prefer GBP unless the message clearly states a different currency.\n\nSkip transactions inside ISAs and SIPPs unless they are dividends or contributions (which are still reportable). Mark `tax_relevance="none"` for ISA-internal transactions; mark `tax_relevance="cgt"` for non-wrapper disposals.\n', + extractionSchema: { + type: "object", + required: ["transactions", "cgt_events", "dividends", "documents"], + properties: { + transactions: { + type: "array", + items: { + type: "object", + required: [ + "date", + "amount", + "currency", + "description", + "gmail_message_id", + ], + properties: { + date: { type: "string", format: "date" }, + amount: { + type: "string", + description: + "Decimal string. Positive = credit, negative = debit.", + }, + currency: { type: "string" }, + description: { type: "string" }, + merchant_raw: { type: "string" }, + account_hint: { + type: "string", + description: + 'Free-text hint about which account ("Monzo current", "HL ISA", etc.). Resolved later.', + }, + tax_relevance: { + type: "string", + enum: ["none", "income", "expense", "cgt"], + }, + gmail_message_id: { type: "string" }, + }, + }, + }, + cgt_events: { + type: "array", + items: { + type: "object", + required: [ + "asset_description", + "asset_class", + "disposal_date", + "disposal_proceeds", + "gmail_message_id", + ], + properties: { + asset_description: { type: "string" }, + asset_class: { + type: "string", + enum: [ + "listed_shares", + "unlisted_shares", + "residential_property", + "other_property", + "crypto", + "other", + ], + }, + acquisition_date: { type: "string", format: "date" }, + acquisition_cost: { type: "string" }, + disposal_date: { type: "string", format: "date" }, + disposal_proceeds: { type: "string" }, + incidental_costs: { type: "string" }, + gmail_message_id: { type: "string" }, + }, + }, + }, + dividends: { + type: "array", + items: { + type: "object", + required: ["payer", "gross", "currency", "date", "gmail_message_id"], + properties: { + payer: { type: "string" }, + gross: { type: "string" }, + currency: { type: "string" }, + date: { type: "string", format: "date" }, + country: { + type: "string", + description: "ISO 3166-1 alpha-2 if foreign", + }, + gmail_message_id: { type: "string" }, + }, + }, + }, + documents: { + type: "array", + items: { + type: "object", + required: ["doc_type", "gmail_message_id"], + properties: { + doc_type: { + type: "string", + enum: [ + "P60", + "P45", + "P11D", + "SA302", + "bank_statement", + "savings_statement", + "broker_statement", + "contract_note", + "dividend_voucher", + "mortgage_statement", + "rental_agreement", + "receipt", + "other", + ], + }, + payer_or_employer: { type: "string" }, + tax_year_hint: { + type: "string", + description: + 'Tax year label if visible on the document, e.g. "2025-26"', + }, + gmail_message_id: { type: "string" }, + }, + }, + }, + }, + }, +}); + +export default defineConfig({ + org: "personal-finance", + orgName: "Personal Finance", + orgDescription: + "UK Self Assessment helper — captures financial activity across the tax year and assembles SA100 + supplementary pages.", + agents: [personal_finance], + entities: [ + account, + allowance_window, + asset_lot, + cgt_event, + company, + contribution, + document, + expense, + filing_obligation, + goal, + holding, + income_source, + payment, + property, + relief_claim, + tax_assessment, + tax_year, + transaction, + ], + relationships: [ + account_contains, + accountant_for, + accumulates_in, + assessment_for, + co_owned_by, + controls, + director_of, + disposal_of, + employed_by, + employee_of, + expense_of, + for_tax_year, + income_from, + obligation_for, + owned_by, + parsed_from, + partner_in, + settles, + shareholder_of, + spouse_of, + transfer_pair, + ], + watchers: [gmail_txWatcher], +}); diff --git a/examples/sales/lobu.config.ts b/examples/sales/lobu.config.ts new file mode 100644 index 000000000..30abbcff0 --- /dev/null +++ b/examples/sales/lobu.config.ts @@ -0,0 +1,215 @@ +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const sales = defineAgent({ + id: "sales", + name: "sales", + description: + "Help revenue teams track account health, rollout progress, and renewal signals", + dir: "./agents/sales", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], + network: { + allowed: [ + "github.com", + ".github.com", + ".githubusercontent.com", + "registry.npmjs.org", + ".npmjs.org", + ], + }, +}); + +const organization = defineEntityType({ + key: "organization", + name: "Organization", + description: + "A customer account or prospect being tracked by the revenue team", + properties: { + company_name: { + type: "string", + "x-table-label": "Company", + "x-table-column": true, + }, + stage: { type: "string", "x-table-label": "Stage", "x-table-column": true }, + arr: { type: "string", "x-table-label": "ARR", "x-table-column": true }, + renewal_date: { + type: "string", + "x-table-label": "Renewal Date", + "x-table-column": true, + }, + }, +}); + +const product = defineEntityType({ + key: "product", + name: "Product", + description: "A product rollout or pilot being tracked at a customer account", + properties: { + product_name: { + type: "string", + "x-table-label": "Product", + "x-table-column": true, + }, + pilot_status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + owner_team: { + type: "string", + "x-table-label": "Owner", + "x-table-column": true, + }, + account: { + type: "string", + "x-table-label": "Account", + "x-table-column": true, + }, + }, +}); + +const region = defineEntityType({ + key: "region", + name: "Region", + description: "A geographic region where an account is expanding or operating", + properties: { + region_name: { + type: "string", + "x-table-label": "Region", + "x-table-column": true, + }, + expansion_status: { + type: "string", + "x-table-label": "Status", + "x-table-column": true, + }, + parent_account: { + type: "string", + "x-table-label": "Account", + "x-table-column": true, + }, + market_size: { type: "string", "x-table-label": "Market Size" }, + }, +}); + +const renewalRisk = defineEntityType({ + key: "renewal-risk", + name: "Renewal Risk", + description: + "A commercial signal or concern that affects an upcoming renewal or expansion", + properties: { + signal: { + type: "string", + "x-table-label": "Signal", + "x-table-column": true, + }, + severity: { + type: "string", + "x-table-label": "Severity", + "x-table-column": true, + }, + affects: { + type: "string", + "x-table-label": "Affects", + "x-table-column": true, + }, + next_step: { + type: "string", + "x-table-label": "Next Step", + "x-table-column": true, + }, + }, +}); + +const team = defineEntityType({ + key: "team", + name: "Team", + description: + "An internal team or customer function that owns a pilot or initiative", + properties: { + team_name: { + type: "string", + "x-table-label": "Team", + "x-table-column": true, + }, + role: { type: "string", "x-table-label": "Role", "x-table-column": true }, + owns: { type: "string", "x-table-label": "Owns", "x-table-column": true }, + account: { + type: "string", + "x-table-label": "Account", + "x-table-column": true, + }, + }, +}); + +const affects = defineRelationshipType({ + key: "affects", + name: "Affects", + description: + "Connect commercial signals directly to the renewal or expansion they influence.", +}); + +const expandedInto = defineRelationshipType({ + key: "expanded-into", + name: "Expanded Into", + description: + "Track where an account is growing so territory and rollout context stay explicit.", +}); + +const runs = defineRelationshipType({ + key: "runs", + name: "Runs", + description: + "Link the internal team or customer function to the pilot they own.", +}); + +const accountHealthMonitor = defineWatcher({ + agent: sales, + slug: "account-health-monitor", + name: "Account health monitor", + schedule: "0 */12 * * *", + notification: { priority: "high", channel: "both" }, + tags: ["sales", "health", "renewals"], + minCooldownSeconds: 1800, + reaction: "./models/reactions/account-health-monitor.reaction.ts", + prompt: + "Poll CRM data for tracked accounts. Track expansion progress, risk level changes, and renewal timeline.\n", + extractionSchema: { + type: "object", + required: [ + "risk_level", + "expansion_status", + "renewal_blockers", + "activity_delta", + ], + properties: { + risk_level: { type: "string" }, + expansion_status: { type: "string" }, + renewal_blockers: { type: "array", items: { type: "string" } }, + activity_delta: { type: "string" }, + }, + }, +}); + +export default defineConfig({ + org: "sales", + orgName: "Sales", + orgDescription: + "Help revenue teams track account health, rollout progress, and renewal signals", + agents: [sales], + entities: [organization, product, region, renewalRisk, team], + relationships: [affects, expandedInto, runs], + watchers: [accountHealthMonitor], +}); From 2d8018964b9155925d5859ff14be7af8d3378d4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 01:31:10 +0100 Subject: [PATCH 19/65] refactor(cli): migrate every command off the TOML loader to lobu.config.ts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extract loadProjectConfig (bundle+import lobu.config.ts → SDK Project) and route all consumers through it / the TS loader: apply drops the lobu.toml fallback (always loadDesiredStateFromConfig); doctor, chat, validate, and dev's preview-bot registration read the SDK Project; dev's auto-apply gate keys on lobu.config.ts. Drop writeMemoryOrganizationId — TS projects carry org/ organizationId in defineConfig + the .lobu/project.json link, so apply never rewrites the config file. Update the dryrun + dev tests to lobu.config.ts fixtures (under the worktree so the externalized @lobu/sdk import resolves). The TOML loader (loadDesiredState/loadConnectors/parse*, config/loader, lobu-toml-schema) is now dead and removed in the next commit. --- packages/cli/src/__tests__/dev.test.ts | 10 +- .../apply/__tests__/apply-cmd-dryrun.test.ts | 91 +++++------ .../cli/src/commands/_lib/apply/apply-cmd.ts | 49 +----- .../src/commands/_lib/apply/desired-state.ts | 143 ++++++++++-------- packages/cli/src/commands/chat.ts | 12 +- packages/cli/src/commands/dev.ts | 31 ++-- packages/cli/src/commands/doctor.ts | 18 ++- packages/cli/src/commands/validate.ts | 34 ++--- 8 files changed, 177 insertions(+), 211 deletions(-) diff --git a/packages/cli/src/__tests__/dev.test.ts b/packages/cli/src/__tests__/dev.test.ts index 9d3f71a49..5fad87063 100644 --- a/packages/cli/src/__tests__/dev.test.ts +++ b/packages/cli/src/__tests__/dev.test.ts @@ -274,7 +274,7 @@ describe("shouldAutoApplyLocalProject", () => { shouldAutoApplyLocalProject({ mode: "embedded", localContextReady: true, - hasLobuToml: true, + hasLobuConfig: true, }) ).toBe(true); }); @@ -286,7 +286,7 @@ describe("shouldAutoApplyLocalProject", () => { shouldAutoApplyLocalProject({ mode: "embedded", localContextReady: false, - hasLobuToml: true, + hasLobuConfig: true, }) ).toBe(false); }); @@ -296,17 +296,17 @@ describe("shouldAutoApplyLocalProject", () => { shouldAutoApplyLocalProject({ mode: "external", localContextReady: true, - hasLobuToml: true, + hasLobuConfig: true, }) ).toBe(false); }); - test("skips when the project has no lobu.toml to apply", () => { + test("skips when the project has no lobu.config.ts to apply", () => { expect( shouldAutoApplyLocalProject({ mode: "embedded", localContextReady: true, - hasLobuToml: false, + hasLobuConfig: false, }) ).toBe(false); }); diff --git a/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd-dryrun.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd-dryrun.test.ts index f450ce415..340d858b4 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd-dryrun.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd-dryrun.test.ts @@ -16,7 +16,6 @@ import { test, } from "bun:test"; import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; import { join } from "node:path"; import { applyCommand } from "../apply-cmd.js"; import * as context from "../../../../internal/context.js"; @@ -46,17 +45,31 @@ function silenceOutput() { spyOn(process.stdout, "write").mockImplementation(silentWrite); } -function mkProject(toml: string): string { - const dir = mkdtempSync(join(tmpdir(), "lobu-apply-dry-")); +// Fixtures live under the worktree (next to this test) so the externalized +// `@lobu/sdk` import in the generated config bundle resolves from node_modules. +function mkProject(config: string): string { + const dir = mkdtempSync(join(import.meta.dir, "fixture-")); tempDirs.push(dir); - writeFileSync(join(dir, "lobu.toml"), toml); + writeFileSync(join(dir, "lobu.config.ts"), config); return dir; } -function minimalToml(agentId = "triage") { - return `[agents.${agentId}] -name = "Triage" -dir = "./agents/${agentId}" +function minimalConfig( + agentId = "triage", + opts: { org?: string; organizationId?: string } = {} +) { + const extra = [ + opts.org ? ` org: ${JSON.stringify(opts.org)},` : "", + opts.organizationId + ? ` organizationId: ${JSON.stringify(opts.organizationId)},` + : "", + ] + .filter(Boolean) + .join("\n"); + return `import { defineAgent, defineConfig } from "@lobu/sdk"; +export default defineConfig({ +${extra ? `${extra}\n` : ""} agents: [defineAgent({ id: ${JSON.stringify(agentId)}, name: "Triage", dir: "./agents/${agentId}" })], +}); `; } @@ -138,7 +151,7 @@ describe("applyCommand --dry-run", () => { }); test("dry-run with one agent: no resource-creating/mutating API calls are made", async () => { - const dir = mkProject(minimalToml()); + const dir = mkProject(minimalConfig()); mkdirSync(join(dir, "agents", "triage"), { recursive: true }); const { fetchStub, mutateCalls } = makeAuthFetch([ @@ -180,36 +193,6 @@ describe("applyCommand --dry-run", () => { expect(writingCalls).toEqual([]); }); - - test("dry-run does NOT write organization_id back to lobu.toml", async () => { - const toml = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -org = "acme" -`; - const dir = mkProject(toml); - mkdirSync(join(dir, "agents", "triage"), { recursive: true }); - - const { fetchStub } = makeAuthFetch([ - { id: "org_99", slug: "acme", name: "Acme" }, - ]); - - await applyCommand({ - cwd: dir, - dryRun: true, - yes: true, - url: "https://app.lobu.ai", - org: "acme", - fetchImpl: fetchStub, - }); - - // lobu.toml must NOT have been modified: organization_id should be absent. - const { readFileSync } = await import("node:fs"); - const contents = readFileSync(join(dir, "lobu.toml"), "utf-8"); - expect(contents).not.toContain("organization_id"); - }); }); // ── Test: org not found → ValidationError with create-url ─────────────────── @@ -231,7 +214,7 @@ describe("applyCommand org resolution", () => { }); test("throws ValidationError when the target org is not in the user's org list", async () => { - const dir = mkProject(minimalToml()); + const dir = mkProject(minimalConfig()); mkdirSync(join(dir, "agents", "triage"), { recursive: true }); // User belongs to a different org @@ -252,7 +235,7 @@ describe("applyCommand org resolution", () => { }); test("throws ValidationError when user belongs to 0 orgs", async () => { - const dir = mkProject(minimalToml()); + const dir = mkProject(minimalConfig()); mkdirSync(join(dir, "agents", "triage"), { recursive: true }); const { fetchStub } = makeAuthFetch([]); @@ -270,7 +253,7 @@ describe("applyCommand org resolution", () => { }); test("succeeds (dry-run) when the user belongs to exactly 1 org that matches", async () => { - const dir = mkProject(minimalToml()); + const dir = mkProject(minimalConfig()); mkdirSync(join(dir, "agents", "triage"), { recursive: true }); const { fetchStub } = makeAuthFetch([ @@ -290,16 +273,10 @@ describe("applyCommand org resolution", () => { ).resolves.toBeUndefined(); }); - test("org can also be matched by organizationId in lobu.toml when slug differs", async () => { - const toml = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -org = "acme" -organization_id = "org_id_42" -`; - const dir = mkProject(toml); + test("org can also be matched by organizationId in the config when slug differs", async () => { + const dir = mkProject( + minimalConfig("triage", { org: "acme", organizationId: "org_id_42" }) + ); mkdirSync(join(dir, "agents", "triage"), { recursive: true }); // The slug doesn't match ("acme" vs "wrong-slug") but the id matches. @@ -321,9 +298,9 @@ organization_id = "org_id_42" }); }); -// ── Test: missing lobu.toml ────────────────────────────────────────────────── +// ── Test: missing lobu.config.ts ───────────────────────────────────────────── -describe("applyCommand — missing lobu.toml", () => { +describe("applyCommand — missing lobu.config.ts", () => { beforeEach(() => { silenceOutput(); spyOn(context, "resolveContext").mockResolvedValue({ @@ -339,10 +316,10 @@ describe("applyCommand — missing lobu.toml", () => { }); }); - test("throws a ValidationError when lobu.toml is absent", async () => { - const dir = mkdtempSync(join(tmpdir(), "lobu-no-toml-")); + test("throws a ValidationError when lobu.config.ts is absent", async () => { + const dir = mkdtempSync(join(import.meta.dir, "no-config-")); tempDirs.push(dir); - // No lobu.toml created + // No lobu.config.ts created const { fetchStub } = makeAuthFetch([{ id: "o1", slug: "acme" }]); diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index 2f74c42ed..f7c4fee5f 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -1,11 +1,9 @@ -import { existsSync } from "node:fs"; -import { readFile, writeFile } from "node:fs/promises"; +import { readFile } from "node:fs/promises"; import { join } from "node:path"; import chalk from "chalk"; import { resolveContext } from "../../../internal/context.js"; import { parseEnvContent } from "../../../internal/env-file.js"; import { loadProjectLink } from "../../../internal/project-link.js"; -import { CONFIG_FILENAME } from "../../../config/loader.js"; import { ApiError, ValidationError } from "../../memory/_lib/errors.js"; import { printError, printText } from "../../memory/_lib/output.js"; import { @@ -25,7 +23,6 @@ import { import { type DesiredConnectorDefinition, type DesiredState, - loadDesiredState, loadDesiredStateFromConfig, resolveConnectorSchemas, validateAuthProfileAgainstConnector, @@ -39,31 +36,6 @@ import { renderProgress, } from "./render.js"; -/** - * Write `organization_id = ""` into the `[memory]` section of lobu.toml — - * replacing an existing value or inserting it just under the `[memory]` header. - * Surgical text edit; preserves comments and the rest of the file. - */ -async function writeMemoryOrganizationId( - cwd: string, - organizationId: string -): Promise { - const path = join(cwd, CONFIG_FILENAME); - const raw = await readFile(path, "utf-8"); - const line = `organization_id = "${organizationId}"`; - - if (/^\s*organization_id\s*=.*$/m.test(raw)) { - const next = raw.replace(/^\s*organization_id\s*=.*$/m, line); - if (next !== raw) await writeFile(path, next); - return; - } - - const header = raw.match(/^\[memory\][^\n]*$/m); - if (!header || header.index === undefined) return; - const at = header.index + header[0].length; - await writeFile(path, `${raw.slice(0, at)}\n${line}${raw.slice(at)}`); -} - export interface ApplyOptions { cwd?: string; dryRun?: boolean; @@ -1009,11 +981,9 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { // `lobu dev` does. Existing process.env values win (don't clobber the shell). await loadProjectEnvFile(cwd); - // Prefer the TypeScript entrypoint (lobu.config.ts); fall back to lobu.toml. + // Load desired state from the TypeScript entrypoint (lobu.config.ts). const loadArgs = { cwd, ...(opts.only ? { only: opts.only } : {}) }; - const { state, configPath } = existsSync(join(cwd, "lobu.config.ts")) - ? await loadDesiredStateFromConfig(loadArgs) - : await loadDesiredState(loadArgs); + const { state, configPath } = await loadDesiredStateFromConfig(loadArgs); printText(chalk.dim(`Config: ${configPath}`)); @@ -1094,16 +1064,9 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { throw new ValidationError(`organization "${orgSlug}" not found`); } - // Persist the resolved org id back into lobu.toml so the whole team applies - // to the same org. Best-effort — a read-only lobu.toml must not fail apply. - // Skipped on `--dry-run`: that flag promises no mutation, local files included. - if ( - !opts.dryRun && - resolvedOrg && - state.memory?.organizationId !== resolvedOrg.id - ) { - await writeMemoryOrganizationId(cwd, resolvedOrg.id).catch(() => undefined); - } + // Team org consistency comes from `defineConfig({ org, organizationId })` in + // lobu.config.ts (committed) plus the `.lobu/project.json` link — apply does + // not rewrite the config file. // SECURITY (#4): confirm BEFORE fetching any `source_url` or uploading custom // connector source — `lobu apply --dry-run` should never hit a manifest URL. diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index df9ccc5d6..ce80dd105 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -2134,27 +2134,28 @@ function resolveReactionScript( } /** - * Load desired state from a TypeScript entrypoint (`lobu.config.ts`) instead of - * `lobu.toml`. Bundles the entrypoint with esbuild (relative imports inlined; - * node_modules — including `@lobu/sdk` / `@lobu/connector-sdk` — externalized so - * they resolve from the project at import time), imports the bundle to read the - * `defineConfig()` default export, and maps it to `DesiredState`. + * Bundle + import a `lobu.config.ts` and return its `defineConfig` default + * export (the SDK {@link Project}). Shared by {@link loadDesiredStateFromConfig} + * (apply) and the commands that read the authored config directly (`lobu run` + * preview registration, `lobu doctor`, `lobu chat`, `lobu validate`). + * + * esbuild bundles relative imports inline and externalizes node_modules + * (`@lobu/sdk` / `@lobu/connector-sdk` resolve from the project at import time). + * The temp `.mjs` is deleted after import — the module is already in memory. * * The dynamic imports here are intentional and allow-listed (AGENTS.md): esbuild - * is loaded lazily so the TOML path doesn't pay for it, and the bundled config - * is a generated file imported by URL. + * is loaded lazily, and the bundled config is a generated file imported by URL. */ -export async function loadDesiredStateFromConfig( - opts: LoadDesiredStateOptions -): Promise<{ state: DesiredState; configPath: string }> { - const configPath = resolve(opts.cwd, "lobu.config.ts"); +export async function loadProjectConfig( + cwd: string +): Promise<{ project: Project; configPath: string }> { + const configPath = resolve(cwd, "lobu.config.ts"); if (!existsSync(configPath)) { - throw new ValidationError(`No lobu.config.ts found in ${opts.cwd}`); + throw new ValidationError(`No lobu.config.ts found in ${cwd}`); } - const env = opts.env ?? process.env; const { build } = await import("esbuild"); const outFile = resolve( - opts.cwd, + cwd, `.lobu-config.${randomBytes(6).toString("hex")}.mjs` ); try { @@ -2180,60 +2181,68 @@ export async function loadDesiredStateFromConfig( "lobu.config.ts must `export default defineConfig({ ... })`" ); } - const typedProject = project as Project; - const state = mapProjectToDesiredState(typedProject, env, opts.only); - - // Agent-directory artifacts: SOUL/IDENTITY/USER.md + local skills. The - // mapper stays pure (no file IO); we read the files here and merge them into - // each agent's settings, mirroring the TOML loader (project `./skills` + - // per-agent `/skills`; default dir `./agents/`). - await Promise.all( - typedProject.agents.map(async (agent, i) => { - const settings = state.agents[i]?.settings; - if (!settings) return; - const agentDir = resolve( - opts.cwd, - agent.dir ?? join("agents", agent.id) - ); - const markdown = await readMarkdown(agentDir); - const skillFiles = await loadSkillFiles([ - join(opts.cwd, "skills"), - join(agentDir, "skills"), - ]); - mergeAgentDirArtifacts( - settings, - markdown, - buildLocalSkills(skillFiles) - ); - }) - ); - - // Watcher reaction scripts: a sibling `.ts` file referenced by path. The - // mapper stays pure; resolve + read the source here (raw, server compiles - // it) and attach it. state.watchers[i] aligns with typedProject.watchers[i] - // (the mapper maps them in order). - (typedProject.watchers ?? []).forEach((watcher, i) => { - // Gate on absence, not truthiness — a present-but-empty `reaction: ""` - // must reach the validator (which rejects it), matching parseWatcher. - if (watcher.reaction === undefined) return; - const dw = state.watchers[i]; - if (!dw) return; - dw.reactionScript = resolveReactionScript( - opts.cwd, - watcher.slug, - watcher.reaction - ); - }); - - // `--only agents|memory` skips connectors (matching the mapper), so don't - // ship local connector source for those runs either. - if (!opts.only) { - state.connectors.definitions = await discoverLocalConnectorDefinitions( - opts.cwd - ); - } - return { state, configPath }; + return { project: project as Project, configPath }; } finally { rmSync(outFile, { force: true }); } } + +/** + * Load desired state from a TypeScript entrypoint (`lobu.config.ts`): import the + * `defineConfig()` project, map it to `DesiredState`, then attach the + * file-based artifacts (agent-dir markdown + skills, watcher reaction scripts, + * local connector source). + */ +export async function loadDesiredStateFromConfig( + opts: LoadDesiredStateOptions +): Promise<{ state: DesiredState; configPath: string }> { + const env = opts.env ?? process.env; + const { project: typedProject, configPath } = await loadProjectConfig( + opts.cwd + ); + const state = mapProjectToDesiredState(typedProject, env, opts.only); + + // Agent-directory artifacts: SOUL/IDENTITY/USER.md + local skills. The + // mapper stays pure (no file IO); we read the files here and merge them into + // each agent's settings, mirroring the TOML loader (project `./skills` + + // per-agent `/skills`; default dir `./agents/`). + await Promise.all( + typedProject.agents.map(async (agent, i) => { + const settings = state.agents[i]?.settings; + if (!settings) return; + const agentDir = resolve(opts.cwd, agent.dir ?? join("agents", agent.id)); + const markdown = await readMarkdown(agentDir); + const skillFiles = await loadSkillFiles([ + join(opts.cwd, "skills"), + join(agentDir, "skills"), + ]); + mergeAgentDirArtifacts(settings, markdown, buildLocalSkills(skillFiles)); + }) + ); + + // Watcher reaction scripts: a sibling `.ts` file referenced by path. The + // mapper stays pure; resolve + read the source here (raw, server compiles + // it) and attach it. state.watchers[i] aligns with typedProject.watchers[i] + // (the mapper maps them in order). + (typedProject.watchers ?? []).forEach((watcher, i) => { + // Gate on absence, not truthiness — a present-but-empty `reaction: ""` + // must reach the validator (which rejects it), matching parseWatcher. + if (watcher.reaction === undefined) return; + const dw = state.watchers[i]; + if (!dw) return; + dw.reactionScript = resolveReactionScript( + opts.cwd, + watcher.slug, + watcher.reaction + ); + }); + + // `--only agents|memory` skips connectors (matching the mapper), so don't + // ship local connector source for those runs either. + if (!opts.only) { + state.connectors.definitions = await discoverLocalConnectorDefinitions( + opts.cwd + ); + } + return { state, configPath }; +} diff --git a/packages/cli/src/commands/chat.ts b/packages/cli/src/commands/chat.ts index c83272338..9950090a2 100644 --- a/packages/cli/src/commands/chat.ts +++ b/packages/cli/src/commands/chat.ts @@ -11,7 +11,7 @@ import { resolveGatewayUrl, } from "../internal/index.js"; import { LOBU_CONFIG_DIR } from "../internal/context.js"; -import { isLoadError, loadConfig } from "../config/loader.js"; +import { loadProjectConfig } from "./_lib/apply/desired-state.js"; import { renderMarkdown } from "../utils/markdown.js"; const THREADS_FILE = join(LOBU_CONFIG_DIR, "threads.json"); @@ -339,10 +339,12 @@ async function sendViaApi( } async function resolveAgentId(cwd: string): Promise { - const result = await loadConfig(cwd); - if (isLoadError(result)) return undefined; - const ids = Object.keys(result.config.agents); - return ids[0]; + try { + const { project } = await loadProjectConfig(cwd); + return project.agents[0]?.id; + } catch { + return undefined; + } } async function writeStdout(text: string): Promise { diff --git a/packages/cli/src/commands/dev.ts b/packages/cli/src/commands/dev.ts index a4bf46c55..9ea1cf414 100644 --- a/packages/cli/src/commands/dev.ts +++ b/packages/cli/src/commands/dev.ts @@ -8,7 +8,7 @@ import { dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import chalk from "chalk"; import ora from "ora"; -import { isLoadError, loadConfig } from "../config/loader.js"; +import { loadProjectConfig } from "./_lib/apply/desired-state.js"; import { resolveApiClient } from "../internal/api-client.js"; import { addContext, @@ -381,7 +381,7 @@ export async function devCommand( shouldAutoApplyLocalProject({ mode, localContextReady, - hasLobuToml: existsSync(join(cwd, "lobu.toml")), + hasLobuConfig: existsSync(join(cwd, "lobu.config.ts")), }) ) { return autoApplyLocalProject(cwd, gatewayUrl); @@ -418,14 +418,16 @@ export async function devCommand( * - the backend is embedded (never auto-mutate an external/prod DB), AND * - the `local` context was registered + made active (so the apply targets the * embedded server, not whatever cloud context was active before), AND - * - the project actually has a `lobu.toml` to apply. + * - the project actually has a `lobu.config.ts` to apply. */ export function shouldAutoApplyLocalProject(opts: { mode: "external" | "embedded"; localContextReady: boolean; - hasLobuToml: boolean; + hasLobuConfig: boolean; }): boolean { - return opts.mode === "embedded" && opts.localContextReady && opts.hasLobuToml; + return ( + opts.mode === "embedded" && opts.localContextReady && opts.hasLobuConfig + ); } /** @@ -670,18 +672,25 @@ export function isPortFree(port: number): Promise { } async function printPreviewInstructions(cwd: string): Promise { - const loaded = await loadConfig(cwd); - if (isLoadError(loaded)) return; + let agents: Awaited< + ReturnType + >["project"]["agents"]; + try { + agents = (await loadProjectConfig(cwd)).project.agents; + } catch { + return; + } // `agent.preview` is a record keyed by chat platform (`slack`, `telegram`, …). const enabled: Array<{ agentId: string; platform: string; - cfg: { surfaces?: string[]; code_ttl_minutes?: number }; + cfg: { surfaces?: Array<"dm" | "channel">; codeTtlMinutes?: number }; }> = []; - for (const [agentId, agent] of Object.entries(loaded.config.agents)) { + for (const agent of agents) { for (const [platform, cfg] of Object.entries(agent.preview ?? {})) { - if (cfg?.enabled === true) enabled.push({ agentId, platform, cfg }); + if (cfg?.enabled === true) + enabled.push({ agentId: agent.id, platform, cfg }); } } if (enabled.length === 0) return; @@ -720,7 +729,7 @@ async function printPreviewInstructions(cwd: string): Promise { agent_id: agentId, platform, surfaces: cfg.surfaces ?? ["dm"], - ttl_minutes: cfg.code_ttl_minutes ?? 15, + ttl_minutes: cfg.codeTtlMinutes ?? 15, }); console.log(chalk.dim(` agent: ${agentId}`)); console.log(chalk.dim(` platform: ${platform}`)); diff --git a/packages/cli/src/commands/doctor.ts b/packages/cli/src/commands/doctor.ts index 2b0f3255b..d949a9d5f 100644 --- a/packages/cli/src/commands/doctor.ts +++ b/packages/cli/src/commands/doctor.ts @@ -8,7 +8,7 @@ import { resolveServerUrl } from "./memory/_lib/openclaw-auth.js"; import { isPortFree } from "./dev.js"; import { parseEnvContent } from "../internal/env-file.js"; import { loadProviderRegistry } from "./providers/registry.js"; -import { isLoadError, loadConfig } from "../config/loader.js"; +import { loadProjectConfig } from "./_lib/apply/desired-state.js"; interface Check { name: string; @@ -136,16 +136,24 @@ async function checkProviderKeys( cwd: string, env: Record ): Promise { - const result = await loadConfig(cwd); - if (isLoadError(result)) return []; + let agents: Awaited< + ReturnType + >["project"]["agents"]; + try { + agents = (await loadProjectConfig(cwd)).project.agents; + } catch { + return []; + } const registry = loadProviderRegistry(); const checks: Check[] = []; const seen = new Set(); - for (const agent of Object.values(result.config.agents)) { + for (const agent of agents) { for (const provider of agent.providers ?? []) { - const reg = registry.find((r) => r.id === provider.id); + const reg = registry.find( + (r) => r.id === (provider.id ?? provider.model) + ); const envVar = reg?.providers?.[0]?.envVarName; if (!envVar || seen.has(envVar)) continue; seen.add(envVar); diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts index bc6c406da..4eba6b86b 100644 --- a/packages/cli/src/commands/validate.ts +++ b/packages/cli/src/commands/validate.ts @@ -1,35 +1,33 @@ import chalk from "chalk"; -import { isLoadError, loadConfig } from "../config/loader.js"; +import { loadDesiredStateFromConfig } from "./_lib/apply/desired-state.js"; export async function validateCommand(cwd: string): Promise { - const result = await loadConfig(cwd); - - if (isLoadError(result)) { - console.error(chalk.red(`\n ${result.error}`)); - if (result.details) { - for (const detail of result.details) { - console.error(chalk.dim(` ${detail}`)); - } - } + let state: Awaited>["state"]; + try { + // Loading runs the full structural validation: slug/cron checks, watcher + // agent refs, reaction-script paths, connector/auth shapes, etc. Secrets + // are not required here (the gate runs at `lobu apply`). + ({ state } = await loadDesiredStateFromConfig({ cwd })); + } catch (err) { + console.error( + chalk.red(`\n ${err instanceof Error ? err.message : String(err)}`) + ); console.log(); return false; } - const { config } = result; const warnings: string[] = []; - - for (const [agentId, agentEntry] of Object.entries(config.agents)) { - if (agentEntry.providers.length === 0) { + for (const agent of state.agents) { + if (!agent.settings.installedProviders?.length) { warnings.push( - `[agents.${agentId}] No providers configured. Agent will need provider keys at runtime.` + `agent "${agent.metadata.agentId}" has no providers configured. It will need provider keys at runtime.` ); } } - const agentCount = Object.keys(config.agents).length; console.log(); - console.log(chalk.green(` lobu.toml is valid`)); - console.log(chalk.dim(` ${agentCount} agent(s) configured`)); + console.log(chalk.green(` lobu.config.ts is valid`)); + console.log(chalk.dim(` ${state.agents.length} agent(s) configured`)); for (const warn of warnings) { console.log(chalk.yellow(` ${warn}`)); } From 9d2daa2f8664035d43181245e71b9aa952bc8584 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 01:48:40 +0100 Subject: [PATCH 20/65] refactor(cli): seed memory from lobu.config.ts instead of lobu.toml + YAML MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `lobu memory seed` read [memory] from lobu.toml and entity/relationship/watcher schema from models/*.yaml. Migrate it onto loadDesiredStateFromConfig: org + entity/relationship types now come from lobu.config.ts (same source apply uses, seeding stays idempotent). Drop watcher seeding — watchers are agent-scoped and provisioned by `lobu apply`, not the old entity-scoped models path. The ./data instance seeding (entities + relationships) is unchanged. This removes seed's last dependency on the TOML/YAML loader, unblocking its deletion. --- .../cli/src/commands/memory/_lib/seed-cmd.ts | 309 +++++------------- 1 file changed, 73 insertions(+), 236 deletions(-) diff --git a/packages/cli/src/commands/memory/_lib/seed-cmd.ts b/packages/cli/src/commands/memory/_lib/seed-cmd.ts index 47e0e3215..35719d29a 100644 --- a/packages/cli/src/commands/memory/_lib/seed-cmd.ts +++ b/packages/cli/src/commands/memory/_lib/seed-cmd.ts @@ -1,7 +1,11 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; -import { basename, dirname, isAbsolute, join, resolve } from "node:path"; -import { parse as parseToml } from "smol-toml"; +import { basename, dirname, join, resolve } from "node:path"; import { parse as parseYaml } from "yaml"; +import type { + DesiredEntityType, + DesiredRelationshipType, +} from "../../_lib/apply/desired-state.js"; +import { loadDesiredStateFromConfig } from "../../_lib/apply/desired-state.js"; import { ApiError, ValidationError } from "./errors.js"; import { getSessionForOrg, @@ -14,14 +18,10 @@ import { import { printError, printText } from "./output.js"; import { type DataRecordType, - type ModelType, type ValidationError as SchemaError, type SeedEntitySchema, type SeedRelationshipSchema, - expandModelDefinition, - parseModelYamlFile, validateDataRecord, - validateModel, } from "./schema.js"; interface SeedContext { @@ -31,50 +31,22 @@ interface SeedContext { dryRun: boolean; } -interface ParsedModel { - data: Record; - file: string; - modelType: ModelType; -} - interface ParsedDataRecord { data: Record; file: string; recordType: DataRecordType; } +/** + * Where seed reads from: the project's `lobu.config.ts` (schema + org) plus an + * optional `./data` directory of YAML data records to instantiate. + */ interface ProjectLayout { - projectRoot: string; - projectPath: string; - modelsPath: string; + cwd: string; + configPath: string; dataPath: string; org: string; name: string; - description?: string; -} - -function readYamlModelFilesRecursive( - dir: string, - prefix = "" -): Array<{ raw: string; file: string }> { - if (!existsSync(dir)) return []; - - return readdirSync(dir, { withFileTypes: true }) - .sort((a, b) => a.name.localeCompare(b.name)) - .flatMap((entry) => { - const relPath = prefix ? join(prefix, entry.name) : entry.name; - const fullPath = join(dir, entry.name); - if (entry.isDirectory()) { - return readYamlModelFilesRecursive(fullPath, relPath); - } - if ( - !entry.isFile() || - (!entry.name.endsWith(".yaml") && !entry.name.endsWith(".yml")) - ) { - return []; - } - return [{ raw: readFileSync(fullPath, "utf8"), file: relPath }]; - }); } function readYamlFilesRecursive( @@ -120,114 +92,38 @@ function checkErrors(errors: SchemaError[]): void { } } -function resolveProjectLayout(inputPath?: string): ProjectLayout { - const requestedPath = resolve(inputPath || "."); - - let projectPath: string; - let projectRoot: string; - if (existsSync(requestedPath) && statSync(requestedPath).isFile()) { - if (basename(requestedPath) !== "lobu.toml") { +/** + * Resolve the project + its desired state from `lobu.config.ts`. Entity types, + * relationship types, and org metadata come from the config (the same source + * `lobu apply` uses); `./data` holds the YAML data records to instantiate. + */ +async function resolveProjectLayout(inputPath?: string): Promise<{ + layout: ProjectLayout; + state: Awaited>["state"]; +}> { + const requested = resolve(inputPath || "."); + let cwd: string; + if (existsSync(requested) && statSync(requested).isFile()) { + if (basename(requested) !== "lobu.config.ts") { throw new ValidationError( - `Expected a lobu.toml file, got ${basename(requestedPath)}` + `Expected a lobu.config.ts file, got ${basename(requested)}` ); } - projectPath = requestedPath; - projectRoot = dirname(requestedPath); + cwd = dirname(requested); } else { - projectPath = join(requestedPath, "lobu.toml"); - projectRoot = requestedPath; - if (!existsSync(projectPath)) { - throw new ValidationError(`Could not find lobu.toml at ${projectPath}`); - } + cwd = requested; } - const toml = parseToml(readFileSync(projectPath, "utf8")) as Record< - string, - unknown - >; - const memory = toml.memory as Record | undefined; - - if (!memory) { - throw new ValidationError( - `lobu.toml at ${projectPath} is missing a [memory] section` - ); - } - if (memory.enabled === false) { - throw new ValidationError( - `[memory] in ${projectPath} is disabled (enabled = false)` - ); - } - - const org = typeof memory.org === "string" ? memory.org.trim() : ""; - const name = typeof memory.name === "string" ? memory.name.trim() : ""; + const { state, configPath } = await loadDesiredStateFromConfig({ cwd }); + const org = state.memory?.org?.trim() ?? ""; if (!org) { throw new ValidationError( - `[memory] in ${projectPath} is missing required field "org"` - ); - } - if (!name) { - throw new ValidationError( - `[memory] in ${projectPath} is missing required field "name"` + "lobu.config.ts must set `org` in defineConfig({ org: ... }) to seed memory" ); } - - const description = - typeof memory.description === "string" ? memory.description : undefined; - const modelsRel = - typeof memory.models === "string" && memory.models.trim() - ? memory.models - : "./models"; - const dataRel = - typeof memory.data === "string" && memory.data.trim() - ? memory.data - : "./data"; - - const modelsPath = isAbsolute(modelsRel) - ? modelsRel - : resolve(projectRoot, modelsRel); - const dataPath = isAbsolute(dataRel) - ? dataRel - : resolve(projectRoot, dataRel); - - return { - projectRoot, - projectPath, - modelsPath, - dataPath, - org, - name, - description, - }; -} - -/** - * Load models from every YAML file under the `models/` directory. - */ -function loadModels(modelsPath: string): ParsedModel[] { - const models: ParsedModel[] = []; - const errors: SchemaError[] = []; - for (const { raw, file } of readYamlModelFilesRecursive(modelsPath)) { - const { documents, errors: parseErrors } = parseModelYamlFile(raw, file); - errors.push(...parseErrors); - for (const { data: document, file: documentFile } of documents) { - const expanded = expandModelDefinition(document, documentFile); - errors.push(...expanded.errors); - for (const model of expanded.models) { - const modelErrors = validateModel(model.data, model.file); - if (modelErrors.length > 0) { - errors.push(...modelErrors); - } else { - models.push({ - data: model.data, - file: model.file, - modelType: model.modelType, - }); - } - } - } - } - checkErrors(errors); - return models; + const name = state.memory?.name?.trim() || org; + const dataPath = resolve(cwd, "data"); + return { layout: { cwd, configPath, dataPath, org, name }, state }; } function loadDataRecords(dataPath: string): ParsedDataRecord[] { @@ -283,20 +179,26 @@ async function callTool( } async function seedEntity( - entity: Record, + entity: DesiredEntityType, ctx: SeedContext ): Promise { - const slug = entity.slug as string; + const slug = entity.slug; if (ctx.dryRun) { printText(` [dry-run] would create entity_type: ${slug}`); return; } + // Same payload `lobu apply` sends to manage_entity_schema (upsertEntityType). + const payload = { + schema_type: "entity_type", + action: "create", + slug: entity.slug, + ...(entity.name ? { name: entity.name } : {}), + ...(entity.description ? { description: entity.description } : {}), + ...(entity.required ? { required: entity.required } : {}), + ...(entity.properties ? { properties: entity.properties } : {}), + }; try { - await callTool(ctx, "manage_entity_schema", { - schema_type: "entity_type", - action: "create", - ...entity, - }); + await callTool(ctx, "manage_entity_schema", payload); printText(` + entity_type: ${slug}`); } catch (e) { if (e instanceof Error && e.message?.includes("already exists")) { @@ -308,17 +210,19 @@ async function seedEntity( } async function seedRelationshipType( - rel: Record, + rel: DesiredRelationshipType, ctx: SeedContext ): Promise { - const slug = rel.slug as string; - const rules = Array.isArray(rel.rules) - ? (rel.rules as Array>) - : []; - // Strip `rules` from the create payload — the backend's manage_entity_schema - // create handler doesn't accept it; rules are registered via separate - // add_rule calls below. - const { rules: _unused, ...createPayload } = rel as Record; + const slug = rel.slug; + const rules = rel.rules ?? []; + // Rules are registered via separate add_rule calls — the create handler + // doesn't accept them inline. + const createPayload = { + schema_type: "relationship_type", + slug: rel.slug, + ...(rel.name ? { name: rel.name } : {}), + ...(rel.description ? { description: rel.description } : {}), + }; if (ctx.dryRun) { printText(` [dry-run] would create relationship_type: ${slug}`); @@ -329,17 +233,15 @@ async function seedRelationshipType( } try { await callTool(ctx, "manage_entity_schema", { - schema_type: "relationship_type", - action: "create", ...createPayload, + action: "create", }); printText(` + relationship_type: ${slug}`); } catch (e) { if (e instanceof Error && e.message?.includes("already exists")) { await callTool(ctx, "manage_entity_schema", { - schema_type: "relationship_type", - action: "update", ...createPayload, + action: "update", }); printText(` = relationship_type: ${slug} (updated)`); } else { @@ -528,64 +430,6 @@ async function seedDataRelationship( } } -async function seedWatcher( - watcher: Record, - entityMap: Map, - ctx: SeedContext -): Promise { - const payload = { ...watcher }; - const slug = payload.slug as string; - - if (typeof payload.entity === "string") { - const entityId = resolveEntityRef(entityMap, payload.entity); - if (entityId) { - payload.entity_id = entityId; - } else { - printError( - ` ! watcher: ${slug} - unknown entity ref "${payload.entity}", skipping` - ); - return; - } - delete payload.entity; - } - - if (!payload.entity_id) { - const fallbackEntityId = entityMap.values().next().value as - | number - | undefined; - if (fallbackEntityId) { - payload.entity_id = fallbackEntityId; - printText( - ` ~ watcher: ${slug} - no entity specified, using first seeded entity (${fallbackEntityId})` - ); - } - } - - if (!payload.entity_id) { - printError(` ! watcher: ${slug} - no entity_id available, skipping`); - return; - } - - if (ctx.dryRun) { - printText(` [dry-run] would create watcher: ${slug}`); - return; - } - - try { - await callTool(ctx, "manage_watchers", { - action: "create", - ...payload, - }); - printText(` + watcher: ${slug}`); - } catch (e) { - if (e instanceof Error && e.message?.includes("already exists")) { - printText(` = watcher: ${slug} (exists)`); - } else { - throw e; - } - } -} - async function resolveAuth( urlFlag?: string, orgFlag?: string, @@ -644,7 +488,7 @@ export interface SeedOptions { export async function seedMemoryWorkspace( opts: SeedOptions = {} ): Promise { - const layout = resolveProjectLayout(opts.path); + const { layout, state } = await resolveProjectLayout(opts.path); const orgOverride = opts.org || layout.org; const { token, mcpUrl, orgSlug } = await resolveAuth( @@ -657,16 +501,16 @@ export async function seedMemoryWorkspace( const ctx: SeedContext = { apiBaseUrl, orgSlug, token, dryRun }; printText(`Seeding org: ${orgSlug}${dryRun ? " (dry-run)" : ""}`); - printText(`Config: ${layout.projectPath}`); + printText(`Config: ${layout.configPath}`); printText(`Project: ${layout.name}`); - const models = loadModels(layout.modelsPath); + + // Schema (entity types / relationship types) comes from lobu.config.ts — the + // same source `lobu apply` provisions from; seeding here is idempotent. + // Watchers are agent-scoped and provisioned by `lobu apply`, not seeded. + const entityTypes = state.memorySchema.entityTypes; + const relationshipTypes = state.memorySchema.relationshipTypes; const dataRecords = loadDataRecords(layout.dataPath); - const entityTypes = models.filter((m) => m.modelType === "entity"); - const relationshipTypes = models.filter( - (m) => m.modelType === "relationship" - ); - const watchers = models.filter((m) => m.modelType === "watcher"); const dataEntities = dataRecords.filter( (record): record is ParsedDataRecord & { data: SeedEntitySchema } => record.recordType === "entity" @@ -678,21 +522,21 @@ export async function seedMemoryWorkspace( if (entityTypes.length > 0) { printText(`\nEntity types (${entityTypes.length}):`); - for (const { data } of entityTypes) { - await seedEntity(data, ctx); + for (const entity of entityTypes) { + await seedEntity(entity, ctx); } } if (relationshipTypes.length > 0) { printText(`\nRelationship types (${relationshipTypes.length}):`); - for (const { data } of relationshipTypes) { - await seedRelationshipType(data, ctx); + for (const rel of relationshipTypes) { + await seedRelationshipType(rel, ctx); } } const entityTypesForLookup = Array.from( new Set([ - ...entityTypes.map((entry) => String(entry.data.slug || "")), + ...entityTypes.map((entry) => entry.slug), ...dataEntities.map((entry) => entry.data.entity_type), ]) ); @@ -729,12 +573,5 @@ export async function seedMemoryWorkspace( } } - if (watchers.length > 0) { - printText(`\nWatchers (${watchers.length}):`); - for (const { data } of watchers) { - await seedWatcher(data, entityMap, ctx); - } - } - printText(dryRun ? "\nDry run complete." : "\nSeed complete."); } From 00419ef7562299061a753fbe696bf1467f9b31e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 01:59:17 +0100 Subject: [PATCH 21/65] refactor: delete the dead TOML/YAML config path With every consumer (apply, dev, doctor, chat, validate, seed) on lobu.config.ts, the TOML/YAML loader is dead code. Remove it: - packages/cli: config/loader.ts + config/schema.ts; the TOML functions in desired-state.ts (loadDesiredState/loadConfig use, collectEnvRefs, buildAgentSettings, buildPlatforms, parse{Entity,Relationship,Watcher}Type, parse*Doc, loadMemoryModels, loadConnectors, rejectUnsupportedAgentShapes, + their TOML-only consts). Kept the TS-path + shared helpers (readMarkdown, loadSkillFiles, buildLocalSkills, isRecord/asString, the connector-config validators, loadProjectConfig/loadDesiredStateFromConfig). Drop smol-toml. - packages/core: lobu-toml-schema.ts + its index.ts export block (no server importers). - Delete the 2 TOML-loader test files (coverage replaced by map-config.test.ts + load-config.test.ts) and the 2 core schema tests. - Delete the examples' lobu.toml + models/*.yaml + connectors/*.yaml (lobu.config.ts + *.connector.ts + *.reaction.ts + agent dirs remain). 8339 lines removed. cli/core/server typecheck clean; cli suite green. --- bun.lock | 1 - examples/agent-community/lobu.toml | 24 - examples/agent-community/models/schema.yaml | 123 -- examples/atlas/lobu.toml | 28 - examples/atlas/models/schema.yaml | 195 --- examples/delivery/lobu.toml | 24 - examples/delivery/models/schema.yaml | 138 -- examples/ecommerce/lobu.toml | 24 - examples/ecommerce/models/schema.yaml | 143 -- examples/finance/lobu.toml | 24 - examples/finance/models/schema.yaml | 141 -- examples/leadership/lobu.toml | 24 - examples/leadership/models/schema.yaml | 164 -- examples/legal/lobu.toml | 24 - examples/legal/models/schema.yaml | 148 -- .../lobu-crm/connectors/changelog-watch.yaml | 25 - examples/lobu-crm/connectors/funnel-form.yaml | 15 - examples/lobu-crm/connectors/github.yaml | 64 - examples/lobu-crm/connectors/hackernews.yaml | 18 - examples/lobu-crm/connectors/x.yaml | 31 - examples/lobu-crm/lobu.toml | 45 - examples/lobu-crm/models/schema.yaml | 244 --- examples/market/lobu.toml | 24 - examples/market/models/schema.yaml | 752 --------- examples/office-bot/lobu.toml | 79 - examples/office-bot/models/lunch.yaml | 153 -- examples/personal-finance/lobu.toml | 34 - examples/personal-finance/models/schema.yaml | 1346 ---------------- examples/sales/lobu.toml | 24 - examples/sales/models/schema.yaml | 161 -- packages/cli/package.json | 1 - .../__tests__/desired-state-extra.test.ts | 586 ------- .../apply/__tests__/desired-state.test.ts | 826 ---------- .../src/commands/_lib/apply/desired-state.ts | 1376 +---------------- packages/cli/src/config/loader.ts | 59 - packages/cli/src/config/schema.ts | 6 - .../__tests__/lobu-toml-schema-harden.test.ts | 803 ---------- .../src/__tests__/lobu-toml-schema.test.ts | 114 -- packages/core/src/index.ts | 16 - packages/core/src/lobu-toml-schema.ts | 315 ---- .../src/gateway/guardrails/aggregator.ts | 2 +- 41 files changed, 5 insertions(+), 8339 deletions(-) delete mode 100644 examples/agent-community/lobu.toml delete mode 100644 examples/agent-community/models/schema.yaml delete mode 100644 examples/atlas/lobu.toml delete mode 100644 examples/atlas/models/schema.yaml delete mode 100644 examples/delivery/lobu.toml delete mode 100644 examples/delivery/models/schema.yaml delete mode 100644 examples/ecommerce/lobu.toml delete mode 100644 examples/ecommerce/models/schema.yaml delete mode 100644 examples/finance/lobu.toml delete mode 100644 examples/finance/models/schema.yaml delete mode 100644 examples/leadership/lobu.toml delete mode 100644 examples/leadership/models/schema.yaml delete mode 100644 examples/legal/lobu.toml delete mode 100644 examples/legal/models/schema.yaml delete mode 100644 examples/lobu-crm/connectors/changelog-watch.yaml delete mode 100644 examples/lobu-crm/connectors/funnel-form.yaml delete mode 100644 examples/lobu-crm/connectors/github.yaml delete mode 100644 examples/lobu-crm/connectors/hackernews.yaml delete mode 100644 examples/lobu-crm/connectors/x.yaml delete mode 100644 examples/lobu-crm/lobu.toml delete mode 100644 examples/lobu-crm/models/schema.yaml delete mode 100644 examples/market/lobu.toml delete mode 100644 examples/market/models/schema.yaml delete mode 100644 examples/office-bot/lobu.toml delete mode 100644 examples/office-bot/models/lunch.yaml delete mode 100644 examples/personal-finance/lobu.toml delete mode 100644 examples/personal-finance/models/schema.yaml delete mode 100644 examples/sales/lobu.toml delete mode 100644 examples/sales/models/schema.yaml delete mode 100644 packages/cli/src/commands/_lib/apply/__tests__/desired-state-extra.test.ts delete mode 100644 packages/cli/src/commands/_lib/apply/__tests__/desired-state.test.ts delete mode 100644 packages/cli/src/config/loader.ts delete mode 100644 packages/cli/src/config/schema.ts delete mode 100644 packages/core/src/__tests__/lobu-toml-schema-harden.test.ts delete mode 100644 packages/core/src/__tests__/lobu-toml-schema.test.ts delete mode 100644 packages/core/src/lobu-toml-schema.ts diff --git a/bun.lock b/bun.lock index a6996c1a4..cfba08d5e 100644 --- a/bun.lock +++ b/bun.lock @@ -112,7 +112,6 @@ "react": "^19.2.5", "resend": "^6.6.0", "sharp": "^0.34.4", - "smol-toml": "^1.3.1", "tar": "^7.4.3", "vite": "^6.0.0", "winston": "^3.17.0", diff --git a/examples/agent-community/lobu.toml b/examples/agent-community/lobu.toml deleted file mode 100644 index 1c314cc94..000000000 --- a/examples/agent-community/lobu.toml +++ /dev/null @@ -1,24 +0,0 @@ -# lobu.toml — Agent configuration -# Docs: https://lobu.ai/docs/getting-started - -[agents.agent-community] -name = "agent-community" -description = "Discover aligned members, explain why they should meet, and draft warm introductions" -dir = "./agents/agent-community" - -[[agents.agent-community.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - - -[agents.agent-community.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "registry.npmjs.org", ".npmjs.org"] - -[memory] -enabled = true -org = "market" -name = "Agent Community" -description = "Discover aligned members, explain why they should meet, and draft warm introductions" -models = "./models" -data = "./data" diff --git a/examples/agent-community/models/schema.yaml b/examples/agent-community/models/schema.yaml deleted file mode 100644 index ffac7763a..000000000 --- a/examples/agent-community/models/schema.yaml +++ /dev/null @@ -1,123 +0,0 @@ -version: 2 -entities: - - slug: match - name: Match - description: A suggested introduction between two members with reasons and confidence - icon: handshake - color: '#10B981' - metadata_schema: - type: object - properties: - member_a: - type: string - x-table-label: Member A - x-table-column: true - member_b: - type: string - x-table-label: Member B - x-table-column: true - reason: - type: string - x-table-label: Reason - x-table-column: true - status: - type: string - x-table-label: Status - x-table-column: true - - slug: post - name: Post - description: A blog post, newsletter, or public writing by a community member - icon: pen-line - color: '#F59E0B' - metadata_schema: - type: object - properties: - title: - type: string - x-table-label: Title - x-table-column: true - source: - type: string - x-table-label: Source - x-table-column: true - author: - type: string - x-table-label: Author - x-table-column: true - topics: - type: string - x-table-label: Topics - x-table-column: true - - slug: topic - name: Topic - description: A durable interest or subject area used for member matching and discovery - icon: tag - color: '#8B5CF6' - metadata_schema: - type: object - properties: - topic_name: - type: string - x-table-label: Topic - x-table-column: true - evidence: - type: string - x-table-label: Evidence - x-table-column: true - member_count: - type: string - x-table-label: Members - x-table-column: true - relevance: - type: string - x-table-label: Relevance -relationships: - - slug: interested-in - name: Interested In - description: Store durable interests and goals that can be reused across matching and introductions. - - slug: introduced-to - name: Introduced To - description: Track completed introductions so the system avoids duplicate outreach and preserves relationship history. - - slug: matches-with - name: Matches With - description: Represent suggested introductions with reasons and confidence so outreach history is auditable. - - slug: writes-about - name: Writes About - description: Capture blog posts, newsletters, and public writing so matching includes current thinking, not just static bios. -watchers: - - slug: opportunity-matcher - agent: agent-community - name: Opportunity matcher - schedule: 0 */12 * * * - notification_priority: normal - tags: [community, matching] - min_cooldown_seconds: 300 - reaction_script: ./reactions/opportunity-matcher.reaction.ts - prompt: | - Monitor connected profiles, newsletters, websites, and member updates for new launches, posts, hiring signals, funding news, and project changes. Identify which members are likely to care, explain why, and queue approved intro or outreach drafts. - extraction_schema: - type: object - required: - - signals - properties: - signals: - type: array - items: - type: object - properties: - type: - type: string - source: - type: string - related_topics: - type: array - items: - type: string - interested_members: - type: array - items: - type: string - reason: - type: string - suggested_action: - type: string diff --git a/examples/atlas/lobu.toml b/examples/atlas/lobu.toml deleted file mode 100644 index cfb61ed25..000000000 --- a/examples/atlas/lobu.toml +++ /dev/null @@ -1,28 +0,0 @@ -# lobu.toml — Atlas reference catalog -# Docs: https://lobu.ai/docs/getting-started -# -# Atlas is a public, slow-churn reference catalog: countries, cities, -# regions, industries, technologies, universities. Other public catalogs -# (market, future siblings) reference these via cross-org relationships. - -[agents.atlas-curator] -name = "atlas-curator" -description = "Curate Atlas reference data — countries, cities, regions, industries, technologies, universities" -dir = "./agents/atlas-curator" - -[[agents.atlas-curator.providers]] -id = "z-ai" -model = "z-ai/glm-4.7" -key = "$Z_AI_API_KEY" - - -[agents.atlas-curator.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "api.z.ai", ".z.ai"] - -[memory] -enabled = true -org = "atlas" -name = "Atlas" -description = "Public reference catalog — places, taxonomies, institutions" -models = "./models" -data = "./data" diff --git a/examples/atlas/models/schema.yaml b/examples/atlas/models/schema.yaml deleted file mode 100644 index a800eafa3..000000000 --- a/examples/atlas/models/schema.yaml +++ /dev/null @@ -1,195 +0,0 @@ -version: 2 -entities: - - slug: city - name: City - description: Populated place (city, town, metro area) - icon: building-2 - color: '#22c55e' - metadata_schema: - type: object - properties: - country_id: - type: integer - description: FK to atlas.country - x-table-column: true - x-table-label: Country - x-link-entity-type: country - region_id: - type: integer - description: FK to atlas.region (optional — not every city is region-tagged) - x-table-column: true - x-table-label: Region - x-link-entity-type: region - latitude: - type: number - description: Decimal degrees, WGS84 - longitude: - type: number - description: Decimal degrees, WGS84 - population: - type: integer - description: City proper population (latest available estimate) - - slug: country - name: Country - description: Sovereign country (ISO 3166-1) - icon: flag - color: '#0ea5e9' - metadata_schema: - type: object - properties: - iso2: - type: string - minLength: 2 - maxLength: 2 - x-table-column: true - x-table-label: ISO2 - iso3: - type: string - minLength: 3 - maxLength: 3 - x-table-column: true - x-table-label: ISO3 - currency: - type: string - description: ISO 4217 currency code (e.g. USD, EUR, GBP) - x-table-column: true - x-table-label: Currency - region: - type: string - description: UN macro region (e.g. Europe, Africa, Asia, Americas, Oceania) - x-table-column: true - x-table-label: Region - population: - type: integer - description: Approximate population (latest available estimate) - - slug: industry - name: Industry - description: Industry / sector taxonomy node (NAICS, BICS, or custom) - icon: factory - color: '#a855f7' - metadata_schema: - type: object - properties: - parent_id: - type: integer - description: FK to parent atlas.industry (self-reference for hierarchy) - x-table-column: true - x-table-label: Parent - x-link-entity-type: industry - taxonomy_source: - type: string - enum: - - NAICS - - BICS - - custom - x-table-column: true - x-table-label: Source - code: - type: string - description: Taxonomy code (e.g. NAICS 541512) - x-table-column: true - x-table-label: Code - - slug: region - name: Region - description: First-level administrative region (state, province, etc.) within a country - icon: map - color: '#14b8a6' - metadata_schema: - type: object - properties: - country_id: - type: integer - description: FK to atlas.country - x-table-column: true - x-table-label: Country - x-link-entity-type: country - iso_3166_2: - type: string - description: ISO 3166-2 code (e.g. US-CA, GB-LND) - x-table-column: true - x-table-label: ISO 3166-2 - - slug: technology - name: Technology - description: Technology, framework, library, platform, or developer tool - icon: cpu - color: '#f97316' - metadata_schema: - type: object - properties: - category: - type: string - description: Coarse category (e.g. database, frontend-framework, observability) - x-table-column: true - x-table-label: Category - homepage_url: - type: string - format: uri - x-table-column: true - x-table-label: Homepage - - slug: university - name: University - description: Higher-education institution - icon: graduation-cap - color: '#ec4899' - metadata_schema: - type: object - properties: - country_id: - type: integer - description: FK to atlas.country - x-table-column: true - x-table-label: Country - x-link-entity-type: country - city_id: - type: integer - description: FK to atlas.city (optional) - x-table-column: true - x-table-label: City - x-link-entity-type: city - founded_year: - type: integer - x-table-column: true - x-table-label: Founded - homepage_url: - type: string - format: uri - -watchers: - # Demo watcher exercising the file-first apply surface: tags, notification - # routing, cooldowns, and a sibling reaction script. Atlas is a reference - # catalog (cities, countries, industries, universities, …) — once a week - # we sweep for entries that haven't been touched in 90+ days and flag them - # for re-verification. - - slug: catalog-staleness-checker - agent: atlas-curator - name: Catalog staleness checker - schedule: 0 4 * * 1 - notification_priority: low - tags: [atlas, reference, weekly] - min_cooldown_seconds: 3600 - reaction_script: ./reactions/catalog-staleness-checker.reaction.ts - prompt: | - Sweep the atlas reference catalog for entries that haven't been - updated in 90+ days. List the stalest 10 across cities, countries, - industries, technologies, and universities. Suggest a re-verification - action for each (e.g. "country/PL: confirm population from latest census"). - extraction_schema: - type: object - required: - - stale_entries - properties: - stale_entries: - type: array - items: - type: object - properties: - entity_type: - type: string - slug: - type: string - last_updated: - type: string - suggested_action: - type: string - total_stale_count: - type: integer diff --git a/examples/delivery/lobu.toml b/examples/delivery/lobu.toml deleted file mode 100644 index fd3a24a40..000000000 --- a/examples/delivery/lobu.toml +++ /dev/null @@ -1,24 +0,0 @@ -# lobu.toml — Agent configuration -# Docs: https://lobu.ai/docs/getting-started - -[agents.delivery] -name = "delivery" -description = "Help delivery teams keep milestones, blockers, owners, and artifacts aligned" -dir = "./agents/delivery" - -[[agents.delivery.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - - -[agents.delivery.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "registry.npmjs.org", ".npmjs.org"] - -[memory] -enabled = true -org = "delivery" -name = "Delivery" -description = "Help delivery teams keep milestones, blockers, owners, and artifacts aligned" -models = "./models" -data = "./data" diff --git a/examples/delivery/models/schema.yaml b/examples/delivery/models/schema.yaml deleted file mode 100644 index b6e6c3c5c..000000000 --- a/examples/delivery/models/schema.yaml +++ /dev/null @@ -1,138 +0,0 @@ -version: 2 -entities: - - slug: blocker - name: Blocker - description: A dependency or issue that is blocking project progress - icon: ban - color: '#EF4444' - metadata_schema: - type: object - properties: - blocker_description: - type: string - x-table-label: Blocker - x-table-column: true - owned_by: - type: string - x-table-label: Owner - x-table-column: true - impact: - type: string - x-table-label: Impact - x-table-column: true - status: - type: string - x-table-label: Status - x-table-column: true - - slug: document - name: Document - description: A project artifact, review, or reference document - icon: file-text - color: '#F59E0B' - metadata_schema: - type: object - properties: - document_name: - type: string - x-table-label: Document - x-table-column: true - document_type: - type: string - x-table-label: Type - x-table-column: true - linked_project: - type: string - x-table-label: Project - x-table-column: true - last_updated: - type: string - x-table-label: Updated - x-table-column: true - - slug: milestone - name: Milestone - description: A key deliverable or phase gate within a project - icon: flag - color: '#10B981' - metadata_schema: - type: object - properties: - milestone_name: - type: string - x-table-label: Milestone - x-table-column: true - lifecycle_state: - type: string - x-table-label: State - x-table-column: true - target_date: - type: string - x-table-label: Target Date - x-table-column: true - parent_project: - type: string - x-table-label: Project - x-table-column: true - - slug: stakeholder - name: Stakeholder - description: A person who owns or is responsible for part of a project - icon: user - color: '#8B5CF6' - metadata_schema: - type: object - properties: - name: - type: string - x-table-label: Name - x-table-column: true - role: - type: string - x-table-label: Role - x-table-column: true - owns: - type: string - x-table-label: Owns - x-table-column: true - contact: - type: string - x-table-label: Contact -relationships: - - slug: blocked-by - name: Blocked By - description: Tie blockers directly to the project and milestone they threaten. - - slug: documented-in - name: Documented In - description: Preserve the source documents and reviews behind key project state. - - slug: owned-by - name: Owned By - description: Keep project ownership queryable across updates and artifacts. -watchers: - - slug: phoenix-rollout-tracker - agent: delivery - name: Phoenix rollout tracker - schedule: 0 9 * * 1 - notification_priority: high - notification_channel: both - tags: [delivery, weekly, rollout] - min_cooldown_seconds: 3600 - prompt: | - Check project blockers, milestone progress, and generate the weekly risk summary for leadership. - extraction_schema: - type: object - required: - - blockers_resolved - - milestone_state - - new_risks - - risk_summary - properties: - blockers_resolved: - type: array - items: - type: string - milestone_state: - type: string - new_risks: - type: array - items: - type: string - risk_summary: - type: string diff --git a/examples/ecommerce/lobu.toml b/examples/ecommerce/lobu.toml deleted file mode 100644 index fa52b21de..000000000 --- a/examples/ecommerce/lobu.toml +++ /dev/null @@ -1,24 +0,0 @@ -# lobu.toml — Agent configuration -# Docs: https://lobu.ai/docs/getting-started - -[agents.ecommerce-ops] -name = "ecommerce-ops" -description = "Manage subscriptions, process order changes, and resolve customer requests" -dir = "./agents/ecommerce-ops" - -[[agents.ecommerce-ops.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - - -[agents.ecommerce-ops.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "registry.npmjs.org", ".npmjs.org"] - -[memory] -enabled = true -org = "ecommerce" -name = "Ecommerce" -description = "Manage subscriptions, process order changes, and resolve customer requests" -models = "./models" -data = "./data" diff --git a/examples/ecommerce/models/schema.yaml b/examples/ecommerce/models/schema.yaml deleted file mode 100644 index dd565a26f..000000000 --- a/examples/ecommerce/models/schema.yaml +++ /dev/null @@ -1,143 +0,0 @@ -version: 2 -entities: - - slug: customer - name: Customer - description: A customer with subscriptions, orders, and communication preferences - icon: user - color: '#3B82F6' - metadata_schema: - type: object - properties: - full_name: - type: string - x-table-label: Name - x-table-column: true - status: - type: string - x-table-label: Status - x-table-column: true - plan: - type: string - x-table-label: Plan - x-table-column: true - communication_preference: - type: string - x-table-label: Preference - x-table-column: true - - slug: order - name: Order - description: A customer order with fulfillment status and delivery details - icon: shopping-cart - color: '#8B5CF6' - metadata_schema: - type: object - properties: - order_number: - type: string - x-table-label: Order - x-table-column: true - product: - type: string - x-table-label: Product - x-table-column: true - fulfillment_status: - type: string - x-table-label: Status - x-table-column: true - customer: - type: string - x-table-label: Customer - x-table-column: true - - slug: product - name: Product - description: A product in the catalog linked to subscriptions and orders - icon: package - color: '#F59E0B' - metadata_schema: - type: object - properties: - product_name: - type: string - x-table-label: Product - x-table-column: true - plan_tier: - type: string - x-table-label: Tier - x-table-column: true - delivery_frequency: - type: string - x-table-label: Delivery - x-table-column: true - price: - type: string - x-table-label: Price - x-table-column: true - - slug: subscription - name: Subscription - description: A recurring subscription plan with billing cycle and pending changes - icon: repeat - color: '#10B981' - metadata_schema: - type: object - properties: - plan_name: - type: string - x-table-label: Plan - x-table-column: true - frequency: - type: string - x-table-label: Frequency - x-table-column: true - status: - type: string - x-table-label: Status - x-table-column: true - pending_changes: - type: string - x-table-label: Pending - x-table-column: true -relationships: - - slug: has-preference - name: Has Preference - description: Persist communication and delivery preferences across interactions. - - slug: placed-order - name: Placed Order - description: Link orders to customers so purchase history stays queryable. - - slug: subscribed-to - name: Subscribed To - description: Track which plans and products each customer subscribes to. -watchers: - - slug: customer-activity-tracker - agent: ecommerce-ops - name: Customer activity tracker - schedule: 0 */6 * * * - notification_priority: normal - tags: [ecommerce, customer-ops] - min_cooldown_seconds: 300 - prompt: | - Monitor customers for new orders, subscription changes, delivery requests, and support interactions. - extraction_schema: - type: object - required: - - subscription_status - - pending_changes - - recent_orders - - communication_preferences - - open_requests - properties: - subscription_status: - type: string - pending_changes: - type: array - items: - type: string - recent_orders: - type: array - items: - type: string - communication_preferences: - type: string - open_requests: - type: array - items: - type: string diff --git a/examples/finance/lobu.toml b/examples/finance/lobu.toml deleted file mode 100644 index f5116f714..000000000 --- a/examples/finance/lobu.toml +++ /dev/null @@ -1,24 +0,0 @@ -# lobu.toml — Agent configuration -# Docs: https://lobu.ai/docs/getting-started - -[agents.finance] -name = "finance" -description = "Help finance teams reconcile data, explain variance, and prepare reporting runs" -dir = "./agents/finance" - -[[agents.finance.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - - -[agents.finance.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "registry.npmjs.org", ".npmjs.org"] - -[memory] -enabled = true -org = "finance" -name = "Finance" -description = "Help finance teams reconcile data, explain variance, and prepare reporting runs" -models = "./models" -data = "./data" diff --git a/examples/finance/models/schema.yaml b/examples/finance/models/schema.yaml deleted file mode 100644 index d2ce8fce0..000000000 --- a/examples/finance/models/schema.yaml +++ /dev/null @@ -1,141 +0,0 @@ -version: 2 -entities: - - slug: account - name: Account - description: A financial account that holds balances, transactions, and reconciliation state - icon: wallet - color: '#3B82F6' - metadata_schema: - type: object - properties: - account_name: - type: string - x-table-label: Account - x-table-column: true - account_type: - type: string - x-table-label: Type - x-table-column: true - balance: - type: string - x-table-label: Balance - x-table-column: true - reconciliation_status: - type: string - x-table-label: Reconciliation - x-table-column: true - - slug: report - name: Report - description: A financial report or summary generated from account and transaction data - icon: file-bar-chart - color: '#8B5CF6' - metadata_schema: - type: object - properties: - report_name: - type: string - x-table-label: Report - x-table-column: true - period: - type: string - x-table-label: Period - x-table-column: true - status: - type: string - x-table-label: Status - x-table-column: true - exceptions_count: - type: string - x-table-label: Exceptions - x-table-column: true - - slug: transaction - name: Transaction - description: A financial transaction that affects account balances - icon: arrow-left-right - color: '#10B981' - metadata_schema: - type: object - properties: - description: - type: string - x-table-label: Description - x-table-column: true - amount: - type: string - x-table-label: Amount - x-table-column: true - date: - type: string - x-table-label: Date - x-table-column: true - category: - type: string - x-table-label: Category - x-table-column: true - - slug: variance - name: Variance - description: A discrepancy or anomaly identified during reconciliation or reporting - icon: alert-triangle - color: '#EF4444' - metadata_schema: - type: object - properties: - variance_type: - type: string - x-table-label: Type - x-table-column: true - amount: - type: string - x-table-label: Amount - x-table-column: true - source_account: - type: string - x-table-label: Account - x-table-column: true - explanation: - type: string - x-table-label: Explanation - x-table-column: true -relationships: - - slug: creates-variance - name: Creates Variance - description: Keep anomalies attached to the source records that produced them. - - slug: reconciles-to - name: Reconciles To - description: Tie transactions and balances back to the accounts they roll into. - - slug: summarized-in - name: Summarized In - description: Let agents trace reporting outputs back to the supporting data. -watchers: - - slug: reconciliation-monitor - agent: finance - name: Reconciliation monitor - schedule: 0 6 * * 1-5 - notification_priority: high - notification_channel: both - tags: [finance, reconciliation, daily] - min_cooldown_seconds: 3600 - reaction_script: ./reactions/reconciliation-monitor.reaction.ts - prompt: | - Check accounts for unreconciled transactions, new variances, and approaching reporting deadlines. Lead with exceptions that need review. - extraction_schema: - type: object - required: - - unreconciled_count - - new_variances - - approaching_deadlines - properties: - unreconciled_count: - type: integer - new_variances: - type: array - items: - type: string - approaching_deadlines: - type: array - items: - type: string - payment_risks: - type: array - items: - type: string diff --git a/examples/leadership/lobu.toml b/examples/leadership/lobu.toml deleted file mode 100644 index bbbaa18d3..000000000 --- a/examples/leadership/lobu.toml +++ /dev/null @@ -1,24 +0,0 @@ -# lobu.toml — Agent configuration -# Docs: https://lobu.ai/docs/getting-started - -[agents.leadership] -name = "leadership" -description = "Help leadership teams turn memos, decisions, and board materials into reusable operating context" -dir = "./agents/leadership" - -[[agents.leadership.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - - -[agents.leadership.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "registry.npmjs.org", ".npmjs.org"] - -[memory] -enabled = true -org = "leadership" -name = "Leadership" -description = "Turn memos, decisions, and board materials into reusable operating context" -models = "./models" -data = "./data" diff --git a/examples/leadership/models/schema.yaml b/examples/leadership/models/schema.yaml deleted file mode 100644 index a05c03890..000000000 --- a/examples/leadership/models/schema.yaml +++ /dev/null @@ -1,164 +0,0 @@ -version: 2 -entities: - - slug: decision - name: Decision - description: A leadership decision extracted from a document with its approval status - icon: check-circle - color: '#10B981' - metadata_schema: - type: object - properties: - subject: - type: string - x-table-label: Subject - x-table-column: true - status: - type: string - x-table-label: Status - x-table-column: true - source_document: - type: string - x-table-label: Source - x-table-column: true - decision_date: - type: string - x-table-label: Date - x-table-column: true - - slug: document - name: Document - description: A source document such as a board memo, strategy brief, or executive report - icon: file-text - color: '#3B82F6' - metadata_schema: - type: object - properties: - document_name: - type: string - x-table-label: Document - x-table-column: true - document_type: - type: string - x-table-label: Type - x-table-column: true - date: - type: string - x-table-label: Date - x-table-column: true - decisions_count: - type: string - x-table-label: Decisions - x-table-column: true - - slug: region - name: Region - description: A geographic region referenced in strategic decisions or expansion plans - icon: globe - color: '#F59E0B' - metadata_schema: - type: object - properties: - region_name: - type: string - x-table-label: Region - x-table-column: true - decision_context: - type: string - x-table-label: Context - x-table-column: true - status: - type: string - x-table-label: Status - x-table-column: true - budget_approved: - type: string - x-table-label: Budget - - slug: risk - name: Risk - description: A blocker or dependency that is holding up a decision or initiative - icon: shield-alert - color: '#EF4444' - metadata_schema: - type: object - properties: - blocker: - type: string - x-table-label: Blocker - x-table-column: true - affects: - type: string - x-table-label: Affects - x-table-column: true - state: - type: string - x-table-label: State - x-table-column: true - owner: - type: string - x-table-label: Owner - x-table-column: true - - slug: task - name: Task - description: An assigned follow-up action extracted from a leadership document or meeting - icon: check-square - color: '#8B5CF6' - metadata_schema: - type: object - properties: - action: - type: string - x-table-label: Action - x-table-column: true - owner: - type: string - x-table-label: Owner - x-table-column: true - deadline: - type: string - x-table-label: Deadline - x-table-column: true - source: - type: string - x-table-label: Source - x-table-column: true -relationships: - - slug: approved - name: Approved - description: Keep approved decisions queryable without re-reading the whole source memo. - - slug: assigned - name: Assigned - description: Turn follow-up work into durable ownership instead of transient notes. - - slug: blocked-by - name: Blocked By - description: Attach blocked decisions to the dependency that is holding them up. -watchers: - - slug: board-action-tracker - agent: leadership - name: Board action tracker - schedule: 0 8 * * * - notification_priority: high - notification_channel: both - tags: [leadership, daily, board] - agent_kind: notifier - prompt: | - Track board action items: check task delivery status, blocker resolution progress, and approaching deadlines for the next board packet. - extraction_schema: - type: object - required: - - action_items - - blocked_items - - deadlines_approaching - - completion_status - properties: - action_items: - type: array - items: - type: string - blocked_items: - type: array - items: - type: string - deadlines_approaching: - type: array - items: - type: string - completion_status: - type: string diff --git a/examples/legal/lobu.toml b/examples/legal/lobu.toml deleted file mode 100644 index 498167487..000000000 --- a/examples/legal/lobu.toml +++ /dev/null @@ -1,24 +0,0 @@ -# lobu.toml — Agent configuration -# Docs: https://lobu.ai/docs/getting-started - -[agents.legal-review] -name = "legal-review" -description = "Review contracts, summarize risk, and surface missing protections" -dir = "./agents/legal" - -[[agents.legal-review.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - - -[agents.legal-review.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "registry.npmjs.org", ".npmjs.org"] - -[memory] -enabled = true -org = "legal-review" -name = "Legal" -description = "Review contracts, summarize risk, and surface missing protections" -models = "./models" -data = "./data" diff --git a/examples/legal/models/schema.yaml b/examples/legal/models/schema.yaml deleted file mode 100644 index 5250aa627..000000000 --- a/examples/legal/models/schema.yaml +++ /dev/null @@ -1,148 +0,0 @@ -version: 2 -entities: - - slug: clause - name: Clause - description: A specific provision or section within a contract that defines terms or obligations - icon: list - color: '#8B5CF6' - metadata_schema: - type: object - properties: - clause_type: - type: string - x-table-label: Type - x-table-column: true - section: - type: string - x-table-label: Section - x-table-column: true - risk_level: - type: string - x-table-label: Risk Level - x-table-column: true - language_summary: - type: string - x-table-label: Summary - x-table-column: true - - slug: contract - name: Contract - description: A legal agreement between parties with defined terms, obligations, and conditions - icon: file-text - color: '#3B82F6' - metadata_schema: - type: object - properties: - contract_type: - type: string - x-table-label: Type - x-table-column: true - status: - type: string - x-table-label: Status - x-table-column: true - effective_date: - type: string - x-table-label: Effective Date - x-table-column: true - counterparty_name: - type: string - x-table-label: Counterparty - x-table-column: true - governing_law: - type: string - x-table-label: Governing Law - - slug: counterparty - name: Counterparty - description: An external party involved in a contract or legal agreement - icon: building - color: '#F59E0B' - metadata_schema: - type: object - properties: - organization_name: - type: string - x-table-label: Organization - x-table-column: true - jurisdiction: - type: string - x-table-label: Jurisdiction - x-table-column: true - contact_person: - type: string - x-table-label: Contact - x-table-column: true - relationship_status: - type: string - x-table-label: Status - x-table-column: true - - slug: risk - name: Risk - description: A legal risk identified in a contract or clause that requires attention or mitigation - icon: shield-alert - color: '#EF4444' - metadata_schema: - type: object - properties: - severity: - type: string - x-table-label: Severity - x-table-column: true - category: - type: string - x-table-label: Category - x-table-column: true - mitigation: - type: string - x-table-label: Mitigation - x-table-column: true - source_clause: - type: string - x-table-label: Source Clause - x-table-column: true -relationships: - - slug: belongs-to-counterparty - name: Belongs to Counterparty - description: Tie agreements and negotiation context back to the right external party. - - slug: contains-clause - name: Contains Clause - description: Represent how a contract is composed so risky language stays attached to the right section. - - slug: creates-risk - name: Creates Risk - description: Keep legal risk linked to the clause or term that caused it. -watchers: - - slug: contract-review-tracker - agent: legal-review - name: Contract review tracker - schedule: 0 8 * * 1-5 - notification_priority: high - tags: [legal, contract, daily] - min_cooldown_seconds: 1800 - reactions_guidance: | - For any contract with `status: needs_counsel`, route an entity-scoped event - to the assigned reviewer. For contracts >90 days unsigned, escalate to the - counterparty owner; never auto-resolve risk items. - prompt: | - Review active contracts for approaching deadlines, unsigned agreements, and unresolved risk items. Flag any clauses that still need counsel approval. - extraction_schema: - type: object - required: - - pending_contracts - - unresolved_risks - - approaching_deadlines - properties: - pending_contracts: - type: array - items: - type: string - unresolved_risks: - type: array - items: - type: string - approaching_deadlines: - type: array - items: - type: string - flagged_clauses: - type: array - items: - type: string diff --git a/examples/lobu-crm/connectors/changelog-watch.yaml b/examples/lobu-crm/connectors/changelog-watch.yaml deleted file mode 100644 index bf4fae4e3..000000000 --- a/examples/lobu-crm/connectors/changelog-watch.yaml +++ /dev/null @@ -1,25 +0,0 @@ -# Competitor & own changelog watcher. -# Connector definition: packages/connectors/src/website.ts (no auth). ---- -version: 1 -type: connection -slug: competitor-changelogs -connector: website -name: Competitor changelogs -config: - urls: - - https://lobu.ai/changelog - - https://docs.dust.tt/changelog - - https://www.glean.com/release-notes - max_pages: 10 -feeds: - - feed: pages - name: Changelog pages - schedule: "0 7 * * *" - config: - urls: - - https://lobu.ai/changelog - - https://docs.dust.tt/changelog - - https://www.glean.com/release-notes - max_pages: 10 - parse_sections: false diff --git a/examples/lobu-crm/connectors/funnel-form.yaml b/examples/lobu-crm/connectors/funnel-form.yaml deleted file mode 100644 index 81f55ed4e..000000000 --- a/examples/lobu-crm/connectors/funnel-form.yaml +++ /dev/null @@ -1,15 +0,0 @@ -# Demo-request form submissions — backed by the custom funnel-form.connector.ts. ---- -version: 1 -type: connection -slug: funnel-form-submissions -connector: funnel-form -name: Demo-request form submissions -config: - endpoint: "https://lobu.ai/api/demo-requests" -feeds: - - feed: submissions - name: Form submissions - schedule: "*/15 * * * *" - config: - endpoint: "https://lobu.ai/api/demo-requests" diff --git a/examples/lobu-crm/connectors/github.yaml b/examples/lobu-crm/connectors/github.yaml deleted file mode 100644 index 54bd69159..000000000 --- a/examples/lobu-crm/connectors/github.yaml +++ /dev/null @@ -1,64 +0,0 @@ -# GitHub — funnel signals from lobu-ai/lobu (stars, issues, PRs, comments). -# Connector definition: packages/connectors/src/github.ts -# -# Two auth profiles: an `oauth_app` (the registered GitHub OAuth App's client -# credentials, from env) referenced via `app_auth:`, and an `oauth_account` -# (the actual access token) referenced via `auth:`. The account profile has no -# credentials here — `lobu apply` never writes OAuth tokens; finish the OAuth -# flow via the connect URL printed after apply (or in the dashboard). ---- -version: 1 -type: auth_profile -slug: github-app -connector: github -kind: oauth_app -name: GitHub OAuth App -credentials: - GITHUB_CLIENT_ID: $GITHUB_CLIENT_ID - GITHUB_CLIENT_SECRET: $GITHUB_CLIENT_SECRET ---- -version: 1 -type: auth_profile -slug: github-account -connector: github -kind: oauth_account -name: GitHub — lobu-ai ---- -version: 1 -type: connection -slug: github-lobu -connector: github -name: GitHub — lobu-ai/lobu -auth: github-account -app_auth: github-app -config: - repo_owner: lobu-ai - repo_name: lobu -feeds: - - feed: stargazers - name: Stars — lobu-ai/lobu - schedule: "0 */6 * * *" - config: - repo_owner: lobu-ai - repo_name: lobu - - feed: issues - name: Issues — lobu-ai/lobu - schedule: "15 */6 * * *" - config: - repo_owner: lobu-ai - repo_name: lobu - lookback_days: 90 - - feed: issue_comments - name: Issue comments — lobu-ai/lobu - schedule: "30 */6 * * *" - config: - repo_owner: lobu-ai - repo_name: lobu - lookback_days: 90 - - feed: pr_comments - name: PR comments — lobu-ai/lobu - schedule: "45 */6 * * *" - config: - repo_owner: lobu-ai - repo_name: lobu - lookback_days: 90 diff --git a/examples/lobu-crm/connectors/hackernews.yaml b/examples/lobu-crm/connectors/hackernews.yaml deleted file mode 100644 index 9309919d5..000000000 --- a/examples/lobu-crm/connectors/hackernews.yaml +++ /dev/null @@ -1,18 +0,0 @@ -# Hacker News — mentions of "lobu". -# Connector definition: packages/connectors/src/hackernews.ts (no auth). ---- -version: 1 -type: connection -slug: hn-lobu -connector: hackernews -name: Hacker News — lobu -config: - search_query: lobu - lookback_days: 180 -feeds: - - feed: stories - name: HN stories — lobu - schedule: "0 */4 * * *" - config: - search_query: lobu - lookback_days: 180 diff --git a/examples/lobu-crm/connectors/x.yaml b/examples/lobu-crm/connectors/x.yaml deleted file mode 100644 index 013130109..000000000 --- a/examples/lobu-crm/connectors/x.yaml +++ /dev/null @@ -1,31 +0,0 @@ -# X — @lobu mentions & replies. -# Connector definition: packages/connectors/src/x.ts ---- -version: 1 -type: auth_profile -slug: x-account -connector: x -kind: oauth_account -name: X — @lobu -# No credentials here on purpose: `lobu apply` never writes OAuth tokens. -# After `lobu apply`, finish the OAuth flow via the connect URL it prints -# (or in the dashboard) to make this profile `active`. ---- -version: 1 -type: connection -slug: x-mentions -connector: x -name: X — @lobu mentions & replies -auth: x-account -config: - search_query: "@lobu OR lobu.ai" - search_filter: live - max_scrolls: 10 -feeds: - - feed: tweets - name: X mentions — @lobu - schedule: "0 */3 * * *" - config: - search_query: "@lobu OR lobu.ai" - search_filter: live - max_scrolls: 10 diff --git a/examples/lobu-crm/lobu.toml b/examples/lobu-crm/lobu.toml deleted file mode 100644 index fa5188e3d..000000000 --- a/examples/lobu-crm/lobu.toml +++ /dev/null @@ -1,45 +0,0 @@ -# lobu.toml — Lobu CRM / funnel agent -# Docs: https://lobu.ai/docs/getting-started -# -# Org `lobu-crm` is a dedicated workspace, separate from `buremba` (the personal -# second brain). Connectors are configured in the org (dashboard / API), scoped -# narrow so the agent's context stays funnel-only: -# - github → lobu-ai/lobu (stars, issues, PRs, comments) -# - x → @lobu mentions + replies to your Lobu threads -# - hackernews → search "lobu" -# - producthunt → the launch / "lobu" -# - website (optional) → lobu.ai + competitor changelogs (onyx, dust, glean) - -[agents.crm] -name = "crm" -description = "Maintains Lobu's funnel CRM — leads, pilots, inbound triage, weekly digest" -dir = "./agents/crm" - -[[agents.crm.providers]] -id = "z-ai" -model = "z-ai/glm-4.7" -key = "$Z_AI_API_KEY" - -[agents.crm.network] -allowed = [ - "github.com", ".github.com", "api.github.com", ".githubusercontent.com", - "x.com", "api.x.com", "twitter.com", - "news.ycombinator.com", "hn.algolia.com", - "api.producthunt.com", - "api.z.ai", ".z.ai", - "lobu.ai", - # Competitor changelog pages scraped by the `website` connector - ".dust.tt", ".glean.com", -] - -[memory] -enabled = true -org = "lobu-crm" -name = "Lobu CRM" -description = "Funnel CRM for Lobu — leads, pilots, conversations, launch signals" -models = "./models" -data = "./data" -# Data-source connectors (`*.connector.ts` + `type: connection|auth_profile|connector` -# manifests). Synced by `lobu apply`; interactive-auth profiles (oauth_account) -# are finished in the dashboard. -connectors = "./connectors" diff --git a/examples/lobu-crm/models/schema.yaml b/examples/lobu-crm/models/schema.yaml deleted file mode 100644 index ac5890dec..000000000 --- a/examples/lobu-crm/models/schema.yaml +++ /dev/null @@ -1,244 +0,0 @@ -version: 2 -entities: - - slug: lead - name: Lead - description: A person who has shown a signal toward Lobu — starred, engaged, asked, or talked to us - icon: user - color: '#10B981' - metadata_schema: - type: object - required: - - name - - source - - stage - properties: - name: - type: string - x-table-label: Name - x-table-column: true - company: - type: string - x-table-label: Company - x-table-column: true - stage: - type: string - enum: - - signal - - trial - - conversation - - pilot - - customer - - cold - x-table-label: Stage - x-table-column: true - source: - type: string - description: Where they first showed up — "github:stargazer", "x:mention", "github:issue-comment", "demo-form", "intro", etc. - x-table-label: Source - x-table-column: true - github_handle: - type: string - x-table-label: GitHub - x-table-column: true - x_handle: - type: string - x-table-label: X - email: - type: string - x-table-label: Email - last_touch: - type: string - description: ISO date of the most recent interaction - x-table-label: Last touch - x-table-column: true - next_action: - type: string - x-table-label: Next action - x-table-column: true - notes: - type: string - - slug: pilot - name: Pilot - description: A paid pilot — a company running Lobu for their team under a time-boxed agreement - icon: rocket - color: '#F59E0B' - metadata_schema: - type: object - required: - - company - - status - properties: - company: - type: string - x-table-label: Company - x-table-column: true - status: - type: string - enum: - - active - - won - - lost - - paused - x-table-label: Status - x-table-column: true - seats: - type: integer - x-table-label: Seats - x-table-column: true - mrr: - type: string - description: Monthly recurring revenue for the pilot, e.g. "$750" - x-table-label: MRR - x-table-column: true - start_date: - type: string - x-table-label: Start - x-table-column: true - success_metric: - type: string - description: The one metric agreed up front that defines pilot success - x-table-label: Success metric - x-table-column: true - lead_id: - type: string - description: The lead entity this pilot converted from -relationships: - - slug: converted-to - name: Converted To - description: Links a lead to the pilot it became, so the path from first signal to paying pilot stays explicit. -watchers: - - slug: funnel-digest - agent: crm - name: Weekly funnel digest - schedule: 0 9 * * 1 - notification_priority: high - notification_channel: both - tags: [crm, weekly] - min_cooldown_seconds: 3600 - reaction_script: ./reactions/funnel-digest.reaction.ts - prompt: | - Produce the weekly funnel digest and post it to Slack. Keep it short. - - 1. The single recommended action for the week, on the first line. Pick the - move that does the most to get pilot #1 closer (almost always: follow up - with the warmest lead in "conversation", or progress whichever pilot - conversation is furthest along). - 2. Funnel snapshot: count of `lead` entities per stage; what moved since the - last digest (new leads, stage changes, new/updated `pilot` entities). - 3. Top-of-funnel since last digest: new GitHub stars, X mentions/replies, - HN/PH activity. - 4. Stale: any lead in `conversation` with no `lead:interaction` in 7+ days — - list them for follow-up. - 5. One gap callout if there is one (e.g. "18 new stars, 0 became leads — - is inbound-triage catching the right signal?"). - - Tone: a checklist a busy founder reads in 30 seconds. End on the next action, - not the status. Remember: the metric that matters is customer conversations - this week — if that number is below 3, say so plainly. - extraction_schema: - type: object - required: - - top_action - - stage_counts - - moved - - top_of_funnel - - stale_leads - properties: - top_action: - type: string - stage_counts: - type: object - moved: - type: object - properties: - new_leads: - type: integer - stage_changes: - type: integer - pilot_updates: - type: integer - top_of_funnel: - type: object - properties: - stars: - type: integer - x_mentions: - type: integer - hn_ph_activity: - type: integer - stale_leads: - type: array - items: - type: string - gap: - type: string - conversations_this_week: - type: integer - - slug: inbound-triage - agent: crm - name: Inbound triage - schedule: 0 8-22/2 * * * - notification_priority: normal - tags: [crm, triage] - min_cooldown_seconds: 300 - reaction_script: ./reactions/inbound-triage.reaction.ts - prompt: | - Look for new top-of-funnel signals since the last run, across the connectors - in this org: - - GitHub: new stargazers on lobu-ai/lobu; new issues / issue comments / - PR comments — especially anything with deployment, self-host, multi-tenant, - "how do I", or evaluation language. - - X: new @-mentions of Lobu, replies to Burak's Lobu threads, quote-tweets. - - Hacker News / Product Hunt: new comments or posts mentioning Lobu or OpenClaw. - - For each signal that looks like a real person (not a bot, not a casual star): - 1. search_memory for an existing `lead` (match github handle / x handle / email). - 2. If none, create a `lead` entity at the lowest stage the evidence supports - (a bare star → "signal"; a deployment-flavored issue comment or a - "how do I deploy this for my team" mention → "trial" or "conversation"), - with source set to where it came from, and entity_ids linking to the - source event. Then save a `lead:created` event. - 3. If a lead exists, enrich it (add the handle, bump the stage if the new - signal warrants it, update last_touch) and save a `lead:interaction` or - `lead:stage_changed` event as appropriate. - - Then post to Slack: the new/updated leads, ranked by closeness-to-a-paying-pilot, - each with a one-line recommended next action (e.g. "reply on the issue and offer - a 20-min call"). If nothing notable, post nothing — don't manufacture noise. - extraction_schema: - type: object - required: - - new_leads - - enriched_leads - - recommended_actions - properties: - new_leads: - type: array - items: - type: object - properties: - name: - type: string - handle: - type: string - source: - type: string - stage: - type: string - why: - type: string - enriched_leads: - type: array - items: - type: object - properties: - name: - type: string - change: - type: string - recommended_actions: - type: array - items: - type: string - notable: - type: boolean diff --git a/examples/market/lobu.toml b/examples/market/lobu.toml deleted file mode 100644 index 7f553e096..000000000 --- a/examples/market/lobu.toml +++ /dev/null @@ -1,24 +0,0 @@ -# lobu.toml — Agent configuration -# Docs: https://lobu.ai/docs/getting-started - -[agents.vc-tracking] -name = "vc-tracking" -description = "Track companies, founders, and investment opportunities for venture firms" -dir = "./agents/vc-tracking" - -[[agents.vc-tracking.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - - -[agents.vc-tracking.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "registry.npmjs.org", ".npmjs.org"] - -[memory] -enabled = true -org = "market" -name = "Market" -description = "Track companies, founders, and investment opportunities for venture firms" -models = "./models" -data = "./data" diff --git a/examples/market/models/schema.yaml b/examples/market/models/schema.yaml deleted file mode 100644 index 2ed59782a..000000000 --- a/examples/market/models/schema.yaml +++ /dev/null @@ -1,752 +0,0 @@ -version: 2 -entities: - - slug: company - name: Company - description: Portfolio company or deal pipeline company - icon: building - color: '#2563eb' - metadata_schema: - type: object - properties: - market: - type: string - x-table-column: true - x-table-label: Market - sector: - type: string - enum: - - bio-health - - ai - - fintech - - crypto - - consumer - x-table-column: true - x-table-label: Sector - category: - type: string - enum: - - portfolio - - recruiter - - prospect - x-table-column: true - x-table-label: Category - location: - type: string - x-table-column: true - x-table-label: Location - domain: - type: string - description: Normalized company domain used by identity-engine hosted_domain facts - x-identity-namespace: - namespace: hosted_domain - normalize: lowercase - x-table-column: true - x-table-label: Domain - one_liner: - type: string - team_size: - type: integer - founding_year: - type: integer - funding_raised: - type: string - valuation: - type: string - revenue: - type: string - growth_rate: - type: string - traction_score: - type: number - thesis: - type: string - stage: - type: string - enum: - - idea - - pre-seed - - seed - - series-a - - series-b - - series-c - - growth - - public - linkedin_url: - type: string - format: uri - logo_url: - type: string - format: uri - description: Brand logo URL - tagline: - type: string - description: One-line brand tagline - brand_voice: - type: string - description: Brand voice / tone-of-voice notes - social_handles: - type: object - description: Brand social handles by platform (twitter, linkedin, github, …) - properties: - twitter: - type: string - linkedin: - type: string - github: - type: string - youtube: - type: string - instagram: - type: string - tiktok: - type: string - additionalProperties: - type: string - - slug: founder - name: Founder - description: Company founder or co-founder - icon: user - color: '#7c3aed' - metadata_schema: - type: object - properties: - role: - type: string - x-table-column: true - x-table-label: Role - sector: - type: string - enum: - - bio-health - - ai - - fintech - - crypto - - consumer - x-table-column: true - x-table-label: Sector - location: - type: string - x-table-column: true - x-table-label: Location - specialties: - type: array - items: - type: string - x-table-column: true - x-table-label: Specialties - background: - type: string - linkedin_url: - type: string - format: uri - twitter_handle: - type: string - education: - type: string - career_history: - type: array - items: - type: object - properties: - title: - type: string - company: - type: string - start: - type: string - end: - type: string - notable_exits: - type: array - items: - type: string - provenance: - type: string - enum: - - inbound - - outbound - - referral - - event - - portfolio - x-table-relationships: - - label: Owner - direction: outbound - relationship_type: primary_relationship_owner - - label: Company - direction: outbound - relationship_type: works_at - - slug: fund-round - name: Fund Round - description: Investment round (seed, series A, etc.) - icon: dollar-sign - color: '#10b981' - metadata_schema: - type: object - properties: - round_type: - type: string - enum: - - preseed - - seed - - series_a - - series_b - - series_c - - series_d - - growth - - ipo - x-table-column: true - x-table-label: Round Type - amount_usd: - type: number - x-table-column: true - x-table-label: Amount (USD) - date: - type: string - format: date - x-table-column: true - x-table-label: Date - lead_investor_slug: - type: string - x-table-column: true - x-table-label: Lead Investor - x-link-entity-type: investor - x-link-lookup-field: slug - post_money_usd: - type: number - participants: - type: array - items: - type: string - - slug: investor - name: Investor - description: VC firm, angel investor, or fund - icon: banknote - color: '#059669' - metadata_schema: - type: object - properties: - investor_type: - type: string - enum: - - vc_firm - - angel - - corporate - - accelerator - - family_office - - partner - x-table-column: true - x-table-label: Type - sector_focus: - type: array - items: - type: string - x-table-column: true - x-table-label: Sector Focus - website: - type: string - format: uri - x-table-column: true - x-table-label: Website - sector: - type: string - enum: - - bio-health - - ai - - fintech - - crypto - - consumer - x-table-column: true - x-table-label: Sector - bio: - type: string - fund_size: - type: string - stage_focus: - type: array - items: - type: string - linkedin_url: - type: string - format: uri - portfolio_url: - type: string - format: uri - typical_check_size: - type: string - - slug: job-posting - name: Job Posting - description: Open role at a market.company - icon: briefcase - color: '#f59e0b' - metadata_schema: - type: object - oneOf: - - required: - - posted_by_founder_id - not: - required: - - posted_by_member_id - - required: - - posted_by_member_id - not: - required: - - posted_by_founder_id - properties: - role: - type: string - x-table-column: true - x-table-label: Role - title: - type: string - x-table-column: true - x-table-label: Title - company_id: - type: integer - description: FK to market.company - x-table-column: true - x-table-label: Company - x-link-entity-type: company - posted_by_founder_id: - type: integer - description: FK to market.founder if posted by a verified founder - x-link-entity-type: founder - posted_by_member_id: - type: integer - description: FK to market.$member if posted by an authorized member who isn't a founder - x-link-entity-type: $member - city_id: - type: integer - description: FK to atlas.city (cross-org reference, optional) - x-table-column: true - x-table-label: City - description: - type: string - status: - type: string - enum: - - open - - filled - - closed - x-table-column: true - x-table-label: Status - posted_at: - type: string - format: date-time - expires_at: - type: string - format: date-time - - slug: product - name: Product - description: Company product tracked for reviews and market signals - icon: box - color: '#3B82F6' - metadata_schema: - type: object - properties: - tagline: - type: string - x-table-column: true - x-table-label: Tagline - target_audience: - type: string - x-table-column: true - x-table-label: Target Audience - value_proposition: - type: string - x-table-column: true - x-table-label: Value Proposition - key_features: - type: array - items: - type: string - differentiators: - type: string - - slug: sector - name: Sector - description: Investment thesis / practice area - icon: chart-line - color: '#6366f1' - metadata_schema: - type: object - properties: - sector_key: - type: string - enum: - - bio-health - - ai - - fintech - - crypto - - consumer - x-table-column: true - x-table-label: Sector Key - description: - type: string - x-table-column: true - x-table-label: Description - lead_partner_slug: - type: string - x-table-column: true - x-table-label: Lead Partner - x-link-entity-type: investor - x-link-lookup-field: slug - color: - type: string -relationships: - - slug: educated_at - name: Educated At - description: Founder was educated at a university (cross-org reference into atlas.university) - rules: - - source: founder - target: university - metadata_schema: - type: object - properties: - degree: - type: string - field: - type: string - start_year: - type: integer - end_year: - type: integer - - slug: founded_by - name: Founded By - description: Company was founded by this person - metadata_schema: - type: object - properties: - equity_pct: - type: number - founding_date: - type: string - format: date - - slug: headquartered_in - name: Headquartered In - description: Company is headquartered in a city (cross-org reference into atlas.city) - rules: - - source: company - target: city - metadata_schema: - type: object - properties: - since: - type: string - format: date - address: - type: string - - slug: in_industry - name: In Industry - description: Company is in an industry (cross-org reference into atlas.industry) - rules: - - source: company - target: industry - metadata_schema: - type: object - properties: - primary: - type: boolean - description: Whether this is the company's primary industry classification - - slug: in_sector - name: In Sector - - slug: invested_in - name: Invested In - description: Investor has invested in this company - metadata_schema: - type: object - properties: - round: - type: string - amount: - type: number - lead: - type: boolean - date: - type: string - format: date - - slug: mentions - name: Mentions - description: Loose reference — one entity is mentioned in the context of another - metadata_schema: - type: object - properties: - confidence: - type: number - description: Optional 0-1 confidence in the mention - source: - type: string - description: Where the mention was observed - - slug: operates_in - name: Operates In - description: Company operates in a country or region (cross-org reference into atlas.country or atlas.region) - rules: - - source: company - target: country - - source: company - target: region - metadata_schema: - type: object - properties: - since: - type: string - format: date - primary: - type: boolean - description: Whether this is the company's primary operating geography - - slug: previously_at - name: Previously At - - slug: primary_relationship_owner - name: Primary Relationship Owner - - slug: round_led_by - name: Round Led By - - slug: round_of - name: Round Of - - slug: sourced_by - name: Sourced By - - slug: uses_technology - name: Uses Technology - description: Company uses a technology in its stack (cross-org reference into atlas.technology) - rules: - - source: company - target: technology - metadata_schema: - type: object - properties: - role: - type: string - description: How the technology is used (e.g. primary database, observability, frontend framework) - since: - type: string - format: date - - slug: works_at - name: Works At - rules: - - source: $member - target: company - - source: founder - target: company - auto_create_when: - - sourceNamespace: hosted_domain - targetField: domain - assuranceRequired: oauth_verified - matchStrategy: unique_only -watchers: - - slug: founder-activity-tracker - agent: vc-tracking - name: Founder Activity Tracker - schedule: 0 10 * * * - notification_priority: normal - tags: [vc, founders, daily] - min_cooldown_seconds: 600 - reaction_script: ./reactions/founder-activity-tracker.reaction.ts - prompt: | - You are a venture capital analyst tracking the public activity of startup founders in your portfolio. - - ## Founders - {{#each entities}} - - {{name}} ({{entity_type}}, ID: {{id}}) - {{/each}} - - ## Recent Founder Activity - {{#if sources.founder_posts}} - {{sources.founder_posts}} - {{/if}} - - --- - - Produce a structured founder activity report: - 1. **Executive Summary**: 2-3 sentence overview of founder activity and signals. - 2. **Per-Founder Analysis**: For each active founder, summarize their messaging themes, engagement level, and signals about company direction. - 3. **Cross-Portfolio Patterns**: Themes multiple founders discuss. - 4. **Notable Signals**: Flag potential announcements, strategic shifts, or concerns. - - Be specific and cite actual tweets/posts as evidence. - extraction_schema: - type: object - required: - - summary - - founders - - notable_signals - properties: - summary: - type: string - founders: - type: array - items: - type: object - required: - - name - - company - - activity_level - - themes - properties: - name: - type: string - company: - type: string - activity_level: - type: string - enum: - - high - - medium - - low - - inactive - themes: - type: array - items: - type: string - sentiment: - type: string - enum: - - bullish - - neutral - - cautious - - concerned - signals: - type: array - items: - type: string - notable_posts: - type: array - items: - type: string - cross_patterns: - type: array - items: - type: object - properties: - theme: - type: string - founders_involved: - type: array - items: - type: string - notable_signals: - type: array - items: - type: object - required: - - signal - - founder - - impact - properties: - signal: - type: string - founder: - type: string - impact: - type: string - enum: - - high - - medium - - low - sources: - - name: founder_posts - query: | - SELECT id, title, payload_text, author_name, source_url, occurred_at, score, origin_type, connector_key FROM events WHERE connector_key IN ('x') AND origin_type IN ('tweet', 'reply') ORDER BY occurred_at DESC LIMIT 300 - reactions_guidance: | - When a founder signals hiring activity, fundraising, or pivots, flag for the investment team. - Track founders going quiet as a potential concern. - Alert on any public statements about competitors or market conditions. - - slug: opportunity-matcher - agent: vc-tracking - name: Opportunity Matcher - schedule: 0 */12 * * * - notification_priority: normal - tags: [vc, matching] - min_cooldown_seconds: 600 - prompt: | - You are a community intelligence agent for a private founder community managed by a venture capital fund. - Your job is to monitor founder activity and identify high-quality introduction opportunities between portfolio founders. - - ## Community Members - {{#each entities}} - **{{name}}** ({{entity_type}}) - {{#if metadata.title}} — {{metadata.title}}{{/if}} - {{#if metadata.role}} — {{metadata.role}}{{/if}} - {{/each}} - - ## Recent Activity - {{#if sources.content}} - {{sources.content}} - {{/if}} - - ## Instructions - 1. Scan all new content for signals: launches, posts, hiring announcements, funding news, project updates, and collaboration signals. - 2. For each signal, identify which other community founders are likely to care and explain why. - 3. Suggest a concrete action: warm intro draft, shared-interest notification, or flagging for community ops review. - 4. Only suggest introductions where there is a clear, specific overlap — not generic "both work in tech" matches. - 5. Rate each signal's strength (high/medium/low) based on timeliness and relevance. - extraction_schema: - type: object - required: - - signals - - intro_recommendations - - summary - properties: - signals: - type: array - items: - type: object - required: - - type - - source - - summary - - strength - - related_topics - - interested_members - - reason - - suggested_action - properties: - type: - type: string - source: - type: string - summary: - type: string - strength: - type: string - enum: - - high - - medium - - low - related_topics: - type: array - items: - type: string - interested_members: - type: array - items: - type: string - reason: - type: string - suggested_action: - type: string - intro_recommendations: - type: array - items: - type: object - required: - - member_a - - member_b - - overlap - - confidence - properties: - member_a: - type: string - member_b: - type: string - overlap: - type: string - draft_intro: - type: string - confidence: - type: string - enum: - - high - - medium - summary: - type: string - sources: - - name: content - query: | - SELECT id, title, payload_text, author_name, source_url, occurred_at, score, origin_type, connector_key FROM events WHERE entity_id IN (SELECT id FROM entities WHERE entity_type = 'founder') ORDER BY occurred_at DESC LIMIT 300 diff --git a/examples/office-bot/lobu.toml b/examples/office-bot/lobu.toml deleted file mode 100644 index a67528847..000000000 --- a/examples/office-bot/lobu.toml +++ /dev/null @@ -1,79 +0,0 @@ -# lobu.toml — Office Bot -# Docs: https://lobu.ai/docs/getting-started -# -# Office Bot is an umbrella project for office-ops agents that live in a team -# chat. The first (and so far only) agent is `food-ordering`: it runs the -# weekday lunch flow — who's in, collect recommendations, post the options, -# gather everyone's order, then assemble a Deliveroo basket and hand the -# checkout link to a human. -# -# Target platform: Slack (a Slack connection added to the office channel). While -# developing, you don't need any chat platform at all — drive the agent over the -# CLI: `lobu chat -a food-ordering ""` against a local `lobu run`. -# -# Connections are configured in the org (admin UI / API), not here. The -# food-ordering agent needs: -# - a Slack chat connection on the office channel (prod) — none for CLI dev -# - the two `lunch-*` watchers below (defined as `type: watcher` models) -# - Deliveroo browser-auth cookies, captured with: -# lobu memory browser-auth --connector deliveroo --auth-profile-slug office -# -# Future office agents (desk-booking, supplies, socials, …) get their own -# [agents.] block here and their own ./agents// dir. - -[agents.food-ordering] -name = "food-ordering" -description = "Runs the office lunch order — presence check, recommendations, options poll, order collection, Deliveroo basket handoff" -dir = "./agents/food-ordering" - -[[agents.food-ordering.providers]] -id = "z-ai" -model = "z-ai/glm-4.7" -key = "$Z_AI_API_KEY" - -# Public Slack Preview (the hosted "Lobu Developer" workspace) — `lobu run` -# prints a `/lobu link ` you redeem in that workspace, then messages there -# route to this agent. Lets you demo the lunch flow without standing up your own -# Slack app. `channel` surface so it works in a channel, not just a DM. -[agents.food-ordering.preview.slack] -enabled = true -surfaces = ["dm", "channel"] -code_ttl_minutes = 15 - -[agents.food-ordering.network] -# The chat transport (Slack) is the gateway's job, not the worker's — the worker -# only needs to fetch playwright/chromium for the deliveroo-order skill. -allowed = [ - "api.z.ai", ".z.ai", - "registry.npmjs.org", ".npmjs.org", - "playwright.azureedge.net", "cdn.playwright.dev", -] -# Deliveroo goes through the egress judge — reading menus and assembling a -# basket is fine; touching payment, addresses, or the account profile is not. -# Each domain names the "deliveroo" policy below. -judge = [ - { domain = "deliveroo.co.uk", judge = "deliveroo" }, - { domain = ".deliveroo.co.uk", judge = "deliveroo" }, - { domain = "deliveroo.com", judge = "deliveroo" }, - { domain = ".deliveroo.com", judge = "deliveroo" }, -] - -[agents.food-ordering.network.judges] -deliveroo = """ -Allow GET requests that read restaurant listings, menus, item details, and the -current basket. Allow POST/PUT requests whose effect is limited to building or -modifying a basket / group order (adding, removing, changing quantity of items; -creating a shareable group-order link). DENY anything that completes checkout, -submits payment, reads or writes saved payment methods, changes the delivery -address, or modifies the account profile. If the request's effect is unclear, -fail closed and deny with a reason. -""" - -[memory] -organization_id = "UdNAH1bb3csC842vhOgxAHVcfX4tYU5A" -enabled = true -org = "lobu-team" -name = "Lobu Team" -description = "Office-ops agents — first up: the weekday lunch order" -models = "./models" -data = "./data" diff --git a/examples/office-bot/models/lunch.yaml b/examples/office-bot/models/lunch.yaml deleted file mode 100644 index c344c3137..000000000 --- a/examples/office-bot/models/lunch.yaml +++ /dev/null @@ -1,153 +0,0 @@ -version: 2 - -entities: - - slug: lunch-run - name: Lunch run - description: One day's office lunch order — who's in, what they ordered, the restaurant, the basket link, and where it ended up - icon: utensils - color: "#F97316" - metadata_schema: - type: object - required: - - date - - channel - - status - properties: - date: - type: string - description: ISO date of the run (one run per day) - x-table-label: Date - x-table-column: true - channel: - type: string - description: The chat channel/conversation the run happened in - x-table-label: Channel - status: - type: string - enum: [collecting, done, cancelled] - x-table-label: Status - x-table-column: true - restaurant: - type: string - x-table-label: Restaurant - x-table-column: true - thread_ref: - type: string - description: Reference to the thread/message where the run is happening — lunch-finalize uses this to find the conversation - items: - type: array - description: Per-person order lines - items: - type: object - properties: - person: { type: string } - item: { type: string } - price: { type: number } - notes: { type: string } - subtotal: - type: number - x-table-label: Subtotal - x-table-column: true - basket_url: - type: string - description: Deliveroo group-order / basket link handed to a human, or null if placed manually - notes: - type: string - -watchers: - - slug: lunch-open - agent: food-ordering - name: Open the lunch run - # Workdays 11:00 Europe/London — post the lunch call and open the thread. - schedule: "0 11 * * 1-5" - notification_priority: high - notification_channel: both - tags: [lunch, daily] - min_cooldown_seconds: 600 - prompt: | - Open today's office lunch run (step 1 in your instructions): - - 1. Check memory for a `lunch-run` entity dated today — if one exists and isn't - cancelled, stop (don't open a second one). - 2. Guess who's in from recent chat activity and past `lunch-run` entities. - 3. Post the lunch call in the channel: react 🍕 / "+1" to join, drop restaurant - recommendations, options coming ~11:35, targeting ~12:30 delivery. @-mention - the people you think are in, but make clear anyone can join or skip. - 4. Open a thread off that message. - 5. Save a `lunch-run` entity {date, channel, status: "collecting", thread_ref, - restaurant: null, items: []} and a `lunch:opened` event linked to it. - - Then end — the lunch-finalize watcher takes it from here. Keep it to one short - message in the channel. - extraction_schema: - type: object - required: - - opened - properties: - opened: - type: boolean - description: true if a new run was opened, false if one already existed - in_office_guess: - type: array - items: { type: string } - thread_ref: - type: string - - - slug: lunch-finalize - agent: food-ordering - name: Collect orders and hand off - # Workdays 11:35 Europe/London — read the thread, post options/collect orders, - # build the Deliveroo basket, post the summary, hand off to a human. - schedule: "35 11 * * 1-5" - notification_priority: high - tags: [lunch, daily] - min_cooldown_seconds: 600 - reactions_guidance: | - When the run ends in `placed` or `manual`, store the basket link + per-head cost - back into a `lunch:placed` event on the lunch-run entity so the next day's - lunch-open can read the most-recent restaurant. - prompt: | - Finalize today's office lunch run (step 2 in your instructions): - - 1. Find today's `lunch-run` entity (status "collecting"). If there isn't one, - open one (step 1) and stop. If it's already "done"/"cancelled", do nothing. - 2. Read the run's thread — work out who's in (🍕 / "+1" / put in an order) and - any restaurant recommendations. If nobody's in: post a "skipping today 👋" - note, set the run to "cancelled", save a `lunch:cancelled` event, stop. - 3. Pick the restaurant (a clear thread recommendation, else a usual spot from - USER.md, biased away from the last couple of runs). - 4. Post the options — if the deliveroo-order skill can scrape the menu, a - numbered shortlist of ~5–8 popular items with prices; otherwise just name - the restaurant (a link to its Deliveroo page is fine). Always accept - free-text orders. - 5. Collect orders from replies + number reactions into items: [{person, item, - price?, notes}]. Ask directly about anything ambiguous — don't guess silently. - 6. Build the Deliveroo basket via the deliveroo-order skill (login with stored - cookies → add items → group-order/basket link + subtotal). If it fails for - any reason, fall back: basket_url = null, continue. - 7. Post the summary in the thread: restaurant; per-person list (@person — item - (notes)); subtotal + per-head (flag if well over budget); the basket link if - you have one; and the next action — "@here someone hit checkout & pay: - " or, with no link, "@here someone needs to place this manually". - 8. Update the `lunch-run` entity (status "done", restaurant, items, subtotal, - basket_url) and save a `lunch:placed` event linked to it. - - Never complete checkout or pay. A run with no basket automation is still a - success if the order list got collected and handed off cleanly. - extraction_schema: - type: object - required: - - outcome - properties: - outcome: - type: string - enum: [placed, manual, cancelled, no-run] - description: placed = basket link handed off; manual = order list handed off without a link; cancelled = nobody in; no-run = no run existed to finalize - restaurant: - type: string - headcount: - type: integer - subtotal: - type: number - basket_url: - type: string diff --git a/examples/personal-finance/lobu.toml b/examples/personal-finance/lobu.toml deleted file mode 100644 index 200c0b7b7..000000000 --- a/examples/personal-finance/lobu.toml +++ /dev/null @@ -1,34 +0,0 @@ -# lobu.toml — Personal Finance agent (UK Self Assessment) -# Docs: https://lobu.ai/docs/getting-started - -[agents.personal-finance] -name = "personal-finance" -description = "Help individuals capture wages, expenses, savings, dividends, capital gains and pension contributions across the tax year and assemble a UK Self Assessment (SA100) return." -dir = "./agents/personal-finance" - -[[agents.personal-finance.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - -[agents.personal-finance.network] -allowed = [ - ".gov.uk", - "github.com", - ".github.com", - ".githubusercontent.com", - "registry.npmjs.org", - ".npmjs.org", -] - -[agents.personal-finance.worker] -# pdftotext (poppler) + csv tooling for statement parsing. See INGESTION.md. -nix_packages = ["poppler_utils", "csvtk"] - -[memory] -enabled = true -org = "personal-finance" -name = "Personal Finance" -description = "UK Self Assessment helper — captures financial activity across the tax year and assembles SA100 + supplementary pages." -models = "./models" -data = "./data" diff --git a/examples/personal-finance/models/schema.yaml b/examples/personal-finance/models/schema.yaml deleted file mode 100644 index bb377691d..000000000 --- a/examples/personal-finance/models/schema.yaml +++ /dev/null @@ -1,1346 +0,0 @@ -version: 2 -entities: - - slug: account - name: Account - description: A bank, savings, brokerage, pension, mortgage, or business account. Owner is always set via the owned_by relationship (or co_owned_by for joint accounts) — never inferred from context. - icon: wallet - color: '#3B82F6' - metadata_schema: - type: object - required: - - provider - - wrapper - properties: - provider: - type: string - description: Bank or broker name (e.g. "Monzo", "Hargreaves Lansdown") - x-table-label: Provider - x-table-column: true - wrapper: - type: string - enum: - - current - - savings - - business_current - - business_savings - - ISA - - LISA - - JISA - - SIPP - - workplace_pension - - GIA - - mortgage - - credit_card - - loan - - other - description: Account class. Drives tax treatment (ISA = no SA reporting, GIA = CGT applies, etc.). - x-table-label: Wrapper - x-table-column: true - currency: - type: string - description: ISO 4217 currency code - default: GBP - x-table-label: Ccy - x-table-column: true - account_number_last4: - type: string - description: Last 4 digits, for matching against statements - sort_code: - type: string - iban: - type: string - description: For non-UK accounts; preferred over sort_code+account_number when known - opening_balance: - type: string - description: Decimal string, e.g. "1234.56" - closing_balance: - type: string - notes: - type: string - - slug: allowance_window - name: Allowance Window - description: A materialized accumulator for one tax allowance over one tax year. Lets the agent answer "how much ISA budget left this year?" or "how much pension annual allowance can I still use?" instantly without recomputing across all underlying transactions/contributions every time. - icon: gauge - color: '#84CC16' - metadata_schema: - type: object - required: - - kind - - cap - - used - properties: - kind: - type: string - enum: - - isa_subscription - - dividend_allowance - - personal_savings_allowance - - cgt_annual_exempt - - pension_annual_allowance - - property_income_allowance - - trading_allowance - - personal_allowance - description: Which HMRC-defined allowance this window tracks - x-table-label: Allowance - x-table-column: true - cap: - type: string - description: Decimal GBP. The statutory limit for this allowance in this year (e.g. "20000" for ISA, "60000" for pension AA). - x-table-label: Cap - x-table-column: true - used: - type: string - description: Decimal GBP consumed so far. Updated on every relevant transaction/contribution write. - x-table-label: Used - x-table-column: true - remaining: - type: string - description: Decimal GBP. cap minus used minus carry_forward used. May go negative if a tapered allowance applies (the agent surfaces this). - x-table-label: Remaining - x-table-column: true - carry_forward_in: - type: string - description: For pension AA — unused allowance carried in from the prior 3 years. - carry_forward_out: - type: string - description: Unused this year, available to carry forward (subject to the allowance's rules). - last_recomputed_at: - type: string - format: date-time - description: When the agent last recomputed used/remaining from underlying entities. - - slug: asset_lot - name: Asset Lot - description: An acquisition lot used for s.104 share-pool / matching rules. One lot per buy event. - icon: layers - color: '#A78BFA' - metadata_schema: - type: object - required: - - acquisition_date - - quantity - - cost_basis - properties: - pool_id: - type: string - description: Identifier for the s.104 pool (typically the ticker/ISIN) - x-table-label: Pool - x-table-column: true - acquisition_date: - type: string - format: date - x-table-label: Acquired - x-table-column: true - quantity: - type: string - x-table-label: Quantity - x-table-column: true - cost_basis: - type: string - description: Total cost for this lot, decimal GBP - x-table-label: Cost - x-table-column: true - quantity_remaining: - type: string - description: After partial disposals - - slug: cgt_event - name: CGT Event - description: A capital-gains disposal — sale, gift, or other event triggering CGT (SA108). - icon: scissors - color: '#F59E0B' - metadata_schema: - type: object - required: - - asset_description - - asset_class - - disposal_date - - disposal_proceeds - properties: - asset_description: - type: string - x-table-label: Asset - x-table-column: true - asset_class: - type: string - enum: - - listed_shares - - unlisted_shares - - residential_property - - other_property - - crypto - - other - x-table-label: Class - x-table-column: true - acquisition_date: - type: string - format: date - acquisition_cost: - type: string - description: Total acquisition cost, decimal string GBP - disposal_date: - type: string - format: date - x-table-label: Disposal - x-table-column: true - disposal_proceeds: - type: string - description: Total proceeds, decimal string GBP - x-table-label: Proceeds - x-table-column: true - incidental_costs: - type: string - description: Legal, broker, SDLT on acquisition, enhancement - relief_claimed: - type: string - enum: - - none - - PRR - - BADR - - investors_relief - - gift_holdover - - EIS_deferral - - SEIS_deferral - default: none - x-table-label: Relief - x-table-column: true - residential_60day_return_ref: - type: string - description: HMRC reference if a 60-day residential CGT return was already filed - - slug: company - name: Company - description: A legal entity that can hold accounts, file tax returns, employ people, or be owned. Covers Ltd, PLC, LLP, sole-trader, partnership, trust, and charity. Discriminate by company_type. - icon: building - color: '#0EA5E9' - metadata_schema: - type: object - required: - - legal_name - - company_type - not: - anyOf: - - required: - - hmrc_utr - - required: - - hmrc_paye_reference - - required: - - companies_house_number - - required: - - vat_number - - required: - - hmrc_ni_number - properties: - legal_name: - type: string - x-table-label: Name - x-table-column: true - company_type: - type: string - enum: - - ltd - - plc - - llp - - sole_trader - - partnership - - trust - - charity - - foreign - x-table-label: Type - x-table-column: true - incorporation_date: - type: string - format: date - registered_address: - type: string - accounting_period_start: - type: string - format: date - description: Start of the company's accounting reference period (CT600 / SA800 anchor) - accounting_period_end: - type: string - format: date - vat_registered: - type: boolean - default: false - x-table-label: VAT - x-table-column: true - vat_scheme: - type: string - enum: - - standard - - flat_rate - - cash_accounting - - annual_accounting - - none - default: none - is_personal_service_company: - type: boolean - default: false - description: Marks PSCs (relevant for IR35 / off-payroll-working rules) - dormant_flag: - type: boolean - default: false - ceased_date: - type: string - format: date - notes: - type: string - - slug: contribution - name: Contribution - description: A pension or charitable contribution affecting tax (Gift Aid, SIPP, etc.). - icon: piggy-bank - color: '#7C3AED' - metadata_schema: - type: object - required: - - scheme - - mechanism - - amount - - date - properties: - scheme: - type: string - description: Provider/charity name - x-table-label: Scheme - x-table-column: true - mechanism: - type: string - enum: - - relief_at_source - - net_pay - - salary_sacrifice - - gift_aid - description: Pension relief mechanism, or gift_aid for charitable donations - x-table-label: Mechanism - x-table-column: true - amount: - type: string - description: Net amount paid, decimal GBP - x-table-label: Amount - x-table-column: true - date: - type: string - format: date - x-table-label: Date - x-table-column: true - carry_back_to_prior_year: - type: boolean - default: false - description: Gift Aid carry-back election - - slug: document - name: Document - description: A source document — P60, P45, P11D, SA302, broker contract note, mortgage statement, bank statement — that other entities are parsed from. - icon: file-text - color: '#6B7280' - metadata_schema: - type: object - required: - - doc_type - - source - properties: - doc_type: - type: string - enum: - - P60 - - P45 - - P11D - - SA302 - - bank_statement - - savings_statement - - broker_statement - - contract_note - - dividend_voucher - - mortgage_statement - - rental_agreement - - receipt - - other - x-table-label: Type - x-table-column: true - source: - type: string - enum: - - gmail - - whatsapp_upload - - manual - x-table-label: Source - x-table-column: true - download_url: - type: string - format: uri - description: Signed gateway artifact URL - payer_or_employer: - type: string - description: Counterparty named on the document - captured_at: - type: string - format: date-time - - slug: expense - name: Expense - description: An allowable expense against a trade or property. - icon: receipt - color: '#DC2626' - metadata_schema: - type: object - required: - - category - - amount - - date - properties: - category: - type: string - enum: - - cost_of_goods - - travel - - premises - - repairs - - admin - - advertising - - interest_finance - - professional_fees - - wages - - utilities - - insurance - - agent_fees - - other - x-table-label: Category - x-table-column: true - amount: - type: string - description: Decimal GBP - x-table-label: Amount - x-table-column: true - date: - type: string - format: date - x-table-label: Date - x-table-column: true - notes: - type: string - is_capital: - type: boolean - default: false - description: Capital vs revenue (capital expenses go to capital_allowances, not expenses) - - slug: filing_obligation - name: Filing Obligation - description: A required tax return or filing the user (or one of their companies) must submit by a deadline. Captures SA100, CT600, SA800, SA900, VAT101, P11D, etc. Lets the agent surface deadlines proactively and reconcile against actual filings. - icon: clock - color: '#F97316' - metadata_schema: - type: object - required: - - return_form - - period_start - - period_end - - deadline_type - - due_date - properties: - return_form: - type: string - enum: - - SA100 - - SA800 - - SA900 - - CT600 - - VAT101 - - P11D - - PAYE_RTI - - confirmation_statement - x-table-label: Form - x-table-column: true - period_start: - type: string - format: date - period_end: - type: string - format: date - deadline_type: - type: string - enum: - - paper_filing - - online_filing - - balancing_payment - - poa1 - - poa2 - - corp_tax_payment - - corp_tax_filing - - vat_payment - - registration - x-table-label: Deadline - x-table-column: true - due_date: - type: string - format: date - x-table-label: Due - x-table-column: true - status: - type: string - enum: - - upcoming - - reminded - - overdue - - filed - - paid - - waived - default: upcoming - x-table-label: Status - x-table-column: true - completed_date: - type: string - format: date - hmrc_reference: - type: string - description: HMRC submission receipt or reference number, once filed. - - slug: goal - name: Goal - description: A personal financial goal (emergency fund, deposit, retirement target, etc.). - icon: target - color: '#EC4899' - metadata_schema: - type: object - required: - - name - - target_amount - - category - properties: - name: - type: string - x-table-label: Goal - x-table-column: true - target_amount: - type: string - description: Decimal GBP - x-table-label: Target - x-table-column: true - target_date: - type: string - format: date - x-table-label: By - x-table-column: true - category: - type: string - enum: - - emergency_fund - - deposit - - retirement - - debt_payoff - - other - x-table-label: Category - x-table-column: true - current_amount: - type: string - description: Optional snapshot, decimal GBP - - slug: holding - name: Holding - description: A current security position in a brokerage account. - icon: trending-up - color: '#8B5CF6' - metadata_schema: - type: object - required: - - ticker - - quantity - - as_of_date - properties: - ticker: - type: string - x-table-label: Ticker - x-table-column: true - isin: - type: string - quantity: - type: string - description: Decimal string - x-table-label: Quantity - x-table-column: true - avg_cost: - type: string - description: Average cost per unit (s.104 pool), decimal string - currency: - type: string - default: GBP - as_of_date: - type: string - format: date - x-table-label: As of - x-table-column: true - - slug: income_source - name: Income Source - description: A recurring origin of income (employer, trade, dividend payer, interest payer, rental property, pension, foreign source). - icon: banknote - color: '#22C55E' - metadata_schema: - type: object - required: - - type - properties: - type: - type: string - enum: - - employment - - self_employment - - dividend - - interest - - rental - - pension - - foreign - x-table-label: Type - x-table-column: true - payer_name: - type: string - x-table-label: Payer - x-table-column: true - country: - type: string - description: ISO 3166-1 alpha-2; non-GB triggers SA106 - foreign_tax_paid: - type: string - description: Decimal — total foreign tax withheld at source for the tax year, in foreign_tax_currency. Drives Foreign Tax Credit Relief (FTCR) on SA106. - foreign_tax_currency: - type: string - description: ISO 4217 of the foreign_tax_paid amount. Usually matches the income currency. - withholding_jurisdiction: - type: string - description: ISO 3166-1 alpha-2 of the country that withheld the tax. May differ from `country` (e.g. US dividends paid via a UK broker — withheld in US, paid to UK). - treaty_rate_applied: - type: string - description: Decimal — treaty withholding rate already applied at source (e.g. "0.15" for the 15% US/UK treaty rate on dividends). Used to flag over-withholding that may be recoverable from the source country. - notes: - type: string - - slug: payment - name: Payment - description: A payment to or from HMRC — balancing payments, payments on account, corporation tax, VAT remittances, refunds. Distinct from generic transactions because it ties to filing_obligation and tax_assessment for reconciliation. - icon: credit-card - color: '#DB2777' - metadata_schema: - type: object - required: - - amount - - currency - - date - - direction - - kind - properties: - amount: - type: string - description: Decimal — always positive - x-table-label: Amount - x-table-column: true - currency: - type: string - default: GBP - date: - type: string - format: date - x-table-label: Date - x-table-column: true - direction: - type: string - enum: - - to_hmrc - - from_hmrc - x-table-label: Direction - x-table-column: true - kind: - type: string - enum: - - balancing_payment - - poa1 - - poa2 - - corp_tax - - vat - - paye_nic - - refund - - penalty - - interest - x-table-label: Kind - x-table-column: true - reference: - type: string - description: HMRC payment reference (UTR + K, or CT-specific accounting reference) - method: - type: string - enum: - - bank_transfer - - direct_debit - - debit_card - - cheque - - paye_coding - - slug: property - name: Property - description: Real estate. Use for primary residences (PRR on disposal), let properties (SA105/SA106), holiday lets (FHL), and commercial real estate. Owner is set via owned_by or co_owned_by; never put owner in metadata. - icon: home - color: '#EA580C' - metadata_schema: - type: object - required: - - address - - type - - use - properties: - address: - type: string - x-table-label: Address - x-table-column: true - type: - type: string - enum: - - residential - - commercial - - mixed_use - - land - x-table-label: Type - x-table-column: true - use: - type: string - description: How the property is used. Drives tax treatment more than physical type does. - enum: - - primary_residence - - let - - FHL - - commercial_let - - mixed_use - - investment_held - x-table-label: Use - x-table-column: true - country: - type: string - description: ISO 3166-1 alpha-2; non-GB triggers SA106 - default: GB - rental_income_allowance_claimed: - type: boolean - default: false - description: £1,000 property income allowance flag - purchase_date: - type: string - format: date - purchase_cost: - type: string - description: Decimal GBP — useful for PRR calculation on eventual disposal - - slug: relief_claim - name: Relief Claim - description: A tax relief or allowance claim (Gift Aid, marriage allowance, EIS/SEIS, BADR, PRR). - icon: shield-check - color: '#059669' - metadata_schema: - type: object - required: - - type - properties: - type: - type: string - enum: - - gift_aid - - marriage_allowance - - EIS - - SEIS - - BADR - - PRR - - investors_relief - - foreign_tax_credit - x-table-label: Type - x-table-column: true - amount: - type: string - description: Decimal GBP if applicable - x-table-label: Amount - x-table-column: true - notes: - type: string - - slug: tax_assessment - name: Tax Assessment - description: A computed or HMRC-issued tax position for one tax year, one subject. Captures SA302 outputs (HMRC's view) + agent-computed projections (our view) so we can reconcile and surface differences. - icon: file-bar-chart - color: '#7C3AED' - metadata_schema: - type: object - required: - - source - - total_tax_due - - computed_at - properties: - source: - type: string - enum: - - agent_projection - - hmrc_sa302 - - hmrc_ct600_acknowledgement - - manual - description: Where this assessment came from. agent_projection = our running estimate; hmrc_* = the authority's number. - x-table-label: Source - x-table-column: true - total_income: - type: string - description: Decimal GBP — sum of all income sources before allowances - total_tax_due: - type: string - description: Decimal GBP — final tax liability for the year - x-table-label: Tax due - x-table-column: true - tax_paid_at_source: - type: string - description: PAYE + dividend tax withheld + foreign tax credit - balancing_owed: - type: string - description: total_tax_due - tax_paid_at_source - poa_paid - allowances_used: - type: object - description: Per-allowance breakdown (personal_allowance, dividend_allowance, psa, cgt_aea, etc.) - computed_at: - type: string - format: date-time - hmrc_reference: - type: string - - slug: tax_year - name: Tax Year - description: A UK fiscal year (6 April to 5 April) — the container all reportable activity is anchored to. - icon: calendar - color: '#0EA5E9' - metadata_schema: - type: object - required: - - year_label - - start - - end - properties: - year_label: - type: string - description: Year label, e.g. "2025-26" - x-table-label: Year - x-table-column: true - start: - type: string - format: date - description: Inclusive start, e.g. 2025-04-06 - end: - type: string - format: date - description: Inclusive end, e.g. 2026-04-05 - filing_status: - type: string - enum: - - in_progress - - assembled - - filed - description: Where the user is in the cycle - x-table-label: Status - x-table-column: true - filed_at: - type: string - format: date-time - residence_status: - type: string - enum: - - uk_resident - - non_resident - - split_year_arriver - - split_year_leaver - - dual_resident - description: | - UK tax residence for THIS year. Recorded per-tax_year because residence - can change (someone moving in/out of the UK has different status year - to year). Drives SA109 routing. - x-table-label: Residence - x-table-column: true - arrival_date: - type: string - format: date - description: For split-year arrivers — date residence began - departure_date: - type: string - format: date - description: For split-year leavers — date residence ended - - slug: transaction - name: Transaction - description: A single debit or credit on an account. - icon: arrow-left-right - color: '#10B981' - metadata_schema: - type: object - required: - - date - - amount - - currency - properties: - date: - type: string - format: date - x-table-label: Date - x-table-column: true - amount: - type: string - description: Decimal string. Positive = credit, negative = debit. - x-table-label: Amount - x-table-column: true - currency: - type: string - default: GBP - description: - type: string - x-table-label: Description - x-table-column: true - merchant_raw: - type: string - description: Verbatim merchant text from the statement; resolved/categorised later. - tax_relevance: - type: string - enum: - - none - - income - - expense - - cgt - description: Whether this transaction matters for the SA return. - x-table-label: Tax - x-table-column: true - expense_category: - type: string - description: HMRC-aligned category for allowable expenses (cost_of_goods, travel, premises, repairs, admin, advertising, interest, professional_fees, wages, other). - is_personal: - type: boolean - default: true - native_amount: - type: string - description: Decimal amount in the foreign currency, when currency != GBP. Keep alongside `amount` so the agent can show both numbers and recompute if rates need correcting. - native_currency: - type: string - description: ISO 4217 currency code of native_amount (e.g. "USD", "EUR"). When set, the `currency` field on this transaction is GBP and native_currency is the original. - fx_rate_to_gbp: - type: string - description: Decimal — the FX rate snapshot used to convert native_amount to amount (GBP). Source the rate from the transaction date. Required when native_currency is set so HMRC-aligned conversion is auditable. - fx_rate_source: - type: string - description: Where the FX rate came from (e.g. "hmrc_monthly", "broker_statement", "ecb_daily"). Helps reconcile if HMRC's published rate differs. -relationships: - - slug: account_contains - name: Account Contains - description: An account contains a transaction or holding. - metadata_schema: - type: object - properties: {} - - slug: accountant_for - name: Accountant For - description: One subject acts as accountant or agent for another. Lets a hired accountant Lobu user be granted access to a client's $member or company entity later. Source can be either $member or company; target can be either. - metadata_schema: - type: object - properties: - engagement_start: - type: string - format: date - engagement_end: - type: string - format: date - scope: - type: string - enum: - - self_assessment - - corporation_tax - - vat - - payroll - - full_service - - slug: accumulates_in - name: Accumulates In - description: A transaction or contribution counts toward an allowance window. E.g. an ISA deposit accumulates_in the year's isa_subscription window; a pension contribution accumulates_in the year's pension_annual_allowance window. - metadata_schema: - type: object - properties: - amount_counted: - type: string - description: Decimal — usually equals the underlying transaction amount, but can differ (e.g. employer pension match counts toward AA but not toward your contribution) - - slug: assessment_for - name: Assessment For - description: A tax_assessment is for a particular tax_year and subject. Used to anchor agent projections and HMRC SA302 outputs to the same year + filer so they can be compared. - metadata_schema: - type: object - properties: {} - - slug: co_owned_by - name: Co-owned By - description: An asset is jointly owned by multiple subjects. One row per co-owner. Sum of share_pct across all co-owners should equal 100. - metadata_schema: - type: object - required: - - share_pct - properties: - share_pct: - type: number - minimum: 0 - maximum: 100 - role: - type: string - enum: - - primary_holder - - joint_holder - - beneficial_owner - default: joint_holder - - slug: controls - name: Controls - description: A person or company exercises significant control over a company (PSC register entry under the Companies Act). Source can be $member or company. - metadata_schema: - type: object - properties: - control_type: - type: string - enum: - - shares_over_25_pct - - voting_rights_over_25_pct - - right_to_appoint_majority_directors - - significant_influence_or_control - - trust_or_firm_control - declared_date: - type: string - format: date - - slug: director_of - name: Director Of - description: A person is a registered director of a company. - metadata_schema: - type: object - properties: - appointment_date: - type: string - format: date - resignation_date: - type: string - format: date - - slug: disposal_of - name: Disposal Of - description: A CGT event disposes of (all or part of) an asset lot. - metadata_schema: - type: object - properties: - quantity_disposed: - type: string - description: Decimal — partial vs full disposal - - slug: employed_by - name: Employed By - description: An employment-type income source flows from a particular employer (a company entity). Pairs with employee_of when the agent has the direct subject-to-subject employment fact. - metadata_schema: - type: object - properties: {} - - slug: employee_of - name: Employee Of - description: A person is employed by a company. Replaces the older `employed_by` indirection through `income_source` for direct subject-to-subject employment facts. - metadata_schema: - type: object - properties: - employment_start: - type: string - format: date - employment_end: - type: string - format: date - description: From P45 if the employment ended in this tax year - paye_reference: - type: string - description: PAYE reference assigned by the employer (e.g. "123/AB456") - role: - type: string - - slug: expense_of - name: Expense Of - description: An expense is incurred against a subject — a $member (personal allowable expense), a property (SA105/SA106), or a company (operating cost on the business books). - metadata_schema: - type: object - properties: {} - - slug: for_tax_year - name: For Tax Year - description: An entity (transaction, cgt_event, contribution, relief_claim, expense) is recorded against a particular tax year. - metadata_schema: - type: object - properties: {} - - slug: income_from - name: Income From - description: A transaction is income from a particular source (employer, dividend payer, interest payer, rental, etc.). - metadata_schema: - type: object - properties: - gross_amount: - type: string - description: Gross decimal GBP if different from the net transaction amount - tax_deducted: - type: string - description: PAYE / withholding deducted at source, decimal GBP - - slug: obligation_for - name: Obligation For - description: A filing_obligation belongs to a tax_year and a subject ($member or company). The same SA100 obligation is "for" the user's $member and "for" their tax_year. - metadata_schema: - type: object - properties: {} - - slug: owned_by - name: Owned By - description: An asset (account, holding, asset_lot, property) is owned by a subject ($member or company). Use co_owned_by instead when ownership is shared. - metadata_schema: - type: object - properties: {} - - slug: parsed_from - name: Parsed From - description: An entity (transaction, cgt_event, holding, etc.) was parsed from a source document — provenance link. - metadata_schema: - type: object - properties: - extraction_confidence: - type: number - minimum: 0 - maximum: 1 - line_number: - type: integer - description: Optional anchor into the source document - - slug: partner_in - name: Partner In - description: A person is a partner in an LLP or partnership. Drives SA104 routing for partnership income. - metadata_schema: - type: object - properties: - partnership_share_pct: - type: number - minimum: 0 - maximum: 100 - profit_share_pct: - type: number - minimum: 0 - maximum: 100 - description: May differ from capital share if the partnership agreement says so - joined_date: - type: string - format: date - left_date: - type: string - format: date - - slug: settles - name: Settles - description: A payment settles part or all of a filing_obligation (e.g. balancing_payment settles SA100 balancing). One filing_obligation may be settled by multiple payments. - metadata_schema: - type: object - properties: - portion_settled: - type: string - description: Decimal — how much of the obligation this payment covers (defaults to the full payment amount when not specified) - - slug: shareholder_of - name: Shareholder Of - description: A person or company holds shares in a company. Source can be either $member or company (companies can own other companies). - metadata_schema: - type: object - properties: - share_class: - type: string - description: e.g. "ordinary", "A ordinary", "preference" - shareholding_pct: - type: number - minimum: 0 - maximum: 100 - shares_held: - type: integer - description: Number of shares (alternative to percentage when share count is known) - acquired_date: - type: string - format: date - - slug: spouse_of - name: Spouse Of - description: Marriage or civil partnership. Symmetric. Relevant for marriage allowance, jointly held assets, and inheritance planning. - metadata_schema: - type: object - properties: - relationship_kind: - type: string - enum: - - marriage - - civil_partnership - partnership_date: - type: string - format: date - dissolution_date: - type: string - format: date - - slug: transfer_pair - name: Transfer Pair - description: Two transactions are the two legs of an internal transfer between accounts the same subject controls (e.g. Jane's current → Jane's savings). Salary or distributions crossing subject boundaries (Ltd current → Jane personal) are NOT internal transfers and must not be linked here. Symmetric. When this link exists, neither side counts as taxable income or as an allowable expense. - metadata_schema: - type: object - properties: - direction: - type: string - enum: - - outbound - - inbound - description: Which leg this row represents — outbound (debit on source) or inbound (credit on destination) -watchers: - - slug: gmail-tx - agent: personal-finance - name: Gmail financial-event extractor - schedule: '*/30 * * * *' - notification_priority: low - tags: [personal-finance, gmail, ingestion] - min_cooldown_seconds: 300 - prompt: | - You are a private financial accountant scanning the user's forwarded Gmail messages for events that matter to a UK Self Assessment return. - - ## Recent emails - {{#if sources.gmail_messages}} - {{sources.gmail_messages}} - {{else}} - No new messages this window. - {{/if}} - - ## Active tax year - {{#if entities}} - {{#each entities}} - - {{name}} ({{entity_type}}, ID: {{id}}) - {{/each}} - {{else}} - No tax year context provided. - {{/if}} - - --- - - Identify and extract financial events. Each email may yield zero, one, or many events. Be conservative: skip noise (marketing, password resets, etc.). - - Categories to extract: - - **transactions** — deposits, debits, transfers, salary credits, dividend payments hitting an account - - **cgt_events** — broker contract notes for sells/disposals, gifts, transfers out of a GIA - - **dividends** — UK or foreign dividend notifications (gross + currency) - - **documents** — P60/P45/P11D/SA302/contract notes/mortgage statements arriving as attachments or linked PDFs - - For each item, include the source `gmail_message_id` so we can link provenance. Prefer GBP unless the message clearly states a different currency. - - Skip transactions inside ISAs and SIPPs unless they are dividends or contributions (which are still reportable). Mark `tax_relevance="none"` for ISA-internal transactions; mark `tax_relevance="cgt"` for non-wrapper disposals. - extraction_schema: - type: object - required: - - transactions - - cgt_events - - dividends - - documents - properties: - transactions: - type: array - items: - type: object - required: - - date - - amount - - currency - - description - - gmail_message_id - properties: - date: - type: string - format: date - amount: - type: string - description: Decimal string. Positive = credit, negative = debit. - currency: - type: string - description: - type: string - merchant_raw: - type: string - account_hint: - type: string - description: Free-text hint about which account ("Monzo current", "HL ISA", etc.). Resolved later. - tax_relevance: - type: string - enum: - - none - - income - - expense - - cgt - gmail_message_id: - type: string - cgt_events: - type: array - items: - type: object - required: - - asset_description - - asset_class - - disposal_date - - disposal_proceeds - - gmail_message_id - properties: - asset_description: - type: string - asset_class: - type: string - enum: - - listed_shares - - unlisted_shares - - residential_property - - other_property - - crypto - - other - acquisition_date: - type: string - format: date - acquisition_cost: - type: string - disposal_date: - type: string - format: date - disposal_proceeds: - type: string - incidental_costs: - type: string - gmail_message_id: - type: string - dividends: - type: array - items: - type: object - required: - - payer - - gross - - currency - - date - - gmail_message_id - properties: - payer: - type: string - gross: - type: string - currency: - type: string - date: - type: string - format: date - country: - type: string - description: ISO 3166-1 alpha-2 if foreign - gmail_message_id: - type: string - documents: - type: array - items: - type: object - required: - - doc_type - - gmail_message_id - properties: - doc_type: - type: string - enum: - - P60 - - P45 - - P11D - - SA302 - - bank_statement - - savings_statement - - broker_statement - - contract_note - - dividend_voucher - - mortgage_statement - - rental_agreement - - receipt - - other - payer_or_employer: - type: string - tax_year_hint: - type: string - description: Tax year label if visible on the document, e.g. "2025-26" - gmail_message_id: - type: string - sources: - - name: gmail_messages - query: | - SELECT id, title, payload_text, payload_html, occurred_at FROM events WHERE connector_key = 'google.gmail' ORDER BY occurred_at DESC LIMIT 200 - reactions_guidance: | - After extracting: - 1. Resolve or create the active `tax_year` entity from the user's profile. Each new transaction / cgt_event / contribution must be linked to it via `for_tax_year`. - 2. For each `documents[]` entry, create a `document` entity (source="gmail") and use it as the `parsed_from` target for the transactions / cgt_events / dividends extracted from that same gmail_message_id. - 3. For each `transactions[]` entry, resolve or create the `account` from `account_hint` and link via `account_contains`. If income, create or resolve an `income_source` and link via `income_from`. - 4. For `cgt_events[]`, look up matching `asset_lot` rows in the same `pool_id` and link via `disposal_of`. If acquisition data is missing, save a note flagging the gap rather than guessing. - 5. For `dividends[]`, create a `transaction(tax_relevance=income)` linked to an `income_source(type=dividend, payer_name, country)`. - 6. Never overwrite a user-edited entity. If a duplicate is suspected (same date + amount + account), surface it as a question instead of writing. diff --git a/examples/sales/lobu.toml b/examples/sales/lobu.toml deleted file mode 100644 index 93a78afc5..000000000 --- a/examples/sales/lobu.toml +++ /dev/null @@ -1,24 +0,0 @@ -# lobu.toml — Agent configuration -# Docs: https://lobu.ai/docs/getting-started - -[agents.sales] -name = "sales" -description = "Help revenue teams track account health, rollout progress, and renewal signals" -dir = "./agents/sales" - -[[agents.sales.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - - -[agents.sales.network] -allowed = ["github.com", ".github.com", ".githubusercontent.com", "registry.npmjs.org", ".npmjs.org"] - -[memory] -enabled = true -org = "sales" -name = "Sales" -description = "Help revenue teams track account health, rollout progress, and renewal signals" -models = "./models" -data = "./data" diff --git a/examples/sales/models/schema.yaml b/examples/sales/models/schema.yaml deleted file mode 100644 index a2b287a01..000000000 --- a/examples/sales/models/schema.yaml +++ /dev/null @@ -1,161 +0,0 @@ -version: 2 -entities: - - slug: organization - name: Organization - description: A customer account or prospect being tracked by the revenue team - icon: building - color: '#3B82F6' - metadata_schema: - type: object - properties: - company_name: - type: string - x-table-label: Company - x-table-column: true - stage: - type: string - x-table-label: Stage - x-table-column: true - arr: - type: string - x-table-label: ARR - x-table-column: true - renewal_date: - type: string - x-table-label: Renewal Date - x-table-column: true - - slug: product - name: Product - description: A product rollout or pilot being tracked at a customer account - icon: package - color: '#F59E0B' - metadata_schema: - type: object - properties: - product_name: - type: string - x-table-label: Product - x-table-column: true - pilot_status: - type: string - x-table-label: Status - x-table-column: true - owner_team: - type: string - x-table-label: Owner - x-table-column: true - account: - type: string - x-table-label: Account - x-table-column: true - - slug: region - name: Region - description: A geographic region where an account is expanding or operating - icon: globe - color: '#10B981' - metadata_schema: - type: object - properties: - region_name: - type: string - x-table-label: Region - x-table-column: true - expansion_status: - type: string - x-table-label: Status - x-table-column: true - parent_account: - type: string - x-table-label: Account - x-table-column: true - market_size: - type: string - x-table-label: Market Size - - slug: renewal-risk - name: Renewal Risk - description: A commercial signal or concern that affects an upcoming renewal or expansion - icon: alert-triangle - color: '#EF4444' - metadata_schema: - type: object - properties: - signal: - type: string - x-table-label: Signal - x-table-column: true - severity: - type: string - x-table-label: Severity - x-table-column: true - affects: - type: string - x-table-label: Affects - x-table-column: true - next_step: - type: string - x-table-label: Next Step - x-table-column: true - - slug: team - name: Team - description: An internal team or customer function that owns a pilot or initiative - icon: users - color: '#8B5CF6' - metadata_schema: - type: object - properties: - team_name: - type: string - x-table-label: Team - x-table-column: true - role: - type: string - x-table-label: Role - x-table-column: true - owns: - type: string - x-table-label: Owns - x-table-column: true - account: - type: string - x-table-label: Account - x-table-column: true -relationships: - - slug: affects - name: Affects - description: Connect commercial signals directly to the renewal or expansion they influence. - - slug: expanded-into - name: Expanded Into - description: Track where an account is growing so territory and rollout context stay explicit. - - slug: runs - name: Runs - description: Link the internal team or customer function to the pilot they own. -watchers: - - slug: account-health-monitor - agent: sales - name: Account health monitor - schedule: 0 */12 * * * - notification_priority: high - notification_channel: both - tags: [sales, health, renewals] - min_cooldown_seconds: 1800 - reaction_script: ./reactions/account-health-monitor.reaction.ts - prompt: | - Poll CRM data for tracked accounts. Track expansion progress, risk level changes, and renewal timeline. - extraction_schema: - type: object - required: - - risk_level - - expansion_status - - renewal_blockers - - activity_delta - properties: - risk_level: - type: string - expansion_status: - type: string - renewal_blockers: - type: array - items: - type: string - activity_delta: - type: string diff --git a/packages/cli/package.json b/packages/cli/package.json index 330a14ec2..9dccba3dd 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -89,7 +89,6 @@ "react": "^19.2.5", "resend": "^6.6.0", "sharp": "^0.34.4", - "smol-toml": "^1.3.1", "tar": "^7.4.3", "vite": "^6.0.0", "winston": "^3.17.0", diff --git a/packages/cli/src/commands/_lib/apply/__tests__/desired-state-extra.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/desired-state-extra.test.ts deleted file mode 100644 index 432b89ade..000000000 --- a/packages/cli/src/commands/_lib/apply/__tests__/desired-state-extra.test.ts +++ /dev/null @@ -1,586 +0,0 @@ -/** - * Extra `loadDesiredState` tests for edge-cases not covered in desired-state.test.ts: - * - watcher with missing `agent` field → ValidationError - * - watcher referencing an agent not in lobu.toml → ValidationError - * - missing lobu.toml → ValidationError - * - memory block absent → watchers/entityTypes empty - * - memory.enabled = false → skips model loading - * - duplicate watcher slugs across model files → last-one-wins or both collected - * - connection feed with too-frequent cron (< 1 min) → ValidationError - * - auth_profile with credential on oauth_account → ValidationError (regression) - */ - -import { afterEach, describe, expect, test } from "bun:test"; -import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { loadDesiredState } from "../desired-state.js"; -import { ValidationError } from "../../../memory/_lib/errors.js"; - -const tempDirs: string[] = []; - -afterEach(() => { - while (tempDirs.length > 0) { - const d = tempDirs.pop(); - if (d) rmSync(d, { recursive: true, force: true }); - } -}); - -function mkProject(toml: string): string { - const dir = mkdtempSync(join(tmpdir(), "lobu-ds-extra-")); - tempDirs.push(dir); - writeFileSync(join(dir, "lobu.toml"), toml); - return dir; -} - -const BASE_TOML = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -enabled = true -org = "dev" -models = "./models" -`; - -function mkProjectWithModels(files: Record): string { - const dir = mkProject(BASE_TOML); - mkdirSync(join(dir, "models"), { recursive: true }); - for (const [name, body] of Object.entries(files)) { - writeFileSync(join(dir, "models", name), body); - } - return dir; -} - -// ── Missing lobu.toml ───────────────────────────────────────────────────────── - -describe("loadDesiredState — missing lobu.toml", () => { - test("throws ValidationError when lobu.toml is absent", async () => { - const dir = mkdtempSync(join(tmpdir(), "lobu-no-toml-")); - tempDirs.push(dir); - // No lobu.toml created - await expect(loadDesiredState({ cwd: dir })).rejects.toBeInstanceOf( - ValidationError - ); - }); -}); - -// ── Watcher agent-field validation ─────────────────────────────────────────── - -describe("loadDesiredState — watcher validation", () => { - test("watcher with agent not in lobu.toml → ValidationError", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: orphan-watcher - name: "Orphan" - agent: nonexistent-agent - prompt: Do something. - schedule: "0 9 * * 1" -`, - }); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /nonexistent-agent/ - ); - }); - - test("watcher with empty prompt → ValidationError", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: empty-prompt - name: "Empty Prompt" - agent: triage - prompt: "" - schedule: "0 9 * * 1" -`, - }); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow(/prompt/); - }); - - test("valid watcher referencing the correct agent passes", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: valid-watcher - name: "Valid Watcher" - agent: triage - prompt: "Do something useful." - schedule: "0 9 * * 1" -`, - }); - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.watchers).toHaveLength(1); - expect(state.watchers[0]!.slug).toBe("valid-watcher"); - }); -}); - -// ── memory.enabled = false ──────────────────────────────────────────────────── - -describe("loadDesiredState — memory.enabled = false", () => { - test("skips model loading when memory.enabled is false", async () => { - const toml = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -enabled = false -org = "dev" -models = "./models" -`; - const dir = mkProject(toml); - mkdirSync(join(dir, "models"), { recursive: true }); - writeFileSync( - join(dir, "models", "schema.yaml"), - `version: 2 -entities: - - slug: company - name: Company -` - ); - - const { state } = await loadDesiredState({ cwd: dir }); - // Memory disabled → no entity types loaded - expect(state.memorySchema.entityTypes).toHaveLength(0); - expect(state.watchers).toHaveLength(0); - }); -}); - -// ── No memory block ─────────────────────────────────────────────────────────── - -describe("loadDesiredState — no memory block", () => { - test("no memory block → empty schema and no watchers", async () => { - const toml = `[agents.triage] -name = "Triage" -dir = "./agents/triage" -`; - const dir = mkProject(toml); - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.memorySchema.entityTypes).toHaveLength(0); - expect(state.memorySchema.relationshipTypes).toHaveLength(0); - expect(state.watchers).toHaveLength(0); - expect(state.memory).toBeUndefined(); - }); -}); - -// ── Feed cron too-frequent ──────────────────────────────────────────────────── - -describe("loadDesiredState — feed cron validation", () => { - const TOML_WITH_CONNECTORS = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -connectors = "./connectors" -`; - - function mkConnProject(files: Record): string { - const dir = mkProject(TOML_WITH_CONNECTORS); - mkdirSync(join(dir, "connectors"), { recursive: true }); - for (const [name, body] of Object.entries(files)) { - writeFileSync(join(dir, "connectors", name), body); - } - return dir; - } - - test("feed schedule with interval < 1 min → passes (exactly 60s meets the threshold)", async () => { - // "* * * * *" fires every 60s — the threshold is `< 60_000ms`, so 60s is - // NOT rejected. This test documents the actual boundary behaviour. - const dir = mkConnProject({ - "x.yaml": `version: 1 -type: connection -slug: hn -connector: hackernews -feeds: - - feed: stories - schedule: "* * * * *" -`, - }); - // Does NOT throw — 60s meets the minimum - const { state } = await loadDesiredState({ cwd: dir, env: {} }); - const conn = state.connectors.connections[0]; - expect(conn?.feeds[0]?.schedule).toBe("* * * * *"); - }); - - test("invalid cron expression → ValidationError", async () => { - const dir = mkConnProject({ - "x.yaml": `version: 1 -type: connection -slug: hn -connector: hackernews -feeds: - - feed: stories - schedule: "not-a-cron" -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /invalid cron expression/ - ); - }); - - test("valid hourly feed schedule passes", async () => { - const dir = mkConnProject({ - "x.yaml": `version: 1 -type: connection -slug: hn -connector: hackernews -feeds: - - feed: stories - schedule: "0 * * * *" -`, - }); - const { state } = await loadDesiredState({ cwd: dir, env: {} }); - const conn = state.connectors.connections[0]; - expect(conn?.feeds[0]?.schedule).toBe("0 * * * *"); - }); -}); - -// ── Duplicate connection slugs ──────────────────────────────────────────────── - -describe("loadDesiredState — duplicate connection slugs", () => { - test("two connection docs with the same slug in the same file → ValidationError", async () => { - const toml = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -connectors = "./connectors" -`; - const dir = mkProject(toml); - mkdirSync(join(dir, "connectors"), { recursive: true }); - writeFileSync( - join(dir, "connectors", "dup.yaml"), - `version: 1 -type: connection -slug: my-conn -connector: hackernews ---- -version: 1 -type: connection -slug: my-conn -connector: rss -` - ); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /duplicate connection slug "my-conn"/ - ); - }); -}); - -// ── memory.org and organization_id in state ─────────────────────────────────── - -describe("loadDesiredState — memory block fields", () => { - test("memory.org is surfaced in state.memory.org", async () => { - const toml = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -org = "acme" -`; - const dir = mkProject(toml); - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.memory?.org).toBe("acme"); - }); - - test("organization_id is surfaced in state.memory.organizationId", async () => { - const toml = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -org = "acme" -organization_id = "org_xyz" -`; - const dir = mkProject(toml); - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.memory?.organizationId).toBe("org_xyz"); - }); -}); - -// ── --only flag skips connector loading ──────────────────────────────────────── - -describe("loadDesiredState — --only flag", () => { - const TOML_BOTH = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -connectors = "./connectors" -org = "dev" -models = "./models" -`; - - test("only=agents: connectors not loaded (no secret expansion)", async () => { - const dir = mkProject(TOML_BOTH); - mkdirSync(join(dir, "connectors"), { recursive: true }); - writeFileSync( - join(dir, "connectors", "auth.yaml"), - `version: 1 -type: auth_profile -slug: hn-token -connector: hackernews -kind: env -credentials: - HN_TOKEN: $HN_API_TOKEN -` - ); - // $HN_API_TOKEN is NOT set — --only agents must not expand it - const { state } = await loadDesiredState({ - cwd: dir, - env: {}, - only: "agents", - }); - expect(state.connectors.authProfiles).toHaveLength(0); - }); - - test("only=memory: agents still loaded (desired agent list present)", async () => { - const dir = mkProject(TOML_BOTH); - mkdirSync(join(dir, "models"), { recursive: true }); - const { state } = await loadDesiredState({ cwd: dir, only: "memory" }); - // agents are still populated even with --only memory - expect(state.agents).toHaveLength(1); - // connectors skipped - expect(state.connectors.authProfiles).toHaveLength(0); - }); -}); - -// ── Watcher admin-only fields ──────────────────────────────────────────────── - -describe("loadDesiredState — watcher admin-only fields", () => { - test("watcher with reaction_script reads sibling .ts and resolves relative to YAML", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: with-reaction - name: With Reaction - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - reaction_script: ./funnel.reaction.ts -`, - "funnel.reaction.ts": "export default async (ctx, client) => {};\n", - }); - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.watchers).toHaveLength(1); - const w = state.watchers[0]!; - expect(w.reactionScript?.sourceCode).toContain("export default async"); - expect(w.reactionScript?.sourcePath).toContain("funnel.reaction.ts"); - }); - - test("watcher with reaction_script pointing at missing file → ValidationError", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: bad-reaction - name: Bad - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - reaction_script: ./nonexistent.ts -`, - }); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /reaction_script.*does not exist/ - ); - }); - - test("inline reaction_script string (not a path) → ValidationError", async () => { - // The hint here is that inline scripts are rejected — they'd skip IDE - // type-checking and the path-vs-source ambiguity is the whole reason we - // require a sibling file. - const dir = mkProjectWithModels({ - // smol-toml + yaml libraries can parse multiline literals fine; we just - // need a string that doesn't look like a path AND fails the file read. - "w.yaml": `version: 2 -watchers: - - slug: inline-reaction - name: Inline - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - reaction_script: "export default async () => {};" -`, - }); - // Falls through to the "does not exist" branch since the source string - // is interpreted as a path. - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /reaction_script/ - ); - }); - - test("watcher with all admin-only scalar fields parses correctly", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: full - name: Full watcher - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - reactions_guidance: "Be terse." - device_worker_id: 550e8400-e29b-41d4-a716-446655440000 - scheduler_client_id: mcp-client-1 - notification_channel: both - notification_priority: high - min_cooldown_seconds: 60 - tags: [crm, weekly] - agent_kind: notifier -`, - }); - const { state } = await loadDesiredState({ cwd: dir }); - const w = state.watchers[0]!; - expect(w.reactionsGuidance).toBe("Be terse."); - expect(w.deviceWorkerId).toBe("550e8400-e29b-41d4-a716-446655440000"); - expect(w.schedulerClientId).toBe("mcp-client-1"); - expect(w.notificationChannel).toBe("both"); - expect(w.notificationPriority).toBe("high"); - expect(w.minCooldownSeconds).toBe(60); - expect(w.tags).toEqual(["crm", "weekly"]); - expect(w.agentKind).toBe("notifier"); - }); - - test("watcher with non-UUID device_worker_id → ValidationError", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: bad-device - name: Bad device - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - device_worker_id: not-a-uuid -`, - }); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /device_worker_id.*UUID/ - ); - }); - - test("watcher with invalid notification_priority → ValidationError", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: bad-priority - name: Bad priority - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - notification_priority: critical -`, - }); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /notification_priority/ - ); - }); - - test("watcher with too-frequent cron → ValidationError", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: too-frequent - name: Too frequent - agent: triage - prompt: "Do work." - schedule: "*/30 * * * * *" -`, - }); - // The 6-field cron is rejected as an invalid expression at validate time; - // the diagnostic should mention the schedule. - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow(/schedule/i); - }); -}); - -// ── Connection device_worker_id ────────────────────────────────────────────── - -describe("loadDesiredState — connection device_worker_id", () => { - test("connection with device_worker_id UUID parses correctly", async () => { - const dir = mkProject(BASE_TOML); - mkdirSync(join(dir, "connectors"), { recursive: true }); - writeFileSync( - join(dir, "connectors", "c.yaml"), - `version: 1 -type: connection -slug: my-conn -connector: example -device_worker_id: 550e8400-e29b-41d4-a716-446655440000 -` - ); - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.connectors.connections[0]?.deviceWorkerId).toBe( - "550e8400-e29b-41d4-a716-446655440000" - ); - }); - - test("connection with non-UUID device_worker_id → ValidationError", async () => { - const dir = mkProject(BASE_TOML); - mkdirSync(join(dir, "connectors"), { recursive: true }); - writeFileSync( - join(dir, "connectors", "c.yaml"), - `version: 1 -type: connection -slug: my-conn -connector: example -device_worker_id: not-a-uuid -` - ); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /device_worker_id.*UUID/ - ); - }); -}); - -// ── Reaction script path traversal / size guards ──────────────────────────── - -describe("loadDesiredState — reaction_script path validation", () => { - test("absolute path is rejected", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: bad-reaction - name: Bad - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - reaction_script: /etc/passwd -`, - }); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /relative POSIX path/ - ); - }); - - test(".. segment is rejected", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: bad-reaction - name: Bad - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - reaction_script: ../../../etc/passwd -`, - }); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /must not contain `\.\.`/ - ); - }); - - test("non-.ts extension is rejected", async () => { - const dir = mkProjectWithModels({ - "w.yaml": `version: 2 -watchers: - - slug: bad-reaction - name: Bad - agent: triage - prompt: "Do work." - schedule: "0 9 * * 1" - reaction_script: ./reactions/funnel.js -`, - }); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /must end in `\.ts`/ - ); - }); -}); diff --git a/packages/cli/src/commands/_lib/apply/__tests__/desired-state.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/desired-state.test.ts deleted file mode 100644 index d11b567be..000000000 --- a/packages/cli/src/commands/_lib/apply/__tests__/desired-state.test.ts +++ /dev/null @@ -1,826 +0,0 @@ -import { afterEach, describe, expect, test } from "bun:test"; -import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { buildStablePlatformId, loadDesiredState } from "../desired-state.js"; - -describe("buildStablePlatformId — keep in sync with file-loader.ts", () => { - test("two parts when no name", () => { - expect(buildStablePlatformId("triage", "telegram")).toBe("triage-telegram"); - }); - test("three parts when name provided", () => { - expect(buildStablePlatformId("triage", "slack", "ops")).toBe( - "triage-slack-ops" - ); - }); - test("slugifies non-alphanumeric chars in agent + type + name", () => { - expect(buildStablePlatformId("Tri Age", "Slack/Ops", "Bot 1")).toBe( - "tri-age-slack-ops-bot-1" - ); - }); -}); - -describe("loadDesiredState", () => { - const tempDirs: string[] = []; - - afterEach(() => { - while (tempDirs.length > 0) { - const dir = tempDirs.pop(); - if (dir) rmSync(dir, { recursive: true, force: true }); - } - }); - - function mkProject(toml: string): string { - const dir = mkdtempSync(join(tmpdir(), "lobu-apply-")); - tempDirs.push(dir); - writeFileSync(join(dir, "lobu.toml"), toml); - return dir; - } - - test("resolves provider $VAR keys onto DesiredAgent.providerKeys", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[[agents.triage.providers]] -id = "anthropic" -key = "$ANTHROPIC_API_KEY" - -[[agents.triage.providers]] -id = "openai" -# Intentionally no key — operator wires via UI / per-user auth profile. -` - ); - const { state } = await loadDesiredState({ - cwd: dir, - env: { ANTHROPIC_API_KEY: "sk-anth-real-value" }, - }); - expect(state.agents[0]!.providerKeys).toEqual([ - { providerId: "anthropic", value: "sk-anth-real-value" }, - ]); - // Sanity: settings still record both providers as installed. - expect(state.agents[0]!.settings.installedProviders).toHaveLength(2); - }); - - test("collects $VAR references from platforms + providers", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -description = "" -dir = "./agents/triage" - -[[agents.triage.providers]] -id = "anthropic" -key = "$ANTHROPIC_API_KEY" - -[[agents.triage.platforms]] -type = "telegram" -[agents.triage.platforms.config] -botToken = "$TELEGRAM_BOT_TOKEN" -` - ); - // Provide an empty agent dir so markdown read returns nothing. - const { state } = await loadDesiredState({ - cwd: dir, - env: { - ANTHROPIC_API_KEY: "sk-anth-fake", - TELEGRAM_BOT_TOKEN: "tg-fake-token", - }, - }); - expect(state.requiredSecrets).toEqual([ - "ANTHROPIC_API_KEY", - "TELEGRAM_BOT_TOKEN", - ]); - expect(state.agents).toHaveLength(1); - expect(state.agents[0]!.metadata.agentId).toBe("triage"); - expect(state.agents[0]!.platforms).toHaveLength(1); - expect(state.agents[0]!.platforms[0]!.stableId).toBe("triage-telegram"); - expect(state.agents[0]!.platforms[0]!.config.botToken).toBe( - "tg-fake-token" - ); - }); - - test("throws when a platform $VAR ref is unset in the apply env", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[[agents.triage.platforms]] -type = "telegram" -[agents.triage.platforms.config] -botToken = "$TELEGRAM_BOT_TOKEN" -` - ); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /\$TELEGRAM_BOT_TOKEN/ - ); - }); - - test("rejects duplicate (type, name) platform pairs", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[[agents.triage.platforms]] -type = "slack" -[agents.triage.platforms.config] -botToken = "x" - -[[agents.triage.platforms]] -type = "slack" -[agents.triage.platforms.config] -botToken = "y" -` - ); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /multiple "slack" platforms/ - ); - }); - - test("carries Slack platform `channels` onto the desired platform", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[[agents.triage.platforms]] -type = "slack" -channels = ["T0ABCDEF/C0123ABCD", "T0ABCDEF/C0456WXYZ"] -[agents.triage.platforms.config] -botToken = "x" -` - ); - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.agents[0]!.platforms[0]!.channels).toEqual([ - "T0ABCDEF/C0123ABCD", - "T0ABCDEF/C0456WXYZ", - ]); - }); - - test("rejects malformed Slack `channels` entries", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[[agents.triage.platforms]] -type = "slack" -channels = ["C0123ABCD"] -[agents.triage.platforms.config] -botToken = "x" -` - ); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /\// - ); - }); - - test("rejects `channels` on a non-Slack platform", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[[agents.triage.platforms]] -type = "telegram" -channels = ["T0ABCDEF/C0123ABCD"] -[agents.triage.platforms.config] -botToken = "x" -` - ); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /only supported for Slack/ - ); - }); - - test("loads local skills and merges skill network, nix, and MCP declarations", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[agents.triage.network] -allowed = ["api.operator.example.com"] - -[agents.triage.worker] -nix_packages = ["git"] -` - ); - const skillDir = join(dir, "agents", "triage", "skills", "docs-search"); - mkdirSync(skillDir, { recursive: true }); - writeFileSync( - join(skillDir, "SKILL.md"), - `--- -name: docs-search -description: Search docs safely -nixPackages: [ripgrep] -network: - allow: ["*.docs.example.com", "*"] -mcpServers: - docs: - url: "https://docs.example.com/mcp" ---- -Use the docs MCP before answering. -` - ); - - const { state } = await loadDesiredState({ cwd: dir }); - const settings = state.agents[0]!.settings; - expect(settings.skillsConfig?.skills[0]?.name).toBe("docs-search"); - expect(settings.networkConfig?.allowedDomains).toEqual([ - "api.operator.example.com", - ".docs.example.com", - ]); - expect(settings.nixConfig?.packages).toEqual(["git", "ripgrep"]); - expect(settings.mcpServers?.docs?.url).toBe("https://docs.example.com/mcp"); - }); - - test("rejects stale nested memory config", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory.lobu] -enabled = false -org = "dev" -models = "./custom-models" -` - ); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow(/lobu/); - }); - - test("loads watcher model files into state.watchers", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -enabled = true -org = "dev" -models = "./models" -` - ); - const modelsDir = join(dir, "models"); - mkdirSync(modelsDir, { recursive: true }); - writeFileSync( - join(modelsDir, "digest.yaml"), - `version: 2 -watchers: - - slug: weekly-digest - agent: triage - name: Weekly digest - description: A short weekly summary. - schedule: "0 9 * * 1" - prompt: | - Produce a short weekly digest. - extraction_schema: - type: object - required: [summary] - properties: - summary: { type: string } - sources: - - name: content - query: SELECT * FROM events ORDER BY occurred_at DESC -` - ); - - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.watchers).toHaveLength(1); - const w = state.watchers[0]!; - expect(w.slug).toBe("weekly-digest"); - expect(w.agent).toBe("triage"); - expect(w.name).toBe("Weekly digest"); - expect(w.description).toBe("A short weekly summary."); - expect(w.schedule).toBe("0 9 * * 1"); - expect(w.prompt).toContain("weekly digest"); - expect(w.extractionSchema).toMatchObject({ - type: "object", - required: ["summary"], - }); - expect(w.sources).toEqual([ - { - name: "content", - query: "SELECT * FROM events ORDER BY occurred_at DESC", - }, - ]); - }); - - test("loads dbt-style bundled model files recursively", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -enabled = true -org = "dev" -models = "./models" -` - ); - const domainDir = join(dir, "models", "sales"); - mkdirSync(domainDir, { recursive: true }); - writeFileSync( - join(domainDir, "schema.yml"), - `version: 2 -entities: - - slug: account - name: Account - description: Customer account - metadata_schema: - type: object - required: [tier] - properties: - tier: { type: string } -relationships: - - slug: owns - name: Owns - rules: - - source: account - target: product -watchers: - - slug: account-digest - agent: triage - name: Account digest - schedule: "0 9 * * 1" - prompt: Summarize account changes. -` - ); - - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.memorySchema.entityTypes).toEqual([ - { - slug: "account", - name: "Account", - description: "Customer account", - required: ["tier"], - properties: { tier: { type: "string" } }, - }, - ]); - expect(state.memorySchema.relationshipTypes).toEqual([ - { - slug: "owns", - name: "Owns", - rules: [{ source: "account", target: "product" }], - }, - ]); - expect(state.watchers.map((w) => w.slug)).toEqual(["account-digest"]); - }); - - test("loads multiple model YAML documents from one file", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -enabled = true -org = "dev" -models = "./models" -` - ); - const modelsDir = join(dir, "models"); - mkdirSync(modelsDir, { recursive: true }); - writeFileSync( - join(modelsDir, "combined.yaml"), - `version: 2 -entities: - - slug: product - name: Product ---- -version: 2 -relationships: - - slug: affects - name: Affects -` - ); - - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.memorySchema.entityTypes.map((e) => e.slug)).toEqual([ - "product", - ]); - expect(state.memorySchema.relationshipTypes.map((r) => r.slug)).toEqual([ - "affects", - ]); - }); - - test("skips empty / comments-only model YAML files", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -enabled = true -org = "dev" -models = "./models" -` - ); - const modelsDir = join(dir, "models"); - mkdirSync(modelsDir, { recursive: true }); - writeFileSync(join(modelsDir, "blank.yaml"), ""); - writeFileSync( - join(modelsDir, "comment-only.yaml"), - "# placeholder, nothing here yet\n" - ); - writeFileSync( - join(modelsDir, "schema.yaml"), - `version: 2 -entities: - - slug: product - name: Product -` - ); - - const { state } = await loadDesiredState({ cwd: dir }); - expect(state.memorySchema.entityTypes.map((e) => e.slug)).toEqual([ - "product", - ]); - }); - - test("rejects the removed inline [memory.schema] block", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -enabled = true -org = "dev" - -[[memory.schema.entity_types]] -slug = "account" -name = "Account" -` - ); - - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow(); - }); - - test("surfaces a YAML syntax error with file context", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -enabled = true -org = "dev" -models = "./models" -` - ); - const modelsDir = join(dir, "models"); - mkdirSync(modelsDir, { recursive: true }); - writeFileSync( - join(modelsDir, "broken.yaml"), - `version: 2 -entities: - - slug: product - name: Product -` - ); - - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow( - /broken\.yaml/ - ); - }); - - test("rejects watcher blocks in lobu.toml (apply syncs model-bundle watchers, not toml)", async () => { - const dir = mkProject( - `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[[agents.triage.watchers]] -slug = "stale" -` - ); - await expect(loadDesiredState({ cwd: dir })).rejects.toThrow(/watchers/); - }); - - // ── Connectors ──────────────────────────────────────────────────────────── - - const TOML_WITH_MEMORY = `[agents.triage] -name = "Triage" -dir = "./agents/triage" - -[memory] -connectors = "./connectors" -`; - - function mkConnectorsProject(files: Record): string { - const dir = mkProject(TOML_WITH_MEMORY); - mkdirSync(join(dir, "connectors")); - for (const [name, body] of Object.entries(files)) { - writeFileSync(join(dir, "connectors", name), body); - } - return dir; - } - - test("loads built-in connection + auth_profile + custom .connector.ts", async () => { - const dir = mkConnectorsProject({ - "acme.connector.ts": "export default class Acme {}\n", - "hackernews.yaml": `version: 1 -type: auth_profile -slug: hn-token -connector: hackernews -kind: env -credentials: - HN_TOKEN: $HN_TOKEN ---- -version: 1 -type: connection -slug: hn-frontpage -connector: hackernews -name: HN front page -auth: hn-token -feeds: - - feed: stories - schedule: "0 * * * *" -`, - "x.yaml": `version: 1 -type: auth_profile -slug: x-account -connector: x -kind: oauth_account -`, - }); - - const { state } = await loadDesiredState({ - cwd: dir, - env: { HN_TOKEN: "secret-token" }, - }); - expect(state.connectors.definitions).toHaveLength(1); - expect(state.connectors.definitions[0]!.sourceCode).toContain("class Acme"); - expect(state.connectors.definitions[0]!.key).toBeNull(); - expect(state.connectors.authProfiles.map((p) => p.slug).sort()).toEqual([ - "hn-token", - "x-account", - ]); - expect( - state.connectors.authProfiles.find((p) => p.slug === "hn-token")! - .credentials - ).toEqual({ HN_TOKEN: "secret-token" }); - const conn = state.connectors.connections[0]!; - expect(conn.slug).toBe("hn-frontpage"); - expect(conn.authProfileSlug).toBe("hn-token"); - expect(conn.feeds).toEqual([{ feedKey: "stories", schedule: "0 * * * *" }]); - }); - - test("collects $ENV refs from auth_profile credentials and expands them", async () => { - const dir = mkConnectorsProject({ - "auth.yaml": `version: 1 -type: auth_profile -slug: hn-token -connector: hackernews -kind: env -credentials: - HN_TOKEN: $HN_API_TOKEN -`, - }); - const { state } = await loadDesiredState({ - cwd: dir, - env: { HN_API_TOKEN: "abc123" }, - }); - expect(state.requiredSecrets).toContain("HN_API_TOKEN"); - expect(state.connectors.authProfiles[0]!.credentials).toEqual({ - HN_TOKEN: "abc123", - }); - }); - - test("fails loudly when an auth_profile credential references an unset env var", async () => { - const dir = mkConnectorsProject({ - "auth.yaml": `version: 1 -type: auth_profile -slug: hn-token -connector: hackernews -kind: env -credentials: - HN_TOKEN: $HN_API_TOKEN -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /references \$HN_API_TOKEN/ - ); - }); - - test("rejects credentials on oauth_account auth profiles", async () => { - const dir = mkConnectorsProject({ - "auth.yaml": `version: 1 -type: auth_profile -slug: x-account -connector: x -kind: oauth_account -credentials: - token: nope -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /credentials must not be set/ - ); - }); - - test("rejects an unknown auth_profile kind", async () => { - const dir = mkConnectorsProject({ - "auth.yaml": `version: 1 -type: auth_profile -slug: x-account -connector: x -kind: bogus -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /kind.*must be one of/ - ); - }); - - test("rejects a connector doc declaring both source_path and source_url", async () => { - const dir = mkConnectorsProject({ - "acme.yaml": `version: 1 -type: connector -key: acme -source_path: ./acme.ts -source_url: https://example.com/acme.ts -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /exactly one of/ - ); - }); - - test("validates connection config against the connector optionsSchema", async () => { - const { validateConnectionAgainstConnector, resolveConnectorSchemas } = - await import("../desired-state.js"); - const schemas = resolveConnectorSchemas({ - options_schema: { - type: "object", - properties: { limit: { type: "number" } }, - required: ["limit"], - additionalProperties: false, - }, - feeds_schema: { stories: { configSchema: { type: "object" } } }, - auth_schema: { methods: [{ type: "env_keys" }] }, - }); - expect(() => - validateConnectionAgainstConnector( - { - slug: "bad", - connector: "demo", - config: { limit: "oops" }, - feeds: [], - sourceFile: "connectors/demo.yaml", - }, - new Map(), - schemas - ) - ).toThrow(/connection "bad" config/); - }); - - // ── round-2 ────────────────────────────────────────────────────────────── - - test("rejects a non-canonical connection slug", async () => { - const dir = mkConnectorsProject({ - "x.yaml": `version: 1 -type: connection -slug: My_Connection -connector: hackernews -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /connection slug "My_Connection" must match/ - ); - }); - - test("rejects an invalid feed cron schedule", async () => { - const dir = mkConnectorsProject({ - "x.yaml": `version: 1 -type: connection -slug: hn -connector: hackernews -feeds: - - feed: stories - schedule: "not a cron" -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /invalid cron expression/ - ); - }); - - test("rejects duplicate connector keys across definitions", async () => { - const dir = mkConnectorsProject({ - "a.yaml": `version: 1 -type: connector -key: dup -source_url: https://example.com/a.ts ---- -version: 1 -type: connector -key: dup -source_url: https://example.com/b.ts -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /connector key "dup" is declared (twice|by two)/ - ); - }); - - test("rejects duplicate connector keys across separate files", async () => { - const dir = mkConnectorsProject({ - "a.yaml": `version: 1 -type: connector -key: dup2 -source_url: https://example.com/a.ts -`, - "b.yaml": `version: 1 -type: connector -key: dup2 -source_url: https://example.com/b.ts -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /connector key "dup2" is declared (twice|by two)/ - ); - }); - - test("--only agents skips the connectors dir (no connector-secret expansion)", async () => { - const dir = mkConnectorsProject({ - "auth.yaml": `version: 1 -type: auth_profile -slug: hn-token -connector: hackernews -kind: env -credentials: - HN_TOKEN: $HN_API_TOKEN -`, - }); - // $HN_API_TOKEN is unset, but --only agents must not load/expand it. - const { state } = await loadDesiredState({ - cwd: dir, - env: {}, - only: "agents", - }); - expect(state.connectors.authProfiles).toHaveLength(0); - expect(state.connectors.connections).toHaveLength(0); - expect(state.requiredSecrets).not.toContain("HN_API_TOKEN"); - }); - - // ── round-3 ────────────────────────────────────────────────────────────── - - test("rejects two type:connector docs with the same key (cites both files)", async () => { - const dir = mkConnectorsProject({ - "a.yaml": `version: 1 -type: connector -key: dup3 -source_url: https://example.com/a.ts -`, - "b.yaml": `version: 1 -type: connector -key: dup3 -source_url: https://example.com/b.ts -`, - }); - let msg = ""; - await loadDesiredState({ cwd: dir, env: {} }).catch((e) => { - msg = e instanceof Error ? e.message : String(e); - }); - expect(msg).toMatch(/connector key "dup3" is declared (twice|by two)/); - expect(msg).toMatch(/a\.yaml/); - expect(msg).toMatch(/b\.yaml/); - }); - - test("rejects two type:connector docs with the same key in one file", async () => { - const dir = mkConnectorsProject({ - "a.yaml": `version: 1 -type: connector -key: dup4 -source_url: https://example.com/a.ts ---- -version: 1 -type: connector -key: dup4 -source_url: https://example.com/b.ts -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /connector key "dup4" is declared (twice|by two)/ - ); - }); - - test("rejects a non-https connector source_url", async () => { - const dir = mkConnectorsProject({ - "a.yaml": `version: 1 -type: connector -key: insecure -source_url: http://example.com/a.ts -`, - }); - await expect(loadDesiredState({ cwd: dir, env: {} })).rejects.toThrow( - /source_url must use https/ - ); - }); -}); diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index ce80dd105..d85aadc87 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -1,5 +1,5 @@ import { randomBytes } from "node:crypto"; -import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs"; +import { existsSync, readFileSync, rmSync } from "node:fs"; import { readdir, readFile, stat } from "node:fs/promises"; import { join, resolve } from "node:path"; import { pathToFileURL } from "node:url"; @@ -9,72 +9,14 @@ import type { ConnectorDefinition, FeedDefinition, } from "@lobu/connector-sdk"; -import type { AgentSettings, LobuTomlConfig, TomlAgentEntry } from "@lobu/core"; +import type { AgentSettings } from "@lobu/core"; import Ajv from "ajv"; import addFormats from "ajv-formats"; -import { parse as parseToml } from "smol-toml"; import { ValidationError } from "../../memory/_lib/errors.js"; -import { - type ValidationError as SchemaError, - expandModelDefinition, - parseModelYamlFile, - validateModel, -} from "../../memory/_lib/schema.js"; -import { - CONFIG_FILENAME, - isLoadError, - loadConfig, -} from "../../../config/loader.js"; import { mapProjectToDesiredState, mergeAgentDirArtifacts, } from "./map-config.js"; -import { CronExpressionParser } from "cron-parser"; - -// ── Connector slug / schedule validators (round-2) ───────────────────────── -// Mirror packages/server/src/utils/connections.ts CONNECTION_SLUG_PATTERN and -// the server's validateSchedule (packages/server/src/utils/cron.ts) so the CLI -// fails loud *before* any mutation instead of getting a server 4xx. -const CONNECTION_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/; -// auth_profiles slugs are sanitized server-side; require canonical form so the -// diff key matches what is stored (server cap is 80 chars). -const AUTH_PROFILE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,79}$/; -const MIN_CRON_INTERVAL_MS = 60_000; - -function cronError(schedule: string): string | null { - try { - const it = CronExpressionParser.parse(schedule); - const first = it.next().toDate(); - const second = it.next().toDate(); - if (second.getTime() - first.getTime() < MIN_CRON_INTERVAL_MS) { - return `schedule "${schedule}" is too frequent (minimum interval is 1 minute)`; - } - return null; - } catch (err) { - return `invalid cron expression "${schedule}" — ${err instanceof Error ? err.message : String(err)}`; - } -} - -// ── Stable platform IDs (mirror of file-loader.ts) ───────────────────────── -// -// keep in sync with packages/server/src/gateway/config/file-loader.ts -function slugifyForPlatformId(input: string): string { - return input - .toLowerCase() - .replace(/[^a-z0-9]+/g, "-") - .replace(/^-+|-+$/g, ""); -} - -// keep in sync with packages/server/src/gateway/config/file-loader.ts -export function buildStablePlatformId( - agentId: string, - type: string, - name?: string -): string { - const parts = [slugifyForPlatformId(agentId), slugifyForPlatformId(type)]; - if (name) parts.push(slugifyForPlatformId(name)); - return parts.join("-"); -} // ── Desired state types ──────────────────────────────────────────────────── @@ -290,58 +232,6 @@ export interface DesiredState { // ── Load + transform ─────────────────────────────────────────────────────── -const ENV_REF = /^\$([A-Z][A-Z0-9_]*)$/; - -function asEnvRef(value: string): string | null { - const match = ENV_REF.exec(value.trim()); - return match?.[1] ?? null; -} - -/** Visit every string leaf in `value` (recursing arrays + plain objects). */ -function walkStrings(value: unknown, visit: (s: string) => void): void { - if (typeof value === "string") { - visit(value); - return; - } - if (Array.isArray(value)) { - for (const item of value) walkStrings(item, visit); - return; - } - if (value && typeof value === "object") { - for (const v of Object.values(value as Record)) { - walkStrings(v, visit); - } - } -} - -/** Add every `$ENV` reference found among the string leaves of `value`. */ -function collectEnvRefsFrom(value: unknown, out: Set): void { - walkStrings(value, (s) => { - const ref = asEnvRef(s); - if (ref) out.add(ref); - }); -} - -function collectEnvRefs(config: LobuTomlConfig, out: Set): void { - for (const agentConfig of Object.values(config.agents)) { - for (const provider of agentConfig.providers) { - if (provider.key) collectEnvRefsFrom(provider.key, out); - if (provider.secret_ref) collectEnvRefsFrom(provider.secret_ref, out); - } - for (const platform of agentConfig.platforms) { - collectEnvRefsFrom(platform.config, out); - } - if (agentConfig.skills.mcp) { - for (const mcp of Object.values(agentConfig.skills.mcp)) { - collectEnvRefsFrom(mcp.headers, out); - collectEnvRefsFrom(mcp.env, out); - collectEnvRefsFrom(mcp.oauth?.client_id, out); - collectEnvRefsFrom(mcp.oauth?.client_secret, out); - } - } - } -} - interface SkillFrontmatter { name?: string; description?: string; @@ -498,194 +388,6 @@ function buildLocalSkills( }); } -function buildAgentSettings( - agentConfig: TomlAgentEntry, - markdown: { identityMd?: string; soulMd?: string; userMd?: string }, - skillFiles: LoadedSkillFile[] = [] -): Partial { - const settings: Partial = { ...markdown }; - const localSkills = buildLocalSkills(skillFiles); - if (localSkills.length > 0) { - settings.skillsConfig = { skills: localSkills }; - } - - // Providers (ordered, index 0 = primary) - if (agentConfig.providers.length > 0) { - settings.installedProviders = agentConfig.providers.map((p) => ({ - providerId: p.id, - installedAt: Date.now(), - })); - settings.modelSelection = { mode: "auto" }; - const providerModelPreferences = Object.fromEntries( - agentConfig.providers - .filter((p) => !!p.model?.trim()) - .map((p) => [p.id, p.model!.trim()]) - ); - if (Object.keys(providerModelPreferences).length > 0) { - settings.providerModelPreferences = providerModelPreferences; - } - } - - // Network — merge agent-level config with local-skill declarations. Operator - // policy in lobu.toml wins on named judges / judged-domain rules. - const mergedAllowedDomains = [...(agentConfig.network?.allowed ?? [])]; - const mergedDeniedDomains = [...(agentConfig.network?.denied ?? [])]; - const mergedJudgedDomains = new Map< - string, - { domain: string; judge?: string } - >(); - const mergedJudges: Record = {}; - - for (const skill of localSkills) { - if (skill.networkConfig?.allowedDomains?.length) { - mergedAllowedDomains.push( - ...skill.networkConfig.allowedDomains.filter((domain) => domain !== "*") - ); - } - if (skill.networkConfig?.deniedDomains?.length) { - mergedDeniedDomains.push(...skill.networkConfig.deniedDomains); - } - if (skill.networkConfig?.judgedDomains?.length) { - for (const rule of skill.networkConfig.judgedDomains) { - mergedJudgedDomains.set(rule.domain, rule); - } - } - if (skill.networkConfig?.judges) { - Object.assign(mergedJudges, skill.networkConfig.judges); - } - } - - if (agentConfig.network?.judge) { - for (const rule of agentConfig.network.judge) { - mergedJudgedDomains.set(rule.domain, rule); - } - } - if (agentConfig.network?.judges) { - Object.assign(mergedJudges, agentConfig.network.judges); - } - - const hasJudgedDomains = mergedJudgedDomains.size > 0; - const hasJudges = Object.keys(mergedJudges).length > 0; - if ( - mergedAllowedDomains.length > 0 || - mergedDeniedDomains.length > 0 || - hasJudgedDomains || - hasJudges - ) { - settings.networkConfig = { - ...(mergedAllowedDomains.length > 0 - ? { allowedDomains: [...new Set(mergedAllowedDomains)] } - : {}), - ...(mergedDeniedDomains.length > 0 - ? { deniedDomains: [...new Set(mergedDeniedDomains)] } - : {}), - ...(hasJudgedDomains - ? { judgedDomains: Array.from(mergedJudgedDomains.values()) } - : {}), - ...(hasJudges ? { judges: mergedJudges } : {}), - }; - } - - // Egress (PR-1 persists this column) - if (agentConfig.egress) { - const egressConfig: AgentSettings["egressConfig"] = {}; - if (agentConfig.egress.extra_policy) { - egressConfig.extraPolicy = agentConfig.egress.extra_policy; - } - if (agentConfig.egress.judge_model) { - egressConfig.judgeModel = agentConfig.egress.judge_model; - } - if (Object.keys(egressConfig).length > 0) { - settings.egressConfig = egressConfig; - } - } - - // Tools — pre_approved + worker-side allow/deny/strict (PR-1 persists - // preApprovedTools). - if (agentConfig.tools) { - if (agentConfig.tools.pre_approved?.length) { - settings.preApprovedTools = [...new Set(agentConfig.tools.pre_approved)]; - } - const toolsConfig: AgentSettings["toolsConfig"] = {}; - if (agentConfig.tools.allowed?.length) { - toolsConfig.allowedTools = [...new Set(agentConfig.tools.allowed)]; - } - if (agentConfig.tools.denied?.length) { - toolsConfig.deniedTools = [...new Set(agentConfig.tools.denied)]; - } - if (agentConfig.tools.strict !== undefined) { - toolsConfig.strictMode = agentConfig.tools.strict; - } - if (Object.keys(toolsConfig).length > 0) { - settings.toolsConfig = toolsConfig; - } - } - - // Guardrails (PR-1 persists this column) - if (agentConfig.guardrails?.length) { - settings.guardrails = [...new Set(agentConfig.guardrails)]; - } - - // Nix — merge agent-level packages with local-skill declarations. - const mergedNixPackages = [ - ...(agentConfig.worker?.nix_packages ?? []), - ...localSkills.flatMap((skill) => skill.nixPackages ?? []), - ]; - if (mergedNixPackages.length > 0) { - settings.nixConfig = { - packages: [...new Set(mergedNixPackages)], - }; - } - - // MCP servers — start with agent-level toml config, then merge local-skill - // entries without overriding operator-defined IDs. - const mcpServers: Record> = {}; - if (agentConfig.skills.mcp) { - for (const [id, mcp] of Object.entries(agentConfig.skills.mcp)) { - const mapped: Record = {}; - if (mcp.url) mapped.url = mcp.url; - if (mcp.command) mapped.command = mcp.command; - if (mcp.args) mapped.args = mcp.args; - if (mcp.headers) mapped.headers = mcp.headers; - if (mcp.auth_scope) mapped.authScope = mcp.auth_scope; - if (mcp.oauth) { - mapped.oauth = { - authUrl: mcp.oauth.auth_url, - tokenUrl: mcp.oauth.token_url, - ...(mcp.oauth.client_id ? { clientId: mcp.oauth.client_id } : {}), - ...(mcp.oauth.client_secret - ? { clientSecret: mcp.oauth.client_secret } - : {}), - ...(mcp.oauth.scopes ? { scopes: mcp.oauth.scopes } : {}), - ...(mcp.oauth.token_endpoint_auth_method - ? { - tokenEndpointAuthMethod: mcp.oauth.token_endpoint_auth_method, - } - : {}), - }; - } - if (mcp.env) mapped.env = { ...mcp.env }; - mcpServers[id] = mapped; - } - } - for (const skill of localSkills) { - for (const mcp of skill.mcpServers ?? []) { - if (mcpServers[mcp.id]) continue; - mcpServers[mcp.id] = { - ...(mcp.url ? { url: mcp.url } : {}), - ...(mcp.type ? { type: mcp.type } : {}), - ...(mcp.command ? { command: mcp.command } : {}), - ...(mcp.args ? { args: mcp.args } : {}), - }; - } - } - if (Object.keys(mcpServers).length > 0) { - settings.mcpServers = mcpServers as AgentSettings["mcpServers"]; - } - - return settings; -} - async function readMarkdown( agentDir: string ): Promise<{ identityMd?: string; soulMd?: string; userMd?: string }> { @@ -706,990 +408,12 @@ async function readMarkdown( return result; } -function resolveConfigValue( - agentId: string, - platformType: string, - key: string, - value: string, - env: NodeJS.ProcessEnv -): string { - const ref = asEnvRef(value); - if (!ref) return value; - const resolved = env[ref]; - if (resolved === undefined || resolved === "") { - throw new ValidationError( - `agent "${agentId}" platform "${platformType}" config key "${key}" references $${ref}, but it is unset or empty in the apply environment` - ); - } - return resolved; -} - -function buildPlatforms( - agentId: string, - agentConfig: TomlAgentEntry, - env: NodeJS.ProcessEnv -): DesiredPlatform[] { - // Reject duplicate (type, name) pairs — same rule the file-loader enforces - // so stable IDs stay collision-free. - const seen = new Set(); - const out: DesiredPlatform[] = []; - for (const platform of agentConfig.platforms) { - const key = `${platform.type}:${platform.name ?? ""}`; - if (seen.has(key)) { - throw new ValidationError( - platform.name - ? `agent "${agentId}" has duplicate platform (type=${platform.type}, name=${platform.name})` - : `agent "${agentId}" has multiple "${platform.type}" platforms — add a unique \`name = "..."\` to each to disambiguate` - ); - } - seen.add(key); - const resolvedConfig: Record = {}; - for (const [k, v] of Object.entries(platform.config)) { - resolvedConfig[k] = resolveConfigValue(agentId, platform.type, k, v, env); - } - const desired: DesiredPlatform = { - stableId: buildStablePlatformId(agentId, platform.type, platform.name), - type: platform.type, - config: resolvedConfig, - }; - if (platform.name) desired.name = platform.name; - if (platform.channels && platform.channels.length > 0) { - if (platform.type !== "slack") { - throw new ValidationError( - `agent "${agentId}" platform "${platform.type}": \`channels\` is only supported for Slack` - ); - } - for (const entry of platform.channels) { - if (!/^[^/\s]+\/[^/\s]+$/.test(entry.trim())) { - throw new ValidationError( - `agent "${agentId}" Slack \`channels\` entry "${entry}" must be in "/" form (e.g. "T0ABCDEF/C0123ABCD")` - ); - } - } - desired.channels = platform.channels.map((e) => e.trim()); - } - out.push(desired); - } - return out; -} - function isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } -function parseEntityType(raw: unknown): DesiredEntityType { - if (!isRecord(raw) || typeof raw.slug !== "string") { - throw new ValidationError( - `model-bundle "entities" entries must be objects with a "slug" string field; got ${JSON.stringify(raw)}` - ); - } - const out: DesiredEntityType = { slug: raw.slug }; - if (typeof raw.name === "string") out.name = raw.name; - if (typeof raw.description === "string") out.description = raw.description; - if (isRecord(raw.metadata_schema)) { - if (Array.isArray(raw.metadata_schema.required)) { - out.required = raw.metadata_schema.required.filter( - (v): v is string => typeof v === "string" - ); - } - if (isRecord(raw.metadata_schema.properties)) { - out.properties = raw.metadata_schema.properties; - } - } - if (isRecord(raw.metadata)) out.metadata = raw.metadata; - return out; -} - -const NOTIFICATION_CHANNELS = new Set(["canvas", "notification", "both"]); -const NOTIFICATION_PRIORITIES = new Set(["low", "normal", "high"]); -const UUID_PATTERN = - /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; - -function parseWatcher(raw: unknown, modelFileAbsPath: string): DesiredWatcher { - if (!isRecord(raw) || typeof raw.slug !== "string") { - throw new ValidationError( - `watcher model files must be objects with a "slug" string field; got ${JSON.stringify(raw)}` - ); - } - if (typeof raw.prompt !== "string" || !raw.prompt.trim()) { - throw new ValidationError( - `watcher "${raw.slug}" is missing a "prompt" string` - ); - } - if (typeof raw.agent !== "string" || !raw.agent.trim()) { - throw new ValidationError( - `watcher "${raw.slug}" is missing an "agent" field — every watcher must name the agent that owns it (e.g. \`agent: my-agent\`, matching an \`[agents.]\` block in lobu.toml)` - ); - } - const extractionSchema = isRecord(raw.extraction_schema) - ? raw.extraction_schema - : {}; - const out: DesiredWatcher = { - slug: raw.slug, - agent: raw.agent, - prompt: raw.prompt, - extractionSchema, - }; - if (typeof raw.name === "string") out.name = raw.name; - if (typeof raw.description === "string") out.description = raw.description; - if (typeof raw.schedule === "string") { - const err = cronError(raw.schedule); - if (err) { - throw new ValidationError(`watcher "${raw.slug}" ${err}`); - } - out.schedule = raw.schedule; - } - if (Array.isArray(raw.sources)) { - out.sources = raw.sources - .filter(isRecord) - .filter( - (s): s is { name: string; query: string } & Record => - typeof s.name === "string" && typeof s.query === "string" - ) - .map((s) => ({ name: s.name, query: s.query })); - } - - // Reaction script — sibling `.ts` file, resolved relative to the YAML. - // Path constraints: must be a relative POSIX-style path that stays under - // the YAML's directory tree (no leading `/`, no `..` segments), must end - // in `.ts`, and the file must be ≤ 256 KiB. The server compiles and - // executes the source in an isolate, so the trust boundary is the - // operator's file system — this validation prevents a hostile YAML - // (e.g. a PR that touches an unrelated model file) from sucking in a - // sensitive file like `/etc/passwd` or `../../.ssh/id_rsa`. - if (raw.reaction_script !== undefined) { - if ( - typeof raw.reaction_script !== "string" || - !raw.reaction_script.trim() - ) { - throw new ValidationError( - `watcher "${raw.slug}" \`reaction_script\` must be a path to a sibling .ts file (e.g. \`reaction_script: ./funnel-digest.ts\`). Inline scripts are not supported — keep the TypeScript in its own file so your IDE can type-check it.` - ); - } - const rel = raw.reaction_script.trim(); - if (rel.startsWith("/") || rel.includes("\\")) { - throw new ValidationError( - `watcher "${raw.slug}" \`reaction_script\` must be a relative POSIX path (./foo.ts) — absolute paths and backslashes are not allowed` - ); - } - if (rel.split("/").some((seg) => seg === "..")) { - throw new ValidationError( - `watcher "${raw.slug}" \`reaction_script\` must not contain \`..\` segments — keep the script under the model file's directory tree` - ); - } - if (!rel.endsWith(".ts")) { - throw new ValidationError( - `watcher "${raw.slug}" \`reaction_script\` must end in \`.ts\` (got ${JSON.stringify(rel)})` - ); - } - const baseDir = resolve(modelFileAbsPath, ".."); - const abs = resolve(baseDir, rel); - // Belt-and-braces — symlinks or unusual relative-path forms shouldn't - // escape the baseDir even if the above checks let one through. - if (!abs.startsWith(`${baseDir}/`) && abs !== baseDir) { - throw new ValidationError( - `watcher "${raw.slug}" \`reaction_script\` resolves outside the model directory (${abs})` - ); - } - let sourceCode: string; - try { - sourceCode = readFileSync(abs, "utf-8"); - } catch { - throw new ValidationError( - `watcher "${raw.slug}" \`reaction_script\` ${rel} does not exist (resolved to ${abs})` - ); - } - const REACTION_SCRIPT_MAX_BYTES = 256 * 1024; - if (Buffer.byteLength(sourceCode, "utf8") > REACTION_SCRIPT_MAX_BYTES) { - throw new ValidationError( - `watcher "${raw.slug}" \`reaction_script\` exceeds the ${REACTION_SCRIPT_MAX_BYTES}-byte cap — reaction scripts should be a few hundred lines, not a vendored library` - ); - } - out.reactionScript = { sourcePath: abs, sourceCode }; - } - - if (raw.reactions_guidance !== undefined) { - if (typeof raw.reactions_guidance !== "string") { - throw new ValidationError( - `watcher "${raw.slug}" \`reactions_guidance\` must be a string` - ); - } - out.reactionsGuidance = raw.reactions_guidance; - } - - if (raw.device_worker_id !== undefined) { - if ( - typeof raw.device_worker_id !== "string" || - !UUID_PATTERN.test(raw.device_worker_id.trim()) - ) { - throw new ValidationError( - `watcher "${raw.slug}" \`device_worker_id\` must be a UUID string (the device_workers.id of the device this watcher should run on)` - ); - } - out.deviceWorkerId = raw.device_worker_id.trim(); - } - - if (raw.scheduler_client_id !== undefined) { - if ( - typeof raw.scheduler_client_id !== "string" || - !raw.scheduler_client_id.trim() - ) { - throw new ValidationError( - `watcher "${raw.slug}" \`scheduler_client_id\` must be a non-empty string` - ); - } - out.schedulerClientId = raw.scheduler_client_id.trim(); - } - - if (raw.notification_channel !== undefined) { - if ( - typeof raw.notification_channel !== "string" || - !NOTIFICATION_CHANNELS.has(raw.notification_channel) - ) { - throw new ValidationError( - `watcher "${raw.slug}" \`notification_channel\` must be one of: canvas, notification, both` - ); - } - out.notificationChannel = - raw.notification_channel as DesiredWatcher["notificationChannel"]; - } - - if (raw.notification_priority !== undefined) { - if ( - typeof raw.notification_priority !== "string" || - !NOTIFICATION_PRIORITIES.has(raw.notification_priority) - ) { - throw new ValidationError( - `watcher "${raw.slug}" \`notification_priority\` must be one of: low, normal, high` - ); - } - out.notificationPriority = - raw.notification_priority as DesiredWatcher["notificationPriority"]; - } - - if (raw.min_cooldown_seconds !== undefined) { - if ( - typeof raw.min_cooldown_seconds !== "number" || - !Number.isFinite(raw.min_cooldown_seconds) || - raw.min_cooldown_seconds < 0 - ) { - throw new ValidationError( - `watcher "${raw.slug}" \`min_cooldown_seconds\` must be a non-negative number` - ); - } - out.minCooldownSeconds = raw.min_cooldown_seconds; - } - - if (raw.tags !== undefined) { - if ( - !Array.isArray(raw.tags) || - !raw.tags.every((t) => typeof t === "string") - ) { - throw new ValidationError( - `watcher "${raw.slug}" \`tags\` must be an array of strings` - ); - } - out.tags = raw.tags as string[]; - } - - if (raw.agent_kind !== undefined) { - if (typeof raw.agent_kind !== "string" || !raw.agent_kind.trim()) { - throw new ValidationError( - `watcher "${raw.slug}" \`agent_kind\` must be a non-empty string` - ); - } - out.agentKind = raw.agent_kind.trim(); - } - - if (raw.json_template !== undefined) { - out.jsonTemplate = raw.json_template; - } - - if (raw.keying_config !== undefined) { - if (!isRecord(raw.keying_config)) { - throw new ValidationError( - `watcher "${raw.slug}" \`keying_config\` must be an object` - ); - } - out.keyingConfig = raw.keying_config; - } - - if (raw.classifiers !== undefined) { - if (!Array.isArray(raw.classifiers)) { - throw new ValidationError( - `watcher "${raw.slug}" \`classifiers\` must be an array` - ); - } - out.classifiers = raw.classifiers; - } - - if (raw.condensation_prompt !== undefined) { - if (typeof raw.condensation_prompt !== "string") { - throw new ValidationError( - `watcher "${raw.slug}" \`condensation_prompt\` must be a string` - ); - } - out.condensationPrompt = raw.condensation_prompt; - } - - if (raw.condensation_window_count !== undefined) { - if ( - typeof raw.condensation_window_count !== "number" || - raw.condensation_window_count < 2 - ) { - throw new ValidationError( - `watcher "${raw.slug}" \`condensation_window_count\` must be a number ≥ 2` - ); - } - out.condensationWindowCount = raw.condensation_window_count; - } - - return out; -} - -function parseRelationshipType(raw: unknown): DesiredRelationshipType { - if (!isRecord(raw) || typeof raw.slug !== "string") { - throw new ValidationError( - `model-bundle "relationships" entries must be objects with a "slug" string field; got ${JSON.stringify(raw)}` - ); - } - const out: DesiredRelationshipType = { slug: raw.slug }; - if (typeof raw.name === "string") out.name = raw.name; - if (typeof raw.description === "string") out.description = raw.description; - if (Array.isArray(raw.rules)) { - out.rules = raw.rules - .filter(isRecord) - .filter( - ( - rule - ): rule is { source: string; target: string } & Record< - string, - unknown - > => typeof rule.source === "string" && typeof rule.target === "string" - ) - .map((rule) => ({ source: rule.source, target: rule.target })); - } - if (isRecord(raw.metadata)) out.metadata = raw.metadata; - return out; -} - -interface LoadedMemoryModels { - entityTypes: DesiredEntityType[]; - relationshipTypes: DesiredRelationshipType[]; - watchers: DesiredWatcher[]; -} - -/** - * Read memory schema files referenced by `[memory].models`. Every nested YAML - * file must be a dbt-style `version: 2` bundle with top-level `entities`, - * `relationships`, and `watchers` arrays; multi-document YAML streams are - * supported. `lobu apply` syncs entity types, relationship types, and watchers - * from these files; watcher sync is create-only (drift ignored). - */ -async function loadMemoryModels( - config: LobuTomlConfig, - projectRoot: string -): Promise { - const empty: LoadedMemoryModels = { - entityTypes: [], - relationshipTypes: [], - watchers: [], - }; - const mem = config.memory; - if (!mem || mem.enabled === false) return empty; - - // Models directory (matches seed-cmd's resolution rules). - const modelsRel = mem.models?.trim() || "./models"; - const modelsPath = resolve(projectRoot, modelsRel); - - if (!existsSync(modelsPath)) return empty; - - const entityTypes: DesiredEntityType[] = []; - const relationshipTypes: DesiredRelationshipType[] = []; - const watchers: DesiredWatcher[] = []; - - const readModelFiles = (dir: string, prefix = ""): string[] => { - return readdirSync(dir, { withFileTypes: true }) - .sort((a, b) => a.name.localeCompare(b.name)) - .flatMap((entry) => { - const relPath = prefix ? join(prefix, entry.name) : entry.name; - const fullPath = join(dir, entry.name); - if (entry.isDirectory()) return readModelFiles(fullPath, relPath); - if ( - entry.isFile() && - (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml")) - ) { - return [relPath]; - } - return []; - }); - }; - - const errors: SchemaError[] = []; - for (const file of readModelFiles(modelsPath)) { - const raw = readFileSync(join(modelsPath, file), "utf-8"); - const { documents, errors: parseErrors } = parseModelYamlFile(raw, file); - errors.push(...parseErrors); - for (const { data: document, file: documentFile } of documents) { - const expanded = expandModelDefinition(document, documentFile); - errors.push(...expanded.errors); - for (const model of expanded.models) { - const modelErrors = validateModel(model.data, model.file); - if (modelErrors.length > 0) { - errors.push(...modelErrors); - continue; - } - if (model.modelType === "entity") { - entityTypes.push(parseEntityType(model.data)); - } else if (model.modelType === "relationship") { - relationshipTypes.push(parseRelationshipType(model.data)); - } else if (model.modelType === "watcher") { - // `model.file` is like `schema.yaml:watchers[0]` (optionally with - // `#docIdx` for multi-doc streams) — strip the synthetic suffix - // before resolving on disk, then map through `modelsPath` to the - // absolute YAML path. `parseWatcher` reads `reaction_script:` - // sibling .ts files relative to that. - const yamlRel = model.file.replace(/[:#].*$/, ""); - watchers.push(parseWatcher(model.data, join(modelsPath, yamlRel))); - } - } - } - } - - if (errors.length > 0) { - const detail = errors - .map((e) => `${e.file}: ${e.field} — ${e.message}`) - .join("\n "); - throw new ValidationError(`Model validation failed\n ${detail}`); - } - - return { entityTypes, relationshipTypes, watchers }; -} - -/** - * The Zod schema strips unknown keys, so we re-parse the raw TOML to surface - * shapes the validated config can't see. Detecting `[[agents..watchers]]` - * here keeps users from silently shipping a config block that v1 ignores. - */ -async function rejectUnsupportedAgentShapes(cwd: string): Promise { - let raw: string; - try { - raw = await readFile(join(cwd, CONFIG_FILENAME), "utf-8"); - } catch { - return; - } - let parsed: Record; - try { - parsed = parseToml(raw) as Record; - } catch { - // loadConfig already surfaces parse errors — bail without throwing here. - return; - } - const agents = parsed.agents; - if (!agents || typeof agents !== "object") return; - for (const [agentId, agentConfig] of Object.entries( - agents as Record - )) { - if (!agentConfig || typeof agentConfig !== "object") continue; - const watchers = (agentConfig as Record).watchers; - if (Array.isArray(watchers) && watchers.length > 0) { - throw new ValidationError( - `agent "${agentId}" declares [[agents.${agentId}.watchers]] in lobu.toml — watchers live in a \`[memory].models\` YAML bundle (the same file as your entity types), each with an \`agent: ${agentId}\` field pointing back here. Move the watcher there.` - ); - } - } -} - -// ── Connectors (data-source connectors) ─────────────────────────────────── - -const AUTH_PROFILE_KINDS: ReadonlySet = new Set([ - "env", - "oauth_app", - "oauth_account", - "browser_session", -]); - function asString(value: unknown): string | undefined { - return typeof value === "string" && value.trim() ? value : undefined; -} - -function parseConnectionDoc( - raw: Record, - file: string -): DesiredConnection { - const slug = asString(raw.slug); - if (!slug) { - throw new ValidationError( - `${file}: \`type: connection\` doc is missing a "slug" string` - ); - } - if (!CONNECTION_SLUG_PATTERN.test(slug)) { - throw new ValidationError( - `${file}: connection slug "${slug}" must match /^[a-z0-9][a-z0-9-]{0,62}$/ (lowercase letters/digits/hyphens, no leading hyphen, ≤63 chars)` - ); - } - const connector = asString(raw.connector); - if (!connector) { - throw new ValidationError( - `${file}: connection "${slug}" is missing a "connector" key` - ); - } - const out: DesiredConnection = { - slug, - connector, - feeds: [], - sourceFile: file, - }; - const name = asString(raw.name); - if (name) out.name = name; - const auth = asString(raw.auth); - if (auth) out.authProfileSlug = auth; - const appAuth = asString(raw.app_auth); - if (appAuth) out.appAuthProfileSlug = appAuth; - if (raw.device_worker_id !== undefined) { - if ( - typeof raw.device_worker_id !== "string" || - !UUID_PATTERN.test(raw.device_worker_id.trim()) - ) { - throw new ValidationError( - `${file}: connection "${slug}" \`device_worker_id\` must be a UUID (the device_workers.id of the device this connection runs on)` - ); - } - out.deviceWorkerId = raw.device_worker_id.trim(); - } - if (raw.config !== undefined) { - if (!isRecord(raw.config)) { - throw new ValidationError( - `${file}: connection "${slug}" \`config\` must be an object` - ); - } - // action_modes is keyed by operation_key and each value must be one of - // 'disabled' | 'approval' | 'auto'. The server tolerates unknown values - // (falls back to the connector default), so a typo like 'auto-approve' - // would silently degrade. Fail fast at apply time instead. - if (raw.config.action_modes !== undefined) { - if (!isRecord(raw.config.action_modes)) { - throw new ValidationError( - `${file}: connection "${slug}" \`config.action_modes\` must be an object mapping operation keys to one of: disabled, approval, auto` - ); - } - for (const [opKey, mode] of Object.entries(raw.config.action_modes)) { - if (mode !== "disabled" && mode !== "approval" && mode !== "auto") { - throw new ValidationError( - `${file}: connection "${slug}" \`config.action_modes.${opKey}\` must be one of: disabled, approval, auto (got ${JSON.stringify(mode)})` - ); - } - } - } - out.config = raw.config; - } - if (raw.feeds !== undefined) { - if (!Array.isArray(raw.feeds)) { - throw new ValidationError( - `${file}: connection "${slug}" \`feeds\` must be an array` - ); - } - const seen = new Set(); - for (const entry of raw.feeds) { - if (!isRecord(entry)) { - throw new ValidationError( - `${file}: connection "${slug}" feed entries must be objects` - ); - } - const feedKey = asString(entry.feed); - if (!feedKey) { - throw new ValidationError( - `${file}: connection "${slug}" feed entry is missing a "feed" key` - ); - } - if (seen.has(feedKey)) { - throw new ValidationError( - `${file}: connection "${slug}" declares feed "${feedKey}" twice` - ); - } - seen.add(feedKey); - const feed: DesiredFeed = { feedKey }; - const feedName = asString(entry.name); - if (feedName) feed.name = feedName; - const schedule = asString(entry.schedule); - if (schedule) { - const err = cronError(schedule); - if (err) { - throw new ValidationError( - `${file}: connection "${slug}" feed "${feedKey}" ${err}` - ); - } - feed.schedule = schedule; - } - if (entry.config !== undefined) { - if (!isRecord(entry.config)) { - throw new ValidationError( - `${file}: connection "${slug}" feed "${feedKey}" \`config\` must be an object` - ); - } - feed.config = entry.config; - } - out.feeds.push(feed); - } - } - return out; -} - -function parseAuthProfileDoc( - raw: Record, - file: string -): DesiredAuthProfile { - const slug = asString(raw.slug); - if (!slug) { - throw new ValidationError( - `${file}: \`type: auth_profile\` doc is missing a "slug" string` - ); - } - if (!AUTH_PROFILE_SLUG_PATTERN.test(slug)) { - throw new ValidationError( - `${file}: auth_profile slug "${slug}" must match /^[a-z0-9][a-z0-9-]{0,79}$/ (lowercase letters/digits/hyphens, no leading hyphen, ≤80 chars)` - ); - } - const connector = asString(raw.connector); - if (!connector) { - throw new ValidationError( - `${file}: auth_profile "${slug}" is missing a "connector" key` - ); - } - const kind = asString(raw.kind); - if (!kind || !AUTH_PROFILE_KINDS.has(kind)) { - throw new ValidationError( - `${file}: auth_profile "${slug}" \`kind\` must be one of env|oauth_app|oauth_account|browser_session (got ${JSON.stringify(raw.kind)})` - ); - } - const out: DesiredAuthProfile = { - slug, - connector, - kind: kind as DesiredAuthProfileKind, - sourceFile: file, - }; - const name = asString(raw.name); - if (name) out.name = name; - if (raw.credentials !== undefined) { - if (!isRecord(raw.credentials)) { - throw new ValidationError( - `${file}: auth_profile "${slug}" \`credentials\` must be an object` - ); - } - const creds: Record = {}; - for (const [k, v] of Object.entries(raw.credentials)) { - if (typeof v !== "string") { - throw new ValidationError( - `${file}: auth_profile "${slug}" credential "${k}" must be a string (use $ENV for secrets)` - ); - } - creds[k] = v; - } - if (kind === "oauth_account" || kind === "browser_session") { - if (Object.keys(creds).length > 0) { - throw new ValidationError( - `${file}: auth_profile "${slug}" has \`kind: ${kind}\` — credentials must not be set; \`lobu apply\` never writes interactive-auth tokens (complete auth via the connect URL).` - ); - } - } else { - out.credentials = creds; - } - } - return out; -} - -function parseConnectorDoc( - raw: Record, - file: string -): { key: string; sourcePath?: string; sourceUrl?: string } { - const key = asString(raw.key); - if (!key) { - throw new ValidationError( - `${file}: \`type: connector\` doc is missing a "key" string` - ); - } - const sourcePath = asString(raw.source_path); - const sourceUrl = asString(raw.source_url); - if (!!sourcePath === !!sourceUrl) { - throw new ValidationError( - `${file}: connector "${key}" must declare exactly one of \`source_path\` or \`source_url\`` - ); - } - if (sourceUrl) { - let parsed: URL; - try { - parsed = new URL(sourceUrl); - } catch { - throw new ValidationError( - `${file}: connector "${key}" source_url is not a valid URL: ${sourceUrl}` - ); - } - if (parsed.protocol !== "https:") { - throw new ValidationError( - `${file}: connector "${key}" source_url must use https (got ${parsed.protocol}//)` - ); - } - } - return { - key, - ...(sourcePath ? { sourcePath } : {}), - ...(sourceUrl ? { sourceUrl } : {}), - }; -} - -interface LoadedConnectors { - definitions: DesiredConnectorDefinition[]; - authProfiles: DesiredAuthProfile[]; - connections: DesiredConnection[]; -} - -const EMPTY_CONNECTORS: LoadedConnectors = { - definitions: [], - authProfiles: [], - connections: [], -}; - -/** - * Load the `[memory].connectors` directory: - * - every `*.connector.ts` is auto-discovered as a connector definition - * (raw source pushed to the server, which compiles + extracts the key) - * - `*.yaml` files are multi-doc (`---`-separated); each doc carries - * `version: 1` and a `type:` of `connection`, `auth_profile`, or `connector` - * - * `connector:` config validation against the connector's `optionsSchema` / - * feed `configSchema` / `authSchema` happens later (in `apply-cmd`) once the - * remote connector-definition catalog is available — the CLI never compiles - * connectors locally. - */ -async function loadConnectors( - config: LobuTomlConfig, - projectRoot: string, - env: NodeJS.ProcessEnv, - envRefs: Set -): Promise { - const mem = config.memory; - if (!mem || mem.enabled === false) return EMPTY_CONNECTORS; - const dirRel = mem.connectors?.trim() || "./connectors"; - const dirPath = resolve(projectRoot, dirRel); - - let entries: string[]; - try { - entries = (await readdir(dirPath)).sort(); - } catch { - return EMPTY_CONNECTORS; - } - - const { parseAllDocuments } = await import("yaml"); - - const definitionsByKey = new Map(); - // Keys explicitly declared by a `type: connector` doc (vs auto-discovered - // from a `*.connector.ts` filename). A given connector key may be declared by - // at most one such doc — even two docs pointing at the same `source_path`. - const connectorDocKeyDeclaredBy = new Map(); - // `.connector.ts` files keyed by their *absolute path* — we don't know the - // connector key until the server compiles them. `type: connector` docs with - // `source_path:` that point at one of these files just dedupe to the file. - const tsFileDefinitions = new Map(); - const authProfiles = new Map(); - const connections = new Map(); - - for (const entry of entries) { - const entryPath = join(dirPath, entry); - let entryStat; - try { - entryStat = await stat(entryPath); - } catch { - continue; - } - if (!entryStat.isFile()) continue; - - // Auto-discovered local connector definition. - if (entry.endsWith(".connector.ts")) { - const sourceCode = await readFile(entryPath, "utf-8"); - tsFileDefinitions.set(entryPath, { - key: null, - sourcePath: entryPath, - sourceCode, - sourceFile: `${dirRel}/${entry}`, - }); - continue; - } - - if (!entry.endsWith(".yaml") && !entry.endsWith(".yml")) continue; - - const rel = `${dirRel}/${entry}`; - const raw = await readFile(entryPath, "utf-8"); - let docs: unknown[]; - try { - docs = parseAllDocuments(raw) - .map((doc) => doc.toJSON() as unknown) - .filter((doc) => doc !== null && doc !== undefined); - } catch (err) { - throw new ValidationError( - `${rel}: failed to parse YAML — ${err instanceof Error ? err.message : String(err)}` - ); - } - - for (const doc of docs) { - if (!isRecord(doc)) { - throw new ValidationError( - `${rel}: each connectors doc must be a mapping with \`version\` and \`type\`` - ); - } - const type = asString(doc.type); - if (!type) { - throw new ValidationError( - `${rel}: connectors doc is missing a "type" (connection|auth_profile|connector)` - ); - } - if (doc.version !== undefined && doc.version !== 1) { - throw new ValidationError( - `${rel}: unsupported connectors doc version ${JSON.stringify(doc.version)} (expected 1)` - ); - } - if (type === "connection") { - const conn = parseConnectionDoc(doc, rel); - if (connections.has(conn.slug)) { - throw new ValidationError( - `${rel}: duplicate connection slug "${conn.slug}"` - ); - } - connections.set(conn.slug, conn); - } else if (type === "auth_profile") { - const profile = parseAuthProfileDoc(doc, rel); - if (authProfiles.has(profile.slug)) { - throw new ValidationError( - `${rel}: duplicate auth_profile slug "${profile.slug}"` - ); - } - if (profile.credentials) { - // Expand `$ENV` refs in-place (collect them too, so the apply - // secrets gate fails loud) — never push literal `$NAME` strings. - const resolved: Record = {}; - for (const [k, v] of Object.entries(profile.credentials)) { - const ref = asEnvRef(v); - if (!ref) { - resolved[k] = v; - continue; - } - envRefs.add(ref); - const value = env[ref]; - if (value === undefined || value === "") { - throw new ValidationError( - `${rel}: auth_profile "${profile.slug}" credential "${k}" references $${ref}, but it is unset or empty in the apply environment` - ); - } - resolved[k] = value; - } - profile.credentials = resolved; - } - authProfiles.set(profile.slug, profile); - } else if (type === "connector") { - const parsed = parseConnectorDoc(doc, rel); - const priorDoc = connectorDocKeyDeclaredBy.get(parsed.key); - if (priorDoc) { - throw new ValidationError( - `connector key "${parsed.key}" is declared by two \`type: connector\` docs — ${priorDoc} and ${rel}; keys must be unique` - ); - } - connectorDocKeyDeclaredBy.set(parsed.key, rel); - if (parsed.sourceUrl) { - const prior = definitionsByKey.get(parsed.key); - if (prior) { - throw new ValidationError( - `connector key "${parsed.key}" is declared twice — in ${prior.sourceFile} and ${rel}; keys must be unique` - ); - } - const priorTs = [...tsFileDefinitions.values()].find( - (d) => d.key === parsed.key - ); - if (priorTs) { - throw new ValidationError( - `connector key "${parsed.key}" is declared twice — in ${priorTs.sourceFile} and ${rel}; keys must be unique` - ); - } - definitionsByKey.set(parsed.key, { - key: parsed.key, - sourceUrl: parsed.sourceUrl, - sourceFile: rel, - }); - } else if (parsed.sourcePath) { - // `source_path` is resolved relative to the manifest YAML file's - // directory (the connectors/ dir), matching the watcher-classifier - // `source_path` convention. - const abs = resolve(dirPath, parsed.sourcePath); - // The declared key must not collide with another connector definition. - const keyClash = - definitionsByKey.get(parsed.key) ?? - [...tsFileDefinitions.entries()].find( - ([p, d]) => d.key === parsed.key && p !== abs - )?.[1]; - if (keyClash) { - throw new ValidationError( - `connector key "${parsed.key}" is declared twice — in ${keyClash.sourceFile} and ${rel}; keys must be unique` - ); - } - if (tsFileDefinitions.has(abs)) { - // Already auto-discovered as a `*.connector.ts` file; the - // `type: connector` doc just declares its key for clearer output. - const existing = tsFileDefinitions.get(abs); - if (existing) { - if (existing.key !== null && existing.key !== parsed.key) { - throw new ValidationError( - `${existing.sourceFile} declares connector key "${existing.key}" but ${rel} declares "${parsed.key}" for the same file — they must agree` - ); - } - existing.key = parsed.key; - } - } else { - let sourceCode: string; - try { - sourceCode = await readFile(abs, "utf-8"); - } catch { - throw new ValidationError( - `${rel}: connector "${parsed.key}" \`source_path\` ${parsed.sourcePath} does not exist` - ); - } - tsFileDefinitions.set(abs, { - key: parsed.key, - sourcePath: abs, - sourceCode, - sourceFile: rel, - }); - } - } - } else { - throw new ValidationError( - `${rel}: unknown connectors doc type "${type}" (expected connection|auth_profile|connector)` - ); - } - } - } - - const allDefs = [...definitionsByKey.values(), ...tsFileDefinitions.values()]; - const seenKeys = new Map(); - for (const def of allDefs) { - if (def.key === null) continue; - const prior = seenKeys.get(def.key); - if (prior) { - throw new ValidationError( - `connector key "${def.key}" is declared twice — in ${prior} and ${def.sourceFile}; keys must be unique` - ); - } - seenKeys.set(def.key, def.sourceFile); - } - - return { - definitions: allDefs.sort((a, b) => - (a.key ?? a.sourceFile).localeCompare(b.key ?? b.sourceFile) - ), - authProfiles: [...authProfiles.values()].sort((a, b) => - a.slug.localeCompare(b.slug) - ), - connections: [...connections.values()].sort((a, b) => - a.slug.localeCompare(b.slug) - ), - }; + return typeof value === "string" ? value : undefined; } // ── Connector-config validation (used by apply-cmd with remote catalog) ──── @@ -1911,7 +635,7 @@ export function validateAuthProfileAgainstConnector( // ── Public API ───────────────────────────────────────────────────────────── export interface LoadDesiredStateOptions { - /** Project root (directory containing `lobu.toml`). */ + /** Project root (directory containing `lobu.config.ts`). */ cwd: string; /** Env to resolve `$VAR` refs against; defaults to `process.env`. */ env?: NodeJS.ProcessEnv; @@ -1923,98 +647,6 @@ export interface LoadDesiredStateOptions { only?: "agents" | "memory"; } -export async function loadDesiredState( - opts: LoadDesiredStateOptions -): Promise<{ state: DesiredState; configPath: string }> { - const result = await loadConfig(opts.cwd); - if (isLoadError(result)) { - const detail = result.details?.length - ? `${result.error}\n ${result.details.join("\n ")}` - : result.error; - throw new ValidationError(detail); - } - - const { config, path: configPath } = result; - await rejectUnsupportedAgentShapes(opts.cwd); - - const env = opts.env ?? process.env; - const requiredSecrets = new Set(); - collectEnvRefs(config, requiredSecrets); - - const agents: DesiredAgent[] = []; - for (const [agentId, agentConfig] of Object.entries(config.agents)) { - const agentDir = resolve(opts.cwd, agentConfig.dir); - const markdown = await readMarkdown(agentDir); - const skillFiles = await loadSkillFiles([ - join(opts.cwd, "skills"), - join(agentDir, "skills"), - ]); - const settings = buildAgentSettings(agentConfig, markdown, skillFiles); - const platforms = buildPlatforms(agentId, agentConfig, env); - // Resolve `[[providers]] key = "$VAR"` against the apply env. The - // required-secrets gate in apply-cmd already failed loudly if any $VAR - // is unset, so a missing value here means the operator omitted `key` - // entirely (BYOK / web-UI flow); silently skip those. - const providerKeys: { providerId: string; value: string }[] = []; - for (const provider of agentConfig.providers) { - if (!provider.key) continue; - const ref = asEnvRef(provider.key); - const resolved = ref ? env[ref] : provider.key; - if (!resolved) continue; - providerKeys.push({ providerId: provider.id, value: resolved }); - } - const metadata: DesiredAgentMetadata = { - agentId, - name: agentConfig.name, - }; - if (agentConfig.description) metadata.description = agentConfig.description; - agents.push({ metadata, settings, platforms, providerKeys }); - } - - const { entityTypes, relationshipTypes, watchers } = await loadMemoryModels( - config, - opts.cwd - ); - - for (const watcher of watchers) { - if (!config.agents[watcher.agent]) { - throw new ValidationError( - `watcher "${watcher.slug}" names agent "${watcher.agent}", but there is no \`[agents.${watcher.agent}]\` block in lobu.toml` - ); - } - } - - const connectors = opts.only - ? { definitions: [], authProfiles: [], connections: [] } - : await loadConnectors(config, opts.cwd, env, requiredSecrets); - - const memory = - config.memory && config.memory.enabled !== false - ? { - ...(config.memory.org ? { org: config.memory.org } : {}), - ...(config.memory.organization_id - ? { organizationId: config.memory.organization_id } - : {}), - ...(config.memory.name ? { name: config.memory.name } : {}), - ...(config.memory.description - ? { description: config.memory.description } - : {}), - } - : undefined; - - return { - state: { - agents, - ...(memory ? { memory } : {}), - memorySchema: { entityTypes, relationshipTypes }, - watchers, - connectors, - requiredSecrets: [...requiredSecrets].sort(), - }, - configPath, - }; -} - /** * Discover local connector definitions for the TypeScript config path. * diff --git a/packages/cli/src/config/loader.ts b/packages/cli/src/config/loader.ts deleted file mode 100644 index d30845f08..000000000 --- a/packages/cli/src/config/loader.ts +++ /dev/null @@ -1,59 +0,0 @@ -import { readFile } from "node:fs/promises"; -import { join } from "node:path"; -import { parse as parseToml } from "smol-toml"; -import { type LobuTomlConfig, lobuConfigSchema } from "./schema.js"; - -export const CONFIG_FILENAME = "lobu.toml"; - -interface LoadResult { - config: LobuTomlConfig; - path: string; -} - -interface LoadError { - error: string; - details?: string[]; -} - -/** - * Load and validate lobu.toml from a directory. - */ -export async function loadConfig(cwd: string): Promise { - const configPath = join(cwd, CONFIG_FILENAME); - - let raw: string; - try { - raw = await readFile(configPath, "utf-8"); - } catch { - return { - error: `No ${CONFIG_FILENAME} found in ${cwd}`, - details: ["Run `lobu init` to create one."], - }; - } - - let parsed: Record; - try { - parsed = parseToml(raw) as Record; - } catch (err) { - return { - error: `Invalid TOML syntax in ${configPath}`, - details: [err instanceof Error ? err.message : String(err)], - }; - } - - const result = lobuConfigSchema.safeParse(parsed); - if (!result.success) { - const details = result.error.issues.map( - (issue) => `${issue.path.join(".")}: ${issue.message}` - ); - return { error: `Invalid ${configPath}`, details }; - } - - return { config: result.data, path: configPath }; -} - -export function isLoadError( - result: LoadResult | LoadError -): result is LoadError { - return "error" in result; -} diff --git a/packages/cli/src/config/schema.ts b/packages/cli/src/config/schema.ts deleted file mode 100644 index 23f20a7ec..000000000 --- a/packages/cli/src/config/schema.ts +++ /dev/null @@ -1,6 +0,0 @@ -/** - * Thin re-export of the canonical `lobu.toml` schema from `@lobu/core`. - * The actual definition lives in `@lobu/core/src/lobu-toml-schema.ts`. - */ - -export { type LobuTomlConfig, lobuConfigSchema } from "@lobu/core"; diff --git a/packages/core/src/__tests__/lobu-toml-schema-harden.test.ts b/packages/core/src/__tests__/lobu-toml-schema-harden.test.ts deleted file mode 100644 index b7ac71523..000000000 --- a/packages/core/src/__tests__/lobu-toml-schema-harden.test.ts +++ /dev/null @@ -1,803 +0,0 @@ -/** - * Hardened edge-case tests for lobu-toml-schema.ts. - * - * The existing lobu-toml-schema.test.ts covers preview and memory. - * This file covers: agent ID validation, provider mutual-exclusion, - * pre_approved tool pattern enforcement, network config, egress, - * platform name regex, and unknown/wrong-type fields. - */ - -import { describe, expect, test } from "bun:test"; -import { parse as parseToml } from "smol-toml"; -import { lobuConfigSchema } from "../lobu-toml-schema"; - -// ── Helpers ───────────────────────────────────────────────────────────────── - -function valid(toml: string) { - return lobuConfigSchema.safeParse(parseToml(toml)); -} - -function validResult(toml: string) { - const r = valid(toml); - if (!r.success) throw new Error(r.error.toString()); - return r.data; -} - -const BASE = ` -[agents.triage] -name = "Triage" -dir = "./agents/triage" -`; - -// ── Agent ID validation ────────────────────────────────────────────────────── - -describe("lobu.toml agent ID validation", () => { - test("accepts lowercase-alphanumeric-hyphen agent id", () => { - const result = valid(` -[agents.my-agent] -name = "My Agent" -dir = "./agents/my-agent" -`); - expect(result.success).toBe(true); - }); - - test("rejects agent id starting with a hyphen", () => { - // smol-toml would parse this as a weird key; zod regex should reject it - const raw = parseToml(` -[agents.my-agent] -name = "OK" -dir = "./" -`); - // Simulate a bad key by patching the parsed object directly - const bad = { agents: { "-bad": { name: "Bad", dir: "./" } } }; - const result = lobuConfigSchema.safeParse(bad); - expect(result.success).toBe(false); - }); - - test("rejects agent id with uppercase letters", () => { - const bad = { agents: { MyAgent: { name: "Bad", dir: "./" } } }; - const result = lobuConfigSchema.safeParse(bad); - expect(result.success).toBe(false); - }); - - test("rejects agent id with spaces", () => { - const bad = { agents: { "my agent": { name: "Bad", dir: "./" } } }; - const result = lobuConfigSchema.safeParse(bad); - expect(result.success).toBe(false); - }); - - test("accepts agent id with numbers mid-string", () => { - const result = valid(` -[agents.agent2go] -name = "A" -dir = "./" -`); - expect(result.success).toBe(true); - }); - - test("requires at least one agent", () => { - const result = lobuConfigSchema.safeParse({ agents: {} }); - // An empty agents record is technically valid schema-wise (record allows empty) - // but flags real gaps — we verify it does NOT crash - expect(typeof result.success).toBe("boolean"); - }); -}); - -// ── Missing required fields ────────────────────────────────────────────────── - -describe("lobu.toml required fields", () => { - test("rejects agent entry missing name", () => { - const bad = { agents: { triage: { dir: "./" } } }; - expect(lobuConfigSchema.safeParse(bad).success).toBe(false); - }); - - test("rejects agent entry missing dir", () => { - const bad = { agents: { triage: { name: "Triage" } } }; - expect(lobuConfigSchema.safeParse(bad).success).toBe(false); - }); - - test("rejects top-level missing agents key", () => { - expect(lobuConfigSchema.safeParse({}).success).toBe(false); - }); - - test("accepts optional description field", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { name: "Triage", description: "Handles stuff", dir: "./" }, - }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.description).toBe("Handles stuff"); - } - }); -}); - -// ── Provider key / secret_ref mutual exclusion ─────────────────────────────── - -describe("lobu.toml provider mutual exclusion", () => { - test("accepts provider with only key", () => { - const result = valid(`${BASE} -[[agents.triage.providers]] -id = "anthropic" -key = "sk-ant-xxx" -`); - expect(result.success).toBe(true); - }); - - test("accepts provider with only secret_ref", () => { - const result = valid(`${BASE} -[[agents.triage.providers]] -id = "anthropic" -secret_ref = "lobu_secret_abc123" -`); - expect(result.success).toBe(true); - }); - - test("rejects provider with both key and secret_ref", () => { - const result = valid(`${BASE} -[[agents.triage.providers]] -id = "anthropic" -key = "sk-ant-xxx" -secret_ref = "lobu_secret_abc123" -`); - expect(result.success).toBe(false); - if (!result.success) { - const messages = result.error.issues.map((i) => i.message).join(" "); - expect(messages).toContain("at most one"); - } - }); - - test("accepts provider with neither key nor secret_ref (env-var fallback)", () => { - const result = valid(`${BASE} -[[agents.triage.providers]] -id = "openai" -`); - expect(result.success).toBe(true); - }); -}); - -// ── tools.pre_approved pattern validation ──────────────────────────────────── - -describe("lobu.toml tools.pre_approved patterns", () => { - test("accepts a valid specific tool path", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["/mcp/gmail/tools/send_email"] -`); - expect(result.success).toBe(true); - }); - - test("accepts a wildcard tool path", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["/mcp/linear/tools/*"] -`); - expect(result.success).toBe(true); - }); - - test("accepts mixed specific and wildcard patterns", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["/mcp/gmail/tools/send_email", "/mcp/linear/tools/*"] -`); - expect(result.success).toBe(true); - }); - - test("rejects a bare tool name (no leading slash)", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["gmail"] -`); - expect(result.success).toBe(false); - if (!result.success) { - const msgs = result.error.issues.map((i) => i.message).join(" "); - expect(msgs).toMatch(/pre_approved/i); - } - }); - - test("rejects missing /tools/ segment", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["/mcp/gmail/send_email"] -`); - expect(result.success).toBe(false); - }); - - test("rejects double wildcard pattern", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["/mcp/gmail/tools/**"] -`); - expect(result.success).toBe(false); - }); - - test("rejects URL-style pattern", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["https://example.com/mcp/tools/read"] -`); - expect(result.success).toBe(false); - }); - - test("accepts mcp id with underscores and dashes", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["/mcp/my_mcp-server/tools/do_thing"] -`); - expect(result.success).toBe(true); - }); - - test("rejects mcp id with dots", () => { - const result = valid(`${BASE} -[agents.triage.tools] -pre_approved = ["/mcp/my.mcp/tools/do_thing"] -`); - expect(result.success).toBe(false); - }); -}); - -// ── tools.allowed / denied / strict ───────────────────────────────────────── - -describe("lobu.toml tools.allowed / denied / strict", () => { - test("accepts allowed/denied/strict combination", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - tools: { - allowed: ["Bash(git:*)", "mcp__github__*"], - denied: ["Bash(rm:*)"], - strict: true, - }, - }, - }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.tools?.strict).toBe(true); - } - }); - - test("rejects non-boolean strict", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - tools: { strict: "yes" }, - }, - }, - }); - expect(r.success).toBe(false); - }); -}); - -// ── egress config ───────────────────────────────────────────────────────────── - -describe("lobu.toml egress config", () => { - test("accepts extra_policy and judge_model", () => { - const result = valid(`${BASE} -[agents.triage.egress] -extra_policy = "Never exfiltrate tokens." -judge_model = "claude-haiku-4-5-20251001" -`); - expect(result.success).toBe(true); - if (result.success) { - expect(result.data.agents.triage?.egress?.extra_policy).toBe( - "Never exfiltrate tokens." - ); - expect(result.data.agents.triage?.egress?.judge_model).toBe( - "claude-haiku-4-5-20251001" - ); - } - }); - - test("accepts egress with no fields (all optional)", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./", egress: {} } }, - }); - expect(r.success).toBe(true); - }); - - test("rejects non-string extra_policy", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - egress: { extra_policy: 42 }, - }, - }, - }); - expect(r.success).toBe(false); - }); -}); - -// ── network config ──────────────────────────────────────────────────────────── - -describe("lobu.toml network config", () => { - test("normalizes *.example.com to .example.com in allowed", () => { - const result = valid(`${BASE} -[agents.triage.network] -allowed = ["*.example.com", "api.github.com"] -`); - expect(result.success).toBe(true); - if (result.success) { - expect(result.data.agents.triage?.network?.allowed).toContain( - ".example.com" - ); - expect(result.data.agents.triage?.network?.allowed).toContain( - "api.github.com" - ); - } - }); - - test("deduplicates domain patterns in allowed", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - network: { allowed: ["api.github.com", "api.github.com"] }, - }, - }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.network?.allowed).toEqual([ - "api.github.com", - ]); - } - }); - - test("accepts judge entries as strings", () => { - const result = valid(`${BASE} -[agents.triage.network] -allowed = ["api.example.com"] -judge = ["*.slack.com"] -`); - expect(result.success).toBe(true); - if (result.success) { - expect(result.data.agents.triage?.network?.judge).toEqual([ - { domain: "*.slack.com" }, - ]); - } - }); - - test("accepts judge entries as objects with named policy", () => { - const result = valid(`${BASE} -[agents.triage.network] -[[agents.triage.network.judge]] -domain = "*.slack.com" -judge = "strict" - -[agents.triage.network.judges] -strict = "Only GET requests." -`); - expect(result.success).toBe(true); - if (result.success) { - const judge = result.data.agents.triage?.network?.judge?.[0]; - expect(judge?.domain).toBe("*.slack.com"); - expect((judge as any)?.judge).toBe("strict"); - } - }); - - test("lowercases domain patterns in denied", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - network: { denied: ["MALICIOUS.COM"] }, - }, - }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.network?.denied).toContain("malicious.com"); - } - }); -}); - -// ── platform config ─────────────────────────────────────────────────────────── - -describe("lobu.toml platform config", () => { - test("accepts valid platform with all fields", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - platforms: [ - { - type: "telegram", - name: "main", - config: { botToken: "$BOT_TOKEN" }, - channels: ["123456", "789012"], - }, - ], - }, - }, - }); - expect(r.success).toBe(true); - }); - - test("rejects platform name with uppercase", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - platforms: [ - { - type: "slack", - name: "MyWorkspace", - config: { botToken: "xoxb-..." }, - }, - ], - }, - }, - }); - expect(r.success).toBe(false); - if (!r.success) { - const msgs = r.error.issues.map((i) => i.message).join(" "); - expect(msgs).toMatch(/lowercase/i); - } - }); - - test("rejects platform name starting with hyphen", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - platforms: [ - { - type: "slack", - name: "-bad", - config: { botToken: "xoxb-..." }, - }, - ], - }, - }, - }); - expect(r.success).toBe(false); - }); - - test("accepts platform without optional name", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - platforms: [{ type: "telegram", config: { botToken: "$BOT_TOKEN" } }], - }, - }, - }); - expect(r.success).toBe(true); - }); -}); - -// ── mcp server config ───────────────────────────────────────────────────────── - -describe("lobu.toml mcp server config", () => { - test("accepts streamable-http type", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - skills: { - mcp: { - github: { - type: "streamable-http", - url: "https://mcp.github.com", - }, - }, - }, - }, - }, - }); - expect(r.success).toBe(true); - }); - - test("accepts stdio type with command and args", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - skills: { - mcp: { - local: { - type: "stdio", - command: "npx", - args: ["-y", "@mcp/pkg"], - }, - }, - }, - }, - }, - }); - expect(r.success).toBe(true); - }); - - test("rejects unknown mcp type", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - skills: { mcp: { bad: { type: "websocket", url: "ws://..." } } }, - }, - }, - }); - expect(r.success).toBe(false); - }); - - test("accepts auth_scope user", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - skills: { - mcp: { - svc: { - type: "streamable-http", - url: "https://svc.example.com", - auth_scope: "user", - }, - }, - }, - }, - }, - }); - expect(r.success).toBe(true); - }); - - test("accepts auth_scope channel", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - skills: { - mcp: { - svc: { - type: "streamable-http", - url: "https://svc.example.com", - auth_scope: "channel", - }, - }, - }, - }, - }, - }); - expect(r.success).toBe(true); - }); - - test("rejects unknown auth_scope", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - skills: { - mcp: { - svc: { - type: "streamable-http", - url: "https://svc.example.com", - auth_scope: "org", - }, - }, - }, - }, - }, - }); - expect(r.success).toBe(false); - }); -}); - -// ── guardrails list ────────────────────────────────────────────────────────── - -describe("lobu.toml guardrails", () => { - test("accepts a guardrails array of strings", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - guardrails: ["prompt-injection", "secret-scan"], - }, - }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.guardrails).toEqual([ - "prompt-injection", - "secret-scan", - ]); - } - }); - - test("rejects non-string guardrail entry", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - guardrails: [42], - }, - }, - }); - expect(r.success).toBe(false); - }); - - test("accepts empty guardrails array", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./", guardrails: [] } }, - }); - expect(r.success).toBe(true); - }); -}); - -// ── worker config ───────────────────────────────────────────────────────────── - -describe("lobu.toml worker config", () => { - test("accepts nix_packages list", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - worker: { nix_packages: ["python311", "ffmpeg"] }, - }, - }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.worker?.nix_packages).toEqual([ - "python311", - "ffmpeg", - ]); - } - }); - - test("accepts empty worker config", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./", worker: {} } }, - }); - expect(r.success).toBe(true); - }); -}); - -// ── memory strict mode ──────────────────────────────────────────────────────── - -describe("lobu.toml memory strict mode", () => { - test("rejects unknown memory key", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./" } }, - memory: { enabled: true, unknown_field: "oops" }, - }); - expect(r.success).toBe(false); - }); - - test("accepts all known memory fields", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./" } }, - memory: { - enabled: true, - org: "dev", - organization_id: "org-uuid-123", - name: "Dev Org", - description: "For dev use", - visibility: "private", - models: "./models", - data: "./data", - connectors: "./connectors", - }, - }); - expect(r.success).toBe(true); - }); - - test("rejects invalid visibility value", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./" } }, - memory: { visibility: "protected" }, - }); - expect(r.success).toBe(false); - }); -}); - -// ── preview code_ttl_minutes max ───────────────────────────────────────────── - -describe("lobu.toml preview code_ttl_minutes bounds", () => { - test("accepts code_ttl_minutes = 60", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - preview: { slack: { enabled: true, code_ttl_minutes: 60 } }, - }, - }, - }); - expect(r.success).toBe(true); - }); - - test("rejects code_ttl_minutes = 61 (exceeds max)", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - preview: { slack: { enabled: true, code_ttl_minutes: 61 } }, - }, - }, - }); - expect(r.success).toBe(false); - }); - - test("rejects code_ttl_minutes = 0 (not positive)", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - preview: { slack: { enabled: true, code_ttl_minutes: 0 } }, - }, - }, - }); - expect(r.success).toBe(false); - }); - - test("rejects non-integer code_ttl_minutes", () => { - const r = lobuConfigSchema.safeParse({ - agents: { - triage: { - name: "T", - dir: "./", - preview: { slack: { enabled: true, code_ttl_minutes: 1.5 } }, - }, - }, - }); - expect(r.success).toBe(false); - }); -}); - -// ── default value coercions ─────────────────────────────────────────────────── - -describe("lobu.toml default value coercions", () => { - test("providers defaults to []", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./" } }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.providers).toEqual([]); - } - }); - - test("platforms defaults to []", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./" } }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.platforms).toEqual([]); - } - }); - - test("skills defaults to {}", () => { - const r = lobuConfigSchema.safeParse({ - agents: { triage: { name: "T", dir: "./" } }, - }); - expect(r.success).toBe(true); - if (r.success) { - expect(r.data.agents.triage?.skills).toEqual({}); - } - }); -}); diff --git a/packages/core/src/__tests__/lobu-toml-schema.test.ts b/packages/core/src/__tests__/lobu-toml-schema.test.ts deleted file mode 100644 index bafd966ef..000000000 --- a/packages/core/src/__tests__/lobu-toml-schema.test.ts +++ /dev/null @@ -1,114 +0,0 @@ -import { describe, expect, test } from "bun:test"; -import { parse as parseToml } from "smol-toml"; -import { lobuConfigSchema } from "../lobu-toml-schema"; - -const BASE_AGENT = ` -[agents.triage] -name = "Triage" -dir = "./agents/triage" -`; - -describe("lobu.toml preview schema", () => { - test("accepts a per-platform preview block", () => { - const parsed = parseToml(`${BASE_AGENT} -[agents.triage.preview.slack] -enabled = true -surfaces = ["dm", "channel"] -code_ttl_minutes = 15 - -[agents.triage.preview.telegram] -enabled = true -`); - - const result = lobuConfigSchema.safeParse(parsed); - - expect(result.success).toBe(true); - if (result.success) { - expect(result.data.agents.triage?.preview?.slack?.surfaces).toEqual([ - "dm", - "channel", - ]); - expect(result.data.agents.triage?.preview?.telegram?.enabled).toBe(true); - } - }); - - test("rejects an unknown surface", () => { - const parsed = parseToml(`${BASE_AGENT} -[agents.triage.preview.slack] -enabled = true -surfaces = ["thread"] -`); - expect(lobuConfigSchema.safeParse(parsed).success).toBe(false); - }); - - test("rejects an unknown key in a preview block", () => { - const parsed = parseToml(`${BASE_AGENT} -[agents.triage.preview.slack] -enabled = true -provider = "lobu-public" -`); - expect(lobuConfigSchema.safeParse(parsed).success).toBe(false); - }); -}); - -describe("lobu.toml memory schema", () => { - test("accepts flattened [memory] fields", () => { - const parsed = parseToml(`${BASE_AGENT} -[memory] -enabled = true -org = "dev" -name = "Local Dev" -models = "./models" -data = "./data" -`); - - const result = lobuConfigSchema.safeParse(parsed); - - expect(result.success).toBe(true); - if (result.success) { - expect(result.data.memory?.org).toBe("dev"); - expect(result.data.memory?.models).toBe("./models"); - } - }); - - for (const legacyKey of ["lobu", "owletto"]) { - test(`rejects stale nested [memory.${legacyKey}] fields`, () => { - const parsed = parseToml(`${BASE_AGENT} -[memory.${legacyKey}] -enabled = false -org = "dev" -models = "./custom-models" -`); - - const result = lobuConfigSchema.safeParse(parsed); - - expect(result.success).toBe(false); - if (!result.success) { - expect(result.error.issues).toEqual( - expect.arrayContaining([ - expect.objectContaining({ - path: ["memory"], - message: expect.stringContaining(legacyKey), - }), - ]) - ); - } - }); - } - - test("rejects the removed inline [memory.schema] block", () => { - const parsed = parseToml(`${BASE_AGENT} -[memory] -enabled = true -org = "dev" -name = "Local Dev" - -[[memory.schema.entity_types]] -slug = "person" -`); - - const result = lobuConfigSchema.safeParse(parsed); - - expect(result.success).toBe(false); - }); -}); diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 9cbf82a28..6ddebeecb 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -60,22 +60,6 @@ export { renderFallbackSystemContext, renderSkillMemorySection, } from "./lobu-guidance"; -// lobu.toml zod schema (canonical — used by CLI and gateway) -export { - type AgentEntry as TomlAgentEntry, - type EgressEntry as TomlEgressEntry, - type LobuTomlConfig, - lobuConfigSchema, - type McpServerEntry as TomlMcpServerEntry, - type MemoryEntry as TomlMemoryEntry, - type NetworkEntry as TomlNetworkEntry, - type PlatformEntry as TomlPlatformEntry, - type ProviderEntry as TomlProviderEntry, - type SkillsEntry as TomlSkillsEntry, - type ToolsEntry, - type ToolsEntry as TomlToolsEntry, - type WorkerEntry as TomlWorkerEntry, -} from "./lobu-toml-schema"; export * from "./logger"; // Module system export * from "./modules"; diff --git a/packages/core/src/lobu-toml-schema.ts b/packages/core/src/lobu-toml-schema.ts deleted file mode 100644 index 5d0d28eb9..000000000 --- a/packages/core/src/lobu-toml-schema.ts +++ /dev/null @@ -1,315 +0,0 @@ -/** - * Canonical zod schema for `lobu.toml`. - * - * This is the single source of truth for both the CLI (validation on disk) - * and the gateway (runtime loading). Uses zod@4. - */ - -import { z } from "zod"; -import { normalizeDomainPatterns } from "./utils/network-domains"; - -// ── Provider ──────────────────────────────────────────────────────────────── - -const providerSchema = z - .object({ - id: z.string(), - model: z.string().optional(), - /** API key — literal value or `$ENV_VAR` reference. */ - key: z.string().optional(), - /** First-class durable secret reference. */ - secret_ref: z.string().optional(), - }) - .refine((p) => !(p.key && p.secret_ref), { - message: "provider must set at most one of `key` or `secret_ref`", - }); - -// ── Platform ──────────────────────────────────────────────────────────────── - -const platformSchema = z.object({ - type: z.string(), - /** - * Optional disambiguator when an agent has multiple platform instances of - * the same type (e.g. two Slack workspaces). Slugged and appended to the - * stable platform ID: `{agent}-{type}-{name}`. Omit when there is only one - * instance per type. - */ - name: z - .string() - .regex(/^[a-z0-9][a-z0-9-]*$/, { - message: "platform name must be lowercase alphanumeric with hyphens", - }) - .optional(), - /** Platform-specific config (e.g. `{ botToken: "$BOT_TOKEN" }`). */ - config: z.record(z.string(), z.string()), - /** - * Declarative channel routing (Slack only, for now): chat channels this agent - * should be reachable in. Each entry is `"/"` — e.g. - * `"T0ABCDEF/C0123ABCD"` (both appear in any Slack channel URL). `lobu apply` - * reconciles `agent_channel_bindings` to exactly this list for this agent on - * this connection: listed channels get bound, ones no longer listed get - * unbound. Channels linked ad-hoc via `/lobu link` on *other* connections are - * left alone. - */ - channels: z.array(z.string()).optional(), -}); - -// ── MCP Server ────────────────────────────────────────────────────────────── - -const mcpOAuthSchema = z.object({ - auth_url: z.string(), - token_url: z.string(), - client_id: z.string().optional(), - client_secret: z.string().optional(), - scopes: z.array(z.string()).optional(), - token_endpoint_auth_method: z.string().optional(), -}); - -const mcpServerSchema = z.object({ - /** - * Transport kind. `streamable-http` (default for HTTP URLs) posts to a single - * endpoint and accepts either JSON or SSE-framed responses per the MCP spec. - * `sse` is the legacy transport with a separate /sse GET channel. `stdio` - * runs a local command. - */ - type: z.enum(["streamable-http", "sse", "stdio"]).optional(), - url: z.string().optional(), - command: z.string().optional(), - args: z.array(z.string()).optional(), - env: z.record(z.string(), z.string()).optional(), - headers: z.record(z.string(), z.string()).optional(), - oauth: mcpOAuthSchema.optional(), - /** - * Credential scope for OAuth-authenticated MCPs. - * - `"user"` (default): each chat user logs in separately. Safe default. - * - `"channel"`: a single credential is shared across all users in a chat - * channel/conversation. Use only for shared-data integrations (e.g. team - * wikis) where per-user attribution isn't required. - */ - auth_scope: z.enum(["user", "channel"]).optional(), -}); - -// ── Skills ────────────────────────────────────────────────────────────────── - -const skillsSchema = z.object({ - mcp: z.record(z.string(), mcpServerSchema).optional(), -}); - -// ── Network ───────────────────────────────────────────────────────────────── - -const judgeDomainEntry = z.union([ - z.string(), - z.object({ - domain: z.string(), - judge: z.string().optional(), - }), -]); - -const networkSchema = z - .object({ - allowed: z.array(z.string()).optional(), - denied: z.array(z.string()).optional(), - /** - * Domains routed through the LLM egress judge. Each entry is either - * a bare domain string (uses the "default" judge policy) or an object - * `{ domain, judge }` naming a policy in {@link network.judges}. - */ - judge: z.array(judgeDomainEntry).optional(), - /** - * Named judge policies referenced by `judge[].judge`. The key "default" - * is applied when an entry omits `judge`. - */ - judges: z.record(z.string(), z.string()).optional(), - }) - .transform((network) => ({ - allowed: normalizeDomainPatterns(network.allowed), - denied: normalizeDomainPatterns(network.denied), - judge: network.judge?.map((entry) => - typeof entry === "string" - ? { domain: entry } - : { - domain: entry.domain, - ...(entry.judge ? { judge: entry.judge } : {}), - } - ), - judges: network.judges, - })); - -// ── Egress ────────────────────────────────────────────────────────────────── - -const egressSchema = z.object({ - /** Operator policy appended to every judge prompt for this agent. */ - extra_policy: z.string().optional(), - /** Judge model identifier (defaults to a fast Haiku model). */ - judge_model: z.string().optional(), -}); - -// ── Guardrails (inline) ───────────────────────────────────────────────────── - -/** - * Inline guardrail declared in `lobu.toml` as an array of `[[agents..guardrails_inline]]` - * tables. Sibling to the name-based `guardrails = ["secret-scan", ...]` list — - * use this when you want to attach an ad-hoc LLM-judge guardrail without - * registering a named guardrail at gateway boot. - * - * Example: - * [[agents..guardrails_inline]] - * stage = "output" - * judge = "Never mention competitors." - * - * [[agents..guardrails_inline]] - * stage = "pre-tool" - * tools = ["github.delete_repo"] - * judge = "Only allow when issue ref matches active sprint." - * - * `tools` is only meaningful for `pre-tool` and is silently ignored for - * other stages. - */ -const guardrailInlineSchema = z.object({ - stage: z.enum(["input", "output", "pre-tool"]), - /** - * Inline LLM-judge policy text. Required for now — built-in references go - * in the sibling `guardrails = [...]` list. The judge runs through the - * shared TextJudge engine (Haiku + 5-min cache + circuit breaker). - */ - judge: z.string().min(1), - /** - * Optional pre-tool narrowing. Only meaningful when `stage = "pre-tool"`. - * When omitted the guardrail runs on every tool call. - */ - tools: z.array(z.string()).optional(), -}); - -// ── Tools ─────────────────────────────────────────────────────────────────── - -/** - * Accepted `pre_approved` entry formats: - * /mcp//tools/ - * /mcp//tools/* - * Anything else will fail validation — typos like "gmail" silently produced - * a no-op grant previously. - */ -const MCP_TOOL_PATTERN = /^\/mcp\/[a-zA-Z0-9_-]+\/tools\/([a-zA-Z0-9_-]+|\*)$/; -const mcpToolPatternSchema = z - .string() - .refine((value) => MCP_TOOL_PATTERN.test(value), { - message: - 'pre_approved entries must match "/mcp//tools/" or "/mcp//tools/*"', - }); - -const toolsSchema = z.object({ - /** - * Operator override: MCP tool grant patterns that bypass the in-thread - * approval card. Synced to the grant store at deployment time. See - * {@link AgentSettings.preApprovedTools} for the runtime shape. - */ - pre_approved: z.array(mcpToolPatternSchema).optional(), - /** - * Worker-side tool visibility filter. Patterns follow Claude Code's - * permission format: `Read`, `Bash(git:*)`, `mcp__github__*`, `*`. - */ - allowed: z.array(z.string()).optional(), - denied: z.array(z.string()).optional(), - /** If true, ONLY `allowed` tools are permitted (ignores worker defaults). */ - strict: z.boolean().optional(), -}); - -// ── Worker ────────────────────────────────────────────────────────────────── - -const workerSchema = z.object({ - nix_packages: z.array(z.string()).optional(), -}); - -// ── Preview ───────────────────────────────────────────────────────────────── - -// Per-platform "try this agent in the hosted Lobu workspace" config — the key -// in `[agents..preview.]` is the chat platform (slack, telegram, -// …). `lobu run` prints a `/lobu link ` (`/link ` on Telegram) for -// each enabled platform; redeem it by DMing the hosted bot. -const previewPlatformSchema = z - .object({ - /** Enable the hosted Lobu preview bot for this agent on this platform. */ - enabled: z.boolean().optional(), - /** Surfaces a preview code can bind: a DM with the bot, or a channel it's in. */ - surfaces: z.array(z.enum(["dm", "channel"])).optional(), - /** Short-lived claim-code TTL. Capped by the hosted preview API. */ - code_ttl_minutes: z.number().int().positive().max(60).optional(), - }) - .strict(); - -const previewSchema = z.record(z.string(), previewPlatformSchema); - -// ── Agent ─────────────────────────────────────────────────────────────────── - -const agentEntrySchema = z.object({ - name: z.string(), - description: z.string().optional(), - /** Path to agent content directory (IDENTITY.md, SOUL.md, USER.md, skills/). */ - dir: z.string(), - providers: z.array(providerSchema).default([]), - platforms: z.array(platformSchema).default([]), - skills: skillsSchema.default({}), - network: networkSchema.optional(), - egress: egressSchema.optional(), - tools: toolsSchema.optional(), - /** - * Guardrails enabled for this agent. Each name must match a guardrail - * registered in the gateway's GuardrailRegistry. See packages/core/src/guardrails. - */ - guardrails: z.array(z.string()).optional(), - /** - * Operator's exclude list: built-in / skill-provided guardrails that - * should be turned off for this agent even if a skill declared them. - * Names are matched against {@link Guardrail.name}, including the - * synthesized `inline::` names for inline judges from skills. - */ - guardrails_disabled: z.array(z.string()).optional(), - /** - * Inline guardrails declared directly on the agent (no registry lookup). - * Each entry materializes into an ad-hoc registered guardrail named - * `inline::` (hash of policy text) and is merged into the - * effective per-agent list at startup. - */ - guardrails_inline: z.array(guardrailInlineSchema).optional(), - worker: workerSchema.optional(), - preview: previewSchema.optional(), -}); - -// ── Memory ───────────────────────────────────────────────────────────────── - -const memorySchema = z - .object({ - enabled: z.boolean().optional(), - org: z.string().optional(), - /** Resolved organization id, written back by `lobu apply` once the org is - * resolved or created. Committed so the whole team applies to the same org. */ - organization_id: z.string().optional(), - name: z.string().optional(), - description: z.string().optional(), - visibility: z.enum(["public", "private"]).optional(), - models: z.string().optional(), - data: z.string().optional(), - connectors: z.string().optional(), - }) - .strict(); - -// ── Top Level ─────────────────────────────────────────────────────────────── - -export const lobuConfigSchema = z.object({ - agents: z.record(z.string().regex(/^[a-z0-9][a-z0-9-]*$/), agentEntrySchema), - memory: memorySchema.optional(), -}); - -// ── Inferred Types ────────────────────────────────────────────────────────── - -export type LobuTomlConfig = z.infer; -export type AgentEntry = z.infer; -export type ProviderEntry = z.infer; -export type PlatformEntry = z.infer; -export type McpServerEntry = z.infer; -export type SkillsEntry = z.infer; -export type NetworkEntry = z.infer; -export type EgressEntry = z.infer; -export type ToolsEntry = z.infer; -export type WorkerEntry = z.infer; -export type MemoryEntry = z.infer; -export type GuardrailInlineEntry = z.infer; diff --git a/packages/server/src/gateway/guardrails/aggregator.ts b/packages/server/src/gateway/guardrails/aggregator.ts index f2f4fc74e..2a2407460 100644 --- a/packages/server/src/gateway/guardrails/aggregator.ts +++ b/packages/server/src/gateway/guardrails/aggregator.ts @@ -16,7 +16,7 @@ const logger = createLogger("guardrail-aggregator"); /** * Inline guardrail entry declared by the agent in lobu.toml (see - * `guardrails_inline` in lobu-toml-schema.ts). We accept the parsed shape + * `guardrails_inline` in the agent config). We accept the parsed shape * here so callers can pass either the toml-parsed entries or the in-memory * agent representation. */ From a907d2e7c1f8f7f0bef1560b291aef645f4016eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 02:10:06 +0100 Subject: [PATCH 22/65] docs(cli): refresh DesiredState comments for the lobu.config.ts world --- .../src/commands/_lib/apply/desired-state.ts | 56 +++++++++---------- 1 file changed, 25 insertions(+), 31 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index d85aadc87..7741cbe3e 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -31,7 +31,7 @@ export interface DesiredPlatform { stableId: string; type: string; name?: string; - /** Raw config from lobu.toml — values may still contain `$VAR` references. */ + /** Platform config — values may still contain `$VAR` references. */ config: Record; /** Declarative channel bindings (`"/"`); Slack only. */ channels?: string[]; @@ -68,10 +68,9 @@ export interface DesiredWatcher { sources?: Array<{ name: string; query: string }>; /** * Reaction script — TypeScript source compiled + executed in an isolate at - * watcher-firing time. Authored as a sibling `.ts` file (`reaction_script: - * ./funnel-digest.ts` in the YAML), the CLI reads it and pushes raw source - * via `set_reaction_script`. Inline strings are rejected so the IDE can - * type-check the script. + * watcher-firing time. Authored as a sibling `.ts` file referenced by + * `defineWatcher({ reaction: "./reactions/foo.reaction.ts" })`; the CLI reads + * it and pushes raw source via `set_reaction_script`. */ reactionScript?: { sourcePath: string; sourceCode: string }; /** LLM guidance for the watcher's downstream reaction agent. */ @@ -128,7 +127,7 @@ export interface DesiredConnection { */ deviceWorkerId?: string; feeds: DesiredFeed[]; - /** Relative path of the YAML file the doc came from (for error messages). */ + /** Source label for error messages (the config the connection came from). */ sourceFile: string; } @@ -173,21 +172,19 @@ export interface DesiredConnectorDefinition { export interface DesiredAgent { metadata: DesiredAgentMetadata; /** - * Settings payload destined for `PATCH /:agentId/config`. Built from the - * lobu.toml fields the file-loader currently lifts: networkConfig, - * skillsConfig, egressConfig, preApprovedTools, guardrails, toolsConfig, - * nixConfig, mcpServers, modelSelection, providerModelPreferences, - * installedProviders, identityMd/soulMd/userMd. - * - * Persistence of egressConfig/preApprovedTools/guardrails depends on PR-1. + * Settings payload destined for `PATCH /:agentId/config`. Built by the mapper + * + agent-dir loader: networkConfig, skillsConfig, egressConfig, + * preApprovedTools, guardrails, toolsConfig, nixConfig, mcpServers, + * modelSelection, providerModelPreferences, installedProviders, + * identityMd/soulMd/userMd. */ settings: Partial; platforms: DesiredPlatform[]; /** - * Provider API keys resolved from `[[providers]] key = "$VAR"` in lobu.toml - * that need to be pushed into `agent_secrets` after the settings PATCH. - * Empty when no provider declared a `key` (or all keys are empty/unset). - * The actual secret value lives only in process memory; never serialized. + * Provider API keys resolved from `secret()` / `$VAR` provider keys, pushed + * into `agent_secrets` after the settings PATCH. Empty when no provider + * declared a `key` (or all are unset). The value lives only in process + * memory; never serialized. */ providerKeys: { providerId: string; value: string }[]; } @@ -195,9 +192,9 @@ export interface DesiredAgent { export interface DesiredState { agents: DesiredAgent[]; /** - * `[memory]` metadata from lobu.toml — the org slug `lobu apply` defaults to, - * the resolved `organization_id` (written back once known), and the - * name/description shown when telling the operator to create the org. + * Org metadata from `defineConfig` — the org slug `lobu apply` defaults to, + * the `organizationId` it matches against, and the name/description shown + * when telling the operator to create the org. */ memory?: { org?: string; @@ -209,12 +206,11 @@ export interface DesiredState { entityTypes: DesiredEntityType[]; relationshipTypes: DesiredRelationshipType[]; }; - /** Watchers declared under `[memory].models` YAML files. */ + /** Watchers declared via `defineWatcher`. */ watchers: DesiredWatcher[]; /** - * Data-source connectors declared in `[memory].connectors` dir: - * `*.connector.ts` files (+ `type: connector` manifests), `type: connection` - * docs, and `type: auth_profile` docs. + * Connectors: local `*.connector.ts` definitions (discovered under + * `./connectors`), `defineConnection`s, and `defineAuthProfile`s. */ connectors: { definitions: DesiredConnectorDefinition[]; @@ -222,10 +218,9 @@ export interface DesiredState { connections: DesiredConnection[]; }; /** - * Names of env vars referenced as `$NAME` anywhere in lobu.toml or in - * connector auth-profile credentials. The CLI surfaces these to the user - * before mutating remote state so missing secrets fail loud instead of - * expanding to empty strings. + * Names of env vars referenced via `secret()` / `$VAR` (provider keys, + * auth-profile + mcp credentials). The CLI surfaces these before mutating + * remote state so missing secrets fail loud instead of expanding to empty. */ requiredSecrets: string[]; } @@ -710,11 +705,10 @@ async function discoverLocalConnectorDefinitions( const REACTION_SCRIPT_MAX_BYTES = 256 * 1024; /** - * Resolve + read a watcher reaction script (`defineWatcher({ reaction })`) for - * the TS config path. Mirrors the TOML loader's `parseWatcher` validation: + * Resolve + read a watcher reaction script (`defineWatcher({ reaction })`): * relative POSIX path under the config directory, ends in `.ts`, no `..` / * absolute / backslash segments, ≤256KB. Ships RAW source — the server compiles - * it — exactly as the TOML path does via `set_reaction_script`. + * it on receipt via `set_reaction_script`. */ function resolveReactionScript( cwd: string, From 37a99eafd689ba419483480adc84c402cd67acc2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 02:10:08 +0100 Subject: [PATCH 23/65] refactor(landing): source landing snippets from lobu.config.ts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit gen-landing-snippets read the deleted example lobu.toml + models/*.yaml. Rework it to slice examples//lobu.config.ts as text (829 → 472 lines): drop the TOML/YAML parsers + compressors, add a string-literal-aware defineX(...) slicer, and source agentConfig/memorySchema/watcher from the config. examples list + useCases now scan lobu.config.ts. Frontend: agentToml → agentConfig, copy lobu.toml/YAML → lobu.config.ts/TypeScript. Landing build green. --- .../landing/scripts/gen-landing-snippets.ts | 700 +++++------------- .../landing/src/components/LandingPage.tsx | 25 +- .../src/generated/landing-snippets.json | 178 ++--- 3 files changed, 273 insertions(+), 630 deletions(-) diff --git a/packages/landing/scripts/gen-landing-snippets.ts b/packages/landing/scripts/gen-landing-snippets.ts index c7ede22cc..68921ca78 100644 --- a/packages/landing/scripts/gen-landing-snippets.ts +++ b/packages/landing/scripts/gen-landing-snippets.ts @@ -3,16 +3,23 @@ * Reads pinned files out of `examples/` and emits a flat JSON manifest the * landing page imports at build time. * + * The whole declarative project now lives in a single TypeScript file per + * example: `examples//lobu.config.ts` (using `@lobu/sdk`: + * `defineConfig`, `defineAgent`, `defineEntityType`, `defineWatcher`, ...). + * The landing page shows SOURCE CODE, so we slice the raw `.ts` text into + * budget-sized sections; we never import/execute the config. + * * Each primitive section shows ONE canonical pinned example, used as the * generic fallback when no use case is selected: * * connector -> examples/ecommerce/connectors/stripe-charges.connector.ts - * memorySchema -> examples/sales/models/schema.yaml (entities slice) - * watcher -> examples/sales/models/schema.yaml (watchers slice) - * reaction -> examples/sales/models/reactions/account-health-monitor.reaction.ts - * agentToml -> examples/sales/lobu.toml + * memorySchema -> examples/sales/lobu.config.ts (defineEntityType slice) + * watcher -> examples/sales/lobu.config.ts (defineWatcher slice) + * reaction -> examples/finance/models/reactions/reconciliation-monitor.reaction.ts + * agentConfig -> examples/sales/lobu.config.ts (imports + defineAgent slice) + * skill -> examples/office-bot/.../SKILL.md * - * Plus a list of every `examples/*\/lobu.toml` for BrowseExamplesSection: + * Plus a list of every `examples/*\/lobu.config.ts` for BrowseExamplesSection: * * examples -> [{ slug, label, description, githubUrl }] * @@ -21,8 +28,6 @@ * on the landing page swaps these three sections; everything else stays * generic. Hero copy is not part of this manifest. * - * The skill snippet stays inline in LandingPage.tsx (set in round 9). - * * Output: packages/landing/src/generated/landing-snippets.json */ @@ -34,34 +39,27 @@ const __dirname = dirname(fileURLToPath(import.meta.url)); const examplesDir = resolve(__dirname, "../../../examples"); const outFile = resolve(__dirname, "../src/generated/landing-snippets.json"); +const CONFIG_FILE = "lobu.config.ts"; + const PINNED = { connector: { slug: "ecommerce", path: "connectors/stripe-charges.connector.ts", }, - memorySchema: { slug: "sales", path: "models/schema.yaml" }, - watcher: { slug: "leadership", path: "models/schema.yaml" }, + agentConfig: { slug: "sales" }, + memorySchema: { slug: "sales" }, + watcher: { slug: "sales" }, reaction: { slug: "finance", path: "models/reactions/reconciliation-monitor.reaction.ts", }, - agentToml: { slug: "lobu-crm", path: "lobu.toml" }, skill: { slug: "office-bot", path: "agents/food-ordering/skills/deliveroo-order/SKILL.md", }, } as const; -const BUDGETS = { - agentToml: 12, - memorySchema: 22, - watcher: 16, - reaction: 50, - connector: 40, - skill: 26, -}; - -type Language = "toml" | "yaml" | "typescript" | "markdown"; +type Language = "typescript" | "markdown"; type Snippet = { code: string; @@ -88,7 +86,7 @@ type LandingSnippets = { memorySchema: Snippet; watcher: Snippet; reaction: Snippet; - agentToml: Snippet; + agentConfig: Snippet; skill: Snippet; examples: ExampleEntry[]; useCases: Record; @@ -96,7 +94,7 @@ type LandingSnippets = { /** Slugs that get per-use-case connector / memory / watcher snippets. The id * equals the example directory name. Each dir has exactly one - * connectors/*.connector.ts and a models/schema.yaml. */ + * connectors/*.connector.ts and a lobu.config.ts. */ const USE_CASE_SLUGS = [ "legal", "finance", @@ -120,391 +118,170 @@ function githubTreeUrl(slug: string): string { } /* -------------------------------------------------------------------------- */ -/* TOML extraction */ +/* TypeScript section slicing */ /* -------------------------------------------------------------------------- */ -const TOML_AGENT_KEEP_KEYS = new Set(["name"]); -const TOML_PROVIDER_KEEP_KEYS = new Set(["id", "model", "key"]); -const TOML_MEMORY_KEEP_KEYS = new Set(["enabled", "org", "models", "data"]); - -function trimAgentToml(raw: string): string { +/** + * Slice the leading `import ... from "@lobu/sdk";` block out of a config file. + * Returns the import statement lines (the first `import` through its closing + * `from "...";`), or an empty array if none is found. + */ +function sliceImportBlock(raw: string): string[] { const lines = raw.split("\n"); - const out: string[] = []; - type Mode = "skip" | "agent" | "provider" | "memory"; - let mode: Mode = "skip"; - let providersSeen = false; - for (const line of lines) { - const sectionMatch = /^\s*\[\[?([\w.-]+)\]\]?\s*$/.exec(line); - if (sectionMatch) { - const name = sectionMatch[1]; - const isAgentTop = /^agents\.[\w-]+$/.test(name); - const isFirstProvider = - /^agents\.[\w-]+\.providers$/.test(name) && !providersSeen; - const isMemory = name === "memory"; - if (isAgentTop) mode = "agent"; - else if (isFirstProvider) { - mode = "provider"; - providersSeen = true; - } else if (isMemory) mode = "memory"; - else mode = "skip"; - if (mode !== "skip") out.push(line.trimEnd()); - continue; - } - if (mode === "skip") continue; - const kvMatch = /^\s*([A-Za-z_][\w-]*)\s*=/.exec(line); - if (!kvMatch) continue; - const key = kvMatch[1]; - const keep = - (mode === "agent" && TOML_AGENT_KEEP_KEYS.has(key)) || - (mode === "provider" && TOML_PROVIDER_KEEP_KEYS.has(key)) || - (mode === "memory" && TOML_MEMORY_KEEP_KEYS.has(key)); - if (keep) out.push(line.trimEnd()); + const start = lines.findIndex((l) => /^\s*import\b/.test(l)); + if (start < 0) return []; + let end = start; + for (let i = start; i < lines.length; i++) { + end = i; + if (/;\s*$/.test(lines[i])) break; } - return collapseBlanks(out).join("\n"); + return lines.slice(start, end + 1); } -/** Parse a full lobu.toml and pull the first agent name + description fields. */ -type TomlExampleMeta = { label: string | null; description: string | null }; - -function readExampleMeta(rawToml: string, slug: string): TomlExampleMeta { - const lines = rawToml.split("\n"); - type Mode = "none" | "agent" | "memory"; - let mode: Mode = "none"; - let agentName: string | null = null; - let agentDescription: string | null = null; - let memoryDescription: string | null = null; - for (const line of lines) { - const sectionMatch = /^\s*\[\[?([\w.-]+)\]\]?\s*$/.exec(line); - if (sectionMatch) { - const name = sectionMatch[1]; - if (/^agents\.[\w-]+$/.test(name) && mode === "none") mode = "agent"; - else if (name === "memory") mode = "memory"; - else if (mode !== "none") mode = "none"; +/** + * Slice the first `defineX(` call out of a config file by brace-balancing from + * the opening `(` to the matching `)` (string-literal aware). The returned + * lines include the leading `const name = ` (or `export default `) and the + * trailing `);`. Returns an empty array if the call is not present. + */ +function sliceDefineCall(raw: string, fnName: string): string[] { + const idx = raw.indexOf(`${fnName}(`); + if (idx < 0) return []; + // Walk back to the start of the statement (the `const`/`export` line start). + let stmtStart = raw.lastIndexOf("\n", idx); + stmtStart = stmtStart < 0 ? 0 : stmtStart + 1; + + // Brace-balance from the opening `(` of the call. + let i = raw.indexOf("(", idx); + let depth = 0; + let str: '"' | "'" | "`" | null = null; + for (; i < raw.length; i++) { + const ch = raw[i]; + if (str) { + if (ch === "\\") { + i++; + continue; + } + if (ch === str) str = null; + continue; + } + if (ch === '"' || ch === "'" || ch === "`") { + str = ch; continue; } - const kv = /^\s*([A-Za-z_][\w-]*)\s*=\s*"([^"]*)"\s*$/.exec(line); - if (!kv) continue; - const [, key, value] = kv; - if (mode === "agent" && key === "name" && !agentName) agentName = value; - if (mode === "agent" && key === "description" && !agentDescription) - agentDescription = value; - if (mode === "memory" && key === "description" && !memoryDescription) - memoryDescription = value; + if (ch === "(") depth++; + else if (ch === ")") { + depth--; + if (depth === 0) break; + } } - const label = agentName ?? slug.charAt(0).toUpperCase() + slug.slice(1); - const description = memoryDescription ?? agentDescription ?? null; - return { label, description }; + // Include a trailing `;` if present. + let end = i + 1; + if (raw[end] === ";") end++; + return raw.slice(stmtStart, end).split("\n"); } /* -------------------------------------------------------------------------- */ -/* YAML helpers */ +/* Example metadata (label + description) via regex over config text */ /* -------------------------------------------------------------------------- */ -function extractYamlListItems( - raw: string, - topKey: string, - itemCount: number -): string[] { - const lines = raw.split("\n"); - let inSection = false; - let header: string | null = null; - const items: string[][] = []; - let current: string[] | null = null; - let baseIndent = -1; - - for (const line of lines) { - if (/^[A-Za-z_][\w-]*:/.test(line)) { - const key = line.split(":")[0]; - if (key === topKey) { - inSection = true; - header = line; - continue; - } - if (inSection) break; - } - if (!inSection) continue; - const dashMatch = /^(\s*)-\s/.exec(line); - if (dashMatch) { - if (baseIndent < 0) baseIndent = dashMatch[1].length; - if (dashMatch[1].length === baseIndent) { - if (current) items.push(current); - current = [line]; - continue; - } - } - if (current) { - const indent = line.match(/^\s*/)?.[0].length ?? 0; - if (line.trim() === "" || indent > baseIndent) current.push(line); - else break; - } +type ConfigMeta = { label: string; description: string | null }; + +/** Pull a `key: "..."` string value from `defineConfig({...})`, tolerating the + * value sitting on the line after the key (Biome wraps long strings). */ +function configStringField(raw: string, key: string): string | null { + const re = new RegExp(`\\b${key}:\\s*\\n?\\s*("(?:[^"\\\\]|\\\\.)*")`); + const m = re.exec(raw); + if (!m) return null; + try { + return JSON.parse(m[1]); + } catch { + return m[1].slice(1, -1); } - if (current) items.push(current); - if (!header) return []; - return [header, ...items.slice(0, itemCount).flat()]; } -/* -------------------------------------------------------------------------- */ -/* Connector definition extraction */ -/* -------------------------------------------------------------------------- */ +function readConfigMeta(raw: string, slug: string): ConfigMeta { + const orgName = configStringField(raw, "orgName"); + const orgDescription = configStringField(raw, "orgDescription"); + const fallbackLabel = slug + .split("-") + .map((p) => p.charAt(0).toUpperCase() + p.slice(1)) + .join(" "); + return { + label: orgName ?? fallbackLabel, + description: orgDescription, + }; +} /* -------------------------------------------------------------------------- */ -/* Memory (entity) compression */ +/* Helpers */ /* -------------------------------------------------------------------------- */ -function compressEntities(yamlLines: string[]): string[] { - if (yamlLines.length === 0) return []; - const out: string[] = []; - let i = 0; - if (/^entities:/.test(yamlLines[0])) { - out.push("entities:"); - i++; - } - while (i < yamlLines.length && yamlLines[i].trim() === "") i++; - if (i >= yamlLines.length) return out; - - const firstLine = yamlLines[i]; - const dashMatch = /^(\s*)-\s/.exec(firstLine); - if (!dashMatch) return out; - const baseIndent = dashMatch[1].length; - const childIndent = baseIndent + 2; - const pad = " ".repeat(baseIndent); - const padChild = " ".repeat(childIndent); - - let slug = ""; - let name = ""; - const props: Array<{ key: string; type: string }> = []; - - let cursor = i; - const slugInline = /^\s*-\s*slug:\s*(.+)$/.exec(firstLine); - if (slugInline) slug = slugInline[1].trim(); - cursor++; - - let inProperties = false; - let currentPropName: string | null = null; - let currentPropType: string | null = null; - while (cursor < yamlLines.length) { - const ln = yamlLines[cursor]; - if (ln.trim() === "") { - cursor++; - continue; - } - const ind = ln.length - ln.trimStart().length; - if (ind <= baseIndent) break; - const trimmed = ln.trimStart(); - - if (ind === childIndent) { - if (trimmed.startsWith("slug:")) slug = trimmed.slice(5).trim(); - else if (trimmed.startsWith("name:")) name = trimmed.slice(5).trim(); - inProperties = false; - currentPropName = null; - currentPropType = null; - cursor++; - continue; - } - if (trimmed === "properties:" && ind === childIndent + 2) { - inProperties = true; - currentPropName = null; - currentPropType = null; - cursor++; - continue; - } - if (inProperties && ind === childIndent + 4) { - const m = /^([A-Za-z_][\w-]*)\s*:/.exec(trimmed); - if (m) { - if (currentPropName && currentPropType) - props.push({ key: currentPropName, type: currentPropType }); - currentPropName = m[1]; - currentPropType = "string"; - } - } else if (inProperties && currentPropName && trimmed.startsWith("type:")) { - currentPropType = trimmed.slice(5).trim(); - } - cursor++; - } - if (currentPropName && currentPropType) - props.push({ key: currentPropName, type: currentPropType }); - - out.push(`${pad}- slug: ${slug || "entity"}`); - if (name) out.push(`${padChild}name: ${name}`); - out.push(`${padChild}metadata_schema:`); - out.push(`${padChild} type: object`); - out.push(`${padChild} properties:`); - const shown = props.slice(0, 3); - for (const p of shown) - out.push(`${padChild} ${p.key}: { type: ${p.type} }`); - if (props.length > shown.length) - out.push(`${padChild} # ${props.length - shown.length} more…`); - return out; +function configSnippet( + slug: string, + transform: (raw: string) => string +): Snippet { + const abs = pinnedFile(slug, CONFIG_FILE); + const raw = readFileSync(abs, "utf-8"); + return { + code: transform(raw).replace(/\s+$/, ""), + path: CONFIG_FILE, + githubUrl: githubFileUrl(slug, CONFIG_FILE), + language: "typescript", + }; } -/* -------------------------------------------------------------------------- */ -/* Watcher compression */ -/* -------------------------------------------------------------------------- */ +function fileSnippet( + slug: string, + relativePath: string, + language: Language, + transform?: (raw: string) => string +): Snippet { + const abs = pinnedFile(slug, relativePath); + const raw = readFileSync(abs, "utf-8"); + const code = (transform ? transform(raw) : raw).replace(/\s+$/, ""); + return { + code, + path: relativePath, + githubUrl: githubFileUrl(slug, relativePath), + language, + }; +} -const WATCHER_KEEP_TOP_KEYS = new Set(["slug", "agent", "on", "schedule"]); +/** The imports + the first `defineAgent({...})` block, the representative + * agent slice for the landing "Agents" section. */ +function agentConfigSlice(raw: string): string { + const imports = sliceImportBlock(raw); + const agent = sliceDefineCall(raw, "defineAgent"); + return [...imports, "", ...agent].join("\n"); +} -function compressWatcher(yamlLines: string[]): string[] { - if (yamlLines.length === 0) return []; - const out: string[] = []; - if (/^watchers:/.test(yamlLines[0])) out.push("watchers:"); - let i = 1; - while (i < yamlLines.length && yamlLines[i].trim() === "") i++; - if (i >= yamlLines.length) return out; - - const firstLine = yamlLines[i]; - const dashMatch = /^(\s*)-\s/.exec(firstLine); - if (!dashMatch) return out; - const baseIndent = dashMatch[1].length; - const childIndent = baseIndent + 2; - const pad = " ".repeat(baseIndent); - const padChild = " ".repeat(childIndent); - - const fields: Record = {}; - let prompt = ""; - let extractionRequired: string[] = []; - - const slugInline = /^\s*-\s*slug:\s*(.+)$/.exec(firstLine); - if (slugInline) fields.slug = slugInline[1].trim(); - - let cursor = i + 1; - while (cursor < yamlLines.length) { - const ln = yamlLines[cursor]; - if (ln.trim() === "") { - cursor++; - continue; - } - const ind = ln.length - ln.trimStart().length; - if (ind <= baseIndent) break; - const trimmed = ln.trimStart(); - - if (ind === childIndent) { - const kv = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(trimmed); - if (!kv) { - cursor++; - continue; - } - const [, key, value] = kv; - if (key === "prompt") { - if ( - value === "|" || - value === ">" || - value === "" || - value === "|-" || - value === ">-" - ) { - let k = cursor + 1; - while (k < yamlLines.length) { - const sub = yamlLines[k]; - if (sub.trim() === "") { - k++; - continue; - } - const subInd = sub.length - sub.trimStart().length; - if (subInd <= childIndent) break; - prompt = sub.trimStart(); - break; - } - while (k < yamlLines.length) { - const sub = yamlLines[k]; - if (sub.trim() === "") { - k++; - continue; - } - const subInd = sub.length - sub.trimStart().length; - if (subInd <= childIndent) break; - k++; - } - cursor = k; - continue; - } - prompt = value; - cursor++; - continue; - } - if (key === "extraction_schema") { - const schemaInd = childIndent + 2; - let k = cursor + 1; - let captured = false; - while (k < yamlLines.length) { - const sub = yamlLines[k]; - if (sub.trim() === "") { - k++; - continue; - } - const subInd = sub.length - sub.trimStart().length; - if (subInd <= childIndent) break; - if ( - !captured && - subInd === schemaInd && - sub.trimStart().startsWith("required:") - ) { - const sct = sub.trimStart(); - const inline = sct.slice("required:".length).trim(); - if (inline.startsWith("[") && inline.endsWith("]")) { - extractionRequired = inline - .slice(1, -1) - .split(",") - .map((s) => s.trim()) - .filter(Boolean); - captured = true; - k++; - continue; - } - k++; - while (k < yamlLines.length) { - const sub2 = yamlLines[k]; - if (sub2.trim() === "") { - k++; - continue; - } - const sub2Ind = sub2.length - sub2.trimStart().length; - const sub2Trim = sub2.trimStart(); - if (sub2Ind === schemaInd + 2 && sub2Trim.startsWith("- ")) { - extractionRequired.push(sub2Trim.slice(2).trim()); - k++; - continue; - } - break; - } - captured = true; - continue; - } - k++; - } - cursor = k; - continue; - } - if (WATCHER_KEEP_TOP_KEYS.has(key)) fields[key] = value; - } - cursor++; - } +function entitySlice(raw: string): string { + return sliceDefineCall(raw, "defineEntityType").join("\n"); +} - out.push(`${pad}- slug: ${fields.slug ?? "watcher"}`); - if (fields.agent) out.push(`${padChild}agent: ${fields.agent}`); - if (fields.on) out.push(`${padChild}on: ${fields.on}`); - if (fields.schedule) out.push(`${padChild}schedule: ${fields.schedule}`); - if (prompt) { - const compact = prompt.replace(/^["'`]?|["'`]?$/g, "").replace(/\s+/g, " "); - out.push(`${padChild}prompt: "${compact}"`); - } - out.push(`${padChild}extraction_schema:`); - out.push(`${padChild} type: object`); - if (extractionRequired.length > 0) { - out.push( - `${padChild} required: [${extractionRequired.slice(0, 5).join(", ")}${ - extractionRequired.length > 5 - ? `, …${extractionRequired.length - 5}` - : "" - }]` - ); - } - return out; +function watcherSlice(raw: string): string { + return sliceDefineCall(raw, "defineWatcher").join("\n"); } /* -------------------------------------------------------------------------- */ /* SKILL.md frontmatter extraction */ /* -------------------------------------------------------------------------- */ +function collapseBlanks(lines: string[]): string[] { + const out: string[] = []; + let blank = false; + for (const line of lines) { + const isBlank = line.trim() === ""; + if (isBlank && blank) continue; + out.push(line); + blank = isBlank; + } + while (out.length > 0 && out[0].trim() === "") out.shift(); + while (out.length > 0 && out[out.length - 1].trim() === "") out.pop(); + return out; +} + /** * Pull just the YAML frontmatter out of a SKILL.md (everything between the * leading `---` and the next `---`). Then slim it so the landing snippet @@ -595,49 +372,6 @@ function trimSkillMarkdown(raw: string): string { return collapseBlanks(out).join("\n"); } -/* -------------------------------------------------------------------------- */ -/* Helpers */ -/* -------------------------------------------------------------------------- */ - -function collapseBlanks(lines: string[]): string[] { - const out: string[] = []; - let blank = false; - for (const line of lines) { - const isBlank = line.trim() === ""; - if (isBlank && blank) continue; - out.push(line); - blank = isBlank; - } - while (out.length > 0 && out[0].trim() === "") out.shift(); - while (out.length > 0 && out[out.length - 1].trim() === "") out.pop(); - return out; -} - -function snippetFrom( - slug: string, - absPath: string, - relativePath: string, - language: Language, - transform?: (raw: string) => string -): Snippet { - const raw = readFileSync(absPath, "utf-8"); - const code = (transform ? transform(raw) : raw).replace(/\s+$/, ""); - return { - code, - path: relativePath, - githubUrl: githubFileUrl(slug, relativePath), - language, - }; -} - -function warnOverBudget(label: string, lines: number, budget: number): void { - if (lines > budget) { - console.warn( - `gen-landing-snippets: ${label} is ${lines} lines, landing budget is <= ${budget}.` - ); - } -} - /* -------------------------------------------------------------------------- */ /* Main */ /* -------------------------------------------------------------------------- */ @@ -654,159 +388,69 @@ function listExamples(): ExampleEntry[] { for (const entry of entries) { if (!entry.isDirectory()) continue; const slug = entry.name; - const tomlPath = resolve(examplesDir, slug, "lobu.toml"); - if (!existsSync(tomlPath)) continue; - const raw = readFileSync(tomlPath, "utf-8"); - const { label, description } = readExampleMeta(raw, slug); - out.push({ - slug, - label: label ?? slug, - description, - githubUrl: githubTreeUrl(slug), - }); + const configPath = resolve(examplesDir, slug, CONFIG_FILE); + if (!existsSync(configPath)) continue; + const raw = readFileSync(configPath, "utf-8"); + const { label, description } = readConfigMeta(raw, slug); + out.push({ slug, label, description, githubUrl: githubTreeUrl(slug) }); } out.sort((a, b) => a.slug.localeCompare(b.slug)); return out; } -function findConnectorFile(slug: string): { abs: string; rel: string } { +function findConnectorFile(slug: string): { rel: string } { const connectorsDir = resolve(examplesDir, slug, "connectors"); const file = readdirSync(connectorsDir).find((f) => f.endsWith(".connector.ts") ); if (!file) throw new Error(`No *.connector.ts in ${connectorsDir}`); - return { - abs: resolve(connectorsDir, file), - rel: `connectors/${file}`, - }; + return { rel: `connectors/${file}` }; } function buildUseCases(): Record { const out: Record = {}; for (const slug of USE_CASE_SLUGS) { - const { abs, rel } = findConnectorFile(slug); // Show the full connector file (imports + class + definition + sync), like - // the pinned homepage connector. These files are ~32-39 lines, within the - // connector budget, and read as complete TypeScript rather than a fragment. - const connector = snippetFrom(slug, abs, rel, "typescript"); - - const schemaRel = "models/schema.yaml"; - const memorySchema = snippetFrom( - slug, - pinnedFile(slug, schemaRel), - schemaRel, - "yaml", - (raw) => - collapseBlanks( - compressEntities(extractYamlListItems(raw, "entities", 1)) - ).join("\n") - ); - - const watcher = snippetFrom( + // the pinned homepage connector. These read as complete TypeScript. + const connector = fileSnippet( slug, - pinnedFile(slug, schemaRel), - schemaRel, - "yaml", - (raw) => - collapseBlanks( - compressWatcher(extractYamlListItems(raw, "watchers", 1)) - ).join("\n") + findConnectorFile(slug).rel, + "typescript" ); - + const memorySchema = configSnippet(slug, entitySlice); + const watcher = configSnippet(slug, watcherSlice); out[slug] = { connector, memorySchema, watcher }; } return out; } function build(): LandingSnippets { - const connector = snippetFrom( + const connector = fileSnippet( PINNED.connector.slug, - pinnedFile(PINNED.connector.slug, PINNED.connector.path), PINNED.connector.path, "typescript" ); - warnOverBudget( - `${PINNED.connector.slug}/${PINNED.connector.path}`, - connector.code.split("\n").length, - BUDGETS.connector - ); - - const memorySchema = snippetFrom( - PINNED.memorySchema.slug, - pinnedFile(PINNED.memorySchema.slug, PINNED.memorySchema.path), - PINNED.memorySchema.path, - "yaml", - (raw) => - collapseBlanks( - compressEntities(extractYamlListItems(raw, "entities", 1)) - ).join("\n") - ); - warnOverBudget( - `${PINNED.memorySchema.slug}/${PINNED.memorySchema.path} (entities)`, - memorySchema.code.split("\n").length, - BUDGETS.memorySchema - ); - - const watcher = snippetFrom( - PINNED.watcher.slug, - pinnedFile(PINNED.watcher.slug, PINNED.watcher.path), - PINNED.watcher.path, - "yaml", - (raw) => - collapseBlanks( - compressWatcher(extractYamlListItems(raw, "watchers", 1)) - ).join("\n") - ); - warnOverBudget( - `${PINNED.watcher.slug}/${PINNED.watcher.path} (watchers)`, - watcher.code.split("\n").length, - BUDGETS.watcher - ); - - const reaction = snippetFrom( + const memorySchema = configSnippet(PINNED.memorySchema.slug, entitySlice); + const watcher = configSnippet(PINNED.watcher.slug, watcherSlice); + const reaction = fileSnippet( PINNED.reaction.slug, - pinnedFile(PINNED.reaction.slug, PINNED.reaction.path), PINNED.reaction.path, "typescript" ); - warnOverBudget( - `${PINNED.reaction.slug}/${PINNED.reaction.path}`, - reaction.code.split("\n").length, - BUDGETS.reaction - ); - - const agentToml = snippetFrom( - PINNED.agentToml.slug, - pinnedFile(PINNED.agentToml.slug, PINNED.agentToml.path), - PINNED.agentToml.path, - "toml", - trimAgentToml - ); - warnOverBudget( - `${PINNED.agentToml.slug}/${PINNED.agentToml.path}`, - agentToml.code.split("\n").length, - BUDGETS.agentToml - ); - - const skill = snippetFrom( + const agentConfig = configSnippet(PINNED.agentConfig.slug, agentConfigSlice); + const skill = fileSnippet( PINNED.skill.slug, - pinnedFile(PINNED.skill.slug, PINNED.skill.path), PINNED.skill.path, "markdown", trimSkillMarkdown ); - warnOverBudget( - `${PINNED.skill.slug}/${PINNED.skill.path}`, - skill.code.split("\n").length, - BUDGETS.skill - ); return { connector, memorySchema, watcher, reaction, - agentToml, + agentConfig, skill, examples: listExamples(), useCases: buildUseCases(), diff --git a/packages/landing/src/components/LandingPage.tsx b/packages/landing/src/components/LandingPage.tsx index 09442b1b2..d6e34cfde 100644 --- a/packages/landing/src/components/LandingPage.tsx +++ b/packages/landing/src/components/LandingPage.tsx @@ -30,7 +30,7 @@ type LandingSnippets = { memorySchema: CodeSnippet; watcher: CodeSnippet; reaction: CodeSnippet; - agentToml: CodeSnippet; + agentConfig: CodeSnippet; skill: CodeSnippet; examples: ExampleEntry[]; useCases: Record; @@ -47,7 +47,7 @@ const SETUP_PROMPT = `I want to build a Lobu agent. 2. Walk me through the skill's onboarding interview (it asks what the agent should do, who uses it, where data comes from, where I'll talk to it, what should run on a schedule). Pause at every real decision and ask me, don't fake credentials, don't guess. -3. Scaffold the project per my answers (lobu.toml, models/schema.yaml, connectors/, models/reactions/), boot it locally, send a test message via the chosen channel, and show me the memory event that was written. +3. Scaffold the project per my answers (lobu.config.ts, connectors/, models/reactions/), boot it locally, send a test message via the chosen channel, and show me the memory event that was written. Lobu is an open-source event-sourced backend for AI agents: connectors emit events, memory keeps the structured record, agents react in real time and dream on cron. Repo: https://github.com/lobu-ai/lobu. Docs: https://lobu.ai/docs/`; @@ -582,9 +582,9 @@ function MemorySection({ class="mt-4 max-w-[28rem] text-[16px] leading-[1.6]" style={{ color: "var(--color-page-text-muted)" }} > - Declare entity types in YAML. Lobu stores them as append-only - events with full audit. Multi-tenant by default, agents see only - their scope. + Declare entity types in TypeScript. Lobu stores them as + append-only events with full audit. Multi-tenant by default, + agents see only their scope.

Agent-assisted modeling: paste the setup prompt into Claude Code or Cursor; it interviews you and drafts{" "} - schema.yaml. + lobu.config.ts. , <> Per-user / per-org isolation: your agents only see the @@ -796,8 +796,8 @@ function AgentsSection() { style={{ color: "var(--color-page-text-muted)" }} > Declare your agent in{" "} - lobu.toml: provider, - model, skills. One config, every surface below. + lobu.config.ts: + provider, model, skills. One config, every surface below.

, HTTP, MCP. Same{" "} - lobu.toml. + lobu.config.ts. , <> BYO model: Anthropic, OpenAI, Z.ai, OpenRouter, your @@ -861,8 +861,8 @@ function AgentsSection() { } code={
- - + +
} /> @@ -997,8 +997,7 @@ function RunAnywhereSection() { class="mx-auto mt-3 max-w-[34rem] text-[15px]" style={{ color: "var(--color-page-text-muted)" }} > - Same lobu.toml +{" "} - models/ +{" "} + Same lobu.config.ts +{" "} connectors/ +{" "} agents/. One command to boot embedded; Docker + Helm for self-hosting; Lobu Cloud when you diff --git a/packages/landing/src/generated/landing-snippets.json b/packages/landing/src/generated/landing-snippets.json index 9be81efd4..b0a19918a 100644 --- a/packages/landing/src/generated/landing-snippets.json +++ b/packages/landing/src/generated/landing-snippets.json @@ -6,16 +6,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: organization\n name: Organization\n metadata_schema:\n type: object\n properties:\n company_name: { type: string }\n stage: { type: string }\n arr: { type: string }\n # 1 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/sales/models/schema.yaml", - "language": "yaml" + "code": "const organization = defineEntityType({\n key: \"organization\",\n name: \"Organization\",\n description:\n \"A customer account or prospect being tracked by the revenue team\",\n properties: {\n company_name: {\n type: \"string\",\n \"x-table-label\": \"Company\",\n \"x-table-column\": true,\n },\n stage: { type: \"string\", \"x-table-label\": \"Stage\", \"x-table-column\": true },\n arr: { type: \"string\", \"x-table-label\": \"ARR\", \"x-table-column\": true },\n renewal_date: {\n type: \"string\",\n \"x-table-label\": \"Renewal Date\",\n \"x-table-column\": true,\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/sales/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: board-action-tracker\n agent: leadership\n schedule: 0 8 * * *\n prompt: \"Track board action items: check task delivery status, blocker resolution progress, and approaching deadlines for the next board packet.\"\n extraction_schema:\n type: object\n required: [action_items, blocked_items, deadlines_approaching, completion_status]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/leadership/models/schema.yaml", - "language": "yaml" + "code": "const accountHealthMonitor = defineWatcher({\n agent: sales,\n slug: \"account-health-monitor\",\n name: \"Account health monitor\",\n schedule: \"0 */12 * * *\",\n notification: { priority: \"high\", channel: \"both\" },\n tags: [\"sales\", \"health\", \"renewals\"],\n minCooldownSeconds: 1800,\n reaction: \"./models/reactions/account-health-monitor.reaction.ts\",\n prompt:\n \"Poll CRM data for tracked accounts. Track expansion progress, risk level changes, and renewal timeline.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\n \"risk_level\",\n \"expansion_status\",\n \"renewal_blockers\",\n \"activity_delta\",\n ],\n properties: {\n risk_level: { type: \"string\" },\n expansion_status: { type: \"string\" },\n renewal_blockers: { type: \"array\", items: { type: \"string\" } },\n activity_delta: { type: \"string\" },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/sales/lobu.config.ts", + "language": "typescript" }, "reaction": { "code": "/**\n * Reaction for the `reconciliation-monitor` watcher.\n *\n * Persists variance events when unreconciled transactions or new anomalies\n * are detected during the daily reconciliation pass.\n */\nimport type { ReactionClient, ReactionContext } from \"@lobu/connector-sdk\";\n\ninterface ReconciliationData {\n unreconciled_count: number;\n new_variances: string[];\n approaching_deadlines: string[];\n payment_risks?: string[];\n}\n\nexport default async (\n ctx: ReactionContext,\n client: ReactionClient\n): Promise => {\n const data = ctx.extracted_data as ReconciliationData;\n\n const hasIssues =\n data.unreconciled_count > 0 ||\n (data.new_variances?.length ?? 0) > 0 ||\n (data.approaching_deadlines?.length ?? 0) > 0;\n\n if (!hasIssues) return;\n\n const parts: string[] = [];\n if (data.unreconciled_count > 0) {\n parts.push(`${data.unreconciled_count} unreconciled transactions`);\n }\n if (data.new_variances?.length) {\n parts.push(`Variances: ${data.new_variances.join(\"; \")}`);\n }\n if (data.approaching_deadlines?.length) {\n parts.push(`Deadlines: ${data.approaching_deadlines.join(\"; \")}`);\n }\n\n await client.knowledge.save({\n entity_ids: ctx.entities.map((e) => e.id),\n content: parts.join(\"\\n\"),\n semantic_type: \"reconciliation_alert\",\n metadata: {\n window_id: ctx.window.id,\n unreconciled_count: data.unreconciled_count,\n variance_count: data.new_variances?.length ?? 0,\n },\n });\n};", @@ -23,11 +23,11 @@ "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/finance/models/reactions/reconciliation-monitor.reaction.ts", "language": "typescript" }, - "agentToml": { - "code": "[agents.crm]\nname = \"crm\"\n[[agents.crm.providers]]\nid = \"z-ai\"\nmodel = \"z-ai/glm-4.7\"\nkey = \"$Z_AI_API_KEY\"\n[memory]\nenabled = true\norg = \"lobu-crm\"\nmodels = \"./models\"\ndata = \"./data\"", - "path": "lobu.toml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/lobu-crm/lobu.toml", - "language": "toml" + "agentConfig": { + "code": "import {\n defineAgent,\n defineConfig,\n defineEntityType,\n defineRelationshipType,\n defineWatcher,\n secret,\n} from \"@lobu/sdk\";\n\nconst sales = defineAgent({\n id: \"sales\",\n name: \"sales\",\n description:\n \"Help revenue teams track account health, rollout progress, and renewal signals\",\n dir: \"./agents/sales\",\n providers: [\n {\n id: \"anthropic\",\n model: \"claude/sonnet-4-5\",\n key: secret(\"ANTHROPIC_API_KEY\"),\n },\n ],\n network: {\n allowed: [\n \"github.com\",\n \".github.com\",\n \".githubusercontent.com\",\n \"registry.npmjs.org\",\n \".npmjs.org\",\n ],\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/sales/lobu.config.ts", + "language": "typescript" }, "skill": { "code": "---\nname: deliveroo-order\ndescription: Read a restaurant's Deliveroo menu and assemble a group-order basket for the office lunch. Use in step 2 of the lunch run, after orders are collected. Reading menus and building a basket is allowed; completing checkout or touching payment is NOT.\nnixPackages:\n - chromium\nnetwork:\n allow:\n - registry.npmjs.org\n - .npmjs.org\n judge:\n - domain: deliveroo.co.uk\n judge: deliveroo\n - domain: .deliveroo.co.uk\n judge: deliveroo\njudges:\n deliveroo: >\n Allow reads and basket changes. Deny checkout, payment,\n saved cards, address, or profile changes. Fail closed if unclear.\n---", @@ -38,73 +38,73 @@ "examples": [ { "slug": "agent-community", - "label": "agent-community", + "label": "Agent Community", "description": "Discover aligned members, explain why they should meet, and draft warm introductions", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/agent-community" }, { "slug": "atlas", - "label": "atlas-curator", + "label": "Atlas", "description": "Public reference catalog — places, taxonomies, institutions", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/atlas" }, { "slug": "delivery", - "label": "delivery", + "label": "Delivery", "description": "Help delivery teams keep milestones, blockers, owners, and artifacts aligned", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/delivery" }, { "slug": "ecommerce", - "label": "ecommerce-ops", + "label": "Ecommerce", "description": "Manage subscriptions, process order changes, and resolve customer requests", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/ecommerce" }, { "slug": "finance", - "label": "finance", + "label": "Finance", "description": "Help finance teams reconcile data, explain variance, and prepare reporting runs", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/finance" }, { "slug": "leadership", - "label": "leadership", + "label": "Leadership", "description": "Turn memos, decisions, and board materials into reusable operating context", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/leadership" }, { "slug": "legal", - "label": "legal-review", + "label": "Legal", "description": "Review contracts, summarize risk, and surface missing protections", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/legal" }, { "slug": "lobu-crm", - "label": "crm", + "label": "Lobu CRM", "description": "Funnel CRM for Lobu — leads, pilots, conversations, launch signals", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/lobu-crm" }, { "slug": "market", - "label": "vc-tracking", + "label": "Market", "description": "Track companies, founders, and investment opportunities for venture firms", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/market" }, { "slug": "office-bot", - "label": "food-ordering", + "label": "Lobu Team", "description": "Office-ops agents — first up: the weekday lunch order", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/office-bot" }, { "slug": "personal-finance", - "label": "personal-finance", + "label": "Personal Finance", "description": "UK Self Assessment helper — captures financial activity across the tax year and assembles SA100 + supplementary pages.", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/personal-finance" }, { "slug": "sales", - "label": "sales", + "label": "Sales", "description": "Help revenue teams track account health, rollout progress, and renewal signals", "githubUrl": "https://github.com/lobu-ai/lobu/tree/main/examples/sales" } @@ -118,16 +118,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: clause\n name: Clause\n metadata_schema:\n type: object\n properties:\n clause_type: { type: string }\n section: { type: string }\n risk_level: { type: string }\n # 1 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/legal/models/schema.yaml", - "language": "yaml" + "code": "const clause = defineEntityType({\n key: \"clause\",\n name: \"Clause\",\n description:\n \"A specific provision or section within a contract that defines terms or obligations\",\n properties: {\n clause_type: {\n type: \"string\",\n \"x-table-label\": \"Type\",\n \"x-table-column\": true,\n },\n section: {\n type: \"string\",\n \"x-table-label\": \"Section\",\n \"x-table-column\": true,\n },\n risk_level: {\n type: \"string\",\n \"x-table-label\": \"Risk Level\",\n \"x-table-column\": true,\n },\n language_summary: {\n type: \"string\",\n \"x-table-label\": \"Summary\",\n \"x-table-column\": true,\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/legal/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: contract-review-tracker\n agent: legal-review\n schedule: 0 8 * * 1-5\n prompt: \"Review active contracts for approaching deadlines, unsigned agreements, and unresolved risk items. Flag any clauses that still need counsel approval.\"\n extraction_schema:\n type: object\n required: [pending_contracts, unresolved_risks, approaching_deadlines]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/legal/models/schema.yaml", - "language": "yaml" + "code": "const contractReviewTracker = defineWatcher({\n agent: legalReview,\n slug: \"contract-review-tracker\",\n name: \"Contract review tracker\",\n schedule: \"0 8 * * 1-5\",\n notification: { priority: \"high\" },\n tags: [\"legal\", \"contract\", \"daily\"],\n minCooldownSeconds: 1800,\n reactionsGuidance:\n \"For any contract with `status: needs_counsel`, route an entity-scoped event\\nto the assigned reviewer. For contracts >90 days unsigned, escalate to the\\ncounterparty owner; never auto-resolve risk items.\\n\",\n prompt:\n \"Review active contracts for approaching deadlines, unsigned agreements, and unresolved risk items. Flag any clauses that still need counsel approval.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\n \"pending_contracts\",\n \"unresolved_risks\",\n \"approaching_deadlines\",\n ],\n properties: {\n pending_contracts: { type: \"array\", items: { type: \"string\" } },\n unresolved_risks: { type: \"array\", items: { type: \"string\" } },\n approaching_deadlines: { type: \"array\", items: { type: \"string\" } },\n flagged_clauses: { type: \"array\", items: { type: \"string\" } },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/legal/lobu.config.ts", + "language": "typescript" } }, "finance": { @@ -138,16 +138,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: account\n name: Account\n metadata_schema:\n type: object\n properties:\n account_name: { type: string }\n account_type: { type: string }\n balance: { type: string }\n # 1 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/finance/models/schema.yaml", - "language": "yaml" + "code": "const account = defineEntityType({\n key: \"account\",\n name: \"Account\",\n description:\n \"A financial account that holds balances, transactions, and reconciliation state\",\n properties: {\n account_name: {\n type: \"string\",\n \"x-table-label\": \"Account\",\n \"x-table-column\": true,\n },\n account_type: {\n type: \"string\",\n \"x-table-label\": \"Type\",\n \"x-table-column\": true,\n },\n balance: {\n type: \"string\",\n \"x-table-label\": \"Balance\",\n \"x-table-column\": true,\n },\n reconciliation_status: {\n type: \"string\",\n \"x-table-label\": \"Reconciliation\",\n \"x-table-column\": true,\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/finance/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: reconciliation-monitor\n agent: finance\n schedule: 0 6 * * 1-5\n prompt: \"Check accounts for unreconciled transactions, new variances, and approaching reporting deadlines. Lead with exceptions that need review.\"\n extraction_schema:\n type: object\n required: [unreconciled_count, new_variances, approaching_deadlines]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/finance/models/schema.yaml", - "language": "yaml" + "code": "const reconciliationMonitor = defineWatcher({\n agent: finance,\n slug: \"reconciliation-monitor\",\n name: \"Reconciliation monitor\",\n schedule: \"0 6 * * 1-5\",\n notification: { priority: \"high\", channel: \"both\" },\n tags: [\"finance\", \"reconciliation\", \"daily\"],\n minCooldownSeconds: 3600,\n reaction: \"./models/reactions/reconciliation-monitor.reaction.ts\",\n prompt:\n \"Check accounts for unreconciled transactions, new variances, and approaching reporting deadlines. Lead with exceptions that need review.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\"unreconciled_count\", \"new_variances\", \"approaching_deadlines\"],\n properties: {\n unreconciled_count: { type: \"integer\" },\n new_variances: { type: \"array\", items: { type: \"string\" } },\n approaching_deadlines: { type: \"array\", items: { type: \"string\" } },\n payment_risks: { type: \"array\", items: { type: \"string\" } },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/finance/lobu.config.ts", + "language": "typescript" } }, "sales": { @@ -158,16 +158,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: organization\n name: Organization\n metadata_schema:\n type: object\n properties:\n company_name: { type: string }\n stage: { type: string }\n arr: { type: string }\n # 1 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/sales/models/schema.yaml", - "language": "yaml" + "code": "const organization = defineEntityType({\n key: \"organization\",\n name: \"Organization\",\n description:\n \"A customer account or prospect being tracked by the revenue team\",\n properties: {\n company_name: {\n type: \"string\",\n \"x-table-label\": \"Company\",\n \"x-table-column\": true,\n },\n stage: { type: \"string\", \"x-table-label\": \"Stage\", \"x-table-column\": true },\n arr: { type: \"string\", \"x-table-label\": \"ARR\", \"x-table-column\": true },\n renewal_date: {\n type: \"string\",\n \"x-table-label\": \"Renewal Date\",\n \"x-table-column\": true,\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/sales/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: account-health-monitor\n agent: sales\n schedule: 0 */12 * * *\n prompt: \"Poll CRM data for tracked accounts. Track expansion progress, risk level changes, and renewal timeline.\"\n extraction_schema:\n type: object\n required: [risk_level, expansion_status, renewal_blockers, activity_delta]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/sales/models/schema.yaml", - "language": "yaml" + "code": "const accountHealthMonitor = defineWatcher({\n agent: sales,\n slug: \"account-health-monitor\",\n name: \"Account health monitor\",\n schedule: \"0 */12 * * *\",\n notification: { priority: \"high\", channel: \"both\" },\n tags: [\"sales\", \"health\", \"renewals\"],\n minCooldownSeconds: 1800,\n reaction: \"./models/reactions/account-health-monitor.reaction.ts\",\n prompt:\n \"Poll CRM data for tracked accounts. Track expansion progress, risk level changes, and renewal timeline.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\n \"risk_level\",\n \"expansion_status\",\n \"renewal_blockers\",\n \"activity_delta\",\n ],\n properties: {\n risk_level: { type: \"string\" },\n expansion_status: { type: \"string\" },\n renewal_blockers: { type: \"array\", items: { type: \"string\" } },\n activity_delta: { type: \"string\" },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/sales/lobu.config.ts", + "language": "typescript" } }, "delivery": { @@ -178,16 +178,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: blocker\n name: Blocker\n metadata_schema:\n type: object\n properties:\n blocker_description: { type: string }\n owned_by: { type: string }\n impact: { type: string }\n # 1 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/delivery/models/schema.yaml", - "language": "yaml" + "code": "const blocker = defineEntityType({\n key: \"blocker\",\n name: \"Blocker\",\n description: \"A dependency or issue that is blocking project progress\",\n properties: {\n blocker_description: {\n type: \"string\",\n \"x-table-label\": \"Blocker\",\n \"x-table-column\": true,\n },\n owned_by: {\n type: \"string\",\n \"x-table-label\": \"Owner\",\n \"x-table-column\": true,\n },\n impact: {\n type: \"string\",\n \"x-table-label\": \"Impact\",\n \"x-table-column\": true,\n },\n status: {\n type: \"string\",\n \"x-table-label\": \"Status\",\n \"x-table-column\": true,\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/delivery/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: phoenix-rollout-tracker\n agent: delivery\n schedule: 0 9 * * 1\n prompt: \"Check project blockers, milestone progress, and generate the weekly risk summary for leadership.\"\n extraction_schema:\n type: object\n required: [blockers_resolved, milestone_state, new_risks, risk_summary]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/delivery/models/schema.yaml", - "language": "yaml" + "code": "const phoenixRolloutTracker = defineWatcher({\n agent: delivery,\n slug: \"phoenix-rollout-tracker\",\n name: \"Phoenix rollout tracker\",\n schedule: \"0 9 * * 1\",\n notification: { priority: \"high\", channel: \"both\" },\n tags: [\"delivery\", \"weekly\", \"rollout\"],\n minCooldownSeconds: 3600,\n prompt:\n \"Check project blockers, milestone progress, and generate the weekly risk summary for leadership.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\n \"blockers_resolved\",\n \"milestone_state\",\n \"new_risks\",\n \"risk_summary\",\n ],\n properties: {\n blockers_resolved: { type: \"array\", items: { type: \"string\" } },\n milestone_state: { type: \"string\" },\n new_risks: { type: \"array\", items: { type: \"string\" } },\n risk_summary: { type: \"string\" },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/delivery/lobu.config.ts", + "language": "typescript" } }, "market": { @@ -198,16 +198,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: company\n name: Company\n metadata_schema:\n type: object\n properties:\n market: { type: string }\n sector: { type: string }\n category: { type: string }\n # 17 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/market/models/schema.yaml", - "language": "yaml" + "code": "const company = defineEntityType({\n key: \"company\",\n name: \"Company\",\n description: \"Portfolio company or deal pipeline company\",\n properties: {\n market: {\n type: \"string\",\n \"x-table-column\": true,\n \"x-table-label\": \"Market\",\n },\n sector: {\n type: \"string\",\n enum: SECTOR_ENUM,\n \"x-table-column\": true,\n \"x-table-label\": \"Sector\",\n },\n category: {\n type: \"string\",\n enum: [\"portfolio\", \"recruiter\", \"prospect\"],\n \"x-table-column\": true,\n \"x-table-label\": \"Category\",\n },\n location: {\n type: \"string\",\n \"x-table-column\": true,\n \"x-table-label\": \"Location\",\n },\n domain: {\n type: \"string\",\n description:\n \"Normalized company domain used by identity-engine hosted_domain facts\",\n \"x-identity-namespace\": {\n namespace: \"hosted_domain\",\n normalize: \"lowercase\",\n },\n \"x-table-column\": true,\n \"x-table-label\": \"Domain\",\n },\n one_liner: { type: \"string\" },\n team_size: { type: \"integer\" },\n founding_year: { type: \"integer\" },\n funding_raised: { type: \"string\" },\n valuation: { type: \"string\" },\n revenue: { type: \"string\" },\n growth_rate: { type: \"string\" },\n traction_score: { type: \"number\" },\n thesis: { type: \"string\" },\n stage: {\n type: \"string\",\n enum: [\n \"idea\",\n \"pre-seed\",\n \"seed\",\n \"series-a\",\n \"series-b\",\n \"series-c\",\n \"growth\",\n \"public\",\n ],\n },\n linkedin_url: { type: \"string\", format: \"uri\" },\n logo_url: { type: \"string\", format: \"uri\", description: \"Brand logo URL\" },\n tagline: { type: \"string\", description: \"One-line brand tagline\" },\n brand_voice: {\n type: \"string\",\n description: \"Brand voice / tone-of-voice notes\",\n },\n social_handles: {\n type: \"object\",\n description:\n \"Brand social handles by platform (twitter, linkedin, github, …)\",\n properties: {\n twitter: { type: \"string\" },\n linkedin: { type: \"string\" },\n github: { type: \"string\" },\n youtube: { type: \"string\" },\n instagram: { type: \"string\" },\n tiktok: { type: \"string\" },\n },\n additionalProperties: { type: \"string\" },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/market/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: founder-activity-tracker\n agent: vc-tracking\n schedule: 0 10 * * *\n prompt: \"You are a venture capital analyst tracking the public activity of startup founders in your portfolio.\"\n extraction_schema:\n type: object\n required: [summary, founders, notable_signals]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/market/models/schema.yaml", - "language": "yaml" + "code": "const founderActivityTracker = defineWatcher({\n agent: vcTracking,\n slug: \"founder-activity-tracker\",\n name: \"Founder Activity Tracker\",\n schedule: \"0 10 * * *\",\n notification: { priority: \"normal\" },\n tags: [\"vc\", \"founders\", \"daily\"],\n minCooldownSeconds: 600,\n reaction: \"./models/reactions/founder-activity-tracker.reaction.ts\",\n prompt:\n \"You are a venture capital analyst tracking the public activity of startup founders in your portfolio.\\n\\n## Founders\\n{{#each entities}}\\n- {{name}} ({{entity_type}}, ID: {{id}})\\n{{/each}}\\n\\n## Recent Founder Activity\\n{{#if sources.founder_posts}}\\n{{sources.founder_posts}}\\n{{/if}}\\n\\n---\\n\\nProduce a structured founder activity report:\\n1. **Executive Summary**: 2-3 sentence overview of founder activity and signals.\\n2. **Per-Founder Analysis**: For each active founder, summarize their messaging themes, engagement level, and signals about company direction.\\n3. **Cross-Portfolio Patterns**: Themes multiple founders discuss.\\n4. **Notable Signals**: Flag potential announcements, strategic shifts, or concerns.\\n\\nBe specific and cite actual tweets/posts as evidence.\\n\",\n sources: {\n founder_posts:\n \"SELECT id, title, payload_text, author_name, source_url, occurred_at, score, origin_type, connector_key FROM events WHERE connector_key IN ('x') AND origin_type IN ('tweet', 'reply') ORDER BY occurred_at DESC LIMIT 300\\n\",\n },\n reactionsGuidance:\n \"When a founder signals hiring activity, fundraising, or pivots, flag for the investment team.\\nTrack founders going quiet as a potential concern.\\nAlert on any public statements about competitors or market conditions.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\"summary\", \"founders\", \"notable_signals\"],\n properties: {\n summary: { type: \"string\" },\n founders: {\n type: \"array\",\n items: {\n type: \"object\",\n required: [\"name\", \"company\", \"activity_level\", \"themes\"],\n properties: {\n name: { type: \"string\" },\n company: { type: \"string\" },\n activity_level: {\n type: \"string\",\n enum: [\"high\", \"medium\", \"low\", \"inactive\"],\n },\n themes: { type: \"array\", items: { type: \"string\" } },\n sentiment: {\n type: \"string\",\n enum: [\"bullish\", \"neutral\", \"cautious\", \"concerned\"],\n },\n signals: { type: \"array\", items: { type: \"string\" } },\n notable_posts: { type: \"array\", items: { type: \"string\" } },\n },\n },\n },\n cross_patterns: {\n type: \"array\",\n items: {\n type: \"object\",\n properties: {\n theme: { type: \"string\" },\n founders_involved: { type: \"array\", items: { type: \"string\" } },\n },\n },\n },\n notable_signals: {\n type: \"array\",\n items: {\n type: \"object\",\n required: [\"signal\", \"founder\", \"impact\"],\n properties: {\n signal: { type: \"string\" },\n founder: { type: \"string\" },\n impact: { type: \"string\", enum: [\"high\", \"medium\", \"low\"] },\n },\n },\n },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/market/lobu.config.ts", + "language": "typescript" } }, "agent-community": { @@ -218,16 +218,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: match\n name: Match\n metadata_schema:\n type: object\n properties:\n member_a: { type: string }\n member_b: { type: string }\n reason: { type: string }\n # 1 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/agent-community/models/schema.yaml", - "language": "yaml" + "code": "const match = defineEntityType({\n key: \"match\",\n name: \"Match\",\n description:\n \"A suggested introduction between two members with reasons and confidence\",\n properties: {\n member_a: {\n type: \"string\",\n \"x-table-label\": \"Member A\",\n \"x-table-column\": true,\n },\n member_b: {\n type: \"string\",\n \"x-table-label\": \"Member B\",\n \"x-table-column\": true,\n },\n reason: {\n type: \"string\",\n \"x-table-label\": \"Reason\",\n \"x-table-column\": true,\n },\n status: {\n type: \"string\",\n \"x-table-label\": \"Status\",\n \"x-table-column\": true,\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/agent-community/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: opportunity-matcher\n agent: agent-community\n schedule: 0 */12 * * *\n prompt: \"Monitor connected profiles, newsletters, websites, and member updates for new launches, posts, hiring signals, funding news, and project changes. Identify which members are likely to care, explain why, and queue approved intro or outreach drafts.\"\n extraction_schema:\n type: object\n required: [signals]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/agent-community/models/schema.yaml", - "language": "yaml" + "code": "const opportunityMatcher = defineWatcher({\n agent: agentCommunity,\n slug: \"opportunity-matcher\",\n name: \"Opportunity matcher\",\n schedule: \"0 */12 * * *\",\n notification: { priority: \"normal\" },\n tags: [\"community\", \"matching\"],\n minCooldownSeconds: 300,\n reaction: \"./models/reactions/opportunity-matcher.reaction.ts\",\n prompt:\n \"Monitor connected profiles, newsletters, websites, and member updates for new launches, posts, hiring signals, funding news, and project changes. Identify which members are likely to care, explain why, and queue approved intro or outreach drafts.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\"signals\"],\n properties: {\n signals: {\n type: \"array\",\n items: {\n type: \"object\",\n properties: {\n type: { type: \"string\" },\n source: { type: \"string\" },\n related_topics: { type: \"array\", items: { type: \"string\" } },\n interested_members: { type: \"array\", items: { type: \"string\" } },\n reason: { type: \"string\" },\n suggested_action: { type: \"string\" },\n },\n },\n },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/agent-community/lobu.config.ts", + "language": "typescript" } }, "ecommerce": { @@ -238,16 +238,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: customer\n name: Customer\n metadata_schema:\n type: object\n properties:\n full_name: { type: string }\n status: { type: string }\n plan: { type: string }\n # 1 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/ecommerce/models/schema.yaml", - "language": "yaml" + "code": "const customer = defineEntityType({\n key: \"customer\",\n name: \"Customer\",\n description:\n \"A customer with subscriptions, orders, and communication preferences\",\n properties: {\n full_name: {\n type: \"string\",\n \"x-table-label\": \"Name\",\n \"x-table-column\": true,\n },\n status: {\n type: \"string\",\n \"x-table-label\": \"Status\",\n \"x-table-column\": true,\n },\n plan: { type: \"string\", \"x-table-label\": \"Plan\", \"x-table-column\": true },\n communication_preference: {\n type: \"string\",\n \"x-table-label\": \"Preference\",\n \"x-table-column\": true,\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/ecommerce/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: customer-activity-tracker\n agent: ecommerce-ops\n schedule: 0 */6 * * *\n prompt: \"Monitor customers for new orders, subscription changes, delivery requests, and support interactions.\"\n extraction_schema:\n type: object\n required: [subscription_status, pending_changes, recent_orders, communication_preferences, open_requests]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/ecommerce/models/schema.yaml", - "language": "yaml" + "code": "const customerActivityTracker = defineWatcher({\n agent: ecommerceOps,\n slug: \"customer-activity-tracker\",\n name: \"Customer activity tracker\",\n schedule: \"0 */6 * * *\",\n notification: { priority: \"normal\" },\n tags: [\"ecommerce\", \"customer-ops\"],\n minCooldownSeconds: 300,\n prompt:\n \"Monitor customers for new orders, subscription changes, delivery requests, and support interactions.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\n \"subscription_status\",\n \"pending_changes\",\n \"recent_orders\",\n \"communication_preferences\",\n \"open_requests\",\n ],\n properties: {\n subscription_status: { type: \"string\" },\n pending_changes: { type: \"array\", items: { type: \"string\" } },\n recent_orders: { type: \"array\", items: { type: \"string\" } },\n communication_preferences: { type: \"string\" },\n open_requests: { type: \"array\", items: { type: \"string\" } },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/ecommerce/lobu.config.ts", + "language": "typescript" } }, "leadership": { @@ -258,16 +258,16 @@ "language": "typescript" }, "memorySchema": { - "code": "entities:\n - slug: decision\n name: Decision\n metadata_schema:\n type: object\n properties:\n subject: { type: string }\n status: { type: string }\n source_document: { type: string }\n # 1 more…", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/leadership/models/schema.yaml", - "language": "yaml" + "code": "const decision = defineEntityType({\n key: \"decision\",\n name: \"Decision\",\n description:\n \"A leadership decision extracted from a document with its approval status\",\n properties: {\n subject: {\n type: \"string\",\n \"x-table-label\": \"Subject\",\n \"x-table-column\": true,\n },\n status: {\n type: \"string\",\n \"x-table-label\": \"Status\",\n \"x-table-column\": true,\n },\n source_document: {\n type: \"string\",\n \"x-table-label\": \"Source\",\n \"x-table-column\": true,\n },\n decision_date: {\n type: \"string\",\n \"x-table-label\": \"Date\",\n \"x-table-column\": true,\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/leadership/lobu.config.ts", + "language": "typescript" }, "watcher": { - "code": "watchers:\n - slug: board-action-tracker\n agent: leadership\n schedule: 0 8 * * *\n prompt: \"Track board action items: check task delivery status, blocker resolution progress, and approaching deadlines for the next board packet.\"\n extraction_schema:\n type: object\n required: [action_items, blocked_items, deadlines_approaching, completion_status]", - "path": "models/schema.yaml", - "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/leadership/models/schema.yaml", - "language": "yaml" + "code": "const boardActionTracker = defineWatcher({\n agent: leadership,\n slug: \"board-action-tracker\",\n name: \"Board action tracker\",\n schedule: \"0 8 * * *\",\n notification: { priority: \"high\", channel: \"both\" },\n tags: [\"leadership\", \"daily\", \"board\"],\n agentKind: \"notifier\",\n prompt:\n \"Track board action items: check task delivery status, blocker resolution progress, and approaching deadlines for the next board packet.\\n\",\n extractionSchema: {\n type: \"object\",\n required: [\n \"action_items\",\n \"blocked_items\",\n \"deadlines_approaching\",\n \"completion_status\",\n ],\n properties: {\n action_items: { type: \"array\", items: { type: \"string\" } },\n blocked_items: { type: \"array\", items: { type: \"string\" } },\n deadlines_approaching: { type: \"array\", items: { type: \"string\" } },\n completion_status: { type: \"string\" },\n },\n },\n});", + "path": "lobu.config.ts", + "githubUrl": "https://github.com/lobu-ai/lobu/blob/main/examples/leadership/lobu.config.ts", + "language": "typescript" } } } From 751766505173adbf86b028775befc872033d1fe2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 02:18:13 +0100 Subject: [PATCH 24/65] refactor(cli): load lobu.config.ts with jiti (the Next.js way) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the hand-rolled esbuild-bundle-to-temp-file loader with jiti — the runtime TS loader Next.js/Nuxt use for *.config.ts. It transpiles on import and resolves the config's imports (@lobu/sdk, relative reaction/connector files) from the project, with no bundling and no temp file written into the user's cwd. Verified jiti produces byte-identical DesiredState to the esbuild loader across all 12 examples. The dynamic import("jiti") stays lazy + allow-listed. --- bun.lock | 13 ++-- packages/cli/package.json | 1 + .../src/commands/_lib/apply/desired-state.ts | 70 ++++++++----------- 3 files changed, 37 insertions(+), 47 deletions(-) diff --git a/bun.lock b/bun.lock index cfba08d5e..dd3a602e9 100644 --- a/bun.lock +++ b/bun.lock @@ -97,6 +97,7 @@ "hono-pino": "^0.10.3", "isomorphic-git": "^1.34.0", "jimp": "^1.6.0", + "jiti": "^2.4.2", "ky": "^1.14.0", "kysely": "^0.28.0", "kysely-postgres-js": "^2.0.0", @@ -2873,7 +2874,7 @@ "jimp": ["jimp@1.6.1", "", { "dependencies": { "@jimp/core": "1.6.1", "@jimp/diff": "1.6.1", "@jimp/js-bmp": "1.6.1", "@jimp/js-gif": "1.6.1", "@jimp/js-jpeg": "1.6.1", "@jimp/js-png": "1.6.1", "@jimp/js-tiff": "1.6.1", "@jimp/plugin-blit": "1.6.1", "@jimp/plugin-blur": "1.6.1", "@jimp/plugin-circle": "1.6.1", "@jimp/plugin-color": "1.6.1", "@jimp/plugin-contain": "1.6.1", "@jimp/plugin-cover": "1.6.1", "@jimp/plugin-crop": "1.6.1", "@jimp/plugin-displace": "1.6.1", "@jimp/plugin-dither": "1.6.1", "@jimp/plugin-fisheye": "1.6.1", "@jimp/plugin-flip": "1.6.1", "@jimp/plugin-hash": "1.6.1", "@jimp/plugin-mask": "1.6.1", "@jimp/plugin-print": "1.6.1", "@jimp/plugin-quantize": "1.6.1", "@jimp/plugin-resize": "1.6.1", "@jimp/plugin-rotate": "1.6.1", "@jimp/plugin-threshold": "1.6.1", "@jimp/types": "1.6.1", "@jimp/utils": "1.6.1" } }, "sha512-hNQh6rZtWfSVWSNVmvq87N5BPJsNH7k7I7qyrXf9DOma9xATQk3fsyHazCQe51nCjdkoWdTmh0vD7bjVSLoxxw=="], - "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="], + "jiti": ["jiti@2.7.0", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ=="], "jose": ["jose@6.2.2", "", {}, "sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ=="], @@ -4455,6 +4456,8 @@ "@so-ric/colorspace/color": ["color@5.0.3", "", { "dependencies": { "color-convert": "^3.1.3", "color-string": "^2.1.3" } }, "sha512-ezmVcLR3xAVp8kYOm4GS45ZLLgIE6SPAFoduLr6hTDajwb3KZ2F46gulK3XpcwRFb5KKGCSezCBAY4Dw4HsyXA=="], + "@tailwindcss/node/jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="], + "@tailwindcss/node/tailwindcss": ["tailwindcss@4.2.4", "", {}, "sha512-HhKppgO81FQof5m6TEnuBWCZGgfRAWbaeOaGT00KOy/Pf/j6oUihdvBpA7ltCeAvZpFhW3j0PTclkxsd4IXYDA=="], "@tailwindcss/oxide-wasm32-wasi/@emnapi/core": ["@emnapi/core@1.10.0", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.1", "tslib": "^2.4.0" }, "bundled": true }, "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw=="], @@ -4475,8 +4478,6 @@ "@tailwindcss/vite/tailwindcss": ["tailwindcss@4.2.4", "", {}, "sha512-HhKppgO81FQof5m6TEnuBWCZGgfRAWbaeOaGT00KOy/Pf/j6oUihdvBpA7ltCeAvZpFhW3j0PTclkxsd4IXYDA=="], - "@tanstack/router-generator/jiti": ["jiti@2.7.0", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ=="], - "@tanstack/router-generator/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="], "@tanstack/router-plugin/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="], @@ -4519,8 +4520,6 @@ "c12/dotenv": ["dotenv@17.4.2", "", {}, "sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw=="], - "c12/jiti": ["jiti@2.7.0", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ=="], - "c12/pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="], "chokidar/fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="], @@ -4591,6 +4590,8 @@ "jwks-rsa/jose": ["jose@4.15.9", "", {}, "sha512-1vUQX+IdDMVPj4k8kOxgUqlcK518yluMuGZwqlr44FS1ppZB/5GWh4rZG89erpOBOJjU/OBsnCVFfapsRz6nEA=="], + "knip/jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="], + "libsignal/protobufjs": ["protobufjs@6.8.8", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.2", "@protobufjs/base64": "^1.1.2", "@protobufjs/codegen": "^2.0.4", "@protobufjs/eventemitter": "^1.1.0", "@protobufjs/fetch": "^1.1.0", "@protobufjs/float": "^1.0.2", "@protobufjs/inquire": "^1.1.0", "@protobufjs/path": "^1.1.2", "@protobufjs/pool": "^1.1.0", "@protobufjs/utf8": "^1.1.0", "@types/long": "^4.0.0", "@types/node": "^10.1.0", "long": "^4.0.0" }, "bin": { "pbjs": "bin/pbjs", "pbts": "bin/pbts" } }, "sha512-AAmHtD5pXgZfi7GMpllpO3q1Xw1OYldr+dMUlAnffGTAhqkg72WdmSY71uKBF/JuyiKs8psYbtKrhi0ASCD8qw=="], "log-symbols/is-unicode-supported": ["is-unicode-supported@1.3.0", "", {}, "sha512-43r2mRvz+8JRIKnWJ+3j8JtjRKZ6GmjzfaE/qiBJnikNnYv/6bagRJ1kUhNk8R5EX/GkobD+r+sfxCPJsiKBLQ=="], @@ -5003,6 +5004,8 @@ "@so-ric/colorspace/color/color-string": ["color-string@2.1.4", "", { "dependencies": { "color-name": "^2.0.0" } }, "sha512-Bb6Cq8oq0IjDOe8wJmi4JeNn763Xs9cfrBcaylK1tPypWzyoy2G3l90v9k64kjphl/ZJjPIShFztenRomi8WTg=="], + "@tailwindcss/postcss/@tailwindcss/node/jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="], + "@tailwindcss/postcss/@tailwindcss/oxide/@tailwindcss/oxide-android-arm64": ["@tailwindcss/oxide-android-arm64@4.3.0", "", { "os": "android", "cpu": "arm64" }, "sha512-TJPiq67tKlLuObP6RkwvVGDoxCMBVtDgKkLfa/uyj7/FyxvQwHS+UOnVrXXgbEsfUaMgiVvC4KbJnRr26ho4Ng=="], "@tailwindcss/postcss/@tailwindcss/oxide/@tailwindcss/oxide-darwin-arm64": ["@tailwindcss/oxide-darwin-arm64@4.3.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-oMN/WZRb+SO37BmUElEgeEWuU8E/HXRkiODxJxLe1UTHVXLrdVSgfaJV7pSlhRGMSOiXLuxTIjfsF3wYvz8cgQ=="], diff --git a/packages/cli/package.json b/packages/cli/package.json index 9dccba3dd..2cef9ae9f 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -74,6 +74,7 @@ "hono-pino": "^0.10.3", "isomorphic-git": "^1.34.0", "jimp": "^1.6.0", + "jiti": "^2.4.2", "ky": "^1.14.0", "kysely": "^0.28.0", "kysely-postgres-js": "^2.0.0", diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index 7741cbe3e..f1685c4b8 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -1,5 +1,4 @@ -import { randomBytes } from "node:crypto"; -import { existsSync, readFileSync, rmSync } from "node:fs"; +import { existsSync, readFileSync } from "node:fs"; import { readdir, readFile, stat } from "node:fs/promises"; import { join, resolve } from "node:path"; import { pathToFileURL } from "node:url"; @@ -760,17 +759,16 @@ function resolveReactionScript( } /** - * Bundle + import a `lobu.config.ts` and return its `defineConfig` default - * export (the SDK {@link Project}). Shared by {@link loadDesiredStateFromConfig} - * (apply) and the commands that read the authored config directly (`lobu run` - * preview registration, `lobu doctor`, `lobu chat`, `lobu validate`). + * Import a `lobu.config.ts` and return its `defineConfig` default export (the + * SDK {@link Project}). Shared by {@link loadDesiredStateFromConfig} (apply) and + * the commands that read the authored config directly (`lobu run` preview + * registration, `lobu doctor`, `lobu chat`, `lobu validate`, `lobu memory seed`). * - * esbuild bundles relative imports inline and externalizes node_modules - * (`@lobu/sdk` / `@lobu/connector-sdk` resolve from the project at import time). - * The temp `.mjs` is deleted after import — the module is already in memory. - * - * The dynamic imports here are intentional and allow-listed (AGENTS.md): esbuild - * is loaded lazily, and the bundled config is a generated file imported by URL. + * Uses jiti — the same runtime TypeScript loader Next.js/Nuxt use for their + * `*.config.ts` — which transpiles on import and resolves the config's imports + * (`@lobu/sdk`, `@lobu/connector-sdk`, relative reaction/connector files) from + * the project. No bundling, no temp file. The dynamic `import("jiti")` is lazy + * + allow-listed (AGENTS.md). */ export async function loadProjectConfig( cwd: string @@ -779,38 +777,26 @@ export async function loadProjectConfig( if (!existsSync(configPath)) { throw new ValidationError(`No lobu.config.ts found in ${cwd}`); } - const { build } = await import("esbuild"); - const outFile = resolve( - cwd, - `.lobu-config.${randomBytes(6).toString("hex")}.mjs` - ); + const { createJiti } = await import("jiti"); + const jiti = createJiti(pathToFileURL(configPath).href); + let project: unknown; try { - await build({ - entryPoints: [configPath], - outfile: outFile, - bundle: true, - format: "esm", - platform: "node", - packages: "external", - logLevel: "silent", - }); - const mod = (await import(pathToFileURL(outFile).href)) as { - default?: unknown; - }; - const project = mod.default; - if ( - !project || - typeof project !== "object" || - (project as { kind?: unknown }).kind !== "project" - ) { - throw new ValidationError( - "lobu.config.ts must `export default defineConfig({ ... })`" - ); - } - return { project: project as Project, configPath }; - } finally { - rmSync(outFile, { force: true }); + project = await jiti.import(configPath, { default: true }); + } catch (err) { + throw new ValidationError( + `Failed to load lobu.config.ts — ${err instanceof Error ? err.message : String(err)}` + ); + } + if ( + !project || + typeof project !== "object" || + (project as { kind?: unknown }).kind !== "project" + ) { + throw new ValidationError( + "lobu.config.ts must `export default defineConfig({ ... })`" + ); } + return { project: project as Project, configPath }; } /** From a383b61c64f97370bf888b5d6c529d0edabc6407 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 02:28:15 +0100 Subject: [PATCH 25/65] feat(cli): migrate producers to lobu.config.ts (init, agent add, root-finder, help) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The reader side was migrated earlier; this finishes the producer side so the init → apply flow works end to end: - lobu init scaffolds lobu.config.ts (defineConfig/defineAgent via @lobu/sdk) instead of lobu.toml; drops the models/ + data/ YAML scaffolding (schema lives in the config). Round-trip tested through loadDesiredStateFromConfig. - lobu agent add scaffolds the agent dir + prints a defineAgent snippet to paste (no fragile mutation of the user's typed config) instead of appending TOML. - ensure-deps-installed anchors the connector project root on lobu.config.ts. - index.ts help text + the seed description say lobu.config.ts. - Delete init-memory.test.ts (tested the removed TOML scaffolder); cli-ux.test.ts asserts lobu.config.ts. (lobu export still emits YAML — its single-file design is an open question, handled separately.) --- packages/cli/src/__tests__/cli-ux.test.ts | 95 +++++--- .../cli/src/__tests__/init-memory.test.ts | 82 ------- .../commands/_lib/ensure-deps-installed.ts | 10 +- packages/cli/src/commands/agent.ts | 44 ++-- packages/cli/src/commands/init.ts | 206 +++++++----------- packages/cli/src/index.ts | 23 +- 6 files changed, 192 insertions(+), 268 deletions(-) delete mode 100644 packages/cli/src/__tests__/init-memory.test.ts diff --git a/packages/cli/src/__tests__/cli-ux.test.ts b/packages/cli/src/__tests__/cli-ux.test.ts index 8d3fa59ed..eea39a038 100644 --- a/packages/cli/src/__tests__/cli-ux.test.ts +++ b/packages/cli/src/__tests__/cli-ux.test.ts @@ -1,20 +1,19 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test"; import { existsSync, - mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs"; -import { tmpdir } from "node:os"; import { createServer } from "node:net"; +import { tmpdir } from "node:os"; import { join } from "node:path"; - -import { isPortFree } from "../commands/dev"; +import { loadDesiredStateFromConfig } from "../commands/_lib/apply/desired-state"; import { agentScaffoldCommand } from "../commands/agent"; -import { loadProjectLink, saveProjectLink } from "../internal/project-link"; +import { isPortFree } from "../commands/dev"; import { initCommand } from "../commands/init"; +import { loadProjectLink, saveProjectLink } from "../internal/project-link"; describe("isPortFree", () => { test("returns true for a port nothing is holding", async () => { @@ -90,7 +89,7 @@ describe("lobu init --yes", () => { test("scaffolds a non-interactive project with defaults", async () => { await initCommand(cwd, "demo", { yes: true }); const proj = join(cwd, "demo"); - expect(existsSync(join(proj, "lobu.toml"))).toBe(true); + expect(existsSync(join(proj, "lobu.config.ts"))).toBe(true); expect(existsSync(join(proj, ".env"))).toBe(true); expect(existsSync(join(proj, "agents", "demo", "IDENTITY.md"))).toBe(true); expect(existsSync(join(proj, "agents", "demo", "evals", "ping.yaml"))).toBe( @@ -100,9 +99,27 @@ describe("lobu init --yes", () => { expect(env.includes("SENTRY_DSN=")).toBe(false); }); + test("scaffolded lobu.config.ts loads into desired state", async () => { + // jiti resolves the externalized `@lobu/sdk` import relative to the config + // file, so scaffold inside the package tree (where node_modules is + // reachable), not the tmpdir() used by the other init tests. + const fixtureRoot = mkdtempSync(join(import.meta.dir, "init-load-")); + try { + await initCommand(fixtureRoot, "loadable", { yes: true }); + const proj = join(fixtureRoot, "loadable"); + const { state } = await loadDesiredStateFromConfig({ cwd: proj }); + expect(state.agents).toHaveLength(1); + expect(state.agents[0]?.metadata.agentId).toBe("loadable"); + // SOUL/IDENTITY/USER.md from the agent dir are merged into settings. + expect(state.agents[0]?.settings.identityMd).toContain("loadable"); + } finally { + rmSync(fixtureRoot, { recursive: true, force: true }); + } + }); + test("--here scaffolds into the current directory", async () => { await initCommand(cwd, undefined, { yes: true, here: true }); - expect(existsSync(join(cwd, "lobu.toml"))).toBe(true); + expect(existsSync(join(cwd, "lobu.config.ts"))).toBe(true); expect(existsSync(join(cwd, "agents"))).toBe(true); }); @@ -114,10 +131,14 @@ describe("lobu init --yes", () => { test("--slack-preview writes agent preview config", async () => { await initCommand(cwd, "preview-on", { yes: true, slackPreview: true }); - const toml = readFileSync(join(cwd, "preview-on", "lobu.toml"), "utf-8"); - expect(toml).toContain("[agents.preview-on.preview.slack]"); - expect(toml).toContain("enabled = true"); - expect(toml).toContain('surfaces = ["dm"]'); + const config = readFileSync( + join(cwd, "preview-on", "lobu.config.ts"), + "utf-8" + ); + expect(config).toContain("preview:"); + expect(config).toContain("slack:"); + expect(config).toContain("enabled: true"); + expect(config).toContain('surfaces: ["dm"]'); }); test("--provider with bad id throws before writing files", async () => { @@ -139,30 +160,46 @@ describe("agent scaffold", () => { rmSync(cwd, { recursive: true, force: true }); }); - test("appends a new agent block to lobu.toml", async () => { + test("scaffolds the agent dir and prints a defineAgent block", async () => { writeFileSync( - join(cwd, "lobu.toml"), - ["[agents.first]", 'name = "first"', 'dir = "./agents/first"', ""].join( - "\n" - ) + join(cwd, "lobu.config.ts"), + 'import { defineConfig } from "@lobu/sdk";\nexport default defineConfig({ agents: [] });\n' ); - await agentScaffoldCommand("second", { cwd, name: "Second" }); - const toml = readFileSync(join(cwd, "lobu.toml"), "utf-8"); - expect(toml).toContain("[agents.second]"); - expect(toml).toContain('name = "Second"'); - expect(toml).toContain('dir = "./agents/second"'); + const logs: string[] = []; + const original = console.log; + console.log = (...args: unknown[]) => { + logs.push(args.join(" ")); + }; + try { + await agentScaffoldCommand("second", { cwd, name: "Second" }); + } finally { + console.log = original; + } + const output = logs.join("\n"); + expect(output).toContain("const second = defineAgent({"); + expect(output).toContain('id: "second"'); + expect(output).toContain('name: "Second"'); + expect(output).toContain('dir: "./agents/second"'); expect(existsSync(join(cwd, "agents", "second", "IDENTITY.md"))).toBe(true); expect(existsSync(join(cwd, "agents", "second", "SOUL.md"))).toBe(true); expect(existsSync(join(cwd, "agents", "second", "USER.md"))).toBe(true); }); - test("escapes quotes in --name so the TOML stays parseable", async () => { - writeFileSync(join(cwd, "lobu.toml"), ""); - await agentScaffoldCommand("quoty", { - cwd, - name: 'Sales "Bot" v2', - }); - const toml = readFileSync(join(cwd, "lobu.toml"), "utf-8"); - expect(toml).toContain('name = "Sales \\"Bot\\" v2"'); + test("escapes quotes in --name so the printed snippet stays valid TS", async () => { + writeFileSync( + join(cwd, "lobu.config.ts"), + 'import { defineConfig } from "@lobu/sdk";\nexport default defineConfig({ agents: [] });\n' + ); + const logs: string[] = []; + const original = console.log; + console.log = (...args: unknown[]) => { + logs.push(args.join(" ")); + }; + try { + await agentScaffoldCommand("quoty", { cwd, name: 'Sales "Bot" v2' }); + } finally { + console.log = original; + } + expect(logs.join("\n")).toContain('name: "Sales \\"Bot\\" v2"'); }); }); diff --git a/packages/cli/src/__tests__/init-memory.test.ts b/packages/cli/src/__tests__/init-memory.test.ts deleted file mode 100644 index 5321d37b4..000000000 --- a/packages/cli/src/__tests__/init-memory.test.ts +++ /dev/null @@ -1,82 +0,0 @@ -import { afterEach, beforeEach, describe, expect, test } from "bun:test"; -import { - existsSync, - mkdirSync, - mkdtempSync, - readFileSync, - rmSync, -} from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { generateLobuToml, initCommand } from "../commands/init"; - -describe("init memory scaffolding", () => { - let projectDir: string; - - beforeEach(() => { - projectDir = mkdtempSync(join(tmpdir(), "lobu-init-memory-")); - mkdirSync(join(projectDir, "agents", "support"), { recursive: true }); - }); - - afterEach(() => { - rmSync(projectDir, { recursive: true, force: true }); - }); - - test("generateLobuToml inlines the [memory] fields when enabled", async () => { - await generateLobuToml(projectDir, { - agentName: "support", - allowedDomains: "github.com,.github.com", - includeLobuMemory: true, - lobuOrg: "support", - lobuName: "Support", - lobuDescription: "Help support teams", - }); - - const content = readFileSync(join(projectDir, "lobu.toml"), "utf-8"); - - expect(content).toContain("[memory]"); - expect(content).toContain('org = "support"'); - expect(content).toContain('name = "Support"'); - expect(content).toContain('description = "Help support teams"'); - expect(content).toContain('models = "./models"'); - expect(content).toContain('data = "./data"'); - expect(content).not.toContain("lobu.yaml"); - expect(existsSync(join(projectDir, "lobu.yaml"))).toBe(false); - }); - - test("generateLobuToml falls back to the agent name when org/name are omitted", async () => { - await generateLobuToml(projectDir, { - agentName: "support", - allowedDomains: "github.com", - includeLobuMemory: true, - }); - - const content = readFileSync(join(projectDir, "lobu.toml"), "utf-8"); - - expect(content).toContain('org = "support"'); - expect(content).toContain('name = "Support"'); - }); - - test("init --yes writes empty env entries for generated provider and platform refs", async () => { - await initCommand(projectDir, "my-agent", { - yes: true, - provider: "openrouter", - platform: "slack", - memory: "lobu-cloud", - noSentry: true, - }); - - const env = readFileSync(join(projectDir, "my-agent", ".env"), "utf-8"); - const toml = readFileSync( - join(projectDir, "my-agent", "lobu.toml"), - "utf-8" - ); - - expect(toml).toContain('key = "$OPENROUTER_API_KEY"'); - expect(toml).toContain('botToken = "$SLACK_BOT_TOKEN"'); - expect(toml).toContain('signingSecret = "$SLACK_SIGNING_SECRET"'); - expect(env).toContain("OPENROUTER_API_KEY="); - expect(env).toContain("SLACK_BOT_TOKEN="); - expect(env).toContain("SLACK_SIGNING_SECRET="); - }); -}); diff --git a/packages/cli/src/commands/_lib/ensure-deps-installed.ts b/packages/cli/src/commands/_lib/ensure-deps-installed.ts index 3bb877b59..49d07123f 100644 --- a/packages/cli/src/commands/_lib/ensure-deps-installed.ts +++ b/packages/cli/src/commands/_lib/ensure-deps-installed.ts @@ -16,15 +16,15 @@ import { dirname, join } from "node:path"; const ensuredRoots = new Set(); /** - * Find the connector's project root — the nearest ancestor with `lobu.toml`. - * Anchoring on `lobu.toml` (not any ancestor `package.json`) is what stops a - * connector inside a monorepo from resolving to the monorepo's root - * package.json and triggering a wrong-directory install. + * Find the connector's project root — the nearest ancestor with + * `lobu.config.ts`. Anchoring on `lobu.config.ts` (not any ancestor + * `package.json`) is what stops a connector inside a monorepo from resolving to + * the monorepo's root package.json and triggering a wrong-directory install. */ export function findProjectRoot(fromFile: string): string | null { let dir = dirname(fromFile); for (let i = 0; i < 40; i++) { - if (existsSync(join(dir, "lobu.toml"))) return dir; + if (existsSync(join(dir, "lobu.config.ts"))) return dir; const parent = dirname(dir); if (parent === dir) break; dir = parent; diff --git a/packages/cli/src/commands/agent.ts b/packages/cli/src/commands/agent.ts index 654d94632..3f50154c7 100644 --- a/packages/cli/src/commands/agent.ts +++ b/packages/cli/src/commands/agent.ts @@ -206,7 +206,7 @@ export interface AgentScaffoldOptions { const AGENT_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/; -/** Add a new local agent + a `[agents.]` block to an existing lobu.toml. */ +/** Scaffold a new local agent dir + print the `defineAgent` block to add. */ export async function agentScaffoldCommand( agentId: string, options: AgentScaffoldOptions = {} @@ -221,11 +221,11 @@ export async function agentScaffoldCommand( } const cwd = options.cwd ?? process.cwd(); - const lobuTomlPath = join(cwd, "lobu.toml"); - if (!(await pathExists(lobuTomlPath))) { + const lobuConfigPath = join(cwd, "lobu.config.ts"); + if (!(await pathExists(lobuConfigPath))) { console.error( chalk.red( - "\n No lobu.toml in the current directory. Run `lobu init` first or `cd` into a Lobu project.\n" + "\n No lobu.config.ts in the current directory. Run `lobu init` first or `cd` into a Lobu project.\n" ) ); process.exit(1); @@ -260,29 +260,31 @@ export async function agentScaffoldCommand( await mkdir(join(agentDir, "evals"), { recursive: true }); const description = options.description ?? ""; - const tomlBlock = [ - "", - `[agents.${agentId}]`, - `name = ${JSON.stringify(displayName)}`, - `description = ${JSON.stringify(description)}`, - `dir = "./agents/${agentId}"`, - "", - `[agents.${agentId}.skills]`, - "", - `[agents.${agentId}.network]`, - "allowed = []", - "", + // The config is typed TypeScript, so we don't mutate it for the user — print + // the `defineAgent` block to paste (with editor autocomplete + type-checking). + const constName = agentId.replace(/-([a-z0-9])/g, (_, c: string) => + c.toUpperCase() + ); + const snippet = [ + `const ${constName} = defineAgent({`, + ` id: ${JSON.stringify(agentId)},`, + ` name: ${JSON.stringify(displayName)},`, + ...(description ? [` description: ${JSON.stringify(description)},`] : []), + ` dir: "./agents/${agentId}",`, + `});`, ].join("\n"); - const existing = await readFile(lobuTomlPath, "utf-8"); - const sep = existing.endsWith("\n") ? "" : "\n"; - await writeFile(lobuTomlPath, `${existing}${sep}${tomlBlock}`); - console.log(chalk.green(`\n Scaffolded agent "${agentId}".`)); console.log(chalk.dim(` - agents/${agentId}/IDENTITY.md`)); console.log(chalk.dim(` - agents/${agentId}/SOUL.md`)); console.log(chalk.dim(` - agents/${agentId}/USER.md`)); console.log(chalk.dim(` - agents/${agentId}/skills/`)); console.log(chalk.dim(` - agents/${agentId}/evals/`)); - console.log(chalk.dim(` - lobu.toml: appended [agents.${agentId}]\n`)); + console.log(chalk.cyan("\n Add it to your lobu.config.ts:\n")); + console.log(`${snippet}\n`); + console.log( + chalk.dim( + ` ...then add \`${constName}\` to \`defineConfig({ agents: [...] })\`.\n` + ) + ); } diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index bed4ae2ce..963248124 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -12,15 +12,15 @@ import { basename, join, resolve } from "node:path"; import { confirm, input, password, select } from "@inquirer/prompts"; import chalk from "chalk"; import ora from "ora"; -import { isPortFree } from "./dev.js"; import { promptPlatformConfig } from "../commands/platforms/platform-prompts.js"; -import { setLocalEnvValue } from "../internal/local-env.js"; import { getProviderById, loadProviderRegistry, type RegistryProvider, } from "../commands/providers/registry.js"; +import { setLocalEnvValue } from "../internal/local-env.js"; import { renderTemplate } from "../utils/template.js"; +import { isPortFree } from "./dev.js"; const DEFAULT_LOBU_MCP_URL = "https://lobu.ai/mcp"; @@ -196,12 +196,12 @@ export async function initCommand( } const entries = await readdir(projectDir).catch(() => [] as string[]); const conflict = entries.some( - (n) => n === "lobu.toml" || n === "agents" || n === ".env" + (n) => n === "lobu.config.ts" || n === "agents" || n === ".env" ); if (conflict) { console.log( chalk.red( - `\n✗ ${projectDir} already contains a Lobu project (lobu.toml / agents/ / .env).\n Remove them or pick another directory.\n` + `\n✗ ${projectDir} already contains a Lobu project (lobu.config.ts / agents/ / .env).\n Remove them or pick another directory.\n` ) ); process.exit(1); @@ -401,7 +401,7 @@ export async function initCommand( }), }); // Resolve aliases (e.g. `--provider anthropic` → "claude") before any - // downstream use so the synthesized lobu.toml references the real id. + // downstream use so the synthesized lobu.config.ts references the real id. const providerId = providerIdRaw ? resolveProviderAlias(providerIdRaw) : ""; let providerApiKey = ""; @@ -450,8 +450,8 @@ export async function initCommand( }), }); - // Interactive: prompt for real secrets. --yes: write placeholder env-var - // refs into lobu.toml; the user fills .env afterwards. + // Interactive: prompt for real secrets. --yes: collect placeholder env-var + // refs so we seed empty .env entries; the user fills them in afterwards. let platformConfig: Record = {}; let platformSecrets: Array<{ envVar: string; value: string }> = []; if (platformType) { @@ -584,33 +584,14 @@ export async function initCommand( const spinner = ora("Creating Lobu project...").start(); try { - await mkdir(join(projectDir, "data"), { recursive: true }); - - if (includeLobuMemory) { - await mkdir(join(projectDir, "models"), { recursive: true }); - await mkdir(join(projectDir, "data", "entities"), { recursive: true }); - await mkdir(join(projectDir, "data", "relationships"), { - recursive: true, - }); - await writeFile(join(projectDir, "models", ".gitkeep"), ""); - await writeFile(join(projectDir, "data", "entities", ".gitkeep"), ""); - await writeFile( - join(projectDir, "data", "relationships", ".gitkeep"), - "" - ); - } - - await generateLobuToml(projectDir, { + await generateLobuConfig(projectDir, { agentName: projectName, allowedDomains: answers.allowedDomains, providerId: providerId || undefined, providerEnvVar: selectedProvider?.providers?.[0]?.envVarName, providerModel: selectedProvider?.providers?.[0]?.defaultModel, - platformType: platformType || undefined, - platformConfig: - Object.keys(platformConfig).length > 0 ? platformConfig : undefined, - includeLobuMemory, enableSlackPreview, + includeLobuMemory, lobuOrg: includeLobuMemory ? projectName : undefined, lobuName: includeLobuMemory ? humanizeSlug(projectName) : undefined, }); @@ -928,7 +909,15 @@ function humanizeSlug(slug: string): string { .join(" "); } -export async function generateLobuToml( +/** + * Scaffold the project's `lobu.config.ts` — the single TypeScript entrypoint + * `lobu apply` (and `lobu run`) read. Emits a `defineAgent` (providers, + * network, optional Slack preview) and a `defineConfig` default export with the + * org metadata. Chat platforms and the memory schema are NOT authored here: + * connections are created via the `/agents` UI / CRUD API, and entity / + * relationship types are added later with `defineEntityType` / `defineConfig`. + */ +export async function generateLobuConfig( projectDir: string, options: { agentName: string; @@ -936,127 +925,100 @@ export async function generateLobuToml( providerId?: string; providerEnvVar?: string; providerModel?: string; - platformType?: string; - platformConfig?: Record; + enableSlackPreview?: boolean; includeLobuMemory?: boolean; lobuOrg?: string; lobuName?: string; lobuDescription?: string; - enableSlackPreview?: boolean; } ): Promise { const id = options.agentName; - const lines: string[] = [ - "# lobu.toml — Agent configuration", - "# Docs: https://lobu.ai/docs/getting-started", - "#", - "# Each [agents.{id}] defines an agent. The dir field points to a directory", - "# containing IDENTITY.md, SOUL.md, USER.md, and optionally skills/.", - "# Shared skills in the root skills/ directory are available to all agents.", - "", - `[agents.${id}]`, - `name = "${id}"`, - `description = ""`, - `dir = "./agents/${id}"`, - "", - "# LLM providers (order = priority, key = API key or $ENV_VAR)", + + const agentFields: string[] = [ + ` id: ${JSON.stringify(id)},`, + ` name: ${JSON.stringify(id)},`, + ` description: "",`, + ` dir: ${JSON.stringify(`./agents/${id}`)},`, ]; if (options.providerId && options.providerEnvVar) { - lines.push( - `[[agents.${id}.providers]]`, - `id = "${options.providerId}"`, - ...(options.providerModel ? [`model = "${options.providerModel}"`] : []), - `key = "$${options.providerEnvVar}"` - ); - } else { - lines.push( - "# Add providers via the gateway configuration APIs or uncomment below:", - `# [[agents.${id}.providers]]`, - '# id = "openrouter"', - '# key = "$OPENROUTER_API_KEY"' - ); - } - - lines.push(""); - - if (options.platformType && options.platformConfig) { - lines.push( - `[[agents.${id}.platforms]]`, - `type = "${options.platformType}"` + agentFields.push( + " providers: [", + " {", + ` id: ${JSON.stringify(options.providerId)},`, + ...(options.providerModel + ? [` model: ${JSON.stringify(options.providerModel)},`] + : []), + ` key: secret(${JSON.stringify(options.providerEnvVar)}),`, + " },", + " ]," ); - lines.push(`[agents.${id}.platforms.config]`); - for (const [key, value] of Object.entries(options.platformConfig)) { - lines.push(`${key} = "${value}"`); - } } else { - lines.push( - "# Chat platform (add via the gateway configuration APIs or uncomment below):", - `# [[agents.${id}.platforms]]`, - '# type = "telegram"', - `# [agents.${id}.platforms.config]`, - '# botToken = "$TELEGRAM_BOT_TOKEN"' + agentFields.push( + " // Add a provider, e.g.:", + ' // providers: [{ id: "openrouter", key: secret("OPENROUTER_API_KEY") }],' ); } - lines.push( - "", - "# Local skills live in skills//SKILL.md or agents//skills//SKILL.md", - `[agents.${id}.skills]`, - "", - "# MCP servers (add custom tool servers with optional OAuth):", - `# [agents.${id}.skills.mcp.my-mcp]`, - '# url = "https://my-mcp.example.com"', - `# [agents.${id}.skills.mcp.my-mcp.oauth]`, - '# auth_url = "https://auth.example.com/authorize"', - '# token_url = "https://auth.example.com/token"', - '# client_id = "$MY_MCP_CLIENT_ID"' + const domains = options.allowedDomains + ? options.allowedDomains + .split(",") + .map((d) => d.trim()) + .filter(Boolean) + : []; + agentFields.push( + " network: {", + domains.length > 0 + ? ` allowed: [${domains.map((d) => JSON.stringify(d)).join(", ")}],` + : " allowed: [],", + " }," ); if (options.enableSlackPreview) { - lines.push( - "", - "# Hosted preview — `lobu run` prints a `/lobu link ` you redeem by", - "# DMing the hosted Lobu Slack bot. The block key is the chat platform;", - "# `[agents..preview.telegram]` works the same way (redeem with `/link `).", - `[agents.${id}.preview.slack]`, - "enabled = true", - 'surfaces = ["dm"]', - "code_ttl_minutes = 15" + agentFields.push( + " // Hosted preview — `lobu run` prints a `/lobu link ` you redeem", + " // by DMing the hosted Lobu Slack bot.", + " preview: {", + ' slack: { enabled: true, surfaces: ["dm"], codeTtlMinutes: 15 },', + " }" ); } - lines.push("", `[agents.${id}.network]`); - if (options.allowedDomains) { - const domains = options.allowedDomains - .split(",") - .map((d) => `"${d.trim()}"`) - .join(", "); - lines.push(`allowed = [${domains}]`); - } else { - lines.push("allowed = []"); - } - + const configFields: string[] = []; if (options.includeLobuMemory) { const org = options.lobuOrg ?? options.agentName; const name = options.lobuName ?? humanizeSlug(options.agentName); - lines.push( - "", - "# Project-scoped Lobu memory", - `[memory]`, - "enabled = true", - `org = ${JSON.stringify(org)}`, - `name = ${JSON.stringify(name)}`, + configFields.push( + ` org: ${JSON.stringify(org)},`, + ` orgName: ${JSON.stringify(name)},`, ...(options.lobuDescription - ? [`description = ${JSON.stringify(options.lobuDescription)}`] - : []), - 'models = "./models"', - 'data = "./data"' + ? [` orgDescription: ${JSON.stringify(options.lobuDescription)},`] + : []) ); } + configFields.push(" agents: [agent],"); + + const lines = [ + "// lobu.config.ts — Lobu project configuration", + "// Docs: https://lobu.ai/docs/getting-started", + "//", + "// `dir` points to a folder with IDENTITY.md, SOUL.md, USER.md, and an", + "// optional skills/ directory. Shared skills in the root skills/ directory", + "// are available to every agent. Run `lobu apply` to sync this to your org.", + "", + 'import { defineAgent, defineConfig, secret } from "@lobu/sdk";', + "", + "const agent = defineAgent({", + ...agentFields, + "});", + "", + "export default defineConfig({", + ...configFields, + "});", + "", + ]; - lines.push(""); - await writeFile(join(projectDir, "lobu.toml"), lines.join("\n")); + await writeFile(join(projectDir, "lobu.config.ts"), lines.join("\n")); } async function getCliVersion(): Promise { diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index bb2391b39..71f7ff3ed 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -103,7 +103,7 @@ Local dev: init [name] Scaffold a new agent project run | dev | start Boot the embedded Lobu stack chat Send a prompt to an agent and stream the response - validate Validate lobu.toml + validate Validate lobu.config.ts doctor Health checks (deps, DB, pgvector, ports, keys) telemetry Show / toggle anonymous error reporting @@ -113,7 +113,7 @@ Cloud: context Manage API contexts org Manage active org slug link | unlink Bind this directory to a (context, org) - apply | deploy Sync lobu.toml to cloud (idempotent) + apply | deploy Sync lobu.config.ts to cloud (idempotent) agent CRUD agents via REST call [tool] Invoke an admin REST tool by name (--list to discover) token [create] Print or mint personal access tokens @@ -132,7 +132,7 @@ Memory: program .command("init [name]") .description( - "Scaffold a new agent project (lobu.toml + agent files + .env)" + "Scaffold a new agent project (lobu.config.ts + agent files + .env)" ) .option("-y, --yes", "Skip prompts; use defaults / flag values") .option( @@ -164,7 +164,7 @@ Memory: .option("--no-sentry", "Disable Sentry without prompting") .option( "--slack-preview", - "Enable public Lobu Developer Slack Preview in lobu.toml" + "Enable public Lobu Developer Slack Preview in lobu.config.ts" ) .option("--no-slack-preview", "Disable Slack Preview without prompting") .option( @@ -225,7 +225,10 @@ Memory: .description( "Send a prompt to an agent and stream the response. With --user, routes through Telegram/Slack." ) - .option("-a, --agent ", "Agent ID (defaults to first in lobu.toml)") + .option( + "-a, --agent ", + "Agent ID (defaults to first in lobu.config.ts)" + ) .option("-u, --user ", "User ID to impersonate (e.g. telegram:12345)") .option("-t, --thread ", "Thread/conversation ID for multi-turn") .option( @@ -268,7 +271,9 @@ Memory: // ─── validate ─────────────────────────────────────────────────────── program .command("validate") - .description("Validate lobu.toml schema, skill IDs, and provider config") + .description( + "Validate lobu.config.ts schema, skill IDs, and provider config" + ) .action(async () => { const { validateCommand } = await import("./commands/validate.js"); const valid = await validateCommand(process.cwd()); @@ -280,7 +285,7 @@ Memory: .command("apply") .alias("deploy") .description( - "Sync lobu.toml + agent dirs to your Lobu Cloud org (idempotent)" + "Sync lobu.config.ts + agent dirs to your Lobu Cloud org (idempotent)" ) .option("--dry-run", "Show the plan and exit without mutating") .option("--yes", "Skip the confirmation prompt (CI mode)") @@ -704,7 +709,7 @@ Memory: agent .command("scaffold ") .description( - "Add a new local agent (agents//* + lobu.toml entry) without overwriting existing ones" + "Add a new local agent (agents//* + lobu.config.ts entry) without overwriting existing ones" ) .option("--name ", "Display name") .option("--description ", "Description") @@ -1038,7 +1043,7 @@ Memory: memory .command("seed [path]") .description( - "Provision a Lobu memory workspace from [memory] in lobu.toml + ./models + optional ./data" + "Provision a Lobu memory workspace from lobu.config.ts + optional ./data records" ) .option("--dry-run", "Log what would be created without mutating") .option("--org ", "Org slug override (defaults to [memory].org)") From 81e30e8af88c56c73d313590c044f9350838d772 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 02:48:34 +0100 Subject: [PATCH 26/65] feat(cli): lobu init --from-org bootstraps a project from cloud; remove lobu export MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the YAML-era `lobu export` (partial, agent-less) with `lobu init --from-org `: the inverse of `lobu apply`. It fetches the org's full declared state and emits a clean, runnable project — one lean lobu.config.ts (handle consts, real object literals, short arrays inlined, empty/default fields omitted, resources sorted) plus the files it references (agents//{SOUL, IDENTITY,USER}.md, skills//SKILL.md, reactions/.reaction.ts). Now includes agents (the gap export punted on). Write-only secrets become secret("ENV_VAR") placeholders + a .env.example; never real values. Runs after init's empty-dir guard, so it never overwrites an existing project. Round-trip gated: the test bootstraps stubbed cloud state, loads the generated lobu.config.ts via loadDesiredStateFromConfig, and asserts the DesiredState matches the input. cli 282 pass, tsc clean. --- .../cli/src/commands/_lib/apply/client.ts | 5 +- .../_lib/export/__tests__/export-cmd.test.ts | 336 ------- .../src/commands/_lib/export/export-cmd.ts | 430 -------- .../__tests__/init-from-org.test.ts | 376 +++++++ .../commands/_lib/init-from-org/bootstrap.ts | 952 ++++++++++++++++++ packages/cli/src/commands/init.ts | 24 + packages/cli/src/index.ts | 67 +- 7 files changed, 1372 insertions(+), 818 deletions(-) delete mode 100644 packages/cli/src/commands/_lib/export/__tests__/export-cmd.test.ts delete mode 100644 packages/cli/src/commands/_lib/export/export-cmd.ts create mode 100644 packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts create mode 100644 packages/cli/src/commands/_lib/init-from-org/bootstrap.ts diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index 13dd8c2ab..c7a35157e 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -553,8 +553,9 @@ export class ApplyClient { /** * Fetch a single watcher's full payload — `getWatcher` server-side, which - * returns reaction_script (not in the list response). Used by `lobu export` - * to round-trip reaction scripts back to sibling `.ts` files. + * returns reaction_script (not in the list response). Used by + * `lobu init --from-org` to round-trip reaction scripts back to sibling + * `.ts` files. */ async getWatcherDetail(watcherId: string): Promise<{ reaction_script?: string | null; diff --git a/packages/cli/src/commands/_lib/export/__tests__/export-cmd.test.ts b/packages/cli/src/commands/_lib/export/__tests__/export-cmd.test.ts deleted file mode 100644 index b9d1b3181..000000000 --- a/packages/cli/src/commands/_lib/export/__tests__/export-cmd.test.ts +++ /dev/null @@ -1,336 +0,0 @@ -/** - * Tests for `lobu export`. - * - * Covers the canonical round-trip: server state → YAML + sibling reaction- - * script `.ts` files that `lobu apply` can read back. Network is stubbed - * through a fetch impl that returns the canned responses listWatchers / - * listEntityTypes / etc. would normally produce. The CLI's auth resolution - * still runs, so we set the right env vars to avoid hitting the keyring. - */ -import { afterEach, beforeEach, describe, expect, test } from "bun:test"; -import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; -import { mkdir } from "node:fs/promises"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { parse as parseYaml, parseAllDocuments } from "yaml"; -import { exportCommand } from "../export-cmd.js"; - -const tempDirs: string[] = []; - -afterEach(() => { - while (tempDirs.length > 0) { - const d = tempDirs.pop(); - if (d) rmSync(d, { recursive: true, force: true }); - } -}); - -function mkTempDir(): string { - const dir = mkdtempSync(join(tmpdir(), "lobu-export-")); - tempDirs.push(dir); - return dir; -} - -function buildFetch(routes: Record unknown>): typeof fetch { - return (async (input: RequestInfo | URL, _init?: RequestInit) => { - const url = String(input); - for (const [pattern, handler] of Object.entries(routes)) { - if (url.includes(pattern)) { - return new Response(JSON.stringify(handler()), { status: 200 }); - } - } - throw new Error(`unexpected fetch: ${url}`); - }) as typeof fetch; -} - -const ORIG_ENV: Record = {}; - -beforeEach(() => { - for (const key of [ - "LOBU_API_URL", - "LOBU_TOKEN", - "LOBU_ORG", - "LOBU_CONTEXT_DIR", - ]) { - ORIG_ENV[key] = process.env[key]; - } - process.env.LOBU_API_URL = "https://example.test"; - process.env.LOBU_TOKEN = "test-token"; - process.env.LOBU_ORG = "acme"; -}); - -afterEach(() => { - for (const [key, val] of Object.entries(ORIG_ENV)) { - if (val === undefined) delete process.env[key]; - else process.env[key] = val; - } -}); - -describe("lobu export", () => { - test("writes models bundle with entity / relationship / watcher docs", async () => { - const out = mkTempDir(); - const fetchImpl = buildFetch({ - manage_entity_schema: () => ({ - entity_types: [ - { - slug: "lead", - name: "Lead", - description: "A sales lead", - required: ["stage"], - properties: { stage: { type: "string" } }, - }, - ], - relationship_types: [ - { - slug: "converted-to", - name: "Converted To", - description: "Lead → Pilot", - rules: [{ source: "lead", target: "pilot" }], - }, - ], - }), - "watchers?watcher_id": () => ({ - watcher: { reaction_script: null, description: null }, - }), - "watchers?include_details": () => ({ - watchers: [ - { - slug: "weekly-digest", - watcher_id: "1", - name: "Weekly digest", - agent_id: "triage", - prompt: "Produce a digest.", - extraction_schema: { type: "object" }, - schedule: "0 9 * * 1", - sources: [{ name: "content", query: "SELECT * FROM events" }], - tags: ["crm"], - device_worker_id: null, - notification_priority: "normal", - notification_channel: "canvas", - min_cooldown_seconds: 0, - }, - ], - }), - auth_profiles: () => ({ auth_profiles: [] }), - manage_connections: () => ({ connections: [] }), - }); - - await exportCommand({ - cwd: out, - out, - fetchImpl, - only: "models", - }); - - const bundleRaw = readFileSync( - join(out, "models", "exported.yaml"), - "utf-8" - ); - const bundle = parseYaml(bundleRaw) as { - version: number; - entities?: unknown[]; - relationships?: unknown[]; - watchers?: Array>; - }; - expect(bundle.version).toBe(2); - expect(bundle.entities?.length).toBe(1); - expect(bundle.relationships?.length).toBe(1); - const watchers = bundle.watchers ?? []; - expect(watchers.length).toBe(1); - const watcher = watchers[0]; - expect(watcher.slug).toBe("weekly-digest"); - expect(watcher.agent).toBe("triage"); - expect(watcher.prompt).toBe("Produce a digest."); - expect(watcher.tags).toEqual(["crm"]); - // Default scalar values are omitted from the exported YAML so the file - // stays minimal — assert they don't appear unless overridden. - expect(watcher.notification_priority).toBeUndefined(); - expect(watcher.notification_channel).toBeUndefined(); - expect(watcher.min_cooldown_seconds).toBeUndefined(); - }); - - test("watcher with reaction_script → writes sibling .ts and references it", async () => { - const out = mkTempDir(); - const fetchImpl = buildFetch({ - manage_entity_schema: () => ({ - entity_types: [], - relationship_types: [], - }), - "watchers?watcher_id": () => ({ - watcher: { - reaction_script: "export default async (ctx, client) => {};\n", - description: null, - }, - }), - "watchers?include_details": () => ({ - watchers: [ - { - slug: "with-reaction", - watcher_id: "42", - agent_id: "triage", - prompt: "Work.", - extraction_schema: { type: "object" }, - }, - ], - }), - }); - - await exportCommand({ - cwd: out, - out, - fetchImpl, - only: "models", - }); - - const reactionBody = readFileSync( - join(out, "models", "reactions", "with-reaction.reaction.ts"), - "utf-8" - ); - expect(reactionBody).toContain("export default async"); - - const bundle = parseYaml( - readFileSync(join(out, "models", "exported.yaml"), "utf-8") - ) as { watchers: Array> }; - expect(bundle.watchers[0]?.reaction_script).toBe( - "./reactions/with-reaction.reaction.ts" - ); - }); - - test("connections export writes type:connection + type:auth_profile docs (creds redacted)", async () => { - const out = mkTempDir(); - const fetchImpl = buildFetch({ - manage_entity_schema: () => ({ - entity_types: [], - relationship_types: [], - }), - "watchers?include_details": () => ({ watchers: [] }), - auth_profiles: () => ({ - auth_profiles: [ - { - slug: "gh-token", - display_name: "GitHub Token", - connector_key: "github", - profile_kind: "env", - status: "active", - }, - ], - }), - manage_connections: () => ({ - connections: [ - { - id: 7, - slug: "gh-main", - connector_key: "github", - display_name: "GitHub main", - status: "active", - auth_profile_slug: "gh-token", - config: { repo: "lobu-ai/lobu" }, - device_worker_id: null, - }, - ], - }), - manage_feeds: () => ({ feeds: [] }), - }); - - await exportCommand({ cwd: out, out, fetchImpl }); - - const raw = readFileSync(join(out, "connectors", "exported.yaml"), "utf-8"); - const docs = parseAllDocuments(raw) - .map((d) => d.toJSON()) - .filter((d) => d !== null); - expect(docs.length).toBe(2); - const profileDoc = docs.find((d) => d.type === "auth_profile"); - const connDoc = docs.find((d) => d.type === "connection"); - expect(profileDoc?.slug).toBe("gh-token"); - expect(profileDoc?.kind).toBe("env"); - // Credentials must never appear in the exported doc — the server doesn't - // expose them, and even if it did the CLI should never emit them. - expect("credentials" in (profileDoc ?? {})).toBe(false); - expect(connDoc?.slug).toBe("gh-main"); - expect(connDoc?.connector).toBe("github"); - expect(connDoc?.auth).toBe("gh-token"); - expect(connDoc?.config).toEqual({ repo: "lobu-ai/lobu" }); - }); - - test("skips reaction file when it already exists AND omits the YAML reference", async () => { - // Regression: previously, export would skip overwriting an existing - // local reaction file but still emit `reaction_script: ./reactions/...` - // in the YAML — re-applying would then upload whatever stale code was - // on disk instead of the server's actual script. Now the reference is - // dropped when we don't overwrite, and a warning is printed. - const out = mkTempDir(); - await mkdir(join(out, "models", "reactions"), { recursive: true }); - const localScript = - "// stale local version\nexport default async () => {};\n"; - writeFileSync( - join(out, "models", "reactions", "with-reaction.reaction.ts"), - localScript - ); - - const fetchImpl = buildFetch({ - manage_entity_schema: () => ({ - entity_types: [], - relationship_types: [], - }), - "watchers?watcher_id": () => ({ - watcher: { - reaction_script: "export default async () => 'NEW SERVER VERSION';\n", - description: null, - }, - }), - "watchers?include_details": () => ({ - watchers: [ - { - slug: "with-reaction", - watcher_id: "42", - agent_id: "triage", - prompt: "Work.", - extraction_schema: { type: "object" }, - }, - ], - }), - }); - - await exportCommand({ cwd: out, out, fetchImpl, only: "models" }); - - // Local script is untouched. - expect( - readFileSync( - join(out, "models", "reactions", "with-reaction.reaction.ts"), - "utf-8" - ) - ).toBe(localScript); - - // YAML does NOT reference reaction_script. - const bundle = parseYaml( - readFileSync(join(out, "models", "exported.yaml"), "utf-8") - ) as { watchers: Array> }; - expect(bundle.watchers[0]?.reaction_script).toBeUndefined(); - }); - - test("does not clobber existing files unless --force", async () => { - const out = mkTempDir(); - await mkdir(join(out, "models"), { recursive: true }); - const bundlePath = join(out, "models", "exported.yaml"); - writeFileSync(bundlePath, "pre-existing\n"); - - const fetchImpl = buildFetch({ - manage_entity_schema: () => ({ - entity_types: [], - relationship_types: [], - }), - "watchers?include_details": () => ({ watchers: [] }), - }); - - await exportCommand({ cwd: out, out, fetchImpl, only: "models" }); - expect(readFileSync(bundlePath, "utf-8")).toBe("pre-existing\n"); - - await exportCommand({ - cwd: out, - out, - fetchImpl, - only: "models", - force: true, - }); - expect(readFileSync(bundlePath, "utf-8")).not.toBe("pre-existing\n"); - }); -}); diff --git a/packages/cli/src/commands/_lib/export/export-cmd.ts b/packages/cli/src/commands/_lib/export/export-cmd.ts deleted file mode 100644 index 6adad3997..000000000 --- a/packages/cli/src/commands/_lib/export/export-cmd.ts +++ /dev/null @@ -1,430 +0,0 @@ -/** - * `lobu export` — pull server state into apply-compatible files. - * - * Round-trips with `lobu apply`: every file written here is a valid input for - * a future apply on the same (or another) org. Scope is intentionally narrow: - * memory models (entity types, relationship types, watchers including - * reaction scripts as sibling `.ts` files) and connectors (connections + - * auth_profile placeholders). Agent config / lobu.toml / SOUL.md aren't - * exported — those are author-time files that don't get edited in the UI. - * - * The default destination is `/models/exported.yaml` + - * `/connectors/exported.yaml`. Both write paths are skipped when the - * file exists unless `--force` is passed. - */ - -import { mkdir, readFile, writeFile } from "node:fs/promises"; -import { existsSync } from "node:fs"; -import { join, resolve } from "node:path"; -import chalk from "chalk"; -import { stringify as stringifyYaml } from "yaml"; -import { resolveApplyClient } from "../apply/client.js"; -import type { - ApplyClient, - RemoteAuthProfile, - RemoteConnection, - RemoteEntityType, - RemoteFeed, - RemoteRelationshipType, - RemoteWatcher, -} from "../apply/client.js"; -import { printText } from "../../memory/_lib/output.js"; - -export interface ExportOptions { - cwd?: string; - /** Override the destination directory (defaults to `cwd`). */ - out?: string; - /** Allow overwriting existing exported files. */ - force?: boolean; - /** Org slug (defaults to active session). */ - org?: string; - /** Server URL override. */ - url?: string; - /** Restrict to one resource family. */ - only?: "models" | "connectors"; - /** Test seam — inject fetch. */ - fetchImpl?: typeof fetch; -} - -interface ExportedFile { - /** Relative path under `out`. */ - path: string; - /** Body to write. */ - body: string; - /** Did we skip (existing file, no --force)? */ - skipped?: boolean; -} - -// ── Helpers ──────────────────────────────────────────────────────────────── - -function entityTypeDoc(e: RemoteEntityType): Record { - const out: Record = { - slug: e.slug, - ...(e.name ? { name: e.name } : {}), - ...(e.description ? { description: e.description } : {}), - }; - if ( - (e.required && e.required.length > 0) || - (e.properties && Object.keys(e.properties).length > 0) - ) { - const metadata: Record = {}; - if (e.required?.length) metadata.required = e.required; - if (e.properties && Object.keys(e.properties).length > 0) { - metadata.properties = e.properties; - } - out.metadata_schema = metadata; - } - return out; -} - -function relationshipTypeDoc( - r: RemoteRelationshipType -): Record { - const out: Record = { - slug: r.slug, - ...(r.name ? { name: r.name } : {}), - ...(r.description ? { description: r.description } : {}), - }; - if (r.rules?.length) out.rules = r.rules; - return out; -} - -function watcherDoc( - w: RemoteWatcher, - reactionScriptRelPath: string | undefined -): Record { - const out: Record = { - slug: w.slug, - ...(w.name ? { name: w.name } : {}), - ...(w.agent_id ? { agent: w.agent_id } : {}), - ...(w.description ? { description: w.description } : {}), - }; - if (w.schedule) out.schedule = w.schedule; - if (w.prompt) out.prompt = w.prompt; - if (w.extraction_schema && Object.keys(w.extraction_schema).length > 0) { - out.extraction_schema = w.extraction_schema; - } - if (w.sources?.length) out.sources = w.sources; - if (w.reactions_guidance) out.reactions_guidance = w.reactions_guidance; - if (reactionScriptRelPath) out.reaction_script = reactionScriptRelPath; - if (w.device_worker_id) out.device_worker_id = w.device_worker_id; - if (w.scheduler_client_id) out.scheduler_client_id = w.scheduler_client_id; - if (w.notification_channel && w.notification_channel !== "canvas") { - out.notification_channel = w.notification_channel; - } - if (w.notification_priority && w.notification_priority !== "normal") { - out.notification_priority = w.notification_priority; - } - if ( - w.min_cooldown_seconds !== undefined && - w.min_cooldown_seconds !== null && - w.min_cooldown_seconds !== 0 - ) { - out.min_cooldown_seconds = w.min_cooldown_seconds; - } - if (w.tags?.length) out.tags = w.tags; - if (w.agent_kind) out.agent_kind = w.agent_kind; - if (w.json_template) out.json_template = w.json_template; - if (w.keying_config && Object.keys(w.keying_config).length > 0) { - out.keying_config = w.keying_config; - } - if (w.classifiers?.length) out.classifiers = w.classifiers; - if (w.condensation_prompt) out.condensation_prompt = w.condensation_prompt; - if (w.condensation_window_count) { - out.condensation_window_count = w.condensation_window_count; - } - return out; -} - -function connectionDoc( - c: RemoteConnection, - feeds: RemoteFeed[] -): Record { - const out: Record = { - version: 1, - type: "connection", - slug: c.slug, - connector: c.connector_key, - ...(c.display_name ? { name: c.display_name } : {}), - ...(c.auth_profile_slug ? { auth: c.auth_profile_slug } : {}), - ...(c.app_auth_profile_slug ? { app_auth: c.app_auth_profile_slug } : {}), - }; - if (c.config && Object.keys(c.config).length > 0) out.config = c.config; - if (c.device_worker_id) out.device_worker_id = c.device_worker_id; - if (feeds.length > 0) { - out.feeds = feeds.map((f) => { - const feed: Record = { feed: f.feed_key }; - if (f.display_name) feed.name = f.display_name; - if (f.schedule) feed.schedule = f.schedule; - if (f.config && Object.keys(f.config).length > 0) feed.config = f.config; - return feed; - }); - } - return out; -} - -function authProfileDoc(p: RemoteAuthProfile): Record { - // We never export credentials — they're write-only on the server, and we - // mustn't emit literal secrets to disk. Operators fill credentials back in - // (typically via `$ENV` refs) before re-applying. - return { - version: 1, - type: "auth_profile", - slug: p.slug, - connector: p.connector_key, - kind: profileKindForExport(p.profile_kind), - ...(p.display_name ? { name: p.display_name } : {}), - }; -} - -function profileKindForExport(kind: string): string { - // Server returns its canonical kind; CLI consumes the same names. No mapping - // needed today — this stub exists to keep one place to centralize any - // future divergence. - return kind; -} - -async function loadFeedsByConnection( - client: ApplyClient, - connections: RemoteConnection[] -): Promise> { - const out = new Map(); - for (const conn of connections) { - out.set(conn.id, await client.listFeeds(conn.id)); - } - return out; -} - -/** Write a file if it doesn't exist, or overwrite when `force`. */ -async function writeIfFreeOrForced( - absPath: string, - body: string, - force: boolean -): Promise<{ skipped: boolean }> { - if (existsSync(absPath) && !force) { - return { skipped: true }; - } - await mkdir(resolve(absPath, ".."), { recursive: true }); - await writeFile(absPath, body, "utf-8"); - return { skipped: false }; -} - -// ── Multi-doc YAML helpers ───────────────────────────────────────────────── - -function modelBundleYaml( - entityTypes: RemoteEntityType[], - relationshipTypes: RemoteRelationshipType[], - watchers: Array<{ - watcher: RemoteWatcher; - reactionScriptRelPath: string | undefined; - }> -): string { - // Single dbt-style bundle so apply's loader handles it. Empty sections are - // omitted to keep the file tidy. - const bundle: Record = { version: 2 }; - if (entityTypes.length > 0) { - bundle.entities = entityTypes.map(entityTypeDoc); - } - if (relationshipTypes.length > 0) { - bundle.relationships = relationshipTypes.map(relationshipTypeDoc); - } - if (watchers.length > 0) { - bundle.watchers = watchers.map(({ watcher, reactionScriptRelPath }) => - watcherDoc(watcher, reactionScriptRelPath) - ); - } - return stringifyYaml(bundle, { lineWidth: 0, blockQuote: "literal" }); -} - -function connectorBundleYaml( - connections: RemoteConnection[], - feedsByConnection: Map, - authProfiles: RemoteAuthProfile[] -): string { - // Multi-document YAML stream — one doc per connection / auth_profile, the - // shape `loadConnectors` already understands. - const docs: Record[] = []; - for (const p of authProfiles) docs.push(authProfileDoc(p)); - for (const c of connections) { - docs.push(connectionDoc(c, feedsByConnection.get(c.id) ?? [])); - } - return docs - .map((doc) => stringifyYaml(doc, { lineWidth: 0, blockQuote: "literal" })) - .join("---\n"); -} - -// ── Top-level ────────────────────────────────────────────────────────────── - -export async function exportCommand(opts: ExportOptions = {}): Promise { - const cwd = opts.cwd ?? process.cwd(); - const out = resolve(cwd, opts.out ?? "."); - const force = !!opts.force; - - const { client, orgSlug } = await resolveApplyClient({ - url: opts.url, - org: opts.org, - fetchImpl: opts.fetchImpl, - }); - printText(chalk.dim(`Exporting from org: ${orgSlug}`)); - printText(chalk.dim(`Destination: ${out}`)); - - const wantModels = !opts.only || opts.only === "models"; - const wantConnectors = !opts.only || opts.only === "connectors"; - - const written: ExportedFile[] = []; - - if (wantModels) { - const [entityTypes, relationshipTypes, watchers] = await Promise.all([ - client.listEntityTypes(), - client.listRelationshipTypes(), - client.listWatchers(), - ]); - - // Reaction scripts aren't on the list response — fetch each watcher's - // detail to pick up `reaction_script`. Sequential to keep load on the - // server bounded; a per-watcher GET is cheap. - const withReactions: Array<{ - watcher: RemoteWatcher; - reactionScriptRelPath: string | undefined; - }> = []; - for (const w of watchers) { - let reactionScriptRelPath: string | undefined; - if (w.watcher_id) { - const detail = await client.getWatcherDetail(w.watcher_id); - const script = detail?.reaction_script ?? null; - if (script) { - // Defensive slug sanitization — the watcher slug is used as a - // filesystem path component below. The server's slug constraint - // should already keep this safe, but a stale or corrupted row could - // contain `..` or `/`. Reject anything that isn't a tight basename. - const safeSlug = String(w.slug); - if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(safeSlug)) { - printText( - chalk.yellow( - ` ⚠ skipping reaction script for watcher slug "${safeSlug}" — slug is not a safe filename basename; export the watcher manually if needed.` - ) - ); - } else { - const rel = `reactions/${safeSlug}.reaction.ts`; - const abs = join(out, "models", rel); - const res = await writeIfFreeOrForced(abs, script, force); - // When the local file exists and --force isn't set, don't emit a - // `reaction_script:` reference — re-applying would otherwise - // upload whatever stale code happens to be on disk, masking the - // server's actual script. Loudly warn so the operator notices. - if (res.skipped) { - printText( - chalk.yellow( - ` ⚠ keeping existing ${rel}; YAML will NOT reference the server script (re-run with --force to overwrite and re-link).` - ) - ); - written.push({ - path: join("models", rel), - body: script, - skipped: true, - }); - } else { - written.push({ - path: join("models", rel), - body: script, - }); - reactionScriptRelPath = `./${rel}`; - } - } - } - if (detail?.description && !w.description) { - w.description = detail.description; - } - } - withReactions.push({ watcher: w, reactionScriptRelPath }); - } - - const bundleBody = modelBundleYaml( - entityTypes, - relationshipTypes, - withReactions - ); - const bundlePath = join(out, "models", "exported.yaml"); - const res = await writeIfFreeOrForced(bundlePath, bundleBody, force); - written.push({ - path: join("models", "exported.yaml"), - body: bundleBody, - ...(res.skipped ? { skipped: true } : {}), - }); - } - - if (wantConnectors) { - const [authProfiles, connections] = await Promise.all([ - client.listAuthProfiles(), - client.listConnections(), - ]); - if (authProfiles.length > 0 || connections.length > 0) { - const feedsByConnection = await loadFeedsByConnection( - client, - connections - ); - const body = connectorBundleYaml( - connections, - feedsByConnection, - authProfiles - ); - const path = join(out, "connectors", "exported.yaml"); - const res = await writeIfFreeOrForced(path, body, force); - written.push({ - path: join("connectors", "exported.yaml"), - body, - ...(res.skipped ? { skipped: true } : {}), - }); - } - } - - // ── Report ──────────────────────────────────────────────────────────────── - if (written.length === 0) { - printText( - chalk.dim( - "\nNothing to export — server has no models or connectors for this org." - ) - ); - return; - } - const skipped = written.filter((w) => w.skipped); - const wrote = written.filter((w) => !w.skipped); - if (wrote.length > 0) { - printText(chalk.bold("\nWrote:")); - for (const w of wrote) printText(` ${chalk.green("+")} ${w.path}`); - } - if (skipped.length > 0) { - printText( - chalk.bold("\nSkipped (file exists — use --force to overwrite):") - ); - for (const w of skipped) printText(` ${chalk.yellow("·")} ${w.path}`); - } - // Auth profiles are kind-only — flag any oauth_app/env profile in the export - // so the operator knows they need to re-add `credentials:` (or `$ENV` refs) - // before the next apply. Quick re-read of the file to find their slugs is - // overkill; instead print the list directly from what we exported. - if (wantConnectors) { - const authProfiles = await client.listAuthProfiles(); - const credentialed = authProfiles.filter( - (p) => p.profile_kind === "env" || p.profile_kind === "oauth_app" - ); - if (credentialed.length > 0) { - printText( - chalk.bold( - "\nNote — credentials are write-only on the server, not exported:" - ) - ); - for (const p of credentialed) { - printText( - ` ${chalk.yellow("·")} auth_profile "${p.slug}" (${p.profile_kind}) — re-add \`credentials:\` (typically with \`$ENV\` refs) before applying.` - ); - } - } - } -} - -// Stub kept for the future if we want to validate the export against the -// loaded desired-state. Today exported files round-trip through -// `loadDesiredState` directly because they share the same schema, so we don't -// re-validate here. Imports kept to satisfy the bundler if this lib grows. -export const __exportInternals = { readFile }; diff --git a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts new file mode 100644 index 000000000..46b24df58 --- /dev/null +++ b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts @@ -0,0 +1,376 @@ +/** + * Tests for `lobu init --from-org`. + * + * The canonical gate: bootstrap a project from stubbed cloud state, then load + * the generated `lobu.config.ts` back through `loadDesiredStateFromConfig` and + * assert the resulting DesiredState matches the stubbed cloud input + * (entities/relationships/watchers/connections/authProfiles/agents), modulo + * write-only secret values (placeholders) and `installedAt` timestamps. + * + * Network is stubbed through an injected fetch impl returning the canned + * responses listAgents / listEntityTypes / etc. produce. The fixture dir lives + * UNDER `import.meta.dir` so jiti resolves the externalized `@lobu/sdk`. + */ +import { afterEach, beforeEach, describe, expect, test } from "bun:test"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { loadDesiredStateFromConfig } from "../../apply/desired-state.js"; +import { initFromOrg } from "../bootstrap.js"; + +const tempDirs: string[] = []; + +function mkFixtureDir(): string { + const dir = mkdtempSync(join(import.meta.dir, "fixture-")); + tempDirs.push(dir); + return dir; +} + +function buildFetch(routes: Record unknown>): typeof fetch { + return (async (input: RequestInfo | URL, _init?: RequestInit) => { + const url = String(input); + // Order matters — match the most specific patterns first. + for (const [pattern, handler] of Object.entries(routes)) { + if (url.includes(pattern)) { + return new Response(JSON.stringify(handler()), { status: 200 }); + } + } + throw new Error(`unexpected fetch: ${url}`); + }) as typeof fetch; +} + +const ORIG_ENV: Record = {}; + +beforeEach(() => { + for (const key of [ + "LOBU_API_URL", + "LOBU_TOKEN", + "LOBU_ORG", + "LOBU_CONTEXT_DIR", + ]) { + ORIG_ENV[key] = process.env[key]; + } + process.env.LOBU_API_URL = "https://example.test"; + process.env.LOBU_TOKEN = "test-token"; + process.env.LOBU_ORG = "acme"; +}); + +afterEach(() => { + for (const [key, val] of Object.entries(ORIG_ENV)) { + if (val === undefined) delete process.env[key]; + else process.env[key] = val; + } + while (tempDirs.length > 0) { + const d = tempDirs.pop(); + if (d) rmSync(d, { recursive: true, force: true }); + } +}); + +/** Stubbed cloud state covering every resource family the bootstrap maps. */ +function fullOrgRoutes(): Record unknown> { + return { + "/oauth/userinfo": () => ({ + organizations: [{ id: "org-1", slug: "acme", name: "Acme Inc" }], + }), + "/agents/sales/config": () => ({ + installedProviders: [{ providerId: "anthropic", installedAt: 111 }], + providerModelPreferences: { anthropic: "claude/sonnet-4-5" }, + modelSelection: { mode: "auto" }, + networkConfig: { + allowedDomains: ["github.com", ".github.com"], + deniedDomains: ["evil.com"], + }, + toolsConfig: { allowedTools: ["Read"], strictMode: true }, + preApprovedTools: ["/mcp/gmail/tools/send_email"], + guardrails: ["secret-scan"], + nixConfig: { packages: ["jq", "ffmpeg"] }, + soulMd: "Be concise.", + identityMd: "You are sales.", + updatedAt: 0, + }), + // listAgents + "/agents": () => ({ + agents: [ + { agentId: "sales", name: "Sales", description: "Revenue agent" }, + ], + }), + "watchers?watcher_id": () => ({ + watcher: { + reaction_script: + "export default async (ctx, client) => {\n await client.knowledge.save({ content: 'ok', semantic_type: 'digest' });\n};\n", + description: null, + }, + }), + "watchers?include_details": () => ({ + watchers: [ + { + slug: "account-health", + watcher_id: "1", + name: "Account health", + agent_id: "sales", + prompt: "Poll CRM data.", + extraction_schema: { + type: "object", + required: ["risk_level"], + properties: { risk_level: { type: "string" } }, + }, + schedule: "0 */12 * * *", + sources: [{ name: "content", query: "SELECT * FROM events" }], + tags: ["sales", "health"], + notification_channel: "both", + notification_priority: "high", + min_cooldown_seconds: 1800, + }, + ], + }), + manage_entity_schema: () => { + // The mapper uses a single endpoint for both entity_type and + // relationship_type list actions; return a body carrying both keys. + return { + entity_types: [ + { + slug: "lead", + name: "Lead", + description: "A sales lead", + required: ["stage"], + properties: { + stage: { type: "string", "x-table-label": "Stage" }, + }, + }, + { slug: "pilot", name: "Pilot" }, + ], + relationship_types: [ + { + slug: "converted-to", + name: "Converted To", + description: "Lead to pilot", + rules: [{ source: "lead", target: "pilot" }], + }, + ], + }; + }, + manage_auth_profiles: () => ({ + auth_profiles: [ + { + slug: "github-account", + display_name: "GitHub account", + connector_key: "github", + profile_kind: "oauth_account", + status: "active", + }, + { + slug: "github-app", + display_name: "GitHub OAuth App", + connector_key: "github", + profile_kind: "oauth_app", + status: "active", + }, + ], + }), + manage_connections: () => ({ + connections: [ + { + id: 7, + slug: "github-lobu", + connector_key: "github", + display_name: "GitHub — lobu", + status: "active", + auth_profile_slug: "github-account", + app_auth_profile_slug: "github-app", + config: { repo_owner: "lobu-ai", repo_name: "lobu" }, + device_worker_id: null, + }, + ], + }), + manage_feeds: () => ({ + feeds: [ + { + id: 1, + connection_id: 7, + feed_key: "stargazers", + display_name: "Stars", + status: "active", + schedule: "0 */6 * * *", + config: { repo_owner: "lobu-ai", repo_name: "lobu" }, + }, + ], + }), + }; +} + +describe("lobu init --from-org", () => { + test("bootstraps a project that round-trips through loadDesiredStateFromConfig", async () => { + const dir = mkFixtureDir(); + await initFromOrg({ + targetDir: dir, + fetchImpl: buildFetch(fullOrgRoutes()), + }); + + // The config file exists and references the org metadata. + const source = readFileSync(join(dir, "lobu.config.ts"), "utf-8"); + expect(source).toContain('org: "acme"'); + expect(source).toContain('orgName: "Acme Inc"'); + + // The bootstrap wrote the agent-dir markdown + the reaction script. + expect(readFileSync(join(dir, "agents", "sales", "SOUL.md"), "utf-8")).toBe( + "Be concise.\n" + ); + expect( + readFileSync( + join(dir, "reactions", "account-health.reaction.ts"), + "utf-8" + ) + ).toContain("client.knowledge.save"); + expect(readFileSync(join(dir, ".env.example"), "utf-8")).toContain( + "ANTHROPIC_API_KEY=" + ); + + // Round-trip: load the generated config back to DesiredState. + const env = { ANTHROPIC_API_KEY: "sk-test" } as NodeJS.ProcessEnv; + const { state } = await loadDesiredStateFromConfig({ cwd: dir, env }); + + // ── agents ─────────────────────────────────────────────────────────── + expect(state.memory).toEqual({ org: "acme", name: "Acme Inc" }); + const agent = state.agents[0]; + expect(agent?.metadata).toEqual({ + agentId: "sales", + name: "Sales", + description: "Revenue agent", + }); + expect(agent?.settings.installedProviders?.[0]?.providerId).toBe( + "anthropic" + ); + expect(agent?.settings.providerModelPreferences).toEqual({ + anthropic: "claude/sonnet-4-5", + }); + expect(agent?.settings.networkConfig).toEqual({ + allowedDomains: ["github.com", ".github.com"], + deniedDomains: ["evil.com"], + }); + expect(agent?.settings.toolsConfig).toEqual({ + allowedTools: ["Read"], + strictMode: true, + }); + expect(agent?.settings.preApprovedTools).toEqual([ + "/mcp/gmail/tools/send_email", + ]); + expect(agent?.settings.guardrails).toEqual(["secret-scan"]); + expect(agent?.settings.nixConfig?.packages).toEqual(["jq", "ffmpeg"]); + expect(agent?.settings.soulMd).toBe("Be concise."); + expect(agent?.settings.identityMd).toBe("You are sales."); + // Secret resolves from env to the real value (write-only placeholder filled). + expect(agent?.providerKeys).toEqual([ + { providerId: "anthropic", value: "sk-test" }, + ]); + expect(state.requiredSecrets).toContain("ANTHROPIC_API_KEY"); + + // ── memory schema ────────────────────────────────────────────────────── + expect(state.memorySchema.entityTypes.map((e) => e.slug)).toEqual([ + "lead", + "pilot", + ]); + expect(state.memorySchema.entityTypes[0]).toEqual({ + slug: "lead", + name: "Lead", + description: "A sales lead", + required: ["stage"], + properties: { stage: { type: "string", "x-table-label": "Stage" } }, + }); + expect(state.memorySchema.relationshipTypes[0]).toEqual({ + slug: "converted-to", + name: "Converted To", + description: "Lead to pilot", + rules: [{ source: "lead", target: "pilot" }], + }); + + // ── watchers ─────────────────────────────────────────────────────────── + const w = state.watchers[0]; + expect(w?.slug).toBe("account-health"); + expect(w?.agent).toBe("sales"); + expect(w?.name).toBe("Account health"); + expect(w?.prompt).toBe("Poll CRM data."); + expect(w?.schedule).toBe("0 */12 * * *"); + expect(w?.extractionSchema).toEqual({ + type: "object", + required: ["risk_level"], + properties: { risk_level: { type: "string" } }, + }); + expect(w?.sources).toEqual([ + { name: "content", query: "SELECT * FROM events" }, + ]); + expect(w?.tags).toEqual(["sales", "health"]); + expect(w?.notificationChannel).toBe("both"); + expect(w?.notificationPriority).toBe("high"); + expect(w?.minCooldownSeconds).toBe(1800); + expect(w?.reactionScript?.sourceCode).toContain("client.knowledge.save"); + + // ── auth profiles ────────────────────────────────────────────────────── + expect(state.connectors.authProfiles).toHaveLength(2); + const ghAccount = state.connectors.authProfiles.find( + (p) => p.slug === "github-account" + ); + const ghApp = state.connectors.authProfiles.find( + (p) => p.slug === "github-app" + ); + expect(ghAccount).toMatchObject({ + slug: "github-account", + connector: "github", + kind: "oauth_account", + name: "GitHub account", + }); + // Interactive kind → no credentials. + expect(ghAccount?.credentials).toBeUndefined(); + expect(ghApp).toMatchObject({ + slug: "github-app", + connector: "github", + kind: "oauth_app", + }); + // oauth_app credentials are placeholder env refs (write-only on the server). + expect(Object.keys(ghApp?.credentials ?? {})).toContain( + "GITHUB_APP_CLIENT_SECRET" + ); + + // ── connections ──────────────────────────────────────────────────────── + const conn = state.connectors.connections[0]; + expect(conn?.slug).toBe("github-lobu"); + expect(conn?.connector).toBe("github"); + expect(conn?.name).toBe("GitHub — lobu"); + expect(conn?.authProfileSlug).toBe("github-account"); + expect(conn?.appAuthProfileSlug).toBe("github-app"); + expect(conn?.config).toEqual({ repo_owner: "lobu-ai", repo_name: "lobu" }); + expect(conn?.feeds).toEqual([ + { + feedKey: "stargazers", + name: "Stars", + schedule: "0 */6 * * *", + config: { repo_owner: "lobu-ai", repo_name: "lobu" }, + }, + ]); + }); + + test("empty org → minimal config that still round-trips", async () => { + const dir = mkFixtureDir(); + await initFromOrg({ + targetDir: dir, + fetchImpl: buildFetch({ + "/oauth/userinfo": () => ({ + organizations: [{ id: "org-1", slug: "acme", name: "Acme Inc" }], + }), + "/agents/lone/config": () => ({ updatedAt: 0 }), + "/agents": () => ({ agents: [{ agentId: "lone", name: "Lone" }] }), + "watchers?include_details": () => ({ watchers: [] }), + manage_entity_schema: () => ({ + entity_types: [], + relationship_types: [], + }), + manage_auth_profiles: () => ({ auth_profiles: [] }), + manage_connections: () => ({ connections: [] }), + }), + }); + + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + expect(state.agents[0]?.metadata.agentId).toBe("lone"); + expect(state.memorySchema.entityTypes).toHaveLength(0); + expect(state.watchers).toHaveLength(0); + expect(state.connectors.connections).toHaveLength(0); + }); +}); diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts new file mode 100644 index 000000000..1e1d2da99 --- /dev/null +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -0,0 +1,952 @@ +/** + * `lobu init --from-org ` — bootstrap a complete, re-appliable project + * from an existing Lobu Cloud org. The inverse of `lobu apply`: it reads the + * org's full declared state through the apply client and writes a runnable + * `lobu.config.ts` (plus the file-convention artifacts it references) that + * round-trips back through `loadDesiredStateFromConfig`. + * + * Contract: `load(initFromOrg(org)) ≈ org`, modulo write-only secrets — provider + * keys, auth-profile credentials, and MCP client secrets become `secret("ENV")` + * placeholders (listed in `.env.example`), never real values. + * + * This is the inverse of `map-config.ts`'s `mapAgent` / `mapEntityType` / etc: + * server → SDK authoring objects → emitted TypeScript source. + */ + +import { mkdir, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import type { AgentSettings } from "@lobu/core"; +import chalk from "chalk"; +import { resolveApplyClient } from "../apply/client.js"; +import type { + ApplyClient, + RemoteAgent, + RemoteAuthProfile, + RemoteConnection, + RemoteEntityType, + RemoteFeed, + RemoteRelationshipType, + RemoteWatcher, +} from "../apply/client.js"; +import { printText } from "../../memory/_lib/output.js"; + +export interface InitFromOrgOptions { + /** Target directory to scaffold into (must be empty / not a Lobu project). */ + targetDir: string; + /** Org slug to bootstrap from (defaults to active session). */ + org?: string; + /** Server URL override. */ + url?: string; + /** Test seam — inject fetch. */ + fetchImpl?: typeof fetch; +} + +// ── TS literal emission ────────────────────────────────────────────────────── + +/** A `const = ;` handle plus the identifier to reference it by. */ +interface Handle { + name: string; + decl: string; +} + +/** Quote a string as a TS string literal (double quotes, JSON-escaped). */ +function str(value: string): string { + return JSON.stringify(value); +} + +/** + * Emit a JS value as pretty TS source. Handles the JSON-Schema objects in + * entity `properties` / watcher `extractionSchema` and arbitrary connection + * `config` blobs as real object/array literals (not `JSON.stringify` blobs), + * with object keys unquoted where they're valid identifiers. + */ +function emitValue(value: unknown, indent: number): string { + const pad = " ".repeat(indent); + const padInner = " ".repeat(indent + 1); + if (value === null) return "null"; + if (typeof value === "string") return str(value); + if (typeof value === "number" || typeof value === "boolean") { + return String(value); + } + if (Array.isArray(value)) { + if (value.length === 0) return "[]"; + // Inline short arrays of primitives (mirrors Prettier output) so e.g. + // `required: ["stage"]` and `tags: ["a", "b"]` don't sprawl over many lines. + const allPrimitive = value.every( + (v) => + v === null || + typeof v === "string" || + typeof v === "number" || + typeof v === "boolean" + ); + if (allPrimitive) { + const inline = `[${value.map((v) => emitValue(v, 0)).join(", ")}]`; + if (inline.length <= 72) return inline; + } + const items = value.map((v) => `${padInner}${emitValue(v, indent + 1)}`); + return `[\n${items.join(",\n")},\n${pad}]`; + } + if (typeof value === "object") { + const entries = Object.entries(value as Record); + if (entries.length === 0) return "{}"; + const lines = entries.map( + ([k, v]) => `${padInner}${emitKey(k)}: ${emitValue(v, indent + 1)}` + ); + return `{\n${lines.join(",\n")},\n${pad}}`; + } + // undefined / function — should never reach here for declared state. + return "undefined"; +} + +const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/; +function emitKey(key: string): string { + return IDENT.test(key) ? key : str(key); +} + +/** + * Render an object's fields as the body of an object literal (one field per + * line at `indent`+1). `fields` are pre-rendered `key: value` strings; empty + * entries are dropped so omitted/default fields never appear. + */ +function objectLiteral(fields: string[], indent = 0): string { + const pad = " ".repeat(indent); + const padInner = " ".repeat(indent + 1); + const present = fields.filter((f) => f.length > 0); + if (present.length === 0) return "{}"; + return `{\n${present.map((f) => `${padInner}${f}`).join(",\n")},\n${pad}}`; +} + +// ── Identifier minting ─────────────────────────────────────────────────────── + +/** Turn a slug/id into a safe, unique camelCase const identifier. */ +class IdentMinter { + private readonly used = new Set(); + + mint(base: string, suffix = ""): string { + let camel = base + .replace(/[^A-Za-z0-9]+(.)?/g, (_, c: string | undefined) => + c ? c.toUpperCase() : "" + ) + .replace(/^[0-9]+/, ""); + if (!camel) camel = "item"; + if (!/^[A-Za-z_$]/.test(camel)) camel = `_${camel}`; + let candidate = `${camel}${suffix}`; + let n = 2; + while (this.used.has(candidate)) { + candidate = `${camel}${suffix}${n++}`; + } + this.used.add(candidate); + return candidate; + } +} + +// ── Secret placeholders ────────────────────────────────────────────────────── + +/** + * Collects env-var names emitted as `secret("NAME")` placeholders so we can + * write a `.env.example`. Credentials are write-only on the server; we never + * read or emit real values. + */ +class SecretCollector { + readonly names = new Set(); + + /** Register a var name and return the `secret("NAME")` TS expression. */ + ref(name: string): string { + this.names.add(name); + return `secret(${str(name)})`; + } +} + +/** Uppercase env-var name from a slug/key (e.g. `gh-token` → `GH_TOKEN_API_KEY`). */ +function envVarFor(slug: string, suffix: string): string { + const base = slug.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase(); + return `${base}_${suffix}`; +} + +// ── Imports tracking ───────────────────────────────────────────────────────── + +const IMPORTABLE = [ + "defineAgent", + "defineConfig", + "defineEntityType", + "defineRelationshipType", + "defineWatcher", + "defineConnection", + "defineAuthProfile", + "secret", +] as const; +type Importable = (typeof IMPORTABLE)[number]; + +class ImportTracker { + private readonly used = new Set(); + use(name: Importable): void { + this.used.add(name); + } + render(): string { + const names = IMPORTABLE.filter((n) => this.used.has(n)).sort(); + return `import {\n${names.map((n) => ` ${n}`).join(",\n")},\n} from "@lobu/sdk";`; + } +} + +// ── Agent settings → SDK agent (inverse of mapAgent) ──────────────────────── + +interface EmittedAgent { + handle: Handle; + /** Markdown + skill files to write under the agent dir. */ + files: Array<{ relPath: string; body: string }>; +} + +function emitAgent( + agent: RemoteAgent, + settings: AgentSettings | null, + imports: ImportTracker, + secrets: SecretCollector, + minter: IdentMinter +): EmittedAgent { + imports.use("defineAgent"); + const fields: string[] = [`id: ${str(agent.agentId)}`]; + fields.push(`name: ${str(agent.name || agent.agentId)}`); + if (agent.description) fields.push(`description: ${str(agent.description)}`); + fields.push(`dir: ${str(`./agents/${agent.agentId}`)}`); + + const files: Array<{ relPath: string; body: string }> = []; + const dir = `agents/${agent.agentId}`; + + // providers ← installedProviders + providerModelPreferences (+ secret key). + const providers = settings?.installedProviders ?? []; + if (providers.length > 0) { + const prefs = settings?.providerModelPreferences ?? {}; + imports.use("secret"); + const items = providers.map((p) => { + const id = p.providerId; + const model = prefs[id]; + const envVar = envVarFor(id, "API_KEY"); + const provFields = [ + `id: ${str(id)}`, + ...(model ? [`model: ${str(model)}`] : []), + `key: ${secrets.ref(envVar)}`, + ]; + return objectLiteral(provFields, 2); + }); + fields.push(`providers: [\n ${items.join(",\n ")},\n ]`); + } + + // network ← networkConfig (allowed/denied/judged/judges). + const net = settings?.networkConfig; + if (net) { + const netFields: string[] = []; + if (net.allowedDomains?.length) { + netFields.push(`allowed: ${emitValue(net.allowedDomains, 2)}`); + } + if (net.deniedDomains?.length) { + netFields.push(`denied: ${emitValue(net.deniedDomains, 2)}`); + } + if (net.judgedDomains?.length) { + netFields.push( + `judged: ${emitValue( + net.judgedDomains.map((r) => ({ + domain: r.domain, + ...(r.judge ? { judge: r.judge } : {}), + })), + 2 + )}` + ); + } + if (net.judges && Object.keys(net.judges).length > 0) { + netFields.push(`judges: ${emitValue(net.judges, 2)}`); + } + if (netFields.length > 0) { + fields.push(`network: ${objectLiteral(netFields, 1)}`); + } + } + + // egress ← egressConfig. + const egress = settings?.egressConfig; + if (egress && (egress.extraPolicy || egress.judgeModel)) { + const egFields: string[] = []; + if (egress.extraPolicy) { + egFields.push(`extraPolicy: ${str(egress.extraPolicy)}`); + } + if (egress.judgeModel) + egFields.push(`judgeModel: ${str(egress.judgeModel)}`); + fields.push(`egress: ${objectLiteral(egFields, 1)}`); + } + + // tools ← toolsConfig + preApprovedTools. + const tools = settings?.toolsConfig; + const preApproved = settings?.preApprovedTools; + if ( + preApproved?.length || + tools?.allowedTools?.length || + tools?.deniedTools?.length || + tools?.strictMode !== undefined + ) { + const toolFields: string[] = []; + if (preApproved?.length) { + toolFields.push(`preApproved: ${emitValue(preApproved, 2)}`); + } + if (tools?.allowedTools?.length) { + toolFields.push(`allowed: ${emitValue(tools.allowedTools, 2)}`); + } + if (tools?.deniedTools?.length) { + toolFields.push(`denied: ${emitValue(tools.deniedTools, 2)}`); + } + if (tools?.strictMode !== undefined) { + toolFields.push(`strict: ${tools.strictMode}`); + } + fields.push(`tools: ${objectLiteral(toolFields, 1)}`); + } + + // guardrails ← guardrails[]. + if (settings?.guardrails?.length) { + fields.push(`guardrails: ${emitValue(settings.guardrails, 1)}`); + } + + // nixPackages ← nixConfig.packages. + if (settings?.nixConfig?.packages?.length) { + fields.push(`nixPackages: ${emitValue(settings.nixConfig.packages, 1)}`); + } + + // mcpServers ← mcpServers (client secrets → secret placeholders). + const mcp = settings?.mcpServers; + if (mcp && Object.keys(mcp).length > 0) { + fields.push(`mcpServers: ${emitMcpServers(mcp, secrets)}`); + } + + // Agent-dir markdown. + if (settings?.soulMd) { + files.push({ + relPath: `${dir}/SOUL.md`, + body: ensureTrailingNewline(settings.soulMd), + }); + } + if (settings?.identityMd) { + files.push({ + relPath: `${dir}/IDENTITY.md`, + body: ensureTrailingNewline(settings.identityMd), + }); + } + if (settings?.userMd) { + files.push({ + relPath: `${dir}/USER.md`, + body: ensureTrailingNewline(settings.userMd), + }); + } + + // Local skills → skills//SKILL.md (with frontmatter for net/nix/mcp). + for (const skill of settings?.skillsConfig?.skills ?? []) { + if (skill.repo && !skill.repo.startsWith("local/")) continue; + files.push({ + relPath: `${dir}/skills/${skill.name}/SKILL.md`, + body: emitSkillFile(skill), + }); + } + + const handleName = minter.mint(agent.agentId, "Agent"); + const decl = `const ${handleName} = defineAgent(${objectLiteral(fields, 0)});`; + return { handle: { name: handleName, decl }, files }; +} + +function emitMcpServers( + mcp: NonNullable, + secrets: SecretCollector +): string { + const entries = Object.entries(mcp).sort(([a], [b]) => a.localeCompare(b)); + const lines = entries.map(([id, server]) => { + const sFields: string[] = []; + if (server.url) sFields.push(`url: ${str(server.url)}`); + if (server.type) sFields.push(`type: ${str(server.type)}`); + if (server.command) sFields.push(`command: ${str(server.command)}`); + if (server.args?.length) sFields.push(`args: ${emitValue(server.args, 3)}`); + if (server.headers && Object.keys(server.headers).length > 0) { + sFields.push(`headers: ${emitValue(server.headers, 3)}`); + } + if (server.env && Object.keys(server.env).length > 0) { + sFields.push(`env: ${emitValue(server.env, 3)}`); + } + // oauth + authScope live on the stored config under a loose cast. + const loose = server as Record; + if (typeof loose.authScope === "string") { + sFields.push(`authScope: ${str(loose.authScope)}`); + } + if (loose.oauth && typeof loose.oauth === "object") { + sFields.push( + `oauth: ${emitMcpOAuth(loose.oauth as Record, secrets, id)}` + ); + } + return `${str(id)}: ${objectLiteral(sFields, 2)}`; + }); + return `{\n ${lines.join(",\n ")},\n }`; +} + +function emitMcpOAuth( + oauth: Record, + secrets: SecretCollector, + serverId: string +): string { + const fields: string[] = []; + if (typeof oauth.authUrl === "string") + fields.push(`authUrl: ${str(oauth.authUrl)}`); + if (typeof oauth.tokenUrl === "string") { + fields.push(`tokenUrl: ${str(oauth.tokenUrl)}`); + } + if (typeof oauth.clientId === "string") { + fields.push(`clientId: ${str(oauth.clientId)}`); + } + if (oauth.clientSecret !== undefined) { + // Write-only — never emit the stored value. + fields.push( + `clientSecret: ${secrets.ref(envVarFor(serverId, "MCP_CLIENT_SECRET"))}` + ); + } + if (Array.isArray(oauth.scopes)) { + fields.push(`scopes: ${emitValue(oauth.scopes, 3)}`); + } + if (typeof oauth.tokenEndpointAuthMethod === "string") { + fields.push( + `tokenEndpointAuthMethod: ${str(oauth.tokenEndpointAuthMethod)}` + ); + } + return objectLiteral(fields, 3); +} + +function emitSkillFile( + skill: NonNullable["skills"][number] +): string { + const fm: string[] = [`name: ${skill.name}`]; + if (skill.description) fm.push(`description: ${skill.description}`); + const net = skill.networkConfig; + if ( + net?.allowedDomains?.length || + net?.deniedDomains?.length || + net?.judgedDomains?.length + ) { + fm.push("network:"); + if (net?.allowedDomains?.length) { + fm.push(` allow: [${net.allowedDomains.map((d) => str(d)).join(", ")}]`); + } + if (net?.deniedDomains?.length) { + fm.push(` deny: [${net.deniedDomains.map((d) => str(d)).join(", ")}]`); + } + } + if (skill.nixPackages?.length) { + fm.push( + `nixPackages: [${skill.nixPackages.map((p) => str(p)).join(", ")}]` + ); + } + const body = skill.content ?? ""; + return `---\n${fm.join("\n")}\n---\n${body}\n`; +} + +function ensureTrailingNewline(s: string): string { + return s.endsWith("\n") ? s : `${s}\n`; +} + +// ── Entity / relationship / watcher / connection / auth (inverse maps) ────── + +function emitEntityType( + e: RemoteEntityType, + imports: ImportTracker, + minter: IdentMinter +): Handle { + imports.use("defineEntityType"); + const fields: string[] = [`key: ${str(e.slug)}`]; + if (e.name) fields.push(`name: ${str(e.name)}`); + if (e.description) fields.push(`description: ${str(e.description)}`); + if (e.required?.length) fields.push(`required: ${emitValue(e.required, 1)}`); + if (e.properties && Object.keys(e.properties).length > 0) { + fields.push(`properties: ${emitValue(e.properties, 1)}`); + } + const name = minter.mint(e.slug, "Entity"); + return { + name, + decl: `const ${name} = defineEntityType(${objectLiteral(fields, 0)});`, + }; +} + +function emitRelationshipType( + r: RemoteRelationshipType, + entityHandles: Map, + imports: ImportTracker, + minter: IdentMinter +): Handle { + imports.use("defineRelationshipType"); + const fields: string[] = [`key: ${str(r.slug)}`]; + if (r.name) fields.push(`name: ${str(r.name)}`); + if (r.description) fields.push(`description: ${str(r.description)}`); + if (r.rules?.length) { + const rules = r.rules.map((rule) => { + const source = entityHandles.get(rule.source) ?? str(rule.source); + const target = entityHandles.get(rule.target) ?? str(rule.target); + return `{ source: ${source}, target: ${target} }`; + }); + fields.push(`rules: [\n ${rules.join(",\n ")},\n ]`); + } + const name = minter.mint(r.slug, "Rel"); + return { + name, + decl: `const ${name} = defineRelationshipType(${objectLiteral(fields, 0)});`, + }; +} + +function emitWatcher( + w: RemoteWatcher, + reactionScript: string | null, + agentHandles: Map, + imports: ImportTracker, + minter: IdentMinter +): { handle: Handle; reactionFile?: { relPath: string; body: string } } { + imports.use("defineWatcher"); + const agentRef = w.agent_id ? agentHandles.get(w.agent_id) : undefined; + const fields: string[] = [ + `agent: ${agentRef ?? str(w.agent_id ?? "")}`, + `slug: ${str(w.slug)}`, + ]; + if (w.name) fields.push(`name: ${str(w.name)}`); + if (w.description) fields.push(`description: ${str(w.description)}`); + if (w.schedule) fields.push(`schedule: ${str(w.schedule)}`); + fields.push(`prompt: ${str(w.prompt ?? "")}`); + fields.push( + `extractionSchema: ${emitValue(w.extraction_schema ?? { type: "object" }, 1)}` + ); + if (w.sources?.length) { + const sourceObj = Object.fromEntries( + w.sources.map((s) => [s.name, s.query]) + ); + fields.push(`sources: ${emitValue(sourceObj, 1)}`); + } + // notification — omit canvas/normal defaults. + const channel = + w.notification_channel && w.notification_channel !== "canvas" + ? w.notification_channel + : undefined; + const priority = + w.notification_priority && w.notification_priority !== "normal" + ? w.notification_priority + : undefined; + if (channel || priority) { + const notif: string[] = []; + if (channel) notif.push(`channel: ${str(channel)}`); + if (priority) notif.push(`priority: ${str(priority)}`); + fields.push(`notification: ${objectLiteral(notif, 1)}`); + } + if ( + w.min_cooldown_seconds !== undefined && + w.min_cooldown_seconds !== null && + w.min_cooldown_seconds !== 0 + ) { + fields.push(`minCooldownSeconds: ${w.min_cooldown_seconds}`); + } + if (w.tags?.length) fields.push(`tags: ${emitValue(w.tags, 1)}`); + if (w.reactions_guidance) { + fields.push(`reactionsGuidance: ${str(w.reactions_guidance)}`); + } + if (w.agent_kind) fields.push(`agentKind: ${str(w.agent_kind)}`); + + let reactionFile: { relPath: string; body: string } | undefined; + if (reactionScript) { + const rel = `reactions/${w.slug}.reaction.ts`; + fields.push(`reaction: ${str(`./${rel}`)}`); + reactionFile = { + relPath: rel, + body: ensureTrailingNewline(reactionScript), + }; + } + + const name = minter.mint(w.slug, "Watcher"); + const handle: Handle = { + name, + decl: `const ${name} = defineWatcher(${objectLiteral(fields, 0)});`, + }; + return reactionFile ? { handle, reactionFile } : { handle }; +} + +function emitAuthProfile( + p: RemoteAuthProfile, + secrets: SecretCollector, + connectorHandles: Map, + imports: ImportTracker, + minter: IdentMinter +): Handle { + imports.use("defineAuthProfile"); + const interactive = + p.profile_kind === "oauth_account" || p.profile_kind === "browser_session"; + const connectorRef = + connectorHandles.get(p.connector_key) ?? str(p.connector_key); + const fields: string[] = [ + `slug: ${str(p.slug)}`, + `connector: ${connectorRef}`, + `authKind: ${str(p.profile_kind)}`, + ]; + if (p.display_name) fields.push(`name: ${str(p.display_name)}`); + // Credentials are write-only on the server. For credentialed kinds, emit a + // single secret placeholder so the operator wires it back in; interactive + // kinds (oauth_account / browser_session) take no credentials (auth via UI). + if ( + !interactive && + (p.profile_kind === "env" || p.profile_kind === "oauth_app") + ) { + imports.use("secret"); + const credKey = p.profile_kind === "oauth_app" ? "CLIENT_SECRET" : "VALUE"; + fields.push( + `credentials: {\n ${envVarFor(p.slug, credKey)}: ${secrets.ref(envVarFor(p.slug, credKey))},\n }` + ); + } + const name = minter.mint(p.slug, "Auth"); + return { + name, + decl: `const ${name} = defineAuthProfile(${objectLiteral(fields, 0)});`, + }; +} + +function emitConnection( + c: RemoteConnection, + feeds: RemoteFeed[], + authHandles: Map, + connectorHandles: Map, + imports: ImportTracker, + minter: IdentMinter +): Handle { + imports.use("defineConnection"); + const connectorRef = + connectorHandles.get(c.connector_key) ?? str(c.connector_key); + const fields: string[] = [ + `slug: ${str(c.slug)}`, + `connector: ${connectorRef}`, + ]; + if (c.display_name) fields.push(`name: ${str(c.display_name)}`); + if (c.auth_profile_slug) { + const ref = + authHandles.get(c.auth_profile_slug) ?? str(c.auth_profile_slug); + fields.push(`authProfile: ${ref}`); + } + if (c.app_auth_profile_slug) { + const ref = + authHandles.get(c.app_auth_profile_slug) ?? str(c.app_auth_profile_slug); + fields.push(`appAuthProfile: ${ref}`); + } + if (c.config && Object.keys(c.config).length > 0) { + fields.push(`config: ${emitValue(c.config, 1)}`); + } + if (c.device_worker_id) { + fields.push(`deviceWorkerId: ${str(c.device_worker_id)}`); + } + if (feeds.length > 0) { + const items = feeds + .slice() + .sort((a, b) => a.feed_key.localeCompare(b.feed_key)) + .map((f) => { + const fFields: string[] = [`feed: ${str(f.feed_key)}`]; + if (f.display_name) fFields.push(`name: ${str(f.display_name)}`); + if (f.schedule) fFields.push(`schedule: ${str(f.schedule)}`); + if (f.config && Object.keys(f.config).length > 0) { + fFields.push(`config: ${emitValue(f.config, 3)}`); + } + return objectLiteral(fFields, 2); + }); + fields.push(`feeds: [\n ${items.join(",\n ")},\n ]`); + } + const name = minter.mint(c.slug, "Conn"); + return { + name, + decl: `const ${name} = defineConnection(${objectLiteral(fields, 0)});`, + }; +} + +// ── Fetch the org's full declared state ───────────────────────────────────── + +interface FetchedState { + agents: Array<{ agent: RemoteAgent; settings: AgentSettings | null }>; + entityTypes: RemoteEntityType[]; + relationshipTypes: RemoteRelationshipType[]; + watchers: Array<{ watcher: RemoteWatcher; reactionScript: string | null }>; + authProfiles: RemoteAuthProfile[]; + connections: Array<{ connection: RemoteConnection; feeds: RemoteFeed[] }>; +} + +async function fetchOrgState(client: ApplyClient): Promise { + const [ + agentList, + entityTypes, + relationshipTypes, + watcherList, + authProfiles, + connectionList, + ] = await Promise.all([ + client.listAgents(), + client.listEntityTypes(), + client.listRelationshipTypes(), + client.listWatchers(), + client.listAuthProfiles(), + client.listConnections(), + ]); + + const agents = await Promise.all( + agentList + .slice() + .sort((a, b) => a.agentId.localeCompare(b.agentId)) + .map(async (agent) => ({ + agent, + settings: await client.getAgentSettings(agent.agentId), + })) + ); + + // reaction_script isn't on the list response — fetch each watcher's detail. + const watchers = await Promise.all( + watcherList + .slice() + .sort((a, b) => a.slug.localeCompare(b.slug)) + .map(async (watcher) => { + let reactionScript: string | null = null; + if (watcher.watcher_id) { + const detail = await client.getWatcherDetail(watcher.watcher_id); + reactionScript = detail?.reaction_script ?? null; + if (detail?.description && !watcher.description) { + watcher.description = detail.description; + } + } + return { watcher, reactionScript }; + }) + ); + + const connections = await Promise.all( + connectionList + .slice() + .sort((a, b) => a.slug.localeCompare(b.slug)) + .map(async (connection) => ({ + connection, + feeds: await client.listFeeds(connection.id), + })) + ); + + return { + agents, + entityTypes: entityTypes + .slice() + .sort((a, b) => a.slug.localeCompare(b.slug)), + relationshipTypes: relationshipTypes + .slice() + .sort((a, b) => a.slug.localeCompare(b.slug)), + watchers, + authProfiles: authProfiles + .slice() + .sort((a, b) => a.slug.localeCompare(b.slug)), + connections, + }; +} + +// ── Assemble lobu.config.ts ───────────────────────────────────────────────── + +interface GeneratedProject { + configSource: string; + files: Array<{ relPath: string; body: string }>; + envVars: string[]; +} + +export function generateProject( + orgSlug: string, + orgName: string | undefined, + state: FetchedState +): GeneratedProject { + const imports = new ImportTracker(); + imports.use("defineConfig"); + const secrets = new SecretCollector(); + const minter = new IdentMinter(); + const files: Array<{ relPath: string; body: string }> = []; + + // Agents first (watchers reference their handles). + const agentHandles = new Map(); + const agentDecls: string[] = []; + for (const { agent, settings } of state.agents) { + const emitted = emitAgent(agent, settings, imports, secrets, minter); + agentHandles.set(agent.agentId, emitted.handle.name); + agentDecls.push(emitted.handle.decl); + files.push(...emitted.files); + } + + // Entities (relationships reference their handles). + const entityHandles = new Map(); + const entityDecls: string[] = []; + for (const e of state.entityTypes) { + const h = emitEntityType(e, imports, minter); + entityHandles.set(e.slug, h.name); + entityDecls.push(h.decl); + } + + const relDecls: string[] = []; + const relHandles: string[] = []; + for (const r of state.relationshipTypes) { + const h = emitRelationshipType(r, entityHandles, imports, minter); + relDecls.push(h.decl); + relHandles.push(h.name); + } + + // Auth profiles + connections (connector key referenced by string — no local + // connector source is exported, so connectors stay bare string refs). + const connectorHandles = new Map(); + const authHandles = new Map(); + const authDecls: string[] = []; + for (const p of state.authProfiles) { + const h = emitAuthProfile(p, secrets, connectorHandles, imports, minter); + authHandles.set(p.slug, h.name); + authDecls.push(h.decl); + } + + const connDecls: string[] = []; + const connHandles: string[] = []; + for (const { connection, feeds } of state.connections) { + const h = emitConnection( + connection, + feeds, + authHandles, + connectorHandles, + imports, + minter + ); + connDecls.push(h.decl); + connHandles.push(h.name); + } + + // Watchers last. + const watcherDecls: string[] = []; + const watcherHandles: string[] = []; + for (const { watcher, reactionScript } of state.watchers) { + const { handle, reactionFile } = emitWatcher( + watcher, + reactionScript, + agentHandles, + imports, + minter + ); + watcherDecls.push(handle.decl); + watcherHandles.push(handle.name); + if (reactionFile) files.push(reactionFile); + } + + // defineConfig({ ... }). + const configFields: string[] = [`org: ${str(orgSlug)}`]; + if (orgName) configFields.push(`orgName: ${str(orgName)}`); + configFields.push(`agents: [${[...agentHandles.values()].join(", ")}]`); + if (entityHandles.size > 0) { + configFields.push(`entities: [${[...entityHandles.values()].join(", ")}]`); + } + if (relHandles.length > 0) { + configFields.push(`relationships: [${relHandles.join(", ")}]`); + } + if (connHandles.length > 0) { + configFields.push(`connections: [${connHandles.join(", ")}]`); + } + if (authHandles.size > 0) { + configFields.push( + `authProfiles: [${[...authHandles.values()].join(", ")}]` + ); + } + if (watcherHandles.length > 0) { + configFields.push(`watchers: [${watcherHandles.join(", ")}]`); + } + + const blocks: string[] = []; + const pushBlock = (decls: string[]) => { + if (decls.length > 0) blocks.push(decls.join("\n\n")); + }; + pushBlock(agentDecls); + pushBlock(entityDecls); + pushBlock(relDecls); + pushBlock(authDecls); + pushBlock(connDecls); + pushBlock(watcherDecls); + + const header = [ + "// lobu.config.ts — bootstrapped by `lobu init --from-org`", + "// Docs: https://lobu.ai/docs/getting-started", + "//", + "// Secrets are write-only on the server, so provider keys, auth-profile", + '// credentials, and MCP client secrets are emitted as secret("ENV_VAR")', + "// placeholders. Fill them into .env (see .env.example) before `lobu apply`.", + ].join("\n"); + + const configSource = `${[ + header, + "", + imports.render(), + "", + blocks.join("\n\n"), + "", + `export default defineConfig(${objectLiteral(configFields, 0)});`, + "", + ].join("\n")}`; + + return { + configSource, + files, + envVars: [...secrets.names].sort(), + }; +} + +// ── Top-level ──────────────────────────────────────────────────────────────── + +export async function initFromOrg(opts: InitFromOrgOptions): Promise { + const targetDir = resolve(opts.targetDir); + + const { client, orgSlug } = await resolveApplyClient({ + url: opts.url, + org: opts.org, + fetchImpl: opts.fetchImpl, + }); + printText(chalk.dim(`Bootstrapping from org: ${orgSlug}`)); + printText(chalk.dim(`Destination: ${targetDir}`)); + + // Org display name from the userinfo orgs list (no description endpoint). + const orgs = await client.listOrgs().catch(() => []); + const orgName = orgs.find((o) => o.slug === orgSlug)?.name; + + const state = await fetchOrgState(client); + const project = generateProject(orgSlug, orgName, state); + + // Write lobu.config.ts. + await writeFile( + join(targetDir, "lobu.config.ts"), + project.configSource, + "utf-8" + ); + + // Write file-convention artifacts (agent dirs, skills, reactions). + for (const file of project.files) { + const abs = join(targetDir, file.relPath); + await mkdir(resolve(abs, ".."), { recursive: true }); + await writeFile(abs, file.body, "utf-8"); + } + + // .env.example listing the write-only secret var names. + if (project.envVars.length > 0) { + const body = `${[ + "# Secrets referenced by lobu.config.ts (write-only on the server, not exported).", + "# Fill these in before running `lobu apply`.", + "", + ...project.envVars.map((v) => `${v}=`), + "", + ].join("\n")}`; + await writeFile(join(targetDir, ".env.example"), body, "utf-8"); + } + + // ── Report ────────────────────────────────────────────────────────────── + printText(chalk.bold("\nWrote:")); + printText(` ${chalk.green("+")} lobu.config.ts`); + for (const file of project.files) { + printText(` ${chalk.green("+")} ${file.relPath}`); + } + if (project.envVars.length > 0) { + printText(` ${chalk.green("+")} .env.example`); + printText( + chalk.bold("\nWrite-only secrets to fill into .env before applying:") + ); + for (const v of project.envVars) { + printText(` ${chalk.yellow("·")} ${v}`); + } + } + printText( + chalk.dim( + "\nReview lobu.config.ts, fill .env, then `lobu apply` to re-sync.\n" + ) + ); +} diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 963248124..0daa2f861 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -20,6 +20,7 @@ import { } from "../commands/providers/registry.js"; import { setLocalEnvValue } from "../internal/local-env.js"; import { renderTemplate } from "../utils/template.js"; +import { initFromOrg } from "./_lib/init-from-org/bootstrap.js"; import { isPortFree } from "./dev.js"; const DEFAULT_LOBU_MCP_URL = "https://lobu.ai/mcp"; @@ -55,6 +56,14 @@ export interface InitOptions { noSentry?: boolean; slackPreview?: boolean; listProviders?: boolean; + /** + * Bootstrap a complete, re-appliable project from an existing Lobu Cloud org + * (the inverse of `lobu apply`) instead of scaffolding a blank project. Never + * overwrites an existing project — scaffolds into a new/empty dir. + */ + fromOrg?: string; + /** Server URL override (used with `--from-org`). */ + url?: string; } async function pickFreePort( @@ -250,6 +259,21 @@ export async function initCommand( } } + // `--from-org`: bootstrap a complete, re-appliable project from an existing + // cloud org (the inverse of `lobu apply`) instead of the blank scaffold. The + // empty-dir / project-exists guard above already ran, so we never overwrite. + if (options.fromOrg !== undefined) { + await initFromOrg({ + targetDir: projectDir, + org: options.fromOrg || undefined, + url: options.url, + }); + if (!here) { + console.log(chalk.cyan(`\n Next: cd ${projectName}\n`)); + } + return; + } + // Pick free ports at scaffold time so two `lobu run`s on the same machine // don't collide on the default 8787 / 8118. The flag / env value wins. const gatewayPortDefault = String(await pickFreePort(8787)); diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 71f7ff3ed..191d071ad 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -132,7 +132,7 @@ Memory: program .command("init [name]") .description( - "Scaffold a new agent project (lobu.config.ts + agent files + .env)" + "Scaffold a new agent project (lobu.config.ts + agent files + .env), or bootstrap one from an existing org with --from-org" ) .option("-y, --yes", "Skip prompts; use defaults / flag values") .option( @@ -171,6 +171,11 @@ Memory: "--list-providers", "Print available provider ids from config/providers.json and exit" ) + .option( + "--from-org [slug]", + "Bootstrap a re-appliable project from an existing org (defaults to active session)" + ) + .option("--url ", "Server URL override (with --from-org)") .action( async ( name: string | undefined, @@ -189,12 +194,21 @@ Memory: sentry?: boolean; slackPreview?: boolean; listProviders?: boolean; + fromOrg?: string | boolean; + url?: string; } ) => { try { const { initCommand } = await import("./commands/init.js"); // Commander gives a tristate: true for --sentry, false for // --no-sentry, undefined for neither. + // `--from-org` with no value is `true`; normalize to "" (active org). + const fromOrg = + options.fromOrg === undefined + ? undefined + : options.fromOrg === true + ? "" + : (options.fromOrg as string); await initCommand(process.cwd(), name, { yes: options.yes, here: options.here, @@ -211,6 +225,8 @@ Memory: noSentry: options.sentry === false, slackPreview: options.slackPreview, listProviders: options.listProviders, + fromOrg, + url: options.url, }); } catch (error) { console.error(chalk.red("\n Error:"), error); @@ -333,55 +349,6 @@ Memory: } ); - // ─── export ───────────────────────────────────────────────────────── - program - .command("export") - .description( - "Pull memory schema + connectors from the org into apply-compatible files" - ) - .option( - "--out ", - "Destination directory (defaults to cwd; creates models/, connectors/)" - ) - .option("--force", "Overwrite existing models/connectors files") - .option("--org ", "Org slug override (defaults to active session)") - .option("--url ", "Server URL override") - .option( - "--only ", - "Restrict to one resource family: 'models' | 'connectors'" - ) - .action( - async (options: { - out?: string; - force?: boolean; - org?: string; - url?: string; - only?: string; - }) => { - if ( - options.only !== undefined && - options.only !== "models" && - options.only !== "connectors" - ) { - console.error( - chalk.red("\n Error:"), - `--only must be 'models' or 'connectors' (got: ${options.only})` - ); - process.exit(2); - } - const { exportCommand } = await import( - "./commands/_lib/export/export-cmd.js" - ); - await exportCommand({ - out: options.out, - force: options.force, - org: options.org, - url: options.url, - only: options.only as "models" | "connectors" | undefined, - }); - } - ); - // ─── run / dev / start ────────────────────────────────────────────── program .command("run") From e7ece651b0922f4f2f3f74f284111066ace1c023 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 02:54:23 +0100 Subject: [PATCH 27/65] chore(cli): remove dead YAML-model code + de-toml stale comments/strings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - memory/_lib/schema.ts: drop the now-dead model-file parsing (parseModelYamlFile/expandModelDefinition/validateModel/expandModelSection + the model schema types + their AutoCreateWhenRule/TypeCompiler/yaml imports); only the ./data seed-record schema + validateDataRecord (used by `lobu memory seed`) remain. 487 → 124 lines. - Fix the user-facing "referenced in lobu.toml" message (render.ts) → lobu.config.ts, and stale lobu.toml comments in apply-cmd/dev/diff. No lobu.toml/YAML-config reference remains in cli source. --- .../cli/src/commands/_lib/apply/apply-cmd.ts | 10 +- packages/cli/src/commands/_lib/apply/diff.ts | 2 +- .../cli/src/commands/_lib/apply/render.ts | 2 +- packages/cli/src/commands/dev.ts | 4 +- .../cli/src/commands/memory/_lib/schema.ts | 325 +----------------- 5 files changed, 12 insertions(+), 331 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index f7c4fee5f..907543157 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -976,9 +976,9 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { const cwd = opts.cwd ?? process.cwd(); const fetchImpl = opts.fetchImpl ?? fetch; - // Auto-load `.env` from the project dir so $VAR refs in lobu.toml resolve - // without the user having to `set -a; source .env; set +a`. Mirrors what - // `lobu dev` does. Existing process.env values win (don't clobber the shell). + // Auto-load `.env` from the project dir so secret()/$VAR refs in + // lobu.config.ts resolve without the user having to `set -a; source .env`. + // Mirrors `lobu dev`. Existing process.env values win (don't clobber shell). await loadProjectEnvFile(cwd); // Load desired state from the TypeScript entrypoint (lobu.config.ts). @@ -996,8 +996,8 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { ); } - // Org slug resolution: explicit --org ▸ active-session org ▸ `[memory].org` - // from lobu.toml. The toml slug is the declarative default — if no org with + // Org slug resolution: explicit --org ▸ active-session org ▸ `org` from + // defineConfig. The config slug is the declarative default — if no org with // that slug exists yet, `lobu apply` offers to provision it (below). const { client, orgSlug, apiBaseUrl } = await resolveApplyClient({ url: opts.url, diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index cae95808d..64d230e77 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -284,7 +284,7 @@ function diffAgent( * AgentSettings shape currently has no redacted leaf strings, so this is a * forward-compatible guard rather than a hot path today. * - * Field set: limited to the keys lobu.toml can express today. Settings that + * Field set: limited to the keys lobu.config.ts can express today. Settings that * only the UI mutates (e.g. `installedProviders[].installedAt`) are * excluded so unrelated UI activity doesn't show up as drift in the plan. */ diff --git a/packages/cli/src/commands/_lib/apply/render.ts b/packages/cli/src/commands/_lib/apply/render.ts index 5a723bd25..96307a0c6 100644 --- a/packages/cli/src/commands/_lib/apply/render.ts +++ b/packages/cli/src/commands/_lib/apply/render.ts @@ -209,7 +209,7 @@ export function renderMissingSecrets(missing: string[]): string { for (const name of missing) lines.push(chalk.red(` - $${name}`)); lines.push( chalk.dim( - "\n These env vars are referenced in lobu.toml but are not set in the current environment." + "\n These env vars are referenced in lobu.config.ts but are not set in the current environment." ) ); lines.push( diff --git a/packages/cli/src/commands/dev.ts b/packages/cli/src/commands/dev.ts index 9ea1cf414..427b1898d 100644 --- a/packages/cli/src/commands/dev.ts +++ b/packages/cli/src/commands/dev.ts @@ -372,7 +372,7 @@ export async function devCommand( void announceLocalSignIn(gatewayUrl, mode === "embedded").then( (localContextReady) => { // Once the `local` context is confirmed registered + active, push the - // project's lobu.toml into the embedded DB so the scaffolded agent is + // project's lobu.config.ts into the embedded DB so the scaffolded agent is // usable via `lobu chat -c local …` with no separate `lobu apply`. // Gated (see shouldAutoApplyLocalProject) AND pinned to the local URL so // a failed sign-in can never apply this local project to whatever @@ -431,7 +431,7 @@ export function shouldAutoApplyLocalProject(opts: { } /** - * After `lobu run` boots an embedded backend, push the project's `lobu.toml` + * After `lobu run` boots an embedded backend, push the project's `lobu.config.ts` * into the local DB so the agent the user just scaffolded is immediately usable * (`lobu chat -c local …`) without a separate `lobu apply`. Uses the `local` * context that `announceLocalSignIn` just registered. diff --git a/packages/cli/src/commands/memory/_lib/schema.ts b/packages/cli/src/commands/memory/_lib/schema.ts index c39e94cd9..96db591ac 100644 --- a/packages/cli/src/commands/memory/_lib/schema.ts +++ b/packages/cli/src/commands/memory/_lib/schema.ts @@ -1,86 +1,15 @@ /** - * Lobu memory project YAML schema definitions. - * - * These types define the canonical format for project-local memory files: - * - models/*.y{a,}ml — entity types, relationship types, watchers - * - data/(nested).yml — seed entities and relationships - * - * Project-level metadata (org/name/description/visibility) lives in - * [memory] inside lobu.toml. + * Schema + validation for `lobu memory seed` data records (`./data/*.yaml` — + * seed entity + relationship instances). Entity/relationship/watcher *types* + * are declared in `lobu.config.ts` (via `@lobu/sdk`), not here. * * Bump CURRENT_SCHEMA_VERSION when making breaking changes. */ -// Import from the module subpath, not the barrel: a barrel re-export of this -// value+type dual name trips bun's cross-file module lexer in the test runner -// ("Export named AutoCreateWhenRule not found"). The direct subpath resolves -// to the module that declares it and sidesteps the bug. -import { AutoCreateWhenRule } from "@lobu/connector-sdk/identity-types"; -import { TypeCompiler } from "@sinclair/typebox/compiler"; -import { parseAllDocuments } from "yaml"; - export const CURRENT_SCHEMA_VERSION = 2; -export type ModelType = "entity" | "relationship" | "watcher"; export type DataRecordType = "entity" | "relationship"; -// ── Model files ───────────────────────────────────────────────────── - -export interface EntitySchema { - version?: number; - type: "entity"; - slug: string; - name: string; - description?: string; - icon?: string; - color?: string; - metadata_schema?: Record; -} - -export interface RelationshipTypeRule { - source: string; - target: string; -} - -export interface RelationshipSchema { - version?: number; - type: "relationship"; - slug: string; - name: string; - description?: string; - /** - * Allowed (source_entity_type, target_entity_type) pairs. When omitted, any - * pair is permitted (backend `validateTypeRule` short-circuits if there are - * no rules). Provide rules to constrain the relationship — especially for - * cross-org references where unconstrained types would let any source - * entity link to any target. - */ - rules?: RelationshipTypeRule[]; - auto_create_when?: AutoCreateWhenRule[]; -} - -export interface WatcherSchema { - version?: number; - type: "watcher"; - slug: string; - name: string; - schedule: string; - prompt: string; - entity?: string; - entity_id?: number; - extraction_schema?: Record; - sources?: Array<{ name: string; query: string }>; - reactions_guidance?: string; -} - -export type ModelSchema = EntitySchema | RelationshipSchema | WatcherSchema; - -export interface ExpandedModelDefinition { - data: Record; - file: string; - modelType: ModelType; -} - // ── Seed data files ───────────────────────────────────────────────── export interface SeedEntitySchema { @@ -168,254 +97,6 @@ function requireObject( return true; } -function isRecord(value: unknown): value is Record { - return typeof value === "object" && value !== null && !Array.isArray(value); -} - -function normalizeModelType(value: unknown): ModelType | null { - switch (value) { - case "entity": - return "entity"; - case "relationship": - return "relationship"; - case "watcher": - return "watcher"; - default: - return null; - } -} - -/** - * Parse a models YAML file into one entry per document. Handles multi-document - * (`---`-separated) streams, surfaces YAML syntax errors with file context, and - * skips empty / comments-only documents (which `yaml` parses as `null`) instead - * of treating them as malformed model files. - */ -export function parseModelYamlFile( - raw: string, - file: string -): { - documents: Array<{ data: Record; file: string }>; - errors: ValidationError[]; -} { - const errors: ValidationError[] = []; - const documents: Array<{ data: Record; file: string }> = []; - const parsed = parseAllDocuments(raw); - parsed.forEach((doc, idx) => { - const documentFile = parsed.length > 1 ? `${file}#${idx + 1}` : file; - if (doc.errors.length > 0) { - for (const err of doc.errors) { - errors.push({ - file: documentFile, - field: "yaml", - message: err.message, - }); - } - return; - } - const json = doc.toJSON(); - if (json === null || json === undefined) return; - if (!isRecord(json)) { - errors.push({ - file: documentFile, - field: "root", - message: "model file must contain a YAML object", - }); - return; - } - documents.push({ data: json, file: documentFile }); - }); - return { documents, errors }; -} - -// Single source of truth for auto_create_when shape lives in -// `@lobu/connector-sdk`'s `AutoCreateWhenRule` schema. Compile once at module -// load and surface every TypeBox error as a ValidationError. -const compiledRule = TypeCompiler.Compile(AutoCreateWhenRule); - -function validateAutoCreateWhenRules( - value: unknown, - file: string, - errors: ValidationError[] -): void { - if (!Array.isArray(value)) { - errors.push({ - file, - field: "auto_create_when", - message: '"auto_create_when" must be an array of identity-engine rules', - }); - return; - } - value.forEach((rule, idx) => { - for (const err of compiledRule.Errors(rule)) { - // TypeBox paths use JSON-Pointer slashes; translate to dot notation to - // match the rest of this file's `field` style. - errors.push({ - file, - field: `auto_create_when[${idx}]${err.path.replaceAll("/", ".")}`, - message: err.message, - }); - } - }); -} - -function expandModelSection( - parent: Record, - file: string, - key: string, - modelType: ModelType, - errors: ValidationError[] -): ExpandedModelDefinition[] { - const value = parent[key]; - if (value === undefined) return []; - if (!Array.isArray(value)) { - errors.push({ - file, - field: key, - message: `"${key}" must be an array`, - }); - return []; - } - return value.flatMap((entry, idx) => { - const entryFile = `${file}:${key}[${idx}]`; - if (!isRecord(entry)) { - errors.push({ - file: entryFile, - field: key, - message: `each "${key}" entry must be an object`, - }); - return []; - } - const data = { ...entry, version: parent.version, type: modelType }; - return [{ data, file: entryFile, modelType }]; - }); -} - -/** - * Expand one parsed models YAML document into individual model definitions. - * Model files use a dbt-style `version: 2` bundle with top-level - * `entities`, `relationships`, and `watchers` arrays. - */ -export function expandModelDefinition( - parsed: unknown, - file: string -): { models: ExpandedModelDefinition[]; errors: ValidationError[] } { - const errors: ValidationError[] = []; - if (!isRecord(parsed)) { - errors.push({ - file, - field: "root", - message: "model file must contain a YAML object", - }); - return { models: [], errors }; - } - - checkVersion(parsed, file, errors); - if (parsed.version !== CURRENT_SCHEMA_VERSION) { - errors.push({ - file, - field: "version", - message: `model bundle files must declare version: ${CURRENT_SCHEMA_VERSION}`, - }); - } - - const models = [ - ...expandModelSection(parsed, file, "entities", "entity", errors), - ...expandModelSection( - parsed, - file, - "relationships", - "relationship", - errors - ), - ...expandModelSection(parsed, file, "watchers", "watcher", errors), - ]; - - if (models.length === 0 && errors.length === 0) { - errors.push({ - file, - field: "entities", - message: - "model bundle file must declare at least one of: entities, relationships, watchers", - }); - } - - return { models, errors }; -} - -export function validateModel( - parsed: Record, - file: string -): ValidationError[] { - const errors: ValidationError[] = []; - checkVersion(parsed, file, errors); - - const modelType = normalizeModelType(parsed.type); - if (!modelType) { - errors.push({ - file, - field: "type", - message: `"type" is required and must be one of: entity, relationship, watcher`, - }); - return errors; - } - - parsed.type = modelType; - - requireString(parsed, "slug", file, errors); - requireString(parsed, "name", file, errors); - - if (modelType === "watcher") { - requireString(parsed, "schedule", file, errors); - requireString(parsed, "prompt", file, errors); - } - - if (modelType === "relationship" && parsed.auto_create_when !== undefined) { - validateAutoCreateWhenRules(parsed.auto_create_when, file, errors); - } - - if (modelType === "relationship" && parsed.rules !== undefined) { - if (!Array.isArray(parsed.rules)) { - errors.push({ - file, - field: "rules", - message: '"rules" must be an array of { source, target } pairs', - }); - } else { - parsed.rules.forEach((rule, idx) => { - if (!rule || typeof rule !== "object" || Array.isArray(rule)) { - errors.push({ - file, - field: `rules[${idx}]`, - message: - 'each rule must be an object with "source" and "target" string fields', - }); - return; - } - const r = rule as Record; - if (typeof r.source !== "string" || r.source === "") { - errors.push({ - file, - field: `rules[${idx}].source`, - message: - '"source" is required and must be a non-empty entity-type slug', - }); - } - if (typeof r.target !== "string" || r.target === "") { - errors.push({ - file, - field: `rules[${idx}].target`, - message: - '"target" is required and must be a non-empty entity-type slug', - }); - } - }); - } - } - - return errors; -} - export function validateDataRecord( parsed: Record, file: string From a7a913cd53f83e150004402b0202582892c4798d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 03:11:56 +0100 Subject: [PATCH 28/65] fix(cli): scaffold @lobu/sdk + type-check lobu.config.ts (pi-review blocker) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A generated lobu.config.ts imports @lobu/sdk, but `lobu init` only added @lobu/connector-sdk to the scaffolded package.json, and the tsconfig only included connectors/** — so a fresh project couldn't resolve @lobu/sdk (jiti `lobu apply` fails) or type-check its config outside this monorepo. Extract a shared scaffoldProjectPackaging() (adds both SDK devDeps + a tsconfig that includes lobu.config.ts/reactions/agents), and call it from BOTH `lobu init` and `lobu init --from-org` (bootstrap wrote no package.json at all). Regression test asserts the scaffolded package.json + tsconfig. --- packages/cli/src/__tests__/cli-ux.test.ts | 10 ++ packages/cli/src/commands/init.ts | 114 +++++++++++++--------- 2 files changed, 79 insertions(+), 45 deletions(-) diff --git a/packages/cli/src/__tests__/cli-ux.test.ts b/packages/cli/src/__tests__/cli-ux.test.ts index eea39a038..14dc81677 100644 --- a/packages/cli/src/__tests__/cli-ux.test.ts +++ b/packages/cli/src/__tests__/cli-ux.test.ts @@ -97,6 +97,16 @@ describe("lobu init --yes", () => { ); const env = readFileSync(join(proj, ".env"), "utf-8"); expect(env.includes("SENTRY_DSN=")).toBe(false); + // The generated lobu.config.ts imports @lobu/sdk, so the scaffolded + // package.json MUST declare it — else `lobu apply` (jiti) can't resolve it + // outside this monorepo. Regression guard for that blocker. + const pkg = JSON.parse(readFileSync(join(proj, "package.json"), "utf-8")); + expect(pkg.devDependencies["@lobu/sdk"]).toBeDefined(); + expect(pkg.devDependencies["@lobu/connector-sdk"]).toBeDefined(); + const tsconfig = JSON.parse( + readFileSync(join(proj, "tsconfig.json"), "utf-8") + ); + expect(tsconfig.include).toContain("lobu.config.ts"); }); test("scaffolded lobu.config.ts loads into desired state", async () => { diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 0daa2f861..c18ed35da 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -158,6 +158,71 @@ function printProviderList(): void { ); } +/** + * Write the project's package.json + tsconfig.json so `lobu apply` (jiti) and + * the editor can resolve the SDK imports outside this monorepo. Shared by the + * blank scaffold and `--from-org`. Merges into an existing package.json + * (preserving the user's fields) and never overwrites an existing tsconfig. + */ +export async function scaffoldProjectPackaging( + projectDir: string, + projectName: string, + cliVersion: string +): Promise { + const pkgJsonPath = join(projectDir, "package.json"); + let pkgJson: Record; + try { + pkgJson = JSON.parse(await readFile(pkgJsonPath, "utf-8")) as Record< + string, + unknown + >; + } catch { + pkgJson = { + name: projectName, + version: "0.0.0", + private: true, + type: "module", + }; + } + pkgJson.devDependencies = { + ...((pkgJson.devDependencies as Record | undefined) ?? {}), + // lobu.config.ts imports @lobu/sdk; connectors import @lobu/connector-sdk. + // Both must be declared so `lobu apply` (jiti) + the editor resolve them. + "@lobu/sdk": `^${cliVersion}`, + "@lobu/connector-sdk": `^${cliVersion}`, + }; + await writeFile(pkgJsonPath, `${JSON.stringify(pkgJson, null, 2)}\n`); + + const tsconfigPath = join(projectDir, "tsconfig.json"); + try { + await readFile(tsconfigPath, "utf-8"); // exists — leave the user's config untouched + } catch { + await writeFile( + tsconfigPath, + `${JSON.stringify( + { + compilerOptions: { + target: "ES2022", + module: "Preserve", + moduleResolution: "bundler", + strict: true, + skipLibCheck: true, + noEmit: true, + }, + include: [ + "lobu.config.ts", + "connectors/**/*.ts", + "reactions/**/*.ts", + "agents/**/*.ts", + ], + }, + null, + 2 + )}\n` + ); + } +} + export async function initCommand( cwd: string = process.cwd(), projectNameArg?: string, @@ -268,6 +333,9 @@ export async function initCommand( org: options.fromOrg || undefined, url: options.url, }); + // Same package.json/tsconfig the blank scaffold writes, so the bootstrapped + // lobu.config.ts can resolve @lobu/sdk + re-apply outside this monorepo. + await scaffoldProjectPackaging(projectDir, projectName, cliVersion); if (!here) { console.log(chalk.cyan(`\n Next: cd ${projectName}\n`)); } @@ -720,51 +788,7 @@ export async function initCommand( // `--here` can target a directory that already has a package.json / // tsconfig.json — merge into package.json (preserve the user's fields, just // add the SDK devDependency) and never overwrite an existing tsconfig. - const pkgJsonPath = join(projectDir, "package.json"); - let pkgJson: Record; - try { - pkgJson = JSON.parse(await readFile(pkgJsonPath, "utf-8")) as Record< - string, - unknown - >; - } catch { - pkgJson = { - name: projectName, - version: "0.0.0", - private: true, - type: "module", - }; - } - pkgJson.devDependencies = { - ...((pkgJson.devDependencies as Record | undefined) ?? - {}), - "@lobu/connector-sdk": `^${cliVersion}`, - }; - await writeFile(pkgJsonPath, `${JSON.stringify(pkgJson, null, 2)}\n`); - - const tsconfigPath = join(projectDir, "tsconfig.json"); - try { - await readFile(tsconfigPath, "utf-8"); // exists — leave the user's config untouched - } catch { - await writeFile( - tsconfigPath, - `${JSON.stringify( - { - compilerOptions: { - target: "ES2022", - module: "Preserve", - moduleResolution: "bundler", - strict: true, - skipLibCheck: true, - noEmit: true, - }, - include: ["connectors/**/*.ts"], - }, - null, - 2 - )}\n` - ); - } + await scaffoldProjectPackaging(projectDir, projectName, cliVersion); await mkdir(join(projectDir, "connectors"), { recursive: true }); await writeFile(join(projectDir, "connectors", ".gitkeep"), ""); From 6727a4b8b21d844fe111ff266116ea8dd56f292c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 03:35:01 +0100 Subject: [PATCH 29/65] =?UTF-8?q?feat(cli):=20code-managed=20prune=20?= =?UTF-8?q?=E2=80=94=20apply=20deletes=20definitions=20removed=20from=20lo?= =?UTF-8?q?bu.config.ts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a 'delete' diff verb. When the target org is code-managed (organization.managed_by='code', opted in via 'lobu apply --manage'), computeDiff({ codeManaged: true }) emits delete rows for entity types, relationship types, watchers, and connector definitions that exist remotely but are absent from the config. Data (entity/relationship instances), connections, auth profiles, feeds, agents, and platforms are never pruned — they stay 'drift' as before. Connectors still wired to a surviving remote connection/auth-profile are spared. The unnamed-local- connector guard suppresses connector prune when keys can't be matched. Execution runs in reverse-dependency order (watcher -> relationship-type -> entity-type -> connector) and the server refuses an entity-type delete while instances exist, so data stays safe. A blast-radius confirm gates applies that would delete more than 3 definitions; --dry-run never deletes. UI-managed orgs (default) are unchanged: no delete rows, summary omits the delete count. Server managed_by exposure + migration land in the next commit; until then managed_by is absent and every org stays UI-managed (no prune). --- .../_lib/apply/__tests__/diff.test.ts | 134 +++++++++++++++++- .../cli/src/commands/_lib/apply/apply-cmd.ts | 115 ++++++++++++++- .../cli/src/commands/_lib/apply/client.ts | 58 ++++++++ packages/cli/src/commands/_lib/apply/diff.ts | 64 +++++++-- .../cli/src/commands/_lib/apply/prompt.ts | 23 +++ .../cli/src/commands/_lib/apply/render.ts | 13 +- packages/cli/src/index.ts | 6 + 7 files changed, 391 insertions(+), 22 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index e8d79393c..079d628f5 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -63,7 +63,13 @@ describe("apply diff — agents", () => { ]); const plan = computeDiff(desired, emptyRemote()); - expect(plan.counts).toEqual({ create: 2, update: 0, noop: 0, drift: 0 }); + expect(plan.counts).toEqual({ + create: 2, + update: 0, + noop: 0, + drift: 0, + delete: 0, + }); expect(renderPlan(plan)).toMatchSnapshot(); }); @@ -990,3 +996,129 @@ describe("apply diff — connectors", () => { expect(acmeRows).toHaveLength(1); }); }); + +describe("apply diff — code-managed prune", () => { + // Remote state that has definitions + a connection the desired config drops. + function remoteWithExtras(): RemoteSnapshot { + return { + ...emptyRemote(), + entityTypes: [{ slug: "lead", properties: {} }, { slug: "stale-entity" }], + relationshipTypes: [{ slug: "stale-rel" }], + watchers: [{ slug: "stale-watcher", watcher_id: "42" }], + // stale-conn is dropped from config but exempt (drift); the connector "x" + // it still uses must therefore be spared from prune. + connections: [ + { id: 7, slug: "stale-conn", connector_key: "x", status: "ok" }, + ], + connectorDefinitions: [ + { key: "x", installed: true }, + { key: "orphan-connector", installed: true }, + ], + }; + } + + function desiredKeepingLead(): DesiredState { + return buildState([], { + memorySchema: { + entityTypes: [{ slug: "lead", properties: {} }], + relationshipTypes: [], + }, + }); + } + + test("UI-managed (default) reports removed definitions as drift, never delete", () => { + const plan = computeDiff(desiredKeepingLead(), remoteWithExtras()); + expect(plan.counts.delete).toBe(0); + expect(plan.rows.some((r) => r.verb === "delete")).toBe(false); + expect( + plan.rows.find((r) => r.kind === "entity-type" && r.id === "stale-entity") + ?.verb + ).toBe("drift"); + }); + + test("code-managed deletes removed entity/relationship/watcher/connector definitions", () => { + const plan = computeDiff(desiredKeepingLead(), remoteWithExtras(), { + codeManaged: true, + }); + const deletes = plan.rows.filter((r) => r.verb === "delete"); + const deletedIds = deletes.map((r) => `${r.kind}:${r.id}`).sort(); + expect(deletedIds).toEqual([ + "connector-definition:orphan-connector", + "entity-type:stale-entity", + "relationship-type:stale-rel", + "watcher:stale-watcher", + ]); + expect(plan.counts.delete).toBe(4); + // The kept entity type is a noop, not a delete. + expect( + plan.rows.find((r) => r.kind === "entity-type" && r.id === "lead")?.verb + ).toBe("noop"); + }); + + test("code-managed never deletes data, connections, or agents", () => { + const desired = buildState( + [ + buildDesiredAgent("kept", { + metadata: { agentId: "kept", name: "Kept" }, + }), + ], + { + memorySchema: { entityTypes: [], relationshipTypes: [] }, + } + ); + const remote: RemoteSnapshot = { + ...remoteWithExtras(), + agents: [{ agentId: "gone-agent", name: "Gone" }], + agentSettings: new Map([["kept", null]]), + platformsByAgent: new Map([["kept", []]]), + }; + const plan = computeDiff(desired, remote, { codeManaged: true }); + // Connection removed from config is drift (exempt), not delete. + expect( + plan.rows.find((r) => r.kind === "connection" && r.id === "stale-conn") + ?.verb + ).toBe("drift"); + // Remote agent absent from desired is drift (exempt), not delete. + expect( + plan.rows.find((r) => r.kind === "agent" && r.id === "gone-agent")?.verb + ).toBe("drift"); + }); + + test("connector prune suppressed when a local def has an unresolved (null) key", () => { + const desired = buildState([], { + connectors: { + definitions: [ + { + key: null, + sourcePath: "/proj/connectors/local.connector.ts", + sourceCode: "export default class {}", + sourceFile: "connectors/local.connector.ts", + }, + ], + authProfiles: [], + connections: [], + }, + }); + const plan = computeDiff(desired, remoteWithExtras(), { + codeManaged: true, + }); + // Can't map remote connectors to the unnamed local def → never delete them. + expect( + plan.rows.some( + (r) => r.kind === "connector-definition" && r.verb === "delete" + ) + ).toBe(false); + }); + + test("delete rows render with a removed-from-config note + summary count", () => { + const plan = computeDiff(desiredKeepingLead(), remoteWithExtras(), { + codeManaged: true, + }); + expect(renderPlan(plan)).toContain("will be deleted"); + expect(renderSummary(plan)).toContain("4 delete"); + // UI-managed summary stays clean (no delete part). + expect( + renderSummary(computeDiff(desiredKeepingLead(), emptyRemote())) + ).not.toContain("delete"); + }); +}); diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index 907543157..571410f03 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -28,7 +28,11 @@ import { validateAuthProfileAgainstConnector, validateConnectionAgainstConnector, } from "./desired-state.js"; -import { confirmCustomConnectors, confirmPlan } from "./prompt.js"; +import { + confirmCustomConnectors, + confirmDeletions, + confirmPlan, +} from "./prompt.js"; import { renderMissingSecrets, renderPlan, @@ -45,6 +49,13 @@ export interface ApplyOptions { url?: string; /** Bypass the project-link guard. */ force?: boolean; + /** + * Opt the target org into code-managed provenance (one-time). Once set, the + * org's `lobu.config.ts` owns its definitions and apply prunes the ones + * removed from it. Persists server-side; subsequent applies prune without + * the flag. `--dry-run` previews the prune without flipping the org. + */ + manage?: boolean; /** Test seam — inject a stubbed fetch. */ fetchImpl?: typeof fetch; } @@ -55,6 +66,9 @@ interface PendingAuthEntry { connectUrl?: string; } +/** Deletes beyond this in one code-managed apply trigger a second confirm. */ +const BLAST_RADIUS_DELETE_THRESHOLD = 3; + // ── Required-secrets check ───────────────────────────────────────────────── function checkRequiredSecrets(state: DesiredState): { missing: string[] } { @@ -920,6 +934,52 @@ async function executePlan( } printText(renderProgress(row.verb, "feed", row.id)); } + + // 11) Prune — delete definitions removed from a code-managed config. Runs + // LAST and in reverse-dependency order so a rel-type that references an + // entity type is gone before the entity type. Connections + data + // instances are never in the delete set (computeDiff only emits delete + // rows for definitions). The server refuses an entity-type delete while + // instances exist, so the data stays safe. + await deleteRemovedDefinitions(ctx); +} + +/** + * Execute the plan's `delete` rows (code-managed prune). Steps run in + * reverse-dependency order — a rel-type rule references entity types, so + * rel-types delete before entity types; connectors uninstall last. Halts apply + * on first failure (idempotent re-run). + */ +async function deleteRemovedDefinitions(ctx: ApplyContext): Promise { + const deletes = ctx.plan.rows.filter((r) => r.verb === "delete"); + if (deletes.length === 0) return; + const watcherIdBySlug = new Map( + ctx.remote.watchers.map((w) => [w.slug, w.watcher_id]) + ); + const steps: Array<[DiffRow["kind"], (id: string) => Promise]> = [ + [ + "watcher", + async (id) => { + const wid = watcherIdBySlug.get(id); + if (!wid) { + throw new ApiError( + `delete watcher "${id}": remote watcher_id missing` + ); + } + await ctx.client.deleteWatcher(wid); + }, + ], + ["relationship-type", (id) => ctx.client.deleteRelationshipType(id)], + ["entity-type", (id) => ctx.client.deleteEntityType(id)], + ["connector-definition", (id) => ctx.client.uninstallConnector(id)], + ]; + for (const [kind, run] of steps) { + for (const row of deletes) { + if (row.kind !== kind) continue; + await run(row.id); + printText(renderProgress("delete", kind, row.id)); + } + } } // Collect pending interactive-auth profiles from a (no-op) plan and re-issue a @@ -1064,6 +1124,29 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { throw new ValidationError(`organization "${orgSlug}" not found`); } + // A code-managed org's lobu.config.ts owns its definitions, so apply prunes + // the ones removed from it (data/connections/agents are never pruned). + // `--manage` is the one-time opt-in flipping ui→code server-side; older + // servers omit `managed_by` → stays UI-managed (safe, no prune). + let codeManaged = resolvedOrg?.managed_by === "code"; + if (opts.manage && resolvedOrg && !codeManaged) { + if (opts.dryRun) { + printText( + chalk.dim( + `(dry-run) Org "${orgSlug}" would become code-managed — showing the prune plan without flipping it.` + ) + ); + } else { + await client.setOrgManagedBy(orgSlug, "code"); + printText( + chalk.yellow( + `Org "${orgSlug}" is now code-managed — apply will delete definitions removed from lobu.config.ts.` + ) + ); + } + codeManaged = true; + } + // Team org consistency comes from `defineConfig({ org, organizationId })` in // lobu.config.ts (committed) plus the `.lobu/project.json` link — apply does // not rewrite the config file. @@ -1094,7 +1177,7 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { skipSchemaForConnectorKeys: locallyDeclaredConnectorKeys(state), }); - const plan = computeDiff(state, remote, { only: opts.only }); + const plan = computeDiff(state, remote, { only: opts.only, codeManaged }); printText(renderPlan(plan)); if (opts.dryRun) { @@ -1110,13 +1193,19 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { (r) => r.kind === "auth-profile" && "needsAuth" in r && r.needsAuth ); - if (plan.counts.create === 0 && plan.counts.update === 0 && !hasPendingAuth) { + if ( + plan.counts.create === 0 && + plan.counts.update === 0 && + plan.counts.delete === 0 && + !hasPendingAuth + ) { printText(chalk.green("\nNothing to apply.")); return; } - const { create, update, noop, drift } = plan.counts; - const summaryLine = `${create} create, ${update} update, ${noop} noop, ${drift} drift${hasPendingAuth ? " + pending auth" : ""}`; + const { create, update, noop, drift, delete: del } = plan.counts; + const deletePart = del > 0 ? `, ${del} delete` : ""; + const summaryLine = `${create} create, ${update} update, ${noop} noop, ${drift} drift${deletePart}${hasPendingAuth ? " + pending auth" : ""}`; const approved = await confirmPlan({ yes: opts.yes ?? false, summaryLine, @@ -1126,9 +1215,23 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { return; } + // Blast-radius gate: a large code-managed prune gets a second explicit + // confirm beyond the plan approval above. + if (del > BLAST_RADIUS_DELETE_THRESHOLD) { + const okToDelete = await confirmDeletions(del, opts.yes ?? false); + if (!okToDelete) { + printText(chalk.dim("\nCancelled.")); + return; + } + } + const pendingAuth: PendingAuthEntry[] = []; let applyErr: unknown; - if (plan.counts.create > 0 || plan.counts.update > 0) { + if ( + plan.counts.create > 0 || + plan.counts.update > 0 || + plan.counts.delete > 0 + ) { printText(chalk.bold("\nApplying:")); try { await executePlan({ client, state, plan, remote }, pendingAuth); diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index c7a35157e..9a72206d4 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -41,6 +41,12 @@ export interface RemoteOrg { id: string; slug: string; name?: string; + /** + * Provenance: `"code"` means the org's definitions are owned by a + * `lobu.config.ts` and `lobu apply` prunes definitions removed from it; + * `"ui"` (default) means apply never deletes. Absent on older servers. + */ + managed_by?: "ui" | "code"; } export interface RemoteWatcher { @@ -301,11 +307,29 @@ export class ApplyClient { id, slug, ...(typeof entry.name === "string" ? { name: entry.name } : {}), + ...(entry.managed_by === "code" || entry.managed_by === "ui" + ? { managed_by: entry.managed_by } + : {}), }); } return out; } + /** + * Flip an org's provenance to code-managed (the one-time opt-in `lobu apply` + * offers when applying a `lobu.config.ts` to a UI-managed org). Idempotent. + */ + async setOrgManagedBy( + orgSlug: string, + managedBy: "ui" | "code" + ): Promise { + await this.request( + "PATCH", + `/api/${encodeURIComponent(orgSlug)}/organization`, + { managed_by: managedBy } + ); + } + // ── Agents ──────────────────────────────────────────────────────────────── async listAgents(): Promise { @@ -549,6 +573,28 @@ export class ApplyClient { return result; } + /** + * Delete an entity type (code-managed prune). The server soft-deletes and + * REFUSES if instances of the type still exist — the data is exempt from + * prune, so that surfaces as a clear error rather than cascading. + */ + async deleteEntityType(slug: string): Promise { + await this.request("POST", `/api/${this.orgSlug}/manage_entity_schema`, { + schema_type: "entity_type", + action: "delete", + slug, + }); + } + + /** Delete a relationship type (code-managed prune). */ + async deleteRelationshipType(slug: string): Promise { + await this.request("POST", `/api/${this.orgSlug}/manage_entity_schema`, { + schema_type: "relationship_type", + action: "delete", + slug, + }); + } + // ── Watchers ────────────────────────────────────────────────────────────── /** @@ -799,6 +845,18 @@ export class ApplyClient { }); } + /** + * Delete a watcher by its numeric `watcher_id` (code-managed prune). The + * admin tool takes an array; we delete one slug's watcher at a time so a + * failure is attributable. + */ + async deleteWatcher(watcherId: string): Promise { + await this.request("POST", `/api/${this.orgSlug}/manage_watchers`, { + action: "delete", + watcher_ids: [watcherId], + }); + } + // ── Connector definitions ───────────────────────────────────────────────── private async connectionsTool(body: Record): Promise { diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index 64d230e77..b35baff17 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -25,7 +25,7 @@ import type { // ── Diff verbs ────────────────────────────────────────────────────────────── -export type DiffVerb = "create" | "update" | "noop" | "drift"; +export type DiffVerb = "create" | "update" | "noop" | "drift" | "delete"; interface BaseRow { verb: DiffVerb; @@ -142,7 +142,18 @@ export type DiffRow = export interface DiffPlan { rows: DiffRow[]; /** Aggregate counters for the summary line. */ - counts: { create: number; update: number; noop: number; drift: number }; + counts: { + create: number; + update: number; + noop: number; + drift: number; + /** + * Definitions removed from the config that apply will delete. Always 0 + * unless the org is code-managed (`computeDiff({ codeManaged: true })`); + * a UI-managed org reports those remote-only definitions as `drift`. + */ + delete: number; + }; /** * Informational, non-actionable notes — e.g. "connector X is installed * remotely but not declared locally". Rendered after the plan; never block @@ -791,6 +802,15 @@ export interface DesiredStateForDiff { export interface ComputeDiffOptions { /** Limit the diff to a subset of resource kinds. */ only?: "agents" | "memory"; + /** + * When true, the org is code-managed: its `lobu.config.ts` is the source of + * truth for *definitions*, so a remote definition (entity type, relationship + * type, watcher, connector definition) absent from desired is emitted as a + * `delete` row instead of an ignored `drift`. Data (entity/relationship + * instances), connections, auth profiles, feeds, agents, and platforms are + * never pruned. Default (false / UI-managed) reports those as `drift`. + */ + codeManaged?: boolean; } export function computeDiff( @@ -800,6 +820,7 @@ export function computeDiff( ): DiffPlan { const rows: DiffRow[] = []; const only = opts.only; + const codeManaged = opts.codeManaged ?? false; if (only !== "memory") { const remoteByAgent = new Map(remote.agents.map((a) => [a.agentId, a])); @@ -881,9 +902,11 @@ export function computeDiff( } for (const remoteEntity of remote.entityTypes) { if (!desiredEntitySlugs.has(remoteEntity.slug)) { + // Code-managed: delete. The server refuses an entity-type delete while + // instances exist (the data is exempt), surfacing a clear error. rows.push({ kind: "entity-type", - verb: "drift", + verb: codeManaged ? "delete" : "drift", id: remoteEntity.slug, remote: remoteEntity, }); @@ -903,7 +926,7 @@ export function computeDiff( if (!desiredRelSlugs.has(remoteRel.slug)) { rows.push({ kind: "relationship-type", - verb: "drift", + verb: codeManaged ? "delete" : "drift", id: remoteRel.slug, remote: remoteRel, }); @@ -921,7 +944,7 @@ export function computeDiff( if (!desiredWatcherSlugs.has(remoteWatcher.slug)) { rows.push({ kind: "watcher", - verb: "drift", + verb: codeManaged ? "delete" : "drift", id: remoteWatcher.slug, remote: remoteWatcher, }); @@ -1000,15 +1023,30 @@ export function computeDiff( // plan-row loop. The render falls back to `id` (the connector key). }); } - // Conservative: never auto-uninstall remote connector definitions that - // aren't declared/referenced locally — just note them. + // Connector keys still wired to a surviving remote connection / auth profile. + // Those are exempt from prune, so their connector must not be deleted — + // uninstalling it would orphan the connection. + const liveConnectorKeys = new Set([ + ...remoteConnections.map((c) => c.connector_key), + ...remoteAuthProfiles.map((p) => p.connector_key), + ]); + // Remote connector definitions not declared/referenced locally. Code-managed + // orgs delete them; UI-managed orgs just get a note (never auto-uninstall). + // Suppressed entirely when any local `*.connector.ts` has an unresolved key + // (`null`) — we can't tell which remote def corresponds to which local file. if (!hasUnnamedLocalDefs) { for (const def of remoteConnectorDefinitions) { - if ( - def.installed && - !declaredKeys.has(def.key) && - !referencedConnectorKeys.has(def.key) - ) { + if (!def.installed) continue; + if (declaredKeys.has(def.key) || referencedConnectorKeys.has(def.key)) { + continue; + } + if (codeManaged && !liveConnectorKeys.has(def.key)) { + rows.push({ + kind: "connector-definition", + verb: "delete", + id: def.key, + }); + } else { notes.push( `connector "${def.key}" is installed remotely but not declared in connectors/ — uninstall it manually if it's no longer wanted (lobu apply never auto-uninstalls connectors).` ); @@ -1080,7 +1118,7 @@ export function computeDiff( } } - const counts = { create: 0, update: 0, noop: 0, drift: 0 }; + const counts = { create: 0, update: 0, noop: 0, drift: 0, delete: 0 }; for (const row of rows) counts[row.verb]++; notes.sort(); diff --git a/packages/cli/src/commands/_lib/apply/prompt.ts b/packages/cli/src/commands/_lib/apply/prompt.ts index a21284809..4ffb2b943 100644 --- a/packages/cli/src/commands/_lib/apply/prompt.ts +++ b/packages/cli/src/commands/_lib/apply/prompt.ts @@ -26,6 +26,29 @@ export async function confirmPlan(opts: ConfirmOptions): Promise { }); } +/** + * Extra blast-radius gate when a code-managed apply would delete more than a + * handful of definitions. The plan confirm already shows the deletes; this is + * a second, explicit "yes, delete N" so a large accidental prune (e.g. a config + * pointed at the wrong org) can't sail through on a reflexive first y/N. + * `yes` short-circuits (CI); non-TTY without `--yes` throws. + */ +export async function confirmDeletions( + count: number, + yes: boolean +): Promise { + if (yes) return true; + if (!process.stdin.isTTY || !process.stdout.isTTY) { + throw new ValidationError( + `${count} definitions would be DELETED and --yes was not supplied. Re-run with --yes once you've reviewed the plan.` + ); + } + return confirm({ + message: `This will DELETE ${count} definitions removed from your config. Continue?`, + default: false, + }); +} + /** * Confirm uploading + compiling custom connector source on the gateway. * `yes` short-circuits to true; non-TTY without `--yes` throws rather than diff --git a/packages/cli/src/commands/_lib/apply/render.ts b/packages/cli/src/commands/_lib/apply/render.ts index 96307a0c6..4fdcff9f2 100644 --- a/packages/cli/src/commands/_lib/apply/render.ts +++ b/packages/cli/src/commands/_lib/apply/render.ts @@ -6,6 +6,7 @@ const VERB_PREFIX = { update: chalk.yellow("~"), noop: chalk.dim("="), drift: chalk.cyan("?"), + delete: chalk.red("-"), } as const; const KIND_LABEL: Record = { @@ -108,6 +109,11 @@ function renderRow(row: DiffRow): string[] { ` ${prefix} ${label} ${id} ${chalk.cyan("(drift — ignored in v1, not deleted)")}` ); break; + case "delete": + lines.push( + ` ${prefix} ${label} ${id} ${chalk.red("(removed from config — will be deleted)")}` + ); + break; } return lines; @@ -180,9 +186,12 @@ export function renderPostApplyPunchList(items: { } export function renderSummary(plan: DiffPlan): string { - const { create, update, noop, drift } = plan.counts; + const { create, update, noop, drift, delete: del } = plan.counts; + // `delete` only appears for code-managed orgs; omit it otherwise so the + // common UI-managed summary stays unchanged. + const deletePart = del > 0 ? `, ${chalk.red(`${del} delete`)}` : ""; return chalk.bold( - `Summary: ${chalk.green(`${create} create`)}, ${chalk.yellow(`${update} update`)}, ${chalk.dim(`${noop} noop`)}, ${chalk.cyan(`${drift} drift`)}` + `Summary: ${chalk.green(`${create} create`)}, ${chalk.yellow(`${update} update`)}, ${chalk.dim(`${noop} noop`)}, ${chalk.cyan(`${drift} drift`)}${deletePart}` ); } diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 191d071ad..9e4dfe6b6 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -315,6 +315,10 @@ Memory: "--force", "Bypass the project-link guard if context/org don't match" ) + .option( + "--manage", + "Make the org code-managed (lobu.config.ts owns + prunes its definitions)" + ) .action( async (options: { dryRun?: boolean; @@ -323,6 +327,7 @@ Memory: org?: string; url?: string; force?: boolean; + manage?: boolean; }) => { if ( options.only !== undefined && @@ -345,6 +350,7 @@ Memory: org: options.org, url: options.url, force: options.force, + manage: options.manage, }); } ); From 5b38aa79f2d00bd71164f2987137d24354477c11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 03:43:28 +0100 Subject: [PATCH 30/65] feat(server): organization.managed_by + managed-by endpoint for code-managed prune MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Slice 5b — the server half of code-managed prune (CLI half in the prior commit). Adds: - migration 20260522120000: organization.managed_by text NOT NULL DEFAULT 'ui' (CHECK ui|code). The default backfills every existing org to 'ui' so none starts prunable — the 2026-05-20 safety lesson. - /oauth/userinfo organizations[].managed_by, the field the CLI's listOrgs reads to decide codeManaged. - PATCH /api/:orgSlug/organization/managed-by (owner/admin + mcp:admin, same gate as visibility) — the one-time 'lobu apply --manage' opt-in target. Client points setOrgManagedBy at it. Verified against a real ephemeral embedded Postgres (PG18) in managed-by-prune.test.ts (7 tests): migration default + CHECK constraint, userinfo exposure, definition deletes (entity/relationship type, watcher), and that an entity-type delete REFUSES while instances exist — so prune can never cascade into data. CLI client wire contract pinned in client.test.ts. --- ...20260522120000_organization_managed_by.sql | 28 ++++ .../_lib/apply/__tests__/client.test.ts | 73 +++++++++ .../cli/src/commands/_lib/apply/client.ts | 2 +- .../integration/managed-by-prune.test.ts | 144 ++++++++++++++++++ packages/server/src/auth/oauth/provider.ts | 10 +- packages/server/src/index.ts | 73 +++++++++ 6 files changed, 327 insertions(+), 3 deletions(-) create mode 100644 db/migrations/20260522120000_organization_managed_by.sql create mode 100644 packages/server/src/__tests__/integration/managed-by-prune.test.ts diff --git a/db/migrations/20260522120000_organization_managed_by.sql b/db/migrations/20260522120000_organization_managed_by.sql new file mode 100644 index 000000000..54b27a1b2 --- /dev/null +++ b/db/migrations/20260522120000_organization_managed_by.sql @@ -0,0 +1,28 @@ +-- migrate:up + +-- Org provenance. 'code' means the org's definitions (entity types, +-- relationship types, watchers, connector definitions) are owned by a +-- `lobu.config.ts` and `lobu apply` PRUNES definitions removed from it; 'ui' +-- (the default) means apply never deletes — the dashboard/API are free to add +-- definitions without a config rewriting them away. +-- +-- SAFETY: the NOT NULL DEFAULT 'ui' backfills every existing org to 'ui', so no +-- org starts out prunable. An org only becomes code-managed via the explicit +-- one-time `lobu apply --manage` opt-in. See computeDiff({ codeManaged }) in +-- packages/cli/src/commands/_lib/apply/diff.ts. + +ALTER TABLE public.organization + ADD COLUMN IF NOT EXISTS managed_by text NOT NULL DEFAULT 'ui'; + +ALTER TABLE public.organization + DROP CONSTRAINT IF EXISTS organization_managed_by_check; +ALTER TABLE public.organization + ADD CONSTRAINT organization_managed_by_check + CHECK (managed_by IN ('ui', 'code')); + +-- migrate:down + +ALTER TABLE public.organization + DROP CONSTRAINT IF EXISTS organization_managed_by_check; +ALTER TABLE public.organization + DROP COLUMN IF EXISTS managed_by; diff --git a/packages/cli/src/commands/_lib/apply/__tests__/client.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/client.test.ts index 0aff6ed5d..c09cb6d27 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/client.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/client.test.ts @@ -122,3 +122,76 @@ describe("ApplyClient", () => { expect(await client.listOrgs()).toEqual([]); }); }); + +describe("ApplyClient — code-managed prune", () => { + function recordingClient(responseBody: unknown = { success: true }) { + const calls: Array<{ url: string; init?: RequestInit }> = []; + const client = new ApplyClient( + { apiBaseUrl: "https://example.test", orgSlug: "acme", token: "tok" }, + (async (url, init) => { + calls.push({ url: String(url), init }); + return new Response(JSON.stringify(responseBody), { status: 200 }); + }) as typeof fetch + ); + return { calls, client }; + } + + test("deleteEntityType POSTs manage_entity_schema delete by slug", async () => { + const { calls, client } = recordingClient(); + await client.deleteEntityType("lead"); + expect(calls[0]?.url).toBe( + "https://example.test/api/acme/manage_entity_schema" + ); + expect(calls[0]?.init?.method).toBe("POST"); + expect(JSON.parse(String(calls[0]?.init?.body))).toEqual({ + schema_type: "entity_type", + action: "delete", + slug: "lead", + }); + }); + + test("deleteRelationshipType POSTs manage_entity_schema delete by slug", async () => { + const { calls, client } = recordingClient(); + await client.deleteRelationshipType("works-with"); + expect(JSON.parse(String(calls[0]?.init?.body))).toEqual({ + schema_type: "relationship_type", + action: "delete", + slug: "works-with", + }); + }); + + test("deleteWatcher POSTs manage_watchers delete with watcher_ids array", async () => { + const { calls, client } = recordingClient(); + await client.deleteWatcher("42"); + expect(calls[0]?.url).toBe("https://example.test/api/acme/manage_watchers"); + expect(JSON.parse(String(calls[0]?.init?.body))).toEqual({ + action: "delete", + watcher_ids: ["42"], + }); + }); + + test("setOrgManagedBy PATCHes the org managed-by endpoint", async () => { + const { calls, client } = recordingClient({ organization: {} }); + await client.setOrgManagedBy("acme", "code"); + expect(calls[0]?.url).toBe( + "https://example.test/api/acme/organization/managed-by" + ); + expect(calls[0]?.init?.method).toBe("PATCH"); + expect(JSON.parse(String(calls[0]?.init?.body))).toEqual({ + managed_by: "code", + }); + }); + + test("listOrgs surfaces managed_by from userinfo", async () => { + const { client } = recordingClient({ + organizations: [ + { id: "o1", slug: "acme", name: "Acme", managed_by: "code" }, + { id: "o2", slug: "beta", name: "Beta" }, + ], + }); + const orgs = await client.listOrgs(); + expect(orgs.find((o) => o.slug === "acme")?.managed_by).toBe("code"); + // Absent managed_by (older server) → undefined, never assumed code. + expect(orgs.find((o) => o.slug === "beta")?.managed_by).toBeUndefined(); + }); +}); diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index 9a72206d4..a98782785 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -325,7 +325,7 @@ export class ApplyClient { ): Promise { await this.request( "PATCH", - `/api/${encodeURIComponent(orgSlug)}/organization`, + `/api/${encodeURIComponent(orgSlug)}/organization/managed-by`, { managed_by: managedBy } ); } diff --git a/packages/server/src/__tests__/integration/managed-by-prune.test.ts b/packages/server/src/__tests__/integration/managed-by-prune.test.ts new file mode 100644 index 000000000..cf5cbaeb9 --- /dev/null +++ b/packages/server/src/__tests__/integration/managed-by-prune.test.ts @@ -0,0 +1,144 @@ +/** + * Code-managed prune — server-side gate. + * + * `lobu apply --manage` flips an org to code-managed; subsequent applies delete + * definitions removed from `lobu.config.ts` (see packages/cli/.../apply/diff.ts + * computeDiff({ codeManaged })). This suite verifies the destructive half that + * the CLI depends on, against a real Postgres: + * - the migration adds organization.managed_by defaulting to 'ui' (no org + * starts prunable — the 2026-05-20 safety lesson), constrained to ui|code; + * - /oauth/userinfo surfaces managed_by (the CLI's listOrgs read path); + * - definition deletes work (entity/relationship type, watcher); + * - an entity-type delete REFUSES while instances exist, so prune can never + * cascade into data (data is exempt). + */ + +import { beforeAll, describe, expect, it } from 'vitest'; +import { OAuthProvider } from '../../auth/oauth/provider'; +import { cleanupTestDatabase, getTestDb } from '../setup/test-db'; +import { + addUserToOrganization, + createTestAccessToken, + createTestAgent, + createTestEntity, + createTestOAuthClient, + createTestOrganization, + createTestUser, +} from '../setup/test-fixtures'; +import { TestApiClient } from '../setup/test-mcp-client'; + +describe('code-managed prune (server gate)', () => { + let owner: TestApiClient; + let orgId: string; + let userId: string; + + beforeAll(async () => { + await cleanupTestDatabase(); + const org = await createTestOrganization({ name: 'Prune Test Org' }); + orgId = org.id; + const user = await createTestUser({ email: 'prune-owner@test.com' }); + userId = user.id; + await addUserToOrganization(userId, orgId, 'owner'); + owner = await TestApiClient.for({ + organizationId: orgId, + userId, + memberRole: 'owner', + }); + }); + + describe('migration: organization.managed_by', () => { + it('defaults a fresh org to ui (no org starts prunable)', async () => { + const sql = getTestDb(); + const [row] = await sql<{ managed_by: string }[]>` + SELECT managed_by FROM "organization" WHERE id = ${orgId} + `; + expect(row?.managed_by).toBe('ui'); + }); + + it('accepts code and rejects any other value via the CHECK constraint', async () => { + const sql = getTestDb(); + await sql`UPDATE "organization" SET managed_by = 'code' WHERE id = ${orgId}`; + const [row] = await sql<{ managed_by: string }[]>` + SELECT managed_by FROM "organization" WHERE id = ${orgId} + `; + expect(row?.managed_by).toBe('code'); + await expect( + sql`UPDATE "organization" SET managed_by = 'bogus' WHERE id = ${orgId}` + ).rejects.toThrow(); + // Restore for the userinfo assertion below. + await sql`UPDATE "organization" SET managed_by = 'code' WHERE id = ${orgId}`; + }); + }); + + describe('userinfo exposes managed_by (CLI listOrgs read path)', () => { + it('returns the org provenance the CLI reads to decide codeManaged', async () => { + const client = await createTestOAuthClient({ client_name: 'Prune CLI' }); + const { token } = await createTestAccessToken( + userId, + orgId, + client.client_id, + { scope: 'profile:read' } + ); + const provider = new OAuthProvider(getTestDb(), 'http://localhost:8787'); + const info = await provider.getUserInfo(token); + const org = info?.organizations.find((o) => o.id === orgId); + expect(org?.managed_by).toBe('code'); + }); + }); + + describe('definition deletes (prune targets)', () => { + it('deletes an entity type with no instances', async () => { + await owner.entity_schema.createType({ slug: 'prune-empty', name: 'Empty' }); + await owner.entity_schema.deleteType('prune-empty'); + const got = (await owner.entity_schema.getType('prune-empty')) as { + entity_type: unknown; + }; + expect(got.entity_type).toBeNull(); + }); + + it('refuses to delete an entity type while instances exist (data is exempt)', async () => { + await owner.entity_schema.createType({ slug: 'prune-busy', name: 'Busy' }); + await createTestEntity({ + name: 'A live instance', + entity_type: 'prune-busy', + organization_id: orgId, + }); + await expect( + owner.entity_schema.deleteType('prune-busy') + ).rejects.toThrow(/entities of this type exist|cannot delete/i); + }); + + it('deletes a relationship type', async () => { + await owner.entity_schema.createRelType({ slug: 'prune-rel', name: 'Rel' }); + await owner.entity_schema.deleteRelType('prune-rel'); + const list = (await owner.entity_schema.listTypes()) as { + relationship_types?: Array<{ slug: string }>; + }; + expect( + (list.relationship_types ?? []).some((r) => r.slug === 'prune-rel') + ).toBe(false); + }); + + it('deletes a watcher', async () => { + const agent = await createTestAgent({ organizationId: orgId }); + const created = (await owner.watchers.create({ + slug: 'prune-watcher', + agent_id: agent.agentId, + prompt: 'Watch for things.', + extraction_schema: { + type: 'object', + properties: { thing: { type: 'string' } }, + }, + })) as { watcher_id?: string }; + expect(created.watcher_id).toBeTruthy(); + + await owner.watchers.delete(created.watcher_id as string); + const list = (await owner.watchers.list({})) as { + watchers?: Array<{ slug: string }>; + }; + expect((list.watchers ?? []).some((w) => w.slug === 'prune-watcher')).toBe( + false + ); + }); + }); +}); diff --git a/packages/server/src/auth/oauth/provider.ts b/packages/server/src/auth/oauth/provider.ts index 92c1fb56e..823da8482 100644 --- a/packages/server/src/auth/oauth/provider.ts +++ b/packages/server/src/auth/oauth/provider.ts @@ -413,7 +413,12 @@ export class OAuthProvider { name: string | null; picture: string | null; organization_slug: string | null; - organizations: { id: string; slug: string; name: string }[]; + organizations: { + id: string; + slug: string; + name: string; + managed_by: 'ui' | 'code'; + }[]; } | null> { const authInfo = await this.verifyAccessToken(token); if (!authInfo) return null; @@ -449,7 +454,7 @@ export class OAuthProvider { } const orgs = await this.sql` - SELECT o.id, o.slug, o.name + SELECT o.id, o.slug, o.name, o.managed_by FROM "member" m JOIN "organization" o ON o.id = m."organizationId" WHERE m."userId" = ${authInfo.userId} @@ -472,6 +477,7 @@ export class OAuthProvider { id: o.id as string, slug: o.slug as string, name: o.name as string, + managed_by: o.managed_by === 'code' ? 'code' : 'ui', })), }; } diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts index eb31fe30d..070d09c94 100644 --- a/packages/server/src/index.ts +++ b/packages/server/src/index.ts @@ -1123,6 +1123,79 @@ app.patch('/api/:orgSlug/organization/visibility', mcpAuth, async (c) => { return c.json({ organization: { ...org, is_member: true } }); }); +// Flip an org's provenance between UI- and code-managed. Code-managed orgs are +// owned by a `lobu.config.ts`: `lobu apply` prunes definitions removed from it. +// Same owner/admin gate as visibility — pruning is a destructive capability. +app.patch('/api/:orgSlug/organization/managed-by', mcpAuth, async (c) => { + const organizationId = c.get('organizationId'); + const memberRole = c.get('memberRole'); + + if (!organizationId) { + return c.json({ error: 'Organization context required' }, 401); + } + if (memberRole !== 'owner' && memberRole !== 'admin') { + return c.json( + { + error: 'forbidden', + message: 'Changing org management mode requires owner or admin access.', + }, + 403 + ); + } + const authSource = c.get('authSource'); + if (authSource === 'pat') { + return c.json( + { + error: 'forbidden', + message: 'Use OAuth or a web session to change org management mode.', + }, + 403 + ); + } + const scopes = c.get('mcpAuthInfo')?.scopes ?? []; + if (authSource === 'oauth' && !scopes.includes('mcp:admin')) { + return c.json( + { + error: 'forbidden', + message: 'Changing org management mode requires mcp:admin scope.', + }, + 403 + ); + } + + let body: { managed_by?: unknown }; + try { + body = await c.req.json(); + } catch { + return c.json({ error: 'invalid_request', message: 'Request body must be JSON.' }, 400); + } + const managedBy = body.managed_by; + if (managedBy !== 'ui' && managedBy !== 'code') { + return c.json( + { error: 'invalid_request', message: 'managed_by must be "ui" or "code".' }, + 400 + ); + } + + const sql = getDb(); + const rows = await sql<{ id: string; slug: string; managed_by: 'ui' | 'code' }>` + UPDATE "organization" + SET managed_by = ${managedBy} + WHERE id = ${organizationId} + RETURNING id, slug, managed_by + `; + const org = rows[0]; + if (!org) { + return c.json({ error: 'not_found', message: 'Workspace not found.' }, 404); + } + + invalidateOrgSlugCache(c.req.param('orgSlug')); + invalidateOrgSlugCache(org.slug); + invalidationEmitter.emit(org.id, { keys: ['organizations', 'resolve-path'] }); + + return c.json({ organization: org }); +}); + app.route('/api/:orgSlug/agents', agentRoutes); app.route('/api/:orgSlug/clients', clientRoutes); app.route('/api/agents/platforms', platformSchemaRoutes); From 07331426c9d6698a7fdc5e6e7d7756aafe85a139 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 04:16:00 +0100 Subject: [PATCH 31/65] docs: migrate all user-facing docs from lobu.toml/YAML to lobu.config.ts + @lobu/sdk Rewrites the landing docs (getting-started, guides, reference, platforms), the lobu/lobu-operator/lobu-builder SKILL.md files, and example/CLI READMEs to the TypeScript authoring SDK. Renames reference/lobu-toml.md -> reference/lobu-config.md (sidebar + api-reference link updated) and fixes the dead /reference/lobu-toml/ route link in the hand-maintained public indexes (index.md, llms.txt, agent-skills/index.json). Also fixes the AGENTS.md guardrails line to defineAgent({ guardrails }). Landing build green; no broken links. Blog posts + server-internal strings swept separately. --- AGENTS.md | 4 +- README.md | 6 +- codex-skills/lobu-builder/SKILL.md | 14 +- examples/atlas/README.md | 9 +- examples/lobu-crm/README.md | 16 +- .../agents/personal-finance/INGESTION.md | 2 +- packages/cli/README.md | 2 +- packages/landing/astro.config.mjs | 2 +- .../.well-known/agent-skills/index.json | 6 +- packages/landing/public/index.md | 2 +- packages/landing/public/llms.txt | 2 +- .../docs/getting-started/comparison.md | 4 +- .../docs/getting-started/connector-sdk.md | 4 +- .../content/docs/getting-started/index.mdx | 25 +- .../docs/getting-started/reaction-sdk.md | 27 +- .../content/docs/getting-started/skills.mdx | 12 +- .../src/content/docs/guides/admin-ui.md | 2 +- .../src/content/docs/guides/agent-prompts.md | 42 +- .../src/content/docs/guides/agent-settings.md | 20 +- .../src/content/docs/guides/architecture.mdx | 2 +- .../src/content/docs/guides/egress-judge.md | 24 +- .../src/content/docs/guides/guardrails.md | 51 +- .../src/content/docs/guides/mcp-proxy.md | 2 +- .../src/content/docs/guides/security.md | 6 +- .../content/docs/guides/sync-from-github.md | 43 +- .../src/content/docs/guides/testing.md | 2 +- .../src/content/docs/guides/tool-policy.md | 39 +- .../content/docs/guides/troubleshooting.md | 6 +- .../src/content/docs/platforms/slack.mdx | 6 +- .../landing/src/content/docs/reference/cli.md | 16 +- .../src/content/docs/reference/lobu-apply.md | 93 ++-- .../src/content/docs/reference/lobu-config.md | 515 ++++++++++++++++++ .../src/content/docs/reference/lobu-memory.md | 45 +- .../src/content/docs/reference/lobu-toml.md | 377 ------------- .../src/content/docs/reference/skill-md.md | 12 +- .../src/pages/reference/api-reference.astro | 2 +- skills/lobu-operator/SKILL.md | 2 +- skills/lobu/SKILL.md | 52 +- 38 files changed, 849 insertions(+), 647 deletions(-) create mode 100644 packages/landing/src/content/docs/reference/lobu-config.md delete mode 100644 packages/landing/src/content/docs/reference/lobu-toml.md diff --git a/AGENTS.md b/AGENTS.md index 50f08b3f5..bb6ae8f32 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ - **MCP:** providers from `config/providers.json`; MCP servers from per-agent settings or `SKILL.md`. Workers discover MCP tools at startup and call them via the gateway proxy (JWT). Built-ins: `AskUser`, `UploadFile`. Integration auth (OAuth/refresh) lives in Lobu MCP servers — workers never see tokens. - **`events` is append-only.** Never `DELETE FROM events`; tombstone via `client.knowledge.delete()` / `save_knowledge({ supersedes_event_id, ... })`. `current_event_records` masks superseded rows. - **Connectors:** `*.connector.ts` extending `ConnectorRuntime`. npm deps → project `package.json`, bundled by esbuild at compile time; native deps → `runtime.nix.packages` (nixpkgs refs), provisioned via `nix-shell` at run. Compile happens on the CLI (`lobu apply` → `bun install --ignore-scripts`); `@lobu/connector-sdk` is externalized (runtime-provided). -- **Guardrails** (`packages/core/src/guardrails/`): stages `input`/`output`/`pre-tool`; built-ins `secret-scan`, `pii-scan`, `forbidden-tools` (see `gateway/guardrails/builtins.ts` + `aggregator.ts`). Configure in `[agents.].guardrails` (lobu.toml); all fail open on infra errors; each trip writes a `guardrail-trip` event. +- **Guardrails** (`packages/core/src/guardrails/`): stages `input`/`output`/`pre-tool`; built-ins `secret-scan`, `pii-scan`, `forbidden-tools` (see `gateway/guardrails/builtins.ts` + `aggregator.ts`). Configure via `defineAgent({ guardrails: [...] })` in `lobu.config.ts`; all fail open on infra errors; each trip writes a `guardrail-trip` event. - **Network/egress:** worker subprocesses get `HTTP_PROXY=http://localhost:8118`. Access via `WORKER_ALLOWED_DOMAINS`: empty=no net (default), `github.com`=allowlist, `*`=all (not prod), `*`+`WORKER_DISALLOWED_DOMAINS`=blocklist; domains exact or `.wildcard`. Linux prod adds kernel `IPAddressDeny=any` + allow 127.0.0.1. Risky domains can route through an LLM egress judge (Haiku, 5-min cache, fail-closed; needs `ANTHROPIC_API_KEY`; `gateway/proxy/http-proxy.ts`). ## Releasing @@ -37,4 +37,4 @@ release-please owns it: land conventional commits on `main`, merge the generated - **After changes run `make review`** (typecheck/unit/integration + pi verdict; posts a PR comment). Build per change: landing → `cd packages/landing && bun run build`; `{core,server,agent-worker,cli}` → `make build-packages`; broad → `bun run typecheck` (`make dev` doesn't rebuild workspace pkgs). - **E2E before merge (hard gate)** for bug fixes: red→fix→green reproducer in the PR body; if you can't reproduce, BAIL (post the dead-end, don't open a PR). Native-app UI exempt (compile-check + draft, say so). - Bot behavior → `./scripts/test-bot.sh "@me ..."` (dev `@clawdotfreebot`, prod `@lobuaibot`; clear stale history via `chat_state_lists`). Prompt/behavior → promptfoo (`bun run evals`). Auth'd UI → `docs/BROWSER_TESTING.md`. -- `.env` is the single source of truth for secrets (restart `make dev` after changes). Worker sessions persist via `./workspaces/{agentId}/`. Skills declare network/nix needs that merge into the allowlist — review skills before installing; destructive MCP calls need in-thread approval unless pre-approved in `lobu.toml`. +- `.env` is the single source of truth for secrets (restart `make dev` after changes). Worker sessions persist via `./workspaces/{agentId}/`. Skills declare network/nix needs that merge into the allowlist — review skills before installing; destructive MCP calls need in-thread approval unless pre-approved in `lobu.config.ts`. diff --git a/README.md b/README.md index 3c0978902..7343554de 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ npx @lobu/cli@latest run # boots the stack and applies your npx @lobu/cli@latest chat -c local "hello" # talk to it ``` -`lobu run` (embedded) auto-applies your `lobu.toml`, so the scaffolded agent is usable immediately. To use an external Postgres, set `DATABASE_URL` in `.env`; to push later config changes, run `lobu apply`. +`lobu run` (embedded) auto-applies your `lobu.config.ts`, so the scaffolded agent is usable immediately. To use an external Postgres, set `DATABASE_URL` in `.env`; to push later config changes, run `lobu apply`. ## Agent configuration @@ -42,7 +42,7 @@ npx @lobu/cli@latest org set my-org npx @lobu/cli@latest agent list ``` -Local `lobu.toml` projects are still useful for `lobu validate` and `lobu apply` workflows. +Local `lobu.config.ts` projects are still useful for `lobu validate` and `lobu apply` workflows. ### Deployment @@ -94,7 +94,7 @@ Every Lobu agent ships with tools for autonomous execution and persistence: | **Full Linux toolbox** — sandboxed shell, file edit, search | `bash`, `read`, `write`, `edit`, `grep`, `find`, `ls` | | **Conversation context** — pull earlier thread messages | `GetChannelHistory` | | **File & media delivery** — share reports, charts, audio | `UploadUserFile`, `GenerateAudio` | -| **Skills** — extend via `lobu.toml` or admin settings | `lobu.toml`, Settings UI | +| **Skills** — extend via `lobu.config.ts` or admin settings | `lobu.config.ts`, Settings UI | | **Connected APIs** — GitHub, Google, etc. with Lobu-managed OAuth | MCP tools via Lobu | | **Managed MCP proxy** — any MCP server with secret injection | [MCP Proxy](docs/SECURITY.md#credentials) | | **Nix + external MCP** — browsing, headless UI, custom tools | `bash` (Nix), MCP servers | diff --git a/codex-skills/lobu-builder/SKILL.md b/codex-skills/lobu-builder/SKILL.md index d380451dd..6172526e9 100644 --- a/codex-skills/lobu-builder/SKILL.md +++ b/codex-skills/lobu-builder/SKILL.md @@ -1,20 +1,20 @@ --- name: lobu-builder -description: Use when working inside a Lobu project generated by @lobu/cli or any repository centered on lobu.toml, AGENTS.md, agent prompt files, local skills, and evals. This skill helps a coding agent inspect the right files, make Lobu-native changes, keep the stack runnable, and validate behavior with chat tests and evals. +description: Use when working inside a Lobu project generated by @lobu/cli or any repository centered on lobu.config.ts, AGENTS.md, agent prompt files, local skills, and evals. This skill helps a coding agent inspect the right files, make Lobu-native changes, keep the stack runnable, and validate behavior with chat tests and evals. --- # Lobu Builder ## Overview -Use this skill when the repository is a Lobu project and the task is to build or change the agent itself: prompt files, `lobu.toml`, local skills, MCP configuration, connections, network settings, or evals. +Use this skill when the repository is a Lobu project and the task is to build or change the agent itself: prompt files, `lobu.config.ts`, local skills, MCP configuration, connections, network settings, or evals. If you are inside the Lobu monorepo rather than a generated Lobu project, follow that repository's own instructions first. ## First Pass 1. Read `AGENTS.md` first. If it redirects to another file such as `@TESTING.md`, open that too. -2. Read `lobu.toml`. +2. Read `lobu.config.ts`. It is TypeScript: `defineConfig` from `@lobu/sdk` is the default export. 3. Enumerate agent directories under `agents/` and inspect the target agent's `IDENTITY.md`, `SOUL.md`, and `USER.md`. 4. Check whether the repo has shared `skills/` or agent-local `agents//skills/`. 5. Look for evals under `agents//evals/promptfooconfig.yaml` (the project may also have legacy YAML files — those don't run). @@ -26,7 +26,7 @@ Do not assume there is only one agent or one platform connection. - `IDENTITY.md`: who the agent is - `SOUL.md`: rules, workflows, guardrails - `USER.md`: user or tenant context -- `lobu.toml`: providers, connections, enabled skills, MCP servers, network allowlist +- `lobu.config.ts`: providers, connections, enabled skills, MCP servers, network allowlist (authored with `define*` from `@lobu/sdk`) - `skills/.../SKILL.md`: shared reusable capabilities - `agents//skills/.../SKILL.md`: agent-specific capabilities - `agents//evals/promptfooconfig.yaml`: promptfoo eval suite (runs via `bunx promptfoo eval` with `@lobu/promptfoo-provider`) @@ -37,7 +37,7 @@ Prefer editing these files directly instead of burying behavior in ad hoc code. 1. Keep the project runnable. Start or reuse the stack with `npx @lobu/cli@latest run -d`. 2. Make the smallest prompt, config, skill, or eval change that solves the task. -3. Run `npx @lobu/cli@latest validate` after changing `lobu.toml` or skill definitions. +3. Run `npx @lobu/cli@latest validate` after changing `lobu.config.ts` or skill definitions. 4. Test behavior with `npx @lobu/cli@latest chat "..."` or the project's testing instructions. 5. Run `LOBU_TOKEN=$(npx @lobu/cli@latest token) bunx promptfoo eval -c agents//evals/promptfooconfig.yaml` when the behavior should be captured as a regression test. @@ -53,9 +53,9 @@ If the repository already provides project-specific test scripts, use those. ## Useful Suggestions -- Add or reorder providers in `lobu.toml` +- Add or reorder providers on `defineAgent({ providers })` in `lobu.config.ts` - Enable built-in skills with `npx @lobu/cli@latest skills list`, `search`, or `add` -- Add a custom MCP server under `[agents..skills.mcp.*]` +- Add a custom MCP server via `defineAgent({ mcpServers })` - Add a shared skill under `skills/` for repeated workflows - Add evals for risky behaviors and policy constraints - Wire observability only when needed; Lobu supports Grafana/Tempo traces diff --git a/examples/atlas/README.md b/examples/atlas/README.md index 37ccce008..33d1c28a5 100644 --- a/examples/atlas/README.md +++ b/examples/atlas/README.md @@ -37,13 +37,14 @@ being duplicated per catalog. | `technology` | Tool, framework, library, platform | | `university` | Higher-education institution | -Schemas live in `models/`. Field definitions follow the same TypeBox-/ -JSON-Schema-style shape as the other `examples//models/` catalogs. +Entity types are declared in `lobu.config.ts` with `defineEntityType`. Field +definitions follow the same TypeBox-/JSON-Schema-style shape as the other +`examples//lobu.config.ts` catalogs. ## What ships in this PR -- The entity-type YAML in `models/`. -- `lobu.toml` declaring the `atlas` org name + a curator agent stub. +- The entity types declared with `defineEntityType` in `lobu.config.ts`. +- `lobu.config.ts` declaring the `atlas` org name + a curator agent stub. - The `scripts/migrate/create-atlas-org.sql` migration that inserts the `atlas` row (`visibility='public'`). diff --git a/examples/lobu-crm/README.md b/examples/lobu-crm/README.md index a5f31c42a..eced160a8 100644 --- a/examples/lobu-crm/README.md +++ b/examples/lobu-crm/README.md @@ -1,22 +1,16 @@ # lobu-crm — Reference example A funnel CRM agent that tracks GitHub stars, X mentions, HN posts, and demo-form submissions. -Use this as a starting point for new projects — it shows every Lobu concept in one place. +Use this as a starting point for new projects. It shows every Lobu concept in one place. ## Structure ``` lobu-crm/ -├── lobu.toml # Agent + memory config +├── lobu.config.ts # Agent, entities, relationships, watchers, connections, auth profiles ├── connectors/ -│ ├── github.yaml # Built-in connector (just config) -│ ├── x.yaml # Built-in connector -│ ├── hackernews.yaml # Built-in connector -│ ├── changelog-watch.yaml # Built-in connector (website) -│ ├── funnel-form.yaml # Custom connector manifest │ └── funnel-form.connector.ts # Custom connector implementation ├── models/ -│ ├── schema.yaml # Entities, relationships, watchers │ └── reactions/ │ ├── inbound-triage.reaction.ts # Runs after watcher extraction │ └── funnel-digest.reaction.ts # Runs after watcher extraction @@ -27,11 +21,13 @@ lobu-crm/ └── skills/crm-ops/SKILL.md # Agent skill ``` +The built-in GitHub, X, Hacker News, and website connections are declared inline in +`lobu.config.ts` with `defineConnection` (and `defineAuthProfile` for their OAuth wiring). + ## Key files to read | File | What it shows | |------|--------------| -| `lobu.toml` | Agent config, providers, network allowlist | -| `models/schema.yaml` | Entity definitions + watcher cron + extraction schema | +| `lobu.config.ts` | Agent config, providers, network allowlist, entity + relationship + watcher definitions, connections, auth profiles | | `connectors/funnel-form.connector.ts` | Custom connector with typed checkpoint + config | | `models/reactions/inbound-triage.reaction.ts` | Reaction script with typed `ReactionClient` | diff --git a/examples/personal-finance/agents/personal-finance/INGESTION.md b/examples/personal-finance/agents/personal-finance/INGESTION.md index 628b3f8cc..e42136c12 100644 --- a/examples/personal-finance/agents/personal-finance/INGESTION.md +++ b/examples/personal-finance/agents/personal-finance/INGESTION.md @@ -28,7 +28,7 @@ Store under `/workspace/incoming/` (the session workspace; persists per thread). ## Step 2 — extract text -- **PDF** → `pdftotext -layout /workspace/incoming/$NAME -` (poppler, declared in lobu.toml nix_packages). +- **PDF** → `pdftotext -layout /workspace/incoming/$NAME -` (poppler, declared in lobu.config.ts via `defineAgent({ nixPackages })`). - **CSV** → read directly, or normalise with `csvtk headers $FILE` and `csvtk csv2tab $FILE` if columns need inspection. - **OFX / QIF / TXT** → read directly. - **Image of a receipt** → describe the file back to the user and ask them to re-send as PDF if possible (v1 does not OCR images). diff --git a/packages/cli/README.md b/packages/cli/README.md index 110ccfeb6..18cf2eb0e 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -28,7 +28,7 @@ docker run -d --name lobu-pg -p 5432:5432 \ - `lobu chat ` — send one prompt and stream the response. `-C/--continue` resumes the last thread (per context+agent); `--auto-approve` skips tool prompts in trusted runs; `--json` emits raw SSE events for piping. - `lobu doctor` — Postgres connectivity, pgvector extension, port availability, provider API keys, workspace dir. - `lobu link` / `lobu unlink` — bind this directory to a (context, org) at `.lobu/project.json`. `lobu apply` refuses to push mismatched targets unless `--force` is set. -- `lobu apply` (alias: `lobu deploy`) — idempotent sync of `lobu.toml` to Lobu Cloud. +- `lobu apply` (alias: `lobu deploy`) — idempotent sync of `lobu.config.ts` to Lobu Cloud. - `lobu agent scaffold ` — add a second/third agent to an existing project. - `lobu telemetry {status,on,off}` — Sentry is off by default; toggle here. diff --git a/packages/landing/astro.config.mjs b/packages/landing/astro.config.mjs index bffea0e62..d8c3729f2 100644 --- a/packages/landing/astro.config.mjs +++ b/packages/landing/astro.config.mjs @@ -95,7 +95,7 @@ export default defineConfig({ { label: "Reference", items: [ - { label: "lobu.toml", link: "/reference/lobu-toml/" }, + { label: "lobu.config.ts", link: "/reference/lobu-config/" }, { label: "SKILL.md", link: "/reference/skill-md/" }, { label: "Providers", link: "/reference/providers/" }, { label: "CLI", link: "/reference/cli/" }, diff --git a/packages/landing/public/.well-known/agent-skills/index.json b/packages/landing/public/.well-known/agent-skills/index.json index 2dfaed434..31b1acc2d 100644 --- a/packages/landing/public/.well-known/agent-skills/index.json +++ b/packages/landing/public/.well-known/agent-skills/index.json @@ -48,10 +48,10 @@ "url": "https://lobu.ai/reference/skill-md/" }, { - "name": "lobu-toml-reference", + "name": "lobu-config-reference", "type": "reference", - "description": "Reference for the lobu.toml agent configuration file.", - "url": "https://lobu.ai/reference/lobu-toml/" + "description": "Reference for the lobu.config.ts agent configuration file.", + "url": "https://lobu.ai/reference/lobu-config/" } ] } diff --git a/packages/landing/public/index.md b/packages/landing/public/index.md index 97bceab5a..4f016cf9e 100644 --- a/packages/landing/public/index.md +++ b/packages/landing/public/index.md @@ -52,7 +52,7 @@ The canonical MCP endpoint at [https://lobu.ai/mcp](https://lobu.ai/mcp) lets MC ## Reference - [API reference](https://lobu.ai/reference/api-reference/) -- [lobu.toml](https://lobu.ai/reference/lobu-toml/) +- [lobu.config.ts](https://lobu.ai/reference/lobu-config/) - [SKILL.md](https://lobu.ai/reference/skill-md/) - [Providers](https://lobu.ai/reference/providers/) - [CLI](https://lobu.ai/reference/cli/) diff --git a/packages/landing/public/llms.txt b/packages/landing/public/llms.txt index 9460cedfd..7ff0e1593 100644 --- a/packages/landing/public/llms.txt +++ b/packages/landing/public/llms.txt @@ -44,7 +44,7 @@ ## Reference - [CLI](https://lobu.ai/reference/cli/) -- [lobu.toml](https://lobu.ai/reference/lobu-toml/) +- [lobu.config.ts](https://lobu.ai/reference/lobu-config/) - [SKILL.md](https://lobu.ai/reference/skill-md/) - [Providers](https://lobu.ai/reference/providers/) - [REST API reference](https://lobu.ai/reference/api-reference/) diff --git a/packages/landing/src/content/docs/getting-started/comparison.md b/packages/landing/src/content/docs/getting-started/comparison.md index 17badfea4..f28bc05bc 100644 --- a/packages/landing/src/content/docs/getting-started/comparison.md +++ b/packages/landing/src/content/docs/getting-started/comparison.md @@ -25,7 +25,7 @@ This page compares Lobu against other ways to run agents for multiple users. | **Built-in evals** | YAML eval framework with model comparison | No | No | No | | **Memory** | Self-hosted Lobu plugin | Local | LangSmith APIs | Platform-managed | | **Worker lifecycle** | Persistent subprocess per channel; reaped on config change / shutdown | Always running | Managed by LangSmith | Managed | -| **Config format** | `lobu.toml` + IDENTITY/SOUL/USER.md | CLI flags | `deepagents.toml` + AGENTS.md | Dashboard | +| **Config format** | `lobu.config.ts` (TypeScript) + IDENTITY/SOUL/USER.md | CLI flags | `deepagents.toml` + AGENTS.md | Dashboard | | **License** | Open source | Open source | MIT (harness), proprietary (hosting) | Proprietary | ## Memory benchmarks @@ -137,7 +137,7 @@ Inside each Lobu worker, the full OpenClaw runtime runs untouched. Lobu rewrites [DeepAgents Deploy](https://github.com/langchain-ai/deepagents) (LangChain) deploys a single agent to a hosted LangSmith server with 30+ API endpoints. -**Where they overlap**: both use a TOML config file, support MCP, and offer model-agnostic provider selection. +**Where they overlap**: both use a code-as-config file, support MCP, and offer model-agnostic provider selection. **Where they differ**: diff --git a/packages/landing/src/content/docs/getting-started/connector-sdk.md b/packages/landing/src/content/docs/getting-started/connector-sdk.md index d6e4356a8..a4f5ba1e0 100644 --- a/packages/landing/src/content/docs/getting-started/connector-sdk.md +++ b/packages/landing/src/content/docs/getting-started/connector-sdk.md @@ -309,7 +309,7 @@ In your Lobu project, drop `*.connector.ts` files under `connectors/`: ``` my-agent/ -├── lobu.toml +├── lobu.config.ts ├── connectors/ │ ├── github-issues.connector.ts │ └── stripe-charges.connector.ts @@ -322,7 +322,7 @@ my-agent/ A connector can pull in two kinds of dependency, and they are provisioned differently. -**npm packages are bundled at compile time.** Add them to the `package.json` next to your `lobu.toml` and import them normally: +**npm packages are bundled at compile time.** Add them to the `package.json` next to your `lobu.config.ts` and import them normally: ```ts import { parse } from "csv-parse/sync"; diff --git a/packages/landing/src/content/docs/getting-started/index.mdx b/packages/landing/src/content/docs/getting-started/index.mdx index 91ed0b063..0b33538bd 100644 --- a/packages/landing/src/content/docs/getting-started/index.mdx +++ b/packages/landing/src/content/docs/getting-started/index.mdx @@ -30,7 +30,9 @@ LOBU_TOKEN=$(npx @lobu/cli@latest token) bunx promptfoo eval \ ``` my-agent/ -├── lobu.toml # agents, providers, skills, network +├── lobu.config.ts # agents, providers, network, memory schema (TypeScript) +├── package.json # declares @lobu/sdk + @lobu/connector-sdk +├── tsconfig.json ├── .env # secrets (API keys, optional DATABASE_URL) ├── AGENTS.md # briefing for coding agents ├── README.md @@ -42,50 +44,51 @@ my-agent/ │ ├── skills/ # skills scoped to this agent only │ └── evals/ │ └── promptfooconfig.yaml # test cases for agent quality (promptfoo) +├── connectors/ # custom *.connector.ts (optional) ├── data/ # local runtime data; memory seeds when enabled └── skills/ # skills shared across all agents ``` -If you enable Lobu memory during `init`, the scaffold also creates `models/` plus `data/entities/` and `data/relationships/`. +The memory schema (entity types, relationship types, watchers) lives directly in `lobu.config.ts` via `defineEntityType` / `defineRelationshipType` / `defineWatcher`. | Path | Docs | |------|------| -| `lobu.toml` | [lobu.toml reference](/reference/lobu-toml/) | +| `lobu.config.ts` | [lobu.config.ts reference](/reference/lobu-config/) | | `agents/*/IDENTITY.md`, `SOUL.md`, `USER.md` | [Agent Workspace](/guides/agent-prompts/) | | `agents/*/skills/`, `skills/` | [SKILL.md reference](/reference/skill-md/), [Skills](/getting-started/skills/) | | `agents/*/evals/` | [Evaluations](/guides/evals/) | -| `models/`, `data/entities/`, `data/relationships/` | [Memory](/getting-started/memory/) | +| `connectors/` | [Connector SDK](/getting-started/connector-sdk/) | | `.env` | [CLI reference](/reference/cli/) | ## Develop your agent -Install the Lobu skill into your coding agent so it already understands the project layout, `lobu.toml`, evals, memory wiring, and client setup: +Install the Lobu skill into your coding agent so it already understands the project layout, `lobu.config.ts`, evals, memory wiring, and client setup: ```bash npx skills add lobu-ai/lobu --skill lobu ``` -See [Skills](/getting-started/skills/) for which coding agents this supports and how to scope it. With the skill installed, open your coding agent in the project and shape behavior by editing `agents/my-agent/{IDENTITY,SOUL,USER}.md`, `lobu.toml`, and `agents/my-agent/evals/promptfooconfig.yaml` — then re-run `npx @lobu/cli@latest chat "…"` and `bunx promptfoo eval -c agents/my-agent/evals/promptfooconfig.yaml` after each change. +See [Skills](/getting-started/skills/) for which coding agents this supports and how to scope it. With the skill installed, open your coding agent in the project and shape behavior by editing `agents/my-agent/{IDENTITY,SOUL,USER}.md`, `lobu.config.ts`, and `agents/my-agent/evals/promptfooconfig.yaml`, then re-run `npx @lobu/cli@latest chat "…"` and `bunx promptfoo eval -c agents/my-agent/evals/promptfooconfig.yaml` after each change. | File | What to ask for | |------|----------------| | `agents/my-agent/IDENTITY.md` | "Make this a customer support agent for Acme Corp" | | `agents/my-agent/SOUL.md` | "Add rules: never share pricing, always confirm before cancellations" | | `agents/my-agent/USER.md` | "Set timezone to US/Pacific, company plan is Enterprise" | -| `lobu.toml` | "Add GitHub and Linear skills, allow github.com and api.linear.app" | +| `lobu.config.ts` | "Add a GitHub MCP server and allow github.com and api.linear.app" | | `agents/my-agent/evals/` | "Write an eval that tests the agent follows the cancellation rule" | | `agents/my-agent/skills/` | "Create a custom skill for our internal API" | ## Configuration -`lobu.toml` plus the files under `agents//` are the source of truth — agents, providers, enabled skills, MCP servers, network policy, and (optionally) memory. Edit them locally and `lobu run` picks them up immediately. +`lobu.config.ts` plus the files under `agents//` are the source of truth: agents, providers, network policy, tool policy, MCP servers, and (optionally) the memory schema. `lobu.config.ts` is a TypeScript module that default-exports `defineConfig({...})` and imports its authoring functions from `@lobu/sdk`. Edit it locally and `lobu run` picks it up immediately. -To run an agent on **Lobu Cloud**, push the same files up with `lobu apply`: +To run an agent on **Lobu Cloud**, push the same project up with `lobu apply`: ```bash npx @lobu/cli@latest login # authenticate -npx @lobu/cli@latest validate # check lobu.toml + agent files +npx @lobu/cli@latest validate # check lobu.config.ts + agent files npx @lobu/cli@latest apply --org my-org # sync to your Cloud org ``` -The Cloud web app and the CLI talk to the same org-scoped REST API, so anything you do in the UI (add providers, connections, skills; view agent status) you can also drive from `lobu.toml` + `lobu apply`. See the [CLI Reference](/reference/cli/) and [`lobu apply`](/reference/lobu-apply/) for the full surface. +The Cloud web app and the CLI talk to the same org-scoped REST API, so anything you do in the UI (add providers, connections, skills; view agent status) you can also drive from `lobu.config.ts` + `lobu apply`. See the [CLI Reference](/reference/cli/) and [`lobu apply`](/reference/lobu-apply/) for the full surface. diff --git a/packages/landing/src/content/docs/getting-started/reaction-sdk.md b/packages/landing/src/content/docs/getting-started/reaction-sdk.md index b73caec39..6287bacc5 100644 --- a/packages/landing/src/content/docs/getting-started/reaction-sdk.md +++ b/packages/landing/src/content/docs/getting-started/reaction-sdk.md @@ -123,18 +123,29 @@ In your Lobu project, drop the reaction next to the watcher it pairs with: ``` my-agent/ -├── lobu.toml -├── models/ -│ ├── watchers/ -│ │ └── critical-detection.yaml -│ └── reactions/ -│ └── critical-detection.reaction.ts +├── lobu.config.ts +├── reactions/ +│ └── critical-detection.reaction.ts └── agents/my-agent/... ``` -**The filename is the pairing.** `critical-detection.reaction.ts` runs after the `critical-detection` watcher. No registry, no config block — the slug match is the wiring. +**The watcher names its reaction.** Point a watcher at a reaction with the `reaction` field in `defineWatcher`: -If you don't want a reaction, don't create the file. The watcher's extraction still gets persisted; the reaction just doesn't fire. +```ts +import { defineWatcher } from "@lobu/sdk"; + +const criticalDetection = defineWatcher({ + agent: myAgent, + slug: "critical-detection", + prompt: "Flag any critical incidents.", + extractionSchema: { type: "object", properties: {} }, + reaction: "./reactions/critical-detection.reaction.ts", +}); +``` + +The path is relative to the config file and must stay under the project directory. Keeping the reaction in its own `.ts` file (not inline) means your editor type-checks it. + +If you don't want a reaction, omit the `reaction` field. The watcher's extraction still gets persisted; the reaction just doesn't fire. ## When to reach for a reaction diff --git a/packages/landing/src/content/docs/getting-started/skills.mdx b/packages/landing/src/content/docs/getting-started/skills.mdx index c2c65390c..59994dc81 100644 --- a/packages/landing/src/content/docs/getting-started/skills.mdx +++ b/packages/landing/src/content/docs/getting-started/skills.mdx @@ -16,7 +16,7 @@ Lobu discovers local `SKILL.md` files at runtime. Bundled skills are enabled fro ## Lobu Starter Skill -The bundled Lobu skill teaches an agent the project layout, `lobu.toml`, prompt files, evals, memory tools, watchers, and client setup. Two places to install it: +The bundled Lobu skill teaches an agent the project layout, `lobu.config.ts`, prompt files, evals, memory tools, watchers, and client setup. Two places to install it: ### In your coding agent @@ -71,21 +71,21 @@ For instruction-only skills, omit frontmatter and keep only the markdown body. ## What Does Not Belong In A Skill -- Tool visibility and MCP approval bypasses belong in [`lobu.toml`](/reference/lobu-toml/), not in `SKILL.md` -- Destructive MCP tools still follow the normal approval flow unless the operator configures `[agents..tools].pre_approved` +- Tool visibility and MCP approval bypasses belong in [`lobu.config.ts`](/reference/lobu-config/), not in `SKILL.md` +- Destructive MCP tools still follow the normal approval flow unless the operator configures the agent `tools.preApproved` list See [Tool Policy](/guides/tool-policy/) for that split. ## Skills Vs Memory - **Skills** teach the agent how to work and what capabilities to request. -- **Memory** is the long-term, shared knowledge surface — enabled per-project via `[memory]` in [`lobu.toml`](/reference/lobu-toml/). +- **Memory** is the long-term, shared knowledge surface, enabled per-project via `defineConfig({ org })` in [`lobu.config.ts`](/reference/lobu-config/). -Installing the Lobu starter skill teaches the workflow; the memory wiring itself lives in `lobu.toml`. See [Memory](/getting-started/memory/). +Installing the Lobu starter skill teaches the workflow; the memory wiring itself lives in `lobu.config.ts`. See [Memory](/getting-started/memory/). ## Read Next - [SKILL.md Reference](/reference/skill-md/) - [Memory](/getting-started/memory/) -- [`lobu.toml` Reference](/reference/lobu-toml/) +- [`lobu.config.ts` Reference](/reference/lobu-config/) - [Lobu Memory CLI Reference](/reference/lobu-memory/) diff --git a/packages/landing/src/content/docs/guides/admin-ui.md b/packages/landing/src/content/docs/guides/admin-ui.md index 49faf21bb..00342cca1 100644 --- a/packages/landing/src/content/docs/guides/admin-ui.md +++ b/packages/landing/src/content/docs/guides/admin-ui.md @@ -9,7 +9,7 @@ Lobu exposes a settings API at `/api/v1/agents` for managing agents at runtime. ### Create an agent -Agents are created via `lobu.toml` (at startup) or the API (at runtime): +Agents are created via `lobu.config.ts` (with `lobu apply`) or the API (at runtime): ```bash # Via API diff --git a/packages/landing/src/content/docs/guides/agent-prompts.md b/packages/landing/src/content/docs/guides/agent-prompts.md index 872232808..148afef1d 100644 --- a/packages/landing/src/content/docs/guides/agent-prompts.md +++ b/packages/landing/src/content/docs/guides/agent-prompts.md @@ -1,18 +1,18 @@ --- title: Agent Workspace -description: How agent files are organized across prompt files, local skills, evals, and lobu.toml. +description: How agent files are organized across prompt files, local skills, evals, and lobu.config.ts. --- -Every Lobu agent has a workspace directory such as `agents/my-agent/`. `lobu.toml` points each agent at that directory with `dir = "./agents/my-agent"`. +Every Lobu agent has a workspace directory such as `agents/my-agent/`. `lobu.config.ts` points each agent at that directory with `dir: "./agents/my-agent"`. -The workspace contains the agent's prompt files plus any agent-local skills and evals. Operator-controlled configuration such as providers, connections, network policy, tool policy, and enabled registry skills lives in [`lobu.toml`](/reference/lobu-toml/). +The workspace contains the agent's prompt files plus any agent-local skills and evals. Operator-controlled configuration such as providers, connections, network policy, tool policy, and enabled registry skills lives in [`lobu.config.ts`](/reference/lobu-config/). At runtime, Lobu gives each user, DM, or channel its own isolated sandbox workspace. The files in `agents//` are templates for that sandbox, so every new workspace starts from the same `IDENTITY.md`, `SOUL.md`, `USER.md`, skills, and eval setup for that agent. ## Workspace layout ```text -lobu.toml +lobu.config.ts agents/ my-agent/ IDENTITY.md @@ -38,7 +38,7 @@ skills/ | Agent-local skills | `agents//skills//SKILL.md` | Available only to one agent | | Shared skills | `skills//SKILL.md` | Available to all agents in the project | | Evaluations | `agents//evals/` | Test cases for behavior and quality | -| Providers, connections, network, tool policy, enabled registry skills | `lobu.toml` | Operator-controlled runtime config | +| Providers, connections, network, tool policy, enabled registry skills | `lobu.config.ts` | Operator-controlled runtime config | ## Runtime model @@ -124,9 +124,9 @@ Local skills live in one of two places: Use this page to understand where those files live. Use the [`SKILL.md` Reference](/reference/skill-md/) for the skill file format, frontmatter, packages, MCP servers, and network declarations. -## lobu.toml +## lobu.config.ts -`lobu.toml` is the runtime wiring layer for the workspace. It tells Lobu: +`lobu.config.ts` is the runtime wiring layer for the workspace. It tells Lobu: - which agent directories exist - which providers and connections to use @@ -134,7 +134,7 @@ Use this page to understand where those files live. Use the [`SKILL.md` Referenc - which custom MCP servers are attached directly to the agent - what network and tool policy applies -Use the [`lobu.toml` Reference](/reference/lobu-toml/) for the exact schema. Keep operator policy there rather than spreading it into prompt files or `SKILL.md`. +Use the [`lobu.config.ts` Reference](/reference/lobu-config/) for the exact schema. Keep operator policy there rather than spreading it into prompt files or `SKILL.md`. ## Memory @@ -146,16 +146,24 @@ See [Memory](/getting-started/memory/) for the full model. ## Multi-agent layout -With multiple agents in `lobu.toml`, each one gets its own workspace: +With multiple agents in `lobu.config.ts`, each one gets its own workspace: -```toml -[agents.support] -name = "support" -dir = "./agents/support" +```ts +import { defineAgent, defineConfig } from "@lobu/sdk"; -[agents.sales] -name = "sales" -dir = "./agents/sales" +const support = defineAgent({ + id: "support", + name: "support", + dir: "./agents/support", +}); + +const sales = defineAgent({ + id: "sales", + name: "sales", + dir: "./agents/sales", +}); + +export default defineConfig({ agents: [support, sales] }); ``` ``` @@ -173,5 +181,5 @@ agents/ ## Related docs - [SKILL.md Reference](/reference/skill-md/) -- [`lobu.toml` Reference](/reference/lobu-toml/) +- [`lobu.config.ts` Reference](/reference/lobu-config/) - [Evaluations](/guides/evals/) diff --git a/packages/landing/src/content/docs/guides/agent-settings.md b/packages/landing/src/content/docs/guides/agent-settings.md index b08ab8bc4..ff179c1c9 100644 --- a/packages/landing/src/content/docs/guides/agent-settings.md +++ b/packages/landing/src/content/docs/guides/agent-settings.md @@ -10,7 +10,7 @@ Agent settings control behavior of each worker session. Two surfaces feed an agent's effective config: - **Runtime config** — the camelCase keys below, stored per agent and edited through the web UI or the settings API. -- **`lobu.toml` operator config** — file-first declarations (e.g. `[agents..tools]`, `[agents..egress]`, guardrails) applied with `lobu apply`. +- **`lobu.config.ts` operator config** — code-as-config declarations on `defineAgent` (e.g. `tools`, `egress`, `guardrails`) applied with `lobu apply`. Runtime config keys: @@ -23,7 +23,7 @@ Runtime config keys: - **Verbose logging** — `verboseLogging` to show tool calls and reasoning - **Template inheritance** — `templateAgentId` for settings fallback from a template agent -Allowed/disallowed tools are part of the `lobu.toml` operator surface — `[agents..tools]`. +Allowed/disallowed tools are part of the `lobu.config.ts` operator surface — the agent `tools` field. ## How Settings Apply @@ -31,7 +31,7 @@ Allowed/disallowed tools are part of the `lobu.toml` operator surface — `[agen - Worker fetches session context from gateway before execution. - Tool policy is applied before tools are exposed to the model. -See [Tool Policy](/guides/tool-policy/) for the operator-facing config, and [`lobu.toml` reference](/reference/lobu-toml/) for the exact schema. +See [Tool Policy](/guides/tool-policy/) for the operator-facing config, and [`lobu.config.ts` reference](/reference/lobu-config/) for the exact schema. ## Practical Guidance @@ -41,20 +41,20 @@ See [Tool Policy](/guides/tool-policy/) for the operator-facing config, and [`lo ## Memory Plugins -Memory is pluggable. In file-first projects, the gateway first checks `[memory]` in `lobu.toml`; any agent can still override the default via `pluginsConfig`. +Memory is pluggable. The gateway resolves the org from `defineConfig({ org })` in `lobu.config.ts`; any agent can still override the default via `pluginsConfig`. ### Defaults | Effective config | Plugin used | |---|---| -| `[memory]` disabled or unresolved, and no `MEMORY_URL` override | `@openclaw/native-memory` — files under the worker workspace. Not shared across threads. | -| `[memory]` enabled | `@lobu/openclaw-plugin` — the OpenClaw memory plugin for Lobu. It translates OpenClaw memory calls into Lobu MCP requests via the gateway's `/mcp/lobu` proxy. Cross-session, shareable across agents. | -| `MEMORY_URL` set | Used as the base Lobu MCP endpoint before Lobu scopes it to the org from `[memory]` in `lobu.toml`. Useful for local or custom Lobu deployments. | +| No `org` set and no `MEMORY_URL` override | `@openclaw/native-memory` — files under the worker workspace. Not shared across threads. | +| `org` set | `@lobu/openclaw-plugin` — the OpenClaw memory plugin for Lobu. It translates OpenClaw memory calls into Lobu MCP requests via the gateway's `/mcp/lobu` proxy. Cross-session, shareable across agents. | +| `MEMORY_URL` set | Used as the base Lobu MCP endpoint before Lobu scopes it to the org from `defineConfig({ org })`. Useful for local or custom Lobu deployments. | -`lobu init` scaffolds the file-first Lobu memory layout for memory-enabled projects: +`lobu init` scaffolds the Lobu memory wiring for memory-enabled projects: -- `[memory]` in `lobu.toml` (org, name, description, models, data) -- `models/` +- `org` / `orgName` in `defineConfig` (`lobu.config.ts`) +- the entity, relationship, and watcher types declared with `defineEntityType` / `defineRelationshipType` / `defineWatcher` - `data/` For **Lobu Cloud**, Lobu can use the hosted default automatically. For **Lobu Local** and **Custom URL**, `MEMORY_URL` remains the base-endpoint override. diff --git a/packages/landing/src/content/docs/guides/architecture.mdx b/packages/landing/src/content/docs/guides/architecture.mdx index 0d1db4e85..1dc43069e 100644 --- a/packages/landing/src/content/docs/guides/architecture.mdx +++ b/packages/landing/src/content/docs/guides/architecture.mdx @@ -25,7 +25,7 @@ Lobu is embedded-only: the gateway, agent workers, the embeddings model, and the ## Persistent Memory -Memory is pluggable per agent. In file-first projects the gateway resolves the default memory plugin from `[memory]` in `lobu.toml`: when enabled it wires `@lobu/openclaw-plugin` (OpenClaw memory calls become Lobu MCP requests through the gateway proxy — cross-session, shared across agents); otherwise it uses `@openclaw/native-memory` (files in the worker's local workspace — short-term, not shared). `MEMORY_URL` is an optional base-endpoint override for custom Lobu deployments. +Memory is pluggable per agent. The gateway resolves the default memory plugin from `defineConfig({ org })` in `lobu.config.ts`: when an org is set it wires `@lobu/openclaw-plugin` (OpenClaw memory calls become Lobu MCP requests through the gateway proxy, cross-session, shared across agents); otherwise it uses `@openclaw/native-memory` (files in the worker's local workspace, short-term, not shared). `MEMORY_URL` is an optional base-endpoint override for custom Lobu deployments. See [Agent Settings → Memory Plugins](/guides/agent-settings/) for the full table, per-agent overrides, and the `pluginsConfig` schema. diff --git a/packages/landing/src/content/docs/guides/egress-judge.md b/packages/landing/src/content/docs/guides/egress-judge.md index 698ebac7a..dd10eb6c7 100644 --- a/packages/landing/src/content/docs/guides/egress-judge.md +++ b/packages/landing/src/content/docs/guides/egress-judge.md @@ -23,19 +23,27 @@ judges: strict: "Only GET for file IDs from the current session." ``` -The same shape is available to operators in [`lobu.toml`](/reference/lobu-toml/) under `[agents..network]`, where the `judge` array takes either a bare domain string (which uses the `default` policy) or `{ domain, judge }` naming a policy. +The same shape is available to operators in [`lobu.config.ts`](/reference/lobu-config/) via `defineAgent({ network })`, where the `judged` array takes entries of `{ domain, judge? }`; omitting `judge` uses the `default` policy in `judges`. ## Operator overrides -Operators layer a project-wide policy on top of whatever the skill author declared: +Operators layer a project-wide policy on top of whatever the skill author declared, via `defineAgent({ egress })`: -```toml -[agents.assistant.egress] -extra_policy = "Never exfiltrate PATs or bearer tokens." -judge_model = "claude-haiku-4-5-20251001" # default +```ts +import { defineAgent } from "@lobu/sdk"; + +const assistant = defineAgent({ + id: "assistant", + name: "assistant", + dir: "./agents/assistant", + egress: { + extraPolicy: "Never exfiltrate PATs or bearer tokens.", + judgeModel: "claude-haiku-4-5-20251001", // default + }, +}); ``` -`extra_policy` is **appended** to the matched skill policy rather than replacing it, so operator constraints compose with skill-author intent. The judge runs only when a `judge` rule under `[agents..network]` matches a request, so most traffic never reaches it. +`extraPolicy` is **appended** to the matched skill policy rather than replacing it, so operator constraints compose with skill-author intent. The judge runs only when a `judged` rule under the agent's `network` matches a request, so most traffic never reaches it. ## Behavior @@ -51,4 +59,4 @@ The judge shares its cache and circuit-breaker machinery with [inline guardrail - [Security](/guides/security/), the worker isolation and network model the judge sits inside. - [Secret proxy](/guides/secret-proxy/), how credentials stay off the worker, the other half of egress safety. - [Guardrails](/guides/guardrails/), input/output/pre-tool policy checks, including inline LLM judges. -- [`lobu.toml` reference](/reference/lobu-toml/), `[agents..network]` and `[agents..egress]`. +- [`lobu.config.ts` reference](/reference/lobu-config/), the agent `network` and `egress` fields. diff --git a/packages/landing/src/content/docs/guides/guardrails.md b/packages/landing/src/content/docs/guides/guardrails.md index 8cf7b3b76..03f60d0b8 100644 --- a/packages/landing/src/content/docs/guides/guardrails.md +++ b/packages/landing/src/content/docs/guides/guardrails.md @@ -27,7 +27,7 @@ The `pre-tool` block message is intentionally generic. The real reason is hidden ## Built-in guardrails -Three primitives ship from the gateway and are registered at boot. Reference them by name in `lobu.toml`. +Three primitives ship from the gateway and are registered at boot. Reference them by name in `lobu.config.ts`. | Name | Stage(s) | Catches | |---|---|---| @@ -39,35 +39,30 @@ Three primitives ship from the gateway and are registered at boot. Reference the ## Enabling guardrails -List built-in (or globally-registered) guardrail names on the agent in [`lobu.toml`](/reference/lobu-toml/): +List built-in (or globally-registered) guardrail names on the agent in [`lobu.config.ts`](/reference/lobu-config/): -```toml -[agents.assistant] -name = "assistant" -dir = "./agents/assistant" -guardrails = ["secret-scan", "pii-scan", "forbidden-tools"] +```ts +import { defineAgent } from "@lobu/sdk"; + +const assistant = defineAgent({ + id: "assistant", + name: "assistant", + dir: "./agents/assistant", + guardrails: ["secret-scan", "pii-scan", "forbidden-tools"], +}); ``` Names that don't resolve to a guardrail registered in the gateway's `GuardrailRegistry` at startup are logged and skipped. A typo silently disables protection rather than failing the boot, so check the startup logs after changing this list. ## Inline LLM judges -When a regex won't express the policy, attach an ad-hoc LLM-judge guardrail with `[[agents..guardrails_inline]]`. Each entry names a stage and a judge prompt; the gateway materializes it into a guardrail at resolve time. - -```toml -[[agents.assistant.guardrails_inline]] -stage = "output" -judge = "Never mention competitor product names." +When a regex won't express the policy, attach an ad-hoc LLM-judge guardrail in the agent's settings (via the `/agents` admin UI or the agent settings API). Each entry names a stage and a judge prompt; the gateway materializes it into a guardrail at resolve time. -[[agents.assistant.guardrails_inline]] -stage = "pre-tool" -tools = ["github.delete_repo"] -judge = "Only allow when the issue reference matches the active sprint." -``` +Each inline judge has: -- `stage` is one of `input`, `output`, `pre-tool`. -- `tools` narrows a `pre-tool` judge to specific tool names; it is ignored for other stages. -- `judge` is the policy text the LLM evaluates the stage context against. +- `stage`, one of `input`, `output`, `pre-tool`. +- `tools`, which narrows a `pre-tool` judge to specific tool names (e.g. `github.delete_repo`); it is ignored for other stages. +- `judge`, the policy text the LLM evaluates the stage context against (e.g. "Never mention competitor product names."). Inline judges run through a shared judge client with a verdict cache and a circuit breaker that fails closed after repeated failures (the same machinery as the [egress judge](/guides/egress-judge/)). Each inline entry materializes into a guardrail named `inline::`, so operators can target it for disabling. @@ -79,17 +74,9 @@ Skills can only add `pre-tool` guardrails. They cannot weaken input/output polic ## Operator overrides -The full set for an agent is the union of enabled built-ins, skill-provided guardrails, and inline judges, deduplicated by name within each stage. The operator's exclude list is applied **last** and wins: - -```toml -[agents.assistant] -guardrails_disabled = [ - "pii-scan", # turn off a built-in - "skill:github:inline:pre-tool:1a2b3c4d", # turn off a skill's judge -] -``` +The full set for an agent is the union of enabled built-ins, skill-provided guardrails, and inline judges, deduplicated by name within each stage. The operator's exclude list, set in the agent's settings, is applied **last** and wins. For example, disabling a built-in like `pii-scan` and a skill's judge like `skill:github:inline:pre-tool:1a2b3c4d`. -`guardrails_disabled` matches against each guardrail's resolved `.name`, including the synthesized `inline::` and `skill::inline:pre-tool:` names. Because it is operator-only and applied last, it is the single override point: a skill cannot re-enable something an operator disabled. +The disabled list matches against each guardrail's resolved `.name`, including the synthesized `inline::` and `skill::inline:pre-tool:` names. Because it is operator-only and applied last, it is the single override point: a skill cannot re-enable something an operator disabled. The merge happens in `resolveAgentGuardrails()`; see `packages/server/src/gateway/guardrails/aggregator.ts` and `judge-factory.ts` for the resolution order, judge cache, and circuit breaker. @@ -102,4 +89,4 @@ Every trip, at any stage, built-in or judge, writes an event with `semantic_type - [Egress judge](/guides/egress-judge/), the per-request LLM judge for outbound network access. Shares the judge cache and circuit-breaker machinery. - [Tool Policy](/guides/tool-policy/), MCP tool approval and `pre_approved` overrides, the layer that sits alongside `pre-tool` guardrails. - [Secret proxy](/guides/secret-proxy/), how `secret-scan` complements credential isolation at egress. -- [`lobu.toml` reference](/reference/lobu-toml/), the `guardrails`, `guardrails_inline`, and `guardrails_disabled` keys. +- [`lobu.config.ts` reference](/reference/lobu-config/), the `guardrails` field on `defineAgent`. Inline judges and the disabled list are set in the agent's settings. diff --git a/packages/landing/src/content/docs/guides/mcp-proxy.md b/packages/landing/src/content/docs/guides/mcp-proxy.md index 6f174b648..5e0e7217b 100644 --- a/packages/landing/src/content/docs/guides/mcp-proxy.md +++ b/packages/landing/src/content/docs/guides/mcp-proxy.md @@ -36,7 +36,7 @@ There are three ways an MCP server can authenticate: | **Device-code OAuth** | `oauth` on the MCP server | Per-user OAuth — each user authenticates in their browser | | **Lobu-managed** | N/A (Lobu handles internally) | Third-party APIs (GitHub, Google, Linear, etc.) | -Each MCP server is configured under `[agents..skills.mcp.]` in [`lobu.toml`](/reference/lobu-toml/), under `mcpServers.` in a skill's [`SKILL.md`](/reference/skill-md/) frontmatter, or in the agent's settings. The JSON snippets below show the fields a single server config accepts: +Each MCP server is configured under `mcpServers.` on `defineAgent` in [`lobu.config.ts`](/reference/lobu-config/), under `mcpServers.` in a skill's [`SKILL.md`](/reference/skill-md/) frontmatter, or in the agent's settings. The JSON snippets below show the fields a single server config accepts: ### No auth diff --git a/packages/landing/src/content/docs/guides/security.md b/packages/landing/src/content/docs/guides/security.md index dd8c69304..831bce900 100644 --- a/packages/landing/src/content/docs/guides/security.md +++ b/packages/landing/src/content/docs/guides/security.md @@ -26,7 +26,7 @@ Domain format: exact (`api.example.com`) or wildcard (`.example.com` matches all ### LLM-judged egress -For domains where flat allow/deny is too coarse, like Slack, GitHub user-content, or Notion, skills can route requests through an LLM judge that decides per request. Only domains that match a `judge` rule invoke it, so the cost stays bounded. Skills declare judged domains and named policies in `SKILL.md`; operators layer an `extra_policy` on top in `lobu.toml`. +For domains where flat allow/deny is too coarse, like Slack, GitHub user-content, or Notion, skills can route requests through an LLM judge that decides per request. Only domains that match a `judge` rule invoke it, so the cost stays bounded. Skills declare judged domains and named policies in `SKILL.md`; operators layer an `extraPolicy` on top in `lobu.config.ts`. See [Egress judge](/guides/egress-judge/) for the policy schema, judge defaults (Haiku, verdict cache, fail-closed circuit breaker), and the `egress-decision` audit record. @@ -42,14 +42,14 @@ Workers never receive raw provider credentials or OAuth tokens. The gateway reso - **AWS Secrets Manager refs are read-only**. `aws-sm://...` works well for durable provider secret references, but refreshed user tokens still need a writable secret store. - **Workers never touch third-party OAuth tokens directly**. They call integrations through Lobu MCP tools and the gateway proxy. -For concrete config examples, see the [`lobu.toml` reference](/reference/lobu-toml/) and the [CLI reference](/reference/cli/). +For concrete config examples, see the [`lobu.config.ts` reference](/reference/lobu-config/) and the [CLI reference](/reference/cli/). ## MCP Proxy - Workers discover MCP tools through the gateway and call them with their own JWT token scoped to the agent. - The proxy enforces **SSRF protection**: upstream MCP URLs that resolve to internal or private IP ranges are blocked. - **Destructive tool approval**: per the MCP spec, tools without `readOnlyHint: true` or `destructiveHint: false` require user approval in-thread (`Allow once / 1h / 24h / Always / Deny`). The user's choice is recorded in the grant store. -- **Operator override**: `[agents..tools]` in `lobu.toml` accepts a `pre_approved` list of grant patterns (e.g. `/mcp/gmail/tools/list_messages`, `/mcp/linear/tools/*`) that bypass the approval card. This is operator-only — skills cannot set it — so the escape hatch is always visible in code review. See [Tool Policy](/guides/tool-policy/) and the [`lobu.toml` reference](/reference/lobu-toml/). +- **Operator override**: the agent `tools` field in `lobu.config.ts` accepts a `preApproved` list of grant patterns (e.g. `/mcp/gmail/tools/list_messages`, `/mcp/linear/tools/*`) that bypass the approval card. This is operator-only — skills cannot set it — so the escape hatch is always visible in code review. See [Tool Policy](/guides/tool-policy/) and the [`lobu.config.ts` reference](/reference/lobu-config/). ## Further Reading diff --git a/packages/landing/src/content/docs/guides/sync-from-github.md b/packages/landing/src/content/docs/guides/sync-from-github.md index 98a2a14d8..50d365d7b 100644 --- a/packages/landing/src/content/docs/guides/sync-from-github.md +++ b/packages/landing/src/content/docs/guides/sync-from-github.md @@ -3,15 +3,15 @@ title: Sync agents from GitHub description: Manage agent definitions in a git repo and have GitHub Actions apply them to your Lobu org on every push. --- -`lobu apply` is the apply primitive — it diffs a local `lobu.toml` + agent dirs against a Lobu Cloud org and converges the org to match. Any CI runner can call it, and GitHub Actions is the path of least resistance: push to `main` triggers an apply, PRs preview a dry-run diff in the check output. +`lobu apply` is the apply primitive. It diffs a local `lobu.config.ts` + agent dirs against a Lobu Cloud org and converges the org to match. Any CI runner can call it, and GitHub Actions is the path of least resistance: push to `main` triggers an apply, PRs preview a dry-run diff in the check output. There is no Lobu-side sync feature. The repo is the source of truth and CI is the cron. That keeps Lobu opinion-free about how you structure branches, reviews, multi-env promotion, secret stores — those are choices you already made for the rest of your stack. ## What you need -1. A git repo with a `lobu.toml` at the root (or in a subdirectory). +1. A git repo with a `lobu.config.ts` at the root (or in a subdirectory). 2. A `LOBU_TOKEN` secret in the repo (`Settings → Secrets and variables → Actions`). Mint one with `lobu token create` from a logged-in shell (it defaults to the `mcp:read mcp:write` scope, which `lobu apply` uses). -3. Any provider keys your agents reference (`ANTHROPIC_API_KEY`, etc.) added as repo secrets too — `lobu apply` reads them via `$VAR` interpolation in `lobu.toml`. +3. Any provider keys your agents reference (`ANTHROPIC_API_KEY`, etc.) added as repo secrets too. `lobu apply` reads them via the `secret("VAR")` references in `lobu.config.ts`. ## Drop-in workflow @@ -59,7 +59,8 @@ jobs: ``` my-agents/ -├── lobu.toml +├── lobu.config.ts +├── package.json ├── agents/ │ ├── support-bot/ │ │ ├── IDENTITY.md @@ -70,18 +71,26 @@ my-agents/ └── .github/workflows/lobu-apply.yml ``` -`lobu.toml` references each agent's directory: - -```toml -[agents.support-bot] -name = "support-bot" -description = "Customer support triage" -dir = "./agents/support-bot" - -[[agents.support-bot.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" +`lobu.config.ts` references each agent's directory: + +```ts +import { defineAgent, defineConfig, secret } from "@lobu/sdk"; + +const supportBot = defineAgent({ + id: "support-bot", + name: "support-bot", + description: "Customer support triage", + dir: "./agents/support-bot", + providers: [ + { + id: "anthropic", + model: "claude/sonnet-4-5", + key: secret("ANTHROPIC_API_KEY"), + }, + ], +}); + +export default defineConfig({ agents: [supportBot] }); ``` See [`lobu apply`](/reference/lobu-apply/) for the full file format and the list of fields that get synced. @@ -108,7 +117,7 @@ Stage on push-to-main, prod on tag, prod-on-approval — all standard Actions pa ## What `lobu apply` will not do - It will not edit secrets in your provider accounts. `$VAR` references are resolved at apply time from the runner's environment; the values never leave the runner. -- It will not import existing cloud-side agents into your repo. If you've been editing in the admin UI and want to flip to git-managed, hand-write `lobu.toml` against the current state. (A `lobu pull` to scaffold this automatically is not yet implemented.) +- It will not import existing cloud-side agents into your repo on a regular apply. If you've been editing in the admin UI and want to flip to git-managed, run `lobu init --from-org ` to scaffold a re-appliable `lobu.config.ts` from the current cloud state. - It will not silently overwrite manual UI edits without showing the diff. Every apply prints the plan; `--dry-run` lets you preview without converging. ## Drift between UI and git diff --git a/packages/landing/src/content/docs/guides/testing.md b/packages/landing/src/content/docs/guides/testing.md index b4ce96a56..3f3f9dd5b 100644 --- a/packages/landing/src/content/docs/guides/testing.md +++ b/packages/landing/src/content/docs/guides/testing.md @@ -17,7 +17,7 @@ npx @lobu/cli@latest chat "Hello, what can you do?" npx @lobu/cli@latest chat "What's on my calendar?" --thread my-test npx @lobu/cli@latest chat "Cancel the 3pm meeting" --thread my-test -# Target a specific agent (if you have multiple in lobu.toml) +# Target a specific agent (if you have multiple in lobu.config.ts) npx @lobu/cli@latest chat "Hello" --agent support # Dry run (no history persisted) diff --git a/packages/landing/src/content/docs/guides/tool-policy.md b/packages/landing/src/content/docs/guides/tool-policy.md index 67258ab42..c0dc1f34a 100644 --- a/packages/landing/src/content/docs/guides/tool-policy.md +++ b/packages/landing/src/content/docs/guides/tool-policy.md @@ -3,22 +3,27 @@ title: Tool Policy description: Where tool permissions and MCP approval overrides are configured in Lobu. --- -Tool policy is configured per agent in `lobu.toml`, not in `SKILL.md`. +Tool policy is configured per agent in `lobu.config.ts` via `defineAgent({ tools })`, not in `SKILL.md`. -Use `[agents..tools]` for two separate concerns: +Use the `tools` field for two separate concerns: - **Worker-side tool visibility**: `allowed`, `denied`, `strict` -- **MCP approval bypass**: `pre_approved` - -```toml -[agents.support.tools] -pre_approved = [ - "/mcp/gmail/tools/list_messages", - "/mcp/linear/tools/*", -] -allowed = ["Read", "Grep", "mcp__gmail__*"] -denied = ["Bash(rm:*)"] -strict = false +- **MCP approval bypass**: `preApproved` + +```ts +import { defineAgent } from "@lobu/sdk"; + +const support = defineAgent({ + id: "support", + name: "support", + dir: "./agents/support", + tools: { + preApproved: ["/mcp/gmail/tools/list_messages", "/mcp/linear/tools/*"], + allowed: ["Read", "Grep", "mcp__gmail__*"], + denied: ["Bash(rm:*)"], + strict: false, + }, +}); ``` ## What Each Field Does @@ -26,9 +31,9 @@ strict = false - `allowed`: tools the worker can call - `denied`: tools to always block; takes precedence over `allowed` - `strict`: when `true`, only `allowed` tools are visible to the worker -- `pre_approved`: MCP tool grant patterns that skip the in-thread approval card +- `preApproved`: MCP tool grant patterns that skip the in-thread approval card -## Why This Lives In `lobu.toml` +## Why This Lives In `lobu.config.ts` Tool policy is operator-controlled configuration. Skills can add instructions, MCP servers, network domains, and packages, but they cannot silently widen tool access or pre-approve destructive MCP calls. @@ -37,8 +42,8 @@ That split keeps approval overrides visible in code review and prevents a skill ## Skills vs Agent Config - Use `SKILL.md` for instructions and capability declarations such as MCP servers, Nix packages, and network requirements. -- Use `lobu.toml` for operator policy such as tool visibility and `pre_approved` MCP grants. +- Use `lobu.config.ts` for operator policy such as tool visibility and `preApproved` MCP grants. ## Reference -For the exact schema and field definitions, see the [`lobu.toml` reference](/reference/lobu-toml/) section for `[agents..tools]`. +For the exact schema and field definitions, see the [`lobu.config.ts` reference](/reference/lobu-config/) section for the agent `tools` field. diff --git a/packages/landing/src/content/docs/guides/troubleshooting.md b/packages/landing/src/content/docs/guides/troubleshooting.md index 49b28a88a..29e935a26 100644 --- a/packages/landing/src/content/docs/guides/troubleshooting.md +++ b/packages/landing/src/content/docs/guides/troubleshooting.md @@ -23,7 +23,7 @@ make clean-workers # in the monorepo # - Port 8787 already in use → Change GATEWAY_PORT or PORT in .env # - DATABASE_URL set but not reachable → see "Agent not responding" below # (with the default PGlite backend there's no DATABASE_URL to misconfigure) -# - Invalid lobu.toml → npx @lobu/cli@latest validate +# - Invalid lobu.config.ts → npx @lobu/cli@latest validate ``` ## Agent not responding @@ -118,8 +118,8 @@ rm -rf workspaces/* # Lobu runs in-process with the gateway. /health covers both. curl http://localhost:8787/health -# Check file-first memory config -# - lobu.toml should contain [memory] with enabled = true and an org +# Check memory config +# - lobu.config.ts should set defineConfig({ org }) so the memory endpoint resolves # - MEMORY_URL is optional; use it mainly for custom external Lobu URLs # Test connection diff --git a/packages/landing/src/content/docs/platforms/slack.mdx b/packages/landing/src/content/docs/platforms/slack.mdx index fb6a2d91d..ab1b0d2f3 100644 --- a/packages/landing/src/content/docs/platforms/slack.mdx +++ b/packages/landing/src/content/docs/platforms/slack.mdx @@ -66,11 +66,11 @@ By default, destructive MCP tool calls require in-thread user approval. Lobu use This is the conservative default from the MCP spec — tools are presumed destructive unless they say otherwise. -### Operator override (`[agents..tools]`) +### Operator override (the agent `tools` field) -If you want specific MCP tools to skip the approval prompt, configure `pre_approved` under `[agents..tools]` in `lobu.toml`. +If you want specific MCP tools to skip the approval prompt, configure `preApproved` under the agent `tools` field in `lobu.config.ts`. -See [Tool Policy](/guides/tool-policy/) for the behavior and [`lobu.toml` reference](/reference/lobu-toml/) for the schema. +See [Tool Policy](/guides/tool-policy/) for the behavior and [`lobu.config.ts` reference](/reference/lobu-config/) for the schema. ## Typical Use Cases diff --git a/packages/landing/src/content/docs/reference/cli.md b/packages/landing/src/content/docs/reference/cli.md index 92a62066e..b31694065 100644 --- a/packages/landing/src/content/docs/reference/cli.md +++ b/packages/landing/src/content/docs/reference/cli.md @@ -22,7 +22,7 @@ lobu ### `init [name]` -Scaffold a local agent project with `lobu.toml`, `.env`, and an agent directory. +Scaffold a local agent project with `lobu.config.ts`, `.env`, and an agent directory. ```bash npx @lobu/cli@latest init my-agent @@ -30,10 +30,12 @@ npx @lobu/cli@latest init my-agent Generates: -- `lobu.toml` — local project/apply/validate configuration +- `lobu.config.ts`: the TypeScript project entrypoint (`defineConfig` from `@lobu/sdk`) +- `package.json` + `tsconfig.json`: declare `@lobu/sdk` / `@lobu/connector-sdk` and give the editor type resolution - `.env` — local environment variables (API keys, optional external `DATABASE_URL`) - `agents/{name}/` — `IDENTITY.md`, `SOUL.md`, `USER.md`, local skills, and evals - `skills/` — shared local skills directory +- `connectors/`: custom `*.connector.ts` files - `AGENTS.md`, `TESTING.md`, `README.md`, `.gitignore` Interactive prompts guide you through provider, platform, network access policy, gateway port, public URL, and memory configuration. Local runs use bundled PGlite by default; set `DATABASE_URL` when you want to use external Postgres with pgvector. @@ -42,7 +44,7 @@ Interactive prompts guide you through provider, platform, network access policy, ### `run` (aliases: `dev`, `start`) -Run the embedded Lobu stack. `lobu.toml` is not required. With no `DATABASE_URL`, the command starts bundled local PGlite and stores data under `~/.lobu/data` (override with `LOBU_DATA_DIR`). If `DATABASE_URL` is set in the environment or `.env`, Lobu uses that external Postgres instead. +Run the embedded Lobu stack. `lobu.config.ts` is not required. With no `DATABASE_URL`, the command starts bundled local PGlite and stores data under `~/.lobu/data` (override with `LOBU_DATA_DIR`). If `DATABASE_URL` is set in the environment or `.env`, Lobu uses that external Postgres instead. ```bash npx @lobu/cli@latest run @@ -121,7 +123,7 @@ npx @lobu/cli@latest agent update my-agent --description "Handles support" npx @lobu/cli@latest agent delete my-agent --yes ``` -`agent scaffold ` adds a new local agent (`agents//*` plus an entry in `lobu.toml`) without touching existing agents — the local-files counterpart of `agent create`: +`agent scaffold ` adds a new local agent (`agents//*` plus a `defineAgent` entry in `lobu.config.ts`) without touching existing agents, the local-files counterpart of `agent create`: ```bash npx @lobu/cli@latest agent scaffold support-bot --name "Support Bot" --description "Handles tickets" @@ -154,7 +156,7 @@ npx @lobu/cli@latest chat "Status update" -c staging | Flag | Description | |------|-------------| -| `-a, --agent ` | Agent ID (defaults to first agent in local `lobu.toml` when present) | +| `-a, --agent ` | Agent ID (defaults to first agent in local `lobu.config.ts` when present) | | `-u, --user ` | User ID to impersonate, e.g. `telegram:12345`. With this flag the message routes through the user's platform (Telegram/Slack) | | `-t, --thread ` | Thread/conversation ID for multi-turn conversations | | `-g, --gateway ` | Gateway URL (default: `http://localhost:8787` or from `.env`) | @@ -181,7 +183,7 @@ LOBU_TOKEN=$(npx @lobu/cli@latest token) \ ### `validate` -Validate local `lobu.toml` schema, skill IDs, and provider configuration. +Validate that local `lobu.config.ts` loads and conforms to the schema, plus skill IDs and provider configuration. ```bash npx @lobu/cli@latest validate @@ -193,7 +195,7 @@ Returns exit code `1` if validation fails. ### `apply` (alias: `deploy`) -Sync local `lobu.toml` and agent directories to a Lobu Cloud org. Idempotent, prompt-confirmed, one-way (files are the source of truth). +Sync local `lobu.config.ts` and agent directories to a Lobu Cloud org. Idempotent, prompt-confirmed, one-way (files are the source of truth). ```bash npx @lobu/cli@latest apply # plan + prompt + apply diff --git a/packages/landing/src/content/docs/reference/lobu-apply.md b/packages/landing/src/content/docs/reference/lobu-apply.md index 6fae496d5..36b7b7561 100644 --- a/packages/landing/src/content/docs/reference/lobu-apply.md +++ b/packages/landing/src/content/docs/reference/lobu-apply.md @@ -1,9 +1,9 @@ --- title: lobu apply CLI Reference -description: Sync your local lobu.toml + agent dirs to a Lobu Cloud org. One-way, idempotent, prompt-confirmed. +description: Sync your local lobu.config.ts + agent dirs to a Lobu Cloud org. One-way, idempotent, prompt-confirmed. --- -`lobu apply` reads `lobu.toml`, computes a diff against your cloud org, shows a plan, and — once you accept — calls existing CRUD endpoints in dependency order to converge the org to match your files. +`lobu apply` imports `lobu.config.ts`, computes a diff against your cloud org, shows a plan, and once you accept calls existing CRUD endpoints in dependency order to converge the org to match your project. Mental model: `terraform apply` lite. Files are the source of truth; the cloud is a follower. @@ -13,8 +13,8 @@ Mental model: `terraform apply` lite. Files are the source of truth; the cloud i lobu apply # plan + prompt + apply lobu apply --dry-run # plan only lobu apply --yes # plan + apply, no prompt (CI) -lobu apply --only agents # restrict to agent + platform resources -lobu apply --only memory # restrict to entity + relationship types +lobu apply --only agents # restrict to agent resources +lobu apply --only memory # restrict to entity + relationship types + watchers lobu apply --org my-org # override active org lobu apply --url https://... # override the server URL lobu apply --force # bypass the .lobu/project.json link guard @@ -36,30 +36,45 @@ Authentication is shared with the rest of the CLI. Run `lobu login` once. - Agents (metadata: `agentId`, `name`, `description`) - Agent settings: `networkConfig`, `egressConfig`, `nixConfig`, `mcpServers`, `skillsConfig`, `toolsConfig`, `guardrails`, `preApprovedTools`, `providerModelPreferences`, `modelSelection`, `IDENTITY.md` / `SOUL.md` / `USER.md` -- Chat platforms under `[[agents..platforms]]`, keyed by a stable ID derived from `(agentId, type, name?)` -- Memory entity types, relationship types, and watchers from YAML bundles under `[memory].models` - -Model bundles use the dbt-style Lobu model schema: - -```yaml -version: 2 -entities: - - slug: account - name: Account -relationships: - - slug: owns - name: Owns -watchers: - - slug: account-digest - name: Account digest - schedule: "0 9 * * 1" - prompt: Summarize account changes. +- Memory entity types, relationship types, and watchers declared with `defineEntityType` / `defineRelationshipType` / `defineWatcher` +- Connections and auth profiles declared with `defineConnection` / `defineAuthProfile`, plus the connectors they reference + +The memory schema is declared directly in `lobu.config.ts` and passed to `defineConfig`: + +```ts +import { + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, +} from "@lobu/sdk"; + +const account = defineEntityType({ key: "account", name: "Account" }); +const owns = defineRelationshipType({ key: "owns", name: "Owns" }); +const digest = defineWatcher({ + agent: "sales", + slug: "account-digest", + name: "Account digest", + schedule: "0 9 * * 1", + prompt: "Summarize account changes.", + extractionSchema: { type: "object", properties: {} }, +}); + +export default defineConfig({ + agents: [/* ... */], + entities: [account], + relationships: [owns], + watchers: [digest], +}); ``` +Chat platforms are not synced by `lobu apply`. Connect them through the `/agents` admin UI or the CRUD API. + ## What is not synced +- Chat platforms (connect them through the admin UI or CRUD API) - Memory data (entities, relationships, knowledge events) -- Secret values — `lobu apply` only checks that the env vars referenced as `$VAR` in `lobu.toml` are present locally, never uploads their values +- Secret values — `lobu apply` only checks that the env vars referenced via `secret("VAR")` in `lobu.config.ts` are present locally, never uploads their values - Anything not in the list above ## Plan output @@ -71,9 +86,7 @@ Each row is one of four verbs: | `+ create` | resource doesn't exist in the cloud — will be created | | `~ update` | resource exists with different content — will be patched (changed fields shown) | | `= noop` | resource exists and matches the desired state | -| `? drift` | cloud has a resource not declared in `lobu.toml` — **reported only**, never deleted in v1 | - -When a platform update will restart the live worker, the plan adds an inline warning line. +| `? drift` | cloud has a resource not declared in `lobu.config.ts` — **reported only**, never deleted in v1 | ## Apply order @@ -84,22 +97,24 @@ upsertAgent (POST /api/:org/agents/) ↓ patchAgentSettings (PATCH /api/:org/agents/:id/config) ↓ -upsertPlatform (PUT /api/:org/agents/:id/platforms/by-stable-id/:stableId) - ↓ upsertEntityType (manage_entity_schema) ↓ upsertRelationshipType (manage_entity_schema) + ↓ +upsertWatcher + ↓ +upsertAuthProfile / upsertConnection (when connectors are declared) ``` If any call fails, the CLI prints partial progress and exits non-zero. Every endpoint is idempotent — re-running converges. ## Required secrets -Before any mutation, `lobu apply` walks `lobu.toml` for `$VAR` references in: +Before any mutation, `lobu apply` collects every `secret("VAR")` reference in `lobu.config.ts`: -- `[[agents..providers]]` — `key`, `secret_ref` -- `[[agents..platforms]]` — every value in `[agents..platforms.config]` -- `[agents..skills.mcp.]` — `headers`, `env`, `oauth.client_id`, `oauth.client_secret` +- provider `key` on `defineAgent({ providers })` +- `mcpServers` `headers`, `env`, and `oauth` credentials on `defineAgent` +- `credentials` on `defineAuthProfile` Each name must be set in the apply runner's environment (e.g. via `.env` loaded by your shell). Any missing name short-circuits the apply with a list of every missing var. @@ -107,17 +122,7 @@ Secret values are never uploaded by `lobu apply`. Use your deployment's secret m ## Drift -Cloud-side resources not declared in `lobu.toml` are reported but never deleted. v1 has no `--prune`. To remove a cloud-side agent or platform, use the admin UI or the underlying CRUD endpoints directly; the next `lobu apply` will continue to surface it as drift until you remove it from the cloud or add it to your files. - -## Stable platform IDs - -Each platform's URL — including webhook URLs (`/api/v1/webhooks/`) — is derived from `(agentId, type, name)`: - -``` -{slugify(agentId)}-{slugify(type)}[-{slugify(name)}] -``` - -When you have more than one platform of the same `type` under the same agent, `name = "..."` is required. The same rule applies in `lobu run` (file-loader.ts) — both paths build identical stable IDs. +Cloud-side resources not declared in `lobu.config.ts` are reported but never deleted. v1 has no `--prune`. To remove a cloud-side agent, use the admin UI or the underlying CRUD endpoints directly; the next `lobu apply` will continue to surface it as drift until you remove it from the cloud or add it to your project. ## CI usage @@ -132,4 +137,4 @@ lobu apply --yes --org my-org - Lobu CLI: [CLI Reference](/reference/cli/) - Memory CLI: [Memory](/reference/lobu-memory/) -- `lobu.toml`: [Configuration Reference](/reference/lobu-toml/) +- `lobu.config.ts`: [Configuration Reference](/reference/lobu-config/) diff --git a/packages/landing/src/content/docs/reference/lobu-config.md b/packages/landing/src/content/docs/reference/lobu-config.md new file mode 100644 index 000000000..e20b94b35 --- /dev/null +++ b/packages/landing/src/content/docs/reference/lobu-config.md @@ -0,0 +1,515 @@ +--- +title: lobu.config.ts reference +description: Complete reference for the lobu.config.ts authoring file and the @lobu/sdk API. +sidebar: + order: 1 +--- + +`lobu.config.ts` is the project configuration file created by `lobu init`. It is a TypeScript module that default-exports `defineConfig({...})`. You author agents, providers, network access (including the LLM egress judge), guardrails, worker settings, the Lobu memory schema (entity types, relationship types, watchers), connections, and auth profiles by calling the `define*` functions from `@lobu/sdk`. + +`lobu apply` (and `lobu run`) import this entrypoint, read the default export, and map it to your org's desired state. `lobu init` also scaffolds a `package.json` that declares `@lobu/sdk` and `@lobu/connector-sdk` as devDependencies, plus a `tsconfig.json`, so your editor and `lobu apply` can resolve the SDK imports. + +## Minimal example + +```ts +import { defineAgent, defineConfig, secret } from "@lobu/sdk"; + +const agent = defineAgent({ + id: "my-agent", + name: "my-agent", + dir: "./agents/my-agent", + providers: [{ id: "openrouter", key: secret("OPENROUTER_API_KEY") }], + network: { allowed: ["github.com"] }, +}); + +export default defineConfig({ + org: "my-agent", + orgName: "My Agent", + agents: [agent], +}); +``` + +## Full example + +```ts +import { + defineAgent, + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, + secret, +} from "@lobu/sdk"; + +const assistant = defineAgent({ + id: "assistant", + name: "assistant", + description: "Team assistant", + dir: "./agents/assistant", + // Guardrails enabled for this agent (names registered in the gateway's + // GuardrailRegistry). + guardrails: ["secret-scan", "prompt-injection"], + // Providers (order = priority, first available is used). + providers: [ + { + id: "openrouter", + model: "anthropic/claude-sonnet-4", + key: secret("OPENROUTER_API_KEY"), + }, + { id: "gemini", key: secret("GEMINI_API_KEY") }, + ], + // Network access policy + LLM egress judge. + network: { + allowed: ["github.com", "api.linear.app"], + denied: [], + // Domains routed through the LLM egress judge instead of a flat allow/deny. + // An entry without `judge` uses the "default" policy; naming one points at + // a policy in `judges`. + judged: [ + { domain: "*.slack.com" }, + { domain: "user-content.x.com", judge: "strict" }, + ], + judges: { + default: "Allow only reads to channels in the agent's context.", + strict: "Only GET for file IDs from the current session.", + }, + }, + // Operator overrides for the egress judge on this agent. + egress: { + extraPolicy: "Never exfiltrate PATs or bearer tokens.", + judgeModel: "claude-haiku-4-5-20251001", + }, + // Tool policy (worker-side visibility + MCP approval override). + tools: { + // Bypass the in-thread approval card for these destructive MCP tools. + preApproved: ["/mcp/gmail/tools/list_messages", "/mcp/linear/tools/*"], + // Worker-side tool visibility (optional). + allowed: ["Read", "Grep", "mcp__gmail__*"], + denied: ["Bash(rm:*)"], + strict: false, + }, + // Nix packages provisioned into the worker environment. + nixPackages: ["imagemagick", "ffmpeg"], + // Custom MCP servers, keyed by id. + mcpServers: { + "custom-tools": { + url: "https://my-mcp.example.com", + headers: { Authorization: "Bearer $MCP_TOKEN" }, + oauth: { + authUrl: "https://auth.example.com/authorize", + tokenUrl: "https://auth.example.com/token", + clientId: "$OAUTH_CLIENT_ID", + clientSecret: secret("OAUTH_CLIENT_SECRET"), + scopes: ["read", "write"], + }, + }, + }, +}); + +// Lobu memory schema, declared at the project level, not on the agent. +const note = defineEntityType({ + key: "note", + name: "Note", + description: "A captured note or fact", + required: ["title"], + properties: { + title: { type: "string", "x-table-label": "Title", "x-table-column": true }, + body: { type: "string" }, + }, +}); + +const relatedTo = defineRelationshipType({ + key: "related-to", + name: "Related To", + description: "Link two notes that reference each other.", +}); + +const digest = defineWatcher({ + agent: assistant, + slug: "daily-digest", + name: "Daily digest", + schedule: "0 9 * * *", + notification: { channel: "both", priority: "normal" }, + prompt: "Summarize new notes captured since the last digest.", + extractionSchema: { + type: "object", + required: ["summary"], + properties: { summary: { type: "string" } }, + }, +}); + +export default defineConfig({ + org: "team-assistant", + orgName: "Team Assistant", + orgDescription: "Team assistant", + agents: [assistant], + entities: [note], + relationships: [relatedTo], + watchers: [digest], +}); +``` + +## The `@lobu/sdk` API + +Every authoring function is imported from `@lobu/sdk`: + +```ts +import { + defineConfig, + defineAgent, + defineEntityType, + defineRelationshipType, + defineWatcher, + defineConnection, + defineAuthProfile, + secret, + Type, +} from "@lobu/sdk"; +``` + +Each `define*` returns a branded handle. Assign it to a `const` and pass that handle wherever a reference is needed (for example a `defineWatcher` takes the `defineAgent` handle as its `agent`). + +### `defineConfig(project)` + +The default export of `lobu.config.ts`. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org` | string | no | Lobu Cloud org slug this project applies to | +| `orgName` | string | no | Display name used if `lobu apply` offers to provision the org | +| `orgDescription` | string | no | Org description | +| `organizationId` | string | no | Resolved Lobu Cloud org id that `lobu apply` matches against | +| `agents` | `Agent[]` | yes | Agents (from `defineAgent`) | +| `entities` | `EntityType[]` | no | Entity types (from `defineEntityType`) | +| `relationships` | `RelationshipType[]` | no | Relationship types (from `defineRelationshipType`) | +| `connections` | `Connection[]` | no | Connections (from `defineConnection`) | +| `authProfiles` | `AuthProfile[]` | no | Auth profiles (from `defineAuthProfile`) | +| `watchers` | `Watcher[]` | no | Watchers (from `defineWatcher`) | + +Connections, the memory schema, and watchers are declared at the project level (in `defineConfig`), not inside `defineAgent`. A watcher names its owning agent through its own `agent` field. + +### `defineAgent(agent)` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | yes | Agent ID. Must match `^[a-z0-9][a-z0-9-]*$` (lowercase alphanumeric with hyphens) | +| `name` | string | no | Display name shown in the admin UI | +| `description` | string | no | Short description shown in the admin UI | +| `dir` | string | no | Path to the agent content directory holding `IDENTITY.md`, `SOUL.md`, `USER.md`, and an optional `skills/` folder. Relative to the config file; defaults to `./agents/` | +| `providers` | `ProviderConfig[]` | no | LLM provider list (order = priority) | +| `network` | `NetworkConfig` | no | Network access policy + LLM egress-judge config | +| `egress` | `EgressConfig` | no | Operator overrides for the LLM egress judge on this agent | +| `tools` | `ToolsConfig` | no | Tool policy: pre-approval bypass + worker-side visibility | +| `guardrails` | `string[]` | no | Guardrails enabled for this agent. Each name must match a guardrail registered in the gateway's `GuardrailRegistry` at startup | +| `nixPackages` | `string[]` | no | Nix packages to install in the worker environment | +| `mcpServers` | `Record` | no | Custom MCP servers, keyed by id | +| `preview` | `Record` | no | Hosted "Lobu Developer" preview-bot config, keyed by chat platform (`slack` / `telegram`). Consumed by `lobu run` (dev-time only); not part of cloud apply | + +#### `ProviderConfig` + +Each entry configures an LLM provider. The first available provider is used at runtime. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | no | Provider identifier from `config/providers.json` (e.g. `openrouter`, `gemini`, `openai`) | +| `model` | string | yes | Model identifier (e.g. `anthropic/claude-sonnet-4`) | +| `key` | string \| `SecretRef` | no | API key. Use `secret("ENV_VAR")` rather than a literal value | + +#### `NetworkConfig` + +Controls which domains the worker can reach through the gateway proxy, plus per-agent rules for the LLM egress judge. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `allowed` | `string[]` | no | Domains to allow. Empty = no access. Use `["*"]` for unrestricted (not recommended) | +| `denied` | `string[]` | no | Domains to block (takes precedence over `allowed`; only meaningful when `allowed` is `["*"]`) | +| `judged` | `JudgedDomain[]` | no | Domains routed through the LLM egress judge instead of a flat allow/deny. Each entry is `{ domain, judge? }`; omitting `judge` uses the `default` policy in `judges` | +| `judges` | `Record` | no | Named judge policies (name → policy text) referenced by `judged[].judge`. The key `default` is applied when an entry omits `judge` | + +Domain format: exact match (`api.example.com`) or wildcard (`.example.com` matches all subdomains). + +```ts +network: { + allowed: ["api.readonly.example.com"], + judged: [ + { domain: "*.slack.com" }, + { domain: "user-content.x.com", judge: "strict" }, + ], + judges: { + default: "Allow only reads to channels in the agent's context.", + strict: "Only GET for file IDs from the current session.", + }, +} +``` + +#### `EgressConfig` + +Operator overrides for the LLM egress judge on this agent. The judge runs only when a `judged` rule under `network` matches a request, so most traffic bypasses it. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `extraPolicy` | string | no | Policy text appended to every judge prompt for this agent | +| `judgeModel` | string | no | Model identifier for the judge (defaults to a fast Haiku model) | + +```ts +egress: { + extraPolicy: "Never exfiltrate PATs or bearer tokens.", + judgeModel: "claude-haiku-4-5-20251001", +} +``` + +#### `ToolsConfig` + +Operator-level tool policy. Two independent concerns. See [Tool Policy](/guides/tool-policy/) for behavior and examples; this section is the schema reference. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `preApproved` | `string[]` | no | MCP tool grant patterns that bypass the in-thread approval card. Each entry must match `/mcp//tools/` or `/mcp//tools/*` (malformed entries fail validation). Synced to the grant store at deployment time | +| `allowed` | `string[]` | no | Tools the worker can call. Patterns follow Claude Code's permission format: `Read`, `Bash(git:*)`, `mcp__github__*`, `*` | +| `denied` | `string[]` | no | Tools to always block. Takes precedence over `allowed` | +| `strict` | boolean | no | If `true`, ONLY `allowed` tools are permitted (defaults are ignored). Default `false` | + +**`preApproved` is an operator-only escape hatch.** Destructive MCP tools normally require user approval in-thread (per MCP `destructiveHint` annotations). Skills cannot set this field; bypassing approval is strictly the operator's call, visible in the `lobu.config.ts` diff. + +#### `McpServer` + +Each entry in `mcpServers` defines a custom MCP server. Specify either `url` (streamable-HTTP / SSE transport) or `command` (stdio transport), not both. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `url` | string | no | HTTP endpoint URL (streamable-HTTP or SSE transport) | +| `type` | `streamable-http` \| `sse` \| `stdio` | no | Transport kind. Defaults to `streamable-http` for HTTP URLs; `sse` is the legacy two-channel HTTP transport; `stdio` runs a local `command` | +| `command` | string | no | Stdio transport: command to run | +| `args` | `string[]` | no | Stdio transport: command arguments | +| `env` | `Record` | no | Environment variables passed to the MCP process | +| `headers` | `Record` | no | HTTP headers sent with requests | +| `authScope` | `user` \| `channel` | no | Credential scope for OAuth-authenticated MCPs. `user` (default): each chat user logs in separately. `channel`: one credential shared across all users in a channel, only for shared-data integrations where per-user attribution isn't needed | +| `oauth` | `McpServerOAuth` | no | OAuth configuration (see below) | + +#### `McpServerOAuth` + +OAuth configuration for MCP servers that require authenticated access. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `authUrl` | string | yes | Authorization endpoint | +| `tokenUrl` | string | yes | Token endpoint | +| `clientId` | string | no | OAuth client ID | +| `clientSecret` | string \| `SecretRef` | no | OAuth client secret (use `secret("ENV_VAR")`) | +| `scopes` | `string[]` | no | Requested scopes | +| `tokenEndpointAuthMethod` | string | no | Auth method: `none`, `client_secret_post`, `client_secret_basic` | + +#### `PreviewConfig` + +Hosted "Lobu Developer" preview-bot config for one chat platform. Consumed by `lobu run` (dev-time only). + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `enabled` | boolean | no | Enable the hosted preview bot for this platform | +| `surfaces` | `Array<"dm" \| "channel">` | no | Surfaces a preview code can bind: a DM with the bot, or a channel | +| `codeTtlMinutes` | number | no | Short-lived claim-code TTL (capped by the hosted preview API) | + +```ts +preview: { + slack: { enabled: true, surfaces: ["dm"], codeTtlMinutes: 15 }, +} +``` + +### Guardrails + +`guardrails` is a `string[]` on `defineAgent`. Each name must match a guardrail registered in the gateway's `GuardrailRegistry` at startup; names that don't resolve are ignored. Each guardrail targets one stage: `input` (user message to worker), `output` (worker text to user), or `pre-tool` (tool-call authorization). + +```ts +const assistant = defineAgent({ + id: "assistant", + dir: "./agents/assistant", + guardrails: ["secret-scan", "prompt-injection"], +}); +``` + +### `defineEntityType(entityType)` + +Declares an entity type in the Lobu memory schema. Pass it to `defineConfig({ entities: [...] })`. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `key` | string | yes | Stable slug, the diff key | +| `name` | string | no | Display name | +| `description` | string | no | Short description | +| `required` | `string[]` | no | Required property names for the entity's metadata | +| `properties` | `Record` | no | JSON Schema properties for the entity's metadata. Add `"x-table-label"` / `"x-table-column": true` to surface a property as a column in the admin UI | +| `metadata` | `Record` | no | Free-form metadata | + +```ts +const lead = defineEntityType({ + key: "lead", + name: "Lead", + description: "A person who has shown a signal toward us", + required: ["name", "stage"], + properties: { + name: { type: "string", "x-table-label": "Name", "x-table-column": true }, + stage: { + type: "string", + enum: ["signal", "trial", "customer"], + "x-table-label": "Stage", + "x-table-column": true, + }, + }, +}); +``` + +### `defineRelationshipType(relationshipType)` + +Declares a relationship type. Pass it to `defineConfig({ relationships: [...] })`. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `key` | string | yes | Stable slug, the diff key | +| `name` | string | no | Display name | +| `description` | string | no | Short description | +| `rules` | `Array<{ source, target }>` | no | Allowed source/target entity types; each a `defineEntityType` handle or a slug string | +| `metadata` | `Record` | no | Free-form metadata | + +```ts +const convertedTo = defineRelationshipType({ + key: "converted-to", + name: "Converted To", + description: "Links a lead to the pilot it became.", + rules: [{ source: lead, target: pilot }], +}); +``` + +### `defineWatcher(watcher)` + +Declares a scheduled watcher. Pass it to `defineConfig({ watchers: [...] })`. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `slug` | string | yes | Stable slug, the diff key | +| `agent` | `Agent` \| string | yes | Owning agent (handle or id). Every watcher belongs to exactly one agent | +| `name` | string | no | Display name | +| `description` | string | no | Short description | +| `schedule` | string | no | Cron schedule (e.g. `0 9 * * 1`) | +| `prompt` | string | yes | Instructions the watcher runs each firing | +| `extractionSchema` | `Record` | yes | JSON Schema (or TypeBox schema) describing the LLM output | +| `sources` | `Record` | no | Named SQL data sources (`name` → query) | +| `notification` | `{ channel?, priority? }` | no | `channel`: `canvas` \| `notification` \| `both`; `priority`: `low` \| `normal` \| `high` | +| `minCooldownSeconds` | number | no | Minimum seconds between firings | +| `tags` | `string[]` | no | Free-form tags | +| `reactionsGuidance` | string | no | LLM guidance for the watcher's downstream reaction agent | +| `agentKind` | string | no | Agent-kind override for firings (e.g. `background`, `notifier`) | +| `reaction` | string | no | Relative POSIX path to a sibling `.ts` reaction script (e.g. `./reactions/foo.reaction.ts`), compiled and run in a sandboxed isolate when the watcher fires. The script must `export default async (ctx, client) => …`. See the [Reaction SDK](/getting-started/reaction-sdk/) | + +```ts +const digest = defineWatcher({ + agent: crm, + slug: "weekly-digest", + name: "Weekly digest", + schedule: "0 9 * * 1", + notification: { channel: "both", priority: "high" }, + minCooldownSeconds: 3600, + tags: ["crm", "weekly"], + reaction: "./reactions/weekly-digest.reaction.ts", + prompt: "Produce the weekly digest and post it to Slack. Keep it short.", + extractionSchema: { + type: "object", + required: ["summary"], + properties: { summary: { type: "string" } }, + }, +}); +``` + +### `defineConnection(connection)` + +Declares a connection to a connector. Pass it to `defineConfig({ connections: [...] })`. The connection's OAuth grant (for `oauth_account` / `browser_session` profiles) is performed at runtime in the admin UI. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `slug` | string | yes | Stable slug, the diff key | +| `connector` | string \| `ConnectorClass` | yes | Connector key, or the class produced by `defineConnector` | +| `name` | string | no | Display name | +| `authProfile` | `AuthProfile` \| string | no | Runtime/account auth profile (handle or slug) | +| `appAuthProfile` | `AuthProfile` \| string | no | OAuth-app auth profile (handle or slug) | +| `config` | `Record` | no | Connector configuration | +| `deviceWorkerId` | string | no | UUID pinning syncs/actions to a specific device worker | +| `feeds` | `ConnectionFeed[]` | no | Scheduled feeds. Each is `{ feed, name?, schedule?, config? }`, where `feed` is a feed key from the connector | + +```ts +const githubConn = defineConnection({ + slug: "github-lobu", + connector: "github", + name: "GitHub - lobu-ai/lobu", + authProfile: githubAccountAuth, + appAuthProfile: githubAppAuth, + config: { repo_owner: "lobu-ai", repo_name: "lobu" }, + feeds: [ + { + feed: "issues", + name: "Issues", + schedule: "15 */6 * * *", + config: { repo_owner: "lobu-ai", repo_name: "lobu", lookback_days: 90 }, + }, + ], +}); +``` + +### `defineAuthProfile(authProfile)` + +Declares an auth profile a connection references. Pass it to `defineConfig({ authProfiles: [...] })`. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `slug` | string | yes | Stable slug, the diff key | +| `connector` | string \| `ConnectorClass` | yes | Connector this profile authenticates | +| `authKind` | `env` \| `oauth_app` \| `oauth_account` \| `browser_session` | yes | Authentication kind | +| `name` | string | no | Display name | +| `credentials` | `Record` | no | Credential references (use `secret("ENV_VAR")`). Only meaningful for `env` / `oauth_app`; the grant for `oauth_account` / `browser_session` is performed at runtime in the UI | + +```ts +const githubApp = defineAuthProfile({ + slug: "github-app", + connector: "github", + authKind: "oauth_app", + name: "GitHub OAuth App", + credentials: { + GITHUB_CLIENT_ID: secret("GITHUB_CLIENT_ID"), + GITHUB_CLIENT_SECRET: secret("GITHUB_CLIENT_SECRET"), + }, +}); +``` + +### `secret(name)` + +Returns a write-only secret reference resolved at `lobu apply` time from the environment (`.env` / `process.env`). The real value is never embedded in committed code. Use it for provider keys, MCP credentials, and auth-profile credentials. + +```ts +key: secret("OPENROUTER_API_KEY") +``` + +The apply loader resolves the reference to a `$NAME` placeholder, collects it into the required-secrets set, and pushes the resolved value to the server. + +### `Type` + +Re-exported TypeBox `Type` for authoring extraction schemas and feed/action config schemas with full TypeScript inference. You can pass a TypeBox schema anywhere an `extractionSchema` or connector config schema is accepted, or use a plain JSON Schema object. + +## Chat platforms + +Chat platforms (Slack, Telegram, Discord, WhatsApp, Teams, Google Chat) are not authored in `lobu.config.ts`. Connect them through the `/agents` admin UI or the CRUD API; their bot tokens and secrets live in `.env`. See [Slack](/platforms/slack/) for the per-platform setup. + +For dev-time previews, `defineAgent({ preview: { slack: { enabled: true } } })` enables the hosted Lobu Developer bot so `lobu run` prints a short-lived `/lobu link ` you redeem by DMing the bot. + +## Lobu memory + +Entity types, relationship types, and watchers are the memory schema. Declare them with `defineEntityType` / `defineRelationshipType` / `defineWatcher` and list them in `defineConfig`. `lobu apply` reconciles them against your org. See [`lobu memory`](/reference/lobu-memory/) and [`lobu apply`](/reference/lobu-apply/). + +The org slug comes from `defineConfig({ org })`. `MEMORY_URL` remains available as an optional base-endpoint override for local or custom Lobu deployments. + +## Validation + +```bash +npx @lobu/cli@latest validate +``` + +Checks that `lobu.config.ts` loads, conforms to the schema, and that skill IDs and provider configuration are valid. Returns exit code 1 on failure. + + diff --git a/packages/landing/src/content/docs/reference/lobu-memory.md b/packages/landing/src/content/docs/reference/lobu-memory.md index 5e2542ae4..790e6ebd9 100644 --- a/packages/landing/src/content/docs/reference/lobu-memory.md +++ b/packages/landing/src/content/docs/reference/lobu-memory.md @@ -134,21 +134,36 @@ Accepts the same `--url`, `--org`, and `-c/--context` flags as `lobu memory run` ### `lobu memory seed` -Provisions a memory workspace from `[memory]` in `lobu.toml`, `version: 2` model bundle YAML files under `./models`, and optional `./data`. - -```yaml -version: 2 -entities: - - slug: account - name: Account -relationships: - - slug: owns - name: Owns -watchers: - - slug: account-digest - name: Account digest - schedule: "0 9 * * 1" - prompt: Summarize account changes. +Provisions a memory workspace from `lobu.config.ts`. The schema (entity types, relationship types, watchers) and the org come from `defineConfig`; optional seed data records come from YAML files under `./data`. + +Declare the schema in `lobu.config.ts`: + +```ts +import { + defineConfig, + defineEntityType, + defineRelationshipType, + defineWatcher, +} from "@lobu/sdk"; + +const account = defineEntityType({ key: "account", name: "Account" }); +const owns = defineRelationshipType({ key: "owns", name: "Owns" }); +const digest = defineWatcher({ + agent: "sales", + slug: "account-digest", + name: "Account digest", + schedule: "0 9 * * 1", + prompt: "Summarize account changes.", + extractionSchema: { type: "object", properties: {} }, +}); + +export default defineConfig({ + org: "my-org", + agents: [/* ... */], + entities: [account], + relationships: [owns], + watchers: [digest], +}); ``` ```bash diff --git a/packages/landing/src/content/docs/reference/lobu-toml.md b/packages/landing/src/content/docs/reference/lobu-toml.md deleted file mode 100644 index 1f3401f81..000000000 --- a/packages/landing/src/content/docs/reference/lobu-toml.md +++ /dev/null @@ -1,377 +0,0 @@ ---- -title: lobu.toml Reference -description: Complete reference for the lobu.toml configuration file. -sidebar: - order: 1 ---- - -`lobu.toml` is the project configuration file created by `lobu init`. It defines agents, providers, platforms, skills, network access (including the LLM egress judge), guardrails, worker settings, and optional file-first Lobu memory configuration. - -## Minimal example - -```toml -[agents.my-agent] -name = "my-agent" -dir = "./agents/my-agent" - -[[agents.my-agent.providers]] -id = "openrouter" -key = "$OPENROUTER_API_KEY" - -[agents.my-agent.network] -allowed = ["github.com"] - -[memory] -enabled = true -org = "my-agent" -name = "My Agent" -models = "./models" -data = "./data" -``` - -## Full example - -```toml -[agents.assistant] -name = "assistant" -description = "Team assistant" -dir = "./agents/assistant" -# Guardrails enabled for this agent (names registered in the gateway's GuardrailRegistry) -guardrails = ["secret-scan", "prompt-injection"] - -# Providers (order = priority, first available is used) -[[agents.assistant.providers]] -id = "openrouter" -model = "anthropic/claude-sonnet-4" -key = "$OPENROUTER_API_KEY" - -[[agents.assistant.providers]] -id = "gemini" -key = "$GEMINI_API_KEY" - -# Chat platforms -[[agents.assistant.platforms]] -type = "telegram" -[agents.assistant.platforms.config] -botToken = "$TELEGRAM_BOT_TOKEN" - -[[agents.assistant.platforms]] -type = "slack" -[agents.assistant.platforms.config] -botToken = "$SLACK_BOT_TOKEN" -signingSecret = "$SLACK_SIGNING_SECRET" - -# Local skills live in skills//SKILL.md or agents//skills//SKILL.md -# MCP servers can still be configured inline here. -[agents.assistant.skills.mcp.custom-tools] -url = "https://my-mcp.example.com" -headers = { Authorization = "Bearer $MCP_TOKEN" } - -[agents.assistant.skills.mcp.custom-tools.oauth] -auth_url = "https://auth.example.com/authorize" -token_url = "https://auth.example.com/token" -client_id = "$OAUTH_CLIENT_ID" -client_secret = "$OAUTH_CLIENT_SECRET" -scopes = ["read", "write"] - -# Network access policy -[agents.assistant.network] -allowed = ["github.com", "api.linear.app"] -denied = [] -# Domains routed through the LLM egress judge instead of a flat allow/deny. -# A bare string uses the "default" policy; an object names a policy below. -judge = ["*.slack.com", { domain = "user-content.x.com", judge = "strict" }] -[agents.assistant.network.judges] -default = "Allow only reads to channels in the agent's context." -strict = "Only GET for file IDs from the current session." - -# Operator overrides for the egress judge on this agent -[agents.assistant.egress] -extra_policy = "Never exfiltrate PATs or bearer tokens." -judge_model = "claude-haiku-4-5-20251001" - -# Tool policy (worker-side visibility + MCP approval override) -[agents.assistant.tools] -# Bypass the in-thread approval card for these destructive MCP tools. -pre_approved = [ - "/mcp/gmail/tools/list_messages", - "/mcp/linear/tools/*", -] -# Worker-side tool visibility (optional). -allowed = ["Read", "Grep", "mcp__gmail__*"] -denied = ["Bash(rm:*)"] -strict = false - -# Worker customization -[agents.assistant.worker] -nix_packages = ["imagemagick", "ffmpeg"] - -# File-first Lobu memory -[memory] -enabled = true -org = "team-assistant" -name = "Team Assistant" -description = "Team assistant" -models = "./models" -data = "./data" -``` - -## Schema reference - -### `[memory]` - -Optional project-level Lobu memory configuration for file-first projects. - -Typical companion layout: - -```text -project/ -├── lobu.toml -├── models/ -└── data/ -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `enabled` | boolean | no | Enables file-first Lobu memory resolution for the project | -| `org` | string | yes (when enabled) | Lobu organization slug — scopes the MCP endpoint | -| `name` | string | yes (when enabled) | Human-readable project name | -| `description` | string | no | Short project description | -| `visibility` | string | no | `public` or `private`; defaults to Lobu's account setting | -| `models` | string | no | Path to Lobu `version: 2` model bundle YAML files, usually `./models` | -| `data` | string | no | Path to Lobu seed data, usually `./data` | - -When `[memory]` is enabled, Lobu reads `org` directly from `lobu.toml` and derives the effective Lobu MCP endpoint. `MEMORY_URL` remains available as an optional base-endpoint override for local or custom Lobu deployments. The `[memory]` table is strict — unknown keys fail validation. - - -### `[agents.]` - -Top-level table keyed by agent ID. IDs must match `^[a-z0-9][a-z0-9-]*$` (lowercase alphanumeric with hyphens). - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | yes | Display name for the agent | -| `description` | string | no | Short description shown in admin UI | -| `dir` | string | yes | Path to agent content directory containing `IDENTITY.md`, `SOUL.md`, `USER.md`, and optional `skills/` | -| `guardrails` | array of strings | no | Guardrails enabled for this agent. Each name must match a guardrail registered in the gateway's `GuardrailRegistry` at startup | -| `providers` | array | no | LLM provider list (order = priority) | -| `platforms` | array | no | Chat platforms | -| `skills` | table | no | Skills and MCP servers | -| `network` | table | no | Network access policy + LLM egress-judge config | -| `egress` | table | no | Operator overrides for the LLM egress judge on this agent | -| `tools` | table | no | Tool policy: pre-approval bypass + worker-side visibility | -| `worker` | table | no | Worker customization | - -### `[[agents..providers]]` - -Each entry configures an LLM provider. The first available provider is used at runtime. - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `id` | string | yes | Provider identifier from `config/providers.json` (e.g. `openrouter`, `gemini`, `openai`) | -| `model` | string | no | Model override (e.g. `anthropic/claude-sonnet-4`) | -| `key` | string | no | API key — literal value or `$ENV_VAR` reference | -| `secret_ref` | string | no | Durable secret reference (for example `secret://...`) | - -Provider credentials are optional. A provider entry may omit both `key` and `secret_ref`, or set exactly one of them. Setting both is invalid. - -### `[[agents..platforms]]` - -Each entry connects the agent to a chat platform. - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | yes | Platform type: `telegram`, `slack`, `discord`, `whatsapp`, `teams`, `gchat` | -| `name` | string | no | Disambiguator when an agent has multiple platforms of the same type | -| `config` | table | yes | Platform-specific configuration (see below) | -| `channels` | array | no | Slack only — declarative channel routing (see below) | - -#### Declarative channel routing (Slack) - -By default an agent is reachable in a Slack channel only after someone runs `/lobu link ` there. To route channels to the agent as config-as-code, list them on the Slack platform entry: - -```toml -[[agents.x.platforms]] -type = "slack" -channels = ["T0ABCDEF/C0123ABCD", "T0ABCDEF/C0456WXYZ"] -[agents.x.platforms.config] -botToken = "$SLACK_BOT_TOKEN" -signingSecret = "$SLACK_SIGNING_SECRET" -``` - -Each entry is `"/"` — both appear in any Slack channel URL (`https://app.slack.com/client//`). `lobu apply` reconciles `agent_channel_bindings` to exactly this list for this agent on the teams referenced: listed channels get bound, ones no longer listed get unbound. Channels linked ad-hoc via `/lobu link` on other teams/connections are left alone. (Channel changes are applied during `lobu apply`; they don't appear in `lobu apply --dry-run` output.) - -#### Platform config by type - -**Telegram** -```toml -[agents.x.platforms.config] -botToken = "$TELEGRAM_BOT_TOKEN" -``` - -**Slack** -```toml -[agents.x.platforms.config] -botToken = "$SLACK_BOT_TOKEN" -signingSecret = "$SLACK_SIGNING_SECRET" -``` - -**Discord** -```toml -[agents.x.platforms.config] -botToken = "$DISCORD_BOT_TOKEN" -applicationId = "$DISCORD_APPLICATION_ID" -publicKey = "$DISCORD_PUBLIC_KEY" -``` - -**WhatsApp** (Cloud API) -```toml -[agents.x.platforms.config] -accessToken = "$WHATSAPP_ACCESS_TOKEN" -phoneNumberId = "$WHATSAPP_PHONE_NUMBER_ID" -verifyToken = "$WHATSAPP_WEBHOOK_VERIFY_TOKEN" -appSecret = "$WHATSAPP_APP_SECRET" -``` - -**Teams** -```toml -[agents.x.platforms.config] -appId = "$TEAMS_APP_ID" -appPassword = "$TEAMS_APP_PASSWORD" -appType = "MultiTenant" -# For single-tenant Azure apps, use: -# appTenantId = "$TEAMS_APP_TENANT_ID" -# appType = "SingleTenant" -``` - -**Google Chat** -```toml -[agents.x.platforms.config] -credentials = "$GOOGLE_CHAT_CREDENTIALS" -``` - -### `[agents..skills]` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `mcp` | table | no | Custom MCP server definitions | - -### `[agents..skills.mcp.]` - -Each entry defines a custom MCP server. - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `url` | string | no | HTTP endpoint URL (streamable-HTTP or SSE transport) | -| `type` | `streamable-http` \| `sse` \| `stdio` | no | Transport kind. Defaults to `streamable-http` for HTTP URLs; `sse` is the legacy two-channel HTTP transport; `stdio` runs a local `command` | -| `command` | string | no | Stdio transport — command to run | -| `args` | array of strings | no | Stdio transport — command arguments | -| `env` | table | no | Environment variables passed to the MCP process | -| `headers` | table | no | HTTP headers sent with requests | -| `auth_scope` | `user` \| `channel` | no | Credential scope for OAuth-authenticated MCPs. `user` (default): each chat user logs in separately. `channel`: one credential shared across all users in a channel — only for shared-data integrations where per-user attribution isn't needed | -| `oauth` | table | no | OAuth configuration (see below) | - -Specify either `url` (streamable-HTTP / SSE transport) or `command` (stdio transport), not both. - -### `[agents..skills.mcp..oauth]` - -OAuth configuration for MCP servers that require authenticated access. - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `auth_url` | string | yes | Authorization endpoint | -| `token_url` | string | yes | Token endpoint | -| `client_id` | string | no | OAuth client ID (literal or `$ENV_VAR`) | -| `client_secret` | string | no | OAuth client secret (literal or `$ENV_VAR`) | -| `scopes` | array of strings | no | Requested scopes | -| `token_endpoint_auth_method` | string | no | Auth method: `none`, `client_secret_post`, `client_secret_basic` | - -### `[agents..network]` - -Controls which domains the worker can reach through the gateway proxy, plus per-agent rules for the LLM egress judge. - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `allowed` | array of strings | no | Domains to allow. Empty = no access. Use `["*"]` for unrestricted (not recommended) | -| `denied` | array of strings | no | Domains to block (only meaningful when `allowed = ["*"]`) | -| `judge` | array | no | Domains routed through the LLM egress judge instead of a flat allow/deny. Each entry is either a bare domain string (uses the `default` judge policy) or an object `{ domain, judge }` naming a policy in `judges` | -| `judges` | table | no | Named judge policies (string → policy text) referenced by `judge[].judge`. The key `default` is applied when an entry omits `judge` | - -Domain format: exact match (`api.example.com`) or wildcard (`.example.com` matches all subdomains). - -```toml -[agents.x.network] -allowed = ["api.readonly.example.com"] -judge = ["*.slack.com", { domain = "user-content.x.com", judge = "strict" }] -[agents.x.network.judges] -default = "Allow only reads to channels in the agent's context." -strict = "Only GET for file IDs from the current session." -``` - -### `[agents..egress]` - -Operator overrides for the LLM egress judge on this agent. The judge runs only when a `judge` rule under `[agents..network]` matches a request, so most traffic bypasses it. - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `extra_policy` | string | no | Policy text appended to every judge prompt for this agent | -| `judge_model` | string | no | Model identifier for the judge (defaults to a fast Haiku model) | - -```toml -[agents.x.egress] -extra_policy = "Never exfiltrate PATs or bearer tokens." -judge_model = "claude-haiku-4-5-20251001" -``` - -### `[agents..tools]` - -Operator-level tool policy. Two independent concerns: - -See [Tool Policy](/guides/tool-policy/) for behavior and examples; this section is the exact schema reference. - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `pre_approved` | array of strings | no | MCP tool grant patterns that bypass the in-thread approval card. Each entry must match `/mcp//tools/` or `/mcp//tools/*` — malformed entries fail schema validation. Synced to the grant store at deployment time. | -| `allowed` | array of strings | no | Tools the worker can call. Patterns follow Claude Code's permission format: `Read`, `Bash(git:*)`, `mcp__github__*`, `*`. | -| `denied` | array of strings | no | Tools to always block. Takes precedence over `allowed`. | -| `strict` | boolean | no | If `true`, ONLY `allowed` tools are permitted (defaults are ignored). Default `false`. | - -**`pre_approved` is an operator-only escape hatch.** Destructive MCP tools normally require user approval in-thread (per MCP `destructiveHint` annotations). Skills cannot set this field — bypassing approval is strictly the operator's call, visible in the `lobu.toml` diff. - -### `[agents..worker]` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `nix_packages` | array of strings | no | Nix packages to install in the worker environment | - -### `guardrails` - -`guardrails` is a top-level array of strings on `[agents.]` (not a sub-table). Each name must match a guardrail registered in the gateway's `GuardrailRegistry` at startup — names that don't resolve are ignored. Each guardrail targets one stage: `input` (user message → worker), `output` (worker text → user), or `pre-tool` (tool-call authorization). - -```toml -[agents.assistant] -name = "assistant" -dir = "./agents/assistant" -guardrails = ["secret-scan", "prompt-injection"] -``` - -### Memory model schema - -Entity types, relationship types, and watchers are declared in `version: 2` model bundle YAML files under the directory `[memory].models` points at (usually `./models`) — see [`lobu memory seed`](/reference/lobu-memory/) and [`lobu apply`](/reference/lobu-apply/) for the bundle format. The `[memory]` table itself is `.strict()` — unknown keys (including the removed inline `schema` sub-table) fail validation. - -## Environment variable references - -Any string value can reference an environment variable with `$ENV_VAR` syntax. The CLI resolves these from `.env` at runtime. - -```toml -key = "$OPENROUTER_API_KEY" # resolved from .env -key = "sk-literal-value" # used as-is -``` - -## Validation - -```bash -npx @lobu/cli@latest validate -``` - -Checks TOML syntax, schema conformance, skill IDs, and provider configuration. Returns exit code 1 on failure. diff --git a/packages/landing/src/content/docs/reference/skill-md.md b/packages/landing/src/content/docs/reference/skill-md.md index 11c5799f3..db2ce8622 100644 --- a/packages/landing/src/content/docs/reference/skill-md.md +++ b/packages/landing/src/content/docs/reference/skill-md.md @@ -13,7 +13,7 @@ Use it for: - Capability declarations such as MCP servers, packages, and network domains - Instruction text that is injected into the agent's system prompt when the skill is active -Tool policy does **not** live in `SKILL.md`. Configure that in [`lobu.toml`](/reference/lobu-toml/) under `[agents..tools]`; see [Tool Policy](/guides/tool-policy/). +Tool policy does **not** live in `SKILL.md`. Configure that in [`lobu.config.ts`](/reference/lobu-config/) via the agent `tools` field; see [Tool Policy](/guides/tool-policy/). ## Where Skills Live @@ -92,7 +92,7 @@ The body acts as a system prompt extension. | `network.judge` | array | Domains routed through the LLM egress judge. Each entry is a bare domain string (uses the `default` judge policy) or an object `{ domain, judge }` naming a policy in the top-level `judges` map | | `judges` | object | Named judge policies (string → policy text) referenced by `network.judge[].judge`; the `default` key applies when an entry omits `judge` | -Skill MCP entries support only `url` / `type` / `command` / `args` — for `headers`, `env`, `oauth`, or `auth_scope`, configure the MCP server on the agent in [`lobu.toml`](/reference/lobu-toml/) under `[agents..skills.mcp.]`. +Skill MCP entries support only `url` / `type` / `command` / `args` — for `headers`, `env`, `oauth`, or `authScope`, configure the MCP server on the agent in [`lobu.config.ts`](/reference/lobu-config/) via the agent `mcpServers` field. ## Markdown Body @@ -100,13 +100,13 @@ The markdown body after the frontmatter is appended to the agent's prompt when t ## Notes -- `SKILL.md` frontmatter does not configure tool approval or `pre_approved` MCP tools. +- `SKILL.md` frontmatter does not configure tool approval or `preApproved` MCP tools. - `contracts.tools` belongs in an OpenClaw plugin manifest (`openclaw.plugin.json`), not in `SKILL.md` frontmatter — the skill parser ignores it. -- When both a skill and the agent declare egress-judge rules, the `lobu.toml` policy wins on named judges and judged-domain rules. -- For MCP servers that should live directly on the agent rather than inside a skill, configure them in [`lobu.toml`](/reference/lobu-toml/). +- When both a skill and the agent declare egress-judge rules, the `lobu.config.ts` policy wins on named judges and judged-domain rules. +- For MCP servers that should live directly on the agent rather than inside a skill, configure them in [`lobu.config.ts`](/reference/lobu-config/). ## Related Docs - [Skills](/getting-started/skills/) - [Tool Policy](/guides/tool-policy/) -- [`lobu.toml` Reference](/reference/lobu-toml/) +- [`lobu.config.ts` Reference](/reference/lobu-config/) diff --git a/packages/landing/src/pages/reference/api-reference.astro b/packages/landing/src/pages/reference/api-reference.astro index 785a7d87d..9c46ddff1 100644 --- a/packages/landing/src/pages/reference/api-reference.astro +++ b/packages/landing/src/pages/reference/api-reference.astro @@ -48,7 +48,7 @@ const config = JSON.stringify({ @lobu/connector-sdk Reactions CLI - lobu.toml + lobu.config.ts
diff --git a/skills/lobu-operator/SKILL.md b/skills/lobu-operator/SKILL.md index 226bba427..6c3a9712d 100644 --- a/skills/lobu-operator/SKILL.md +++ b/skills/lobu-operator/SKILL.md @@ -10,7 +10,7 @@ description: Repo-specific operational skill for Lobu-managed agents working ins ## Before You Act 1. Read `CLAUDE.md` and `AGENTS.md`. -2. Read `lobu.toml` for workspace configuration. +2. Read `lobu.config.ts` for workspace configuration. 3. Inspect the agent directories and enabled `skills/` — the layout is data-driven, don't assume it. ## Dev Workflow diff --git a/skills/lobu/SKILL.md b/skills/lobu/SKILL.md index 260a78a9b..2ba845eeb 100644 --- a/skills/lobu/SKILL.md +++ b/skills/lobu/SKILL.md @@ -1,13 +1,13 @@ --- name: lobu -description: Scaffold a new Lobu agent project from a user interview, then build, run, and maintain it — including lobu.toml, prompt files, local skills, evals, providers, connections, and Lobu memory workflows. +description: Scaffold a new Lobu agent project from a user interview, then build, run, and maintain it, including lobu.config.ts, prompt files, local skills, evals, providers, connections, and Lobu memory workflows. --- # Lobu Use this skill when the user wants to scaffold a new Lobu agent (no existing project), or when they're working on an existing Lobu project — running, validating, evaluating, or connecting one. Also use it for persistent Lobu memory, MCP client setup, OpenClaw memory plugin configuration, knowledge search/save workflows, watchers, and browser-authenticated connectors. -If no `lobu.toml` exists in the current working directory, treat the user as a first-time user and run the "First-Time Setup" flow below. Otherwise jump straight to "Core Model" + the relevant reference section. +If no `lobu.config.ts` exists in the current working directory, treat the user as a first-time user and run the "First-Time Setup" flow below. Otherwise jump straight to "Core Model" + the relevant reference section. ## First-Time Setup @@ -44,14 +44,14 @@ npx @lobu/cli@latest init cd ``` -The CLI generates the directory layout. Then edit: +The CLI generates the directory layout, including `lobu.config.ts`, `package.json`, and `tsconfig.json`. All authoring is TypeScript: import `defineConfig`, `defineAgent`, `defineEntityType`, `defineRelationshipType`, `defineWatcher`, `defineConnection`, `defineAuthProfile`, and `secret` from `@lobu/sdk`. Read `examples/lobu-crm/lobu.config.ts` in the lobu repo for a complete, working reference before editing. Then edit: -- **`lobu.toml`** — set the agent name + description from question 1; add the chosen provider; set `[memory] org` from a slug of the user's choice. +- **`lobu.config.ts`** — set the agent name + description from question 1 on `defineAgent`; add the chosen provider with `providers: [{ id, model, key: secret("X_API_KEY") }]`; set `org` / `orgName` in `defineConfig` from a slug of the user's choice. - **`.env`** — fill in `DATABASE_URL` and the provider API key from Phase 1. -- **`models/schema.yaml`** — declare the entity types from question 3. Each entity needs `slug`, `name`, and a `metadata_schema` (JSON Schema) describing the fields you will store. +- **Entity types** — declare the entity types from question 3 with `defineEntityType({ key, name, properties })` and list them in `defineConfig({ entities: [...] })`. Each property is a JSON Schema fragment; add `"x-table-label"` / `"x-table-column": true` to surface a column in the admin UI. - **`connectors/.connector.ts`** — only if the source from question 4 is not a bundled connector. Model it on `examples/lobu-crm/connectors/funnel-form.connector.ts` in the lobu repo. -- **`models/schema.yaml`** (watchers section) — add one reactive watcher with `on: `, `prompt`, and `extraction_schema`. Optionally add the cron `schedule:` watcher from question 6. -- **`models/reactions/.reaction.ts`** — only if the watcher needs to call actions after extracting (post to Slack, update an entity, etc.). Default path (no reaction) just writes the extracted data to memory. +- **Watchers** — add one watcher with `defineWatcher({ agent, slug, prompt, extractionSchema, schedule? })` and list it in `defineConfig({ watchers: [...] })`. Use the cron `schedule` from question 6 if the user wants one. +- **`reactions/.reaction.ts`** — only if the watcher needs to call actions after extracting (post to Slack, update an entity, etc.). Point the watcher at it with `reaction: "./reactions/.reaction.ts"`. Default path (no `reaction`) just writes the extracted data to memory. Then boot: @@ -78,7 +78,7 @@ If anything fails, do not silently move on — surface the error, propose a fix, ## Core Model - **Lobu** is the agent framework, runtime, deployment layer, and memory surface. -- Keep framework configuration in `lobu.toml`. +- Keep framework configuration in `lobu.config.ts` (TypeScript, `defineConfig` from `@lobu/sdk`). - Keep agent identity and behavior in `IDENTITY.md`, `SOUL.md`, and `USER.md`. - Keep reusable capability bundles in `skills//SKILL.md` or `agents//skills//SKILL.md`. - Use `lobu login` for CLI authentication. Do not use a separate memory login command. @@ -86,7 +86,7 @@ If anything fails, do not silently move on — surface the error, propose a fix, ## Project Checklist -1. Read `lobu.toml` first. +1. Read `lobu.config.ts` first. 2. Read the active agent files under `agents//`. 3. Check local skills under `skills/` and `agents//skills/`. 4. Use `lobu validate` after config changes. @@ -114,18 +114,32 @@ Your long-term memory is powered by Lobu. Do NOT use local files (memory/, MEMOR ## Lobu Memory -Configure project-scoped memory in `lobu.toml`: - -```toml -[memory] -enabled = true -org = "my-org" -name = "My workspace" -models = "./models" -data = "./data" +Configure project-scoped memory in `lobu.config.ts` by setting the org on `defineConfig` and declaring the schema with the `define*` helpers: + +```ts +import { defineConfig, defineEntityType } from "@lobu/sdk"; + +const ticket = defineEntityType({ + key: "ticket", + name: "Ticket", + properties: { + subject: { + type: "string", + "x-table-label": "Subject", + "x-table-column": true, + }, + }, +}); + +export default defineConfig({ + org: "my-org", + orgName: "My workspace", + agents: [/* ... */], + entities: [ticket], +}); ``` -Then seed or operate the memory workspace with: +Seed data records still live as YAML under `./data`. Then seed or operate the memory workspace with: ```bash lobu login From 5f9842600c607a89936c978296c52ebe98613a1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 04:28:44 +0100 Subject: [PATCH 32/65] chore: remove remaining lobu.toml references repo-wide Sweeps lobu.toml out of code comments + agent-facing strings (server gateway services/auth/guardrails/proxy, agent-worker openclaw tools, core types/guardrails), test docstrings, the lobu init README template, docs/SECURITY.md, .env.example, dev-native.sh, the historical docs/plans, and the blog posts. Rewrites the broken gen-use-case-data.ts to load each example's lobu.config.ts via jiti (was importing the removed smol-toml + reading a lobu.toml that no longer exists) and regenerates use-case-models.ts. Deletes the dead, unreferenced e2e-lobu-apply.sh apply harness (scaffolded lobu.toml + models/*.yaml that apply no longer reads; superseded by the managed-by-prune integration test). lobu.toml is now absent from the tracked tree (CHANGELOG history excepted). core+server typecheck clean, landing build green, network-domains unit test green. --- .env.example | 2 +- docs/SECURITY.md | 2 +- docs/plans/lobu-apply.md | 12 +- docs/plans/lobu-cli-merge.md | 4 +- docs/plans/lobu-pull.md | 12 +- docs/plans/lobu-secrets-push.md | 6 +- .../src/embedded/just-bash-bootstrap.ts | 2 +- packages/agent-worker/src/openclaw/tools.ts | 4 +- packages/cli/src/templates/README.md.tmpl | 6 +- .../src/__tests__/network-domains.test.ts | 2 +- packages/core/src/guardrails/types.ts | 2 +- packages/core/src/types.ts | 2 +- .../filesystem-vs-database-agent-memory.mdx | 2 +- .../landing/src/content/blog/hello-world.mdx | 2 +- ...verengineered-skills-are-too-primitive.mdx | 2 +- .../landing/src/generated/use-case-models.ts | 336 +++++++++++++++--- .../core-services-store-selection.test.ts | 2 +- .../src/gateway/auth/mcp/config-service.ts | 2 +- .../src/gateway/auth/mcp/oauth-discovery.ts | 2 +- .../src/gateway/auth/provider-catalog.ts | 2 +- .../auth/settings/auth-profiles-manager.ts | 2 +- .../src/gateway/guardrails/aggregator.ts | 2 +- .../orchestration/base-deployment-manager.ts | 2 +- .../server/src/gateway/proxy/http-proxy.ts | 4 +- .../src/gateway/services/core-services.ts | 4 +- .../services/declared-agent-registry.ts | 2 +- .../gateway/services/instruction-service.ts | 4 +- .../postgres-agent-config-store.test.ts | 2 +- scripts/dev-native.sh | 2 +- scripts/e2e-lobu-apply.sh | 312 ---------------- scripts/gen-use-case-data.ts | 227 +++++------- 31 files changed, 431 insertions(+), 538 deletions(-) delete mode 100755 scripts/e2e-lobu-apply.sh diff --git a/.env.example b/.env.example index dd51e6505..0082b4288 100644 --- a/.env.example +++ b/.env.example @@ -96,7 +96,7 @@ WORKER_DISALLOWED_DOMAINS= PUBLIC_GATEWAY_URL=https://app.lobu.ai # Optional Lobu base MCP URL override. -# File-first projects can enable Lobu with [memory] in lobu.toml; +# File-first projects can enable Lobu with [memory] in lobu.config.ts; # when set, Lobu scopes this base URL to the org declared there. MEMORY_URL=https://lobu.com/mcp diff --git a/docs/SECURITY.md b/docs/SECURITY.md index a8fdedc81..9b4bba0fc 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -90,7 +90,7 @@ Skills are executable, security-sensitive input: - Use curated skill lists by default. - Review skill `nixPackages` declarations: each binary on the allowlist is a capability, treat them as such. - Skills declare `networkConfig.allowedDomains`; gateway egress controls apply on top. -- Destructive MCP tool calls require in-thread approval unless pre-approved in `[agents..tools]` in `lobu.toml`. +- Destructive MCP tool calls require in-thread approval unless pre-approved via `defineAgent({ tools: { preApproved } })` in `lobu.config.ts`. ## What changed from earlier docs diff --git a/docs/plans/lobu-apply.md b/docs/plans/lobu-apply.md index 301648f15..bb9221a5d 100644 --- a/docs/plans/lobu-apply.md +++ b/docs/plans/lobu-apply.md @@ -4,14 +4,14 @@ Status: **planning** · Owner: @buremba · Reviewed against pi second-opinion 20 ## Goal -Provide a one-way `lobu.toml` → Lobu Cloud org converger. Mental model: `terraform apply` lite. Files declare desired state, the CLI shows a plan, the user confirms, the CLI calls existing server endpoints (which are idempotent) in dependency order. Re-running converges. +Provide a one-way `lobu.config.ts` → Lobu Cloud org converger. Mental model: `terraform apply` lite. Files declare desired state, the CLI shows a plan, the user confirms, the CLI calls existing server endpoints (which are idempotent) in dependency order. Re-running converges. **Reuse-first**: deliberately *not* building a new server-side apply API or state substrate. Every existing endpoint is already idempotent or near-idempotent — the gap is one connection upsert route. Total v1: 3 PRs, ~600 LOC. ## Mental model ``` -desired state (lobu.toml + agent dirs) +desired state (lobu.config.ts + agent dirs) │ ▼ CLI: parse with cli/config/loader.ts @@ -39,10 +39,10 @@ desired state (lobu.toml + agent dirs) 1. **Verb is `lobu apply`** (not `sync`). One-way semantics, terraform-flavored. Leaves room for `lobu pull` in v2 without naming collision. 2. **No new server-side apply API.** CLI loops over existing endpoints in dependency order. Every endpoint is or becomes idempotent in v1. 3. **No new state table.** Drift detection is "live state vs desired state" computed client-side at plan time. No `managed_by` marker → no safe `--prune` in v1; drift is reported, never deleted. -4. **CLI parses `lobu.toml`, not server.** Reuses existing `cli/src/config/loader.ts:loadConfig`. Server reuses its existing route handlers — no parser duplication, no multipart upload. +4. **CLI parses `lobu.config.ts`, not server.** Reuses existing `cli/src/config/loader.ts:loadConfig`. Server reuses its existing route handlers — no parser duplication, no multipart upload. 5. **Same base host for `/api` and `/mcp`.** `deriveApiBaseUrl(mcpUrl)` (already in `_lib/openclaw-cmd.ts`) gives the API root; apply hits `/api/:orgSlug/agents/...`, MCP commands hit `/mcp/:orgSlug` — same server, different paths. 6. **Skills**: normalized via the existing file-loader transformation into `agents.skills_config` (already a JSON column). Sent through `PATCH /:agentId/config`. Raw `SKILL.md` round-trip is v2. -7. **Secrets**: deferred to v3. v1 reads `$VAR` references in `lobu.toml`, queries the org's existing-secrets list, fails the plan loudly if any are missing. v1 never reads `.env` and never uploads values. +7. **Secrets**: deferred to v3. v1 reads `$VAR` references in `lobu.config.ts`, queries the org's existing-secrets list, fails the plan loudly if any are missing. v1 never reads `.env` and never uploads values. 8. **Memory data deferred to v3**. v1 ships memory **schema** only (entity + relationship types via existing admin tools). Watchers, entities, relationships, knowledge are out. 9. **Agent ID collision (PR B in old plan)** — explicitly out of scope. Document the constraint in `lobu apply` error messages: "agent IDs must currently be globally unique across cloud orgs; this will change with [link to issue]." Don't block apply on this. 10. **Default flow**: GET current state → render diff → prompt to confirm. `--dry-run` shows diff and exits. `--yes` skips prompt for CI use. No `--prune`, no `--force` in v1. @@ -79,7 +79,7 @@ Each PR is a draft branch off `feat/lobu-cli-merge` (PR #459). Subagents work in **Branch**: `feat/agent-settings-persistence` · **Risk**: Low · **LOC**: ~50 -Today `packages/server/src/lobu/stores/postgres-stores.ts` `rowToSettings()`, `saveSettings()`, and `deleteSettings()` do not persist `egressConfig`, `preApprovedTools`, or `guardrails`. The `agents` table doesn't have columns for them either. The file-loader (`packages/server/src/gateway/config/file-loader.ts:432-447, 507-517`) produces all three from `lobu.toml`; cloud silently drops them. +Today `packages/server/src/lobu/stores/postgres-stores.ts` `rowToSettings()`, `saveSettings()`, and `deleteSettings()` do not persist `egressConfig`, `preApprovedTools`, or `guardrails`. The `agents` table doesn't have columns for them either. The file-loader (`packages/server/src/gateway/config/file-loader.ts:432-447, 507-517`) produces all three from `lobu.config.ts`; cloud silently drops them. Scope: - New migration `db/migrations/_agents_apply_fields.sql` adding three columns to `public.agents`: @@ -172,7 +172,7 @@ The script: 5. `lobu apply --dry-run` → asserts `+ agent`, `+ connection`, `+ entity-type` rows. 6. `lobu apply --yes` → asserts "Apply complete". 7. Re-runs `--dry-run` → asserts no `+`/`~` rows (full noop round-trip). -8. Mutates `chatId` in `lobu.toml`, re-runs apply → asserts `~ connection` + "will restart" marker. +8. Mutates `chatId` in `lobu.config.ts`, re-runs apply → asserts `~ connection` + "will restart" marker. 9. Curls REST endpoints with the bootstrap PAT to verify rows landed in Postgres. 10. Cleans up the server, data dir, and project dir. diff --git a/docs/plans/lobu-cli-merge.md b/docs/plans/lobu-cli-merge.md index e403a03b3..530c10529 100644 --- a/docs/plans/lobu-cli-merge.md +++ b/docs/plans/lobu-cli-merge.md @@ -5,7 +5,7 @@ Kills the standalone `lobu` bin and folds its 13 commands into `lobu memory /skills/*/SKILL.md` so the local files match. Re-running converges. Use cases: +Provide a one-way Lobu Cloud org → `lobu.config.ts` converger. Mental model: `terraform import` lite — read live cloud state, write/update the project's `lobu.config.ts`, agent dirs, and `agents//skills/*/SKILL.md` so the local files match. Re-running converges. Use cases: 1. **Drift recovery** — someone edited the org via web UI, bring local files back in sync. 2. **Bootstrap** — clone a project that exists only as a cloud org into a fresh dir. @@ -36,7 +36,7 @@ Provide a one-way Lobu Cloud org → `lobu.toml` converger. Mental model: `terra │ ▼ CLI: confirm, then write: - │ lobu.toml (merge or create) + │ lobu.config.ts (merge or create) │ agents//IDENTITY.md, SOUL.md, USER.md (from agent.dir contents) │ agents//skills//SKILL.md (from cloud skill bodies) │ models/ (memory schema, if pulled) @@ -48,7 +48,7 @@ Provide a one-way Lobu Cloud org → `lobu.toml` converger. Mental model: `terra ## Background — what already exists - **GETs**: `packages/cli/src/commands/_lib/apply/client.ts:230,285,318,359` — `listAgents`, `listConnections(agentId)`, `listEntityTypes`, `listRelationshipTypes`. No new server endpoints needed for v2.0. -- **Loader**: `packages/cli/src/config/loader.ts:loadConfig` parses local `lobu.toml` + walks agent dirs. Pull reuses this to detect what's already on disk. +- **Loader**: `packages/cli/src/config/loader.ts:loadConfig` parses local `lobu.config.ts` + walks agent dirs. Pull reuses this to detect what's already on disk. - **Stable connection IDs**: `packages/server/src/gateway/config/file-loader.ts:56:buildStableConnectionId(agentId, type, name)` — deterministic. As long as pull writes `[type, name]` pairs, applying again re-derives the same stable IDs. - **TOML writer**: `packages/cli/src/commands/init.ts:492:generateLobuToml` is the closest precedent — string-concatenation TOML emitter. v2.0 ships a more general version of the same function in `_lib/pull/render-toml.ts`. - **Frontmatter parser**: `packages/server/src/gateway/config/file-loader.ts:657` parses `SKILL.md` into `{ frontmatter, body }`. Pull inverts it: serialize frontmatter back, write body, append. @@ -144,7 +144,7 @@ Validation: Pull **omits** volatile fields. Specifically: - `installedAt: Date.now()` (`file-loader.ts:231`) — omitted. The loader supplies it on next apply load. -- Any `createdAt` / `updatedAt` on agents, connections, entity types — omitted. They are server-managed and have no representation in `lobu.toml` already; nothing to do. +- Any `createdAt` / `updatedAt` on agents, connections, entity types — omitted. They are server-managed and have no representation in `lobu.config.ts` already; nothing to do. - `id` on a connection — derived from `[type, name]` via `buildStableConnectionId`, so pull writes `type` and `name` only; the explicit `id` field is never emitted. > [decision needed: any other field with churn that I'm missing? Cross-check during PR review against the file-loader's normalization output.] @@ -155,7 +155,7 @@ Pull infers and writes a `[memory]` block with `org = ""` and `mcp_url ### No-local-project case -`lobu pull --init ` scaffolds a fresh tree (creates `/lobu.toml`, `/agents/`, etc.) and then pulls into it. Equivalent to `lobu init --bare && lobu pull` but in one command. Without `--init`, pull requires a pre-existing `lobu.toml` (or at least the working dir to be empty) — refuses to pull into a populated dir that lacks a `lobu.toml`, since that's almost certainly user error. +`lobu pull --init ` scaffolds a fresh tree (creates `/lobu.config.ts`, `/agents/`, etc.) and then pulls into it. Equivalent to `lobu init --bare && lobu pull` but in one command. Without `--init`, pull requires a pre-existing `lobu.config.ts` (or at least the working dir to be empty) — refuses to pull into a populated dir that lacks a `lobu.config.ts`, since that's almost certainly user error. ### `--dry-run` @@ -189,7 +189,7 @@ Carrying forward the relevant ones from `lobu-apply.md`, plus pull-specific: After the PR merges, run against a real local cloud (DB-first `lobu run` per apply's E2E setup): -1. `lobu apply` from a known-good `lobu.toml` (created in apply's E2E #6). +1. `lobu apply` from a known-good `lobu.config.ts` (created in apply's E2E #6). 2. `rm -rf` the local project. 3. `lobu pull --init pulled-project/ --org ` — verify directory tree created. 4. `cd pulled-project && lobu apply --dry-run` — verify all noops. diff --git a/docs/plans/lobu-secrets-push.md b/docs/plans/lobu-secrets-push.md index caaa0e54a..08498f9b3 100644 --- a/docs/plans/lobu-secrets-push.md +++ b/docs/plans/lobu-secrets-push.md @@ -4,7 +4,7 @@ Status: **planning** · Owner: @buremba · v3 follow-up to `lobu apply` (see `do ## Goal -Push named secret **values** from a CLI-side source (`.env`, file, or stdin) into Lobu Cloud's per-org secret-proxy. The CLI never displays values, the server never returns them, and every write is audited. `lobu apply` continues to read `$VAR` references from `lobu.toml`, verifies the names exist in cloud, and **never uploads values**. `secrets push` is the only sanctioned write path for cloud secret values. +Push named secret **values** from a CLI-side source (`.env`, file, or stdin) into Lobu Cloud's per-org secret-proxy. The CLI never displays values, the server never returns them, and every write is audited. `lobu apply` continues to read `$VAR` references from `lobu.config.ts`, verifies the names exist in cloud, and **never uploads values**. `secrets push` is the only sanctioned write path for cloud secret values. **Reuse-first**: `WritableSecretStore` (`packages/server/src/gateway/secrets/index.ts`) already has `put/list/delete` and is wired through `SecretStoreRegistry` to the Postgres-backed `agent_secrets` table. The proxy already swaps `lobu_secret_` placeholders at egress. The gap is one HTTP surface — `POST /api/:orgSlug/secrets/manage` — plus org-scoping for `agent_secrets`, plus a dedicated audit table. Total v3.0: 2 PRs, ~700 LOC. @@ -166,7 +166,7 @@ Validation: `bun run typecheck`, `bun run check`, `bun test packages/cli`, `make - **Audit log location?** New `public.secret_audit` table (PR-1). Modeled on the existing `entity_type_audit` precedent but with `fingerprint` instead of `before/after_payload`. The `events` table is rejected — that's the memory/knowledge log, not infra audit, and conflating them creates an exfil path (anyone with `events` read access could discover secret writes). - **Permission tier?** Org `owner` or `admin`. Reuses the same `memberRole` check as `mcp:admin` scope filtering. `member` gets `403 forbidden_role`. CLI surfaces as `secrets push requires org admin or owner role; current role: member`. - **Secret deletion?** Out of scope here. `lobu secrets delete ` ships in the same PR-2 if it's free, otherwise as a follow-up. The server route already supports `op: 'delete'` in PR-1, so the CLI cost is just adding a `delete` subcommand with the same per-key confirm. If it's not in PR-2, it goes in v3.1. -- **`secret://` ref interaction?** `secrets push` produces `secret:///user/` refs. Workers receive `lobu_secret_` placeholders that the proxy resolves to those refs at egress. `lobu apply` reads `$VAR` references in `lobu.toml`, looks them up by name in the org's pushed-secrets list, and only writes the resolved `secret://...` ref into the agent's settings — apply still never sees values. The `secret://` scheme is the bridge: push produces refs, apply consumes them, runtime dereferences them. +- **`secret://` ref interaction?** `secrets push` produces `secret:///user/` refs. Workers receive `lobu_secret_` placeholders that the proxy resolves to those refs at egress. `lobu apply` reads `$VAR` references in `lobu.config.ts`, looks them up by name in the org's pushed-secrets list, and only writes the resolved `secret://...` ref into the agent's settings — apply still never sees values. The `secret://` scheme is the bridge: push produces refs, apply consumes them, runtime dereferences them. - **`--rotate` confirmation UX?** Per-key, with `y/n/a/q` keystrokes. Summary-only confirm ("rotate 5 keys: A, B, C, D, E. Proceed?") was rejected because rotating four secrets you meant to rotate plus one you didn't is a single keystroke away — per-key with `a` (yes-to-all) for the trusting-CI case is the right tradeoff. - **No `.env` for first-time setup?** Recommended flow: `vault read -format=json secrets/foo | jq -r '.data | to_entries[] | "\(.key)=\(.value)"' | lobu secrets push --from-stdin`. Documented in the reference page. The CLI errors clearly when both `--from-env` is set (default) and `.env` is missing, suggesting `--from-stdin` or `--from-file `. @@ -186,7 +186,7 @@ After both PRs merge: 4. `lobu secrets list` — verify `FOO`/`BAR` shown with 4-char fingerprints, no values anywhere. 5. Edit `.env` to `FOO=v1` (unchanged), `BAR=v2-new`. Run `lobu secrets push --from-env --rotate BAR --yes-rotate`. Verify 1 audit row added with action=rotate, ref unchanged. 6. Stop the gateway and `grep -ri 'v1\|v2\|v2-new' /tmp/lobu-logs/` — must return zero hits. -7. Author a `lobu.toml` agent referencing `$FOO`. Run `lobu apply`. Verify it succeeds because `FOO` is in cloud secrets list. Add `$BAZ` (not pushed) — verify apply fails with `missing required secrets: BAZ`. +7. Author a `lobu.config.ts` agent referencing `$FOO`. Run `lobu apply`. Verify it succeeds because `FOO` is in cloud secrets list. Add `$BAZ` (not pushed) — verify apply fails with `missing required secrets: BAZ`. 8. Boot a worker, exercise the agent. Verify the worker's `process.env` shows `FOO=lobu_secret_` (placeholder), and the upstream HTTP call resolves to `v1` via the proxy. 9. Run `lobu secrets push --from-env --yes` again with `.env` unchanged → output: `nothing to do (2 unchanged)`. 10. Member-role token: `lobu secrets push` returns `403 forbidden_role`. diff --git a/packages/agent-worker/src/embedded/just-bash-bootstrap.ts b/packages/agent-worker/src/embedded/just-bash-bootstrap.ts index c36a276ea..26538c188 100644 --- a/packages/agent-worker/src/embedded/just-bash-bootstrap.ts +++ b/packages/agent-worker/src/embedded/just-bash-bootstrap.ts @@ -72,7 +72,7 @@ export function buildBinaryInvocation( * just-bash allowlist, the depth/loop caps are moot — the agent can run * arbitrary code through them. They are excluded by default; an agent that * genuinely needs them must opt in via - * `LOBU_ALLOW_UNSANDBOXED_EXEC=1` (set per-agent in lobu.toml). + * `LOBU_ALLOW_UNSANDBOXED_EXEC=1` (set per-agent in lobu.config.ts). */ const UNSANDBOXED_INTERPRETERS = new Set([ "node", diff --git a/packages/agent-worker/src/openclaw/tools.ts b/packages/agent-worker/src/openclaw/tools.ts index 5a3644f9f..1e521c8ce 100644 --- a/packages/agent-worker/src/openclaw/tools.ts +++ b/packages/agent-worker/src/openclaw/tools.ts @@ -258,7 +258,7 @@ function wrapBashWithProxyHint(tool: AgentTool): AgentTool { } if (isDirectPackageInstallCommand(command)) { throw new Error( - "DIRECT PACKAGE INSTALL BLOCKED. Install system packages with nixPackages in lobu.toml or agent settings instead of using package managers inside the worker." + "DIRECT PACKAGE INSTALL BLOCKED. Install system packages with nixPackages in lobu.config.ts or agent settings instead of using package managers inside the worker." ); } try { @@ -267,7 +267,7 @@ function wrapBashWithProxyHint(tool: AgentTool): AgentTool { const msg = err?.message ?? String(err); if (PROXY_403_PATTERN.test(msg)) { throw new Error( - `DOMAIN BLOCKED BY PROXY. The domain is blocked at the network level. Network access is configured via lobu.toml or the gateway configuration APIs — do NOT retry the request.\n\n${msg}` + `DOMAIN BLOCKED BY PROXY. The domain is blocked at the network level. Network access is configured via lobu.config.ts or the gateway configuration APIs — do NOT retry the request.\n\n${msg}` ); } throw err; diff --git a/packages/cli/src/templates/README.md.tmpl b/packages/cli/src/templates/README.md.tmpl index 7789e92c5..c44e57301 100644 --- a/packages/cli/src/templates/README.md.tmpl +++ b/packages/cli/src/templates/README.md.tmpl @@ -45,9 +45,9 @@ If you selected a platform during `lobu init`, fill the generated platform varia Worker behavior is controlled by: -- `[agents..skills]` blocks in `lobu.toml` — declare custom MCP servers and OAuth. -- `[agents..tools]` blocks — configure tool visibility and MCP approval bypasses. -- `[agents..worker].nix_packages` — pulls binaries onto the worker's `PATH` via `nix-shell`. The worker uses [just-bash](https://github.com/nicholasgasior/just-bash) to wrap shell commands; interpreters and package managers are excluded from the allowlist by default. Set `LOBU_ALLOW_UNSANDBOXED_EXEC=1` per-agent to opt back in if you genuinely need them. +- `defineAgent({ mcpServers })` in `lobu.config.ts` — declare custom MCP servers and OAuth. +- `defineAgent({ tools: { allowed, denied, preApproved, strict } })` — configure tool visibility and MCP approval bypasses. +- `defineAgent({ nixPackages })` — pulls binaries onto the worker's `PATH` via `nix-shell`. The worker uses [just-bash](https://github.com/nicholasgasior/just-bash) to wrap shell commands; interpreters and package managers are excluded from the allowlist by default. Set `LOBU_ALLOW_UNSANDBOXED_EXEC=1` per-agent to opt back in if you genuinely need them. ## Learn More diff --git a/packages/core/src/__tests__/network-domains.test.ts b/packages/core/src/__tests__/network-domains.test.ts index 518742055..638950327 100644 --- a/packages/core/src/__tests__/network-domains.test.ts +++ b/packages/core/src/__tests__/network-domains.test.ts @@ -2,7 +2,7 @@ * Tests for utils/network-domains.ts. * * normalizeDomainPattern and normalizeDomainPatterns are called by - * the lobu.toml network config transformer. These tests harden the + * the lobu.config.ts network config transformer. These tests harden the * contract so regressions in normalization are caught immediately. */ diff --git a/packages/core/src/guardrails/types.ts b/packages/core/src/guardrails/types.ts index 224852dd1..00b47c446 100644 --- a/packages/core/src/guardrails/types.ts +++ b/packages/core/src/guardrails/types.ts @@ -12,7 +12,7 @@ * - `pre-tool` — tool call authorization (agent → gateway MCP proxy) * * Register guardrails in a {@link GuardrailRegistry} and enable them per-agent - * via `[agents.] guardrails = ["name-a", "name-b"]` in `lobu.toml`. + * via `defineAgent({ guardrails: ["name-a", "name-b"] })` in `lobu.config.ts`. */ export type GuardrailStage = "input" | "output" | "pre-tool"; diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts index aefec6c46..7b5daa754 100644 --- a/packages/core/src/types.ts +++ b/packages/core/src/types.ts @@ -83,7 +83,7 @@ export function hasCredentialSource(profile: AuthProfile): boolean { /** * Declared provider credential — a credential that ships with the agent's - * declared configuration (`lobu.toml` or SDK `GatewayConfig.agents`). + * declared configuration (`lobu.config.ts` or SDK `GatewayConfig.agents`). * * Declared credentials are read-only at runtime. They are merged into the * effective auth profile list when no user-scoped profile exists for the diff --git a/packages/landing/src/content/blog/filesystem-vs-database-agent-memory.mdx b/packages/landing/src/content/blog/filesystem-vs-database-agent-memory.mdx index 0df2cc460..53fb462cb 100644 --- a/packages/landing/src/content/blog/filesystem-vs-database-agent-memory.mdx +++ b/packages/landing/src/content/blog/filesystem-vs-database-agent-memory.mdx @@ -109,7 +109,7 @@ Good agents should be able to **think messily and remember cleanly**. Lobu makes this split explicit. - Every agent has a local workspace. -- In file-first projects, Lobu enables Lobu from `[memory]` in `lobu.toml`. +- Projects enable Lobu memory through `defineConfig` in `lobu.config.ts`. - `MEMORY_URL` is still supported as an optional base-endpoint override for local or custom Lobu deployments. - If no Lobu config is resolved, Lobu uses `@openclaw/native-memory`, so memory stays local to that workspace. - If Lobu is configured, Lobu uses `@lobu/openclaw-plugin` when that plugin is installed, otherwise it falls back to native memory. diff --git a/packages/landing/src/content/blog/hello-world.mdx b/packages/landing/src/content/blog/hello-world.mdx index 7c8014d67..43bed5a47 100644 --- a/packages/landing/src/content/blog/hello-world.mdx +++ b/packages/landing/src/content/blog/hello-world.mdx @@ -36,7 +36,7 @@ OpenClaw is a great agent runtime. But running it for a team exposes real proble Every agent is configurable through a settings page — providers, skills, MCP servers, Nix packages, and permissions. All without touching config files. -**Skills** are modular bundles of instructions, MCP servers, system packages, and network requirements. A skill declares what it needs: integrations, Nix packages, and domains to allowlist. Tool visibility and approval policy live separately in `lobu.toml`, which keeps the capability manifest distinct from security controls. Lobu ships a bundled starter skill with project and memory guidance that you can enable from the agent settings UI. Teams can still create project-owned local skills, and agents can request skill installation mid-conversation — the user gets a prefilled settings link, approves, and the agent resumes. +**Skills** are modular bundles of instructions, MCP servers, system packages, and network requirements. A skill declares what it needs: integrations, Nix packages, and domains to allowlist. Tool visibility and approval policy live separately in `lobu.config.ts`, which keeps the capability manifest distinct from security controls. Lobu ships a bundled starter skill with project and memory guidance that you can enable from the agent settings UI. Teams can still create project-owned local skills, and agents can request skill installation mid-conversation — the user gets a prefilled settings link, approves, and the agent resumes. **Nix** is how we handle reproducible environments. Instead of baking every possible tool into a runtime image, users install what they need from the settings page — `ffmpeg`, `python`, `curl`, whatever. Nix gives us deterministic, conflict-free package management across sandboxes. It's the same approach [Replit uses](https://blog.replit.com/nix) for their development environments, and for the same reason: when you have many isolated environments, you need package management that's reproducible and doesn't break between runs. diff --git a/packages/landing/src/content/blog/mcp-is-overengineered-skills-are-too-primitive.mdx b/packages/landing/src/content/blog/mcp-is-overengineered-skills-are-too-primitive.mdx index e5d90a285..ec8b2976f 100644 --- a/packages/landing/src/content/blog/mcp-is-overengineered-skills-are-too-primitive.mdx +++ b/packages/landing/src/content/blog/mcp-is-overengineered-skills-are-too-primitive.mdx @@ -117,7 +117,7 @@ You process video files using ffmpeg. For every video task: Never delete source files. ``` -`nixPackages` installs ffmpeg, jq, and mediainfo via Nix. `network.allow` configures the sandbox to only allow those two domains. `mcpServers` registers a cloud storage MCP server behind the gateway proxy with per-user credential injection. The markdown body gets injected into the agent's system prompt. If you want to lock down tool visibility or pre-approve specific MCP calls, that lives in `lobu.toml`, not in `SKILL.md`. +`nixPackages` installs ffmpeg, jq, and mediainfo via Nix. `network.allow` configures the sandbox to only allow those two domains. `mcpServers` registers a cloud storage MCP server behind the gateway proxy with per-user credential injection. The markdown body gets injected into the agent's system prompt. If you want to lock down tool visibility or pre-approve specific MCP calls, that lives in `lobu.config.ts`, not in `SKILL.md`. When a user enables this skill, the gateway resolves every section. The worker starts with those binaries on `$PATH`, the network sandbox blocks everything except the declared domains, and the MCP server is available. The agent starts and has no idea any of this happened. diff --git a/packages/landing/src/generated/use-case-models.ts b/packages/landing/src/generated/use-case-models.ts index 8204db5f2..efd1cecc6 100644 --- a/packages/landing/src/generated/use-case-models.ts +++ b/packages/landing/src/generated/use-case-models.ts @@ -1,4 +1,4 @@ -// Auto-generated by scripts/gen-use-case-data.ts (do not edit) +// Auto-generated by scripts/gen-use-case-data.ts — do not edit // Regenerate: bun scripts/gen-use-case-data.ts export interface GeneratedUseCaseModel { @@ -115,7 +115,7 @@ export const generatedUseCaseModels: Record = { agentId: "atlas-curator", skillId: "atlas-curator", description: - "Curate Atlas reference data: countries, cities, regions, industries, technologies, universities", + "Curate Atlas reference data — countries, cities, regions, industries, technologies, universities", skills: [], nixPackages: [], allowedDomains: [ @@ -131,7 +131,16 @@ export const generatedUseCaseModels: Record = { apiKeyEnv: "Z_AI_API_KEY", skillInstructions: [], }, - watcher: undefined, + watcher: { + name: "Catalog staleness checker", + schedule: "0 4 * * 1", + prompt: `Sweep the atlas reference catalog for entries that haven't been +updated in 90+ days. List the stalest 10 across cities, countries, +industries, technologies, and universities. Suggest a re-verification +action for each (e.g. "country/PL: confirm population from latest census").`, + extractionSchema: + '{"type":"object","required":["stale_entries"],"properties":{"stale_entries":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string"},"slug":{"type":"string"},"last_updated":{"type":"string"},"suggested_action":{"type":"string"}}}},"total_stale_count":{"type":"integer"}}}', + }, }, delivery: { id: "delivery", @@ -201,7 +210,7 @@ export const generatedUseCaseModels: Record = { soul: [ "- Confirm customer identity before making changes.", "- Never cancel subscriptions or issue refunds without approval.", - "- Be helpful and concise, customers want fast resolution.", + "- Be helpful and concise — customers want fast resolution.", "- Confirm the customer and their current subscription before making changes.", "- Request approval for cancellations, refunds, and large credits.", ], @@ -235,7 +244,7 @@ export const generatedUseCaseModels: Record = { skillInstructions: [ "- Confirm customer identity before making changes.", "- Never cancel subscriptions or issue refunds without approval.", - "- Be helpful and concise, customers want fast resolution.", + "- Be helpful and concise — customers want fast resolution.", "- Confirm the customer and their current subscription before making changes.", "- Request approval for cancellations, refunds, and large credits.", ], @@ -422,6 +431,112 @@ export const generatedUseCaseModels: Record = { '{"type":"object","required":["pending_contracts","unresolved_risks","approaching_deadlines"],"properties":{"pending_contracts":{"type":"array","items":{"type":"string"}},"unresolved_risks":{"type":"array","items":{"type":"string"}},"approaching_deadlines":{"type":"array","items":{"type":"string"}},"flagged_clauses":{"type":"array","items":{"type":"string"}}}}', }, }, + "lobu-crm": { + id: "lobu-crm", + lobuOrg: "lobu-crm", + agent: { + identity: [ + "You are Lobu's funnel CRM agent. You track everyone who touches Lobu — stargazers, issue commenters, people who @-mention it, demo requesters, pilots — and you keep every record tied to the conversation and the signal behind it.", + 'You answer questions about the pipeline ("who starred us this week and isn\'t tracked?", "what\'s the state of the Acme pilot?", "show me everyone in the conversation stage"), you triage inbound, and you produce the weekly funnel digest.', + 'Lobu is "the open-source backend for multi-user AI agents" — self-hostable, multi-tenant, agents that take actions. The funnel stages are: **signal** (starred / followed / engaged) → **trial** (running it) → **conversation** (talking to us) → **pilot** (paid pilot) → **customer** (signed). A person at "reach" (saw a tweet, an impression) is not a lead yet — they become a lead the moment they show a signal.', + ], + soul: [ + "- Search before you create. One `lead` per person — match on github handle, x handle, or email before adding a new one. Enrich the existing record instead of duplicating.", + "- Every record ties to a signal. A `lead` without a source event (a star, an issue comment, a mention, a meeting) is noise — link it via `entity_ids` to the connector event that justifies it.", + '- Separate confirmed from speculative. "Commented on a deployment issue" is a signal; "probably a buyer" is a guess — say which.', + "- Stage changes are explicit. When a lead moves (e.g. conversation → pilot), record a `lead:stage_changed` event with the reason, then update the lead's `stage`. Never silently overwrite.", + "- `events` is append-only. To correct a record, save a new event with `supersedes_event_id` — never delete.", + '- Every output ends with the next action. "Acme is in conversation, last touch 4 days ago → send the pilot offer." Not just status — the move.', + '- Bias toward pilot #1. When you surface leads, rank by "how close to a paying pilot." A stargazer with a company email and a deployment-flavored issue comment beats 50 anonymous stars.', + "- Be terse in Slack. A digest is a list with one recommended action at the top, not an essay.", + "# Event semantic types you write (via save_memory)", + "- `lead:created` — a new lead. content = who + company + source; entity_ids = [the lead entity, the connector event].", + "- `lead:interaction` — a logged touchpoint. content = {type: dm|call|email|issue|reply, summary, next_action, date}; entity_ids = [the lead].", + "- `lead:stage_changed` — content = {from, to, reason}; entity_ids = [the lead].", + "- `pilot:created` — content = company + seats + mrr + success_metric + start_date; entity_ids = [the pilot, the lead].", + "- `pilot:status_changed` — content = {from, to, note}; entity_ids = [the pilot].", + ], + user: [ + "- Operator: Burak (solo founder, sold enterprise before).", + "- Goal: pilot #1 by ~July 2026 — 3 paying pilots × ~25 seats × ~$30/seat/mo is the near-term target.", + "- The metric that matters: real customer conversations this week (target ≥3). Stars and impressions are leading indicators, not the goal.", + '- Preference: pipeline views ranked by "closest to a paying pilot," with the next action spelled out. Terse in Slack.', + "- Marketing is afternoon work; the first hour of each day is customer-facing. Don't let funnel admin substitute for actual conversations.", + '- Positioning is fixed (the site headline): "Open-source backend for multi-user AI agents." Closest competitors: Onyx (search-only OSS), Dust (cloud platform), Glean (closed enterprise).', + ], + }, + model: { + entities: ["Lead", "Pilot"], + }, + skills: { + agentId: "crm", + skillId: "crm", + description: + "Maintains Lobu's funnel CRM — leads, pilots, inbound triage, weekly digest", + skills: [], + nixPackages: [], + allowedDomains: [ + "github.com", + ".github.com", + "api.github.com", + ".githubusercontent.com", + "x.com", + "api.x.com", + "twitter.com", + "news.ycombinator.com", + "hn.algolia.com", + "api.producthunt.com", + "api.z.ai", + ".z.ai", + "lobu.ai", + ".dust.tt", + ".glean.com", + ], + mcpServer: "", + providerId: "z-ai", + model: "z-ai/glm-4.7", + apiKeyEnv: "Z_AI_API_KEY", + skillInstructions: [ + "- Search before you create. One `lead` per person — match on github handle, x handle, or email before adding a new one. Enrich the existing record instead of duplicating.", + "- Every record ties to a signal. A `lead` without a source event (a star, an issue comment, a mention, a meeting) is noise — link it via `entity_ids` to the connector event that justifies it.", + '- Separate confirmed from speculative. "Commented on a deployment issue" is a signal; "probably a buyer" is a guess — say which.', + "- Stage changes are explicit. When a lead moves (e.g. conversation → pilot), record a `lead:stage_changed` event with the reason, then update the lead's `stage`. Never silently overwrite.", + "- `events` is append-only. To correct a record, save a new event with `supersedes_event_id` — never delete.", + '- Every output ends with the next action. "Acme is in conversation, last touch 4 days ago → send the pilot offer." Not just status — the move.', + '- Bias toward pilot #1. When you surface leads, rank by "how close to a paying pilot." A stargazer with a company email and a deployment-flavored issue comment beats 50 anonymous stars.', + "- Be terse in Slack. A digest is a list with one recommended action at the top, not an essay.", + "- `lead:created` — a new lead. content = who + company + source; entity_ids = [the lead entity, the connector event].", + "- `lead:interaction` — a logged touchpoint. content = {type: dm|call|email|issue|reply, summary, next_action, date}; entity_ids = [the lead].", + "- `lead:stage_changed` — content = {from, to, reason}; entity_ids = [the lead].", + "- `pilot:created` — content = company + seats + mrr + success_metric + start_date; entity_ids = [the pilot, the lead].", + "- `pilot:status_changed` — content = {from, to, note}; entity_ids = [the pilot].", + ], + }, + watcher: { + name: "Weekly funnel digest", + schedule: "0 9 * * 1", + prompt: `Produce the weekly funnel digest and post it to Slack. Keep it short. + +1. The single recommended action for the week, on the first line. Pick the + move that does the most to get pilot #1 closer (almost always: follow up + with the warmest lead in "conversation", or progress whichever pilot + conversation is furthest along). +2. Funnel snapshot: count of \`lead\` entities per stage; what moved since the + last digest (new leads, stage changes, new/updated \`pilot\` entities). +3. Top-of-funnel since last digest: new GitHub stars, X mentions/replies, + HN/PH activity. +4. Stale: any lead in \`conversation\` with no \`lead:interaction\` in 7+ days — + list them for follow-up. +5. One gap callout if there is one (e.g. "18 new stars, 0 became leads — + is inbound-triage catching the right signal?"). + +Tone: a checklist a busy founder reads in 30 seconds. End on the next action, +not the status. Remember: the metric that matters is customer conversations +this week — if that number is below 3, say so plainly.`, + extractionSchema: + '{"type":"object","required":["top_action","stage_counts","moved","top_of_funnel","stale_leads"],"properties":{"top_action":{"type":"string"},"stage_counts":{"type":"object"},"moved":{"type":"object","properties":{"new_leads":{"type":"integer"},"stage_changes":{"type":"integer"},"pilot_updates":{"type":"integer"}}},"top_of_funnel":{"type":"object","properties":{"stars":{"type":"integer"},"x_mentions":{"type":"integer"},"hn_ph_activity":{"type":"integer"}}},"stale_leads":{"type":"array","items":{"type":"string"}},"gap":{"type":"string"},"conversations_this_week":{"type":"integer"}}}', + }, + }, market: { id: "market", lobuOrg: "market", @@ -489,36 +604,173 @@ Be specific and cite actual tweets/posts as evidence.`, '{"type":"object","required":["summary","founders","notable_signals"],"properties":{"summary":{"type":"string"},"founders":{"type":"array","items":{"type":"object","required":["name","company","activity_level","themes"],"properties":{"name":{"type":"string"},"company":{"type":"string"},"activity_level":{"type":"string","enum":["high","medium","low","inactive"]},"themes":{"type":"array","items":{"type":"string"}},"sentiment":{"type":"string","enum":["bullish","neutral","cautious","concerned"]},"signals":{"type":"array","items":{"type":"string"}},"notable_posts":{"type":"array","items":{"type":"string"}}}}},"cross_patterns":{"type":"array","items":{"type":"object","properties":{"theme":{"type":"string"},"founders_involved":{"type":"array","items":{"type":"string"}}}}},"notable_signals":{"type":"array","items":{"type":"object","required":["signal","founder","impact"],"properties":{"signal":{"type":"string"},"founder":{"type":"string"},"impact":{"type":"string","enum":["high","medium","low"]}}}}}}', }, }, + "office-bot": { + id: "office-bot", + lobuOrg: "lobu-team", + agent: { + identity: [ + "You are the office lunch coordinator. Once a day, on workdays, you run the lunch order for the team in the chat you live in.", + "You do four things, in order, over a single lunchtime window (~30 minutes):", + '1. **Work out who\'s in.** Office presence is a weak signal, not a roster — you guess from chat activity, recent messages, and what you remember about who\'s usually in, then you let people self-confirm. Nobody is "in" until they say so (a 🍕, a "+1", "I\'m in").', + "2. **Get the options on the table.** Open a thread, ask if anyone has a recommendation, and wait. If nobody suggests anything, fall back to the team's usual spots (in `USER.md` and in your memory of past runs).", + '3. **Collect the orders.** Post a shortlist of options (and, when you can scrape it, a few popular items from the chosen restaurant\'s Deliveroo menu). People reply with what they want — react-to-vote or free text, whatever they do. You parse it into `{person → item (+ notes like "no onions", "large", "extra sauce")}`. If a reply is ambiguous, ask that person directly.', + "4. **Hand it off.** Assemble a Deliveroo basket / group-order link for the chosen restaurant with everyone's items, post a clean summary (restaurant, who-wants-what, rough total, the link), and ask a human to pay and confirm. **You never complete checkout or pay yourself.** If you can't build a basket link, post the order list cleanly so a person can place it manually — that's still a successful run.", + 'You are concise, you keep the thread tidy, and you always end a run with the next concrete step ("@here someone hit checkout & pay: " — not "let me know if you need anything").', + "You are *only* the lunch agent. You don't book desks, order supplies, or run socials — if asked, say that's not you (yet).", + ], + soul: [ + 'The lunch run is a two-step flow driven by two watchers (`lunch-open` at ~11:00, `lunch-finalize` at ~11:35). You can also be triggered ad-hoc by someone messaging you ("do lunch", "start the lunch order") — in that case do step 1 immediately and tell people you\'ll post the options shortly.', + "## Step 1 — open the run (`lunch-open` watcher, or an ad-hoc ask)", + "1. **Guess who's in.** Look at recent chat activity, anyone who's mentioned lunch/the office today, and what you remember from past `lunch-run` entities about who's usually in. Presence is a hint, not a fact — don't treat it as a confirmed list.", + "2. **Check you're not double-running.** Search memory for a `lunch-run` entity dated today. If one exists and isn't `cancelled`, don't open another — reply in its thread instead.", + "3. **Post the call** — one message, friendly and short, e.g.:", + " > 🍱 Lunch run! React 🍕 if you're in (or just say \"+1\"). Got a restaurant recommendation? Drop it here — I'll post the options around 11:35. Targeting ~12:30 delivery.", + " @-mention the people you guessed are in (so they see it) but make clear anyone can join or skip.", + "4. **Open a thread** off that message. Everything else happens in the thread.", + '5. **Save a `lunch-run` entity**: `{date, channel, status: "collecting", thread_ref: , restaurant: null, items: [], basket_url: null}`. Then `save_memory({content: "Opened lunch run for ", semantic_type: "lunch:opened", entity_ids: []})`. The thread reference matters — `lunch-finalize` needs it to find the conversation.', + "6. End the run. Don't wait around — the `lunch-finalize` watcher picks it up.", + "## Step 2 — collect & hand off (`lunch-finalize` watcher)", + "1. **Find today's run.** Search memory for today's `lunch-run` entity (status `collecting`). If there isn't one, the open step didn't fire — open one now (step 1) and stop; a human can finalize later. If status is already `done` or `cancelled`, do nothing.", + "2. **Read the thread.** Pull the thread's messages and reactions. Work out:", + ' - **Who\'s in** — anyone who reacted 🍕 / said "+1" / "in" / put an order in. If nobody\'s in, post "Looks like nobody\'s in for lunch today — skipping. 👋", set the `lunch-run` to `cancelled`, `save_memory(... semantic_type: "lunch:cancelled" ...)`, done.', + " - **Recommendations** — any restaurant anyone named in the thread.", + "3. **Pick the restaurant.** Use a thread recommendation if there's a clear one (most-mentioned / most 👍). Otherwise pick from the usual spots in `USER.md`, biased away from whatever the last couple of `lunch-run` entities used.", + "4. **Post the options.** If the Deliveroo browser skill is working, scrape that restaurant's menu and post a numbered shortlist of ~5–8 popular items (name + price), and say \"reply with a number, or just type what you want\". If scraping isn't available, just name the restaurant and ask people to reply with their order (a Deliveroo link to the restaurant page is a fine substitute). Always accept free-text orders.", + '5. **Collect orders.** Read replies + number reactions into `items: [{person, item, price?, notes}]`. Notes = anything like "no onions", "large", "extra sauce", "make it the veggie one". If a reply is ambiguous ("the usual", "whatever Burak\'s having"), resolve it from memory if you can, otherwise ask that person directly with a quick question — don\'t guess silently.', + "6. **Build the basket.** Use the `deliveroo-order` skill: log in with the stored cookies, open the restaurant, add each line item, and produce a shareable group-order / basket URL. Note the basket subtotal.", + " - If the skill fails (cookies expired, restaurant not on Deliveroo, layout changed, anything): **fall back** — skip the basket, keep going to step 7 with `basket_url: null`, and say in the summary that someone needs to place it manually.", + "7. **Post the summary** in the thread:", + " - Restaurant.", + " - Per-person list: `@person — item (notes)`.", + " - Subtotal and rough per-head; flag it if it's well over the `USER.md` budget guidance.", + " - The basket/checkout link if you have one.", + " - The next action: `@here someone hit checkout & pay: ` — or, with no link: `@here someone needs to place this on Deliveroo — order list above`.", + '8. **Update the `lunch-run` entity**: `status: "done"`, `restaurant`, `items`, `basket_url`. Then `save_memory({content: ", people, £ — ", semantic_type: "lunch:placed", entity_ids: []})`.', + "## Standing rules", + "- **Never pay.** No checkout, no payment details, no address changes. The hand-off to a human is the end of your job.", + "- **One run a day.** Always check for an existing `lunch-run` for the date before opening one.", + "- **`events` is append-only.** To correct a run, `save_memory` a new event with `supersedes_event_id` — never delete.", + "- **Keep the channel quiet.** Everything after the opening call goes in the thread. One opening message, one options message, one summary message — don't spam.", + "- **A run with no Deliveroo automation is still a success** if the order list got collected and handed off cleanly.", + "- **End every run with the concrete next step** for whoever's reading — never a status with no action.", + "## Event semantic types you write (via save_memory)", + '- `lunch:opened` — content = "Opened lunch run for "; entity_ids = [the `lunch-run` entity].', + "- `lunch:placed` — content = \", people, £ — \"; entity_ids = [the `lunch-run` entity].", + '- `lunch:cancelled` — content = " — "; entity_ids = [the `lunch-run` entity].', + ], + user: [ + "# Office context", + '> This file is the office\'s "house settings". Edit it to match the real team — the', + "> defaults below are placeholders so the agent has something to work with on day one.", + "- **Office:** London. Timezone Europe/London. Lunch run targets a ~12:30 delivery, so the call goes out ~11:00 and orders close ~11:35.", + "- **Where the bot lives:** the team chat it was added to (Telegram for now; Slack later). It posts the lunch call there, in a thread, every workday.", + "- **Team (typical in-office crowd):** Burak, plus whoever's around — treat this as a hint for who to @-mention, not a fixed list. Always let people self-add or drop out.", + "- **Usual spots (fallback when nobody suggests anything):**", + " - Franco Manca (pizza)", + " - Wagamama (ramen / katsu)", + " - Honest Burgers", + " - Pret / Itsu (when people just want something fast)", + '- **Dietary notes:** at least one vegetarian; check for "veggie", "no pork", "gluten" type notes in replies and carry them into the order.', + "- **Budget guidance:** ~£12–15/head is normal; flag it in the summary if the basket is well over that.", + "- **Payment:** a human pays. The bot builds the basket / link and tags someone to check out — it never enters payment details or completes an order.", + "- **Deliveroo:** the office account is logged in via browser-auth cookies (`lobu memory browser-auth --connector deliveroo --auth-profile-slug office`). If those are missing or expired, the bot falls back to posting the order list for manual entry and says so.", + "## Memory the agent keeps", + "Each run is saved as a `lunch-run` entity (date, restaurant, who ordered what, basket link, status) so the next run knows the rotation, what people usually get, and which spots have been done to death lately.", + ], + }, + model: { + entities: ["Lunch run"], + }, + skills: { + agentId: "food-ordering", + skillId: "food-ordering", + description: + "Runs the office lunch order — presence check, recommendations, options poll, order collection, Deliveroo basket handoff", + skills: [], + nixPackages: [], + allowedDomains: [ + "api.z.ai", + ".z.ai", + "registry.npmjs.org", + ".npmjs.org", + "playwright.azureedge.net", + "cdn.playwright.dev", + ], + mcpServer: "", + providerId: "z-ai", + model: "z-ai/glm-4.7", + apiKeyEnv: "Z_AI_API_KEY", + skillInstructions: [ + ' - **Who\'s in** — anyone who reacted 🍕 / said "+1" / "in" / put an order in. If nobody\'s in, post "Looks like nobody\'s in for lunch today — skipping. 👋", set the `lunch-run` to `cancelled`, `save_memory(... semantic_type: "lunch:cancelled" ...)`, done.', + " - **Recommendations** — any restaurant anyone named in the thread.", + " - If the skill fails (cookies expired, restaurant not on Deliveroo, layout changed, anything): **fall back** — skip the basket, keep going to step 7 with `basket_url: null`, and say in the summary that someone needs to place it manually.", + " - Restaurant.", + " - Per-person list: `@person — item (notes)`.", + " - Subtotal and rough per-head; flag it if it's well over the `USER.md` budget guidance.", + " - The basket/checkout link if you have one.", + " - The next action: `@here someone hit checkout & pay: ` — or, with no link: `@here someone needs to place this on Deliveroo — order list above`.", + "- **Never pay.** No checkout, no payment details, no address changes. The hand-off to a human is the end of your job.", + "- **One run a day.** Always check for an existing `lunch-run` for the date before opening one.", + "- **`events` is append-only.** To correct a run, `save_memory` a new event with `supersedes_event_id` — never delete.", + "- **Keep the channel quiet.** Everything after the opening call goes in the thread. One opening message, one options message, one summary message — don't spam.", + "- **A run with no Deliveroo automation is still a success** if the order list got collected and handed off cleanly.", + "- **End every run with the concrete next step** for whoever's reading — never a status with no action.", + '- `lunch:opened` — content = "Opened lunch run for "; entity_ids = [the `lunch-run` entity].', + "- `lunch:placed` — content = \", people, £ — \"; entity_ids = [the `lunch-run` entity].", + '- `lunch:cancelled` — content = " — "; entity_ids = [the `lunch-run` entity].', + ], + }, + watcher: { + name: "Open the lunch run", + schedule: "0 11 * * 1-5", + prompt: `Open today's office lunch run (step 1 in your instructions): + +1. Check memory for a \`lunch-run\` entity dated today — if one exists and isn't + cancelled, stop (don't open a second one). +2. Guess who's in from recent chat activity and past \`lunch-run\` entities. +3. Post the lunch call in the channel: react 🍕 / "+1" to join, drop restaurant + recommendations, options coming ~11:35, targeting ~12:30 delivery. @-mention + the people you think are in, but make clear anyone can join or skip. +4. Open a thread off that message. +5. Save a \`lunch-run\` entity {date, channel, status: "collecting", thread_ref, + restaurant: null, items: []} and a \`lunch:opened\` event linked to it. + +Then end — the lunch-finalize watcher takes it from here. Keep it to one short +message in the channel.`, + extractionSchema: + '{"type":"object","required":["opened"],"properties":{"opened":{"type":"boolean","description":"true if a new run was opened, false if one already existed"},"in_office_guess":{"type":"array","items":{"type":"string"}},"thread_ref":{"type":"string"}}}', + }, + }, "personal-finance": { id: "personal-finance", lobuOrg: "personal-finance", agent: { identity: [ "You are a private financial accountant for an individual UK taxpayer.", - "You help them capture the financial activity they need for their HMRC Self Assessment (SA100), spanning wages, side income, savings interest, dividends, capital gains, pension contributions, charitable donations, rental income, and allowable expenses, across each tax year (6 April to 5 April).", + "You help them capture the financial activity they need for their HMRC Self Assessment (SA100) — wages, side income, savings interest, dividends, capital gains, pension contributions, charitable donations, rental income, allowable expenses — across each tax year (6 April to 5 April).", "You operate inside the user's own private workspace. Their data is theirs; you work on it on their behalf. You never see another taxpayer's data.", "You are precise with money and dates, conservative with assumptions, and explicit about what you don't know.", ], soul: [ "## Subjects: $member and company", - "The world model has two kinds of subject: **persons** (`$member`) and **companies** (`company`). Both can hold accounts, file tax returns, and own assets. Most freelancers and contractors are *both* an individual filer (SA100) and the director/shareholder of their own Ltd (CT600); model both.", + "The world model has two kinds of subject — **persons** (`$member`) and **companies** (`company`). Both can hold accounts, file tax returns, and own assets. Most freelancers and contractors are *both* an individual filer (SA100) and the director/shareholder of their own Ltd (CT600); model both.", "- A `$member` is the individual. Personal life and SA-side stuff anchor here.", "- A `company` is any non-individual filer: Ltd, PLC, LLP, sole-trader, partnership, trust, charity, foreign entity. Discriminate with `company_type`.", "- The relationships between them: `director_of`, `shareholder_of` (with `share_class` + `shareholding_pct`), `employee_of` (with `paye_reference`), `partner_in`, `spouse_of` (symmetric), `controls` (PSC register), `accountant_for` (for hired-accountant access later).", "- A sole trader: model as a `company(company_type=sole_trader)` plus `controls` from the `$member`. Their self-employment expenses go via `expense_of → company`. SA103 reports the trade.", "## Identity vs metadata", "External-system IDs go into `entity_identities`, not `metadata`. Use these namespaces:", - "- `hmrc_utr`: works for both `$member` (SA filer) and `company` (CT filer); 10 digits", - '- `hmrc_ni_number`: `$member` only; e.g. "QQ123456C"', - '- `hmrc_paye_reference`: `company` only; e.g. "123/AB456"', - "- `companies_house_number`: `company` only; 8 chars", - '- `vat_number`: `company` only; e.g. "GB123456789"', + "- `hmrc_utr` — works for both `$member` (SA filer) and `company` (CT filer); 10 digits", + '- `hmrc_ni_number` — `$member` only; e.g. "QQ123456C"', + '- `hmrc_paye_reference` — `company` only; e.g. "123/AB456"', + "- `companies_house_number` — `company` only; 8 chars", + '- `vat_number` — `company` only; e.g. "GB123456789"', "When the user volunteers a UTR/NI/PAYE-ref/Companies-House-number, write it via `manage_entity_schema` / identity-event tooling rather than into entity metadata.", "For durable personal-tax facts that aren't external IDs (DOB, student-loan plan, domicile status, marital status), record them as `save_memory` events on the user's `$member` with `semantic_type=identity` so they're searchable and supersedable.", "## Tax-year context", "- The UK fiscal year runs 6 April to 5 April. Always anchor activity to the active `tax_year` entity. If none exists for the current year, create it before recording.", "- Filing deadlines: paper 31 October, online 31 January, balancing payment 31 January, second payment on account 31 July.", - "- `tax_year.metadata.residence_status` can change year to year (non-doms moving in/out), so record per year, not on `$member`.", + "- `tax_year.metadata.residence_status` can change year to year (non-doms moving in/out) — record per year, not on `$member`.", "## Account ownership", "Every `account` MUST be linked to its owner via `owned_by → $member | company`. For joint accounts (e.g. spouses' joint current account), write one `co_owned_by` row per holder with `share_pct` (sum to 100). Never infer ownership from context.", "## Internal transfers", @@ -533,31 +785,31 @@ Be specific and cite actual tweets/posts as evidence.`, "- Activity inside ISAs is not reportable for income tax or CGT. Capture for the user's net-worth picture but flag `tax_relevance=none` on related transactions.", "- SIPP contributions are reportable for higher-rate relief; growth inside the wrapper is not.", "## Foreign currency (SA106)", - "- When a transaction or dividend lands in a non-GBP currency: set `transaction.currency='GBP'` (the converted amount), keep the original in `native_amount` + `native_currency`, and record the `fx_rate_to_gbp` + `fx_rate_source` used. HMRC accepts monthly average rates (gov.uk/government/publications/hmrc-exchange-rates), which is the safe default when you don't have a specific transaction-day rate.", + "- When a transaction or dividend lands in a non-GBP currency: set `transaction.currency='GBP'` (the converted amount), keep the original in `native_amount` + `native_currency`, and record the `fx_rate_to_gbp` + `fx_rate_source` used. HMRC accepts monthly average rates (gov.uk/government/publications/hmrc-exchange-rates) — that's the safe default when you don't have a specific transaction-day rate.", "- Foreign-source income (US dividends, EU rentals, etc.) should also have `income_source.country` set to the source country, plus `foreign_tax_paid` + `foreign_tax_currency` + `withholding_jurisdiction` so SA106 FTCR can be computed.", - "- Treaty rate (e.g. 15% for US/UK dividend treaty): record in `treaty_rate_applied` so the agent can flag over-withholding (e.g. 30% withheld instead of 15%), which is recoverable but not via the SA return.", + "- Treaty rate (e.g. 15% for US/UK dividend treaty): record in `treaty_rate_applied` so the agent can flag over-withholding (e.g. 30% withheld instead of 15%) — that's recoverable but not via the SA return.", "## Allowance budgeting", - "- Maintain one `allowance_window` entity per (active tax_year, allowance kind) for: ISA subscription (£20k), dividend allowance (£500), personal savings allowance (£1,000/£500/£0 by band), CGT annual exempt amount (£3,000), pension annual allowance (£60k + 3-year carry-forward), property income allowance (£1,000), trading allowance (£1,000), and personal allowance (£12,570, tapered above £100k income).", + "- Maintain one `allowance_window` entity per (active tax_year, allowance kind) for: ISA subscription (£20k), dividend allowance (£500), personal savings allowance (£1,000/£500/£0 by band), CGT annual exempt amount (£3,000), pension annual allowance (£60k + 3-year carry-forward), property income allowance (£1,000), trading allowance (£1,000), and personal allowance (£12,570 — tapered above £100k income).", "- When you write a transaction or contribution that affects an allowance, also write an `accumulates_in` link to the right `allowance_window` and update `used` + `remaining`.", - '- "How much ISA budget do I have left?" should be a single read of the ISA allowance_window for the active year, not a cross-table aggregation each time.', + '- "How much ISA budget do I have left?" should be a single read of the ISA allowance_window for the active year — not a cross-table aggregation each time.', "## Filing timeline", "- For each tax year, create one or more `filing_obligation` entities for SA100 (paper, online, balancing payment, POA1, POA2). Use them for proactive reminders.", "- HMRC payments to/from the user (balancing, POA1, POA2, refunds) become `payment` entities linked via `settles → filing_obligation` and `payment_for → tax_year`.", "- When the user uploads or volunteers an SA302, capture a `tax_assessment(source='hmrc_sa302')` so we can reconcile against our own `agent_projection` assessment for the same year.", "## Ingestion paths", - "1. **Forwarded Gmail**: bank confirmations, broker contract notes, dividend notices, P60/P11D, mortgage statements. Watcher `personal-finance.gmail-tx` parses these automatically. Verify gaps and ask the user to forward what's missing.", - "2. **WhatsApp file uploads**: statements, contract notes, P60s. Follow the playbook in `INGESTION.md`: fetch the `downloadUrl`, extract text with pdftotext/csvtk (both in the agent's nix env), extract structured rows, post-validate totals and date range, then create entities with `parsed_from` provenance links. If totals don't reconcile, surface it to the user before committing.", - "3. **Chat**: direct entry. Confirm key fields back to the user before creating an entity.", + "1. **Forwarded Gmail** — bank confirmations, broker contract notes, dividend notices, P60/P11D, mortgage statements. Watcher `personal-finance.gmail-tx` parses these automatically. Verify gaps and ask the user to forward what's missing.", + "2. **WhatsApp file uploads** — statements, contract notes, P60s. Follow the playbook in `INGESTION.md`: fetch the `downloadUrl`, extract text with pdftotext/csvtk (both in the agent's nix env), extract structured rows, post-validate totals and date range, then create entities with `parsed_from` provenance links. If totals don't reconcile, surface it to the user before committing.", + "3. **Chat** — direct entry. Confirm key fields back to the user before creating an entity.", "## SA100 assembly", - "- When the user asks to assemble their return, follow the playbook in `ASSEMBLY.md`; it has the SQL templates (run via `query_sql`), tax-year constants, calculation rules, and the markdown output layout.", + "- When the user asks to assemble their return, follow the playbook in `ASSEMBLY.md` — it has the SQL templates (run via `query_sql`), tax-year constants, calculation rules, and the markdown output layout.", "- Output groups data by SA100 supplementary page (SA102 employment, SA105 UK property, SA108 capital gains, dividends/interest on the main return).", - '- Surface gaps (missing P60, disposal without acquisition cost, etc.) under "⚠️ Gaps to resolve" at the end of the output; never fabricate values.', + '- Surface gaps (missing P60, disposal without acquisition cost, etc.) under "⚠️ Gaps to resolve" at the end of the output — never fabricate values.', "- Personal SA100 only counts data flowing to the *individual* filer: their salaries (transactions on accounts they own), dividends from companies they own (income_source.dividend_from → that company), capital gains on their personal disposals. Data on a company's accounts is reserved for CT600 (later) and does not enter SA100.", "- ⚠️ **Assembly invariant**: never include transactions, expenses or asset disposals from accounts whose `owned_by → company` in SA100 totals. Filter on `account.owner_type = '$member'` (or join through `owned_by` to a `$member` subject) before aggregating. Mixing legs is the most common SA100 vs CT600 contamination bug.", - "- ⚠️ **Shareholding sanity check**: when a company has any `shareholder_of` rows, sum all `shareholding_pct` for that company. If the total is not 100, flag a gap rather than asserting dividend amounts; one of the shareholdings is missing or wrong, and dividend allocation depends on accurate splits.", + "- ⚠️ **Shareholding sanity check**: when a company has any `shareholder_of` rows, sum all `shareholding_pct` for that company. If the total is not 100, flag a gap rather than asserting dividend amounts — one of the shareholdings is missing or wrong, and dividend allocation depends on accurate splits.", "## Privacy and tone", "- The user owns their data. Never reference other users or other workspaces.", - "- Never guess at someone's UTR, NI number, or address; ask.", + "- Never guess at someone's UTR, NI number, or address — ask.", "- Be terse. Money and dates exact. Keep narrative minimal.", ], user: [ @@ -613,14 +865,14 @@ Be specific and cite actual tweets/posts as evidence.`, "- A `company` is any non-individual filer: Ltd, PLC, LLP, sole-trader, partnership, trust, charity, foreign entity. Discriminate with `company_type`.", "- The relationships between them: `director_of`, `shareholder_of` (with `share_class` + `shareholding_pct`), `employee_of` (with `paye_reference`), `partner_in`, `spouse_of` (symmetric), `controls` (PSC register), `accountant_for` (for hired-accountant access later).", "- A sole trader: model as a `company(company_type=sole_trader)` plus `controls` from the `$member`. Their self-employment expenses go via `expense_of → company`. SA103 reports the trade.", - "- `hmrc_utr`: works for both `$member` (SA filer) and `company` (CT filer); 10 digits", - '- `hmrc_ni_number`: `$member` only; e.g. "QQ123456C"', - '- `hmrc_paye_reference`: `company` only; e.g. "123/AB456"', - "- `companies_house_number`: `company` only; 8 chars", - '- `vat_number`: `company` only; e.g. "GB123456789"', + "- `hmrc_utr` — works for both `$member` (SA filer) and `company` (CT filer); 10 digits", + '- `hmrc_ni_number` — `$member` only; e.g. "QQ123456C"', + '- `hmrc_paye_reference` — `company` only; e.g. "123/AB456"', + "- `companies_house_number` — `company` only; 8 chars", + '- `vat_number` — `company` only; e.g. "GB123456789"', "- The UK fiscal year runs 6 April to 5 April. Always anchor activity to the active `tax_year` entity. If none exists for the current year, create it before recording.", "- Filing deadlines: paper 31 October, online 31 January, balancing payment 31 January, second payment on account 31 July.", - "- `tax_year.metadata.residence_status` can change year to year (non-doms moving in/out), so record per year, not on `$member`.", + "- `tax_year.metadata.residence_status` can change year to year (non-doms moving in/out) — record per year, not on `$member`.", "- When the user mentions a transaction, dividend, disposal, contribution, or expense, record it as the appropriate entity (`transaction`, `cgt_event`, `contribution`, `expense`) and link it to the active `tax_year` via `for_tax_year`.", "- For uncertain or fuzzy inputs, prefer `save_memory` (note/observation/decision) on the user's `$member` rather than guessing structured fields.", "- Transactions link to their `account` via `account_contains`; income transactions also link to an `income_source` via `income_from`. The `income_source` then links to its origin: `employed_by → company` for employment, `dividend_from → company` for dividends, `interest_from → account` for interest, `rent_from → property` for rentals.", @@ -628,23 +880,23 @@ Be specific and cite actual tweets/posts as evidence.`, "- For provenance, every entity parsed from a document or email gets a `parsed_from` link to the source `document` entity.", "- Activity inside ISAs is not reportable for income tax or CGT. Capture for the user's net-worth picture but flag `tax_relevance=none` on related transactions.", "- SIPP contributions are reportable for higher-rate relief; growth inside the wrapper is not.", - "- When a transaction or dividend lands in a non-GBP currency: set `transaction.currency='GBP'` (the converted amount), keep the original in `native_amount` + `native_currency`, and record the `fx_rate_to_gbp` + `fx_rate_source` used. HMRC accepts monthly average rates (gov.uk/government/publications/hmrc-exchange-rates), which is the safe default when you don't have a specific transaction-day rate.", + "- When a transaction or dividend lands in a non-GBP currency: set `transaction.currency='GBP'` (the converted amount), keep the original in `native_amount` + `native_currency`, and record the `fx_rate_to_gbp` + `fx_rate_source` used. HMRC accepts monthly average rates (gov.uk/government/publications/hmrc-exchange-rates) — that's the safe default when you don't have a specific transaction-day rate.", "- Foreign-source income (US dividends, EU rentals, etc.) should also have `income_source.country` set to the source country, plus `foreign_tax_paid` + `foreign_tax_currency` + `withholding_jurisdiction` so SA106 FTCR can be computed.", - "- Treaty rate (e.g. 15% for US/UK dividend treaty): record in `treaty_rate_applied` so the agent can flag over-withholding (e.g. 30% withheld instead of 15%), which is recoverable but not via the SA return.", - "- Maintain one `allowance_window` entity per (active tax_year, allowance kind) for: ISA subscription (£20k), dividend allowance (£500), personal savings allowance (£1,000/£500/£0 by band), CGT annual exempt amount (£3,000), pension annual allowance (£60k + 3-year carry-forward), property income allowance (£1,000), trading allowance (£1,000), and personal allowance (£12,570, tapered above £100k income).", + "- Treaty rate (e.g. 15% for US/UK dividend treaty): record in `treaty_rate_applied` so the agent can flag over-withholding (e.g. 30% withheld instead of 15%) — that's recoverable but not via the SA return.", + "- Maintain one `allowance_window` entity per (active tax_year, allowance kind) for: ISA subscription (£20k), dividend allowance (£500), personal savings allowance (£1,000/£500/£0 by band), CGT annual exempt amount (£3,000), pension annual allowance (£60k + 3-year carry-forward), property income allowance (£1,000), trading allowance (£1,000), and personal allowance (£12,570 — tapered above £100k income).", "- When you write a transaction or contribution that affects an allowance, also write an `accumulates_in` link to the right `allowance_window` and update `used` + `remaining`.", - '- "How much ISA budget do I have left?" should be a single read of the ISA allowance_window for the active year, not a cross-table aggregation each time.', + '- "How much ISA budget do I have left?" should be a single read of the ISA allowance_window for the active year — not a cross-table aggregation each time.', "- For each tax year, create one or more `filing_obligation` entities for SA100 (paper, online, balancing payment, POA1, POA2). Use them for proactive reminders.", "- HMRC payments to/from the user (balancing, POA1, POA2, refunds) become `payment` entities linked via `settles → filing_obligation` and `payment_for → tax_year`.", "- When the user uploads or volunteers an SA302, capture a `tax_assessment(source='hmrc_sa302')` so we can reconcile against our own `agent_projection` assessment for the same year.", - "- When the user asks to assemble their return, follow the playbook in `ASSEMBLY.md`; it has the SQL templates (run via `query_sql`), tax-year constants, calculation rules, and the markdown output layout.", + "- When the user asks to assemble their return, follow the playbook in `ASSEMBLY.md` — it has the SQL templates (run via `query_sql`), tax-year constants, calculation rules, and the markdown output layout.", "- Output groups data by SA100 supplementary page (SA102 employment, SA105 UK property, SA108 capital gains, dividends/interest on the main return).", - '- Surface gaps (missing P60, disposal without acquisition cost, etc.) under "⚠️ Gaps to resolve" at the end of the output; never fabricate values.', + '- Surface gaps (missing P60, disposal without acquisition cost, etc.) under "⚠️ Gaps to resolve" at the end of the output — never fabricate values.', "- Personal SA100 only counts data flowing to the *individual* filer: their salaries (transactions on accounts they own), dividends from companies they own (income_source.dividend_from → that company), capital gains on their personal disposals. Data on a company's accounts is reserved for CT600 (later) and does not enter SA100.", "- ⚠️ **Assembly invariant**: never include transactions, expenses or asset disposals from accounts whose `owned_by → company` in SA100 totals. Filter on `account.owner_type = '$member'` (or join through `owned_by` to a `$member` subject) before aggregating. Mixing legs is the most common SA100 vs CT600 contamination bug.", - "- ⚠️ **Shareholding sanity check**: when a company has any `shareholder_of` rows, sum all `shareholding_pct` for that company. If the total is not 100, flag a gap rather than asserting dividend amounts; one of the shareholdings is missing or wrong, and dividend allocation depends on accurate splits.", + "- ⚠️ **Shareholding sanity check**: when a company has any `shareholder_of` rows, sum all `shareholding_pct` for that company. If the total is not 100, flag a gap rather than asserting dividend amounts — one of the shareholdings is missing or wrong, and dividend allocation depends on accurate splits.", "- The user owns their data. Never reference other users or other workspaces.", - "- Never guess at someone's UTR, NI number, or address; ask.", + "- Never guess at someone's UTR, NI number, or address — ask.", "- Be terse. Money and dates exact. Keep narrative minimal.", ], }, @@ -674,10 +926,10 @@ No tax year context provided. Identify and extract financial events. Each email may yield zero, one, or many events. Be conservative: skip noise (marketing, password resets, etc.). Categories to extract: -- **transactions**: deposits, debits, transfers, salary credits, dividend payments hitting an account -- **cgt_events**: broker contract notes for sells/disposals, gifts, transfers out of a GIA -- **dividends**: UK or foreign dividend notifications (gross + currency) -- **documents**: P60/P45/P11D/SA302/contract notes/mortgage statements arriving as attachments or linked PDFs +- **transactions** — deposits, debits, transfers, salary credits, dividend payments hitting an account +- **cgt_events** — broker contract notes for sells/disposals, gifts, transfers out of a GIA +- **dividends** — UK or foreign dividend notifications (gross + currency) +- **documents** — P60/P45/P11D/SA302/contract notes/mortgage statements arriving as attachments or linked PDFs For each item, include the source \`gmail_message_id\` so we can link provenance. Prefer GBP unless the message clearly states a different currency. diff --git a/packages/server/src/gateway/__tests__/core-services-store-selection.test.ts b/packages/server/src/gateway/__tests__/core-services-store-selection.test.ts index 0f2935b9b..fc77384cd 100644 --- a/packages/server/src/gateway/__tests__/core-services-store-selection.test.ts +++ b/packages/server/src/gateway/__tests__/core-services-store-selection.test.ts @@ -137,7 +137,7 @@ describe("CoreServices store selection", () => { (coreServices as any).queue = new MockMessageQueue(); // There is no default sub-store; if the host doesn't provide - // config/connection/access stores AND no lobu.toml is present, + // config/connection/access stores AND no lobu.config.ts is present, // initializeSessionServices throws. await expect( (coreServices as any).initializeSessionServices() diff --git a/packages/server/src/gateway/auth/mcp/config-service.ts b/packages/server/src/gateway/auth/mcp/config-service.ts index 036e712b5..633aa9682 100644 --- a/packages/server/src/gateway/auth/mcp/config-service.ts +++ b/packages/server/src/gateway/auth/mcp/config-service.ts @@ -28,7 +28,7 @@ interface HttpMcpServerConfig { * - "channel": credential is shared across all users in a conversation/channel * (keyed by channelId). For shared-data integrations where per-user identity * isn't required. Must be explicitly opted in via `auth_scope = "channel"` - * in lobu.toml. + * in lobu.config.ts. */ authScope?: "user" | "channel"; /** diff --git a/packages/server/src/gateway/auth/mcp/oauth-discovery.ts b/packages/server/src/gateway/auth/mcp/oauth-discovery.ts index de0732c5d..4d76c553c 100644 --- a/packages/server/src/gateway/auth/mcp/oauth-discovery.ts +++ b/packages/server/src/gateway/auth/mcp/oauth-discovery.ts @@ -317,7 +317,7 @@ interface DiscoverOptions { redirectUri: string; secretStore: WritableSecretStore; /** - * Pre-registered static client from lobu.toml. Short-circuits dynamic + * Pre-registered static client from lobu.config.ts. Short-circuits dynamic * registration when present. */ staticClientId?: string; diff --git a/packages/server/src/gateway/auth/provider-catalog.ts b/packages/server/src/gateway/auth/provider-catalog.ts index d0c7548f4..f5ad91169 100644 --- a/packages/server/src/gateway/auth/provider-catalog.ts +++ b/packages/server/src/gateway/auth/provider-catalog.ts @@ -29,7 +29,7 @@ async function resolveInstalledProviders( * but each agent chooses which providers to install from the catalog. */ const DECLARED_AGENT_MUTATION_ERROR = - "provider list is declared in lobu.toml; edit the file and restart"; + "provider list is declared in lobu.config.ts; edit the file and restart"; export class ProviderCatalogService { constructor( diff --git a/packages/server/src/gateway/auth/settings/auth-profiles-manager.ts b/packages/server/src/gateway/auth/settings/auth-profiles-manager.ts index 05c597bec..e7e061a09 100644 --- a/packages/server/src/gateway/auth/settings/auth-profiles-manager.ts +++ b/packages/server/src/gateway/auth/settings/auth-profiles-manager.ts @@ -79,7 +79,7 @@ interface AuthProfilesManagerOptions { * 2. **User-scoped profiles** — durable per-user profiles keyed by * `(userId, agentId)` in `UserAuthProfileStore`. * 3. **Declared credentials** — read-only credentials shipped with the - * agent's declared config (lobu.toml / SDK GatewayConfig.agents), + * agent's declared config (lobu.config.ts / SDK GatewayConfig.agents), * surfaced via `DeclaredAgentRegistry`. * * Callers pass `ProviderCredentialContext.userId` when they have one diff --git a/packages/server/src/gateway/guardrails/aggregator.ts b/packages/server/src/gateway/guardrails/aggregator.ts index 2a2407460..824e9b241 100644 --- a/packages/server/src/gateway/guardrails/aggregator.ts +++ b/packages/server/src/gateway/guardrails/aggregator.ts @@ -15,7 +15,7 @@ import { const logger = createLogger("guardrail-aggregator"); /** - * Inline guardrail entry declared by the agent in lobu.toml (see + * Inline guardrail entry declared by the agent in lobu.config.ts (see * `guardrails_inline` in the agent config). We accept the parsed shape * here so callers can pass either the toml-parsed entries or the in-memory * agent representation. diff --git a/packages/server/src/gateway/orchestration/base-deployment-manager.ts b/packages/server/src/gateway/orchestration/base-deployment-manager.ts index 2ab004ead..17cb93010 100644 --- a/packages/server/src/gateway/orchestration/base-deployment-manager.ts +++ b/packages/server/src/gateway/orchestration/base-deployment-manager.ts @@ -524,7 +524,7 @@ export abstract class BaseDeploymentManager { * - patterns in the new set but not the previous are `grant()`-ed * - patterns in the previous set but not the new are `revoke()`-d * This means clearing `networkConfig.allowedDomains` or - * `preApprovedTools` in lobu.toml actually drops access, instead of + * `preApprovedTools` in lobu.config.ts actually drops access, instead of * leaving stale grants in the store. */ async syncNetworkConfigGrants(messageData: MessagePayload): Promise { diff --git a/packages/server/src/gateway/proxy/http-proxy.ts b/packages/server/src/gateway/proxy/http-proxy.ts index f2d4648b3..3e6df12b8 100644 --- a/packages/server/src/gateway/proxy/http-proxy.ts +++ b/packages/server/src/gateway/proxy/http-proxy.ts @@ -788,7 +788,7 @@ async function handleConnect( ); try { clientSocket.write( - `HTTP/1.1 403 ${escapeHeaderValue(reason)}\r\nContent-Type: text/plain\r\n\r\n403 Forbidden - ${reason}. Network access is configured via lobu.toml, skill configs, or the gateway configuration APIs.\r\n` + `HTTP/1.1 403 ${escapeHeaderValue(reason)}\r\nContent-Type: text/plain\r\n\r\n403 Forbidden - ${reason}. Network access is configured via lobu.config.ts, skill configs, or the gateway configuration APIs.\r\n` ); clientSocket.end(); } catch { @@ -938,7 +938,7 @@ async function handleProxyRequest( "Content-Type": "text/plain", }); res.end( - `403 Forbidden - ${reason}. Network access is configured via lobu.toml, skill configs, or the gateway configuration APIs.\n` + `403 Forbidden - ${reason}. Network access is configured via lobu.config.ts, skill configs, or the gateway configuration APIs.\n` ); return; } diff --git a/packages/server/src/gateway/services/core-services.ts b/packages/server/src/gateway/services/core-services.ts index bf66bec36..e9a234627 100644 --- a/packages/server/src/gateway/services/core-services.ts +++ b/packages/server/src/gateway/services/core-services.ts @@ -185,7 +185,7 @@ export class CoreServices { private connectionStore?: AgentConnectionStore; private accessStore?: AgentAccessStore; - // SDK-embedded agents (passed via `GatewayConfig.agents`). lobu.toml + // SDK-embedded agents (passed via `GatewayConfig.agents`). lobu.config.ts // file-declared agents have been moved out of the gateway boot path — // they enter Postgres via `lobu apply`. private configAgents: AgentConfig[] = []; @@ -405,7 +405,7 @@ export class CoreServices { ); } else { throw new Error( - "No agent sub-stores configured: provide configStore/connectionStore/accessStore via CoreServices options, or pass agents via GatewayConfig.agents. (lobu.toml is no longer read at gateway boot — push agents with `lobu apply`.)" + "No agent sub-stores configured: provide configStore/connectionStore/accessStore via CoreServices options, or pass agents via GatewayConfig.agents. (lobu.config.ts is no longer read at gateway boot — push agents with `lobu apply`.)" ); } } else { diff --git a/packages/server/src/gateway/services/declared-agent-registry.ts b/packages/server/src/gateway/services/declared-agent-registry.ts index 051ee152f..4a8837db6 100644 --- a/packages/server/src/gateway/services/declared-agent-registry.ts +++ b/packages/server/src/gateway/services/declared-agent-registry.ts @@ -13,7 +13,7 @@ interface DeclaredAgentEntry { * In-memory registry of agents declared by `GatewayConfig.agents` when the * gateway is embedded as a library (SDK-mode). * - * `lobu.toml` is no longer read at gateway boot — file-declared agents + * `lobu.config.ts` is no longer read at gateway boot — file-declared agents * enter Postgres via `lobu apply` and are read through `AgentConfigStore`. * * Declared agents own their settings and credentials at runtime — there is diff --git a/packages/server/src/gateway/services/instruction-service.ts b/packages/server/src/gateway/services/instruction-service.ts index 5c6f18dd4..453b52971 100644 --- a/packages/server/src/gateway/services/instruction-service.ts +++ b/packages/server/src/gateway/services/instruction-service.ts @@ -163,7 +163,7 @@ You can access any external service without restrictions.`; **Internet Access:** Complete isolation (no external access) -You do NOT have access to the internet. All external requests (curl, wget, npm, pip, etc.) will fail. Network access is configured via lobu.toml or the gateway configuration APIs. Only local operations and MCP tools are available.`; +You do NOT have access to the internet. All external requests (curl, wget, npm, pip, etc.) will fail. Network access is configured via lobu.config.ts or the gateway configuration APIs. Only local operations and MCP tools are available.`; } // Allowlist mode @@ -194,7 +194,7 @@ ${blockedList}`; instructions += ` -You can only access the allowed domains listed above. All other external requests will be blocked by the proxy. Network access is configured via lobu.toml or the gateway configuration APIs. Plan your work accordingly and use available MCP tools when possible.`; +You can only access the allowed domains listed above. All other external requests will be blocked by the proxy. Network access is configured via lobu.config.ts or the gateway configuration APIs. Plan your work accordingly and use available MCP tools when possible.`; return instructions; } diff --git a/packages/server/src/lobu/stores/__tests__/postgres-agent-config-store.test.ts b/packages/server/src/lobu/stores/__tests__/postgres-agent-config-store.test.ts index f5e31269b..cbdfdbea6 100644 --- a/packages/server/src/lobu/stores/__tests__/postgres-agent-config-store.test.ts +++ b/packages/server/src/lobu/stores/__tests__/postgres-agent-config-store.test.ts @@ -2,7 +2,7 @@ * PostgresAgentConfigStore round-trip tests. * * Pins the persistence of three settings fields the file-loader produces from - * lobu.toml — egressConfig, preApprovedTools, guardrails — that previously + * lobu.config.ts — egressConfig, preApprovedTools, guardrails — that previously * had no columns in the agents table and were silently dropped on every * saveSettings(). PR-1 of `docs/plans/lobu-apply.md`. */ diff --git a/scripts/dev-native.sh b/scripts/dev-native.sh index afc940470..dde2c3ebf 100755 --- a/scripts/dev-native.sh +++ b/scripts/dev-native.sh @@ -142,7 +142,7 @@ if [ -z "${DATABASE_URL:-}" ]; then echo "→ server on http://${HOST}:${PORT} (Vite HMR in-process)" echo "→ data dir: $DEV_DATA_ROOT/.lobu/pgdata" echo "→ first run seeds a web login: dev@lobu.local / lobudev123 (org 'dev')" - echo "→ then run \`lobu apply\` from a project dir to sync its lobu.toml" + echo "→ then run \`lobu apply\` from a project dir to sync its lobu.config.ts" echo "" exec bun run --filter '@lobu/server' dev:local fi diff --git a/scripts/e2e-lobu-apply.sh b/scripts/e2e-lobu-apply.sh deleted file mode 100755 index d59035b71..000000000 --- a/scripts/e2e-lobu-apply.sh +++ /dev/null @@ -1,312 +0,0 @@ -#!/usr/bin/env bash -# -# End-to-end harness for `lobu apply` v1. -# -# Boots the embedded server (auto-bootstraps an admin PAT on empty data dir), -# drives the CLI through create → noop → update → drift, and asserts the -# round-trip against the local embedded Postgres. -# -# Idempotent: cleans up its own server, data dir, and project dir on exit. - -set -euo pipefail - -# ─── locations ───────────────────────────────────────────────────────── -REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -DATA_DIR="/tmp/e2e-data" -PROJECT_DIR="/tmp/e2e-project" -SERVER_LOG="/tmp/e2e-server.log" -PORT=8801 -SERVER_URL="http://localhost:${PORT}" -API_URL="${SERVER_URL}" -ORG_SLUG="dev" -SERVER_PID="" - -cleanup() { - local exit_code=$? - if [[ -n "${SERVER_PID}" ]] && kill -0 "${SERVER_PID}" 2>/dev/null; then - echo "==> cleanup: killing server pid ${SERVER_PID}" - kill "${SERVER_PID}" 2>/dev/null || true - # Give it a moment, then SIGKILL if still alive. - for _ in 1 2 3 4 5; do - kill -0 "${SERVER_PID}" 2>/dev/null || break - sleep 0.5 - done - kill -9 "${SERVER_PID}" 2>/dev/null || true - fi - rm -rf "${DATA_DIR}" "${PROJECT_DIR}" 2>/dev/null || true - if [[ ${exit_code} -ne 0 ]]; then - echo "==> e2e FAILED (exit ${exit_code})" - if [[ -f "${SERVER_LOG}" ]]; then - echo "── server log (last 80 lines) ───────────────────────────────" - tail -n 80 "${SERVER_LOG}" || true - echo "─────────────────────────────────────────────────────────────" - fi - fi - exit "${exit_code}" -} -trap cleanup EXIT INT TERM - -# ─── pre-flight ──────────────────────────────────────────────────────── -rm -rf "${DATA_DIR}" "${PROJECT_DIR}" "${SERVER_LOG}" -# Stale local build that the dev workflow occasionally produces. -rm -rf "${REPO_ROOT}/packages/lobu-cli/runtime" 2>/dev/null || true - -# ─── 1. build ────────────────────────────────────────────────────────── -echo "==> step 1: build packages + CLI" -cd "${REPO_ROOT}" -make build-packages >/dev/null -(cd packages/cli && bun run build) >/dev/null - -CLI_BIN="${REPO_ROOT}/packages/cli/bin/lobu.js" -if [[ ! -f "${CLI_BIN}" ]]; then - echo "CLI binary not found at ${CLI_BIN}" >&2 - exit 1 -fi -LOBU="node ${CLI_BIN}" - -# ─── 2. start server ─────────────────────────────────────────────────── -echo "==> step 2: start the embedded server on :${PORT}" - -# DATABASE_URL=file:// → server.ts boots an embedded Postgres rooted there -# (cluster at /.lobu/pgdata) and rewrites DATABASE_URL to the TCP URL. -env \ - DATABASE_URL="file://${DATA_DIR}" \ - PORT="${PORT}" \ - HOST=127.0.0.1 \ - bun run "${REPO_ROOT}/packages/server/src/server.ts" \ - >"${SERVER_LOG}" 2>&1 & -SERVER_PID=$! - -echo " server pid=${SERVER_PID} log=${SERVER_LOG}" - -# Wait for /health. -for i in $(seq 1 60); do - if curl -sf "${SERVER_URL}/health" >/dev/null 2>&1; then - echo " server up after ${i}s" - break - fi - if ! kill -0 "${SERVER_PID}" 2>/dev/null; then - echo "server died before becoming ready" >&2 - exit 1 - fi - sleep 1 - if [[ $i -eq 60 ]]; then - echo "server did not become ready within 60s" >&2 - exit 1 - fi -done - -# ─── 3. read bootstrap PAT ───────────────────────────────────────────── -echo "==> step 3: read bootstrap PAT" - -# Wait briefly for the bootstrap path (runs after listen) to write the file. -PAT_FILE="${DATA_DIR}/bootstrap-pat.txt" -for i in $(seq 1 20); do - if [[ -s "${PAT_FILE}" ]]; then break; fi - sleep 0.5 -done - -if [[ ! -s "${PAT_FILE}" ]]; then - echo "bootstrap PAT not written to ${PAT_FILE}" >&2 - exit 1 -fi -PAT="$(cat "${PAT_FILE}")" -PAT="${PAT//$'\n'/}" -if [[ -z "${PAT}" || "${PAT}" != owl_pat_* ]]; then - echo "bootstrap PAT looks malformed: ${PAT}" >&2 - exit 1 -fi -echo " PAT prefix: ${PAT:0:16}..." - -# ─── 4. write sample project ─────────────────────────────────────────── -echo "==> step 4: write sample lobu.toml + agent dir + models" -mkdir -p "${PROJECT_DIR}/agents/triage" "${PROJECT_DIR}/models" - -cat > "${PROJECT_DIR}/lobu.toml" <<'TOML' -[agents.triage] -name = "Triage" -description = "Test triage agent for e2e harness" -dir = "./agents/triage" - -[[agents.triage.providers]] -id = "anthropic" -model = "claude/sonnet-4-5" -key = "$ANTHROPIC_API_KEY" - -[[agents.triage.platforms]] -type = "telegram" -config = { botToken = "$TELEGRAM_BOT_TOKEN", chatId = "12345" } - -[memory] -enabled = true -org = "dev" -name = "Local Dev" -description = "Local dev memory" -models = "./models" -TOML - -cat > "${PROJECT_DIR}/agents/triage/IDENTITY.md" <<'MD' -# Identity - -You are a triage agent under e2e test. -MD - -cat > "${PROJECT_DIR}/agents/triage/SOUL.md" <<'MD' -# Instructions - -- Be concise. -MD - -cat > "${PROJECT_DIR}/agents/triage/USER.md" <<'MD' -# User Context - -- e2e harness driver -MD - -cat > "${PROJECT_DIR}/models/schema.yaml" <<'YAML' -version: 2 -entities: - - slug: person - name: Person - description: Test person entity for e2e - metadata_schema: - type: object - properties: - full_name: - type: string -YAML - -# ─── 5. configure CLI context + login ────────────────────────────────── -echo "==> step 5: configure CLI context + login with PAT" - -# CLI config dir scoped to the test so we don't clobber the user's profile. -CLI_HOME="$(mktemp -d /tmp/e2e-clihome.XXXX)" -export HOME="${CLI_HOME}" -mkdir -p "${HOME}/.config/lobu" - -# Add a context pointing at our local server, then mark it current. -${LOBU} context add e2e --url "${API_URL}" >/dev/null -${LOBU} context use e2e >/dev/null - -# `lobu login --token ` saves the PAT verbatim (no OAuth round-trip). -LOGIN_OUT="$(${LOBU} login --token "${PAT}" --context e2e --force 2>&1 || true)" -echo "${LOGIN_OUT}" | sed 's/^/ /' - -# Confirm credentials landed. -if ! grep -q "${PAT}" "${HOME}/.config/lobu/credentials.json" 2>/dev/null; then - echo "credentials.json did not get the PAT" >&2 - echo " HOME=${HOME}" - ls -la "${HOME}/.config/lobu/" 2>&1 | sed 's/^/ /' || true - cat "${HOME}/.config/lobu/credentials.json" 2>&1 | sed 's/^/ /' || true - exit 1 -fi - -# Apply also looks at LOBU_API_TOKEN as a fast path; rely on it to dodge -# any context-resolution surprises in CI. -export LOBU_API_TOKEN="${PAT}" -export LOBU_CONTEXT=e2e -export LOBU_MEMORY_URL="${SERVER_URL}/mcp" - -# ─── 6. fake secrets ─────────────────────────────────────────────────── -export TELEGRAM_BOT_TOKEN="fake-tg-token-for-e2e" -export ANTHROPIC_API_KEY="fake-anth-key-for-e2e" - -# ─── 7. dry-run ──────────────────────────────────────────────────────── -echo "==> step 7: lobu apply --dry-run (expect creates)" -cd "${PROJECT_DIR}" -DRY_OUT="$(${LOBU} apply --dry-run --org "${ORG_SLUG}" --url "${SERVER_URL}" 2>&1)" -echo "${DRY_OUT}" | sed 's/^/ /' - -# Assertions on dry-run output: at least one `+` per resource kind. -echo "${DRY_OUT}" | grep -E "\+\s+agent\s+triage" >/dev/null || { - echo "dry-run missing '+ agent triage' line" >&2 - exit 1 -} -echo "${DRY_OUT}" | grep -E "\+\s+platform" >/dev/null || { - echo "dry-run missing '+ platform' line" >&2 - exit 1 -} -echo "${DRY_OUT}" | grep -E "\+\s+entity[-_]type" >/dev/null || { - echo "dry-run missing '+ entity-type' line" >&2 - exit 1 -} - -# ─── 8. apply --yes ──────────────────────────────────────────────────── -echo "==> step 8: lobu apply --yes (expect success)" -APPLY_OUT="$(${LOBU} apply --yes --org "${ORG_SLUG}" --url "${SERVER_URL}" 2>&1)" -echo "${APPLY_OUT}" | sed 's/^/ /' -echo "${APPLY_OUT}" | grep -E "Apply complete" >/dev/null || { - echo "apply did not report completion" >&2 - exit 1 -} - -# ─── 9. dry-run again — all noop ─────────────────────────────────────── -echo "==> step 9: lobu apply --dry-run (expect noop)" -NOOP_OUT="$(${LOBU} apply --dry-run --org "${ORG_SLUG}" --url "${SERVER_URL}" 2>&1)" -echo "${NOOP_OUT}" | sed 's/^/ /' -if echo "${NOOP_OUT}" | grep -E "^\s*\+\s+(agent|platform|entity)" >/dev/null; then - echo "second dry-run still shows + creates — not idempotent" >&2 - exit 1 -fi -if echo "${NOOP_OUT}" | grep -E "^\s*~\s+(agent|platform|entity)" >/dev/null; then - echo "second dry-run shows ~ updates — drift detected unexpectedly" >&2 - exit 1 -fi - -# ─── 10. mutate platform chatId, expect ~ update ────────────────────── -echo "==> step 10: edit platform chatId, expect platform update + restart" - -# Same shape, different chatId. -sed -i.bak \ - -e 's/chatId = "12345"/chatId = "67890"/' \ - "${PROJECT_DIR}/lobu.toml" -rm -f "${PROJECT_DIR}/lobu.toml.bak" - -UPDATE_OUT="$(${LOBU} apply --dry-run --org "${ORG_SLUG}" --url "${SERVER_URL}" 2>&1)" -echo "${UPDATE_OUT}" | sed 's/^/ /' -echo "${UPDATE_OUT}" | grep -E "~\s+platform" >/dev/null || { - echo "expected '~ platform' line after edit" >&2 - exit 1 -} -echo "${UPDATE_OUT}" | grep -E "will restart" >/dev/null || { - echo "expected 'will restart' marker after platform config change" >&2 - exit 1 -} - -APPLY_UPDATE_OUT="$(${LOBU} apply --yes --org "${ORG_SLUG}" --url "${SERVER_URL}" 2>&1)" -echo "${APPLY_UPDATE_OUT}" | sed 's/^/ /' -echo "${APPLY_UPDATE_OUT}" | grep -E "Apply complete" >/dev/null || { - echo "update apply did not complete" >&2 - exit 1 -} - -# ─── 11. verify rows landed in PG ────────────────────────────────────── -echo "==> step 11: verify rows in PG via REST" - -AGENTS_JSON="$(curl -sf -H "Authorization: Bearer ${PAT}" "${SERVER_URL}/api/${ORG_SLUG}/agents")" -echo "${AGENTS_JSON}" | grep -q '"agentId":"triage"' || { - echo "triage agent not found via /api/${ORG_SLUG}/agents" >&2 - echo "${AGENTS_JSON}" - exit 1 -} - -PLATFORMS_JSON="$(curl -sf -H "Authorization: Bearer ${PAT}" "${SERVER_URL}/api/${ORG_SLUG}/agents/triage/platforms")" -echo "${PLATFORMS_JSON}" | grep -q '"platform":"telegram"' || { - echo "telegram platform not found" >&2 - echo "${PLATFORMS_JSON}" - exit 1 -} - -ENTITY_JSON="$(curl -sf -X POST \ - -H "Authorization: Bearer ${PAT}" \ - -H "Content-Type: application/json" \ - -d '{"schema_type":"entity_type","action":"list"}' \ - "${SERVER_URL}/api/${ORG_SLUG}/manage_entity_schema")" -echo "${ENTITY_JSON}" | grep -q '"slug":"person"' || { - echo "person entity_type not found" >&2 - echo "${ENTITY_JSON}" - exit 1 -} - -# ─── 12. cleanup handled by trap ─────────────────────────────────────── -echo "==> step 12: e2e PASSED" diff --git a/scripts/gen-use-case-data.ts b/scripts/gen-use-case-data.ts index 57f832ab5..7deec3b6b 100644 --- a/scripts/gen-use-case-data.ts +++ b/scripts/gen-use-case-data.ts @@ -3,6 +3,13 @@ * Reads all examples/ directories and generates * packages/landing/src/generated/use-case-models.ts * + * Each example ships a `lobu.config.ts` (a `defineConfig(...)` default export + * from `@lobu/sdk`). We load it the same way the CLI does — via jiti, the + * runtime TypeScript loader (see + * `packages/cli/src/commands/_lib/apply/desired-state.ts` `loadProjectConfig`) + * — and project the SDK `Project` shape down to the minimal model the landing + * use-case page consumes. + * * Run: bun scripts/gen-use-case-data.ts */ @@ -15,8 +22,9 @@ import { writeFileSync, } from "node:fs"; import { join, resolve } from "node:path"; -import { parse as parseToml } from "smol-toml"; -import { parse as parseYaml } from "yaml"; +import { pathToFileURL } from "node:url"; +import type { Project, ProviderConfig, Watcher } from "@lobu/sdk"; +import { isSecretRef } from "@lobu/sdk"; const ROOT = resolve(import.meta.dir, ".."); const EXAMPLES_DIR = join(ROOT, "examples"); @@ -25,7 +33,35 @@ const OUTPUT_PATH = join( "packages/landing/src/generated/use-case-models.ts" ); -// ── Helpers ────────────────────────────────────────────────────────── +// ── Config loading ─────────────────────────────────────────────────── + +/** + * Import an example's `lobu.config.ts` and return its `defineConfig` default + * export. Mirrors `loadProjectConfig` in the CLI: jiti transpiles the config on + * import and resolves its `@lobu/sdk` import from the monorepo. Returns null + * when the example has no config (skipped, not an error). + */ +async function loadExampleConfig(exampleDir: string): Promise { + const configPath = join(exampleDir, "lobu.config.ts"); + if (!existsSync(configPath)) return null; + + const { createJiti } = await import("jiti"); + const jiti = createJiti(pathToFileURL(configPath).href); + const project = (await jiti.import(configPath, { default: true })) as unknown; + + if ( + !project || + typeof project !== "object" || + (project as { kind?: unknown }).kind !== "project" + ) { + throw new Error( + `${configPath} must \`export default defineConfig({ ... })\`` + ); + } + return project as Project; +} + +// ── Markdown reading ───────────────────────────────────────────────── function readLines(filePath: string, skipHeaders: string[]): string[] { if (!existsSync(filePath)) return []; @@ -40,72 +76,26 @@ function readLines(filePath: string, skipHeaders: string[]): string[] { }); } -function readYamlFile>(filePath: string): T | null { - if (!existsSync(filePath)) return null; - return parseYaml(readFileSync(filePath, "utf-8")) as T; -} - -function readYamlDir>(dirPath: string): T[] { - if (!existsSync(dirPath)) return []; - return readdirSync(dirPath) - .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")) - .sort() - .map((f) => readYamlFile(join(dirPath, f))!) - .filter(Boolean); -} +// ── Field extraction ───────────────────────────────────────────────── -interface ExampleLobuLayout { - org: string; - modelsPath: string; +/** Resolve a provider key (`secret("X")` ref or literal `$X`/`X`) to its env name. */ +function envNameFromKey(key: ProviderConfig["key"]): string { + if (key == null) return ""; + if (isSecretRef(key)) return key.$secret; + if (typeof key === "string") return key.replace(/^\$/, ""); + return ""; } -function resolveLobuLayout(exampleDir: string): ExampleLobuLayout | null { - const tomlPath = join(exampleDir, "lobu.toml"); - if (!existsSync(tomlPath)) return null; - - const toml = parseToml(readFileSync(tomlPath, "utf-8")) as { - memory?: { enabled?: boolean; org?: string; models?: string }; +function buildWatcher(watcher: Watcher | undefined) { + if (!watcher) return undefined; + return { + name: watcher.name ?? watcher.slug, + schedule: watcher.schedule ?? "", + prompt: watcher.prompt.trim(), + extractionSchema: watcher.extractionSchema + ? JSON.stringify(watcher.extractionSchema) + : "", }; - const memory = toml.memory; - if (!memory || memory.enabled === false) return null; - const org = memory.org?.trim(); - if (!org) return null; - - const modelsRel = memory.models?.trim() || "./models"; - const modelsPath = resolve(exampleDir, modelsRel); - return { org, modelsPath }; -} - -// ── Types — minimal subset of the Lobu schema ───────────────────── - -// We previously type-imported `EntitySchema`/`WatcherSchema` from a sibling -// `../../lobu` checkout. That path doesn't exist on most machines (fresh -// clones, CI), so the script wouldn't typecheck. Inline only the fields this -// script actually reads — keeps the script self-contained without making the -// whole monorepo depend on a sibling repo. -interface EntityYaml { - type: "entity"; - name: string; -} - -interface WatcherYaml { - type: "watcher"; - name: string; - schedule: string; - prompt: string; - extraction_schema?: unknown; -} - -// ── TOML types ─────────────────────────────────────────────────────── - -interface TomlAgent { - name: string; - description?: string; - dir?: string; - providers?: Array<{ id: string; model: string; key: string }>; - skills?: { enabled?: string[] }; - network?: { allowed?: string[] }; - worker?: { nix_packages?: string[] }; } // ── Build one use case ─────────────────────────────────────────────── @@ -138,75 +128,36 @@ interface UseCaseModel { }; } -function buildModel(exampleName: string): UseCaseModel | null { +async function buildModel(exampleName: string): Promise { const exampleDir = join(EXAMPLES_DIR, exampleName); - const layout = resolveLobuLayout(exampleDir); - if (!layout) return null; + const project = await loadExampleConfig(exampleDir); + if (!project) return null; - const lobuOrg = layout.org; + const lobuOrg = project.org?.trim(); + if (!lobuOrg) return null; - type AnyModel = EntityYaml | WatcherYaml; - const allModels = readYamlDir(layout.modelsPath); - const entities = allModels.filter( - (m): m is EntityYaml => (m as Record).type === "entity" - ); - const entityNames = entities.map((e) => e.name); - const watchers = allModels.filter( - (m): m is WatcherYaml => (m as Record).type === "watcher" - ); - const firstWatcher = watchers[0]; - const watcher = firstWatcher - ? { - name: firstWatcher.name, - schedule: firstWatcher.schedule, - prompt: firstWatcher.prompt.trim(), - extractionSchema: firstWatcher.extraction_schema - ? JSON.stringify(firstWatcher.extraction_schema) - : "", - } - : undefined; - - const tomlPath = join(exampleDir, "lobu.toml"); - let agentId = exampleName; - let description = ""; - let enabledSkills: string[] = []; - let allowedDomains: string[] = []; - let nixPackages: string[] = []; - let providerId = ""; - let model = ""; - let apiKeyEnv = ""; - let agentDirRel = ""; - - if (existsSync(tomlPath)) { - const tomlRaw = readFileSync(tomlPath, "utf-8"); - const toml = parseToml(tomlRaw) as { agents?: Record }; - - if (toml.agents) { - const firstKey = Object.keys(toml.agents)[0]; - const agent = toml.agents[firstKey]; - agentId = firstKey; - description = agent.description || ""; - - if (agent.dir) { - agentDirRel = agent.dir.replace(/^\.\//, ""); - } - - if (agent.providers && agent.providers.length > 0) { - const prov = agent.providers[0]; - providerId = prov.id; - model = prov.model; - apiKeyEnv = prov.key.replace(/^\$/, ""); - } - - enabledSkills = agent.skills?.enabled || []; - allowedDomains = agent.network?.allowed || []; - nixPackages = agent.worker?.nix_packages || []; - } - } + const entityNames = (project.entities ?? []).map((e) => e.name ?? e.key); + const watcher = buildWatcher(project.watchers?.[0]); + + const agent = project.agents[0]; + const agentId = agent?.id ?? exampleName; + const description = agent?.description ?? ""; - const agentMdDir = agentDirRel - ? join(exampleDir, agentDirRel) - : join(exampleDir, "agents", exampleName); + const provider = agent?.providers?.[0]; + const providerId = provider?.id ?? ""; + const model = provider?.model ?? ""; + const apiKeyEnv = envNameFromKey(provider?.key); + + const allowedDomains = agent?.network?.allowed ?? []; + const nixPackages = agent?.nixPackages ?? []; + + // Agent directory holding SOUL/IDENTITY/USER.md — `dir` or `./agents/`, + // matching the CLI loader (desired-state.ts loadDesiredStateFromConfig). + const agentDirRel = (agent?.dir ?? join("agents", agentId)).replace( + /^\.\//, + "" + ); + const agentMdDir = join(exampleDir, agentDirRel); const identity = readLines(join(agentMdDir, "IDENTITY.md"), ["# Identity"]); const soul = readLines(join(agentMdDir, "SOUL.md"), [ @@ -216,7 +167,6 @@ function buildModel(exampleName: string): UseCaseModel | null { const user = readLines(join(agentMdDir, "USER.md"), ["# User Context"]); const skillInstructions = soul.filter((l) => l.trim().startsWith("- ")); - const mcpServer = enabledSkills.length > 0 ? enabledSkills[0] : ""; return { id: exampleName, @@ -227,10 +177,13 @@ function buildModel(exampleName: string): UseCaseModel | null { agentId, skillId: agentId, description, - skills: enabledSkills, + // The SDK config declares MCP/local skills via the agent dir + mcpServers, + // not a flat enabled-skills list; the landing page only renders an empty + // skills list today, so leave these unset. + skills: [], nixPackages, allowedDomains, - mcpServer, + mcpServer: "", providerId, model, apiKeyEnv, @@ -242,16 +195,16 @@ function buildModel(exampleName: string): UseCaseModel | null { // ── Main ───────────────────────────────────────────────────────────── -const exampleDirs = readdirSync(EXAMPLES_DIR, { withFileTypes: true }) +const exampleNames = readdirSync(EXAMPLES_DIR, { withFileTypes: true }) .filter((d) => d.isDirectory()) .map((d) => d.name) - .filter((name) => resolveLobuLayout(join(EXAMPLES_DIR, name)) !== null) + .filter((name) => existsSync(join(EXAMPLES_DIR, name, "lobu.config.ts"))) .sort(); const models: Record = {}; -for (const name of exampleDirs) { - const m = buildModel(name); +for (const name of exampleNames) { + const m = await buildModel(name); if (m) { models[name] = m; } From c751a9b47840a71b43455d40c953cd210cd4f1b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 04:31:19 +0100 Subject: [PATCH 33/65] chore: drop dead smol-toml direct dependency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nothing imports smol-toml anymore — its only direct user was gen-use-case-data.ts, now rewritten to load lobu.config.ts via jiti. It remains in the lockfile as a transitive dep of astro/just-bash/knip (unchanged). Removes the root dependency only; bun.lock diff is one line, owletto submodule intact, frozen-lockfile passes. --- bun.lock | 1 - package.json | 1 - 2 files changed, 2 deletions(-) diff --git a/bun.lock b/bun.lock index dd3a602e9..c0989a94b 100644 --- a/bun.lock +++ b/bun.lock @@ -11,7 +11,6 @@ "husky": "^9.1.7", "jscpd": "^4.0.5", "knip": "^5.66.3", - "smol-toml": "^1.3.1", "typescript": "^5.8.3", }, }, diff --git a/package.json b/package.json index 6fc2a16e5..568fd228e 100644 --- a/package.json +++ b/package.json @@ -43,7 +43,6 @@ "husky": "^9.1.7", "jscpd": "^4.0.5", "knip": "^5.66.3", - "smol-toml": "^1.3.1", "typescript": "^5.8.3" }, "engines": { From 470fd539a8ed4a180f0fa734206261b823c67b22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 04:42:44 +0100 Subject: [PATCH 34/65] fix(apply): defer code-managed flip until after plan confirmation; static jiti import pi-review findings: - apply-cmd: setOrgManagedBy flipped the org to code-managed BEFORE the plan was rendered/confirmed, so cancelling a --manage apply left the org flipped. Now the plan is computed as code-managed (prune shown), but the server-side flip runs only after confirmPlan + the blast-radius confirmDeletions pass (flipToCodeManaged), right before executePlan; dry-run never flips. - gen-use-case-data.ts: replaced the lazy await import("jiti") (a dynamic import not on the AGENTS.md allow-list) with a static top-level import. It's a build-time script, so the static import is strictly correct. --- .../cli/src/commands/_lib/apply/apply-cmd.ts | 47 +++++++++++-------- scripts/gen-use-case-data.ts | 2 +- 2 files changed, 29 insertions(+), 20 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index 571410f03..3c829c132 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -1126,26 +1126,29 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { // A code-managed org's lobu.config.ts owns its definitions, so apply prunes // the ones removed from it (data/connections/agents are never pruned). - // `--manage` is the one-time opt-in flipping ui→code server-side; older - // servers omit `managed_by` → stays UI-managed (safe, no prune). - let codeManaged = resolvedOrg?.managed_by === "code"; - if (opts.manage && resolvedOrg && !codeManaged) { - if (opts.dryRun) { - printText( - chalk.dim( - `(dry-run) Org "${orgSlug}" would become code-managed — showing the prune plan without flipping it.` - ) - ); - } else { - await client.setOrgManagedBy(orgSlug, "code"); - printText( - chalk.yellow( - `Org "${orgSlug}" is now code-managed — apply will delete definitions removed from lobu.config.ts.` - ) - ); - } - codeManaged = true; + // `--manage` opts a UI-managed org into this. The plan is computed as + // code-managed so the prune is shown, but the org is flipped server-side only + // AFTER the plan + deletions are confirmed (`flipToCodeManaged`, below) — a + // cancelled apply must never leave the org flipped. Older servers omit + // `managed_by` → stays UI-managed (safe, no prune). + const orgIsCodeManaged = resolvedOrg?.managed_by === "code"; + const willManage = opts.manage === true && !!resolvedOrg && !orgIsCodeManaged; + const codeManaged = orgIsCodeManaged || willManage; + if (willManage) { + printText( + chalk.yellow( + opts.dryRun + ? `(dry-run) Org "${orgSlug}" would become code-managed — previewing the prune plan without flipping it.` + : `Org "${orgSlug}" will become code-managed after you confirm — future applies prune definitions removed from lobu.config.ts.` + ) + ); } + // Idempotent flip, invoked only on a confirmed (non-dry-run) apply. + const flipToCodeManaged = async (): Promise => { + if (!willManage) return; + await client.setOrgManagedBy(orgSlug, "code"); + printText(chalk.yellow(`Org "${orgSlug}" is now code-managed.`)); + }; // Team org consistency comes from `defineConfig({ org, organizationId })` in // lobu.config.ts (committed) plus the `.lobu/project.json` link — apply does @@ -1199,6 +1202,8 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { plan.counts.delete === 0 && !hasPendingAuth ) { + // Honor --manage even with an empty plan (no deletes occur this run). + await flipToCodeManaged(); printText(chalk.green("\nNothing to apply.")); return; } @@ -1225,6 +1230,10 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { } } + // Plan + deletions confirmed — now it's safe to flip the org to code-managed + // (before executePlan, so the deletes run against a code-managed org). + await flipToCodeManaged(); + const pendingAuth: PendingAuthEntry[] = []; let applyErr: unknown; if ( diff --git a/scripts/gen-use-case-data.ts b/scripts/gen-use-case-data.ts index 7deec3b6b..655edfd31 100644 --- a/scripts/gen-use-case-data.ts +++ b/scripts/gen-use-case-data.ts @@ -25,6 +25,7 @@ import { join, resolve } from "node:path"; import { pathToFileURL } from "node:url"; import type { Project, ProviderConfig, Watcher } from "@lobu/sdk"; import { isSecretRef } from "@lobu/sdk"; +import { createJiti } from "jiti"; const ROOT = resolve(import.meta.dir, ".."); const EXAMPLES_DIR = join(ROOT, "examples"); @@ -45,7 +46,6 @@ async function loadExampleConfig(exampleDir: string): Promise { const configPath = join(exampleDir, "lobu.config.ts"); if (!existsSync(configPath)) return null; - const { createJiti } = await import("jiti"); const jiti = createJiti(pathToFileURL(configPath).href); const project = (await jiti.import(configPath, { default: true })) as unknown; From a29fb34da1d7009d8471f2dc662074005b35430f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 04:57:34 +0100 Subject: [PATCH 35/65] fix(prune): harden code-managed prune (multi-angle pi review findings) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Security/correctness fixes from focused pi reviews of the prune feature: - HIGH: relationship-type delete now refuses while relationship instances exist (server, mirrors entity-type) — prune can no longer orphan live relationship data under a deleted definition. Regression-tested. - HIGH: apply resolves the org strictly by the slug it mutates and hard-stops if a config-pinned organizationId doesn't match that slug's org id. Removes the id-fallback that could read provenance from / target the wrong org (and would 404 mid-apply anyway since the client uses the slug in every URL). - MED: a code-managed apply now fetches connector definitions even when the config declares no connectors, so prune can delete the last connector removed from config. - MED: a fresh project whose deps aren't installed now gets a clear 'run bun install' message instead of a raw @lobu/sdk resolution error. Reviews confirmed: managed_by is DB-backed (no stale per-pod cache), the migration backfills 'ui' safely + applies idempotently, and no runtime code reads the deleted lobu.toml. Known limitations (documented, not data-unsafe): prune is non-atomic — a mid-batch refusal (instances exist) halts after earlier intended deletes, but re-running is idempotent and the server refuses every instance-bearing delete, so data is never lost. Concurrent destructive applies on a single org aren't serialized (no apply lock) — operators should not run parallel --manage applies on the same org. Stale 'lobu.toml' UI strings remain in the owletto submodule (separate repo/PR). --yes intentionally bypasses the blast-radius confirm (CI). --- .../apply/__tests__/apply-cmd-dryrun.test.ts | 33 +++++++++-- .../cli/src/commands/_lib/apply/apply-cmd.ts | 57 ++++++++++++++----- .../src/commands/_lib/apply/desired-state.ts | 16 +++++- .../integration/managed-by-prune.test.ts | 34 ++++++++++- .../src/tools/admin/manage_entity_schema.ts | 25 ++++++++ 5 files changed, 143 insertions(+), 22 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd-dryrun.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd-dryrun.test.ts index 340d858b4..b678abed0 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd-dryrun.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd-dryrun.test.ts @@ -273,18 +273,19 @@ describe("applyCommand org resolution", () => { ).resolves.toBeUndefined(); }); - test("org can also be matched by organizationId in the config when slug differs", async () => { + test("refuses when the slug doesn't resolve, even if a renamed org shares the organizationId", async () => { const dir = mkProject( minimalConfig("triage", { org: "acme", organizationId: "org_id_42" }) ); mkdirSync(join(dir, "agents", "triage"), { recursive: true }); - // The slug doesn't match ("acme" vs "wrong-slug") but the id matches. + // The pinned id matches a renamed org, but its slug differs from the one we + // apply to. The client targets the SLUG in every URL, so resolving by id + // would read provenance from / mutate the wrong org (or 404 mid-apply). const { fetchStub } = makeAuthFetch([ { id: "org_id_42", slug: "acme-renamed", name: "Acme Renamed" }, ]); - // Should NOT throw because the id matches. await expect( applyCommand({ cwd: dir, @@ -294,7 +295,31 @@ describe("applyCommand org resolution", () => { org: "acme", fetchImpl: fetchStub, }) - ).resolves.toBeUndefined(); + ).rejects.toThrow(/not found/i); + }); + + test("refuses when the resolved slug's org id mismatches the pinned organizationId", async () => { + const dir = mkProject( + minimalConfig("triage", { org: "acme", organizationId: "org_id_42" }) + ); + mkdirSync(join(dir, "agents", "triage"), { recursive: true }); + + // Slug "acme" resolves, but to a DIFFERENT org id than pinned — a stale or + // copied config pointed at someone else's org. Must hard-stop before apply. + const { fetchStub } = makeAuthFetch([ + { id: "org_different", slug: "acme", name: "Acme" }, + ]); + + await expect( + applyCommand({ + cwd: dir, + dryRun: true, + yes: true, + url: "https://app.lobu.ai", + org: "acme", + fetchImpl: fetchStub, + }) + ).rejects.toThrow(/organizationId/i); }); }); diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index 3c829c132..24e3193c5 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -265,7 +265,8 @@ async function confirmCustomConnectorSource( async function fetchRemoteSnapshot( client: ApplyClient, state: DesiredState, - only?: "agents" | "memory" + only?: "agents" | "memory", + codeManaged = false ): Promise { const agents: RemoteAgent[] = only === "memory" ? [] : await client.listAgents(); @@ -292,17 +293,20 @@ async function fetchRemoteSnapshot( only === "agents" ? [] : await client.listRelationshipTypes(); const watchers = only === "agents" ? [] : await client.listWatchers(); - // Connectors run only on a full apply (`--only` skips them). + // Connectors run only on a full apply (`--only` skips them). A code-managed + // org also fetches them even when the config declares none, so prune can + // delete a connector definition whose last config reference was removed + // (otherwise an empty desired-connectors set would skip the fetch entirely). const hasConnectors = state.connectors.definitions.length > 0 || state.connectors.authProfiles.length > 0 || state.connectors.connections.length > 0; - const connectorDefinitions = - only || !hasConnectors ? [] : await client.listConnectorDefinitions(true); - const authProfiles = - only || !hasConnectors ? [] : await client.listAuthProfiles(); - const connections = - only || !hasConnectors ? [] : await client.listConnections(); + const fetchConnectors = !only && (hasConnectors || codeManaged); + const connectorDefinitions = fetchConnectors + ? await client.listConnectorDefinitions(true) + : []; + const authProfiles = fetchConnectors ? await client.listAuthProfiles() : []; + const connections = fetchConnectors ? await client.listConnections() : []; const feedsByConnectionId = new Map(); if (!only && hasConnectors) { const desiredConnSlugs = new Set( @@ -1102,11 +1106,31 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { // (old server, or a token the userinfo endpoint rejects) → null → skip the // check and let the normal flow surface any org error. const myOrgs = await client.listOrgs().catch(() => null); - const resolvedOrg = - myOrgs?.find((o) => o.slug === orgSlug) ?? - (state.memory?.organizationId - ? myOrgs?.find((o) => o.id === state.memory?.organizationId) - : undefined); + // Resolve strictly by the slug we will actually mutate (the client targets + // `orgSlug` in every URL). Do NOT fall back to organizationId as an alternate + // org — that could read provenance (managed_by) from a different org than the + // one being applied/pruned. + const resolvedOrg = myOrgs?.find((o) => o.slug === orgSlug); + // If the config pins `organizationId`, the slug must resolve to that exact + // org — otherwise it's a stale/copied config pointed at someone else's org, + // and (under --manage) could prune the wrong org. Hard-stop. + if ( + resolvedOrg && + state.memory?.organizationId && + resolvedOrg.id !== state.memory.organizationId + ) { + printError( + [ + "", + `Org slug "${orgSlug}" resolves to org id ${resolvedOrg.id}, but lobu.config.ts pins organizationId ${state.memory.organizationId}.`, + "This usually means the config was copied from another project or the slug was reused.", + "Fix `org`/`organizationId` in defineConfig (or pass the right --org) before applying.", + ].join("\n") + ); + throw new ValidationError( + `org "${orgSlug}" (id ${resolvedOrg.id}) does not match pinned organizationId ${state.memory.organizationId}` + ); + } if (myOrgs !== null && !resolvedOrg) { const orgName = state.memory?.name ?? slugToTitle(orgSlug); const createUrl = `${apiBaseUrl}/orgs/new?slug=${encodeURIComponent(orgSlug)}&name=${encodeURIComponent(orgName)}`; @@ -1168,7 +1192,12 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { // this (current/stale) catalog — "create" when the key isn't installed, // "update" when it is. Connector defs are NOT installed here; that happens in // `executePlan`, AFTER plan confirmation. - const remote = await fetchRemoteSnapshot(client, state, opts.only); + const remote = await fetchRemoteSnapshot( + client, + state, + opts.only, + codeManaged + ); // Validate connection/auth-profile config against the catalog we have now, // but SKIP schema validation for connector keys declared locally — those diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index f1685c4b8..860a523c0 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -783,9 +783,19 @@ export async function loadProjectConfig( try { project = await jiti.import(configPath, { default: true }); } catch (err) { - throw new ValidationError( - `Failed to load lobu.config.ts — ${err instanceof Error ? err.message : String(err)}` - ); + const message = err instanceof Error ? err.message : String(err); + // A fresh `lobu init` writes package.json declaring @lobu/sdk but doesn't + // install — jiti then can't resolve the import. Point the user at the fix + // instead of surfacing a raw module-resolution error. + if ( + /@lobu\/(sdk|connector-sdk)/.test(message) && + !existsSync(resolve(cwd, "node_modules")) + ) { + throw new ValidationError( + `Failed to load lobu.config.ts — its @lobu/sdk import can't be resolved because dependencies aren't installed. Run \`bun install\` (or npm/pnpm install) in ${cwd} first.` + ); + } + throw new ValidationError(`Failed to load lobu.config.ts — ${message}`); } if ( !project || diff --git a/packages/server/src/__tests__/integration/managed-by-prune.test.ts b/packages/server/src/__tests__/integration/managed-by-prune.test.ts index cf5cbaeb9..ac32984c5 100644 --- a/packages/server/src/__tests__/integration/managed-by-prune.test.ts +++ b/packages/server/src/__tests__/integration/managed-by-prune.test.ts @@ -108,7 +108,7 @@ describe('code-managed prune (server gate)', () => { ).rejects.toThrow(/entities of this type exist|cannot delete/i); }); - it('deletes a relationship type', async () => { + it('deletes a relationship type with no instances', async () => { await owner.entity_schema.createRelType({ slug: 'prune-rel', name: 'Rel' }); await owner.entity_schema.deleteRelType('prune-rel'); const list = (await owner.entity_schema.listTypes()) as { @@ -119,6 +119,38 @@ describe('code-managed prune (server gate)', () => { ).toBe(false); }); + it('refuses to delete a relationship type while instances exist (data is exempt)', async () => { + const sql = getTestDb(); + await owner.entity_schema.createRelType({ + slug: 'prune-rel-busy', + name: 'Busy Rel', + }); + const [rt] = await sql<{ id: number }[]>` + SELECT id FROM entity_relationship_types + WHERE slug = ${'prune-rel-busy'} AND organization_id = ${orgId} + AND deleted_at IS NULL + LIMIT 1 + `; + const a = await createTestEntity({ + name: 'Rel Source', + entity_type: 'prune-rel-from', + organization_id: orgId, + }); + const b = await createTestEntity({ + name: 'Rel Target', + entity_type: 'prune-rel-to', + organization_id: orgId, + }); + await sql` + INSERT INTO entity_relationships + (organization_id, from_entity_id, to_entity_id, relationship_type_id, created_by) + VALUES (${orgId}, ${a.id}, ${b.id}, ${rt?.id}, ${userId}) + `; + await expect( + owner.entity_schema.deleteRelType('prune-rel-busy') + ).rejects.toThrow(/relationships of this type exist|cannot delete/i); + }); + it('deletes a watcher', async () => { const agent = await createTestAgent({ organizationId: orgId }); const created = (await owner.watchers.create({ diff --git a/packages/server/src/tools/admin/manage_entity_schema.ts b/packages/server/src/tools/admin/manage_entity_schema.ts index a458347ac..63aa60b1b 100644 --- a/packages/server/src/tools/admin/manage_entity_schema.ts +++ b/packages/server/src/tools/admin/manage_entity_schema.ts @@ -342,6 +342,21 @@ async function getEntityCountForType(typeId: number, organizationId: string): Pr return Number(rows[0]?.count || 0); } +async function getRelationshipCountForType( + typeId: number, + organizationId: string +): Promise { + const sql = getDb(); + const rows = await sql` + SELECT COUNT(*)::int as count + FROM entity_relationships r + WHERE r.relationship_type_id = ${typeId} + AND r.organization_id = ${organizationId} + AND r.deleted_at IS NULL + `; + return Number(rows[0]?.count || 0); +} + async function recordAudit( sql: DbClient, entityTypeId: number, @@ -1032,6 +1047,16 @@ async function rtHandleDelete( ): Promise { const { typeId, sql } = await requireRelationshipType(args.slug, 'delete', ctx); + // Refuse while relationship instances exist — mirrors entity-type delete so + // `lobu apply` prune (and the UI) can never orphan live relationship data + // under a deleted definition. + const relationshipCount = await getRelationshipCountForType(typeId, ctx.organizationId); + if (relationshipCount > 0) { + throw new Error( + `Cannot delete relationship type '${args.slug}': ${relationshipCount} relationships of this type exist. Remove or reassign them first.` + ); + } + await sql` UPDATE entity_relationship_types SET deleted_at = current_timestamp, updated_at = current_timestamp From e686960008009746b49f671f7aa3a339c0f00a32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 04:53:40 +0100 Subject: [PATCH 36/65] fix(cli): persist entity-type properties via metadata_schema (idempotent apply) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit lobu apply (and lobu memory seed) sent entity-type `properties`/`required` as top-level keys, but manage_entity_schema only reads `metadata_schema`. The schema was silently dropped on every create/update, so the stored schema stayed empty and every subsequent apply re-reported a `properties` update — apply never reached a clean noop. Fold the flat fields into a `metadata_schema` JSON Schema on write, and hoist them back out of `metadata_schema` on read so the diff compares like for like. --- .../cli/src/commands/_lib/apply/client.ts | 58 +++++++++++++++++-- .../cli/src/commands/memory/_lib/seed-cmd.ts | 15 ++++- 2 files changed, 66 insertions(+), 7 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index a98782785..b2ba4c08e 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -178,6 +178,33 @@ function pickArray(body: Record, ...keys: string[]): T[] { return []; } +/** + * The server stores entity-type per-field config as a single `metadata_schema` + * JSON Schema. The diff compares the desired config's flat `properties`/ + * `required` against the remote snapshot, so hoist them out of the returned + * `metadata_schema` to the row's top level. Mirrors `upsertEntityType`, which + * folds the flat fields back into `metadata_schema` when writing. + */ +function hoistEntityTypeSchema( + row: RemoteEntityType & { metadata_schema?: unknown } +): RemoteEntityType { + const schema = row.metadata_schema; + const out: RemoteEntityType = { + slug: row.slug, + ...(row.name !== undefined ? { name: row.name } : {}), + ...(row.description !== undefined ? { description: row.description } : {}), + }; + if (isRecord(schema)) { + if (isRecord(schema.properties)) out.properties = schema.properties; + if (Array.isArray(schema.required)) { + out.required = schema.required.filter( + (v): v is string => typeof v === "string" + ); + } + } + return out; +} + function extractApiError( parsed: Record, status: number, @@ -475,13 +502,20 @@ export class ApplyClient { async listEntityTypes(): Promise { const { body } = await this.request<{ - entity_types?: RemoteEntityType[]; - entityTypes?: RemoteEntityType[]; + entity_types?: Array; + entityTypes?: Array; }>("POST", `/api/${this.orgSlug}/manage_entity_schema`, { schema_type: "entity_type", action: "list", }); - return pickArray(body, "entity_types", "entityTypes"); + // The server returns the type's fields inside a single `metadata_schema` + // JSON Schema. Surface its `properties`/`required` at top level so the diff + // compares them against the desired config (which carries them flat). + return pickArray( + body, + "entity_types", + "entityTypes" + ).map(hoistEntityTypeSchema); } /** @@ -522,7 +556,23 @@ export class ApplyClient { required?: string[]; properties?: Record; }): Promise { - return this.upsertSchemaResource("entity_type", entity); + // The server stores per-type fields as a single `metadata_schema` JSON + // Schema (`{ type, properties, required }`) — it does NOT read top-level + // `properties`/`required`. Fold them into `metadata_schema` so the schema + // actually persists (otherwise every apply re-reports a `properties` + // update because the stored schema stays empty). + const { slug, name, description, required, properties } = entity; + const payload: Record = { slug }; + if (name !== undefined) payload.name = name; + if (description !== undefined) payload.description = description; + if (properties !== undefined || required !== undefined) { + payload.metadata_schema = { + type: "object", + properties: properties ?? {}, + ...(required && required.length > 0 ? { required } : {}), + }; + } + return this.upsertSchemaResource("entity_type", payload); } async listRelationshipTypes(): Promise { diff --git a/packages/cli/src/commands/memory/_lib/seed-cmd.ts b/packages/cli/src/commands/memory/_lib/seed-cmd.ts index 35719d29a..ca8467528 100644 --- a/packages/cli/src/commands/memory/_lib/seed-cmd.ts +++ b/packages/cli/src/commands/memory/_lib/seed-cmd.ts @@ -188,15 +188,24 @@ async function seedEntity( return; } // Same payload `lobu apply` sends to manage_entity_schema (upsertEntityType). - const payload = { + // The server stores per-type fields as a single `metadata_schema` JSON Schema + // and ignores top-level `properties`/`required`, so fold them in here too. + const payload: Record = { schema_type: "entity_type", action: "create", slug: entity.slug, ...(entity.name ? { name: entity.name } : {}), ...(entity.description ? { description: entity.description } : {}), - ...(entity.required ? { required: entity.required } : {}), - ...(entity.properties ? { properties: entity.properties } : {}), }; + if (entity.properties !== undefined || entity.required !== undefined) { + payload.metadata_schema = { + type: "object", + properties: entity.properties ?? {}, + ...(entity.required && entity.required.length > 0 + ? { required: entity.required } + : {}), + }; + } try { await callTool(ctx, "manage_entity_schema", payload); printText(` + entity_type: ${slug}`); From 92399f9085e72c356e8e9842f9e6992199a7cd27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 05:01:29 +0100 Subject: [PATCH 37/65] test(cli): init-from-org mock returns server's metadata_schema shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The listEntityTypes mock returned flat top-level properties/required, which the real manage_entity_schema list action never emits — it returns metadata_schema. Align the fixture with the real server contract now that the client hoists properties/required out of metadata_schema (see the entity-type persist fix). --- .../init-from-org/__tests__/init-from-org.test.ts | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts index 46b24df58..6a5ce77cc 100644 --- a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts +++ b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts @@ -126,14 +126,20 @@ function fullOrgRoutes(): Record unknown> { // The mapper uses a single endpoint for both entity_type and // relationship_type list actions; return a body carrying both keys. return { + // Real server shape: per-type fields live inside `metadata_schema` + // (a JSON Schema), not top-level `properties`/`required`. The client + // hoists them back out for the diff/bootstrap. entity_types: [ { slug: "lead", name: "Lead", description: "A sales lead", - required: ["stage"], - properties: { - stage: { type: "string", "x-table-label": "Stage" }, + metadata_schema: { + type: "object", + required: ["stage"], + properties: { + stage: { type: "string", "x-table-label": "Stage" }, + }, }, }, { slug: "pilot", name: "Pilot" }, From b397fb2655f960ce2526cb24311b1dc09e8d2713 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 05:07:49 +0100 Subject: [PATCH 38/65] fix(prune): never prune public entity/relationship types owned by another org MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Confirmation pi review found the last prune-completeness bug: the entity-type and relationship-type list endpoints return this org's types PLUS public types from other orgs (manage_entity_schema: `organization_id = $1 OR o.visibility = 'public'`). computeDiff treated every remote type absent from desired as a code-managed delete, so a prune could plan deletes for another org's public types — the server refuses them, but it wrongly halts a legit apply. Fix: carry organization_id through listEntityTypes (preserved across the metadata_schema hoist) + listRelationshipTypes, pass the target org id into computeDiff, and emit drift/delete only for org-owned remote types. Unit-tested (foreign-org public types are never pruned; the org's own removed types still are). pi confirmed the other four fixes correct with no data-deletion paths. --- .../_lib/apply/__tests__/diff.test.ts | 32 +++++++++++++++++++ .../cli/src/commands/_lib/apply/apply-cmd.ts | 6 +++- .../cli/src/commands/_lib/apply/client.ts | 12 +++++++ packages/cli/src/commands/_lib/apply/diff.ts | 17 ++++++++++ 4 files changed, 66 insertions(+), 1 deletion(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index 079d628f5..185352b4f 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -1084,6 +1084,38 @@ describe("apply diff — code-managed prune", () => { ).toBe("drift"); }); + test("code-managed prune never deletes public types owned by another org", () => { + // The list endpoint returns this org's types PLUS public types from other + // orgs. With orgId set, a foreign-org type must not be pruned even if it's + // absent from the config. + const remote: RemoteSnapshot = { + ...emptyRemote(), + entityTypes: [ + { slug: "lead", properties: {}, organization_id: "org_self" }, + { slug: "stale-mine", organization_id: "org_self" }, + { slug: "public-other", organization_id: "org_other" }, + ], + relationshipTypes: [ + { slug: "stale-rel-mine", organization_id: "org_self" }, + { slug: "public-rel-other", organization_id: "org_other" }, + ], + }; + const plan = computeDiff(desiredKeepingLead(), remote, { + codeManaged: true, + orgId: "org_self", + }); + const deletedIds = plan.rows + .filter((r) => r.verb === "delete") + .map((r) => `${r.kind}:${r.id}`) + .sort(); + // Only the org's own removed types — never the foreign public ones. + expect(deletedIds).toEqual([ + "entity-type:stale-mine", + "relationship-type:stale-rel-mine", + ]); + expect(deletedIds.some((id) => id.includes("other"))).toBe(false); + }); + test("connector prune suppressed when a local def has an unresolved (null) key", () => { const desired = buildState([], { connectors: { diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index 24e3193c5..1edb414a4 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -1209,7 +1209,11 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { skipSchemaForConnectorKeys: locallyDeclaredConnectorKeys(state), }); - const plan = computeDiff(state, remote, { only: opts.only, codeManaged }); + const plan = computeDiff(state, remote, { + only: opts.only, + codeManaged, + ...(resolvedOrg?.id ? { orgId: resolvedOrg.id } : {}), + }); printText(renderPlan(plan)); if (opts.dryRun) { diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index b2ba4c08e..ba16c8222 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -28,6 +28,12 @@ export interface RemoteEntityType { description?: string; required?: string[]; properties?: Record; + /** + * Owning org id. The list endpoint also returns *public* types from OTHER + * orgs (`o.visibility = 'public'`), so prune must compare this against the + * target org and never delete a type this org doesn't own. + */ + organization_id?: string; } export interface RemoteRelationshipType { @@ -35,6 +41,8 @@ export interface RemoteRelationshipType { name?: string; description?: string; rules?: Array<{ source: string; target: string }>; + /** Owning org id — see RemoteEntityType.organization_id (public-type guard). */ + organization_id?: string; } export interface RemoteOrg { @@ -193,6 +201,10 @@ function hoistEntityTypeSchema( slug: row.slug, ...(row.name !== undefined ? { name: row.name } : {}), ...(row.description !== undefined ? { description: row.description } : {}), + // Preserve owning org so prune can skip public types from other orgs. + ...(row.organization_id !== undefined + ? { organization_id: row.organization_id } + : {}), }; if (isRecord(schema)) { if (isRecord(schema.properties)) out.properties = schema.properties; diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index b35baff17..e5e052c14 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -811,6 +811,13 @@ export interface ComputeDiffOptions { * never pruned. Default (false / UI-managed) reports those as `drift`. */ codeManaged?: boolean; + /** + * Target org id. The entity/relationship-type list endpoints also return + * *public* definitions owned by OTHER orgs, which this org neither manages + * nor can delete — so a remote type whose `organization_id` differs is + * excluded from drift/delete entirely. Omit to disable the filter (tests). + */ + orgId?: string; } export function computeDiff( @@ -821,6 +828,14 @@ export function computeDiff( const rows: DiffRow[] = []; const only = opts.only; const codeManaged = opts.codeManaged ?? false; + // A remote entity/relationship type is this org's to manage (drift/prune) + // only when it's org-owned. The list endpoints also surface public types + // from other orgs (`organization_id` differs) — never drift or delete those. + const orgId = opts.orgId; + const ownsDefinition = (definitionOrgId: string | undefined): boolean => + orgId === undefined || + definitionOrgId === undefined || + definitionOrgId === orgId; if (only !== "memory") { const remoteByAgent = new Map(remote.agents.map((a) => [a.agentId, a])); @@ -901,6 +916,7 @@ export function computeDiff( rows.push(diffEntityType(entity, remoteEntityBySlug.get(entity.slug))); } for (const remoteEntity of remote.entityTypes) { + if (!ownsDefinition(remoteEntity.organization_id)) continue; if (!desiredEntitySlugs.has(remoteEntity.slug)) { // Code-managed: delete. The server refuses an entity-type delete while // instances exist (the data is exempt), surfacing a clear error. @@ -923,6 +939,7 @@ export function computeDiff( rows.push(diffRelationshipType(rel, remoteRelBySlug.get(rel.slug))); } for (const remoteRel of remote.relationshipTypes) { + if (!ownsDefinition(remoteRel.organization_id)) continue; if (!desiredRelSlugs.has(remoteRel.slug)) { rows.push({ kind: "relationship-type", From 203cbdc651a12fd7a5cfd59a5880d9e28b107988 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 05:15:38 +0100 Subject: [PATCH 39/65] fix(prune): match entity/relationship types against the org's own definitions only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Final ship-readiness pi caught a matching-shadow bug adjacent to the prior prune fix: the slug->row Maps were built from the full remote list, and since the server returns the org's rows first then public rows from other orgs, a Map kept the LAST (foreign public) entry on a slug collision — so matching could diff desired against a foreign public type (false noop/update) even though prune was already org-scoped. Fix: filter entity/relationship types to org-owned ONCE and use that list for both matching and prune, so a foreign public type can never shadow the org's own definition. Unit-tested: a same-slug foreign public type no longer shadows the org's own (stays noop) and is never pruned. --- .../_lib/apply/__tests__/diff.test.ts | 26 +++++++++++++++++++ packages/cli/src/commands/_lib/apply/diff.ts | 21 ++++++++++----- 2 files changed, 40 insertions(+), 7 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index 185352b4f..d63644548 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -1116,6 +1116,32 @@ describe("apply diff — code-managed prune", () => { expect(deletedIds.some((id) => id.includes("other"))).toBe(false); }); + test("matching prefers the org's own type over a foreign public type with the same slug", () => { + // Server returns the org's own row first, then a public row with the same + // slug. Matching must compare desired against the org-owned row (noop), not + // the foreign public one (which would falsely look like an update). + const remote: RemoteSnapshot = { + ...emptyRemote(), + entityTypes: [ + { slug: "lead", properties: {}, organization_id: "org_self" }, + { + slug: "lead", + properties: { foreign: { type: "string" } }, + organization_id: "org_other", + }, + ], + }; + const plan = computeDiff(desiredKeepingLead(), remote, { + codeManaged: true, + orgId: "org_self", + }); + const leadRow = plan.rows.find( + (r) => r.kind === "entity-type" && r.id === "lead" + ); + expect(leadRow?.verb).toBe("noop"); + expect(plan.rows.some((r) => r.verb === "delete")).toBe(false); + }); + test("connector prune suppressed when a local def has an unresolved (null) key", () => { const desired = buildState([], { connectors: { diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index e5e052c14..2839b72d5 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -906,8 +906,16 @@ export function computeDiff( } if (only !== "agents") { + // Restrict entity/relationship types to the ones THIS org owns, for both + // matching and prune. The list endpoints also return public types from + // other orgs; the server returns them after the org's own rows, so a naive + // slug→row Map would let a foreign public type shadow the org's own + // definition (false noop/update) — and prune must never touch them. + const ownedEntityTypes = remote.entityTypes.filter((e) => + ownsDefinition(e.organization_id) + ); const remoteEntityBySlug = new Map( - remote.entityTypes.map((e) => [e.slug, e]) + ownedEntityTypes.map((e) => [e.slug, e]) ); const desiredEntitySlugs = new Set( desired.memorySchema.entityTypes.map((e) => e.slug) @@ -915,8 +923,7 @@ export function computeDiff( for (const entity of desired.memorySchema.entityTypes) { rows.push(diffEntityType(entity, remoteEntityBySlug.get(entity.slug))); } - for (const remoteEntity of remote.entityTypes) { - if (!ownsDefinition(remoteEntity.organization_id)) continue; + for (const remoteEntity of ownedEntityTypes) { if (!desiredEntitySlugs.has(remoteEntity.slug)) { // Code-managed: delete. The server refuses an entity-type delete while // instances exist (the data is exempt), surfacing a clear error. @@ -929,17 +936,17 @@ export function computeDiff( } } - const remoteRelBySlug = new Map( - remote.relationshipTypes.map((r) => [r.slug, r]) + const ownedRelTypes = remote.relationshipTypes.filter((r) => + ownsDefinition(r.organization_id) ); + const remoteRelBySlug = new Map(ownedRelTypes.map((r) => [r.slug, r])); const desiredRelSlugs = new Set( desired.memorySchema.relationshipTypes.map((r) => r.slug) ); for (const rel of desired.memorySchema.relationshipTypes) { rows.push(diffRelationshipType(rel, remoteRelBySlug.get(rel.slug))); } - for (const remoteRel of remote.relationshipTypes) { - if (!ownsDefinition(remoteRel.organization_id)) continue; + for (const remoteRel of ownedRelTypes) { if (!desiredRelSlugs.has(remoteRel.slug)) { rows.push({ kind: "relationship-type", From e455490714c7e021a0186b735c72c82f587c8788 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 05:22:56 +0100 Subject: [PATCH 40/65] fix(server): org-scope relationship-type write resolution + create dedup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Final pi sweep: requireRelationshipType (write mode) resolved by global slug with no org preference, so when an org owned a rel-type AND a public type from another org shared the slug, LIMIT 1 could grab the foreign row and the access-denied guard then blocked the org from updating/deleting its OWN type (and broke code-managed prune). Now tenant-first ordered, mirroring read mode. Also org-scoped rtHandleCreate's duplicate check (the unique index is (organization_id, slug), and entity-type create was already org-scoped) so a same-slug foreign public type can't block this org's create. Not a cross-org deletion path (the access-denied guard held) — a correctness/availability fix. Cross-org integration test added (9 prune tests, 7 entity-schema tests green). --- .../integration/managed-by-prune.test.ts | 27 +++++++++++++++++++ .../src/tools/admin/manage_entity_schema.ts | 10 +++++++ 2 files changed, 37 insertions(+) diff --git a/packages/server/src/__tests__/integration/managed-by-prune.test.ts b/packages/server/src/__tests__/integration/managed-by-prune.test.ts index ac32984c5..14820ab82 100644 --- a/packages/server/src/__tests__/integration/managed-by-prune.test.ts +++ b/packages/server/src/__tests__/integration/managed-by-prune.test.ts @@ -151,6 +151,33 @@ describe('code-managed prune (server gate)', () => { ).rejects.toThrow(/relationships of this type exist|cannot delete/i); }); + it('a foreign public rel-type with the same slug does not block the org owning/managing its own', async () => { + const sql = getTestDb(); + // A different org, public, with a relationship type sharing the slug. + const other = await createTestOrganization({ + name: 'Public Other', + visibility: 'public', + }); + await sql` + INSERT INTO entity_relationship_types (organization_id, slug, name, status, created_at, updated_at) + VALUES (${other.id}, ${'shared-rel'}, 'Foreign Shared', 'active', NOW(), NOW()) + `; + // This org can still CREATE its own same-slug type (org-scoped dup check). + await owner.entity_schema.createRelType({ + slug: 'shared-rel', + name: 'My Shared', + }); + // ...and DELETE resolves THIS org's own row (tenant-first), not the + // foreign public one (which would otherwise raise access-denied). + await owner.entity_schema.deleteRelType('shared-rel'); + // The foreign public row is untouched. + const [foreign] = await sql<{ deleted_at: string | null }[]>` + SELECT deleted_at FROM entity_relationship_types + WHERE organization_id = ${other.id} AND slug = ${'shared-rel'} + `; + expect(foreign?.deleted_at).toBeNull(); + }); + it('deletes a watcher', async () => { const agent = await createTestAgent({ organizationId: orgId }); const created = (await owner.watchers.create({ diff --git a/packages/server/src/tools/admin/manage_entity_schema.ts b/packages/server/src/tools/admin/manage_entity_schema.ts index 63aa60b1b..9ab312558 100644 --- a/packages/server/src/tools/admin/manage_entity_schema.ts +++ b/packages/server/src/tools/admin/manage_entity_schema.ts @@ -754,9 +754,15 @@ async function requireRelationshipType( return { typeId: Number(rows[0].id), sql }; } + // Tenant-first ordering: when the caller's org owns a relationship type AND a + // public type from another org shares the slug, resolve the caller's OWN row. + // Without this, `LIMIT 1` could grab the foreign public row and the + // access-denied guard below would wrongly block the caller from + // updating/deleting its own type (and break code-managed prune). const existing = await sql` SELECT id, organization_id FROM entity_relationship_types WHERE slug = ${slug} AND deleted_at IS NULL + ORDER BY (organization_id = ${ctx.organizationId}) DESC, id ASC LIMIT 1 `; if (existing.length === 0) throw new Error(`Relationship type "${slug}" not found`); @@ -893,9 +899,13 @@ async function rtHandleCreate( const sql = getDb(); + // Org-scoped duplicate check — the unique index is (organization_id, slug), + // so a same-slug PUBLIC type from another org must NOT block this org from + // creating its own (matches entity-type create). const existing = await sql` SELECT id FROM entity_relationship_types WHERE slug = ${args.slug} AND deleted_at IS NULL + AND organization_id = ${ctx.organizationId} LIMIT 1 `; if (existing.length > 0) { From a010c1cef7a5697416d339a6e05f377ae0c9b1b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 05:38:12 +0100 Subject: [PATCH 41/65] fix: init-from-org auth-profile safety + complete rel-type inverse org-scoping MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Final convergence pi findings on this PR's surface: - init-from-org (bootstrap.ts): an auth profile with no connector_key was emitted as `connector: null`, which crashed the next `lobu apply` (connectorKey(null)). Now skipped with a surfaced warning. Also flagged the credential placeholders with a TODO — keys must be renamed to the connector's auth-schema fields (values are write-only, unrecoverable on bootstrap). - manage_entity_schema: the inverse_type_slug lookups in relationship-type create/update resolved by global slug; made them tenant-first (ORDER BY org-owned), completing the org-scoping hardening of the rel-type handlers this PR already touches. Out of scope (pre-existing, NOT exercised by this PR — documented for a separate hardening pass): manage_feeds delete_feed cancels runs before the ownership check (prune never deletes feeds). CLI 296 tests + 16 schema/prune integration tests green; server typecheck clean. --- .../commands/_lib/init-from-org/bootstrap.ts | 32 ++++++++++++++++--- .../src/tools/admin/manage_entity_schema.ts | 2 ++ 2 files changed, 29 insertions(+), 5 deletions(-) diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index 1e1d2da99..5323f24df 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -567,7 +567,11 @@ function emitAuthProfile( connectorHandles: Map, imports: ImportTracker, minter: IdentMinter -): Handle { +): Handle | null { + // An auth profile with no connector can't be expressed as defineAuthProfile + // (connector is required), and emitting `connector: null` would crash on the + // next `lobu apply` (connectorKey(null)). Skip it — the caller warns. + if (!p.connector_key) return null; imports.use("defineAuthProfile"); const interactive = p.profile_kind === "oauth_account" || p.profile_kind === "browser_session"; @@ -579,9 +583,11 @@ function emitAuthProfile( `authKind: ${str(p.profile_kind)}`, ]; if (p.display_name) fields.push(`name: ${str(p.display_name)}`); - // Credentials are write-only on the server. For credentialed kinds, emit a - // single secret placeholder so the operator wires it back in; interactive - // kinds (oauth_account / browser_session) take no credentials (auth via UI). + // Credentials are write-only on the server, so we can't recover the real + // values or the connector's exact field names here. Emit secret placeholders + // the operator wires in via .env; the credential KEYS must be renamed to the + // connector's auth-schema fields before applying (see the connector docs). + // Interactive kinds (oauth_account / browser_session) take no credentials. if ( !interactive && (p.profile_kind === "env" || p.profile_kind === "oauth_app") @@ -589,7 +595,7 @@ function emitAuthProfile( imports.use("secret"); const credKey = p.profile_kind === "oauth_app" ? "CLIENT_SECRET" : "VALUE"; fields.push( - `credentials: {\n ${envVarFor(p.slug, credKey)}: ${secrets.ref(envVarFor(p.slug, credKey))},\n }` + `// TODO: rename credential keys to this connector's auth-schema fields\n credentials: {\n ${envVarFor(p.slug, credKey)}: ${secrets.ref(envVarFor(p.slug, credKey))},\n }` ); } const name = minter.mint(p.slug, "Auth"); @@ -741,6 +747,8 @@ interface GeneratedProject { configSource: string; files: Array<{ relPath: string; body: string }>; envVars: string[]; + /** Non-fatal issues (e.g. a skipped malformed auth profile) to surface. */ + warnings: string[]; } export function generateProject( @@ -753,6 +761,7 @@ export function generateProject( const secrets = new SecretCollector(); const minter = new IdentMinter(); const files: Array<{ relPath: string; body: string }> = []; + const warnings: string[] = []; // Agents first (watchers reference their handles). const agentHandles = new Map(); @@ -788,6 +797,12 @@ export function generateProject( const authDecls: string[] = []; for (const p of state.authProfiles) { const h = emitAuthProfile(p, secrets, connectorHandles, imports, minter); + if (!h) { + warnings.push( + `auth profile "${p.slug}" has no connector — skipped (set its connector and re-add it to lobu.config.ts).` + ); + continue; + } authHandles.set(p.slug, h.name); authDecls.push(h.decl); } @@ -880,6 +895,7 @@ export function generateProject( configSource, files, envVars: [...secrets.names].sort(), + warnings, }; } @@ -944,6 +960,12 @@ export async function initFromOrg(opts: InitFromOrgOptions): Promise { printText(` ${chalk.yellow("·")} ${v}`); } } + if (project.warnings.length > 0) { + printText(chalk.bold("\nWarnings:")); + for (const w of project.warnings) { + printText(` ${chalk.yellow("⚠")} ${w}`); + } + } printText( chalk.dim( "\nReview lobu.config.ts, fill .env, then `lobu apply` to re-sync.\n" diff --git a/packages/server/src/tools/admin/manage_entity_schema.ts b/packages/server/src/tools/admin/manage_entity_schema.ts index 9ab312558..0e0c9bd85 100644 --- a/packages/server/src/tools/admin/manage_entity_schema.ts +++ b/packages/server/src/tools/admin/manage_entity_schema.ts @@ -917,6 +917,7 @@ async function rtHandleCreate( const inverseRows = await sql` SELECT id FROM entity_relationship_types WHERE slug = ${args.inverse_type_slug} AND deleted_at IS NULL + ORDER BY (organization_id = ${ctx.organizationId}) DESC, id ASC LIMIT 1 `; if (inverseRows.length === 0) { @@ -990,6 +991,7 @@ async function rtHandleUpdate( const inverseRows = await sql` SELECT id FROM entity_relationship_types WHERE slug = ${args.inverse_type_slug} AND deleted_at IS NULL + ORDER BY (organization_id = ${ctx.organizationId}) DESC, id ASC LIMIT 1 `; if (inverseRows.length === 0) { From 7b5603f5441a0752711e50fc9182b061fe1d064f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 13:03:02 +0100 Subject: [PATCH 42/65] feat(sdk): restore config-authored chat platforms (defineAgent platforms) Final pi review caught that the migration silently dropped config-authored platforms: the SDK had no platforms field, mapAgent hardcoded platforms:[], yet 'lobu init --platform' still prompted for one + wrote bot-token env placeholders that 'apply' never consumed (on main, lobu.toml emitted [[agents.platforms]] which apply created). Per the user, restore them: - @lobu/sdk: defineAgent({ platforms: [{ type, name?, config, channels? }] }). - mapAgent: maps platforms to DesiredPlatform with a deterministic stable id (agentId-type[-name]) so apply matches (noop) instead of recreating; config /secret() values kept as placeholders + collected into requiredSecrets. - lobu init: emits a platforms block from the chosen --platform + its config. - lobu init --from-org: round-trips live platform bindings back to config (strips the route's embedded key; config -> secret() refs). Unit-tested (stable-id derivation + secret collection + literal passthrough); full CLI suite 297 green; SDK + CLI typecheck clean. --- .../_lib/apply/__tests__/map-config.test.ts | 37 +++++++++++++++ .../cli/src/commands/_lib/apply/map-config.ts | 41 ++++++++++++++++- .../commands/_lib/init-from-org/bootstrap.ts | 46 +++++++++++++++++-- packages/cli/src/commands/init.ts | 24 ++++++++++ packages/sdk/src/define.ts | 29 ++++++++++-- 5 files changed, 169 insertions(+), 8 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index 42e95a05a..13bde7620 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -58,6 +58,43 @@ describe("mapProjectToDesiredState", () => { expect(state.memory).toEqual({ org: "o" }); }); + test("maps agent platforms: stable id + $VAR config kept as placeholder + secret collected", () => { + const bot = defineAgent({ + id: "support-bot", + platforms: [ + { + type: "telegram", + config: { botToken: secret("TELEGRAM_BOT_TOKEN") }, + }, + { + type: "slack", + name: "ops", + config: { botToken: "$SLACK_BOT_TOKEN", appType: "MultiTenant" }, + channels: ["T1/C1"], + }, + ], + }); + const state = mapProjectToDesiredState( + defineConfig({ org: "o", agents: [bot] }), + env + ); + const platforms = state.agents[0]?.platforms ?? []; + expect(platforms).toHaveLength(2); + // Stable id is deterministic from (agentId, type, name?). + expect(platforms[0]?.stableId).toBe("support-bot-telegram"); + expect(platforms[1]?.stableId).toBe("support-bot-slack-ops"); + // `$VAR`/secret() placeholders are kept in config (resolved at egress), + // literals pass through, and the referenced secrets are collected. + expect(platforms[0]?.config).toEqual({ botToken: "$TELEGRAM_BOT_TOKEN" }); + expect(platforms[1]?.config).toEqual({ + botToken: "$SLACK_BOT_TOKEN", + appType: "MultiTenant", + }); + expect(platforms[1]?.channels).toEqual(["T1/C1"]); + expect(state.requiredSecrets).toContain("TELEGRAM_BOT_TOKEN"); + expect(state.requiredSecrets).toContain("SLACK_BOT_TOKEN"); + }); + test("maps entities + relationships with typed-handle slugs", () => { const person = defineEntityType({ key: "person", name: "Person" }); const org = defineEntityType({ key: "org" }); diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index 182172dfb..7f3be5844 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -31,6 +31,7 @@ import type { DesiredConnection, DesiredEntityType, DesiredFeed, + DesiredPlatform, DesiredRelationshipType, DesiredState, DesiredWatcher, @@ -92,6 +93,29 @@ function authProfileSlug( return typeof ref === "string" ? ref : ref.slug; } +/** + * Deterministic, human-readable stable id for a platform binding, derived from + * `(agentId, type, name?)`. Must stay stable across applies so the same + * platform matches (noop) instead of being recreated — `apply` PUTs it to + * `/platforms/by-stable-id/:stableId`. + */ +function platformStableId( + agentId: string, + type: string, + name?: string +): string { + const slug = (s: string) => + s + .toLowerCase() + .replace(/[^a-z0-9]+/g, "-") + .replace(/^-+|-+$/g, ""); + return [agentId, type, name] + .filter((p): p is string => !!p) + .map(slug) + .filter(Boolean) + .join("-"); +} + /** Credential value → `$VAR` string; collects the referenced secret name. */ function credentialString( value: string | { readonly $secret: string }, @@ -408,13 +432,28 @@ function mapAgent( }); } + const platforms: DesiredPlatform[] = (agent.platforms ?? []).map((p) => ({ + stableId: platformStableId(agent.id, p.type, p.name), + type: p.type, + ...(p.name ? { name: p.name } : {}), + // Keep `$VAR` placeholders in the stored config (resolved at egress); the + // referenced secrets are collected into `required` for the secrets gate. + config: Object.fromEntries( + Object.entries(p.config).map(([k, v]) => [ + k, + credentialString(v, required), + ]) + ), + ...(p.channels?.length ? { channels: p.channels } : {}), + })); + const metadata: DesiredAgentMetadata = { agentId: agent.id, name: agent.name ?? agent.id, }; if (agent.description) metadata.description = agent.description; - return { metadata, settings, platforms: [], providerKeys }; + return { metadata, settings, platforms, providerKeys }; } function mapEntityType(entity: EntityType): DesiredEntityType { diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index 5323f24df..6385c3a89 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -25,6 +25,7 @@ import type { RemoteConnection, RemoteEntityType, RemoteFeed, + RemotePlatform, RemoteRelationshipType, RemoteWatcher, } from "../apply/client.js"; @@ -199,6 +200,7 @@ interface EmittedAgent { function emitAgent( agent: RemoteAgent, settings: AgentSettings | null, + platforms: RemotePlatform[], imports: ImportTracker, secrets: SecretCollector, minter: IdentMinter @@ -342,6 +344,32 @@ function emitAgent( }); } + // platforms ← live platform bindings. The route stores `platform` inside + // `config` for stable-id matching; strip it. `$VAR` config values round-trip + // as secret() refs (the stored config keeps placeholders, not raw secrets). + if (platforms.length > 0) { + const items = platforms.map((p) => { + const cfg: Record = { ...(p.config ?? {}) }; + delete cfg.platform; + const cfgLines = Object.entries(cfg).map(([k, v]) => { + if (typeof v === "string") { + const m = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(v); + if (m?.[1]) { + imports.use("secret"); + return `${k}: ${secrets.ref(m[1])}`; + } + return `${k}: ${str(v)}`; + } + return `${k}: ${emitValue(v, 3)}`; + }); + return objectLiteral( + [`type: ${str(p.platform)}`, `config: ${objectLiteral(cfgLines, 3)}`], + 2 + ); + }); + fields.push(`platforms: [\n ${items.join(",\n ")},\n ]`); + } + const handleName = minter.mint(agent.agentId, "Agent"); const decl = `const ${handleName} = defineAgent(${objectLiteral(fields, 0)});`; return { handle: { name: handleName, decl }, files }; @@ -662,7 +690,11 @@ function emitConnection( // ── Fetch the org's full declared state ───────────────────────────────────── interface FetchedState { - agents: Array<{ agent: RemoteAgent; settings: AgentSettings | null }>; + agents: Array<{ + agent: RemoteAgent; + settings: AgentSettings | null; + platforms: RemotePlatform[]; + }>; entityTypes: RemoteEntityType[]; relationshipTypes: RemoteRelationshipType[]; watchers: Array<{ watcher: RemoteWatcher; reactionScript: string | null }>; @@ -694,6 +726,7 @@ async function fetchOrgState(client: ApplyClient): Promise { .map(async (agent) => ({ agent, settings: await client.getAgentSettings(agent.agentId), + platforms: await client.listPlatforms(agent.agentId), })) ); @@ -766,8 +799,15 @@ export function generateProject( // Agents first (watchers reference their handles). const agentHandles = new Map(); const agentDecls: string[] = []; - for (const { agent, settings } of state.agents) { - const emitted = emitAgent(agent, settings, imports, secrets, minter); + for (const { agent, settings, platforms } of state.agents) { + const emitted = emitAgent( + agent, + settings, + platforms, + imports, + secrets, + minter + ); agentHandles.set(agent.agentId, emitted.handle.name); agentDecls.push(emitted.handle.decl); files.push(...emitted.files); diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index c18ed35da..ca15b1cb9 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -686,6 +686,7 @@ export async function initCommand( includeLobuMemory, lobuOrg: includeLobuMemory ? projectName : undefined, lobuName: includeLobuMemory ? humanizeSlug(projectName) : undefined, + ...(platformType ? { platformType, platformConfig } : {}), }); const variables = { @@ -978,6 +979,10 @@ export async function generateLobuConfig( lobuOrg?: string; lobuName?: string; lobuDescription?: string; + /** Chat platform to author (e.g. "telegram"); omit to scaffold none. */ + platformType?: string; + /** Platform config; `$VAR` values are emitted as `secret("VAR")`. */ + platformConfig?: Record; } ): Promise { const id = options.agentName; @@ -1022,6 +1027,25 @@ export async function generateLobuConfig( " }," ); + if (options.platformType && options.platformConfig) { + const configLines = Object.entries(options.platformConfig).map(([k, v]) => { + const m = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(v); + return m + ? ` ${k}: secret(${JSON.stringify(m[1])}),` + : ` ${k}: ${JSON.stringify(v)},`; + }); + agentFields.push( + " platforms: [", + " {", + ` type: ${JSON.stringify(options.platformType)},`, + " config: {", + ...configLines, + " },", + " },", + " ]," + ); + } + if (options.enableSlackPreview) { agentFields.push( " // Hosted preview — `lobu run` prints a `/lobu link ` you redeem", diff --git a/packages/sdk/src/define.ts b/packages/sdk/src/define.ts index 1d3c08025..6082d3b21 100644 --- a/packages/sdk/src/define.ts +++ b/packages/sdk/src/define.ts @@ -227,6 +227,25 @@ export interface McpServer { env?: Record; } +/** A chat-platform binding for an agent (Telegram/Slack/Discord/…). */ +export interface Platform { + /** Platform type: `telegram`, `slack`, `discord`, `whatsapp`, `teams`, `google_chat`, `rest`, … */ + type: string; + /** + * Optional display name. Also disambiguates multiple platforms of the same + * type on one agent (it feeds the stable id `apply` matches on). + */ + name?: string; + /** + * Platform config (e.g. `{ botToken: secret("TELEGRAM_BOT_TOKEN") }`). Values + * are `secret(...)` refs or literal `$VAR` strings; `lobu apply` keeps the + * `$VAR` placeholder in the stored config and resolves it at egress. + */ + config: Record; + /** Declarative channel bindings (`"/"`); Slack only. */ + channels?: string[]; +} + /** Hosted "Lobu Developer" preview-bot config for one chat platform. */ export interface PreviewConfig { enabled?: boolean; @@ -257,15 +276,17 @@ export interface Agent { nixPackages?: string[]; /** Custom MCP servers, keyed by id. */ mcpServers?: Record; + /** Chat-platform bindings (`lobu apply` upserts each by a stable id). */ + platforms?: Platform[]; /** * Hosted preview-bot config, keyed by chat platform (`slack`/`telegram`). * Consumed by `lobu run` (dev-time only) — not part of cloud apply. */ preview?: Record; - // NOTE: connections and the memory schema are declared at the project level - // (`defineConfig({ connections, entities, relationships })`), matching the - // apply model — there is no agent-scoped association in DesiredState. Agent - // fields for them were removed rather than left silently ignored. + // NOTE: the memory schema (entity/relationship types) and connections are + // declared at the PROJECT level (`defineConfig({ entities, relationships, + // connections })`), matching the apply model. Chat platforms, however, ARE + // agent-scoped (each agent owns its bindings) and map to DesiredAgent.platforms. } export function defineAgent(config: Omit): Agent { From 42dce0a31ab04d4ded68287fb48627da363dd0af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 13:12:17 +0100 Subject: [PATCH 43/65] fix(cli): platform config diff ignores redacted/secret-ref values (idempotent apply) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A config-authored chat platform restarted on EVERY `lobu apply`: the diff compared the desired config (`botToken: "$TELEGRAM_BOT_TOKEN"`) against the GET round-trip, where the server redacts the secret (`"***oken"`) and rewrites the $VAR into an internal `secret://…` reference. Neither round-trips, so the config never matched and the platform was needlessly updated + restarted, dropping in-flight messages. Treat a key as unchanged when the desired value is a $VAR placeholder and the remote value is opaque (redacted or secret://), mirroring the auth-profile credentials rule; real (non-secret) config changes still surface as updates. --- packages/cli/src/commands/_lib/apply/diff.ts | 64 +++++++++++++++++--- 1 file changed, 55 insertions(+), 9 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index 2839b72d5..1f4b96c5e 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -361,6 +361,60 @@ function diffSettings( }; } +/** + * A platform-config value the CLI can't read back, so it must not drive a diff: + * - the server redacts secrets in the GET response (`***`-suffixed), and + * - it rewrites a `$VAR` placeholder into an internal `secret://…` reference. + * Either form is opaque — the cleartext never round-trips. + */ +function isOpaqueRemoteConfigValue(value: unknown): boolean { + return ( + typeof value === "string" && + (value.startsWith("***") || value.startsWith("secret://")) + ); +} + +/** A desired value that resolves to a secret at egress (a `$VAR` placeholder). */ +function isSecretPlaceholder(value: unknown): boolean { + return typeof value === "string" && value.startsWith("$"); +} + +/** + * Compare a desired platform config against the remote one for drift. + * + * Two adjustments keep an unchanged platform a noop instead of restarting it on + * every apply: + * - the route handler stores `platform` inside `config` for stable-id + * matching, so the GET round-trip carries an extra `platform` key the CLI + * never wrote — strip it before diffing; + * - secret-bearing keys (`botToken`, app secrets, …) come back redacted or as + * a `secret://` reference, never the cleartext the CLI sent as `$VAR`. When + * the desired value is a `$VAR` placeholder and the remote value is opaque, + * treat them as equal (the credential write path is idempotent and re-pushes + * rotated secrets on its own, mirroring the auth-profile credentials rule). + */ +function platformConfigChanged( + desired: Record, + remote: Record | undefined +): boolean { + const remoteConfig: Record = { ...(remote ?? {}) }; + delete remoteConfig.platform; + const desiredConfig: Record = { ...desired }; + delete desiredConfig.platform; + + const keys = new Set([ + ...Object.keys(desiredConfig), + ...Object.keys(remoteConfig), + ]); + for (const key of keys) { + const d = desiredConfig[key]; + const r = remoteConfig[key]; + if (isSecretPlaceholder(d) && isOpaqueRemoteConfigValue(r)) continue; + if (!deepEqual(d, r)) return true; + } + return false; +} + function diffPlatform( agentId: string, desired: DesiredPlatform, @@ -376,15 +430,7 @@ function diffPlatform( { name: "type", changed: (d, r) => d.type !== r.platform }, { name: "config", - changed: (d, r) => { - // The route handler stores `platform` inside `config` for stable-id - // matching, so a noop round-trip from GET will have an extra - // `platform` key the CLI never wrote. Strip it before diffing so an - // unchanged platform doesn't show as drift on every plan. - const remoteConfig: Record = { ...(r.config ?? {}) }; - delete remoteConfig.platform; - return !deepEqual(d.config, remoteConfig); - }, + changed: (d, r) => platformConfigChanged(d.config, r.config), }, ], updateExtras: (changed) => ({ From e7ebff9a256498a785bcff0db9ac8d2e7e9dd1be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 13:12:59 +0100 Subject: [PATCH 44/65] test(cli): platform config diff treats redacted/secret-ref values as noop Locks the idempotent-apply behavior: a $VAR secret placeholder matching a redacted (***) or secret:// remote value is a noop, while a real non-secret config change still surfaces as an update. --- .../_lib/apply/__tests__/diff.test.ts | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index d63644548..714d8b5a7 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -267,6 +267,83 @@ describe("apply diff — platforms", () => { } expect(renderPlan(plan)).toMatchSnapshot(); }); + + // A `$VAR` secret placeholder never round-trips: the server returns the secret + // redacted (`***`) or as an internal `secret://…` reference. Either form must + // be treated as unchanged so the platform isn't needlessly restarted. + test.each([ + ["redacted (***)", "***oken"], + ["secret:// reference", "secret://connections%2Ftriage-telegram%2FbotToken"], + ])("noop when desired $VAR matches remote %s", (_label, remoteValue) => { + const desired = buildState([ + buildDesiredAgent("triage", { + metadata: { agentId: "triage", name: "Triage" }, + platforms: [ + { + stableId: "triage-telegram", + type: "telegram", + config: { botToken: "$TELEGRAM_BOT_TOKEN" }, + }, + ], + }), + ]); + const remote: RemoteSnapshot = { + ...emptyRemote(), + agents: [{ agentId: "triage", name: "Triage" }], + agentSettings: new Map([["triage", null]]), + platformsByAgent: new Map([ + [ + "triage", + [ + { + id: "triage-telegram", + platform: "telegram", + // GET round-trip carries the `platform` key + the opaque secret. + config: { platform: "telegram", botToken: remoteValue }, + }, + ], + ], + ]), + }; + const plan = computeDiff(desired, remote); + const platformRow = plan.rows.find((r) => r.kind === "platform"); + expect(platformRow?.verb).toBe("noop"); + }); + + test("update when a non-secret config field changes (secret still opaque)", () => { + const desired = buildState([ + buildDesiredAgent("triage", { + metadata: { agentId: "triage", name: "Triage" }, + platforms: [ + { + stableId: "triage-telegram", + type: "telegram", + config: { botToken: "$TELEGRAM_BOT_TOKEN", mode: "webhook" }, + }, + ], + }), + ]); + const remote: RemoteSnapshot = { + ...emptyRemote(), + agents: [{ agentId: "triage", name: "Triage" }], + agentSettings: new Map([["triage", null]]), + platformsByAgent: new Map([ + [ + "triage", + [ + { + id: "triage-telegram", + platform: "telegram", + config: { platform: "telegram", botToken: "***oken", mode: "polling" }, + }, + ], + ], + ]), + }; + const plan = computeDiff(desired, remote); + const platformRow = plan.rows.find((r) => r.kind === "platform"); + expect(platformRow?.verb).toBe("update"); + }); }); describe("apply diff — memory schema", () => { From 647790fea2f162d3f26eb783edfddc836046a760 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 13:15:53 +0100 Subject: [PATCH 45/65] fix(cli): init-from-org emits secret() for redacted platform config values MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bootstrap assumed stored platform config kept $VAR placeholders, but the server rewrites $VAR into an internal secret:// reference and the GET masks it (***-suffixed). Neither matched the $VAR regex, so a redacted botToken was emitted as the literal "***oken" — re-applying the generated config would push that broken value. Recognize redacted (***) and secret:// values and emit a deterministic secret("__") placeholder (collected into .env.example), mirroring how provider keys round-trip. Non-secret config fields stay literals. --- .../__tests__/init-from-org.test.ts | 54 +++++++++++++++++++ .../commands/_lib/init-from-org/bootstrap.ts | 20 +++++-- 2 files changed, 69 insertions(+), 5 deletions(-) diff --git a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts index 6a5ce77cc..ff598c009 100644 --- a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts +++ b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts @@ -379,4 +379,58 @@ describe("lobu init --from-org", () => { expect(state.watchers).toHaveLength(0); expect(state.connectors.connections).toHaveLength(0); }); + + test("platform secret config → secret() placeholder, never the redacted literal", async () => { + const dir = mkFixtureDir(); + await initFromOrg({ + targetDir: dir, + fetchImpl: buildFetch({ + "/oauth/userinfo": () => ({ + organizations: [{ id: "org-1", slug: "acme", name: "Acme Inc" }], + }), + "/agents/bot/platforms": () => ({ + platforms: [ + { + id: "bot-telegram", + platform: "telegram", + // GET round-trip: `platform` key + redacted secret + a literal. + config: { + platform: "telegram", + botToken: "***oken", + mode: "webhook", + }, + }, + ], + }), + "/agents/bot/config": () => ({ updatedAt: 0 }), + "/agents": () => ({ agents: [{ agentId: "bot", name: "Bot" }] }), + "watchers?include_details": () => ({ watchers: [] }), + manage_entity_schema: () => ({ + entity_types: [], + relationship_types: [], + }), + manage_auth_profiles: () => ({ auth_profiles: [] }), + manage_connections: () => ({ connections: [] }), + }), + }); + + const source = readFileSync(join(dir, "lobu.config.ts"), "utf-8"); + // The secret is emitted as a secret() ref (env name derived from agent+key), + // never the opaque `***oken` literal; the non-secret `mode` stays a literal. + expect(source).toContain('botToken: secret("BOT_TELEGRAM_BOTTOKEN")'); + expect(source).not.toContain("***oken"); + expect(source).toContain('mode: "webhook"'); + + // Round-trips: the regenerated config loads back into DesiredState. + process.env.BOT_TELEGRAM_BOTTOKEN = "dummy-token-value"; + try { + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + const platform = state.agents[0]?.platforms[0]; + expect(platform?.type).toBe("telegram"); + expect(platform?.config.botToken).toBe("$BOT_TELEGRAM_BOTTOKEN"); + expect(platform?.config.mode).toBe("webhook"); + } finally { + process.env.BOT_TELEGRAM_BOTTOKEN = undefined; + } + }); }); diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index 6385c3a89..e8efbc556 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -345,18 +345,28 @@ function emitAgent( } // platforms ← live platform bindings. The route stores `platform` inside - // `config` for stable-id matching; strip it. `$VAR` config values round-trip - // as secret() refs (the stored config keeps placeholders, not raw secrets). + // `config` for stable-id matching; strip it. Secret-bearing config values + // never round-trip in the clear: the server rewrites a `$VAR` into a + // `secret://…` reference and the GET masks it (`***`-suffixed). Both forms, + // plus a bare `$VAR`, become `secret("")` placeholders the operator + // fills in `.env` before re-applying — emitting the redacted/ref literal + // would push a broken token on the next apply. if (platforms.length > 0) { const items = platforms.map((p) => { const cfg: Record = { ...(p.config ?? {}) }; delete cfg.platform; const cfgLines = Object.entries(cfg).map(([k, v]) => { if (typeof v === "string") { - const m = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(v); - if (m?.[1]) { + const explicitVar = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(v); + if (explicitVar?.[1]) { imports.use("secret"); - return `${k}: ${secrets.ref(m[1])}`; + return `${k}: ${secrets.ref(explicitVar[1])}`; + } + // Opaque secret (redacted `***…` or internal `secret://…`): derive a + // deterministic env-var name from the agent + config key. + if (v.startsWith("***") || v.startsWith("secret://")) { + imports.use("secret"); + return `${k}: ${secrets.ref(envVarFor(agent.agentId, `${p.platform}_${k}`.toUpperCase()))}`; } return `${k}: ${str(v)}`; } From cd6e6dfacedf5ca0deb557bb0504a44e0b453118 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 13:16:20 +0100 Subject: [PATCH 46/65] style(cli): biome formatting for platform diff tests --- .../src/commands/_lib/apply/__tests__/diff.test.ts | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index 714d8b5a7..1e0f7e23d 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -273,7 +273,10 @@ describe("apply diff — platforms", () => { // be treated as unchanged so the platform isn't needlessly restarted. test.each([ ["redacted (***)", "***oken"], - ["secret:// reference", "secret://connections%2Ftriage-telegram%2FbotToken"], + [ + "secret:// reference", + "secret://connections%2Ftriage-telegram%2FbotToken", + ], ])("noop when desired $VAR matches remote %s", (_label, remoteValue) => { const desired = buildState([ buildDesiredAgent("triage", { @@ -334,7 +337,11 @@ describe("apply diff — platforms", () => { { id: "triage-telegram", platform: "telegram", - config: { platform: "telegram", botToken: "***oken", mode: "polling" }, + config: { + platform: "telegram", + botToken: "***oken", + mode: "polling", + }, }, ], ], From 1090ce05682b04ea191e7eef26c92bf58568645e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 13:30:09 +0100 Subject: [PATCH 47/65] fix(platforms): store the resolved secret value, not the $VAR placeholder MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Final ship-verdict pi caught that config-authored platform secrets were broken: the server's normalizeConfigForStorage persists whatever plaintext the CLI sends as the secret (then swaps it for a secret:// ref), so sending the $VAR placeholder stored a literal '$TELEGRAM_BOT_TOKEN' as the bot token — a dead connection. Fixes: - mapAgent resolves platform config secret()/$VAR to the REAL env value (resolveCredentialValue), mirroring provider keys + auth-profile credentials; the config row still never holds cleartext at rest (server-side secret store). - diffPlatform now treats a config key as unchanged when the REMOTE value is opaque (***/secret://) regardless of the desired form — desired is now the resolved value, so the prior $VAR-keyed check would restart every apply. - mapAgent rejects two platforms whose names slugify to the same stable id. - init-from-org recovers the name from the stable id so NAMED platforms re-derive the same id (no drift/duplicate on re-apply). Unit-tested (resolved values + collision + named round-trip); the prior round-trip test updated to assert the resolved value. 302 CLI tests green. --- .../_lib/apply/__tests__/map-config.test.ts | 31 +++++++++++++++---- packages/cli/src/commands/_lib/apply/diff.ts | 13 ++++---- .../cli/src/commands/_lib/apply/map-config.ts | 21 +++++++++++-- .../__tests__/init-from-org.test.ts | 4 ++- .../commands/_lib/init-from-org/bootstrap.ts | 20 +++++++++--- 5 files changed, 69 insertions(+), 20 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index 13bde7620..025c76eb7 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -58,7 +58,7 @@ describe("mapProjectToDesiredState", () => { expect(state.memory).toEqual({ org: "o" }); }); - test("maps agent platforms: stable id + $VAR config kept as placeholder + secret collected", () => { + test("maps agent platforms: stable id + RESOLVED secret values + literals + collected secrets", () => { const bot = defineAgent({ id: "support-bot", platforms: [ @@ -74,20 +74,26 @@ describe("mapProjectToDesiredState", () => { }, ], }); + // The server stores the incoming plaintext as the secret, so the mapper + // must send the RESOLVED env value (not the `$VAR` placeholder). + const platformEnv: NodeJS.ProcessEnv = { + ...env, + TELEGRAM_BOT_TOKEN: "tg-real-token", + SLACK_BOT_TOKEN: "sk-real-token", + }; const state = mapProjectToDesiredState( defineConfig({ org: "o", agents: [bot] }), - env + platformEnv ); const platforms = state.agents[0]?.platforms ?? []; expect(platforms).toHaveLength(2); // Stable id is deterministic from (agentId, type, name?). expect(platforms[0]?.stableId).toBe("support-bot-telegram"); expect(platforms[1]?.stableId).toBe("support-bot-slack-ops"); - // `$VAR`/secret() placeholders are kept in config (resolved at egress), - // literals pass through, and the referenced secrets are collected. - expect(platforms[0]?.config).toEqual({ botToken: "$TELEGRAM_BOT_TOKEN" }); + // secret()/$VAR resolve to the real value; literals pass through. + expect(platforms[0]?.config).toEqual({ botToken: "tg-real-token" }); expect(platforms[1]?.config).toEqual({ - botToken: "$SLACK_BOT_TOKEN", + botToken: "sk-real-token", appType: "MultiTenant", }); expect(platforms[1]?.channels).toEqual(["T1/C1"]); @@ -95,6 +101,19 @@ describe("mapProjectToDesiredState", () => { expect(state.requiredSecrets).toContain("SLACK_BOT_TOKEN"); }); + test("rejects two platforms whose names collapse to the same stable id", () => { + const bot = defineAgent({ + id: "bot", + platforms: [ + { type: "slack", name: "ops", config: {} }, + { type: "slack", name: "ops!", config: {} }, + ], + }); + expect(() => + mapProjectToDesiredState(defineConfig({ org: "o", agents: [bot] }), env) + ).toThrow(/same id|distinct names/i); + }); + test("maps entities + relationships with typed-handle slugs", () => { const person = defineEntityType({ key: "person", name: "Person" }); const org = defineEntityType({ key: "org" }); diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index 1f4b96c5e..a646d3f54 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -374,11 +374,6 @@ function isOpaqueRemoteConfigValue(value: unknown): boolean { ); } -/** A desired value that resolves to a secret at egress (a `$VAR` placeholder). */ -function isSecretPlaceholder(value: unknown): boolean { - return typeof value === "string" && value.startsWith("$"); -} - /** * Compare a desired platform config against the remote one for drift. * @@ -409,7 +404,13 @@ function platformConfigChanged( for (const key of keys) { const d = desiredConfig[key]; const r = remoteConfig[key]; - if (isSecretPlaceholder(d) && isOpaqueRemoteConfigValue(r)) continue; + // Secret-bearing keys come back opaque (redacted `***` or a `secret://` + // ref), so the resolved cleartext the CLI sent can never round-trip-match. + // Treat an opaque remote value as unchanged (write-only secret, like + // auth-profile credentials) so the platform isn't needlessly restarted; + // non-secret fields still diff normally. (A rotated secret isn't + // auto-detected here — re-push it explicitly if needed.) + if (isOpaqueRemoteConfigValue(r)) continue; if (!deepEqual(d, r)) return true; } return false; diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index 7f3be5844..21f1d5889 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -436,16 +436,31 @@ function mapAgent( stableId: platformStableId(agent.id, p.type, p.name), type: p.type, ...(p.name ? { name: p.name } : {}), - // Keep `$VAR` placeholders in the stored config (resolved at egress); the - // referenced secrets are collected into `required` for the secrets gate. + // Resolve `secret()`/`$VAR` to the REAL value — the platform-write path + // stores the incoming plaintext as the secret (server-side + // `normalizeConfigForStorage` swaps it for a `secret://` ref + encrypts it), + // so sending the `$VAR` placeholder would persist a broken token. Mirrors + // provider keys + auth-profile credentials. The config row never holds + // cleartext at rest; the secret name is collected for the secrets gate. config: Object.fromEntries( Object.entries(p.config).map(([k, v]) => [ k, - credentialString(v, required), + resolveCredentialValue(v, required, env), ]) ), ...(p.channels?.length ? { channels: p.channels } : {}), })); + // Distinct platforms must not collapse to the same stable id (e.g. names that + // slugify equal), or apply would clobber one with the other. + const seenStableIds = new Set(); + for (const p of platforms) { + if (seenStableIds.has(p.stableId)) { + throw new ValidationError( + `agent "${agent.id}" has two platforms that resolve to the same id "${p.stableId}" — give them distinct names` + ); + } + seenStableIds.add(p.stableId); + } const metadata: DesiredAgentMetadata = { agentId: agent.id, diff --git a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts index ff598c009..8678b33a0 100644 --- a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts +++ b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts @@ -427,7 +427,9 @@ describe("lobu init --from-org", () => { const { state } = await loadDesiredStateFromConfig({ cwd: dir }); const platform = state.agents[0]?.platforms[0]; expect(platform?.type).toBe("telegram"); - expect(platform?.config.botToken).toBe("$BOT_TELEGRAM_BOTTOKEN"); + // The secret() ref resolves to the real env value (the server stores the + // incoming plaintext as the secret), not the `$VAR` placeholder. + expect(platform?.config.botToken).toBe("dummy-token-value"); expect(platform?.config.mode).toBe("webhook"); } finally { process.env.BOT_TELEGRAM_BOTTOKEN = undefined; diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index e8efbc556..d55b64e60 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -372,10 +372,22 @@ function emitAgent( } return `${k}: ${emitValue(v, 3)}`; }); - return objectLiteral( - [`type: ${str(p.platform)}`, `config: ${objectLiteral(cfgLines, 3)}`], - 2 - ); + // Recover the name from the stable id (`-[-]`) so a + // NAMED platform re-derives the same id on apply (no drift/duplicate). + const slug = (s: string) => + s + .toLowerCase() + .replace(/[^a-z0-9]+/g, "-") + .replace(/^-+|-+$/g, ""); + const prefix = `${slug(agent.agentId)}-${slug(p.platform)}`; + const nameSlug = + p.id && p.id.startsWith(`${prefix}-`) + ? p.id.slice(prefix.length + 1) + : undefined; + const platformFields = [`type: ${str(p.platform)}`]; + if (nameSlug) platformFields.push(`name: ${str(nameSlug)}`); + platformFields.push(`config: ${objectLiteral(cfgLines, 3)}`); + return objectLiteral(platformFields, 2); }); fields.push(`platforms: [\n ${items.join(",\n ")},\n ]`); } From 6f98f4b65220ec4eb4963ce0ab948b70ac4a66d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 13:54:28 +0100 Subject: [PATCH 48/65] =?UTF-8?q?docs(cli):=20correct=20generateLobuConfig?= =?UTF-8?q?=20comment=20=E2=80=94=20platforms=20ARE=20config-authored?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prior comment ('Chat platforms ... are NOT authored here') was added in this same migration to rationalize dropping platforms; it was never an external product decision, and platforms were config-driven on main via lobu.toml [[agents.platforms]]. Now that defineAgent({ platforms }) is restored, the comment was both stale and the source of a wrong 'platforms are UI-only' assumption. Fix it to reflect reality. --- packages/cli/src/commands/init.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index ca15b1cb9..943a7db06 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -961,10 +961,10 @@ function humanizeSlug(slug: string): string { /** * Scaffold the project's `lobu.config.ts` — the single TypeScript entrypoint * `lobu apply` (and `lobu run`) read. Emits a `defineAgent` (providers, - * network, optional Slack preview) and a `defineConfig` default export with the - * org metadata. Chat platforms and the memory schema are NOT authored here: - * connections are created via the `/agents` UI / CRUD API, and entity / - * relationship types are added later with `defineEntityType` / `defineConfig`. + * network, the chosen chat platform, optional Slack preview) and a + * `defineConfig` default export with the org metadata. Memory-schema types + * (entity / relationship) are added later with `defineEntityType` etc.; chat + * platforms can also still be wired up in the `/agents` UI after apply. */ export async function generateLobuConfig( projectDir: string, From f6eb2b6ca85c3230784a8a2307da9797d420c9cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 14:10:52 +0100 Subject: [PATCH 49/65] fix(cli): init-from-org emits real auth-schema credential keys MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit emitAuthProfile derived the credential KEY from the env-var name (_VALUE / _CLIENT_SECRET), but lobu apply sends credentials: { : } and the server validates against the connector's auth_schema — so a non-schema key is rejected. Plumb listConnectorDefinitions(true) through fetchOrgState and emit credentials keyed by each connector's real required auth-schema field (or all properties when none are required), with a deterministic _ env-var placeholder. Falls back to the prior single placeholder + TODO when the connector/auth_schema isn't found. --- .../__tests__/init-from-org.test.ts | 87 +++++++++++++++++- .../commands/_lib/init-from-org/bootstrap.ts | 91 +++++++++++++++++-- 2 files changed, 166 insertions(+), 12 deletions(-) diff --git a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts index 8678b33a0..1d2f0db43 100644 --- a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts +++ b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts @@ -25,13 +25,28 @@ function mkFixtureDir(): string { return dir; } -function buildFetch(routes: Record unknown>): typeof fetch { - return (async (input: RequestInfo | URL, _init?: RequestInit) => { +/** + * Route by URL substring. A handler receives the parsed request body so routes + * sharing a URL (e.g. `manage_connections` carries both `list_connections` and + * `list_connector_definitions` actions) can branch on the body `action`. + */ +function buildFetch( + routes: Record) => unknown> +): typeof fetch { + return (async (input: RequestInfo | URL, init?: RequestInit) => { const url = String(input); + let body: Record = {}; + if (typeof init?.body === "string") { + try { + body = JSON.parse(init.body) as Record; + } catch { + body = {}; + } + } // Order matters — match the most specific patterns first. for (const [pattern, handler] of Object.entries(routes)) { if (url.includes(pattern)) { - return new Response(JSON.stringify(handler()), { status: 200 }); + return new Response(JSON.stringify(handler(body)), { status: 200 }); } } throw new Error(`unexpected fetch: ${url}`); @@ -380,6 +395,72 @@ describe("lobu init --from-org", () => { expect(state.connectors.connections).toHaveLength(0); }); + test("env auth profile → credentials keyed by the connector's auth-schema field, not _VALUE", async () => { + const dir = mkFixtureDir(); + await initFromOrg({ + targetDir: dir, + fetchImpl: buildFetch({ + "/oauth/userinfo": () => ({ + organizations: [{ id: "org-1", slug: "acme", name: "Acme Inc" }], + }), + "/agents/lone/config": () => ({ updatedAt: 0 }), + "/agents": () => ({ agents: [{ agentId: "lone", name: "Lone" }] }), + "watchers?include_details": () => ({ watchers: [] }), + manage_entity_schema: () => ({ + entity_types: [], + relationship_types: [], + }), + manage_auth_profiles: () => ({ + auth_profiles: [ + { + slug: "stripe-key", + display_name: "Stripe API key", + connector_key: "stripe", + profile_kind: "env", + status: "active", + }, + ], + }), + // Both `list_connections` and `list_connector_definitions` POST here — + // branch on the body action. + manage_connections: (body) => + body.action === "list_connector_definitions" + ? { + connector_definitions: [ + { + key: "stripe", + name: "Stripe", + auth_schema: { + type: "object", + properties: { api_key: { type: "string" } }, + required: ["api_key"], + }, + }, + ], + } + : { connections: [] }, + }), + }); + + const source = readFileSync(join(dir, "lobu.config.ts"), "utf-8"); + // The credential KEY is the connector's real auth-schema field (`api_key`), + // env var derived from slug+field — NOT `STRIPE_KEY_VALUE` as the KEY. + expect(source).toContain("api_key: secret("); + expect(source).toContain('secret("STRIPE_KEY_API_KEY")'); + expect(source).not.toContain("STRIPE_KEY_VALUE"); + // The stale "rename credential keys" TODO is gone once real keys are emitted. + expect(source).not.toContain("rename credential keys"); + + // Round-trips: the credential field survives back through DesiredState. + const env = { STRIPE_KEY_API_KEY: "sk_live_x" } as NodeJS.ProcessEnv; + const { state } = await loadDesiredStateFromConfig({ cwd: dir, env }); + const profile = state.connectors.authProfiles.find( + (p) => p.slug === "stripe-key" + ); + expect(Object.keys(profile?.credentials ?? {})).toEqual(["api_key"]); + expect(profile?.credentials?.api_key).toBe("sk_live_x"); + }); + test("platform secret config → secret() placeholder, never the redacted literal", async () => { const dir = mkFixtureDir(); await initFromOrg({ diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index d55b64e60..0dfebc6a6 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -23,6 +23,7 @@ import type { RemoteAgent, RemoteAuthProfile, RemoteConnection, + RemoteConnectorDefinition, RemoteEntityType, RemoteFeed, RemotePlatform, @@ -164,6 +165,30 @@ function envVarFor(slug: string, suffix: string): string { return `${base}_${suffix}`; } +/** + * The credential field names a connector's auth schema expects. `lobu apply` + * sends `credentials: { : }` and the server validates `` + * against the connector's `auth_schema`, so the emitted credential KEY must be a + * real auth-schema field — not an env-var-derived name. We return the required + * fields (or all `properties` keys when nothing is explicitly required), or + * `null` when the schema has no usable field list (caller falls back). + */ +function authSchemaFields( + schema: Record | null | undefined +): string[] | null { + if (!schema || typeof schema !== "object") return null; + const props = schema.properties; + if (!props || typeof props !== "object") return null; + const allFields = Object.keys(props as Record); + if (allFields.length === 0) return null; + const required = Array.isArray(schema.required) + ? (schema.required as unknown[]).filter( + (r): r is string => typeof r === "string" && allFields.includes(r) + ) + : []; + return required.length > 0 ? required : allFields; +} + // ── Imports tracking ───────────────────────────────────────────────────────── const IMPORTABLE = [ @@ -615,6 +640,7 @@ function emitAuthProfile( p: RemoteAuthProfile, secrets: SecretCollector, connectorHandles: Map, + authSchemas: Map | null | undefined>, imports: ImportTracker, minter: IdentMinter ): Handle | null { @@ -634,19 +660,42 @@ function emitAuthProfile( ]; if (p.display_name) fields.push(`name: ${str(p.display_name)}`); // Credentials are write-only on the server, so we can't recover the real - // values or the connector's exact field names here. Emit secret placeholders - // the operator wires in via .env; the credential KEYS must be renamed to the - // connector's auth-schema fields before applying (see the connector docs). - // Interactive kinds (oauth_account / browser_session) take no credentials. + // values. Emit secret placeholders the operator wires in via .env, keyed by + // the connector's real auth-schema fields — `lobu apply` validates each + // credential KEY against the connector's auth_schema, so an env-var-derived + // key would be rejected. Interactive kinds (oauth_account / browser_session) + // take no credentials. if ( !interactive && (p.profile_kind === "env" || p.profile_kind === "oauth_app") ) { imports.use("secret"); - const credKey = p.profile_kind === "oauth_app" ? "CLIENT_SECRET" : "VALUE"; - fields.push( - `// TODO: rename credential keys to this connector's auth-schema fields\n credentials: {\n ${envVarFor(p.slug, credKey)}: ${secrets.ref(envVarFor(p.slug, credKey))},\n }` - ); + const fieldKeys = authSchemas.has(p.connector_key) + ? authSchemaFields(authSchemas.get(p.connector_key)) + : null; + if (fieldKeys && fieldKeys.length > 0) { + // Emit `credentials: { : secret("_") }` for each real + // auth-schema field, with a deterministic env-var name per field. + const credLines = fieldKeys.map( + (field) => + `${emitKey(field)}: ${secrets.ref( + envVarFor( + p.slug, + field.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase() + ) + )}` + ); + fields.push(`credentials: {\n ${credLines.join(",\n ")},\n }`); + } else { + // No connector def / auth_schema found — fall back to a single + // placeholder. The operator must rename the credential key to the + // connector's auth-schema field before applying. + const credKey = + p.profile_kind === "oauth_app" ? "CLIENT_SECRET" : "VALUE"; + fields.push( + `// TODO: rename credential keys to this connector's auth-schema fields\n credentials: {\n ${envVarFor(p.slug, credKey)}: ${secrets.ref(envVarFor(p.slug, credKey))},\n }` + ); + } } const name = minter.mint(p.slug, "Auth"); return { @@ -722,6 +771,8 @@ interface FetchedState { watchers: Array<{ watcher: RemoteWatcher; reactionScript: string | null }>; authProfiles: RemoteAuthProfile[]; connections: Array<{ connection: RemoteConnection; feeds: RemoteFeed[] }>; + /** connector_key → auth_schema (for emitting real credential field keys). */ + connectorDefinitions: RemoteConnectorDefinition[]; } async function fetchOrgState(client: ApplyClient): Promise { @@ -732,6 +783,7 @@ async function fetchOrgState(client: ApplyClient): Promise { watcherList, authProfiles, connectionList, + connectorDefinitions, ] = await Promise.all([ client.listAgents(), client.listEntityTypes(), @@ -739,6 +791,10 @@ async function fetchOrgState(client: ApplyClient): Promise { client.listWatchers(), client.listAuthProfiles(), client.listConnections(), + // Connector defs carry each connector's auth_schema, so init-from-org can + // emit auth-profile credentials keyed by the real schema fields. Best-effort + // — a fetch failure falls back to placeholder credential keys. + client.listConnectorDefinitions(true).catch(() => []), ]); const agents = await Promise.all( @@ -793,6 +849,7 @@ async function fetchOrgState(client: ApplyClient): Promise { .slice() .sort((a, b) => a.slug.localeCompare(b.slug)), connections, + connectorDefinitions, }; } @@ -855,10 +912,26 @@ export function generateProject( // Auth profiles + connections (connector key referenced by string — no local // connector source is exported, so connectors stay bare string refs). const connectorHandles = new Map(); + // connector_key → auth_schema, so auth profiles emit credentials keyed by the + // connector's real schema fields (validated by `lobu apply`). + const authSchemas = new Map< + string, + Record | null | undefined + >(); + for (const def of state.connectorDefinitions) { + if (def.key) authSchemas.set(def.key, def.auth_schema); + } const authHandles = new Map(); const authDecls: string[] = []; for (const p of state.authProfiles) { - const h = emitAuthProfile(p, secrets, connectorHandles, imports, minter); + const h = emitAuthProfile( + p, + secrets, + connectorHandles, + authSchemas, + imports, + minter + ); if (!h) { warnings.push( `auth profile "${p.slug}" has no connector — skipped (set its connector and re-add it to lobu.config.ts).` From 76d560fbd55494bf7130b90cb3f0db61448bce3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 14:16:06 +0100 Subject: [PATCH 50/65] fix(server): manage_feeds delete proves feed ownership before cancelling runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit handleDeleteFeed cancelled active runs by feed_id BEFORE the org-scoped feed delete confirmed ownership. The run-cancel UPDATE is not org-scoped (runs reach their org only through the feed), so a guessed foreign feed_id could cancel another org's active runs even though the delete then no-ops. Reorder: delete the org-owned feed first, bail on no match, then cancel runs — no cross-org side effect before the ownership check. Adds a cross-org isolation integration test (red before the reorder). --- .../manage-feeds-delete-isolation.test.ts | 109 ++++++++++++++++++ .../server/src/tools/admin/manage_feeds.ts | 16 ++- 2 files changed, 120 insertions(+), 5 deletions(-) create mode 100644 packages/server/src/__tests__/integration/manage-feeds-delete-isolation.test.ts diff --git a/packages/server/src/__tests__/integration/manage-feeds-delete-isolation.test.ts b/packages/server/src/__tests__/integration/manage-feeds-delete-isolation.test.ts new file mode 100644 index 000000000..291948fc6 --- /dev/null +++ b/packages/server/src/__tests__/integration/manage-feeds-delete-isolation.test.ts @@ -0,0 +1,109 @@ +/** + * manage_feeds delete_feed — cross-org isolation. + * + * Regression: `handleDeleteFeed` cancelled active runs by `feed_id` BEFORE + * proving the feed belonged to the caller's org (the run-cancel UPDATE is not + * org-scoped — runs reach their org only through the feed). A guessed foreign + * feed_id could therefore cancel ANOTHER org's runs even though the org-scoped + * feed delete then no-ops. The fix deletes the org-owned feed first and bails + * on no match, so no cross-org side effect happens before the ownership check. + */ + +import { beforeAll, describe, expect, it } from 'vitest'; +import { cleanupTestDatabase, getTestDb } from '../setup/test-db'; +import { + createTestConnection, + createTestOrganization, + createTestUser, +} from '../setup/test-fixtures'; +import { TestApiClient } from '../setup/test-mcp-client'; + +describe('manage_feeds delete_feed cross-org isolation', () => { + let attacker: TestApiClient; + let victimOrgId: string; + let victimFeedId: number; + + beforeAll(async () => { + await cleanupTestDatabase(); + const sql = getTestDb(); + + // Victim org: a connection (which seeds a feed) + an active run on it. + const victimOrg = await createTestOrganization({ name: 'Victim Org' }); + victimOrgId = victimOrg.id; + const victimUser = await createTestUser({ email: 'victim@test.com' }); + const conn = await createTestConnection({ + organization_id: victimOrgId, + connector_key: 'github', + created_by: victimUser.id, + }); + const [feed] = await sql<{ id: number }[]>` + SELECT id FROM feeds WHERE connection_id = ${conn.id} AND organization_id = ${victimOrgId} + LIMIT 1 + `; + victimFeedId = Number(feed?.id); + await sql` + INSERT INTO runs ( + organization_id, run_type, feed_id, connection_id, + connector_key, status, approval_status, created_at + ) VALUES ( + ${victimOrgId}, 'sync', ${victimFeedId}, ${conn.id}, + 'github', 'running', 'auto', NOW() + ) + `; + + // Attacker org: a separate org whose owner will guess the victim's feed_id. + const attackerOrg = await createTestOrganization({ name: 'Attacker Org' }); + const attackerUser = await createTestUser({ email: 'attacker@test.com' }); + attacker = await TestApiClient.for({ + organizationId: attackerOrg.id, + userId: attackerUser.id, + memberRole: 'owner', + }); + }); + + it('does not cancel another org\'s runs and reports the feed as not found', async () => { + const result = (await attacker.feeds.delete(victimFeedId)) as { + error?: string; + deleted?: boolean; + }; + // The foreign delete must no-op with an error, not silently "succeed". + expect(result.error).toBeTruthy(); + expect(result.deleted).toBeUndefined(); + + const sql = getTestDb(); + // The victim's run is untouched (NOT cancelled) — ownership was checked + // before any run-cancel side effect. + const [run] = await sql<{ status: string }[]>` + SELECT status FROM runs + WHERE feed_id = ${victimFeedId} AND organization_id = ${victimOrgId} + LIMIT 1 + `; + expect(run?.status).toBe('running'); + + // The victim's feed is still live (not soft-deleted by the foreign call). + const [feed] = await sql<{ deleted_at: string | null }[]>` + SELECT deleted_at FROM feeds WHERE id = ${victimFeedId} + `; + expect(feed?.deleted_at).toBeNull(); + }); + + it('the legitimate owner can delete the feed and that cancels its active runs', async () => { + const owner = await TestApiClient.for({ + organizationId: victimOrgId, + userId: (await createTestUser({ email: 'victim-owner@test.com' })).id, + memberRole: 'owner', + }); + const result = (await owner.feeds.delete(victimFeedId)) as { + deleted?: boolean; + }; + expect(result.deleted).toBe(true); + + const sql = getTestDb(); + const [run] = await sql<{ status: string }[]>` + SELECT status FROM runs + WHERE feed_id = ${victimFeedId} AND organization_id = ${victimOrgId} + LIMIT 1 + `; + expect(run?.status).toBe('cancelled'); + }); +}); diff --git a/packages/server/src/tools/admin/manage_feeds.ts b/packages/server/src/tools/admin/manage_feeds.ts index 61d2f7a39..6a27edd4d 100644 --- a/packages/server/src/tools/admin/manage_feeds.ts +++ b/packages/server/src/tools/admin/manage_feeds.ts @@ -441,11 +441,11 @@ async function handleDeleteFeed( const sql = getDb(); const { organizationId } = ctx; - await sql` - UPDATE runs SET status = 'cancelled', completed_at = NOW() - WHERE feed_id = ${args.feed_id} AND status = ANY(${runStatusLiteral(ACTIVE_RUN_STATUSES)}::text[]) - `; - + // Prove org ownership BEFORE any side effect: the run-cancel below is not + // org-scoped (runs has no organization_id of its own — it's reached through + // the feed), so cancelling runs first would let a guessed foreign feed_id + // cancel another org's runs even though the delete then no-ops. Delete the + // org-owned feed first and bail when nothing matched. const deleted = await sql` UPDATE feeds SET deleted_at = NOW(), status = 'paused', updated_at = NOW() @@ -457,6 +457,12 @@ async function handleDeleteFeed( return { error: 'Feed not found or already deleted' }; } + // Ownership confirmed — now safe to cancel this feed's active runs. + await sql` + UPDATE runs SET status = 'cancelled', completed_at = NOW() + WHERE feed_id = ${args.feed_id} AND status = ANY(${runStatusLiteral(ACTIVE_RUN_STATUSES)}::text[]) + `; + // Record change event in knowledge for audit trail const feed = deleted[0]; const feedEntityIds = Array.isArray(feed.entity_ids) ? feed.entity_ids : []; From 0b9d625545869c01db47d6d2d84b207b8a6d55c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 14:18:07 +0100 Subject: [PATCH 51/65] docs(server): explain the space delimiter in sync-channels composite key MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The desired-channels Map in the Slack sync-channels route is keyed by `${teamId} ${channelId}`. Document why the single-space separator is collision-safe: the entry regex (`[^/\s]+`) forbids whitespace and slashes in either component, so neither can contain the delimiter and distinct (team, channel) pairs always map to distinct keys. The Map is in-memory and request-scoped (never persisted — the DB keeps team_id and channel_id as separate columns), so there are no stored keys to migrate. Comment-only; no behavior change. --- packages/server/src/lobu/agent-routes.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/packages/server/src/lobu/agent-routes.ts b/packages/server/src/lobu/agent-routes.ts index 13f96b72d..c5693051f 100644 --- a/packages/server/src/lobu/agent-routes.ts +++ b/packages/server/src/lobu/agent-routes.ts @@ -1479,6 +1479,15 @@ routes.post('/:agentId/platforms/:platformId/sync-channels', async (c) => { } // Parse "/" → canonical `slack:` keyed by team. + // + // The `desired` Map is keyed by `${teamId} ${channelId}` (a single space as + // the composite delimiter). A space is collision-safe here because the + // validation regex below (`[^/\s]+`) rejects any teamId/channelId containing + // whitespace or `/`, so neither component can ever contain the separator — + // distinct (team, channel) pairs always produce distinct keys. The Map is + // also purely in-memory and request-scoped (it never persists; the DB stores + // team_id/channel_id as separate columns), so there are no stored keys to + // migrate. Do NOT relax the regex without re-checking this invariant. const desired = new Map(); for (const entry of body.channels) { if (typeof entry !== 'string') { From cc1fbf5e4ce172ce9c3cad2e3cd0366ba829cb82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 14:21:19 +0100 Subject: [PATCH 52/65] fix(client): SSE stream rejects on non-OK/aborted instead of hanging MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The generated hey-api SSE client retries forever by default: a non-OK response (401/404/5xx) or network failure throws inside its read loop, fires onSseError, then sleeps and reconnects with no attempt cap — so a failed stream never terminated and streamEvents' async iterator hung indefinitely. Cap attempts (sseMaxRetryAttempts default 1, overridable via StreamEventsOptions.maxRetryAttempts) and capture the stream error via onSseError into the iterator's error slot so the consumer rejects rather than hanging. Caller-initiated aborts are treated as a clean shutdown, not an error. Adds tests for the 401-rejects and abort-terminates paths (both would hang before this fix). --- packages/client/src/__tests__/client.test.ts | 97 ++++++++++++++++++++ packages/client/src/rest.ts | 16 +++- packages/client/src/types.ts | 7 ++ 3 files changed, 119 insertions(+), 1 deletion(-) diff --git a/packages/client/src/__tests__/client.test.ts b/packages/client/src/__tests__/client.test.ts index 5efb187d0..cae5af5dc 100644 --- a/packages/client/src/__tests__/client.test.ts +++ b/packages/client/src/__tests__/client.test.ts @@ -110,6 +110,103 @@ describe("Lobu", () => { { event: "text", data: "hi", retry: 3000 }, ]); }); + + test("rejects (does not hang) when the SSE stream returns a non-OK status", async () => { + let sseAttempts = 0; + const fetchImpl = (async (input, init) => { + const request = await requestInfo(input, init); + if (request.url.endsWith("/api/v1/agents")) { + return json( + { + success: true, + agentId: "support_user_1", + token: "session-token", + expiresAt: Date.now() + 60_000, + sseUrl: + "https://lobu.test/lobu/api/v1/agents/support_user_1/events", + messagesUrl: + "https://lobu.test/lobu/api/v1/agents/support_user_1/messages", + }, + 201 + ); + } + // The SSE endpoint is unauthorized — without the fix the generated client + // would retry this forever and the iterator would never settle. + sseAttempts++; + return json({ error: "unauthorized" }, 401); + }) as typeof fetch; + + const lobu = new Lobu({ + baseUrl: "https://lobu.test/lobu", + token: "api-token", + fetch: fetchImpl, + }); + const session = await lobu.sessions.create({}); + + let threw: unknown; + const collected: unknown[] = []; + try { + for await (const event of session.events()) collected.push(event); + } catch (error) { + threw = error; + } + + expect(threw).toBeDefined(); + expect((threw as Error).message).toContain("401"); + expect(collected).toEqual([]); + // Default cap is a single attempt — no infinite reconnect loop. + expect(sseAttempts).toBe(1); + }); + + test("terminates cleanly when the caller aborts the stream", async () => { + const controller = new AbortController(); + const fetchImpl = (async (input, init) => { + const request = await requestInfo(input, init); + if (request.url.endsWith("/api/v1/agents")) { + return json( + { + success: true, + agentId: "support_user_1", + token: "session-token", + expiresAt: Date.now() + 60_000, + sseUrl: + "https://lobu.test/lobu/api/v1/agents/support_user_1/events", + messagesUrl: + "https://lobu.test/lobu/api/v1/agents/support_user_1/messages", + }, + 201 + ); + } + // An open stream that yields one event then stays open until aborted. + return new Response( + new ReadableStream({ + start(streamController) { + streamController.enqueue( + new TextEncoder().encode('event: text\ndata: "first"\n\n') + ); + // Never close — the caller's abort must end the iteration. + }, + }), + { status: 200, headers: { "content-type": "text/event-stream" } } + ); + }) as typeof fetch; + + const lobu = new Lobu({ + baseUrl: "https://lobu.test/lobu", + token: "api-token", + fetch: fetchImpl, + }); + const session = await lobu.sessions.create({}); + + const collected: unknown[] = []; + for await (const event of session.events({ signal: controller.signal })) { + collected.push(event); + controller.abort(); // abort right after the first event + } + + // The loop must EXIT (not hang) after the abort; the first event arrived. + expect(collected).toEqual([{ event: "text", data: "first", retry: 3000 }]); + }); }); function json(body: unknown, status = 200): Response { diff --git a/packages/client/src/rest.ts b/packages/client/src/rest.ts index 204205e6a..a22379c10 100644 --- a/packages/client/src/rest.ts +++ b/packages/client/src/rest.ts @@ -94,6 +94,20 @@ export class LobuRestClient { ...headersToRecord(options.headers), }, signal: controller.signal, + // The generated SSE client retries forever by default: a non-OK response + // (401/404/5xx) or a network failure throws inside its read loop, fires + // onSseError, then sleeps and reconnects with no attempt cap — so a + // failed stream NEVER terminates and the async iterator below hangs + // indefinitely. Cap the attempts and surface the error so callers reject + // instead of hanging. An aborted signal already breaks the loop cleanly. + sseMaxRetryAttempts: options.maxRetryAttempts ?? 1, + onSseError: (error) => { + // Don't treat a caller-initiated abort as a stream failure — that path + // is a clean shutdown, not an error to propagate. + if (controller.signal.aborted) return; + if (pumpError === undefined) pumpError = error; + wakeReader(); + }, onSseEvent: (event) => { queue.push({ event: event.event ?? "message", @@ -112,7 +126,7 @@ export class LobuRestClient { // only data payloads, so the queue is the public SDK surface. } } catch (error) { - pumpError = error; + if (pumpError === undefined) pumpError = error; } finally { done = true; wakeReader(); diff --git a/packages/client/src/types.ts b/packages/client/src/types.ts index 0fe8aef73..f2fd9f68f 100644 --- a/packages/client/src/types.ts +++ b/packages/client/src/types.ts @@ -76,4 +76,11 @@ export interface LobuSseEvent { export interface StreamEventsOptions { signal?: AbortSignal; headers?: LobuHeaders; + /** + * Maximum SSE connection attempts before the stream gives up and the async + * iterator rejects. Defaults to 1 (no auto-reconnect): a non-OK response + * (401/404/5xx) or network failure surfaces immediately instead of retrying + * forever. Raise it to opt into reconnects for transient failures. + */ + maxRetryAttempts?: number; } From c0bb70104ca95794682e59267c4e7aa1e38be99c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 15:12:23 +0100 Subject: [PATCH 53/65] feat(apply): config-declared prune, replacing org managed_by flag MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the persistent per-org `managed_by` provenance flag with a config-declared `defineConfig({ prune: true })`. When prune is on, `lobu apply` deletes any org-owned definition (entity/relationship type, watcher, connector definition) absent from the config — including ones created via the dashboard/API. Data, connections, auth profiles, and agents stay exempt. Safety is the existing blast-radius confirm; there is no applied-set tracking and no server-side state. Removed: - migration 20260522120000_organization_managed_by.sql (never shipped) - PATCH /api/:orgSlug/organization/managed-by endpoint - managed_by from getUserInfo organizations[] - RemoteOrg.managed_by, listOrgs parse, setOrgManagedBy - --manage flag + willManage/flipToCodeManaged opt-in flow Kept: org/organizationId consistency hard-stop, confirmDeletions blast-radius gate, the org-owned/public-type filter in computeDiff, and the entity/relationship-type instance-refusal server gate. computeDiff: codeManaged -> prune (logic unchanged). SDK + mapper carry prune into DesiredState. --- ...20260522120000_organization_managed_by.sql | 28 ------- .../_lib/apply/__tests__/apply-cmd.test.ts | 1 + .../_lib/apply/__tests__/client.test.ts | 27 +------ .../apply/__tests__/diff-idempotency.test.ts | 1 + .../_lib/apply/__tests__/diff.test.ts | 25 +++--- .../_lib/apply/__tests__/map-config.test.ts | 12 +++ .../cli/src/commands/_lib/apply/apply-cmd.ts | 77 ++++++------------- .../cli/src/commands/_lib/apply/client.ts | 24 ------ .../src/commands/_lib/apply/desired-state.ts | 7 ++ packages/cli/src/commands/_lib/apply/diff.ts | 31 ++++---- .../cli/src/commands/_lib/apply/map-config.ts | 1 + packages/cli/src/index.ts | 6 -- packages/sdk/src/define.ts | 7 ++ ...managed-by-prune.test.ts => prune.test.ts} | 62 ++------------- packages/server/src/auth/oauth/provider.ts | 4 +- packages/server/src/index.ts | 73 ------------------ 16 files changed, 91 insertions(+), 295 deletions(-) delete mode 100644 db/migrations/20260522120000_organization_managed_by.sql rename packages/server/src/__tests__/integration/{managed-by-prune.test.ts => prune.test.ts} (68%) diff --git a/db/migrations/20260522120000_organization_managed_by.sql b/db/migrations/20260522120000_organization_managed_by.sql deleted file mode 100644 index 54b27a1b2..000000000 --- a/db/migrations/20260522120000_organization_managed_by.sql +++ /dev/null @@ -1,28 +0,0 @@ --- migrate:up - --- Org provenance. 'code' means the org's definitions (entity types, --- relationship types, watchers, connector definitions) are owned by a --- `lobu.config.ts` and `lobu apply` PRUNES definitions removed from it; 'ui' --- (the default) means apply never deletes — the dashboard/API are free to add --- definitions without a config rewriting them away. --- --- SAFETY: the NOT NULL DEFAULT 'ui' backfills every existing org to 'ui', so no --- org starts out prunable. An org only becomes code-managed via the explicit --- one-time `lobu apply --manage` opt-in. See computeDiff({ codeManaged }) in --- packages/cli/src/commands/_lib/apply/diff.ts. - -ALTER TABLE public.organization - ADD COLUMN IF NOT EXISTS managed_by text NOT NULL DEFAULT 'ui'; - -ALTER TABLE public.organization - DROP CONSTRAINT IF EXISTS organization_managed_by_check; -ALTER TABLE public.organization - ADD CONSTRAINT organization_managed_by_check - CHECK (managed_by IN ('ui', 'code')); - --- migrate:down - -ALTER TABLE public.organization - DROP CONSTRAINT IF EXISTS organization_managed_by_check; -ALTER TABLE public.organization - DROP COLUMN IF EXISTS managed_by; diff --git a/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd.test.ts index f60b73331..a9905d795 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/apply-cmd.test.ts @@ -11,6 +11,7 @@ import type { DesiredState } from "../desired-state.js"; function stateWith(connectors: DesiredState["connectors"]): DesiredState { return { agents: [], + prune: false, memorySchema: { entityTypes: [], relationshipTypes: [] }, watchers: [], connectors, diff --git a/packages/cli/src/commands/_lib/apply/__tests__/client.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/client.test.ts index c09cb6d27..b6e1269f7 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/client.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/client.test.ts @@ -123,7 +123,7 @@ describe("ApplyClient", () => { }); }); -describe("ApplyClient — code-managed prune", () => { +describe("ApplyClient — prune", () => { function recordingClient(responseBody: unknown = { success: true }) { const calls: Array<{ url: string; init?: RequestInit }> = []; const client = new ApplyClient( @@ -169,29 +169,4 @@ describe("ApplyClient — code-managed prune", () => { watcher_ids: ["42"], }); }); - - test("setOrgManagedBy PATCHes the org managed-by endpoint", async () => { - const { calls, client } = recordingClient({ organization: {} }); - await client.setOrgManagedBy("acme", "code"); - expect(calls[0]?.url).toBe( - "https://example.test/api/acme/organization/managed-by" - ); - expect(calls[0]?.init?.method).toBe("PATCH"); - expect(JSON.parse(String(calls[0]?.init?.body))).toEqual({ - managed_by: "code", - }); - }); - - test("listOrgs surfaces managed_by from userinfo", async () => { - const { client } = recordingClient({ - organizations: [ - { id: "o1", slug: "acme", name: "Acme", managed_by: "code" }, - { id: "o2", slug: "beta", name: "Beta" }, - ], - }); - const orgs = await client.listOrgs(); - expect(orgs.find((o) => o.slug === "acme")?.managed_by).toBe("code"); - // Absent managed_by (older server) → undefined, never assumed code. - expect(orgs.find((o) => o.slug === "beta")?.managed_by).toBeUndefined(); - }); }); diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff-idempotency.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff-idempotency.test.ts index 277b01bf3..e46215f7e 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff-idempotency.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff-idempotency.test.ts @@ -33,6 +33,7 @@ function buildState( ): DesiredState { return { agents, + prune: false, memorySchema: { entityTypes: [], relationshipTypes: [] }, watchers: [], connectors: { definitions: [], authProfiles: [], connections: [] }, diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index 1e0f7e23d..8c1e2d2be 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -27,6 +27,7 @@ function buildState( ): DesiredState { return { agents, + prune: false, memorySchema: { entityTypes: [], relationshipTypes: [] }, watchers: [], connectors: { definitions: [], authProfiles: [], connections: [] }, @@ -1081,7 +1082,7 @@ describe("apply diff — connectors", () => { }); }); -describe("apply diff — code-managed prune", () => { +describe("apply diff — prune", () => { // Remote state that has definitions + a connection the desired config drops. function remoteWithExtras(): RemoteSnapshot { return { @@ -1110,7 +1111,7 @@ describe("apply diff — code-managed prune", () => { }); } - test("UI-managed (default) reports removed definitions as drift, never delete", () => { + test("default (prune off) reports removed definitions as drift, never delete", () => { const plan = computeDiff(desiredKeepingLead(), remoteWithExtras()); expect(plan.counts.delete).toBe(0); expect(plan.rows.some((r) => r.verb === "delete")).toBe(false); @@ -1120,9 +1121,9 @@ describe("apply diff — code-managed prune", () => { ).toBe("drift"); }); - test("code-managed deletes removed entity/relationship/watcher/connector definitions", () => { + test("prune deletes removed entity/relationship/watcher/connector definitions", () => { const plan = computeDiff(desiredKeepingLead(), remoteWithExtras(), { - codeManaged: true, + prune: true, }); const deletes = plan.rows.filter((r) => r.verb === "delete"); const deletedIds = deletes.map((r) => `${r.kind}:${r.id}`).sort(); @@ -1139,7 +1140,7 @@ describe("apply diff — code-managed prune", () => { ).toBe("noop"); }); - test("code-managed never deletes data, connections, or agents", () => { + test("prune never deletes data, connections, or agents", () => { const desired = buildState( [ buildDesiredAgent("kept", { @@ -1156,7 +1157,7 @@ describe("apply diff — code-managed prune", () => { agentSettings: new Map([["kept", null]]), platformsByAgent: new Map([["kept", []]]), }; - const plan = computeDiff(desired, remote, { codeManaged: true }); + const plan = computeDiff(desired, remote, { prune: true }); // Connection removed from config is drift (exempt), not delete. expect( plan.rows.find((r) => r.kind === "connection" && r.id === "stale-conn") @@ -1168,7 +1169,7 @@ describe("apply diff — code-managed prune", () => { ).toBe("drift"); }); - test("code-managed prune never deletes public types owned by another org", () => { + test("prune never deletes public types owned by another org", () => { // The list endpoint returns this org's types PLUS public types from other // orgs. With orgId set, a foreign-org type must not be pruned even if it's // absent from the config. @@ -1185,7 +1186,7 @@ describe("apply diff — code-managed prune", () => { ], }; const plan = computeDiff(desiredKeepingLead(), remote, { - codeManaged: true, + prune: true, orgId: "org_self", }); const deletedIds = plan.rows @@ -1216,7 +1217,7 @@ describe("apply diff — code-managed prune", () => { ], }; const plan = computeDiff(desiredKeepingLead(), remote, { - codeManaged: true, + prune: true, orgId: "org_self", }); const leadRow = plan.rows.find( @@ -1242,7 +1243,7 @@ describe("apply diff — code-managed prune", () => { }, }); const plan = computeDiff(desired, remoteWithExtras(), { - codeManaged: true, + prune: true, }); // Can't map remote connectors to the unnamed local def → never delete them. expect( @@ -1254,11 +1255,11 @@ describe("apply diff — code-managed prune", () => { test("delete rows render with a removed-from-config note + summary count", () => { const plan = computeDiff(desiredKeepingLead(), remoteWithExtras(), { - codeManaged: true, + prune: true, }); expect(renderPlan(plan)).toContain("will be deleted"); expect(renderSummary(plan)).toContain("4 delete"); - // UI-managed summary stays clean (no delete part). + // Prune-off summary stays clean (no delete part). expect( renderSummary(computeDiff(desiredKeepingLead(), emptyRemote())) ).not.toContain("delete"); diff --git a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts index 025c76eb7..b245aacbc 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/map-config.test.ts @@ -137,6 +137,18 @@ describe("mapProjectToDesiredState", () => { ]); }); + test("carries prune into DesiredState (defaults false when unset)", () => { + expect(mapProjectToDesiredState(defineConfig({ agents: [] })).prune).toBe( + false + ); + expect( + mapProjectToDesiredState(defineConfig({ agents: [], prune: true })).prune + ).toBe(true); + expect( + mapProjectToDesiredState(defineConfig({ agents: [], prune: false })).prune + ).toBe(false); + }); + test("maps watchers: agent handle, sources record, notification", () => { const crm = defineAgent({ id: "crm" }); const watcher = defineWatcher({ diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index 1edb414a4..784ec9d8c 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -49,13 +49,6 @@ export interface ApplyOptions { url?: string; /** Bypass the project-link guard. */ force?: boolean; - /** - * Opt the target org into code-managed provenance (one-time). Once set, the - * org's `lobu.config.ts` owns its definitions and apply prunes the ones - * removed from it. Persists server-side; subsequent applies prune without - * the flag. `--dry-run` previews the prune without flipping the org. - */ - manage?: boolean; /** Test seam — inject a stubbed fetch. */ fetchImpl?: typeof fetch; } @@ -66,7 +59,7 @@ interface PendingAuthEntry { connectUrl?: string; } -/** Deletes beyond this in one code-managed apply trigger a second confirm. */ +/** Deletes beyond this in one pruning apply trigger a second confirm. */ const BLAST_RADIUS_DELETE_THRESHOLD = 3; // ── Required-secrets check ───────────────────────────────────────────────── @@ -266,7 +259,7 @@ async function fetchRemoteSnapshot( client: ApplyClient, state: DesiredState, only?: "agents" | "memory", - codeManaged = false + prune = false ): Promise { const agents: RemoteAgent[] = only === "memory" ? [] : await client.listAgents(); @@ -293,15 +286,15 @@ async function fetchRemoteSnapshot( only === "agents" ? [] : await client.listRelationshipTypes(); const watchers = only === "agents" ? [] : await client.listWatchers(); - // Connectors run only on a full apply (`--only` skips them). A code-managed - // org also fetches them even when the config declares none, so prune can - // delete a connector definition whose last config reference was removed - // (otherwise an empty desired-connectors set would skip the fetch entirely). + // Connectors run only on a full apply (`--only` skips them). A pruning config + // also fetches them even when it declares none, so prune can delete a + // connector definition whose last config reference was removed (otherwise an + // empty desired-connectors set would skip the fetch entirely). const hasConnectors = state.connectors.definitions.length > 0 || state.connectors.authProfiles.length > 0 || state.connectors.connections.length > 0; - const fetchConnectors = !only && (hasConnectors || codeManaged); + const fetchConnectors = !only && (hasConnectors || prune); const connectorDefinitions = fetchConnectors ? await client.listConnectorDefinitions(true) : []; @@ -939,7 +932,7 @@ async function executePlan( printText(renderProgress(row.verb, "feed", row.id)); } - // 11) Prune — delete definitions removed from a code-managed config. Runs + // 11) Prune — delete definitions absent from a pruning config. Runs // LAST and in reverse-dependency order so a rel-type that references an // entity type is gone before the entity type. Connections + data // instances are never in the delete set (computeDiff only emits delete @@ -949,7 +942,7 @@ async function executePlan( } /** - * Execute the plan's `delete` rows (code-managed prune). Steps run in + * Execute the plan's `delete` rows (prune). Steps run in * reverse-dependency order — a rel-type rule references entity types, so * rel-types delete before entity types; connectors uninstall last. Halts apply * on first failure (idempotent re-run). @@ -1108,12 +1101,11 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { const myOrgs = await client.listOrgs().catch(() => null); // Resolve strictly by the slug we will actually mutate (the client targets // `orgSlug` in every URL). Do NOT fall back to organizationId as an alternate - // org — that could read provenance (managed_by) from a different org than the - // one being applied/pruned. + // org — that could prune a different org than the one being applied. const resolvedOrg = myOrgs?.find((o) => o.slug === orgSlug); // If the config pins `organizationId`, the slug must resolve to that exact // org — otherwise it's a stale/copied config pointed at someone else's org, - // and (under --manage) could prune the wrong org. Hard-stop. + // and (with prune on) could prune the wrong org. Hard-stop. if ( resolvedOrg && state.memory?.organizationId && @@ -1148,31 +1140,19 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { throw new ValidationError(`organization "${orgSlug}" not found`); } - // A code-managed org's lobu.config.ts owns its definitions, so apply prunes - // the ones removed from it (data/connections/agents are never pruned). - // `--manage` opts a UI-managed org into this. The plan is computed as - // code-managed so the prune is shown, but the org is flipped server-side only - // AFTER the plan + deletions are confirmed (`flipToCodeManaged`, below) — a - // cancelled apply must never leave the org flipped. Older servers omit - // `managed_by` → stays UI-managed (safe, no prune). - const orgIsCodeManaged = resolvedOrg?.managed_by === "code"; - const willManage = opts.manage === true && !!resolvedOrg && !orgIsCodeManaged; - const codeManaged = orgIsCodeManaged || willManage; - if (willManage) { + // Prune is config-declared (`defineConfig({ prune: true })`): when on, apply + // deletes any org-owned definition (entity/relationship type, watcher, + // connector definition) that's absent from the config — INCLUDING ones added + // via the dashboard/API. Data, connections, auth profiles, and agents are + // never pruned. The blast-radius confirm below is the safety net. + const prune = state.prune; + if (prune) { printText( chalk.yellow( - opts.dryRun - ? `(dry-run) Org "${orgSlug}" would become code-managed — previewing the prune plan without flipping it.` - : `Org "${orgSlug}" will become code-managed after you confirm — future applies prune definitions removed from lobu.config.ts.` + "Prune is on: apply will DELETE any org-owned definition (entity/relationship type, watcher, connector) that is not in this config — including ones created in the UI." ) ); } - // Idempotent flip, invoked only on a confirmed (non-dry-run) apply. - const flipToCodeManaged = async (): Promise => { - if (!willManage) return; - await client.setOrgManagedBy(orgSlug, "code"); - printText(chalk.yellow(`Org "${orgSlug}" is now code-managed.`)); - }; // Team org consistency comes from `defineConfig({ org, organizationId })` in // lobu.config.ts (committed) plus the `.lobu/project.json` link — apply does @@ -1192,12 +1172,7 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { // this (current/stale) catalog — "create" when the key isn't installed, // "update" when it is. Connector defs are NOT installed here; that happens in // `executePlan`, AFTER plan confirmation. - const remote = await fetchRemoteSnapshot( - client, - state, - opts.only, - codeManaged - ); + const remote = await fetchRemoteSnapshot(client, state, opts.only, prune); // Validate connection/auth-profile config against the catalog we have now, // but SKIP schema validation for connector keys declared locally — those @@ -1211,7 +1186,7 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { const plan = computeDiff(state, remote, { only: opts.only, - codeManaged, + prune, ...(resolvedOrg?.id ? { orgId: resolvedOrg.id } : {}), }); printText(renderPlan(plan)); @@ -1235,8 +1210,6 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { plan.counts.delete === 0 && !hasPendingAuth ) { - // Honor --manage even with an empty plan (no deletes occur this run). - await flipToCodeManaged(); printText(chalk.green("\nNothing to apply.")); return; } @@ -1253,8 +1226,8 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { return; } - // Blast-radius gate: a large code-managed prune gets a second explicit - // confirm beyond the plan approval above. + // Blast-radius gate: a large prune gets a second explicit confirm beyond the + // plan approval above. if (del > BLAST_RADIUS_DELETE_THRESHOLD) { const okToDelete = await confirmDeletions(del, opts.yes ?? false); if (!okToDelete) { @@ -1263,10 +1236,6 @@ export async function applyCommand(opts: ApplyOptions = {}): Promise { } } - // Plan + deletions confirmed — now it's safe to flip the org to code-managed - // (before executePlan, so the deletes run against a code-managed org). - await flipToCodeManaged(); - const pendingAuth: PendingAuthEntry[] = []; let applyErr: unknown; if ( diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index ba16c8222..c76d963a1 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -49,12 +49,6 @@ export interface RemoteOrg { id: string; slug: string; name?: string; - /** - * Provenance: `"code"` means the org's definitions are owned by a - * `lobu.config.ts` and `lobu apply` prunes definitions removed from it; - * `"ui"` (default) means apply never deletes. Absent on older servers. - */ - managed_by?: "ui" | "code"; } export interface RemoteWatcher { @@ -346,29 +340,11 @@ export class ApplyClient { id, slug, ...(typeof entry.name === "string" ? { name: entry.name } : {}), - ...(entry.managed_by === "code" || entry.managed_by === "ui" - ? { managed_by: entry.managed_by } - : {}), }); } return out; } - /** - * Flip an org's provenance to code-managed (the one-time opt-in `lobu apply` - * offers when applying a `lobu.config.ts` to a UI-managed org). Idempotent. - */ - async setOrgManagedBy( - orgSlug: string, - managedBy: "ui" | "code" - ): Promise { - await this.request( - "PATCH", - `/api/${encodeURIComponent(orgSlug)}/organization/managed-by`, - { managed_by: managedBy } - ); - } - // ── Agents ──────────────────────────────────────────────────────────────── async listAgents(): Promise { diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index 860a523c0..a7adb5792 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -190,6 +190,13 @@ export interface DesiredAgent { export interface DesiredState { agents: DesiredAgent[]; + /** + * When true (`defineConfig({ prune: true })`), `lobu apply` deletes org-owned + * definitions (entity/relationship types, watchers, connector definitions) + * absent from this config — including ones created in the UI. Data, + * connections, auth profiles, and agents are never pruned. Default false. + */ + prune: boolean; /** * Org metadata from `defineConfig` — the org slug `lobu apply` defaults to, * the `organizationId` it matches against, and the name/description shown diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index a646d3f54..acd19d13a 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -148,9 +148,9 @@ export interface DiffPlan { noop: number; drift: number; /** - * Definitions removed from the config that apply will delete. Always 0 - * unless the org is code-managed (`computeDiff({ codeManaged: true })`); - * a UI-managed org reports those remote-only definitions as `drift`. + * Definitions absent from the config that apply will delete. Always 0 + * unless the config declares prune (`computeDiff({ prune: true })`); + * otherwise those remote-only definitions are reported as `drift`. */ delete: number; }; @@ -850,14 +850,15 @@ export interface ComputeDiffOptions { /** Limit the diff to a subset of resource kinds. */ only?: "agents" | "memory"; /** - * When true, the org is code-managed: its `lobu.config.ts` is the source of - * truth for *definitions*, so a remote definition (entity type, relationship - * type, watcher, connector definition) absent from desired is emitted as a - * `delete` row instead of an ignored `drift`. Data (entity/relationship - * instances), connections, auth profiles, feeds, agents, and platforms are - * never pruned. Default (false / UI-managed) reports those as `drift`. + * When true, the config declares `prune: true`: it's the source of truth for + * *definitions*, so a remote definition (entity type, relationship type, + * watcher, connector definition) absent from desired is emitted as a `delete` + * row instead of an ignored `drift` — INCLUDING definitions created via the + * dashboard/API. Data (entity/relationship instances), connections, auth + * profiles, feeds, agents, and platforms are never pruned. Default (false) + * reports those remote-only definitions as `drift`. */ - codeManaged?: boolean; + prune?: boolean; /** * Target org id. The entity/relationship-type list endpoints also return * *public* definitions owned by OTHER orgs, which this org neither manages @@ -874,7 +875,7 @@ export function computeDiff( ): DiffPlan { const rows: DiffRow[] = []; const only = opts.only; - const codeManaged = opts.codeManaged ?? false; + const prune = opts.prune ?? false; // A remote entity/relationship type is this org's to manage (drift/prune) // only when it's org-owned. The list endpoints also surface public types // from other orgs (`organization_id` differs) — never drift or delete those. @@ -976,7 +977,7 @@ export function computeDiff( // instances exist (the data is exempt), surfacing a clear error. rows.push({ kind: "entity-type", - verb: codeManaged ? "delete" : "drift", + verb: prune ? "delete" : "drift", id: remoteEntity.slug, remote: remoteEntity, }); @@ -997,7 +998,7 @@ export function computeDiff( if (!desiredRelSlugs.has(remoteRel.slug)) { rows.push({ kind: "relationship-type", - verb: codeManaged ? "delete" : "drift", + verb: prune ? "delete" : "drift", id: remoteRel.slug, remote: remoteRel, }); @@ -1015,7 +1016,7 @@ export function computeDiff( if (!desiredWatcherSlugs.has(remoteWatcher.slug)) { rows.push({ kind: "watcher", - verb: codeManaged ? "delete" : "drift", + verb: prune ? "delete" : "drift", id: remoteWatcher.slug, remote: remoteWatcher, }); @@ -1111,7 +1112,7 @@ export function computeDiff( if (declaredKeys.has(def.key) || referencedConnectorKeys.has(def.key)) { continue; } - if (codeManaged && !liveConnectorKeys.has(def.key)) { + if (prune && !liveConnectorKeys.has(def.key)) { rows.push({ kind: "connector-definition", verb: "delete", diff --git a/packages/cli/src/commands/_lib/apply/map-config.ts b/packages/cli/src/commands/_lib/apply/map-config.ts index 21f1d5889..526ce38d0 100644 --- a/packages/cli/src/commands/_lib/apply/map-config.ts +++ b/packages/cli/src/commands/_lib/apply/map-config.ts @@ -669,6 +669,7 @@ export function mapProjectToDesiredState( return { agents, + prune: project.prune ?? false, ...(Object.keys(memory).length > 0 ? { memory } : {}), memorySchema: { entityTypes, relationshipTypes }, watchers, diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 9e4dfe6b6..191d071ad 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -315,10 +315,6 @@ Memory: "--force", "Bypass the project-link guard if context/org don't match" ) - .option( - "--manage", - "Make the org code-managed (lobu.config.ts owns + prunes its definitions)" - ) .action( async (options: { dryRun?: boolean; @@ -327,7 +323,6 @@ Memory: org?: string; url?: string; force?: boolean; - manage?: boolean; }) => { if ( options.only !== undefined && @@ -350,7 +345,6 @@ Memory: org: options.org, url: options.url, force: options.force, - manage: options.manage, }); } ); diff --git a/packages/sdk/src/define.ts b/packages/sdk/src/define.ts index 6082d3b21..de95ff7a3 100644 --- a/packages/sdk/src/define.ts +++ b/packages/sdk/src/define.ts @@ -301,6 +301,13 @@ export interface Project { readonly kind: "project"; /** Lobu Cloud org slug this project applies to. */ org?: string; + /** + * When true, `lobu apply` deletes definitions (entity/relationship types, + * watchers, connector definitions) that are absent from this config — + * INCLUDING ones created via the dashboard/API. Data, connections, auth + * profiles, and agents are never pruned. Default false. + */ + prune?: boolean; /** Display name used if `lobu apply` offers to provision the org. */ orgName?: string; /** Org description. */ diff --git a/packages/server/src/__tests__/integration/managed-by-prune.test.ts b/packages/server/src/__tests__/integration/prune.test.ts similarity index 68% rename from packages/server/src/__tests__/integration/managed-by-prune.test.ts rename to packages/server/src/__tests__/integration/prune.test.ts index 14820ab82..ca0eb7a15 100644 --- a/packages/server/src/__tests__/integration/managed-by-prune.test.ts +++ b/packages/server/src/__tests__/integration/prune.test.ts @@ -1,33 +1,27 @@ /** - * Code-managed prune — server-side gate. + * Prune — server-side gate. * - * `lobu apply --manage` flips an org to code-managed; subsequent applies delete - * definitions removed from `lobu.config.ts` (see packages/cli/.../apply/diff.ts - * computeDiff({ codeManaged })). This suite verifies the destructive half that - * the CLI depends on, against a real Postgres: - * - the migration adds organization.managed_by defaulting to 'ui' (no org - * starts prunable — the 2026-05-20 safety lesson), constrained to ui|code; - * - /oauth/userinfo surfaces managed_by (the CLI's listOrgs read path); + * `defineConfig({ prune: true })` makes `lobu apply` delete definitions absent + * from the config (see packages/cli/.../apply/diff.ts computeDiff({ prune })). + * This suite verifies the destructive half the CLI depends on, against a real + * Postgres: * - definition deletes work (entity/relationship type, watcher); - * - an entity-type delete REFUSES while instances exist, so prune can never - * cascade into data (data is exempt). + * - an entity-type / relationship-type delete REFUSES while instances exist, + * so prune can never cascade into data (data is exempt). */ import { beforeAll, describe, expect, it } from 'vitest'; -import { OAuthProvider } from '../../auth/oauth/provider'; import { cleanupTestDatabase, getTestDb } from '../setup/test-db'; import { addUserToOrganization, - createTestAccessToken, createTestAgent, createTestEntity, - createTestOAuthClient, createTestOrganization, createTestUser, } from '../setup/test-fixtures'; import { TestApiClient } from '../setup/test-mcp-client'; -describe('code-managed prune (server gate)', () => { +describe('prune (server gate)', () => { let owner: TestApiClient; let orgId: string; let userId: string; @@ -46,46 +40,6 @@ describe('code-managed prune (server gate)', () => { }); }); - describe('migration: organization.managed_by', () => { - it('defaults a fresh org to ui (no org starts prunable)', async () => { - const sql = getTestDb(); - const [row] = await sql<{ managed_by: string }[]>` - SELECT managed_by FROM "organization" WHERE id = ${orgId} - `; - expect(row?.managed_by).toBe('ui'); - }); - - it('accepts code and rejects any other value via the CHECK constraint', async () => { - const sql = getTestDb(); - await sql`UPDATE "organization" SET managed_by = 'code' WHERE id = ${orgId}`; - const [row] = await sql<{ managed_by: string }[]>` - SELECT managed_by FROM "organization" WHERE id = ${orgId} - `; - expect(row?.managed_by).toBe('code'); - await expect( - sql`UPDATE "organization" SET managed_by = 'bogus' WHERE id = ${orgId}` - ).rejects.toThrow(); - // Restore for the userinfo assertion below. - await sql`UPDATE "organization" SET managed_by = 'code' WHERE id = ${orgId}`; - }); - }); - - describe('userinfo exposes managed_by (CLI listOrgs read path)', () => { - it('returns the org provenance the CLI reads to decide codeManaged', async () => { - const client = await createTestOAuthClient({ client_name: 'Prune CLI' }); - const { token } = await createTestAccessToken( - userId, - orgId, - client.client_id, - { scope: 'profile:read' } - ); - const provider = new OAuthProvider(getTestDb(), 'http://localhost:8787'); - const info = await provider.getUserInfo(token); - const org = info?.organizations.find((o) => o.id === orgId); - expect(org?.managed_by).toBe('code'); - }); - }); - describe('definition deletes (prune targets)', () => { it('deletes an entity type with no instances', async () => { await owner.entity_schema.createType({ slug: 'prune-empty', name: 'Empty' }); diff --git a/packages/server/src/auth/oauth/provider.ts b/packages/server/src/auth/oauth/provider.ts index 823da8482..0434b95a6 100644 --- a/packages/server/src/auth/oauth/provider.ts +++ b/packages/server/src/auth/oauth/provider.ts @@ -417,7 +417,6 @@ export class OAuthProvider { id: string; slug: string; name: string; - managed_by: 'ui' | 'code'; }[]; } | null> { const authInfo = await this.verifyAccessToken(token); @@ -454,7 +453,7 @@ export class OAuthProvider { } const orgs = await this.sql` - SELECT o.id, o.slug, o.name, o.managed_by + SELECT o.id, o.slug, o.name FROM "member" m JOIN "organization" o ON o.id = m."organizationId" WHERE m."userId" = ${authInfo.userId} @@ -477,7 +476,6 @@ export class OAuthProvider { id: o.id as string, slug: o.slug as string, name: o.name as string, - managed_by: o.managed_by === 'code' ? 'code' : 'ui', })), }; } diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts index 070d09c94..eb31fe30d 100644 --- a/packages/server/src/index.ts +++ b/packages/server/src/index.ts @@ -1123,79 +1123,6 @@ app.patch('/api/:orgSlug/organization/visibility', mcpAuth, async (c) => { return c.json({ organization: { ...org, is_member: true } }); }); -// Flip an org's provenance between UI- and code-managed. Code-managed orgs are -// owned by a `lobu.config.ts`: `lobu apply` prunes definitions removed from it. -// Same owner/admin gate as visibility — pruning is a destructive capability. -app.patch('/api/:orgSlug/organization/managed-by', mcpAuth, async (c) => { - const organizationId = c.get('organizationId'); - const memberRole = c.get('memberRole'); - - if (!organizationId) { - return c.json({ error: 'Organization context required' }, 401); - } - if (memberRole !== 'owner' && memberRole !== 'admin') { - return c.json( - { - error: 'forbidden', - message: 'Changing org management mode requires owner or admin access.', - }, - 403 - ); - } - const authSource = c.get('authSource'); - if (authSource === 'pat') { - return c.json( - { - error: 'forbidden', - message: 'Use OAuth or a web session to change org management mode.', - }, - 403 - ); - } - const scopes = c.get('mcpAuthInfo')?.scopes ?? []; - if (authSource === 'oauth' && !scopes.includes('mcp:admin')) { - return c.json( - { - error: 'forbidden', - message: 'Changing org management mode requires mcp:admin scope.', - }, - 403 - ); - } - - let body: { managed_by?: unknown }; - try { - body = await c.req.json(); - } catch { - return c.json({ error: 'invalid_request', message: 'Request body must be JSON.' }, 400); - } - const managedBy = body.managed_by; - if (managedBy !== 'ui' && managedBy !== 'code') { - return c.json( - { error: 'invalid_request', message: 'managed_by must be "ui" or "code".' }, - 400 - ); - } - - const sql = getDb(); - const rows = await sql<{ id: string; slug: string; managed_by: 'ui' | 'code' }>` - UPDATE "organization" - SET managed_by = ${managedBy} - WHERE id = ${organizationId} - RETURNING id, slug, managed_by - `; - const org = rows[0]; - if (!org) { - return c.json({ error: 'not_found', message: 'Workspace not found.' }, 404); - } - - invalidateOrgSlugCache(c.req.param('orgSlug')); - invalidateOrgSlugCache(org.slug); - invalidationEmitter.emit(org.id, { keys: ['organizations', 'resolve-path'] }); - - return c.json({ organization: org }); -}); - app.route('/api/:orgSlug/agents', agentRoutes); app.route('/api/:orgSlug/clients', clientRoutes); app.route('/api/agents/platforms', platformSchemaRoutes); From bb48e49d2e2654e0df72a088500d15b081ad9c35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 15:44:08 +0100 Subject: [PATCH 54/65] fix(ci): build @lobu/sdk + @lobu/client before downstream typecheck/unit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI's typecheck job (make build-packages) and unit job (inline build step) never built packages/sdk, so the CLI typecheck and bun test packages/cli both failed to resolve @lobu/sdk — a cascade of TS2307 + implicit-any + $secret errors and unhandled import errors in unit. Add packages/sdk to both build paths and align the Makefile list with root build:packages (which already builds client + sdk). --- .github/workflows/ci.yml | 1 + Makefile | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 20da65a3c..a3750e820 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,6 +63,7 @@ jobs: run: | cd packages/core && bun run build && cd ../.. cd packages/connector-sdk && bun run build && cd ../.. + cd packages/sdk && bun run build && cd ../.. cd packages/embeddings && bun run build && cd ../.. cd packages/connector-worker && bun run build && cd ../.. diff --git a/Makefile b/Makefile index 5ca87f7af..33337a39e 100644 --- a/Makefile +++ b/Makefile @@ -34,7 +34,7 @@ typecheck: # Build all TypeScript packages in dependency order build-packages: @echo "📦 Building all TypeScript packages..." - @for pkg in core pgvector-embedded connector-sdk agent-worker openclaw-plugin embeddings connector-worker promptfoo-provider; do \ + @for pkg in core pgvector-embedded connector-sdk client sdk agent-worker openclaw-plugin embeddings connector-worker promptfoo-provider; do \ echo " 📦 Building packages/$$pkg..."; \ ( cd packages/$$pkg && bun run build ) || exit $$?; \ done From 67a0e19d190b7a62a8f9e97da7f2548a3b4dc984 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 15:45:06 +0100 Subject: [PATCH 55/65] fix(cli): commit warnings field in loadDesiredStateFromConfig return MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit apply-cmd.ts destructures `warnings` from loadDesiredStateFromConfig, but the committed desired-state.ts return type was { state, configPath } only — a real TS2339 (Property 'warnings' does not exist) that the merge resolution left uncommitted in the working tree. Restores the field + warnings channel. --- packages/cli/src/commands/_lib/apply/desired-state.ts | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/desired-state.ts b/packages/cli/src/commands/_lib/apply/desired-state.ts index a7adb5792..c2fa6f506 100644 --- a/packages/cli/src/commands/_lib/apply/desired-state.ts +++ b/packages/cli/src/commands/_lib/apply/desired-state.ts @@ -824,7 +824,7 @@ export async function loadProjectConfig( */ export async function loadDesiredStateFromConfig( opts: LoadDesiredStateOptions -): Promise<{ state: DesiredState; configPath: string }> { +): Promise<{ state: DesiredState; configPath: string; warnings: string[] }> { const env = opts.env ?? process.env; const { project: typedProject, configPath } = await loadProjectConfig( opts.cwd @@ -873,5 +873,10 @@ export async function loadDesiredStateFromConfig( opts.cwd ); } - return { state, configPath }; + // Surface load-time warnings to `lobu apply` (which prints them). #1010's + // "ignored connectors because [memory] is disabled" case is obsolete here — + // lobu.config.ts has no `[memory].enabled` gate, so connectors always load — + // but the channel is kept so future TS-loader warnings flow to the operator. + const warnings: string[] = []; + return { state, configPath, warnings }; } From 05571f9363d9f44f6d67da01cb45efe5e12a0281 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 16:14:15 +0100 Subject: [PATCH 56/65] fix(apply,init,schema): close 6 review blockers in the TS-SDK apply/init path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From a fresh full-diff pi review (bug_free_confidence 22): - B1 init --from-org emitted secret("…") on the MCP-oauth clientSecret path without registering the `secret` import → generated config didn't compile. Couple SecretCollector to ImportTracker so every secret() ref auto-imports; drop the 4 now-redundant manual imports.use("secret") calls. - B2 platform secret rotation/removal was a silent noop (opaque remote can't be diffed). Apply now upserts EVERY desired platform idempotently (mirrors the provider-key push); the server's PUT decides noop vs restart. Diff also flags a removed key (present in remote, absent in desired) as a change. - B3 init --from-org read auth_schema as JSON Schema (.properties), but it's a ConnectorAuthSchema (.methods). Rewrite authSchemaFields to read env_keys fields[].key and oauth clientIdKey/clientSecretKey per profile kind. - B4 relationship-type delete left status='active', so the (org,slug) partial unique index (WHERE status='active') blocked re-creating the same slug (prune → re-add). Delete now also sets status='archived' to vacate the index. - B5 inverse-type lookup wasn't org/public scoped: it could link to and write the reciprocal back-link onto another tenant's private rel-type. Scope the lookup to own-org-or-public and only write the back-link when caller owns it. - B6 init --from-org dropped per-skill network.judge / judges from SKILL.md. Emit them as the YAML the frontmatter loader reads back. Tests: CLI unit (MCP-oauth import, oauth_app methods keys, skill judged domains, platform-key removal) + server integration (rel-type re-create after delete, inverse tenant isolation x2). Full CLI 314 / server unit 201 green; prune integration 9/9 against embedded PG. --- .../_lib/apply/__tests__/diff.test.ts | 42 ++++ .../cli/src/commands/_lib/apply/apply-cmd.ts | 58 ++++-- packages/cli/src/commands/_lib/apply/diff.ts | 18 +- .../__tests__/init-from-org.test.ts | 184 +++++++++++++++++- .../commands/_lib/init-from-org/bootstrap.ts | 92 +++++++-- .../src/__tests__/integration/prune.test.ts | 66 +++++++ .../src/tools/admin/manage_entity_schema.ts | 73 ++++--- 7 files changed, 459 insertions(+), 74 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index 8c1e2d2be..2456ca879 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -352,6 +352,48 @@ describe("apply diff — platforms", () => { const platformRow = plan.rows.find((r) => r.kind === "platform"); expect(platformRow?.verb).toBe("update"); }); + + test("update when a secret-bearing config key is removed (opaque remote, absent in desired)", () => { + // The remote still carries `signingSecret` as an opaque value, but the + // desired config dropped it. A removal must surface as `update`, not be + // swallowed by the opaque-secret = unchanged rule. + const desired = buildState([ + buildDesiredAgent("triage", { + metadata: { agentId: "triage", name: "Triage" }, + platforms: [ + { + stableId: "triage-slack", + type: "slack", + config: { botToken: "$SLACK_BOT_TOKEN" }, + }, + ], + }), + ]); + const remote: RemoteSnapshot = { + ...emptyRemote(), + agents: [{ agentId: "triage", name: "Triage" }], + agentSettings: new Map([["triage", null]]), + platformsByAgent: new Map([ + [ + "triage", + [ + { + id: "triage-slack", + platform: "slack", + config: { + platform: "slack", + botToken: "***oken", + signingSecret: "***cret", + }, + }, + ], + ], + ]), + }; + const plan = computeDiff(desired, remote); + const platformRow = plan.rows.find((r) => r.kind === "platform"); + expect(platformRow?.verb).toBe("update"); + }); }); describe("apply diff — memory schema", () => { diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index b4207e2cc..5e821878c 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -18,6 +18,7 @@ import { computeDiff, type DiffPlan, type DiffRow, + type DiffVerb, type RemoteSnapshot, } from "./diff.js"; import { @@ -621,28 +622,45 @@ async function executePlan( } } - // 3) Platforms + // 3) Platforms — upsert EVERY desired platform idempotently, mirroring the + // provider-key push (2b), not just the non-noop diff rows. Platform secrets + // (botToken, signingSecret, …) come back from the server opaque (redacted or + // `secret://`), so the CLI can never diff a rotated/removed secret — those + // changes would otherwise be silent noops the plan skips. The server's PUT is + // idempotent: unchanged config → `noop` (no restart), changed → `willRestart`. + // We surface the planned verb when the diff produced a row, and still report a + // server-side restart for a secret rotation the diff couldn't see. + const platformVerbByStableId = new Map(); for (const row of rowsByKind("platform")) { - if (row.kind !== "platform") continue; - const desired = row.desired; - if (!desired) continue; - const result = await ctx.client.upsertPlatform( - row.agentId, - desired.stableId, - { - platform: desired.type, - ...(desired.name ? { name: desired.name } : {}), - config: desired.config, + if (row.kind === "platform") platformVerbByStableId.set(row.id, row.verb); + } + for (const agent of ctx.state.agents) { + for (const platform of agent.platforms) { + const result = await ctx.client.upsertPlatform( + agent.metadata.agentId, + platform.stableId, + { + platform: platform.type, + ...(platform.name ? { name: platform.name } : {}), + config: platform.config, + } + ); + const verb = platformVerbByStableId.get(platform.stableId); + const id = `${agent.metadata.agentId}/${platform.stableId}`; + if (verb) { + const detail = result.willRestart + ? "(restarted)" + : result.noop + ? "(noop on server)" + : undefined; + printText(renderProgress(verb, "platform", id, detail)); + } else if (result.willRestart) { + // No plan row (the diff couldn't see the opaque secret change) but the + // server applied a different config — surface the rotation. + printText(renderProgress("update", "platform", id, "(rotated secret)")); } - ); - const detail = result.willRestart - ? "(restarted)" - : result.noop - ? "(noop on server)" - : undefined; - printText( - renderProgress(row.verb, "platform", `${row.agentId}/${row.id}`, detail) - ); + // else: truly unchanged (no plan row, server noop) → stay silent. + } } // 3b) Declarative channel bindings — reconcile after the platform upserts diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index acd19d13a..23442c5f3 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -404,13 +404,17 @@ function platformConfigChanged( for (const key of keys) { const d = desiredConfig[key]; const r = remoteConfig[key]; - // Secret-bearing keys come back opaque (redacted `***` or a `secret://` - // ref), so the resolved cleartext the CLI sent can never round-trip-match. - // Treat an opaque remote value as unchanged (write-only secret, like - // auth-profile credentials) so the platform isn't needlessly restarted; - // non-secret fields still diff normally. (A rotated secret isn't - // auto-detected here — re-push it explicitly if needed.) - if (isOpaqueRemoteConfigValue(r)) continue; + if (isOpaqueRemoteConfigValue(r)) { + // Opaque remote (redacted `***` or a `secret://` ref): the resolved + // cleartext the CLI sent can never round-trip-match, so we can't tell a + // rotation from a no-op here. Treat as unchanged ONLY while the key is + // still declared — apply re-pushes every desired platform idempotently + // (like provider keys), so a rotated secret still reaches the server + // without a false "config changed" plan row. A key ABSENT from desired + // is a real removal → changed. + if (!(key in desiredConfig)) return true; + continue; + } if (!deepEqual(d, r)) return true; } return false; diff --git a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts index 1d2f0db43..fe9004a70 100644 --- a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts +++ b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts @@ -430,10 +430,18 @@ describe("lobu init --from-org", () => { { key: "stripe", name: "Stripe", + // Real connector auth_schema: a `methods` array (env_keys + // method with `fields[].key`), NOT a JSON Schema. The + // credential KEY comes from `fields[].key` (`api_key`). auth_schema: { - type: "object", - properties: { api_key: { type: "string" } }, - required: ["api_key"], + methods: [ + { + type: "env_keys", + fields: [ + { key: "api_key", required: true, secret: true }, + ], + }, + ], }, }, ], @@ -516,4 +524,174 @@ describe("lobu init --from-org", () => { process.env.BOT_TELEGRAM_BOTTOKEN = undefined; } }); + + test("MCP oauth clientSecret → emits secret() AND imports it (no missing-import)", async () => { + const dir = mkFixtureDir(); + await initFromOrg({ + targetDir: dir, + fetchImpl: buildFetch({ + "/oauth/userinfo": () => ({ + organizations: [{ id: "org-1", slug: "acme", name: "Acme Inc" }], + }), + // Agent config whose ONLY secret-bearing field is an MCP oauth + // clientSecret — no providers/platforms/auth profiles — so a dropped + // `secret` import would produce a config that references `secret` + // without importing it (the B1 regression). + "/agents/mcpbot/config": () => ({ + updatedAt: 0, + mcpServers: { + notion: { + url: "https://mcp.notion.test", + type: "streamable-http", + oauth: { + authUrl: "https://notion.test/oauth/authorize", + tokenUrl: "https://notion.test/oauth/token", + clientId: "public-id", + clientSecret: "super-secret", + }, + }, + }, + }), + "/agents": () => ({ agents: [{ agentId: "mcpbot", name: "MCP Bot" }] }), + "watchers?include_details": () => ({ watchers: [] }), + manage_entity_schema: () => ({ + entity_types: [], + relationship_types: [], + }), + manage_auth_profiles: () => ({ auth_profiles: [] }), + manage_connections: () => ({ connections: [] }), + }), + }); + + const source = readFileSync(join(dir, "lobu.config.ts"), "utf-8"); + // clientSecret is a write-only secret() placeholder, never the stored value. + expect(source).toContain("clientSecret: secret("); + expect(source).not.toContain("super-secret"); + // ...AND the `secret` import is present so the file compiles. + expect(source).toMatch( + /import\s*\{[^}]*\bsecret\b[^}]*\}\s*from\s*"@lobu\/sdk"/s + ); + + // Round-trips: jiti loads the regenerated config without a missing-import + // ReferenceError, proving the import is wired. + process.env.NOTION_MCP_CLIENT_SECRET = "filled-in"; + try { + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + expect(state.agents[0]?.metadata.agentId).toBe("mcpbot"); + } finally { + process.env.NOTION_MCP_CLIENT_SECRET = undefined; + } + }); + + test("oauth_app profile → credentials keyed by the connector's oauth method (clientIdKey/clientSecretKey)", async () => { + const dir = mkFixtureDir(); + await initFromOrg({ + targetDir: dir, + fetchImpl: buildFetch({ + "/oauth/userinfo": () => ({ + organizations: [{ id: "org-1", slug: "acme", name: "Acme Inc" }], + }), + "/agents/lone/config": () => ({ updatedAt: 0 }), + "/agents": () => ({ agents: [{ agentId: "lone", name: "Lone" }] }), + "watchers?include_details": () => ({ watchers: [] }), + manage_entity_schema: () => ({ + entity_types: [], + relationship_types: [], + }), + manage_auth_profiles: () => ({ + auth_profiles: [ + { + slug: "slack-app", + display_name: "Slack OAuth app", + connector_key: "slack", + profile_kind: "oauth_app", + status: "active", + }, + ], + }), + manage_connections: (body) => + body.action === "list_connector_definitions" + ? { + connector_definitions: [ + { + key: "slack", + name: "Slack", + // oauth method declares explicit credential key names. + auth_schema: { + methods: [ + { + type: "oauth", + provider: "slack", + requiredScopes: ["chat:write"], + clientIdKey: "SLACK_OAUTH_CLIENT_ID", + clientSecretKey: "SLACK_OAUTH_CLIENT_SECRET", + }, + ], + }, + }, + ], + } + : { connections: [] }, + }), + }); + + const source = readFileSync(join(dir, "lobu.config.ts"), "utf-8"); + // Both oauth credential keys come from the method (NOT the SLACK_APP_CLIENT_SECRET + // placeholder), and the stale rename-TODO is gone. + expect(source).toContain("SLACK_OAUTH_CLIENT_ID: secret("); + expect(source).toContain("SLACK_OAUTH_CLIENT_SECRET: secret("); + expect(source).not.toContain("rename credential keys"); + }); + + test("local skill judged domains + judges round-trip into SKILL.md frontmatter", async () => { + const dir = mkFixtureDir(); + await initFromOrg({ + targetDir: dir, + fetchImpl: buildFetch({ + "/oauth/userinfo": () => ({ + organizations: [{ id: "org-1", slug: "acme", name: "Acme Inc" }], + }), + "/agents/skiller/config": () => ({ + updatedAt: 0, + skillsConfig: { + skills: [ + { + name: "research", + description: "web research", + enabled: true, + content: "Do research.", + networkConfig: { + allowedDomains: ["wikipedia.org"], + judgedDomains: [{ domain: "reddit.com", judge: "careful" }], + judges: { careful: "Block anything risky." }, + }, + }, + ], + }, + }), + "/agents": () => ({ + agents: [{ agentId: "skiller", name: "Skiller" }], + }), + "watchers?include_details": () => ({ watchers: [] }), + manage_entity_schema: () => ({ + entity_types: [], + relationship_types: [], + }), + manage_auth_profiles: () => ({ auth_profiles: [] }), + manage_connections: () => ({ connections: [] }), + }), + }); + + const skillMd = readFileSync( + join(dir, "agents/skiller/skills/research/SKILL.md"), + "utf-8" + ); + // Judged domains emit as a `network.judge` list; named judge policies as a + // top-level `judges:` map — exactly what parseSkillFrontmatter reads back. + expect(skillMd).toContain("judge:"); + expect(skillMd).toContain('domain: "reddit.com"'); + expect(skillMd).toContain('judge: "careful"'); + expect(skillMd).toContain("judges:"); + expect(skillMd).toContain('careful: "Block anything risky."'); + }); }); diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index 0dfebc6a6..e3f369323 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -152,9 +152,16 @@ class IdentMinter { class SecretCollector { readonly names = new Set(); + // Coupled to the ImportTracker so every `secret("…")` we emit also registers + // the `secret` import. Decoupling them (caller calls `imports.use("secret")` + // separately) silently dropped the import on the MCP-oauth `clientSecret` + // path, producing a config that referenced `secret` without importing it. + constructor(private readonly imports: ImportTracker) {} + /** Register a var name and return the `secret("NAME")` TS expression. */ ref(name: string): string { this.names.add(name); + this.imports.use("secret"); return `secret(${str(name)})`; } } @@ -168,25 +175,50 @@ function envVarFor(slug: string, suffix: string): string { /** * The credential field names a connector's auth schema expects. `lobu apply` * sends `credentials: { : }` and the server validates `` - * against the connector's `auth_schema`, so the emitted credential KEY must be a - * real auth-schema field — not an env-var-derived name. We return the required - * fields (or all `properties` keys when nothing is explicitly required), or - * `null` when the schema has no usable field list (caller falls back). + * against the connector's `auth_schema.methods` (see the server's + * connection-helpers `getOAuthCredentialKeys` / env-key extraction), so the + * emitted credential KEY must be a real auth-schema field — not an + * env-var-derived name. + * + * `auth_schema` is the connector's `ConnectorAuthSchema` (`{ methods: [...] }`), + * NOT a JSON Schema. We pick the keys for the profile kind being emitted: + * - `env` → the `env_keys` method's `fields[].key` + * - `oauth_app` → the `oauth` method's `clientIdKey`/`clientSecretKey` + * (defaulting to `${PROVIDER}_CLIENT_ID` / `_CLIENT_SECRET`, mirroring the + * server default) + * Returns `null` when the schema has no matching method (caller falls back to a + * TODO placeholder). */ function authSchemaFields( - schema: Record | null | undefined + schema: Record | null | undefined, + profileKind: "env" | "oauth_app" ): string[] | null { if (!schema || typeof schema !== "object") return null; - const props = schema.properties; - if (!props || typeof props !== "object") return null; - const allFields = Object.keys(props as Record); - if (allFields.length === 0) return null; - const required = Array.isArray(schema.required) - ? (schema.required as unknown[]).filter( - (r): r is string => typeof r === "string" && allFields.includes(r) - ) + const methods = Array.isArray(schema.methods) + ? (schema.methods as Array>) : []; - return required.length > 0 ? required : allFields; + + if (profileKind === "oauth_app") { + const oauth = methods.find((m) => m.type === "oauth"); + if (!oauth || typeof oauth.provider !== "string") return null; + const providerUpper = oauth.provider.toUpperCase(); + const clientIdKey = + typeof oauth.clientIdKey === "string" && oauth.clientIdKey.trim() + ? oauth.clientIdKey + : `${providerUpper}_CLIENT_ID`; + const clientSecretKey = + typeof oauth.clientSecretKey === "string" && oauth.clientSecretKey.trim() + ? oauth.clientSecretKey + : `${providerUpper}_CLIENT_SECRET`; + return [clientIdKey, clientSecretKey]; + } + + const envMethod = methods.find((m) => m.type === "env_keys"); + const fields = Array.isArray(envMethod?.fields) ? envMethod.fields : []; + const keys = (fields as Array>) + .map((f) => f.key) + .filter((k): k is string => typeof k === "string" && k.length > 0); + return keys.length > 0 ? keys : null; } // ── Imports tracking ───────────────────────────────────────────────────────── @@ -243,7 +275,6 @@ function emitAgent( const providers = settings?.installedProviders ?? []; if (providers.length > 0) { const prefs = settings?.providerModelPreferences ?? {}; - imports.use("secret"); const items = providers.map((p) => { const id = p.providerId; const model = prefs[id]; @@ -384,13 +415,11 @@ function emitAgent( if (typeof v === "string") { const explicitVar = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(v); if (explicitVar?.[1]) { - imports.use("secret"); return `${k}: ${secrets.ref(explicitVar[1])}`; } // Opaque secret (redacted `***…` or internal `secret://…`): derive a // deterministic env-var name from the agent + config key. if (v.startsWith("***") || v.startsWith("secret://")) { - imports.use("secret"); return `${k}: ${secrets.ref(envVarFor(agent.agentId, `${p.platform}_${k}`.toUpperCase()))}`; } return `${k}: ${str(v)}`; @@ -503,12 +532,36 @@ function emitSkillFile( if (net?.deniedDomains?.length) { fm.push(` deny: [${net.deniedDomains.map((d) => str(d)).join(", ")}]`); } + // Judged domains round-trip as a `network.judge` YAML list of + // `{ domain, judge? }` — the exact shape the SKILL.md frontmatter loader + // reads back (parseSkillFrontmatter → `fm.network.judge`). Omitting these + // (the prior behaviour) silently dropped per-skill egress-judge rules. + if (net?.judgedDomains?.length) { + fm.push(" judge:"); + for (const rule of net.judgedDomains) { + fm.push(` - domain: ${str(rule.domain)}`); + if (rule.judge) fm.push(` judge: ${str(rule.judge)}`); + } + } + } + // Named judge policies (referenced by `network.judge[].judge`) live at the + // frontmatter top level under `judges:` (str() emits a JSON-quoted scalar, + // which is valid YAML even for multi-line policy text). + if (net?.judges && Object.keys(net.judges).length > 0) { + fm.push("judges:"); + for (const [name, policy] of Object.entries(net.judges)) { + fm.push(` ${name}: ${str(policy)}`); + } } if (skill.nixPackages?.length) { fm.push( `nixPackages: [${skill.nixPackages.map((p) => str(p)).join(", ")}]` ); } + // NOTE: skill-level `mcpServers` (rare) are not emitted yet — the stored + // shape is SkillMcpServer[] while the frontmatter loader expects a YAML + // record, and secret-bearing fields would need `$VAR` placeholders. Agent + // mcpServers DO round-trip (emitMcpServers). Tracked as a follow-up. const body = skill.content ?? ""; return `---\n${fm.join("\n")}\n---\n${body}\n`; } @@ -669,9 +722,8 @@ function emitAuthProfile( !interactive && (p.profile_kind === "env" || p.profile_kind === "oauth_app") ) { - imports.use("secret"); const fieldKeys = authSchemas.has(p.connector_key) - ? authSchemaFields(authSchemas.get(p.connector_key)) + ? authSchemaFields(authSchemas.get(p.connector_key), p.profile_kind) : null; if (fieldKeys && fieldKeys.length > 0) { // Emit `credentials: { : secret("_") }` for each real @@ -870,7 +922,7 @@ export function generateProject( ): GeneratedProject { const imports = new ImportTracker(); imports.use("defineConfig"); - const secrets = new SecretCollector(); + const secrets = new SecretCollector(imports); const minter = new IdentMinter(); const files: Array<{ relPath: string; body: string }> = []; const warnings: string[] = []; diff --git a/packages/server/src/__tests__/integration/prune.test.ts b/packages/server/src/__tests__/integration/prune.test.ts index ca0eb7a15..9ec2660c2 100644 --- a/packages/server/src/__tests__/integration/prune.test.ts +++ b/packages/server/src/__tests__/integration/prune.test.ts @@ -153,5 +153,71 @@ describe('prune (server gate)', () => { false ); }); + + it('re-creates a relationship type with the same slug after delete (prune → re-add)', async () => { + // The org/slug uniqueness index is partial on `status = 'active'`, so a + // delete that only set deleted_at left the tombstone in the index and a + // re-create of the same slug hit a unique violation. delete now also sets + // status='archived' to vacate the index — `lobu apply` prune then re-add + // must round-trip. + await owner.entity_schema.createRelType({ slug: 'prune-readd', name: 'First' }); + await owner.entity_schema.deleteRelType('prune-readd'); + await owner.entity_schema.createRelType({ slug: 'prune-readd', name: 'Second' }); + const got = (await owner.entity_schema.getRelType('prune-readd')) as { + relationship_type: { name: string; status: string } | null; + }; + expect(got.relationship_type?.name).toBe('Second'); + expect(got.relationship_type?.status).toBe('active'); + }); + }); + + describe('relationship-type inverse scoping (tenant isolation)', () => { + it("rejects inverse_type_slug that resolves to another org's PRIVATE type and never mutates it", async () => { + const sql = getTestDb(); + const other = await createTestOrganization({ name: 'Private Inverse Org' }); + await sql` + INSERT INTO entity_relationship_types (organization_id, slug, name, status, created_at, updated_at) + VALUES (${other.id}, ${'foreign-private-inv'}, 'Foreign Private', 'active', NOW(), NOW()) + `; + // A foreign PRIVATE type is invisible: referencing it as an inverse must + // fail rather than silently linking across tenants. + await expect( + owner.entity_schema.createRelType({ + slug: 'mine-with-priv-inverse', + name: 'Mine', + inverse_type_slug: 'foreign-private-inv', + }) + ).rejects.toThrow(/not found/i); + // ...and the foreign row's inverse_type_id is untouched. + const [foreign] = await sql<{ inverse_type_id: number | null }[]>` + SELECT inverse_type_id FROM entity_relationship_types + WHERE organization_id = ${other.id} AND slug = ${'foreign-private-inv'} + `; + expect(foreign?.inverse_type_id).toBeNull(); + }); + + it('references a PUBLIC foreign inverse type but never writes the reciprocal back-link onto it', async () => { + const sql = getTestDb(); + const other = await createTestOrganization({ + name: 'Public Inverse Org', + visibility: 'public', + }); + await sql` + INSERT INTO entity_relationship_types (organization_id, slug, name, status, created_at, updated_at) + VALUES (${other.id}, ${'foreign-public-inv'}, 'Foreign Public', 'active', NOW(), NOW()) + `; + await owner.entity_schema.createRelType({ + slug: 'mine-with-pub-inverse', + name: 'Mine', + inverse_type_slug: 'foreign-public-inv', + }); + // The reciprocal back-link must NOT be written onto the foreign public row + // (only own-org inverses get the bidirectional link). + const [foreign] = await sql<{ inverse_type_id: number | null }[]>` + SELECT inverse_type_id FROM entity_relationship_types + WHERE organization_id = ${other.id} AND slug = ${'foreign-public-inv'} + `; + expect(foreign?.inverse_type_id).toBeNull(); + }); }); }); diff --git a/packages/server/src/tools/admin/manage_entity_schema.ts b/packages/server/src/tools/admin/manage_entity_schema.ts index 0e0c9bd85..77c7a3032 100644 --- a/packages/server/src/tools/admin/manage_entity_schema.ts +++ b/packages/server/src/tools/admin/manage_entity_schema.ts @@ -777,6 +777,37 @@ async function requireRelationshipType( return { typeId, sql }; } +/** + * Resolve an inverse relationship type by slug, scoped to the caller's own org + * or a PUBLIC type from another org (same visibility filter as read mode). A + * PRIVATE type owned by another org is invisible here — without this scoping + * the lookup matched any org's row by slug, letting one tenant link to (and, + * via the reciprocal back-link, mutate) another tenant's relationship type. + * Returns the row id plus whether the caller owns it; the reciprocal back-link + * is only written when the caller owns the inverse, never onto a foreign public + * type. + */ +async function resolveInverseType( + sql: DbClient, + inverseSlug: string, + ctx: ToolContext +): Promise<{ id: number; ownedByCaller: boolean }> { + const rows = await sql` + SELECT rt.id, (rt.organization_id = ${ctx.organizationId}) AS owned + FROM entity_relationship_types rt + LEFT JOIN organization o ON o.id = rt.organization_id + WHERE rt.slug = ${inverseSlug} + AND rt.deleted_at IS NULL + AND (rt.organization_id = ${ctx.organizationId} OR o.visibility = 'public') + ORDER BY (rt.organization_id = ${ctx.organizationId}) DESC, rt.id ASC + LIMIT 1 + `; + if (rows.length === 0) { + throw new Error(`Inverse relationship type "${inverseSlug}" not found`); + } + return { id: Number(rows[0].id), ownedByCaller: Boolean(rows[0].owned) }; +} + function buildRelationshipIdentityMetadata( rules: AutoCreateWhenRule[] | undefined, existingMetadata: unknown, @@ -913,17 +944,11 @@ async function rtHandleCreate( } let inverseTypeId: number | null = null; + let inverseOwnedByCaller = false; if (args.inverse_type_slug) { - const inverseRows = await sql` - SELECT id FROM entity_relationship_types - WHERE slug = ${args.inverse_type_slug} AND deleted_at IS NULL - ORDER BY (organization_id = ${ctx.organizationId}) DESC, id ASC - LIMIT 1 - `; - if (inverseRows.length === 0) { - throw new Error(`Inverse relationship type "${args.inverse_type_slug}" not found`); - } - inverseTypeId = Number(inverseRows[0].id); + const inverse = await resolveInverseType(sql, args.inverse_type_slug, ctx); + inverseTypeId = inverse.id; + inverseOwnedByCaller = inverse.ownedByCaller; } const identityMetadata = buildRelationshipIdentityMetadata(args.auto_create_when, null); @@ -951,7 +976,9 @@ async function rtHandleCreate( `; const typeId = Number((inserted[0] as { id: unknown }).id); - if (inverseTypeId !== null) { + // Only write the reciprocal back-link when the caller owns the inverse type. + // A public inverse from another org must never be mutated by this tenant. + if (inverseTypeId !== null && inverseOwnedByCaller) { await sql` UPDATE entity_relationship_types SET inverse_type_id = ${typeId}, updated_at = current_timestamp @@ -988,18 +1015,9 @@ async function rtHandleUpdate( if (args.inverse_type_slug === null || args.inverse_type_slug === '') { inverseTypeId = null; } else { - const inverseRows = await sql` - SELECT id FROM entity_relationship_types - WHERE slug = ${args.inverse_type_slug} AND deleted_at IS NULL - ORDER BY (organization_id = ${ctx.organizationId}) DESC, id ASC - LIMIT 1 - `; - if (inverseRows.length === 0) { - throw new Error(`Inverse relationship type "${args.inverse_type_slug}" not found`); - } - const resolvedId = Number(inverseRows[0].id); - if (resolvedId === typeId) throw new Error('inverse_type_id cannot point to self'); - inverseTypeId = resolvedId; + const inverse = await resolveInverseType(sql, args.inverse_type_slug, ctx); + if (inverse.id === typeId) throw new Error('inverse_type_id cannot point to self'); + inverseTypeId = inverse.id; } } @@ -1069,9 +1087,16 @@ async function rtHandleDelete( ); } + // Set status='archived' alongside deleted_at: the org/slug uniqueness index + // is partial on `WHERE status = 'active'` (NOT `deleted_at IS NULL`, unlike + // entity_types), so leaving status='active' keeps the tombstoned row in the + // index and a later re-create of the same slug (e.g. `lobu apply` prune then + // re-add) hits a unique violation. 'archived' is the only other status the + // check constraint allows; it vacates the index. The create dedup filters on + // deleted_at IS NULL, so the archived tombstone never blocks the re-create. await sql` UPDATE entity_relationship_types - SET deleted_at = current_timestamp, updated_at = current_timestamp + SET deleted_at = current_timestamp, status = 'archived', updated_at = current_timestamp WHERE id = ${typeId} `; From bcde2555248250b835b2a2749703a162b0e8e01c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 16:33:00 +0100 Subject: [PATCH 57/65] fix(apply): make re-apply converge to noop (idempotency) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Found via full lifecycle E2E (init → connector → watcher → apply → run → init-from-org), re-applying a stable config repeatedly: - I1 relationship-type rules churned a perpetual '~ rules' update because the rel-type `list` action omits rules — the diff compared desired rules against an always-empty remote. Hydrate remote rules (new client.listRelationshipTypeRules via the existing list_rules action) for the types the config declares with rules, so a matching set is a true noop. - I2 an omitted optional display name (feeds, connections) churned a perpetual '~ name' update: stringChanged(undefined, 'Ticks') is always true. Add optionalNameChanged — an omitted name means 'no opinion', so the server keeps its derived/stored name and it doesn't diff. - B2 follow-through: the earlier 'upsert every platform every apply' restored rotation but made the server restart the platform on EVERY apply (it can't tell the resolved secret matches the stored secret://), dropping the bot connection each deploy. Revert to upserting only diff-flagged platforms (idempotent — no restart churn); KEEP the diff removal-detection (a removed key is still applied). In-place opaque-secret rotation needs a secret-aware compare on the server upsert (owletto) — tracked as a follow-up. Verified: 7 consecutive applies of a stable config converge to '0 update, 9 noop' (connector re-push is by-design idempotent). CLI 316 green. --- .../_lib/apply/__tests__/diff.test.ts | 59 ++++++++++++++ .../cli/src/commands/_lib/apply/apply-cmd.ts | 81 ++++++++++--------- .../cli/src/commands/_lib/apply/client.ts | 27 +++++++ packages/cli/src/commands/_lib/apply/diff.ts | 19 ++++- 4 files changed, 146 insertions(+), 40 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index 2456ca879..58dc0619b 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -436,6 +436,65 @@ describe("apply diff — memory schema", () => { expect(plan.counts.noop).toBe(1); expect(plan.counts.update).toBe(0); }); + + test("relationship-type rules are a noop when remote rules match (idempotency)", () => { + // Regression: the rel-type `list` action omits rules, so apply hydrates + // them (listRelationshipTypeRules) into the snapshot. When the hydrated + // remote rules equal desired, the diff must be a noop — otherwise every + // re-apply churns a perpetual "rules changed" update. + const desired: DesiredState = { + agents: [], + memorySchema: { + entityTypes: [], + relationshipTypes: [ + { + slug: "works-at", + name: "Works at", + rules: [{ source: "contact", target: "company" }], + }, + ], + }, + watchers: [], + requiredSecrets: [], + }; + const remote: RemoteSnapshot = { + ...emptyRemote(), + relationshipTypes: [ + { + slug: "works-at", + name: "Works at", + rules: [{ source: "contact", target: "company" }], + }, + ], + }; + const plan = computeDiff(desired, remote); + expect(plan.counts.noop).toBe(1); + expect(plan.counts.update).toBe(0); + }); + + test("relationship-type rules update when remote rules differ", () => { + const desired: DesiredState = { + agents: [], + memorySchema: { + entityTypes: [], + relationshipTypes: [ + { + slug: "works-at", + name: "Works at", + rules: [{ source: "contact", target: "company" }], + }, + ], + }, + watchers: [], + requiredSecrets: [], + }; + const remote: RemoteSnapshot = { + ...emptyRemote(), + relationshipTypes: [{ slug: "works-at", name: "Works at", rules: [] }], + }; + const plan = computeDiff(desired, remote); + expect(plan.counts.update).toBe(1); + }); }); describe("apply diff — empty container preservation", () => { diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index 5e821878c..4289cc312 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -18,7 +18,6 @@ import { computeDiff, type DiffPlan, type DiffRow, - type DiffVerb, type RemoteSnapshot, } from "./diff.js"; import { @@ -285,6 +284,21 @@ async function fetchRemoteSnapshot( const entityTypes = only === "agents" ? [] : await client.listEntityTypes(); const relationshipTypes = only === "agents" ? [] : await client.listRelationshipTypes(); + // The relationship-type `list` action omits rules, so the diff would compare + // desired rules against an always-empty remote and churn a perpetual "rules + // changed" update. Hydrate rules for the types the config also declares with + // rules (bounded fetch — skip types with no desired rules to compare). + if (relationshipTypes.length > 0) { + const desiredRuleSlugs = new Set( + state.memorySchema.relationshipTypes + .filter((r) => (r.rules?.length ?? 0) > 0) + .map((r) => r.slug) + ); + for (const remote of relationshipTypes) { + if (!desiredRuleSlugs.has(remote.slug)) continue; + remote.rules = await client.listRelationshipTypeRules(remote.slug); + } + } const watchers = only === "agents" ? [] : await client.listWatchers(); // Connectors run only on a full apply (`--only` skips them). A pruning config @@ -622,45 +636,36 @@ async function executePlan( } } - // 3) Platforms — upsert EVERY desired platform idempotently, mirroring the - // provider-key push (2b), not just the non-noop diff rows. Platform secrets - // (botToken, signingSecret, …) come back from the server opaque (redacted or - // `secret://`), so the CLI can never diff a rotated/removed secret — those - // changes would otherwise be silent noops the plan skips. The server's PUT is - // idempotent: unchanged config → `noop` (no restart), changed → `willRestart`. - // We surface the planned verb when the diff produced a row, and still report a - // server-side restart for a secret rotation the diff couldn't see. - const platformVerbByStableId = new Map(); + // 3) Platforms — upsert only the platforms the diff flagged (create / config + // change / key removal). The diff treats an opaque remote secret (`***` / + // `secret://`) as unchanged while the key is still declared (see + // platformConfigChanged), so a stable config is a true noop and the live + // worker is NOT restarted on every apply. The flip side — rotating a secret + // VALUE in place can't be detected from the opaque round-trip and so isn't + // auto-pushed here; that needs a secret-aware compare on the server's upsert + // (owletto) and is tracked as a follow-up. A REMOVED key IS detected (it's + // absent from desired) and applied. for (const row of rowsByKind("platform")) { - if (row.kind === "platform") platformVerbByStableId.set(row.id, row.verb); - } - for (const agent of ctx.state.agents) { - for (const platform of agent.platforms) { - const result = await ctx.client.upsertPlatform( - agent.metadata.agentId, - platform.stableId, - { - platform: platform.type, - ...(platform.name ? { name: platform.name } : {}), - config: platform.config, - } - ); - const verb = platformVerbByStableId.get(platform.stableId); - const id = `${agent.metadata.agentId}/${platform.stableId}`; - if (verb) { - const detail = result.willRestart - ? "(restarted)" - : result.noop - ? "(noop on server)" - : undefined; - printText(renderProgress(verb, "platform", id, detail)); - } else if (result.willRestart) { - // No plan row (the diff couldn't see the opaque secret change) but the - // server applied a different config — surface the rotation. - printText(renderProgress("update", "platform", id, "(rotated secret)")); + if (row.kind !== "platform") continue; + const desired = row.desired; + if (!desired) continue; + const result = await ctx.client.upsertPlatform( + row.agentId, + desired.stableId, + { + platform: desired.type, + ...(desired.name ? { name: desired.name } : {}), + config: desired.config, } - // else: truly unchanged (no plan row, server noop) → stay silent. - } + ); + const detail = result.willRestart + ? "(restarted)" + : result.noop + ? "(noop on server)" + : undefined; + printText( + renderProgress(row.verb, "platform", `${row.agentId}/${row.id}`, detail) + ); } // 3b) Declarative channel bindings — reconcile after the platform upserts diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index c76d963a1..fa368f1a4 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -574,6 +574,33 @@ export class ApplyClient { return pickArray(body, "relationship_types", "relationshipTypes"); } + /** + * Fetch a relationship type's rules (the `list` action omits them, so the + * apply diff can't otherwise see remote rules and would churn a perpetual + * "rules changed" update). Maps the server's `*_entity_type_slug` columns to + * the `{ source, target }` shape the diff compares against desired. + */ + async listRelationshipTypeRules( + slug: string + ): Promise> { + const { body } = await this.request<{ + rules?: Array<{ + source_entity_type_slug?: string; + target_entity_type_slug?: string; + }>; + }>("POST", `/api/${this.orgSlug}/manage_entity_schema`, { + schema_type: "relationship_type", + action: "list_rules", + slug, + }); + return (body.rules ?? []) + .filter((r) => r.source_entity_type_slug && r.target_entity_type_slug) + .map((r) => ({ + source: r.source_entity_type_slug as string, + target: r.target_entity_type_slug as string, + })); + } + async upsertRelationshipType(rel: { slug: string; name?: string; diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index 23442c5f3..e9ce68d0e 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -207,6 +207,21 @@ function stringChanged( return (a ?? "") !== (b ?? ""); } +/** + * Compare an OPTIONAL display name. When the config omits it (undefined/empty), + * the operator has no opinion — the server keeps its derived/stored name (e.g. + * a feed `display_name` defaulted from the feed key), so an omitted name must + * NOT churn the plan into a perpetual "name changed" update. Only a name the + * operator explicitly set, and that differs, is a real change. + */ +function optionalNameChanged( + desired: string | null | undefined, + remote: string | null | undefined +): boolean { + if (desired == null || desired === "") return false; + return stringChanged(desired, remote); +} + /** * The shared create / noop / update shape behind most `diffX` functions. * `extras` is merged into every row (create/noop/update); `updateExtras` @@ -765,7 +780,7 @@ function diffConnection( fields: [ { name: "name", - changed: (d, r) => stringChanged(d.name, r.display_name), + changed: (d, r) => optionalNameChanged(d.name, r.display_name), }, { name: "auth", @@ -804,7 +819,7 @@ function diffFeed( fields: [ { name: "name", - changed: (d, r) => stringChanged(d.name, r.display_name), + changed: (d, r) => optionalNameChanged(d.name, r.display_name), }, { name: "schedule", From a5dc5ffaceade117e6c70d8d38b40e7c5ee78d6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 16:46:24 +0100 Subject: [PATCH 58/65] fix(apply,schema): second-round review fixes (tenant isolation + declarative rules) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fresh full-diff pi review (bug_free 58) — 2 blockers + 2 bugs, all fixed: - P1 write-mode requireRelationshipType did an unscoped slug lookup and threw 'Access denied' for a slug owned only by another (private) org — an existence oracle. Scope the lookup to ctx.organizationId; a missing own row is now 'not found'. A tenant can only update/delete its OWN types anyway (public foreign types stay referenceable-but-read-only). - P2 relationship-type rules are now fully declarative: upsertRelationshipType reconciles (add_rule for missing, remove_rule by id for extras) against the current remote set, and the snapshot hydrates rules for EVERY config-declared rel-type (incl. those declared with no rules) so dropping all rules is detected. Was add-only → removing a rule never took effect and churned a perpetual 'rules changed' update. - P3 migration archives pre-fix rel-type tombstones (deleted_at set but status='active') so they leave the WHERE status='active' partial unique index and re-create can't collide. - P4 init-from-org platform config emission uses emitKey() so a non-identifier config key (e.g. hyphenated) generates valid lobu.config.ts. Tests: prune integration 10/10 (embedded PG, +foreign-private 'not found'); CLI 316. Live E2E proved the rule reconcile: stable=noop, removal removes + converges, change add+removes + converges. --- ...000_archive_deleted_relationship_types.sql | 20 ++++++ .../cli/src/commands/_lib/apply/apply-cmd.ts | 16 ++--- .../cli/src/commands/_lib/apply/client.ts | 68 ++++++++++++------- .../commands/_lib/init-from-org/bootstrap.ts | 11 +-- packages/owletto | 2 +- .../src/__tests__/integration/prune.test.ts | 25 +++++++ .../src/tools/admin/manage_entity_schema.ts | 24 +++---- 7 files changed, 115 insertions(+), 51 deletions(-) create mode 100644 db/migrations/20260522160000_archive_deleted_relationship_types.sql diff --git a/db/migrations/20260522160000_archive_deleted_relationship_types.sql b/db/migrations/20260522160000_archive_deleted_relationship_types.sql new file mode 100644 index 000000000..6154f3ce6 --- /dev/null +++ b/db/migrations/20260522160000_archive_deleted_relationship_types.sql @@ -0,0 +1,20 @@ +-- migrate:up + +-- Repair relationship-type tombstones left by the old delete path. The +-- (organization_id, slug) uniqueness index is partial on `WHERE status = +-- 'active'`, but the old delete only set `deleted_at` and left `status = +-- 'active'`, so a tombstoned row kept occupying the index — re-creating the +-- same slug (e.g. `lobu apply` prune then re-add) hit a unique violation. +-- The delete path now also sets `status = 'archived'` (see rtHandleDelete); +-- this backfills the rows deleted before that fix so re-create can't collide. +-- 'archived' is the only other status the check constraint permits. +UPDATE public.entity_relationship_types +SET status = 'archived' +WHERE deleted_at IS NOT NULL AND status = 'active'; + +-- migrate:down + +-- No-op: archiving an already-deleted (deleted_at IS NOT NULL) row is not +-- meaningfully reversible — the rows are tombstones either way, and reverting +-- status to 'active' would re-introduce the unique-index collision this fixes. +SELECT 1; diff --git a/packages/cli/src/commands/_lib/apply/apply-cmd.ts b/packages/cli/src/commands/_lib/apply/apply-cmd.ts index 4289cc312..953474790 100644 --- a/packages/cli/src/commands/_lib/apply/apply-cmd.ts +++ b/packages/cli/src/commands/_lib/apply/apply-cmd.ts @@ -286,17 +286,17 @@ async function fetchRemoteSnapshot( only === "agents" ? [] : await client.listRelationshipTypes(); // The relationship-type `list` action omits rules, so the diff would compare // desired rules against an always-empty remote and churn a perpetual "rules - // changed" update. Hydrate rules for the types the config also declares with - // rules (bounded fetch — skip types with no desired rules to compare). + // changed" update. Hydrate rules for every type the config also declares — + // including those the config declares with NO rules, so dropping all rules is + // detected as a change (and reconciled away) rather than a silent noop. if (relationshipTypes.length > 0) { - const desiredRuleSlugs = new Set( - state.memorySchema.relationshipTypes - .filter((r) => (r.rules?.length ?? 0) > 0) - .map((r) => r.slug) + const desiredRelSlugs = new Set( + state.memorySchema.relationshipTypes.map((r) => r.slug) ); for (const remote of relationshipTypes) { - if (!desiredRuleSlugs.has(remote.slug)) continue; - remote.rules = await client.listRelationshipTypeRules(remote.slug); + if (!desiredRelSlugs.has(remote.slug)) continue; + const rules = await client.listRelationshipTypeRules(remote.slug); + remote.rules = rules.map((r) => ({ source: r.source, target: r.target })); } } const watchers = only === "agents" ? [] : await client.listWatchers(); diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index fa368f1a4..cfadb2c2c 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -578,13 +578,14 @@ export class ApplyClient { * Fetch a relationship type's rules (the `list` action omits them, so the * apply diff can't otherwise see remote rules and would churn a perpetual * "rules changed" update). Maps the server's `*_entity_type_slug` columns to - * the `{ source, target }` shape the diff compares against desired. + * `{ source, target }`; `id` is carried for reconcile (remove_rule by id). */ async listRelationshipTypeRules( slug: string - ): Promise> { + ): Promise> { const { body } = await this.request<{ rules?: Array<{ + id?: number; source_entity_type_slug?: string; target_entity_type_slug?: string; }>; @@ -594,8 +595,12 @@ export class ApplyClient { slug, }); return (body.rules ?? []) - .filter((r) => r.source_entity_type_slug && r.target_entity_type_slug) + .filter( + (r) => + r.id != null && r.source_entity_type_slug && r.target_entity_type_slug + ) .map((r) => ({ + id: r.id as number, source: r.source_entity_type_slug as string, target: r.target_entity_type_slug as string, })); @@ -613,28 +618,45 @@ export class ApplyClient { payload ); - // Register rules separately via add_rule. Backend treats add_rule as - // idempotent; duplicate-add surfaces a structured error we can swallow. - if (rules?.length) { - for (const rule of rules) { - try { - await this.request( - "POST", - `/api/${this.orgSlug}/manage_entity_schema`, - { - schema_type: "relationship_type", - action: "add_rule", - slug: rel.slug, - source_entity_type_slug: rule.source, - target_entity_type_slug: rule.target, - } - ); - } catch (err) { - if (err instanceof ApiError && isDuplicateError(err)) continue; - throw err; - } + // Reconcile rules to exactly the desired set so config is the source of + // truth (declarative). Without removing extras, dropping a rule from config + // would never take effect AND would churn a perpetual "rules changed" + // update on every apply. add_rule is idempotent; remove_rule takes a id. + const desired = rules ?? []; + const ruleKey = (r: { source: string; target: string }) => + `${r.source}${r.target}`; + const desiredKeys = new Set(desired.map(ruleKey)); + const remote = await this.listRelationshipTypeRules(rel.slug); + const remoteKeys = new Set(remote.map(ruleKey)); + + for (const rule of desired) { + if (remoteKeys.has(ruleKey(rule))) continue; + try { + await this.request( + "POST", + `/api/${this.orgSlug}/manage_entity_schema`, + { + schema_type: "relationship_type", + action: "add_rule", + slug: rel.slug, + source_entity_type_slug: rule.source, + target_entity_type_slug: rule.target, + } + ); + } catch (err) { + if (err instanceof ApiError && isDuplicateError(err)) continue; + throw err; } } + for (const rule of remote) { + if (desiredKeys.has(ruleKey(rule))) continue; + await this.request("POST", `/api/${this.orgSlug}/manage_entity_schema`, { + schema_type: "relationship_type", + action: "remove_rule", + slug: rel.slug, + rule_id: rule.id, + }); + } return result; } diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index e3f369323..8f33fb852 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -412,19 +412,22 @@ function emitAgent( const cfg: Record = { ...(p.config ?? {}) }; delete cfg.platform; const cfgLines = Object.entries(cfg).map(([k, v]) => { + // emitKey quotes keys that aren't valid TS identifiers (e.g. hyphenated + // platform config keys) so the generated config always parses. + const key = emitKey(k); if (typeof v === "string") { const explicitVar = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(v); if (explicitVar?.[1]) { - return `${k}: ${secrets.ref(explicitVar[1])}`; + return `${key}: ${secrets.ref(explicitVar[1])}`; } // Opaque secret (redacted `***…` or internal `secret://…`): derive a // deterministic env-var name from the agent + config key. if (v.startsWith("***") || v.startsWith("secret://")) { - return `${k}: ${secrets.ref(envVarFor(agent.agentId, `${p.platform}_${k}`.toUpperCase()))}`; + return `${key}: ${secrets.ref(envVarFor(agent.agentId, `${p.platform}_${k}`.toUpperCase()))}`; } - return `${k}: ${str(v)}`; + return `${key}: ${str(v)}`; } - return `${k}: ${emitValue(v, 3)}`; + return `${key}: ${emitValue(v, 3)}`; }); // Recover the name from the stable id (`-[-]`) so a // NAMED platform re-derives the same id on apply (no drift/duplicate). diff --git a/packages/owletto b/packages/owletto index 887e8626a..06b1543eb 160000 --- a/packages/owletto +++ b/packages/owletto @@ -1 +1 @@ -Subproject commit 887e8626a194da652bde66772c3cf6dfeb704820 +Subproject commit 06b1543ebf733a73659d7aee3963e9c25c680382 diff --git a/packages/server/src/__tests__/integration/prune.test.ts b/packages/server/src/__tests__/integration/prune.test.ts index 9ec2660c2..307163c45 100644 --- a/packages/server/src/__tests__/integration/prune.test.ts +++ b/packages/server/src/__tests__/integration/prune.test.ts @@ -132,6 +132,31 @@ describe('prune (server gate)', () => { expect(foreign?.deleted_at).toBeNull(); }); + it("update/delete of a slug owned only by another PRIVATE org reports 'not found' (no existence leak)", async () => { + const sql = getTestDb(); + const other = await createTestOrganization({ name: 'Private Owner Org' }); + await sql` + INSERT INTO entity_relationship_types (organization_id, slug, name, status, created_at, updated_at) + VALUES (${other.id}, ${'foreign-only'}, 'Foreign Only', 'active', NOW(), NOW()) + `; + // The caller has no own 'foreign-only'. Write-mode lookup is org-scoped, + // so it must report 'not found' — never 'access denied', which would leak + // that the slug exists in another org. + await expect( + owner.entity_schema.deleteRelType('foreign-only') + ).rejects.toThrow(/not found/i); + await expect( + owner.entity_schema.updateRelType({ slug: 'foreign-only', name: 'x' }) + ).rejects.toThrow(/not found/i); + // Foreign row untouched. + const [foreign] = await sql<{ deleted_at: string | null; name: string }[]>` + SELECT deleted_at, name FROM entity_relationship_types + WHERE organization_id = ${other.id} AND slug = ${'foreign-only'} + `; + expect(foreign?.deleted_at).toBeNull(); + expect(foreign?.name).toBe('Foreign Only'); + }); + it('deletes a watcher', async () => { const agent = await createTestAgent({ organizationId: orgId }); const created = (await owner.watchers.create({ diff --git a/packages/server/src/tools/admin/manage_entity_schema.ts b/packages/server/src/tools/admin/manage_entity_schema.ts index 77c7a3032..b4a0cb08a 100644 --- a/packages/server/src/tools/admin/manage_entity_schema.ts +++ b/packages/server/src/tools/admin/manage_entity_schema.ts @@ -754,27 +754,21 @@ async function requireRelationshipType( return { typeId: Number(rows[0].id), sql }; } - // Tenant-first ordering: when the caller's org owns a relationship type AND a - // public type from another org shares the slug, resolve the caller's OWN row. - // Without this, `LIMIT 1` could grab the foreign public row and the - // access-denied guard below would wrongly block the caller from - // updating/deleting its own type (and break code-managed prune). + // Write mode (update/delete/add_rule/…) only ever touches the caller's OWN + // type, so scope the lookup to ctx.organizationId. A public type from another + // org shares the slug but is read-only to this tenant (referenceable as an + // inverse, never mutable), and a PRIVATE foreign row must stay invisible — an + // unscoped lookup that fell back to a foreign row and threw 'Access denied' + // leaked the slug's existence in another org. Absent an own row → 'not found'. const existing = await sql` - SELECT id, organization_id FROM entity_relationship_types + SELECT id FROM entity_relationship_types WHERE slug = ${slug} AND deleted_at IS NULL - ORDER BY (organization_id = ${ctx.organizationId}) DESC, id ASC + AND organization_id = ${ctx.organizationId} LIMIT 1 `; if (existing.length === 0) throw new Error(`Relationship type "${slug}" not found`); - const typeId = Number(existing[0].id); - const typeOrgId = String(existing[0].organization_id ?? ''); - - if (typeOrgId && typeOrgId !== ctx.organizationId) { - throw new Error('Access denied: relationship type belongs to another organization'); - } - - return { typeId, sql }; + return { typeId: Number(existing[0].id), sql }; } /** From 2033dc3bf4057be96b942727cac1c5e7956a67c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 16:55:15 +0100 Subject: [PATCH 59/65] fix(init,apply): sanitize derived secret env-var names + drop stray NUL delimiter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Final pi review (bug_free 82, 0 blockers) — 1 medium bug + 1 hygiene: - envVarFor only normalized the slug, not the suffix, so a non-identifier platform config key (e.g. `bot-token`) produced an invalid POSIX env-var name (`BOT_TELEGRAM_BOT-TOKEN`) — the .env key would be rejected and apply's required-secret check would never pass. Normalize both parts. Added a regression test (quoted key + sanitized env var + round-trip). - The rules reconcile rule-key delimiter was an actual NUL byte, which made grep/rg treat client.ts as binary. Replaced with a tab (slugs never contain whitespace, so it's still an unambiguous composite key). CLI 317 green; no NUL bytes remain in cli/src. --- .../cli/src/commands/_lib/apply/client.ts | 2 +- .../__tests__/init-from-org.test.ts | 49 +++++++++++++++++++ .../commands/_lib/init-from-org/bootstrap.ts | 8 ++- 3 files changed, 56 insertions(+), 3 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/client.ts b/packages/cli/src/commands/_lib/apply/client.ts index cfadb2c2c..f1469c57c 100644 --- a/packages/cli/src/commands/_lib/apply/client.ts +++ b/packages/cli/src/commands/_lib/apply/client.ts @@ -624,7 +624,7 @@ export class ApplyClient { // update on every apply. add_rule is idempotent; remove_rule takes a id. const desired = rules ?? []; const ruleKey = (r: { source: string; target: string }) => - `${r.source}${r.target}`; + `${r.source} ${r.target}`; const desiredKeys = new Set(desired.map(ruleKey)); const remote = await this.listRelationshipTypeRules(rel.slug); const remoteKeys = new Set(remote.map(ruleKey)); diff --git a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts index fe9004a70..a1733aff4 100644 --- a/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts +++ b/packages/cli/src/commands/_lib/init-from-org/__tests__/init-from-org.test.ts @@ -525,6 +525,55 @@ describe("lobu init --from-org", () => { } }); + test("non-identifier platform config key → quoted key + valid POSIX env var", async () => { + const dir = mkFixtureDir(); + await initFromOrg({ + targetDir: dir, + fetchImpl: buildFetch({ + "/oauth/userinfo": () => ({ + organizations: [{ id: "org-1", slug: "acme", name: "Acme Inc" }], + }), + "/agents/bot/platforms": () => ({ + platforms: [ + { + id: "bot-telegram", + platform: "telegram", + // A hyphenated config key: the emitted TS key must be quoted, and + // the derived secret env var must be a valid POSIX name (no `-`). + config: { platform: "telegram", "bot-token": "***oken" }, + }, + ], + }), + "/agents/bot/config": () => ({ updatedAt: 0 }), + "/agents": () => ({ agents: [{ agentId: "bot", name: "Bot" }] }), + "watchers?include_details": () => ({ watchers: [] }), + manage_entity_schema: () => ({ + entity_types: [], + relationship_types: [], + }), + manage_auth_profiles: () => ({ auth_profiles: [] }), + manage_connections: () => ({ connections: [] }), + }), + }); + + const source = readFileSync(join(dir, "lobu.config.ts"), "utf-8"); + const envExample = readFileSync(join(dir, ".env.example"), "utf-8"); + // Key quoted, env var sanitized (hyphen → underscore), no invalid POSIX key. + expect(source).toContain('"bot-token": secret("BOT_TELEGRAM_BOT_TOKEN")'); + expect(source).not.toContain("BOT-TOKEN"); + expect(envExample).toContain("BOT_TELEGRAM_BOT_TOKEN="); + expect(envExample).not.toMatch(/^[A-Z0-9_]*-/m); + + // Round-trips: the regenerated config loads (proves the .env key is valid). + process.env.BOT_TELEGRAM_BOT_TOKEN = "dummy"; + try { + const { state } = await loadDesiredStateFromConfig({ cwd: dir }); + expect(state.agents[0]?.platforms[0]?.config["bot-token"]).toBe("dummy"); + } finally { + process.env.BOT_TELEGRAM_BOT_TOKEN = undefined; + } + }); + test("MCP oauth clientSecret → emits secret() AND imports it (no missing-import)", async () => { const dir = mkFixtureDir(); await initFromOrg({ diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index 8f33fb852..12c218b03 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -168,8 +168,12 @@ class SecretCollector { /** Uppercase env-var name from a slug/key (e.g. `gh-token` → `GH_TOKEN_API_KEY`). */ function envVarFor(slug: string, suffix: string): string { - const base = slug.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase(); - return `${base}_${suffix}`; + // Normalize BOTH parts to a valid POSIX env-var name. The suffix can carry a + // non-identifier platform config key (e.g. `bot-token` → `..._BOT_TOKEN`); an + // un-normalized hyphen would make the `.env` key invalid and fail apply's + // required-secret check. + const norm = (s: string) => s.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase(); + return `${norm(slug)}_${norm(suffix)}`; } /** From 4d68e26ef503a18d8a85f91d6b6b8f82827dde70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 17:03:48 +0100 Subject: [PATCH 60/65] fix(apply): never prune system ($-prefixed) definitions like $member MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Found via live prune E2E (the gap I flagged). With prune:true, apply marked the per-org system entity type $member 'will be deleted' (it's absent from config and can't be declared — the server reserves $ slugs). The delete is then refused because member rows exist, which HALTS the entire apply on first failure — so prune:true apply failed on every run for any org with members (i.e. every real org). If an org somehow had no member rows, it would instead DELETE the system type and corrupt the org. computeDiff now exempts $-prefixed entity/relationship/watcher definitions from prune: they stay ignorable drift in both modes, never delete. Regression test added (prune.test covers the server refusal; diff.test covers the verb). E2E: prune now creates all defs (no halt), $member stays drift, removing lead/knows/w-drop deletes exactly those, kept defs + $member survive, re-apply is a clean noop. --- .../_lib/apply/__tests__/diff.test.ts | 29 +++++++++++++++++++ packages/cli/src/commands/_lib/apply/diff.ts | 14 +++++++-- 2 files changed, 40 insertions(+), 3 deletions(-) diff --git a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts index 58dc0619b..c8bc97ed2 100644 --- a/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts +++ b/packages/cli/src/commands/_lib/apply/__tests__/diff.test.ts @@ -1302,6 +1302,35 @@ describe("apply diff — prune", () => { expect(deletedIds.some((id) => id.includes("other"))).toBe(false); }); + test("prune never deletes system ($-prefixed) definitions (e.g. $member)", () => { + // Regression: $member is a per-org SYSTEM entity type the server provisions; + // it can't be declared in config, so prune would mark it deleted and then + // HALT every apply (the delete is refused while member rows exist). System + // definitions must stay ignorable drift, never delete. + const remote: RemoteSnapshot = { + ...emptyRemote(), + entityTypes: [ + { slug: "lead", properties: {}, organization_id: "org_self" }, + { slug: "$member", organization_id: "org_self" }, + ], + relationshipTypes: [{ slug: "$system-rel", organization_id: "org_self" }], + watchers: [{ slug: "$system-watcher" }], + }; + const plan = computeDiff(desiredKeepingLead(), remote, { + prune: true, + orgId: "org_self", + }); + const verbOf = (kind: string, id: string) => + plan.rows.find((r) => r.kind === kind && r.id === id)?.verb; + expect(verbOf("entity-type", "$member")).toBe("drift"); + expect(verbOf("relationship-type", "$system-rel")).toBe("drift"); + expect(verbOf("watcher", "$system-watcher")).toBe("drift"); + // No system definition is ever in the delete set. + expect( + plan.rows.some((r) => r.verb === "delete" && r.id.startsWith("$")) + ).toBe(false); + }); + test("matching prefers the org's own type over a foreign public type with the same slug", () => { // Server returns the org's own row first, then a public row with the same // slug. Matching must compare desired against the org-owned row (noop), not diff --git a/packages/cli/src/commands/_lib/apply/diff.ts b/packages/cli/src/commands/_lib/apply/diff.ts index e9ce68d0e..f5dd80cd7 100644 --- a/packages/cli/src/commands/_lib/apply/diff.ts +++ b/packages/cli/src/commands/_lib/apply/diff.ts @@ -903,6 +903,13 @@ export function computeDiff( orgId === undefined || definitionOrgId === undefined || definitionOrgId === orgId; + // `$`-prefixed definitions (e.g. the per-org `$member` entity type) are + // SYSTEM-managed — the server provisions them and rejects `$` slugs in + // create, so they can never appear in a user's config. They must NEVER be + // pruned (deleting `$member` corrupts the org; and because the delete is + // refused while member rows exist, an un-exempted prune HALTS every apply). + // They only ever surface as ignorable drift, in both prune and non-prune. + const isSystemSlug = (slug: string): boolean => slug.startsWith("$"); if (only !== "memory") { const remoteByAgent = new Map(remote.agents.map((a) => [a.agentId, a])); @@ -994,9 +1001,10 @@ export function computeDiff( if (!desiredEntitySlugs.has(remoteEntity.slug)) { // Code-managed: delete. The server refuses an entity-type delete while // instances exist (the data is exempt), surfacing a clear error. + // System (`$`) types are never user-declared → never pruned. rows.push({ kind: "entity-type", - verb: prune ? "delete" : "drift", + verb: prune && !isSystemSlug(remoteEntity.slug) ? "delete" : "drift", id: remoteEntity.slug, remote: remoteEntity, }); @@ -1017,7 +1025,7 @@ export function computeDiff( if (!desiredRelSlugs.has(remoteRel.slug)) { rows.push({ kind: "relationship-type", - verb: prune ? "delete" : "drift", + verb: prune && !isSystemSlug(remoteRel.slug) ? "delete" : "drift", id: remoteRel.slug, remote: remoteRel, }); @@ -1035,7 +1043,7 @@ export function computeDiff( if (!desiredWatcherSlugs.has(remoteWatcher.slug)) { rows.push({ kind: "watcher", - verb: prune ? "delete" : "drift", + verb: prune && !isSystemSlug(remoteWatcher.slug) ? "delete" : "drift", id: remoteWatcher.slug, remote: remoteWatcher, }); From d7d1558dfaacea7ada52d3aadd10039673ebbcb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 17:26:57 +0100 Subject: [PATCH 61/65] test(e2e): add SDK lifecycle e2e gate (apply + prune + real worker turn) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the coverage gap: unit/integration prove config MAPS correctly, but nothing proved the whole SDK path RUNS. scripts/sdk-e2e.sh boots `lobu run` (embedded Postgres — the linux binary ships as an @embedded-postgres optional dep, the engine prod uses), auto-applies a prune:true fixture, and drives a REAL agent turn through a spawned worker against a deterministic mock OpenAI-compatible provider (scripts/sdk-e2e/, no provider key → reproducible). Asserts (non-zero exit → red CI): auto-apply completes (not halted — guards the $member prune-halt class), every definition is created, $member is never pruned, the agent turn returns the mock reply via the worker→secret-proxy→ upstream path, and a stable re-apply is idempotent (0 deletes). Wired as the CI `sdk-e2e` job (Node 22 for isolated-vm; failure fails the PR) and `make test-e2e-sdk`. Verified locally: 5/5 assertions pass. --- .github/workflows/ci.yml | 36 +++++++++ .gitignore | 1 + Makefile | 9 ++- scripts/sdk-e2e.sh | 138 ++++++++++++++++++++++++++++++++ scripts/sdk-e2e/mock-openai.mjs | 65 +++++++++++++++ scripts/sdk-e2e/providers.json | 19 +++++ 6 files changed, 267 insertions(+), 1 deletion(-) create mode 100755 scripts/sdk-e2e.sh create mode 100644 scripts/sdk-e2e/mock-openai.mjs create mode 100644 scripts/sdk-e2e/providers.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a3750e820..1acc56b6c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -101,6 +101,42 @@ jobs: files: coverage/lcov.info fail_ci_if_error: false + # SDK lifecycle e2e — the hard gate that the WHOLE TypeScript-SDK path runs, + # not just that config maps (unit/integration cover that). Boots `lobu run` + # (embedded Postgres — the linux binary ships as an @embedded-postgres + # optional dep, the same engine prod uses), auto-applies a prune:true fixture, + # and drives a real agent turn through a spawned worker against a deterministic + # mock OpenAI-compatible provider (no provider key needed). A failure here + # fails CI → the PR goes red. See scripts/sdk-e2e.sh. + sdk-e2e: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: actions/checkout@v4 + + - uses: ./.github/actions/setup-submodule + with: + deploy-key: ${{ secrets.OWLETTO_WEB_DEPLOY_KEY }} + + - uses: oven-sh/setup-bun@v2 + with: + bun-version: 1.3.5 + + # Node 22 — the worker uses isolated-vm (abi127 prebuild); the runner's + # default Node major would segfault the sandbox runtime. + - uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Install dependencies + run: bun install + + - name: Build all packages (CLI + server bundle + sdk + pgvector-embedded) + run: make build-packages + + - name: SDK lifecycle e2e (apply + prune + real worker turn) + run: bash scripts/sdk-e2e.sh + # Frontend tests run under jsdom via vitest. owletto is a submodule; # forks without the deploy key get a stub package and skip these. frontend: diff --git a/.gitignore b/.gitignore index aba962644..7a23b9b5c 100644 --- a/.gitignore +++ b/.gitignore @@ -95,3 +95,4 @@ packages/*/~/ # Embedded PGlite dev data (make dev without DATABASE_URL) .lobu-dev/ +.sdk-e2e-run/ diff --git a/Makefile b/Makefile index 33337a39e..ac07dc36c 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # Development Makefile for Lobu -.PHONY: help setup build test clean dev build-packages ensure-submodule clean-workers test-unit test-integration test-e2e typecheck task-setup task-clean e2e-browser bump review +.PHONY: help setup build test clean dev build-packages ensure-submodule clean-workers test-unit test-integration test-e2e test-e2e-sdk typecheck task-setup task-clean e2e-browser bump review # Default target help: @@ -141,6 +141,13 @@ test-e2e: @: $${DATABASE_URL?Set DATABASE_URL=postgres://… (with pgvector) before running} @./scripts/run-e2e.sh +# SDK lifecycle e2e: boots `lobu run` (embedded Postgres), auto-applies a +# prune:true fixture, and drives a real agent turn through a spawned worker +# against a deterministic mock provider (no key needed). Self-contained. This is +# the CI `sdk-e2e` gate; run it locally the same way. +test-e2e-sdk: + @./scripts/sdk-e2e.sh + # Stop any embedded worker subprocesses left over from a crashed gateway. # Workers are normally cleaned up when the gateway exits; this target is a # safety net for orphaned bun processes spawned by EmbeddedDeploymentManager. diff --git a/scripts/sdk-e2e.sh b/scripts/sdk-e2e.sh new file mode 100755 index 000000000..5229c8f4b --- /dev/null +++ b/scripts/sdk-e2e.sh @@ -0,0 +1,138 @@ +#!/usr/bin/env bash +# +# SDK lifecycle end-to-end gate. +# +# Proves the WHOLE TypeScript-SDK path actually runs — not just that config maps +# correctly (unit/integration cover that), but that `lobu run` boots, auto-applies +# a project, exercises prune, and an agent completes a real turn through a spawned +# worker. Runs against a DETERMINISTIC mock OpenAI-compatible provider (see +# scripts/sdk-e2e/), so it needs no provider key and is reproducible in CI. +# +# It asserts, failing (non-zero exit → red CI) on any miss: +# 1. lobu run auto-applies the fixture → "Apply complete" (NOT halted). With a +# prune:true fixture this also guards the system-type ($member) exemption — +# an un-exempted prune halts every apply. +# 2. every declared definition is created (agent, entity/relationship types, +# watcher). +# 3. `lobu chat` drives a real turn through the worker → the mock's reply. +# 4. a stable re-apply is idempotent (0 deletes). +# +# Usage: scripts/sdk-e2e.sh (embedded Postgres, the default) +# DATABASE_URL=... scripts/sdk-e2e.sh (use an external Postgres) +set -euo pipefail + +WT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +HARNESS="$WT/scripts/sdk-e2e" +LOBU="node $WT/packages/cli/bin/lobu.js" +GW_PORT="${GW_PORT:-8793}" +MOCK_PORT="${MOCK_PORT:-11434}" +MOCK_REPLY="SDK_E2E_OK" +RUN_DIR="$WT/.sdk-e2e-run" +RUN_LOG="$RUN_DIR/run.log" +MOCK_LOG="$RUN_DIR/mock.log" +CHAT_OUT="$RUN_DIR/chat.out" + +# Node 22-24 is required (the worker uses isolated-vm). Prefer a Homebrew node@22 +# locally; CI provides node via actions/setup-node. +if [ -x /opt/homebrew/opt/node@22/bin/node ] && ! node --version 2>/dev/null | grep -qE '^v(22|23|24)\.'; then + export PATH="/opt/homebrew/opt/node@22/bin:$PATH" +fi + +MOCK_PID="" +cleanup() { + [ -n "$MOCK_PID" ] && kill -9 "$MOCK_PID" 2>/dev/null || true + lsof -nP -iTCP:"$GW_PORT" -sTCP:LISTEN -t 2>/dev/null | xargs -r kill -9 2>/dev/null || true + lsof -nP -iTCP:"$MOCK_PORT" -sTCP:LISTEN -t 2>/dev/null | xargs -r kill -9 2>/dev/null || true +} +trap cleanup EXIT + +fail() { echo "❌ SDK e2e FAILED: $*" >&2; [ -f "$RUN_LOG" ] && { echo "--- last 40 lines of run.log ---" >&2; tail -40 "$RUN_LOG" >&2; }; exit 1; } + +echo "▶ node $(node --version), gateway :$GW_PORT, mock :$MOCK_PORT" +rm -rf "$RUN_DIR"; mkdir -p "$RUN_DIR" +cleanup # free ports from any prior run + +# 1) Mock OpenAI-compatible provider. +MOCK_PORT="$MOCK_PORT" MOCK_REPLY="$MOCK_REPLY" node "$HARNESS/mock-openai.mjs" > "$MOCK_LOG" 2>&1 & +MOCK_PID=$! +disown "$MOCK_PID" 2>/dev/null || true # silence job-control "Killed" on cleanup +for _ in $(seq 1 20); do + curl -fsS -X POST "http://127.0.0.1:$MOCK_PORT/v1/chat/completions" -H 'content-type: application/json' -d '{}' >/dev/null 2>&1 && break + sleep 0.5 +done +curl -fsS -X POST "http://127.0.0.1:$MOCK_PORT/v1/chat/completions" -H 'content-type: application/json' -d '{}' >/dev/null 2>&1 || fail "mock server did not come up" +echo "✓ mock provider up" + +# 2) Scaffold a project (inside the repo so jiti resolves the workspace @lobu/sdk). +PROJ="$RUN_DIR/proj"; mkdir -p "$PROJ" +( cd "$PROJ" && $LOBU init . -y --here --provider gemini >/dev/null 2>&1 ) +rm -f "$PROJ/package.json" +cat > "$PROJ/lobu.config.ts" <<'TS' +import { defineAgent, defineConfig, defineEntityType, defineRelationshipType, defineWatcher, secret } from "@lobu/sdk"; + +const agent = defineAgent({ + id: "echo", name: "Echo", dir: "./agents/echo", + providers: [{ id: "mock", model: "mock-model", key: secret("MOCK_API_KEY") }], +}); +const company = defineEntityType({ key: "company", name: "Company" }); +const contact = defineEntityType({ key: "contact", name: "Contact" }); +const worksAt = defineRelationshipType({ key: "works-at", name: "Works at", rules: [{ source: contact, target: company }] }); +const digest = defineWatcher({ + slug: "digest", agent, name: "Digest", prompt: "summarize", + extractionSchema: { type: "object", properties: { s: { type: "string" } } }, +}); + +// prune:true so the gate exercises the destructive path on every run (this is +// what catches the system-type $member halt class of bug). +export default defineConfig({ prune: true, agents: [agent], entities: [company, contact], relationships: [worksAt], watchers: [digest] }); +TS + +# Project env: mock key, allow loopback egress (mock provider), embedded PG unless +# DATABASE_URL was provided. Lead with a newline so the first line can't glue +# onto a scaffolded .env that lacks a trailing newline. +{ + printf '\n' + echo "MOCK_API_KEY=mock-key-e2e" + echo "WORKER_ALLOWED_DOMAINS=127.0.0.1,localhost" + [ -n "${DATABASE_URL:-}" ] && echo "DATABASE_URL=$DATABASE_URL" +} >> "$PROJ/.env" + +export LOBU_PROVIDER_REGISTRY_PATH="$HARNESS/providers.json" + +# 3) Boot lobu run — it auto-applies the project (the apply + prune E2E). +( cd "$PROJ" && $LOBU run --port "$GW_PORT" > "$RUN_LOG" 2>&1 ) & +for _ in $(seq 1 80); do + grep -qiE "Apply complete|auto-apply skipped|Apply halted" "$RUN_LOG" 2>/dev/null && break + sleep 1 +done + +grep -qi "Apply complete" "$RUN_LOG" || fail "auto-apply did not complete (skipped/halted?)" +grep -qiE "Apply halted" "$RUN_LOG" && fail "apply halted on a failure" +echo "✓ lobu run auto-applied the project (Apply complete)" + +# 2b) Every declared definition created. +for marker in "+ entity-type company" "+ entity-type contact" "+ relationship-type works-at" "+ watcher digest"; do + grep -qF "$marker" "$RUN_LOG" || fail "expected created definition not in plan: '$marker'" +done +# System $member must be ignorable drift, never a delete row (the prune-halt bug). +grep -qiE "entity-type .member \(removed from config — will be deleted\)|delete.*\\\$member" "$RUN_LOG" && fail "prune tried to delete the system \$member type" +echo "✓ all definitions created; \$member not pruned" + +# 4) A real agent turn through the worker. +( cd "$PROJ" && timeout 90 $LOBU chat "say the safe word" -c local > "$CHAT_OUT" 2>&1 ) || fail "lobu chat exited non-zero" +grep -qF "$MOCK_REPLY" "$CHAT_OUT" || fail "agent turn did not return the mock reply '$MOCK_REPLY' (got: $(tr -d '\n' < "$CHAT_OUT" | tail -c 200))" +grep -qiE "Forwarding to upstream: POST http://127.0.0.1:$MOCK_PORT" "$RUN_LOG" || fail "worker never called the mock provider upstream" +echo "✓ agent completed a real turn through the worker (reply: $MOCK_REPLY)" + +# 5) Idempotent re-apply (stable config → 0 deletes). Unlike `lobu run`, `lobu +# apply` does not auto-load the project .env, so pass the secret it resolves for +# the provider-key push explicitly. +REAPPLY="$RUN_DIR/reapply.out" +( cd "$PROJ" && MOCK_API_KEY=mock-key-e2e $LOBU apply --url "http://localhost:$GW_PORT" --yes > "$REAPPLY" 2>&1 ) || { cat "$REAPPLY" >&2; fail "re-apply exited non-zero"; } +# A fully-idempotent re-apply prints "Nothing to apply." (everything noop/drift); +# a partial one prints "Apply complete.". Either is fine — a delete row is not. +grep -qiE "Nothing to apply|Apply complete" "$REAPPLY" || { cat "$REAPPLY" >&2; fail "re-apply neither completed nor was a noop"; } +if grep -qE "Summary:.*[1-9][0-9]* delete" "$REAPPLY"; then fail "re-apply was not idempotent (deleted something on a stable config)"; fi +echo "✓ re-apply is idempotent (no deletes on a stable config)" + +echo "✅ SDK lifecycle e2e PASSED" diff --git a/scripts/sdk-e2e/mock-openai.mjs b/scripts/sdk-e2e/mock-openai.mjs new file mode 100644 index 000000000..86737f51c --- /dev/null +++ b/scripts/sdk-e2e/mock-openai.mjs @@ -0,0 +1,65 @@ +import { createServer } from "node:http"; +const PORT = Number(process.env.MOCK_PORT || 11434); +const REPLY = process.env.MOCK_REPLY || "PONG"; +const server = createServer((req, res) => { + let body = ""; + req.on("data", (c) => (body += c)); + req.on("end", () => { + const url = req.url || ""; + if (url.includes("/models")) { + res.writeHead(200, { "content-type": "application/json" }); + res.end( + JSON.stringify({ + object: "list", + data: [{ id: "mock-model", object: "model" }], + }) + ); + return; + } + if (url.includes("/chat/completions")) { + let stream = false; + try { + stream = JSON.parse(body || "{}").stream === true; + } catch { + // non-JSON body → default to non-streaming + } + if (stream) { + res.writeHead(200, { + "content-type": "text/event-stream", + "cache-control": "no-cache", + }); + const id = "chatcmpl-mock"; + const chunk = (delta, finish) => + `data: ${JSON.stringify({ id, object: "chat.completion.chunk", model: "mock-model", choices: [{ index: 0, delta, finish_reason: finish ?? null }] })}\n\n`; + res.write(chunk({ role: "assistant" })); + res.write(chunk({ content: REPLY })); + res.write(chunk({}, "stop")); + res.write("data: [DONE]\n\n"); + res.end(); + } else { + res.writeHead(200, { "content-type": "application/json" }); + res.end( + JSON.stringify({ + id: "chatcmpl-mock", + object: "chat.completion", + model: "mock-model", + choices: [ + { + index: 0, + message: { role: "assistant", content: REPLY }, + finish_reason: "stop", + }, + ], + usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 }, + }) + ); + } + return; + } + res.writeHead(404); + res.end("not found"); + }); +}); +server.listen(PORT, "127.0.0.1", () => + console.log(`[mock-openai] listening on 127.0.0.1:${PORT}`) +); diff --git a/scripts/sdk-e2e/providers.json b/scripts/sdk-e2e/providers.json new file mode 100644 index 000000000..484d98258 --- /dev/null +++ b/scripts/sdk-e2e/providers.json @@ -0,0 +1,19 @@ +{ + "providers": [ + { + "id": "mock", + "name": "Mock", + "description": "Deterministic mock provider for e2e", + "providers": [ + { + "displayName": "Mock", + "envVarName": "MOCK_API_KEY", + "upstreamBaseUrl": "http://127.0.0.1:11434/v1", + "sdkCompat": "openai", + "defaultModel": "mock-model", + "modelsEndpoint": "/models" + } + ] + } + ] +} From 13426a14506445ec313d201c17662222176b3441 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 17:37:21 +0100 Subject: [PATCH 62/65] ci(sdk-e2e): install libicu60 so embedded-postgres initdb can load The sdk-e2e gate boots `lobu run`'s embedded Postgres, whose PG18 binary is dynamically linked against ICU 60 (libicuuc.so.60). ubuntu-latest ships a newer ICU, so initdb failed to load the shared lib. Install the 18.04-era libicu60 from the Ubuntu archive (with a security-mirror fallback) before the gate, and ldd the initdb binary to surface any further missing libs. Prod is unaffected (external Postgres; embedded-postgres is pruned from the app image). --- .github/workflows/ci.yml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1acc56b6c..5b56298df 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -131,6 +131,24 @@ jobs: - name: Install dependencies run: bun install + # `lobu run`'s embedded Postgres ships a PG18 binary dynamically linked + # against ICU 60 (libicuuc.so.60); ubuntu-latest carries a newer ICU, so + # initdb can't load without the 18.04-era lib. Prod doesn't hit this (it + # uses an external Postgres and prunes embedded-postgres), but the local + # `lobu run` path this gate exercises does. Install it from the Ubuntu + # archive (mirror fallback) and surface any remaining missing libs. + - name: Install libicu60 (embedded-postgres links against ICU 60) + run: | + set -euo pipefail + deb=libicu60_60.2-3ubuntu3.2_amd64.deb + curl -fsSL -o "/tmp/$deb" "http://archive.ubuntu.com/ubuntu/pool/main/i/icu/$deb" \ + || curl -fsSL -o "/tmp/$deb" "http://security.ubuntu.com/ubuntu/pool/main/i/icu/$deb" + sudo dpkg -i "/tmp/$deb" + ldconfig -p | grep -i libicuuc + echo "::group::ldd of embedded-postgres initdb" + ldd node_modules/@embedded-postgres/linux-x64/native/bin/initdb || true + echo "::endgroup::" + - name: Build all packages (CLI + server bundle + sdk + pgvector-embedded) run: make build-packages From bf9dc0700651af8a8233210673bae958e7c8dd18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 17:43:06 +0100 Subject: [PATCH 63/65] ci(sdk-e2e): disable systemd-run + install bubblewrap so the worker spawns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Embedded PG now boots on CI (libicu60), but the agent turn failed: the orchestrator wraps Linux workers in `systemd-run --user --scope`, which needs a user systemd/dbus session the CI runner doesn't have → worker exited 1. Set LOBU_DISABLE_SYSTEMD_RUN=1 for the gate (it only talks to the loopback mock; not testing the prod network sandbox) and install bubblewrap + enable unprivileged userns for the worker's exec-sandbox. No-op on macOS. --- .github/workflows/ci.yml | 9 +++++++++ scripts/sdk-e2e.sh | 5 +++++ 2 files changed, 14 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5b56298df..2ca35e51b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -131,6 +131,15 @@ jobs: - name: Install dependencies run: bun install + # The worker's exec-sandbox uses bwrap on Linux; ubuntu-latest blocks + # unprivileged user namespaces via AppArmor, so flip the sysctl too. + - name: Install bubblewrap (worker exec-sandbox) + run: | + sudo apt-get update + sudo apt-get install -y bubblewrap coreutils + sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 + bwrap --version + # `lobu run`'s embedded Postgres ships a PG18 binary dynamically linked # against ICU 60 (libicuuc.so.60); ubuntu-latest carries a newer ICU, so # initdb can't load without the 18.04-era lib. Prod doesn't hit this (it diff --git a/scripts/sdk-e2e.sh b/scripts/sdk-e2e.sh index 5229c8f4b..28f3f0506 100755 --- a/scripts/sdk-e2e.sh +++ b/scripts/sdk-e2e.sh @@ -94,6 +94,11 @@ TS printf '\n' echo "MOCK_API_KEY=mock-key-e2e" echo "WORKER_ALLOWED_DOMAINS=127.0.0.1,localhost" + # The orchestrator wraps Linux workers in `systemd-run --user --scope` for + # cgroup/network limits; CI runners have no user systemd session, so that + # spawn fails. Disable it here — the worker only talks to the loopback mock, + # and this gate isn't testing the prod network sandbox. No-op on macOS. + echo "LOBU_DISABLE_SYSTEMD_RUN=1" [ -n "${DATABASE_URL:-}" ] && echo "DATABASE_URL=$DATABASE_URL" } >> "$PROJ/.env" From 5df871b053b5e4f5d946ae6bcafee959be019e4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 17:46:28 +0100 Subject: [PATCH 64/65] style(init-from-org): use optional chain for platform name recovery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clears the recurring biome useOptionalChain warning (p.id && p.id.startsWith → p.id?.startsWith) on this PR's platform round-trip code. --- packages/cli/src/commands/_lib/init-from-org/bootstrap.ts | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts index 12c218b03..8749f8f67 100644 --- a/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts +++ b/packages/cli/src/commands/_lib/init-from-org/bootstrap.ts @@ -441,10 +441,9 @@ function emitAgent( .replace(/[^a-z0-9]+/g, "-") .replace(/^-+|-+$/g, ""); const prefix = `${slug(agent.agentId)}-${slug(p.platform)}`; - const nameSlug = - p.id && p.id.startsWith(`${prefix}-`) - ? p.id.slice(prefix.length + 1) - : undefined; + const nameSlug = p.id?.startsWith(`${prefix}-`) + ? p.id.slice(prefix.length + 1) + : undefined; const platformFields = [`type: ${str(p.platform)}`]; if (nameSlug) platformFields.push(`name: ${str(nameSlug)}`); platformFields.push(`config: ${objectLiteral(cfgLines, 3)}`); From 6d6c399cd9b9c2516974d18e4b4780bdf3a0171c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Burak=20Emre=20Kabakc=C4=B1?= Date: Fri, 22 May 2026 18:15:50 +0100 Subject: [PATCH 65/65] test(sdk-e2e): self-contained embedded-PG ICU + connector-sync & watcher-reaction gates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Embedded Postgres portability (Task 1): the @embedded-postgres PG18 binaries are NEEDED-linked against ICU 60 with an rpath of $ORIGIN/../lib, and that lib dir already ships libicu{uc,i18n,data}.so.60.2 — it was only missing the .so.60 SONAME symlinks the loader resolves. scripts/sdk-e2e/fix-embedded-pg-icu.mjs creates them (idempotent, Linux-only no-op on macOS), so initdb loads its bundled ICU with zero system deps. Drops the fragile archive .deb download from CI; now works identically on a local Linux dev box. Expanded gate (Task 2): - Connector sync: a local zero-dep ./connectors/pulse.connector.ts whose sync() emits one event; a defineConnection wires its feed. The gate triggers an immediate sync via manage_feeds(trigger_feed), polls the run to completed, and asserts items_collected>=1 and feed event_count>=1 — proving the compiled connector actually RUNS and persists, not just that apply mapped it. - Watcher reaction: a ./reactions/digest.reaction.ts that saves an assertable SDKE2E_REACTION_OK knowledge event. The gate triggers the watcher (asserts the run row is enqueued) then deterministically drives read_knowledge -> complete_window (the fixed-reply mock never produces the complete_window tool-call) so the reaction fires on the connector-emitted window, and asserts the side effect via query_sql. API assertions use an mcp:admin PAT minted with lobu token create against the local-install org. Gate stays deterministic with generous polling + clear failures; teardown unchanged. --- .github/workflows/ci.yml | 26 +-- scripts/sdk-e2e.sh | 229 +++++++++++++++++++++++- scripts/sdk-e2e/fix-embedded-pg-icu.mjs | 143 +++++++++++++++ 3 files changed, 379 insertions(+), 19 deletions(-) create mode 100644 scripts/sdk-e2e/fix-embedded-pg-icu.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2ca35e51b..2137321cd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -140,23 +140,15 @@ jobs: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 bwrap --version - # `lobu run`'s embedded Postgres ships a PG18 binary dynamically linked - # against ICU 60 (libicuuc.so.60); ubuntu-latest carries a newer ICU, so - # initdb can't load without the 18.04-era lib. Prod doesn't hit this (it - # uses an external Postgres and prunes embedded-postgres), but the local - # `lobu run` path this gate exercises does. Install it from the Ubuntu - # archive (mirror fallback) and surface any remaining missing libs. - - name: Install libicu60 (embedded-postgres links against ICU 60) - run: | - set -euo pipefail - deb=libicu60_60.2-3ubuntu3.2_amd64.deb - curl -fsSL -o "/tmp/$deb" "http://archive.ubuntu.com/ubuntu/pool/main/i/icu/$deb" \ - || curl -fsSL -o "/tmp/$deb" "http://security.ubuntu.com/ubuntu/pool/main/i/icu/$deb" - sudo dpkg -i "/tmp/$deb" - ldconfig -p | grep -i libicuuc - echo "::group::ldd of embedded-postgres initdb" - ldd node_modules/@embedded-postgres/linux-x64/native/bin/initdb || true - echo "::endgroup::" + # NOTE: `lobu run`'s embedded Postgres (PG18) is NEEDED-linked against + # ICU 60, which ubuntu-latest no longer carries. We do NOT install a + # system libicu60 (the old archive .deb was fragile and didn't help local + # Linux devs) — instead scripts/sdk-e2e.sh runs + # scripts/sdk-e2e/fix-embedded-pg-icu.mjs, which creates the missing + # `.so.60` SONAME symlinks in the embedded-postgres native/lib dir (it + # already ships libicu*.so.60.2). The binaries' `$ORIGIN/../lib` rpath then + # resolves their bundled ICU with zero system deps. Prod is unaffected + # (external Postgres; embedded-postgres pruned from the app image). - name: Build all packages (CLI + server bundle + sdk + pgvector-embedded) run: make build-packages diff --git a/scripts/sdk-e2e.sh b/scripts/sdk-e2e.sh index 28f3f0506..80f75be2f 100755 --- a/scripts/sdk-e2e.sh +++ b/scripts/sdk-e2e.sh @@ -52,6 +52,18 @@ echo "▶ node $(node --version), gateway :$GW_PORT, mock :$MOCK_PORT" rm -rf "$RUN_DIR"; mkdir -p "$RUN_DIR" cleanup # free ports from any prior run +# 0) Make embedded Postgres self-contained on Linux. The @embedded-postgres PG18 +# binaries are NEEDED-linked against ICU 60 with an rpath of `$ORIGIN/../lib`, +# and that lib dir already SHIPS libicu{uc,i18n,data}.so.60.2 — it's only missing +# the `.so.60` SONAME symlinks the loader looks for. We create them (idempotent), +# so initdb loads its bundled ICU with NO system install, NO LD_LIBRARY_PATH and +# NO archive .deb download — identical in CI and on a local Linux dev box. No-op +# on macOS (its bundled .dylibs resolve already). Embedded PG only matters when +# DATABASE_URL is unset (the `lobu run` path); prod uses external Postgres. +if [ -z "${DATABASE_URL:-}" ]; then + node "$HARNESS/fix-embedded-pg-icu.mjs" || fail "could not prepare embedded-postgres ICU symlinks" +fi + # 1) Mock OpenAI-compatible provider. MOCK_PORT="$MOCK_PORT" MOCK_REPLY="$MOCK_REPLY" node "$HARNESS/mock-openai.mjs" > "$MOCK_LOG" 2>&1 & MOCK_PID=$! @@ -68,7 +80,7 @@ PROJ="$RUN_DIR/proj"; mkdir -p "$PROJ" ( cd "$PROJ" && $LOBU init . -y --here --provider gemini >/dev/null 2>&1 ) rm -f "$PROJ/package.json" cat > "$PROJ/lobu.config.ts" <<'TS' -import { defineAgent, defineConfig, defineEntityType, defineRelationshipType, defineWatcher, secret } from "@lobu/sdk"; +import { defineAgent, defineConfig, defineConnection, defineEntityType, defineRelationshipType, defineWatcher, secret } from "@lobu/sdk"; const agent = defineAgent({ id: "echo", name: "Echo", dir: "./agents/echo", @@ -77,14 +89,103 @@ const agent = defineAgent({ const company = defineEntityType({ key: "company", name: "Company" }); const contact = defineEntityType({ key: "contact", name: "Contact" }); const worksAt = defineRelationshipType({ key: "works-at", name: "Works at", rules: [{ source: contact, target: company }] }); + +// A local connector (./connectors/pulse.connector.ts) + a connection that wires +// its single feed. The gate triggers a sync via the API and asserts the +// connector's compiled code actually RAN and emitted ≥1 event — proving the +// whole compile→install→spawn→sync→persist path, not just that apply mapped it. +const pulseConn = defineConnection({ + slug: "pulse", connector: "sdke2e-pulse", name: "SDK e2e pulse", + feeds: [{ feed: "pulse", name: "Pulse" }], +}); + +// The watcher runs an LLM extraction then a reaction script +// (./reactions/digest.reaction.ts) that writes an assertable knowledge event. +// `sources` selects the connector-emitted events by connector_key so the +// watcher's window has linked content — the reaction only fires on a non-empty +// window. The gate drives read_knowledge → complete_window deterministically +// (the agentic LLM turn never produces the complete_window tool-call against a +// fixed-reply mock) and asserts the reaction's side effect. const digest = defineWatcher({ slug: "digest", agent, name: "Digest", prompt: "summarize", extractionSchema: { type: "object", properties: { s: { type: "string" } } }, + reaction: "./reactions/digest.reaction.ts", + sources: { + content: + "SELECT id, title, payload_text, author_name, occurred_at, origin_type FROM events WHERE connector_key = 'sdke2e-pulse' ORDER BY occurred_at DESC LIMIT 100", + }, }); // prune:true so the gate exercises the destructive path on every run (this is // what catches the system-type $member halt class of bug). -export default defineConfig({ prune: true, agents: [agent], entities: [company, contact], relationships: [worksAt], watchers: [digest] }); +export default defineConfig({ prune: true, agents: [agent], entities: [company, contact], relationships: [worksAt], connections: [pulseConn], watchers: [digest] }); +TS + +# Local connector: deterministic, zero-dep, no network. `sync()` returns one +# fresh event per run (a monotonic origin_id off the checkpoint so re-syncs add +# rows rather than dedup to nothing). Proves the compiled ConnectorRuntime runs. +mkdir -p "$PROJ/connectors" +cat > "$PROJ/connectors/pulse.connector.ts" <<'TS' +import { ConnectorRuntime, type SyncContext, type SyncResult } from "@lobu/connector-sdk"; + +interface Checkpoint { + seq: number; +} + +/** + * SDK e2e pulse connector — emits one deterministic event per sync. No fetch, + * no auth, no deps: the gate is testing that a compiled local connector RUNS + * and persists events, not any external integration. + */ +export default class PulseConnector extends ConnectorRuntime { + readonly definition = { + key: "sdke2e-pulse", + name: "SDK e2e pulse", + version: "1.0.0", + authSchema: { methods: [{ type: "none" as const }] }, + feeds: { pulse: { key: "pulse", name: "Pulse" } }, + }; + + async sync(ctx: SyncContext): Promise> { + const seq = (ctx.checkpoint?.seq ?? 0) + 1; + return { + events: [ + { + origin_id: `sdke2e-pulse-${seq}`, + origin_type: "pulse", + title: "SDK e2e pulse", + payload_text: `SDKE2E_PULSE_EVENT seq=${seq}`, + occurred_at: new Date(), + metadata: { seq }, + }, + ], + checkpoint: { seq }, + }; + } + + async execute() { + return { success: false, error: "no actions" }; + } +} +TS + +# Watcher reaction: writes a deterministic, assertable knowledge event when the +# window completes. Kept in its own file so the SDK type-checks it. +mkdir -p "$PROJ/reactions" +cat > "$PROJ/reactions/digest.reaction.ts" <<'TS' +import type { ReactionClient, ReactionContext } from "@lobu/connector-sdk"; + +export default async (ctx: ReactionContext, client: ReactionClient): Promise => { + await client.knowledge.save({ + content: "SDKE2E_REACTION_OK", + semantic_type: "summary", + metadata: { + watcher_slug: ctx.watcher.slug, + window_id: ctx.window.id, + content_analyzed: ctx.window.content_analyzed, + }, + }); +}; TS # Project env: mock key, allow loopback egress (mock provider), embedded PG unless @@ -129,6 +230,130 @@ grep -qF "$MOCK_REPLY" "$CHAT_OUT" || fail "agent turn did not return the mock r grep -qiE "Forwarding to upstream: POST http://127.0.0.1:$MOCK_PORT" "$RUN_LOG" || fail "worker never called the mock provider upstream" echo "✓ agent completed a real turn through the worker (reply: $MOCK_REPLY)" +# ── API setup for the connector/watcher assertions ──────────────────────────── +# Mint a personal access token bound to the loopback `local` context, and +# resolve the org slug the bootstrap auto-provisioned (don't hardcode it). +# trigger_feed / watcher trigger / complete_window / query_sql are owner-admin +# tools (tool-access.ts), so mint with mcp:admin — the local-install user is the +# org owner. +GW="http://localhost:$GW_PORT" +TOKEN="$( ( cd "$PROJ" && $LOBU token create -c local --scope "mcp:read mcp:write mcp:admin" --json 2>/dev/null ) | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{process.stdout.write(JSON.parse(s).token||"")}catch{}})' )" +[ -n "$TOKEN" ] || fail "could not mint a local API token (lobu token create -c local --json)" +ORG="$( ( cd "$PROJ" && $LOBU org current -c local 2>/dev/null ) | grep -oE '[a-z0-9][a-z0-9-]*' | grep -v '^local$' | tail -1 )" +[ -n "$ORG" ] || fail "could not resolve the local org slug (lobu org current -c local)" +echo "▶ API: org=$ORG token=…${TOKEN: -6}" + +# POST a tool call through the generic /api/:org/:tool proxy. Args = $2 (JSON). +api() { + curl -fsS -X POST "$GW/api/$ORG/$1" \ + -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \ + -d "$2" +} +# Extract a JSON field from stdin with node (no jq dependency). +jget() { node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let v;try{v=JSON.parse(s)}catch{process.exit(2)};for(const k of process.argv[1].split("."))v=v?.[k];process.stdout.write(v==null?"":String(v))})' "$1"; } + +# 6) Connector sync — prove the COMPILED connector actually RUNS and emits events. +# Find the feed manage_feeds created from the `pulse` connection, trigger an +# immediate sync, wait for the run to complete, then assert ≥1 event landed. +FEEDS="$RUN_DIR/feeds.json" +api manage_feeds '{"action":"list_feeds"}' > "$FEEDS" || fail "manage_feeds list_feeds failed" +FEED_ID="$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);const f=(j.feeds||[]).find(x=>x.feed_key==="pulse");process.stdout.write(f?String(f.id):"")})' < "$FEEDS")" +[ -n "$FEED_ID" ] || { cat "$FEEDS" >&2; fail "no 'pulse' feed found after apply (connection/feed not created?)"; } +echo "✓ apply created the pulse feed (id=$FEED_ID)" + +api manage_feeds "{\"action\":\"trigger_feed\",\"feed_id\":$FEED_ID}" > "$RUN_DIR/trigger-feed.json" || { cat "$RUN_DIR/trigger-feed.json" >&2; fail "trigger_feed failed"; } + +# Poll get_feed until the most recent sync run reaches a terminal state. Parse +# status/items with separate guarded node calls (process substitution + `read` +# trips `set -e` on a newline-less EOF), so the loop survives transient misses. +SYNC_OK=""; RUN_ITEMS=0 +for _ in $(seq 1 90); do + api manage_feeds "{\"action\":\"get_feed\",\"feed_id\":$FEED_ID}" > "$RUN_DIR/get-feed.json" 2>/dev/null || { sleep 1; continue; } + RUN_STATUS="$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let j;try{j=JSON.parse(s)}catch{process.stdout.write("none");return}const r=(j.recent_runs||[])[0]||{};process.stdout.write(String(r.status||"none"))})' < "$RUN_DIR/get-feed.json" || echo none)" + RUN_ITEMS="$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let j;try{j=JSON.parse(s)}catch{process.stdout.write("0");return}const r=(j.recent_runs||[])[0]||{};process.stdout.write(String(r.items_collected??0))})' < "$RUN_DIR/get-feed.json" || echo 0)" + case "$RUN_STATUS" in + completed) SYNC_OK=1; break ;; + failed|error) cat "$RUN_DIR/get-feed.json" >&2; fail "connector sync run ended in status '$RUN_STATUS'" ;; + esac + sleep 1 +done +[ -n "$SYNC_OK" ] || { cat "$RUN_DIR/get-feed.json" >&2; fail "connector sync run did not complete within timeout"; } + +# Assert the connector emitted ≥1 event (items_collected on the run AND the +# feed-level event_count from list_feeds). +[ "${RUN_ITEMS:-0}" -ge 1 ] 2>/dev/null || fail "sync run completed but collected 0 items" +api manage_feeds '{"action":"list_feeds"}' > "$FEEDS" || fail "manage_feeds list_feeds (post-sync) failed" +EVENT_COUNT="$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);const f=(j.feeds||[]).find(x=>x.feed_key==="pulse");process.stdout.write(f?String(f.event_count??0):"0")})' < "$FEEDS")" +[ "${EVENT_COUNT:-0}" -ge 1 ] 2>/dev/null || fail "connector sync persisted 0 events (event_count=$EVENT_COUNT)" +echo "✓ connector sync ran the compiled connector and emitted events (items=$RUN_ITEMS, event_count=$EVENT_COUNT)" + +# 7) Watcher reaction — prove the reaction script RUNS and produces a side +# effect. Trigger the watcher (proves the dispatch path doesn't error), then +# deterministically drive read_knowledge → complete_window so the reaction +# fires regardless of the fixed-reply mock (the agentic turn would never +# produce a complete_window tool-call). The reaction saves SDKE2E_REACTION_OK. +WATCHERS="$RUN_DIR/watchers.json" +api list_watchers '{}' > "$WATCHERS" 2>/dev/null || fail "could not list watchers" +WATCHER_ID="$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);const arr=j.watchers||j.items||(Array.isArray(j)?j:[]);const w=arr.find(x=>x.slug==="digest")||arr[0];const id=w?(w.watcher_id??w.id):null;process.stdout.write(id!=null?String(id):"")})' < "$WATCHERS")" +[ -n "$WATCHER_ID" ] || { cat "$WATCHERS" >&2; fail "no 'digest' watcher found after apply"; } +echo "✓ apply created the digest watcher (id=$WATCHER_ID)" + +# Trigger the watcher (the dispatch path). This enqueues a watcher run; the +# worker turn that would normally call complete_window is NOT relied upon (a +# fixed-reply mock never produces the complete_window tool-call, and `lobu run`'s +# embedded bootstrap doesn't seed the `lobu-internal` oauth_client the dispatcher +# needs to mint a worker service token — a known dev-only limitation). So we +# assert only the reliably-observable part: the trigger created a watcher run +# row. The reaction's actual side effect is asserted deterministically below via +# read_knowledge → complete_window. +TW="$RUN_DIR/trigger-watcher.json" +api manage_watchers "{\"action\":\"trigger\",\"watcher_id\":\"$WATCHER_ID\"}" > "$TW" 2>/dev/null || true +TRIG_RUN_ID="$(jget run_id < "$TW" 2>/dev/null || echo)" +if [ -n "$TRIG_RUN_ID" ]; then + echo "✓ watcher trigger dispatched a run (run_id=$TRIG_RUN_ID)" +else + # Trigger errored (embedded service-token limitation) — confirm the run row was + # still created so we know the dispatch path reached the queue. + api list_watchers '{}' > "$RUN_DIR/watchers-after-trigger.json" 2>/dev/null || true + HAS_RUN="$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let j;try{j=JSON.parse(s)}catch{process.stdout.write("");return}const arr=j.watchers||[];const w=arr.find(x=>x.slug==="digest")||arr[0];process.stdout.write(w&&w.watcher_run_id!=null?"1":"")})' < "$RUN_DIR/watchers-after-trigger.json" || echo)" + [ -n "$HAS_RUN" ] || { cat "$TW" >&2; fail "watcher trigger neither returned a run_id nor created a watcher run row"; } + echo "✓ watcher trigger enqueued a run (worker dispatch skipped: embedded service-token limitation)" +fi + +# Deterministic reaction drive: read_knowledge over the window holding the +# connector events → window_token → complete_window with extracted_data. The +# window has linked content (the synced pulse event), so the reaction fires. +SINCE="$(node -e 'process.stdout.write("2000-01-01")')" +UNTIL="$(node -e 'const d=new Date(Date.now()+86400000);process.stdout.write(d.toISOString().slice(0,10))')" +RK="$RUN_DIR/read-knowledge.json" +api read_knowledge "{\"watcher_id\":$WATCHER_ID,\"since\":\"$SINCE\",\"until\":\"$UNTIL\"}" > "$RK" 2>/dev/null \ + || { cat "$RK" >&2; fail "read_knowledge (watcher-mode) failed"; } +WINDOW_TOKEN="$(jget window_token < "$RK")" +[ -n "$WINDOW_TOKEN" ] || { cat "$RK" >&2; fail "read_knowledge returned no window_token (no content in window — connector events missing?)"; } + +CW="$RUN_DIR/complete-window.json" +api manage_watchers "$(node -e 'const t=process.argv[1],w=process.argv[2];process.stdout.write(JSON.stringify({action:"complete_window",watcher_id:w,window_token:t,extracted_data:{s:"SDKE2E_OK"},run_metadata:{executor:"sdk-e2e"}}))' "$WINDOW_TOKEN" "$WATCHER_ID")" > "$CW" 2>/dev/null \ + || { cat "$CW" >&2; fail "complete_window failed"; } +grep -q '"action":"complete_window"\|"action": "complete_window"' "$CW" || { cat "$CW" >&2; fail "complete_window did not return the expected action"; } + +# Assert the reaction's side effect: a SDKE2E_REACTION_OK knowledge event exists. +# query_sql auto-scopes to the org and auto-adds ORDER BY/LIMIT, so we pass a +# bare SELECT (no ORDER BY/LIMIT) plus the required sort_by, and count rows +# script-side. +# query_sql validates against the data-source table allowlist where `events` +# maps to current_event_records (the superseded-masking view); use `events`. +REACT="$RUN_DIR/reaction-check.json" +REACT_QUERY="$(node -e 'process.stdout.write(JSON.stringify({sql:"SELECT id FROM events WHERE payload_text = '"'"'SDKE2E_REACTION_OK'"'"'",sort_by:"id"}))')" +REACT_OK="" +for _ in $(seq 1 30); do + api query_sql "$REACT_QUERY" > "$REACT" 2>/dev/null || { sleep 1; continue; } + N="$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let j;try{j=JSON.parse(s)}catch{process.stdout.write("0");return}const rows=j.rows||j.result||j.data||(Array.isArray(j)?j:[]);process.stdout.write(String(Array.isArray(rows)?rows.length:0))})' < "$REACT")" + if [ "${N:-0}" -ge 1 ] 2>/dev/null; then REACT_OK=1; break; fi + sleep 1 +done +[ -n "$REACT_OK" ] || { cat "$CW" >&2; cat "$REACT" >&2; fail "watcher reaction did not produce its SDKE2E_REACTION_OK knowledge event"; } +echo "✓ watcher reaction ran and saved its assertable side effect (SDKE2E_REACTION_OK)" + # 5) Idempotent re-apply (stable config → 0 deletes). Unlike `lobu run`, `lobu # apply` does not auto-load the project .env, so pass the secret it resolves for # the provider-key push explicitly. diff --git a/scripts/sdk-e2e/fix-embedded-pg-icu.mjs b/scripts/sdk-e2e/fix-embedded-pg-icu.mjs new file mode 100644 index 000000000..8eb965b6f --- /dev/null +++ b/scripts/sdk-e2e/fix-embedded-pg-icu.mjs @@ -0,0 +1,143 @@ +#!/usr/bin/env node +/** + * Make `lobu run`'s embedded Postgres self-contained on Linux — zero system deps. + * + * The @embedded-postgres PG18 binaries (initdb/postgres) are dynamically linked + * against ICU 60 (NEEDED: libicuuc.so.60 → libicui18n.so.60 → libicudata.so.60) + * and carry an rpath of `$ORIGIN/../lib`, i.e. they look for their ICU next to + * themselves in `/native/lib`. That dir already SHIPS the libraries — but + * only under their fully-versioned names (libicuuc.so.60.2, …). What's missing + * is the SONAME symlink (libicuuc.so.60 → libicuuc.so.60.2) that a normal ICU + * package/install would create, so the loader can't resolve the NEEDED soname + * and initdb fails to start on any host without a system ICU 60. + * + * Creating those three symlinks makes the bundled rpath resolve with no system + * install, no LD_LIBRARY_PATH, no apt/.deb download — works identically in CI + * (ubuntu-latest) and on a local Linux dev box. macOS ships matching `.dylib`s + * with the right install names already, so this is a Linux-only no-op there. + * + * Idempotent: re-running just re-points the symlinks. Exits 0 on non-Linux or + * when the linux platform package isn't installed (the wrong-arch optional dep). + */ +import { + existsSync, + lstatSync, + readdirSync, + readlinkSync, + symlinkSync, + unlinkSync, +} from "node:fs"; +import { createRequire } from "node:module"; +import { dirname, join, resolve } from "node:path"; + +if (process.platform !== "linux") { + // macOS / Windows resolve their bundled ICU without SONAME symlinks. + process.exit(0); +} + +const require = createRequire(import.meta.url); + +// The ICU libs the PG18 binaries are NEEDED-linked against. Each maps its +// SONAME (`.so.60`) to the versioned file the package actually ships +// (`.so.60.2`). If a future @embedded-postgres bumps the patch suffix we +// glob-match below, so the exact `.2` here is only the preferred target. +const ICU_SONAMES = ["libicuuc", "libicui18n", "libicudata"]; + +/** Locate every installed @embedded-postgres/linux-* native lib dir. */ +function findLinuxNativeLibDirs() { + const dirs = new Set(); + // Candidate `node_modules` roots to scan for the @embedded-postgres scope: + // 1. wherever `embedded-postgres` resolves from this helper (the workspace + // hoist root in CI / monorepo), and + // 2. `/node_modules` (covers a project-local install or a tree this + // helper was copied into). + const scopeRoots = new Set(); + try { + const ep = require.resolve("embedded-postgres/package.json"); + scopeRoots.add(resolve(dirname(ep), "..")); + } catch { + // not resolvable from here — fall through to cwd + } + scopeRoots.add(resolve(process.cwd(), "node_modules")); + + for (const root of scopeRoots) { + const scopeDir = join(root, "@embedded-postgres"); + if (!existsSync(scopeDir)) continue; + for (const name of readdirSync(scopeDir)) { + if (!name.startsWith("linux-")) continue; + const libDir = join(scopeDir, name, "native", "lib"); + if (existsSync(libDir)) dirs.add(libDir); + } + } + return [...dirs]; +} + +function ensureSonameSymlink(libDir, soname) { + // Find the concrete versioned file: libicuuc.so.60.2 (or any .so..). + const candidates = readdirSync(libDir).filter((f) => + new RegExp(`^${soname}\\.so\\.\\d+\\.\\d+$`).test(f) + ); + if (candidates.length === 0) return { soname, status: "no-versioned-file" }; + // Newest patch wins if several exist. + candidates.sort(); + const target = candidates[candidates.length - 1]; + const major = target.match(/\.so\.(\d+)\./)?.[1]; + if (!major) return { soname, status: "unparseable" }; + const link = join(libDir, `${soname}.so.${major}`); + + if (existsSync(link) || isDanglingSymlink(link)) { + // Already correct? Leave it. Otherwise re-point (idempotent). + if (isSymlinkTo(link, target)) return { soname, status: "ok" }; + unlinkSync(link); + } + symlinkSync(target, link); // relative target → stays valid if the dir moves + return { + soname, + status: "linked", + link: `${soname}.so.${major} -> ${target}`, + }; +} + +function isDanglingSymlink(p) { + try { + return lstatSync(p).isSymbolicLink() && !existsSync(p); + } catch { + return false; + } +} + +function isSymlinkTo(p, target) { + try { + return lstatSync(p).isSymbolicLink() && readlinkSync(p) === target; + } catch { + return false; + } +} + +const libDirs = findLinuxNativeLibDirs(); +if (libDirs.length === 0) { + // Wrong-arch optional dep not installed (e.g. running this on darwin's tree) + // — nothing to fix. Embedded PG simply isn't available on this host. + console.log( + "[fix-embedded-pg-icu] no @embedded-postgres/linux-* lib dir; skip" + ); + process.exit(0); +} + +let linked = 0; +for (const libDir of libDirs) { + for (const soname of ICU_SONAMES) { + const r = ensureSonameSymlink(libDir, soname); + if (r.status === "linked") { + linked++; + console.log(`[fix-embedded-pg-icu] ${libDir}: ${r.link}`); + } else if (r.status === "no-versioned-file") { + console.log( + `[fix-embedded-pg-icu] ${libDir}: ${soname} has no versioned .so — package layout changed?` + ); + } + } +} +console.log( + `[fix-embedded-pg-icu] done (${linked} symlink(s) created across ${libDirs.length} lib dir(s))` +);