@artooi/ag-ui-web-component 0.12.0 → 0.13.0

package/dist/tools/page_state.d.ts

@@ -0,0 +1,40 @@
+import type { ClientTool } from "./client_tool_registry.js";
+/**
+ * A binding from a named piece of host page state to agent tools.
+ *
+ * Ergonomic sugar over `registerTool` for SPA state (Redux/Zustand/signals):
+ * generates a read tool and, when `write` is given, a destructive set tool.
+ *
+ * This is **not** AG-UI shared state. `STATE_SNAPSHOT` / `STATE_DELTA` are
+ * protocol events carrying state between agent and client; this is a pair of
+ * ordinary client tools the agent calls like any other. The two are unrelated,
+ * which is why this no longer carries the word "hook" — the old name read as
+ * protocol state sync, which this component does not implement.
+ */
+export interface PageState {
+    /** Base name; tools become `read_<name>` and `set_<name>`. */
+    readonly name: string;
+    /** Returns the current state value. */
+    readonly read: () => unknown;
+    /** Mutates the state from the agent-supplied args. Omit for read-only. */
+    readonly write?: (args: Record<string, unknown>) => unknown;
+    /** JSON-Schema for the set tool's args. Defaults to an open object. */
+    readonly schema?: Record<string, unknown>;
+}
+/**
+ * Build the tools for a {@link PageState}: always a `read_<name>` (read-only)
+ * tool, plus a `set_<name>` (`x-destructive`) tool when `write` is supplied.
+ */
+export declare function createPageStateTools(binding: PageState): ClientTool[];
+/**
+ * @deprecated Renamed to {@link PageState}. The old name read as AG-UI
+ * shared-state sync (`STATE_SNAPSHOT` / `STATE_DELTA`), which this component
+ * does not implement. Will be removed in a future major.
+ */
+export type StateHook = PageState;
+/**
+ * @deprecated Renamed to {@link createPageStateTools}. Will be removed in a
+ * future major.
+ */
+export declare const createStateHookTools: typeof createPageStateTools;
+//# sourceMappingURL=page_state.d.ts.map

package/dist/tools/page_state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page_state.d.ts","sourceRoot":"","sources":["../../src/tools/page_state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAC5D,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,GAAG,UAAU,EAAE,CA4BrE;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,6BAAuB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artooi/ag-ui-web-component",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Framework-free <ag-ui-chat> Web Component over the AG-UI protocol. Drop-in chat sidebar with a pluggable client-side tool registry, DOM driver primitives, animations, and destructive-action confirmation modal.",
   "type": "module",
   "main": "./dist/index.js",

package/src/constants.ts

@@ -19,6 +19,16 @@ export const SUBMIT_EVENT = "ag-ui-submit";
  */
 export const TOGGLE_EVENT = "ag-ui-toggle";
 
+/**
+ * Event dispatched by `<ag-ui-chat>` when AG-UI **shared state** changes — the
+ * server streamed a `STATE_SNAPSHOT` / `STATE_DELTA`, or the host assigned
+ * {@link AgUiChat.sharedState}. `detail` carries `{ state }`.
+ *
+ * This is the protocol's own state channel, distinct from `registerPageState`,
+ * which exposes host state to the agent as ordinary *tools*.
+ */
+export const STATE_EVENT = "ag-ui-state";
+
 /** Roles a chat message can take. */
 export const MESSAGE_ROLE = {
   USER: "user",

package/src/core/ag_ui_chat.ts

@@ -2,6 +2,7 @@ import type { Context, Interrupt, Message, Tool } from "@ag-ui/core";
 import {
   DEFAULT_ATTACHMENT_MAX_BYTES,
   MESSAGE_ROLE,
+  STATE_EVENT,
   SUBMIT_EVENT,
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
@@ -17,9 +18,9 @@ import { isDestructive } from "../tools/is_destructive.js";
 import { isNavigates } from "../tools/is_navigates.js";
 import { createPageActionTools, type ResolvePageTarget } from "../tools/page_action_tools.js";
 import { createPageMapContext, type PageMap } from "../tools/page_map.js";
+import { createPageStateTools, type PageState } from "../tools/page_state.js";
 import { parseToolCatalog } from "../tools/parse_tool_catalog.js";
 import { createRouteTools, type RouteMap } from "../tools/route_map.js";
-import { createStateHookTools, type StateHook } from "../tools/state_hook.js";
 import {
   type ApprovalRenderer,
   type ApprovalRequest,
@@ -73,6 +74,11 @@ export interface SubmitDetail {
   readonly attachments: readonly AttachmentRef[];
 }
 
+/** `detail` shape of the {@link STATE_EVENT} CustomEvent. */
+export interface StateDetail {
+  readonly state: Readonly<Record<string, unknown>>;
+}
+
 /** `detail` shape of the {@link TOGGLE_EVENT} CustomEvent. */
 export interface ToggleDetail {
   readonly collapsed: boolean;
@@ -158,7 +164,7 @@ export class AgUiChat extends HTMLElement {
   /**
    * Per-run frontend tool catalog provider. Defaults to the built-in
    * `route.*` tools (when a {@link routeMap} is set) plus the tools registered
-   * via {@link registerTool} / {@link registerStateHook}; override to supply a
+   * via {@link registerTool} / {@link registerPageState}; override to supply a
    * fully custom catalog.
    */
   getTools: () => Tool[] = () => [
@@ -322,6 +328,10 @@ export class AgUiChat extends HTMLElement {
   #runAttachments: readonly AttachmentRef[] = [];
 
   #client: AgUiClient | null = null;
+  // Seed for the next client. Once one exists it owns the live value (the
+  // agent applies STATE_SNAPSHOT / STATE_DELTA into it), so this is only the
+  // starting point — `sharedState` reads through to the client when present.
+  #sharedState: Record<string, unknown> = {};
   // Whether an interaction is in flight (first onRunStart → onSettled). Drives
   // the Send⇄Stop button: `agent.isRunning` is false between frontend-tool
   // rounds, but the user must still be able to stop there.
@@ -479,13 +489,46 @@ export class AgUiChat extends HTMLElement {
     this.#toolRegistry.register(tool);
   }
 
-  /** Bind a piece of host state to `read_<name>` / `set_<name>` tools. */
-  registerStateHook(hook: StateHook): void {
-    for (const tool of createStateHookTools(hook)) {
+  /**
+   * AG-UI **shared state** for this conversation — the protocol's own state
+   * channel, sent as `RunAgentInput.state` on every run and replaced in place
+   * when the server streams `STATE_SNAPSHOT` / `STATE_DELTA`. Assigning seeds
+   * the next run; reading returns whatever the agent last applied.
+   *
+   * Listen for {@link STATE_EVENT} to react to server-driven changes.
+   *
+   * Not to be confused with {@link registerPageState}, which exposes host
+   * state to the agent as ordinary *tools*.
+   */
+  get sharedState(): Readonly<Record<string, unknown>> {
+    return this.#client?.state ?? this.#sharedState;
+  }
+
+  set sharedState(state: Readonly<Record<string, unknown>>) {
+    this.#sharedState = { ...state };
+    // A client already exists for this conversation — push it through so the
+    // next run sends it, rather than silently waiting for a new conversation.
+    this.#client?.setState(this.#sharedState);
+  }
+
+  /** Bind a piece of host page state to `read_<name>` / `set_<name>` tools. */
+  registerPageState(binding: PageState): void {
+    for (const tool of createPageStateTools(binding)) {
       this.#toolRegistry.register(tool);
     }
   }
 
+  /**
+   * @deprecated Renamed to {@link registerPageState}. The old name read as
+   * AG-UI shared-state sync (`STATE_SNAPSHOT` / `STATE_DELTA`), which this
+   * component does not implement — these are ordinary client tools over host
+   * page state. Behaviour is unchanged; this alias will be removed in a future
+   * major.
+   */
+  registerStateHook(binding: PageState): void {
+    this.registerPageState(binding);
+  }
+
   /** The built-in `route.*` tools, present only when a route map is set. */
   #routeTools(): ClientTool[] {
     if (this.routeMap.length === 0) {
@@ -1588,6 +1631,7 @@ export class AgUiChat extends HTMLElement {
         getHeaders: () => this.headers,
         threadId: this.#threadId,
         initialMessages: this.#initialMessages,
+        initialState: this.#sharedState,
       });
       this.#client = new AgUiClient({
         agent,
@@ -1597,12 +1641,25 @@ export class AgUiChat extends HTMLElement {
         executeTool: (call) => this.#executeTool(call),
         resolveInterrupts: (interrupts) => this.#resolveInterrupts(interrupts),
         onPersist: (messages) => this.conversationStore.saveMessages(this.#threadId, messages),
+        onStateChanged: (state) => this.#onSharedStateChanged(state),
         connectionLostMessage: this.#strings.connectionLost,
       });
     }
     return this.#client;
   }
 
+  /** Mirror the agent's applied state and tell the host it moved. */
+  #onSharedStateChanged(state: Readonly<Record<string, unknown>>): void {
+    this.#sharedState = { ...state };
+    this.dispatchEvent(
+      new CustomEvent<StateDetail>(STATE_EVENT, {
+        detail: { state: this.#sharedState },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
   /** Whether ``call`` should be gated behind the confirmation card. */
   async #needsConfirmation(call: AgUiToolCall, tool: ClientTool): Promise<boolean> {
     if (this.autoConfirm) {

package/src/core/agui_client.ts

@@ -131,6 +131,13 @@ export interface AgUiClientConfig extends AgUiRunInputs {
    * conversation in-memory only.
    */
   onPersist?: (messages: readonly Message[]) => void;
+  /**
+   * Called whenever AG-UI shared state changes — the server streamed a
+   * `STATE_SNAPSHOT` / `STATE_DELTA`, or {@link AgUiClient.setState} was
+   * called. `@ag-ui/client` owns applying those events; this only forwards
+   * the result so a host can react.
+   */
+  onStateChanged?: (state: Readonly<Record<string, unknown>>) => void;
   /**
    * Error text surfaced to {@link AgUiClientHandlers.onError} when a run's
    * stream closes without a terminal AG-UI event (`RUN_FINISHED`/`RUN_ERROR`) —
@@ -182,6 +189,27 @@ export class AgUiClient {
     this.#resolveInterrupts = config.resolveInterrupts ?? null;
     this.#onPersist = config.onPersist ?? (() => {});
     this.#connectionLostMessage = config.connectionLostMessage ?? "Connection lost";
+    const onStateChanged = config.onStateChanged;
+    if (onStateChanged !== undefined) {
+      // The agent applies STATE_SNAPSHOT / STATE_DELTA itself; subscribing is
+      // how we learn the result rather than re-deriving it from the event
+      // stream. Lives for the agent's lifetime, which is this client's.
+      this.#agent.subscribe({
+        onStateChanged: ({ state }) => {
+          onStateChanged(state as Record<string, unknown>);
+        },
+      });
+    }
+  }
+
+  /** The current AG-UI shared state, as the agent last applied it. */
+  get state(): Readonly<Record<string, unknown>> {
+    return this.#agent.state as Record<string, unknown>;
+  }
+
+  /** Replace the shared state; the next run sends it as `RunAgentInput.state`. */
+  setState(state: Readonly<Record<string, unknown>>): void {
+    this.#agent.setState({ ...state });
   }
 
   /** Whether a run is currently in flight. */

package/src/core/create_http_agent.ts

@@ -18,6 +18,12 @@ export interface HttpAgentOptions {
   threadId?: string;
   /** Rehydrated history to seed the agent with (durable conversation). */
   initialMessages?: readonly Message[];
+  /**
+   * AG-UI shared state to seed the agent with. `@ag-ui/client` sends it as
+   * `RunAgentInput.state` on every run and replaces it in place when the
+   * server streams `STATE_SNAPSHOT` / `STATE_DELTA`.
+   */
+  initialState?: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -31,6 +37,7 @@ export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
   return new HttpAgent({
     url: options.endpoint,
     headers: options.headers ?? {},
+    initialState: { ...(options.initialState ?? {}) },
     // HttpAgent invokes its configured fetch as a method (`this.fetch(...)`),
     // which would rebind the global `fetch` to the agent instance and trigger
     // "Illegal invocation" in browsers. Wrap it so `fetch` is always called as

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   ELEMENT_TAG,
   MAX_TOOL_ROUNDS,
   MESSAGE_ROLE,
+  STATE_EVENT,
   SUBMIT_EVENT,
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
@@ -16,6 +17,7 @@ export {
 export {
   AgUiChat,
   type MessageRole,
+  type StateDetail,
   type SubmitDetail,
   type ToggleDetail,
 } from "./core/ag_ui_chat.js";
@@ -93,6 +95,16 @@ export {
   type ResolvePageTarget,
 } from "./tools/page_action_tools.js";
 export { createPageMapContext, type PageMap } from "./tools/page_map.js";
+/**
+ * @deprecated Renamed to `createPageStateTools` / `PageState`. The old names
+ * read as AG-UI shared-state sync, which this component does not implement.
+ */
+export {
+  createPageStateTools,
+  createStateHookTools,
+  type PageState,
+  type StateHook,
+} from "./tools/page_state.js";
 export { parseToolCatalog, type ToolCatalogEntry } from "./tools/parse_tool_catalog.js";
 export {
   createRouteTools,
@@ -100,7 +112,6 @@ export {
   type RouteMap,
   type RouteWithParams,
 } from "./tools/route_map.js";
-export { createStateHookTools, type StateHook } from "./tools/state_hook.js";
 export {
   type ApprovalOptions,
   type ApprovalRenderer,

package/src/tools/page_state.ts

@@ -0,0 +1,72 @@
+import { X_DESTRUCTIVE_KEY, X_SUMMARY_KEY } from "../constants.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/**
+ * A binding from a named piece of host page state to agent tools.
+ *
+ * Ergonomic sugar over `registerTool` for SPA state (Redux/Zustand/signals):
+ * generates a read tool and, when `write` is given, a destructive set tool.
+ *
+ * This is **not** AG-UI shared state. `STATE_SNAPSHOT` / `STATE_DELTA` are
+ * protocol events carrying state between agent and client; this is a pair of
+ * ordinary client tools the agent calls like any other. The two are unrelated,
+ * which is why this no longer carries the word "hook" — the old name read as
+ * protocol state sync, which this component does not implement.
+ */
+export interface PageState {
+  /** Base name; tools become `read_<name>` and `set_<name>`. */
+  readonly name: string;
+  /** Returns the current state value. */
+  readonly read: () => unknown;
+  /** Mutates the state from the agent-supplied args. Omit for read-only. */
+  readonly write?: (args: Record<string, unknown>) => unknown;
+  /** JSON-Schema for the set tool's args. Defaults to an open object. */
+  readonly schema?: Record<string, unknown>;
+}
+
+/**
+ * Build the tools for a {@link PageState}: always a `read_<name>` (read-only)
+ * tool, plus a `set_<name>` (`x-destructive`) tool when `write` is supplied.
+ */
+export function createPageStateTools(binding: PageState): ClientTool[] {
+  const tools: ClientTool[] = [
+    {
+      name: `read_${binding.name}`,
+      description: `Read the "${binding.name}" state.`,
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: `Read ${binding.name}`,
+      },
+      handler: () => binding.read(),
+    },
+  ];
+  const write = binding.write;
+  if (write !== undefined) {
+    tools.push({
+      name: `set_${binding.name}`,
+      description: `Update the "${binding.name}" state.`,
+      parameters: {
+        ...(binding.schema ?? { type: "object" }),
+        [X_DESTRUCTIVE_KEY]: true,
+        [X_SUMMARY_KEY]: `Update ${binding.name}`,
+      },
+      handler: (args) => write(args),
+    });
+  }
+  return tools;
+}
+
+/**
+ * @deprecated Renamed to {@link PageState}. The old name read as AG-UI
+ * shared-state sync (`STATE_SNAPSHOT` / `STATE_DELTA`), which this component
+ * does not implement. Will be removed in a future major.
+ */
+export type StateHook = PageState;
+
+/**
+ * @deprecated Renamed to {@link createPageStateTools}. Will be removed in a
+ * future major.
+ */
+export const createStateHookTools = createPageStateTools;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.12.0";
+export const VERSION: string = "0.13.0";

package/dist/tools/state_hook.d.ts

@@ -1,23 +0,0 @@
-import type { ClientTool } from "./client_tool_registry.js";
-/**
- * A binding from a named piece of host application state to agent tools.
- *
- * Ergonomic sugar over `registerTool` for SPA state (Redux/Zustand/signals):
- * generates a read tool and, when `write` is given, a destructive set tool.
- */
-export interface StateHook {
-    /** Base name; tools become `read_<name>` and `set_<name>`. */
-    readonly name: string;
-    /** Returns the current state value. */
-    readonly read: () => unknown;
-    /** Mutates the state from the agent-supplied args. Omit for read-only. */
-    readonly write?: (args: Record<string, unknown>) => unknown;
-    /** JSON-Schema for the set tool's args. Defaults to an open object. */
-    readonly schema?: Record<string, unknown>;
-}
-/**
- * Build the tools for a {@link StateHook}: always a `read_<name>` (read-only)
- * tool, plus a `set_<name>` (`x-destructive`) tool when `write` is supplied.
- */
-export declare function createStateHookTools(hook: StateHook): ClientTool[];
-//# sourceMappingURL=state_hook.d.ts.map

package/dist/tools/state_hook.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"state_hook.d.ts","sourceRoot":"","sources":["../../src/tools/state_hook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAC5D,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,EAAE,CA4BlE"}

package/src/tools/state_hook.ts

@@ -1,53 +0,0 @@
-import { X_DESTRUCTIVE_KEY, X_SUMMARY_KEY } from "../constants.js";
-import type { ClientTool } from "./client_tool_registry.js";
-
-/**
- * A binding from a named piece of host application state to agent tools.
- *
- * Ergonomic sugar over `registerTool` for SPA state (Redux/Zustand/signals):
- * generates a read tool and, when `write` is given, a destructive set tool.
- */
-export interface StateHook {
-  /** Base name; tools become `read_<name>` and `set_<name>`. */
-  readonly name: string;
-  /** Returns the current state value. */
-  readonly read: () => unknown;
-  /** Mutates the state from the agent-supplied args. Omit for read-only. */
-  readonly write?: (args: Record<string, unknown>) => unknown;
-  /** JSON-Schema for the set tool's args. Defaults to an open object. */
-  readonly schema?: Record<string, unknown>;
-}
-
-/**
- * Build the tools for a {@link StateHook}: always a `read_<name>` (read-only)
- * tool, plus a `set_<name>` (`x-destructive`) tool when `write` is supplied.
- */
-export function createStateHookTools(hook: StateHook): ClientTool[] {
-  const tools: ClientTool[] = [
-    {
-      name: `read_${hook.name}`,
-      description: `Read the "${hook.name}" state.`,
-      parameters: {
-        type: "object",
-        properties: {},
-        required: [],
-        [X_SUMMARY_KEY]: `Read ${hook.name}`,
-      },
-      handler: () => hook.read(),
-    },
-  ];
-  const write = hook.write;
-  if (write !== undefined) {
-    tools.push({
-      name: `set_${hook.name}`,
-      description: `Update the "${hook.name}" state.`,
-      parameters: {
-        ...(hook.schema ?? { type: "object" }),
-        [X_DESTRUCTIVE_KEY]: true,
-        [X_SUMMARY_KEY]: `Update ${hook.name}`,
-      },
-      handler: (args) => write(args),
-    });
-  }
-  return tools;
-}