@beeos-ai/acp-types

TypeScript wire types for the BeeOS proxy ACP protocol (agent client protocol speaker between beeos-claw agent and web / mobile SDKs).

This package is the single source of truth for the JSON-over-WebSocket protocol that flows between BeeOS agents and their front-end clients. It is independent of the upstream @agentclientprotocol/sdk — BeeOS operates a proxy layer that adapts ACP for multi-tenant cloud deployment.

Install

npm install @beeos-ai/acp-types

Usage

Consume types (client or agent side)

import type {
  ServerSessionUpdate,
  ClientSessionUpdate,
  AgentMessageChunkUpdate,
  ToolCallStartUpdate,
  StreamCompleteOk,
  StreamCompleteErr,
} from "@beeos-ai/acp-types";

function handle(update: ClientSessionUpdate) {
  switch (update.sessionUpdate) {
    case "agent_message_chunk":
      // update.content is narrowed to TextBlock | ImageBlock | ResourceLinkBlock
      break;
    case "stream_complete":
      if (update.stopReason === "error") {
        // update.error is narrowed to string (required)
      }
      break;
    // ...
  }
}

Produce messages (factories, type-safe, no as any)

import {
  makeAgentMessageChunk,
  makeToolCallStart,
  makeStreamCompleteError,
} from "@beeos-ai/acp-types/factories";

const chunk = makeAgentMessageChunk("Hello", { _turnId: "run-abc" });
const err = makeStreamCompleteError("Provider timed out");

Normalize snake_case payloads (legacy interop)

import { normalizeSessionUpdate } from "@beeos-ai/acp-types/normalize";

// Converts upstream snake_case keys (tool_call_id, raw_input) to camelCase
// and trims unknown fields before feeding to chat-store.
const camel = normalizeSessionUpdate(rawWireMessage);

Design principles

1. Protocol is a contract, not an implementation — types live in a versioned package so beeos-claw, web, and mobile depend on the same source.
2. Discriminated unions — every sessionUpdate variant and JSON-RPC method is a separate interface keyed by a string literal; switch statements are provably exhaustive.
3. LSP subset — ServerSessionUpdate ⊂ ClientSessionUpdate. The transport signature uses the narrower type, the reducer signature uses the wider one.
4. Zero runtime deps — @a2ui/react and other UI frameworks are decoupled via generic CanvasUpdateEnvelope<TMessage = unknown>; consumers instantiate with their message type.
5. Branded IDs — JsonRpcId, SessionId, ToolCallId, MessageId are nominal string types preventing accidental cross-use.

Package layout

src/
├── index.ts                # public barrel
├── meta.ts                 # ACP_PROTOCOL_VERSION, ResponseMeta
├── ids.ts                  # branded IDs
├── enums.ts                # ToolKind / ToolStatus / StopReason / MessageRole
├── run-outcome.ts          # RunOutcomeShape for prompt termination
├── normalize.ts            # runtime snake_case ↔ camelCase helper
├── content/                # ContentBlock variants (Text/Image/Audio/File/Resource/ResourceLink)
├── session-update/         # 16 sessionUpdate variants + ServerSessionUpdate / ClientSessionUpdate
├── json-rpc/               # envelope + 29 method-specific params/results + registry
└── factories/              # type-safe builders (replaces all `as unknown as ACPUpdatePayload`)

Versioning

• 0.x — experimental; breaking changes allowed between minors.
• Future 1.0 — API stable; breaking changes only at majors.

Compatible with:

• beeos-claw >= 0.2.41
• @beeos/sdk (web/mobile) via facade re-exports

License

MIT