canopy-ui 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-ui",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "repository": {
     "type": "git",

package/src/chat/agui.fixture.json

@@ -0,0 +1,235 @@
+[
+  {
+    "canopy": {
+      "event": "chat.stream_start",
+      "data": {
+        "message_id": "m1",
+        "turn_index": 4
+      }
+    },
+    "agui": [
+      {
+        "metadata": {
+          "canopy": {
+            "turn_index": 4
+          }
+        },
+        "type": "TEXT_MESSAGE_START",
+        "messageId": "m1",
+        "role": "assistant"
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "chat.delta",
+      "data": {
+        "message_id": "m1",
+        "text": "hello"
+      }
+    },
+    "agui": [
+      {
+        "type": "TEXT_MESSAGE_CONTENT",
+        "messageId": "m1",
+        "delta": "hello"
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "chat.stream_complete",
+      "data": {
+        "message_id": "m1",
+        "plaintext": "hello"
+      }
+    },
+    "agui": [
+      {
+        "metadata": {
+          "canopy": {
+            "plaintext": "hello"
+          }
+        },
+        "type": "TEXT_MESSAGE_END",
+        "messageId": "m1"
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "chat.user_message",
+      "data": {
+        "message_id": "u1",
+        "turn_index": 3,
+        "plaintext": "hi there"
+      }
+    },
+    "agui": [
+      {
+        "metadata": {
+          "canopy": {
+            "turn_index": 3
+          }
+        },
+        "type": "TEXT_MESSAGE_CHUNK",
+        "messageId": "u1",
+        "role": "user",
+        "delta": "hi there"
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "chat.tool_use",
+      "data": {
+        "tool_message_id": "t9",
+        "parent_message_id": "m1",
+        "turn_index": 5,
+        "block": {
+          "name": "list_insights",
+          "input": {
+            "limit": 5
+          }
+        }
+      }
+    },
+    "agui": [
+      {
+        "metadata": {
+          "canopy": {
+            "turn_index": 5,
+            "block": {
+              "name": "list_insights",
+              "input": {
+                "limit": 5
+              }
+            }
+          }
+        },
+        "type": "TOOL_CALL_START",
+        "toolCallId": "t9",
+        "toolCallName": "list_insights",
+        "parentMessageId": "m1"
+      },
+      {
+        "type": "TOOL_CALL_ARGS",
+        "toolCallId": "t9",
+        "delta": "{\"limit\": 5}"
+      },
+      {
+        "type": "TOOL_CALL_END",
+        "toolCallId": "t9"
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "chat.tool_result",
+      "data": {
+        "tool_message_id": "t9",
+        "parent_message_id": "m1",
+        "turn_index": 6,
+        "block": {
+          "type": "tool_result",
+          "tool_use_id": "toolu_01ABC",
+          "content": "[]"
+        }
+      }
+    },
+    "agui": [
+      {
+        "metadata": {
+          "canopy": {
+            "turn_index": 6,
+            "parent_message_id": "m1",
+            "block": {
+              "type": "tool_result",
+              "tool_use_id": "toolu_01ABC",
+              "content": "[]"
+            }
+          }
+        },
+        "type": "TOOL_CALL_RESULT",
+        "messageId": "t9",
+        "toolCallId": "t9",
+        "content": "[]"
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "session.title_updated",
+      "data": {
+        "title": "Insights triage"
+      }
+    },
+    "agui": [
+      {
+        "type": "STATE_DELTA",
+        "delta": [
+          {
+            "op": "replace",
+            "path": "/title",
+            "value": "Insights triage"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "draft.updated",
+      "data": {
+        "id": "d1",
+        "body": "x",
+        "version": 2
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.draft.updated",
+        "value": {
+          "id": "d1",
+          "body": "x",
+          "version": 2
+        }
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "presence.joined",
+      "data": {
+        "user_id": 7
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.presence.joined",
+        "value": {
+          "user_id": 7
+        }
+      }
+    ]
+  },
+  {
+    "canopy": {
+      "event": "presence.left",
+      "data": {
+        "user_id": 7
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.presence.left",
+        "value": {
+          "user_id": 7
+        }
+      }
+    ]
+  }
+]

package/src/chat/agui.test.ts

@@ -0,0 +1,298 @@
+import { readFileSync } from 'node:fs'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import fixture from './agui.fixture.json'
+import { fromAgui, resetAguiState } from './agui'
+import { sessionReducer } from './sessionReducer'
+import type { SessionState, WsEvent } from './protocol'
+
+/** The hook's own source. Read from disk rather than imported, because what is
+ *  being checked is that the WIRING exists — which no behavioural test of a
+ *  pure module can see. */
+function hookSource(): string {
+  return readFileSync(new URL('./useSessionSocket.ts', import.meta.url), 'utf8')
+}
+
+/**
+ * The inverse projection, checked against the forward one.
+ *
+ * `agui.fixture.json` is GENERATED by `apps/canopy_sessions/agui.py` and a
+ * Python test asserts it is current. So the round trip is proved across two
+ * languages with a shared artifact — which is the only thing that can catch the
+ * projection and its inverse drifting apart, since neither codebase can see the
+ * other.
+ */
+
+beforeEach(() => resetAguiState())
+
+type FixtureEntry = { canopy: WsEvent; agui: Array<Record<string, unknown>> }
+const entries = fixture as unknown as FixtureEntry[]
+
+/** Replay a fixture entry's AG-UI events through the inverse. */
+function roundTrip(entry: FixtureEntry): WsEvent[] {
+  return entry.agui.flatMap((event) => fromAgui(event))
+}
+
+describe('the round trip, against the server’s own output', () => {
+  it('covers a real conversation, not just the easy frames', () => {
+    // A fixture of two trivial events would pass forever while proving nothing
+    // about a streamed reply or a tool call.
+    const covered = new Set(entries.map((e) => e.canopy.event))
+    expect(covered).toContain('chat.stream_start')
+    expect(covered).toContain('chat.tool_use')
+    expect(covered).toContain('chat.tool_result')
+    expect(entries.length).toBeGreaterThanOrEqual(10)
+  })
+
+  it.each(entries.map((e) => [e.canopy.event, e] as const))(
+    'recovers the original canopy frame for %s',
+    (_name, entry) => {
+      expect(roundTrip(entry)).toEqual([entry.canopy])
+    },
+  )
+})
+
+describe('the reducer cannot tell which protocol it was fed', () => {
+  /** The property that actually matters: a client reading AG-UI must end up in
+   *  exactly the state a client reading canopy's own frames ends up in. Field
+   *  equality per frame is necessary but not sufficient — ordering and the
+   *  reducer's own dedupe are where a subtle difference would show. */
+  function reduceAll(frames: WsEvent[]): SessionState {
+    const initial: SessionState = {
+      messages: [],
+      active_draft: null,
+      participants: [],
+      presence_user_ids: [],
+      current_user_id: 0,
+    }
+    return frames.reduce(sessionReducer, initial)
+  }
+
+  it('reaches identical state via canopy frames and via AG-UI', () => {
+    // Time is frozen because the reducer stamps `created_at`/`started_at` with
+    // the wall clock as it runs, so two reductions a millisecond apart differ
+    // in a field that has nothing to do with the protocol. Without this the
+    // test fails intermittently for a reason that would send the next reader
+    // hunting a mapping bug that is not there.
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-09-15T12:00:00Z'))
+    try {
+      const direct = entries.map((e) => e.canopy)
+      const viaAgui = entries.flatMap(roundTrip)
+
+      expect(reduceAll(viaAgui)).toEqual(reduceAll(direct))
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('and that state is not vacuously empty', () => {
+    // Guard: if the fixture stopped producing messages this test would pass
+    // while comparing nothing to nothing.
+    expect(reduceAll(entries.map((e) => e.canopy)).messages.length).toBeGreaterThan(0)
+  })
+})
+
+describe('a tool call spans three events, so it is assembled not truncated', () => {
+  it('emits nothing until the arguments arrive', () => {
+    // canopy carries a tool's input on one frame; AG-UI streams it on the ARGS
+    // event that follows. Emitting on START would render a tool row with no
+    // input — the half-empty tool call the ACP notes warn about.
+    const start = fromAgui({
+      type: 'TOOL_CALL_START',
+      toolCallId: 't1',
+      toolCallName: 'list_insights',
+    })
+
+    expect(start).toEqual([])
+  })
+
+  it('restores the runner’s own block verbatim', () => {
+    // canopy passes the block straight through from the transcript and never
+    // interprets it, so its shape belongs to the PRODUCER — Anthropic's on the
+    // laptop, the cloud runner's over ACP. Rebuilding one from the AG-UI fields
+    // would invent an `id` and a `type` that the real payload may not have had,
+    // and hand the renderer something no runner ever sent.
+    const block = { type: 'tool_use', id: 'toolu_01ABC', name: 'list_insights', input: { limit: 5 } }
+    fromAgui({
+      type: 'TOOL_CALL_START',
+      toolCallId: 't1',
+      toolCallName: 'list_insights',
+      parentMessageId: 'm1',
+      metadata: { canopy: { turn_index: 5, block } },
+    })
+
+    const [frame] = fromAgui({ type: 'TOOL_CALL_ARGS', toolCallId: 't1', delta: '{"limit":5}' })
+
+    expect(frame).toEqual({
+      event: 'chat.tool_use',
+      data: {
+        parent_message_id: 'm1',
+        tool_message_id: 't1',
+        turn_index: 5,
+        block,
+      },
+    })
+  })
+
+  it('falls back to the protocol’s own fields for a non-canopy producer', () => {
+    // An AG-UI stream from something that is not canopy carries no block. The
+    // row is still renderable from name + arguments, which is the minimum the
+    // protocol guarantees — better than dropping the call entirely.
+    fromAgui({ type: 'TOOL_CALL_START', toolCallId: 't1', toolCallName: 'search' })
+    const [frame] = fromAgui({ type: 'TOOL_CALL_ARGS', toolCallId: 't1', delta: '{"q":"x"}' })
+
+    expect((frame.data as unknown as { block: unknown }).block).toEqual({ name: 'search', input: { q: 'x' } })
+  })
+
+  it('ignores arguments for a call it never saw start', () => {
+    // A reconnect mid-call, or a stream that began before this client attached.
+    expect(fromAgui({ type: 'TOOL_CALL_ARGS', toolCallId: 'unknown', delta: '{}' })).toEqual([])
+  })
+
+  it('does not carry a half-read call across a reconnect', () => {
+    fromAgui({ type: 'TOOL_CALL_START', toolCallId: 't1', toolCallName: 'x' })
+    resetAguiState()
+
+    expect(fromAgui({ type: 'TOOL_CALL_ARGS', toolCallId: 't1', delta: '{}' })).toEqual([])
+  })
+
+  it('survives malformed arguments with an empty input rather than no row', () => {
+    fromAgui({ type: 'TOOL_CALL_START', toolCallId: 't1', toolCallName: 'x' })
+    const [frame] = fromAgui({ type: 'TOOL_CALL_ARGS', toolCallId: 't1', delta: 'not json' })
+
+    expect((frame.data as unknown as { block: { input: unknown } }).block.input).toEqual({})
+  })
+})
+
+describe('the blocked agent survives the trip', () => {
+  const INTERRUPT = {
+    type: 'RUN_FINISHED',
+    threadId: 't1',
+    runId: 'r1',
+    outcome: {
+      type: 'interrupt',
+      interrupts: [
+        {
+          id: 'i1',
+          reason: 'transcript',
+          message: 'Phase gate',
+          expiresAt: '2026-09-15T10:00:00+00:00',
+          metadata: {
+            canopy: {
+              body: 'Phase 4 is test-gated.',
+              questions: [
+                {
+                  index: 0,
+                  question: 'Proceed?',
+                  multi_select: false,
+                  options: [{ number: 1, label: 'Yes' }],
+                },
+              ],
+            },
+          },
+        },
+      ],
+    },
+  }
+
+  it('becomes a canopy menu a client can render', () => {
+    const [frame] = fromAgui(INTERRUPT)
+    const menu = (frame.data as unknown as { menu: Record<string, unknown> }).menu
+
+    expect(frame.event).toBe('session.menu')
+    expect(menu.question).toBe('Proceed?')
+    // The body is often the only thing that makes a dialog answerable away from
+    // the keyboard: "Do you want to proceed?" says nothing without it.
+    expect(menu.body).toBe('Phase 4 is test-gated.')
+  })
+
+  it('keeps every question, not only the first', () => {
+    // The TUI draws them as tabs and will not submit until each has an answer,
+    // so a client showing one cannot complete the ask however it is pressed.
+    const [frame] = fromAgui(INTERRUPT)
+    const menu = (frame.data as unknown as { menu: { questions: unknown[] } }).menu
+
+    expect(menu.questions).toHaveLength(1)
+  })
+
+  it('carries the staleness back as observed_at', () => {
+    const [frame] = fromAgui(INTERRUPT)
+    const menu = (frame.data as unknown as { menu: { observed_at: number } }).menu
+
+    expect(menu.observed_at).toBe(Date.parse('2026-09-15T10:00:00+00:00') / 1000)
+  })
+
+  it('retracts a menu when someone answered at the keyboard', () => {
+    const [frame] = fromAgui({ type: 'CUSTOM', name: 'canopy.menu.retracted', value: {} })
+
+    expect(frame).toEqual({ event: 'session.menu', data: { menu: null } })
+  })
+})
+
+describe('stopping is not erroring', () => {
+  it('reads a cancelled run as a cancelled stream', () => {
+    const [frame] = fromAgui({
+      type: 'RUN_FINISHED',
+      threadId: 't1',
+      runId: 'r1',
+      result: { cancelled: true, partial_len: 12 },
+    })
+
+    expect(frame.event).toBe('chat.stream_cancelled')
+  })
+
+  it('reads a plain finish as nothing at all', () => {
+    // canopy has no frame for "the run ended cleanly" — the stream_complete
+    // already said so. Inventing one would double-count the turn.
+    expect(fromAgui({ type: 'RUN_FINISHED', threadId: 't1', runId: 'r1' })).toEqual([])
+  })
+})
+
+describe('an unknown event cannot break a client', () => {
+  it('ignores an event type this version has never heard of', () => {
+    // AG-UI is 0.x and gains event types. A client that throws on one it does
+    // not know is a client that breaks on the protocol improving.
+    expect(fromAgui({ type: 'SOMETHING_NEW_IN_1_0', foo: 1 })).toEqual([])
+  })
+
+  it('ignores a CUSTOM event from someone else’s namespace', () => {
+    expect(fromAgui({ type: 'CUSTOM', name: 'vendor.thing', value: {} })).toEqual([])
+  })
+
+  it.each([{}, { type: null }, { type: 'TEXT_MESSAGE_CONTENT' }])(
+    'does not throw on malformed input %#',
+    (frame) => {
+      expect(() => fromAgui(frame as Record<string, unknown>)).not.toThrow()
+    },
+  )
+})
+
+describe('the socket actually asks for it', () => {
+  /** A pure module nothing calls is a design document with a test suite — the
+   *  mistake `apps/mcp/page_tools.py` made expensive once. These assert the
+   *  option reaches the URL and the message handler, not just that the mapping
+   *  is correct in isolation. */
+  it('is wired to the hook’s public option', () => {
+    const source = hookSource()
+
+    expect(source).toContain('protocol=ag-ui')
+    expect(source).toContain('fromAgui')
+    // And the default stays canopy's own vocabulary, which is what lets an
+    // existing consumer — ace-web installs this package from npm — notice
+    // nothing at all.
+    expect(source).toContain('protocol = "canopy"')
+  })
+
+  it('clears half-read state when it opens a connection', () => {
+    // Tool-call ids are per-stream, so an ARGS event from a new connection must
+    // not complete a call the previous one left open. The BEHAVIOUR is tested
+    // directly above ("does not carry a half-read call across a reconnect");
+    // what is checked here is that `connect` actually calls it, which no
+    // behavioural test of the pure module can see.
+    const connectBody = hookSource().slice(hookSource().indexOf('const connect ='))
+
+    expect(connectBody).toContain('resetAguiState()')
+  })
+})

package/src/chat/agui.ts

@@ -0,0 +1,282 @@
+/**
+ * AG-UI events, read back into canopy's own session frames.
+ *
+ * The inverse of `apps/canopy_sessions/agui.py`. The server projects canopy →
+ * AG-UI; this reads AG-UI → canopy, so `sessionReducer` never learns a second
+ * vocabulary and every existing surface keeps working unchanged.
+ *
+ * **Why an inverse rather than a second reducer.** Teaching the reducer AG-UI
+ * directly would mean two code paths producing the same `SessionState`, and
+ * they would diverge — the multiplayer cases especially, which AG-UI does not
+ * model and which only canopy's path exercises. One reducer with a translator
+ * in front of it has a single behaviour to test.
+ *
+ * **The round trip is proved, not assumed.** `agui.fixture.json` is generated
+ * by the Python projection; a Python test asserts it is current and the test
+ * beside this one asserts this module recovers the original canopy frame from
+ * it. The projection and its inverse live in different languages, so a shared
+ * artifact is the only thing that can catch them drifting apart.
+ *
+ * **Lossless via `metadata`.** AG-UI has no slot for canopy's transcript
+ * ordinal (`turn_index`) or for the settled text of a whole message
+ * (`plaintext`), and the reducer needs both — one to sort a live row into the
+ * position it will occupy after a reload, the other to tell a web send from the
+ * echo of the same text arriving from the runner. They ride `metadata.canopy`,
+ * which is the extension point AG-UI reserves ("Every other key is user
+ * space"). Without them the projection would be a downgrade dressed as a
+ * standard.
+ */
+
+import type { SessionMenu, WsEvent } from "./protocol";
+
+/** Where canopy's own fields ride. Mirrors `agui.METADATA_KEY`. */
+export const METADATA_KEY = "canopy";
+
+/** Prefix on canopy's `CUSTOM` events. Mirrors `agui.CUSTOM_PREFIX`. */
+export const CUSTOM_PREFIX = "canopy.";
+
+/** An AG-UI event as it arrives on the wire: camelCase, unknown shape. */
+type AguiFrame = Record<string, unknown>;
+
+function meta(frame: AguiFrame): Record<string, unknown> {
+  const m = frame.metadata as Record<string, unknown> | undefined;
+  const mine = m?.[METADATA_KEY] as Record<string, unknown> | undefined;
+  return mine ?? {};
+}
+
+function str(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function num(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+/**
+ * One AG-UI event → zero or more canopy frames.
+ *
+ * Zero is a real answer, twice over. Some AG-UI events have no canopy meaning
+ * (`RUN_STARTED` duplicates an activity frame canopy already sent); and an
+ * unknown event returns zero rather than throwing, because a protocol that
+ * gains an event type must not be able to break a client that has not been
+ * updated yet — which, for a 0.x protocol, is a matter of when rather than if.
+ */
+export function fromAgui(frame: AguiFrame): WsEvent[] {
+  const type = typeof frame.type === "string" ? frame.type : "";
+  const m = meta(frame);
+
+  switch (type) {
+    case "TEXT_MESSAGE_START":
+      return [
+        {
+          event: "chat.stream_start",
+          data: { message_id: str(frame.messageId), turn_index: num(m.turn_index) },
+        },
+      ];
+
+    case "TEXT_MESSAGE_CONTENT":
+      return [
+        {
+          event: "chat.delta",
+          data: { message_id: str(frame.messageId), text: str(frame.delta) },
+        },
+      ];
+
+    case "TEXT_MESSAGE_END":
+      return [
+        {
+          event: "chat.stream_complete",
+          data: { message_id: str(frame.messageId), plaintext: str(m.plaintext) },
+        },
+      ];
+
+    case "TEXT_MESSAGE_CHUNK":
+      // Only the USER variant is canopy's `chat.user_message` — a human typing
+      // into emdash rather than into this page. An assistant chunk would be a
+      // whole reply arriving at once, which canopy's runner does not produce;
+      // mapping it to `stream_complete` with no preceding `stream_start` would
+      // hand the reducer a completion for a message it never opened.
+      if (str(frame.role) !== "user") return [];
+      return [
+        {
+          event: "chat.user_message",
+          data: {
+            message_id: str(frame.messageId),
+            turn_index: num(m.turn_index),
+            plaintext: str(frame.delta),
+          },
+        },
+      ];
+
+    case "TOOL_CALL_START":
+      // canopy carries the tool's payload on one frame; AG-UI streams the
+      // arguments on the ARGS event that follows. So nothing is emitted until
+      // ARGS arrives — a row rendered on START would have no input, which is
+      // the half-empty-tool-call bug the ACP notes warn about.
+      pendingCalls.set(str(frame.toolCallId), {
+        name: str(frame.toolCallName),
+        parentMessageId: str(frame.parentMessageId),
+        turnIndex: num(m.turn_index),
+        block: m.block as Record<string, unknown> | undefined,
+      });
+      return [];
+
+    case "TOOL_CALL_ARGS": {
+      const id = str(frame.toolCallId);
+      const pending = pendingCalls.get(id);
+      if (!pending) return [];
+      let input: unknown = {};
+      try {
+        input = JSON.parse(str(frame.delta) || "{}");
+      } catch {
+        // A fragment that is not valid JSON on its own is legal in AG-UI. The
+        // server sends arguments whole, so this means genuinely malformed
+        // input, and an empty object is a better row than a dropped one.
+        input = {};
+      }
+      // The runner's own payload where we have it, verbatim. canopy passes the
+      // block straight through from the transcript and never interprets it, so
+      // its shape belongs to the PRODUCER — reconstructing one from the AG-UI
+      // fields would invent a `type` and an `id` the real payload may not have
+      // carried, and hand the renderer something no runner ever sent.
+      const block = pending.block ?? { name: pending.name, input };
+      return [
+        {
+          event: "chat.tool_use",
+          data: {
+            parent_message_id: pending.parentMessageId || null,
+            tool_message_id: id,
+            turn_index: pending.turnIndex,
+            block,
+          },
+        },
+      ];
+    }
+
+    case "TOOL_CALL_END":
+      pendingCalls.delete(str(frame.toolCallId));
+      return [];
+
+    case "TOOL_CALL_RESULT":
+      return [
+        {
+          event: "chat.tool_result",
+          data: {
+            parent_message_id: (m.parent_message_id as string | undefined) ?? null,
+            tool_message_id: str(frame.toolCallId),
+            turn_index: num(m.turn_index),
+            block: (m.block as Record<string, unknown> | undefined) ?? { content: frame.content },
+          },
+        },
+      ];
+
+    case "ACTIVITY_SNAPSHOT": {
+      const content = (frame.content as Record<string, unknown>) ?? {};
+      const state = str(content.state);
+      if (!state) return [];
+      return [{ event: "session.activity", data: { state: state as "working" | "idle" | "blocked" } }];
+    }
+
+    case "RUN_FINISHED": {
+      const outcome = frame.outcome as Record<string, unknown> | undefined;
+      if (outcome?.type === "interrupt") {
+        const interrupts = (outcome.interrupts as Array<Record<string, unknown>>) ?? [];
+        return interrupts.map((i) => ({
+          event: "session.menu" as const,
+          data: { menu: interruptToMenu(i) },
+        }));
+      }
+      const result = frame.result as Record<string, unknown> | undefined;
+      if (result?.cancelled) {
+        return [
+          {
+            event: "chat.stream_cancelled",
+            data: { message_id: null, partial_len: num(result.partial_len) },
+          },
+        ];
+      }
+      return [];
+    }
+
+    case "RUN_ERROR":
+      return [
+        {
+          event: "session.error",
+          data: { code: str(frame.code) || "run_error", message: str(frame.message) },
+        },
+      ];
+
+    case "STATE_DELTA": {
+      // Only the one patch canopy sends. A general JSON-Patch applier would be
+      // a second source of truth for session state, which is the reducer's job.
+      const ops = (frame.delta as Array<Record<string, unknown>>) ?? [];
+      const title = ops.find((op) => op.path === "/title");
+      if (!title) return [];
+      return [{ event: "session.title_updated", data: { title: str(title.value) } }];
+    }
+
+    case "CUSTOM": {
+      // canopy's own vocabulary, coming home. Drafts, presence and placement
+      // have no AG-UI spelling because the protocol models one user and one
+      // agent; they were namespaced on the way out and are unwrapped here.
+      const name = str(frame.name);
+      if (!name.startsWith(CUSTOM_PREFIX)) return [];
+      const event = name.slice(CUSTOM_PREFIX.length);
+      if (event === "menu.retracted") return [{ event: "session.menu", data: { menu: null } }];
+      if (event === "menu") {
+        return [{ event: "session.menu", data: { menu: frame.value as never } }];
+      }
+      return [{ event, data: frame.value } as unknown as WsEvent];
+    }
+
+    default:
+      return [];
+  }
+}
+
+/** Arguments arrive on a later event than the tool's name, so the head of a
+ *  call is held until they do. Module-level because a socket is a stream and
+ *  the pairing spans events; `resetAguiState` exists so a test — and a
+ *  reconnect — can start from nothing rather than inheriting a half-read call
+ *  from the connection before. */
+const pendingCalls = new Map<
+  string,
+  {
+    name: string;
+    parentMessageId: string;
+    turnIndex: number;
+    block?: Record<string, unknown>;
+  }
+>();
+
+export function resetAguiState(): void {
+  pendingCalls.clear();
+}
+
+/** An AG-UI interrupt back into canopy's menu shape.
+ *
+ *  The fields line up because the protocol independently arrived at the same
+ *  ones: `expiresAt` is canopy's `observed_at` (a dialog lives on a terminal
+ *  and this is a copy, so it has to carry its own age), and the option list
+ *  lives in `metadata.canopy.questions` because a response schema can say a
+ *  field takes a list but not that the TUI draws it as checkboxes a number key
+ *  TOGGLES rather than answers. */
+function interruptToMenu(interrupt: Record<string, unknown>): SessionMenu {
+  const m = (interrupt.metadata as Record<string, unknown> | undefined)?.[METADATA_KEY] as
+    | Record<string, unknown>
+    | undefined;
+  const questions = (m?.questions as Array<Record<string, unknown>>) ?? [];
+  const first = questions[0] ?? {};
+  return {
+    question: str(first.question) || str(interrupt.message),
+    title: str(interrupt.message),
+    body: str(m?.body),
+    source: str(interrupt.reason),
+    questions: questions as unknown as SessionMenu["questions"],
+    options: (first.options as unknown as SessionMenu["options"]) ?? [],
+    answer_error: str(m?.answer_error) || undefined,
+    answer_note: str(m?.answer_note) || undefined,
+    restored: Boolean(m?.restored),
+    observed_at: interrupt.expiresAt ? Date.parse(str(interrupt.expiresAt)) / 1000 : undefined,
+  };
+}

package/src/chat/index.ts

@@ -17,6 +17,10 @@ export type {
   WsEvent,
 } from "./protocol";
 
+// REST <-> kit conversion. Shared because both hosts that read a transcript over
+// REST were writing this out by hand, against this kit's own Message type.
+export { restToKitMessage, type RestMessage } from "./restMessage";
+
 // Reducer (pure)
 export { sessionReducer } from "./sessionReducer";
 export { prependHistory } from "./history";
@@ -67,3 +71,6 @@ export {
   type PlacementBannerProps,
   type PlacementRunner,
 } from "./PlacementBanner";
+// The AG-UI projection's inverse. Exported so a consumer can translate a stream
+// it obtained some other way — and so the round-trip test can reach it.
+export { fromAgui, resetAguiState, CUSTOM_PREFIX, METADATA_KEY } from "./agui";

package/src/chat/restMessage.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import { prependHistory } from "./history";
+import { restToKitMessage, type RestMessage } from "./restMessage";
+import type { Message } from "./protocol";
+
+const row: RestMessage = {
+  turn_index: 7,
+  role: "assistant",
+  content: { text: "hello" },
+  plaintext: "hello",
+  created_at: "2026-09-16T10:00:00Z",
+};
+
+describe("restToKitMessage", () => {
+  it("maps a REST row onto the kit's Message shape", () => {
+    expect(restToKitMessage(row)).toEqual({
+      id: "t7",
+      turn_index: 7,
+      role: "assistant",
+      content: { text: "hello" },
+      plaintext: "hello",
+      status: "complete",
+      error_detail: null,
+      started_at: null,
+      completed_at: "2026-09-16T10:00:00Z",
+      created_at: "2026-09-16T10:00:00Z",
+    });
+  });
+
+  it("gives a row read back from REST no streaming history", () => {
+    // A REST row was never watched arriving, so claiming a `started_at` would
+    // invent a fact. `completed_at` is what the server does know.
+    const m = restToKitMessage(row);
+    expect(m.started_at).toBeNull();
+    expect(m.completed_at).toBe(row.created_at);
+  });
+
+  it("accepts a readonly generated row (what both hosts actually pass)", () => {
+    // openapi-typescript emits every field `readonly`. Property readonly-ness
+    // does not affect assignability, and this asserts that stays true — it is
+    // the reason `RestMessage` can be declared structurally instead of as
+    // either host's generated type.
+    const generated: { readonly [K in keyof RestMessage]: RestMessage[K] } = row;
+    expect(restToKitMessage(generated).id).toBe("t7");
+  });
+
+  it("does not collide with the live WS row for the same turn", () => {
+    // The synthetic `t<turn_index>` id is only safe because prependHistory
+    // dedupes on turn_index. If that ever changed to dedupe on id, this fails.
+    const live: Message = { ...restToKitMessage(row), id: "1234", status: "streaming" };
+    const merged = prependHistory([live], [restToKitMessage(row)]);
+    expect(merged).toHaveLength(1);
+    expect(merged[0].id).toBe("1234");
+  });
+});

package/src/chat/restMessage.ts

@@ -0,0 +1,54 @@
+/**
+ * One REST transcript row -> the kit's `Message`.
+ *
+ * This lived twice, written out by hand in both hosts that read a transcript
+ * over REST and then hand it to this kit: canopy-web's own
+ * `pages/chatPageLogic.ts` and ace-web's `canopy/CanopyChatPanel.tsx`, whose
+ * copy carried the comment "mirrors canopy-web's own
+ * `chatPageLogic.ts::restToKitMessage`" — an accurate description of a bug
+ * waiting to happen. It is a pure function OF this kit's own `Message` type
+ * against canopy's own `MessageOut` wire schema, so neither host was ever the
+ * right owner of it; both were translating between two shapes they had each
+ * imported from somewhere else.
+ *
+ * The input is declared structurally rather than as either host's generated
+ * type, because the hosts generate their own: canopy-web has
+ * `components["schemas"]["MessageOut"]`, ace-web casts an `unknown` row. Both
+ * are assignable to `RestMessage`, and a generated type's `readonly` property
+ * modifiers do not affect that.
+ */
+
+import type { Message } from "./protocol";
+
+/** canopy's `MessageOut` (apps/canopy_sessions/schemas.py), structurally. */
+export interface RestMessage {
+  turn_index: number;
+  role: string;
+  content: Record<string, unknown>;
+  plaintext: string;
+  created_at: string;
+}
+
+/**
+ * Synthetic id (`t<turn_index>`) + `status: "complete"`.
+ *
+ * `prependHistory` dedupes on `turn_index`, not on `id`, so a synthetic id can
+ * never collide with the live WS row for the same turn — which is the whole
+ * reason it is safe to invent one here. `started_at` is null because a row read
+ * back from REST has no streaming history to report; `completed_at` takes
+ * `created_at`, which is when the turn finished as far as the server records it.
+ */
+export function restToKitMessage(m: RestMessage): Message {
+  return {
+    id: `t${m.turn_index}`,
+    turn_index: m.turn_index,
+    role: m.role as Message["role"],
+    content: m.content,
+    plaintext: m.plaintext,
+    status: "complete",
+    error_detail: null,
+    started_at: null,
+    completed_at: m.created_at,
+    created_at: m.created_at,
+  };
+}

package/src/chat/useSessionSocket.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
+import { fromAgui, resetAguiState } from "./agui";
 import type { Message, SessionState, WsEvent } from "./protocol";
 import { shouldSyncDraftLive } from "./drafts";
 import { prependHistory } from "./history";
@@ -32,6 +33,29 @@ export interface UseSessionSocketOptions {
    * has no opinion on what to do with it.
    */
   onTitleUpdated?: () => void;
+  /**
+   * A frame the kit does not understand.
+   *
+   * The kit stays agnostic: canopy grew `session.page_action` (an agent asking
+   * the embedded page to do something) and ace-web will grow its own. Teaching
+   * the reducer about each would make a shared kit carry one app's vocabulary.
+   * Same shape as `onTitleUpdated` — handed over, no opinion taken.
+   */
+  onUnknownEvent?: (frame: WsEvent) => void;
+  /**
+   * Which vocabulary to ask the server for.
+   *
+   * `"canopy"` (the default) is this kit's own frames, unchanged — the reason
+   * an existing consumer, including ace-web installing `canopy-ui` from npm,
+   * notices nothing. `"ag-ui"` asks the server to project the same conversation
+   * into AG-UI and translates it back here, so the reducer never learns a
+   * second vocabulary and there is one behaviour to test rather than two.
+   *
+   * Opting in buys interoperability, not features: a canopy frame and its
+   * AG-UI projection reduce to identical state (`agui.test.ts` asserts exactly
+   * that against a fixture the server generates).
+   */
+  protocol?: "canopy" | "ag-ui";
 }
 
 export interface UseSessionSocketResult {
@@ -51,10 +75,27 @@ export interface UseSessionSocketResult {
   lastError: string | null;
 }
 
+/**
+ * Frames `sessionReducer` understands. Anything else is handed to
+ * `onUnknownEvent` rather than dropped — the reducer ignores what it does not
+ * recognise, which silently swallows an app-specific frame and leaves the
+ * container wondering why its feature never fires.
+ *
+ * Keep in step with sessionReducer's own switch.
+ */
+const KNOWN_EVENTS = new Set([
+  "chat.delta", "chat.stream_cancelled", "chat.stream_complete",
+  "chat.stream_error", "chat.stream_start", "chat.tool_result",
+  "chat.tool_use", "chat.user_message", "session.activity", "session.error",
+  "session.menu", "session.state", "session.stop", "session.title_updated",
+]);
+
 export function useSessionSocket({
   sessionId,
   wsUrl,
   onTitleUpdated,
+  onUnknownEvent,
+  protocol = "canopy",
 }: UseSessionSocketOptions): UseSessionSocketResult {
   const [state, setState] = useState<SessionState>(INITIAL_STATE);
   const [connected, setConnected] = useState(false);
@@ -73,6 +114,13 @@ export function useSessionSocket({
   const pendingDraftBodyRef = useRef<string | null>(null);
   const closedByUserRef = useRef(false);
   const onTitleUpdatedRef = useRef(onTitleUpdated);
+  const onUnknownEventRef = useRef(onUnknownEvent);
+  // A ref, like the callbacks above: `connect` is a stable callback with empty
+  // deps, so reading the prop directly would pin whatever it was on first
+  // render — and a socket that reconnects would silently drop back to the other
+  // vocabulary mid-session.
+  const protocolRef = useRef(protocol);
+  protocolRef.current = protocol;
   // Control frames that must not be lost across a reconnect (currently
   // only chat.stop). The WS-world analogue of an abortable chat transport.
   const pendingFramesRef = useRef<{ action: string; data: unknown }[]>([]);
@@ -85,6 +133,10 @@ export function useSessionSocket({
     onTitleUpdatedRef.current = onTitleUpdated;
   }, [onTitleUpdated]);
 
+  useEffect(() => {
+    onUnknownEventRef.current = onUnknownEvent;
+  }, [onUnknownEvent]);
+
   const send = useCallback((frame: { action: string; data: unknown }) => {
     const ws = socketRef.current;
     if (ws && ws.readyState === WebSocket.OPEN) {
@@ -134,12 +186,25 @@ export function useSessionSocket({
         }
       }
     }
+    // The reducer ignores anything it does not know, which silently drops an
+    // app-specific frame. Hand it over instead, so the container can act on
+    // vocabulary the shared kit deliberately does not carry.
+    if (!KNOWN_EVENTS.has(frame.event)) {
+      onUnknownEventRef.current?.(frame);
+      return;
+    }
     setState((prev) => sessionReducer(prev, frame));
   }, []);
 
   const connect = useCallback(() => {
     if (closedByUserRef.current) return;
-    const ws = new WebSocket(wsUrl(`ws/canopy-sessions/${sessionId}/`));
+    // A half-read tool call from the previous connection must not be completed
+    // by an ARGS event from this one — the ids are per-stream.
+    resetAguiState();
+    const path = `ws/canopy-sessions/${sessionId}/`;
+    const ws = new WebSocket(
+      wsUrl(protocolRef.current === "ag-ui" ? `${path}?protocol=ag-ui` : path),
+    );
     socketRef.current = ws;
 
     ws.onopen = () => {
@@ -162,8 +227,14 @@ export function useSessionSocket({
 
     ws.onmessage = (e) => {
       try {
-        const frame = JSON.parse(e.data) as WsEvent;
-        applyEvent(frame);
+        const raw = JSON.parse(e.data);
+        if (protocolRef.current === "ag-ui") {
+          // One AG-UI event can be several canopy frames (a tool call is three
+          // events) or none, so this is a fan-out rather than a rename.
+          for (const frame of fromAgui(raw)) applyEvent(frame);
+          return;
+        }
+        applyEvent(raw as WsEvent);
       } catch {
         // ignore malformed frames
       }

package/src/shell/WorkbenchNavItem.tsx

@@ -12,8 +12,10 @@ export function workbenchNavItemClass({
     variant === 'neutral'
       ? 'bg-accent border-transparent text-foreground font-medium'
       : 'bg-primary/10 border-primary/30 text-primary font-medium'
+  // `min-h-11` below `sm` is the 44px touch minimum; from `sm` up the rail keeps
+  // its original density, where the pointer is precise and vertical space is dear.
   return cn(
-    'flex items-center justify-between gap-2 rounded-md border px-3 py-1.5 text-sm transition-colors',
+    'flex min-h-11 items-center justify-between gap-2 rounded-md border px-3 py-1.5 text-sm transition-colors sm:min-h-0',
     active
       ? activeClass
       : 'border-transparent text-muted-foreground hover:bg-accent hover:text-foreground',

package/src/ui/button.tsx

@@ -4,6 +4,11 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { cn } from "../lib/cn"
 
 const buttonVariants = cva(
+  // Every size variant sets a fixed height (default h-8, sm h-7, xs h-6), all of
+  // them below the 44px touch minimum. Rather than teach each variant about
+  // touch, the floor lives here once and lifts off at `sm`, where a pointer is
+  // precise and the density is the point.
+  "min-h-11 min-w-11 sm:min-h-0 sm:min-w-0 " +
   "group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
   {
     variants: {

package/src/ui/input.tsx

@@ -9,7 +9,9 @@ function Input({ className, type, ...props }: React.ComponentProps<"input">) {
       type={type}
       data-slot="input"
       className={cn(
-        "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        // Touch floor, matching Button: `h-8` is 32px, under the 44px minimum. Lifts
+        // off at `sm` so desktop density is unchanged.
+        "min-h-11 sm:min-h-0 sm:h-8 h-11 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
         className
       )}
       {...props}

package/src/ui/tabs.tsx

@@ -23,8 +23,17 @@ function Tabs({
   )
 }
 
+// Touch first, then shrink to the desktop density at `sm`.
+//
+// `w-fit` + a fixed `h-8` was two bugs at once on a phone: the list sized itself
+// to its content, so a fourth tab ran off the viewport with no scroll and no
+// wrap (measured on /supervisor at 375px: scrollWidth 302 vs clientWidth 293,
+// clipping "Runners"), and the height capped every trigger at 23px — roughly
+// half the 44px touch minimum, on the surface that ships as the phone PWA.
+// Below `sm` the list is now full-width and wraps; from `sm` up it is exactly
+// what it was.
 const tabsListVariants = cva(
-  "group/tabs-list inline-flex w-fit items-center justify-center rounded-lg p-[3px] text-muted-foreground group-data-horizontal/tabs:h-8 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col data-[variant=line]:rounded-none",
+  "group/tabs-list grid w-full max-w-full grid-cols-2 items-center justify-center rounded-lg p-[3px] text-muted-foreground sm:inline-flex sm:w-fit sm:grid-cols-none group-data-horizontal/tabs:h-auto sm:group-data-horizontal/tabs:h-8 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col data-[variant=line]:rounded-none",
   {
     variants: {
       variant: {
@@ -58,7 +67,7 @@ function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props) {
     <TabsPrimitive.Tab
       data-slot="tabs-trigger"
       className={cn(
-        "relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2.5 py-0.5 text-sm font-medium whitespace-nowrap text-muted-foreground transition-all group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start hover:text-foreground-secondary focus-visible:border-primary/50 focus-visible:ring-2 focus-visible:ring-primary/20 focus-visible:outline-1 focus-visible:outline-primary/40 disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 group-data-[variant=default]/tabs-list:data-active:shadow-sm group-data-[variant=line]/tabs-list:data-active:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "relative inline-flex min-h-11 flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-0.5 text-sm font-medium whitespace-nowrap text-muted-foreground transition-all sm:h-[calc(100%-1px)] sm:min-h-0 sm:px-2.5 group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start hover:text-foreground-secondary focus-visible:border-primary/50 focus-visible:ring-2 focus-visible:ring-primary/20 focus-visible:outline-1 focus-visible:outline-primary/40 disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 group-data-[variant=default]/tabs-list:data-active:shadow-sm group-data-[variant=line]/tabs-list:data-active:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent group-data-[variant=line]/tabs-list:data-active:border-transparent",
         "data-active:bg-background data-active:text-foreground data-active:border-border",
         "after:absolute after:bg-primary after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-0.5 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",