@robota-sdk/agent-transport 3.0.0-beta.100

package/src/session-message-handler.ts

@@ -0,0 +1,413 @@
+/**
+ * Carrier-neutral session message adapter.
+ *
+ * Framework-agnostic: works with any transport implementation via
+ * send/onMessage callbacks. No dependency on a carrier library.
+ *
+ * Protocol: JSON messages with { type, ...payload } structure.
+ * Server pushes IProtocolSession events to client in real-time.
+ */
+
+import {
+  handleAppToolMessage,
+  handleAppViewMessage,
+  isAppToolMessage,
+  isAppViewMessage,
+  type IAppMessageOptions,
+} from './app-tool-messages.js';
+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,
+  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, 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 { 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.
+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 — `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
+   * and the "what does a failed send mean for this connection" policy, so it builds the boundary and
+   * passes it down; the raw sink never crosses this parameter, which is what stops a future reply family
+   * from reaching the wire unguarded.
+   */
+  deliver: TOutboundDeliver;
+  /**
+   * REMOTE-014 E5: the SERVER-ASSIGNED driver id for THIS remote surface (the E3 `deviceId`). Injected into
+   * every inbound `submit`/`command`/prompt-response so a co-drive turn/answer is attributed to this driver —
+   * a client-supplied driver id is NEVER trusted. Absent → unattributed (the session defaults to the owner).
+   */
+  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;
+  /**
+   * The most bytes one frame answering an app tool call or view read may take, for a carrier whose
+   * channel carries less than the inbound limit (a WebRTC data channel). An answer over it is
+   * replaced by a `protocol_error` before it reaches any buffer. Defaults to the inbound limit less
+   * a margin for a carrier that stamps frames afterwards.
+   */
+  maxFrameBytes?: number;
+}
+
+/**
+ * Create a carrier-neutral message handler for an IProtocolSession.
+ *
+ * Returns:
+ * - `onMessage(data)`: call this when the WebSocket receives a message
+ * - `cleanup()`: call this when the WebSocket disconnects
+ *
+ * Usage:
+ * ```typescript
+ * const delivery = createOutboundDelivery(
+ *   (msg) => ws.send(JSON.stringify(msg)),
+ *   (error) => ws.close(1011, error.message),
+ * );
+ * const { onMessage, cleanup } = createSessionMessageHandler({ session: interactiveSession, deliver: delivery });
+ *
+ * ws.on('message', (data) => onMessage(String(data)));
+ * ws.on('close', cleanup);
+ * ```
+ */
+export function createSessionMessageHandler(options: ISessionMessageHandlerOptions): {
+  onMessage: (data: string) => void;
+  cleanup: () => void;
+} {
+  const role = options.role ?? 'drive';
+  const unsubscribe = subscribeSessionEvents(options.session, options.deliver, {
+    getSurfaceDriverId: () => options.driverId,
+    receivePrompts: role === 'drive',
+  });
+  // One per connection: when the connection goes, work it started for a hosted app view (a tool call
+  // waiting on its permission prompt) is cancelled, so the prompt is withdrawn instead of left open.
+  const connection = new AbortController();
+  const cleanup = (): void => {
+    connection.abort();
+    unsubscribe();
+  };
+  const onMessage = createMessageHandler(
+    options.session,
+    options.deliver,
+    options.driverId,
+    {
+      personalUsageReporter: options.personalUsageReporter,
+      usageReporter: options.usageReporter,
+      storedSessionUsageReporter: options.storedSessionUsageReporter,
+    },
+    options.surface,
+    role,
+    options.sessionDirectory,
+    options.settingsReporter,
+    options.commandSurfaceLocality,
+    {
+      signal: connection.signal,
+      ...(options.maxFrameBytes !== undefined ? { maxFrameBytes: options.maxFrameBytes } : {}),
+    },
+  );
+
+  return { onMessage, cleanup };
+}
+
+function createMessageHandler(
+  session: TProjectReadCapableSession,
+  deliver: TOutboundDeliver,
+  driverId?: TDriverId,
+  reporters: IUsageQueryReporters = EMPTY_USAGE_REPORTERS,
+  surface?: TUsageSurface,
+  role: TSessionSurfaceRole = 'drive',
+  sessionDirectory?: ISessionDirectory,
+  settingsReporter?: ISettingsReporter,
+  commandSurfaceLocality?: TCommandSurfaceLocality,
+  appMessages?: IAppMessageOptions,
+): (data: string) => void {
+  return (data: string): void => {
+    const msg = parseClientMessage(data, deliver);
+    if (!msg) return;
+    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,
+      appMessages,
+    );
+  };
+}
+
+const EMPTY_USAGE_REPORTERS: IUsageQueryReporters = {
+  personalUsageReporter: undefined,
+  usageReporter: undefined,
+  storedSessionUsageReporter: undefined,
+};
+
+/**
+ * Route a parsed client message to the session (control/query/background/prompt-response). Exported for E4:
+ * the {@link SessionResumeBridge} intercepts `resume`/`ack` itself and delegates everything else here.
+ */
+export function handleClientMessage(
+  session: TProjectReadCapableSession,
+  deliver: TOutboundDeliver,
+  msg: TClientMessage,
+  driverId?: TDriverId,
+  reporters: IUsageQueryReporters = EMPTY_USAGE_REPORTERS,
+  surface?: TUsageSurface,
+  sessionDirectory?: ISessionDirectory,
+  settingsReporter?: ISettingsReporter,
+  commandSurfaceLocality?: TCommandSurfaceLocality,
+  appMessages?: IAppMessageOptions,
+): 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, 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 (isAppToolMessage(msg)) {
+    handleAppToolMessage(session, deliver, msg, driverId, appMessages);
+    return;
+  }
+  if (isAppViewMessage(msg)) {
+    handleAppViewMessage(session, deliver, msg, appMessages);
+    return;
+  }
+  if (isBackgroundQueryMessage(msg)) {
+    handleBackgroundQueryMessage(session, deliver, msg);
+    return;
+  }
+  if (isBackgroundControlMessage(msg)) {
+    handleBackgroundControlMessage(session, deliver, msg);
+    return;
+  }
+  if (isPromptResponseMessage(msg)) {
+    handlePromptResponseMessage(session, msg, driverId);
+    return;
+  }
+  const unknownType = (msg as { type: string }).type;
+  deliver({ type: 'protocol_error', message: `Unknown message type: ${unknownType}` });
+}
+
+function isSessionControlMessage(
+  msg: TClientMessage,
+): msg is Extract<TClientMessage, { type: 'submit' | 'command' | 'abort' | 'cancel-queue' }> {
+  return (
+    msg.type === 'submit' ||
+    msg.type === 'command' ||
+    msg.type === 'abort' ||
+    msg.type === 'cancel-queue'
+  );
+}
+
+function isBackgroundQueryMessage(
+  msg: TClientMessage,
+): msg is Extract<
+  TClientMessage,
+  | { type: 'get-background-tasks' | 'get-background-task' | 'read-background-task-log' }
+  | { type: 'get-background-job-groups' | 'get-background-job-group' | 'wait-background-job-group' }
+> {
+  return (
+    msg.type === 'get-background-tasks' ||
+    msg.type === 'get-background-task' ||
+    msg.type === 'read-background-task-log' ||
+    msg.type === 'get-background-job-groups' ||
+    msg.type === 'get-background-job-group' ||
+    msg.type === 'wait-background-job-group'
+  );
+}
+
+function isBackgroundControlMessage(
+  msg: TClientMessage,
+): msg is Extract<
+  TClientMessage,
+  { type: 'cancel-background-task' | 'close-background-task' | 'send-background-task' }
+> {
+  return (
+    msg.type === 'cancel-background-task' ||
+    msg.type === 'close-background-task' ||
+    msg.type === 'send-background-task'
+  );
+}
+
+function isPromptResponseMessage(
+  msg: TClientMessage,
+): msg is Extract<TClientMessage, { type: 'permission-response' | 'ask-response' }> {
+  return msg.type === 'permission-response' || msg.type === 'ask-response';
+}
+
+/**
+ * REMOTE-007: a driving client answered a pending prompt by id. `resolvePermission`/`resolveAsk` are
+ * idempotent — a stale id (already answered by another surface, or drained) is a safe no-op, so no
+ * acknowledgement is needed; the resulting `prompt_resolved` server event is the shared signal.
+ */
+function handlePromptResponseMessage(
+  session: IProtocolSession,
+  msg: Extract<TClientMessage, { type: 'permission-response' | 'ask-response' }>,
+  driverId?: TDriverId,
+): void {
+  // REMOTE-014 E5: record the SERVER-ASSIGNED answering driver (not client-sent) on `prompt_resolved`.
+  if (msg.type === 'permission-response') {
+    session.resolvePermission(msg.id, msg.result, driverId);
+  } else {
+    session.resolveAsk(msg.id, msg.response, driverId);
+  }
+}
+
+function handleSessionControlMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  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
+    // and passed the previous `!msg.prompt` guard. It matters more here than at the other payload
+    // fields because the value does not stop at this session — it is re-emitted as `user_message` to
+    // EVERY attached client inside a frame whose `content` is declared `string`.
+    if (typeof msg.prompt !== 'string' || msg.prompt.length === 0) {
+      deliver({ type: 'protocol_error', message: 'prompt must be a non-empty string' });
+      return;
+    }
+    // REMOTE-014 E5: attribute this remote turn to the SERVER-ASSIGNED driver id (never a client-sent one).
+    const submitOptions = {
+      ...(driverId ? { driverId } : {}),
+      ...(surface ? { surface } : {}),
+    };
+    session
+      .submit(
+        msg.prompt,
+        undefined,
+        undefined,
+        Object.keys(submitOptions).length > 0 ? submitOptions : undefined,
+      )
+      .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', ...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, commandSurfaceLocality).then(
+      (result) => {
+        deliver({
+          type: 'command_result',
+          name: msg.name,
+          message: result?.message ?? `Unknown command: ${msg.name}`,
+          success: result?.success ?? false,
+          data: result?.data,
+          ...request,
+        });
+      },
+      (error: Error) => {
+        deliver({ type: 'protocol_error', message: error.message, ...request });
+      },
+    );
+  } else if (msg.type === 'abort') {
+    session.abort();
+  } else {
+    session.cancelQueue();
+  }
+}

package/src/session-query-messages.ts

@@ -0,0 +1,160 @@
+import { listOpenPrompts } from './open-prompts.js';
+
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { IWireHistoryEntry, TClientMessage, TServerMessage } from './wire-messages.js';
+
+type TSessionQueryMessage = Extract<
+  TClientMessage,
+  {
+    type:
+      | '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 === 'read-execution-detail'
+  );
+}
+
+export function handleSessionQueryMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TSessionQueryMessage,
+): void {
+  if (msg.type === 'get-messages') {
+    // #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') {
+    deliver({
+      type: 'execution_workspace_event',
+      snapshot: session.getExecutionWorkspaceSnapshot(),
+    });
+  } else if (msg.type === 'read-execution-detail') {
+    readExecutionDetail(session, deliver, msg);
+  } else {
+    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();
+}