{"_id":"@beeos-ai/acp-types","name":"@beeos-ai/acp-types","dist-tags":{"beta":"0.1.0-beta.1","latest":"0.1.0-beta.1"},"versions":{"0.1.0-beta.1":{"name":"@beeos-ai/acp-types","version":"0.1.0-beta.1","description":"TypeScript wire types for the BeeOS proxy ACP protocol (beeos-claw <-> web/mobile SDKs). Independent of upstream @agentclientprotocol/sdk.","license":"MIT","author":{"name":"BeeOS","email":"dev@beeos.ai"},"repository":{"type":"git","url":"git+https://github.com/beeos-ai/acp-types.git"},"homepage":"https://github.com/beeos-ai/acp-types","keywords":["beeos","acp","agent-client-protocol","types","json-rpc","wire-protocol"],"type":"module","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./factories":{"types":"./dist/factories/index.d.ts","default":"./dist/factories/index.js"},"./normalize":{"types":"./dist/normalize.d.ts","default":"./dist/normalize.js"}},"main":"dist/index.js","types":"dist/index.d.ts","sideEffects":false,"engines":{"node":">=18"},"scripts":{"clean":"rm -rf dist coverage","build":"npm run clean && tsc -p tsconfig.json","test":"vitest run","test:types":"tsc --noEmit -p tsconfig.test.json","test:coverage":"vitest run --coverage","prepublishOnly":"npm run clean && npm run build && npm run test"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.3","vitest":"^3.0.0","@vitest/coverage-v8":"^3.0.0"},"_id":"@beeos-ai/acp-types@0.1.0-beta.1","gitHead":"dace40d4aafdd47d237c832415383a83588c05cb","bugs":{"url":"https://github.com/beeos-ai/acp-types/issues"},"_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-HEY+1fAUaQZ/vcPqKWFXFZt+rcCFt96yHIFr6towl6jolygIvX+rRe7fkdsFMDbbKPzllkdQa5lgcyhs4mVlTw==","shasum":"73bd7b563d6e0ffb864f7af632b8bf8ba68e04e0","tarball":"https://registry.npmjs.org/@beeos-ai/acp-types/-/acp-types-0.1.0-beta.1.tgz","fileCount":115,"unpackedSize":93575,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGFlcOKyVy170GuyLxZDQLC7Gr0MvJfu2jS4+P0h9kMvAiBzYocEbVVhBN5LxVPSkICmgnfZyaGALNqIGAgXzgWWcQ=="}]},"_npmUser":{"name":"beenpm","email":"beeos001@gmail.com"},"directories":{},"maintainers":[{"name":"beenpm","email":"beeos001@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/acp-types_0.1.0-beta.1_1776888604464_0.38000510495566053"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-22T20:10:04.368Z","0.1.0-beta.1":"2026-04-22T20:10:04.591Z","modified":"2026-04-22T20:10:04.805Z"},"maintainers":[{"name":"beenpm","email":"beeos001@gmail.com"}],"description":"TypeScript wire types for the BeeOS proxy ACP protocol (beeos-claw <-> web/mobile SDKs). Independent of upstream @agentclientprotocol/sdk.","homepage":"https://github.com/beeos-ai/acp-types","keywords":["beeos","acp","agent-client-protocol","types","json-rpc","wire-protocol"],"repository":{"type":"git","url":"git+https://github.com/beeos-ai/acp-types.git"},"author":{"name":"BeeOS","email":"dev@beeos.ai"},"bugs":{"url":"https://github.com/beeos-ai/acp-types/issues"},"license":"MIT","readme":"# @beeos-ai/acp-types\n\nTypeScript wire types for the BeeOS proxy ACP protocol (agent client protocol speaker between\n`beeos-claw` agent and `web` / `mobile` SDKs).\n\nThis package is the **single source of truth** for the JSON-over-WebSocket protocol that flows\nbetween BeeOS agents and their front-end clients. It is **independent** of the upstream\n`@agentclientprotocol/sdk` — BeeOS operates a proxy layer that adapts ACP for multi-tenant\ncloud deployment.\n\n## Install\n\n```bash\nnpm install @beeos-ai/acp-types\n```\n\n## Usage\n\n### Consume types (client or agent side)\n\n```ts\nimport type {\n  ServerSessionUpdate,\n  ClientSessionUpdate,\n  AgentMessageChunkUpdate,\n  ToolCallStartUpdate,\n  StreamCompleteOk,\n  StreamCompleteErr,\n} from \"@beeos-ai/acp-types\";\n\nfunction handle(update: ClientSessionUpdate) {\n  switch (update.sessionUpdate) {\n    case \"agent_message_chunk\":\n      // update.content is narrowed to TextBlock | ImageBlock | ResourceLinkBlock\n      break;\n    case \"stream_complete\":\n      if (update.stopReason === \"error\") {\n        // update.error is narrowed to string (required)\n      }\n      break;\n    // ...\n  }\n}\n```\n\n### Produce messages (factories, type-safe, no `as any`)\n\n```ts\nimport {\n  makeAgentMessageChunk,\n  makeToolCallStart,\n  makeStreamCompleteError,\n} from \"@beeos-ai/acp-types/factories\";\n\nconst chunk = makeAgentMessageChunk(\"Hello\", { _turnId: \"run-abc\" });\nconst err = makeStreamCompleteError(\"Provider timed out\");\n```\n\n### Normalize snake_case payloads (legacy interop)\n\n```ts\nimport { normalizeSessionUpdate } from \"@beeos-ai/acp-types/normalize\";\n\n// Converts upstream snake_case keys (tool_call_id, raw_input) to camelCase\n// and trims unknown fields before feeding to chat-store.\nconst camel = normalizeSessionUpdate(rawWireMessage);\n```\n\n## Design principles\n\n1. **Protocol is a contract, not an implementation** — types live in a versioned package so\n   `beeos-claw`, `web`, and `mobile` depend on the same source.\n2. **Discriminated unions** — every `sessionUpdate` variant and JSON-RPC `method` is a\n   separate interface keyed by a string literal; `switch` statements are provably exhaustive.\n3. **LSP subset** — `ServerSessionUpdate ⊂ ClientSessionUpdate`. The transport signature\n   uses the narrower type, the reducer signature uses the wider one.\n4. **Zero runtime deps** — `@a2ui/react` and other UI frameworks are decoupled via generic\n   `CanvasUpdateEnvelope<TMessage = unknown>`; consumers instantiate with their message type.\n5. **Branded IDs** — `JsonRpcId`, `SessionId`, `ToolCallId`, `MessageId` are nominal string\n   types preventing accidental cross-use.\n\n## Package layout\n\n```\nsrc/\n├── index.ts                # public barrel\n├── meta.ts                 # ACP_PROTOCOL_VERSION, ResponseMeta\n├── ids.ts                  # branded IDs\n├── enums.ts                # ToolKind / ToolStatus / StopReason / MessageRole\n├── run-outcome.ts          # RunOutcomeShape for prompt termination\n├── normalize.ts            # runtime snake_case ↔ camelCase helper\n├── content/                # ContentBlock variants (Text/Image/Audio/File/Resource/ResourceLink)\n├── session-update/         # 16 sessionUpdate variants + ServerSessionUpdate / ClientSessionUpdate\n├── json-rpc/               # envelope + 29 method-specific params/results + registry\n└── factories/              # type-safe builders (replaces all `as unknown as ACPUpdatePayload`)\n```\n\n## Versioning\n\n- `0.x` — experimental; breaking changes allowed between minors.\n- Future `1.0` — API stable; breaking changes only at majors.\n\nCompatible with:\n\n- `beeos-claw` >= 0.2.41\n- `@beeos/sdk` (web/mobile) via facade re-exports\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-01fce6b9bdbe2ab698dc5038d5c7a9d4"}