@robota-sdk/agent-transport 3.0.0-beta.82 → 3.0.0-beta.83

package/src/__tests__/session-message-handler-observe.test.ts

@@ -0,0 +1,193 @@
+/**
+ * The read-only `observe` role: an observer reads the session's own conversation and state, never
+ * counts as a surface that can answer a prompt, and cannot submit, answer, or control anything.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ATTACHED_SURFACE_MAX_PENDING_BYTES,
+  createOutboundDelivery,
+} from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+type TListener = (...args: unknown[]) => void;
+
+function createSession(): IInteractiveSession & {
+  emit: (event: string, ...args: unknown[]) => void;
+  listenerCount: (event: string) => number;
+} {
+  const listeners = new Map<string, Set<TListener>>();
+  const session = createTestInteractiveSession({
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    executeCommand: vi.fn(),
+    resolvePermission: vi.fn(),
+    resolveAsk: vi.fn(),
+    cancelBackgroundTask: vi.fn(),
+    closeBackgroundTask: vi.fn(),
+    sendBackgroundTask: vi.fn(),
+    getMessages: vi.fn().mockReturnValue([{ role: 'user', content: 'hi' }]),
+    isExecuting: vi.fn().mockReturnValue(true),
+    on: ((event: string, handler: TListener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: TListener) => {
+      listeners.get(event)?.delete(handler);
+    }) as IInteractiveSession['off'],
+  });
+  return Object.assign(session, {
+    emit: (event: string, ...args: unknown[]) => {
+      listeners.get(event)?.forEach((handler) => handler(...args));
+    },
+    listenerCount: (event: string) => listeners.get(event)?.size ?? 0,
+  });
+}
+
+function attach(
+  session: IInteractiveSession,
+  role?: 'drive' | 'observe',
+): { sent: TServerMessage[]; send: (message: TClientMessage) => void; cleanup: () => void } {
+  const sent: TServerMessage[] = [];
+  const { onMessage, cleanup } = createSessionMessageHandler({
+    session,
+    deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+    driverId: role === 'observe' ? 'attach:2' : 'attach:1',
+    ...(role === undefined ? {} : { role }),
+  });
+  return { sent, send: (message) => onMessage(JSON.stringify(message)), cleanup };
+}
+
+const MUTATING: readonly TClientMessage[] = [
+  { type: 'submit', prompt: 'hello' },
+  { type: 'command', name: 'exit' },
+  { type: 'abort' },
+  { type: 'cancel-queue' },
+  { type: 'cancel-background-task', taskId: 't1' },
+  { type: 'close-background-task', taskId: 't1' },
+  { type: 'send-background-task', taskId: 't1', input: { prompt: 'x' } },
+  { type: 'permission-response', id: 'p1', result: true },
+  { type: 'ask-response', id: 'a1', response: { type: 'answer', values: ['React'] } } as TClientMessage,
+  { type: 'get-personal-usage-report', requestId: 'r1', period: '7d', timezone: 'UTC' },
+  { type: 'get-stored-session-usage-report', requestId: 'r2', sessionId: 'other' },
+];
+
+describe('observe role', () => {
+  it('refuses every mutating or cross-session message with protocol_error and touches nothing', () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    for (const message of MUTATING) {
+      observer.sent.length = 0;
+      observer.send(message);
+      expect(observer.sent).toEqual([
+        { type: 'protocol_error', message: `Not permitted for an observer: ${message.type}` },
+      ]);
+    }
+    expect(session.submit).not.toHaveBeenCalled();
+    expect(session.executeCommand).not.toHaveBeenCalled();
+    expect(session.abort).not.toHaveBeenCalled();
+    expect(session.cancelQueue).not.toHaveBeenCalled();
+    expect(session.cancelBackgroundTask).not.toHaveBeenCalled();
+    expect(session.closeBackgroundTask).not.toHaveBeenCalled();
+    expect(session.sendBackgroundTask).not.toHaveBeenCalled();
+    expect(session.resolvePermission).not.toHaveBeenCalled();
+    expect(session.resolveAsk).not.toHaveBeenCalled();
+  });
+
+  it('keeps the read queries for this session', () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    observer.send({ type: 'get-messages' });
+    observer.send({ type: 'get-executing' });
+    expect(observer.sent).toEqual([
+      { type: 'messages', messages: [{ role: 'user', content: 'hi' }] },
+      { type: 'executing', executing: true },
+    ]);
+  });
+
+  it('#3186: reads the session status and the command catalog, which every client shows', () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    observer.send({ type: 'get-status' });
+    observer.send({ type: 'get-commands' });
+    expect(observer.sent).toEqual([
+      { type: 'session_status', status: session.getStatusSnapshot() },
+      { type: 'commands', commands: [], skills: [] },
+    ]);
+  });
+
+  it('never subscribes to prompt events, so it does not count as a surface that can answer', () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    expect(session.listenerCount('permission_request')).toBe(0);
+    expect(session.listenerCount('ask_request')).toBe(0);
+    expect(session.listenerCount('prompt_resolved')).toBe(1);
+    expect(session.listenerCount('text_delta')).toBe(1);
+    session.emit('permission_request', { id: 'p1', toolName: 'Bash', toolArgs: {} });
+    session.emit('ask_request', { id: 'a1', request: { id: 'r', title: 'Pick' } });
+    session.emit('prompt_resolved', { id: 'p1' });
+    expect(observer.sent).toEqual([{ type: 'prompt_resolved', event: { id: 'p1' } }]);
+    observer.cleanup();
+    expect(session.listenerCount('prompt_resolved')).toBe(0);
+  });
+
+  it('cannot answer a prompt that a drive surface holds', () => {
+    const session = createSession();
+    const drive = attach(session, 'drive');
+    const observer = attach(session, 'observe');
+    session.emit('permission_request', { id: 'p1', toolName: 'Bash', toolArgs: {} });
+    expect(drive.sent).toContainEqual({
+      type: 'permission_request',
+      event: { id: 'p1', toolName: 'Bash', toolArgs: {} },
+    });
+    observer.send({ type: 'permission-response', id: 'p1', result: true });
+    expect(session.resolvePermission).not.toHaveBeenCalled();
+    drive.send({ type: 'permission-response', id: 'p1', result: false });
+    expect(session.resolvePermission).toHaveBeenCalledExactlyOnceWith('p1', false, 'attach:1');
+  });
+
+  it('leaves the drive role unchanged', () => {
+    const session = createSession();
+    const drive = attach(session);
+    expect(session.listenerCount('permission_request')).toBe(1);
+    expect(session.listenerCount('ask_request')).toBe(1);
+    drive.send({ type: 'abort' });
+    drive.send({ type: 'permission-response', id: 'p1', result: true });
+    expect(session.abort).toHaveBeenCalledTimes(1);
+    expect(session.resolvePermission).toHaveBeenCalledExactlyOnceWith('p1', true, 'attach:1');
+    expect(drive.sent).toEqual([]);
+  });
+
+  it('disconnects an observer that stops reading while the session keeps streaming to others', () => {
+    const session = createSession();
+    const drive = attach(session, 'drive');
+    let pending = 0;
+    const onDeliveryError = vi.fn();
+    const received: TServerMessage[] = [];
+    createSessionMessageHandler({
+      session,
+      role: 'observe',
+      deliver: createOutboundDelivery(
+        (message) => {
+          received.push(message);
+          pending += 64 * 1024;
+        },
+        onDeliveryError,
+        () => pending,
+        ATTACHED_SURFACE_MAX_PENDING_BYTES,
+      ),
+    });
+    for (let index = 0; index < 64; index++) {
+      expect(() => session.emit('text_delta', `delta ${index}`)).not.toThrow();
+    }
+    expect(onDeliveryError).toHaveBeenCalledTimes(1);
+    expect(received.length).toBeLessThan(64);
+    expect(drive.sent.filter((message) => message.type === 'text_delta')).toHaveLength(64);
+  });
+});

package/src/__tests__/session-message-handler.test.ts

@@ -10,6 +10,7 @@ import { createSessionMessageHandler } from '../session-message-handler.js';
 import { PROTOCOL_SESSION_EVENT_CLASSIFICATION } from '../session-events.js';
 import type { TServerMessage } from '../wire-messages.js';
 import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { ICommandListEntry } from '@robota-sdk/agent-interface-command';
 import type {
   IBackgroundJobGroupState,
   IExecutionWorkspaceEvent,
@@ -157,6 +158,35 @@ describe('WebSocket Transport Handler', () => {
     expect(sent[0]!.type).toBe('context');
   });
 
+  it('#3186: get-commands sends the commands and skills a client can offer', () => {
+    const { onMessage, session, sent } = setup();
+    const command: ICommandListEntry = {
+      name: 'help',
+      description: 'Show commands',
+      modelInvocable: false,
+      runner: 'runtime',
+    };
+    const skill = {
+      name: 'parity-demo',
+      description: 'Demo',
+      source: 'project',
+      modelInvocable: true,
+      userInvocable: true,
+    };
+    Object.assign(session, {
+      listCommands: vi.fn().mockReturnValue([command]),
+      listSkills: vi.fn().mockReturnValue([skill]),
+    });
+    onMessage(JSON.stringify({ type: 'get-commands' }));
+    expect(sent).toEqual([{ type: 'commands', commands: [command], skills: [skill] }]);
+  });
+
+  it('#3186: get-status sends the session status snapshot', () => {
+    const { onMessage, session, sent } = setup();
+    onMessage(JSON.stringify({ type: 'get-status' }));
+    expect(sent).toEqual([{ type: 'session_status', status: session.getStatusSnapshot() }]);
+  });
+
   it('get-executing sends executing status', () => {
     const { onMessage, sent } = setup();
     onMessage(JSON.stringify({ type: 'get-executing' }));
@@ -166,7 +196,35 @@ describe('WebSocket Transport Handler', () => {
   it('get-pending sends pending prompt', () => {
     const { onMessage, sent } = setup();
     onMessage(JSON.stringify({ type: 'get-pending' }));
-    expect(sent[0]).toEqual({ type: 'pending', pending: null });
+    expect(sent[0]).toEqual({ type: 'pending', pending: null, pendingCount: 0 });
+  });
+
+  it('#3189: answers a submit with the queue once the prompt is taken, so a queued prompt shows', async () => {
+    const { onMessage, sent, session } = setup();
+    const mock = session as unknown as {
+      submit: ReturnType<typeof vi.fn>;
+      getPendingPrompt: ReturnType<typeof vi.fn>;
+      getPendingCount: ReturnType<typeof vi.fn>;
+    };
+    let queue: () => void = () => undefined;
+    // A turn is running: the session queues the prompt only after its own initialization yields.
+    mock.submit.mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          queue = () => {
+            mock.getPendingPrompt.mockReturnValue('follow-up');
+            mock.getPendingCount.mockReturnValue(1);
+            resolve();
+          };
+        }),
+    );
+    onMessage(JSON.stringify({ type: 'submit', prompt: 'follow-up' }));
+    // A `get-pending` sent beside the submit is answered before the prompt is queued.
+    onMessage(JSON.stringify({ type: 'get-pending' }));
+    expect(sent).toEqual([{ type: 'pending', pending: null, pendingCount: 0 }]);
+    queue();
+    await new Promise((r) => setTimeout(r, 0));
+    expect(sent.at(-1)).toEqual({ type: 'pending', pending: 'follow-up', pendingCount: 1 });
   });
 
   it('get-background-tasks sends current background task list', () => {
@@ -447,6 +505,29 @@ describe('WebSocket Transport Handler', () => {
     expect(sent).toEqual([{ type: 'protocol_error', message: 'command failed' }]);
   });
 
+  it("#3189: echoes a command's requestId on its result and on its failure, and on nothing else", async () => {
+    const { onMessage, sent, session } = setup();
+    const { executeCommand, submit } = session as unknown as {
+      executeCommand: ReturnType<typeof vi.fn>;
+      submit: ReturnType<typeof vi.fn>;
+    };
+    executeCommand.mockResolvedValueOnce({ message: 'done', success: true });
+    executeCommand.mockRejectedValueOnce(new Error('command failed'));
+    submit.mockRejectedValueOnce(new Error('A turn is running.'));
+    onMessage(JSON.stringify({ type: 'command', name: 'clear', requestId: 'c1' }));
+    onMessage(JSON.stringify({ type: 'command', name: 'broken', requestId: 'c2' }));
+    onMessage(JSON.stringify({ type: 'submit', prompt: 'hello' }));
+    await new Promise((r) => setTimeout(r, 10));
+    expect(sent).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: 'command_result', name: 'clear', requestId: 'c1' }),
+        { type: 'protocol_error', message: 'command failed', requestId: 'c2' },
+        { type: 'protocol_error', message: 'A turn is running.' },
+      ]),
+    );
+    expect(sent).toHaveLength(3);
+  });
+
   it('forwards InteractiveSession events to client', () => {
     const { session, sent } = setup();
     (session as unknown as { _emit: (e: string, ...args: unknown[]) => void })._emit(

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

@@ -81,4 +81,14 @@ describe('CMD-004 Stage E — session_renamed / history_cleared broadcast to EVE
     expect(sentA).toEqual([{ type: 'history_cleared' }]);
     expect(sentB).toEqual([{ type: 'history_cleared' }]);
   });
+
+  it('#3189: session_switched reaches both attached surfaces (each re-reads the new session)', () => {
+    const { session, sentA, sentB } = setupTwoSurfaces();
+
+    session._emit('session_switched', { sessionId: 'session-2' });
+
+    const expected = { type: 'session_switched', event: { sessionId: 'session-2' } };
+    expect(sentA).toEqual([expected]);
+    expect(sentB).toEqual([expected]);
+  });
 });

package/src/client.ts

@@ -6,4 +6,12 @@ export {
   decodeServerMessage,
 } from './message-decoders.js';
 export type { TMessageDecodeResult } from './message-decoders.js';
-export type { TClientMessage, TServerMessage, TSeqServerMessage } from './wire-messages.js';
+// The one list of messages an observer may send: the host refuses the rest, a client sends no others.
+export { isObserverMessageType } from './observer-messages.js';
+export type {
+  IWireHistoryEntry,
+  TClientMessage,
+  TServerMessage,
+  TSeqServerMessage,
+  TWireExecutionResult,
+} from './wire-messages.js';

package/src/index.ts

@@ -33,9 +33,13 @@
  */
 
 export { createSessionMessageHandler } from './session-message-handler.js';
-export type { ISessionMessageHandlerOptions } from './session-message-handler.js';
+export type {
+  ISessionMessageHandlerOptions,
+  TSessionSurfaceRole,
+} from './session-message-handler.js';
 // ARCH-030: the connection-scoped outbound delivery boundary every carrier builds and passes down.
 export {
+  ATTACHED_SURFACE_MAX_PENDING_BYTES,
   createOutboundDelivery,
   createPendingStallClock,
   isOverPendingBudget,
@@ -48,9 +52,17 @@ export type {
   TOutboundDeliver,
 } from './outbound-delivery.js';
 export { PROTOCOL_SESSION_EVENT_CLASSIFICATION } from './session-events.js';
+// The one list of messages an observer may send: the host refuses the rest, a client sends no others.
+export { isObserverMessageType } from './observer-messages.js';
 export type { TProtocolSessionEventClassification } from './session-events.js';
 export type { IProtocolSession } from './protocol-session.js';
-export type { TClientMessage, TServerMessage, TSeqServerMessage } from './wire-messages.js';
+export type {
+  IWireHistoryEntry,
+  TClientMessage,
+  TServerMessage,
+  TSeqServerMessage,
+  TWireExecutionResult,
+} from './wire-messages.js';
 // Issue #2045: the owner-side runtime decoders; carriers implement `raw → decodeFrame → typed`.
 export {
   MAX_INBOUND_FRAME_BYTES,

package/src/loop-control-messages.ts

@@ -0,0 +1,34 @@
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TClientMessage } from './wire-messages.js';
+
+type TLoopControlMessage = Extract<TClientMessage, { type: 'stop-waiting-loop' }>;
+
+export function isLoopControlMessage(msg: TClientMessage): msg is TLoopControlMessage {
+  return msg.type === 'stop-waiting-loop';
+}
+
+/**
+ * Stop the self-paced loop that is waiting for its next wake. The session decides which loop, if
+ * any; the reply carries its outcome, and a session that throws is reported as a failed stop.
+ */
+export function handleLoopControlMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TLoopControlMessage,
+): void {
+  const { requestId } = msg;
+  session.stopWaitingSelfPacedLoop().then(
+    (outcome) => deliver({ type: 'waiting_loop_stop', requestId, outcome }),
+    (error: unknown) =>
+      deliver({
+        type: 'waiting_loop_stop',
+        requestId,
+        outcome: { kind: 'failed', message: errorMessage(error) },
+      }),
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/message-decoders.ts

@@ -14,6 +14,8 @@
  * owner and is tracked there, not duplicated in a transport package.
  */
 
+import { SESSION_CHANGE_REFUSAL_CODES } from '@robota-sdk/agent-interface-session';
+
 import type { TBackgroundControlAction, TClientMessage, TServerMessage } from './wire-messages.js';
 
 export type TMessageDecodeResult<TMessage> =
@@ -32,6 +34,7 @@ const isString = (v: unknown): v is string => typeof v === 'string';
 const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
 const isBoolean = (v: unknown): v is boolean => typeof v === 'boolean';
 const isFiniteNumber = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const isCount = (v: unknown): v is number => Number.isSafeInteger(v) && (v as number) >= 0;
 const isOptional =
   (check: (v: unknown) => boolean) =>
   (v: unknown): boolean =>
@@ -42,6 +45,19 @@ const oneOf =
   (members: readonly string[]) =>
   (v: unknown): boolean =>
     typeof v === 'string' && members.includes(v);
+/** A record, not an array, so a turn source added to the union without one here fails to compile. */
+const TURN_SOURCES: Readonly<
+  Record<Extract<TServerMessage, { type: 'turn_source' }>['source'], true>
+> = { user: true, 'agent-wakeup': true, peer: true, external: true };
+/** A history entry's envelope is this package's (`IWireHistoryEntry`); its `data` is the recorder's. */
+const isWireHistoryEntry = (v: unknown): boolean =>
+  isRecord(v) &&
+  isString(v['id']) &&
+  isString(v['timestamp']) &&
+  isString(v['category']) &&
+  isString(v['type']);
+const isWireHistoryEntries = (v: unknown): boolean =>
+  Array.isArray(v) && v.every(isWireHistoryEntry);
 
 type TFieldCheck = (value: unknown) => boolean;
 type TVariantShape = Readonly<Record<string, TFieldCheck>>;
@@ -69,6 +85,7 @@ const isBackgroundTaskListFilter: TFieldCheck = (v) =>
 const isBackgroundTaskInput: TFieldCheck = (v) =>
   isRecord(v) && isOptional(isString)(v['prompt']) && isOptional(isString)(v['stdin']);
 const isBackgroundTaskLogCursor: TFieldCheck = (v) => isRecord(v) && isFiniteNumber(v['offset']);
+const isExecutionDetailCursor: TFieldCheck = (v) => isRecord(v) && isCount(v['offset']);
 const isPermissionResultValue: TFieldCheck = (v) =>
   isBoolean(v) || v === 'allow-session' || v === 'allow-project';
 const isActionResponse: TFieldCheck = (v) =>
@@ -79,14 +96,43 @@ const isActionResponse: TFieldCheck = (v) =>
     isOptional(isString)(v['text'])) ||
     (v['type'] === 'cancelled' && v['values'] === undefined && v['text'] === undefined));
 
+type TWaitingLoopStopOutcome = Extract<TServerMessage, { type: 'waiting_loop_stop' }>['outcome'];
+/** Keyed by `kind`, so an outcome added to the union without a shape here fails to compile. */
+const WAITING_LOOP_STOP_OUTCOME_SHAPES: Readonly<
+  Record<TWaitingLoopStopOutcome['kind'], TVariantShape>
+> = {
+  none: {},
+  several: { message: isString },
+  stopped: { loopId: isNonEmptyString, message: isOptional(isString) },
+  failed: { loopId: isOptional(isNonEmptyString), message: isString },
+};
+const isWaitingLoopStopOutcome: TFieldCheck = (v) => {
+  if (!isRecord(v) || !isString(v['kind'])) return false;
+  const kind = v['kind'];
+  if (!Object.prototype.hasOwnProperty.call(WAITING_LOOP_STOP_OUTCOME_SHAPES, kind)) return false;
+  const shape = WAITING_LOOP_STOP_OUTCOME_SHAPES[kind as TWaitingLoopStopOutcome['kind']];
+  return Object.entries(shape).every(([field, check]) => check(v[field]));
+};
+
 /** One entry per `TClientMessage` variant — a variant added to the union without one fails the test. */
 export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVariantShape>> = {
   submit: { prompt: isNonEmptyString },
-  command: { name: isNonEmptyString, args: isOptional(isString) },
+  command: {
+    name: isNonEmptyString,
+    args: isOptional(isString),
+    requestId: isOptional(isNonEmptyString),
+  },
   abort: {},
   'cancel-queue': {},
   'get-messages': {},
+  'get-history': { fromIndex: isOptional(isCount) },
+  'get-prompts': {},
   'get-context': {},
+  'get-commands': {},
+  'get-status': {},
+  'list-sessions': { requestId: isNonEmptyString },
+  'new-session': { requestId: isOptional(isNonEmptyString) },
+  'switch-session': { sessionId: isNonEmptyString, requestId: isOptional(isNonEmptyString) },
   'get-usage-report': {},
   'get-personal-usage-report': {
     requestId: isNonEmptyString,
@@ -100,6 +146,12 @@ export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVar
   'get-executing': {},
   'get-pending': {},
   'get-execution-workspace': {},
+  'read-execution-detail': {
+    requestId: isNonEmptyString,
+    entryId: isNonEmptyString,
+    cursor: isOptional(isExecutionDetailCursor),
+  },
+  'stop-waiting-loop': { requestId: isNonEmptyString },
   'get-background-tasks': { filter: isOptional(isBackgroundTaskListFilter) },
   'get-background-task': { taskId: isNonEmptyString },
   'get-background-job-groups': {},
@@ -130,9 +182,31 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
   complete: { result: isRecord, ...authored },
   interrupted: { result: isRecord, ...authored },
   error: { message: isString, ...authored },
-  command_result: { name: isString, message: isString, success: isBoolean },
+  command_result: {
+    name: isString,
+    message: isString,
+    success: isBoolean,
+    requestId: isOptional(isString),
+  },
   messages: { messages: isRecordArray },
+  history: { startIndex: isCount, total: isCount, entries: isWireHistoryEntries },
   context: { state: isRecord },
+  history_changed: {},
+  turn_source: { source: oneOf(Object.keys(TURN_SOURCES)) },
+  commands: { commands: isRecordArray, skills: isRecordArray },
+  session_status: { status: isRecord },
+  sessions: { requestId: isNonEmptyString, listing: isRecord },
+  sessions_error: {
+    requestId: isNonEmptyString,
+    code: oneOf(['not_available', 'list_failed']),
+    message: isString,
+  },
+  session_switched: { event: isRecord },
+  session_change_failed: {
+    code: oneOf(SESSION_CHANGE_REFUSAL_CODES),
+    message: isString,
+    requestId: isOptional(isString),
+  },
   usage_report: { report: isRecord },
   personal_usage_report: { requestId: isNonEmptyString, report: isRecord },
   personal_usage_report_error: {
@@ -152,8 +226,12 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
     message: isString,
   },
   executing: { executing: isBoolean },
-  pending: { pending: (v) => v === null || isString(v) },
+  // An older host sends no count; a client then counts the one prompt it can see.
+  pending: { pending: (v) => v === null || isString(v), pendingCount: isOptional(isCount) },
   execution_workspace_event: { snapshot: isRecord },
+  execution_detail: { requestId: isNonEmptyString, page: isRecord },
+  execution_detail_error: { requestId: isNonEmptyString, message: isString },
+  waiting_loop_stop: { requestId: isNonEmptyString, outcome: isWaitingLoopStopOutcome },
   background_task_event: { event: isRecord },
   background_job_group_event: { event: isRecord },
   plan_event: { event: isRecord },
@@ -176,7 +254,7 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
     success: isBoolean,
     message: isOptional(isString),
   },
-  protocol_error: { message: isString },
+  protocol_error: { message: isString, requestId: isOptional(isString) },
   resume_gap: {},
 };