{"_id":"@chaitin-ai/agent-compose-runtime-sdk","_rev":"7-788ffea152d16b863ea12143c1c18283","name":"@chaitin-ai/agent-compose-runtime-sdk","dist-tags":{"latest":"0.11.0"},"versions":{"0.6.0":{"name":"@chaitin-ai/agent-compose-runtime-sdk","version":"0.6.0","keywords":["agent-compose","runtime","sdk"],"license":"LGPL-3.0-only","_id":"@chaitin-ai/agent-compose-runtime-sdk@0.6.0","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"}],"homepage":"https://github.com/chaitin/agent-compose#readme","bugs":{"url":"https://github.com/chaitin/agent-compose/issues"},"dist":{"shasum":"63064a1508ba120bf259294fea3de1a12665dac9","tarball":"https://registry.npmjs.org/@chaitin-ai/agent-compose-runtime-sdk/-/agent-compose-runtime-sdk-0.6.0.tgz","fileCount":49,"integrity":"sha512-5Mr2lnKbsD88FXFuTMlL8FqGSHZxmcNFkKhOgV4wAO/Jnx8Qj65nGMOtH8+7njMsXrcXHZVdT7d7hmxB54fnBQ==","signatures":[{"sig":"MEUCIQCECOwrgufa2827ulWs5leSJFFRLipy36Sr1dgGjkiiCwIgUXhXSPEGsu/ZZH/Zbm3fnJ5ULUy+RdgCIwEcUpTPlZU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaitin-ai%2fagent-compose-runtime-sdk@0.6.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":123211},"main":"./dist/cjs/index.cjs","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs"}},"gitHead":"4ceaa1d88f6df320def2a223d172fcb35176848f","scripts":{"test":"npm run build && vitest run","build":"node scripts/clean-dist.mjs && npm run build:esm && npm run build:cjs && npm run build:types && node scripts/rename-cjs.mjs","prepack":"npm run build","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc -p tsconfig.esm.json --noEmit","build:types":"tsc -p tsconfig.types.json","test:packaging":"node scripts/verify-offline-install.mjs","pack:runtime-bundle":"node scripts/pack-runtime-bundle.mjs"},"_npmUser":{"name":"mentats","email":"innomentats@gmail.com"},"repository":{"url":"git+https://github.com/chaitin/agent-compose.git","type":"git","directory":"runtime/agent-compose-runtime-sdk"},"_npmVersion":"10.9.8","description":"Node.js SDK for scripts running inside an agent-compose guest runtime.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^4.4.3"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typescript":"^5.9.3","@types/node":"^24.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-compose-runtime-sdk_0.6.0_1783696585632_0.3395072261692047","host":"s3://npm-registry-packages-npm-production"}},"0.7.0":{"name":"@chaitin-ai/agent-compose-runtime-sdk","version":"0.7.0","keywords":["agent-compose","runtime","sdk"],"license":"LGPL-3.0-only","_id":"@chaitin-ai/agent-compose-runtime-sdk@0.7.0","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"}],"homepage":"https://github.com/chaitin/agent-compose#readme","bugs":{"url":"https://github.com/chaitin/agent-compose/issues"},"dist":{"shasum":"314e23606d6a7e5e0c9bae13d006802b52e7d220","tarball":"https://registry.npmjs.org/@chaitin-ai/agent-compose-runtime-sdk/-/agent-compose-runtime-sdk-0.7.0.tgz","fileCount":49,"integrity":"sha512-fpLUoDHF2GvWatrNEPrIx+hbgL6U8UfoW6CcgPL1H84j6zxbgp0Pm48VsFX9XkfXIG0Gdecnk8EwxelNhOYEjg==","signatures":[{"sig":"MEYCIQDh80esKXGvMh2IBCbT/Y+5stson6wDv+1885VT+J3dXgIhAKY+d19shgQu3x6HG2Dci7cyiSi8DPVlgMQgubzHtBdR","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaitin-ai%2fagent-compose-runtime-sdk@0.7.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":123294},"main":"./dist/cjs/index.cjs","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs"}},"gitHead":"a86ebd279962d88c8277d3cd52d380965ad41b99","scripts":{"test":"npm run build && vitest run","build":"node scripts/clean-dist.mjs && npm run build:esm && npm run build:cjs && npm run build:types && node scripts/rename-cjs.mjs","prepack":"npm run build","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc -p tsconfig.esm.json --noEmit","build:types":"tsc -p tsconfig.types.json","test:coverage":"vitest run --coverage","test:packaging":"node scripts/verify-offline-install.mjs","pack:runtime-bundle":"node scripts/pack-runtime-bundle.mjs"},"_npmUser":{"name":"mentats","email":"innomentats@gmail.com"},"repository":{"url":"git+https://github.com/chaitin/agent-compose.git","type":"git","directory":"runtime/agent-compose-runtime-sdk"},"_npmVersion":"10.9.8","description":"Node.js SDK for scripts running inside an agent-compose guest runtime.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^4.4.3"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typescript":"^5.9.3","@types/node":"^24.0.0","@vitest/coverage-v8":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-compose-runtime-sdk_0.7.0_1784212422154_0.6593421053459492","host":"s3://npm-registry-packages-npm-production"}},"0.8.0":{"name":"@chaitin-ai/agent-compose-runtime-sdk","version":"0.8.0","keywords":["agent-compose","runtime","sdk"],"license":"LGPL-3.0-only","_id":"@chaitin-ai/agent-compose-runtime-sdk@0.8.0","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"}],"homepage":"https://github.com/chaitin/agent-compose#readme","bugs":{"url":"https://github.com/chaitin/agent-compose/issues"},"dist":{"shasum":"cda56d5ff8dbb2b62ea7a19547d6e5eb6533d45c","tarball":"https://registry.npmjs.org/@chaitin-ai/agent-compose-runtime-sdk/-/agent-compose-runtime-sdk-0.8.0.tgz","fileCount":49,"integrity":"sha512-RJZrY/GvlneFaXTwms4bzZOQuzC6Sq0i3OXup0K2WeEkE9nv03sKcXjwEds9fw/oMm0OnduM8PwslbJl7cLafQ==","signatures":[{"sig":"MEYCIQCNYDgWlENepbwAjD4g0lHEb5KkzEhPczWs0Wc6GIjB6wIhAKQf7YcQNn5WM92rdP4JLw1QppxRg3hbH1T62rlI3Css","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaitin-ai%2fagent-compose-runtime-sdk@0.8.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":123307},"main":"./dist/cjs/index.cjs","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs"}},"gitHead":"243274c1dd3e3c502b548c261be16bcea51fd11e","scripts":{"test":"npm run build && vitest run","build":"node scripts/clean-dist.mjs && npm run build:esm && npm run build:cjs && npm run build:types && node scripts/rename-cjs.mjs","prepack":"npm run build","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc -p tsconfig.esm.json --noEmit","build:types":"tsc -p tsconfig.types.json","test:coverage":"vitest run --coverage","test:packaging":"node scripts/verify-offline-install.mjs","pack:runtime-bundle":"node scripts/pack-runtime-bundle.mjs"},"_npmUser":{"name":"mentats","email":"innomentats@gmail.com"},"repository":{"url":"git+https://github.com/chaitin/agent-compose.git","type":"git","directory":"runtime/agent-compose-runtime-sdk"},"_npmVersion":"10.9.8","description":"Node.js SDK for scripts running inside an agent-compose guest runtime.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^4.4.3"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typescript":"^5.9.3","@types/node":"^24.0.0","@vitest/coverage-v8":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-compose-runtime-sdk_0.8.0_1785498402778_0.09543004344274841","host":"s3://npm-registry-packages-npm-production"}},"0.9.0":{"name":"@chaitin-ai/agent-compose-runtime-sdk","version":"0.9.0","keywords":["agent-compose","runtime","sdk"],"license":"LGPL-3.0-only","_id":"@chaitin-ai/agent-compose-runtime-sdk@0.9.0","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"}],"homepage":"https://github.com/chaitin/agent-compose#readme","bugs":{"url":"https://github.com/chaitin/agent-compose/issues"},"dist":{"shasum":"f302a3b898fe58e51a19f802df96a0ca7d16488c","tarball":"https://registry.npmjs.org/@chaitin-ai/agent-compose-runtime-sdk/-/agent-compose-runtime-sdk-0.9.0.tgz","fileCount":54,"integrity":"sha512-C2vT3eCEgwyoxbRJLQ17r7PG8NZGygJkwUI2DTnrmDCtrXISoSYXKqaZaRlfVppgo2r1t7bjPLk8xgKv2MgZ+w==","signatures":[{"sig":"MEYCIQDzaTUw8r1sbIhDjb89KyUDrVqtwLLHrpAZOwaeC00ZRQIhAJ4ptsoPoBDTjyx/JzQuA0wrnCraQepUPdhUm1eYGm1D","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaitin-ai%2fagent-compose-runtime-sdk@0.9.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":168677},"main":"./dist/cjs/index.cjs","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs"}},"gitHead":"2949b0913566b3f29a050bcaf8365814275ab2ca","scripts":{"test":"npm run build && vitest run","build":"node scripts/clean-dist.mjs && npm run build:esm && npm run build:cjs && npm run build:types && node scripts/rename-cjs.mjs","prepack":"npm run build","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc -p tsconfig.esm.json --noEmit","build:types":"tsc -p tsconfig.types.json","test:coverage":"vitest run --coverage","test:packaging":"node scripts/verify-offline-install.mjs","pack:runtime-bundle":"node scripts/pack-runtime-bundle.mjs"},"_npmUser":{"name":"mentats","email":"innomentats@gmail.com"},"repository":{"url":"git+https://github.com/chaitin/agent-compose.git","type":"git","directory":"runtime/agent-compose-runtime-sdk"},"_npmVersion":"10.9.8","description":"Node.js SDK for scripts running inside an agent-compose guest runtime.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^4.4.3"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typescript":"^5.9.3","@types/node":"^24.0.0","@vitest/coverage-v8":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-compose-runtime-sdk_0.9.0_1786107233289_0.7660872028472077","host":"s3://npm-registry-packages-npm-production"}},"0.10.0":{"name":"@chaitin-ai/agent-compose-runtime-sdk","version":"0.10.0","keywords":["agent-compose","runtime","sdk"],"license":"LGPL-3.0-only","_id":"@chaitin-ai/agent-compose-runtime-sdk@0.10.0","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"}],"homepage":"https://github.com/chaitin/agent-compose#readme","bugs":{"url":"https://github.com/chaitin/agent-compose/issues"},"dist":{"shasum":"2be816357c28aae127408a4ae342ecbdbbc38166","tarball":"https://registry.npmjs.org/@chaitin-ai/agent-compose-runtime-sdk/-/agent-compose-runtime-sdk-0.10.0.tgz","fileCount":54,"integrity":"sha512-zjgF9eJwbP0V05D8gsKekh5wyuyNbiD+evGaB0EvspKX8NZXULT4Bt+FI34zl5E2VPx68I2QVjc6YYStDMvyDg==","signatures":[{"sig":"MEUCIQCGUHutrdvPz0gTn3di0chXsfo/Lw5LoizZgsWPKkhqzgIgbBN5p0n4iUPjOiwzClLG89ZG5sU8COotLnmvR5my6OQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaitin-ai%2fagent-compose-runtime-sdk@0.10.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":168678},"main":"./dist/cjs/index.cjs","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs"}},"gitHead":"5df1acb0cda4159f7106f263e358c8a84026a142","scripts":{"test":"npm run build && vitest run","build":"node scripts/clean-dist.mjs && npm run build:esm && npm run build:cjs && npm run build:types && node scripts/rename-cjs.mjs","prepack":"npm run build","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc -p tsconfig.esm.json --noEmit","build:types":"tsc -p tsconfig.types.json","test:coverage":"vitest run --coverage","test:packaging":"node scripts/verify-offline-install.mjs","pack:runtime-bundle":"node scripts/pack-runtime-bundle.mjs"},"_npmUser":{"name":"mentats","email":"innomentats@gmail.com"},"repository":{"url":"git+https://github.com/chaitin/agent-compose.git","type":"git","directory":"runtime/agent-compose-runtime-sdk"},"_npmVersion":"10.9.8","description":"Node.js SDK for scripts running inside an agent-compose guest runtime.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^4.4.3"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typescript":"^5.9.3","@types/node":"^24.0.0","@vitest/coverage-v8":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-compose-runtime-sdk_0.10.0_1786625136614_0.7038041577940863","host":"s3://npm-registry-packages-npm-production"}},"0.11.0":{"name":"@chaitin-ai/agent-compose-runtime-sdk","version":"0.11.0","keywords":["agent-compose","runtime","sdk"],"license":"LGPL-3.0-only","_id":"@chaitin-ai/agent-compose-runtime-sdk@0.11.0","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"}],"homepage":"https://github.com/chaitin/agent-compose#readme","bugs":{"url":"https://github.com/chaitin/agent-compose/issues"},"dist":{"shasum":"52d683f61878b2350814b70fd21dfcfd7873276c","tarball":"https://registry.npmjs.org/@chaitin-ai/agent-compose-runtime-sdk/-/agent-compose-runtime-sdk-0.11.0.tgz","fileCount":54,"integrity":"sha512-TmNcVv/wtIsc7FcojacT6KxZd1PuFR4zUdvLCetKjcPHVUiG0cykSMX/YeUfwS2WrvkrxHMSdAlixhmvtDeERA==","signatures":[{"sig":"MEQCIGA9hIpeAgBPfAdmGul9wLv6/frsBroFY9rJP5HWZ6vRAiAwM+WsnlmVtyoLEfTxVGvpd/CtYvc9RqQ6XiMMa53SEA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIG2FOpQckDvT5Hd2VWbJrKiKxiBHqzsHw1L5EXNfre9sAiAl/Hn67xePXKVxje2X1bQLYd/7qSMdcG3tY2lHWzPzcQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaitin-ai%2fagent-compose-runtime-sdk@0.11.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":168723},"main":"./dist/cjs/index.cjs","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs"}},"gitHead":"206f3e6bb5020579e178b57ba541fa18e84a2e75","scripts":{"test":"npm run build && vitest run","build":"node scripts/clean-dist.mjs && npm run build:esm && npm run build:cjs && npm run build:types && node scripts/rename-cjs.mjs","prepack":"npm run build","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc -p tsconfig.esm.json --noEmit","build:types":"tsc -p tsconfig.types.json","test:coverage":"vitest run --coverage","test:packaging":"node scripts/verify-offline-install.mjs","pack:runtime-bundle":"node scripts/pack-runtime-bundle.mjs"},"_npmUser":{"name":"mentats","email":"innomentats@gmail.com"},"repository":{"url":"git+https://github.com/chaitin/agent-compose.git","type":"git","directory":"runtime/agent-compose-runtime-sdk"},"_npmVersion":"10.9.8","description":"Node.js SDK for scripts running inside an agent-compose guest runtime.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.4.3"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typescript":"^5.9.3","@types/node":"^24.0.0","@vitest/coverage-v8":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-compose-runtime-sdk_0.11.0_1788857465775_0.16160927949747772","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-07-10T15:16:25.436Z","modified":"2026-09-14T03:25:05.569Z","0.6.0":"2026-07-10T15:16:25.776Z","0.7.0":"2026-07-16T14:33:42.302Z","0.8.0":"2026-07-31T11:46:42.928Z","0.9.0":"2026-08-07T12:53:53.417Z","0.10.0":"2026-08-13T12:45:36.766Z","0.11.0":"2026-09-08T08:51:05.859Z"},"bugs":{"url":"https://github.com/chaitin/agent-compose/issues"},"license":"LGPL-3.0-only","homepage":"https://github.com/chaitin/agent-compose#readme","keywords":["agent-compose","runtime","sdk"],"repository":{"url":"git+https://github.com/chaitin/agent-compose.git","type":"git","directory":"runtime/agent-compose-runtime-sdk"},"description":"Node.js SDK for scripts running inside an agent-compose guest runtime.","maintainers":[{"email":"innomentats@gmail.com","name":"mentats"},{"email":"chuan.wang@chaitin.com","name":"eetoc"}],"readme":"# @chaitin-ai/agent-compose-runtime-sdk\n\nNode.js SDK for scripts running inside an agent-compose guest runtime.\n\nThe package provides both named exports and a default `runtime` object:\n\n```js\nconst { runtime } = require(\"@chaitin-ai/agent-compose-runtime-sdk\");\n```\n\n```js\nimport runtime, { exec, shell, agent, llm, workflowFile } from \"@chaitin-ai/agent-compose-runtime-sdk\";\n```\n\n## Installation\n\nInstall from the public npm registry:\n\n```bash\nnpm install @chaitin-ai/agent-compose-runtime-sdk\n```\n\nGuest images can also install the SDK from an offline tarball:\n\n```bash\nnpm install --offline /opt/agent-compose/npm/agent-compose-runtime-sdk.tgz\n```\n\n## Quick Start\n\n```js\nconst { runtime } = require(\"@chaitin-ai/agent-compose-runtime-sdk\");\n\nasync function main() {\n  const result = await runtime.shell(\"echo hello\");\n  runtime.log(\"command completed\", { success: result.success });\n}\n\nmain().catch((error) => {\n  console.error(error);\n  process.exit(1);\n});\n```\n\n## Runtime Paths\n\n`runtime.paths` exposes runtime paths resolved from environment variables:\n\n| Field | Environment variable | Default |\n| --- | --- | --- |\n| `workspace` | `WORKSPACE` | `/workspace` |\n| `stateRoot` | `STATE_ROOT` | `/data/state` |\n| `runtimeRoot` | `RUNTIME_ROOT` | `/data/runtime` |\n| `home` | `HOME` | `/root` |\n\n## API\n\n### `runtime.exec(command, args?, options?)`\n\nRuns a command directly without shell expansion.\n\n```js\nconst result = await runtime.exec(\"node\", [\"-e\", \"console.log(process.cwd())\"]);\n```\n\nOptions:\n\n| Option | Description |\n| --- | --- |\n| `cwd` | Working directory. Defaults to `runtime.paths.workspace`. |\n| `env` | Key-value pairs appended to the child process environment. |\n| `timeoutMs` | Terminates the command after this number of milliseconds. |\n| `maxOutputBytes` | Maximum captured bytes for `stdout`, `stderr`, and combined `output`. Defaults to 1 MiB. |\n| `rejectOnFailure` | Throws `CommandError` when the process exits with a non-zero status code. |\n| `streamOutput` | Streams child process `stdout` and `stderr` to the current process. Defaults to `true`. |\n| `forwardOutput` | Deprecated. Use `streamOutput` instead. |\n\nReturn value:\n\n```ts\n{\n  stdout: string;\n  stderr: string;\n  output: string;\n  exitCode: number;\n  success: boolean;\n  stdoutTruncated: boolean;\n  stderrTruncated: boolean;\n  outputTruncated: boolean;\n}\n```\n\nBy default, `runtime.exec()` streams command logs so agent-compose can display live output while the script is still running. Pass `{ streamOutput: false }` for quiet execution.\n\n### `runtime.shell(script, options?)`\n\nRuns a shell script through `bash -lc`.\n\n```js\nconst result = await runtime.shell(\"echo shell:$AGENT_COMPOSE_TEST_VALUE\", {\n  env: { AGENT_COMPOSE_TEST_VALUE: \"works\" },\n});\n```\n\nOptions and return values are the same as `runtime.exec()`. Use `runtime.shell()` when you need variable expansion, pipes, redirects, or compound commands.\n\n### `runtime.agent(prompt, options?)`\n\nCalls the agent bridge in the agent-compose runtime.\n\n```js\nconst result = await runtime.agent(\"Inspect the workspace and summarize the project.\");\n```\n\nPass `outputSchema` when you need structured JSON. A Zod schema is recommended: the SDK converts it to JSON Schema for the runtime agent bridge and validates the parsed `json` value with the same Zod schema.\n\n```ts\nimport { z } from \"zod\";\n\nconst RiskSummary = z.object({\n  summary: z.string(),\n  risk: z.enum([\"low\", \"high\"]),\n});\n\nconst result = await runtime.agent(\"Inspect the workspace and return risk.\", {\n  provider: \"codex\",\n  outputSchema: RiskSummary,\n});\n\nconsole.log(result.json.summary);\n```\n\nWhen a Zod schema is passed, the type of `result.json` is inferred from the schema:\n\n```ts\nimport { z } from \"zod\";\n\nconst RiskSummary = z.object({\n  summary: z.string(),\n  risk: z.enum([\"low\", \"high\"]),\n});\n\nconst result = await runtime.agent(\"Inspect the workspace and return risk.\", {\n  provider: \"claude\",\n  outputSchema: RiskSummary,\n});\n\nif (result.json) {\n  console.log(result.json.risk);\n}\n```\n\nYou can also pass a plain JSON Schema object and declare the return type with a generic:\n\n```ts\ntype RiskSummary = {\n  summary: string;\n  risk: \"low\" | \"high\";\n};\n\nconst result = await runtime.agent<RiskSummary>(\"Inspect the workspace and return risk.\", {\n  outputSchema: {\n    type: \"object\",\n    additionalProperties: false,\n    properties: {\n      summary: { type: \"string\" },\n      risk: { type: \"string\", enum: [\"low\", \"high\"] },\n    },\n    required: [\"summary\", \"risk\"],\n  },\n});\n```\n\nOptions:\n\n| Option | Description |\n| --- | --- |\n| `provider` | Agent provider. One of `codex`, `claude`, `gemini`, `opencode`, `pi`, or `dsh`. Defaults to `codex`. |\n| `stateRoot` | Agent state root directory. Defaults to `runtime.paths.stateRoot`. |\n| `workspace` | Workspace path. Defaults to `runtime.paths.workspace`. |\n| `home` | Home directory. Defaults to `runtime.paths.home`. |\n| `timeoutMs` | Terminates the agent bridge after this number of milliseconds. |\n| `outputSchema` | Zod schema or JSON Schema object. When set, the returned `json` field is parsed from `finalText`. Codex and Claude support this; Gemini, OpenCode, Pi, and DSH currently throw an unsupported error when schema-based output is unavailable. |\n\nReturn value:\n\n```ts\n{\n  provider: string;\n  threadId: string;\n  stopReason: string;\n  finalText: string;\n  json: unknown | null;\n  transcript: string;\n  stderr: string;\n}\n```\n\n`finalText` always preserves the raw text returned by the agent bridge. When `outputSchema` is set, `finalText` must be a JSON string. The SDK runs `JSON.parse(finalText)` and stores the result in `json`. If `outputSchema` is a Zod schema, the SDK also validates the parsed result with that schema. Without `outputSchema`, `json` is `null`.\n\nError behavior:\n\n| Scenario | Behavior |\n| --- | --- |\n| `outputSchema` is not a plain JSON object | `runtime.agent()` throws before calling the runtime. |\n| A Zod schema cannot be converted to JSON Schema | `runtime.agent()` throws before calling the runtime. |\n| The provider does not support schema-based output | The runtime throws a provider-specific error. The current Gemini runner reports unsupported output. |\n| The provider returns `finalText` that is not valid JSON | `runtime.agent()` throws a parse error. |\n| The provider returns JSON that does not satisfy the Zod schema | `runtime.agent()` throws a validation error. |\n\n### `runtime.workflow(script, options?)` and `runtime.workflowFile(path, options?)`\n\nRuns a dynamic workflow through the guest runtime CLI. `workflow()` accepts\nsource text and manages a temporary script file; `workflowFile()` passes the\ncaller-owned file directly.\n\n```js\nconst result = await runtime.workflowFile(\"workflows/inspect.js\", {\n  args: { area: \"api\" },\n  provider: \"codex\",\n  concurrency: 4,\n  onUpdate(event) {\n    if (event.type === \"phase\") {\n      console.error(`phase: ${event.title}`)\n    }\n  },\n})\n\nconsole.log(result.result)\n```\n\nOptions include `args`, `provider`, `model`, `concurrency`, `tokenBudget`,\n`runId`, `resumeRunId`, `stateRoot`, `workspace`, `home`, `timeoutMs`, and\n`onUpdate`. Events are decoded incrementally from stderr, so `onUpdate` runs\nwhile the workflow is active. Non-event stderr is returned in `result.stderr`.\n\nFailed or aborted workflow payloads throw `RuntimeWorkflowError`; its `outcome`\nfield retains the run ID, agents, events, and stderr. Invalid CLI protocol throws\n`RuntimeWorkflowProtocolError`. SDK timeout throws\n`RuntimeWorkflowTimeoutError` and retains partial events and stderr.\n\n### `runtime.llm(prompt, options?)`\n\nCalls the agent-compose LLM service. The daemon selects the HTTP protocol via\n`LLM_API_PROTOCOL` (`responses` by default, or `chat_completions` for\nOpenAI-compatible Chat Completions backends). With `outputSchema`,\n`chat_completions` uses prompt guidance and `response_format: json_object`, not\nResponses API strict JSON Schema.\n\n```ts\nconst result = await runtime.llm(\"Summarize the workspace risk.\", {\n  model: \"gpt-5.4\",\n});\n\nconsole.log(result.text);\n```\n\n`runtime.llm()` supports the same `outputSchema` mechanism as `runtime.agent()`. A Zod schema is recommended: the SDK converts it to JSON Schema for the LLM service and validates the parsed `json` value with the same Zod schema.\n\n```ts\nimport { z } from \"zod\";\n\nconst RiskSummary = z.object({\n  summary: z.string(),\n  risk: z.enum([\"low\", \"high\"]),\n});\n\nconst result = await runtime.llm(\"Inspect the workspace and return risk.\", {\n  model: \"gpt-5.4\",\n  outputSchema: RiskSummary,\n});\n\nconsole.log(result.json.risk);\n```\n\nYou can also pass a plain JSON Schema object and declare the return type with a generic:\n\n```ts\ntype RiskSummary = {\n  summary: string;\n  risk: \"low\" | \"high\";\n};\n\nconst result = await runtime.llm<RiskSummary>(\"Inspect the workspace and return risk.\", {\n  outputSchema: {\n    type: \"object\",\n    additionalProperties: false,\n    properties: {\n      summary: { type: \"string\" },\n      risk: { type: \"string\", enum: [\"low\", \"high\"] },\n    },\n    required: [\"summary\", \"risk\"],\n  },\n});\n```\n\nOptions:\n\n| Option | Description |\n| --- | --- |\n| `model` | LLM model name. When omitted, agent-compose uses the server-side configuration. |\n| `baseUrl` | agent-compose service URL. Defaults to `BASE_URL`, then `HTTP_URL`, then `http://127.0.0.1:7410`. |\n| `timeoutMs` | Terminates the LLM service request after this number of milliseconds. |\n| `outputSchema` | Zod schema or JSON Schema object. When set, the returned `json` field is parsed from `text`. |\n\nReturn value:\n\n```ts\n{\n  text: string;\n  model: string;\n  responseId: string;\n  finishReason: string;\n  json: unknown | null;\n}\n```\n\n`text` always preserves the raw text returned by the LLM service. When `outputSchema` is set, `text` must be a JSON string. The SDK runs `JSON.parse(text)` and stores the result in `json`. If `outputSchema` is a Zod schema, the SDK also validates the parsed result with that schema. Without `outputSchema`, `json` is `null`.\n\n### `runtime.env.get(name)`\n\nReads an environment variable. Returns `undefined` when the variable is not set.\n\n```js\nconst value = runtime.env.get(\"WORKSPACE\");\n```\n\n### `runtime.env.require(name)`\n\nReads a required environment variable. Throws when the variable is missing or an empty string.\n\n```js\nconst token = runtime.env.require(\"API_TOKEN\");\n```\n\n### `runtime.env.all()`\n\nReturns all defined environment variables as a plain object.\n\n```js\nconst environment = runtime.env.all();\n```\n\n### `runtime.log(message, payload?)`\n\nWrites one structured runtime log line to `stdout`.\n\n```js\nruntime.log(\"step completed\", { step: \"build\", ok: true });\n```\n\nOutput JSON shape:\n\n```ts\n{\n  type: \"agent-compose.runtime.log\";\n  message: string;\n  payload: unknown;\n  createdAt: string;\n}\n```\n\n### `runtime.report.writeMarkdown(name, content, options?)`\n\nWrites a Markdown report file and returns the created file path.\n\n```js\nconst reportPath = await runtime.report.writeMarkdown(\"summary.md\", \"# Summary\\n\\nDone.\");\n```\n\nOptions:\n\n| Option | Description |\n| --- | --- |\n| `dir` | Output directory. Defaults to `runtime.paths.workspace`. |\n\nFile names are normalized with `path.basename()`, so callers should pass a file name rather than a nested path.\n\n## Errors\n\nWhen `rejectOnFailure` is enabled, a non-zero exit from `runtime.exec()` or `runtime.shell()` throws `CommandError`. The error object contains:\n\n| Field | Description |\n| --- | --- |\n| `command` | Executed command. |\n| `args` | Arguments passed to the command. |\n| `result` | Command result object, with the same shape returned by `runtime.exec()` or `runtime.shell()`. |\n\n```js\nconst { runtime, CommandError } = require(\"@chaitin-ai/agent-compose-runtime-sdk\");\n\ntry {\n  await runtime.shell(\"exit 1\", { rejectOnFailure: true });\n} catch (error) {\n  if (error instanceof CommandError) {\n    runtime.log(\"command failed\", { exitCode: error.result.exitCode });\n  }\n}\n```\n","readmeFilename":"README.md"}