react-websocket 4.0.0 → 4.18.0

package/dist/ag-ui.d.cts

@@ -0,0 +1,493 @@
+//#region src/types.d.ts
+/**
+ * Where to connect: a URL, or a function that returns one (sync or async).
+ *
+ * A function is called before **every** connection attempt, including reconnects,
+ * so it can put a fresh auth token in the URL. If it throws or rejects, that counts
+ * as a failed attempt and is retried with backoff.
+ *
+ * @example
+ * ```ts
+ * createWebSocket(async () => `wss://api.example.com/live?token=${await getToken()}`);
+ * ```
+ */
+type UrlSource = string | (() => string | Promise<string>);
+/**
+ * Connection state.
+ *
+ * - `idle`: not connected and not trying to be. Nobody is using the client yet, or everyone stopped.
+ * - `connecting`: the first attempt is in progress.
+ * - `open`: connected. `send()` goes out immediately.
+ * - `reconnecting`: the connection dropped (or an attempt failed) and a retry is scheduled or in progress.
+ * - `closed`: stopped for good, by `close()` or after giving up on reconnecting.
+ *   It stays closed until `connect()` or `reconnect()` is called, or every hook unmounts. If
+ *   nothing held it when it stopped, the next hook to mount starts it again.
+ */
+type Status = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed';
+/** The client's state as seen by React. A new object is created on every change. */
+interface Snapshot<In> {
+  /** Connection state. */
+  readonly status: Status;
+  /** Most recent message (after `parse`/`json` and `schema`), kept across reconnects. */
+  readonly lastMessage: In | undefined;
+  /**
+   * Consecutive failed attempts since the last stable connection. A connection that closes
+   * within `reconnect.minUptime` of opening counts as failed. `0` while open.
+   */
+  readonly attempt: number;
+}
+/** Details of a closed connection, from the browser's `CloseEvent`. */
+interface CloseInfo {
+  /** Close code: `1000` is a normal close, `1006` an abnormal one (e.g. network loss), `4000`–`4999` are yours. */
+  readonly code: number;
+  /** Close reason sent by the side that closed the connection. Often empty. */
+  readonly reason: string;
+  /** Whether the closing handshake completed. */
+  readonly wasClean: boolean;
+}
+/** Options for `client.migrate()`. */
+interface MigrateOptions {
+  /**
+   * Where to connect instead: a URL, or a function called before the connection, like the
+   * client's own `url`. Later reconnects go there too, until the client is closed, gives up or
+   * is torn down.
+   * @default the client's current URL
+   */
+  url?: UrlSource;
+  /**
+   * Move at a random moment within this many ms, so that clients asked to move together don't
+   * all reconnect at once.
+   * @default 0
+   */
+  within?: number;
+}
+/** Per-message options for `send()`. */
+interface SendOptions {
+  /**
+   * Drop the message instead of queueing it when the socket isn't open. For data that
+   * is stale by the time a reconnect finishes, such as player input or cursor positions.
+   * @default false
+   */
+  volatile?: boolean;
+  /**
+   * Keep only the newest queued message with this key. Sending again with the same key
+   * while disconnected replaces the earlier one, which moves to the back of the queue
+   * (or of the `priority` messages, for a priority one).
+   * For state where only the latest value matters, such as "my position is now (x, y)".
+   */
+  key?: string;
+  /**
+   * Queue this message ahead of every message queued without `priority`, after earlier
+   * priority messages. For control messages that must not wait behind a backlog, such as
+   * cancel, interrupt or a token refresh. Messages sent from `open` listeners still go first.
+   *
+   * It only matters while the socket isn't open: once a message is handed to the browser,
+   * nothing can overtake it. To keep that buffer short, send bulky streams with `maxBuffered`.
+   * @default false
+   */
+  priority?: boolean;
+  /**
+   * Drop the message instead of sending it while more than this many bytes are already
+   * waiting in the browser's send buffer (`socket.bufferedAmount`). For high-rate streams on
+   * a slow link, such as audio frames or per-tick input, where a late message is worse than
+   * none. `send()` returns `false`, and `onDrop` isn't called.
+   *
+   * Only checked while the socket is open: a message queued while disconnected is sent on
+   * open regardless. `bufferedAmount` includes what you sent earlier in the same task, so set
+   * it well above one burst of messages.
+   *
+   * @example
+   * ```ts
+   * voice.send(frame, { volatile: true, maxBuffered: 64 * 1024 });
+   * ```
+   */
+  maxBuffered?: number;
+  /**
+   * Drop the message instead of sending it if it has been queued for longer than this many
+   * ms, for messages that go stale during a long outage, such as "typing" or a price quote.
+   * Overrides `queue.maxAge`. Checked when the socket opens and whenever another message is
+   * queued; `onDrop` is called then.
+   */
+  maxAge?: number;
+  /**
+   * Called if the message is dropped from the queue without being sent: replaced by a
+   * newer message with the same `key`, evicted by `queue.limit`, or older than `maxAge`. Not
+   * called when the queue is cleared because the client closed or gave up, or when `send()`
+   * drops the message right away (`volatile` while not open, or `maxBuffered`) and returns
+   * `false`.
+   */
+  onDrop?: () => void;
+}
+/**
+ * Reported via the `error` event (and `onError`) when an incoming message can't be
+ * decoded by `parse`/`json` or fails `schema` validation. The message is not delivered.
+ *
+ * @example
+ * ```ts
+ * onError(error) {
+ *   if (error instanceof MessageError) report(error.data, error.issues);
+ * }
+ * ```
+ */
+declare class MessageError extends Error {
+  /** The raw `event.data` that failed. */
+  readonly data: unknown;
+  /** Schema validation issues, when the message failed `schema`. */
+  readonly issues: ReadonlyArray<{
+    readonly message: string;
+  }> | undefined;
+  constructor(message: string, data: unknown, options?: {
+    cause?: unknown;
+    issues?: ReadonlyArray<{
+      readonly message: string;
+    }>;
+  });
+}
+/** Events emitted by a client. Subscribe with `client.on(type, listener)` or `useWebSocketEvent`. */
+interface EventMap<In> {
+  /**
+   * The socket opened (initially or after a reconnect). Listeners run before queued
+   * messages are sent, so a handshake sent from here goes out first.
+   */
+  open: (event: Event) => void;
+  /** A message arrived and passed `parse` and `schema`. */
+  message: (message: In, event: MessageEvent) => void;
+  /** A socket closed, whether it will be retried or not. */
+  close: (close: CloseInfo) => void;
+  /**
+   * A socket error `Event`, a {@link MessageError} for an undecodable or invalid message,
+   * or the `Error` thrown by the `WebSocket` constructor or a `url` function.
+   */
+  error: (error: Event | MessageError | Error) => void;
+}
+/**
+ * A WebSocket connection that reconnects, queues, decodes and can be shared.
+ * Create one with `createWebSocket()`.
+ *
+ * The connection is reference-counted: it opens when the first hook mounts (or
+ * `ready` is read) and closes one tick after the last hook unmounts. Calling
+ * `connect()` keeps it open regardless, until `close()`.
+ *
+ * @typeParam In - Type of incoming messages.
+ * @typeParam Out - Type accepted by `send()`.
+ */
+interface WebSocketClient<In = unknown, Out = unknown> {
+  /** The URL (or URL function) the client was created with. */
+  readonly url: UrlSource;
+  /**
+   * A promise that resolves once the socket has opened. Reading it starts an idle client.
+   *
+   * It stays resolved through automatic reconnects, so `use(client.ready)` shows a
+   * Suspense fallback only for the first connection, never on a network blip; use
+   * `status` to show reconnects. It rejects when the client gives up reconnecting, when
+   * `close()` is called, and during a server render. After that, `connect()` or
+   * `reconnect()` make it a new pending promise.
+   *
+   * It is safe to pass to React 19's `use()`: the same promise is returned until its state
+   * changes, and it carries `status`/`value`/`reason` so `use()` doesn't suspend when it is
+   * already settled.
+   */
+  readonly ready: Promise<void>;
+  /** The current underlying `WebSocket`, if any. An escape hatch; prefer the client's methods. */
+  readonly socket: WebSocket | null;
+  /** Subscribe to snapshot changes. Compatible with `useSyncExternalStore`. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+  /** The current {@link Snapshot}. Returns the same object until something changes. */
+  getSnapshot(): Snapshot<In>;
+  /**
+   * Listen to an event. Returns an unsubscribe function. Listener errors are re-thrown
+   * asynchronously, so one failing listener doesn't break the others.
+   */
+  on<K extends keyof EventMap<In>>(type: K, listener: EventMap<In>[K]): () => void;
+  /**
+   * Send a message (encoded with `serialize`/`json` if configured). If the socket isn't
+   * open, the message is queued and sent on open (see the `queue` option), unless
+   * `options.volatile` is set.
+   * @returns `true` if it was sent immediately, `false` if it was queued or dropped
+   *   (`volatile` while not open, or `maxBuffered` while open).
+   *
+   * @example
+   * ```ts
+   * game.send({ type: 'input', dx, dy }, { volatile: true }); // never replayed after a reconnect
+   * game.send({ type: 'position', x, y }, { key: 'position' }); // only the newest is queued
+   * game.send({ type: 'leave' }, { priority: true }); // ahead of everything already queued
+   * ```
+   */
+  send(message: Out, options?: SendOptions): boolean;
+  /**
+   * Start connecting, and keep the connection open even when no hook is using the
+   * client, until `close()` is called. Does nothing if already connecting or open.
+   */
+  connect(): void;
+  /**
+   * Close the connection and stop reconnecting. The status becomes `closed` and the
+   * send queue is cleared. Mounted hooks stay mounted; call `connect()` or `reconnect()`
+   * to start again. Closed while no hook holds it, the next hook to mount starts it again.
+   *
+   * Like `WebSocket.close()`, it throws for a code or reason the socket rejects (browsers take
+   * `1000` or `3000`–`4999`, and a reason up to 123 bytes), and then nothing has changed.
+   * @param code - Close code. @default 1000
+   */
+  close(code?: number, reason?: string): void;
+  /**
+   * Drop the current socket (if any) and connect again immediately, resetting the
+   * backoff. Also restarts a `closed` client.
+   */
+  reconnect(): void;
+  /**
+   * Move to a new connection without a gap, for example when the server asks its clients to
+   * before a deploy. At a random moment within `options.within` ms, it opens a new connection
+   * (to `options.url`, if given) and, once that one is open, closes the current one with code
+   * `1000`. Until then the current connection keeps working, so the status stays `open` and
+   * `send()` doesn't queue.
+   *
+   * `open` listeners run for the new connection, as after any reconnect, so handshakes and
+   * topic subscriptions are sent again. Requests the old connection hadn't answered fail as on
+   * a lost connection. If the new connection fails before opening, the current one stays. If
+   * the client isn't open when the moment comes, only the URL changes, for the next attempt.
+   * A later call replaces one that hasn't moved yet.
+   *
+   * @example
+   * ```ts
+   * // The server sends { type: 'reconnect', within: 30000 } before it shuts down.
+   * live.on('message', message => {
+   *   if (message.type === 'reconnect') live.migrate({ within: message.within, url: message.url });
+   * });
+   * ```
+   */
+  migrate(options?: MigrateOptions): void;
+  /**
+   * Hold the connection open until the returned function is called. This is what the
+   * hooks use; call it yourself to integrate with non-React code.
+   * @returns A release function (safe to call more than once).
+   */
+  acquire(): () => void;
+}
+//#endregion
+//#region src/runs.d.ts
+/**
+ * What happens to a run when its connection drops: `keep` resumes it on the next connection,
+ * for agents that keep working in the background; `cancel` aborts it and tells the server, for
+ * a chat answer nobody may be waiting for.
+ */
+type RunPolicy = 'keep' | 'cancel';
+/** Where a run is: streaming events, or ended. */
+type RunStatus = 'streaming' | 'done' | 'error' | 'aborted';
+/** A run's state, reduced from its events. A new object on every change. */
+interface AgentRun<T> {
+  readonly runId: string;
+  readonly status: RunStatus;
+  /** Reduced from the run's events with `reduce`, starting from `initial`. */
+  readonly value: T;
+  /** What `error` returned for the event that ended the run, when `status` is `'error'`. */
+  readonly error: unknown;
+}
+/** The subset of `Storage` that runs use, so `sessionStorage`, `localStorage` or your own fits. */
+type RunStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/** Runs that stream events and survive reconnects and reloads. Create with {@link createWebSocketRuns}. */
+interface WebSocketRuns<Req, T> {
+  /** The client the runs stream on. */
+  readonly client: WebSocketClient<any, any>;
+  /**
+   * Start a run and return its `runId`. The start message is sent as soon as the socket is
+   * open, and the run is remembered until it ends. `initial` overrides the `initial` option for
+   * this run. A `runId` it already knows, streaming or ended, starts nothing: the server starts
+   * a run only once per id. `delete()` it first to use the id again.
+   */
+  start(request: Req, options?: {
+    runId?: string;
+    policy?: RunPolicy;
+    initial?: T;
+  }): string;
+  /**
+   * Follow a run started elsewhere, such as in another tab or before a reload, from its first
+   * event. Does nothing for a run it already knows.
+   */
+  attach(runId: string, options?: {
+    policy?: RunPolicy;
+    initial?: T;
+  }): void;
+  /** Stop a streaming run: send `cancel`, and make it `'aborted'`. */
+  abort(runId: string): void;
+  /** A run's state, or `undefined` for one it doesn't know. The same object until it changes. */
+  get(runId: string): AgentRun<T> | undefined;
+  /** Every run it knows, oldest first. A new array on every change. */
+  list(): readonly AgentRun<T>[];
+  /** Get notified when a run changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Forget a run, aborting it first if it's streaming. */
+  delete(runId: string): void;
+  /** Stop following runs, and release the connection. Remembered runs stay remembered. */
+  dispose(): void;
+}
+//#endregion
+//#region src/ag-ui.d.ts
+/** A JSON Patch (RFC 6902) operation, as in AG-UI's `STATE_DELTA` and `ACTIVITY_DELTA`. */
+export interface JsonPatchOperation {
+  readonly op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+  /** A JSON Pointer (RFC 6901), such as `/items/0/name`. */
+  readonly path: string;
+  /** The source of `move` and `copy`. */
+  readonly from?: string;
+  /** The value to `add`, `replace` with or `test` for. */
+  readonly value?: unknown;
+}
+/** An AG-UI event: `type` is `'RUN_STARTED'`, `'TEXT_MESSAGE_CONTENT'`, `'STATE_DELTA'`, … */
+export interface AgUiEvent {
+  readonly type: string;
+  readonly [field: string]: any;
+}
+/** A tool call on an assistant message, as in AG-UI. */
+export interface AgUiToolCall {
+  readonly id: string;
+  readonly type: 'function';
+  readonly function: {
+    readonly name: string;
+    readonly arguments: string;
+  };
+}
+/** A message in an AG-UI thread. */
+export interface AgUiMessage {
+  readonly id: string;
+  readonly role: 'developer' | 'system' | 'assistant' | 'user' | 'tool' | 'reasoning' | 'activity';
+  readonly content?: unknown;
+  readonly toolCalls?: readonly AgUiToolCall[];
+  /** For a `tool` message, the call it answers. */
+  readonly toolCallId?: string;
+  /** For an `activity` message. */
+  readonly activityType?: string;
+  readonly [field: string]: unknown;
+}
+/** AG-UI's `RunAgentInput`: what a run starts from. */
+export interface RunAgentInput {
+  readonly threadId: string;
+  readonly runId: string;
+  readonly parentRunId?: string;
+  readonly state?: unknown;
+  readonly messages: readonly AgUiMessage[];
+  readonly tools: readonly unknown[];
+  readonly context: readonly unknown[];
+  readonly forwardedProps: unknown;
+}
+/** A thread's messages and shared state, reduced from AG-UI events. */
+export interface AgUiThread<S = unknown> {
+  readonly messages: readonly AgUiMessage[];
+  /** The shared state, from `STATE_SNAPSHOT` and `STATE_DELTA`. */
+  readonly state: S;
+  /**
+   * `'running'` from `RUN_STARTED`, `'finished'` after `RUN_FINISHED`, `'error'` after
+   * `RUN_ERROR`, `'aborted'` when the run was stopped from this side.
+   */
+  readonly status: 'idle' | 'running' | 'finished' | 'error' | 'aborted';
+  /** The step in progress, between `STEP_STARTED` and `STEP_FINISHED`. */
+  readonly step?: string;
+  /** From `RUN_ERROR`. */
+  readonly error?: {
+    readonly message: string;
+    readonly code?: string;
+  };
+  /** From `RUN_FINISHED`. */
+  readonly result?: unknown;
+  /**
+   * A `STATE_DELTA` couldn't be applied. `state` is the last good one, and later deltas are
+   * skipped until a `STATE_SNAPSHOT` arrives.
+   */
+  readonly stale: boolean;
+}
+/**
+ * Apply a JSON Patch (RFC 6902) without changing `document`: what changes is copied, the rest is
+ * shared. Throws, leaving `document` as it was, if an operation can't be applied: a missing path,
+ * an index out of range, a pointer that doesn't start with `/`, or a failed `test`.
+ */
+export declare function applyPatch<T>(document: T, operations: readonly JsonPatchOperation[]): T;
+/**
+ * Fold one AG-UI event into a thread, without changing it. Handles the run lifecycle, steps,
+ * text, tool calls and their results, reasoning, activity, and message and state snapshots and
+ * deltas. A `STATE_DELTA` that can't be applied marks the thread `stale` instead of throwing.
+ * Other events, such as `CUSTOM` and `RAW`, return the thread unchanged.
+ *
+ * Use it as a `reduce` function, or wrap it to handle events of your own.
+ */
+export declare function applyAgUiEvent<S>(thread: AgUiThread<S>, event: AgUiEvent): AgUiThread<S>;
+/** What the server sends for each event of a run: its run, its offset (from 1), and the event. */
+export interface AgUiEnvelope {
+  readonly runId: string;
+  readonly offset: number;
+  readonly event: AgUiEvent;
+}
+/** Options for {@link createAgUiAgent}. The message formats have defaults; see the guide. */
+export interface AgUiAgentOptions<S, In, Out> {
+  /** The thread's id, sent in every `RunAgentInput`. A new random one by default. */
+  threadId?: string;
+  /** The shared state before the first `STATE_SNAPSHOT`, sent with the first run. */
+  state?: S;
+  /** Names where streaming runs are remembered across reloads. @default 'ag-ui' */
+  name?: string;
+  /** @default `{ type: 'run', runId, input }` */
+  run?: (input: RunAgentInput, runId: string) => Out;
+  /** @default `{ type: 'resume', runId, after }` */
+  resume?: (runId: string, after: number | undefined) => Out;
+  /** @default `{ type: 'cancel', runId }` */
+  cancel?: (runId: string) => Out;
+  /**
+   * The message that asks the server for a `STATE_SNAPSHOT`, sent when a `STATE_DELTA` can't
+   * be applied. Without it, the state stays `stale` until the server sends one by itself.
+   */
+  resync?: (runId: string) => Out;
+  /** Recognize a run's event. @default messages shaped like {@link AgUiEnvelope} */
+  event?: (message: In) => AgUiEnvelope | null | undefined;
+  /** What happens to a run when its connection drops. @default 'keep' */
+  policy?: RunPolicy;
+  /** Where streaming runs are remembered. @default sessionStorage */
+  storage?: RunStorage | null;
+}
+/** An AG-UI agent over a WebSocket. Create with {@link createAgUiAgent}. */
+export interface AgUiAgent<S> {
+  /** The client the runs stream on. */
+  readonly client: WebSocketClient<any, any>;
+  /** The runs underneath, from `createWebSocketRuns`. */
+  readonly runs: WebSocketRuns<RunAgentInput, AgUiThread<S>>;
+  /**
+   * Start a run with the thread so far plus `input.messages`, which show up in the thread right
+   * away. A run that's still streaming is aborted first. Returns the run's id.
+   */
+  run(input?: {
+    messages?: readonly AgUiMessage[];
+    tools?: readonly unknown[];
+    context?: readonly unknown[];
+    forwardedProps?: unknown;
+  }, options?: {
+    policy?: RunPolicy;
+  }): string;
+  /** Stop the run that's streaming, if any. */
+  abort(): void;
+  /** The thread as of the latest run. The same object until it changes. */
+  getSnapshot(): AgUiThread<S>;
+  /** Get notified when the thread changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Stop following runs, and release the connection. */
+  dispose(): void;
+}
+/**
+ * Run an [AG-UI](https://docs.ag-ui.com) agent over a WebSocket. Each run streams AG-UI events,
+ * which are folded into the thread's messages and shared state with {@link applyAgUiEvent}.
+ * Runs come from `createWebSocketRuns`, so they resume after a reconnect or a reload, and a
+ * state delta that can't be applied asks for a snapshot (`resync`).
+ *
+ * AG-UI doesn't define messages for WebSockets, so the defaults are small: the client sends
+ * `{ type: 'run', runId, input }`, `{ type: 'resume', runId, after }` and
+ * `{ type: 'cancel', runId }`, and the server sends `{ runId, offset, event }`, with `offset`
+ * counting each run's events from 1. Each option replaces one of them.
+ *
+ * @example
+ * ```ts
+ * import { createAgUiAgent } from 'react-websocket/ag-ui';
+ *
+ * export const agent = createAgUiAgent(createWebSocket(url, { json: true }));
+ *
+ * agent.run({ messages: [{ id: crypto.randomUUID(), role: 'user', content: 'Plan my week' }] });
+ * ```
+ */
+export declare function createAgUiAgent<S = unknown, In = any, Out = any>(client: WebSocketClient<In, Out>, options?: AgUiAgentOptions<S, NoInfer<In>, NoInfer<Out>>): AgUiAgent<S>;
+//#endregion
+//# sourceMappingURL=ag-ui.d.cts.map

package/dist/ag-ui.d.ts

@@ -0,0 +1,171 @@
+import { RunPolicy, RunStorage, WebSocketClient, WebSocketRuns } from "./core.js";
+//#region src/ag-ui.d.ts
+/** A JSON Patch (RFC 6902) operation, as in AG-UI's `STATE_DELTA` and `ACTIVITY_DELTA`. */
+export interface JsonPatchOperation {
+  readonly op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+  /** A JSON Pointer (RFC 6901), such as `/items/0/name`. */
+  readonly path: string;
+  /** The source of `move` and `copy`. */
+  readonly from?: string;
+  /** The value to `add`, `replace` with or `test` for. */
+  readonly value?: unknown;
+}
+/** An AG-UI event: `type` is `'RUN_STARTED'`, `'TEXT_MESSAGE_CONTENT'`, `'STATE_DELTA'`, … */
+export interface AgUiEvent {
+  readonly type: string;
+  readonly [field: string]: any;
+}
+/** A tool call on an assistant message, as in AG-UI. */
+export interface AgUiToolCall {
+  readonly id: string;
+  readonly type: 'function';
+  readonly function: {
+    readonly name: string;
+    readonly arguments: string;
+  };
+}
+/** A message in an AG-UI thread. */
+export interface AgUiMessage {
+  readonly id: string;
+  readonly role: 'developer' | 'system' | 'assistant' | 'user' | 'tool' | 'reasoning' | 'activity';
+  readonly content?: unknown;
+  readonly toolCalls?: readonly AgUiToolCall[];
+  /** For a `tool` message, the call it answers. */
+  readonly toolCallId?: string;
+  /** For an `activity` message. */
+  readonly activityType?: string;
+  readonly [field: string]: unknown;
+}
+/** AG-UI's `RunAgentInput`: what a run starts from. */
+export interface RunAgentInput {
+  readonly threadId: string;
+  readonly runId: string;
+  readonly parentRunId?: string;
+  readonly state?: unknown;
+  readonly messages: readonly AgUiMessage[];
+  readonly tools: readonly unknown[];
+  readonly context: readonly unknown[];
+  readonly forwardedProps: unknown;
+}
+/** A thread's messages and shared state, reduced from AG-UI events. */
+export interface AgUiThread<S = unknown> {
+  readonly messages: readonly AgUiMessage[];
+  /** The shared state, from `STATE_SNAPSHOT` and `STATE_DELTA`. */
+  readonly state: S;
+  /**
+   * `'running'` from `RUN_STARTED`, `'finished'` after `RUN_FINISHED`, `'error'` after
+   * `RUN_ERROR`, `'aborted'` when the run was stopped from this side.
+   */
+  readonly status: 'idle' | 'running' | 'finished' | 'error' | 'aborted';
+  /** The step in progress, between `STEP_STARTED` and `STEP_FINISHED`. */
+  readonly step?: string;
+  /** From `RUN_ERROR`. */
+  readonly error?: {
+    readonly message: string;
+    readonly code?: string;
+  };
+  /** From `RUN_FINISHED`. */
+  readonly result?: unknown;
+  /**
+   * A `STATE_DELTA` couldn't be applied. `state` is the last good one, and later deltas are
+   * skipped until a `STATE_SNAPSHOT` arrives.
+   */
+  readonly stale: boolean;
+}
+/**
+ * Apply a JSON Patch (RFC 6902) without changing `document`: what changes is copied, the rest is
+ * shared. Throws, leaving `document` as it was, if an operation can't be applied: a missing path,
+ * an index out of range, a pointer that doesn't start with `/`, or a failed `test`.
+ */
+export declare function applyPatch<T>(document: T, operations: readonly JsonPatchOperation[]): T;
+/**
+ * Fold one AG-UI event into a thread, without changing it. Handles the run lifecycle, steps,
+ * text, tool calls and their results, reasoning, activity, and message and state snapshots and
+ * deltas. A `STATE_DELTA` that can't be applied marks the thread `stale` instead of throwing.
+ * Other events, such as `CUSTOM` and `RAW`, return the thread unchanged.
+ *
+ * Use it as a `reduce` function, or wrap it to handle events of your own.
+ */
+export declare function applyAgUiEvent<S>(thread: AgUiThread<S>, event: AgUiEvent): AgUiThread<S>;
+/** What the server sends for each event of a run: its run, its offset (from 1), and the event. */
+export interface AgUiEnvelope {
+  readonly runId: string;
+  readonly offset: number;
+  readonly event: AgUiEvent;
+}
+/** Options for {@link createAgUiAgent}. The message formats have defaults; see the guide. */
+export interface AgUiAgentOptions<S, In, Out> {
+  /** The thread's id, sent in every `RunAgentInput`. A new random one by default. */
+  threadId?: string;
+  /** The shared state before the first `STATE_SNAPSHOT`, sent with the first run. */
+  state?: S;
+  /** Names where streaming runs are remembered across reloads. @default 'ag-ui' */
+  name?: string;
+  /** @default `{ type: 'run', runId, input }` */
+  run?: (input: RunAgentInput, runId: string) => Out;
+  /** @default `{ type: 'resume', runId, after }` */
+  resume?: (runId: string, after: number | undefined) => Out;
+  /** @default `{ type: 'cancel', runId }` */
+  cancel?: (runId: string) => Out;
+  /**
+   * The message that asks the server for a `STATE_SNAPSHOT`, sent when a `STATE_DELTA` can't
+   * be applied. Without it, the state stays `stale` until the server sends one by itself.
+   */
+  resync?: (runId: string) => Out;
+  /** Recognize a run's event. @default messages shaped like {@link AgUiEnvelope} */
+  event?: (message: In) => AgUiEnvelope | null | undefined;
+  /** What happens to a run when its connection drops. @default 'keep' */
+  policy?: RunPolicy;
+  /** Where streaming runs are remembered. @default sessionStorage */
+  storage?: RunStorage | null;
+}
+/** An AG-UI agent over a WebSocket. Create with {@link createAgUiAgent}. */
+export interface AgUiAgent<S> {
+  /** The client the runs stream on. */
+  readonly client: WebSocketClient<any, any>;
+  /** The runs underneath, from `createWebSocketRuns`. */
+  readonly runs: WebSocketRuns<RunAgentInput, AgUiThread<S>>;
+  /**
+   * Start a run with the thread so far plus `input.messages`, which show up in the thread right
+   * away. A run that's still streaming is aborted first. Returns the run's id.
+   */
+  run(input?: {
+    messages?: readonly AgUiMessage[];
+    tools?: readonly unknown[];
+    context?: readonly unknown[];
+    forwardedProps?: unknown;
+  }, options?: {
+    policy?: RunPolicy;
+  }): string;
+  /** Stop the run that's streaming, if any. */
+  abort(): void;
+  /** The thread as of the latest run. The same object until it changes. */
+  getSnapshot(): AgUiThread<S>;
+  /** Get notified when the thread changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Stop following runs, and release the connection. */
+  dispose(): void;
+}
+/**
+ * Run an [AG-UI](https://docs.ag-ui.com) agent over a WebSocket. Each run streams AG-UI events,
+ * which are folded into the thread's messages and shared state with {@link applyAgUiEvent}.
+ * Runs come from `createWebSocketRuns`, so they resume after a reconnect or a reload, and a
+ * state delta that can't be applied asks for a snapshot (`resync`).
+ *
+ * AG-UI doesn't define messages for WebSockets, so the defaults are small: the client sends
+ * `{ type: 'run', runId, input }`, `{ type: 'resume', runId, after }` and
+ * `{ type: 'cancel', runId }`, and the server sends `{ runId, offset, event }`, with `offset`
+ * counting each run's events from 1. Each option replaces one of them.
+ *
+ * @example
+ * ```ts
+ * import { createAgUiAgent } from 'react-websocket/ag-ui';
+ *
+ * export const agent = createAgUiAgent(createWebSocket(url, { json: true }));
+ *
+ * agent.run({ messages: [{ id: crypto.randomUUID(), role: 'user', content: 'Plan my week' }] });
+ * ```
+ */
+export declare function createAgUiAgent<S = unknown, In = any, Out = any>(client: WebSocketClient<In, Out>, options?: AgUiAgentOptions<S, NoInfer<In>, NoInfer<Out>>): AgUiAgent<S>;
+//#endregion
+//# sourceMappingURL=ag-ui.d.ts.map