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

package/src/handoff-chunking.ts

@@ -56,6 +56,39 @@ export interface IHandoffChunk {
  */
 export const DEFAULT_MAX_CHUNK_BYTES = 16 * 1024;
 
+// This module is exported from the package root, which also builds for the browser, so it uses the
+// web platform's bytes, text codecs and base64 (`btoa`/`atob`) rather than Node's `Buffer`.
+
+/** How many bytes go through `String.fromCharCode` at once, well under the argument-count limit. */
+const BINARY_STRING_STEP = 0x8000;
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let offset = 0; offset < bytes.length; offset += BINARY_STRING_STEP) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + BINARY_STRING_STEP));
+  }
+  return btoa(binary);
+}
+
+/** The bytes `data` encodes, or `undefined` when it is not base64 at all. */
+function fromBase64(data: string): Uint8Array | undefined {
+  let binary: string;
+  try {
+    binary = atob(data);
+  } catch {
+    return undefined;
+  }
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+  return true;
+}
+
 /**
  * Cut a sealed payload into chunks.
  *
@@ -75,14 +108,14 @@ export function chunkHandoffPayload(
         'as a hang rather than as the configuration error it is.',
     );
   }
-  const bytes = Buffer.from(serialized, 'utf8');
+  const bytes = new TextEncoder().encode(serialized);
   // An empty payload is still one chunk. Zero chunks would leave the receiver unable to tell a
   // completed empty transfer from one that never started.
   const total = Math.max(1, Math.ceil(bytes.byteLength / maxChunkBytes));
   const chunks: IHandoffChunk[] = [];
   for (let index = 0; index < total; index += 1) {
     const slice = bytes.subarray(index * maxChunkBytes, (index + 1) * maxChunkBytes);
-    chunks.push({ handoffId, index, total, data: slice.toString('base64') });
+    chunks.push({ handoffId, index, total, data: toBase64(slice) });
   }
   return chunks;
 }
@@ -127,7 +160,7 @@ export interface IChunkResult {
  * would make this a dispatcher as well as a buffer.
  */
 export class HandoffChunkAssembler {
-  private readonly chunks = new Map<number, Buffer>();
+  private readonly chunks = new Map<number, Uint8Array>();
   private declaredTotal: number | undefined;
 
   constructor(private readonly handoffId: string) {}
@@ -161,19 +194,19 @@ export class HandoffChunkAssembler {
       return refuse('out-of-range');
     }
 
-    const decoded = Buffer.from(chunk.data, 'base64');
-    // Buffer.from is lenient — it drops what it cannot parse rather than throwing, so a mangled
-    // chunk would silently become a shorter one and corrupt the payload in a way only the final
-    // digest would catch, after the whole transfer completed. Re-encoding is how the leniency is
-    // detected here instead.
-    if (decoded.toString('base64') !== chunk.data) return refuse('undecodable');
+    const decoded = fromBase64(chunk.data);
+    // Base64 decoding is lenient — it skips whitespace and accepts non-canonical padding — so a
+    // mangled chunk could silently become a different one and corrupt the payload in a way only the
+    // final digest would catch, after the whole transfer completed. Re-encoding is how the leniency
+    // is detected here instead.
+    if (decoded === undefined || toBase64(decoded) !== chunk.data) return refuse('undecodable');
 
     this.declaredTotal = chunk.total;
     const held = this.chunks.get(chunk.index);
     if (held !== undefined) {
       // A retry re-sending the same bytes is normal. Different bytes for the same index is the
       // inconsistent case again, and the same reasoning applies.
-      if (held.equals(decoded)) {
+      if (sameBytes(held, decoded)) {
         return { outcome: 'duplicate', received: this.chunks.size, expected: chunk.total };
       }
       return refuse('inconsistent-total');
@@ -206,7 +239,7 @@ export class HandoffChunkAssembler {
   }
 
   private reassemble(total: number): string {
-    const ordered: Buffer[] = [];
+    const ordered: Uint8Array[] = [];
     for (let i = 0; i < total; i += 1) {
       const part = this.chunks.get(i);
       if (part === undefined) {
@@ -217,7 +250,14 @@ export class HandoffChunkAssembler {
       }
       ordered.push(part);
     }
-    return Buffer.concat(ordered).toString('utf8');
+    const joined = new Uint8Array(ordered.reduce((size, part) => size + part.length, 0));
+    let offset = 0;
+    for (const part of ordered) {
+      joined.set(part, offset);
+      offset += part.length;
+    }
+    // Keep a leading byte-order mark: it is part of the payload, as it was with `Buffer`.
+    return new TextDecoder('utf-8', { ignoreBOM: true }).decode(joined);
   }
 }
 

package/src/index.ts

@@ -57,6 +57,7 @@ export { isObserverMessageType } from './observer-messages.js';
 export type { TProtocolSessionEventClassification } from './session-events.js';
 export type { IProtocolSession } from './protocol-session.js';
 export type {
+  IWireAgentDefinitionSummary,
   IWireHistoryEntry,
   TClientMessage,
   TServerMessage,
@@ -88,6 +89,9 @@ export type {
   TResumeSink,
   IAttachOptions,
 } from './session-resume-bridge.js';
+// #3282 §4a: the Settings screen's host-owned read/write seam (parallels `IUsageQueryReporters`).
+export { handleSettingsMessage, isSettingsMessage } from './settings-messages.js';
+export type { ISettingsReporter, TSettingsUpdateOutcome } from './settings-messages.js';
 
 // SEC-008 admission is NOT here: `src/node/admission.ts` mints and compares transport tokens with
 // `node:crypto`. A browser never mints one — it presents one it was handed — so the exclusion costs

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