TypeScript SDK

The @octostaff/sdk package is the shared, framework-agnostic contract layer between the Octostaff service and its consumers: the Octostaff wire protocol types and the thread assembler that turns events into Octostaff messages. Everything else that used to live here — taskqueue, model-stream, stream, env/auth helpers, agent-thread types — has moved into the package that actually uses it.

Subpath ExportsCopy link to heading

The root export is the Octostaff protocol surface; the assembler lives under its own subpath because it pulls in ai as a peer dependency for the post-assembled message reducer, which not every consumer needs.

src/protocol/core-codecs.ts is the runtime boundary shared by both peers: Octostaff verifies client-authored HTTP bodies and WebSocket frames with it and validates server frames before serialization; BubbleConnection validates server HTTP responses and WebSocket frames before exposing them to consumers.

Where to Start ReadingCopy link to heading

If you are…

• …rendering a thread in a React UI: read Thread Assembler. The package's public surface is small (one configured assembler, one stateful thread assembler, and native-part handlers) but the design space it covers — message grouping, segment rules, and idempotency — has a learning curve.
• …emitting Octostaff events from a service: read the Octostaff Events doc for the wire schema; the SDK just types it.
• …writing a new transport or storage adapter that needs to walk a Octostaff backlog and hand off to assistant-ui: the thread assembler doc covers the MessageFormatItem chaining shape.
• …connecting to Octostaff: construct BubbleConnection from @octostaff/sdk/client. It starts idle, opens WebSocket lazily, exposes connection-wide failures through onError, and becomes terminal after close(). Public discovery (listAuthenticators, getServerInfo) needs no token; protected calls fail with BubbleClientError when credentials are absent. Octostaff announces its heartbeat cadence when the socket authenticates; a socket silent for three cadences is treated as dead, and the client terminates it and reconnects. The idle-timeout fallback to HTTP polling applies only to a server that sends no heartbeats.
• …storing or transferring artifacts: read Artifact Protocol for the global /v1/artifacts routes, explicit access scopes, and staged transfer flow.

Local Thread ToolsCopy link to heading

@octostaff/sdk/amphibian exports one curated, harness-neutral tool catalog. LOCAL_BUBBLE_TOOL_DESCRIPTORS is the schema surface, and runLocalBubbleTool dispatches a validated call through the amphibian's own authenticated BubbleApi. Artifact tools share the catalog with four thread-oriented operations:

• browse_thread pages lossless events and participant context, cutting a page at about 20 KB of events and returning nextSeq to continue from;
• open_subthread creates an idempotent agent-only child;
• search_principals resolves an exact principal before mutation; and
• invite_to_thread adds one principal as member.

Thread ids are optional where the active thread is the natural default. An explicit id does not widen authority: Octostaff still evaluates the caller's current read, child-create, grant-management, discoverability, and invite privacy rights. A harness adapter is responsible only for translating the descriptors, supplying active-thread/tool-call correlation, and rendering the harness-neutral result.

Client ContractCopy link to heading

• HTTP and WebSocket responses are runtime-decoded before entering application state. Every failure is a BubbleClientError; branch on kind for local lifecycle/transport failures and code for Octostaff protocol failures.
• Unacknowledged appendEvent calls preserve registration order with cursor frames until socket handoff, but handoff is not a persistence acknowledgement. Pass { ack: true } when persistence or the assigned seq is required. HTTP acknowledgements are not ordered against earlier fire-and-forget WebSocket writes; use one transport when persistence order matters.
• subscribeThreadList, subscribeGrants, and subscribePresence fan multiple local listeners onto the protocol's singleton subscription. Their iterable adapters share { opened, changes(), close() } semantics.
• close() aborts in-flight HTTP, stops reconnect/polling, rejects queued work, and terminates subscriptions. A closed connection cannot be reused.

LayoutCopy link to heading

packages/sdk-typescript/
├── docs/
│   ├── 00-overview.mdx         # this page
│   ├── 10-artifact-protocol.mdx # Artifact HTTP/SDK contract
│   └── 15-assembler.mdx        # Thread Assembler
└── src/
    ├── identity/               # bubble authenticator dispatch
    ├── protocol/               # HTTP/WS shapes + bidirectional runtime codecs
    ├── types/                  # bubble event / principal / authz / message types
    ├── client/                 # connection, consumers, subscriptions, polling
    │   └── transport/          # HTTP, WebSocket, outbound queue, Node adapter
    ├── index.ts                # root barrel re-exporting all of the above
    └── assembler/              # event → BubbleMessage translator
        ├── assembler.ts        # configured assembler + thread lifecycle
        ├── run-segment.ts      # RunSegment class
        ├── tool-parts.ts       # event-neutral AI SDK tool-part traversal
        ├── chunk-helpers.ts    # internal chunk utilities
        ├── segment-reducer.ts  # persistent AI SDK reducer stream
        ├── event-handlers/     # semantic event families
        ├── native-part-handlers/ # core bubble-v1 families
        ├── contracts.ts        # public composition contracts
        └── index.ts            # slim public entrypoint