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

package/src/session-events.ts

@@ -6,14 +6,22 @@
  * `SessionResumeBridge` (REMOTE-013 E4 — a SINGLE subscription that outlives per-channel handlers).
  */
 
+import { holdOpenPrompts } from './open-prompts.js';
+import { classifySessionErrorForWire } from './session-error-classification.js';
+
 import type { TOutboundDeliver } from './outbound-delivery.js';
 import type { IProtocolSession } from './protocol-session.js';
+import type { TWireExecutionResult } from './wire-messages.js';
 import type {
   IExecutionWorkspaceEvent,
   TBackgroundJobGroupEvent,
   TBackgroundTaskEvent,
 } from '@robota-sdk/agent-interface-execution';
-import type { TDriverId, TInteractiveEventName } from '@robota-sdk/agent-interface-session';
+import type {
+  TDriverId,
+  TInteractiveEventName,
+  TTurnSource,
+} from '@robota-sdk/agent-interface-session';
 import type {
   IAskRequestEvent,
   IBranchEvent,
@@ -23,6 +31,8 @@ import type {
   IPromptResolvedEvent,
   IPlanApprovalEvent,
   ISessionRenamedEvent,
+  ISessionStatusSnapshot,
+  ISessionSwitchedEvent,
   IToolState,
   IUiIntentEvent,
 } from '@robota-sdk/agent-interface-session';
@@ -37,17 +47,17 @@ export const PROTOCOL_SESSION_EVENT_CLASSIFICATION = {
   thinking: 'forwarded',
   complete: 'forwarded',
   error: 'forwarded',
-  context_update: 'non-surface',
-  compact: 'non-surface',
+  context_update: 'forwarded',
+  compact: 'forwarded',
   interrupted: 'forwarded',
-  skill_activation: 'non-surface',
+  skill_activation: 'forwarded',
   background_task_event: 'forwarded',
   background_job_group_event: 'forwarded',
   execution_workspace_event: 'forwarded',
   user_message: 'forwarded',
-  turn_source: 'non-surface',
+  turn_source: 'forwarded',
   context_file_refreshed: 'forwarded',
-  memory_event: 'non-surface',
+  memory_event: 'forwarded',
   goal_event: 'non-surface',
   plan_event: 'forwarded',
   branch_event: 'forwarded',
@@ -57,6 +67,8 @@ export const PROTOCOL_SESSION_EVENT_CLASSIFICATION = {
   ui_intent: 'requester-routed',
   session_renamed: 'forwarded',
   history_cleared: 'forwarded',
+  session_switched: 'forwarded',
+  status_changed: 'forwarded',
 } as const satisfies Record<TInteractiveEventName, TProtocolSessionEventClassification>;
 
 /**
@@ -72,6 +84,13 @@ export interface ISubscribeSessionEventsOptions {
    * requester-routed against it (lazy because the resume bridge binds the id only after pairing).
    */
   getSurfaceDriverId?: () => TDriverId | undefined;
+  /**
+   * `false` leaves `permission_request` and `ask_request` unsubscribed. The session parks a prompt
+   * only while someone listens for it, so a surface that may not answer must not listen: otherwise an
+   * unattended session would hold a prompt nobody can settle instead of failing it closed at once.
+   * Defaults to `true`.
+   */
+  receivePrompts?: boolean;
 }
 
 /**
@@ -89,8 +108,8 @@ export function subscribeSessionEvents(
 ): () => void {
   // ARCH-030: no local guard wrapper any more, and no event name passed alongside the message. The name
   // existed so the local guard could label a failure with it; the boundary labels with `message.type`,
-  // which is identical for every forwarded event (asserted in `session-event-delivery.test.ts`). Keeping
-  // the argument would have been a parameter that documents nothing and is read by nobody.
+  // the frame that could not be delivered. Keeping the argument would have been a parameter that
+  // documents nothing and is read by nobody.
   // REMOTE-014 E5: stamp the ACTIVE turn's driver id onto TURN-AUTHORED events (co-drive authorship,
   // display-only), read at emit time. Only these events — background/goal/memory/execution-workspace events
   // are NOT authored by a driver turn and carry no `driverId`. `undefined` when idle or unattributed.
@@ -109,11 +128,16 @@ export function subscribeSessionEvents(
   const onThinking = (isThinking: boolean): void =>
     deliver({ type: 'thinking', isThinking, ...attr() });
   const onComplete = (result: IExecutionResult): void =>
-    deliver({ type: 'complete', result, ...attr() });
+    deliver({ type: 'complete', result: withoutHistory(result), ...attr() });
   const onInterrupted = (result: IExecutionResult): void =>
-    deliver({ type: 'interrupted', result, ...attr() });
+    deliver({ type: 'interrupted', result: withoutHistory(result), ...attr() });
   const onError = (error: Error): void =>
-    deliver({ type: 'error', message: error.message, ...attr() });
+    deliver({
+      type: 'error',
+      message: error.message,
+      ...classifySessionErrorForWire(error),
+      ...attr(),
+    });
   const onBackgroundTaskEvent = (event: TBackgroundTaskEvent): void =>
     deliver({ type: 'background_task_event', event });
   const onBackgroundJobGroupEvent = (event: TBackgroundJobGroupEvent): void =>
@@ -129,11 +153,23 @@ export function subscribeSessionEvents(
   const onBranchEvent = (event: IBranchEvent): void => deliver({ type: 'branch_event', event });
   // REMOTE-007: forward the transport-neutral prompt events so a remote surface can render + answer the
   // SAME permission/ask prompt; `prompt_resolved` dismisses it when another surface answered first.
-  const onPermissionRequest = (event: IPermissionRequestEvent): void =>
-    deliver({ type: 'permission_request', event });
-  const onAskRequest = (event: IAskRequestEvent): void => deliver({ type: 'ask_request', event });
-  const onPromptResolved = (event: IPromptResolvedEvent): void =>
+  // #3189: kept while open, so a client that attaches later can ask for it with `get-prompts`.
+  const receivePrompts = options.receivePrompts ?? true;
+  const openPrompts = receivePrompts ? holdOpenPrompts(session) : undefined;
+  const onPermissionRequest = (event: IPermissionRequestEvent): void => {
+    const frame = { type: 'permission_request', event } as const;
+    openPrompts?.record(frame);
+    deliver(frame);
+  };
+  const onAskRequest = (event: IAskRequestEvent): void => {
+    const frame = { type: 'ask_request', event } as const;
+    openPrompts?.record(frame);
+    deliver(frame);
+  };
+  const onPromptResolved = (event: IPromptResolvedEvent): void => {
+    openPrompts?.forget(event.id);
     deliver({ type: 'prompt_resolved', event });
+  };
   // CMD-004 Stage D: `ui_intent` is REQUESTER-ROUTED — delivered only to the surface whose
   // server-assigned driver id issued the command. An UNATTRIBUTED intent (no requester id, e.g. an
   // idle model-invoked command) is unroutable and reaches every surface — never a silent drop.
@@ -151,6 +187,26 @@ export function subscribeSessionEvents(
   const onSessionRenamed = (event: ISessionRenamedEvent): void =>
     deliver({ type: 'session_renamed', event });
   const onHistoryCleared = (): void => deliver({ type: 'history_cleared' });
+  // #3189: this surface's session is now another one; it re-reads what it shows. Only surfaces
+  // subscribed to the session that moved hear it: a host that binds each connection to its own session
+  // sends it to the connection that switched, never to the others.
+  const onSessionSwitched = (event: ISessionSwitchedEvent): void => {
+    // This connection no longer answers the previous session's prompts; it reads the new session's anew.
+    openPrompts?.clear();
+    deliver({ type: 'session_switched', event });
+  };
+  // #3189: what a client that renders the whole session (the TUI) needs beside the streamed turn.
+  // The context window is pushed in the frame `get-context` answers with. A compaction, a skill
+  // activation or a memory event adds history entries no streamed frame carries, so the client is
+  // told the history changed and re-reads it with `get-history`; the entries themselves are not sent.
+  const onContextUpdate = (state: ReturnType<IProtocolSession['getContextState']>): void =>
+    deliver({ type: 'context', state });
+  const onHistoryChanged = (): void => deliver({ type: 'history_changed' });
+  const onTurnSource = (source: TTurnSource): void => deliver({ type: 'turn_source', source });
+  // One client's `/mode` or `/model` shows on every client on this session, in the frame
+  // `get-status` answers with.
+  const onStatusChanged = (status: ISessionStatusSnapshot): void =>
+    deliver({ type: 'session_status', status });
 
   session.on('user_message', onUserMessage);
   session.on('text_delta', onTextDelta);
@@ -166,12 +222,21 @@ export function subscribeSessionEvents(
   session.on('plan_event', onPlanEvent);
   session.on('context_file_refreshed', onContextFileRefreshed);
   session.on('branch_event', onBranchEvent);
-  session.on('permission_request', onPermissionRequest);
-  session.on('ask_request', onAskRequest);
+  if (receivePrompts) {
+    session.on('permission_request', onPermissionRequest);
+    session.on('ask_request', onAskRequest);
+  }
   session.on('prompt_resolved', onPromptResolved);
   session.on('ui_intent', onUiIntent);
   session.on('session_renamed', onSessionRenamed);
   session.on('history_cleared', onHistoryCleared);
+  session.on('session_switched', onSessionSwitched);
+  session.on('context_update', onContextUpdate);
+  session.on('compact', onHistoryChanged);
+  session.on('skill_activation', onHistoryChanged);
+  session.on('memory_event', onHistoryChanged);
+  session.on('turn_source', onTurnSource);
+  session.on('status_changed', onStatusChanged);
 
   return (): void => {
     session.off('user_message', onUserMessage);
@@ -188,11 +253,27 @@ export function subscribeSessionEvents(
     session.off('plan_event', onPlanEvent);
     session.off('context_file_refreshed', onContextFileRefreshed);
     session.off('branch_event', onBranchEvent);
-    session.off('permission_request', onPermissionRequest);
-    session.off('ask_request', onAskRequest);
+    if (receivePrompts) {
+      session.off('permission_request', onPermissionRequest);
+      session.off('ask_request', onAskRequest);
+    }
     session.off('prompt_resolved', onPromptResolved);
     session.off('ui_intent', onUiIntent);
     session.off('session_renamed', onSessionRenamed);
     session.off('history_cleared', onHistoryCleared);
+    session.off('session_switched', onSessionSwitched);
+    session.off('context_update', onContextUpdate);
+    session.off('compact', onHistoryChanged);
+    session.off('skill_activation', onHistoryChanged);
+    session.off('memory_event', onHistoryChanged);
+    session.off('turn_source', onTurnSource);
+    session.off('status_changed', onStatusChanged);
+    openPrompts?.release();
   };
 }
+
+/** The turn's result without the session's history: that only grows, and `get-history` pages it. */
+function withoutHistory(result: IExecutionResult): TWireExecutionResult {
+  const { history: _history, ...rest } = result;
+  return rest;
+}

package/src/session-message-handler.ts

@@ -12,17 +12,35 @@ import {
   handleBackgroundControlMessage,
   handleBackgroundQueryMessage,
 } from './background-messages.js';
+import { handleLoopControlMessage, isLoopControlMessage } from './loop-control-messages.js';
 import { parseClientMessage } from './message-parser.js';
+import { isObserverMessageType } from './observer-messages.js';
+import { handleProjectReadMessage, isProjectReadMessage } from './project-read-messages.js';
+import {
+  handleSessionDeleteMessage,
+  handleSessionDirectoryMessage,
+  handleSessionRenameMessage,
+  isSessionDeleteMessage,
+  isSessionDirectoryMessage,
+  isSessionRenameMessage,
+} from './session-directory-messages.js';
 import { subscribeSessionEvents } from './session-events.js';
-import { handleSessionQueryMessage, isSessionQueryMessage } from './session-query-messages.js';
+import {
+  handleSessionQueryMessage,
+  isSessionQueryMessage,
+  pendingFrame,
+} from './session-query-messages.js';
+import { handleSettingsMessage, isSettingsMessage } from './settings-messages.js';
 import { handleUsageQueryMessage } from './usage-messages.js';
 
 import type { TOutboundDeliver } from './outbound-delivery.js';
-import type { IProtocolSession } from './protocol-session.js';
+import type { IProtocolSession, TProjectReadCapableSession } from './protocol-session.js';
+import type { ISettingsReporter } from './settings-messages.js';
 import type { IUsageQueryReporters } from './usage-messages.js';
 import type { TClientMessage } from './wire-messages.js';
+import type { TCommandSurfaceLocality } from '@robota-sdk/agent-interface-command';
 import type { TUsageSurface } from '@robota-sdk/agent-interface-analytics';
-import type { TDriverId } from '@robota-sdk/agent-interface-session';
+import type { ISessionDirectory, TDriverId } from '@robota-sdk/agent-interface-session';
 
 // Outbound session→TServerMessage fan-out (incl. CMD-004 requester-routed `ui_intent`) lives in
 // `session-events.ts`; re-exported here for the bridge and existing importers.
@@ -30,9 +48,16 @@ export { subscribeSessionEvents } from './session-events.js';
 export type { ISubscribeSessionEventsOptions } from './session-events.js';
 export { parseClientMessage } from './message-parser.js';
 
+/**
+ * What a connected surface may do. `drive` sends prompts, answers questions and controls the session.
+ * `observe` is read-only: it follows this session's conversation and state, but never submits, answers,
+ * controls, or reads another session's records, and it never counts as a surface that can answer.
+ */
+export type TSessionSurfaceRole = 'drive' | 'observe';
+
 export interface ISessionMessageHandlerOptions {
-  /** IProtocolSession to expose. */
-  session: IProtocolSession;
+  /** IProtocolSession to expose — `Partial<ISessionProjectRead>` is probed, not assumed (#3282 §4c). */
+  session: TProjectReadCapableSession;
   /**
    * ARCH-030: the CARRIER's connection-scoped outbound delivery boundary — not a raw `send`, and not a
    * `send` plus an error callback for this handler to assemble into one. The carrier owns both the sink
@@ -49,12 +74,25 @@ export interface ISessionMessageHandlerOptions {
   driverId?: TDriverId;
   /** Trusted carrier-owned product surface, kept separate from driver identity. */
   surface?: TUsageSurface;
+  /** Carrier-decided role of this connection; defaults to `drive`. The client never chooses it here. */
+  role?: TSessionSurfaceRole;
   /** Host-owned cross-session read model. The protocol only correlates and carries its result. */
   personalUsageReporter?: NonNullable<IUsageQueryReporters['personalUsageReporter']>;
   /** Host-owned current-session trace/cost producer for the pre-existing message family. */
   usageReporter?: NonNullable<IUsageQueryReporters['usageReporter']>;
   /** Host-owned stored-session producer used by cross-session drill-down. */
   storedSessionUsageReporter?: NonNullable<IUsageQueryReporters['storedSessionUsageReporter']>;
+  /** Host-owned session directory (#3189): list, start and switch the host's sessions. */
+  sessionDirectory?: ISessionDirectory;
+  /** #3282 §4a: host-owned read/write for the GUI Settings screen. */
+  settingsReporter?: ISettingsReporter;
+  /**
+   * #3282 §4 part b-2: carrier-decided, like `role` — whether THIS carrier's connections are
+   * provably on this machine. The loopback WS carrier is `'local'`; the device-mesh/WebRTC carrier
+   * sets `'remote'`. Absent → `'local'`, forwarded to `executeCommand` and the settings reporter so a
+   * command that runs code from outside the session (installing a plugin) can refuse a remote device.
+   */
+  commandSurfaceLocality?: TCommandSurfaceLocality;
 }
 
 /**
@@ -80,8 +118,10 @@ export function createSessionMessageHandler(options: ISessionMessageHandlerOptio
   onMessage: (data: string) => void;
   cleanup: () => void;
 } {
+  const role = options.role ?? 'drive';
   const cleanup = subscribeSessionEvents(options.session, options.deliver, {
     getSurfaceDriverId: () => options.driverId,
+    receivePrompts: role === 'drive',
   });
   const onMessage = createMessageHandler(
     options.session,
@@ -93,22 +133,44 @@ export function createSessionMessageHandler(options: ISessionMessageHandlerOptio
       storedSessionUsageReporter: options.storedSessionUsageReporter,
     },
     options.surface,
+    role,
+    options.sessionDirectory,
+    options.settingsReporter,
+    options.commandSurfaceLocality,
   );
 
   return { onMessage, cleanup };
 }
 
 function createMessageHandler(
-  session: IProtocolSession,
+  session: TProjectReadCapableSession,
   deliver: TOutboundDeliver,
   driverId?: TDriverId,
   reporters: IUsageQueryReporters = EMPTY_USAGE_REPORTERS,
   surface?: TUsageSurface,
+  role: TSessionSurfaceRole = 'drive',
+  sessionDirectory?: ISessionDirectory,
+  settingsReporter?: ISettingsReporter,
+  commandSurfaceLocality?: TCommandSurfaceLocality,
 ): (data: string) => void {
   return (data: string): void => {
     const msg = parseClientMessage(data, deliver);
     if (!msg) return;
-    handleClientMessage(session, deliver, msg, driverId, reporters, surface);
+    if (role === 'observe' && !isObserverMessageType(msg.type)) {
+      deliver({ type: 'protocol_error', message: `Not permitted for an observer: ${msg.type}` });
+      return;
+    }
+    handleClientMessage(
+      session,
+      deliver,
+      msg,
+      driverId,
+      reporters,
+      surface,
+      sessionDirectory,
+      settingsReporter,
+      commandSurfaceLocality,
+    );
   };
 }
 
@@ -123,24 +185,51 @@ const EMPTY_USAGE_REPORTERS: IUsageQueryReporters = {
  * the {@link SessionResumeBridge} intercepts `resume`/`ack` itself and delegates everything else here.
  */
 export function handleClientMessage(
-  session: IProtocolSession,
+  session: TProjectReadCapableSession,
   deliver: TOutboundDeliver,
   msg: TClientMessage,
   driverId?: TDriverId,
   reporters: IUsageQueryReporters = EMPTY_USAGE_REPORTERS,
   surface?: TUsageSurface,
+  sessionDirectory?: ISessionDirectory,
+  settingsReporter?: ISettingsReporter,
+  commandSurfaceLocality?: TCommandSurfaceLocality,
 ): void {
   if (handleUsageQueryMessage(session, deliver, msg, reporters)) {
     return;
   }
+  if (isSessionDirectoryMessage(msg)) {
+    handleSessionDirectoryMessage(deliver, msg, sessionDirectory);
+    return;
+  }
+  if (isSettingsMessage(msg)) {
+    handleSettingsMessage(session, deliver, msg, settingsReporter, commandSurfaceLocality);
+    return;
+  }
+  if (isSessionRenameMessage(msg)) {
+    handleSessionRenameMessage(deliver, msg, sessionDirectory);
+    return;
+  }
+  if (isSessionDeleteMessage(msg)) {
+    handleSessionDeleteMessage(deliver, msg, sessionDirectory);
+    return;
+  }
   if (isSessionControlMessage(msg)) {
-    handleSessionControlMessage(session, deliver, msg, driverId, surface);
+    handleSessionControlMessage(session, deliver, msg, driverId, surface, commandSurfaceLocality);
+    return;
+  }
+  if (isLoopControlMessage(msg)) {
+    handleLoopControlMessage(session, deliver, msg);
     return;
   }
   if (isSessionQueryMessage(msg)) {
     handleSessionQueryMessage(session, deliver, msg);
     return;
   }
+  if (isProjectReadMessage(msg)) {
+    handleProjectReadMessage(session, deliver, msg);
+    return;
+  }
   if (isBackgroundQueryMessage(msg)) {
     handleBackgroundQueryMessage(session, deliver, msg);
     return;
@@ -228,6 +317,7 @@ function handleSessionControlMessage(
   msg: Extract<TClientMessage, { type: 'submit' | 'command' | 'abort' | 'cancel-queue' }>,
   driverId?: TDriverId,
   surface?: TUsageSurface,
+  commandSurfaceLocality?: TCommandSurfaceLocality,
 ): void {
   if (msg.type === 'submit') {
     // TRANS-008 (issue #2045). A TYPE check, not a falsy one: `{}`, `[]`, `42` and `true` are truthy
@@ -250,17 +340,21 @@ function handleSessionControlMessage(
         undefined,
         Object.keys(submitOptions).length > 0 ? submitOptions : undefined,
       )
-      .catch((error: Error) => {
-        deliver({ type: 'protocol_error', message: error.message });
-      });
+      .then(
+        // #3189: a prompt submitted during a turn resolves once it is queued. A `get-pending` sent
+        // beside the `submit` would be answered before that, so the queue is reported from here.
+        () => deliver(pendingFrame(session)),
+        (error: Error) => deliver({ type: 'protocol_error', message: error.message }),
+      );
   } else if (msg.type === 'command') {
+    const request = msg.requestId !== undefined ? { requestId: msg.requestId } : {};
     if (!msg.name) {
-      deliver({ type: 'protocol_error', message: 'name is required' });
+      deliver({ type: 'protocol_error', message: 'name is required', ...request });
       return;
     }
     // REMOTE-003: a transport-origin command is tagged `'remote'` (optional policy, allow-by-default;
     // REMOTE-006). CMD-004: the SERVER-ASSIGNED driver id (E5) is the command origin — intents route back here.
-    session.executeCommand(msg.name, msg.args ?? '', 'remote', driverId).then(
+    session.executeCommand(msg.name, msg.args ?? '', 'remote', driverId, commandSurfaceLocality).then(
       (result) => {
         deliver({
           type: 'command_result',
@@ -268,10 +362,11 @@ function handleSessionControlMessage(
           message: result?.message ?? `Unknown command: ${msg.name}`,
           success: result?.success ?? false,
           data: result?.data,
+          ...request,
         });
       },
       (error: Error) => {
-        deliver({ type: 'protocol_error', message: error.message });
+        deliver({ type: 'protocol_error', message: error.message, ...request });
       },
     );
   } else if (msg.type === 'abort') {

package/src/session-query-messages.ts

@@ -1,22 +1,51 @@
+import { listOpenPrompts } from './open-prompts.js';
+
 import type { TOutboundDeliver } from './outbound-delivery.js';
 import type { IProtocolSession } from './protocol-session.js';
-import type { TClientMessage } from './wire-messages.js';
+import type { IWireHistoryEntry, TClientMessage, TServerMessage } from './wire-messages.js';
 
 type TSessionQueryMessage = Extract<
   TClientMessage,
   {
     type:
-      'get-messages' | 'get-context' | 'get-executing' | 'get-pending' | 'get-execution-workspace';
+      | 'get-messages'
+      | 'get-history'
+      | 'get-prompts'
+      | 'get-context'
+      | 'get-commands'
+      | 'get-status'
+      | 'list-models'
+      | 'get-agent-definitions'
+      | 'get-executing'
+      | 'get-pending'
+      | 'get-execution-workspace'
+      | 'read-execution-detail';
   }
 >;
 
+/**
+ * #3189: the most serialized history one `history` frame carries. Well under the tightest outbound
+ * budget (an attached terminal's, 1 MiB), so a client reading page after page is never mistaken for
+ * one that stopped reading.
+ */
+export const HISTORY_PAGE_MAX_BYTES = 256 * 1024;
+
+const utf8 = new TextEncoder();
+
 export function isSessionQueryMessage(msg: TClientMessage): msg is TSessionQueryMessage {
   return (
     msg.type === 'get-messages' ||
+    msg.type === 'get-history' ||
+    msg.type === 'get-prompts' ||
     msg.type === 'get-context' ||
+    msg.type === 'get-commands' ||
+    msg.type === 'get-status' ||
+    msg.type === 'list-models' ||
+    msg.type === 'get-agent-definitions' ||
     msg.type === 'get-executing' ||
     msg.type === 'get-pending' ||
-    msg.type === 'get-execution-workspace'
+    msg.type === 'get-execution-workspace' ||
+    msg.type === 'read-execution-detail'
   );
 }
 
@@ -26,9 +55,30 @@ export function handleSessionQueryMessage(
   msg: TSessionQueryMessage,
 ): void {
   if (msg.type === 'get-messages') {
-    deliver({ type: 'messages', messages: session.getMessages() });
+    // #3288 §2: `display` rides the same frame as `messages` — a reload/reconnect/resume replay
+    // needs both in one round trip, and there is no reason a client would ever want one without
+    // the other (the raw messages already have to be fetched to build the projection).
+    deliver({ type: 'messages', messages: session.getMessages(), display: session.getMessagesDisplay() });
+  } else if (msg.type === 'get-history') {
+    deliver(historyPage(session, msg.fromIndex ?? 0));
+  } else if (msg.type === 'get-prompts') {
+    for (const frame of listOpenPrompts(session)) deliver(frame);
   } else if (msg.type === 'get-context') {
     deliver({ type: 'context', state: session.getContextState() });
+  } else if (msg.type === 'get-commands') {
+    deliver({ type: 'commands', commands: session.listCommands(), skills: session.listSkills() });
+  } else if (msg.type === 'get-status') {
+    deliver({ type: 'session_status', status: session.getStatusSnapshot() });
+  } else if (msg.type === 'list-models') {
+    const snapshot = session.listModels();
+    deliver({ type: 'model_list', requestId: msg.requestId, ...snapshot });
+  } else if (msg.type === 'get-agent-definitions') {
+    deliver({
+      type: 'agent_definitions',
+      requestId: msg.requestId,
+      agents: session.listAgentDefinitions(),
+      current: session.getDefaultAgentType(),
+    });
   } else if (msg.type === 'get-executing') {
     deliver({ type: 'executing', executing: session.isExecuting() });
   } else if (msg.type === 'get-execution-workspace') {
@@ -36,7 +86,75 @@ export function handleSessionQueryMessage(
       type: 'execution_workspace_event',
       snapshot: session.getExecutionWorkspaceSnapshot(),
     });
+  } else if (msg.type === 'read-execution-detail') {
+    readExecutionDetail(session, deliver, msg);
   } else {
-    deliver({ type: 'pending', pending: session.getPendingPrompt() });
+    deliver(pendingFrame(session));
+  }
+}
+
+/** One page of an execution-workspace entry's detail, answered under the request's id. */
+function readExecutionDetail(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'read-execution-detail' }>,
+): void {
+  const { requestId } = msg;
+  session.readExecutionWorkspaceDetail(msg.entryId, msg.cursor).then(
+    (page) => deliver({ type: 'execution_detail', requestId, page }),
+    (error: unknown) =>
+      deliver({
+        type: 'execution_detail_error',
+        requestId,
+        message: error instanceof Error ? error.message : String(error),
+      }),
+  );
+}
+
+/** The next queued prompt and how many wait, as the session reports them now. */
+export function pendingFrame(
+  session: IProtocolSession,
+): Extract<TServerMessage, { type: 'pending' }> {
+  return {
+    type: 'pending',
+    pending: session.getPendingPrompt(),
+    pendingCount: session.getPendingCount(),
+  };
+}
+
+/**
+ * The history from `fromIndex`, as many entries as fit {@link HISTORY_PAGE_MAX_BYTES}. At least one
+ * entry is sent while any remain, so a client always moves forward, even past one larger entry.
+ */
+function historyPage(
+  session: IProtocolSession,
+  fromIndex: number,
+): Extract<TServerMessage, { type: 'history' }> {
+  const history = session.getFullHistory();
+  const total = history.length;
+  const startIndex = Math.min(fromIndex, total);
+  const entries: IWireHistoryEntry[] = [];
+  let bytes = 0;
+  for (let index = startIndex; index < total; index += 1) {
+    const entry = toWireHistoryEntry(history[index]!);
+    const size = utf8.encode(JSON.stringify(entry)).byteLength;
+    if (entries.length > 0 && bytes + size > HISTORY_PAGE_MAX_BYTES) break;
+    entries.push(entry);
+    bytes += size;
   }
+  return { type: 'history', startIndex, total, entries };
+}
+
+function toWireHistoryEntry(
+  entry: ReturnType<IProtocolSession['getFullHistory']>[number],
+): IWireHistoryEntry {
+  return { ...entry, timestamp: toIsoTimestamp(entry.timestamp) };
+}
+
+/**
+ * The declared type is `Date`, but a resumed session's entries were read back from JSON unrevived, so
+ * their `timestamp` is already the ISO string the store wrote. Either way the wire carries that string.
+ */
+function toIsoTimestamp(timestamp: Date | string): string {
+  return typeof timestamp === 'string' ? timestamp : timestamp.toISOString();
 }

package/src/session-resume-bridge.ts

@@ -28,6 +28,7 @@ import type { TOutboundDeliver } from './outbound-delivery.js';
 import type { IProtocolSession } from './protocol-session.js';
 import type { IUsageQueryReporters } from './usage-messages.js';
 import type { TSeqServerMessage, TServerMessage } from './wire-messages.js';
+import type { TCommandSurfaceLocality } from '@robota-sdk/agent-interface-command';
 import type { TUsageSurface } from '@robota-sdk/agent-interface-analytics';
 import type { TDriverId } from '@robota-sdk/agent-interface-session';
 
@@ -65,6 +66,8 @@ export interface ISessionResumeBridgeOptions {
   readonly personalUsageReporter?: IUsageQueryReporters['personalUsageReporter'];
   readonly usageReporter?: IUsageQueryReporters['usageReporter'];
   readonly storedSessionUsageReporter?: IUsageQueryReporters['storedSessionUsageReporter'];
+  /** #3282 §4 part b-2: this bridge is the reconnectable WebRTC path, so it is always `'remote'`. */
+  readonly commandSurfaceLocality?: TCommandSurfaceLocality;
 }
 
 export class SessionResumeBridge {
@@ -73,6 +76,7 @@ export class SessionResumeBridge {
   private driverId?: TDriverId;
   private readonly reporters: IUsageQueryReporters;
   private readonly surface?: TUsageSurface;
+  private readonly commandSurfaceLocality?: TCommandSurfaceLocality;
   private readonly unsubscribe: () => void;
   private onDeliveryError?: IAttachOptions['onDeliveryError'];
   /**
@@ -105,6 +109,7 @@ export class SessionResumeBridge {
     this.buffer = new ResumeBuffer(options.buffer);
     this.driverId = options.driverId;
     this.surface = options.surface;
+    this.commandSurfaceLocality = options.commandSurfaceLocality;
     this.reporters = {
       personalUsageReporter: options.personalUsageReporter,
       usageReporter: options.usageReporter,
@@ -178,6 +183,9 @@ export class SessionResumeBridge {
       this.driverId,
       this.reporters,
       this.surface,
+      undefined,
+      undefined,
+      this.commandSurfaceLocality,
     );
   }