@robota-sdk/agent-transport-acp 3.0.0-beta.96 → 3.0.1

package/src/acp-agent.ts

@@ -6,13 +6,21 @@ import { isAbsolute, resolve } from 'node:path';
 import { agent, PROTOCOL_VERSION, RequestError } from '@agentclientprotocol/sdk';
 import { OWNER_DRIVER_ID } from '@robota-sdk/agent-interface-session';
 
+import { editorFileAccess } from './acp-editor-files.js';
 import { promptText } from './acp-prompt-text.js';
+import { availableCommands, replayHistory } from './acp-session-catalog.js';
 import { runCommandTurn, runModelTurn } from './acp-turn.js';
 import { createUpdateStream } from './acp-updates.js';
 
 import type { IAcpTurnContext } from './acp-turn.js';
 import type { IAcpTransportOptions, IAcpTransportSession } from './acp-types.js';
-import type { AgentApp, PromptResponse } from '@agentclientprotocol/sdk';
+import type {
+  AgentApp,
+  AgentContext,
+  ClientCapabilities,
+  McpServer,
+  PromptResponse,
+} from '@agentclientprotocol/sdk';
 
 /**
  * JSON-RPC server-error code for a workspace the host has not admitted. Not -32000: ACP assigns
@@ -29,6 +37,15 @@ export interface IAcpAgent {
   readonly app: AgentApp;
   /** Cancel the running prompt, if there is one. */
   cancelActive(): void;
+  /** Tell the host the editor's file system is gone, if it was handed one. */
+  withdrawEditorFiles(): void;
+}
+
+/** What `session/new` and `session/load` both carry that decides whether the editor may have the session. */
+interface ISessionRequest {
+  readonly cwd: string;
+  readonly mcpServers: readonly McpServer[];
+  readonly additionalDirectories?: readonly string[] | null;
 }
 
 function sameDirectory(requested: string, served: string): boolean {
@@ -41,6 +58,10 @@ function sameDirectory(requested: string, served: string): boolean {
   }
 }
 
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
 export function createAcpAgent(
   session: IAcpTransportSession,
   options: IAcpTransportOptions,
@@ -48,63 +69,169 @@ export function createAcpAgent(
   const driverId = options.driverId ?? OWNER_DRIVER_ID;
   const report = (error: Error, context: string): void => options.onDeliveryError?.(error, context);
   let boundSessionId: string | undefined;
-  /** A `session/new` is waiting for the session to start; a second one must not also claim it. */
+  /** A `session/new` or `session/load` is still settling which session this connection serves. */
   let binding = false;
   let active: { cancel(): void } | undefined;
   let toolCalls = 0;
+  const usedToolCallIds = new Set<string>();
+  const nextToolCallId = (preferredId?: string): string => {
+    let id = preferredId;
+    while (id === undefined || usedToolCallIds.has(id)) id = `tool-${(toolCalls += 1)}`;
+    usedToolCallIds.add(id);
+    return id;
+  };
+  /** The command list the editor last received, so an unchanged list is not sent again. */
+  let advertised: string | undefined;
+
+  /** Refuse what the editor may not ask for; the same rules hold for a new and a loaded session. */
+  const admit = (params: ISessionRequest): void => {
+    if (!isAbsolute(params.cwd) || !sameDirectory(params.cwd, options.cwd)) {
+      throw RequestError.invalidParams(
+        undefined,
+        `cwd must be the directory this agent was started in: ${options.cwd}`,
+      );
+    }
+    // Servers or roots named by the editor would widen what the session can reach.
+    if (params.mcpServers.length > 0) {
+      throw RequestError.invalidParams(undefined, 'mcpServers are not accepted by this agent');
+    }
+    if ((params.additionalDirectories ?? []).length > 0) {
+      throw RequestError.invalidParams(
+        undefined,
+        'additionalDirectories are not accepted by this agent',
+      );
+    }
+    const admission = options.admitWorkspace();
+    if (!admission.admitted) {
+      throw new RequestError(WORKSPACE_NOT_ADMITTED, admission.message, {
+        reason: 'workspace-not-trusted',
+      });
+    }
+  };
+
+  /** Wait for the attached session to name itself; a session that failed to start is a fixed error. */
+  const sessionId = async (context: string): Promise<string> => {
+    try {
+      // A session that builds itself in the background cannot name itself until it is ready.
+      await session.whenInitialized?.();
+      return session.getStatusSnapshot().sessionId;
+    } catch (error) {
+      report(asError(error), context);
+      // The cause can name host paths or settings; the editor only needs to know it failed.
+      throw new RequestError(INTERNAL_ERROR, 'The session could not be started');
+    }
+  };
+
+  /**
+   * Tell the editor which commands it may offer, when they differ from what it last received. The
+   * update names the session, so it goes out only once the editor holds that id.
+   */
+  const advertiseCommands = (client: AgentContext, id: string): void => {
+    if (session.listCommands === undefined && session.listSkills === undefined) return;
+    let commands: ReturnType<typeof availableCommands>;
+    try {
+      commands = availableCommands(session);
+    } catch (error) {
+      report(asError(error), 'available_commands_update');
+      return;
+    }
+    const serialized = JSON.stringify(commands);
+    if (serialized === advertised) return;
+    advertised = serialized;
+    client
+      .notify('session/update', {
+        sessionId: id,
+        update: { sessionUpdate: 'available_commands_update', availableCommands: commands },
+      })
+      .catch((error: unknown) => report(asError(error), 'available_commands_update'));
+  };
+  /** After the response that gives the editor the session id has been written. */
+  const advertiseAfterReply = (client: AgentContext, id: string): void => {
+    setImmediate(() => advertiseCommands(client, id));
+  };
+
+  /** The file system the editor offered in `initialize`. */
+  let editorFs: ClientCapabilities['fs'];
+  let editorFilesOffered = false;
+  /** Hand the host the editor's file system for the bound session, if the editor offered one. */
+  const offerEditorFiles = (client: AgentContext): void => {
+    const access = editorFileAccess(editorFs, client, () => boundSessionId);
+    if (access === undefined) return;
+    editorFilesOffered = true;
+    options.onEditorFileAccess?.(access);
+  };
 
   const app = agent({ name: options.agentInfo.name })
-    .onRequest('initialize', () => ({
-      // Always the version this agent speaks: the client disconnects if it cannot use it.
-      protocolVersion: PROTOCOL_VERSION,
-      agentCapabilities: {
-        loadSession: false,
-        promptCapabilities: { image: false, audio: false, embeddedContext: true },
-      },
-      agentInfo: { name: options.agentInfo.name, version: options.agentInfo.version },
-    }))
-    .onRequest('session/new', async ({ params }) => {
+    .onRequest('initialize', ({ params }) => {
+      editorFs = params.clientCapabilities?.fs;
+      return {
+        // Always the version this agent speaks: the client disconnects if it cannot use it.
+        protocolVersion: PROTOCOL_VERSION,
+        agentCapabilities: {
+          loadSession:
+            options.loadSession !== undefined && session.getMessagesDisplay !== undefined,
+          promptCapabilities: { image: false, audio: false, embeddedContext: true },
+        },
+        agentInfo: { name: options.agentInfo.name, version: options.agentInfo.version },
+      };
+    })
+    .onRequest('session/new', async ({ params, client }) => {
       if (boundSessionId !== undefined || binding) {
         throw RequestError.invalidParams(undefined, 'one session per connection');
       }
-      if (!isAbsolute(params.cwd) || !sameDirectory(params.cwd, options.cwd)) {
-        throw RequestError.invalidParams(
-          undefined,
-          `cwd must be the directory this agent was started in: ${options.cwd}`,
-        );
-      }
-      // Servers or roots named by the editor would widen what the session can reach.
-      if (params.mcpServers.length > 0) {
-        throw RequestError.invalidParams(undefined, 'mcpServers are not accepted by this agent');
+      admit(params);
+      binding = true;
+      try {
+        boundSessionId = await sessionId('session/new');
+      } finally {
+        binding = false;
       }
-      if ((params.additionalDirectories ?? []).length > 0) {
-        throw RequestError.invalidParams(
-          undefined,
-          'additionalDirectories are not accepted by this agent',
-        );
+      offerEditorFiles(client);
+      advertiseAfterReply(client, boundSessionId);
+      return { sessionId: boundSessionId };
+    })
+    .onRequest('session/load', async ({ params, client }) => {
+      const load = options.loadSession;
+      if (load === undefined || session.getMessagesDisplay === undefined) {
+        throw RequestError.methodNotFound('session/load');
       }
-      const admission = options.admitWorkspace();
-      if (!admission.admitted) {
-        throw new RequestError(WORKSPACE_NOT_ADMITTED, admission.message, {
-          reason: 'workspace-not-trusted',
-        });
+      if (binding) throw RequestError.invalidParams(undefined, 'a session is already being opened');
+      // A load replaces this connection's session, so it may not pull the session out from under a turn.
+      if (active !== undefined) {
+        throw RequestError.invalidParams(undefined, 'a prompt is running');
       }
+      admit(params);
       binding = true;
       try {
-        // A session that builds itself in the background cannot name itself until it is ready.
-        await session.whenInitialized?.();
-        boundSessionId = session.getStatusSnapshot().sessionId;
-      } catch (error) {
-        report(error instanceof Error ? error : new Error(String(error)), 'session/new');
-        // The cause can name host paths or settings; the editor only needs to know it failed.
-        throw new RequestError(INTERNAL_ERROR, 'The session could not be started');
+        let outcome: Awaited<ReturnType<typeof load>>;
+        try {
+          outcome = await load(params.sessionId);
+        } catch (error) {
+          report(asError(error), 'session/load');
+          throw new RequestError(INTERNAL_ERROR, 'The session could not be loaded');
+        }
+        if (!outcome.loaded) throw RequestError.invalidParams(undefined, outcome.message);
+        boundSessionId = await sessionId('session/load');
+        offerEditorFiles(client);
+        // The editor sees the conversation it reopened before the load answers.
+        const updates = createUpdateStream(client, boundSessionId, report);
+        try {
+          replayHistory(session.getMessagesDisplay(), updates, nextToolCallId);
+        } catch (error) {
+          report(asError(error), 'session/load');
+          // The session is loaded; only its history could not be shown, and the cause stays local.
+          throw new RequestError(INTERNAL_ERROR, 'The session history could not be shown');
+        }
+        await updates.drained();
       } finally {
         binding = false;
       }
-      return { sessionId: boundSessionId };
+      advertised = undefined;
+      advertiseAfterReply(client, boundSessionId);
+      return {};
     })
     .onRequest('session/prompt', async ({ params, signal, client }): Promise<PromptResponse> => {
-      if (params.sessionId !== boundSessionId) {
+      if (params.sessionId !== boundSessionId || binding) {
         throw RequestError.invalidParams(undefined, 'unknown session');
       }
       if (active !== undefined) {
@@ -132,7 +259,7 @@ export function createAcpAgent(
         driverId,
         surface: options.surface ?? 'unknown',
         cwd: options.cwd,
-        nextToolCallId: () => `tool-${(toolCalls += 1)}`,
+        nextToolCallId,
         wasCancelled: () => cancelled,
         report,
       };
@@ -142,11 +269,22 @@ export function createAcpAgent(
           : await runModelTurn(turn, text.full);
       } finally {
         active = undefined;
+        // A command or a model turn can change the catalog (a plugin reload, a preset): the editor
+        // gets the new list, and an unchanged one is not sent again.
+        advertiseCommands(client, params.sessionId);
       }
     })
     .onNotification('session/cancel', ({ params }) => {
       if (params.sessionId === boundSessionId) active?.cancel();
     });
 
-  return { app, cancelActive: () => active?.cancel() };
+  return {
+    app,
+    cancelActive: () => active?.cancel(),
+    withdrawEditorFiles: () => {
+      if (!editorFilesOffered) return;
+      editorFilesOffered = false;
+      options.onEditorFileAccess?.(undefined);
+    },
+  };
 }

package/src/acp-editor-files.ts

@@ -0,0 +1,87 @@
+/**
+ * The editor's file system, as the editor offered it in `initialize`: reads and writes the host's
+ * file tools may inspect once the session is bound. ACP v1 carries only a pathname, not a stable
+ * rooted file capability, so this adapter deliberately cannot claim the authority required to
+ * carry contained Read, Write or Edit operations.
+ */
+
+import { isAbsolute } from 'node:path';
+
+import { RequestError } from '@agentclientprotocol/sdk';
+
+import type { IAcpEditorFileAccess } from './acp-types.js';
+import type { AgentContext, ClientCapabilities, SendRequestOptions } from '@agentclientprotocol/sdk';
+
+function cancellable(signal: AbortSignal | undefined): SendRequestOptions | undefined {
+  return signal === undefined ? undefined : { cancellationSignal: signal };
+}
+
+/** A JSON-RPC error names its kind in `message` and, from an SDK client, the cause in `data.details`. */
+function editorError(error: unknown): Error {
+  if (!(error instanceof RequestError)) return error instanceof Error ? error : new Error(String(error));
+  const data: unknown = error.data;
+  const details =
+    typeof data === 'object' && data !== null && 'details' in data && typeof data.details === 'string'
+      ? data.details
+      : undefined;
+  return new Error(details === undefined ? error.message : `${error.message}: ${details}`);
+}
+
+function absolute(path: string): void {
+  // ACP names files by absolute path; a relative one would be resolved by the editor, not the tool.
+  if (!isAbsolute(path)) throw new Error(`the editor is given absolute paths only: ${path}`);
+}
+
+/**
+ * The access the editor offered, for the bound session; `undefined` when it offered neither read nor
+ * write. `sessionId` is read at each request, so the access follows the session the connection serves.
+ */
+export function editorFileAccess(
+  fs: ClientCapabilities['fs'],
+  client: AgentContext,
+  sessionId: () => string | undefined,
+): IAcpEditorFileAccess | undefined {
+  const reads = fs?.readTextFile === true;
+  const writes = fs?.writeTextFile === true;
+  if (!reads && !writes) return undefined;
+  const bound = (): string => {
+    const id = sessionId();
+    if (id === undefined) throw new Error('the editor has no session to read or write for');
+    return id;
+  };
+  return {
+    ...(reads
+      ? {
+          readTextFile: async (path: string, signal?: AbortSignal): Promise<string> => {
+            absolute(path);
+            try {
+              const reply = await client.request(
+                'fs/read_text_file',
+                { sessionId: bound(), path },
+                cancellable(signal),
+              );
+              return reply.content;
+            } catch (error) {
+              throw editorError(error);
+            }
+          },
+        }
+      : {}),
+    ...(writes
+      ? {
+          writeTextFile: async (path: string, content: string, signal?: AbortSignal): Promise<void> => {
+            absolute(path);
+            try {
+              await client.request(
+                'fs/write_text_file',
+                { sessionId: bound(), path, content },
+                cancellable(signal),
+              );
+            } catch (error) {
+              throw editorError(error);
+            }
+          },
+        }
+      : {}),
+  };
+}

package/src/acp-session-catalog.ts

@@ -0,0 +1,65 @@
+/** What an editor learns about the session besides a turn: the commands it can offer, and the history of a loaded session. */
+
+import { acpToolEndStatus, acpToolKind, acpToolStartTitle } from './acp-tool-mapping.js';
+
+import type { IAcpUpdateStream } from './acp-updates.js';
+import type { AvailableCommand } from '@agentclientprotocol/sdk';
+import type { IHistoryDisplaySegment, ISessionCommands } from '@robota-sdk/agent-interface-session';
+
+/**
+ * The slash commands an editor may offer: the runtime's commands, then the user-invocable skills
+ * whose names no command already uses. A command a client implements itself (its runner is the
+ * client) is not offered, because an editor cannot run it and the runtime would not.
+ */
+export function availableCommands(
+  session: Partial<Pick<ISessionCommands, 'listCommands' | 'listSkills'>>,
+): AvailableCommand[] {
+  const offered: AvailableCommand[] = [];
+  const names = new Set<string>();
+  const offer = (name: string, description: string, hint: string | undefined): void => {
+    if (names.has(name)) return;
+    names.add(name);
+    offered.push({ name, description, ...(hint ? { input: { hint } } : {}) });
+  };
+  for (const command of session.listCommands?.() ?? []) {
+    if (command.runner !== 'runtime') continue;
+    offer(command.name, command.description, command.argumentHint);
+  }
+  for (const skill of session.listSkills?.() ?? []) {
+    if (skill.userInvocable) offer(skill.name, skill.description, skill.argumentHint);
+  }
+  return offered;
+}
+
+/**
+ * A loaded session's history as the editor would have seen it live: what the person typed, what the
+ * agent answered, and each finished tool call with how it ended. A call keeps its own id unless that
+ * id already named a row of this replay (a provider can reuse ids across turns), because the editor
+ * would merge the two rows into one. The connection's allocator also keeps later live calls distinct.
+ */
+export function replayHistory(
+  segments: readonly IHistoryDisplaySegment[],
+  updates: IAcpUpdateStream,
+  nextToolCallId: (preferredId?: string) => string,
+): void {
+  for (const segment of segments) {
+    if (segment.type === 'text') {
+      if (segment.content === '') continue;
+      updates.send({
+        sessionUpdate: segment.role === 'user' ? 'user_message_chunk' : 'agent_message_chunk',
+        content: { type: 'text', text: segment.content },
+      });
+      continue;
+    }
+    const { tool } = segment;
+    if (tool.internal) continue;
+    const toolCallId = nextToolCallId(tool.executionId);
+    updates.send({
+      sessionUpdate: 'tool_call',
+      toolCallId,
+      title: acpToolStartTitle(tool),
+      kind: acpToolKind(tool.toolName),
+      status: acpToolEndStatus(tool),
+    });
+  }
+}

package/src/acp-tool-calls.ts

@@ -20,8 +20,8 @@ export interface IAcpToolCallTracker {
 
 export interface IAcpToolCallDeps {
   readonly updates: IAcpUpdateStream;
-  /** Ids for tool calls the session gives no id; unique for the life of the session. */
-  readonly nextToolCallId: () => string;
+  /** Allocate a new row id, preserving a preferred execution id only when no earlier row used it. */
+  readonly nextToolCallId: (preferredId?: string) => string;
   /** The served directory, for paths the session reports relative to it. */
   readonly cwd: string;
 }
@@ -34,6 +34,7 @@ interface IOpenCall {
 
 /** A permission request's row, held until the call it names starts or is refused. */
 interface IAwaitedCall {
+  readonly id: string;
   readonly rawInput: unknown;
   /** A background agent's call can run after this prompt, so its row closes with the answer. */
   readonly background: boolean;
@@ -71,7 +72,7 @@ export function createToolCallTracker(deps: IAcpToolCallDeps): IAcpToolCallTrack
       // An internal signal tool is not a call the person made or should see.
       if (tool.internal) return;
       const asked = take(tool.executionId);
-      const id = tool.executionId ?? deps.nextToolCallId();
+      const id = asked?.id ?? deps.nextToolCallId(tool.executionId);
       open.push({ id, toolName: tool.toolName, executionId: tool.executionId });
       const call = {
         toolCallId: id,
@@ -99,14 +100,15 @@ export function createToolCallTracker(deps: IAcpToolCallDeps): IAcpToolCallTrack
         return;
       }
       // A refused call ends with no start; when its permission was asked, that row is the call.
-      if (take(tool.executionId) !== undefined) {
-        updates.send({ sessionUpdate: 'tool_call_update', toolCallId: tool.executionId!, status });
+      const asked = take(tool.executionId);
+      if (asked !== undefined) {
+        updates.send({ sessionUpdate: 'tool_call_update', toolCallId: asked.id, status });
         return;
       }
       // Otherwise give the editor the call, finished, rather than an update for nothing.
       updates.send({
         sessionUpdate: 'tool_call',
-        toolCallId: tool.executionId ?? deps.nextToolCallId(),
+        toolCallId: deps.nextToolCallId(tool.executionId),
         title: acpToolStartTitle(tool),
         kind: acpToolKind(tool.toolName),
         status,
@@ -116,14 +118,22 @@ export function createToolCallTracker(deps: IAcpToolCallDeps): IAcpToolCallTrack
     requested(event) {
       const { executionId } = event;
       if (executionId === undefined) {
-        const call = permissionToolCall(event, `permission-${event.id}`, deps.cwd);
+        const call = permissionToolCall(
+          event,
+          deps.nextToolCallId(`permission-${event.id}`),
+          deps.cwd,
+        );
         unnamed.set(event.id, call.toolCallId);
         return call;
       }
-      const call = permissionToolCall(event, executionId, deps.cwd);
-      // A call that is already running (asked again before its effect) keeps the row it has.
-      if (!open.some((running) => running.executionId === executionId)) {
+      // A repeated request and the call's own start/end keep the row allocated for this call.
+      const running = open.find((call) => call.executionId === executionId);
+      const waiting = awaited.get(executionId);
+      const id = running?.id ?? waiting?.id ?? deps.nextToolCallId(executionId);
+      const call = permissionToolCall(event, id, deps.cwd);
+      if (running === undefined && waiting === undefined) {
         awaited.set(executionId, {
+          id,
           rawInput: call.rawInput,
           background: event.requester !== undefined,
         });
@@ -147,7 +157,7 @@ export function createToolCallTracker(deps: IAcpToolCallDeps): IAcpToolCallTrack
 
     finish() {
       finished = true;
-      for (const [id, call] of awaited) close(id, call.background && call.allowed === true);
+      for (const call of awaited.values()) close(call.id, call.background && call.allowed === true);
       for (const row of unnamed.values()) close(row, false);
       awaited.clear();
       unnamed.clear();

package/src/acp-transport.ts

@@ -40,6 +40,7 @@ export function createAcpTransport(options: IAcpTransportOptions): IAcpTransport
   let carrier: IStdioCarrier | null = null;
   let connection: AgentConnection | null = null;
   let cancelActive: (() => void) | null = null;
+  let withdrawEditorFiles: (() => void) | null = null;
   let resolveClose: (() => void) | null = null;
   let rejectClose: ((error: Error) => void) | null = null;
   let closePromise: Promise<void> = Promise.resolve();
@@ -53,6 +54,8 @@ export function createAcpTransport(options: IAcpTransportOptions): IAcpTransport
   };
   const release = (): void => {
     try {
+      // The host's tools go back to the disk before the connection that carried their access closes.
+      withdrawEditorFiles?.();
       cancelActive?.();
       connection?.close();
     } finally {
@@ -60,6 +63,7 @@ export function createAcpTransport(options: IAcpTransportOptions): IAcpTransport
       carrier = null;
       connection = null;
       cancelActive = null;
+      withdrawEditorFiles = null;
     }
   };
   const lifecycleError = (code: ITransportLifecycleError['code']): ITransportLifecycleError =>
@@ -84,6 +88,7 @@ export function createAcpTransport(options: IAcpTransportOptions): IAcpTransport
       try {
         const acpAgent = createAcpAgent(session, options);
         cancelActive = acpAgent.cancelActive;
+        withdrawEditorFiles = acpAgent.withdrawEditorFiles;
         // The SDK destroys what it reads when its connection closes; it reads the bridge, never the
         // process input, and a closed or failed end ends the transport instead of leaving it idle.
         const attached = attachStdioCarrier(options.input, options.output, {

package/src/acp-turn.ts

@@ -31,8 +31,8 @@ export interface IAcpTurnContext {
   readonly surface: ISubmitOptions['surface'];
   /** The served directory; paths the session reports relative to it are made absolute for the editor. */
   readonly cwd: string;
-  /** Ids for tool calls the session gives no id; unique for the life of the session. */
-  readonly nextToolCallId: () => string;
+  /** Allocate a new row id, preserving a preferred execution id only when no earlier row used it. */
+  readonly nextToolCallId: (preferredId?: string) => string;
   /** Whether the editor sent `session/cancel` for this prompt. */
   readonly wasCancelled: () => boolean;
   readonly report: (error: Error, context: string) => void;

package/src/acp-types.ts

@@ -1,6 +1,8 @@
 /** Public contract of the ACP agent transport: its session role set, host-injected ports and options. */
 
 import type {
+  ISessionCommands,
+  ISessionConversationRead,
   ISessionEvents,
   ISessionPromptResolution,
   ISessionStatusRead,
@@ -14,7 +16,8 @@ import type { Readable, Writable } from 'node:stream';
 
 /**
  * The session roles ACP uses: submit and abort a turn, stream its events, answer its permission
- * prompts, and name the session. A full interactive session is assignable; nothing else is required.
+ * prompts, and name the session. Optional catalog reads let the editor offer commands; optional
+ * history reads enable a host load port to replay a stored session. A full interactive session is assignable.
  */
 export interface IAcpTransportSession
   extends
@@ -22,28 +25,44 @@ export interface IAcpTransportSession
     ISessionTurnControl,
     ISessionEvents,
     ISessionPromptResolution,
-    ISessionStatusRead {
+    ISessionStatusRead,
+    Partial<Pick<ISessionCommands, 'listCommands' | 'listSkills'>>,
+    Partial<Pick<ISessionConversationRead, 'getMessagesDisplay'>> {
   /**
    * Resolves once the session can name itself, and rejects if it failed to start. A session that
    * builds itself in the background (`InteractiveSession`) has no id before then, so `session/new`
-   * waits on this. A session that is ready at construction can omit it.
+   * and `session/load` wait on this. A session that is ready at construction can omit it.
    */
   whenInitialized?(): Promise<void>;
 }
 
+/**
+ * The editor's pathname file system, as the editor offered it (`clientCapabilities.fs`): a method
+ * it did not offer is absent. Paths are absolute. ACP v1 does not bind the path to stable rooted
+ * authority, so contained host file tools must not treat this as `IEditorFileAccess.pathAuthority`.
+ */
+export interface IAcpEditorFileAccess {
+  readTextFile?(path: string, signal?: AbortSignal): Promise<string>;
+  writeTextFile?(path: string, content: string, signal?: AbortSignal): Promise<void>;
+}
+
 /** The host's answer to whether the workspace may serve an editor; a refusal carries what to tell the user. */
 export type TAcpWorkspaceAdmission =
   { readonly admitted: true } | { readonly admitted: false; readonly message: string };
 
+/** The host's answer to a `session/load`; a refusal carries what to tell the editor. */
+export type TAcpSessionLoad =
+  { readonly loaded: true } | { readonly loaded: false; readonly message: string };
+
 export interface IAcpTransportOptions {
   /** Process-owned byte streams carrying newline-delimited JSON-RPC: the editor writes `input`, reads `output`. */
   readonly input: Readable;
   readonly output: Writable;
   /** Sent to the editor in the `initialize` reply. */
   readonly agentInfo: { readonly name: string; readonly version: string };
-  /** The directory the attached session is rooted at; `session/new` must name this directory. */
+  /** The directory the attached session is rooted at; `session/new` and `session/load` must name it. */
   readonly cwd: string;
-  /** The host's trust check, asked when the editor creates the session. */
+  /** The host's trust check, asked when the editor creates or loads the session. */
   readonly admitWorkspace: () => TAcpWorkspaceAdmission;
   /**
    * Runs a `/command` prompt and returns the text to show. Supplied by the host because command
@@ -52,6 +71,21 @@ export interface IAcpTransportOptions {
    * cancels the prompt or the connection closes; pass it on so what the command starts stops with it.
    */
   readonly executeCommand?: (text: string, signal: AbortSignal) => Promise<string>;
+  /**
+   * Makes the stored session `sessionId` current, so that the object this transport was attached to
+   * answers for it from then on (the host attaches a forwarder, such as a session slot, whose current
+   * session the port replaces). It must admit only a session rooted in the served directory, and may
+   * refuse with a message for the editor. Supplied by the host because building a session from
+   * storage is not this package's; without it or the session's history read, `session/load` is not offered.
+   */
+  readonly loadSession?: (sessionId: string) => Promise<TAcpSessionLoad>;
+  /**
+   * Receives the editor's file system after a new or loaded session binds, when the editor offers reads or
+   * writes, and `undefined` when the transport stops. The host decides which of its tools use it;
+   * they must apply their own path and permission checks first, because the editor checks nothing
+   * for the agent. Never called for an editor that offers no file system.
+   */
+  readonly onEditorFileAccess?: (access: IAcpEditorFileAccess | undefined) => void;
   /** Attribution recorded on turns and prompt answers submitted through this transport. Default `'owner'`. */
   readonly driverId?: TDriverId;
   /** Usage surface recorded on turns. Default `'unknown'` (no editor value exists). */