@nanobpm/agentic 0.7.0 → 0.8.0

package/dist/cockpit/boot.d.ts

@@ -20,9 +20,11 @@
 import type { DemandSupplyReport } from "../demand/index.ts";
 import { type Scheduler, type SocketFactory } from "./relay-client.ts";
 import { type DocumentLike, type ElementLike } from "./render.ts";
-import { type TerminalSink } from "./terminal-session.ts";
+import { type StructuredSink, type TerminalSink } from "./terminal-session.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;
 export interface CockpitEnv {
@@ -36,6 +38,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}. */

package/dist/cockpit/boot.js

@@ -1,6 +1,7 @@
 import { isPosInt } from "../relay/index.js";
 import { RelayChannelClient } from "./relay-client.js";
 import { renderCockpit } from "./render.js";
+import { createStructuredSink } from "./structured-view.js";
 import { TerminalSession } from "./terminal-session.js";
 import { cockpitView } from "./view.js";
 const DEFAULT_REFRESH_MS = 2000;
@@ -8,6 +9,8 @@ class Cockpit {
     #env;
     #matrixRegion;
     #terminalHost;
+    #structuredHost;
+    #createStructured;
     #refreshMs;
     #setTimer;
     #clearTimer;
@@ -20,6 +23,9 @@ class Cockpit {
     // The currently mounted terminal, tracked so switching streams (and dispose)
     // tears down the prior xterm instance instead of leaking it + its listeners.
     #terminal;
+    // The currently mounted structured view, torn down alongside #terminal so a
+    // stream switch / dispose never leaks the prior worker's structured widget.
+    #structured;
     // 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.
@@ -64,6 +70,10 @@ class Cockpit {
                         this.#timeouts.delete(handle);
                     }
                 });
+        // 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();
@@ -81,6 +91,14 @@ class Cockpit {
         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);
@@ -157,11 +175,17 @@ class Cockpit {
         // 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;
             const client = new RelayChannelClient({
                 connect: this.#env.connectRelay,
@@ -175,6 +199,7 @@ class Cockpit {
             session = new TerminalSession({
                 stream,
                 sink,
+                structured,
                 send: (message) => client.sendRelay(message),
                 credit: this.#env.credit,
             });
@@ -194,6 +219,8 @@ class Cockpit {
         this.#drill = undefined;
         this.#terminal?.dispose?.();
         this.#terminal = undefined;
+        this.#structured?.dispose?.();
+        this.#structured = undefined;
     }
 }
 /** Boot the cockpit against an injected environment. Call {@link CockpitHandle.start} to poll. */

package/dist/cockpit/index.d.ts

@@ -21,7 +21,8 @@
  * Nothing here rides the Camunda-8 engine or its transport.
  */
 export { cockpitView, type CockpitLight, type CockpitNetworkRow, type CockpitTokenRow, type CockpitView, type SloStatus, } from "./view.ts";
-export { TerminalSession, type RelayInbound, type RelayOutbound, type RelaySend, type TerminalSessionOptions, type TerminalSink, } from "./terminal-session.ts";
+export { TerminalSession, type RelayInbound, type RelayOutbound, type RelaySend, type StructuredSink, type TerminalSessionOptions, type TerminalSink, } from "./terminal-session.ts";
 export { RelayChannelClient, type RawSocket, type RelayChannelClientOptions, type Scheduler, type SocketFactory, } from "./relay-client.ts";
 export { renderCockpit, type CockpitDom, type DocumentLike, type ElementLike, type RenderOptions, } from "./render.ts";
-export { bootCockpit, type CockpitEnv, type CockpitHandle, type CreateTerminal, type TimerHandle, } from "./boot.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/dist/cockpit/index.js

@@ -24,4 +24,5 @@ export { cockpitView, } from "./view.js";
 export { TerminalSession, } from "./terminal-session.js";
 export { RelayChannelClient, } from "./relay-client.js";
 export { renderCockpit, } from "./render.js";
+export { createStructuredSink, renderStructured, } from "./structured-view.js";
 export { bootCockpit, } from "./boot.js";

package/dist/cockpit/structured-view.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 } from "../transcript/index.ts";
+import type { DocumentLike, ElementLike } from "./render.ts";
+import type { StructuredSink } from "./terminal-session.ts";
+/**
+ * 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 declare function renderStructured(host: ElementLike, doc: DocumentLike, view: DerivedView): void;
+/** 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 declare function createStructuredSink(host: ElementLike, doc: DocumentLike): StructuredTerminal;

package/dist/cockpit/structured-view.js

@@ -0,0 +1,106 @@
+/**
+ * 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 { deriveView } from "../transcript/index.js";
+function el(doc, tag, className, text) {
+    const node = doc.createElement(tag);
+    if (className !== undefined)
+        node.className = className;
+    if (text !== undefined)
+        node.textContent = text;
+    return node;
+}
+function toolCard(doc, tool) {
+    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, turn) {
+    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, doc, view) {
+    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);
+}
+/**
+ * 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, doc) {
+    const events = [];
+    // 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) {
+            events.push(event);
+            renderStructured(host, doc, deriveView(events));
+        },
+        dispose() {
+            events.length = 0;
+            host.replaceChildren();
+        },
+    };
+}

package/dist/cockpit/terminal-session.d.ts

@@ -19,8 +19,24 @@
  *  - inbound  `{ op: "subscribed", stream, gap, nextOffset }` — the resume ack
  *             (`gap: boolean` — the S5 wire flags whether chunks aged out),
  *  - inbound  {@link RelayPayload} `{ stream, offset, chunk }` — a data chunk.
+ *
+ * ## Structured (ACP) vs. raw streams
+ *
+ * A relay stream is either a **raw** byte stream (PTY output — arbitrary bytes) or
+ * a **structured** ACP stream whose chunks are {@link TRANSCRIPT_EVENT_MARKER}-tagged
+ * JSON envelopes (the transcript-event vocabulary) riding the *same*
+ * `{ stream, offset, chunk }` frames. The session classifies **each chunk** through
+ * the one canonical {@link parseTranscriptEvent} — detection is on the marker tag,
+ * never a guess — and routes a decoded structured event to the {@link StructuredSink}
+ * (the derived structured renderer) while writing a raw chunk verbatim to the byte
+ * {@link TerminalSink}. A mixed stream that starts raw and only later carries tagged
+ * chunks is handled per-chunk, so each chunk lands on the right surface. Routing does
+ * not touch the resume machinery: `nextOffset` advances identically whichever surface
+ * a chunk is applied to, so resume-from-offset neither loses nor double-applies
+ * structured events across a reconnect exactly as for raw output.
  */
 import type { RelayPayload } from "../protocol/index.ts";
+import { type TranscriptEvent } from "../transcript/index.ts";
 /** The terminal sink the session writes decoded output to (xterm.js satisfies this). */
 export interface TerminalSink {
     /** Append a chunk of terminal output. */
@@ -28,6 +44,19 @@ export interface TerminalSink {
     /** Tear down the underlying terminal widget and its listeners, if any. */
     dispose?(): void;
 }
+/**
+ * The structured sink a session routes decoded transcript events to when the stream
+ * is a structured ACP stream (marker-tagged chunks). It receives the offset-keyed,
+ * immutable {@link TranscriptEvent} the one canonical {@link parseTranscriptEvent}
+ * derived from the chunk — never raw JSON — so the derived structured renderer folds
+ * over typed events rather than pretty-printing bytes.
+ */
+export interface StructuredSink {
+    /** Apply one decoded structured transcript event (in offset order). */
+    event(event: TranscriptEvent): void;
+    /** Tear down the underlying structured widget and its listeners, if any. */
+    dispose?(): void;
+}
 /** An outbound relay message the session asks its transport to send. */
 export type RelayOutbound = {
     readonly op: "subscribe";
@@ -50,8 +79,15 @@ export type RelaySend = (message: RelayOutbound) => void;
 export interface TerminalSessionOptions {
     /** The relay stream id (one worker's terminal). */
     readonly stream: string;
-    /** Where decoded output is written. */
+    /** Where decoded raw output is written. */
     readonly sink: TerminalSink;
+    /**
+     * Where decoded structured transcript events are routed when the stream is a
+     * structured ACP stream (marker-tagged chunks). Omit for a pure byte-terminal:
+     * without it every chunk — even a marker-tagged one — is written verbatim to
+     * {@link sink}, preserving the legacy raw-only behaviour.
+     */
+    readonly structured?: StructuredSink;
     /** Emits outbound relay messages. */
     readonly send: RelaySend;
     /** Bulk credit requested on each (re)subscribe. Default 1024. */

package/dist/cockpit/terminal-session.js

@@ -1,4 +1,5 @@
 import { addSafeInt, isNonNegInt, isPosInt } from "../relay/index.js";
+import { parseTranscriptEvent } from "../transcript/index.js";
 const DEFAULT_CREDIT = 1024;
 function isRelayData(message) {
     return !("op" in message);
@@ -11,6 +12,7 @@ function isRelayData(message) {
 export class TerminalSession {
     #stream;
     #sink;
+    #structured;
     #send;
     #credit;
     #onGap;
@@ -21,6 +23,7 @@ export class TerminalSession {
     constructor(options) {
         this.#stream = options.stream;
         this.#sink = options.sink;
+        this.#structured = options.structured;
         this.#send = options.send;
         this.#credit = options.credit ?? DEFAULT_CREDIT;
         if (!isPosInt(this.#credit)) {
@@ -84,18 +87,39 @@ export class TerminalSession {
         // re-deliver the boundary chunk; anything we have already applied is dropped.
         if (data.offset < this.#nextOffset)
             return;
-        // Compute the next resume point BEFORE writing so the apply is atomic: a
+        // Compute the next resume point BEFORE applying so the apply is atomic: a
         // chunk at Number.MAX_SAFE_INTEGER makes addSafeInt throw, and it must throw
-        // before we touch the sink — otherwise the chunk is written but #nextOffset
+        // before we touch either sink — otherwise the chunk is applied but #nextOffset
         // is not advanced, leaving a partially-applied state that re-delivers (and
         // so duplicates) the chunk on reconnect. Advancing via addSafeInt also fails
         // fast rather than overflowing into an unsafe nextOffset — that value would
         // later be echoed in subscribe.from and lose precision on any JSON
         // round-trip, silently corrupting resume semantics.
         const nextOffset = addSafeInt(data.offset, 1, "nextOffset");
-        this.#sink.write(data.chunk);
+        this.#apply(data);
         this.#nextOffset = nextOffset;
     }
+    /**
+     * Route one already-de-duplicated data chunk to the right surface. Classify it
+     * through the ONE canonical {@link parseTranscriptEvent}: a marker-tagged, known
+     * envelope decodes to a typed event and (when a {@link StructuredSink} is wired)
+     * is routed there — the derived structured renderer — instead of dumping raw JSON
+     * into the byte-terminal; anything else (raw bytes, non-JSON, an untagged or
+     * malformed envelope) falls back to `stream-chunk` and is written verbatim to the
+     * byte {@link TerminalSink}, so a legacy/raw or mixed stream renders exactly as
+     * before. With no structured sink the parse is skipped entirely, keeping the
+     * raw-only path byte-identical to a pure byte-terminal.
+     */
+    #apply(data) {
+        if (this.#structured !== undefined) {
+            const event = parseTranscriptEvent({ offset: data.offset, chunk: data.chunk });
+            if (event.kind !== "stream-chunk") {
+                this.#structured.event(event);
+                return;
+            }
+        }
+        this.#sink.write(data.chunk);
+    }
     #onSubscribed(gap, nextOffset) {
         // Validate the ack's resume point exactly as the constructor validates
         // `from`: `nextOffset` is echoed back into subscribe.from on the next

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/agentic",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The Nano agentic protocol (ADR 0056): one app-tier channel carrying agent presence/registry, demand×supply, a shared blackboard and live terminal relay — with the wire contract, channel/hub, family modules and the operator cockpit, as subpath exports.",
   "license": "Apache-2.0",
   "type": "module",

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);
+});
+

package/src/cockpit/terminal-session.ts

@@ -19,9 +19,25 @@
  *  - inbound  `{ op: "subscribed", stream, gap, nextOffset }` — the resume ack
  *             (`gap: boolean` — the S5 wire flags whether chunks aged out),
  *  - inbound  {@link RelayPayload} `{ stream, offset, chunk }` — a data chunk.
+ *
+ * ## Structured (ACP) vs. raw streams
+ *
+ * A relay stream is either a **raw** byte stream (PTY output — arbitrary bytes) or
+ * a **structured** ACP stream whose chunks are {@link TRANSCRIPT_EVENT_MARKER}-tagged
+ * JSON envelopes (the transcript-event vocabulary) riding the *same*
+ * `{ stream, offset, chunk }` frames. The session classifies **each chunk** through
+ * the one canonical {@link parseTranscriptEvent} — detection is on the marker tag,
+ * never a guess — and routes a decoded structured event to the {@link StructuredSink}
+ * (the derived structured renderer) while writing a raw chunk verbatim to the byte
+ * {@link TerminalSink}. A mixed stream that starts raw and only later carries tagged
+ * chunks is handled per-chunk, so each chunk lands on the right surface. Routing does
+ * not touch the resume machinery: `nextOffset` advances identically whichever surface
+ * a chunk is applied to, so resume-from-offset neither loses nor double-applies
+ * structured events across a reconnect exactly as for raw output.
  */
 import type { RelayPayload } from "../protocol/index.ts";
 import { addSafeInt, isNonNegInt, isPosInt } from "../relay/index.ts";
+import { type TranscriptEvent, parseTranscriptEvent } from "../transcript/index.ts";
 
 /** The terminal sink the session writes decoded output to (xterm.js satisfies this). */
 export interface TerminalSink {
@@ -31,6 +47,20 @@ export interface TerminalSink {
   dispose?(): void;
 }
 
+/**
+ * The structured sink a session routes decoded transcript events to when the stream
+ * is a structured ACP stream (marker-tagged chunks). It receives the offset-keyed,
+ * immutable {@link TranscriptEvent} the one canonical {@link parseTranscriptEvent}
+ * derived from the chunk — never raw JSON — so the derived structured renderer folds
+ * over typed events rather than pretty-printing bytes.
+ */
+export interface StructuredSink {
+  /** Apply one decoded structured transcript event (in offset order). */
+  event(event: TranscriptEvent): void;
+  /** Tear down the underlying structured widget and its listeners, if any. */
+  dispose?(): void;
+}
+
 /** An outbound relay message the session asks its transport to send. */
 export type RelayOutbound =
   | { readonly op: "subscribe"; readonly stream: string; readonly from: number; readonly credit: number }
@@ -47,8 +77,15 @@ export type RelaySend = (message: RelayOutbound) => void;
 export interface TerminalSessionOptions {
   /** The relay stream id (one worker's terminal). */
   readonly stream: string;
-  /** Where decoded output is written. */
+  /** Where decoded raw output is written. */
   readonly sink: TerminalSink;
+  /**
+   * Where decoded structured transcript events are routed when the stream is a
+   * structured ACP stream (marker-tagged chunks). Omit for a pure byte-terminal:
+   * without it every chunk — even a marker-tagged one — is written verbatim to
+   * {@link sink}, preserving the legacy raw-only behaviour.
+   */
+  readonly structured?: StructuredSink;
   /** Emits outbound relay messages. */
   readonly send: RelaySend;
   /** Bulk credit requested on each (re)subscribe. Default 1024. */
@@ -73,6 +110,7 @@ function isRelayData(message: RelayInbound): message is RelayPayload {
 export class TerminalSession {
   readonly #stream: string;
   readonly #sink: TerminalSink;
+  readonly #structured: StructuredSink | undefined;
   readonly #send: RelaySend;
   readonly #credit: number;
   readonly #onGap: TerminalSessionOptions["onGap"];
@@ -84,6 +122,7 @@ export class TerminalSession {
   constructor(options: TerminalSessionOptions) {
     this.#stream = options.stream;
     this.#sink = options.sink;
+    this.#structured = options.structured;
     this.#send = options.send;
     this.#credit = options.credit ?? DEFAULT_CREDIT;
     if (!isPosInt(this.#credit)) {
@@ -152,19 +191,41 @@ export class TerminalSession {
     // Idempotent apply: a reconnect resubscribes from nextOffset, so the hub may
     // re-deliver the boundary chunk; anything we have already applied is dropped.
     if (data.offset < this.#nextOffset) return;
-    // Compute the next resume point BEFORE writing so the apply is atomic: a
+    // Compute the next resume point BEFORE applying so the apply is atomic: a
     // chunk at Number.MAX_SAFE_INTEGER makes addSafeInt throw, and it must throw
-    // before we touch the sink — otherwise the chunk is written but #nextOffset
+    // before we touch either sink — otherwise the chunk is applied but #nextOffset
     // is not advanced, leaving a partially-applied state that re-delivers (and
     // so duplicates) the chunk on reconnect. Advancing via addSafeInt also fails
     // fast rather than overflowing into an unsafe nextOffset — that value would
     // later be echoed in subscribe.from and lose precision on any JSON
     // round-trip, silently corrupting resume semantics.
     const nextOffset = addSafeInt(data.offset, 1, "nextOffset");
-    this.#sink.write(data.chunk);
+    this.#apply(data);
     this.#nextOffset = nextOffset;
   }
 
+  /**
+   * Route one already-de-duplicated data chunk to the right surface. Classify it
+   * through the ONE canonical {@link parseTranscriptEvent}: a marker-tagged, known
+   * envelope decodes to a typed event and (when a {@link StructuredSink} is wired)
+   * is routed there — the derived structured renderer — instead of dumping raw JSON
+   * into the byte-terminal; anything else (raw bytes, non-JSON, an untagged or
+   * malformed envelope) falls back to `stream-chunk` and is written verbatim to the
+   * byte {@link TerminalSink}, so a legacy/raw or mixed stream renders exactly as
+   * before. With no structured sink the parse is skipped entirely, keeping the
+   * raw-only path byte-identical to a pure byte-terminal.
+   */
+  #apply(data: RelayPayload): void {
+    if (this.#structured !== undefined) {
+      const event = parseTranscriptEvent({ offset: data.offset, chunk: data.chunk });
+      if (event.kind !== "stream-chunk") {
+        this.#structured.event(event);
+        return;
+      }
+    }
+    this.#sink.write(data.chunk);
+  }
+
   #onSubscribed(gap: boolean, nextOffset: number): void {
     // Validate the ack's resume point exactly as the constructor validates
     // `from`: `nextOffset` is echoed back into subscribe.from on the next