@pwrdrvr/agent-acp 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -14,7 +14,16 @@ interface AcpJsonRpcTransport {
  *  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). */
+ *  match at runtime).
+ *
+ *  Every entry here MUST exist on the real `ClientSideConnection`. It is
+ *  attached with an `as unknown as` cast (see `createConnection`), so a name
+ *  that is merely plausible type-checks and then throws
+ *  "conn.<name> is not a function" at runtime, on the wire, against a user's
+ *  agent. `setSessionModel` was such an entry: ACP 1.3 has no `session/set_model`
+ *  at all, so every model selection died before it was sent. Anything the SDK
+ *  does not expose as a typed method belongs in `dispatch`'s default arm, which
+ *  sends it verbatim through `request()`. */
 interface AcpAgentConnection {
     initialize(params: Record<string, unknown>): Promise<unknown>;
     newSession(params: Record<string, unknown>): Promise<unknown>;
@@ -22,11 +31,14 @@ interface AcpAgentConnection {
     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>;
     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 +67,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 +79,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). */
@@ -289,7 +309,11 @@ type AcpPromptContentBlock = {
     mimeType: string;
     data: string;
 };
-type AcpRuntimeOptionSource = "mode" | "model" | "configOption";
+type AcpRuntimeOptionSource = "mode" | "model" | "configOption"
+/** A model write that travels as `session/set_config_option` because the
+ *  agent exposes model choice as a config option rather than via the legacy
+ *  top-level `models` capability. See `setModel`. */
+ | "modelConfigOption";
 type AcpAgentClientOptions = {
     /** The transport (real stdio or a fake). */
     transport: AcpJsonRpcTransport;
@@ -377,8 +401,9 @@ declare class AcpAgentClient implements AgentBackend {
      * Public `AgentBackend.startThread`: accepts NEUTRAL `AgentStartThreadOptions`
      * and maps them onto an ACP `session/new`. ACP supports:
      *   • `cwd` → `session/new.cwd`.
-     *   • `model` → applied via `session/set_model` after the session opens, when
-     *     the agent advertises model selection (best-effort; debug-logged if not).
+     *   • `model` → applied after the session opens, by whichever route the agent
+     *     advertises: the `model` config option, or legacy `session/set_model`
+     *     (best-effort; debug-logged if not). See `setModel`.
      *   • `instructions` is NOT injected here — ACP `session/new` has no base-
      *     instructions slot, matching the adapter's existing behavior. A host that
      *     wants system framing sends it as leading turn text.
@@ -468,6 +493,25 @@ declare class AcpAgentClient implements AgentBackend {
      *  releasing here never blocks resume. */
     archiveThread(threadId: string): Promise<void>;
     setMode(threadId: string, modeId: string): Promise<void>;
+    /** Apply a model selection by whichever route the agent actually advertises.
+     *
+     *  ACP 1.3 has NO `session/set_model` — it is absent from `AGENT_METHODS`.
+     *  An agent that offers model choice does it through a config option with
+     *  `category: "model"` (Kimi's `session/new` returns exactly that, and nothing
+     *  under `models`). Some agents still accept `session/set_model` as a vendor
+     *  extension, and the `models.availableModels` shape is still honoured for
+     *  them, but it is not what the protocol defines any more.
+     *
+     *  Two reasons to prefer the config option when the agent offers it. The READ
+     *  path already draws this distinction — `modelIdFromCapabilities` and
+     *  `modelsFromCapabilities` both fall back to the config option — and the two
+     *  disagreeing lets a host list models it cannot then select. And the config
+     *  option's REPLY carries the agent's full refreshed config set, where
+     *  `session/set_model` answers `{}` and refreshes only via an async
+     *  notification. On Kimi the model DETERMINES which thought levels exist —
+     *  `K2.7 Coding` offers only `on`, `K3` offers `low`/`high`/`max` — and
+     *  `applyReasoning` picks from `runtimeCapabilities` on the following
+     *  `startTurn`, so the refresh this write leaves behind is what it reads. */
     setModel(threadId: string, modelId: string): Promise<void>;
     setConfigOption(threadId: string, optionId: string, value: string): Promise<void>;
     close(): Promise<void>;
@@ -707,7 +751,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 +802,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 +953,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);
@@ -116,8 +144,9 @@ var AcpConnection = class {
         return await conn.prompt(params);
       case "session/set_mode":
         return await conn.setSessionMode(params);
-      case "session/set_model":
-        return await conn.setSessionModel(params);
+      // `session/set_model` is deliberately NOT cased here: SDK 1.3 has no
+      // typed `setSessionModel`, so it goes out through the default arm's
+      // generic `request()` for agents still speaking the older method.
       case "session/cancel":
         await conn.cancel(params);
         return {};
@@ -1033,8 +1062,9 @@ var AcpAgentClient = class {
    * Public `AgentBackend.startThread`: accepts NEUTRAL `AgentStartThreadOptions`
    * and maps them onto an ACP `session/new`. ACP supports:
    *   • `cwd` → `session/new.cwd`.
-   *   • `model` → applied via `session/set_model` after the session opens, when
-   *     the agent advertises model selection (best-effort; debug-logged if not).
+   *   • `model` → applied after the session opens, by whichever route the agent
+   *     advertises: the `model` config option, or legacy `session/set_model`
+   *     (best-effort; debug-logged if not). See `setModel`.
    *   • `instructions` is NOT injected here — ACP `session/new` has no base-
    *     instructions slot, matching the adapter's existing behavior. A host that
    *     wants system framing sends it as leading turn text.
@@ -1412,7 +1442,32 @@ var AcpAgentClient = class {
   async setMode(threadId, modeId) {
     await this.setRuntimeOption(threadId, "mode", modeId, modeId);
   }
+  /** Apply a model selection by whichever route the agent actually advertises.
+   *
+   *  ACP 1.3 has NO `session/set_model` — it is absent from `AGENT_METHODS`.
+   *  An agent that offers model choice does it through a config option with
+   *  `category: "model"` (Kimi's `session/new` returns exactly that, and nothing
+   *  under `models`). Some agents still accept `session/set_model` as a vendor
+   *  extension, and the `models.availableModels` shape is still honoured for
+   *  them, but it is not what the protocol defines any more.
+   *
+   *  Two reasons to prefer the config option when the agent offers it. The READ
+   *  path already draws this distinction — `modelIdFromCapabilities` and
+   *  `modelsFromCapabilities` both fall back to the config option — and the two
+   *  disagreeing lets a host list models it cannot then select. And the config
+   *  option's REPLY carries the agent's full refreshed config set, where
+   *  `session/set_model` answers `{}` and refreshes only via an async
+   *  notification. On Kimi the model DETERMINES which thought levels exist —
+   *  `K2.7 Coding` offers only `on`, `K3` offers `low`/`high`/`max` — and
+   *  `applyReasoning` picks from `runtimeCapabilities` on the following
+   *  `startTurn`, so the refresh this write leaves behind is what it reads. */
   async setModel(threadId, modelId) {
+    const advertisesModelsCapability = (this.runtimeCapabilities?.models?.availableModels?.length ?? 0) > 0;
+    const option = modelConfigOption(this.runtimeCapabilities);
+    if (!advertisesModelsCapability && option !== void 0) {
+      await this.setRuntimeOption(threadId, "modelConfigOption", option.id, modelId);
+      return;
+    }
     await this.setRuntimeOption(threadId, "model", modelId, modelId);
   }
   async setConfigOption(threadId, optionId, value) {
@@ -1436,6 +1491,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);
     });
@@ -1567,7 +1624,16 @@ var AcpAgentClient = class {
       value
     );
     const runtimeCapabilities = this.captureRuntimeCapabilities("session-load", result);
-    const requested = source === "configOption" ? { configValues: { [optionId]: value }, updatedAt: this.now() } : source === "mode" ? { currentModeId: value, updatedAt: this.now() } : { currentModelId: value, updatedAt: this.now() };
+    const requested = source === "configOption" ? { configValues: { [optionId]: value }, updatedAt: this.now() } : source === "mode" ? { currentModeId: value, updatedAt: this.now() } : source === "modelConfigOption" ? (
+      // Record BOTH: it IS the config option's value, and it IS the
+      // session's model. A consumer reading `currentModelId` must not
+      // have to know which route the agent happened to expose.
+      {
+        currentModelId: value,
+        configValues: { [optionId]: value },
+        updatedAt: this.now()
+      }
+    ) : { currentModelId: value, updatedAt: this.now() };
     session.runtimeState = mergeAcpRuntimeState(session.runtimeState, requested);
     const effectiveCapabilities = runtimeCapabilities ?? this.runtimeCapabilities;
     if (effectiveCapabilities) {
@@ -1580,7 +1646,7 @@ var AcpAgentClient = class {
     this.emitThreadSettings(session, effectiveCapabilities, session.runtimeState);
   }
   async setRuntimeOptionOnTransport(protocolSessionId, source, optionId, value) {
-    if (source === "configOption") {
+    if (source === "configOption" || source === "modelConfigOption") {
       return await this.transport.request("session/set_config_option", {
         sessionId: protocolSessionId,
         configId: optionId,
@@ -2314,12 +2380,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 +2400,8 @@ async function discoverLocalAcpAgentInstances(options = {}) {
         env,
         listExecutables,
         options.overrides?.[strategy.id],
-        options.includeRejectedCandidates === true
+        options.includeRejectedCandidates === true,
+        probeOptions
       )
     )
   );
@@ -2353,22 +2425,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 +2608,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 +3024,7 @@ function stringRecord(value) {
 }
 export {
   ACP_REGISTRY_URL,
+  ACP_REQUEST_TIMEOUT_MESSAGE_PREFIX,
   AcpAgentAllowlist,
   AcpAgentClient,
   AcpAgentClientPool,
@@ -2904,6 +3035,7 @@ export {
   BANNED_ACP_REGISTRY_IDS,
   BUILT_IN_ACP_STRATEGIES,
   DEFAULT_ACP_AGENT_ALLOWLIST,
+  DEFAULT_ACP_PROBE_TIMEOUT_MS,
   acpRuntimeSupportsHttpMcp,
   acpRuntimeSupportsSessionLoad,
   acpRuntimeSupportsSseMcp,