canopy-ui 0.7.0 → 0.9.0

package/src/chat/agui.test.ts

@@ -0,0 +1,302 @@
+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()
+
+    // NOT `expect(source).toContain('protocol=ag-ui')`, which this used to say.
+    // It held the whole time the flag was being dropped by any URL builder that
+    // ignores its path — i.e. by canopy-web's widget and by ace-web. Whether the
+    // flag reaches the socket is asserted where it can be seen, against the URL
+    // a socket really opens: `useSessionSocket.protocol.test.tsx`.
+    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,295 @@
+/**
+ * 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);
+
+  // The server's own frame, when it sent one. Where the AG-UI spelling is lossy
+  // for canopy — a run error with no slot for which message failed, a messages
+  // snapshot with none for drafts, presence or a pending dialog, an interrupt
+  // that re-encodes the menu — the original rides under `metadata.canopy.frame`
+  // (`_verbatim` in agui.py), and returning it beats rebuilding it: a rebuilt
+  // frame carries whatever this function guessed, not what the server said.
+  // One rule for every such event, so a newly lossy projection needs no new case
+  // here — which is how the connect snapshot went missing in the first place.
+  const original = m.frame;
+  if (original && typeof original === "object" && typeof (original as WsEvent).event === "string") {
+    return [original as WsEvent];
+  }
+
+  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");
+  });
+});