@pwrdrvr/agent-acp 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -27,6 +27,10 @@ interface AcpAgentConnection {
     request(method: string, params: Record<string, unknown>): Promise<unknown>;
     notify(method: string, params: Record<string, unknown>): Promise<void>;
 }
+/** Prefix on the rejection when a request outlived its budget. Lets a caller
+ *  tell "the agent did not answer in time" apart from "the agent answered with
+ *  an error" — the two want different recovery (retry / restart vs. surface). */
+declare const ACP_REQUEST_TIMEOUT_MESSAGE_PREFIX = "acp request timed out";
 /** Built connection + a teardown handle (kills the child / closes streams). */
 type AcpAgentConnectionHandle = {
     connection: AcpAgentConnection;
@@ -55,7 +59,8 @@ declare class AcpConnection implements AcpJsonRpcTransport {
     private ensureConnected;
     private connect;
     private defaultCreateConnection;
-    request(method: string, params?: Record<string, unknown>, _timeoutMs?: number): Promise<unknown>;
+    request(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    private dispatch;
     notify(method: string, params?: Record<string, unknown>): Promise<void>;
     close(): Promise<void>;
     onNotification(listener: (method: string, params: Record<string, unknown>) => void): () => void;
@@ -66,7 +71,14 @@ type LocalAcpProbeResult = {
     stdout?: string | Buffer;
     stderr?: string | Buffer;
 };
-type LocalAcpAgentProbe = (command: string, args: string[]) => Promise<LocalAcpProbeResult>;
+type LocalAcpProbeOptions = {
+    /** Budget for this probe spawn. An injected probe should honor it so a slow
+     *  CLI is reported as "did not answer in time", not as "not installed". */
+    timeoutMs?: number | undefined;
+    /** Fires when discovery is abandoned mid-probe. */
+    signal?: AbortSignal | undefined;
+};
+type LocalAcpAgentProbe = (command: string, args: string[], options?: LocalAcpProbeOptions) => Promise<LocalAcpProbeResult>;
 /** How a strategy decides it is installed + ACP-capable on this machine. */
 type AcpDiscoveryProbe = {
     /** Args that print a version (probed first; failure = not installed). */
@@ -707,7 +719,10 @@ type RejectedAcpAgentInstance = {
     /** Parsed from successful `--version` output when available. */
     version?: string;
     source: AcpAgentInstanceSource;
-    reason: "version-probe-failed" | "acp-probe-failed" | "acp-help-mismatch";
+    /** `probe-timed-out` means the CLI did not answer within the probe budget —
+     *  UNLIKE the other reasons it is not a verdict on the CLI, and a host may
+     *  re-probe on a larger `probeTimeoutMs` instead of reporting it unusable. */
+    reason: "version-probe-failed" | "acp-probe-failed" | "acp-help-mismatch" | "probe-timed-out";
 };
 /** Every installed instance of one agent found on this machine. */
 type DiscoveredAcpAgentGroup = {
@@ -755,7 +770,23 @@ type LocalAcpDiscoveryOptions = {
     /** Include candidates known to exist but rejected by a discovery probe.
      *  Defaults false to preserve the legacy installed-only result. */
     includeRejectedCandidates?: boolean;
+    /** Budget for ONE probe spawn (the default probe only — an injected `probe`
+     *  owns its own timing). Defaults to `DEFAULT_ACP_PROBE_TIMEOUT_MS`. */
+    probeTimeoutMs?: number;
+    /** Abandon discovery in flight (re-triggered discovery, app quitting).
+     *  Already-probed groups are still returned. */
+    signal?: AbortSignal;
 };
+/**
+ * Budget for one ACP discovery probe spawn, in ms.
+ *
+ * Unchanged from the value this module has always used. Kept lower than
+ * codex-discovery's version-probe budget on purpose: `discoverStrategyInstances`
+ * walks its candidates SERIALLY, so the worst case here is (candidates x
+ * budget) rather than a single budget. Hosts that scan machines with many
+ * installed copies can raise it knowingly via `probeTimeoutMs`.
+ */
+declare const DEFAULT_ACP_PROBE_TIMEOUT_MS = 5000;
 /**
  * Discover every installed instance of each agent (all `PATH` matches +
  * fallbacks + override that pass the probe), grouped per strategy. Groups with
@@ -890,4 +921,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 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 AcpHttpMcpServerConfig, type AcpJsonRpcTransport, type AcpLoadThreadOptions, type AcpMcpKeyValue, type AcpMcpKeyValueCollection, type AcpMcpServerConfig, type AcpMcpServerWireConfig, 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 AcpRuntimeMcpCapabilities, type AcpRuntimeMode, type AcpRuntimeModel, type AcpRuntimeModels, type AcpRuntimeModes, type AcpRuntimeOptionSource, AcpSessionNormalizer, type AcpSessionRuntimeState, type AcpSpawnSpec, type AcpSseMcpServerConfig, type AcpStartThreadOptions, type AcpStartTurnOptions, type AcpStdioMcpServerConfig, 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, type RejectedAcpAgentInstance, acpRuntimeSupportsHttpMcp, acpRuntimeSupportsSessionLoad, acpRuntimeSupportsSseMcp, acpSessionRuntimeStateFromCapabilities, acpSessionRuntimeStateFromUpdate, asRecord, buildAcpBackendId, buildStrategyTable, defaultAcpAgentAllowlist, defaultQuirks, discoverLocalAcpAgentInstances, discoverLocalAcpAgents, evaluateAcpDistributionPolicy, geminiStrategy, grokStrategy, isBannedAcpRegistryId, kimiStrategy, mergeAcpRuntimeState, modeLabelFor, modelConfigOption, modelIdFromCapabilities, modelsFromCapabilities, normalizeAcpMcpServerConfig, normalizeAcpMcpServerConfigs, normalizeAcpRuntimeCapabilities, normalizeRegistry, qwenStrategy, readAcpContentText, readBoolean, readContentText, readFirstLocationPath, readFirstString, readKind, readNonEmptyString, readNumber, readPromptText, readString, readToolCallId, readToolContentText, readToolOutput, readUpdateText, reasoningValueForThoughtLevel, strategyByBackendId, strategyById, toolCallFromUpdate, wellKnownAgentBinDirs };
+export { ACP_REGISTRY_URL, ACP_REQUEST_TIMEOUT_MESSAGE_PREFIX, 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 AcpHttpMcpServerConfig, type AcpJsonRpcTransport, type AcpLoadThreadOptions, type AcpMcpKeyValue, type AcpMcpKeyValueCollection, type AcpMcpServerConfig, type AcpMcpServerWireConfig, 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 AcpRuntimeMcpCapabilities, type AcpRuntimeMode, type AcpRuntimeModel, type AcpRuntimeModels, type AcpRuntimeModes, type AcpRuntimeOptionSource, AcpSessionNormalizer, type AcpSessionRuntimeState, type AcpSpawnSpec, type AcpSseMcpServerConfig, type AcpStartThreadOptions, type AcpStartTurnOptions, type AcpStdioMcpServerConfig, type AcpTitleHandler, type AcpVerificationStatus, BANNED_ACP_REGISTRY_IDS, BUILT_IN_ACP_STRATEGIES, DEFAULT_ACP_AGENT_ALLOWLIST, DEFAULT_ACP_PROBE_TIMEOUT_MS, type DiscoveredAcpAgent, type DiscoveredAcpAgentGroup, type DiscoveredAcpAgentInstance, type LocalAcpAgentProbe, type LocalAcpDiscoveryOptions, type LocalAcpProbeOptions, type LocalAcpProbeResult, type RejectedAcpAgentInstance, acpRuntimeSupportsHttpMcp, acpRuntimeSupportsSessionLoad, acpRuntimeSupportsSseMcp, acpSessionRuntimeStateFromCapabilities, acpSessionRuntimeStateFromUpdate, asRecord, buildAcpBackendId, buildStrategyTable, defaultAcpAgentAllowlist, defaultQuirks, discoverLocalAcpAgentInstances, discoverLocalAcpAgents, evaluateAcpDistributionPolicy, geminiStrategy, grokStrategy, isBannedAcpRegistryId, kimiStrategy, mergeAcpRuntimeState, modeLabelFor, modelConfigOption, modelIdFromCapabilities, modelsFromCapabilities, normalizeAcpMcpServerConfig, normalizeAcpMcpServerConfigs, normalizeAcpRuntimeCapabilities, normalizeRegistry, qwenStrategy, readAcpContentText, readBoolean, readContentText, readFirstLocationPath, readFirstString, readKind, readNonEmptyString, readNumber, readPromptText, readString, readToolCallId, readToolContentText, readToolOutput, readUpdateText, reasoningValueForThoughtLevel, strategyByBackendId, strategyById, toolCallFromUpdate, wellKnownAgentBinDirs };

package/dist/index.js

@@ -10,6 +10,27 @@ import {
   createCommandInvocation,
   prependCommandDirToPath
 } from "@pwrdrvr/agent-transport";
+var ACP_REQUEST_TIMEOUT_MESSAGE_PREFIX = "acp request timed out";
+function withAcpRequestTimeout(method, timeoutMs, run) {
+  if (timeoutMs === void 0 || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return run();
+  }
+  const budget = Math.max(1, Math.floor(timeoutMs));
+  const call = run();
+  void call.catch(() => void 0);
+  let timer;
+  const expiry = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(
+        new Error(`${ACP_REQUEST_TIMEOUT_MESSAGE_PREFIX} after ${budget}ms: ${method}`)
+      ),
+      budget
+    );
+  });
+  return Promise.race([call, expiry]).finally(() => {
+    if (timer !== void 0) clearTimeout(timer);
+  });
+}
 var AcpConnection = class {
   constructor(options) {
     this.options = options;
@@ -101,10 +122,17 @@ var AcpConnection = class {
       };
     };
   }
-  async request(method, params = {}, _timeoutMs) {
+  async request(method, params = {}, timeoutMs) {
     await this.ensureConnected();
     const conn = this.connection;
     if (!conn) throw new Error("acp connection unavailable");
+    return await withAcpRequestTimeout(
+      method,
+      timeoutMs,
+      () => this.dispatch(conn, method, params)
+    );
+  }
+  async dispatch(conn, method, params) {
     switch (method) {
       case "initialize":
         return await conn.initialize(params);
@@ -1436,6 +1464,8 @@ var AcpAgentClient = class {
   }
   async initialize() {
     if (this.initialized) return;
+    this.unsubscribeNotification?.();
+    this.unsubscribeRequest?.();
     this.unsubscribeNotification = this.transport.onNotification((method, params) => {
       this.handleNotification(method, params);
     });
@@ -2314,12 +2344,17 @@ import {
   prependCommandDirToPath as prependCommandDirToPath2
 } from "@pwrdrvr/agent-transport";
 var execFile = promisify(execFileCallback);
+var DEFAULT_ACP_PROBE_TIMEOUT_MS = 5e3;
 async function discoverLocalAcpAgentInstances(options = {}) {
   const strategies = options.strategies ?? BUILT_IN_ACP_STRATEGIES;
   const env = options.env ?? process.env;
   const probe = options.probe ?? makeDefaultProbe(env);
   const listExecutables = options.listExecutables ?? defaultListExecutables;
   const now = options.now ?? Date.now;
+  const probeOptions = {
+    timeoutMs: options.probeTimeoutMs ?? DEFAULT_ACP_PROBE_TIMEOUT_MS,
+    signal: options.signal
+  };
   const groups = await Promise.all(
     strategies.map(
       (strategy) => discoverStrategyInstances(
@@ -2329,7 +2364,8 @@ async function discoverLocalAcpAgentInstances(options = {}) {
         env,
         listExecutables,
         options.overrides?.[strategy.id],
-        options.includeRejectedCandidates === true
+        options.includeRejectedCandidates === true,
+        probeOptions
       )
     )
   );
@@ -2353,22 +2389,27 @@ async function discoverLocalAcpAgents(options = {}) {
     return [agent];
   });
 }
-async function discoverStrategyInstances(strategy, probe, now, env, listExecutables, override, includeRejectedCandidates = false) {
+async function discoverStrategyInstances(strategy, probe, now, env, listExecutables, override, includeRejectedCandidates = false, probeOptions = {}) {
   const candidates = candidateCommands(strategy, env, listExecutables, override);
   const instances = [];
   const rejectedInstances = [];
   for (const candidate of candidates) {
-    const [versionResult, helpResult] = await Promise.all([
-      runProbe(probe, candidate.command, strategy.discoveryProbe.versionArgs),
-      runProbe(probe, candidate.command, strategy.discoveryProbe.helpArgs)
+    if (probeOptions.signal?.aborted) break;
+    const [versionAttempt, helpAttempt] = await Promise.all([
+      runProbe(probe, candidate.command, strategy.discoveryProbe.versionArgs, probeOptions),
+      runProbe(probe, candidate.command, strategy.discoveryProbe.helpArgs, probeOptions)
     ]);
+    if (probeOptions.signal?.aborted) break;
+    const versionResult = versionAttempt.ok ? versionAttempt.result : void 0;
+    const helpResult = helpAttempt.ok ? helpAttempt.result : void 0;
     const version = versionResult ? parseCliVersion(resultText(versionResult)) : void 0;
     if (!versionResult || !helpResult) {
-      if (includeRejectedCandidates && candidate.detected) {
+      const timedOut = !versionAttempt.ok && versionAttempt.timedOut || !helpAttempt.ok && helpAttempt.timedOut;
+      if (candidate.detected && (timedOut || includeRejectedCandidates)) {
         const rejected = {
           command: candidate.command,
           source: candidate.source,
-          reason: versionResult ? "acp-probe-failed" : "version-probe-failed"
+          reason: timedOut ? "probe-timed-out" : versionResult ? "acp-probe-failed" : "version-probe-failed"
         };
         if (version !== void 0) rejected.version = version;
         rejectedInstances.push(rejected);
@@ -2531,25 +2572,78 @@ function ensureArgs(args, ensure) {
   }
   return result;
 }
+var AcpProbeTimeoutError = class extends Error {
+  constructor(command, timeoutMs) {
+    super(`acp probe did not answer within ${timeoutMs}ms: ${command}`);
+    this.name = "AcpProbeTimeoutError";
+  }
+};
+function isProbeTimeout(error) {
+  if (error instanceof AcpProbeTimeoutError) return true;
+  const name = error?.name;
+  return error?.killed === true || name === "AbortError" || name === "TimeoutError";
+}
+function normalizeProbeTimeoutMs(timeoutMs) {
+  if (timeoutMs === void 0 || !Number.isFinite(timeoutMs)) {
+    return DEFAULT_ACP_PROBE_TIMEOUT_MS;
+  }
+  return Math.max(1, Math.floor(timeoutMs));
+}
 function makeDefaultProbe(env) {
-  return async (command, args) => {
+  return async (command, args, options = {}) => {
+    const timeoutMs = normalizeProbeTimeoutMs(options.timeoutMs);
     const launchEnv = prependCommandDirToPath2(command, env);
     const invocation = createCommandInvocation2({ command, args, env: launchEnv });
-    return await execFile(invocation.command, invocation.args, {
-      timeout: 5e3,
-      maxBuffer: 1024 * 1024,
-      // Prepend the candidate's own dir so a node-script CLI (e.g. an nvm-
-      // installed `qwen`) finds its sibling `node` during the probe.
-      env: launchEnv,
-      windowsVerbatimArguments: invocation.windowsVerbatimArguments
+    const controller = new AbortController();
+    let timedOut = false;
+    const onAbort = () => controller.abort();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    const expired = new Promise((resolve) => {
+      controller.signal.addEventListener("abort", () => resolve("expired"), {
+        once: true
+      });
     });
+    try {
+      const execution = execFile(invocation.command, invocation.args, {
+        timeout: timeoutMs,
+        signal: controller.signal,
+        maxBuffer: 1024 * 1024,
+        // A Windows `.cmd` shim runs through `cmd.exe`; without this every
+        // discovery pass flashes console windows over the host app.
+        windowsHide: true,
+        // Prepend the candidate's own dir so a node-script CLI (e.g. an nvm-
+        // installed `qwen`) finds its sibling `node` during the probe.
+        env: launchEnv,
+        windowsVerbatimArguments: invocation.windowsVerbatimArguments
+      }).then(
+        (result) => ({ ok: true, result }),
+        (error) => ({ ok: false, error })
+      );
+      const settled = await Promise.race([execution, expired]);
+      if (settled === "expired") {
+        if (timedOut) throw new AcpProbeTimeoutError(command, timeoutMs);
+        throw new Error(`acp probe aborted: ${command}`);
+      }
+      if (!settled.ok) {
+        if (timedOut) throw new AcpProbeTimeoutError(command, timeoutMs);
+        throw settled.error;
+      }
+      return settled.result;
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+    }
   };
 }
-async function runProbe(probe, command, args) {
+async function runProbe(probe, command, args, options) {
   try {
-    return await probe(command, args);
-  } catch {
-    return void 0;
+    return { ok: true, result: await probe(command, args, options) };
+  } catch (error) {
+    return { ok: false, timedOut: isProbeTimeout(error) };
   }
 }
 function resultText(result) {
@@ -2894,6 +2988,7 @@ function stringRecord(value) {
 }
 export {
   ACP_REGISTRY_URL,
+  ACP_REQUEST_TIMEOUT_MESSAGE_PREFIX,
   AcpAgentAllowlist,
   AcpAgentClient,
   AcpAgentClientPool,
@@ -2904,6 +2999,7 @@ export {
   BANNED_ACP_REGISTRY_IDS,
   BUILT_IN_ACP_STRATEGIES,
   DEFAULT_ACP_AGENT_ALLOWLIST,
+  DEFAULT_ACP_PROBE_TIMEOUT_MS,
   acpRuntimeSupportsHttpMcp,
   acpRuntimeSupportsSessionLoad,
   acpRuntimeSupportsSseMcp,