@wrongstack/acp 0.273.1 → 0.275.0

package/dist/acp-subagent-runner-BAlo23L-.d.ts

@@ -0,0 +1,644 @@
+import { SubagentRunner } from '@wrongstack/core';
+import { A as ACPClientTransport, b as ACPMessage, g as ToolCallUpdateNotification, P as PermissionOption, R as RequestPermissionOutcome, T as ToolKind, h as ToolCallStatus, f as PlanEntry, U as UsageCost, i as AnySessionUpdate, j as AgentCapabilities, k as AuthMethod, l as SessionId, M as McpServer, m as SessionInfo, C as ContentBlock, e as StopReason } from './acp-v1-BxskPsdo.js';
+
+/**
+ * WebSocketClientTransport — remote ACP transport for `ACPSession`.
+ *
+ * Connects to a remote ACP agent over a WebSocket (cloud-hosted agents,
+ * separate-process agents reachable over the network). Each WebSocket
+ * message carries exactly one JSON-RPC 2.0 object — message boundaries
+ * are preserved by the WS framing, so (unlike stdio) no newline delimiter
+ * is needed.
+ *
+ * Uses the Node ≥ 22 built-in global `WebSocket` (undici), so there is no
+ * runtime dependency. Per-connection auth headers are not supported by the
+ * WHATWG WebSocket client; authenticate over the protocol instead
+ * (`ACPSession.authenticate`) or embed a token in the URL query string.
+ *
+ * Spec: https://agentclientprotocol.com/protocol/v1/overview (remote transport)
+ */
+
+interface WebSocketClientTransportOptions {
+    /** ws:// or wss:// URL of the remote ACP agent. */
+    url: string;
+    /** Optional WebSocket subprotocols. */
+    protocols?: string | string[] | undefined;
+    /** How long to wait for the socket to open. Default 30s. */
+    handshakeTimeoutMs?: number | undefined;
+}
+declare class WebSocketClientTransport implements ACPClientTransport {
+    private ws;
+    private readonly handlers;
+    private closed;
+    private readonly opts;
+    constructor(opts: WebSocketClientTransportOptions);
+    start(): Promise<void>;
+    send(msg: ACPMessage): Promise<void>;
+    onMessage(handler: (msg: ACPMessage) => void): () => void;
+    stop(): void;
+    private onData;
+    private dispatch;
+}
+
+/**
+ * Permission policy for ACP v1 client sessions.
+ *
+ * ACP agents can call `session/request_permission` to ask the user
+ * before executing a tool call. The client is expected to surface
+ * the question, get a decision, and respond. This module is the seam
+ * where WrongStack-specific permission UI can plug in; for v1 we ship
+ * a minimal default that auto-approves the first `allow_once` option
+ * (or `allow_always` if present) and rejects on abort.
+ */
+
+/** A single permission decision request. */
+interface PermissionRequest {
+    toolCall: ToolCallUpdateNotification;
+    options: readonly PermissionOption[];
+    signal: AbortSignal;
+}
+/** A permission policy decides how to respond to a request. */
+type PermissionPolicy = (req: PermissionRequest) => Promise<RequestPermissionOutcome>;
+/**
+ * Default policy: auto-approve the least-standing allow option.
+ *
+ * ⚠️ This auto-approves EVERY tool call, including file writes and shell
+ * commands. It exists so non-interactive contexts (CLI `acp spawn`,
+ * the Director fan-out) work without a human in the loop. Interactive
+ * surfaces (TUI/WebUI) MUST inject a policy that surfaces the request to
+ * the user — pass `permissionPolicy` to `ACPSession` / the subagent runner.
+ * For untrusted agents prefer {@link readOnlyPermissionPolicy}.
+ */
+declare const defaultPermissionPolicy: PermissionPolicy;
+/**
+ * Safe-by-default policy: auto-approve only side-effect-free tool calls
+ * (read/search/fetch/think); reject anything that would write files or
+ * run commands. Use this when driving an untrusted external agent and no
+ * interactive surface is available to ask the user.
+ */
+declare const readOnlyPermissionPolicy: PermissionPolicy;
+/**
+ * Build a policy from a yes/no decision function. The decider receives the
+ * tool call (title + kind + rawInput) and returns whether to allow it.
+ * This is the seam an interactive host (TUI/WebUI confirm prompt, trust
+ * store, exec-allowlist) plugs into.
+ */
+declare function makePermissionPolicy(decide: (req: PermissionRequest) => boolean | Promise<boolean>): PermissionPolicy;
+
+/**
+ * ACPSession — v1-correct ACP client.
+ *
+ * Owns one child process running an ACP-supporting agent (Claude Code,
+ * Gemini CLI, Codex CLI, etc.) and translates the wire protocol into
+ * a `SubagentRunner`-shaped surface for the rest of WrongStack.
+ *
+ * Spec: https://agentclientprotocol.com/protocol/v1/overview
+ * Design: see ./acp-session.design.md in this directory.
+ */
+
+interface ACPSessionOptions {
+    command: string;
+    args?: readonly string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+    role?: string | undefined;
+    /** Sandbox root for fs/* and terminal/* methods. */
+    projectRoot: string;
+    /** Hard timeout for one prompt turn. Default 5 minutes. */
+    timeoutMs?: number | undefined;
+    /** Override the permission policy. */
+    permissionPolicy?: PermissionPolicy | undefined;
+    /** Per-fs-call timeout, default 30s. */
+    fsTimeoutMs?: number | undefined;
+    /** Per-terminal command timeout, default 5 minutes. */
+    terminalTimeoutMs?: number | undefined;
+    /** Per-terminal output byte cap, default 1 MiB. */
+    terminalOutputByteLimit?: number | undefined;
+    /**
+     * MCP server configs to include in session/new, session/load, and
+     * session/resume. The agent will connect to these servers to provide
+     * additional tools.
+     *
+     * Stdio servers are always sent. HTTP/SSE servers are only sent if
+     * the agent advertises the corresponding mcpCapabilities.
+     */
+    mcpServers?: McpServer[] | undefined;
+}
+/**
+ * A captured file diff emitted by the agent during a turn (via a tool
+ * call's `diff` content). `oldText: null` means the file was created.
+ */
+interface ACPCapturedDiff {
+    path: string;
+    oldText: string | null;
+    newText: string;
+}
+/**
+ * A captured tool call the agent ran during a turn. We collapse the
+ * `tool_call` + subsequent `tool_call_update` notifications for the same
+ * `toolCallId` into one record carrying its latest status.
+ */
+interface ACPCapturedToolCall {
+    toolCallId: string;
+    title: string;
+    kind?: ToolKind | undefined;
+    status: ToolCallStatus;
+    /** Terminal/command output or text content surfaced by the tool, if any. */
+    rawOutput?: Record<string, unknown> | undefined;
+    rawInput?: Record<string, unknown> | undefined;
+}
+interface ACPSessionRunResult {
+    text: string;
+    stopReason: StopReason;
+    hasText: boolean;
+    usage?: {
+        used: number;
+        size: number;
+        cost?: UsageCost | undefined;
+    } | undefined;
+    plan?: PlanEntry[] | undefined;
+    /** Tool calls the agent ran this turn (deduped by toolCallId). */
+    toolCalls: ACPCapturedToolCall[];
+    /** File diffs the agent produced this turn. */
+    diffs: ACPCapturedDiff[];
+    /** Agent "thinking" text emitted via thought_chunk, concatenated. */
+    thoughts: string;
+}
+/**
+ * Live progress callback. Invoked for every `session/update` notification
+ * the agent streams during a `prompt()` turn, in arrival order, BEFORE the
+ * turn resolves. Lets the host render tool activity / text deltas / diffs
+ * as they happen instead of waiting for the buffered final result.
+ *
+ * The raw `update` (the discriminated `session/update` payload) is passed
+ * through verbatim so callers can switch on `update.sessionUpdate`.
+ */
+type ACPProgressHandler = (event: ACPProgressEvent) => void;
+type ACPProgressEvent = {
+    type: 'message';
+    text: string;
+} | {
+    type: 'thought';
+    text: string;
+} | {
+    type: 'tool_call';
+    toolCall: ACPCapturedToolCall;
+} | {
+    type: 'tool_call_update';
+    toolCall: ACPCapturedToolCall;
+} | {
+    type: 'diff';
+    diff: ACPCapturedDiff;
+} | {
+    type: 'plan';
+    entries: PlanEntry[];
+} | {
+    type: 'usage';
+    usage: {
+        used: number;
+        size: number;
+        cost?: UsageCost | undefined;
+    };
+} | {
+    type: 'raw';
+    update: AnySessionUpdate;
+};
+type ACPSessionErrorKind = 'spawn_failed' | 'init_failed' | 'protocol_error' | 'session_create_failed' | 'prompt_failed' | 'auth_failed' | 'logout_failed' | 'aborted' | 'closed' | 'agent_died' | 'unsupported_capability';
+declare class ACPSessionError extends Error {
+    readonly kind: ACPSessionErrorKind;
+    readonly cause: unknown;
+    constructor(kind: ACPSessionErrorKind, message: string, cause?: unknown);
+}
+declare class ACPSession {
+    private readonly transport;
+    private readonly fileServer;
+    private readonly terminalServer;
+    private readonly permissionPolicy;
+    private readonly timeoutMs;
+    private readonly opts;
+    private state;
+    private sessionId;
+    /** Pending outbound requests (initialize, session/new, session/prompt, etc). */
+    private readonly pending;
+    private nextId;
+    /** True after close() has been called. */
+    private closed;
+    private agentCapabilities;
+    private agentInfo;
+    private authMethods;
+    /** Protocol version negotiated with the agent during initialize. */
+    private negotiatedVersion;
+    private constructor();
+    /** Agent capabilities advertised during initialize. */
+    getCapabilities(): AgentCapabilities;
+    /** Authentication methods advertised by the agent. */
+    getAuthMethods(): AuthMethod[];
+    /** Agent info (name, title, version) from initialize. */
+    getAgentInfo(): {
+        name: string;
+        title?: string | undefined;
+        version: string;
+    } | null;
+    /** Whether the agent requires authentication (has auth methods). */
+    requiresAuth(): boolean;
+    /** Current session id, if one exists. */
+    getSessionId(): SessionId | null;
+    /** Protocol version negotiated during initialize. */
+    getNegotiatedVersion(): number;
+    /**
+     * Spawn the child, run the initialize handshake, install the
+     * message dispatch, and return a ready session.
+     */
+    static start(opts: ACPSessionOptions): Promise<ACPSession>;
+    /**
+     * Connect to a REMOTE ACP agent over a WebSocket instead of spawning a
+     * local subprocess. `opts.command` is ignored for the wire (a label is
+     * still useful for `role`); everything else (projectRoot sandbox for
+     * fs/terminal, timeouts, permission policy, MCP servers) applies the same.
+     */
+    static connectWebSocket(wsOpts: WebSocketClientTransportOptions, opts: ACPSessionOptions): Promise<ACPSession>;
+    /**
+     * Connect using a caller-supplied transport. Lets advanced callers plug
+     * in their own wire (SDK streams, in-process pipes, test doubles).
+     */
+    static connect(transport: ACPClientTransport, opts: ACPSessionOptions): Promise<ACPSession>;
+    /** Shared connect path: start the transport, install dispatch, handshake. */
+    private static attach;
+    private initialize;
+    /**
+     * Authenticate with the agent using one of the advertised auth methods.
+     * Call this AFTER start() and BEFORE any session/new call.
+     *
+     * Throws ACPSessionError('auth_failed') if the agent rejects the
+     * authentication or if the methodId is not in the advertised list.
+     */
+    authenticate(methodId: string): Promise<void>;
+    /**
+     * Log out from the current authenticated session.
+     * Only callable if the agent advertises `auth.logout` capability.
+     */
+    logout(): Promise<void>;
+    /**
+     * Load an existing session. The agent replays the conversation history
+     * via session/update notifications before responding.
+     *
+     * Only works if the agent advertises `loadSession` capability.
+     *
+     * @param sessionId - The session to load
+     * @param mcpServers - Optional MCP servers (defaults to options.mcpServers)
+     * @param cwd - Optional working directory (defaults to options.cwd or projectRoot)
+     */
+    loadSession(sessionId: SessionId, mcpServers?: McpServer[], cwd?: string): Promise<void>;
+    /**
+     * Resume an existing session without replaying history.
+     *
+     * Only works if the agent advertises `sessionCapabilities.resume`.
+     *
+     * @param sessionId - The session to resume
+     * @param mcpServers - Optional MCP servers (defaults to options.mcpServers)
+     * @param cwd - Optional working directory (defaults to options.cwd or projectRoot)
+     */
+    resumeSession(sessionId: SessionId, mcpServers?: McpServer[], cwd?: string): Promise<void>;
+    /**
+     * List existing sessions known to the agent.
+     *
+     * Only works if the agent advertises `sessionCapabilities.list`.
+     */
+    listSessions(cursor?: string, cwd?: string): Promise<{
+        sessions: SessionInfo[];
+        nextCursor?: string | undefined;
+    }>;
+    /**
+     * Delete a session from the agent's session list.
+     *
+     * Only works if the agent advertises `sessionCapabilities.delete`.
+     */
+    deleteSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Fork a session — create a new session from an existing one.
+     */
+    forkSession(sourceSessionId: SessionId, cwd?: string, mcpServers?: McpServer[]): Promise<SessionId>;
+    /**
+     * Set the active mode for a session.
+     */
+    setMode(sessionId: SessionId, modeId: string): Promise<void>;
+    /**
+     * Set a configuration option for a session.
+     */
+    setConfigOption(sessionId: SessionId, configId: string, value: string): Promise<void>;
+    /**
+     * List available providers and the current provider.
+     */
+    listProviders(): Promise<{
+        providers: unknown[];
+        currentProviderId: string | null;
+    }>;
+    /**
+     * Send an MCP message to the agent for routing.
+     */
+    mcpMessage(connectionId: string, message: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Set the active provider for the agent.
+     */
+    setProvider(providerId: string, config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Disable the current provider.
+     */
+    disableProvider(): Promise<void>;
+    /**
+     * Run one prompt turn. Creates a session if needed, sends the
+     * prompt, streams session/update notifications, and resolves with
+     * the agent's response.
+     *
+     * @param blocks - Content blocks to send. Use `textContent()` for plain
+     *   text, or include ImageContent/AudioContent if the agent's
+     *   `promptCapabilities` allow it.
+     * @param signal - AbortSignal for cancellation.
+     *
+     * Cancellation: if `signal` aborts mid-prompt, we send
+     * `session/cancel` (a notification per spec) and keep accepting
+     * updates until the agent returns with `stopReason: 'cancelled'`.
+     * The result is the same shape as a normal turn, with
+     * `stopReason === 'cancelled'`.
+     */
+    prompt(blocks: ContentBlock[], signal: AbortSignal, onProgress?: ACPProgressHandler): Promise<ACPSessionRunResult>;
+    private createSession;
+    /**
+     * Close the current session gracefully (if the agent supports it).
+     *
+     * Sends `session/close` JSON-RPC request, then clears the local
+     * session id. Best-effort — errors are swallowed so the caller can
+     * always proceed to transport teardown.
+     */
+    private closeSession;
+    /** Tear down the session and kill the child process. */
+    close(): Promise<void>;
+    /**
+     * Filter MCP servers according to agent capabilities.
+     * - Stdio servers are always included.
+     * - HTTP servers are only included if agent supports mcpCapabilities.http.
+     * - SSE servers are only included if agent supports mcpCapabilities.sse.
+     */
+    private filterMcpServers;
+    private allocId;
+    private sendRequest;
+    /**
+     * Send a JSON-RPC 2.0 success response to an agent-initiated request.
+     *
+     * Per JSON-RPC 2.0 (and the official ACP SDK's message router) a Response
+     * object MUST carry `jsonrpc: "2.0"` and MUST NOT carry a `method` field —
+     * the SDK classifies any object with a `method` key as a Request and drops
+     * it as a response, so an agent's `fs/*`, `terminal/*`, or
+     * `session/request_permission` callback would hang forever. The legacy
+     * `ACPMessage` type predates v1 (requires `method`, lacks `jsonrpc`), so we
+     * build the correct wire object and cast at the boundary.
+     */
+    private sendResult;
+    /** Send a JSON-RPC 2.0 error response (no `method` field, per spec). */
+    private sendErrorResponse;
+    private handleMessage;
+    private handleUpdate;
+    /**
+     * Fold a `tool_call` / `tool_call_update` notification into the scratch
+     * tool-call map (deduped by toolCallId), extract any `diff` content into
+     * the diffs list, and emit live progress.
+     */
+    private captureToolCall;
+    private emitProgress;
+    /** Live progress handler installed for the duration of a `prompt()` turn. */
+    private progressHandler;
+    private scratch;
+    private resetScratch;
+    private handlePermissionRequest;
+    private handleFsRequest;
+    private handleTerminalRequest;
+}
+/**
+ * Create a text ContentBlock. Convenience helper for callers of
+ * `session.prompt()`.
+ */
+declare function textContent(text: string): ContentBlock;
+/**
+ * Create an image ContentBlock. Only send this if the agent's
+ * `promptCapabilities.image` is `true` (check via
+ * `session.getCapabilities().promptCapabilities?.image`).
+ */
+declare function imageContent(mimeType: string, data: string): ContentBlock;
+/**
+ * Create an audio ContentBlock. Only send this if the agent's
+ * `promptCapabilities.audio` is `true` (check via
+ * `session.getCapabilities().promptCapabilities?.audio`).
+ */
+declare function audioContent(mimeType: string, data: string): ContentBlock;
+
+/**
+ * ACPSubagentRunner — `SubagentRunner` implementation for DIR-1.
+ *
+ * Wraps an external ACP-supporting agent (Claude Code, Gemini CLI, Codex
+ * CLI, Cline, Goose, OpenHands, etc.) as a WrongStack subagent. The
+ * external agent runs its own agent loop; we send it a task via the ACP
+ * v1 protocol and return the result.
+ *
+ * v1 spec: https://agentclientprotocol.com/protocol/v1/overview
+ *
+ * Connected to the Director / MultiAgentCoordinator via the
+ * `SubagentRunner` interface (same shape as `AgentSubagentRunner`).
+ */
+
+interface ACPSubagentRunnerOptions {
+    /** How to spawn the external agent. */
+    command: string;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+    /** Subagent role label — surfaced in errors and used for logging. */
+    role?: string | undefined;
+    /**
+     * Hard wall-clock cap for one prompt turn. Defaults to 5 minutes.
+     * Overrides `SubagentRunContext.budget.limits.timeoutMs` if both are set.
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * Filesystem sandbox root. Defaults to `options.cwd` (when set) or
+     * the process's current working directory. All `fs/read_text_file` /
+     * `fs/write_text_file` calls are bounded to this root.
+     */
+    projectRoot?: string | undefined;
+    /**
+     * Live progress callback. Forwarded to `ACPSession.prompt` so the host
+     * can render the external agent's tool calls / diffs / text as they
+     * stream, instead of waiting for the buffered final result.
+     */
+    onProgress?: ACPProgressHandler | undefined;
+    /**
+     * Permission policy for the external agent's `session/request_permission`
+     * calls. Defaults to the session's own default. Inject the host's
+     * confirm/trust UI here so an external agent's file writes / commands
+     * are surfaced to a human instead of silently auto-approved.
+     */
+    permissionPolicy?: PermissionPolicy | undefined;
+    /**
+     * MCP servers to expose to the external agent (passed through
+     * `session/new` / `session/load`). Stdio servers are always sent;
+     * HTTP/SSE are filtered by the agent's advertised capabilities.
+     */
+    mcpServers?: McpServer[] | undefined;
+    /**
+     * When true, the underlying `ACPSession` is kept open across multiple
+     * runner invocations (multi-turn conversation — the external agent
+     * keeps its context). The caller MUST call `stop()` to tear it down.
+     * Defaults to false (one process per task).
+     */
+    persistent?: boolean | undefined;
+}
+/**
+ * Static catalog of agent ids → spawn options.
+ *
+ * The CLI and the host's `buildACPRunner` look up entries by id. The
+ * canonical, multi-source catalog is `packages/acp/src/registry/agents.catalog.ts`
+ * (the 12-entry static catalog introduced in commit 4ad287b4). This
+ * map stays for backward compatibility with existing call sites that
+ * import it directly; new code should prefer the registry.
+ */
+declare const ACP_AGENT_COMMANDS: Record<string, ACPSubagentRunnerOptions>;
+/**
+ * Build a one-shot `SubagentRunner` for a single agent invocation. Each
+ * call to the returned function spawns a fresh child process, runs one
+ * prompt turn, and tears everything down. The cost is ~1 second of
+ * process-startup per call; for long-lived sessions (multi-turn
+ * conversations), use `makeACPSubagentRunnerWithStop` and call `stop()`
+ * explicitly.
+ */
+declare function makeACPSubagentRunner(options: ACPSubagentRunnerOptions): Promise<SubagentRunner>;
+/**
+ * Build a long-lived `SubagentRunner` plus an explicit `stop()` for
+ * teardown. The caller is responsible for calling `stop()` when done
+ * (or when the host's signal fires). Useful for the `wstack acp spawn`
+ * CLI command, which holds the child open for the duration of a user
+ * task and tears down on SIGINT.
+ */
+declare function makeACPSubagentRunnerWithStop(options: ACPSubagentRunnerOptions): Promise<{
+    runner: SubagentRunner;
+    stop: () => void | Promise<void>;
+}>;
+
+/**
+ * Per-agent ACP invocation overrides, sourced from the user's
+ * `~/.wrongstack/config.json` (`config.acp.agents`). Lets a user point an
+ * agent id at the correct ACP entry — e.g. the Zed Claude-Code adapter —
+ * without a code change. NEVER honoured from in-project config (it is an
+ * arbitrary-command exec surface); see `config-loader.ts`.
+ */
+type AcpAgentCommandOverrides = Record<string, {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}>;
+/** A synced-registry catalog keyed by registry id (from `fetchAcpRegistry`). */
+type AcpLiveCatalog = Record<string, {
+    command: string;
+    args?: readonly string[];
+    env?: Record<string, string>;
+}>;
+/**
+ * Map our stable, human-friendly catalog ids to the official registry's ids,
+ * so a live-synced registry (keyed by registry id) still resolves when the
+ * user types our id. Our id is preferred in the UI; the alias is the bridge.
+ */
+declare const REGISTRY_ID_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Resolve an agent id to its spawn command. Precedence:
+ *   1. user override (`config.acp.agents[id]`)
+ *   2. the bundled static `AGENTS_CATALOG` (curated LOCAL-binary invocations)
+ *   3. live synced registry (`fetchAcpRegistry` → cache), by id or alias
+ *   4. legacy `ACP_AGENT_COMMANDS` map (last resort, kept for back-compat)
+ * Returns `null` for an id present in none of them.
+ *
+ * Why catalog BEFORE the live registry: our goal is to drive the user's
+ * already-installed, logged-in CLI. The catalog hand-curates the LOCAL-binary
+ * ACP entry for each popular agent (`gemini --acp`, `opencode acp`, …), which
+ * preserves the agent's own login and starts instantly. The official registry,
+ * by contrast, encodes "run a fresh copy" invocations — pinned `npx <pkg>@ver`
+ * downloads (no local login, slow first run) and platform binaries like
+ * `opencode.exe` that may not match a shim on PATH. So the registry is the
+ * source for the long tail of agents the catalog doesn't cover, NOT an
+ * override of the curated 12. Users force a specific command via the override.
+ */
+declare function resolveAcpAgentCommand(id: string, overrides?: AcpAgentCommandOverrides, live?: AcpLiveCatalog): ACPSubagentRunnerOptions | null;
+interface RunOneAcpTaskOptions {
+    command: string;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    /** Agent id / role label, surfaced in errors + the synthetic task id. */
+    role?: string | undefined;
+    /** The task description forwarded verbatim to the agent. */
+    task: string;
+    cwd?: string | undefined;
+    projectRoot?: string | undefined;
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+    onProgress?: ACPProgressHandler | undefined;
+    permissionPolicy?: PermissionPolicy | undefined;
+}
+interface RunOneAcpTaskResult {
+    result: string;
+    iterations: number;
+    toolCalls: number;
+}
+/**
+ * Run a single task on one ACP agent and return its result. Spawns a fresh
+ * process, runs one prompt turn, and tears everything down. Throws a
+ * structured `SubagentError` on failure (spawn/init/prompt). This is the
+ * shared engine behind `wstack acp spawn` and `/acp <id> <task>`.
+ */
+declare function runOneAcpTask(opts: RunOneAcpTaskOptions): Promise<RunOneAcpTaskResult>;
+interface AcpProbeResult {
+    id: string;
+    ok: boolean;
+    ms: number;
+    agentInfo?: {
+        name: string;
+        title?: string | undefined;
+        version: string;
+    } | undefined;
+    error?: string | undefined;
+}
+/**
+ * Empirically test whether an agent actually speaks ACP on this machine:
+ * spawn it, run the `initialize` handshake, and close. `ok: true` means the
+ * agent answered `initialize` within `timeoutMs` (default 8s) — the truth,
+ * regardless of what the static catalog guesses. A bare CLI that drops into
+ * an interactive prompt fails here (init times out) instead of hanging a
+ * real turn.
+ */
+declare function probeAcpAgent(idOrCmd: string | ACPSubagentRunnerOptions, opts?: {
+    timeoutMs?: number | undefined;
+    projectRoot?: string | undefined;
+    overrides?: AcpAgentCommandOverrides | undefined;
+    live?: AcpLiveCatalog | undefined;
+}): Promise<AcpProbeResult>;
+interface ProbeAcpAgentsOptions {
+    agentIds: string[];
+    resolveCmd: (id: string) => ACPSubagentRunnerOptions | null;
+    projectRoot?: string | undefined;
+    /** Max agents probed at once. Default 4. Keeps concurrent first-run `npx`
+     *  downloads from starving local agents' stdout past their timeout. */
+    concurrency?: number | undefined;
+    /** Per-agent handshake timeout for LOCAL binary commands. Default 20s. */
+    timeoutMs?: number | undefined;
+    /** Per-agent timeout for `npx`/`uvx` commands (first run downloads the
+     *  package, which is slow). Default 90s. */
+    packageTimeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+    onProgress?: ((id: string, result: AcpProbeResult) => void) | undefined;
+}
+/**
+ * Probe many agents with BOUNDED concurrency. Unbounded `Promise.all` over the
+ * full set spawns every agent at once — and a few concurrent `npx` downloads
+ * peg the machine hard enough that even already-installed local agents miss
+ * their handshake window. Bounding the fan-out (and giving npx/uvx a longer
+ * timeout) is what makes a mixed install probe reliably.
+ */
+declare function probeAcpAgents(opts: ProbeAcpAgentsOptions): Promise<AcpProbeResult[]>;
+
+export { type ACPCapturedDiff as A, type AcpLiveCatalog as B, type ProbeAcpAgentsOptions as C, REGISTRY_ID_ALIASES as D, probeAcpAgents as E, type PermissionPolicy as P, type RunOneAcpTaskOptions as R, WebSocketClientTransport as W, type ACPCapturedToolCall as a, type ACPProgressEvent as b, type ACPProgressHandler as c, ACPSession as d, ACPSessionError as e, type ACPSessionErrorKind as f, type ACPSessionOptions as g, type ACPSessionRunResult as h, type ACPSubagentRunnerOptions as i, ACP_AGENT_COMMANDS as j, type AcpAgentCommandOverrides as k, type AcpProbeResult as l, type PermissionRequest as m, type RunOneAcpTaskResult as n, type WebSocketClientTransportOptions as o, audioContent as p, defaultPermissionPolicy as q, imageContent as r, makeACPSubagentRunner as s, makeACPSubagentRunnerWithStop as t, makePermissionPolicy as u, probeAcpAgent as v, readOnlyPermissionPolicy as w, resolveAcpAgentCommand as x, runOneAcpTask as y, textContent as z };