@wrongstack/acp 0.273.1 → 0.275.0

package/dist/acp-v1-BxskPsdo.d.ts

@@ -0,0 +1,520 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * ACP message types — transport-agnostic JSON-RPC 2.0 envelope.
+ * Reuses MCP types where possible; custom types for agentic UX (diffs, plans).
+ */
+interface ACPMessage {
+    method: string;
+    id?: string | number | undefined;
+    params?: unknown | undefined;
+    result?: unknown | undefined;
+    error?: ACPError | undefined;
+}
+interface ACPError {
+    code: number;
+    message: string;
+    data?: unknown | undefined;
+}
+type ACPRequest = RequiredPick<ACPMessage, 'id' | 'params' | 'method'>;
+type ACPResponse = RequiredPick<ACPMessage, 'id' | 'result' | 'method'>;
+type ACPNotification = Omit<ACPMessage, 'id'> & {
+    method: string;
+};
+interface ACPInitializeParams {
+    capabilities?: string[] | undefined;
+    protocolVersion?: string | undefined;
+    sessionId?: string | undefined;
+    authToken?: string | undefined;
+    sessionPath?: string | undefined;
+    workspaceRoots?: string[] | undefined;
+    mcpServers?: unknown[] | undefined;
+    [key: string]: unknown;
+}
+interface ACPCapabilities {
+    capabilities: string[];
+    agentName: string;
+    agentVersion: string;
+    tools?: ACPToolList | undefined;
+    protocolVersion: string;
+}
+interface ACPToolList {
+    tools: ACPToolDefinition[];
+}
+interface ACPToolDefinition {
+    name: string;
+    description?: string | undefined;
+    inputSchema: ACPInputSchema;
+    annotations?: {
+        title?: string | undefined;
+        description?: string | undefined;
+        priority?: 'high' | 'medium' | 'low' | undefined;
+        alwaysAccept?: boolean | undefined;
+    };
+}
+type ACPInputSchema = {
+    type?: string | undefined;
+    properties?: Record<string, ACPInputSchema>;
+    required?: string[] | undefined;
+    items?: ACPInputSchema | undefined;
+    enum?: unknown[] | undefined;
+    description?: string | undefined;
+    default?: unknown | undefined;
+    minimum?: number | undefined;
+    maximum?: number | undefined;
+    [key: string]: unknown;
+};
+type ContentBlock$1 = ACPTextContent | ACPResourceContent | ACPImageContent | ACPProgressContent;
+interface ACPTextContent {
+    type: 'text';
+    text: string;
+}
+interface ACPResourceContent {
+    type: 'resource';
+    resource: {
+        type: string;
+        uri: string;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+    };
+}
+interface ACPImageContent {
+    type: 'image';
+    data: string;
+    mimeType?: string | undefined;
+}
+interface ACPProgressContent {
+    type: 'progress';
+    id: string;
+    label?: string | undefined;
+    message?: string | undefined;
+    messages?: string[] | undefined;
+}
+interface ACPToolCallRequest {
+    method: 'tools/call';
+    id: string | number;
+    params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+}
+interface ACPToolResult {
+    content: ContentBlock$1[];
+    isError?: boolean | undefined;
+}
+type ACPToolCallResponse = {
+    method: 'tools/call';
+    id: string | number;
+    result: ACPToolResult;
+};
+interface ACPSessionInfo {
+    sessionId: string;
+    path: string;
+    title?: string | undefined;
+    modelId?: string | undefined;
+    createdAt: string;
+    lastActiveAt: string;
+}
+interface ACPPlanStep {
+    id: string;
+    description: string;
+    status?: 'pending' | 'running' | 'completed' | 'skipped' | undefined;
+}
+interface ACPPlanContent {
+    type: 'plan';
+    plan: {
+        steps: ACPPlanStep[];
+    };
+}
+type ACPSessionMode = 'agent' | 'chat' | 'edit' | 'preview';
+interface ACPCancelParams {
+    reason?: string | undefined;
+}
+type RequiredPick<T, K extends keyof T> = Pick<T, K> & Partial<Omit<T, K>>;
+
+interface AgentServerTransport {
+    send(msg: ACPMessage): Promise<void>;
+    sendRaw(chunk: string): void;
+    read(): Promise<ACPMessage | null>;
+    close(): void;
+    onMessage(handler: (msg: ACPMessage) => void): () => void;
+}
+/**
+ * Minimal client-side transport contract `ACPSession` drives. `ClientTransport`
+ * (stdio subprocess) and `WebSocketClientTransport` (remote) both implement it,
+ * so the session is agnostic to how bytes reach the agent.
+ */
+interface ACPClientTransport {
+    start(): Promise<void>;
+    send(msg: ACPMessage): Promise<void>;
+    onMessage(handler: (msg: ACPMessage) => void): () => void;
+    stop(): void;
+}
+declare class StdioTransport implements AgentServerTransport {
+    private readonly stdin;
+    private readonly stdout;
+    private readonly stderr;
+    private buffer;
+    private readonly handlers;
+    private closed;
+    private resolveRead;
+    private messageQueue;
+    constructor();
+    sendStartupMarker(): void;
+    send(msg: ACPMessage): Promise<void>;
+    sendRaw(chunk: string): void;
+    read(): Promise<ACPMessage | null>;
+    onMessage(handler: (msg: ACPMessage) => void): () => void;
+    close(): void;
+    private onData;
+    private dispatch;
+    private handleClose;
+    private failAll;
+}
+
+interface ClientTransportOptions {
+    command: string;
+    args?: string[] | undefined;
+    env?: Record<string, string>;
+    cwd?: string | undefined;
+    handshakeTimeoutMs?: number | undefined;
+    /**
+     * Set to true when the child is an external ACP agent (Claude Code,
+     * Gemini CLI, Codex CLI, …) that does NOT emit a `[wstack-acp]\n`
+     * marker on startup. The v1 client (`ACPSession`) sets this; the
+     * server-side transport (the default) keeps the marker check.
+     */
+    skipHandshakeMarker?: boolean | undefined;
+}
+interface ACPChildProcess extends EventEmitter {
+    stdout: NodeJS.ReadableStream;
+    stdin: NodeJS.WritableStream;
+    stderr: NodeJS.ReadableStream;
+    pid: number | undefined;
+    kill(): void;
+}
+declare class ClientTransport implements ACPClientTransport {
+    private child;
+    private buffer;
+    private readonly handlers;
+    private closed;
+    private resolveRead;
+    private messageQueue;
+    private readonly opts;
+    constructor(options: ClientTransportOptions);
+    start(): Promise<void>;
+    send(msg: ACPMessage): Promise<void>;
+    read(): Promise<ACPMessage | null>;
+    onMessage(handler: (msg: ACPMessage) => void): () => void;
+    stop(): void;
+    private onChildData;
+    private onChildError;
+    private onChildClose;
+    private dispatch;
+}
+
+/** Per the spec: opaque, unique id. We type as branded string. */
+type SessionId = string & {
+    readonly __acpSessionId: unique symbol;
+};
+type ToolCallId = string & {
+    readonly __acpToolCallId: unique symbol;
+};
+type MessageId = string & {
+    readonly __acpMessageId: unique symbol;
+};
+type TerminalId = string & {
+    readonly __acpTerminalId: unique symbol;
+};
+interface PromptCapabilities {
+    image?: boolean | undefined;
+    audio?: boolean | undefined;
+    embeddedContext?: boolean | undefined;
+}
+interface McpCapabilities {
+    http?: boolean | undefined;
+    sse?: boolean | undefined;
+}
+interface SessionCapabilities {
+    close?: Record<string, unknown> | undefined;
+    list?: Record<string, unknown> | undefined;
+    delete?: Record<string, unknown> | undefined;
+    resume?: Record<string, unknown> | undefined;
+    additionalDirectories?: Record<string, unknown> | undefined;
+}
+interface AuthCapabilities {
+    logout?: Record<string, unknown> | undefined;
+}
+interface AgentCapabilities {
+    loadSession?: boolean | undefined;
+    promptCapabilities?: PromptCapabilities | undefined;
+    mcpCapabilities?: McpCapabilities | undefined;
+    sessionCapabilities?: SessionCapabilities | undefined;
+    auth?: AuthCapabilities | undefined;
+}
+interface AuthMethod {
+    id: string;
+    name: string;
+    description?: string | undefined;
+    type?: 'agent' | 'oauth' | 'http' | undefined;
+}
+interface StdioMcpServer {
+    name: string;
+    command: string;
+    args?: string[] | undefined;
+    env?: {
+        name: string;
+        value: string;
+    }[] | undefined;
+}
+interface HttpMcpServer {
+    type: 'http';
+    name: string;
+    url: string;
+    headers?: {
+        name: string;
+        value: string;
+    }[] | undefined;
+}
+interface SseMcpServer {
+    type: 'sse';
+    name: string;
+    url: string;
+    headers?: {
+        name: string;
+        value: string;
+    }[] | undefined;
+}
+type McpServer = StdioMcpServer | HttpMcpServer | SseMcpServer;
+/**
+ * Annotations attached to a content block. Optional, agent-supplied hint
+ * about audience/priority. Spec leaves shape open; we mirror the fields
+ * the spec shows in its examples.
+ */
+interface ContentAnnotations {
+    audience?: ('user' | 'assistant')[] | undefined;
+    priority?: number | undefined;
+    [key: string]: unknown;
+}
+interface TextContent {
+    type: 'text';
+    text: string;
+    annotations?: ContentAnnotations | undefined;
+}
+interface ImageContent {
+    type: 'image';
+    mimeType: string;
+    /** Base64-encoded image data. */
+    data: string;
+    uri?: string | undefined;
+    annotations?: ContentAnnotations | undefined;
+}
+interface AudioContent {
+    type: 'audio';
+    mimeType: string;
+    /** Base64-encoded audio data. */
+    data: string;
+    annotations?: ContentAnnotations | undefined;
+}
+interface TextResourceContents {
+    uri: string;
+    mimeType?: string | undefined;
+    text: string;
+}
+interface BlobResourceContents {
+    uri: string;
+    mimeType?: string | undefined;
+    /** Base64-encoded binary. */
+    blob: string;
+}
+type EmbeddedResourceContents = TextResourceContents | BlobResourceContents;
+interface EmbeddedResourceContent {
+    type: 'resource';
+    resource: EmbeddedResourceContents;
+    annotations?: ContentAnnotations | undefined;
+}
+interface ResourceLinkContent {
+    type: 'resource_link';
+    uri: string;
+    name: string;
+    mimeType?: string | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+    size?: number | undefined;
+    annotations?: ContentAnnotations | undefined;
+}
+type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResourceContent | ResourceLinkContent;
+type ToolKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'switch_mode' | 'other';
+type ToolCallStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+/** A single concrete content payload attached to a tool call. */
+type ToolCallContent = {
+    type: 'content';
+    content: ContentBlock;
+} | {
+    type: 'diff';
+    path: string;
+    oldText: string | null;
+    newText: string;
+} | {
+    type: 'terminal';
+    terminalId: TerminalId;
+};
+interface ToolCallLocation {
+    path: string;
+    /** 1-based per the spec's argument requirements. */
+    line?: number | undefined;
+}
+type PlanEntryPriority = 'high' | 'medium' | 'low';
+type PlanEntryStatus = 'pending' | 'in_progress' | 'completed';
+interface PlanEntry {
+    /** Required by the spec for the array shape, but per-entry id is optional. */
+    content: string;
+    priority: PlanEntryPriority;
+    status: PlanEntryStatus;
+}
+interface AvailableCommandInput {
+    hint: string;
+}
+interface AvailableCommand {
+    name: string;
+    description: string;
+    input?: AvailableCommandInput | undefined;
+}
+type SessionModeId = string & {
+    readonly __acpModeId: unique symbol;
+};
+/** Reserved spec categories. Underscore-prefixed names are free for custom use. */
+type ConfigOptionCategory = 'mode' | 'model' | 'thought_level' | `_${string}`;
+type ConfigOptionType = 'select' | string;
+interface ConfigOptionValue {
+    value: string;
+    name: string;
+    description?: string | undefined;
+}
+interface ConfigOption {
+    id: string;
+    name: string;
+    description?: string | undefined;
+    category?: ConfigOptionCategory | undefined;
+    type: ConfigOptionType;
+    currentValue: string;
+    options: ConfigOptionValue[];
+}
+interface SessionInfo {
+    sessionId: SessionId;
+    cwd: string;
+    title?: string | undefined;
+    updatedAt?: string | undefined;
+    /** Agent-supplied extension metadata; opaque to clients. */
+    _meta?: Record<string, unknown> | undefined;
+}
+interface UsageCost {
+    amount: number;
+    /** ISO 4217 currency code, e.g. "USD". */
+    currency: string;
+}
+type PermissionOptionKind = 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always';
+interface PermissionOption {
+    optionId: string;
+    name: string;
+    kind: PermissionOptionKind;
+}
+type RequestPermissionOutcome = {
+    outcome: 'cancelled';
+} | {
+    outcome: 'selected';
+    optionId: string;
+};
+type StopReason = 'end_turn' | 'max_tokens' | 'max_turn_requests' | 'refusal' | 'cancelled' | string;
+/** Stable v1 variants. The spec currently defines exactly 11. */
+type SessionUpdate = UserMessageChunkUpdate | AgentMessageChunkUpdate | ThoughtChunkUpdate | ToolCallUpdateUpdate | ToolCallUpdateNotification | PlanUpdate | AvailableCommandsUpdate | CurrentModeUpdate | ConfigOptionUpdate | SessionInfoUpdate | UsageUpdateUpdate;
+interface UserMessageChunkUpdate {
+    sessionUpdate: 'user_message_chunk';
+    messageId?: MessageId | undefined;
+    content: ContentBlock;
+}
+interface AgentMessageChunkUpdate {
+    sessionUpdate: 'agent_message_chunk';
+    messageId?: MessageId | undefined;
+    content: ContentBlock;
+}
+interface ThoughtChunkUpdate {
+    sessionUpdate: 'thought_chunk';
+    messageId?: MessageId | undefined;
+    content: ContentBlock;
+}
+/** First notification for a new tool call. */
+interface ToolCallUpdateUpdate {
+    sessionUpdate: 'tool_call';
+    toolCallId: ToolCallId;
+    title: string;
+    kind?: ToolKind | undefined;
+    status?: ToolCallStatus | undefined;
+    content?: ToolCallContent[] | undefined;
+    locations?: ToolCallLocation[] | undefined;
+    rawInput?: Record<string, unknown> | undefined;
+}
+/** Subsequent updates to a previously-emitted tool call. */
+interface ToolCallUpdateNotification {
+    sessionUpdate: 'tool_call_update';
+    toolCallId: ToolCallId;
+    status?: ToolCallStatus | undefined;
+    content?: ToolCallContent[] | undefined;
+    title?: string | undefined;
+    kind?: ToolKind | undefined;
+    locations?: ToolCallLocation[] | undefined;
+    rawInput?: Record<string, unknown> | undefined;
+    rawOutput?: Record<string, unknown> | undefined;
+}
+interface PlanUpdate {
+    sessionUpdate: 'plan';
+    entries: PlanEntry[];
+}
+interface AvailableCommandsUpdate {
+    sessionUpdate: 'available_commands_update';
+    availableCommands: AvailableCommand[];
+}
+interface CurrentModeUpdate {
+    sessionUpdate: 'current_mode_update';
+    modeId: SessionModeId;
+}
+interface ConfigOptionUpdate {
+    sessionUpdate: 'config_option_update';
+    configOptions: ConfigOption[];
+}
+interface SessionInfoUpdate {
+    sessionUpdate: 'session_info_update';
+    title?: string | null | undefined;
+    updatedAt?: string | null | undefined;
+    _meta?: Record<string, unknown> | undefined;
+}
+interface UsageUpdateUpdate {
+    sessionUpdate: 'usage_update';
+    used: number;
+    size: number;
+    cost?: UsageCost | undefined;
+}
+/**
+ * Escape hatch for v2-RFD `sessionUpdate` kinds that have been published
+ * but are not yet stabilised in the v1 spec. Examples seen in the wild:
+ * `next_edit_suggestions`, `elicitation`, `proxy_extension`. We surface
+ * the raw payload so forward-compat code can switch on
+ * `kind === 'next_edit_suggestions'` etc. without losing the data.
+ */
+interface UnstableSessionUpdate {
+    sessionUpdate: `_unstable_${string}`;
+    [key: string]: unknown;
+}
+/**
+ * Last-resort variant: the agent sent a discriminator string we don't
+ * recognise at all. The full payload is preserved as a record so consumers
+ * can still log/inspect it. Prefer matching the known variants first.
+ */
+interface UnknownSessionUpdate {
+    sessionUpdate: string;
+    [key: string]: unknown;
+}
+/** The full union, including escape hatches. */
+type AnySessionUpdate = SessionUpdate | UnstableSessionUpdate | UnknownSessionUpdate;
+
+export { type ACPClientTransport as A, type ACPResponse as B, type ContentBlock as C, type ACPSessionInfo as D, type ACPSessionMode as E, type ACPTextContent as F, type ACPToolCallRequest as G, type ACPToolCallResponse as H, type ACPToolDefinition as I, ClientTransport as J, type ClientTransportOptions as K, type ContentBlock$1 as L, type McpServer as M, type PermissionOption as P, type RequestPermissionOutcome as R, StdioTransport as S, type ToolKind as T, type UsageCost as U, type AgentServerTransport as a, type ACPMessage as b, type ACPToolList as c, type ACPToolResult as d, type StopReason as e, type PlanEntry as f, type ToolCallUpdateNotification as g, type ToolCallStatus as h, type AnySessionUpdate as i, type AgentCapabilities as j, type AuthMethod as k, type SessionId as l, type SessionInfo as m, type ACPCancelParams as n, type ACPCapabilities as o, type ACPChildProcess as p, type ACPError as q, type ACPImageContent as r, type ACPInitializeParams as s, type ACPInputSchema as t, type ACPNotification as u, type ACPPlanContent as v, type ACPPlanStep as w, type ACPProgressContent as x, type ACPRequest as y, type ACPResourceContent as z };

package/dist/agent.d.ts

@@ -1,72 +1,45 @@
-export { A as AgentServerTransport, S as StdioTransport } from './stdio-transport-CsFr8JzC.js';
-export { A as ACPToolsRegistry } from './tools-registry-BCf8evEG.js';
-import { R as RunTurn } 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 { Agent } from '@wrongstack/core';
+import { a as AgentServerTransport, b as ACPMessage } from './acp-v1-BxskPsdo.js';
+export { S as StdioTransport } from './acp-v1-BxskPsdo.js';
+export { A as ACPToolsRegistry } from './tools-registry-D2xdbzN7.js';
+export { A as ACPProtocolHandler, C as ClientCapabilities, R as RunTurn, g as RunTurnApi, a as RunTurnInput, h as RunTurnPermissionRequest, b as RunTurnResult, i as SessionPersistence, e as WrongStackACPServer, f as WrongStackACPServerOptions } from './wrongstack-acp-agent-nzrqmJnc.js';
+export { A as ACPServerAgentTurnOptions, a as ACPSessionStore, P as PersistedSession, S as SessionStoreOptions, m as makeACPServerAgentTurn } from './server-agent-turn-C3U0lhA-.js';
 import 'node:events';
+import '@wrongstack/core';
 
 /**
- * ACPServerAgentTurn — `RunTurn` adapter for the v1 server side.
+ * WsBridgeTransport — an `AgentServerTransport` backed by a single
+ * bidirectional message channel (one WebSocket connection).
  *
- * 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.
+ * Unlike stdio (a process-wide pipe driven by a read loop) or HTTP (one
+ * request/response per POST, notifications buffered), a WebSocket is a live
+ * full-duplex channel: the agent can stream `session/update` notifications
+ * and make `session/request_permission` callbacks WHILE a turn runs. This
+ * transport is the seam that lets `ACPProtocolHandler` drive one such
+ * connection.
  *
- * 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'}`.
+ * It is dependency-free and structural: the caller (the CLI, which already
+ * depends on `ws`) constructs it with a `send` sink and feeds inbound
+ * messages via `receive(msg)`. One handler + one transport per connection.
  */
 
-interface ACPServerAgentTurnOptions {
+declare class WsBridgeTransport implements AgentServerTransport {
+    private readonly sink;
+    private readonly handlers;
+    private closed;
+    /** @param sink Called with each outbound message to write to the socket. */
+    constructor(sink: (msg: ACPMessage) => void);
+    send(msg: ACPMessage): Promise<void>;
+    sendRaw(): void;
+    read(): Promise<ACPMessage | null>;
+    onMessage(handler: (msg: ACPMessage) => void): () => void;
+    close(): void;
     /**
-     * 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.
+     * Feed one inbound message from the socket. Fires the registered
+     * `onMessage` handlers (which route JSON-RPC responses to pending
+     * outbound requests inside the handler). Inbound *requests* are processed
+     * by the caller via `handler.handleMessage(msg)` — call both per message.
      */
-    agentFor: (sessionId: string, cwd: string) => 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;
+    receive(msg: ACPMessage): 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`.
- */
-declare function makeACPServerAgentTurn(opts: ACPServerAgentTurnOptions): RunTurn;
 
-export { type ACPServerAgentTurnOptions, makeACPServerAgentTurn };
+export { AgentServerTransport, WsBridgeTransport };