@nanobpm/agentic 0.6.0 → 0.8.0

package/src/cockpit/boot.test.ts

@@ -3,6 +3,7 @@ import { test } from "node:test";
 
 import { decodeFrame, encodeFrame, type Frame } from "../protocol/index.ts";
 import type { DemandSupplyReport } from "../demand/index.ts";
+import { type TranscriptEvent, encodeTranscriptEvent } from "../transcript/index.ts";
 
 import { bootCockpit, type CockpitEnv } from "./boot.ts";
 import { FakeDocument, FakeElement } from "./fake-dom.ts";
@@ -64,8 +65,11 @@ interface Rig {
   readonly host: FakeElement;
   readonly sockets: FakeSocket[];
   readonly terminalWrites: string[];
+  readonly structuredEvents: TranscriptEvent[];
   terminalMounts: number;
   terminalDisposes: number;
+  structuredMounts: number;
+  structuredDisposes: number;
   readonly timers: Array<{ run: () => void; ms: number }>;
   reconnect: (() => void) | undefined;
   report: DemandSupplyReport;
@@ -76,13 +80,17 @@ function rig(): Rig {
   const host = new FakeElement("body");
   const sockets: FakeSocket[] = [];
   const terminalWrites: string[] = [];
+  const structuredEvents: TranscriptEvent[] = [];
   const timers: Array<{ run: () => void; ms: number }> = [];
   const state: Rig = {
     host,
     sockets,
     terminalWrites,
+    structuredEvents,
     terminalMounts: 0,
     terminalDisposes: 0,
+    structuredMounts: 0,
+    structuredDisposes: 0,
     timers,
     reconnect: undefined,
     report: served,
@@ -106,6 +114,16 @@ function rig(): Rig {
           },
         };
       },
+      createStructured: (structuredHost) => {
+        state.structuredMounts += 1;
+        structuredHost.appendChild(new FakeElement("div"));
+        return {
+          event: (event) => structuredEvents.push(event),
+          dispose: () => {
+            state.structuredDisposes += 1;
+          },
+        };
+      },
       schedule: (run) => {
         state.reconnect = run;
       },
@@ -172,6 +190,102 @@ test("relay output is written to the drilled worker's terminal", async () => {
   r.sockets[0]?.fireOpen();
   r.sockets[0]?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "ci-a", offset: 0, chunk: "boot\n" } });
   assert.deepEqual(r.terminalWrites, ["boot\n"]);
+  assert.deepEqual(r.structuredEvents, [], "a raw stream routes nothing to the structured view");
+});
+
+function structuredFrame(seq: number, offset: number, event: TranscriptEvent): Frame {
+  return { lane: "bulk", family: "relay", seq, payload: { stream: "ci-a", offset, chunk: encodeTranscriptEvent(event) } };
+}
+
+test("a structured (marker-tagged) stream routes to the structured view, NOT the byte-terminal", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  r.sockets[0]?.fireOpen();
+  r.sockets[0]?.deliver(structuredFrame(0, 0, { kind: "turn", offset: 0, index: 0 }));
+  r.sockets[0]?.deliver(structuredFrame(1, 1, { kind: "message", offset: 1, role: "assistant", text: "hi" }));
+  assert.deepEqual(r.terminalWrites, [], "structured chunks are not dumped into the byte-terminal");
+  assert.deepEqual(
+    r.structuredEvents.map((e) => e.kind),
+    ["turn", "message"],
+    "the decoded transcript events reach the structured view",
+  );
+});
+
+test("a mixed stream routes each chunk to the right surface (raw → terminal, tagged → structured)", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  r.sockets[0]?.fireOpen();
+  r.sockets[0]?.deliver({ lane: "bulk", family: "relay", seq: 0, payload: { stream: "ci-a", offset: 0, chunk: "booting\n" } });
+  r.sockets[0]?.deliver(structuredFrame(1, 1, { kind: "message", offset: 1, role: "assistant", text: "ready" }));
+  r.sockets[0]?.deliver({ lane: "bulk", family: "relay", seq: 2, payload: { stream: "ci-a", offset: 2, chunk: "tail\n" } });
+  assert.deepEqual(r.terminalWrites, ["booting\n", "tail\n"]);
+  assert.deepEqual(
+    r.structuredEvents.map((e) => (e.kind === "message" ? e.text : e.kind)),
+    ["ready"],
+  );
+});
+
+test("the structured view survives a cockpit reconnect — resume-from-offset, no loss, no dup", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+
+  const s1 = r.sockets[0];
+  s1?.fireOpen();
+  s1?.deliver(structuredFrame(0, 0, { kind: "message", offset: 0, role: "assistant", text: "a" }));
+  s1?.deliver(structuredFrame(1, 1, { kind: "message", offset: 1, role: "assistant", text: "b" }));
+
+  // The cockpit's socket drops; the client reconnects.
+  s1?.fireClose();
+  assert.ok(r.reconnect !== undefined, "a reconnect was scheduled");
+  r.reconnect?.();
+  const s2 = r.sockets[1];
+  s2?.fireOpen(); // re-attach → resume from offset 2
+  const subs = s2?.subscribeFrames() ?? [];
+  assert.deepEqual(subs.at(-1)?.payload, { op: "subscribe", stream: "ci-a", from: 2, credit: 1024 });
+
+  // The hub replays the retained tail (re-sends offset 1) then continues.
+  s2?.deliver(structuredFrame(0, 1, { kind: "message", offset: 1, role: "assistant", text: "b" }));
+  s2?.deliver(structuredFrame(1, 2, { kind: "message", offset: 2, role: "assistant", text: "c" }));
+  assert.deepEqual(
+    r.structuredEvents.map((e) => (e.kind === "message" ? e.text : e.kind)),
+    ["a", "b", "c"],
+    "no dropped and no duplicated structured events across the reconnect",
+  );
+});
+
+test("the built-in structured renderer derives into the structured host when none is injected", async () => {
+  const r = rig();
+  // Drop the custom createStructured so the default DOM renderer is exercised end-to-end.
+  const { createStructured: _drop, ...envWithoutStructured } = r.env;
+  const cockpit = bootCockpit(envWithoutStructured);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  r.sockets[0]?.fireOpen();
+  r.sockets[0]?.deliver(structuredFrame(0, 0, { kind: "message", offset: 0, role: "assistant", text: "hello" }));
+  assert.deepEqual(r.terminalWrites, [], "structured chunk is not dumped as raw");
+  const rendered = r.host.byClass("cockpit-structured-message");
+  assert.equal(rendered.length, 1, "the built-in structured renderer rendered the derived message");
+  assert.match(rendered[0]?.text() ?? "", /hello/);
+});
+
+test("switching streams disposes the prior structured view", async () => {
+  const r = rig();
+  const cockpit = bootCockpit(r.env);
+  await cockpit.refresh();
+  cockpit.drill("ci-a");
+  assert.equal(r.structuredMounts, 1);
+  assert.equal(r.structuredDisposes, 0);
+  cockpit.drill("ci-b");
+  assert.equal(r.structuredMounts, 2);
+  assert.equal(r.structuredDisposes, 1, "prior structured view disposed on stream switch");
+  cockpit.dispose();
+  assert.equal(r.structuredDisposes, 2, "the live structured view is disposed on dispose()");
 });
 
 test("the terminal survives a matrix refresh — it is not re-mounted and keeps streaming", async () => {

package/src/cockpit/boot.ts

@@ -21,12 +21,16 @@ import type { DemandSupplyReport } from "../demand/index.ts";
 import { isPosInt } from "../relay/index.ts";
 import { RelayChannelClient, type Scheduler, type SocketFactory } from "./relay-client.ts";
 import { type DocumentLike, type ElementLike, renderCockpit } from "./render.ts";
-import { TerminalSession, type TerminalSink } from "./terminal-session.ts";
+import { createStructuredSink } from "./structured-view.ts";
+import { type StructuredSink, TerminalSession, type TerminalSink } from "./terminal-session.ts";
 import { cockpitView } from "./view.ts";
 
 /** Mounts a terminal into `host` and returns the sink relay output is written to. */
 export type CreateTerminal = (host: ElementLike) => TerminalSink;
 
+/** Mounts a structured (ACP) view into `host` and returns the sink decoded transcript events are routed to. */
+export type CreateStructured = (host: ElementLike) => StructuredSink;
+
 /** An opaque poll-timer handle (a Node `Timeout` or a browser timer id). */
 export type TimerHandle = unknown;
 
@@ -41,6 +45,14 @@ export interface CockpitEnv {
   readonly connectRelay: SocketFactory;
   /** Mounts the terminal widget (xterm.js in the browser) and returns its write sink. */
   readonly createTerminal: CreateTerminal;
+  /**
+   * Mounts the structured (ACP) view widget and returns its event sink. Optional:
+   * when omitted the drill-in uses the built-in {@link createStructuredSink} DOM
+   * renderer over {@link doc}, so marker-tagged chunks are decoded and routed to
+   * that structured surface while raw bytes still flow to the {@link createTerminal}
+   * sink. Provide your own to override the built-in renderer.
+   */
+  readonly createStructured?: CreateStructured;
   /** Reconnect scheduler for the relay client. Default `setTimeout(run, 0)`. */
   readonly schedule?: Scheduler;
   /** Poll scheduler. Default `setTimeout`. Injected so tests drive it by hand. Must be paired with {@link clearTimer}. */
@@ -82,6 +94,8 @@ class Cockpit implements CockpitHandle {
   readonly #env: CockpitEnv;
   readonly #matrixRegion: ElementLike;
   readonly #terminalHost: ElementLike;
+  readonly #structuredHost: ElementLike;
+  readonly #createStructured: CreateStructured;
   readonly #refreshMs: number;
   readonly #setTimer: (run: () => void, ms: number) => TimerHandle;
   readonly #clearTimer: (handle: TimerHandle) => void;
@@ -94,6 +108,9 @@ class Cockpit implements CockpitHandle {
   // The currently mounted terminal, tracked so switching streams (and dispose)
   // tears down the prior xterm instance instead of leaking it + its listeners.
   #terminal: TerminalSink | undefined;
+  // The currently mounted structured view, torn down alongside #terminal so a
+  // stream switch / dispose never leaks the prior worker's structured widget.
+  #structured: StructuredSink | undefined;
   // Bumped by every start()/stop() so an in-flight #tick() from a previous
   // start cycle can't reschedule after a stop→start race and leave two
   // overlapping poll chains running against the same cockpit.
@@ -142,6 +159,11 @@ class Cockpit implements CockpitHandle {
         }
       });
 
+    // The structured (ACP) view mounter defaults to the built-in DOM renderer over
+    // the injected document, so a structured stream derives + renders without any
+    // extra wiring; a browser caller may override it (e.g. a richer widget).
+    this.#createStructured = env.createStructured ?? ((host) => createStructuredSink(host, env.doc));
+
     // Build the stable skeleton once: a volatile matrix region the poll
     // re-renders, and a PERSISTENT terminal region a refresh never touches.
     env.host.replaceChildren();
@@ -159,6 +181,14 @@ class Cockpit implements CockpitHandle {
     this.#terminalHost.className = "cockpit-terminal-host";
     this.#terminalHost.setAttribute("data-terminal", "host");
     terminalPanel.appendChild(this.#terminalHost);
+    // A sibling PERSISTENT region for the derived structured (ACP) view. A raw
+    // stream keeps it in its initial/empty structured state; a structured stream
+    // renders here instead of dumping JSON into the byte-terminal; a mixed stream
+    // feeds both.
+    this.#structuredHost = env.doc.createElement("div");
+    this.#structuredHost.className = "cockpit-structured-host";
+    this.#structuredHost.setAttribute("data-structured", "host");
+    terminalPanel.appendChild(this.#structuredHost);
     shell.appendChild(this.#matrixRegion);
     shell.appendChild(terminalPanel);
     env.host.appendChild(shell);
@@ -233,12 +263,18 @@ class Cockpit implements CockpitHandle {
     // still cleans it up on the next drill or on dispose().
     this.#terminal?.dispose?.();
     this.#terminal = undefined;
+    // The structured view is torn down in lockstep with the terminal.
+    this.#structured?.dispose?.();
+    this.#structured = undefined;
 
     try {
-      // Fresh terminal for the newly selected worker.
+      // Fresh terminal + structured view for the newly selected worker.
       this.#terminalHost.replaceChildren();
       const sink = this.#env.createTerminal(this.#terminalHost);
       this.#terminal = sink;
+      this.#structuredHost.replaceChildren();
+      const structured = this.#createStructured(this.#structuredHost);
+      this.#structured = structured;
 
       let session: TerminalSession | undefined;
       const client = new RelayChannelClient({
@@ -253,6 +289,7 @@ class Cockpit implements CockpitHandle {
       session = new TerminalSession({
         stream,
         sink,
+        structured,
         send: (message) => client.sendRelay(message),
         credit: this.#env.credit,
       });
@@ -271,6 +308,8 @@ class Cockpit implements CockpitHandle {
     this.#drill = undefined;
     this.#terminal?.dispose?.();
     this.#terminal = undefined;
+    this.#structured?.dispose?.();
+    this.#structured = undefined;
   }
 }
 

package/src/cockpit/index.ts

@@ -34,6 +34,7 @@ export {
   type RelayInbound,
   type RelayOutbound,
   type RelaySend,
+  type StructuredSink,
   type TerminalSessionOptions,
   type TerminalSink,
 } from "./terminal-session.ts";
@@ -54,10 +55,17 @@ export {
   type RenderOptions,
 } from "./render.ts";
 
+export {
+  createStructuredSink,
+  renderStructured,
+  type StructuredTerminal,
+} from "./structured-view.ts";
+
 export {
   bootCockpit,
   type CockpitEnv,
   type CockpitHandle,
+  type CreateStructured,
   type CreateTerminal,
   type TimerHandle,
 } from "./boot.ts";

package/src/cockpit/structured-view.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { type TranscriptEvent, deriveView } from "../transcript/index.ts";
+
+import { FakeDocument, FakeElement } from "./fake-dom.ts";
+import { createStructuredSink, renderStructured } from "./structured-view.ts";
+
+function fixture(): { host: FakeElement; doc: FakeDocument } {
+  return { host: new FakeElement("div"), doc: new FakeDocument() };
+}
+
+test("renderStructured renders derived turns, messages and tool cards (not raw JSON)", () => {
+  const { host, doc } = fixture();
+  const events: TranscriptEvent[] = [
+    { kind: "turn", offset: 0, index: 0 },
+    { kind: "message", offset: 1, role: "user", text: "run the build" },
+    { kind: "message", offset: 2, role: "assistant", text: "on it" },
+    { kind: "tool-call", offset: 3, name: "shell", callId: "c1", args: { cmd: "build" } },
+    { kind: "tool-result", offset: 4, callId: "c1", ok: true, content: "done" },
+    { kind: "lifecycle", offset: 5, phase: "completed" },
+  ];
+  renderStructured(host, doc, deriveView(events));
+
+  const root = host.byClass("cockpit-structured")[0];
+  assert.ok(root, "a structured root is rendered");
+  assert.equal(root.getAttribute("data-lifecycle"), "completed");
+
+  const messages = host.byClass("cockpit-structured-message");
+  assert.equal(messages.length, 2);
+  assert.equal(messages[0]?.getAttribute("data-role"), "user");
+  assert.match(messages[0]?.text() ?? "", /run the build/);
+
+  const tool = host.byClass("cockpit-structured-tool")[0];
+  assert.ok(tool, "the tool card is rendered");
+  assert.equal(tool.getAttribute("data-tool"), "shell");
+  assert.equal(tool.getAttribute("data-state"), "ok");
+  assert.match(tool.text(), /done/);
+});
+
+test("renderStructured replaces prior content (idempotent re-render)", () => {
+  const { host, doc } = fixture();
+  renderStructured(host, doc, deriveView([{ kind: "message", offset: 0, role: "assistant", text: "one" }]));
+  renderStructured(host, doc, deriveView([{ kind: "message", offset: 0, role: "assistant", text: "two" }]));
+  assert.equal(host.byClass("cockpit-structured").length, 1, "no duplicated roots after a re-render");
+  assert.equal(host.byClass("cockpit-structured-message").length, 1);
+  assert.match(host.byClass("cockpit-structured-message")[0]?.text() ?? "", /two/);
+});
+
+test("createStructuredSink accumulates events and re-derives the view on each one", () => {
+  const { host, doc } = fixture();
+  const sink = createStructuredSink(host, doc);
+  // An empty view is present up-front, before any event.
+  assert.equal(host.byClass("cockpit-structured").length, 1);
+  assert.equal(host.byClass("cockpit-structured-message").length, 0);
+
+  sink.event({ kind: "message", offset: 0, role: "assistant", text: "first" });
+  sink.event({ kind: "message", offset: 1, role: "assistant", text: "second" });
+  const messages = host.byClass("cockpit-structured-message");
+  assert.equal(messages.length, 2, "both accumulated events are folded into the view");
+  assert.match(messages[1]?.text() ?? "", /second/);
+});
+
+test("createStructuredSink.dispose clears the accumulated log and the DOM", () => {
+  const { host, doc } = fixture();
+  const sink = createStructuredSink(host, doc);
+  sink.event({ kind: "message", offset: 0, role: "assistant", text: "hi" });
+  sink.dispose();
+  assert.equal(host.children.length, 0, "the structured host is emptied on dispose");
+});

package/src/cockpit/structured-view.ts

@@ -0,0 +1,114 @@
+/**
+ * The cockpit's structured-stream renderer — S8's drill-in for an ACP stream.
+ *
+ * When a drilled worker's relay stream is a **structured** ACP stream (its chunks
+ * are {@link TRANSCRIPT_EVENT_MARKER}-tagged transcript-event envelopes rather than
+ * raw PTY bytes), the {@link TerminalSession} routes each decoded event here instead
+ * of the byte-terminal. This renderer does **not** re-parse or pretty-print JSON: it
+ * feeds the accumulated typed events straight through the ONE canonical
+ * {@link deriveView} fold from `@nanobpm/agentic/transcript` and renders the resulting
+ * {@link DerivedView} (turns → messages + tool cards) into the DOM.
+ *
+ * Like {@link renderCockpit} it builds against the structural {@link ElementLike} /
+ * {@link DocumentLike} subset (not lib.dom), so it renders identically embedded and
+ * standalone, is unit-tested on Node with the in-memory fake and no `as` cast, and is
+ * browser-safe — it relies only on the browser-safe transcript vocab (no `Buffer`).
+ *
+ * Events arrive offset-keyed and immutable in offset order, so re-deriving the whole
+ * (idempotent) log on each event is correct across a resume-from-offset reconnect: a
+ * replayed chunk below the resume point never reaches this sink, so no event is
+ * dropped or double-applied.
+ */
+import { type DerivedView, type TranscriptEvent, deriveView } from "../transcript/index.ts";
+import type { DocumentLike, ElementLike } from "./render.ts";
+import type { StructuredSink } from "./terminal-session.ts";
+
+function el(doc: DocumentLike, tag: string, className?: string, text?: string): ElementLike {
+  const node = doc.createElement(tag);
+  if (className !== undefined) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function toolCard(doc: DocumentLike, tool: DerivedView["tools"][number]): ElementLike {
+  const card = el(doc, "div", "cockpit-structured-tool");
+  card.setAttribute("data-tool", tool.name);
+  card.setAttribute("data-offset", String(tool.offset));
+  card.setAttribute("data-state", tool.result === undefined ? "pending" : tool.result.ok ? "ok" : "error");
+  const head = el(doc, "div", "cockpit-structured-tool-head");
+  head.appendChild(el(doc, "span", "cockpit-structured-tool-name", tool.name));
+  if (tool.callId !== undefined) head.appendChild(el(doc, "span", "cockpit-structured-tool-id", tool.callId));
+  card.appendChild(head);
+  if (tool.args !== undefined) {
+    card.appendChild(el(doc, "pre", "cockpit-structured-tool-args", JSON.stringify(tool.args)));
+  }
+  if (tool.result !== undefined) {
+    const result = el(doc, "div", "cockpit-structured-tool-result");
+    result.setAttribute("data-ok", tool.result.ok ? "true" : "false");
+    if (tool.result.content !== undefined) result.textContent = tool.result.content;
+    card.appendChild(result);
+  }
+  return card;
+}
+
+function turnSection(doc: DocumentLike, turn: DerivedView["turns"][number]): ElementLike {
+  const section = el(doc, "section", "cockpit-structured-turn");
+  section.setAttribute("data-turn", String(turn.index));
+  section.setAttribute("data-steps", String(turn.steps));
+  for (const message of turn.messages) {
+    const row = el(doc, "div", "cockpit-structured-message");
+    row.setAttribute("data-role", message.role);
+    row.setAttribute("data-offset", String(message.offset));
+    row.appendChild(el(doc, "span", "cockpit-structured-role", message.role));
+    row.appendChild(el(doc, "span", "cockpit-structured-text", message.text));
+    section.appendChild(row);
+  }
+  for (const tool of turn.tools) {
+    section.appendChild(toolCard(doc, tool));
+  }
+  return section;
+}
+
+/**
+ * Render a derived structured view into `host`, replacing whatever was there.
+ * Idempotent: re-call it with the latest {@link DerivedView} on every new event.
+ */
+export function renderStructured(host: ElementLike, doc: DocumentLike, view: DerivedView): void {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-structured");
+  root.setAttribute("data-lifecycle", view.lifecycle);
+  root.setAttribute("data-events", String(view.eventCount));
+  for (const turn of view.turns) {
+    root.appendChild(turnSection(doc, turn));
+  }
+  host.appendChild(root);
+}
+
+/** A structured sink with a `dispose` teardown (mirrors {@link TerminalSink}). */
+export interface StructuredTerminal extends StructuredSink {
+  dispose(): void;
+}
+
+/**
+ * Build a {@link StructuredSink} that accumulates the offset-ordered transcript
+ * events a structured stream delivers, folds them through the canonical
+ * {@link deriveView}, and renders the derived view into `host` on each event. The
+ * accumulated log is this sink's own state, so constructing one per drill-in gives
+ * each worker its own structured view.
+ */
+export function createStructuredSink(host: ElementLike, doc: DocumentLike): StructuredTerminal {
+  const events: TranscriptEvent[] = [];
+  // Render an empty derived view up-front so the structured region is present and
+  // consistent before the first event lands.
+  renderStructured(host, doc, deriveView(events));
+  return {
+    event(event: TranscriptEvent): void {
+      events.push(event);
+      renderStructured(host, doc, deriveView(events));
+    },
+    dispose(): void {
+      events.length = 0;
+      host.replaceChildren();
+    },
+  };
+}

package/src/cockpit/terminal-session.test.ts

@@ -2,23 +2,30 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 import type { RelayPayload } from "../protocol/index.ts";
+import { TRANSCRIPT_EVENT_MARKER, type TranscriptEvent, encodeTranscriptEvent } from "../transcript/index.ts";
 
-import { type RelayOutbound, TerminalSession } from "./terminal-session.ts";
+import { type RelayOutbound, type StructuredSink, TerminalSession } from "./terminal-session.ts";
 
 interface Harness {
   readonly session: TerminalSession;
   readonly sent: RelayOutbound[];
   readonly writes: string[];
+  readonly events: TranscriptEvent[];
   data(offset: number, chunk: string, stream?: string): RelayPayload;
 }
 
-function harness(options: { from?: number; credit?: number; stream?: string } = {}): Harness {
+function harness(options: { from?: number; credit?: number; stream?: string; structured?: boolean } = {}): Harness {
   const stream = options.stream ?? "worker-1";
   const sent: RelayOutbound[] = [];
   const writes: string[] = [];
+  const events: TranscriptEvent[] = [];
+  const structured: StructuredSink | undefined = options.structured
+    ? { event: (event) => events.push(event) }
+    : undefined;
   const session = new TerminalSession({
     stream,
     sink: { write: (chunk) => writes.push(chunk) },
+    structured,
     send: (message) => sent.push(message),
     from: options.from,
     credit: options.credit,
@@ -27,6 +34,7 @@ function harness(options: { from?: number; credit?: number; stream?: string } =
     session,
     sent,
     writes,
+    events,
     data: (offset, chunk, s = stream) => ({ stream: s, offset, chunk }),
   };
 }
@@ -250,3 +258,88 @@ test("grant rejects a non-positive or unsafe credit", () => {
   }
 });
 
+// A marker-tagged chunk (encoded via the ONE canonical grammar, never a hand-rolled marker literal).
+function structuredChunk(event: TranscriptEvent): string {
+  return encodeTranscriptEvent(event);
+}
+
+test("a structured (marker-tagged) chunk routes to the structured sink, NOT the byte-terminal", () => {
+  const h = harness({ structured: true });
+  h.session.attach();
+  h.session.handle(h.data(0, structuredChunk({ kind: "message", offset: 0, role: "assistant", text: "hi" })));
+  assert.deepEqual(h.writes, [], "a structured chunk must not be dumped into the byte-terminal");
+  assert.equal(h.events.length, 1);
+  assert.deepEqual(h.events[0], { kind: "message", offset: 0, role: "assistant", text: "hi" });
+  assert.equal(h.session.nextOffset, 1, "the resume offset advances for a structured chunk too");
+});
+
+test("a raw (untagged) chunk still renders on the byte-terminal even when a structured sink is wired", () => {
+  const h = harness({ structured: true });
+  h.session.attach();
+  h.session.handle(h.data(0, "plain bytes\n"));
+  assert.deepEqual(h.writes, ["plain bytes\n"]);
+  assert.deepEqual(h.events, [], "raw bytes never reach the structured sink");
+  assert.equal(h.session.nextOffset, 1);
+});
+
+test("with no structured sink a marker-tagged chunk is written verbatim (legacy raw-only behaviour)", () => {
+  const h = harness();
+  h.session.attach();
+  const chunk = structuredChunk({ kind: "message", offset: 0, role: "assistant", text: "hi" });
+  h.session.handle(h.data(0, chunk));
+  assert.deepEqual(h.writes, [chunk], "without a structured sink the envelope falls through to the byte-terminal");
+  assert.equal(h.session.nextOffset, 1);
+});
+
+test("a mixed stream that starts raw and only later carries tagged chunks routes each chunk correctly", () => {
+  const h = harness({ structured: true });
+  h.session.attach();
+  h.session.handle(h.data(0, "booting...\n"));
+  h.session.handle(h.data(1, structuredChunk({ kind: "turn", offset: 1, index: 0 })));
+  h.session.handle(h.data(2, structuredChunk({ kind: "message", offset: 2, role: "assistant", text: "done" })));
+  h.session.handle(h.data(3, "trailing raw\n"));
+  assert.deepEqual(h.writes, ["booting...\n", "trailing raw\n"], "raw chunks land on the terminal");
+  assert.deepEqual(
+    h.events.map((e) => e.kind),
+    ["turn", "message"],
+    "only the tagged chunks reach the structured sink",
+  );
+  assert.equal(h.session.nextOffset, 4);
+});
+
+test("a marker-tagged but malformed envelope falls back to raw bytes (byte-terminal), never the structured sink", () => {
+  // A chunk mentioning the marker but with an unknown/rejected body must be
+  // retained verbatim for byte-replay fidelity, not routed as a structured event.
+  const h = harness({ structured: true });
+  h.session.attach();
+  const malformed = JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: 1, kind: "message" }); // no text → decoder rejects
+  h.session.handle(h.data(0, malformed));
+  assert.deepEqual(h.writes, [malformed]);
+  assert.deepEqual(h.events, []);
+  assert.equal(h.session.nextOffset, 1);
+});
+
+test("a structured reconnect resumes from nextOffset — no dropped and no double-applied events", () => {
+  const h = harness({ structured: true });
+  h.session.attach();
+  h.session.handle(h.data(0, structuredChunk({ kind: "turn", offset: 0, index: 0 })));
+  h.session.handle(h.data(1, structuredChunk({ kind: "message", offset: 1, role: "assistant", text: "a" })));
+  assert.equal(h.session.nextOffset, 2);
+
+  // Socket drops; the client reconnects → re-attach resumes from offset 2.
+  h.session.attach();
+  assert.deepEqual(h.sent[1], { op: "subscribe", stream: "worker-1", from: 2, credit: 1024 });
+
+  // The hub replays the retained tail (re-sends offset 1) then continues. The
+  // replayed event is below nextOffset and must be dropped (no double-apply);
+  // the fresh event applies exactly once (no loss).
+  h.session.handle(h.data(1, structuredChunk({ kind: "message", offset: 1, role: "assistant", text: "a" })));
+  h.session.handle(h.data(2, structuredChunk({ kind: "message", offset: 2, role: "assistant", text: "b" })));
+  assert.deepEqual(
+    h.events.map((e) => (e.kind === "message" ? e.text : e.kind)),
+    ["turn", "a", "b"],
+    "no dropped and no duplicated structured events across the reconnect",
+  );
+  assert.equal(h.session.nextOffset, 3);
+});
+