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

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

@@ -0,0 +1,56 @@
+import type {
+  ISessionAgentJobs,
+  ISessionBackgroundGroups,
+  ISessionBackgroundTasks,
+  ISessionCommands,
+  ISessionConversationRead,
+  ISessionDriverAttribution,
+  ISessionEvents,
+  ISessionExecutionDetail,
+  ISessionExecutionState,
+  ISessionExecutionWorkspace,
+  ISessionProjectRead,
+  ISessionPromptResolution,
+  ISessionRuntimeTools,
+  ISessionSelfPacedLoopControl,
+  ISessionStatusRead,
+  ISessionToolAppViews,
+  ISessionTurnControl,
+  ISessionTurnSubmission,
+} from '@robota-sdk/agent-interface-session';
+
+/** Session roles required by the shared WebSocket/WebRTC protocol. */
+export interface IProtocolSession
+  extends
+    ISessionTurnSubmission,
+    ISessionTurnControl,
+    ISessionCommands,
+    ISessionStatusRead,
+    ISessionEvents,
+    ISessionPromptResolution,
+    ISessionConversationRead,
+    ISessionExecutionState,
+    ISessionDriverAttribution,
+    ISessionBackgroundTasks,
+    ISessionBackgroundGroups,
+    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,
+    // A driving surface that hosts an app view runs one runtime tool for it (`call-app-tool`) and
+    // reads a finished call's view (`read-app-view`).
+    ISessionRuntimeTools,
+    ISessionToolAppViews {}
+
+/**
+ * #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/resume-buffer.ts

@@ -0,0 +1,123 @@
+/**
+ * Bounded un-acked output buffer for session-resume (REMOTE-013 Stage E4).
+ *
+ * Holds the tail of outbound `TServerMessage`s that a reconnecting client may not have received, keyed by a
+ * monotonic sequence number. On reconnect the client sends `resume{lastSeq}` and the host replays
+ * {@link ResumeBuffer.tailAfter}; a periodic `ack{seq}` frees everything up to `seq`. The buffer is bounded by
+ * a frame count AND a byte budget (drop-oldest) so a never-acking or gone peer cannot exhaust host memory —
+ * and when a client's `lastSeq` predates the oldest retained frame it returns an **overrun** marker so the
+ * client does a full refresh rather than accept a silent gap.
+ */
+
+import type { TServerMessage } from './wire-messages.js';
+
+/** One retained frame: its sequence number and the message. */
+export interface IBufferedFrame {
+  readonly seq: number;
+  readonly message: TServerMessage;
+}
+
+/** The result of a `tailAfter` — either the ordered replay slice, or an overrun (client must full-refresh). */
+export type TResumeTail =
+  | { readonly kind: 'tail'; readonly frames: readonly IBufferedFrame[] }
+  | { readonly kind: 'overrun' };
+
+export interface IResumeBufferOptions {
+  /** Max retained frames (drop-oldest beyond this). Default 512. */
+  readonly maxFrames?: number;
+  /** Max retained bytes across frames (drop-oldest beyond this). Default 4 MiB. */
+  readonly maxBytes?: number;
+  /** Serialized size of a message (for the byte budget). Default: JSON length. Injectable for tests. */
+  readonly sizeOf?: (message: TServerMessage) => number;
+}
+
+const DEFAULT_MAX_FRAMES = 512;
+const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
+
+/**
+ * A monotonic, bounded ring of un-acked frames. Sequence numbers are assigned by {@link append} and never
+ * reused; `tailAfter` / `ackThrough` operate over the retained window.
+ */
+export class ResumeBuffer {
+  private readonly frames: IBufferedFrame[] = [];
+  private readonly sizes: number[] = []; // parallel to `frames` — retained byte size per frame
+  private nextSeq = 1;
+  private bytes = 0;
+
+  private readonly maxFrames: number;
+  private readonly maxBytes: number;
+  private readonly sizeOf: (message: TServerMessage) => number;
+
+  public constructor(options: IResumeBufferOptions = {}) {
+    this.maxFrames = options.maxFrames ?? DEFAULT_MAX_FRAMES;
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.sizeOf = options.sizeOf ?? ((m) => JSON.stringify(m).length);
+  }
+
+  /** Append a message, assign + return its monotonic seq, and evict oldest frames beyond the bounds. */
+  public append(message: TServerMessage): number {
+    const seq = this.nextSeq;
+    this.nextSeq += 1;
+    const size = this.sizeOf(message);
+    this.frames.push({ seq, message });
+    this.sizes.push(size);
+    this.bytes += size;
+    this.evict();
+    return seq;
+  }
+
+  /** Drop all retained frames with `seq <= throughSeq` (the client confirmed receipt up to there). */
+  public ackThrough(throughSeq: number): void {
+    let drop = 0;
+    while (drop < this.frames.length && this.frames[drop].seq <= throughSeq) drop += 1;
+    this.removeOldest(drop);
+  }
+
+  /**
+   * The ordered frames with `seq > lastSeq`. Returns an `overrun` marker when `lastSeq` is older than the
+   * oldest retained frame (i.e. some frame after `lastSeq` was already evicted) — the client must full-refresh.
+   * `lastSeq` at or beyond the newest seq yields an empty tail (nothing to replay).
+   */
+  public tailAfter(lastSeq: number): TResumeTail {
+    if (this.frames.length === 0) {
+      // Nothing retained. Only an overrun if the client is behind the frames we HAVE emitted+evicted.
+      return lastSeq >= this.nextSeq - 1 ? { kind: 'tail', frames: [] } : { kind: 'overrun' };
+    }
+    const oldest = this.frames[0].seq;
+    if (lastSeq < oldest - 1) return { kind: 'overrun' };
+    return { kind: 'tail', frames: this.frames.filter((f) => f.seq > lastSeq) };
+  }
+
+  /** The last seq assigned (0 when nothing has been appended). */
+  public get lastSeq(): number {
+    return this.nextSeq - 1;
+  }
+
+  /** Retained frame count (diagnostics/tests). */
+  public get size(): number {
+    return this.frames.length;
+  }
+
+  private evict(): void {
+    let drop = 0;
+    let remainingBytes = this.bytes;
+    // Evict oldest while over the frame cap, or over the byte cap (but always keep at least the newest frame).
+    while (
+      this.frames.length - drop > this.maxFrames ||
+      (remainingBytes > this.maxBytes && this.frames.length - drop > 1)
+    ) {
+      remainingBytes -= this.sizes[drop];
+      drop += 1;
+    }
+    this.removeOldest(drop);
+  }
+
+  /** The single place that mutates `frames`/`sizes`/`bytes` for removal, so byte accounting can't drift. */
+  private removeOldest(count: number): void {
+    if (count <= 0) return;
+    for (let i = 0; i < count; i += 1) this.bytes -= this.sizes[i] ?? 0;
+    this.frames.splice(0, count);
+    this.sizes.splice(0, count);
+    if (this.frames.length === 0) this.bytes = 0;
+  }
+}

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 ?? {};
+}