@wrongstack/acp 0.273.1 → 0.275.0

package/dist/server-agent-turn-C3U0lhA-.d.ts

@@ -0,0 +1,163 @@
+import { d as SessionState, g as RunTurnApi, R as RunTurn, b as RunTurnResult } from './wrongstack-acp-agent-nzrqmJnc.js';
+import { Agent } from '@wrongstack/core';
+
+/** A persisted conversation turn (user/agent message chunk) for replay. */
+interface PersistedHistoryUpdate {
+    sessionUpdate: string;
+    content: unknown;
+}
+/** A persisted session: metadata + replayable conversation history. */
+interface PersistedSession extends Partial<SessionState> {
+    history?: PersistedHistoryUpdate[] | undefined;
+}
+interface SessionStoreOptions {
+    /** Directory to store session files. Defaults to a temp dir. */
+    dir?: string | undefined;
+}
+declare class ACPSessionStore {
+    private readonly dir;
+    /**
+     * Memoized result of the first successful `init()`. Saved sessions
+     * are the hot path — calling `mkdir(..., {recursive:true})` on every
+     * turn adds an avoidable syscall to the per-prompt persistence flow.
+     * Cleared automatically if the directory disappears between calls.
+     */
+    private initialized;
+    constructor(opts?: SessionStoreOptions);
+    /** Ensure the store directory exists. Memoized — only mkdirs once. */
+    init(): Promise<void>;
+    /**
+     * Persist a session state (and optionally its conversation history) to
+     * disk. Returns the session id. `history` enables cross-restart
+     * `session/load` replay.
+     */
+    save(state: SessionState, history?: PersistedHistoryUpdate[]): Promise<string>;
+    /** Load a persisted session (metadata + history) from disk, or null. */
+    load(sessionId: string): Promise<PersistedSession | null>;
+    /** List all persisted sessions. */
+    list(): Promise<Array<{
+        id: string;
+        updatedAt: string;
+    }>>;
+    /** Sidecar path that stores `{id, updatedAt}` for every saved session. */
+    private indexPath;
+    /** Read the sidecar index. Returns `null` when missing or unreadable. */
+    private readIndex;
+    /** Atomically replace the sidecar index with the supplied entries. */
+    private writeIndex;
+    /** Update one entry in the index, adding it if missing. Best-effort. */
+    private updateIndex;
+    /** Delete a session file. */
+    delete(sessionId: string): Promise<void>;
+    /** Get the store directory path. */
+    getDirectory(): string;
+}
+
+/**
+ * ACPServerAgentTurn — `RunTurn` adapter for the v1 server side.
+ *
+ * Wires the ACP v1 server (`ACPProtocolHandler`) to a core `Agent`.
+ * Each session gets its own `Agent` instance (per spec: sessions are
+ * isolated; sharing agents across sessions would defeat isolation).
+ * The agent is created lazily on the first `session/prompt` and
+ * torn down when the server is closed or the session is removed.
+ *
+ * The adapter:
+ *  - converts the ACP `ContentBlock[]` prompt into a single string
+ *    (concatenating text blocks; non-text blocks are recorded as a
+ *    note in the prompt — future work can route images / audio to
+ *    the appropriate provider)
+ *  - calls `agent.run(prompt, {signal})` to drive the core loop
+ *  - captures the agent's text result and emits it as one or more
+ *    `agent_message_chunk` notifications
+ *  - maps the agent's stop semantics to a v1 `StopReason`
+ *
+ * Streaming: the core `Agent` API is not currently token-streamed
+ * through this surface (its `run()` returns a final `RunResult`).
+ * v1 clients expect text deltas, but most implementations batch
+ * them — a single chunk per turn is acceptable. A future
+ * enhancement can use the Agent's `Renderer` interface to capture
+ * deltas as they're written, then forward them as multiple chunks.
+ *
+ * Scope: the adapter is deliberately minimal. It does NOT:
+ *  - model the full conversation history across turns (the v1 spec
+ *    leaves this to the agent; on the next prompt we re-feed the
+ *    latest user message and the agent handles its own history)
+ *  - use the agent's tool registry, permission policy, or
+ *    extensions (this adapter is the lowest-fidelity integration;
+ *    a future PR can wire a richer session-aware agent)
+ *  - stream deltas token-by-token (see "Streaming" above)
+ *
+ * Cancellation: the parent `AbortSignal` propagates through
+ * `agent.run({signal})` and the underlying provider call observes
+ * it. On abort, the adapter maps the resulting `AbortError` to
+ * `{stopReason: 'cancelled'}`.
+ */
+
+interface ACPServerAgentTurnOptions {
+    /**
+     * Factory that creates a fresh `Agent` for a given session.
+     * Called once per session on the first `session/prompt` turn.
+     * The factory must isolate each agent — sharing one agent
+     * across sessions would defeat v1's session-isolation model.
+     *
+     * `api` (when provided) is the client-callback surface: ask the client
+     * for permission, and use the client's filesystem/terminal when it
+     * advertises those capabilities. A factory that wires it builds a
+     * client-backed permission policy and ACP-backed fs/terminal tools
+     * instead of silently auto-approving against the local disk.
+     */
+    agentFor: (sessionId: string, cwd: string, api?: RunTurnApi) => Promise<Agent> | Agent;
+    /**
+     * Hard wall-clock cap for one turn. The agent's own provider
+     * timeout is layered under this; this cap is a safety belt.
+     * Default 5 minutes.
+     */
+    timeoutMs?: number | undefined;
+}
+/** A recorded conversation turn, replayable on `session/load`. */
+interface SessionReplayUpdate {
+    sessionUpdate: 'user_message_chunk' | 'agent_message_chunk';
+    content: {
+        type: 'text';
+        text: string;
+    };
+}
+/**
+ * A `RunTurn` that also exposes the recorded per-session history so the
+ * server can replay it on `session/load`.
+ */
+interface ACPServerAgentTurn {
+    (input: Parameters<RunTurn>[0], emit: Parameters<RunTurn>[1], api?: Parameters<RunTurn>[2]): Promise<RunTurnResult>;
+    /** Recorded user/agent text turns for a session, in order. */
+    replay(sessionId: string): SessionReplayUpdate[];
+    /**
+     * Seed a session's history (from a durable store on cold `session/load`)
+     * so `replay()` returns it AND the next-created `Agent` for the session is
+     * primed with the prior conversation as model context — not just the
+     * client UI. Call before the first post-load `session/prompt`.
+     */
+    seed(sessionId: string, history: ReadonlyArray<{
+        sessionUpdate: string;
+        content: unknown;
+    }>): void;
+}
+/**
+ * Build a `RunTurn` that owns per-session `Agent` instances and
+ * delegates each turn to the appropriate agent. The returned
+ * function is reusable across sessions — the agents are kept in a
+ * Map keyed by `sessionId`. It also records each turn's user/agent
+ * text so the server can replay history on `session/load` (see
+ * `.replay(sessionId)`).
+ */
+declare function makeACPServerAgentTurn(opts: ACPServerAgentTurnOptions): ACPServerAgentTurn;
+/**
+ * Tear down the agents and timers held by a turn factory. The
+ * server's `close()` should call this so child connections don't
+ * outlive the server.
+ */
+declare function disposeACPServerAgentTurn(opts: {
+    agents: Map<string, Agent>;
+}): Promise<void>;
+
+export { type ACPServerAgentTurnOptions as A, type PersistedSession as P, type SessionStoreOptions as S, ACPSessionStore as a, disposeACPServerAgentTurn as d, makeACPServerAgentTurn as m };

package/dist/terminal-server-P9KpMZTT.d.ts

@@ -0,0 +1,99 @@
+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;
+}
+
+export { FileServer as F, type ReadFileParams as R, TerminalServer as T, type WriteFileParams as W, type FileServerOptions as a, FsError as b, type FsErrorCode as c, type TerminalServerOptions as d };

package/dist/{tools-registry-BCf8evEG.d.ts → tools-registry-D2xdbzN7.d.ts}

@@ -1,5 +1,5 @@
 import { Tool } from '@wrongstack/core';
-import { a as ACPToolList, b as ACPToolResult } from './stdio-transport-CsFr8JzC.js';
+import { c as ACPToolList, d as ACPToolResult } from './acp-v1-BxskPsdo.js';
 
 /**
  * Tools registry for ACP agent-side.

package/dist/wrongstack-acp-agent-nzrqmJnc.d.ts

@@ -0,0 +1,341 @@
+import { a as AgentServerTransport, C as ContentBlock, T as ToolKind, P as PermissionOption, R as RequestPermissionOutcome, e as StopReason, f as PlanEntry, U as UsageCost } from './acp-v1-BxskPsdo.js';
+
+/**
+ * ACP v1 server-side protocol handler.
+ *
+ * Receives JSON-RPC requests from an external ACP client (Zed, JetBrains
+ * Junie, VS Code ACP extension, etc.) over stdio and answers them per the
+ * v1 spec. See https://agentclientprotocol.com/protocol/v1/overview.
+ *
+ * Supported methods
+ * ─────────────────
+ *  - initialize                — handshake
+ *  - authenticate              — optional, no-op when auth isn't required
+ *  - session/new               — create a session
+ *  - session/load              — restore a session by id
+ *  - session/prompt            — run one turn, stream session/update
+ *                               notifications, return stopReason
+ *  - session/cancel            — notification (no response); cancels the
+ *                               in-flight turn on the target session
+ *  - session/set_mode          — change the active mode for a session
+ *  - session/set_config_option — change a config option value
+ *  - session/list              — list known sessions
+ *
+ * Method execution
+ * ────────────────
+ *  The handler is transport-agnostic; it sends responses via the
+ *  `AgentServerTransport` injected at construction. The actual
+ *  agent-loop work for a `session/prompt` turn is delegated to the
+ *  caller-provided `runTurn` callback, which receives the prompt
+ *  blocks and the per-turn AbortSignal and resolves with the final
+ *  stopReason. Updates are streamed via the `emit` callback passed
+ *  to `runTurn`; the handler wraps each as a `session/update`
+ *  notification.
+ *
+ *  This separation keeps the handler unit-testable: tests can supply
+ *  a fake `runTurn` that yields a canned sequence of updates, and
+ *  assert on the JSON-RPC traffic the handler produces. A real
+ *  production caller wires `runTurn` to a core `Agent` instance.
+ *
+ * Concurrency
+ * ───────────
+ *  Each session is single-threaded (one active turn at a time). The
+ *  handler keeps a per-session AbortController so a `session/cancel`
+ *  notification can stop the running turn mid-stream without tearing
+ *  down the session. Multiple sessions can be active concurrently.
+ */
+
+declare const WRONGSTACK_VERSION = "0.274.1";
+interface RunTurnInput {
+    sessionId: string;
+    /** Content blocks the client sent. */
+    prompt: readonly ContentBlock[];
+    /** Cancelled when the client sends `session/cancel` for this session. */
+    signal: AbortSignal;
+}
+interface RunTurnResult {
+    stopReason: StopReason;
+    /** Optional summary text the agent produced. */
+    text?: string;
+    plan?: PlanEntry[];
+    usage?: {
+        used: number;
+        size: number;
+        cost?: UsageCost | undefined;
+    };
+}
+/**
+ * A tool-call permission request the agent surfaces to the client.
+ */
+interface RunTurnPermissionRequest {
+    toolCall: {
+        toolCallId: string;
+        title: string;
+        kind?: ToolKind | undefined;
+    };
+    options: PermissionOption[];
+}
+/** Client filesystem/terminal capabilities advertised at initialize. */
+interface ClientCapabilities {
+    fs?: {
+        readTextFile?: boolean | undefined;
+        writeTextFile?: boolean | undefined;
+    } | undefined;
+    terminal?: boolean | undefined;
+}
+/**
+ * Client-callback API handed to `runTurn`. Lets the agent's tools call back
+ * into the connected ACP client — ask for permission, and (when the client
+ * advertises the capability) use the client's filesystem and terminal so the
+ * editor's view (including unsaved buffers) is the source of truth.
+ */
+interface RunTurnApi {
+    /**
+     * Ask the connected ACP client to approve/reject a tool call via the
+     * `session/request_permission` method. Resolves with the client's
+     * outcome. Rejects if no client channel is available or the request
+     * times out — the caller decides the fallback.
+     */
+    requestPermission(req: RunTurnPermissionRequest): Promise<RequestPermissionOutcome>;
+    /** Capabilities the client advertised at initialize — gate tool wiring on these. */
+    clientCapabilities: ClientCapabilities;
+    /** Read a text file from the client's filesystem (`fs/read_text_file`). */
+    readTextFile(params: {
+        path: string;
+        line?: number;
+        limit?: number;
+    }): Promise<string>;
+    /** Write a text file in the client's filesystem (`fs/write_text_file`). */
+    writeTextFile(params: {
+        path: string;
+        content: string;
+    }): Promise<void>;
+    /**
+     * Run a command in the client's terminal (`terminal/create` →
+     * `wait_for_exit` → `output` → `release`) and resolve with the combined
+     * output and exit code.
+     */
+    runTerminal(params: {
+        command: string;
+        args?: string[] | undefined;
+        cwd?: string | undefined;
+    }): Promise<{
+        output: string;
+        exitCode: number | null;
+    }>;
+}
+/**
+ * The agent's per-turn work. Streams `SessionUpdate` notifications to
+ * `emit` and resolves with the final stopReason. Errors thrown from
+ * this iterable are converted to a `prompt_failed` JSON-RPC error.
+ *
+ * `api` is an optional client-callback surface (permission requests).
+ * Older runTurn implementations that ignore it keep working unchanged.
+ */
+type RunTurn = (input: RunTurnInput, emit: (update: unknown) => void, api?: RunTurnApi) => Promise<RunTurnResult>;
+interface SessionState {
+    id: string;
+    cwd: string;
+    /** Per-turn abort signal — aborted when the session is cancelled or closed. */
+    abort: AbortController;
+    /** Active mode, advertised to the client in current_mode_update. */
+    modeId: string;
+    /** Created at, for session/list ordering. */
+    createdAt: string;
+    /** Last activity timestamp, for session/info_update. */
+    updatedAt: string;
+    /** Optional human title. */
+    title?: string;
+}
+/** MCP-style session mode advertised in current_mode_update. */
+interface SessionMode {
+    id: string;
+    name: string;
+    description?: string | undefined;
+}
+interface SessionConfigOption {
+    id: string;
+    name: string;
+    type: 'select' | string;
+    currentValue: string;
+    options: {
+        value: string;
+        name: string;
+        description?: string | undefined;
+    }[];
+}
+interface ProtocolHandlerOptions {
+    transport: AgentServerTransport;
+    /** Where the server is running; used for new sessions' default cwd. */
+    defaultCwd: string;
+    /** Agent's per-turn implementation. */
+    runTurn: RunTurn;
+    /**
+     * Optional callbacks for the lifecycle events the server should
+     * surface to the client. All default to no-ops.
+     */
+    onSessionNew?: ((state: SessionState) => void) | undefined;
+    /** Static list of available modes (advertised to clients). */
+    modes?: readonly SessionMode[] | undefined;
+    /** Static list of config options. */
+    configOptions?: readonly SessionConfigOption[] | undefined;
+    /** Agent name advertised in initialize. */
+    agentName?: string | undefined;
+    /**
+     * Optional source of replayable conversation history for `session/load`.
+     * Returns the `session/update` payloads (user/agent message chunks) to
+     * stream back to the client before the load response. Wired from
+     * `makeACPServerAgentTurn(...).replay`.
+     */
+    replayFor?: ((sessionId: string) => Array<{
+        sessionUpdate: string;
+        content: unknown;
+    }>) | undefined;
+    /**
+     * Optional hook to prime the turn engine's session history on cold
+     * `session/load` (server restart). Wired from `makeACPServerAgentTurn(...).seed`
+     * — it re-feeds the persisted conversation into the next-created Agent so
+     * the model resumes, not just the client UI.
+     */
+    seedFor?: ((sessionId: string, history: Array<{
+        sessionUpdate: string;
+        content: unknown;
+    }>) => void) | undefined;
+    /**
+     * Optional durable session store. When set, sessions + their recorded
+     * history are persisted on create/prompt and restored on `session/load`,
+     * so a reconnecting client can resume after a server restart.
+     * (Structural type — `ACPSessionStore` satisfies it without a value import.)
+     */
+    store?: SessionPersistence | undefined;
+}
+/** Minimal durable-store contract the handler uses (ACPSessionStore satisfies it). */
+interface SessionPersistence {
+    save(state: SessionState, history?: Array<{
+        sessionUpdate: string;
+        content: unknown;
+    }>): Promise<unknown>;
+    load(sessionId: string): Promise<(Partial<SessionState> & {
+        history?: Array<{
+            sessionUpdate: string;
+            content: unknown;
+        }> | undefined;
+    }) | null>;
+}
+declare class ACPProtocolHandler {
+    private readonly transport;
+    private readonly defaultCwd;
+    private readonly runTurn;
+    private readonly onSessionNew;
+    private readonly modes;
+    private readonly configOptions;
+    private readonly agentName;
+    private readonly replayFor;
+    private readonly seedFor;
+    private readonly store;
+    private initialized;
+    private clientCapabilities;
+    private readonly sessions;
+    private nextId;
+    private readonly pendingOut;
+    private nextOutId;
+    constructor(opts: ProtocolHandlerOptions);
+    /**
+     * Send a request to the client and await its response. Used for
+     * server-initiated calls like `session/request_permission`. Rejects on
+     * timeout or transport error so the caller can pick a safe fallback.
+     */
+    private request;
+    private maybeResolvePending;
+    /**
+     * Process one inbound message. Returns true if this was a terminal
+     * message (rare; reserved for future use by the server's own
+     * shutdown signal).
+     */
+    handleMessage(msg: unknown): Promise<boolean>;
+    /** Abort all active turns and drop session state. */
+    close(): void;
+    private handleRequest;
+    private handleInitialize;
+    private handleAuthenticate;
+    private handleLogout;
+    private handleSessionNew;
+    private handleSessionLoad;
+    private handleSessionResume;
+    private handleSessionClose;
+    private handleSessionDelete;
+    private handleSessionFork;
+    private handleProvidersList;
+    private handleProvidersSet;
+    private handleProvidersDisable;
+    private handleMcpMessage;
+    private handleSessionPrompt;
+    private handleSetMode;
+    private handleSetConfigOption;
+    private handleSessionList;
+    private handleNotification;
+    private sendNotification;
+    /** Best-effort durable persistence of a session + its recorded history. */
+    private persist;
+    private sendError;
+    private allocId;
+}
+
+interface WrongStackACPServerOptions {
+    runTurn?: RunTurn | undefined;
+    defaultCwd?: string | undefined;
+    agentName?: string | undefined;
+    /**
+     * Transport mode. 'stdio' (default) communicates over stdin/stdout.
+     * When a number is provided, the server listens as an HTTP server on
+     * that port, accepting Streamable HTTP (JSON-RPC over HTTP POST).
+     */
+    transport?: 'stdio' | number | undefined;
+    /** Host for HTTP transport. Defaults to '127.0.0.1'. */
+    host?: string | undefined;
+    /** Emit the pre-v1 startup marker on stdio. Defaults to false. */
+    legacyStartupMarker?: boolean | undefined;
+    /**
+     * Conversation-history source for `session/load` replay. Pass
+     * `makeACPServerAgentTurn(...).replay` here so a reconnecting client
+     * gets prior turns streamed back.
+     */
+    replayFor?: ((sessionId: string) => Array<{
+        sessionUpdate: string;
+        content: unknown;
+    }>) | undefined;
+    /**
+     * Cold-load seed hook. Pass `makeACPServerAgentTurn(...).seed` so a
+     * restored session's Agent resumes the model context, not just the UI.
+     */
+    seedFor?: ((sessionId: string, history: Array<{
+        sessionUpdate: string;
+        content: unknown;
+    }>) => void) | undefined;
+    /**
+     * Durable session store. When set, sessions + history are persisted and
+     * restored across restarts for `session/load`. Pass an `ACPSessionStore`.
+     */
+    store?: SessionPersistence | undefined;
+}
+declare class WrongStackACPServer {
+    private readonly transport;
+    private readonly handler;
+    private readonly options;
+    /** HTTP server when transport mode is HTTP. */
+    private httpServer;
+    private running;
+    constructor(opts?: WrongStackACPServerOptions);
+    /**
+     * Start the server. Mode depends on `options.transport`:
+     * - 'stdio' (default): reads JSON-RPC from stdin, writes to stdout.
+     * - number: listens as HTTP on the given port.
+     */
+    start(): Promise<void>;
+    private startStdio;
+    private startHttp;
+    /** Stop the server. */
+    stop(): void;
+}
+
+export { ACPProtocolHandler as A, type ClientCapabilities as C, type ProtocolHandlerOptions as P, type RunTurn as R, type SessionConfigOption as S, WRONGSTACK_VERSION as W, type RunTurnInput as a, type RunTurnResult as b, type SessionMode as c, type SessionState as d, WrongStackACPServer as e, type WrongStackACPServerOptions as f, type RunTurnApi as g, type RunTurnPermissionRequest as h, type SessionPersistence as i };

package/dist/wrongstack-acp-agent.d.ts

@@ -1,3 +1,3 @@
-export { W as WrongStackACPServer, a as WrongStackACPServerOptions } from './wrongstack-acp-agent-Dv-A0bEm.js';
-import './stdio-transport-CsFr8JzC.js';
+export { e as WrongStackACPServer, f as WrongStackACPServerOptions } from './wrongstack-acp-agent-nzrqmJnc.js';
+import './acp-v1-BxskPsdo.js';
 import 'node:events';