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

package/src/open-prompts.ts

@@ -0,0 +1,76 @@
+/**
+ * #3189: the permission and ask prompts a session has open, as the frames that asked them.
+ *
+ * The session keeps only the promise each prompt waits on, and emits the prompt once, when it is
+ * asked. A client that attaches later would never see a prompt already open. This keeps what the
+ * transport forwarded, per session, for a `get-prompts` reply.
+ *
+ * It is held by the connections that receive prompts and learns everything through their own
+ * subscriptions, so it never listens to the session itself. That matters: a session asks only while
+ * someone listens for prompts, and a listener of its own here would keep an unattended session's
+ * prompt open instead of failing it closed. When the last such connection goes, the session settles
+ * every open prompt, so nothing is kept.
+ */
+
+import type { IProtocolSession } from './protocol-session.js';
+import type { TServerMessage } from './wire-messages.js';
+
+export type TOpenPromptFrame = Extract<
+  TServerMessage,
+  { type: 'permission_request' | 'ask_request' }
+>;
+
+interface IOpenPrompts {
+  readonly frames: Map<string, TOpenPromptFrame>;
+  holders: number;
+}
+
+const openPromptsBySession = new WeakMap<IProtocolSession, IOpenPrompts>();
+
+/** One connection's hold on its session's open prompts; every holder reports what it forwards. */
+export interface IOpenPromptsHold {
+  /** A prompt was asked. */
+  record(frame: TOpenPromptFrame): void;
+  /** A prompt was settled, by an answer or by the session. */
+  forget(id: string): void;
+  /** The host made another session current; the previous session's prompts are settled. */
+  clear(): void;
+  /** This connection no longer receives prompts. */
+  release(): void;
+}
+
+/** Called by a connection that receives prompts, before it subscribes to them. */
+export function holdOpenPrompts(session: IProtocolSession): IOpenPromptsHold {
+  let open = openPromptsBySession.get(session);
+  if (open === undefined) {
+    open = { frames: new Map(), holders: 0 };
+    openPromptsBySession.set(session, open);
+  }
+  const held = open;
+  held.holders += 1;
+  let released = false;
+  return {
+    record: (frame) => {
+      if (!released) held.frames.set(frame.event.id, frame);
+    },
+    forget: (id) => {
+      held.frames.delete(id);
+    },
+    clear: () => {
+      held.frames.clear();
+    },
+    release: () => {
+      if (released) return;
+      released = true;
+      held.holders -= 1;
+      if (held.holders === 0 && openPromptsBySession.get(session) === held) {
+        openPromptsBySession.delete(session);
+      }
+    },
+  };
+}
+
+/** The prompts open now, oldest first; none when no connection that receives prompts is attached. */
+export function listOpenPrompts(session: IProtocolSession): readonly TOpenPromptFrame[] {
+  return [...(openPromptsBySession.get(session)?.frames.values() ?? [])];
+}

package/src/outbound-delivery.ts

@@ -64,8 +64,8 @@ export type TOutboundDeliver = ((message: TServerMessage) => void) & {
 
 /**
  * Observe THIS connection's first outbound delivery failure. `event` is the `type` of the frame that
- * could not be delivered — a session event's own name for the fan-out (they are identical), and the
- * reply's type for a reply (`command_result`, `protocol_error`, …).
+ * could not be delivered — for the fan-out, the frame a session event was forwarded as (usually, not
+ * always, the event's own name), and the reply's type for a reply (`command_result`, `protocol_error`, …).
  *
  * Required, never optional: a carrier that could opt out of observing its own delivery failures is the
  * silent-failure shape this boundary exists to remove.
@@ -98,6 +98,15 @@ export type TDeliveryErrorHandler = (error: Error, event: TServerMessage['type']
 const BYTES_PER_MIB = Number('1024') * Number('1024');
 export const DEFAULT_MAX_PENDING_BYTES = Number('8') * BYTES_PER_MIB;
 
+/**
+ * Backpressure budget for a terminal attached to a session on the same host, in either role.
+ *
+ * 1 MiB, tighter than the default: an attached terminal reads a local socket, so a backlog this large
+ * means it stopped reading rather than that a network is slow. Exceeding it closes that connection
+ * only; the session never waits for a reader, so other surfaces keep streaming.
+ */
+export const ATTACHED_SURFACE_MAX_PENDING_BYTES = BYTES_PER_MIB;
+
 /**
  * Is this carrier holding more than the budget allows?
  *

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,13 +1,18 @@
 import type {
+  ISessionAgentJobs,
   ISessionBackgroundGroups,
   ISessionBackgroundTasks,
   ISessionCommands,
   ISessionConversationRead,
   ISessionDriverAttribution,
   ISessionEvents,
+  ISessionExecutionDetail,
   ISessionExecutionState,
   ISessionExecutionWorkspace,
+  ISessionProjectRead,
   ISessionPromptResolution,
+  ISessionSelfPacedLoopControl,
+  ISessionStatusRead,
   ISessionTurnControl,
   ISessionTurnSubmission,
 } from '@robota-sdk/agent-interface-session';
@@ -18,6 +23,7 @@ export interface IProtocolSession
     ISessionTurnSubmission,
     ISessionTurnControl,
     ISessionCommands,
+    ISessionStatusRead,
     ISessionEvents,
     ISessionPromptResolution,
     ISessionConversationRead,
@@ -25,4 +31,20 @@ export interface IProtocolSession
     ISessionDriverAttribution,
     ISessionBackgroundTasks,
     ISessionBackgroundGroups,
-    ISessionExecutionWorkspace {}
+    ISessionExecutionWorkspace,
+    ISessionExecutionDetail,
+    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

@@ -0,0 +1,162 @@
+import { isSessionChangeRefusal, isSessionDeleteRefusal } from '@robota-sdk/agent-interface-session';
+
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { TClientMessage } from './wire-messages.js';
+import type { ISessionDirectory } from '@robota-sdk/agent-interface-session';
+
+type TSessionDirectoryMessage = Extract<
+  TClientMessage,
+  { type: 'list-sessions' | 'new-session' | 'switch-session' }
+>;
+
+export function isSessionDirectoryMessage(msg: TClientMessage): msg is TSessionDirectoryMessage {
+  return (
+    msg.type === 'list-sessions' || msg.type === 'new-session' || msg.type === 'switch-session'
+  );
+}
+
+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
+ * refusal answers `session_change_failed`, carrying the host's code (or `failed` for an error that is
+ * not a declared refusal) and the request's `requestId`.
+ */
+export function handleSessionDirectoryMessage(
+  deliver: TOutboundDeliver,
+  msg: TSessionDirectoryMessage,
+  directory: ISessionDirectory | undefined,
+): void {
+  if (msg.type === 'list-sessions') {
+    listSessions(deliver, msg.requestId, directory);
+    return;
+  }
+  const request = msg.requestId !== undefined ? { requestId: msg.requestId } : {};
+  if (!directory) {
+    deliver({
+      type: 'session_change_failed',
+      code: 'not_available',
+      message: 'Sessions cannot be switched on this host.',
+      ...request,
+    });
+    return;
+  }
+  const change = (): Promise<void> =>
+    msg.type === 'new-session' ? directory.newSession() : directory.switchSession(msg.sessionId);
+  void Promise.resolve()
+    .then(change)
+    .catch((error: Error | string) =>
+      deliver({
+        type: 'session_change_failed',
+        code: isSessionChangeRefusal(error) ? error.code : 'failed',
+        message: failureMessage(error),
+        ...request,
+      }),
+    );
+}
+
+function listSessions(
+  deliver: TOutboundDeliver,
+  requestId: string,
+  directory: ISessionDirectory | undefined,
+): void {
+  if (!directory) {
+    deliver({
+      type: 'sessions_error',
+      requestId,
+      code: 'not_available',
+      message: 'Session listing is not available on this host.',
+    });
+    return;
+  }
+  try {
+    deliver({ type: 'sessions', requestId, listing: directory.listSessions() });
+  } catch (error) {
+    deliver({
+      type: 'sessions_error',
+      requestId,
+      code: 'list_failed',
+      message: failureMessage(error instanceof Error ? error : String(error)),
+    });
+  }
+}
+
+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 ?? {};
+}