@adia-ai/web-modules 0.8.25 → 0.8.26

package/agent-admin/agent-admin/agent-admin.yaml

@@ -0,0 +1,162 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIAgentAdmin
+tag: agent-admin-ui
+status: stable
+component: AgentAdmin
+category: container
+version: 1
+description: |
+  L4 admin composite (CHAT-HARNESS.md §Components row L4 + §Interfaces 5,
+  gh#600 / WCH-5) — persona roster + settings pane + a chat pane, wired to
+  the store-swap law: a genuine persona switch (a new `SettingsStore`
+  object) resets the conversation, disposes open generative-UI surfaces,
+  and mints a fresh session; re-selecting the already-active persona
+  (same memoized store reference) resets nothing.
+
+  Behavior-only orchestrator (mirrors `<chat-shell>`) — stamps no HTML of
+  its own. Bespoke light-DOM children: `<admin-roster-ui>`,
+  `<admin-settings-ui>`, `<chat-shell>` in EXTERNAL mode (no `proxy-url` —
+  this composite drives it via `wireAgentEvents`).
+
+  Transport-blind (CHAT-HARNESS law 1): the `runTurn` JS property is
+  `(session, text) → AsyncIterable<AgentEvent>`; packaged default
+  `undefined` falls back to a deterministic, keyless stub that compiles
+  the active persona FRESH every turn (`readLivePersona` +
+  `compilePersona`) and visibly cites what it read — the live-apply
+  probe: edit an entry's content in `<admin-settings-ui>`, the next
+  turn's stub output cites the new text immediately, no propagation
+  channel.
+
+  Lives in `packages/web-modules/agent-admin/` alongside
+  `<admin-roster-ui>` and `<admin-settings-ui>`.
+
+composes:
+  - admin-roster-ui
+  - admin-settings-ui
+  - chat-shell
+
+props:
+  personas:
+    description: |
+      Full array of `Persona` objects (from `@adia-ai/persona`) this admin
+      surface manages. JSON-attribute or JS-property; the composite derives
+      `<admin-roster-ui>`'s summary list from it automatically.
+    type: array
+    default: []
+    required: true
+    dynamic: true
+  active-id:
+    description: |
+      The currently-active persona's id. Reflects; setting it programmatically
+      (or via `<admin-roster-ui>`'s `persona-change`) runs `setActivePersona`.
+    type: string
+    default: ""
+    reflect: true
+    dynamic: true
+  renderer:
+    description: |
+      Optional generative-UI renderer (WCH-4's surface-host registry seam)
+      — JS property only, host-injected (private `@genui/renderer` packages
+      never ship inside this composite). Omitted, surface events are safely
+      dropped.
+    type: object
+    dynamic: true
+  runTurn:
+    description: |
+      Optional transport override — `(session, text) => AsyncIterable<AgentEvent>`.
+      JS property only. Omitted, the composite's own deterministic stub
+      drives every turn (see description).
+    type: object
+    dynamic: true
+
+events:
+  persona-activated:
+    description: A persona finished activating (fired for both a genuine swap and a same-store reconnect).
+    detail:
+      personaId:
+        type: string
+      reset:
+        type: boolean
+        description: True for a genuine store swap (conversation/surfaces/session reset); false for a same-store reconnect.
+  persona-imported:
+    description: An imported persona (from `<admin-roster-ui>`'s `persona-import`) was appended and activated.
+    detail:
+      persona:
+        type: object
+
+slots: {}
+
+states:
+  - name: idle
+    description: Default; one persona active, chat pane external-driven.
+
+traits: []
+
+tokens:
+  --agent-admin-roster-w:
+    description: Roster column width.
+    default: var(--a-space-12)
+  --agent-admin-settings-w:
+    description: Settings column width.
+    default: calc(var(--a-space-12) * 1.6)
+  --agent-admin-border:
+    description: Column divider border.
+    default: var(--a-border-subtle)
+
+a2ui:
+  rules:
+    - rule: |
+        Compose `<agent-admin-ui>` with bespoke `<admin-roster-ui>` +
+        `<admin-settings-ui>` + `<chat-shell>` children (chat-shell WITHOUT
+        `proxy-url` — external mode; this composite drives it). Set
+        `personas` as a JS property.
+      reason: Behavior-only orchestrator; the consumer authors the bespoke children.
+    - rule: |
+        Never bind `<chat-shell proxy-url>` inside `<agent-admin-ui>` — the
+        composite drives the chat pane itself via `wireAgentEvents`; a
+        `proxy-url` would double-drive turns.
+      reason: One transport per turn (CHAT-HARNESS law 1).
+
+anti_patterns:
+  - wrong: |
+      {"component": "AgentAdmin", "personas": [{"id": "a", "label": "A", "seedVersion": 1, "entries": []}]}
+    why: Renders nothing without its bespoke children — `<agent-admin-ui>` needs `<admin-roster-ui>` + `<admin-settings-ui>` + `<chat-shell>` authored inside it.
+    fix: |
+      <agent-admin-ui id="admin">
+        <admin-roster-ui></admin-roster-ui>
+        <admin-settings-ui></admin-settings-ui>
+        <chat-shell><chat-header></chat-header><chat-thread></chat-thread><chat-composer></chat-composer></chat-shell>
+      </agent-admin-ui>
+
+examples:
+  - name: composed-shell
+    description: Full agent-admin composition (JS-driven; `personas` with full Entry arrays isn't practically hand-authored as static a2ui JSON).
+    a2ui: |
+      [{"id": "admin", "component": "AgentAdmin", "children": [
+        {"id": "roster", "component": "AdminRoster"},
+        {"id": "settings", "component": "AdminSettings"},
+        {"id": "chat", "component": "ChatShell"}
+      ]}]
+
+keywords:
+  - admin
+  - agent
+  - persona
+  - roster
+  - settings
+  - chat
+  - store-swap
+
+synonyms:
+  admin:
+    - agent-admin
+    - persona-admin
+  persona:
+    - agent
+    - profile
+
+related:
+  - AdminRoster
+  - AdminSettings
+  - ChatShell

package/agent-admin/demo-seeds.js

@@ -0,0 +1,95 @@
+/**
+ * demo-seeds — the three personas `playgrounds/agent-admin` ships with.
+ *
+ * Shared between the playground (imported at a browser-absolute path) and
+ * `demo-seeds.test.js` (modality-neutral lint, CHAT-HARNESS law 4 — a
+ * persona's prose surfaces INTENT only, never dialect specifics: "A2UI",
+ * "envelope", component tag names like "chart-ui" are all disallowed).
+ */
+
+import { definePersona, seedEntries } from '@adia-ai/persona';
+
+export const supportPersona = definePersona({
+  id: 'support',
+  label: 'Support agent',
+  category: 'Customer',
+  seedVersion: 1,
+  entries: seedEntries([
+    {
+      id: 'identity',
+      kind: 'prompt-section',
+      label: 'Identity',
+      description: 'Who this agent is.',
+      content: 'You are a customer support agent for a software product. You help people solve problems with their account and their orders.',
+    },
+    {
+      id: 'tone',
+      kind: 'prompt-section',
+      label: 'Tone',
+      description: 'How this agent talks.',
+      content: 'Be concise, patient, and friendly. Confirm what the person needs before offering a fix.',
+    },
+    {
+      id: 'lookup-order',
+      kind: 'tool',
+      label: 'Look up an order',
+      description: 'Find an order by its confirmation number.',
+      content: 'Given a confirmation number, return the order status and its items.',
+    },
+  ]),
+});
+
+export const writerPersona = definePersona({
+  id: 'writer',
+  label: 'Writer',
+  category: 'Content',
+  seedVersion: 1,
+  entries: seedEntries([
+    {
+      id: 'identity',
+      kind: 'prompt-section',
+      label: 'Identity',
+      description: 'Who this agent is.',
+      content: 'You are a writing assistant. You help people draft, tighten, and proofread short pieces of text.',
+    },
+    {
+      id: 'style',
+      kind: 'prompt-section',
+      label: 'Style',
+      description: 'The house voice.',
+      content: 'Prefer short sentences and plain words. Avoid jargon unless the person uses it first.',
+    },
+    {
+      id: 'editing-checklist',
+      kind: 'skill',
+      label: 'Editing checklist',
+      description: 'A repeatable pass over a draft.',
+      content: 'Check for a clear opening line, one idea per paragraph, and a direct closing.',
+    },
+  ]),
+});
+
+export const researcherPersona = definePersona({
+  id: 'researcher',
+  label: 'Researcher',
+  category: 'Content',
+  seedVersion: 1,
+  entries: seedEntries([
+    {
+      id: 'identity',
+      kind: 'prompt-section',
+      label: 'Identity',
+      description: 'Who this agent is.',
+      content: 'You are a research assistant. You gather facts, summarize sources, and flag open questions.',
+    },
+    {
+      id: 'method',
+      kind: 'workflow',
+      label: 'Research method',
+      description: 'How this agent works through a question.',
+      content: 'Break the question into parts, look for a source for each part, then summarize what is and is not settled.',
+    },
+  ]),
+});
+
+export const DEMO_PERSONAS = [supportPersona, writerPersona, researcherPersona];

package/agent-admin/index.js

@@ -0,0 +1,13 @@
+/**
+ * @adia-ai/web-modules/agent-admin — cluster barrel.
+ *
+ * L4 admin composite family (CHAT-HARNESS.md §Components row L4, gh#600 /
+ * WCH-5) over `@adia-ai/persona`'s L2 store contract: `<admin-roster-ui>`
+ * (persona switch, exactly-one-active), `<admin-settings-ui>` (settings
+ * pane over one bound store), `<agent-admin-ui>` (the composition —
+ * roster + settings + a chat pane, store-swap law, transport-blind).
+ */
+export { UIAdminRoster } from './admin-roster/admin-roster.js';
+export { UIAdminSettings } from './admin-settings/admin-settings.js';
+export { UIAgentAdmin } from './agent-admin/agent-admin.js';
+export { readLivePersona, entryStoreKey } from './live-persona.js';

package/agent-admin/live-persona.js

@@ -0,0 +1,53 @@
+/**
+ * live-persona — the L4 fresh-read overlay (CHAT-HARNESS law 7: "Live-apply
+ * is by fresh read at turn time — no propagation channel").
+ *
+ * `admin-settings-ui` writes edits straight through a per-persona
+ * `SettingsStore` (`@adia-ai/persona`'s `personaStore`) — it never mutates
+ * the `Persona` object in memory. `readLivePersona` is the ONE place that
+ * re-reads the store and overlays it onto the base persona's entries; the
+ * agent-admin composition calls it fresh, immediately before every
+ * `compilePersona()`, so the very next turn always compiles whatever is
+ * currently in the store — there is no cache, no subscription forwarding
+ * content into a second copy of the persona.
+ *
+ * Key convention MIRRORS `@adia-ai/persona`'s `store.ts` (`entry.<id>.<field>`
+ * for `enabled` / `order`) — store.ts doesn't export that helper, so it's
+ * kept in lock-step here by hand. `content` is a THIRD field this module
+ * owns (persona/store.ts never seeds or reads it) — entry authoring
+ * (M-scope 2) persists edited prompt-section/skill/etc. text under the
+ * same `entry.<id>.content` key.
+ */
+
+/** @param {string} entryId @param {'enabled'|'order'|'content'} field */
+export function entryStoreKey(entryId, field) {
+  return `entry.${entryId}.${field}`;
+}
+
+/**
+ * Overlay `store`'s current values onto `persona.entries`, entry by entry.
+ * A field the store has never seen falls back to the persona's own seed
+ * value — same precedence `personaStore` documents for enabled/order.
+ * Never mutates `persona`; always returns a fresh object + fresh entries
+ * array so callers can't accidentally hold a stale reference across turns.
+ *
+ * @param {import('@adia-ai/persona').Persona} persona
+ * @param {import('@adia-ai/persona').SettingsStore} store
+ * @returns {import('@adia-ai/persona').Persona}
+ */
+export function readLivePersona(persona, store) {
+  if (!persona) return persona;
+  if (!store) return persona;
+  const entries = persona.entries.map((entry) => {
+    const enabled = store.get(entryStoreKey(entry.id, 'enabled'));
+    const order = store.get(entryStoreKey(entry.id, 'order'));
+    const content = store.get(entryStoreKey(entry.id, 'content'));
+    return {
+      ...entry,
+      enabled: typeof enabled === 'boolean' ? enabled : entry.enabled,
+      order: typeof order === 'number' ? order : entry.order,
+      content: typeof content === 'string' ? content : entry.content,
+    };
+  });
+  return { ...persona, entries };
+}

package/chat/chat-surfaces/chat-surfaces.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The L3 surface-host registry over genui-system `attachSurface`
+ * (CHAT-HARNESS.md §Interfaces 4).
+ */
+
+/** Renderer seam — only the subset of `@genui/renderer`'s `Renderer` this
+ *  module calls. The real `Renderer` type satisfies this structurally. */
+export interface SurfaceRegistryRenderer {
+  handleFrame(raw: string): void;
+  readonly surfaces: ReadonlyMap<string, unknown>;
+  attachSurface(surfaceId: string, root: Element): { detach(): void; [key: string]: unknown };
+}
+
+export interface SurfaceHost {
+  surfaceId: string;
+  root: Element;
+  handle: { detach(): void; [key: string]: unknown };
+  bubbleEl: Element;
+  status: 'open' | 'closed';
+}
+
+export interface SurfaceRegistry {
+  /** Fresh id ⇒ mount into `turnBubbleEl`; known id ⇒ return the original host. */
+  route(surfaceId: string, turnBubbleEl: Element): SurfaceHost;
+  /** Protocol-level delete + non-removable "Closed." annotation. Idempotent. */
+  close(surfaceId: string): SurfaceHost | undefined;
+  /** Apply one wire envelope line for `surfaceId`, routing/closing as needed. */
+  feed(surfaceId: string, line: string, turnBubbleEl: Element | null): SurfaceHost | undefined;
+  get(surfaceId: string): SurfaceHost | undefined;
+  disposeAll(): void;
+  readonly hosts: ReadonlyMap<string, SurfaceHost>;
+}
+
+export function createSurfaceRegistry(opts: {
+  renderer: SurfaceRegistryRenderer;
+  doc?: Document;
+}): SurfaceRegistry;
+
+/** CHAT-HARNESS law 3 — code-owned progress labels, never model text. */
+export const PROGRESS_LABELS: Record<string, string>;
+
+export function wireAgentEvents(
+  chatShell: Element & {
+    appendChunk?(text: string): void;
+    appendMessage?(msg: { role: string; content?: string; render?: boolean }): Element;
+    startStreaming?(): void;
+    stopStreaming?(): void;
+    streaming?: boolean;
+  },
+  registry: SurfaceRegistry,
+  opts: {
+    events: AsyncIterable<{ type: string; [key: string]: unknown }>;
+    statusEl?: { textContent: string } | null;
+    isProgressStage?: (stage: unknown) => boolean;
+  },
+): Promise<void>;

package/chat/chat-surfaces/chat-surfaces.js

@@ -0,0 +1,242 @@
+/**
+ * chat-surfaces — the L3 surface-host registry over genui-system
+ * `attachSurface` (CHAT-HARNESS.md §Interfaces 4, gh#599 / WCH-4).
+ *
+ * `<chat-thread>` bookkeeping: `Map<surfaceId, host>`.
+ *   - A FRESH surfaceId mounts a new host inline in the CREATING turn's
+ *     bubble (the `chatShell.appendMessage()` element passed in as
+ *     `turnBubbleEl`).
+ *   - A KNOWN surfaceId (open OR closed) always routes back to that
+ *     ORIGINAL host — persistent surface identity across turns. A later
+ *     turn that updates surface S renders into S's original bubble, it
+ *     never mounts a second one.
+ *   - `close(surfaceId)` is a PROTOCOL-level delete (a real `deleteSurface`
+ *     envelope through the renderer — the same path a server-sent delete
+ *     rides, `SurfaceStore#deleteSurface`, idempotent) plus a visible,
+ *     NON-REMOVABLE "Closed." annotation appended to the original bubble.
+ *     History is never silently erased — the annotation stays even if the
+ *     bubble is re-rendered around it (callers must APPEND, never replace).
+ *
+ * Dependency-injected renderer (CHAT-HARNESS law 1 — one-method transport,
+ * packaged seam undefined): this module never imports `@genui/renderer`
+ * itself. `@genui/*` are private, unpublished workspace packages — a real
+ * `@adia-ai/web-modules` npm consumer could never resolve a bare `@genui/…`
+ * specifier. The HOST (a demo page, a consumer app) builds the renderer
+ * (`createRenderer` + its own `WidgetAdapter`) and hands it in; this module
+ * only ever calls the five methods `Renderer` exposes.
+ */
+
+const CLOSED_ANNOTATION_TEXT = 'Closed.';
+const PROTOCOL_VERSION = 'v1.0';
+
+/**
+ * @param {object} opts
+ * @param {{handleFrame(raw: string): void, surfaces: ReadonlyMap<string, unknown>, attachSurface(surfaceId: string, root: Element): {detach(): void}}} opts.renderer
+ * @param {Document} [opts.doc]
+ */
+export function createSurfaceRegistry({ renderer, doc = document }) {
+  if (!renderer) throw new Error('createSurfaceRegistry: opts.renderer is required');
+
+  /** @type {Map<string, {surfaceId: string, root: Element, handle: object, bubbleEl: Element, status: 'open'|'closed'}>} */
+  const hosts = new Map();
+
+  /**
+   * Fresh id ⇒ mount a new host into `turnBubbleEl`. Known id (open or
+   * closed) ⇒ return the ORIGINAL host untouched — never re-mounts, never
+   * moves to a different bubble.
+   */
+  function route(surfaceId, turnBubbleEl) {
+    const existing = hosts.get(surfaceId);
+    if (existing) return existing;
+
+    if (!turnBubbleEl) {
+      throw new Error(`createSurfaceRegistry.route: no bubble element for fresh surfaceId "${surfaceId}"`);
+    }
+
+    // Island posture: the root is the ONLY thing this registry adds to the
+    // bubble — no class/style/chrome on the bubble itself.
+    const root = doc.createElement('div');
+    root.setAttribute('data-surface-root', surfaceId);
+    turnBubbleEl.appendChild(root);
+
+    const handle = renderer.attachSurface(surfaceId, root);
+    const host = { surfaceId, root, handle, bubbleEl: turnBubbleEl, status: 'open' };
+    hosts.set(surfaceId, host);
+    return host;
+  }
+
+  function annotateClosed(host) {
+    const note = doc.createElement('div');
+    note.setAttribute('data-surface-closed', host.surfaceId);
+    // No removal affordance is ever wired to this element — it is
+    // permanent, visible history (CHAT-HARNESS §Interfaces 4).
+    note.textContent = CLOSED_ANNOTATION_TEXT;
+    host.bubbleEl.appendChild(note);
+  }
+
+  /**
+   * Protocol-level delete: rides `deleteSurface` through the renderer
+   * (idempotent — deleting an already-closed or unknown id is a no-op on
+   * the renderer side), marks the host closed, and appends the Closed
+   * annotation. Returns the host record (or undefined for an id this
+   * registry never routed).
+   */
+  function close(surfaceId) {
+    const host = hosts.get(surfaceId);
+    if (!host) return undefined;
+    if (host.status === 'closed') return host;
+
+    renderer.handleFrame(JSON.stringify({
+      version: PROTOCOL_VERSION,
+      deleteSurface: { surfaceId },
+    }));
+    host.status = 'closed';
+    annotateClosed(host);
+    return host;
+  }
+
+  /**
+   * Feed one 'surface' AgentEvent line for `surfaceId` into the renderer,
+   * routing/mounting/closing as needed. `line` is one raw wire envelope
+   * (createSurface / updateComponents / updateDataModel / deleteSurface).
+   *
+   *   - `deleteSurface` line ⇒ apply it, then close() bookkeeping (no
+   *     second envelope is sent — the line already IS the delete).
+   *   - anything else ⇒ apply it, then route() if the surface came up
+   *     live. A fresh id whose createSurface line failed validation never
+   *     becomes live in `renderer.surfaces`, so nothing is mounted for it.
+   */
+  function feed(surfaceId, line, turnBubbleEl) {
+    let envelope = null;
+    try {
+      envelope = JSON.parse(line);
+    } catch {
+      // Malformed line — let the renderer's own diagnostic path handle it.
+    }
+
+    if (envelope && Object.hasOwn(envelope, 'deleteSurface')) {
+      renderer.handleFrame(line);
+      const host = hosts.get(surfaceId);
+      if (host && host.status !== 'closed') {
+        host.status = 'closed';
+        annotateClosed(host);
+      }
+      return host;
+    }
+
+    renderer.handleFrame(line);
+    if (renderer.surfaces.has(surfaceId)) {
+      return route(surfaceId, turnBubbleEl);
+    }
+    return hosts.get(surfaceId);
+  }
+
+  function get(surfaceId) {
+    return hosts.get(surfaceId);
+  }
+
+  /** Page/component teardown — detaches every open host's rendering from
+   *  its Root (island cleanup) without sending any protocol delete; this
+   *  is NOT the same operation as `close()` and leaves no annotation. */
+  function disposeAll() {
+    for (const host of hosts.values()) {
+      host.handle.detach();
+    }
+    hosts.clear();
+  }
+
+  return { route, close, feed, get, disposeAll, hosts };
+}
+
+/** CHAT-HARNESS law 3 — labels rendered from a CODE-OWNED table, never
+ *  model text. Keyed on `@adia-ai/agent`'s closed `ProgressStage` vocabulary
+ *  (`PROGRESS_STAGES`); a stage this table has no entry for renders nothing
+ *  rather than a raw enum value. */
+export const PROGRESS_LABELS = {
+  sent: 'Sending…',
+  started: 'Thinking…',
+  reasoning: 'Reasoning…',
+  content: 'Writing…',
+  validating: 'Validating…',
+  retry: 'Retrying…',
+  tool: 'Using a tool…',
+  done: 'Done',
+};
+
+/**
+ * Consumes ONE `AsyncIterable<AgentEvent>` for the turn already opened on
+ * `chatShell` (the caller has already appended the user message and an
+ * empty assistant draft, and called `chatShell.startStreaming()` — mirrors
+ * `playgrounds/agent-chat`'s existing submit handler). Transport-blind
+ * (CHAT-HARNESS law 1): this function never fetches, never opens a
+ * socket — it only folds the event stream it's handed.
+ *
+ * @param {import('../chat-shell/chat-shell.js').ChatShell} chatShell
+ * @param {ReturnType<typeof createSurfaceRegistry>} registry
+ * @param {object} opts
+ * @param {AsyncIterable<object>} opts.events — the AgentEvent stream
+ * @param {{textContent: string}} [opts.statusEl] — rendered from PROGRESS_LABELS
+ * @param {(stage: unknown) => boolean} [opts.isProgressStage] — closed-vocabulary
+ *   guard; defaults to accepting any key PROGRESS_LABELS has (out-of-vocab drop).
+ */
+export async function wireAgentEvents(chatShell, registry, opts) {
+  const { events, statusEl = null, isProgressStage = (s) => Object.hasOwn(PROGRESS_LABELS, s) } = opts ?? {};
+  if (!events) throw new Error('wireAgentEvents: opts.events (AsyncIterable<AgentEvent>) is required');
+
+  const currentBubble = () => {
+    const thread = chatShell.querySelector?.('chat-thread');
+    return thread?.querySelector('[data-role="assistant"]:last-child [data-bubble]') ?? null;
+  };
+
+  for await (const event of events) {
+    switch (event.type) {
+      case 'text':
+        chatShell.appendChunk?.(event.text);
+        break;
+
+      case 'progress': {
+        if (!isProgressStage(event.stage)) break; // closed-vocab drop (law 3)
+        if (statusEl) statusEl.textContent = PROGRESS_LABELS[event.stage] ?? '';
+        break;
+      }
+
+      case 'surface': {
+        const bubble = currentBubble();
+        registry.feed(event.surfaceId, event.line, bubble);
+        break;
+      }
+
+      case 'tool_use':
+        chatShell.appendMessage?.({
+          role: 'assistant',
+          content: `🔧 \`${event.name}(${JSON.stringify(event.input)})\``,
+          render: true,
+        });
+        chatShell.appendMessage?.({ role: 'assistant', content: '' });
+        break;
+
+      case 'tool_result':
+        chatShell.appendMessage?.({
+          role: event.isError ? 'error' : 'assistant',
+          content: `↩ \`${event.name}\` → ${String(event.output).slice(0, 300)}`,
+          render: true,
+        });
+        chatShell.appendMessage?.({ role: 'assistant', content: '' });
+        break;
+
+      case 'error':
+        chatShell.appendMessage?.({ role: 'error', content: event.error?.message ?? String(event.error) });
+        chatShell.stopStreaming?.();
+        break;
+
+      case 'done':
+        chatShell.stopStreaming?.();
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  if (chatShell.streaming) chatShell.stopStreaming?.();
+}

package/chat/index.js

@@ -2,3 +2,4 @@ export { ChatShell } from './chat-shell/chat-shell.js';
 export { ChatThread } from './chat-thread/chat-thread.js';
 export { ChatComposer } from './chat-composer/chat-composer.js';
 export { ChatSidebar } from './chat-sidebar/chat-sidebar.js';
+export { createSurfaceRegistry, wireAgentEvents, PROGRESS_LABELS } from './chat-surfaces/chat-surfaces.js';