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

package/src/session-events.ts

@@ -0,0 +1,198 @@
+/**
+ * Outbound session-event subscription for the WS/WebRTC transports (split from `session-message-handler.ts` —
+ * the inbound message routing stays there; this module owns the session→`TServerMessage` fan-out).
+ *
+ * Used by `createSessionMessageHandler` (one subscription per channel) and by the persistent
+ * `SessionResumeBridge` (REMOTE-013 E4 — a SINGLE subscription that outlives per-channel handlers).
+ */
+
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type {
+  IExecutionWorkspaceEvent,
+  TBackgroundJobGroupEvent,
+  TBackgroundTaskEvent,
+} from '@robota-sdk/agent-interface-execution';
+import type { TDriverId, TInteractiveEventName } from '@robota-sdk/agent-interface-session';
+import type {
+  IAskRequestEvent,
+  IBranchEvent,
+  IContextFileRefreshedEvent,
+  IExecutionResult,
+  IPermissionRequestEvent,
+  IPromptResolvedEvent,
+  IPlanApprovalEvent,
+  ISessionRenamedEvent,
+  IToolState,
+  IUiIntentEvent,
+} from '@robota-sdk/agent-interface-session';
+
+export type TProtocolSessionEventClassification = 'forwarded' | 'requester-routed' | 'non-surface';
+
+/** Exhaustive protocol-owner policy over the shared session-event vocabulary. */
+export const PROTOCOL_SESSION_EVENT_CLASSIFICATION = {
+  text_delta: 'forwarded',
+  tool_start: 'forwarded',
+  tool_end: 'forwarded',
+  thinking: 'forwarded',
+  complete: 'forwarded',
+  error: 'forwarded',
+  context_update: 'non-surface',
+  compact: 'non-surface',
+  interrupted: 'forwarded',
+  skill_activation: 'non-surface',
+  background_task_event: 'forwarded',
+  background_job_group_event: 'forwarded',
+  execution_workspace_event: 'forwarded',
+  user_message: 'forwarded',
+  turn_source: 'non-surface',
+  context_file_refreshed: 'forwarded',
+  memory_event: 'non-surface',
+  goal_event: 'non-surface',
+  plan_event: 'forwarded',
+  branch_event: 'forwarded',
+  permission_request: 'forwarded',
+  ask_request: 'forwarded',
+  prompt_resolved: 'forwarded',
+  ui_intent: 'requester-routed',
+  session_renamed: 'forwarded',
+  history_cleared: 'forwarded',
+} as const satisfies Record<TInteractiveEventName, TProtocolSessionEventClassification>;
+
+/**
+ * Options for {@link subscribeSessionEvents}.
+ *
+ * ARCH-030: `onDeliveryError` is NOT here. Carrier-failure containment moved to the one
+ * connection-scoped {@link TOutboundDeliver} boundary this function now receives, so the fan-out and
+ * every reply share a single guard instead of the fan-out having its own.
+ */
+export interface ISubscribeSessionEventsOptions {
+  /**
+   * CMD-004 Stage D: lazily read the SERVER-ASSIGNED driver id of THIS surface — `ui_intent` is
+   * requester-routed against it (lazy because the resume bridge binds the id only after pairing).
+   */
+  getSurfaceDriverId?: () => TDriverId | undefined;
+}
+
+/**
+ * Subscribe the session's events and forward each as a `TServerMessage` through the connection's
+ * outbound boundary; returns an unsubscribe. Exported (REMOTE-013 E4) so the persistent
+ * `SessionResumeBridge` can own a SINGLE subscription that outlives per-channel handlers.
+ *
+ * ARCH-030: the second parameter is the boundary, not a raw sink — a carrier `send` cannot be passed
+ * here, which is what keeps the fan-out and the reply paths on one guard.
+ */
+export function subscribeSessionEvents(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  options: ISubscribeSessionEventsOptions = {},
+): () => 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.
+  // 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.
+  const attr = (): { driverId?: TDriverId } => {
+    // ARCH-012: a plain call, not `?.() ?? undefined`. The member is required, so `null` means
+    // nobody is driving — it can no longer also mean "this host cannot answer".
+    const driverId = session.getActiveDriverId();
+    return driverId ? { driverId } : {};
+  };
+  const onUserMessage = (content: string): void =>
+    deliver({ type: 'user_message', content, ...attr() });
+  const onTextDelta = (delta: string): void => deliver({ type: 'text_delta', delta, ...attr() });
+  const onToolStart = (state: IToolState): void =>
+    deliver({ type: 'tool_start', state, ...attr() });
+  const onToolEnd = (state: IToolState): void => deliver({ type: 'tool_end', state, ...attr() });
+  const onThinking = (isThinking: boolean): void =>
+    deliver({ type: 'thinking', isThinking, ...attr() });
+  const onComplete = (result: IExecutionResult): void =>
+    deliver({ type: 'complete', result, ...attr() });
+  const onInterrupted = (result: IExecutionResult): void =>
+    deliver({ type: 'interrupted', result, ...attr() });
+  const onError = (error: Error): void =>
+    deliver({ type: 'error', message: error.message, ...attr() });
+  const onBackgroundTaskEvent = (event: TBackgroundTaskEvent): void =>
+    deliver({ type: 'background_task_event', event });
+  const onBackgroundJobGroupEvent = (event: TBackgroundJobGroupEvent): void =>
+    deliver({ type: 'background_job_group_event', event });
+  const onExecutionWorkspace = (event: IExecutionWorkspaceEvent): void =>
+    deliver({
+      type: 'execution_workspace_event',
+      snapshot: event.snapshot,
+    });
+  const onPlanEvent = (event: IPlanApprovalEvent): void => deliver({ type: 'plan_event', event });
+  const onContextFileRefreshed = (event: IContextFileRefreshedEvent): void =>
+    deliver({ type: 'context_file_refreshed', event });
+  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 =>
+    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.
+  const onUiIntent = (event: IUiIntentEvent): void => {
+    if (
+      event.requesterDriverId !== undefined &&
+      event.requesterDriverId !== options.getSurfaceDriverId?.()
+    ) {
+      return; // another surface's intent — this surface never sees it (and never buffers it)
+    }
+    deliver({ type: 'ui_intent', event });
+  };
+  // CMD-004 Stage E: BROADCAST session-state events — the host executed the rename/clear; EVERY
+  // attached surface (co-driving included) reflects it. Never requester-filtered, unlike `ui_intent`.
+  const onSessionRenamed = (event: ISessionRenamedEvent): void =>
+    deliver({ type: 'session_renamed', event });
+  const onHistoryCleared = (): void => deliver({ type: 'history_cleared' });
+
+  session.on('user_message', onUserMessage);
+  session.on('text_delta', onTextDelta);
+  session.on('tool_start', onToolStart);
+  session.on('tool_end', onToolEnd);
+  session.on('thinking', onThinking);
+  session.on('complete', onComplete);
+  session.on('interrupted', onInterrupted);
+  session.on('error', onError);
+  session.on('background_task_event', onBackgroundTaskEvent);
+  session.on('background_job_group_event', onBackgroundJobGroupEvent);
+  session.on('execution_workspace_event', onExecutionWorkspace);
+  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);
+  session.on('prompt_resolved', onPromptResolved);
+  session.on('ui_intent', onUiIntent);
+  session.on('session_renamed', onSessionRenamed);
+  session.on('history_cleared', onHistoryCleared);
+
+  return (): void => {
+    session.off('user_message', onUserMessage);
+    session.off('text_delta', onTextDelta);
+    session.off('tool_start', onToolStart);
+    session.off('tool_end', onToolEnd);
+    session.off('thinking', onThinking);
+    session.off('complete', onComplete);
+    session.off('interrupted', onInterrupted);
+    session.off('error', onError);
+    session.off('background_task_event', onBackgroundTaskEvent);
+    session.off('background_job_group_event', onBackgroundJobGroupEvent);
+    session.off('execution_workspace_event', onExecutionWorkspace);
+    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);
+    session.off('prompt_resolved', onPromptResolved);
+    session.off('ui_intent', onUiIntent);
+    session.off('session_renamed', onSessionRenamed);
+    session.off('history_cleared', onHistoryCleared);
+  };
+}

package/src/session-message-handler.ts

@@ -0,0 +1,282 @@
+/**
+ * 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 {
+  handleBackgroundControlMessage,
+  handleBackgroundQueryMessage,
+} from './background-messages.js';
+import { parseClientMessage } from './message-parser.js';
+import { subscribeSessionEvents } from './session-events.js';
+import { handleSessionQueryMessage, isSessionQueryMessage } from './session-query-messages.js';
+import { handleUsageQueryMessage } from './usage-messages.js';
+
+import type { TOutboundDeliver } from './outbound-delivery.js';
+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';
+
+// 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';
+
+export interface ISessionMessageHandlerOptions {
+  /** IProtocolSession to expose. */
+  session: IProtocolSession;
+  /**
+   * 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;
+  /** 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']>;
+}
+
+/**
+ * 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 cleanup = subscribeSessionEvents(options.session, options.deliver, {
+    getSurfaceDriverId: () => options.driverId,
+  });
+  const onMessage = createMessageHandler(
+    options.session,
+    options.deliver,
+    options.driverId,
+    {
+      personalUsageReporter: options.personalUsageReporter,
+      usageReporter: options.usageReporter,
+      storedSessionUsageReporter: options.storedSessionUsageReporter,
+    },
+    options.surface,
+  );
+
+  return { onMessage, cleanup };
+}
+
+function createMessageHandler(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  driverId?: TDriverId,
+  reporters: IUsageQueryReporters = EMPTY_USAGE_REPORTERS,
+  surface?: TUsageSurface,
+): (data: string) => void {
+  return (data: string): void => {
+    const msg = parseClientMessage(data, deliver);
+    if (!msg) return;
+    handleClientMessage(session, deliver, msg, driverId, reporters, surface);
+  };
+}
+
+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: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TClientMessage,
+  driverId?: TDriverId,
+  reporters: IUsageQueryReporters = EMPTY_USAGE_REPORTERS,
+  surface?: TUsageSurface,
+): void {
+  if (handleUsageQueryMessage(session, deliver, msg, reporters)) {
+    return;
+  }
+  if (isSessionControlMessage(msg)) {
+    handleSessionControlMessage(session, deliver, msg, driverId, surface);
+    return;
+  }
+  if (isSessionQueryMessage(msg)) {
+    handleSessionQueryMessage(session, deliver, msg);
+    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,
+): 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,
+      )
+      .catch((error: Error) => {
+        deliver({ type: 'protocol_error', message: error.message });
+      });
+  } else if (msg.type === 'command') {
+    if (!msg.name) {
+      deliver({ type: 'protocol_error', message: 'name is required' });
+      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(
+      (result) => {
+        deliver({
+          type: 'command_result',
+          name: msg.name,
+          message: result?.message ?? `Unknown command: ${msg.name}`,
+          success: result?.success ?? false,
+          data: result?.data,
+        });
+      },
+      (error: Error) => {
+        deliver({ type: 'protocol_error', message: error.message });
+      },
+    );
+  } else if (msg.type === 'abort') {
+    session.abort();
+  } else {
+    session.cancelQueue();
+  }
+}

package/src/session-query-messages.ts

@@ -0,0 +1,42 @@
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TClientMessage } from './wire-messages.js';
+
+type TSessionQueryMessage = Extract<
+  TClientMessage,
+  {
+    type:
+      'get-messages' | 'get-context' | 'get-executing' | 'get-pending' | 'get-execution-workspace';
+  }
+>;
+
+export function isSessionQueryMessage(msg: TClientMessage): msg is TSessionQueryMessage {
+  return (
+    msg.type === 'get-messages' ||
+    msg.type === 'get-context' ||
+    msg.type === 'get-executing' ||
+    msg.type === 'get-pending' ||
+    msg.type === 'get-execution-workspace'
+  );
+}
+
+export function handleSessionQueryMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TSessionQueryMessage,
+): void {
+  if (msg.type === 'get-messages') {
+    deliver({ type: 'messages', messages: session.getMessages() });
+  } else if (msg.type === 'get-context') {
+    deliver({ type: 'context', state: session.getContextState() });
+  } 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 {
+    deliver({ type: 'pending', pending: session.getPendingPrompt() });
+  }
+}