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

package/src/message-decoders.ts

@@ -14,7 +14,10 @@
  * owner and is tracked there, not duplicated in a transport package.
  */
 
-import { SESSION_CHANGE_REFUSAL_CODES } from '@robota-sdk/agent-interface-session';
+import {
+  SESSION_CHANGE_REFUSAL_CODES,
+  SESSION_DELETE_REFUSAL_CODES,
+} from '@robota-sdk/agent-interface-session';
 
 import type { TBackgroundControlAction, TClientMessage, TServerMessage } from './wire-messages.js';
 
@@ -58,6 +61,11 @@ const isWireHistoryEntry = (v: unknown): boolean =>
   isString(v['type']);
 const isWireHistoryEntries = (v: unknown): boolean =>
   Array.isArray(v) && v.every(isWireHistoryEntry);
+/** #3282 §4: one row of `agent_definitions` — name, one-line description, plain-words location. */
+const isWireAgentDefinition = (v: unknown): boolean =>
+  isRecord(v) && isString(v['name']) && isString(v['description']) && isString(v['definedIn']);
+const isWireAgentDefinitions = (v: unknown): boolean =>
+  Array.isArray(v) && v.every(isWireAgentDefinition);
 
 type TFieldCheck = (value: unknown) => boolean;
 type TVariantShape = Readonly<Record<string, TFieldCheck>>;
@@ -96,6 +104,38 @@ const isActionResponse: TFieldCheck = (v) =>
     isOptional(isString)(v['text'])) ||
     (v['type'] === 'cancelled' && v['values'] === undefined && v['text'] === undefined));
 
+type TSettingsPatch = Extract<TClientMessage, { type: 'update-settings' }>['patch'];
+/** Keyed by `field`, so a patch variant added to the union without a shape here fails to compile. */
+const SETTINGS_PATCH_SHAPES: Readonly<Record<TSettingsPatch['field'], TVariantShape>> = {
+  language: { language: isNonEmptyString },
+  outputStyle: { styleId: isNonEmptyString },
+  preset: { presetId: isNonEmptyString },
+  permissionMode: { mode: isNonEmptyString },
+  sandbox: { enabled: isBoolean },
+  removePermissionRule: {
+    scope: isNonEmptyString,
+    kind: oneOf(['allow', 'deny', 'ask']),
+    pattern: isNonEmptyString,
+  },
+  mcpServerEnabled: { serverId: isNonEmptyString, enabled: isBoolean },
+  reloadMcpServers: {},
+  pluginEnabled: { pluginId: isNonEmptyString, enabled: isBoolean },
+  reloadPlugins: {},
+  installPlugin: { pluginId: isNonEmptyString },
+  uninstallPlugin: { pluginId: isNonEmptyString },
+  // #3282 §4b: "Providers & Models" — Use, Model, Delete.
+  providerProfile: { profileName: isNonEmptyString },
+  providerModel: { profileName: isNonEmptyString, modelId: isNonEmptyString },
+  deleteProviderProfile: { profileName: isNonEmptyString },
+};
+const isSettingsPatch: TFieldCheck = (v) => {
+  if (!isRecord(v) || !isString(v['field'])) return false;
+  const field = v['field'];
+  if (!Object.prototype.hasOwnProperty.call(SETTINGS_PATCH_SHAPES, field)) return false;
+  const shape = SETTINGS_PATCH_SHAPES[field as TSettingsPatch['field']];
+  return Object.entries(shape).every(([key, check]) => check(v[key]));
+};
+
 type TWaitingLoopStopOutcome = Extract<TServerMessage, { type: 'waiting_loop_stop' }>['outcome'];
 /** Keyed by `kind`, so an outcome added to the union without a shape here fails to compile. */
 const WAITING_LOOP_STOP_OUTCOME_SHAPES: Readonly<
@@ -114,6 +154,72 @@ const isWaitingLoopStopOutcome: TFieldCheck = (v) => {
   return Object.entries(shape).every(([field, check]) => check(v[field]));
 };
 
+/** Decode a `kind`-discriminated result union (the `TWaitingLoopStopOutcome` convention) from a shape
+ *  map keyed by `kind`. */
+function isKindDiscriminated(shapes: Readonly<Record<string, TVariantShape>>): TFieldCheck {
+  return (v) => {
+    if (!isRecord(v) || !isString(v['kind'])) return false;
+    const shape = Object.prototype.hasOwnProperty.call(shapes, v['kind']) ? shapes[v['kind']] : undefined;
+    if (shape === undefined) return false;
+    return Object.entries(shape).every(([field, check]) => check(v[field]));
+  };
+}
+
+// #3282 §4c: the Project panel's reads. Each result is the session method's own return value, crossing
+// the wire unchanged (the `TWaitingLoopStopOutcome` convention above) — decoded from a `kind`-keyed
+// shape map the same way.
+const PROJECT_FILE_STATUSES = [
+  'Added',
+  'Modified',
+  'Deleted',
+  'Renamed',
+  'Copied',
+  'Untracked',
+  'Conflicted',
+] as const;
+const isProjectStatusFile: TFieldCheck = (v) =>
+  isRecord(v) &&
+  isNonEmptyString(v['path']) &&
+  oneOf(PROJECT_FILE_STATUSES)(v['status']) &&
+  isOptional(isNonEmptyString)(v['renamedFrom']) &&
+  isOptional(isFiniteNumber)(v['added']) &&
+  isOptional(isFiniteNumber)(v['removed']);
+const isProjectStatusFiles: TFieldCheck = (v) => Array.isArray(v) && v.every(isProjectStatusFile);
+
+type TProjectStatusReadResult = Extract<TServerMessage, { type: 'project_status' }>['result'];
+const PROJECT_STATUS_READ_SHAPES: Readonly<Record<TProjectStatusReadResult['kind'], TVariantShape>> = {
+  status: {
+    branch: isOptional(isString),
+    unborn: isBoolean,
+    files: isProjectStatusFiles,
+    truncated: isBoolean,
+  },
+  'not-a-repository': {},
+  failed: { message: isString },
+};
+const isProjectStatusRead = isKindDiscriminated(PROJECT_STATUS_READ_SHAPES);
+
+const DIFF_LINE_TYPES = ['add', 'remove', 'context', 'hunk'] as const;
+const isDiffLine: TFieldCheck = (v) =>
+  isRecord(v) && oneOf(DIFF_LINE_TYPES)(v['type']) && isString(v['text']) && isFiniteNumber(v['lineNumber']);
+const isDiffLines: TFieldCheck = (v) => Array.isArray(v) && v.every(isDiffLine);
+
+type TProjectDiffReadResult = Extract<TServerMessage, { type: 'project_diff' }>['result'];
+const PROJECT_DIFF_READ_SHAPES: Readonly<Record<TProjectDiffReadResult['kind'], TVariantShape>> = {
+  diff: { diffLines: isDiffLines, truncated: isBoolean },
+  'not-a-repository': {},
+  'outside-workspace': {},
+  failed: { message: isString },
+};
+const isProjectDiffRead = isKindDiscriminated(PROJECT_DIFF_READ_SHAPES);
+
+type TProjectMemoryReadResult = Extract<TServerMessage, { type: 'project_memory' }>['result'];
+const PROJECT_MEMORY_READ_SHAPES: Readonly<Record<TProjectMemoryReadResult['kind'], TVariantShape>> = {
+  memory: { content: isString, path: isNonEmptyString, truncated: isBoolean },
+  unavailable: { message: isString },
+};
+const isProjectMemoryRead = isKindDiscriminated(PROJECT_MEMORY_READ_SHAPES);
+
 /** One entry per `TClientMessage` variant — a variant added to the union without one fails the test. */
 export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVariantShape>> = {
   submit: { prompt: isNonEmptyString },
@@ -130,9 +236,17 @@ export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVar
   'get-context': {},
   'get-commands': {},
   'get-status': {},
+  'list-models': { requestId: isNonEmptyString },
+  'get-agent-definitions': { requestId: isNonEmptyString },
   'list-sessions': { requestId: isNonEmptyString },
   'new-session': { requestId: isOptional(isNonEmptyString) },
   'switch-session': { sessionId: isNonEmptyString, requestId: isOptional(isNonEmptyString) },
+  'rename-session': {
+    sessionId: isNonEmptyString,
+    name: isNonEmptyString,
+    requestId: isNonEmptyString,
+  },
+  'delete-session': { sessionId: isNonEmptyString, requestId: isNonEmptyString },
   'get-usage-report': {},
   'get-personal-usage-report': {
     requestId: isNonEmptyString,
@@ -152,6 +266,9 @@ export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVar
     cursor: isOptional(isExecutionDetailCursor),
   },
   'stop-waiting-loop': { requestId: isNonEmptyString },
+  'project-status': { requestId: isNonEmptyString },
+  'project-diff': { requestId: isNonEmptyString, path: isNonEmptyString },
+  'project-memory': { requestId: isNonEmptyString },
   'get-background-tasks': { filter: isOptional(isBackgroundTaskListFilter) },
   'get-background-task': { taskId: isNonEmptyString },
   'get-background-job-groups': {},
@@ -168,6 +285,8 @@ export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVar
   'ask-response': { id: isNonEmptyString, response: isActionResponse },
   resume: { lastSeq: isFiniteNumber },
   ack: { seq: isFiniteNumber },
+  'get-settings': { requestId: isNonEmptyString },
+  'update-settings': { requestId: isNonEmptyString, patch: isSettingsPatch },
 };
 
 const authored: TVariantShape = { driverId: isOptional(isString) };
@@ -181,20 +300,38 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
   thinking: { isThinking: isBoolean, ...authored },
   complete: { result: isRecord, ...authored },
   interrupted: { result: isRecord, ...authored },
-  error: { message: isString, ...authored },
+  error: {
+    message: isString,
+    code: isOptional(oneOf(['auth', 'rate_limit', 'model_unavailable', 'network', 'provider'])),
+    provider: isOptional(isString),
+    retryAfterSeconds: isOptional(isFiniteNumber),
+    model: isOptional(isString),
+    ...authored,
+  },
   command_result: {
     name: isString,
     message: isString,
     success: isBoolean,
     requestId: isOptional(isString),
   },
-  messages: { messages: isRecordArray },
+  messages: { messages: isRecordArray, display: isOptional(isRecordArray), ...authored },
   history: { startIndex: isCount, total: isCount, entries: isWireHistoryEntries },
   context: { state: isRecord },
   history_changed: {},
   turn_source: { source: oneOf(Object.keys(TURN_SOURCES)) },
   commands: { commands: isRecordArray, skills: isRecordArray },
   session_status: { status: isRecord },
+  model_list: {
+    requestId: isNonEmptyString,
+    groups: isRecordArray,
+    currentProfile: isOptional(isString),
+    currentModel: isString,
+  },
+  agent_definitions: {
+    requestId: isNonEmptyString,
+    agents: isWireAgentDefinitions,
+    current: isNonEmptyString,
+  },
   sessions: { requestId: isNonEmptyString, listing: isRecord },
   sessions_error: {
     requestId: isNonEmptyString,
@@ -207,6 +344,14 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
     message: isString,
     requestId: isOptional(isString),
   },
+  session_renamed_in_list: { requestId: isNonEmptyString, sessionId: isString, name: isString },
+  session_rename_failed: { requestId: isNonEmptyString, message: isString },
+  session_deleted: { requestId: isNonEmptyString, sessionId: isString },
+  session_delete_failed: {
+    requestId: isNonEmptyString,
+    code: oneOf(SESSION_DELETE_REFUSAL_CODES),
+    message: isString,
+  },
   usage_report: { report: isRecord },
   personal_usage_report: { requestId: isNonEmptyString, report: isRecord },
   personal_usage_report_error: {
@@ -232,6 +377,9 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
   execution_detail: { requestId: isNonEmptyString, page: isRecord },
   execution_detail_error: { requestId: isNonEmptyString, message: isString },
   waiting_loop_stop: { requestId: isNonEmptyString, outcome: isWaitingLoopStopOutcome },
+  project_status: { requestId: isNonEmptyString, result: isProjectStatusRead },
+  project_diff: { requestId: isNonEmptyString, result: isProjectDiffRead },
+  project_memory: { requestId: isNonEmptyString, result: isProjectMemoryRead },
   background_task_event: { event: isRecord },
   background_job_group_event: { event: isRecord },
   plan_event: { event: isRecord },
@@ -256,6 +404,12 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
   },
   protocol_error: { message: isString, requestId: isOptional(isString) },
   resume_gap: {},
+  settings: { requestId: isNonEmptyString, settings: isRecord },
+  settings_error: {
+    requestId: isNonEmptyString,
+    code: oneOf(['not_available', 'invalid', 'refused', 'update_failed']),
+    message: isString,
+  },
 };
 
 function decodeVariant<TMessage extends { type: string }>(

package/src/observer-messages.ts

@@ -16,10 +16,12 @@ export const OBSERVER_MESSAGES: ReadonlySet<TClientMessage['type']> = new Set<
   'get-context',
   'get-status',
   'get-commands',
+  'list-models',
   'get-executing',
   'get-pending',
   'get-execution-workspace',
   'read-execution-detail',
+  'get-agent-definitions',
   'get-usage-report',
   'list-sessions',
   'get-background-tasks',
@@ -28,6 +30,15 @@ export const OBSERVER_MESSAGES: ReadonlySet<TClientMessage['type']> = new Set<
   'get-background-job-group',
   'wait-background-job-group',
   'read-background-task-log',
+  // #3282 §4a: reading the Settings snapshot is a pure read of this session's own configuration.
+  // `update-settings` stays out — an observer never writes.
+  'get-settings',
+  // #3282 §4c: the Project panel's reads — git status, one file's diff, project memory. All three are
+  // read-only (there is no "restore"/write counterpart in this feature — see the SPEC.md design
+  // decision on why checkpoints/rewind are excluded entirely), so all three are observer-safe.
+  'project-status',
+  'project-diff',
+  'project-memory',
 ]);
 
 /** Whether an observer may send a message of this type. */

package/src/project-read-messages.ts

@@ -0,0 +1,74 @@
+/**
+ * #3282 §4c — the Project panel's reads (git status, one file's diff, project memory).
+ *
+ * `TProjectReadCapableSession` is `IProtocolSession & Partial<ISessionProjectRead>` (see
+ * `protocol-session.ts`'s doc comment): the three methods are runtime-probed, never assumed, so
+ * adding this capability changes nothing for a session or test double that does not have it — a
+ * request against one answers `protocol_error` (host-neutral, not a made-up "kind"), the same way an
+ * unknown message type already does.
+ */
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { TProjectReadCapableSession } from './protocol-session.js';
+import type { TClientMessage } from './wire-messages.js';
+
+type TProjectReadMessage = Extract<
+  TClientMessage,
+  { type: 'project-status' | 'project-diff' | 'project-memory' }
+>;
+
+export function isProjectReadMessage(msg: TClientMessage): msg is TProjectReadMessage {
+  return msg.type === 'project-status' || msg.type === 'project-diff' || msg.type === 'project-memory';
+}
+
+function notSupported(deliver: TOutboundDeliver, requestId: string): void {
+  deliver({
+    type: 'protocol_error',
+    message: 'This host does not support the Project panel.',
+    requestId,
+  });
+}
+
+export function handleProjectReadMessage(
+  session: TProjectReadCapableSession,
+  deliver: TOutboundDeliver,
+  msg: TProjectReadMessage,
+): void {
+  const { requestId } = msg;
+  if (msg.type === 'project-status') {
+    if (!session.readProjectStatus) return notSupported(deliver, requestId);
+    session.readProjectStatus().then(
+      (result) => deliver({ type: 'project_status', requestId, result }),
+      (error: unknown) =>
+        deliver({
+          type: 'project_status',
+          requestId,
+          result: { kind: 'failed', message: error instanceof Error ? error.message : String(error) },
+        }),
+    );
+  } else if (msg.type === 'project-diff') {
+    if (!session.readProjectDiff) return notSupported(deliver, requestId);
+    session.readProjectDiff(msg.path).then(
+      (result) => deliver({ type: 'project_diff', requestId, result }),
+      (error: unknown) =>
+        deliver({
+          type: 'project_diff',
+          requestId,
+          result: { kind: 'failed', message: error instanceof Error ? error.message : String(error) },
+        }),
+    );
+  } else {
+    if (!session.readProjectMemory) return notSupported(deliver, requestId);
+    session.readProjectMemory().then(
+      (result) => deliver({ type: 'project_memory', requestId, result }),
+      (error: unknown) =>
+        deliver({
+          type: 'project_memory',
+          requestId,
+          result: {
+            kind: 'unavailable',
+            message: error instanceof Error ? error.message : String(error),
+          },
+        }),
+    );
+  }
+}

package/src/protocol-session.ts

@@ -1,4 +1,5 @@
 import type {
+  ISessionAgentJobs,
   ISessionBackgroundGroups,
   ISessionBackgroundTasks,
   ISessionCommands,
@@ -8,6 +9,7 @@ import type {
   ISessionExecutionDetail,
   ISessionExecutionState,
   ISessionExecutionWorkspace,
+  ISessionProjectRead,
   ISessionPromptResolution,
   ISessionSelfPacedLoopControl,
   ISessionStatusRead,
@@ -31,4 +33,18 @@ export interface IProtocolSession
     ISessionBackgroundGroups,
     ISessionExecutionWorkspace,
     ISessionExecutionDetail,
-    ISessionSelfPacedLoopControl {}
+    ISessionSelfPacedLoopControl,
+    // #3282 §4: the agent switcher's read (`listAgentDefinitions`/`getDefaultAgentType`) — the
+    // group's write members (`spawnAgentJob` and friends) stay unused by any wire handler; they run
+    // only through `executeCommand`, same as every other command-only write.
+    ISessionAgentJobs {}
+
+/**
+ * #3282 §4c: a protocol session that ALSO answers the Project panel's reads. `Partial` (not a fourth
+ * mandatory role on {@link IProtocolSession} itself) deliberately: every existing test double and
+ * every other host that builds an `IProtocolSession` keeps type-checking unchanged, and the panel's
+ * three methods are runtime-probed (`typeof session.readProjectStatus === 'function'`) rather than
+ * assumed — `InteractiveSession` (the one production implementation) provides all three, satisfying
+ * this type with no further wiring.
+ */
+export type TProjectReadCapableSession = IProtocolSession & Partial<ISessionProjectRead>;

package/src/session-directory-messages.ts

@@ -1,4 +1,4 @@
-import { isSessionChangeRefusal } from '@robota-sdk/agent-interface-session';
+import { isSessionChangeRefusal, isSessionDeleteRefusal } from '@robota-sdk/agent-interface-session';
 
 import type { TOutboundDeliver } from './outbound-delivery.js';
 import type { TClientMessage } from './wire-messages.js';
@@ -15,6 +15,17 @@ export function isSessionDirectoryMessage(msg: TClientMessage): msg is TSessionD
   );
 }
 
+type TSessionRenameMessage = Extract<TClientMessage, { type: 'rename-session' }>;
+type TSessionDeleteMessage = Extract<TClientMessage, { type: 'delete-session' }>;
+
+export function isSessionRenameMessage(msg: TClientMessage): msg is TSessionRenameMessage {
+  return msg.type === 'rename-session';
+}
+
+export function isSessionDeleteMessage(msg: TClientMessage): msg is TSessionDeleteMessage {
+  return msg.type === 'delete-session';
+}
+
 /**
  * #3189: the host's sessions. Listing answers on its own correlated reply. A new session or a switch
  * answers nothing on success: `session_switched` from the connection's own session is the signal. A
@@ -83,3 +94,69 @@ function listSessions(
 function failureMessage(error: Error | string): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+/**
+ * #3289 §1: rename a session from the list — current or not. Success replies with the new name so
+ * the client can update it optimistically; the client also re-lists to pick up everything else a
+ * rename can imply (nothing today, but the reply shape matches `delete-session`'s on purpose).
+ */
+export function handleSessionRenameMessage(
+  deliver: TOutboundDeliver,
+  msg: TSessionRenameMessage,
+  directory: ISessionDirectory | undefined,
+): void {
+  if (!directory) {
+    deliver({
+      type: 'session_rename_failed',
+      requestId: msg.requestId,
+      message: 'Sessions cannot be renamed on this host.',
+    });
+    return;
+  }
+  directory.renameSession(msg.sessionId, msg.name).then(
+    () =>
+      deliver({
+        type: 'session_renamed_in_list',
+        requestId: msg.requestId,
+        sessionId: msg.sessionId,
+        name: msg.name,
+      }),
+    (error: Error | string) =>
+      deliver({
+        type: 'session_rename_failed',
+        requestId: msg.requestId,
+        message: failureMessage(error),
+      }),
+  );
+}
+
+/**
+ * #3289 §1: remove a stored session's record. Refused when it is live on another client or running a
+ * turn; deleting the current session switches this binding away first (the directory's own job), so
+ * by the time this answers, the caller's own session is never the one just removed.
+ */
+export function handleSessionDeleteMessage(
+  deliver: TOutboundDeliver,
+  msg: TSessionDeleteMessage,
+  directory: ISessionDirectory | undefined,
+): void {
+  if (!directory) {
+    deliver({
+      type: 'session_delete_failed',
+      requestId: msg.requestId,
+      code: 'not_available',
+      message: 'Sessions cannot be deleted on this host.',
+    });
+    return;
+  }
+  directory.deleteSession(msg.sessionId).then(
+    () => deliver({ type: 'session_deleted', requestId: msg.requestId, sessionId: msg.sessionId }),
+    (error: Error | string) =>
+      deliver({
+        type: 'session_delete_failed',
+        requestId: msg.requestId,
+        code: isSessionDeleteRefusal(error) ? error.code : 'failed',
+        message: failureMessage(error),
+      }),
+  );
+}

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 =>