@automatalabs/acp-agents 0.13.0 → 0.15.0

package/dist/acp-client.d.ts

@@ -1,10 +1,10 @@
-import { type ContentBlock, type AgentNotificationMethod, type AgentNotificationParamsByMethod, type AgentRequestMethod, type AgentRequestParamsByMethod, type AgentRequestResponsesByMethod, type PromptRequest, type PromptResponse, type RequestPermissionResponse, type SendRequestOptions, type SessionConfigOption, type SessionModeState, type SessionNotification, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
+import { type CreateElicitationResponse, type ContentBlock, type AgentNotificationMethod, type AgentNotificationParamsByMethod, type AgentRequestMethod, type AgentRequestParamsByMethod, type AgentRequestResponsesByMethod, type DeleteSessionRequest, type ListSessionsRequest, type ListSessionsResponse, type PromptRequest, type PromptResponse, type RequestPermissionResponse, type SendRequestOptions, type SessionConfigOption, type SessionModeState, type SessionNotification, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
 import type { TSchema } from "typebox";
 import { type AgentHistoryEntry, type McpServerConfig } from "@automatalabs/shared-types";
 import type { Backend, BackendId, StructuredSource } from "./backend.js";
 import { type NegotiatedCapabilities } from "./capabilities.js";
 import { type AcpEventSink } from "./events.js";
-import { type PermissionResolver, type ToolPolicy } from "./permissions.js";
+import { type ElicitationResolver, type PermissionResolver, type ToolPolicy } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
 import { type ClientHandlers } from "./client-handlers.js";
 interface RawResultSuccess {
@@ -18,6 +18,7 @@ declare class SessionState {
     readonly cwd: string;
     readonly policy: ToolPolicy;
     readonly permissionResolver?: PermissionResolver | undefined;
+    readonly elicitationResolver?: ElicitationResolver | undefined;
     readonly label?: string | undefined;
     readonly runId?: string | undefined;
     private readonly retainSessionLog;
@@ -25,12 +26,14 @@ declare class SessionState {
     readonly history: AgentHistoryEntry[];
     readonly usage: UsageAccumulator;
     readonly pendingPermissions: Set<(outcome: RequestPermissionResponse) => void>;
+    readonly pendingElicitations: Set<(outcome: CreateElicitationResponse) => void>;
+    readonly urlElicitationIds: Set<string>;
     rawResultSuccess: RawResultSuccess | undefined;
     modes: SessionModeState | null | undefined;
     private turnStartIndex;
     /** `label`/`runId` are carried here ONLY so the MultiplexClient can stamp them onto emitted
      *  events as context — they never affect routing or the wire request. */
-    constructor(cwd: string, policy: ToolPolicy, permissionResolver?: PermissionResolver | undefined, label?: string | undefined, runId?: string | undefined, modes?: SessionModeState | null, retainSessionLog?: boolean);
+    constructor(cwd: string, policy: ToolPolicy, permissionResolver?: PermissionResolver | undefined, elicitationResolver?: ElicitationResolver | undefined, label?: string | undefined, runId?: string | undefined, modes?: SessionModeState | null, retainSessionLog?: boolean);
     /** Mark the start of a new turn so currentTurnText()/structured_output read only this turn.
      *  Long-lived interactive sessions can opt out of retaining old text/history because hosts
      *  stream live events and keep their own transcript; clearing here prevents dead logs from
@@ -42,6 +45,9 @@ declare class SessionState {
     /** Settle every deferred permission still parked on this session. Used by release/cancel/death
      *  teardown so an interactive resolver can never strand an ACP prompt turn. */
     settlePendingPermissions(): void;
+    /** Same teardown guarantee for elicitation/create: a parked human prompt must not survive
+     *  release/cancel/death after its ACP session is gone. */
+    settlePendingElicitations(): void;
 }
 export interface AcpSessionOptions {
     /** Absolute working directory for the ACP session (worktree isolation). */
@@ -52,6 +58,9 @@ export interface AcpSessionOptions {
     /** Session-scoped permission resolver. When present it wins over the runner default and
      *  replaces the synchronous ToolPolicy auto-response path for this session. */
     permissionResolver?: PermissionResolver;
+    /** Session-scoped elicitation resolver. When present it wins over the runner default for this
+     *  session; initialize-time advertisement still depends on the runner-wide resolver. */
+    elicitationResolver?: ElicitationResolver;
     signal?: AbortSignal;
     /** Client-provided MCP servers to attach at session/new. Omitted => `[]` (the default). */
     mcpServers?: McpServerConfig[];
@@ -83,6 +92,11 @@ export interface PooledConnectionDeps {
     onEvent?: AcpEventSink;
     /** Runner-wide permission resolver default. SessionState.permissionResolver overrides it. */
     permissionResolver?: PermissionResolver;
+    /** Runner-wide elicitation resolver default. SessionState.elicitationResolver overrides it. */
+    elicitationResolver?: ElicitationResolver;
+    /** Initialize-time elicitation advertisement; fixed per connection, so it is driven by the
+     *  runner-wide resolver rather than session-scoped responders attached later. */
+    advertiseElicitation?: boolean;
     /** Client-side ACP fs/terminal handlers advertised once and routed by sessionId. */
     clientHandlers?: ClientHandlers;
 }
@@ -102,6 +116,7 @@ export declare class PooledConnection {
     private readonly onDead;
     private readonly onEvent;
     private readonly clientHandlers;
+    private readonly advertiseElicitation;
     /** Set true at the start of dispose() so the graceful-shutdown death is NOT reported as a crash. */
     private disposing;
     /** Resolves once `initialize` completed (or rejects if the process died first). */
@@ -127,6 +142,9 @@ export declare class PooledConnection {
     /** Drop the backend-declared bare `_meta` keys the connected agent did not advertise support
      *  for (see gateCustomMeta). Applied to BOTH session/new and session/prompt `_meta`. */
     gateCustomMeta(meta: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+    private assertSupportedMcpServers;
+    private sessionRequestMeta;
+    private assertLifecycleSupported;
     /** Mark this connection dead exactly once, then ask the pool to evict it. Idempotent. */
     private die;
     private stderrSuffix;
@@ -140,6 +158,16 @@ export declare class PooledConnection {
      * synchronously (before the first await) so the pool's load accounting is race-free.
      */
     openSession(opts: AcpSessionOptions): Promise<SessionHandle>;
+    /** Reopen an existing session and replay its transcript through the router before resolving. */
+    loadSession(sessionId: string, opts: AcpSessionOptions): Promise<SessionHandle>;
+    /** Reopen an existing session without transcript replay. */
+    resumeSession(sessionId: string, opts: AcpSessionOptions): Promise<SessionHandle>;
+    private rawAgentRequest;
+    private reattachSession;
+    /** session/list on a dedicated connection, gated on the initialize advertisement. */
+    listSessions(request: ListSessionsRequest, label?: string): Promise<ListSessionsResponse>;
+    /** session/delete on a dedicated connection, gated on the initialize advertisement. */
+    deleteSession(request: DeleteSessionRequest, label?: string): Promise<void>;
     /** session/prompt on this connection, raced against process death. */
     prompt(request: PromptRequest): Promise<PromptResponse>;
     /** session/set_config_option on this connection, raced against process death. */
@@ -187,6 +215,8 @@ export declare class SessionHandle implements StructuredSource {
     get usage(): UsageAccumulator;
     /** Diagnostic message/tool history accumulated across this session's run. */
     get history(): AgentHistoryEntry[];
+    /** Assistant text accumulated across the retained session log. */
+    get text(): string;
     /** Agent-advertised session mode catalog plus the currently active mode, if supported. */
     get modes(): SessionModeState | null | undefined;
     /**

package/dist/acp-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../src/acp-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../src/acp-client.ts"],"names":[],"mappings":"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"}

package/dist/acp-client.js

@@ -24,9 +24,9 @@ import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { AGENT_METHODS, client, CLIENT_METHODS, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
 import { META_KEYS, WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
-import { adaptPromptContent, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
+import { adaptPromptContent, describeLifecycleAdvertisement, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
 import { emitSessionUpdate } from "./events.js";
-import { decidePermission } from "./permissions.js";
+import { decidePermission, } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
 import { clientCapabilitiesFor, } from "./client-handlers.js";
 /** A benign client identity. NOT JetBrains/IntelliJ 2026.1 — that exact identity makes
@@ -42,12 +42,22 @@ const CLOSE_SESSION_TIMEOUT_MS = 5_000;
 /** Bound the graceful SIGTERM shutdown before escalating to SIGKILL. */
 const DISPOSE_SIGKILL_GRACE_MS = 2_000;
 const TOMBSTONE_SESSION_CAP = 64;
+const GUARDED_STATEFUL_REQUESTS = new Map([
+    [AGENT_METHODS.session_new, "use openSession()"],
+    [AGENT_METHODS.session_load, "use loadSession()"],
+    [AGENT_METHODS.session_resume, "use resumeSession()"],
+    [
+        AGENT_METHODS.session_fork,
+        "no driven wrapper yet; raw forked sessions cannot be routed (permissions auto-cancel)",
+    ],
+]);
 /** Per-session accumulator: assistant text, tool history, usage, the Claude raw structured_output,
  *  and the permission policy/resolver used to answer permission requests for THIS session. */
 class SessionState {
     cwd;
     policy;
     permissionResolver;
+    elicitationResolver;
     label;
     runId;
     retainSessionLog;
@@ -55,15 +65,18 @@ class SessionState {
     history = [];
     usage = new UsageAccumulator();
     pendingPermissions = new Set();
+    pendingElicitations = new Set();
+    urlElicitationIds = new Set();
     rawResultSuccess;
     modes;
     turnStartIndex = 0;
     /** `label`/`runId` are carried here ONLY so the MultiplexClient can stamp them onto emitted
      *  events as context — they never affect routing or the wire request. */
-    constructor(cwd, policy, permissionResolver, label, runId, modes, retainSessionLog = true) {
+    constructor(cwd, policy, permissionResolver, elicitationResolver, label, runId, modes, retainSessionLog = true) {
         this.cwd = cwd;
         this.policy = policy;
         this.permissionResolver = permissionResolver;
+        this.elicitationResolver = elicitationResolver;
         this.label = label;
         this.runId = runId;
         this.retainSessionLog = retainSessionLog;
@@ -140,6 +153,12 @@ class SessionState {
         for (const settle of [...this.pendingPermissions])
             settle(cancelledPermissionResponse());
     }
+    /** Same teardown guarantee for elicitation/create: a parked human prompt must not survive
+     *  release/cancel/death after its ACP session is gone. */
+    settlePendingElicitations() {
+        for (const settle of [...this.pendingElicitations])
+            settle(cancelledElicitationResponse());
+    }
 }
 /** The single client-side handler set for one pooled connection (registered on the SDK's fluent
  *  client() app). It ROUTES every notification and permission request to the per-session
@@ -150,7 +169,9 @@ class MultiplexClient {
     onEvent;
     handlers;
     permissionResolver;
+    elicitationResolver;
     sessions = new Map();
+    urlElicitationContexts = new Map();
     /** Recently unregistered sessions kept ONLY for the teardown window: ACP agents may
      *  legitimately release terminals (or finish fs/terminal cleanup) after this client releases
      *  the session because session/close is cancel + free resources and the Agent owns terminal
@@ -159,11 +180,12 @@ class MultiplexClient {
     /** `backendId` stamps event context; `onEvent` (optional) bubbles every notification, permission
      *  request and session lifecycle change up to the runner's typed bus. `permissionResolver` is
      *  the runner-wide default; a SessionState resolver wins when present. */
-    constructor(backendId, onEvent, handlers, permissionResolver) {
+    constructor(backendId, onEvent, handlers, permissionResolver, elicitationResolver) {
         this.backendId = backendId;
         this.onEvent = onEvent;
         this.handlers = handlers;
         this.permissionResolver = permissionResolver;
+        this.elicitationResolver = elicitationResolver;
     }
     contextFor(sessionId, state) {
         return { sessionId, backendId: this.backendId, label: state?.label, runId: state?.runId };
@@ -191,8 +213,11 @@ class MultiplexClient {
     unregister(sessionId) {
         const state = this.sessions.get(sessionId);
         state?.settlePendingPermissions();
+        state?.settlePendingElicitations();
         this.sessions.delete(sessionId);
         if (state) {
+            for (const elicitationId of state.urlElicitationIds)
+                this.urlElicitationContexts.delete(elicitationId);
             this.tombstones.set(sessionId, {
                 cwd: state.cwd,
                 label: state.label,
@@ -210,11 +235,19 @@ class MultiplexClient {
     settlePendingPermissions(sessionId) {
         this.sessions.get(sessionId)?.settlePendingPermissions();
     }
+    settlePendingElicitations(sessionId) {
+        this.sessions.get(sessionId)?.settlePendingElicitations();
+    }
     settleAllPendingPermissions() {
         for (const state of this.sessions.values()) {
             state.settlePendingPermissions();
         }
     }
+    settleAllPendingElicitations() {
+        for (const state of this.sessions.values()) {
+            state.settlePendingElicitations();
+        }
+    }
     requestPermission(params) {
         const state = this.sessions.get(params.sessionId);
         // Unknown/closed session: refuse rather than silently allow a tool we can't attribute.
@@ -262,6 +295,63 @@ class MultiplexClient {
         response.catch(() => { });
         return response;
     }
+    requestElicitation(params) {
+        const sessionId = sessionIdFromElicitationRequest(params);
+        if (!sessionId)
+            return declinedElicitationResponse();
+        const state = this.sessions.get(sessionId);
+        const ctx = this.contextFor(sessionId, state);
+        // Unknown/closed session: decline rather than asking a human for a prompt we cannot route.
+        if (!state) {
+            const outcome = declinedElicitationResponse();
+            this.onEvent?.("elicitation_request", { ...ctx, request: params, outcome });
+            return outcome;
+        }
+        this.trackUrlElicitation(params, state, ctx);
+        const resolver = state.elicitationResolver ?? this.elicitationResolver;
+        if (resolver)
+            return this.requestElicitationViaResolver(params, state, ctx, resolver);
+        const outcome = declinedElicitationResponse();
+        this.onEvent?.("elicitation_request", { ...ctx, request: params, outcome });
+        return outcome;
+    }
+    requestElicitationViaResolver(params, state, ctx, resolver) {
+        let settled = false;
+        let settle;
+        const response = new Promise((resolve) => {
+            settle = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                state.pendingElicitations.delete(settle);
+                this.onEvent?.("elicitation_request", { ...ctx, request: params, outcome });
+                resolve(outcome);
+            };
+            state.pendingElicitations.add(settle);
+            this.onEvent?.("elicitation_pending", { ...ctx, request: params });
+            try {
+                Promise.resolve(resolver(params, ctx)).then((outcome) => {
+                    settle(outcome);
+                }, () => {
+                    // Resolver failure is observable as the FINAL cancel outcome; no extra error event is
+                    // needed, and the prompt turn continues instead of hanging behind a rejected promise.
+                    settle(cancelledElicitationResponse());
+                });
+            }
+            catch {
+                settle(cancelledElicitationResponse());
+            }
+        });
+        response.catch(() => { });
+        return response;
+    }
+    trackUrlElicitation(params, state, ctx) {
+        const elicitationId = urlElicitationId(params);
+        if (!elicitationId)
+            return;
+        state.urlElicitationIds.add(elicitationId);
+        this.urlElicitationContexts.set(elicitationId, ctx);
+    }
     readTextFile(params) {
         return this.dispatch(params, CLIENT_METHODS.fs_read_text_file, this.handlers?.fs?.readTextFile);
     }
@@ -308,6 +398,14 @@ class MultiplexClient {
             message: rawMessage,
         });
     }
+    elicitationComplete(params) {
+        const ctx = this.urlElicitationContexts.get(params.elicitationId);
+        if (!ctx)
+            return;
+        this.urlElicitationContexts.delete(params.elicitationId);
+        this.sessions.get(ctx.sessionId)?.urlElicitationIds.delete(params.elicitationId);
+        this.onEvent?.("elicitation_complete", { ...ctx, notification: params });
+    }
 }
 function unknownSession(sessionId) {
     return RequestError.invalidParams({ sessionId }, `unknown session: ${sessionId}`);
@@ -315,9 +413,31 @@ function unknownSession(sessionId) {
 function cancelledPermissionResponse() {
     return { outcome: { outcome: "cancelled" } };
 }
+function declinedElicitationResponse() {
+    return { action: "decline" };
+}
+function cancelledElicitationResponse() {
+    return { action: "cancel" };
+}
+function sessionIdFromElicitationRequest(params) {
+    return "sessionId" in params && typeof params.sessionId === "string" ? params.sessionId : undefined;
+}
+function urlElicitationId(params) {
+    return params.mode === "url" && "elicitationId" in params && typeof params.elicitationId === "string"
+        ? params.elicitationId
+        : undefined;
+}
 function methodNotAdvertised(method) {
     return new RequestError(-32601, `${method} was not advertised by this client`, { method });
 }
+function assertSafeRawRequest(method) {
+    const guidance = GUARDED_STATEFUL_REQUESTS.get(method);
+    if (!guidance)
+        return;
+    throw new Error(`Raw ACP request "${method}" is guarded: ${guidance}. Sessions created, reopened, or forked ` +
+        "outside the router are unregistered: session/update notifications do not fold into an " +
+        "accumulator, permission requests auto-cancel, and fs/terminal dispatch fails for unknown sessions.");
+}
 function modeIds(modes) {
     return modes?.availableModes.map((mode) => mode.id) ?? [];
 }
@@ -326,6 +446,12 @@ function modeSelectionError(backendId, requested, advertisedIds, label, cause) {
     const suffix = cause ? `: ${thrownMessage(cause)}` : "";
     return new WorkflowError(`ACP agent (${backendId}) cannot apply session mode "${requested}" (advertised modes: ${advertised})${suffix}`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label, details: cause });
 }
+function lifecycleCapabilityError(backendId, method, capabilities, label) {
+    const advertised = capabilities
+        ? describeLifecycleAdvertisement(capabilities.agent)
+        : "initialize did not complete";
+    return new WorkflowError(`ACP agent (${backendId}) does not advertise ${method}; advertised lifecycle capabilities: ${advertised}`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+}
 function thrownMessage(error) {
     if (error instanceof Error)
         return error.message;
@@ -388,6 +514,7 @@ export class PooledConnection {
     onDead;
     onEvent;
     clientHandlers;
+    advertiseElicitation;
     /** Set true at the start of dispose() so the graceful-shutdown death is NOT reported as a crash. */
     disposing = false;
     /** Resolves once `initialize` completed (or rejects if the process died first). */
@@ -407,7 +534,8 @@ export class PooledConnection {
         this.onDead = deps.onDead;
         this.onEvent = deps.onEvent;
         this.clientHandlers = deps.clientHandlers;
-        this.client = new MultiplexClient(this.backendId, this.onEvent, deps.clientHandlers, deps.permissionResolver);
+        this.advertiseElicitation = deps.advertiseElicitation ?? Boolean(deps.elicitationResolver);
+        this.client = new MultiplexClient(this.backendId, this.onEvent, deps.clientHandlers, deps.permissionResolver, deps.elicitationResolver);
         const { command, args, env } = backend.spawnConfig();
         // NOTE: deliberately NO `cwd` here. cwd is per-SESSION (session/new), so one pooled process
         // serves runs in different worktrees without losing isolation.
@@ -445,7 +573,9 @@ export class PooledConnection {
         this.connection = client({ name: CLIENT_INFO.name })
             .onNotification(CLIENT_METHODS.session_update, ({ params }) => this.client.sessionUpdate(params))
             .onNotification(CLAUDE_RAW_MESSAGE_METHOD, (params) => (params ?? {}), ({ params }) => this.client.extNotification(CLAUDE_RAW_MESSAGE_METHOD, params))
+            .onNotification(CLIENT_METHODS.elicitation_complete, ({ params }) => this.client.elicitationComplete(params))
             .onRequest(CLIENT_METHODS.session_request_permission, ({ params }) => this.client.requestPermission(params))
+            .onRequest(CLIENT_METHODS.elicitation_create, ({ params }) => this.client.requestElicitation(params))
             .onRequest(CLIENT_METHODS.fs_read_text_file, ({ params }) => this.client.readTextFile(params))
             .onRequest(CLIENT_METHODS.fs_write_text_file, ({ params }) => this.client.writeTextFile(params))
             .onRequest(CLIENT_METHODS.terminal_create, ({ params }) => this.client.createTerminal(params))
@@ -490,6 +620,35 @@ export class PooledConnection {
     gateCustomMeta(meta) {
         return gateCustomMeta(meta, this.negotiated?.customMetaSupport, this.negotiated?.gatedKeys);
     }
+    assertSupportedMcpServers(opts) {
+        const unsupported = this.negotiated
+            ? unsupportedMcpServer(opts.mcpServers, this.negotiated.agent)
+            : undefined;
+        if (!unsupported)
+            return;
+        throw new WorkflowError(`MCP server "${unsupported.name}" uses the "${unsupported.transport}" transport, which the ` +
+            `${this.backendId} agent does not support`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: opts.label });
+    }
+    sessionRequestMeta(opts) {
+        return this.gateCustomMeta(stampRunId(layerMeta(this.backend.sessionMetaDefaults?.(), opts.meta, this.backend.sessionMeta(opts.schema, {
+            baseInstructions: opts.baseInstructions,
+            developerInstructions: opts.developerInstructions,
+        })), opts.runId));
+    }
+    assertLifecycleSupported(method, label) {
+        const supported = method === AGENT_METHODS.session_load
+            ? this.negotiated?.supportsLoadSession
+            : method === AGENT_METHODS.session_list
+                ? this.negotiated?.supportsListSessions
+                : method === AGENT_METHODS.session_delete
+                    ? this.negotiated?.supportsDeleteSession
+                    : method === AGENT_METHODS.session_resume
+                        ? this.negotiated?.supportsResumeSession
+                        : false;
+        if (supported)
+            return;
+        throw lifecycleCapabilityError(this.backendId, method, this.negotiated, label);
+    }
     /** Mark this connection dead exactly once, then ask the pool to evict it. Idempotent. */
     die(error) {
         if (!this._alive)
@@ -498,6 +657,7 @@ export class PooledConnection {
         this.deathError = error;
         this.resolveDead();
         this.client.settleAllPendingPermissions();
+        this.client.settleAllPendingElicitations();
         // A crash (not a graceful dispose) is worth surfacing for observability; the engine still
         // handles it by retrying the run on a fresh process. Best-effort, after death is recorded.
         if (this.onEvent && !this.disposing) {
@@ -541,7 +701,9 @@ export class PooledConnection {
                     protocolVersion: PROTOCOL_VERSION,
                     // Truthful advertisement: computed from the consumer-provided handlers registered on
                     // this runner. Omitted flags are unsupported; false flags are never sent deliberately.
-                    clientCapabilities: clientCapabilitiesFor(this.clientHandlers),
+                    clientCapabilities: clientCapabilitiesFor(this.clientHandlers, {
+                        elicitation: this.advertiseElicitation,
+                    }),
                     clientInfo: { ...CLIENT_INFO },
                 })),
                 deadline,
@@ -577,23 +739,14 @@ export class PooledConnection {
             // does not advertise (http/sse gated on mcpCapabilities; stdio is always serviceable).
             // Fail-fast and non-recoverable — re-running the same incompatible transport can never
             // succeed. Lenient for agents that advertise no mcpCapabilities (the legacy passthrough).
-            const unsupported = this.negotiated
-                ? unsupportedMcpServer(opts.mcpServers, this.negotiated.agent)
-                : undefined;
-            if (unsupported) {
-                throw new WorkflowError(`MCP server "${unsupported.name}" uses the "${unsupported.transport}" transport, which the ` +
-                    `${this.backendId} agent does not support`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: opts.label });
-            }
+            this.assertSupportedMcpServers(opts);
             // session/new `_meta`, layered lowest-to-highest precedence: the backend's static
             // defaults (a custom registry entry's `sessionMeta`), then the generic user passthrough
             // (opts.meta), then the backend's protocol-critical `_meta` (Claude schema channel;
             // Codex base/developer instructions), then the engine runId correlation stamp. The result
             // is gated against the agent's advertised custom capabilities (a declared key the agent
             // said it does not honor is dropped). When no layer survives, no `_meta` is sent.
-            const meta = this.gateCustomMeta(stampRunId(layerMeta(this.backend.sessionMetaDefaults?.(), opts.meta, this.backend.sessionMeta(opts.schema, {
-                baseInstructions: opts.baseInstructions,
-                developerInstructions: opts.developerInstructions,
-            })), opts.runId));
+            const meta = this.sessionRequestMeta(opts);
             const request = {
                 cwd: opts.cwd,
                 // Client-provided MCP servers (additive run input), else the default empty list.
@@ -601,7 +754,7 @@ export class PooledConnection {
                 ...(meta ? { _meta: meta } : {}),
             };
             const response = await this.race(this.connection.agent.request(AGENT_METHODS.session_new, request));
-            const state = new SessionState(opts.cwd, opts.policy, opts.permissionResolver, opts.label, opts.runId, response.modes, opts.retainSessionLog ?? true);
+            const state = new SessionState(opts.cwd, opts.policy, opts.permissionResolver, opts.elicitationResolver, opts.label, opts.runId, response.modes, opts.retainSessionLog ?? true);
             this.client.register(response.sessionId, state);
             return new SessionHandle(this, response.sessionId, state, response.configOptions ?? [], opts);
         }
@@ -610,6 +763,71 @@ export class PooledConnection {
             throw error;
         }
     }
+    /** Reopen an existing session and replay its transcript through the router before resolving. */
+    loadSession(sessionId, opts) {
+        return this.reattachSession(AGENT_METHODS.session_load, sessionId, opts);
+    }
+    /** Reopen an existing session without transcript replay. */
+    resumeSession(sessionId, opts) {
+        return this.reattachSession(AGENT_METHODS.session_resume, sessionId, opts);
+    }
+    rawAgentRequest(method, params) {
+        // SDK 1.2.0 still maps session/load through emptyObjectResponse in ClientContext.request(),
+        // but both supported adapters return configOptions/modes there and the driven wrapper must
+        // adopt them. This bypasses only the SDK response mapper, not JSON-RPC validation/racing.
+        const agent = this.connection.agent;
+        return this.race(agent.sendRequest(method, params));
+    }
+    async reattachSession(method, sessionId, opts) {
+        this._activeSessions += 1;
+        let registered = false;
+        const state = new SessionState(opts.cwd, opts.policy, opts.permissionResolver, opts.elicitationResolver, opts.label, opts.runId, undefined, opts.retainSessionLog ?? true);
+        try {
+            await this.ready;
+            this.assertLifecycleSupported(method, opts.label);
+            this.assertSupportedMcpServers(opts);
+            const meta = this.sessionRequestMeta(opts);
+            const request = {
+                sessionId,
+                cwd: opts.cwd,
+                mcpServers: opts.mcpServers ?? [],
+                ...(meta ? { _meta: meta } : {}),
+            };
+            // Replayed updates and permission requests can arrive before the response, so the
+            // caller-provided id must be routable before the wire call leaves this process.
+            this.client.register(sessionId, state);
+            registered = true;
+            let response;
+            if (method === AGENT_METHODS.session_load) {
+                const loadRequest = request;
+                response = await this.rawAgentRequest(AGENT_METHODS.session_load, loadRequest);
+            }
+            else {
+                const resumeRequest = request;
+                response = await this.rawAgentRequest(AGENT_METHODS.session_resume, resumeRequest);
+            }
+            state.modes = response.modes;
+            return new SessionHandle(this, sessionId, state, response.configOptions ?? [], opts);
+        }
+        catch (error) {
+            if (registered)
+                this.client.unregister(sessionId);
+            this._activeSessions -= 1;
+            throw error;
+        }
+    }
+    /** session/list on a dedicated connection, gated on the initialize advertisement. */
+    async listSessions(request, label) {
+        await this.ready;
+        this.assertLifecycleSupported(AGENT_METHODS.session_list, label);
+        return this.race(this.connection.agent.request(AGENT_METHODS.session_list, request));
+    }
+    /** session/delete on a dedicated connection, gated on the initialize advertisement. */
+    async deleteSession(request, label) {
+        await this.ready;
+        this.assertLifecycleSupported(AGENT_METHODS.session_delete, label);
+        await this.race(this.connection.agent.request(AGENT_METHODS.session_delete, request));
+    }
     /** session/prompt on this connection, raced against process death. */
     prompt(request) {
         return this.race(this.connection.agent.request(AGENT_METHODS.session_prompt, request));
@@ -623,6 +841,7 @@ export class PooledConnection {
         return this.race(this.connection.agent.request(AGENT_METHODS.session_set_mode, request));
     }
     request(method, params, options) {
+        assertSafeRawRequest(method);
         return this.race(this.connection.agent.request(method, params, options));
     }
     notify(method, params) {
@@ -631,6 +850,7 @@ export class PooledConnection {
     /** Best-effort ACP cancel for one session (wired to opts.signal). The PROCESS stays pooled. */
     async cancelSession(sessionId) {
         this.client.settlePendingPermissions(sessionId);
+        this.client.settlePendingElicitations(sessionId);
         if (!this._alive)
             return;
         try {
@@ -743,6 +963,10 @@ export class SessionHandle {
     get history() {
         return this.state.history;
     }
+    /** Assistant text accumulated across the retained session log. */
+    get text() {
+        return this.state.textChunks.join("");
+    }
     /** Agent-advertised session mode catalog plus the currently active mode, if supported. */
     get modes() {
         return this.state.modes;

package/dist/capabilities.d.ts

@@ -18,6 +18,15 @@ export interface NegotiatedCapabilities {
     agentInfo: Implementation | undefined;
     /** Whether session/close is advertised (gates the best-effort release-time close). */
     supportsClose: boolean;
+    /** Whether session/load is advertised. The current SDK keeps this as the legacy top-level
+     *  `loadSession` flag; tolerate a future sessionCapabilities.load shape for forward compat. */
+    supportsLoadSession: boolean;
+    /** Whether session/list is advertised. */
+    supportsListSessions: boolean;
+    /** Whether session/delete is advertised. */
+    supportsDeleteSession: boolean;
+    /** Whether session/resume is advertised. */
+    supportsResumeSession: boolean;
     /** The parsed backend-declared custom-capability block (the namespaced `_meta` object), or
      *  undefined when the backend declared none or the agent did not advertise it — passthrough. */
     customMetaSupport: Record<string, unknown> | undefined;
@@ -27,6 +36,8 @@ export interface NegotiatedCapabilities {
 }
 /** Parse an initialize response into the connection's derived capability state. */
 export declare function negotiateCapabilities(response: InitializeResponse, customCapabilities?: Backend["customCapabilities"]): NegotiatedCapabilities;
+/** Human-readable lifecycle advertisement summary for strict wrapper gate errors. */
+export declare function describeLifecycleAdvertisement(agent: AgentCapabilities): string;
 /** True only when the agent selected EXACTLY PROTOCOL_VERSION. This client implements that one wire
  *  version and adapts its behavior to no other, so any other selected version — older or newer —
  *  means close the connection per the ACP spec's SHOULD-close rule. Per the spec the agent echoes

package/dist/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAQ5C;;;iGAGiG;AACjG,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAInD,CAAC;AAEF,qFAAqF;AACrF,MAAM,WAAW,sBAAsB;IACrC;0FACsF;IACtF,eAAe,EAAE,MAAM,CAAC;IACxB;4DACwD;IACxD,KAAK,EAAE,iBAAiB,CAAC;IACzB,+DAA+D;IAC/D,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,sFAAsF;IACtF,aAAa,EAAE,OAAO,CAAC;IACvB;oGACgG;IAChG,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACvD;+EAC2E;IAC3E,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC1C;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,kBAAkB,EAC5B,kBAAkB,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GACjD,sBAAsB,CAYxB;AAaD;;;;+DAI+D;AAC/D,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;;gEAGgE;AAChE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,SAAS,GAAE,SAAS,MAAM,EAA2B,GACpD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAWrC;AAED;;;;;2EAK2E;AAC3E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EAAE,EACtB,KAAK,EAAE,iBAAiB,EACxB,SAAS,EAAE,MAAM,GAChB,YAAY,EAAE,CAchB;AAkCD;;;;0EAI0E;AAC1E,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EAAE,GAAG,SAAS,EACtC,KAAK,EAAE,iBAAiB,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;CAAE,GAAG,SAAS,CAYzD"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAQ5C;;;iGAGiG;AACjG,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAInD,CAAC;AAEF,qFAAqF;AACrF,MAAM,WAAW,sBAAsB;IACrC;0FACsF;IACtF,eAAe,EAAE,MAAM,CAAC;IACxB;4DACwD;IACxD,KAAK,EAAE,iBAAiB,CAAC;IACzB,+DAA+D;IAC/D,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,sFAAsF;IACtF,aAAa,EAAE,OAAO,CAAC;IACvB;mGAC+F;IAC/F,mBAAmB,EAAE,OAAO,CAAC;IAC7B,0CAA0C;IAC1C,oBAAoB,EAAE,OAAO,CAAC;IAC9B,4CAA4C;IAC5C,qBAAqB,EAAE,OAAO,CAAC;IAC/B,4CAA4C;IAC5C,qBAAqB,EAAE,OAAO,CAAC;IAC/B;oGACgG;IAChG,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACvD;+EAC2E;IAC3E,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC1C;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,kBAAkB,EAC5B,kBAAkB,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GACjD,sBAAsB,CAkBxB;AAMD,qFAAqF;AACrF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAiB/E;AAaD;;;;+DAI+D;AAC/D,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;;gEAGgE;AAChE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,SAAS,GAAE,SAAS,MAAM,EAA2B,GACpD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAWrC;AAED;;;;;2EAK2E;AAC3E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EAAE,EACtB,KAAK,EAAE,iBAAiB,EACxB,SAAS,EAAE,MAAM,GAChB,YAAY,EAAE,CAchB;AAkCD;;;;0EAI0E;AAC1E,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EAAE,GAAG,SAAS,EACtC,KAAK,EAAE,iBAAiB,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;CAAE,GAAG,SAAS,CAYzD"}