@pwrdrvr/agent-acp 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
+import { Client } from '@zed-industries/agent-client-protocol';
 import { Logger, AgentBackend, NormalizedThreadEvent, Unsubscribe, AgentBackendToolCallHandler, AgentBackendApprovalHandler, AgentStartThreadOptions, AgentBackendStartThreadResult, AgentStartTurnOptions, NormalizedTokenUsage, NormalizedToolCall } from '@pwrdrvr/agent-core';
-import { JsonRpcId, JsonRpcObserver, JsonRpcTransport } from '@pwrdrvr/agent-transport';
+import { JsonRpcId } from '@pwrdrvr/agent-transport';
 
-/** The bidirectional transport shape the ACP client drives. */
 interface AcpJsonRpcTransport {
     request(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
     notify?(method: string, params?: Record<string, unknown>): Promise<void>;
@@ -9,23 +9,53 @@ interface AcpJsonRpcTransport {
     onNotification(listener: (method: string, params: Record<string, unknown>) => void): () => void;
     onRequest?(listener: (method: string, params: Record<string, unknown>, id?: JsonRpcId) => Promise<unknown> | unknown): () => void;
 }
-type AcpStdioJsonRpcTransportOptions = {
+
+/** The subset of the library's client→agent surface that `AcpConnection`
+ *  drives. Injectable (via `createConnection`) so the adapter can be unit-tested
+ *  without spawning a real agent. The library's `ClientSideConnection` satisfies
+ *  this structurally (its methods take typed schema params; we pass records that
+ *  match at runtime). */
+interface AcpAgentConnection {
+    initialize(params: Record<string, unknown>): Promise<unknown>;
+    newSession(params: Record<string, unknown>): Promise<unknown>;
+    loadSession(params: Record<string, unknown>): Promise<unknown>;
+    prompt(params: Record<string, unknown>): Promise<unknown>;
+    cancel(params: Record<string, unknown>): Promise<void>;
+    setSessionMode(params: Record<string, unknown>): Promise<unknown>;
+    setSessionModel(params: Record<string, unknown>): Promise<unknown>;
+    authenticate(params: Record<string, unknown>): Promise<unknown>;
+    extMethod(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    extNotification(method: string, params: Record<string, unknown>): Promise<void>;
+}
+/** Built connection + a teardown handle (kills the child / closes streams). */
+type AcpAgentConnectionHandle = {
+    connection: AcpAgentConnection;
+    dispose: () => void;
+};
+type AcpConnectionOptions = {
     command: string;
     args: string[];
     env?: NodeJS.ProcessEnv;
-    requestTimeoutMs?: number;
-    observer?: JsonRpcObserver;
     logger?: Logger;
-    /** Override the underlying JSON-RPC transport (tests inject a fake). */
-    transport?: JsonRpcTransport;
+    /** Test seam: build the underlying connection. Defaults to spawning the agent
+     *  and wiring its stdio through the library's `ClientSideConnection`. */
+    createConnection?: (client: Client) => AcpAgentConnectionHandle;
 };
-declare class AcpStdioJsonRpcTransport implements AcpJsonRpcTransport {
-    private readonly connection;
+declare class AcpConnection implements AcpJsonRpcTransport {
+    private readonly options;
+    private readonly logger;
+    private connection;
+    private dispose;
+    private connecting;
     private readonly notificationListeners;
     private requestHandler;
-    constructor(options: AcpStdioJsonRpcTransportOptions);
-    connect(): Promise<void>;
-    request(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    constructor(options: AcpConnectionOptions);
+    /** The `Client` handler the library invokes for agent→client traffic. */
+    private buildClient;
+    private ensureConnected;
+    private connect;
+    private defaultCreateConnection;
+    request(method: string, params?: Record<string, unknown>, _timeoutMs?: number): Promise<unknown>;
     notify(method: string, params?: Record<string, unknown>): Promise<void>;
     close(): Promise<void>;
     onNotification(listener: (method: string, params: Record<string, unknown>) => void): () => void;
@@ -349,6 +379,20 @@ declare class AcpAgentClient implements AgentBackend {
         turnId: string;
     }>;
     interruptTurn(threadId: string): Promise<void>;
+    /** Release a thread the host has archived/closed.
+     *
+     *  ACP has NO protocol-level session delete/archive — sessions are
+     *  connection-scoped and the spec offers only `session/cancel` (interrupt).
+     *  So unlike the Codex backend (which sends `thread/archive`), there's no
+     *  remote call to make here. What we MUST do is drop the live session
+     *  LOCALLY: a long-lived pooled client (one process shared across surfaces,
+     *  warmed at startup) would otherwise accumulate a dead `AcpSessionState` for
+     *  every closed chat for the life of the app. Best-effort cancels an
+     *  in-flight turn first so the agent stops working on a thread the user
+     *  closed. Idempotent — no-ops if the session is already gone. A later
+     *  `reopenThread` re-establishes a fresh session under the same threadId, so
+     *  releasing here never blocks resume. */
+    archiveThread(threadId: string): Promise<void>;
     setMode(threadId: string, modeId: string): Promise<void>;
     setModel(threadId: string, modelId: string): Promise<void>;
     setConfigOption(threadId: string, optionId: string, value: string): Promise<void>;
@@ -743,4 +787,4 @@ declare class AcpRegistryService {
 declare function evaluateAcpDistributionPolicy(distribution: AcpRegistryDistribution, allowlist: AcpAllowlistDecision): AcpDistributionPolicy;
 declare function normalizeRegistry(raw: unknown): AcpRegistryAgent[];
 
-export { ACP_REGISTRY_URL, AcpAgentAllowlist, type AcpAgentAllowlistRule, AcpAgentClient, type AcpAgentClientFactory, type AcpAgentClientOptions, AcpAgentClientPool, type AcpAgentClientPoolOptions, type AcpAgentInstanceSource, type AcpAgentQuirks, type AcpAgentStrategy, type AcpAllowlistDecision, type AcpApplyContext, type AcpBinaryPlatformDistribution, type AcpDiscoveryProbe, type AcpDistributionKind, type AcpDistributionPolicy, type AcpJsonRpcTransport, type AcpMcpServerConfig, type AcpNormalizeResult, type AcpNormalizerOptions, AcpOneShotClient, type AcpOneShotClientOptions, type AcpOneShotRequest, type AcpOneShotResponse, type AcpPackageDistribution, type AcpPathExecutableLister, type AcpPromptContentBlock, type AcpRegistryAgent, type AcpRegistryAgentWithPolicy, type AcpRegistryAuthDescriptor, type AcpRegistryAuthMethod, type AcpRegistryDistribution, type AcpRegistryFetch, AcpRegistryService, type AcpRegistryServiceOptions, type AcpRegistrySnapshot, type AcpRuntimeAgentCapabilities, type AcpRuntimeAgentInfo, type AcpRuntimeCapabilities, type AcpRuntimeCapabilitiesHandler, type AcpRuntimeCapabilitiesSource, type AcpRuntimeConfigOption, type AcpRuntimeConfigOptionValue, type AcpRuntimeMode, type AcpRuntimeModel, type AcpRuntimeModels, type AcpRuntimeModes, type AcpRuntimeOptionSource, AcpSessionNormalizer, type AcpSessionRuntimeState, type AcpSpawnSpec, type AcpStartThreadOptions, type AcpStartTurnOptions, AcpStdioJsonRpcTransport, type AcpStdioJsonRpcTransportOptions, type AcpTitleHandler, type AcpVerificationStatus, BANNED_ACP_REGISTRY_IDS, BUILT_IN_ACP_STRATEGIES, DEFAULT_ACP_AGENT_ALLOWLIST, type DiscoveredAcpAgent, type DiscoveredAcpAgentGroup, type DiscoveredAcpAgentInstance, type LocalAcpAgentProbe, type LocalAcpDiscoveryOptions, type LocalAcpProbeResult, acpRuntimeSupportsSessionLoad, acpSessionRuntimeStateFromCapabilities, acpSessionRuntimeStateFromUpdate, asRecord, buildAcpBackendId, buildStrategyTable, defaultAcpAgentAllowlist, defaultQuirks, discoverLocalAcpAgentInstances, discoverLocalAcpAgents, evaluateAcpDistributionPolicy, geminiStrategy, grokStrategy, isBannedAcpRegistryId, kimiStrategy, mergeAcpRuntimeState, modeLabelFor, normalizeAcpRuntimeCapabilities, normalizeRegistry, qwenStrategy, readAcpContentText, readBoolean, readContentText, readFirstLocationPath, readFirstString, readKind, readNonEmptyString, readNumber, readPromptText, readString, readToolCallId, readToolContentText, readToolOutput, readUpdateText, strategyByBackendId, strategyById, toolCallFromUpdate, wellKnownAgentBinDirs };
+export { ACP_REGISTRY_URL, AcpAgentAllowlist, type AcpAgentAllowlistRule, AcpAgentClient, type AcpAgentClientFactory, type AcpAgentClientOptions, AcpAgentClientPool, type AcpAgentClientPoolOptions, type AcpAgentConnection, type AcpAgentConnectionHandle, type AcpAgentInstanceSource, type AcpAgentQuirks, type AcpAgentStrategy, type AcpAllowlistDecision, type AcpApplyContext, type AcpBinaryPlatformDistribution, AcpConnection, type AcpConnectionOptions, type AcpDiscoveryProbe, type AcpDistributionKind, type AcpDistributionPolicy, type AcpJsonRpcTransport, type AcpMcpServerConfig, type AcpNormalizeResult, type AcpNormalizerOptions, AcpOneShotClient, type AcpOneShotClientOptions, type AcpOneShotRequest, type AcpOneShotResponse, type AcpPackageDistribution, type AcpPathExecutableLister, type AcpPromptContentBlock, type AcpRegistryAgent, type AcpRegistryAgentWithPolicy, type AcpRegistryAuthDescriptor, type AcpRegistryAuthMethod, type AcpRegistryDistribution, type AcpRegistryFetch, AcpRegistryService, type AcpRegistryServiceOptions, type AcpRegistrySnapshot, type AcpRuntimeAgentCapabilities, type AcpRuntimeAgentInfo, type AcpRuntimeCapabilities, type AcpRuntimeCapabilitiesHandler, type AcpRuntimeCapabilitiesSource, type AcpRuntimeConfigOption, type AcpRuntimeConfigOptionValue, type AcpRuntimeMode, type AcpRuntimeModel, type AcpRuntimeModels, type AcpRuntimeModes, type AcpRuntimeOptionSource, AcpSessionNormalizer, type AcpSessionRuntimeState, type AcpSpawnSpec, type AcpStartThreadOptions, type AcpStartTurnOptions, type AcpTitleHandler, type AcpVerificationStatus, BANNED_ACP_REGISTRY_IDS, BUILT_IN_ACP_STRATEGIES, DEFAULT_ACP_AGENT_ALLOWLIST, type DiscoveredAcpAgent, type DiscoveredAcpAgentGroup, type DiscoveredAcpAgentInstance, type LocalAcpAgentProbe, type LocalAcpDiscoveryOptions, type LocalAcpProbeResult, acpRuntimeSupportsSessionLoad, acpSessionRuntimeStateFromCapabilities, acpSessionRuntimeStateFromUpdate, asRecord, buildAcpBackendId, buildStrategyTable, defaultAcpAgentAllowlist, defaultQuirks, discoverLocalAcpAgentInstances, discoverLocalAcpAgents, evaluateAcpDistributionPolicy, geminiStrategy, grokStrategy, isBannedAcpRegistryId, kimiStrategy, mergeAcpRuntimeState, modeLabelFor, normalizeAcpRuntimeCapabilities, normalizeRegistry, qwenStrategy, readAcpContentText, readBoolean, readContentText, readFirstLocationPath, readFirstString, readKind, readNonEmptyString, readNumber, readPromptText, readString, readToolCallId, readToolContentText, readToolOutput, readUpdateText, strategyByBackendId, strategyById, toolCallFromUpdate, wellKnownAgentBinDirs };

package/dist/index.js

@@ -1,54 +1,143 @@
-// src/acp-stdio-transport.ts
-import { noopLogger } from "@pwrdrvr/agent-core";
+// src/acp-connection.ts
+import { spawn } from "child_process";
+import { Readable, Writable } from "stream";
 import {
-  JsonRpcConnection,
-  StdioJsonRpcTransport
-} from "@pwrdrvr/agent-transport";
-var DEFAULT_REQUEST_TIMEOUT_MS = 10 * 6e4;
-var AcpStdioJsonRpcTransport = class {
+  ClientSideConnection,
+  ndJsonStream
+} from "@zed-industries/agent-client-protocol";
+import { noopLogger } from "@pwrdrvr/agent-core";
+var AcpConnection = class {
+  constructor(options) {
+    this.options = options;
+    this.logger = options.logger ?? noopLogger;
+  }
+  options;
+  logger;
   connection;
+  dispose;
+  connecting;
   notificationListeners = /* @__PURE__ */ new Set();
   requestHandler;
-  constructor(options) {
-    const logger = options.logger ?? noopLogger;
-    const transport = options.transport ?? new StdioJsonRpcTransport({
-      command: options.command,
-      args: options.args,
-      ...options.env !== void 0 ? { env: options.env } : {},
-      logger
-    });
-    this.connection = new JsonRpcConnection(
-      transport,
-      options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
-      options.observer,
-      { logger, logContext: { owner: "acp-stdio-transport" } }
-    );
-    this.connection.setNotificationHandler((method, params) => {
-      const normalized = asRecord(params) ?? {};
-      for (const listener of this.notificationListeners) {
-        listener(method, normalized);
-      }
-    });
-    this.connection.setRequestHandler(async (method, params, id) => {
-      if (!this.requestHandler) {
-        throw new Error(`ACP request handler unavailable for ${method}`);
+  /** The `Client` handler the library invokes for agent→client traffic. */
+  buildClient() {
+    const emit = (method, params) => {
+      for (const listener of this.notificationListeners) listener(method, params);
+    };
+    return {
+      requestPermission: async (params) => {
+        if (!this.requestHandler) {
+          throw new Error("ACP request handler unavailable for session/request_permission");
+        }
+        return await this.requestHandler(
+          "session/request_permission",
+          params
+        );
+      },
+      sessionUpdate: async (params) => {
+        emit("session/update", params);
+      },
+      extNotification: async (method, params) => {
+        emit(method, params);
+      },
+      extMethod: async (method, params) => {
+        if (!this.requestHandler) {
+          throw new Error(`ACP request handler unavailable for ${method}`);
+        }
+        return await this.requestHandler(method, params) ?? {};
       }
-      return await this.requestHandler(method, asRecord(params) ?? {}, id);
-    });
+      // No fs/terminal handlers: we don't advertise those client capabilities at
+      // `initialize`, so a conformant agent won't call them.
+    };
+  }
+  async ensureConnected() {
+    if (this.connection) return;
+    this.connecting ??= this.connect();
+    await this.connecting;
   }
   async connect() {
-    await this.connection.connect();
+    const create = this.options.createConnection ?? this.defaultCreateConnection();
+    const handle = create(this.buildClient());
+    this.connection = handle.connection;
+    this.dispose = handle.dispose;
+  }
+  defaultCreateConnection() {
+    const { command, args, env } = this.options;
+    const logger = this.logger;
+    return (client) => {
+      const child = spawn(command, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        ...env !== void 0 ? { env } : {}
+      });
+      child.on("error", (error) => {
+        logger.error("acp agent process error", { command, message: error.message });
+      });
+      child.stderr?.on("data", (chunk) => {
+        const line = chunk.toString("utf8").trimEnd();
+        if (line.length > 0) logger.debug("acp agent stderr", { line });
+      });
+      const toAgentStdin = Writable.toWeb(child.stdin);
+      const fromAgentStdout = Readable.toWeb(child.stdout);
+      const stream = ndJsonStream(toAgentStdin, fromAgentStdout);
+      const connection = new ClientSideConnection(
+        (_agent) => client,
+        stream
+      );
+      return {
+        connection,
+        dispose: () => {
+          try {
+            child.stdin?.end();
+          } catch {
+          }
+          child.kill();
+        }
+      };
+    };
   }
-  async request(method, params, timeoutMs) {
-    await this.connection.connect();
-    return await this.connection.request(method, params, timeoutMs);
+  async request(method, params = {}, _timeoutMs) {
+    await this.ensureConnected();
+    const conn = this.connection;
+    if (!conn) throw new Error("acp connection unavailable");
+    switch (method) {
+      case "initialize":
+        return await conn.initialize(params);
+      case "session/new":
+        return await conn.newSession(params);
+      case "session/load":
+        return await conn.loadSession(params);
+      case "session/prompt":
+        return await conn.prompt(params);
+      case "session/set_mode":
+        return await conn.setSessionMode(params);
+      case "session/set_model":
+        return await conn.setSessionModel(params);
+      case "session/cancel":
+        await conn.cancel(params);
+        return {};
+      case "authenticate":
+        return await conn.authenticate(params);
+      default:
+        return await conn.extMethod(method, params);
+    }
   }
-  async notify(method, params) {
-    await this.connection.connect();
-    await this.connection.notify(method, params);
+  async notify(method, params = {}) {
+    await this.ensureConnected();
+    const conn = this.connection;
+    if (!conn) throw new Error("acp connection unavailable");
+    if (method === "session/cancel") {
+      await conn.cancel(params);
+      return;
+    }
+    await conn.extNotification(method, params);
   }
   async close() {
-    await this.connection.close();
+    try {
+      this.dispose?.();
+    } finally {
+      this.connection = void 0;
+      this.dispose = void 0;
+      this.connecting = void 0;
+    }
   }
   onNotification(listener) {
     this.notificationListeners.add(listener);
@@ -65,9 +154,6 @@ var AcpStdioJsonRpcTransport = class {
     };
   }
 };
-function asRecord(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
-}
 
 // src/acp-client.ts
 import {
@@ -85,7 +171,7 @@ import {
 } from "@pwrdrvr/agent-core";
 
 // src/normalizer/content.ts
-function asRecord2(value) {
+function asRecord(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
 function readString(record, key) {
@@ -122,7 +208,7 @@ function readAcpContentText(value) {
     const parts = value.map((item) => readAcpContentText(item)).filter((item) => Boolean(item));
     return parts.length > 0 ? parts.join("\n") : void 0;
   }
-  const content = asRecord2(value);
+  const content = asRecord(value);
   if (!content) {
     return void 0;
   }
@@ -143,7 +229,7 @@ function readFirstLocationPath(record) {
     return void 0;
   }
   for (const location of locations) {
-    const path5 = readString(asRecord2(location), "path");
+    const path5 = readString(asRecord(location), "path");
     if (path5 && path5.trim()) {
       return path5;
     }
@@ -244,7 +330,7 @@ function toolCallFromUpdate(update, kind, sessionId) {
 }
 function readToolArgs(update) {
   const raw = update.rawInput ?? update.raw_input ?? update.input ?? update.arguments ?? update.args;
-  return asRecord2(raw) ?? (raw === void 0 ? void 0 : raw);
+  return asRecord(raw) ?? (raw === void 0 ? void 0 : raw);
 }
 function readToolContentText(value) {
   return readContentText({ content: value }, "content");
@@ -484,7 +570,7 @@ function readPlanSteps(record) {
     if (typeof step === "string") {
       return [{ step, status: "pending" }];
     }
-    const stepRecord = asRecord2(step);
+    const stepRecord = asRecord(step);
     if (!stepRecord) {
       return [];
     }
@@ -507,7 +593,7 @@ function readPromptText(content) {
 
 // src/normalizer/runtime-capabilities.ts
 function normalizeAcpRuntimeCapabilities(params) {
-  const record = asRecord2(params.value);
+  const record = asRecord(params.value);
   if (!record) {
     return params.initialize;
   }
@@ -589,7 +675,7 @@ function acpSessionRuntimeStateFromUpdate(update, now) {
     return currentModeId ? { currentModeId, updatedAt: now } : void 0;
   }
   if (kind === "config_option_update") {
-    const configOption = asRecord2(update.configOption ?? update.config_option) ?? update;
+    const configOption = asRecord(update.configOption ?? update.config_option) ?? update;
     const id = readString(configOption, "id") ?? readString(configOption, "configOptionId") ?? readString(configOption, "configId");
     const value = readString(configOption, "currentValue") ?? readString(configOption, "value");
     return id && value ? { configValues: { [id]: value }, updatedAt: now } : void 0;
@@ -619,7 +705,7 @@ function readConfigOptions(value) {
     return [];
   }
   return value.flatMap((item) => {
-    const record = asRecord2(item);
+    const record = asRecord(item);
     const id = readString(record, "id") ?? readString(record, "configOptionId") ?? readString(record, "configId");
     if (!record || !id) {
       return [];
@@ -648,7 +734,7 @@ function readConfigOptionValues(value) {
     return [];
   }
   return value.flatMap((item) => {
-    const record = asRecord2(item);
+    const record = asRecord(item);
     const optionValue = readString(record, "value") ?? readString(record, "id") ?? readString(record, "optionId");
     if (!record || !optionValue) {
       return [];
@@ -662,7 +748,7 @@ function readConfigOptionValues(value) {
   });
 }
 function readModes(value) {
-  const record = asRecord2(value);
+  const record = asRecord(value);
   const modes = Array.isArray(record?.availableModes) ? record.availableModes.flatMap(readMode) : [];
   if (modes.length === 0) {
     return void 0;
@@ -673,7 +759,7 @@ function readModes(value) {
   return result;
 }
 function readMode(value) {
-  const record = asRecord2(value);
+  const record = asRecord(value);
   const id = readString(record, "id") ?? readString(record, "modeId");
   if (!record || !id) {
     return [];
@@ -687,7 +773,7 @@ function readMode(value) {
   return [mode];
 }
 function readModels(value) {
-  const record = asRecord2(value);
+  const record = asRecord(value);
   const models = Array.isArray(record?.availableModels) ? record.availableModels.flatMap(readModel) : [];
   if (models.length === 0) {
     return void 0;
@@ -698,7 +784,7 @@ function readModels(value) {
   return result;
 }
 function readModel(value) {
-  const record = asRecord2(value);
+  const record = asRecord(value);
   const id = readString(record, "modelId") ?? readString(record, "id");
   if (!record || !id) {
     return [];
@@ -711,16 +797,16 @@ function readModel(value) {
   return [model];
 }
 function readAgentCapabilities(value, sessionCapabilitiesValue) {
-  const record = asRecord2(value);
-  const sessionCapabilities = asRecord2(sessionCapabilitiesValue);
-  const sessionMeta = asRecord2(sessionCapabilities?._meta);
-  const kimiMeta = asRecord2(sessionMeta?.kimi);
+  const record = asRecord(value);
+  const sessionCapabilities = asRecord(sessionCapabilitiesValue);
+  const sessionMeta = asRecord(sessionCapabilities?._meta);
+  const kimiMeta = asRecord(sessionMeta?.kimi);
   if (!record && !sessionCapabilities) {
     return void 0;
   }
-  const loadSession = readBoolean(record, "loadSession") ?? readBoolean(record, "load_session") ?? readBoolean(asRecord2(record?.session), "load");
-  const close = readBoolean(asRecord2(record?.session), "close");
-  const cancel = readBoolean(asRecord2(record?.session), "cancel");
+  const loadSession = readBoolean(record, "loadSession") ?? readBoolean(record, "load_session") ?? readBoolean(asRecord(record?.session), "load");
+  const close = readBoolean(asRecord(record?.session), "close");
+  const cancel = readBoolean(asRecord(record?.session), "cancel");
   const sessionHistoryReplay = readBoolean(kimiMeta, "sessionHistoryReplay") ?? readBoolean(kimiMeta, "session_history_replay");
   const capabilities = {
     raw: record ?? sessionCapabilities
@@ -738,7 +824,7 @@ function readAgentCapabilities(value, sessionCapabilitiesValue) {
   return capabilities;
 }
 function readAgentInfo(value) {
-  const record = asRecord2(value);
+  const record = asRecord(value);
   if (!record) {
     return void 0;
   }
@@ -960,7 +1046,7 @@ var AcpAgentClient = class {
       cwd,
       mcpServers
     });
-    const record = asRecord3(result);
+    const record = asRecord2(result);
     const protocolSessionId = readString2(record, "sessionId") ?? readString2(record, "session_id");
     if (!protocolSessionId) {
       throw new Error("ACP session/new did not return a session id");
@@ -1106,6 +1192,40 @@ var AcpAgentClient = class {
       });
     }
   }
+  /** Release a thread the host has archived/closed.
+   *
+   *  ACP has NO protocol-level session delete/archive — sessions are
+   *  connection-scoped and the spec offers only `session/cancel` (interrupt).
+   *  So unlike the Codex backend (which sends `thread/archive`), there's no
+   *  remote call to make here. What we MUST do is drop the live session
+   *  LOCALLY: a long-lived pooled client (one process shared across surfaces,
+   *  warmed at startup) would otherwise accumulate a dead `AcpSessionState` for
+   *  every closed chat for the life of the app. Best-effort cancels an
+   *  in-flight turn first so the agent stops working on a thread the user
+   *  closed. Idempotent — no-ops if the session is already gone. A later
+   *  `reopenThread` re-establishes a fresh session under the same threadId, so
+   *  releasing here never blocks resume. */
+  async archiveThread(threadId) {
+    const session = this.sessions.get(threadId);
+    if (session === void 0) return;
+    if (session.turnId !== void 0) {
+      try {
+        if (this.transport.notify) {
+          await this.transport.notify("session/cancel", {
+            sessionId: session.protocolSessionId
+          });
+        } else {
+          await this.transport.request("session/cancel", {
+            sessionId: session.protocolSessionId
+          });
+        }
+      } catch {
+      }
+    }
+    this.sessions.delete(threadId);
+    this.threadIdByProtocolId.delete(session.protocolSessionId);
+    this.logger.debug("acp thread archived (session released locally)", { threadId });
+  }
   async setMode(threadId, modeId) {
     await this.setRuntimeOption(threadId, "mode", modeId, modeId);
   }
@@ -1167,13 +1287,13 @@ var AcpAgentClient = class {
     if (method !== "session/update" && !vendorMethods.includes(method)) {
       return;
     }
-    const record = asRecord3(params);
+    const record = asRecord2(params);
     if (!record) return;
     this.applySessionUpdate(record);
   }
   applySessionUpdate(params) {
     const protocolSessionId = readString2(params, "sessionId") ?? readString2(params, "session_id");
-    const update = asRecord3(params.update);
+    const update = asRecord2(params.update);
     if (!protocolSessionId || !update) {
       return;
     }
@@ -1366,7 +1486,7 @@ var AcpAgentClient = class {
   }
 };
 function buildApprovalRequest(args) {
-  const toolCall = asRecord3(args.params.toolCall) ?? {};
+  const toolCall = asRecord2(args.params.toolCall) ?? {};
   const title = typeof toolCall.title === "string" && toolCall.title.trim() ? toolCall.title.trim() : "ACP tool call";
   const toolCallId = readString2(toolCall, "toolCallId") ?? readString2(toolCall, "tool_call_id");
   const requestId = args.id == null ? toolCallId ?? `acp:${args.now()}` : String(args.id);
@@ -1402,7 +1522,7 @@ function readPermissionOptions(value) {
     return [];
   }
   return value.flatMap((option) => {
-    const record = asRecord3(option);
+    const record = asRecord2(option);
     const optionId = readString2(record, "optionId");
     if (!record || !optionId) {
       return [];
@@ -1477,12 +1597,12 @@ function readString2(record, key) {
   const value = record?.[key];
   return typeof value === "string" ? value : void 0;
 }
-function asRecord3(value) {
+function asRecord2(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
 function readAcpPromptUsage(result) {
-  const meta = asRecord3(asRecord3(result)?._meta);
-  const tokenCount = asRecord3(asRecord3(meta?.quota)?.token_count);
+  const meta = asRecord2(asRecord2(result)?._meta);
+  const tokenCount = asRecord2(asRecord2(meta?.quota)?.token_count);
   if (!tokenCount) return void 0;
   const num = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
   const input = num(tokenCount.input_tokens);
@@ -2250,7 +2370,7 @@ function evaluateAcpDistributionPolicy(distribution, allowlist) {
   };
 }
 function normalizeRegistry(raw) {
-  const record = asRecord4(raw);
+  const record = asRecord3(raw);
   const rawAgents = Array.isArray(record?.agents) ? record.agents : [];
   return rawAgents.flatMap((item) => {
     const agent = normalizeAgent(item);
@@ -2258,7 +2378,7 @@ function normalizeRegistry(raw) {
   });
 }
 function normalizeAgent(raw) {
-  const record = asRecord4(raw);
+  const record = asRecord3(raw);
   if (!record || typeof record.id !== "string" || typeof record.name !== "string") {
     return void 0;
   }
@@ -2291,7 +2411,7 @@ function normalizeAgent(raw) {
   return agent;
 }
 function normalizeDistributions(raw) {
-  const record = asRecord4(raw);
+  const record = asRecord3(raw);
   if (!record) {
     return [];
   }
@@ -2300,7 +2420,7 @@ function normalizeDistributions(raw) {
   if (npx) distributions.push(npx);
   const uvx = normalizePackageDistribution("uvx", record.uvx);
   if (uvx) distributions.push(uvx);
-  const binaryRecord = asRecord4(record.binary);
+  const binaryRecord = asRecord3(record.binary);
   if (binaryRecord) {
     for (const [platform, value] of Object.entries(binaryRecord)) {
       const binary = normalizeBinaryDistribution(platform, value);
@@ -2310,7 +2430,7 @@ function normalizeDistributions(raw) {
   return distributions;
 }
 function normalizePackageDistribution(kind, raw) {
-  const record = asRecord4(raw);
+  const record = asRecord3(raw);
   if (!record || typeof record.package !== "string") {
     return void 0;
   }
@@ -2322,7 +2442,7 @@ function normalizePackageDistribution(kind, raw) {
   };
 }
 function normalizeBinaryDistribution(platform, raw) {
-  const record = asRecord4(raw);
+  const record = asRecord3(raw);
   if (!record || typeof record.archive !== "string" || typeof record.cmd !== "string") {
     return void 0;
   }
@@ -2344,7 +2464,7 @@ function normalizeAuth(raw) {
   if (!raw) {
     return { required: false, methods: [] };
   }
-  const record = asRecord4(raw);
+  const record = asRecord3(raw);
   if (!record) {
     return { required: true, methods: ["unknown"], raw };
   }
@@ -2357,7 +2477,7 @@ function normalizeAuth(raw) {
     raw
   };
 }
-function asRecord4(value) {
+function asRecord3(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
 function stringValue(value) {
@@ -2367,7 +2487,7 @@ function stringArray(value) {
   return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
 function stringRecord(value) {
-  const record = asRecord4(value);
+  const record = asRecord3(value);
   if (!record) {
     return {};
   }
@@ -2382,17 +2502,17 @@ export {
   AcpAgentAllowlist,
   AcpAgentClient,
   AcpAgentClientPool,
+  AcpConnection,
   AcpOneShotClient,
   AcpRegistryService,
   AcpSessionNormalizer,
-  AcpStdioJsonRpcTransport,
   BANNED_ACP_REGISTRY_IDS,
   BUILT_IN_ACP_STRATEGIES,
   DEFAULT_ACP_AGENT_ALLOWLIST,
   acpRuntimeSupportsSessionLoad,
   acpSessionRuntimeStateFromCapabilities,
   acpSessionRuntimeStateFromUpdate,
-  asRecord2 as asRecord,
+  asRecord,
   buildAcpBackendId,
   buildStrategyTable,
   defaultAcpAgentAllowlist,