@automatalabs/acp-agents 0.12.0 → 0.14.0

package/dist/acp-client.d.ts

@@ -1,4 +1,4 @@
-import { type ContentBlock, type AgentNotificationMethod, type AgentNotificationParamsByMethod, type AgentRequestMethod, type AgentRequestParamsByMethod, type AgentRequestResponsesByMethod, type PromptRequest, type PromptResponse, type RequestPermissionResponse, type SendRequestOptions, type SessionConfigOption, type SessionNotification, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse } from "@agentclientprotocol/sdk";
+import { 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";
@@ -26,10 +26,11 @@ declare class SessionState {
     readonly usage: UsageAccumulator;
     readonly pendingPermissions: Set<(outcome: RequestPermissionResponse) => void>;
     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, retainSessionLog?: boolean);
+    constructor(cwd: string, policy: ToolPolicy, permissionResolver?: PermissionResolver | 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
@@ -126,6 +127,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;
@@ -139,10 +143,22 @@ 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. */
     setSessionConfigOption(request: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
+    /** session/set_mode on this connection, raced against process death. */
+    setSessionMode(request: SetSessionModeRequest): Promise<SetSessionModeResponse>;
     /** RAW protocol escape hatch: this makes the full ACP spec reachable (for example
      *  session/set_mode, session/fork, authenticate). Prefer the named wrappers when they exist
      *  because they preserve engine semantics such as accumulation/drain and usage recording;
@@ -184,6 +200,10 @@ 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;
     /**
      * Select the model for this session from the agent-advertised config options (§5.4).
      * Returns `matched:false` (the caller fires onModelFallback) when the catalog has no value
@@ -220,6 +240,8 @@ export declare class SessionHandle implements StructuredSource {
      *  A boolean value drives a `type: "boolean"` option (the request must carry the type
      *  discriminator on the wire); a string value drives a select option. */
     private applyConfigOption;
+    /** Switch the session's operating mode through ACP's strict confinement channel. */
+    setMode(modeId: string): Promise<void>;
     /** Send a prompt turn and drain it; returns the final PromptResponse. */
     prompt(content: string | ContentBlock[], promptMeta?: Record<string, unknown>): Promise<PromptResponse>;
     /** StructuredSource — the latest turn's assistant text. */

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,7 +24,7 @@ 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 { UsageAccumulator } from "./usage.js";
@@ -42,6 +42,15 @@ 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 {
@@ -56,16 +65,18 @@ class SessionState {
     usage = new UsageAccumulator();
     pendingPermissions = 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, retainSessionLog = true) {
+    constructor(cwd, policy, permissionResolver, label, runId, modes, retainSessionLog = true) {
         this.cwd = cwd;
         this.policy = policy;
         this.permissionResolver = permissionResolver;
         this.label = label;
         this.runId = runId;
         this.retainSessionLog = retainSessionLog;
+        this.modes = modes;
     }
     /** 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
@@ -116,6 +127,13 @@ class SessionState {
                 this.usage.recordContextTokens(update.used, update.size);
                 break;
             }
+            case "current_mode_update": {
+                this.modes = {
+                    ...(this.modes ?? { availableModes: [] }),
+                    currentModeId: update.currentModeId,
+                };
+                break;
+            }
             default:
                 break;
         }
@@ -309,6 +327,35 @@ function cancelledPermissionResponse() {
 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) ?? [];
+}
+function modeSelectionError(backendId, requested, advertisedIds, label, cause) {
+    const advertised = advertisedIds.length > 0 ? advertisedIds.join(", ") : "none";
+    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;
+    if (typeof error === "string")
+        return error;
+    return String(error);
+}
 const DEFAULT_INIT_TIMEOUT_MS = 60_000;
 /** Deadline for the one-time ACP `initialize` handshake per pooled process. Overridable via
  *  AGENTPRISM_ACP_INIT_TIMEOUT_MS (e.g. for slow cold-start backends). Clamped to >= 1s. */
@@ -466,6 +513,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)
@@ -553,24 +629,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 });
-            }
-            const state = new SessionState(opts.cwd, opts.policy, opts.permissionResolver, opts.label, opts.runId, opts.retainSessionLog ?? true);
+            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.
@@ -578,6 +644,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);
             this.client.register(response.sessionId, state);
             return new SessionHandle(this, response.sessionId, state, response.configOptions ?? [], opts);
         }
@@ -586,6 +653,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.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));
@@ -594,7 +726,12 @@ export class PooledConnection {
     setSessionConfigOption(request) {
         return this.race(this.connection.agent.request(AGENT_METHODS.session_set_config_option, request));
     }
+    /** session/set_mode on this connection, raced against process death. */
+    setSessionMode(request) {
+        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) {
@@ -715,6 +852,14 @@ 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;
+    }
     /**
      * Select the model for this session from the agent-advertised config options (§5.4).
      * Returns `matched:false` (the caller fires onModelFallback) when the catalog has no value
@@ -816,6 +961,21 @@ export class SessionHandle {
         const response = await this.pooled.setSessionConfigOption(request);
         this.configOptions = response.configOptions;
     }
+    /** Switch the session's operating mode through ACP's strict confinement channel. */
+    async setMode(modeId) {
+        const modes = this.state.modes;
+        const ids = modeIds(modes);
+        if (!modes || !ids.includes(modeId)) {
+            throw modeSelectionError(this.pooled.backendId, modeId, ids, this.opts.label);
+        }
+        try {
+            await this.pooled.setSessionMode({ sessionId: this.sessionId, modeId });
+        }
+        catch (error) {
+            throw modeSelectionError(this.pooled.backendId, modeId, ids, this.opts.label, error);
+        }
+        this.state.modes = { ...modes, currentModeId: modeId };
+    }
     /** Send a prompt turn and drain it; returns the final PromptResponse. */
     async prompt(content, promptMeta) {
         this.opts.signal?.throwIfAborted();

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"}

package/dist/capabilities.js

@@ -35,17 +35,44 @@ export const GATED_CUSTOM_META_KEYS = [
 /** Parse an initialize response into the connection's derived capability state. */
 export function negotiateCapabilities(response, customCapabilities) {
     const agent = response.agentCapabilities ?? {};
+    const sessionCapabilities = agent.sessionCapabilities;
     return {
         protocolVersion: response.protocolVersion,
         agent,
         agentInfo: response.agentInfo ?? undefined,
-        supportsClose: Boolean(agent.sessionCapabilities?.close),
+        supportsClose: advertised(sessionCapabilities?.close),
+        supportsLoadSession: agent.loadSession === true || advertised(sessionCapabilities?.load),
+        supportsListSessions: advertised(sessionCapabilities?.list),
+        supportsDeleteSession: advertised(sessionCapabilities?.delete),
+        supportsResumeSession: advertised(sessionCapabilities?.resume),
         customMetaSupport: customCapabilities
             ? readCustomNamespace(agent._meta, customCapabilities.namespace)
             : undefined,
         gatedKeys: customCapabilities ? [...customCapabilities.gatedKeys] : undefined,
     };
 }
+function advertised(capability) {
+    return capability !== undefined && capability !== null && capability !== false;
+}
+/** Human-readable lifecycle advertisement summary for strict wrapper gate errors. */
+export function describeLifecycleAdvertisement(agent) {
+    const sessionCapabilities = agent.sessionCapabilities;
+    const session = [
+        ["close", sessionCapabilities?.close],
+        ["list", sessionCapabilities?.list],
+        ["delete", sessionCapabilities?.delete],
+        ["resume", sessionCapabilities?.resume],
+        ["fork", sessionCapabilities?.fork],
+        ["additionalDirectories", sessionCapabilities?.additionalDirectories],
+        ["load", sessionCapabilities?.load],
+    ]
+        .filter(([, value]) => advertised(value))
+        .map(([name]) => name);
+    return [
+        `loadSession=${agent.loadSession === true ? "true" : "false"}`,
+        `sessionCapabilities=${session.length > 0 ? session.join(", ") : "none"}`,
+    ].join("; ");
+}
 function readCustomNamespace(meta, namespace) {
     if (!meta || typeof meta !== "object")
         return undefined;

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
-export type { AcpRunnerOptions } from "./runner.js";
+export type { AcpRunnerOptions, DeleteSessionOptions, ListSessionsOptions, ReattachSessionOptions, } from "./runner.js";
 export { InteractiveSession } from "./interactive.js";
 export type { InteractiveSessionOptions, InteractiveTurn } from "./interactive.js";
 export { AGENT_METHODS, CLIENT_METHODS } from "@agentclientprotocol/sdk";
-export type { AgentNotificationMethod, AgentNotificationParamsByMethod, AgentRequestMethod, AgentRequestParamsByMethod, AgentRequestResponsesByMethod, SendRequestOptions, } from "@agentclientprotocol/sdk";
+export type { AgentNotificationMethod, AgentNotificationParamsByMethod, AgentRequestMethod, AgentRequestParamsByMethod, AgentRequestResponsesByMethod, DeleteSessionRequest, DeleteSessionResponse, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, LoadSessionResponse, ResumeSessionRequest, ResumeSessionResponse, SessionMode, SessionModeState, SessionInfo, SendRequestOptions, } from "@agentclientprotocol/sdk";
 export { BACKENDS_ENV, registryWithRunBackends, resolveBackendRegistry } from "./registry.js";
 export type { BackendRegistry, CustomBackendConfig, RegisteredBackend } from "./registry.js";
 export { PooledConnection, SessionHandle } from "./acp-client.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACzE,YAAY,EACV,uBAAuB,EACvB,+BAA+B,EAC/B,kBAAkB,EAClB,0BAA0B,EAC1B,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9F,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACvF,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAIxF,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,0BAA0B,EAC1B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAI7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG5G,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClG,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACzE,YAAY,EACV,uBAAuB,EACvB,+BAA+B,EAC/B,kBAAkB,EAClB,0BAA0B,EAC1B,6BAA6B,EAC7B,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9F,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACvF,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAIxF,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,0BAA0B,EAC1B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAI7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG5G,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClG,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/interactive.d.ts

@@ -1,5 +1,5 @@
-import type { AgentNotificationMethod, AgentNotificationParamsByMethod, AgentRequestMethod, AgentRequestParamsByMethod, AgentRequestResponsesByMethod, ContentBlock, SendRequestOptions, StopReason } from "@agentclientprotocol/sdk";
-import type { McpServerConfig, PromptImage } from "@automatalabs/shared-types";
+import type { AgentNotificationMethod, AgentNotificationParamsByMethod, AgentRequestMethod, AgentRequestParamsByMethod, AgentRequestResponsesByMethod, ContentBlock, SendRequestOptions, SessionModeState, StopReason } from "@agentclientprotocol/sdk";
+import type { AgentHistoryEntry, McpServerConfig, PromptImage } from "@automatalabs/shared-types";
 import type { RunOptions } from "@automatalabs/shared-types";
 import type { Backend, BackendId } from "./backend.js";
 import type { NegotiatedCapabilities } from "./capabilities.js";
@@ -14,6 +14,8 @@ import type { PermissionResolver } from "./permissions.js";
 export interface InteractiveSessionOptions {
     /** Model spec (`provider/modelId`, bare model id, or registered custom backend route). */
     model?: string;
+    /** Agent-advertised session mode id. Strict: openSession fails rather than running unconfined. */
+    mode?: string;
     /** Coarse tier consulted only when `model` is unset. */
     tier?: string;
     /** Absolute working directory for ACP session/new. Required for held-open sessions. */
@@ -40,6 +42,8 @@ export interface InteractiveSessionOptions {
     developerInstructions?: string;
     /** Client-provided MCP servers to attach at session/new. */
     mcpServers?: McpServerConfig[];
+    /** Keep accumulated text/history after each prompt turn; default false for held-open sessions. */
+    retainSessionLog?: boolean;
     /** Host-owned cancellation. Aborting releases this interactive session. */
     signal?: AbortSignal;
 }
@@ -89,6 +93,12 @@ export declare class InteractiveSession {
     constructor(deps: InteractiveSessionDeps);
     /** Negotiated initialize capabilities for this session's dedicated connection. */
     get capabilities(): NegotiatedCapabilities | undefined;
+    /** Agent-advertised session mode catalog plus the currently active mode, if supported. */
+    get modes(): SessionModeState | null | undefined;
+    /** Assistant text accumulated in this session's retained log. */
+    get text(): string;
+    /** Message/tool history accumulated in this session's retained log. */
+    get history(): readonly AgentHistoryEntry[];
     /** Send one prompt turn. A concurrent prompt on the same InteractiveSession is rejected with a
      *  clear host-side error; queueing is deliberately left to the host so turn boundaries remain
      *  explicit. Per-turn images are appended only to this prompt, and SessionHandle.prompt()
@@ -103,6 +113,8 @@ export declare class InteractiveSession {
      *  recording; calling session/prompt here bypasses those paths. */
     request<Method extends AgentRequestMethod>(method: Method, params: AgentRequestParamsByMethod[Method], options?: SendRequestOptions): Promise<AgentRequestResponsesByMethod[Method]>;
     request<Response = unknown, Params = unknown>(method: string, params?: Params, options?: SendRequestOptions): Promise<Response>;
+    /** Switch this session's ACP operating mode. Fails strictly when the agent did not advertise it. */
+    setMode(modeId: string): Promise<void>;
     /** RAW protocol notification escape hatch for held-open sessions. Params carry `sessionId`
      *  explicitly; use `session.sessionId` so the wire call targets this session. */
     notify<Method extends AgentNotificationMethod>(method: Method, params: AgentNotificationParamsByMethod[Method]): Promise<void>;

package/dist/interactive.d.ts.map

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

package/dist/interactive.js

@@ -49,6 +49,18 @@ export class InteractiveSession {
     get capabilities() {
         return this.connection.capabilities;
     }
+    /** Agent-advertised session mode catalog plus the currently active mode, if supported. */
+    get modes() {
+        return this.session.modes;
+    }
+    /** Assistant text accumulated in this session's retained log. */
+    get text() {
+        return this.session.text;
+    }
+    /** Message/tool history accumulated in this session's retained log. */
+    get history() {
+        return this.session.history;
+    }
     /** Send one prompt turn. A concurrent prompt on the same InteractiveSession is rejected with a
      *  clear host-side error; queueing is deliberately left to the host so turn boundaries remain
      *  explicit. Per-turn images are appended only to this prompt, and SessionHandle.prompt()
@@ -80,6 +92,13 @@ export class InteractiveSession {
             throw new Error("InteractiveSession has been released");
         return this.connection.request(method, params, options);
     }
+    /** Switch this session's ACP operating mode. Fails strictly when the agent did not advertise it. */
+    async setMode(modeId) {
+        if (this.releasePromise)
+            throw new Error("InteractiveSession has been released");
+        this.signal?.throwIfAborted();
+        await this.session.setMode(modeId);
+    }
     async notify(method, params) {
         if (this.releasePromise)
             throw new Error("InteractiveSession has been released");

package/dist/permissions.d.ts

@@ -13,6 +13,10 @@ export interface ToolPolicy {
     allow?: string[];
     /** Deny-list (agentType `disallowedTools`), applied after the allow-list. */
     deny?: string[];
+    /** No-match fallback for the headless auto-responder. Default "allow" preserves historical
+     *  behavior. Explicit ACP session modes set this to "deny" unless a permission resolver is
+     *  present, otherwise read-only/plan confinement can be bypassed by auto-approved escalations. */
+    defaultOutcome?: "allow" | "deny";
 }
 /** Decide the auto-response for one permission request given the tool policy. */
 export declare function decidePermission(request: RequestPermissionRequest, policy: ToolPolicy): RequestPermissionResponse;

package/dist/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAGV,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;wDAMwD;AACxD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,wBAAwB,EAChC,GAAG,EAAE,eAAe,KACjB,OAAO,CAAC,yBAAyB,CAAC,GAAG,yBAAyB,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAKD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,UAAU,GACjB,yBAAyB,CAqC3B"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAGV,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;wDAMwD;AACxD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,wBAAwB,EAChC,GAAG,EAAE,eAAe,KACjB,OAAO,CAAC,yBAAyB,CAAC,GAAG,yBAAyB,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;sGAEkG;IAClG,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACnC;AAKD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,UAAU,GACjB,yBAAyB,CAsC3B"}

package/dist/permissions.js

@@ -9,6 +9,7 @@ export function decidePermission(request, policy) {
     const allPool = [...toolNames, ...decoration];
     const denyList = policy.deny ?? [];
     const allowList = policy.allow ?? [];
+    const defaultOutcome = policy.defaultOutcome ?? "allow";
     const hasDeny = denyList.length > 0;
     const hasAllowList = allowList.length > 0;
     const denyExact = hasDeny && exactMatchesAny(exactPool, denyList);
@@ -20,12 +21,12 @@ export function decidePermission(request, policy) {
         // (Suppresses loose substring matches: a deny `read` no longer catches an exactly
         // allow-listed `thread-reader`.)
         denied = denyExact;
-        allowedByList = !hasAllowList || allowExact;
+        allowedByList = hasAllowList ? allowExact : defaultOutcome === "allow";
     }
     else {
         // (b) No exact match in either list -> best-effort bidirectional substring fallback.
         denied = hasDeny && substringMatchesAny(allPool, denyList);
-        allowedByList = !hasAllowList || substringMatchesAny(allPool, allowList);
+        allowedByList = hasAllowList ? substringMatchesAny(allPool, allowList) : defaultOutcome === "allow";
     }
     const wantAllow = !denied && allowedByList;
     const option = pickOption(request.options, wantAllow);

package/dist/protocol-coverage.d.ts

@@ -3,7 +3,9 @@ type ValueOf<T> = T[keyof T];
 type ClientMethod = ValueOf<typeof CLIENT_METHODS>;
 type AgentMethod = ValueOf<typeof AGENT_METHODS>;
 export type ClientMethodCoverage = "served" | "pending";
-export type AgentMethodCoverage = "driven" | "passthrough";
+/** `guarded` means the raw passthrough would create/reopen session state outside the router, so
+ *  the client rejects it until a driven wrapper can route updates, permissions, and terminals. */
+export type AgentMethodCoverage = "driven" | "passthrough" | "guarded";
 /** Enforceable definition of "full ACP spec support": every SDK method constant is classified
  *  here, and the tripwire test fails when an SDK bump silently widens or shrinks the protocol. */
 export declare const CLIENT_METHOD_COVERAGE: Record<ClientMethod, ClientMethodCoverage>;

package/dist/protocol-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-coverage.d.ts","sourceRoot":"","sources":["../src/protocol-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEzE,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAC7B,KAAK,YAAY,GAAG,OAAO,CAAC,OAAO,cAAc,CAAC,CAAC;AACnD,KAAK,WAAW,GAAG,OAAO,CAAC,OAAO,aAAa,CAAC,CAAC;AAEjD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,SAAS,CAAC;AACxD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAE3D;kGACkG;AAClG,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,YAAY,EAAE,oBAAoB,CAe7E,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,WAAW,EAAE,mBAAmB,CA6B1E,CAAC"}
+{"version":3,"file":"protocol-coverage.d.ts","sourceRoot":"","sources":["../src/protocol-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEzE,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAC7B,KAAK,YAAY,GAAG,OAAO,CAAC,OAAO,cAAc,CAAC,CAAC;AACnD,KAAK,WAAW,GAAG,OAAO,CAAC,OAAO,aAAa,CAAC,CAAC;AAEjD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,SAAS,CAAC;AACxD;kGACkG;AAClG,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,CAAC;AAEvE;kGACkG;AAClG,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,YAAY,EAAE,oBAAoB,CAe7E,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,WAAW,EAAE,mBAAmB,CA6B1E,CAAC"}

package/dist/protocol-coverage.js

@@ -24,16 +24,16 @@ export const AGENT_METHOD_COVERAGE = {
     [AGENT_METHODS.providers_set]: "passthrough",
     [AGENT_METHODS.providers_disable]: "passthrough",
     [AGENT_METHODS.session_new]: "driven",
-    [AGENT_METHODS.session_load]: "passthrough",
-    [AGENT_METHODS.session_set_mode]: "passthrough",
+    [AGENT_METHODS.session_load]: "driven",
+    [AGENT_METHODS.session_set_mode]: "driven",
     [AGENT_METHODS.session_set_config_option]: "driven",
     [AGENT_METHODS.session_prompt]: "driven",
     [AGENT_METHODS.session_cancel]: "driven",
     [AGENT_METHODS.mcp_message]: "passthrough",
-    [AGENT_METHODS.session_list]: "passthrough",
-    [AGENT_METHODS.session_delete]: "passthrough",
-    [AGENT_METHODS.session_fork]: "passthrough",
-    [AGENT_METHODS.session_resume]: "passthrough",
+    [AGENT_METHODS.session_list]: "driven",
+    [AGENT_METHODS.session_delete]: "driven",
+    [AGENT_METHODS.session_fork]: "guarded",
+    [AGENT_METHODS.session_resume]: "driven",
     [AGENT_METHODS.session_close]: "driven",
     [AGENT_METHODS.logout]: "passthrough",
     [AGENT_METHODS.nes_start]: "passthrough",

package/dist/runner.d.ts

@@ -1,4 +1,5 @@
 import { type AgentResult, type AgentRunner, type RunOptions } from "@automatalabs/shared-types";
+import type { ListSessionsResponse } from "@agentclientprotocol/sdk";
 import type { TSchema } from "typebox";
 import { type AcpPoolOptions } from "./pool.js";
 import { type AcpEventListener, type AcpEventName } from "./events.js";
@@ -6,6 +7,39 @@ import type { Backend } from "./backend.js";
 import { InteractiveSession, type InteractiveSessionOptions } from "./interactive.js";
 import { type BackendRegistry, type CustomBackendConfig } from "./registry.js";
 import type { PermissionResolver } from "./permissions.js";
+interface LifecycleRoutingOptions {
+    /** Model spec used only to select the backend process. */
+    model?: string;
+    /** Coarse tier consulted only when `model` is unset. */
+    tier?: string;
+    /** Event/telemetry label used in strict capability errors. */
+    label?: string;
+    /** Host-owned cancellation while the lifecycle request is in flight. */
+    signal?: AbortSignal;
+}
+/** Options for AcpAgentRunner.listSessions(). */
+export interface ListSessionsOptions extends LifecycleRoutingOptions {
+    /** Optional absolute working-directory filter. */
+    cwd?: string;
+    /** Opaque pagination cursor from the previous response. */
+    cursor?: string;
+    /** Generic ACP `_meta` passthrough for session/list. */
+    meta?: Record<string, unknown>;
+}
+/** Options for AcpAgentRunner.deleteSession(). */
+export interface DeleteSessionOptions extends LifecycleRoutingOptions {
+    /** Session id returned by session/list or previously persisted by the backend. */
+    sessionId: string;
+    /** Generic ACP `_meta` passthrough for session/delete. */
+    meta?: Record<string, unknown>;
+}
+/** Options for AcpAgentRunner.loadSession() and resumeSession(). */
+export interface ReattachSessionOptions extends InteractiveSessionOptions {
+    /** Existing backend session id to route before the lifecycle request is sent. */
+    sessionId: string;
+    /** Alias for onPermissionRequest for hosts that name the resolver by role. */
+    permissionResolver?: PermissionResolver;
+}
 /** Constructor options for the runner: pool sizing, client-side handlers, and the custom-backend
  *  registry. `backends` merges over (and wins against) env-declared AGENTPRISM_BACKENDS entries. */
 export interface AcpRunnerOptions extends AcpPoolOptions {
@@ -60,10 +94,20 @@ export declare class AcpAgentRunner implements AgentRunner {
      * is one).
      */
     openSession(opts: InteractiveSessionOptions): Promise<InteractiveSession>;
+    /** List persisted ACP sessions from the selected backend. */
+    listSessions(opts?: ListSessionsOptions): Promise<ListSessionsResponse>;
+    /** Delete a persisted ACP session from the selected backend. */
+    deleteSession(opts: DeleteSessionOptions): Promise<void>;
+    /** Load an existing ACP session and return a live, routed InteractiveSession. */
+    loadSession(opts: ReattachSessionOptions): Promise<InteractiveSession>;
+    /** Resume an existing ACP session without replay and return a live, routed InteractiveSession. */
+    resumeSession(opts: ReattachSessionOptions): Promise<InteractiveSession>;
     run<S extends TSchema | undefined = undefined>(prompt: string, options?: RunOptions<S>): Promise<AgentResult<S>>;
     /** Tear down the whole pool (close every long-lived process). Call when the run ends / the
      *  runner is disposed. Beyond the AgentRunner seam (additive) — never enters the resume hash. */
     dispose(): Promise<void>;
+    private createInteractiveSession;
+    private createDedicatedConnection;
     /** Build the backend choice, model-selection spec, tool policy, and session/new options in one
      *  place for run() and openSession() so new AcpSessionOptions fields cannot drift by path. */
     private prepareSession;
@@ -86,4 +130,5 @@ export declare function selectBackend(opts: {
     model?: string;
     tier?: string;
 }, registry?: BackendRegistry): Backend;
+export {};
 //# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

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

package/dist/runner.js

@@ -91,67 +91,66 @@ export class AcpAgentRunner {
      * is one).
      */
     async openSession(opts) {
+        return this.createInteractiveSession(opts, "openSession", (connection, prepared) => connection.openSession(prepared.sessionOptions));
+    }
+    /** List persisted ACP sessions from the selected backend. */
+    async listSessions(opts = {}) {
         if (this.disposed)
             throw new Error("ACP agent runner is disposed");
-        validateInteractiveCwd(opts.cwd, opts.label);
+        validateOptionalLifecycleCwd(opts.cwd, opts.label, "listSessions");
         opts.signal?.throwIfAborted();
-        const prepared = this.prepareSession(opts, {
-            cwd: opts.cwd,
-            schema: undefined,
-            registry: this.backends,
-            permissionResolver: opts.onPermissionRequest,
-            retainSessionLog: false,
-        });
-        this.installExitHook();
-        let interactive;
-        const connection = PooledConnection.create(prepared.backend, {
-            onDead: () => {
-                // Dedicated connections are not stored in pool arrays, so there is nothing to evict.
-                // Once the public wrapper exists, process death releases it through the normal path:
-                // subscriptions are removed, session_close is emitted, and future prompt() calls fail
-                // with the clean released-session error. Before then, openSession's catch tears down.
-                void interactive?.release();
-            },
-            onEvent: this.emitEvent,
-            permissionResolver: this.permissionResolver,
-            clientHandlers: this.clientHandlers,
-        });
-        let session;
+        const backend = selectBackend(opts, this.backends);
+        const connection = this.createDedicatedConnection(backend, () => undefined);
         try {
-            session = await connection.openSession(prepared.sessionOptions);
+            const request = {
+                ...(opts.cwd ? { cwd: opts.cwd } : {}),
+                ...(opts.cursor ? { cursor: opts.cursor } : {}),
+                ...(opts.meta ? { _meta: opts.meta } : {}),
+            };
+            const response = await connection.listSessions(request, opts.label);
             opts.signal?.throwIfAborted();
-            await applyModelSelection(session, prepared.modelSpec, opts);
+            if (this.disposed)
+                throw new Error("ACP agent runner is disposed");
+            return response;
+        }
+        finally {
+            await disposeBestEffort(connection);
+        }
+    }
+    /** Delete a persisted ACP session from the selected backend. */
+    async deleteSession(opts) {
+        if (this.disposed)
+            throw new Error("ACP agent runner is disposed");
+        if (typeof opts.sessionId !== "string" || opts.sessionId.trim() === "") {
+            throw new WorkflowError("deleteSession requires sessionId to be a non-empty string", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: opts.label });
+        }
+        opts.signal?.throwIfAborted();
+        const backend = selectBackend(opts, this.backends);
+        const connection = this.createDedicatedConnection(backend, () => undefined);
+        try {
+            const request = {
+                sessionId: opts.sessionId,
+                ...(opts.meta ? { _meta: opts.meta } : {}),
+            };
+            await connection.deleteSession(request, opts.label);
             opts.signal?.throwIfAborted();
             if (this.disposed)
                 throw new Error("ACP agent runner is disposed");
-            interactive = new InteractiveSession({
-                session,
-                connection,
-                backend: prepared.backend,
-                subscribe: (name, listener) => this.events.on(name, listener),
-                onRelease: (self) => this.interactiveSessions.delete(self),
-                signal: opts.signal,
-                label: opts.label,
-            });
-            this.interactiveSessions.set(interactive, connection);
-            return interactive;
         }
-        catch (error) {
-            try {
-                await session?.release();
-            }
-            catch {
-                // best-effort: openSession failed, so teardown must never mask the real error.
-            }
-            try {
-                await connection.dispose();
-            }
-            catch {
-                // best-effort: same as pool teardown.
-            }
-            throw error;
+        finally {
+            await disposeBestEffort(connection);
         }
     }
+    /** Load an existing ACP session and return a live, routed InteractiveSession. */
+    async loadSession(opts) {
+        validateLifecycleSessionId(opts.sessionId, opts.label, "loadSession");
+        return this.createInteractiveSession(opts, "loadSession", (connection, prepared) => connection.loadSession(opts.sessionId, prepared.sessionOptions));
+    }
+    /** Resume an existing ACP session without replay and return a live, routed InteractiveSession. */
+    async resumeSession(opts) {
+        validateLifecycleSessionId(opts.sessionId, opts.label, "resumeSession");
+        return this.createInteractiveSession(opts, "resumeSession", (connection, prepared) => connection.resumeSession(opts.sessionId, prepared.sessionOptions));
+    }
     async run(prompt, options = {}) {
         const opts = options;
         const schema = opts.schema;
@@ -183,6 +182,9 @@ export class AcpAgentRunner {
             // model id: "browser" selects nothing; "browser/foo" selects "foo". Built-ins get the
             // full spec unchanged (their catalogs match provider-prefixed and bare ids).
             await applyModelSelection(session, prepared.modelSpec, opts);
+            opts.signal?.throwIfAborted();
+            if (opts.mode)
+                await session.setMode(opts.mode);
             const text = buildRunPrompt(prompt, opts, schema, prepared.backend);
             const initialPrompt = opts.images && opts.images.length > 0 ? promptWithImages(text, opts.images) : text;
             // Generic turn-scoped _meta passthrough merged UNDER the backend-computed keys (e.g. the
@@ -260,11 +262,79 @@ export class AcpAgentRunner {
         await this.pool.dispose();
         this.events.removeAllListeners();
     }
+    async createInteractiveSession(opts, methodName, open) {
+        if (this.disposed)
+            throw new Error("ACP agent runner is disposed");
+        validateInteractiveCwd(opts.cwd, opts.label, methodName);
+        opts.signal?.throwIfAborted();
+        const prepared = this.prepareSession(opts, {
+            cwd: opts.cwd,
+            schema: undefined,
+            registry: this.backends,
+            permissionResolver: opts.permissionResolver ?? opts.onPermissionRequest,
+            retainSessionLog: opts.retainSessionLog ?? false,
+        });
+        this.installExitHook();
+        let interactive;
+        const connection = this.createDedicatedConnection(prepared.backend, () => {
+            // Dedicated connections are not stored in pool arrays, so there is nothing to evict.
+            // Once the public wrapper exists, process death releases it through the normal path:
+            // subscriptions are removed, session_close is emitted, and future prompt() calls fail
+            // with the clean released-session error. Before then, this method's catch tears down.
+            void interactive?.release();
+        });
+        let session;
+        try {
+            session = await open(connection, prepared);
+            opts.signal?.throwIfAborted();
+            await applyModelSelection(session, prepared.modelSpec, opts);
+            opts.signal?.throwIfAborted();
+            if (opts.mode)
+                await session.setMode(opts.mode);
+            opts.signal?.throwIfAborted();
+            if (this.disposed)
+                throw new Error("ACP agent runner is disposed");
+            interactive = new InteractiveSession({
+                session,
+                connection,
+                backend: prepared.backend,
+                subscribe: (name, listener) => this.events.on(name, listener),
+                onRelease: (self) => this.interactiveSessions.delete(self),
+                signal: opts.signal,
+                label: opts.label,
+            });
+            this.interactiveSessions.set(interactive, connection);
+            return interactive;
+        }
+        catch (error) {
+            try {
+                await session?.release();
+            }
+            catch {
+                // best-effort: lifecycle setup failed, so teardown must never mask the real error.
+            }
+            await disposeBestEffort(connection);
+            throw error;
+        }
+    }
+    createDedicatedConnection(backend, onDead) {
+        return PooledConnection.create(backend, {
+            onDead,
+            onEvent: this.emitEvent,
+            permissionResolver: this.permissionResolver,
+            clientHandlers: this.clientHandlers,
+        });
+    }
     /** Build the backend choice, model-selection spec, tool policy, and session/new options in one
      *  place for run() and openSession() so new AcpSessionOptions fields cannot drift by path. */
     prepareSession(opts, config) {
         const backend = selectBackend(opts, config.registry);
-        const policy = { allow: opts.toolNames, deny: opts.disallowedToolNames };
+        const hasPermissionResolver = Boolean(config.permissionResolver ?? this.permissionResolver);
+        const policy = {
+            allow: opts.toolNames,
+            deny: opts.disallowedToolNames,
+            defaultOutcome: opts.mode && !hasPermissionResolver ? "deny" : undefined,
+        };
         return {
             backend,
             modelSpec: innerModelSpec(opts.model ?? opts.tier, backend),
@@ -401,9 +471,27 @@ function innerModelSpec(spec, backend) {
 }
 /** Interactive sessions are public and long-lived, so fail before spawning a dedicated process
  *  when the required worktree root is absent or not absolute. */
-function validateInteractiveCwd(cwd, label) {
+function validateInteractiveCwd(cwd, label, methodName) {
     if (typeof cwd !== "string" || cwd.trim() === "" || !isAbsolute(cwd)) {
-        throw new WorkflowError("openSession requires cwd to be a non-empty absolute path", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        throw new WorkflowError(`${methodName} requires cwd to be a non-empty absolute path`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+    }
+}
+function validateOptionalLifecycleCwd(cwd, label, methodName) {
+    if (cwd === undefined || cwd === null)
+        return;
+    validateInteractiveCwd(cwd, label, methodName);
+}
+function validateLifecycleSessionId(sessionId, label, methodName) {
+    if (typeof sessionId !== "string" || sessionId.trim() === "") {
+        throw new WorkflowError(`${methodName} requires sessionId to be a non-empty string`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+    }
+}
+async function disposeBestEffort(connection) {
+    try {
+        await connection.dispose();
+    }
+    catch {
+        // Dedicated lifecycle processes are already no longer useful; never mask the request result.
     }
 }
 function backendIdForSpec(spec) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -31,7 +31,7 @@
     "@agentclientprotocol/claude-agent-acp": "0.56.0",
     "@automatalabs/codex-acp": "1.4.0",
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.8.0"
+    "@automatalabs/shared-types": "0.9.0"
   },
   "scripts": {
     "build": "tsc -b",