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

package/src/session-events.ts

@@ -6,14 +6,21 @@
  * `SessionResumeBridge` (REMOTE-013 E4 — a SINGLE subscription that outlives per-channel handlers).
  */
 
+import { holdOpenPrompts } from './open-prompts.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 +30,8 @@ import type {
   IPromptResolvedEvent,
   IPlanApprovalEvent,
   ISessionRenamedEvent,
+  ISessionStatusSnapshot,
+  ISessionSwitchedEvent,
   IToolState,
   IUiIntentEvent,
 } from '@robota-sdk/agent-interface-session';
@@ -37,17 +46,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 +66,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 +83,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 +107,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,9 +127,9 @@ 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() });
   const onBackgroundTaskEvent = (event: TBackgroundTaskEvent): void =>
@@ -129,11 +147,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 +181,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 +216,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 +247,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,9 +12,19 @@ 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 {
+  handleSessionDirectoryMessage,
+  isSessionDirectoryMessage,
+} 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 { handleUsageQueryMessage } from './usage-messages.js';
 
 import type { TOutboundDeliver } from './outbound-delivery.js';
@@ -22,7 +32,7 @@ import type { IProtocolSession } from './protocol-session.js';
 import type { IUsageQueryReporters } from './usage-messages.js';
 import type { TClientMessage } from './wire-messages.js';
 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,6 +40,13 @@ 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;
@@ -49,12 +66,16 @@ 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;
 }
 
 /**
@@ -80,8 +101,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,6 +116,8 @@ export function createSessionMessageHandler(options: ISessionMessageHandlerOptio
       storedSessionUsageReporter: options.storedSessionUsageReporter,
     },
     options.surface,
+    role,
+    options.sessionDirectory,
   );
 
   return { onMessage, cleanup };
@@ -104,11 +129,17 @@ function createMessageHandler(
   driverId?: TDriverId,
   reporters: IUsageQueryReporters = EMPTY_USAGE_REPORTERS,
   surface?: TUsageSurface,
+  role: TSessionSurfaceRole = 'drive',
+  sessionDirectory?: ISessionDirectory,
 ): (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);
   };
 }
 
@@ -129,14 +160,23 @@ export function handleClientMessage(
   driverId?: TDriverId,
   reporters: IUsageQueryReporters = EMPTY_USAGE_REPORTERS,
   surface?: TUsageSurface,
+  sessionDirectory?: ISessionDirectory,
 ): void {
   if (handleUsageQueryMessage(session, deliver, msg, reporters)) {
     return;
   }
+  if (isSessionDirectoryMessage(msg)) {
+    handleSessionDirectoryMessage(deliver, msg, sessionDirectory);
+    return;
+  }
   if (isSessionControlMessage(msg)) {
     handleSessionControlMessage(session, deliver, msg, driverId, surface);
     return;
   }
+  if (isLoopControlMessage(msg)) {
+    handleLoopControlMessage(session, deliver, msg);
+    return;
+  }
   if (isSessionQueryMessage(msg)) {
     handleSessionQueryMessage(session, deliver, msg);
     return;
@@ -250,12 +290,16 @@ 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;
@@ -268,10 +312,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,47 @@
+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'
+      | '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 === 'get-executing' ||
     msg.type === 'get-pending' ||
-    msg.type === 'get-execution-workspace'
+    msg.type === 'get-execution-workspace' ||
+    msg.type === 'read-execution-detail'
   );
 }
 
@@ -27,8 +52,16 @@ export function handleSessionQueryMessage(
 ): void {
   if (msg.type === 'get-messages') {
     deliver({ type: 'messages', messages: session.getMessages() });
+  } 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 === 'get-executing') {
     deliver({ type: 'executing', executing: session.isExecuting() });
   } else if (msg.type === 'get-execution-workspace') {
@@ -36,7 +69,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();
 }