@pwrdrvr/agent-acp 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -315,6 +315,11 @@ declare class AcpAgentClient implements AgentBackend {
         /** Built ONLY when a re-establish actually happens (skipped for a live
          *  session), so the host doesn't rebuild the system prompt every turn. */
         buildInstructions?: () => string;
+        /** Per-thread MCP servers for THIS session. Lets ONE shared client serve
+         *  surfaces with different tool sets (library vs sizzle): each surface
+         *  passes its own servers, so its threads spawn its tools — overriding the
+         *  client-level default. */
+        mcpServers?: AcpMcpServerConfig[];
     }): Promise<void>;
     /**
      * Mint a thread id WITHOUT spawning the agent or opening a session. The
@@ -326,6 +331,11 @@ declare class AcpAgentClient implements AgentBackend {
      * turn). The host id is a random UUID since there's no session GUID yet.
      */
     createDeferredThread(_options?: AgentStartThreadOptions): Promise<AgentBackendStartThreadResult>;
+    /** Warm the agent: spawn the process + run the `initialize` handshake WITHOUT
+     *  opening a session, so the first thread/turn doesn't pay the multi-second
+     *  spawn. Idempotent. Used by `AcpAgentClientPool` to hold a configured agent
+     *  ready from app startup. */
+    connect(): Promise<void>;
     /** Shared `session/new` + session registration. Mints a new thread id unless
      *  `bindThreadId` is given (resume), in which case the new ACP session is
      *  bound to that existing host thread id. */
@@ -356,6 +366,10 @@ declare class AcpAgentClient implements AgentBackend {
     private handleNotification;
     private applySessionUpdate;
     private handleAcpRequest;
+    /** Every MCP server name this client knows about — the client-level default
+     *  plus the per-thread servers of every live session. Used to auto-approve a
+     *  configured MCP tool regardless of which session's permission request it is. */
+    private knownMcpServerNames;
     private handlePermissionRequest;
     private setRuntimeOption;
     private setRuntimeOptionOnTransport;
@@ -375,6 +389,37 @@ declare class AcpAgentClient implements AgentBackend {
     supportsSessionLoad(): boolean;
 }
 
+type AcpAgentClientFactory = () => AcpAgentClient;
+type AcpAgentClientPoolOptions = {
+    /** Max time to wait for a client to warm (spawn + `initialize`) before an
+     *  `acquire` rejects. Default 30s. */
+    warmTimeoutMs?: number;
+    logger?: Logger;
+};
+declare class AcpAgentClientPool {
+    private readonly entries;
+    private readonly warmTimeoutMs;
+    private readonly logger;
+    constructor(options?: AcpAgentClientPoolOptions);
+    /**
+     * Return the shared, warmed client for `key`, creating it via `factory` if it
+     * doesn't exist. Concurrent acquires for the same key share ONE spawn — they
+     * receive the same in-flight promise, which resolves when the agent is ready
+     * or rejects if warm-up fails / times out. A failed warm-up evicts the entry
+     * so a later acquire retries with a fresh client.
+     */
+    acquire(key: string, factory: AcpAgentClientFactory): Promise<AcpAgentClient>;
+    /** Fire-and-forget warm-up for app startup. Errors are logged, not thrown. */
+    warm(key: string, factory: AcpAgentClientFactory): void;
+    /** Whether a (warming or warm) entry exists for `key`. */
+    has(key: string): boolean;
+    /** Close + evict ONE key (e.g. its config changed). Safe if absent. */
+    release(key: string): Promise<void>;
+    /** Close + evict EVERY entry (app quit). */
+    closeAll(): Promise<void>;
+    private warmWithTimeout;
+}
+
 type AcpOneShotClientOptions = {
     /** Connected (or lazily-connecting) ACP stdio transport for the agent. */
     transport: AcpJsonRpcTransport;
@@ -706,4 +751,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 AcpAgentClientOptions, 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 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 };

package/dist/index.js

@@ -912,7 +912,8 @@ var AcpAgentClient = class {
     const instructions = options.buildInstructions?.();
     await this.establishSession({
       bindThreadId: options.threadId,
-      ...instructions !== void 0 ? { instructions } : {}
+      ...instructions !== void 0 ? { instructions } : {},
+      ...options.mcpServers !== void 0 ? { mcpServers: options.mcpServers } : {}
     });
   }
   /**
@@ -930,6 +931,13 @@ var AcpAgentClient = class {
     out.modelProvider = this.strategy.id;
     return out;
   }
+  /** Warm the agent: spawn the process + run the `initialize` handshake WITHOUT
+   *  opening a session, so the first thread/turn doesn't pay the multi-second
+   *  spawn. Idempotent. Used by `AcpAgentClientPool` to hold a configured agent
+   *  ready from app startup. */
+  async connect() {
+    await this.initialize();
+  }
   /** Shared `session/new` + session registration. Mints a new thread id unless
    *  `bindThreadId` is given (resume), in which case the new ACP session is
    *  bound to that existing host thread id. */
@@ -967,7 +975,11 @@ var AcpAgentClient = class {
       turnId: void 0,
       runtimeState: void 0,
       pendingTurn: void 0,
-      pendingInstructions: options.instructions
+      pendingInstructions: options.instructions,
+      // Remember the MCP servers attached to THIS session so its tools can be
+      // auto-approved even when the (pooled, shared) client has no client-level
+      // `mcpServers` default.
+      mcpServerNames: (options.mcpServers ?? this.defaultMcpServers).map((server) => server.name)
     };
     this.sessions.set(threadId, session);
     this.threadIdByProtocolId.set(protocolSessionId, threadId);
@@ -1209,14 +1221,21 @@ var AcpAgentClient = class {
     }
     throw new Error(`Unsupported ACP request: ${method}`);
   }
+  /** Every MCP server name this client knows about — the client-level default
+   *  plus the per-thread servers of every live session. Used to auto-approve a
+   *  configured MCP tool regardless of which session's permission request it is. */
+  knownMcpServerNames() {
+    const names = new Set(this.defaultMcpServers.map((server) => server.name));
+    for (const session of this.sessions.values()) {
+      for (const name of session.mcpServerNames) names.add(name);
+    }
+    return [...names];
+  }
   async handlePermissionRequest(params, id) {
     const protocolSessionId = readString2(params, "sessionId") ?? readString2(params, "session_id");
     const threadId = protocolSessionId ? this.threadIdByProtocolId.get(protocolSessionId) : void 0;
     const options = readPermissionOptions(params.options);
-    if (this.autoApproveConfiguredMcpTools && permissionTargetsConfiguredMcpServer(
-      params,
-      this.defaultMcpServers.map((server) => server.name)
-    )) {
+    if (this.autoApproveConfiguredMcpTools && permissionTargetsConfiguredMcpServer(params, this.knownMcpServerNames())) {
       return autoApprovePermissionOutcome(options);
     }
     const handler = this.approvalHandler;
@@ -1497,9 +1516,90 @@ function readAcpPromptUsage(result) {
   return usage;
 }
 
+// src/acp-agent-client-pool.ts
+import { noopLogger as noopLogger3 } from "@pwrdrvr/agent-core";
+function errorMessage2(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+var AcpAgentClientPool = class {
+  entries = /* @__PURE__ */ new Map();
+  warmTimeoutMs;
+  logger;
+  constructor(options = {}) {
+    this.warmTimeoutMs = options.warmTimeoutMs ?? 3e4;
+    this.logger = options.logger ?? noopLogger3;
+  }
+  /**
+   * Return the shared, warmed client for `key`, creating it via `factory` if it
+   * doesn't exist. Concurrent acquires for the same key share ONE spawn — they
+   * receive the same in-flight promise, which resolves when the agent is ready
+   * or rejects if warm-up fails / times out. A failed warm-up evicts the entry
+   * so a later acquire retries with a fresh client.
+   */
+  async acquire(key, factory) {
+    const existing = this.entries.get(key);
+    if (existing !== void 0) return existing.ready;
+    const client = factory();
+    const ready = this.warmWithTimeout(key, client);
+    this.entries.set(key, { client, ready });
+    return ready;
+  }
+  /** Fire-and-forget warm-up for app startup. Errors are logged, not thrown. */
+  warm(key, factory) {
+    void this.acquire(key, factory).catch((cause) => {
+      this.logger.warn?.("acp pool: background warm-up failed", {
+        key,
+        message: errorMessage2(cause)
+      });
+    });
+  }
+  /** Whether a (warming or warm) entry exists for `key`. */
+  has(key) {
+    return this.entries.has(key);
+  }
+  /** Close + evict ONE key (e.g. its config changed). Safe if absent. */
+  async release(key) {
+    const entry = this.entries.get(key);
+    if (entry === void 0) return;
+    this.entries.delete(key);
+    entry.ready.catch(() => void 0);
+    await entry.client.close().catch(() => void 0);
+  }
+  /** Close + evict EVERY entry (app quit). */
+  async closeAll() {
+    const entries = [...this.entries.values()];
+    this.entries.clear();
+    for (const entry of entries) entry.ready.catch(() => void 0);
+    await Promise.allSettled(entries.map((entry) => entry.client.close()));
+  }
+  async warmWithTimeout(key, client) {
+    let timer;
+    try {
+      await Promise.race([
+        client.connect(),
+        new Promise((_, reject) => {
+          timer = setTimeout(
+            () => reject(
+              new Error(`ACP agent "${key}" warm-up timed out after ${this.warmTimeoutMs}ms`)
+            ),
+            this.warmTimeoutMs
+          );
+        })
+      ]);
+      return client;
+    } catch (cause) {
+      if (this.entries.get(key)?.client === client) this.entries.delete(key);
+      await client.close().catch(() => void 0);
+      throw cause;
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
+};
+
 // src/acp-oneshot-client.ts
 import {
-  noopLogger as noopLogger3
+  noopLogger as noopLogger4
 } from "@pwrdrvr/agent-core";
 var AcpOneShotClient = class {
   client;
@@ -1510,7 +1610,7 @@ var AcpOneShotClient = class {
   queue = Promise.resolve();
   constructor(options) {
     this.strategy = options.strategy;
-    const logger = options.logger ?? noopLogger3;
+    const logger = options.logger ?? noopLogger4;
     this.client = new AcpAgentClient({
       transport: options.transport,
       strategy: options.strategy,
@@ -2299,6 +2399,7 @@ export {
   ACP_REGISTRY_URL,
   AcpAgentAllowlist,
   AcpAgentClient,
+  AcpAgentClientPool,
   AcpOneShotClient,
   AcpRegistryService,
   AcpSessionNormalizer,