@wrongstack/acp 0.260.0 → 0.264.0

package/dist/index.d.ts

@@ -1,5 +1,499 @@
-export { A as ACPCancelParams, a as ACPCapabilities, b as ACPChildProcess, c as ACPError, d as ACPImageContent, e as ACPInitializeParams, f as ACPInputSchema, g as ACPMessage, h as ACPNotification, i as ACPPlanContent, j as ACPPlanStep, k as ACPProgressContent, l as ACPRequest, m as ACPResourceContent, n as ACPResponse, o as ACPSessionInfo, p as ACPSessionMode, q as ACPTextContent, r as ACPToolCallRequest, s as ACPToolCallResponse, t as ACPToolDefinition, u as ACPToolList, v as ACPToolResult, w as AgentServerTransport, C as ClientTransport, x as ClientTransportOptions, y as ContentBlock, S as StdioTransport } from './stdio-transport-DoKRVjHz.js';
-export { ACPProtocolHandler, ACPToolsRegistry, WrongStackACPServer, WrongStackACPServerOptions } from './agent.js';
-export { A as ACPSubagentRunnerOptions, a as ACP_AGENT_COMMANDS, T as ToolTranslator, b as ToolTranslatorOptions, m as makeACPSubagentRunner, c as makeACPSubagentRunnerWithStop } from './index-DPMuJGqv.js';
+export { c as ACPCancelParams, d as ACPCapabilities, e as ACPChildProcess, f as ACPError, g as ACPImageContent, h as ACPInitializeParams, i as ACPInputSchema, j as ACPMessage, k as ACPNotification, l as ACPPlanContent, m as ACPPlanStep, n as ACPProgressContent, o as ACPRequest, p as ACPResourceContent, q as ACPResponse, r as ACPSessionInfo, s as ACPSessionMode, t as ACPTextContent, u as ACPToolCallRequest, v as ACPToolCallResponse, w as ACPToolDefinition, a as ACPToolList, b as ACPToolResult, A as AgentServerTransport, C as ClientTransport, x as ClientTransportOptions, y as ContentBlock, S as StdioTransport } from './stdio-transport-CsFr8JzC.js';
+export { A as ACPToolsRegistry } from './tools-registry-BCf8evEG.js';
+import { T as ToolCallUpdateNotification, P as PermissionOption, b as RequestPermissionOutcome, S as StopReason, U as UsageCost, c as PlanEntry } from './wrongstack-acp-agent-Dv-A0bEm.js';
+export { A as ACPProtocolHandler, W as WrongStackACPServer, a as WrongStackACPServerOptions } from './wrongstack-acp-agent-Dv-A0bEm.js';
+import { A as ACPSubagentRunnerOptions } from './index-BvPqJHhm.js';
+export { a as ACP_AGENT_COMMANDS, T as ToolTranslator, b as ToolTranslatorOptions, m as makeACPSubagentRunner, c as makeACPSubagentRunnerWithStop } from './index-BvPqJHhm.js';
 import 'node:events';
 import '@wrongstack/core';
+
+/**
+ * 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: pick the safest-looking allow option if the signal
+ * is not aborted, otherwise report cancelled. Order of preference:
+ *
+ *   1. `allow_always`
+ *   2. `allow_once`
+ *   3. anything else with `optionId` (last resort)
+ *
+ * Real WrongStack permission UIs replace this; the contract is the
+ * `PermissionPolicy` function type, not the implementation.
+ */
+declare const defaultPermissionPolicy: PermissionPolicy;
+
+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;
+}
+interface ACPSessionRunResult {
+    text: string;
+    stopReason: StopReason;
+    hasText: boolean;
+    usage?: {
+        used: number;
+        size: number;
+        cost?: UsageCost | undefined;
+    } | undefined;
+    plan?: PlanEntry[] | undefined;
+}
+type ACPSessionErrorKind = 'spawn_failed' | 'init_failed' | 'protocol_error' | 'session_create_failed' | 'prompt_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 constructor();
+    /**
+     * Spawn the child, run the initialize handshake, install the
+     * message dispatch, and return a ready session.
+     */
+    static start(opts: ACPSessionOptions): Promise<ACPSession>;
+    private initialize;
+    /**
+     * Run one prompt turn. Creates a session if needed, sends the
+     * prompt, streams session/update notifications, and resolves with
+     * the agent's response.
+     *
+     * 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(text: string, signal: AbortSignal): Promise<ACPSessionRunResult>;
+    private createSession;
+    /** Tear down the session and kill the child process. */
+    close(): Promise<void>;
+    private allocId;
+    private sendRequest;
+    private handleMessage;
+    private handleUpdate;
+    private scratch;
+    private accumulatedText;
+    private accumulatedPlan;
+    private accumulatedUsage;
+    private resetScratch;
+    private handlePermissionRequest;
+    private handleFsRequest;
+    private handleTerminalRequest;
+}
+
+/** Vendor classification — used to filter the catalog by family. */
+type ACPAgentVendor = 'anthropic' | 'google' | 'openai' | 'github' | 'community';
+/** How the agent is integrated into ACP. */
+type ACPIntegration = 
+/** Agent ships with a documented ACP entry flag. */
+'native'
+/** Runs through Zed's SDK adapter or similar wrapper. */
+ | 'adapter'
+/** Community-maintained wrapper (e.g. @agentify/cline, bub-acp-server). */
+ | 'community'
+/** Listed by ACP but no public ACP entry yet; may not work. */
+ | 'experimental';
+/** Static metadata for a known agent. */
+interface ACPAgentDescriptor {
+    /** Stable identifier used as the spawn key. Lowercase, hyphenated. */
+    id: string;
+    /** Display name shown in the TUI / WebUI / CLI. */
+    displayName: string;
+    vendor: ACPAgentVendor;
+    /** argv to detect installation. Exits 0 with stdout on success. */
+    probe: {
+        command: string;
+        args?: readonly string[];
+    };
+    /** argv to start the agent in ACP mode. */
+    acp: {
+        command: string;
+        args?: readonly string[];
+        env?: Record<string, string>;
+    };
+    /** Capability hints — used to fail fast when the binary predates ACP. */
+    supports: {
+        loadSession: boolean;
+        promptImages: boolean;
+        terminal: boolean;
+        fs: boolean;
+    };
+    integration: ACPIntegration;
+    /** Documentation URL — shown in `wstack acp list` and the ensemble UI. */
+    docs: string;
+}
+/** A descriptor with its runtime detection result attached. */
+interface DetectedAgent extends ACPAgentDescriptor {
+    installed: boolean;
+    /** Absolute path to the binary, if discovered. */
+    path?: string;
+    /** Captured version string, if `probe` produced one. */
+    version?: string;
+    /**
+     * When `installed: false`, a short reason — typically "binary not
+     * found", "binary predates ACP", or "probe timed out".
+     */
+    reason?: string;
+}
+/** A single probe failure — never thrown, always returned. */
+interface ProbeFailure {
+    ok: false;
+    reason: string;
+    /** Wall-clock duration of the failed probe in ms. */
+    durationMs: number;
+}
+interface ProbeSuccess {
+    ok: true;
+    version: string;
+    path?: string;
+    durationMs: number;
+}
+type ProbeResult = ProbeSuccess | ProbeFailure;
+interface EnsembleRegistryOptions {
+    /** Override the catalog (mostly for tests). */
+    catalog?: readonly ACPAgentDescriptor[];
+    /** Override the probe timeout (ms). */
+    probeTimeoutMs?: number;
+    /** Inject a custom probe function (used by tests). */
+    probeFn?: (descriptor: ACPAgentDescriptor) => Promise<ProbeResult>;
+}
+declare class EnsembleRegistry {
+    private readonly catalog;
+    private readonly timeoutMs;
+    private readonly probe;
+    private cache;
+    constructor(options?: EnsembleRegistryOptions);
+    /** Return the full catalog (no probe), in catalog order. */
+    listAll(): readonly ACPAgentDescriptor[];
+    /**
+     * Probe every catalog entry in parallel and return the detection
+     * results. Results are cached for `PROBE_CACHE_MS`.
+     */
+    list(): Promise<readonly DetectedAgent[]>;
+    /** Probe a single descriptor. Always returns a `DetectedAgent`. */
+    detect(desc: ACPAgentDescriptor): Promise<DetectedAgent>;
+    /** Invalidate the per-process cache. */
+    invalidate(): void;
+    /** Convenience: just the installed agents. */
+    listInstalled(): Promise<readonly DetectedAgent[]>;
+}
+
+/**
+ * Static catalog of ACP-supporting agents known to WrongStack.
+ *
+ * Scope: CLI-spawnable agents only (i.e. agents that can be run as a
+ * subprocess with stdio JSON-RPC, per the ACP v1 spec's local-transport
+ * model). IDE-only or SaaS-only entries from
+ * https://agentclientprotocol.com/get-started/agents are deliberately
+ * omitted — they can't be driven by a SubagentRunner.
+ *
+ * Maintenance
+ * ───────────
+ * This is a static catalog by design. ACP v1 is a moving target: agents
+ * ship ACP support, deprecate it, change invocation flags. Auto-fetching
+ * a live registry sounds appealing but adds a runtime dependency on
+ * network + on whatever schema the ACP team decides on for the Registry
+ * RFD. A typed static file the maintainer refreshes on a known schedule
+ * is more reliable, easier to diff in PRs, and keeps probe failures
+ * attributable to the local machine rather than to a transient registry
+ * outage.
+ *
+ * Each entry tags its `integration` mechanism:
+ *   - `native`       — the agent ships with a documented ACP entry flag.
+ *   - `adapter`      — runs through Zed's SDK adapter or similar wrapper.
+ *   - `community`    — community-maintained wrapper (e.g. `@agentify/cline`,
+ *                      `bub-acp-server`, `pi-acp`).
+ *   - `experimental` — listed by ACP but no public ACP entry yet;
+ *                      entry may not work.
+ *
+ * When the maintainer verifies an entry works, flip `integration` from
+ * `experimental` to `native`/`adapter`/`community` and remove the warning.
+ *
+ * Detection
+ * ─────────
+ * The `EnsembleRegistry` (sibling module) probes each entry's `probe`
+ * argv in parallel via `Promise.allSettled`. A probe that exits 0 with
+ * a non-empty stdout line is considered installed. Probes that time out
+ * or print nothing are treated as not-installed.
+ */
+
+/**
+ * The catalog. Order is significant for the TUI render — most-requested
+ * agents go first. Edit by re-ordering, not by alphabetising.
+ */
+declare const AGENTS_CATALOG: readonly ACPAgentDescriptor[];
+/** O(1) lookup by id. Returns `undefined` for unknown ids. */
+declare function findAgentDescriptor(id: string): ACPAgentDescriptor | undefined;
+
+interface FileServerOptions {
+    /** Absolute path; only files under this root are accessible. */
+    projectRoot: string;
+    /** Per-call timeout, default 30s. */
+    timeoutMs?: number;
+}
+interface ReadFileParams {
+    sessionId: string;
+    path: string;
+}
+interface WriteFileParams {
+    sessionId: string;
+    path: string;
+    content: string;
+}
+type FsErrorCode = 'ENOENT' | 'EACCES' | 'OUTSIDE_ROOT' | 'TIMEOUT' | 'INVALID_PATH';
+/**
+ * Thrown for protocol-level rejections (path outside root, etc.).
+ * The session converts these into JSON-RPC error responses.
+ */
+declare class FsError extends Error {
+    readonly code: FsErrorCode;
+    readonly path: string;
+    constructor(code: FsErrorCode, path: string, message: string);
+}
+declare class FileServer {
+    private readonly root;
+    private readonly timeoutMs;
+    constructor(opts: FileServerOptions);
+    /** Read a text file. Returns the content as a string. */
+    readTextFile(params: ReadFileParams): Promise<{
+        content: string;
+    }>;
+    /** Write a text file. Atomic via write-then-rename. */
+    writeTextFile(params: WriteFileParams): Promise<void>;
+    /**
+     * Resolve a path; throw `FsError('OUTSIDE_ROOT')` if the result is
+     * not under the project root. Symlinks are not followed here — we
+     * operate on the textual path. A future hardening pass can
+     * `fs.realpath` each access to catch symlink escapes.
+     */
+    private resolveInside;
+}
+
+interface TerminalServerOptions {
+    projectRoot: string;
+    /** Hard cap on per-command wall-clock. Default 5 minutes. */
+    commandTimeoutMs?: number;
+    /** Bytes of output to retain per terminal. Default 1 MiB. */
+    outputByteLimit?: number;
+    /** Optional abort signal that kills ALL active terminals. */
+    signal?: AbortSignal;
+}
+declare class TerminalServer {
+    private readonly terminals;
+    private readonly projectRoot;
+    private readonly commandTimeoutMs;
+    private readonly outputByteLimit;
+    private nextId;
+    constructor(opts: TerminalServerOptions);
+    /** Spawn a new terminal. Returns the agent-facing id. */
+    create(params: {
+        sessionId: string;
+        command: string;
+        args?: string[];
+        env?: {
+            name: string;
+            value: string;
+        }[];
+        cwd?: string;
+        outputByteLimit?: number;
+    }): {
+        terminalId: string;
+    };
+    /** Return captured output and (if available) the exit status. */
+    output(terminalId: string): {
+        output: string;
+        truncated: boolean;
+        exitStatus?: {
+            exitCode: number | null;
+            signal: string | null;
+        };
+    };
+    /** Block until the process exits. Resolves with the exit status. */
+    waitForExit(terminalId: string): Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    /** Kill the process but keep the terminal record (agent can still read output). */
+    kill(terminalId: string): void;
+    /** Kill the process if alive and remove the record. */
+    release(terminalId: string): void;
+    /** Kill all active terminals. Used on session close. */
+    releaseAll(): void;
+    private resolveCwd;
+    private buildEnv;
+}
+
+/**
+ * Ensemble runner — fan a single task out to multiple ACP agents in parallel.
+ *
+ * This is the engine behind both:
+ *  - `wstack acp parallel <csv> <task>`  (CLI subcommand)
+ *  - `/ensemble <csv> <task>`            (TUI slash command)
+ *
+ * The CLI wraps `runEnsemble` with a plain-text renderer. The TUI can
+ * call it directly and format the result however it likes (text dump,
+ * per-agent tabbed panels, etc.).
+ *
+ * Design notes
+ * ────────────
+ *  - Skipping is up-front. We probe the registry once, then run only
+ *    the installed agents. This keeps the "no installed agents" path
+ *    cheap (no spawn attempts) and the error message clear.
+ *  - All agents run concurrently via `Promise.allSettled`. A single
+ *    failed agent doesn't kill the others; the call returns once every
+ *    agent has either completed or crashed.
+ *  - Per-agent errors are captured as structured `{kind, message}`
+ *    objects, not thrown. The aggregated result is one `EnsembleResult`
+ *    with per-agent outcomes. Callers can render it as they please.
+ *  - The `signal` option propagates as the parent AbortSignal for each
+ *    `SubagentRunner`. Aborting cancels all in-flight agents.
+ *  - Idempotent cleanup: each agent's `stop()` is called in a
+ *    `finally`, so a throw in the body still tears the child down.
+ */
+
+/**
+ * Per-agent outcome from an ensemble run.
+ * `status === 'skipped'` carries a `reason`; the other statuses carry
+ * either a result or an error envelope.
+ */
+interface EnsembleAgentResult {
+    agentId: string;
+    status: 'success' | 'failed' | 'skipped' | 'cancelled';
+    /** The agent's text result. Present for `status === 'success'`. */
+    result?: string | undefined;
+    /** Structured error. Present for `status === 'failed' | 'cancelled'`. */
+    error?: {
+        kind: string;
+        message: string;
+    } | undefined;
+    /** Why the agent was skipped (not installed, unknown id, etc.). */
+    reason?: string | undefined;
+    /** Wall-clock time spent on this agent. 0 for skipped. */
+    durationMs: number;
+    /** Agent-reported iteration count (1 per ACP turn). */
+    iterations: number;
+    /** Agent-reported tool call count (currently 0 for ACP). */
+    toolCalls: number;
+}
+/** Aggregate result of one ensemble run. */
+interface EnsembleResult {
+    /** The task that was dispatched. */
+    task: string;
+    /** Agent ids as the user provided them, after dedup. */
+    requested: string[];
+    /** Per-agent outcomes, in the order they were requested. */
+    results: EnsembleAgentResult[];
+    /** Roll-up of the per-agent statuses. */
+    summary: {
+        succeeded: number;
+        failed: number;
+        skipped: number;
+        cancelled: number;
+    };
+    /** Total wall-clock time of the run (longest agent). */
+    totalDurationMs: number;
+}
+/** Sync command resolver: id → command, or null if unknown. */
+type EnsembleCmdResolver = (id: string) => ACPSubagentRunnerOptions | null;
+interface EnsembleRunnerOptions {
+    /**
+     * Comma-separated agent ids. Whitespace, empty entries, and
+     * duplicates are filtered out. Order is preserved.
+     */
+    agentIds: string;
+    /** The task description forwarded verbatim to each agent. */
+    task: string;
+    /**
+     * Per-agent hard timeout in ms. Defaults to 5 minutes; the
+     * `SubagentRunner` itself layers a turn-level timeout under this.
+     */
+    timeoutMs?: number;
+    /**
+     * Override the registry used for the install probe. Defaults to
+     * `new EnsembleRegistry()`. Useful for tests.
+     */
+    registry?: EnsembleRegistry;
+    /**
+     * Override the command resolver. Defaults to
+     * `defaultEnsembleCmdResolver` (legacy `ACP_AGENT_COMMANDS` map
+     * with catalog fallback via `findAgentDescriptor`). Useful for
+     * tests that don't want the real `makeACPSubagentRunnerWithStop`.
+     */
+    resolveCmd?: EnsembleCmdResolver;
+    /**
+     * Cancellation signal. Aborting stops all in-flight agents via the
+     * `SubagentRunContext.signal` they receive.
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Default command resolver. Checks the legacy `ACP_AGENT_COMMANDS` map
+ * first, then falls back to the 12-entry catalog. Returns `null` for
+ * ids that aren't in either source.
+ */
+declare const defaultEnsembleCmdResolver: EnsembleCmdResolver;
+/**
+ * Fan a task out to multiple ACP agents concurrently.
+ *
+ * Returns once every requested agent has either completed, failed, or
+ * been cancelled. Skipped agents (not installed, unknown id) are
+ * reported with `status: 'skipped'` and don't block the result.
+ *
+ * The function is a pure orchestrator — it does NOT render output. The
+ * caller decides how to format the `EnsembleResult`.
+ */
+declare function runEnsemble(opts: EnsembleRunnerOptions): Promise<EnsembleResult>;
+/**
+ * Render an `EnsembleResult` as a plain-text block. Useful as the
+ * default for the CLI; the TUI can call this or build a richer view.
+ *
+ * The format mirrors the output the `wstack acp parallel` subcommand
+ * emits, so existing scripts that parse the CLI's output keep working.
+ */
+declare function renderEnsembleText(result: EnsembleResult): string;
+
+export { type ACPAgentDescriptor, type ACPAgentVendor, type ACPIntegration, ACPSession, ACPSessionError, type ACPSessionErrorKind, type ACPSessionOptions, type ACPSessionRunResult, ACPSubagentRunnerOptions, AGENTS_CATALOG, type DetectedAgent, type EnsembleAgentResult, type EnsembleCmdResolver, EnsembleRegistry, type EnsembleRegistryOptions, type EnsembleResult, type EnsembleRunnerOptions, FileServer, type FileServerOptions, FsError, type FsErrorCode, type PermissionPolicy, type PermissionRequest, type ReadFileParams, TerminalServer, type TerminalServerOptions, type WriteFileParams, defaultEnsembleCmdResolver, defaultPermissionPolicy, findAgentDescriptor, renderEnsembleText, runEnsemble };