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

package/src/session-error-classification.ts

@@ -0,0 +1,91 @@
+/**
+ * What the `error` wire frame should say about a session failure, beyond its raw `message` (#3289
+ * §3). A renderer maps `code` to one plain sentence with the next step, keeping `message` behind a
+ * "Details" disclosure — see `agent-ui-web`'s `SessionNotices`.
+ *
+ * Walks wrapped layers (`originalError`/`cause`, a few deep) because a higher-level catch can wrap the
+ * provider's own typed error in another one (e.g. a "Conversation failed" `ProviderError`) before it
+ * reaches here — the same reason `agent-core`'s `classifyProviderFailure` walks layers rather than
+ * looking at the outermost error alone.
+ */
+
+import {
+  AuthenticationError,
+  ModelNotAvailableError,
+  NetworkError,
+  ProviderError,
+  RateLimitError,
+} from '@robota-sdk/agent-core';
+
+/** Kept in sync with `wire-messages.ts`'s `error` variant — see that type for what each means. */
+export type TSessionErrorCode =
+  'auth' | 'rate_limit' | 'model_unavailable' | 'network' | 'provider';
+
+export interface ISessionErrorClassification {
+  code?: TSessionErrorCode;
+  provider?: string;
+  retryAfterSeconds?: number;
+  /** For `code: 'model_unavailable'`, the model the request tried, when the failure named one. */
+  model?: string;
+}
+
+const MAX_WRAP_DEPTH = 8;
+
+/** The error and everything it wraps, outermost first, followed to a small depth and never twice. */
+function layersOf(error: unknown): unknown[] {
+  const layers: unknown[] = [];
+  const seen = new Set<unknown>();
+  let frontier: unknown[] = [error];
+  for (let depth = 0; depth <= MAX_WRAP_DEPTH && frontier.length > 0; depth++) {
+    const next: unknown[] = [];
+    for (const layer of frontier) {
+      if (layer === undefined || layer === null || seen.has(layer)) continue;
+      seen.add(layer);
+      layers.push(layer);
+      if (typeof layer === 'object') {
+        const record = layer as Record<string, unknown>;
+        next.push(record['originalError'], record['cause']);
+      }
+    }
+    frontier = next;
+  }
+  return layers;
+}
+
+/**
+ * Classify a session failure for the wire, or leave it uncoded when it names no provider at all —
+ * an unrelated internal failure keeps showing its raw `message` exactly as before this classification
+ * existed.
+ */
+export function classifySessionErrorForWire(error: unknown): ISessionErrorClassification {
+  // A generic ProviderError never wins outright — a wrapper (e.g. "Conversation failed") can sit
+  // above the real, more specific cause, so it is kept only as a fallback while deeper layers are
+  // still searched for one of the specific types below.
+  let fallback: ISessionErrorClassification | undefined;
+  for (const layer of layersOf(error)) {
+    if (layer instanceof AuthenticationError) {
+      return { code: 'auth', ...(layer.provider !== undefined && { provider: layer.provider }) };
+    }
+    if (layer instanceof RateLimitError) {
+      return {
+        code: 'rate_limit',
+        ...(layer.provider !== undefined && { provider: layer.provider }),
+        ...(layer.retryAfter !== undefined && { retryAfterSeconds: layer.retryAfter }),
+      };
+    }
+    if (layer instanceof ModelNotAvailableError) {
+      return {
+        code: 'model_unavailable',
+        provider: layer.provider,
+        ...(layer.model !== undefined && { model: layer.model }),
+      };
+    }
+    if (layer instanceof NetworkError) {
+      return { code: 'network', ...(layer.provider !== undefined && { provider: layer.provider }) };
+    }
+    if (fallback === undefined && layer instanceof ProviderError) {
+      fallback = { code: 'provider', provider: layer.provider };
+    }
+  }
+  return fallback ?? {};
+}

package/src/session-events.ts

@@ -7,6 +7,7 @@
  */
 
 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';
@@ -131,7 +132,12 @@ export function subscribeSessionEvents(
   const onInterrupted = (result: IExecutionResult): void =>
     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 =>

package/src/session-message-handler.ts

@@ -15,9 +15,14 @@ import {
 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 {
@@ -25,12 +30,15 @@ import {
   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 { ISessionDirectory, TDriverId } from '@robota-sdk/agent-interface-session';
 
@@ -48,8 +56,8 @@ export { parseClientMessage } from './message-parser.js';
 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
@@ -76,6 +84,15 @@ export interface ISessionMessageHandlerOptions {
   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;
 }
 
 /**
@@ -118,19 +135,23 @@ export function createSessionMessageHandler(options: ISessionMessageHandlerOptio
     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);
@@ -139,7 +160,17 @@ function createMessageHandler(
       deliver({ type: 'protocol_error', message: `Not permitted for an observer: ${msg.type}` });
       return;
     }
-    handleClientMessage(session, deliver, msg, driverId, reporters, surface, sessionDirectory);
+    handleClientMessage(
+      session,
+      deliver,
+      msg,
+      driverId,
+      reporters,
+      surface,
+      sessionDirectory,
+      settingsReporter,
+      commandSurfaceLocality,
+    );
   };
 }
 
@@ -154,13 +185,15 @@ 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;
@@ -169,8 +202,20 @@ export function handleClientMessage(
     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)) {
@@ -181,6 +226,10 @@ export function handleClientMessage(
     handleSessionQueryMessage(session, deliver, msg);
     return;
   }
+  if (isProjectReadMessage(msg)) {
+    handleProjectReadMessage(session, deliver, msg);
+    return;
+  }
   if (isBackgroundQueryMessage(msg)) {
     handleBackgroundQueryMessage(session, deliver, msg);
     return;
@@ -268,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
@@ -304,7 +354,7 @@ function handleSessionControlMessage(
     }
     // 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',

package/src/session-query-messages.ts

@@ -14,6 +14,8 @@ type TSessionQueryMessage = Extract<
       | 'get-context'
       | 'get-commands'
       | 'get-status'
+      | 'list-models'
+      | 'get-agent-definitions'
       | 'get-executing'
       | 'get-pending'
       | 'get-execution-workspace'
@@ -38,6 +40,8 @@ export function isSessionQueryMessage(msg: TClientMessage): msg is TSessionQuery
     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' ||
@@ -51,7 +55,10 @@ 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') {
@@ -62,6 +69,16 @@ export function handleSessionQueryMessage(
     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') {

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,
     );
   }
 

package/src/settings-messages.ts

@@ -0,0 +1,103 @@
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TClientMessage } from './wire-messages.js';
+import type { TCommandSurfaceLocality } from '@robota-sdk/agent-interface-command';
+import type { ISettingsSnapshot, TSettingsPatch } from '@robota-sdk/agent-interface-session';
+
+type TSettingsMessage = Extract<TClientMessage, { type: 'get-settings' | 'update-settings' }>;
+
+export function isSettingsMessage(msg: TClientMessage): msg is TSettingsMessage {
+  return msg.type === 'get-settings' || msg.type === 'update-settings';
+}
+
+/** What applying a patch did: the fresh snapshot, or why nothing was written. */
+export type TSettingsUpdateOutcome =
+  | { readonly ok: true; readonly settings: ISettingsSnapshot }
+  | {
+      readonly ok: false;
+      readonly code: 'not_available' | 'invalid' | 'refused' | 'update_failed';
+      readonly message: string;
+    };
+
+/**
+ * #3282 §4a: host-owned read/write for the Settings screen, supplied by the composition root the
+ * same way `IUsageQueryReporters` supplies usage reads — this package only correlates the request
+ * and carries the result. `updateSettings` applies through the SAME function the matching slash
+ * command uses (issue #3282 §4: "one code path, so the behavior matches the TUI"), so whatever a
+ * command would refuse on this surface is refused here too.
+ */
+export interface ISettingsReporter {
+  getSettings(
+    session: IProtocolSession,
+    locality?: TCommandSurfaceLocality,
+  ): ISettingsSnapshot | Promise<ISettingsSnapshot>;
+  /**
+   * Applies through the SAME function the matching slash command uses. `locality` (#3282 §4 part
+   * b-2) is forwarded to that command exactly as the transport received it, so a command that
+   * refuses a remote surface (installing a plugin) refuses identically here.
+   */
+  updateSettings(
+    session: IProtocolSession,
+    patch: TSettingsPatch,
+    locality?: TCommandSurfaceLocality,
+  ): TSettingsUpdateOutcome | Promise<TSettingsUpdateOutcome>;
+}
+
+export function handleSettingsMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TSettingsMessage,
+  reporter: ISettingsReporter | undefined,
+  locality?: TCommandSurfaceLocality,
+): void {
+  if (!reporter) {
+    deliverSettingsError(
+      deliver,
+      msg.requestId,
+      'not_available',
+      'Settings are not available on this host.',
+    );
+    return;
+  }
+  try {
+    if (msg.type === 'get-settings') {
+      void Promise.resolve(reporter.getSettings(session, locality)).then(
+        (settings) => deliver({ type: 'settings', requestId: msg.requestId, settings }),
+        (error) =>
+          deliverSettingsError(deliver, msg.requestId, 'update_failed', failureMessage(error)),
+      );
+      return;
+    }
+    void Promise.resolve(reporter.updateSettings(session, msg.patch, locality)).then(
+      (outcome) => {
+        if (outcome.ok) {
+          deliver({ type: 'settings', requestId: msg.requestId, settings: outcome.settings });
+        } else {
+          deliverSettingsError(deliver, msg.requestId, outcome.code, outcome.message);
+        }
+      },
+      (error) =>
+        deliverSettingsError(deliver, msg.requestId, 'update_failed', failureMessage(error)),
+    );
+  } catch (error) {
+    deliverSettingsError(
+      deliver,
+      msg.requestId,
+      'update_failed',
+      failureMessage(error instanceof Error ? error : String(error)),
+    );
+  }
+}
+
+function deliverSettingsError(
+  deliver: TOutboundDeliver,
+  requestId: string,
+  code: 'not_available' | 'invalid' | 'refused' | 'update_failed',
+  message: string,
+): void {
+  deliver({ type: 'settings_error', requestId, code, message });
+}
+
+function failureMessage(error: Error | string): string {
+  return error instanceof Error ? error.message : String(error);
+}