Statewire bindings

Signatures quoted from source. Usage: Bind a Statewire, Deploy a Statewire. Related: Statewire reference.

Entry pointsCopy Anchor Link

@assistant-ui/react-statewireCopy Anchor Link

StatewireThreadCopy Anchor Link

const StatewireThread: <T>(options: StatewireThread.Options<T>) => ResourceElement<ClientOutput<"thread">>;

Binds a statewire to an assistant-ui thread for AuiConfig({ thread }). The run-dialect commands map onto composer and message actions.

StatewireThread.Options<T>Copy Anchor Link

State and runsCopy Anchor Link

StatewireThread.RunState, one element of the mount's runs array:

StatewireThread.RunsDispatch, the dispatch record; absent between applied and the next dispatch or take:

Commands and input requestsCopy Anchor Link

runsMaterialize, useStatewireSendCommand, useStatewireRuns, useStatewireStateCopy Anchor Link

const runsMaterialize: (mount: unknown, effects: StatewireThread.MaterializeEffects) => void;
const useStatewireSendCommand: () => (command: StatewireThread.Command) => Promise<unknown>;
const useStatewireRuns: () => StatewireThread.Runs;
function useStatewireState(): UserExternalState;
function useStatewireState<T>(selector: (state: UserExternalState) => T): T;

runsMaterialize is the run dialect's materialize fold: rollback(rollbackTo) first when present, then append per dispatched message. It throws when the record carries rollbackTo and no rollback effect. The hooks and every Extras read throw This method can only be called when you are using StatewireThread off another thread type. The hooks, inside the AuiProvider: dispatch any command (rejects with StatewireSendError), the typed runs read, and the replicated statewire state (UserExternalState is Assistant.ExternalState's value type, Record<string, unknown> when none is declared).

@assistant-ui/react-statewire/local-storageCopy Anchor Link

LocalStorageSession, LocalStorageComposerDraftsCopy Anchor Link

const LocalStorageSession: (options: LocalStorageSession.Options) => ResourceElement<StatewireClient.SessionStorage>;
const LocalStorageComposerDrafts: (options: LocalStorageComposerDrafts.Options) => ResourceElement<StatewireThread.ComposerStorage>;

Both options require threadId: string and a nonempty stable principal: string. Changing principal on a mounted resource throws; remount the thread/session per account. Session options also accept protocol, retention, limits, onError, onEvict, and migrate from the key-value session adapter; draft options accept ttl and max. Tabs sharing a principal and threadId share the record (clientId, per-lane nextSeq, commands, outbox, parked verdicts, undelivered inbox updates): one client id, one lane, verdicts fanned out to every attach (concurrent attaches). Record writes serialize under a Web Lock.

• LocalStorageSession stores the SessionRecord under aui:statewire-session:<encoded-principal>:<encoded-threadId>. lock takes the Web Lock aui:statewire-session-lock:<encoded-principal>:<encoded-threadId>, notifyLock the Web Lock statewire-notify:<storage key>, subscribe rides the storage event. Throws without localStorage or navigator.locks
• LocalStorageComposerDrafts stores under aui:composer-draft:<encoded-principal>:<encoded-threadId>. The mount sweep, across the current principal's keys, drops drafts older than ttl (default 7 days) and beyond the newest max (default 50); a corrupt entry is removed, an empty draft deletes its key. Throws without localStorage
• Legacy unscoped records remain quarantined. Migration requires explicit ownership attribution.

localStorageSessionBackend, localStorageSessionNamespaceCopy Anchor Link

const localStorageSessionBackend: KeyValueSessionStorage.Backend;
const localStorageSessionNamespace: string;

The backend LocalStorageSession writes through and the namespace it stores sessions under. Pass both, with the principal, to readOutboxes / subscribeOutboxes to list every thread's outbox:

const unsubscribe = subscribeOutboxes(
  localStorageSessionBackend,
  { namespace: localStorageSessionNamespace, principal: userId },
  (outboxes) => setPending(outboxes.flatMap((o) => o.entries)),
);

@statewire/ai-sdkCopy Anchor Link

useChatCopy Anchor Link

resumeStream() is currently a no-op; the resume option is unused.

const useChat: (options?: UseChatOptions) => UseChatHelpers;

AI SDK useChat hosted in an in-process statewire. The ChatTransport streams UIMessageChunks into ChatState.

• The host element is internal. ChatCommands is the whole command set; extra commands need your own host
• UseChatOptions carries neither optimistic nor materialize
• transport defaults to new DefaultChatTransport(), read fresh per request
• Chunk handling: the chunk pipeline

resume and resumeStream() are inert. stop() acts only while streaming or submitted, clearError() only in error. regenerate and the tool helpers throw StatewireReject on an empty thread or an unknown messageId. | ChatState | { id: string; messages: UIMessage[]; status: ChatStatus; error?: { message: string } } | | ChatAddToolOutputParams | { tool: string; toolCallId: string; options?: ChatRequestOptions } & ({ state?: "output-available"; output: unknown; errorText?: never } \| { state: "output-error"; output?: never; errorText: string }) | | ChatAddToolApprovalResponseParams | { id: string; approved: boolean; reason?: string; options?: ChatRequestOptions } |

plainCopy Anchor Link

const plain: <T>(value: T) => T;

Deep JSON snapshot. Unwraps statewire proxies into plain data.

isRecord, syncArray, syncRecord, syncIndexCopy Anchor Link

const isRecord: (value: unknown) => value is Record<string, unknown>;
const syncArray: (target: unknown[], next: unknown[]) => void;
const syncRecord: (target: Record<string, unknown>, next: Record<string, unknown>) => void;
const syncIndex: (target: unknown[], index: number, next: unknown) => void;

Reconcile a full snapshot into target with minimal in-place mutations. syncIndex appends past the end.

useLatestCopy Anchor Link

const useLatest: <T>(value: T) => () => T;

Stable getter for the latest render's value.

statewire-rivetCopy Anchor Link

Direct StatewireWebsocket connections through the RivetKit 2.3.10 gateway currently fail during subprotocol negotiation. See deployment status and issue #325.

statewireActor, StatewireRivetCopy Anchor Link

const statewireActor: <TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues, TActions>(config: statewireActor.Config<…>) => ActorDefinition<…>;
namespace statewireActor {
  type Config<…> = ActorConfigInput<…> & StatewireHostInternal.SocketHostOptions & { statewire: ResourceElement<Statewire>; onWebSocket?: never };
}
const StatewireRivet: (transport: ResourceElement<Statewire>, options?: StatewireHostInternal.SocketHostOptions) => StatewireRivet.Instance;

statewireActor is a rivetkit actor (peer rivetkit ^2.3.10) serving a statewire host, one socket host per actor instance. It sets canHibernateWebSocket to authorize === undefined, over any value you pass, and rebuilds the host in createVars on every wake. Client ids ride the client query parameter. StatewireRivet is the manual composition into your own actor({...}) via onWebSocket; there, set canHibernateWebSocket: false when passing authorize. Actor destroy sends every client fin: gone, runs your onDestroy, then disposes the host.

@statewire/cloudflareCopy Anchor Link

StatewireDurableObject, statewireHandlersCopy Anchor Link

const StatewireDurableObject: <Env = unknown>(transport?: ResourceElement<Statewire> | StatewireDurableObject.TransportFactory<Env>, options?: StatewireDurableObject.Options) => StatewireDurableObject.Class<Env>;
const statewireHandlers: (ctx: StatewireDurableObject.Context, transport: StatewireDurableObject.Transport, options?: StatewireDurableObject.Options) => StatewireDurableObject.Handlers;

• StatewireDurableObject: class factory for a complete Durable Object (extends StatewireDurableObject(ThreadHost())).
  • An element is sugar over the overridable transport() method. A (restored, env) => transport factory mounts durable.
  • WebSocket upgrades, /stream, and /frames are served. Every other request goes to the overridable onRequest (426 by default).
  • Client ids, the authorize value, and its original authorizedAt timestamp survive hibernation via serializeAttachment. Enabled lease expiry requires a valid unexpired timestamp before restoration; older sockets reconnect and authorize again. A retained socket with a malformed attachment is closed 1008.
  • An open SSE stream holds the object out of hibernation.
• statewireHandlers: raw handlers for an existing Durable Object class, called from the constructor. A durable mount restores statewire:snapshot under blockConcurrencyWhile and persists it on a 1000 ms debounce, flushed on socket close and SSE stream end and written after finish and dispose. Client watermarks live under statewire:client:<id> (the ClientStore of StatewireSocketHost); retained sockets' records load under blockConcurrencyWhile. After dispose, fetch answers 410 and socket events are ignored.

Setup: Durable Objects.

routeStatewireRequest, getStatewireByName, WS_SUBPROTOCOLCopy Anchor Link

const routeStatewireRequest: (request: Request, env: Record<string, unknown>) => Response | Promise<Response> | undefined;
const getStatewireByName: (binding: StatewireDurableObject.Namespace, name: string) => StatewireDurableObject.Stub;
const WS_SUBPROTOCOL = "statewire.v1";

Worker router for /:binding-name/:instance-name (binding match ignores case, -, _; the instance name is URL-decoded; undefined when nothing matches or the path has fewer than two segments) and the direct stub lookup. /frames with a non-POST method answers 405 with Allow: POST. StatewireDurableObject() with neither a transport nor a transport() override throws on first use.

With the default lease lifetime, restored sockets missing the original authorizedAt reconnect before state is restored.

statewire-nodeCopy Anchor Link

statewireHostCopy Anchor Link

const statewireHost: (options: StatewireNode.Options) => StatewireNode.Host;

A statewire host over standard Request/Response for Node servers and pinned instances. fetch routes by path suffix: GET|POST …/stream attaches as SSE, POST …/frames submits statement frames (405 with Allow: POST otherwise), a WebSocket upgrade answers 426, anything else 404. upgrade serves /ws from any runtime's socket: it validates the handshake (400 {"detail":"statewire.v1 is required"} without the subprotocol, 400 {"detail":…} without a valid client query parameter, a thrown error for a request without Upgrade: websocket) and returns { protocol: "statewire.v1", attach }; attach(socket) after the handshake connects the socket, feeds text frames to the host (a binary frame gets fin: protocol-error then close 1008), and detaches on onclose. authorize runs on the socket's initial message with the upgrade headers merged in; a refusal is fin: unauthorized|forbidden then close 1008. After close, fetch and upgrade answer 410. Every StatewireHostInternal.SocketHostOptions field (protocol, key, authorize, heartbeatIntervalMs, …) passes through; an authorize refusal is a thrown Response.

Serve it from node:http with @assistant-ui/pinned/node's toRequest/writeResponse, or from a pinned instance's fetch with /ws through upgradeResponse (apps/proxy/src/statewire.ts adapts the ws socket). Contract tests: packages/statewire/node/tests/host.test.ts.