{"_id":"@code3d/agent","_rev":"4-6930c3b4068a55a6899016aa2a5522cb","name":"@code3d/agent","dist-tags":{"latest":"0.0.1-alpha.10"},"versions":{"0.0.1-alpha.0":{"name":"@code3d/agent","version":"0.0.1-alpha.0","license":"SEE LICENSE IN LICENSE","_id":"@code3d/agent@0.0.1-alpha.0","maintainers":[{"name":"vilicvane","email":"vilicvane@live.com"}],"dist":{"shasum":"5c3f7fc6693081a8d1ab8c00fb0e387c91a16860","tarball":"https://registry.npmjs.org/@code3d/agent/-/agent-0.0.1-alpha.0.tgz","fileCount":33,"integrity":"sha512-gZQ25La1QHauuaIGgddEprVZ7KhG5A8Ca702B5C3pDMUt9OaKi0pYR8tv2ufCEStsvqMtiKFMcrJRZFAouta9Q==","signatures":[{"sig":"MEYCIQDLGR316E4uLrskARnY/NSQy6/BcXC1MW3huaZhaq1DHQIhALdDEuqwFuogD+fGF23A+oN1UGO3gMZHGpuWtSqkTf4m","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":107639},"type":"module","_from":"file:code3d-agent-0.0.1-alpha.0.tgz","exports":{".":{"types":"./bld/index.d.ts","default":"./bld/index.js"}},"scripts":{"test":"npm run build && npm run test:types && npm run test:run","build":"node ../../node_modules/typescript/bin/tsc --build","prepack":"node ../../scripts/package-license.mjs","test:run":"node --test \"test/*.test.ts\"","test:types":"node ../../node_modules/typescript/bin/tsc --noEmit -p test/tsconfig.json"},"_npmUser":{"name":"vilicvane","email":"vilicvane@live.com"},"_resolved":"/tmp/code3d-cli-release-final-0908/code3d-agent-0.0.1-alpha.0.tgz","_integrity":"sha512-gZQ25La1QHauuaIGgddEprVZ7KhG5A8Ca702B5C3pDMUt9OaKi0pYR8tv2ufCEStsvqMtiKFMcrJRZFAouta9Q==","_npmVersion":"11.19.0","description":"Shared browser/Node protocol for the Code3D App and local `c3d` CLI process. The App executes requests and owns all project data and receipts. This package provides configuration, encryption, the local HTTP client, reconnecting App WebSocket transport and","directories":{},"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agent_0.0.1-alpha.0_1788848442586_0.34012184513239396","host":"s3://npm-registry-packages-npm-production"}},"0.0.1-alpha.1":{"name":"@code3d/agent","version":"0.0.1-alpha.1","license":"SEE LICENSE IN LICENSE","_id":"@code3d/agent@0.0.1-alpha.1","maintainers":[{"name":"vilicvane","email":"vilicvane@live.com"}],"dist":{"shasum":"5b40f0790a8eb752dec1012b46b5a3199e52416e","tarball":"https://registry.npmjs.org/@code3d/agent/-/agent-0.0.1-alpha.1.tgz","fileCount":33,"integrity":"sha512-EefJKodAi8j26GjPO3P4YnFk91sBUHxAEG3iwNNAR4Vbw6h1McRAcMZ24VPV3oxJ4BJqMO+kCHOYivzzzFA63Q==","signatures":[{"sig":"MEYCIQCHy2uExlzPRK42RclQEFdpc0HH5T3bMP09BvR0NHR1KgIhAMSWIeDidmEG9/+LCwpuYR6p/FFq2ZxvyEKSYy/z1xpX","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":107144},"type":"module","_from":"file:code3d-agent-0.0.1-alpha.1.tgz","exports":{".":{"types":"./bld/index.d.ts","default":"./bld/index.js"}},"scripts":{"test":"npm run build && npm run test:types && npm run test:run","build":"node ../../node_modules/typescript/bin/tsc --build","prepack":"node ../../scripts/package-license.mjs","test:run":"node --test \"test/*.test.ts\"","test:types":"node ../../node_modules/typescript/bin/tsc --noEmit -p test/tsconfig.json"},"_npmUser":{"name":"vilicvane","email":"vilicvane@live.com"},"_resolved":"/tmp/code3d-agent-config-release-0908-jp44b5g4/final/code3d-agent-0.0.1-alpha.1.tgz","_integrity":"sha512-EefJKodAi8j26GjPO3P4YnFk91sBUHxAEG3iwNNAR4Vbw6h1McRAcMZ24VPV3oxJ4BJqMO+kCHOYivzzzFA63Q==","_npmVersion":"11.19.0","description":"Shared browser/Node protocol for the Code3D App and local `c3d` CLI process. The App executes requests and owns all project data and receipts. This package provides configuration, encryption, the local HTTP client, reconnecting App WebSocket transport and","directories":{},"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agent_0.0.1-alpha.1_1788880386418_0.5115473814473741","host":"s3://npm-registry-packages-npm-production"}},"0.0.1-alpha.2":{"name":"@code3d/agent","version":"0.0.1-alpha.2","license":"SEE LICENSE IN LICENSE","_id":"@code3d/agent@0.0.1-alpha.2","maintainers":[{"name":"vilicvane","email":"vilicvane@live.com"}],"homepage":"https://github.com/vilicvane/code3d#readme","bugs":{"url":"https://github.com/vilicvane/code3d/issues"},"dist":{"shasum":"dc8f9754d0d0b4ef19d5b3172c6051ca2d9173a6","tarball":"https://registry.npmjs.org/@code3d/agent/-/agent-0.0.1-alpha.2.tgz","fileCount":35,"integrity":"sha512-ljvmPUdB7lltK+trIBeXHiqLwLW3Kbe4csoT3SVnz8yN8U3CwfBetugukE8u64f0Ea8JkwL85t2dKrFU7QXARA==","signatures":[{"sig":"MEYCIQD8Y3T3t/VP3kVRQvdv2yVrZGpcQHWstF1G9rieKcRVgwIhAIGl7lWkHr30gGgjO2d79h+5UPqZNQvTLbJ94ca2osAN","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@code3d%2fagent@0.0.1-alpha.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":188724},"type":"module","_from":"file:/home/runner/work/code3d/code3d/dist/packages/code3d-agent-0.0.1-alpha.2.tgz","exports":{".":{"types":"./bld/index.d.ts","default":"./bld/index.js"}},"scripts":{"test":"npm run build && npm run test:types && npm run test:run","build":"node ../../scripts/build-packages.mjs @code3d/agent","prepack":"npm run build","test:run":"node --import ../../test/source-loader.mjs --test --test-concurrency=1 \"test/*.test.ts\"","test:types":"node ../../node_modules/typescript/bin/tsc --noEmit -p test/tsconfig.json"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","approver":{"name":"vilicvane","email":"vilicvane@live.com"},"trustedPublisher":{"id":"github","oidcConfigId":"oidc:9390e854-f5b0-4026-9ce4-e2feb05c168c"}},"_resolved":"/home/runner/work/code3d/code3d/dist/packages/code3d-agent-0.0.1-alpha.2.tgz","_integrity":"sha512-ljvmPUdB7lltK+trIBeXHiqLwLW3Kbe4csoT3SVnz8yN8U3CwfBetugukE8u64f0Ea8JkwL85t2dKrFU7QXARA==","repository":{"url":"git+https://github.com/vilicvane/code3d.git","type":"git","directory":"packages/agent"},"_npmVersion":"11.19.1","description":"Shared browser/Node protocol for the Code3D App and local `c3d` CLI process. The App executes requests and owns all project data and receipts. This package provides configuration, encryption, the local HTTP client, reconnecting App WebSocket transport and","directories":{},"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agent_0.0.1-alpha.2_1789117819121_0.40957323685768254","host":"s3://npm-registry-packages-npm-production"}},"0.0.1-alpha.10":{"_id":"@code3d/agent@0.0.1-alpha.10","bugs":{"url":"https://github.com/vilicvane/code3d/issues"},"dist":{"shasum":"6a5750fcd295d3cb7b3f7ae513d5e67fc0fde50e","tarball":"https://registry.npmjs.org/@code3d/agent/-/agent-0.0.1-alpha.10.tgz","fileCount":35,"integrity":"sha512-zkhyZc/HoqngeQDP7H+y8Dqaf/DctxN8ha/PGAiL/ia14fX8T8v7pKxE506Es2TO4ei0+IHIFB4x69IR7i24Rg==","signatures":[{"sig":"MEUCIQC9y/akGJz4xxcdQih9WNcp47l1gRcYVTD+mZm8vdqEOAIgAcIgt9ZQat3ngFkaIum4JroRhi2xLNa7kJTvP8sJHJU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICeA/NXTvnwEMNyCXOorUy0GA5/qzwmTDPL3J2NUR0HXAiEA6YhsHzFoWKkcqfv4JBcYe5tbyAZYM/7Y/Fqy6yLJRHU="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@code3d%2fagent@0.0.1-alpha.10","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":189490},"name":"@code3d/agent","type":"module","_from":"file:/home/runner/work/code3d/code3d/dist/packages/code3d-agent-0.0.1-alpha.10.tgz","exports":{".":{"types":"./bld/index.d.ts","default":"./bld/index.js"}},"license":"SEE LICENSE IN LICENSE","scripts":{"test":"npm run build && npm run test:types && npm run test:run","build":"node ../../scripts/build-packages.mjs @code3d/agent","prepack":"npm run build","test:run":"node --import ../../test/source-loader.mjs --test --test-concurrency=1 \"test/*.test.ts\"","test:types":"node ../../node_modules/typescript/bin/tsc --noEmit -p test/tsconfig.json"},"version":"0.0.1-alpha.10","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:d4e0af8e-5c2c-4961-b540-27f001f36d17"}},"homepage":"https://github.com/vilicvane/code3d#readme","_resolved":"/home/runner/work/code3d/code3d/dist/packages/code3d-agent-0.0.1-alpha.10.tgz","_integrity":"sha512-zkhyZc/HoqngeQDP7H+y8Dqaf/DctxN8ha/PGAiL/ia14fX8T8v7pKxE506Es2TO4ei0+IHIFB4x69IR7i24Rg==","repository":{"url":"git+https://github.com/vilicvane/code3d.git","type":"git","directory":"packages/agent"},"_npmVersion":"11.19.1","description":"Shared browser/Node protocol for the Code3D App and local `c3d` CLI process. The App executes requests and owns all project data and receipts. This package provides configuration, encryption, the local HTTP client, reconnecting App WebSocket transport and","directories":{},"maintainers":[{"name":"vilicvane","email":"vilicvane@live.com"}],"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent_0.0.1-alpha.10_1789578105344_0.1753601574226158"}}},"time":{"created":"2026-09-08T06:20:42.392Z","modified":"2026-09-16T17:01:45.842Z","0.0.1-alpha.0":"2026-09-08T06:20:42.719Z","0.0.1-alpha.1":"2026-09-08T15:13:06.551Z","0.0.1-alpha.2":"2026-09-11T09:10:19.221Z","0.0.1-alpha.10":"2026-09-16T17:01:45.436Z"},"bugs":{"url":"https://github.com/vilicvane/code3d/issues"},"license":"SEE LICENSE IN LICENSE","homepage":"https://github.com/vilicvane/code3d#readme","repository":{"url":"git+https://github.com/vilicvane/code3d.git","type":"git","directory":"packages/agent"},"description":"Shared browser/Node protocol for the Code3D App and local `c3d` CLI process. The App executes requests and owns all project data and receipts. This package provides configuration, encryption, the local HTTP client, reconnecting App WebSocket transport and","maintainers":[{"name":"vilicvane","email":"vilicvane@live.com"}],"readme":"# @code3d/agent\n\nShared browser/Node protocol for the Code3D App and local `c3d` CLI process.\nThe App executes requests and owns all project data and receipts. This package\nprovides configuration, encryption, the local HTTP client, reconnecting App\nWebSocket transport and per-agent request endpoint. The Node bridge and CLI\nadapter live in [@code3d/cli](../cli/README.md).\n\n## Agent grants\n\nThe App calls `createAgentConfig({port, origin, sessionId, name})` for each agent\nand hands the complete private configuration to it through a copied prompt:\n\n```json\n{\n  \"port\": 54321,\n  \"origin\": \"https://www.code3d.org\",\n  \"sessionId\": \"stable-project-session-id\",\n  \"agentId\": \"stable-agent-id\",\n  \"name\": \"Euler\",\n  \"key\": \"<32 random bytes as unpadded base64url>\"\n}\n```\n\nEach agent has its own secret and local server port. Ports must be integers in\n1024–65535; suggestions use 49152–65535. The server binds only `127.0.0.1` on that\nexact port and never probes alternative ports. The App persists grants per\nproject, including port, color, connection history and receipts. Opening the\nproject restores connections without opening the panel. Changing a port keeps\nthe identity and journal, closes the old socket/retry, and generates an updated\nprompt. Revoke deletes that grant/journal and stops retries; Revoke all does\nso for every agent in the current project. Accepted changes continue saving.\n\nConfiguration and storage have one current format, with no configuration version\nor migration path. The App stores grants and receipts in `code3d-agents`.\nNever reopen an existing grant with an empty journal.\n\n## Local authentication and lifecycle\n\n`LocalHost` opens `ws://127.0.0.1:<port>/sessions/<sessionId>/agents/<agentId>/app`.\nThe Node service checks the exact Host, App Origin and path before upgrading.\nEach side contributes a fresh random challenge. The bridge encrypts both with\nits `bridge-proof` key, and the App responds with the same challenge pair using\nits separate `app-proof` key. Both verify freshness before becoming ready.\nSeparate HKDF domains prevent reflection into either proof or request/response.\nNeither the secret nor source content appears in URLs or plaintext frames.\n\nThe authenticated App connection accepts encrypted requests and sends encrypted\nresponses. Ephemeral transport IDs only correlate current HTTP responses; the\nstable operation IDs and receipts belong to the App. A service restart loses\nconnections and pending waits, and the App reconnects using its original journal.\nHandshake authentication does not mark an agent as having interacted; its first\nvalid operation does. The App retries with bounded exponential backoff until\nrevoked, ended or the project is closed/switched away.\n\nLocal HTTP operations reject any Origin header and require the exact loopback\nHost and configured grant path. Ciphertext is authenticated before forwarding.\nThe local service has no project registration database, offline queue or receipt\ncache. Resource bounds cover messages, sockets, uploading requests, buffered\nbytes and pending responses; there are no public proxy or billing quotas.\n\n## Wire contract\n\nThe client posts an encrypted JSON envelope to:\n\n```text\nPOST http://127.0.0.1:<port>/sessions/<sessionId>/agents/<agentId>/requests\nContent-Type: application/json\n```\n\nThe response body is another envelope. Both have\n`{version: 1, requestId, nonce, ciphertext}`. Binary fields use unpadded base64url.\nHKDF-SHA-256 derives separate AES-256-GCM keys for each agent and direction, with\nthe session ID as salt. A fresh random 96-bit nonce is generated per message;\nthe 128-bit tag authenticates protocol version, session, agent, direction and\nrequest ID. Plaintext JSON is limited to 16 MiB, including encoded artifacts.\n\n`AgentEndpoint.handle(envelope)` decrypts and validates a request, invokes its\nhandler and encrypts the result. The App chooses the grant by agent ID and the\nendpoint authenticates its ciphertext. The local service has exactly its configured grant.\nMultiple endpoints share the App's project service; that service\nowns version checks, batch preflight, serialization and persistence. The endpoint\nalone does not supply transactional file writes or model observation semantics.\n\nThe CLI accepts one JSON request from stdin. `AgentClient.request(value)` encrypts\nand sends that JSON value without interpreting operation names or fields. The\nbridge likewise forwards authenticated content without an operation schema.\nValidation and normalization run in the App's `AgentEndpoint`, so application\noperations can evolve without requiring a new CLI build. Configuration,\nencryption, receipt recovery and the generic response/artifact envelope are the\nstable transport contract. Current App operations still accept one request at a\ntime; this does not introduce batch execution or JSON Lines.\n\n## Use the client\n\nInstall `@code3d/agent` to use the same authenticated client as the CLI. Configuration comes from the App's copied prompt:\n\n```ts\nimport {readFile} from 'node:fs/promises';\nimport {AgentClient, parseAgentConfig} from '@code3d/agent';\n\nconst config = parseAgentConfig(\n  JSON.parse(await readFile('project.c3d.json', 'utf8')),\n);\nconst client = await AgentClient.create(config);\nconst response = await client.request({operation: 'context'});\nconsole.log(response);\n```\n\nThe [local CLI service](../cli/README.md) must be running and connected to the\nopen App. For project work, follow the [agent Markdown entry](../../docs/agents.md):\n[file operations](../../docs/agents/files.md), [cursor selection](../../docs/agents/cursor.md),\n[observations](../../docs/agents/observation.md), and [recovery](../../docs/agents/recovery.md)\ndefine the App's behavior. They are maintained separately from this transport SDK.\n\n## Retries and uncertain outcomes\n\nRequest IDs are scoped to an agent grant. Identical normalized requests with the\nsame ID join an in-progress execution or return the saved result. Different\ncontent with the same ID returns `request_conflict`. Errors from the handler are\nalso retained, since work may have started before failure. Both success and\nfailure responses can carry validated `artifacts`; a failed modeling observation\nmay contain a diagnostic inspect image and available topology in its error\ndetails. Receipt replay preserves the failure status and the same artifacts. Transport failures\nnever imply rollback, and the client does not automatically resubmit changes.\n\n`result` returns the saved response, `result_pending`, `result_interrupted`, or `result_unknown` in the\ncurrent grant. A missing result is not proof of non-execution after a grant was\nreplaced. Keep the original request ID to query or retry the identical request.\n\nReceipts are never evicted while a grant accepts work. The default limit is 4096\nrequests and 64 MiB of serialized responses. Running requests reserve room for\na maximum-size response; new work returns `agent_busy` when reservations exhaust\ncapacity, or `session_capacity` when retained receipts exhaust it. Old results\nand matching retries remain readable. Request fingerprints use SHA-256 so the\njournal does not retain additional copies of full source submissions.\n\nA `ReceiptJournal` records a request fingerprint before the handler can start,\nthen saves the completed response before replying. Failure to write the initial\nrecord prevents execution. A record without a response after reopening returns\n`result_interrupted` with an unknown outcome; matching retries cannot execute it\nagain. Failure to save the outcome returns `receipt_storage_failed` with the\nobserved response. Inspect current files before deciding on a new change.\n\nRun `npm test --workspace @code3d/agent` from the repository root. Tests include\nreal loopback HTTP exchanges, tampering, cross-agent isolation, concurrent retries\nand recovering the result after a lost response. The CLI tests additionally\nexercise real session-managed CLI, WebSockets, restart/reconnect and App-side revocation. App browser\ntests run the real CLI against both storage backends, render PNGs, page topology,\nverify temporary/JSDoc arguments and check independent cursors.\n\n## Source and integration\n\n| Area                                              | Implementation                                                               |\n| ------------------------------------------------- | ---------------------------------------------------------------------------- |\n| Public API and configuration                      | [Exports](src/index.ts), [grant configuration](src/config.ts)                |\n| Encryption and authenticated envelopes            | [Cipher](src/crypto.ts), [validation](src/validation.ts)                     |\n| Node/browser HTTP client                          | [AgentClient](src/client.ts)                                                 |\n| Reconnecting browser transport                    | [LocalHost](src/local-host.ts)                                               |\n| App request validation and response types         | [Protocol](src/protocol.ts), [render options](src/render-options.ts)         |\n| Request deduplication and receipt persistence     | [AgentEndpoint](src/endpoint.ts)                                             |\n| Local service adapter                             | [CLI bridge](../cli/src/bridge.ts), [service lifecycle](../cli/src/serve.ts) |\n| Project files, observations and persistent grants | [App agent integration](../app/src/agent/), [App README](../app/README.md)   |\n\nUse the [tests](test/) for complete endpoint/journal integration examples,\nincluding lost replies and reconnects. Keep the browser transport free of project\nstorage responsibilities: the App project service owns write preflight, saving,\ncompilation, and follow behavior.\n","readmeFilename":"README.md"}