@robota-sdk/agent-transport 3.0.0-beta.78 → 3.0.0-beta.81

package/src/__tests__/session-resume-bridge.test.ts

@@ -0,0 +1,406 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery, DEFAULT_MAX_PENDING_BYTES } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+import { SessionResumeBridge } from '../session-resume-bridge.js';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { IPersonalUsageReport } from '@robota-sdk/agent-interface-analytics';
+
+/**
+ * REMOTE-013 E4 TC-02 — the persistent SessionResumeBridge: a monotonic seq CONTINUOUS across a
+ * detach/attach (channel drop), gap output captured while detached and replayed on `resume`, `ack` freeing the
+ * buffer, and — the regression guard — the WS `createSessionMessageHandler` path stamping NO seq.
+ */
+
+function fakeSession(): {
+  session: IInteractiveSession;
+  fire: (event: string, arg: unknown) => void;
+} {
+  const handlers = new Map<string, (arg: unknown) => void>();
+  // ARCH-012: the published conformant double, overridden where this case needs behaviour. The
+  // hand-rolled partial it replaces was `as unknown as IInteractiveSession` — a cast that hid four
+  // missing members, so this suite proved things the real contract does not permit.
+  const session = createTestInteractiveSession({
+    on: ((event: string, handler: (arg: unknown) => void) =>
+      handlers.set(event, handler)) as IInteractiveSession['on'],
+    off: ((event: string) => {
+      handlers.delete(event);
+    }) as IInteractiveSession['off'],
+  });
+  return { session, fire: (event, arg) => handlers.get(event)?.(arg) };
+}
+
+function frames(sink: { calls: string[] }): { type: string; seq?: number; delta?: string }[] {
+  return sink.calls.map((c) => JSON.parse(c));
+}
+
+function sink(): TResumeSinkStub {
+  const calls: string[] = [];
+  return Object.assign((data: string) => void calls.push(data), { calls });
+}
+type TResumeSinkStub = ((data: string) => void) & { calls: string[] };
+const TEST_ATTACH_OPTIONS = { onDeliveryError: vi.fn() };
+
+describe('SessionResumeBridge (REMOTE-013 TC-02)', () => {
+  it('keeps remote surface attribution separate from the paired device id', async () => {
+    const base = fakeSession().session;
+    const submit = vi.fn().mockResolvedValue(undefined);
+    const session = Object.assign(base, { submit });
+    const bridge = new SessionResumeBridge({
+      session,
+      driverId: 'device-sha256',
+      surface: 'remote',
+    });
+    bridge.attach(sink(), TEST_ATTACH_OPTIONS);
+
+    bridge.onClientMessage(JSON.stringify({ type: 'submit', prompt: 'paired turn' }));
+    await vi.waitFor(() => expect(submit).toHaveBeenCalled());
+
+    expect(submit).toHaveBeenCalledWith('paired turn', undefined, undefined, {
+      driverId: 'device-sha256',
+      surface: 'remote',
+    });
+    bridge.dispose();
+  });
+
+  it('keeps host usage reporting reachable across the resume bridge', async () => {
+    const { session } = fakeSession();
+    const report = { schemaVersion: 1 } as IPersonalUsageReport;
+    const personalUsageReporter = vi.fn().mockResolvedValue(report);
+    const bridge = new SessionResumeBridge({ session, personalUsageReporter });
+    const output = sink();
+    bridge.attach(output, TEST_ATTACH_OPTIONS);
+
+    bridge.onClientMessage(
+      JSON.stringify({
+        type: 'get-personal-usage-report',
+        requestId: 'resume-usage',
+        period: '7d',
+        timezone: 'UTC',
+      }),
+    );
+    await vi.waitFor(() => expect(output.calls).toHaveLength(1));
+
+    expect(personalUsageReporter).toHaveBeenCalledWith({ period: '7d', timezone: 'UTC' });
+    expect(frames(output)[0]).toMatchObject({
+      type: 'personal_usage_report',
+      requestId: 'resume-usage',
+      report,
+    });
+    bridge.dispose();
+  });
+
+  it('stamps a monotonic seq and forwards live to the attached sink', () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    const s = sink();
+    bridge.attach(s, TEST_ATTACH_OPTIONS);
+    fire('text_delta', 'a');
+    fire('text_delta', 'b');
+    expect(frames(s).map((f) => f.seq)).toEqual([1, 2]);
+    expect(frames(s).map((f) => f.delta)).toEqual(['a', 'b']);
+    bridge.dispose();
+  });
+
+  it('the Issue-A guard: seq is CONTINUOUS across detach/attach; gap output is captured + replayed on resume', () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+
+    const s1 = sink();
+    bridge.attach(s1, TEST_ATTACH_OPTIONS);
+    fire('text_delta', 'a'); // seq 1 → s1
+    expect(frames(s1).map((f) => f.seq)).toEqual([1]);
+
+    // Channel drops.
+    bridge.detach();
+    fire('text_delta', 'b'); // seq 2 — buffered, NOT sent (no sink)
+    fire('text_delta', 'c'); // seq 3 — buffered
+    expect(s1.calls).toHaveLength(1); // s1 got nothing during the gap
+
+    // New channel after reconnect. The client last applied seq 1 → asks for the tail.
+    const s2 = sink();
+    bridge.attach(s2, TEST_ATTACH_OPTIONS);
+    expect(s2.calls).toHaveLength(0); // attach does NOT auto-replay
+    bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 1 }));
+
+    const replayed = frames(s2);
+    // seq did NOT reset to 1 on the new channel — the gap frames keep their original 2,3.
+    expect(replayed.map((f) => f.seq)).toEqual([2, 3]);
+    expect(replayed.map((f) => f.delta)).toEqual(['b', 'c']);
+    bridge.dispose();
+  });
+
+  it('reconnect hold (Issue-B): a LIVE frame emitted between attach and resume does not leapfrog the gap', () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    const s1 = sink();
+    bridge.attach(s1, TEST_ATTACH_OPTIONS);
+    fire('text_delta', 'a'); // seq 1 → client applies through 1
+
+    // Drop; gap frames buffered.
+    bridge.detach();
+    fire('text_delta', 'b'); // seq 2 (gap)
+    fire('text_delta', 'c'); // seq 3 (gap)
+
+    // Reconnect attach with awaitResume → live forwarding is HELD until resume flushes the tail.
+    const s2 = sink();
+    bridge.attach(s2, { ...TEST_ATTACH_OPTIONS, awaitResume: true });
+    fire('text_delta', 'd'); // seq 4 — emitted BEFORE the client's resume arrives; must NOT be sent yet
+    expect(s2.calls).toHaveLength(0); // held
+
+    bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 1 }));
+    // The client receives 2,3,4 IN ORDER (gap then the held live frame) — none lost, none reordered.
+    expect(frames(s2).map((f) => f.seq)).toEqual([2, 3, 4]);
+    expect(frames(s2).map((f) => f.delta)).toEqual(['b', 'c', 'd']);
+
+    // Hold released — a subsequent live frame flows immediately behind the flushed tail.
+    fire('text_delta', 'e'); // seq 5
+    expect(frames(s2).map((f) => f.seq)).toEqual([2, 3, 4, 5]);
+    bridge.dispose();
+  });
+
+  it('ack frees the buffer up to seq; a later resume replays only the newer tail', () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    const s = sink();
+    bridge.attach(s, TEST_ATTACH_OPTIONS);
+    fire('text_delta', 'a'); // 1
+    fire('text_delta', 'b'); // 2
+    fire('text_delta', 'c'); // 3
+    bridge.onClientMessage(JSON.stringify({ type: 'ack', seq: 2 })); // free 1,2
+
+    const s2 = sink();
+    bridge.detach();
+    bridge.attach(s2, TEST_ATTACH_OPTIONS);
+    bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 2 }));
+    expect(frames(s2).map((f) => f.seq)).toEqual([3]); // only the un-acked tail
+    bridge.dispose();
+  });
+
+  it('resume with a lastSeq older than the retained buffer sends resume_gap (no silent gap)', () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session, buffer: { maxFrames: 2 } });
+    const s = sink();
+    bridge.attach(s, TEST_ATTACH_OPTIONS);
+    fire('text_delta', 'a'); // 1 (evicted)
+    fire('text_delta', 'b'); // 2
+    fire('text_delta', 'c'); // 3 → buffer holds [2,3]
+    const s2 = sink();
+    bridge.detach();
+    bridge.attach(s2, TEST_ATTACH_OPTIONS);
+    bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 0 })); // saw nothing, 1 is gone
+    expect(frames(s2)).toEqual([{ type: 'resume_gap' }]);
+    bridge.dispose();
+  });
+
+  // CMD-004 Stage D — the bridge's single subscription requester-routes `ui_intent` with the
+  // LATE-BOUND driver id (`setDriverId` binds after pairing), so a skipped intent is never
+  // buffered and can never leak to this surface through a later `resume` replay.
+  it('requester-routes ui_intent by the late-bound driver id; foreign intents are never buffered', () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    const s = sink();
+    bridge.attach(s, TEST_ATTACH_OPTIONS);
+
+    // Not paired yet (no driver id): an intent attributed to another surface is skipped.
+    fire('ui_intent', { intent: { type: 'show-settings' }, requesterDriverId: 'device-9' });
+    expect(s.calls).toHaveLength(0);
+
+    bridge.setDriverId('device-9');
+    fire('ui_intent', { intent: { type: 'show-settings' }, requesterDriverId: 'device-9' });
+    expect(frames(s)).toEqual([
+      {
+        type: 'ui_intent',
+        event: { intent: { type: 'show-settings' }, requesterDriverId: 'device-9' },
+        seq: 1, // the skipped foreign intent consumed NO seq — it was routed out BEFORE buffering
+      },
+    ]);
+
+    // Another surface's intent stays invisible even across a reconnect replay.
+    fire('ui_intent', { intent: { type: 'show-plugin-manager' }, requesterDriverId: 'device-2' });
+    const s2 = sink();
+    bridge.detach();
+    bridge.attach(s2, TEST_ATTACH_OPTIONS);
+    bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+    expect(frames(s2).filter((f) => f.type === 'ui_intent')).toHaveLength(1); // only device-9's own
+
+    // Unattributed intents are unroutable → delivered (never silently dropped).
+    fire('ui_intent', { intent: { type: 'show-agent-switcher' } });
+    expect(frames(s2).at(-1)).toEqual({
+      type: 'ui_intent',
+      event: { intent: { type: 'show-agent-switcher' } },
+      seq: 2, // the device-2 intent consumed no seq either — routing precedes the buffer
+    });
+    bridge.dispose();
+  });
+
+  it('regression: the WS createSessionMessageHandler path stamps NO seq', () => {
+    const { session, fire } = fakeSession();
+    const sent: unknown[] = [];
+    const { cleanup } = createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery((m) => sent.push(m), vi.fn()),
+    });
+    fire('text_delta', 'a');
+    expect(sent).toEqual([{ type: 'text_delta', delta: 'a' }]); // no `seq` field
+    cleanup();
+  });
+
+  it('reports a WebRTC sink failure and detaches instead of swallowing it', () => {
+    const { session, fire } = fakeSession();
+    const failures: Array<{ message: string; event: string }> = [];
+    const bridge = new SessionResumeBridge({ session });
+    bridge.attach(
+      () => {
+        throw new Error('data channel closed');
+      },
+      {
+        onDeliveryError: (error, event) => {
+          failures.push({ message: error.message, event });
+          throw new Error('diagnostic callback failed');
+        },
+      },
+    );
+
+    fire('branch_event', {
+      kind: 'checkpoint_created',
+      checkpointId: 'turn-0001',
+      branchId: 'main',
+    });
+
+    expect(failures).toEqual([{ message: 'data channel closed', event: 'branch_event' }]);
+    expect(bridge.lastSeq).toBe(1); // retained for replay after the carrier reconnects
+    bridge.dispose();
+  });
+
+  // ARCH-030: the bridge's own string-level try/catch is gone; its only guard is the per-attachment
+  // outbound boundary. These three pin the semantics that used to be side effects of `detach()`.
+  describe('the attachment boundary (ARCH-030)', () => {
+    it('reports ONCE across a failing multi-frame replay, and the dropped frames survive', () => {
+      const { session, fire } = fakeSession();
+      const failures: Array<{ message: string; event: string }> = [];
+      const bridge = new SessionResumeBridge({ session });
+
+      // Three frames buffered while no channel is attached — the reconnect gap.
+      fire('text_delta', 'a');
+      fire('text_delta', 'b');
+      fire('text_delta', 'c');
+      expect(bridge.lastSeq).toBe(3);
+
+      bridge.attach(
+        () => {
+          throw new Error('data channel closed');
+        },
+        {
+          awaitResume: true,
+          onDeliveryError: (error, event) => failures.push({ message: error.message, event }),
+        },
+      );
+      bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+
+      // One report for the whole tail. Before the boundary this was one only because
+      // `reportDeliveryError` happened to `detach()` mid-loop; now it is the stated contract.
+      expect(failures).toEqual([{ message: 'data channel closed', event: 'text_delta' }]);
+
+      // Nothing was acked, so every frame is still replayable on the NEXT sink.
+      const healthy = sink();
+      bridge.attach(healthy, { awaitResume: true, onDeliveryError: vi.fn() });
+      bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+      expect(frames(healthy).map((f) => f.seq)).toEqual([1, 2, 3]);
+      expect(frames(healthy).map((f) => f.delta)).toEqual(['a', 'b', 'c']);
+      bridge.dispose();
+    });
+
+    it('ARCH-030: a replay burst stops when the budget closes the boundary, and the rest survives', () => {
+      // The replay-burst contract case. A reconnecting peer is handed the whole retained tail at
+      // once; if it stops reading part-way, the loop must stop rather than push the remainder into a
+      // carrier that is already over budget.
+      const { session, fire } = fakeSession();
+      const failures: Array<{ message: string; event: string }> = [];
+      const bridge = new SessionResumeBridge({ session });
+
+      for (const delta of ['a', 'b', 'c', 'd']) fire('text_delta', delta);
+      expect(bridge.lastSeq).toBe(4);
+
+      const written: string[] = [];
+      let pending = 0;
+      bridge.attach(
+        (data) => {
+          written.push(data);
+          // The peer reads nothing. This carrier is already holding a large backlog, so the second
+          // frame of the replay finds it past DEFAULT_MAX_PENDING_BYTES — the real default, not a
+          // budget invented for the test.
+          pending += DEFAULT_MAX_PENDING_BYTES;
+        },
+        {
+          awaitResume: true,
+          onDeliveryError: (error, event) => failures.push({ message: error.message, event }),
+          pendingBytes: () => pending,
+        },
+      );
+      bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+
+      // It stopped short rather than draining the tail into a carrier over its limit.
+      expect(written.length).toBeLessThan(4);
+      expect(failures).toHaveLength(1);
+      expect(failures[0]?.message).toContain('pending');
+
+      // And nothing was lost: the frames it did not push are still replayable on the next sink.
+      const healthy = sink();
+      bridge.attach(healthy, { awaitResume: true, onDeliveryError: vi.fn() });
+      bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+      expect(frames(healthy).map((f) => f.seq)).toEqual([1, 2, 3, 4]);
+      bridge.dispose();
+    });
+
+    it('a fresh attach un-latches the connection, and seq stays continuous across the failure', () => {
+      const { session, fire } = fakeSession();
+      const bridge = new SessionResumeBridge({ session });
+      bridge.attach(
+        () => {
+          throw new Error('data channel closed');
+        },
+        { onDeliveryError: vi.fn() },
+      );
+      fire('text_delta', 'a');
+
+      const second = sink();
+      const secondFailures: string[] = [];
+      bridge.attach(second, { onDeliveryError: (error) => secondFailures.push(error.message) });
+      fire('text_delta', 'b');
+
+      // The new attachment delivers: a latched boundary is not carried across `attach`.
+      expect(frames(second).map((f) => f.seq)).toEqual([2]);
+      expect(secondFailures).toEqual([]);
+      expect(bridge.lastSeq).toBe(2); // the failed frame still consumed its seq
+      bridge.dispose();
+    });
+
+    it('routes a reply to an inbound frame through the same boundary as the event fan-out', () => {
+      const handlers = new Map<string, (arg: unknown) => void>();
+      const session = createTestInteractiveSession({
+        on: ((event: string, handler: (arg: unknown) => void) =>
+          handlers.set(event, handler)) as IInteractiveSession['on'],
+        off: ((event: string) => {
+          handlers.delete(event);
+        }) as IInteractiveSession['off'],
+      });
+      const failures: Array<{ message: string; event: string }> = [];
+      const bridge = new SessionResumeBridge({ session });
+      bridge.attach(
+        () => {
+          throw new Error('data channel closed');
+        },
+        { onDeliveryError: (error, event) => failures.push({ message: error.message, event }) },
+      );
+
+      // A synchronous query reply — before ARCH-030 the bridge guarded this at the string level, and
+      // the handler path next to it did not guard it at all.
+      expect(() => bridge.onClientMessage(JSON.stringify({ type: 'get-executing' }))).not.toThrow();
+      expect(failures).toEqual([{ message: 'data channel closed', event: 'executing' }]);
+      bridge.dispose();
+    });
+  });
+});

package/src/__tests__/submit-prompt-shape.test.ts

@@ -0,0 +1,78 @@
+/**
+ * TRANS-008 (issue #2045) — a `submit` prompt that is not a string must not reach the session.
+ *
+ * `parseClientMessage` does `JSON.parse(data) as TClientMessage`, and the only guard in the submit
+ * handler is `if (!msg.prompt)`. That is a FALSY check, not a type check: `{}`, `[]` and `42` are
+ * truthy, so they pass it and reach `session.submit(input: string)`.
+ *
+ * Why this one field and not the other thirteen with payloads: the value does not stop at the
+ * session. `interactive-session-execution-controller.ts:249` does
+ * `emit('user_message', displayInput ?? input)`, `session-events.ts` classifies `user_message` as
+ * `'forwarded'` and delivers `{ type: 'user_message', content, … }` — declared `content: string` —
+ * to EVERY attached client, not only the sender. Both client cast sites (`ws-session-client.ts:66`,
+ * `rtc-responder-gate.ts:118`) accept it with `as TServerMessage`, so nothing on the receiving side
+ * rejects it either.
+ *
+ * So one unguarded field lets a client put a shape-invalid value into a typed frame delivered to its
+ * peers. The permission and resume paths were measured too and do NOT cross that way: `interpretApproval`
+ * compares by strict equality against a closed set and defaults to deny, and a malformed `ack`/`resume`
+ * seq degrades only the sender's own attachment.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TServerMessage } from '../wire-messages.js';
+
+function setup() {
+  const submit = vi.fn().mockResolvedValue({ turnId: 't1', completed: Promise.resolve() });
+  // The published conformant double, not a cast: a hand-rolled object asserted to be an
+  // `IInteractiveSession` is a partial re-implementation nothing checks against the real contract.
+  const session = Object.assign(createTestInteractiveSession(), { submit });
+  const sent: TServerMessage[] = [];
+  const { onMessage } = createSessionMessageHandler({
+    session,
+    deliver: createOutboundDelivery((msg) => sent.push(msg), vi.fn()),
+  });
+  return { submit, sent, onMessage };
+}
+
+describe('TRANS-008: a non-string submit prompt is refused at the ingress', () => {
+  it.each([
+    ['an object', {}],
+    ['an array', []],
+    ['a number', 42],
+    ['a boolean', true],
+  ])('refuses %s — it is truthy, so the falsy guard passes it', (_label, prompt) => {
+    const { submit, sent, onMessage } = setup();
+
+    onMessage(JSON.stringify({ type: 'submit', prompt }));
+
+    // The session must never see it: once it does, the value is re-emitted as `user_message` to
+    // every attached client inside a frame whose `content` is declared `string`.
+    expect(submit).not.toHaveBeenCalled();
+    expect(sent.some((msg) => msg.type === 'protocol_error')).toBe(true);
+  });
+
+  it('still refuses an EMPTY prompt, which the falsy guard already caught', () => {
+    // The control for the guard that exists. A type check that replaced it would otherwise let
+    // `''` through — a regression hidden by the new assertions above.
+    const { submit, sent, onMessage } = setup();
+
+    onMessage(JSON.stringify({ type: 'submit', prompt: '' }));
+
+    expect(submit).not.toHaveBeenCalled();
+    expect(sent.some((msg) => msg.type === 'protocol_error')).toBe(true);
+  });
+
+  it('still accepts a real string prompt, so the refusal is about shape and not about submitting', () => {
+    const { submit, onMessage } = setup();
+
+    onMessage(JSON.stringify({ type: 'submit', prompt: 'hello' }));
+
+    expect(submit).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/usage-report-carrier.test.ts

@@ -0,0 +1,98 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, it, expect, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+import type { TServerMessage } from '../wire-messages.js';
+import type { IUsageBySourceReport } from '@robota-sdk/agent-interface-analytics';
+
+/**
+ * SELFHOST-004 P5 (TC-08): the new `usage_report` TServerMessage variant carries the assembled
+ * trace/cost read-model (per-operation span timeline + cost-by-source) across the sidecar boundary.
+ * No pre-existing variant carries per-op `durationMs` or per-source `costUsd`; this test proves the
+ * carrier is well-typed AND survives JSON serialization (the WS stream is JSON) so the timeline/cost
+ * actually reaches the GUI — not assumed "free".
+ */
+describe('SELFHOST-004 TC-08 — usage_report server-message carrier', () => {
+  const report: IUsageBySourceReport = {
+    sessionId: 'sess-1',
+    totalTokens: 300,
+    promptTokens: 200,
+    completionTokens: 100,
+    costUsd: 0.0015,
+    costExact: true,
+    bySource: [
+      {
+        key: 'main:',
+        source: { scope: 'main', label: 'main thread' },
+        label: 'main thread',
+        promptTokens: 200,
+        completionTokens: 100,
+        totalTokens: 300,
+        turns: 1,
+        percentage: 100,
+        costUsd: 0.0015,
+        costExact: true,
+      },
+    ],
+    timeline: [
+      {
+        turnIndex: 0,
+        source: { scope: 'main', label: 'main thread' },
+        label: 'main thread',
+        spans: [
+          { spanId: 'span_a', op: 'read', durationMs: 5 },
+          { spanId: 'span_b', op: 'grep', durationMs: 7 },
+        ],
+        totalDurationMs: 12,
+      },
+    ],
+  };
+
+  it('is assignable to TServerMessage and carries per-op durationMs + per-source costUsd together', () => {
+    const message: TServerMessage = { type: 'usage_report', report };
+
+    // narrow by discriminant — the carrier’s payload is the assembled read-model
+    expect(message.type).toBe('usage_report');
+    if (message.type !== 'usage_report') throw new Error('unreachable');
+
+    // per-op timing rides the carrier (the datum no prior variant carried)
+    expect(message.report.timeline[0]?.spans.map((s) => s.durationMs)).toEqual([5, 7]);
+    // per-source cost rides the carrier
+    expect(message.report.bySource[0]?.costUsd).toBeCloseTo(0.0015, 6);
+    expect(message.report.costUsd).toBeCloseTo(0.0015, 6);
+  });
+
+  it('survives JSON round-trip (the WS stream) with the timeline + cost intact', () => {
+    const message: TServerMessage = { type: 'usage_report', report };
+
+    const wire = JSON.parse(JSON.stringify(message)) as TServerMessage;
+    expect(wire).toEqual(message);
+    if (wire.type !== 'usage_report') throw new Error('unreachable');
+    expect(wire.report.timeline[0]?.totalDurationMs).toBe(12);
+    expect(wire.report.bySource[0]?.costUsd).toBeCloseTo(0.0015, 6);
+  });
+
+  it('requests are expressible via the get-usage-report client message', () => {
+    // compile-time proof the request variant exists (the GUI asks for the report)
+    const req = { type: 'get-usage-report' } as const;
+    expect(req.type).toBe('get-usage-report');
+  });
+
+  it('routes the request through the host producer and delivers the report', async () => {
+    const sent: TServerMessage[] = [];
+    const reporter = vi.fn().mockReturnValue(report);
+    const session = createTestInteractiveSession();
+    const { onMessage } = createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+      usageReporter: reporter,
+    });
+
+    onMessage(JSON.stringify({ type: 'get-usage-report' }));
+    await Promise.resolve();
+
+    expect(reporter).toHaveBeenCalledWith(session);
+    expect(sent).toContainEqual({ type: 'usage_report', report });
+  });
+});

package/src/__tests__/ws-broadcast-events.test.ts

@@ -0,0 +1,84 @@
+/**
+ * CMD-004 Phase 2 Stage E — broadcast session events over the WS transport.
+ *
+ * The spec's final carriers: `session_renamed` and `history_cleared` are BROADCAST session events —
+ * every attached surface (including co-driving ones) receives them, so titles update and transcripts
+ * refresh everywhere. Unlike `ui_intent` (requester-routed), these are never filtered by driver id.
+ *
+ * Red-first evidence: against pre-Stage-E code neither event is forwarded by
+ * `subscribeSessionEvents` at all — a co-driving surface's title/transcript went stale.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TServerMessage } from '../wire-messages.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+type TEmittingSession = IInteractiveSession & {
+  _emit: (event: string, ...args: unknown[]) => void;
+};
+
+function createMockSession(): TEmittingSession {
+  const listeners = new Map<string, Set<(...args: unknown[]) => void>>();
+  return {
+    // ARCH-012: required. This double feeds `subscribeSessionEvents`, which calls it on every
+    // turn-authored event — omitting it throws the moment a case emits one.
+    getActiveDriverId: () => null,
+    on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }),
+    off: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      listeners.get(event)?.delete(handler);
+    }),
+    _emit: (event: string, ...args: unknown[]) => {
+      listeners.get(event)?.forEach((h) => h(...args));
+    },
+  } as unknown as TEmittingSession;
+}
+
+/** Two real WS handlers (surfaces) over ONE session — the co-driving topology. */
+function setupTwoSurfaces(): {
+  session: TEmittingSession;
+  sentA: TServerMessage[];
+  sentB: TServerMessage[];
+} {
+  const session = createMockSession();
+  const sentA: TServerMessage[] = [];
+  const sentB: TServerMessage[] = [];
+  createSessionMessageHandler({
+    session,
+    deliver: createOutboundDelivery((m) => sentA.push(m), vi.fn()),
+    driverId: 'device-A',
+  });
+  createSessionMessageHandler({
+    session,
+    deliver: createOutboundDelivery((m) => sentB.push(m), vi.fn()),
+    driverId: 'device-B',
+  });
+  return { session, sentA, sentB };
+}
+
+describe('CMD-004 Stage E — session_renamed / history_cleared broadcast to EVERY surface', () => {
+  it('session_renamed reaches both attached surfaces (titles update everywhere)', () => {
+    const { session, sentA, sentB } = setupTwoSurfaces();
+
+    session._emit('session_renamed', { name: 'Renamed Everywhere' });
+
+    const expected = { type: 'session_renamed', event: { name: 'Renamed Everywhere' } };
+    expect(sentA).toEqual([expected]);
+    expect(sentB).toEqual([expected]);
+  });
+
+  it('history_cleared reaches both attached surfaces (transcripts refresh everywhere)', () => {
+    const { session, sentA, sentB } = setupTwoSurfaces();
+
+    session._emit('history_cleared');
+
+    expect(sentA).toEqual([{ type: 'history_cleared' }]);
+    expect(sentB).toEqual([{ type: 'history_cleared' }]);
+  });
+});