BETAv0.24.11
GitHub Install
The SDK
Docs/Automate/The SDK

The SDK

Edit on GitHub
docs-site/automate/sdk.md

Install it from npm, at the version of the orrery you talk to:

pnpm add @getorrery/client

The SDK packages are published with every harness release, at the harness's version: @getorrery/protocol (the wire types), @getorrery/client, @getorrery/cells (terminal cells), @getorrery/anim, @getorrery/bind (puts data into catalog components; WebAssembly, about 900 KB), and for Angular @getorrery/chat, @getorrery/ui and @getorrery/styles.

@getorrery/client is the TypeScript half of the client SDK. It is pure data, with no drawing:

  • AguiSession: decodes frames, tracks seq, re-attaches with since, and sends control requests (session.attach, turn.cancel, intent, consent.answer, query).
  • SurfaceStore: holds the surfaces a session describes, for your UI to draw.
  • Transports: HttpSseTransport for orrery serve, WebSocketTransport for a node's /ws and the relay.

session.httpAgent() hands you the stock @ag-ui/client HttpAgent, unmodified, pointed at POST /run. A test runs that agent against a real kernel on every build, which is how Orrery checks that existing AG-UI clients work as they are. frameOf(raw) reads a frame off the wire: it lifts seq and Orrery's other extras out of metadata.orrery.

The main entry imports nothing from node:, so a web page bundles it as is. The Node-only parts (the orrery-client/1 channel over ORRERY_ENDPOINT, reading fixtures from disk) are in @getorrery/client/node.

Send files

session.submit(text, [filePart(name, type, base64)]);

Files travel as AG-UI content parts in turn.submit's input.parts. The limits are the same as run --attach: 5 MB a file, 10 MB a message.

A client never writes state

AG-UI's shared state is bidirectional; Orrery's is not. StateSnapshot and StateDelta flow out of the kernel only. An edit a person makes goes back as an intent, which the kernel validates.

Rust

The Rust equivalent is the orrery-client crate on crates.io (cargo add orrery-client), tested against the same conformance fixtures. Its version follows the harness's, like the npm packages.

Extensions are a different SDK

To write an extension rather than a client, use @getorrery/ext (Node), orrery-guest (Rust to WebAssembly) or orrery-ext-api (native Rust). See Write your first extension.

Limits

  • One version for all. Every package and crate carries the harness version; mixing versions across them is not supported.
  • No provenance. The packages are built in a private repository, so npm shows no provenance attestation; check a release against its git tag harness-vX.Y.Z instead.
  • A bundler's resolution. The type declarations use extensionless relative imports: set "moduleResolution": "bundler" in your tsconfig.json. A project on node16/nodenext resolution does not type-check against them yet.
  • ESM only. No CommonJS build is published.
  • Releases are permanent. A broken version is fixed by the next patch, never replaced.
  • Before 0.3.0 the packages were not published and were named @orrery/*; the @orrery scope on npm belongs to someone else.