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

package/src/core/agui_client.ts

@@ -79,6 +79,12 @@ export interface AgUiClientHandlers {
    * their result itself — so this is the channel for server-executed output.
    */
   onToolResult(toolCallId: string, content: string): void;
+  /**
+   * Fired for AG-UI activity events — ambient notices about what the *run* did,
+   * as opposed to work the agent asked for. `django-ag-ui` emits one with
+   * `activityType: "compaction"` when it condensed the history.
+   */
+  onActivity(activityType: string, content: unknown): void;
   /** Fired when a reasoning model starts emitting its chain-of-thought. */
   onReasoningStart(): void;
   /** Fired on every reasoning token; ``buffer`` is the full reasoning text so far. */
@@ -131,6 +137,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 +195,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. */
@@ -385,6 +419,9 @@ export class AgUiClient {
       onToolCallResultEvent({ event }) {
         h.onToolResult(event.toolCallId, event.content);
       },
+      onActivitySnapshotEvent({ event }) {
+        h.onActivity(event.activityType, event.content);
+      },
       // Reasoning. `@ag-ui/client` already maps the deprecated
       // THINKING_* events onto these REASONING_* callbacks, so handling the
       // reasoning family alone covers both protocol versions.

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

@@ -1,9 +1,12 @@
 // Public surface re-exports. Per CLAUDE.md, this is the only re-export point.
 
 export {
+  COMPACTION_ACTIVITY_TYPE,
   ELEMENT_TAG,
+  LOAD_CAPABILITY_TOOL,
   MAX_TOOL_ROUNDS,
   MESSAGE_ROLE,
+  STATE_EVENT,
   SUBMIT_EVENT,
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
@@ -16,6 +19,7 @@ export {
 export {
   AgUiChat,
   type MessageRole,
+  type StateDetail,
   type SubmitDetail,
   type ToggleDetail,
 } from "./core/ag_ui_chat.js";
@@ -93,6 +97,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 +114,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/ui/run_notice.ts

@@ -0,0 +1,35 @@
+/**
+ * A muted one-line notice about something the *run* did, rendered inline in the
+ * transcript between turns.
+ *
+ * Distinct from a tool card (which reports work the agent asked for and is
+ * settleable) and from an error (which is a failure). A notice is ambient: the
+ * agent condensed earlier turns, or loaded a skill. It never settles, never
+ * takes an action, and carries no controls — so it stays visually quiet and out
+ * of the way of the conversation it annotates.
+ */
+export function renderRunNotice(icon: string, text: string, kind: string): HTMLDivElement {
+  const notice = document.createElement("div");
+  notice.className = `run-notice run-notice--${kind}`;
+  notice.setAttribute("part", `run-notice run-notice-${kind}`);
+  // A status role, not an alert: this is informational and must not interrupt a
+  // screen reader mid-sentence. Polite announcements land after the current
+  // utterance, which is right for an annotation about turns already spoken.
+  notice.setAttribute("role", "status");
+
+  const glyph = document.createElement("span");
+  glyph.className = "run-notice-icon";
+  glyph.setAttribute("part", "run-notice-icon");
+  glyph.textContent = icon;
+  // Decorative: the adjacent text already says what happened, and a screen
+  // reader announcing the emoji's name would just add noise.
+  glyph.setAttribute("aria-hidden", "true");
+
+  const label = document.createElement("span");
+  label.className = "run-notice-text";
+  label.setAttribute("part", "run-notice-text");
+  label.textContent = text;
+
+  notice.append(glyph, label);
+  return notice;
+}

package/src/ui/styles.ts

@@ -886,6 +886,32 @@ export const STYLES = `
   margin-top: 6px;
 }
 
+.run-notice {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  align-self: flex-start;
+  max-width: 100%;
+  margin: 2px 0;
+  padding: 3px 10px;
+  border: 1px dashed var(--ag-ui-border);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--ag-ui-muted);
+  font-size: 0.8em;
+  line-height: 1.4;
+}
+
+.run-notice-icon {
+  flex: none;
+  opacity: 0.75;
+}
+
+.run-notice-text {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
 .attachment-chip {
   display: inline-flex;
   align-items: center;

package/src/ui/ui_strings.ts

@@ -49,6 +49,10 @@ export interface UiStrings {
   navigating: string;
   /** Missing-placeholder skill hint. Tokens: `{title}`, `{fields}`. */
   skillNeeds: string;
+  /** Notice shown when the agent condensed earlier turns. Token: `{count}`. */
+  historyCompacted: string;
+  /** Notice shown when the agent loads an agent skill. Token: `{name}`. */
+  usingSkill: string;
 
   // ── Composer ────────────────────────────────────────────────────────────────
   /** `aria-label` of the message textarea. */
@@ -195,6 +199,8 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   noResult: "No result returned.",
   declinedAction: "User declined the action.",
   navigating: "Navigating…",
+  historyCompacted: "Earlier turns condensed to fit the context window ({count} removed)",
+  usingSkill: "Using skill {name}",
   skillNeeds: "“{title}” needs: {fields}",
 
   message: "Message",

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.12.0";
+export const VERSION: string = "0.14.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;
-}