@wrongstack/acp 0.297.0 → 0.298.0

package/dist/agent/protocol-handler.d.ts

@@ -1,50 +1,6 @@
-/**
- * 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.
- */
-import { WRONGSTACK_VERSION, type ProtocolHandlerOptions } from './protocol-contract.js';
-export { WRONGSTACK_VERSION };
+import { type ProtocolHandlerOptions, WRONGSTACK_VERSION } from './protocol-contract.js';
 export type { AgentCapabilities, ClientCapabilities, PromptCapabilities, ProtocolHandlerOptions, RunTurn, RunTurnApi, RunTurnInput, RunTurnPermissionRequest, RunTurnResult, SessionConfigOption, SessionMode, SessionPersistence, SessionState, } from './protocol-contract.js';
+export { WRONGSTACK_VERSION };
 export declare class ACPProtocolHandler {
     private readonly transport;
     private readonly defaultCwd;
@@ -104,6 +60,43 @@ export declare class ACPProtocolHandler {
     /** Best-effort durable persistence of a session + its recorded history. */
     private persist;
     private sendError;
+    /**
+     * Allocate a session id (WS-015).
+     *
+     * This was `this.nextId++`, so ids were `sess_1`, `sess_2`, … — and the
+     * handler has no per-connection ownership: any caller that names a session
+     * id can `session/load`, `session/prompt`, `session/cancel` or
+     * `session/delete` it. Over stdio that is academic (one client per process),
+     * but the agent also serves over HTTP, where a guessable id is the whole
+     * authorization story for any local process or page that reaches the port.
+     *
+     * Random ids do not create ownership — they remove the trivial enumeration
+     * that made its absence exploitable. Real per-connection ownership is the
+     * larger fix and is noted in the WS-015 test file.
+     *
+     * The counter is retained: it keeps ids ordered for debugging and guarantees
+     * uniqueness within a process even in the (impossible) event of a UUID
+     * collision. The random half is what makes the id unguessable.
+     */
+    /**
+     * Resolve a client-supplied `cwd` for a session, or `null` when it is not
+     * usable (WS-015).
+     *
+     * `session/new`, `session/load` and `session/fork` all took `params.cwd`
+     * with a single `typeof === 'string'` check and nothing else. That value is
+     * the working directory the agent then reads, writes and executes in.
+     *
+     * SCOPE, deliberately stated: this does NOT confine the session to a root.
+     * In ACP the client IS the editor and legitimately names its own workspace —
+     * Zed and JetBrains pass the project root — so a fixed boundary here would
+     * break the integration this package exists for. What it enforces is that
+     * the directory is absolute and actually exists as a directory: a relative
+     * or missing `cwd` is a bug or an attack under either reading, and silently
+     * running the agent somewhere other than where the client asked is worse
+     * than refusing. Confinement, if wanted, belongs in an operator-set option
+     * on top of this, not in place of it.
+     */
+    private resolveSessionCwd;
     private allocId;
 }
 declare function errorToJsonRpc(err: unknown): {

package/dist/agent/session-store.d.ts

@@ -21,7 +21,43 @@ export declare class ACPSessionStore {
      * Cleared automatically if the directory disappears between calls.
      */
     private initialized;
+    /**
+     * Tail of in-flight sidecar-index mutations. `readIndex`/`writeIndex`/
+     * `updateIndex`/delete's index-touching branch all run through the
+     * `withIndexLock` gate so a concurrent save/delete/save cannot read the
+     * same baseline twice and clobber the other writer's edit (Chimera
+     * HIGH — race that could permanently omit or resurrect sessions in
+     * `list()`). Mirrors the `writeChains` pattern in
+     * `packages/core/src/storage/tool-audit-log.ts`.
+     */
+    private indexChain;
+    /**
+     * Monotonic per-store counter. Used to make tmp filenames unique so two
+     * concurrent saves started in the same millisecond cannot collide on
+     * `<target>.<pid>.<ts>.tmp` and lose one's tmp mid-write (latent bug
+     * discovered by the concurrent same-id save/delete stress test).
+     */
+    private writeSeq;
     constructor(opts?: SessionStoreOptions);
+    /**
+     * Path of `<sessionId>.json` inside the store, or `null` when `sessionId`
+     * is not usable as a single path segment (WS-015).
+     *
+     * The session id arrives from the ACP client — `session/load`,
+     * `session/close` and `session/delete` all take it verbatim from the wire.
+     * It was joined straight onto the store directory, so `../../..` escaped it,
+     * and the `.json` suffix was the only thing narrowing the blast radius:
+     *
+     *   - `load`   — read any `.json` on the machine, e.g. the provider config
+     *                holding API keys
+     *   - `delete` — unlink any `.json` on the machine
+     *   - `save`   — the worst one: a loaded session keeps the traversing id as
+     *                its `state.id`, so the next persist WRITES to that path
+     *
+     * All three now route through here, so the escape is closed once rather than
+     * three times.
+     */
+    private sessionFile;
     /** Ensure the store directory exists. Memoized — only mkdirs once. */
     init(): Promise<void>;
     /**
@@ -37,8 +73,27 @@ export declare class ACPSessionStore {
         id: string;
         updatedAt: string;
     }>>;
+    /**
+     * Walk `<dir>` and parse every session file into `{id, updatedAt}`
+     * metadata. Used as the slow-path fallback by `list()` and by
+     * `updateIndex()` when the sidecar index is missing. Pure read —
+     * does NOT touch `index.json`.
+     */
+    private scanForSessions;
     /** Sidecar path that stores `{id, updatedAt}` for every saved session. */
     private indexPath;
+    /**
+     * Serialize sidecar-index mutations. Each call appends `fn` to the tail
+     * of `indexChain` so reads and writes see a linearized order — a second
+     * caller cannot start until the first one's index update has finished.
+     *
+     * The chain swallows errors (`prev.then(fn, fn)`) so one failing writer
+     * does not poison every subsequent caller, and the catch keeps an
+     * unhandled rejection from leaking out of the stored tail. The cleanup
+     * removes the tail entry once settled, so a quiet store does not retain
+     * stale promises forever.
+     */
+    private withIndexLock;
     /** Read the sidecar index. Returns `null` when missing or unreadable. */
     private readIndex;
     /** Atomically replace the sidecar index with the supplied entries. */

package/dist/agent/stdio-transport.d.ts

@@ -4,8 +4,33 @@ export interface AgentServerTransport {
     send(msg: ACPMessage): Promise<void>;
     sendRaw(chunk: string): void;
     read(): Promise<ACPMessage | null>;
-    close(): void;
+    /**
+     * Register an observer that fires for every inbound message — including
+     * messages that resolve a parked `read()` call.
+     *
+     * Dual-fire contract: a message is delivered to BOTH the `read()`
+     * promise (if one is parked) AND every handler registered here. The
+     * legacy behavior was "no fire while read() is parked"; the new
+     * behavior was adopted to fix a deadlock when a JSON-RPC reply
+     * arrived before the next read() call (handlers that correlate
+     * responses to outbound requests would never see it). Handlers MUST
+     * tolerate being called for every inbound message and MUST NOT
+     * assume the message has not also been delivered to read().
+     *
+     * To consume a message exclusively (prevent it from being enqueued for
+     * read()), use `onMessageClaim()` instead. Most observers want
+     * `onMessage`; correlation handlers and the protocol layer want
+     * `onMessageClaim`.
+     */
     onMessage(handler: (msg: ACPMessage) => void): () => void;
+    /**
+     * Register a handler that MAY claim a message by returning `true`.
+     * Claimed messages are NOT enqueued for the read() loop. Required
+     * for the server transport so the correlation handler (which always
+     * fires) doesn't starve the read loop of pipelined requests and
+     * notifications. See `onMessageClaim` on the implementations.
+     */
+    onMessageClaim?(handler: (msg: ACPMessage) => boolean): () => void;
 }
 /**
  * Minimal client-side transport contract `ACPSession` drives. `ClientTransport`
@@ -15,7 +40,21 @@ export interface AgentServerTransport {
 export interface ACPClientTransport {
     start(): Promise<void>;
     send(msg: ACPMessage): Promise<void>;
+    /**
+     * See {@link AgentServerTransport.onMessage}. The client contract has the
+     * same dual-fire guarantee: handlers fire for every inbound message,
+     * regardless of any concurrent reader. Client-side consumers always
+     * observe the full message stream via onMessage, so claim semantics
+     * are not needed — see {@link onMessageClaim} for the optional
+     * claim variant.
+     */
     onMessage(handler: (msg: ACPMessage) => void): () => void;
+    /**
+     * See {@link AgentServerTransport.onMessageClaim}. Optional on the
+     * client contract: client-side consumers always observe the full
+     * message stream via onMessage, so claim semantics are not needed.
+     */
+    onMessageClaim?(handler: (msg: ACPMessage) => boolean): () => void;
     stop(): void;
 }
 export declare class StdioTransport implements AgentServerTransport {
@@ -24,20 +63,38 @@ export declare class StdioTransport implements AgentServerTransport {
     private readonly stderr;
     private buffer;
     private readonly handlers;
+    private readonly claimHandlers;
     private closed;
     private resolveRead;
     private messageQueue;
+    private queuedChars;
     private readonly maxFrameChars;
     private readonly maxQueuedMessages;
+    private readonly maxQueuedChars;
+    private readonly onStdinData;
+    private readonly onStdinEnd;
+    private readonly onStdinError;
     constructor(opts?: {
         maxFrameChars?: number;
         maxQueuedMessages?: number;
+        maxQueuedChars?: number;
     });
     sendStartupMarker(): void;
     send(msg: ACPMessage): Promise<void>;
     sendRaw(chunk: string): void;
     read(): Promise<ACPMessage | null>;
     onMessage(handler: (msg: ACPMessage) => void): () => void;
+    /**
+     * Register a handler that MAY claim a message by returning `true`.
+     * Claimed messages are NOT enqueued for the read() loop — they are
+     * considered fully consumed by the handler. This is how the ACP
+     * server transport prevents the correlation handler (which always
+     * fires on every message but only actually correlates responses)
+     * from starving the read() loop of pipelined requests, notifications,
+     * and any message the handler chose to ignore. See dispatch() for
+     * the gating logic.
+     */
+    onMessageClaim(handler: (msg: ACPMessage) => boolean): () => void;
     close(): void;
     private onData;
     private dispatch;
@@ -62,6 +119,8 @@ export interface ClientTransportOptions {
     maxFrameChars?: number | undefined;
     /** Maximum messages retained for the optional read() API. Default 1000. */
     maxQueuedMessages?: number | undefined;
+    /** Maximum serialized characters retained for the optional read() API. Default 32 MiB. */
+    maxQueuedChars?: number | undefined;
 }
 export interface ACPChildProcess extends EventEmitter {
     stdout: NodeJS.ReadableStream;
@@ -74,17 +133,31 @@ export declare class ClientTransport implements ACPClientTransport {
     private child;
     private buffer;
     private readonly handlers;
+    private readonly claimHandlers;
     private closed;
     private resolveRead;
     private messageQueue;
+    private queuedChars;
     private readonly opts;
     private readonly maxFrameChars;
     private readonly maxQueuedMessages;
+    private readonly maxQueuedChars;
     constructor(options: ClientTransportOptions);
     start(): Promise<void>;
     send(msg: ACPMessage): Promise<void>;
     read(): Promise<ACPMessage | null>;
     onMessage(handler: (msg: ACPMessage) => void): () => void;
+    /**
+     * Register a handler that MAY claim a message by returning `true`.
+     * Claimed messages are NOT enqueued for the read() loop — they are
+     * considered fully consumed by the handler. This is how the ACP
+     * server transport prevents the correlation handler (which always
+     * fires on every message but only actually correlates responses)
+     * from starving the read() loop of pipelined requests, notifications,
+     * and any message the handler chose to ignore. See dispatch() for
+     * the gating logic.
+     */
+    onMessageClaim(handler: (msg: ACPMessage) => boolean): () => void;
     stop(): void;
     private onChildData;
     private onChildError;