@agentproto/acp 0.1.0-alpha.2 → 0.2.0

package/dist/tunnel/index.d.ts

@@ -81,6 +81,10 @@ interface SpawnFrame {
      * line-delimited JSON-RPC.
      */
     pty?: boolean;
+    /** Initial PTY column width. Ignored when `pty` is false. Default 80. */
+    cols?: number;
+    /** Initial PTY row height. Ignored when `pty` is false. Default 24. */
+    rows?: number;
 }
 interface StdinFrame {
     t: "stdin";
@@ -130,6 +134,20 @@ interface HttpRequestFrame {
 /**
  * Generic HTTP-over-tunnel response (DAEMON → HOST). Mirrors
  * `HttpRequestFrame` — see its docs.
+ *
+ * Two-frame protocol:
+ *   - SHORT RESPONSES (most HTTP): daemon emits a single `http_response`
+ *     with body inline. The buffered `forwardHttp` resolves directly
+ *     from this frame.
+ *   - STREAMED RESPONSES (text/event-stream, long-lived chunked
+ *     transfers, large downloads): daemon emits `http_response_head`
+ *     first with status+headers, then one or more `http_response_chunk`
+ *     frames, the last of which has `end: true`. The streaming
+ *     `forwardHttpStream` builds a `ReadableStream` from the chunks.
+ *
+ * Hosts that only support the legacy buffered API can detect the
+ * stream protocol by looking for `http_response_head` and either
+ * pull the chunks into a buffer (compat) or refuse to handle.
  */
 interface HttpResponseFrame {
     t: "http_response";
@@ -146,6 +164,43 @@ interface HttpResponseFrame {
         message: string;
     }>;
 }
+/**
+ * Streaming HTTP response head (DAEMON → HOST). Sent ONCE per
+ * streaming response, before any chunk frames. Carries status +
+ * headers so the host can finalize the response shape (e.g. write
+ * Content-Type) before any body bytes arrive.
+ */
+interface HttpResponseHeadFrame {
+    t: "http_response_head";
+    reqId: string;
+    status: number;
+    headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Streaming HTTP response body chunk (DAEMON → HOST). Each chunk
+ * carries some bytes of the response body. The terminal chunk has
+ * `end: true` and MAY include final bytes. An immediate `end: true`
+ * with no data signals empty-body close.
+ *
+ * `error` set on a chunk frame indicates the daemon's upstream
+ * failed mid-stream; host SHOULD propagate it as a stream error.
+ */
+interface HttpResponseChunkFrame {
+    t: "http_response_chunk";
+    reqId: string;
+    /** Base64-encoded chunk bytes. Omitted on pure end-of-stream
+     *  markers (those carry `end: true` only). */
+    data?: string;
+    /** Set on the last chunk. After this frame the host SHOULD ignore
+     *  any further frames for this reqId. */
+    end?: boolean;
+    /** Set when the upstream failed mid-stream. Host surfaces this as
+     *  a stream error and closes the readable. */
+    error?: Readonly<{
+        code: string;
+        message: string;
+    }>;
+}
 interface HelloFrame {
     t: "hello";
     version: typeof TUNNEL_VERSION;
@@ -155,6 +210,19 @@ interface HelloFrame {
      */
     capabilities: Readonly<{
         pty: boolean;
+        /** Daemon can bridge browser-WS upgrades to its local upstream via
+         *  `ws_open` / `ws_message` / `ws_close`. Hosts MUST gate
+         *  `forwardWebSocket()` on this — older daemons ignore the frames. */
+        wsForward?: boolean;
+        /**
+         * Identifiers of the capabilities the daemon serves — its registered
+         * agent adapters / tool surfaces. Lets a host that fronts several
+         * daemons enumerate and route by what each one can do, without a
+         * round-trip. Omitted by older daemons (host treats as "unknown",
+         * not "none"). Advisory: the authoritative surface is still the
+         * daemon's live `tools/list` over the HTTP relay.
+         */
+        tools?: ReadonlyArray<string>;
     }>;
     /** User-friendly daemon label, surfaced in host UIs. */
     label?: string;
@@ -209,8 +277,105 @@ interface PongFrame {
     t: "pong";
     nonce: string;
 }
-type HostToDaemonFrame = SpawnFrame | StdinFrame | KillFrame | ResizeFrame | HttpRequestFrame | PingFrame | PongFrame | ErrorFrame;
-type DaemonToHostFrame = HelloFrame | SpawnedFrame | StdoutFrame | StderrFrame | ExitFrame | HttpResponseFrame | PingFrame | PongFrame | ErrorFrame;
+/**
+ * HOST → DAEMON. Graceful drain signal sent during host rollover (e.g.
+ * Kubernetes preStop). On receipt the daemon SHOULD:
+ *   1. Stop accepting new in-flight work where it can.
+ *   2. Close the WS cleanly (does not need to wait — host will follow
+ *      up with a `close(1012, "service_restart")` ~2 s later as a
+ *      hard backstop).
+ *   3. Reconnect IMMEDIATELY without the usual exponential backoff —
+ *      the host is mid-deploy, the new replica is already listening.
+ *
+ * Backward-compatible: daemons that don't know the frame just ignore
+ * it (parseFrame returns null for unknown types). The host's close
+ * then triggers the daemon's normal backoff loop — worst case ~30 s
+ * reconnect gap instead of ~2 s with the handler.
+ */
+interface ReconnectSoonFrame {
+    t: "reconnect_soon";
+    /** Hint of how long the host plans to wait before forcing close.
+     *  Optional — daemons MAY use it to decide whether to finish
+     *  in-flight work or close immediately. */
+    reasonMs?: number;
+}
+/**
+ * HOST → DAEMON. Open a WS connection to the daemon's upstream.
+ * Path semantics match `HttpRequestFrame` — absolute URLs rejected,
+ * daemon prepends its `ws://<upstream>` base. Headers forwarded as-is
+ * (cookies are typically NOT forwarded since the daemon's upstream is
+ * loopback; cookie passthrough is opt-in via daemon config).
+ */
+interface WsOpenFrame {
+    t: "ws_open";
+    /** Correlates every WS frame in both directions for this connection. */
+    reqId: string;
+    /** Path + querystring on the daemon-local upstream, e.g.
+     *  `/sessions/abc/pty?cols=80&rows=24`. */
+    path: string;
+    /** Optional registered upstream to dial instead of the daemon's
+     *  default gateway — a NAME the daemon resolves to a base URL (never
+     *  a URL itself, so the host can't point the daemon at an arbitrary
+     *  origin). Used to reach an imported local service (e.g. a browser
+     *  capability server) by alias. Absent ⇒ the daemon's own gateway. */
+    upstream?: string;
+    /** Headers to set on the upstream WS request. Hop-by-hop headers
+     *  (Connection, Upgrade, Sec-WebSocket-*) MUST be stripped — the
+     *  daemon's `ws` client manages those. */
+    headers?: Readonly<Record<string, string>>;
+    /** Subprotocols requested by the browser; forwarded to upstream. */
+    protocols?: readonly string[];
+}
+/**
+ * DAEMON → HOST. Result of a `ws_open`. On success the upstream WS is
+ * connected and frames can flow. On failure `error` is set; no further
+ * frames for this `reqId` will arrive.
+ */
+interface WsOpenAckFrame {
+    t: "ws_open_ack";
+    reqId: string;
+    /** HTTP status from the upstream upgrade. 101 on success; 4xx/5xx
+     *  when the upstream refused the upgrade. */
+    status: number;
+    /** Selected subprotocol, if any. */
+    protocol?: string;
+    /** Set when the daemon couldn't open the upstream (DNS failure,
+     *  refused, timeout). Distinct from a clean upstream-side close,
+     *  which arrives as `ws_close`. */
+    error?: Readonly<{
+        code: string;
+        message: string;
+    }>;
+}
+/**
+ * Either direction. One application-level WS frame's payload. Text
+ * frames carry UTF-8 bytes (`binary: false`); binary frames carry
+ * arbitrary bytes (`binary: true`). The `data` field is base64-encoded
+ * either way so the transport stays JSON.
+ */
+interface WsMessageFrame {
+    t: "ws_message";
+    reqId: string;
+    /** Base64-encoded WS frame payload. */
+    data: string;
+    /** True for binary frames; false (or omitted) for text. */
+    binary?: boolean;
+}
+/**
+ * Either direction. Close the bridged WS connection. Includes the
+ * close code (1000 normal, 1006 abnormal, etc.) and optional reason.
+ * After sending or receiving this frame, neither side will send
+ * further frames for `reqId`.
+ */
+interface WsCloseFrame {
+    t: "ws_close";
+    reqId: string;
+    /** WebSocket close code. */
+    code: number;
+    reason?: string;
+}
+type HostToDaemonFrame = SpawnFrame | StdinFrame | KillFrame | ResizeFrame | HttpRequestFrame | WsOpenFrame | WsMessageFrame | WsCloseFrame | PingFrame | PongFrame | ErrorFrame | ReconnectSoonFrame;
+type DaemonToHostFrame = HelloFrame | SpawnedFrame | StdoutFrame | StderrFrame | ExitFrame | HttpResponseFrame | HttpResponseHeadFrame | HttpResponseChunkFrame | WsOpenAckFrame | WsMessageFrame | WsCloseFrame | PingFrame | PongFrame | ErrorFrame;
 type TunnelFrame = HostToDaemonFrame | DaemonToHostFrame;
 /**
  * Parse a raw WS message into a `TunnelFrame`. Returns null when the
@@ -271,6 +436,19 @@ interface FrameSink {
  * and can mutate it (e.g. force `cwd` into a workspace) or reject.
  */
 
+/**
+ * Default ceiling for an upstream WS dial. An upstream that accepts the TCP
+ * connection but never completes (or rejects) the WebSocket upgrade would
+ * otherwise leave the `ws_open` pending forever — the host never gets an ack or
+ * a reject. Bounded so a hung upstream surfaces as a 504 instead.
+ */
+declare const DEFAULT_WS_DIAL_TIMEOUT_MS = 10000;
+/**
+ * Default ceiling for an `http_request` forward when the frame carries no
+ * `timeoutMs`. Covers connect + buffered body (or connect + headers for a
+ * stream, after which the bound is handed to `httpStreamIdleTimeoutMs`).
+ */
+declare const DEFAULT_HTTP_FORWARD_TIMEOUT_MS = 30000;
 interface TunnelServerOptions {
     sink: FrameSink;
     /**
@@ -291,14 +469,49 @@ interface TunnelServerOptions {
      * `error: { code: "http_upstream_not_configured" }`.
      */
     httpUpstream?: string;
+    /**
+     * Default ceiling for an `http_request` forward (connect + buffered body, or
+     * connect + headers for a stream) when the frame carries no `timeoutMs`.
+     * Defaults to DEFAULT_HTTP_FORWARD_TIMEOUT_MS. Disarmed once a streaming
+     * response is detected — see `httpStreamIdleTimeoutMs` for the stream phase.
+     */
+    httpForwardTimeoutMs?: number;
+    /**
+     * Idle ceiling between chunks of a STREAMING response (SSE / ndjson). A
+     * stalled upstream that sends headers then hangs forever between chunks would
+     * otherwise block indefinitely (the regular timeout is disarmed for streams,
+     * since they're long-lived by design). Counts time since the last byte and
+     * resets on every chunk, so a heartbeating stream is never cut. Omitted ⇒ no
+     * idle bound (current behaviour); set it to guard against silent stalls.
+     */
+    httpStreamIdleTimeoutMs?: number;
     /** User-friendly label sent in the hello frame. */
     label?: string;
     /**
-     * Whether this daemon advertises PTY support. v0 always reports
-     * false — PTY allocation needs node-pty (optional dep) and we
-     * haven't wired that side yet.
+     * Capability identifiers advertised in the hello frame — the agent
+     * adapters / tool surfaces this daemon serves (e.g. the gateway's
+     * registered adapter ids). Lets a multi-daemon host enumerate and
+     * route by capability without a round-trip. Omit to advertise none.
+     */
+    tools?: ReadonlyArray<string>;
+    /**
+     * Whether this daemon advertises PTY support. Set to true only when
+     * `spawnPty` is also provided.
      */
     pty?: boolean;
+    /**
+     * Factory for PTY-backed processes. When provided (and `pty: true`),
+     * spawn frames with `pty: true` use this instead of node:child_process.
+     * Injected from the CLI layer so the ACP package stays native-free.
+     */
+    spawnPty?: (opts: {
+        command: string;
+        args: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+        cols: number;
+        rows: number;
+    }) => PtyProcess;
     /**
      * Optional hook fired once per successful spawn — after authorize
      * passed and the ChildProcess has emitted its `spawn` event.
@@ -316,6 +529,89 @@ interface TunnelServerOptions {
         child: ChildProcess;
         request: SpawnFrame;
     }) => void;
+    /**
+     * Optional hook fired when the host sends a `reconnect_soon` frame —
+     * graceful drain signal during host rollover. The daemon SHOULD
+     * close + reconnect immediately (skipping any backoff) so the new
+     * host replica picks it up. Default: ignore (the host follows up
+     * with `close(1012)` and the daemon's own reconnect supervisor
+     * handles it via normal backoff, ~30 s gap).
+     *
+     * Implementations typically call into their connection supervisor
+     * to mark the next reconnect as "no-backoff" then close the sink.
+     * `reasonMs` is the host's hint for how long it will wait before
+     * forcing close — daemons MAY use it to drain in-flight RPCs first.
+     */
+    onReconnectSoon?: (info: {
+        reasonMs?: number;
+    }) => void;
+    /**
+     * Factory that dials a WS connection to the local upstream. When
+     * provided (and `httpUpstream` is set), the daemon advertises
+     * `wsForward` capability and handles `ws_open` frames by piping the
+     * upstream WS through the tunnel. Injected so `@agentproto/acp`
+     * stays free of a hard `ws` dependency — the CLI provides this
+     * factory using its already-pulled-in `ws` package.
+     */
+    dialUpstreamWs?: (params: {
+        url: string;
+        protocols?: readonly string[];
+        headers?: Readonly<Record<string, string>>;
+        /**
+         * Aborted when the dial exceeds `wsDialTimeoutMs` (or the tunnel tears down
+         * mid-dial). A cooperating implementation SHOULD abort the in-flight upgrade
+         * and reject so the socket isn't left half-open; even if it doesn't, the
+         * server bounds the wait independently and rejects the `ws_open`.
+         */
+        signal?: AbortSignal;
+    }) => Promise<UpstreamWebSocket>;
+    /**
+     * Ceiling for `dialUpstreamWs` to resolve before the `ws_open` is rejected
+     * with 504 `upstream_ws_timeout`. Defaults to DEFAULT_WS_DIAL_TIMEOUT_MS.
+     */
+    wsDialTimeoutMs?: number;
+    /**
+     * Resolve a named upstream (a `ws_open` frame's `upstream` field) to an
+     * HTTP base URL the daemon should dial instead of `httpUpstream`. Lets a
+     * host reach an imported local service by alias (e.g. a browser capability
+     * server) without ever naming a raw origin — the daemon owns the name→URL
+     * mapping. Return undefined for an unknown alias (the open is rejected).
+     * Omitted ⇒ every `ws_open` dials the default `httpUpstream`.
+     */
+    resolveWsUpstream?: (upstream: string) => string | undefined | Promise<string | undefined>;
+}
+/**
+ * Minimal upstream WS surface — satisfied by the `ws` library's
+ * client socket. Daemons supplying `dialUpstreamWs` resolve into
+ * one of these as soon as the WS is OPEN. `protocol` is the
+ * subprotocol negotiated by the upstream (empty string when none).
+ */
+interface UpstreamWebSocket {
+    readonly protocol: string;
+    /** Send a frame to the upstream. */
+    send(data: Buffer | string, opts: {
+        binary: boolean;
+    }): void;
+    /** Close the upstream connection. */
+    close(code?: number, reason?: string): void;
+    /** Subscribe to inbound frames. */
+    onMessage(handler: (data: Buffer, isBinary: boolean) => void): void;
+    /** Subscribe to upstream close. */
+    onClose(handler: (code: number, reason: string) => void): void;
+    /** Subscribe to transport errors. */
+    onError(handler: (err: Error) => void): void;
+}
+/** Minimal PTY process surface — satisfied by node-pty's IPty. */
+interface PtyProcess {
+    readonly pid: number;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    onData(handler: (data: string) => void): void;
+    onExit(handler: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => void): void;
 }
 interface TunnelServer {
     /** Currently-live execId → ChildProcess. Read-only diagnostic. */
@@ -352,6 +648,16 @@ interface TunnelHttpResponse {
         message: string;
     }>;
 }
+/** Resolved response from `forwardHttpStream`. Body is a Web
+ *  `ReadableStream<Uint8Array>` — consume it to receive chunks as
+ *  they arrive from the daemon's upstream (SSE, long-poll, NDJSON).
+ *  The stream closes when the daemon's upstream closes OR an upstream
+ *  error occurs (surfaced as a stream error on the reader). */
+interface TunnelHttpStreamResponse {
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    body: ReadableStream<Uint8Array>;
+}
 interface TunnelHttpRequest {
     method: string;
     path: string;
@@ -360,6 +666,48 @@ interface TunnelHttpRequest {
     /** Per-request timeout in ms. Default 30_000. */
     timeoutMs?: number;
 }
+interface TunnelWebSocketOpenRequest {
+    /** Path + querystring on the daemon-local upstream. Daemon prepends
+     *  its `ws://<upstream>` base; absolute URLs are rejected. */
+    path: string;
+    /** Optional registered upstream to dial instead of the daemon's default
+     *  gateway — a NAME the daemon resolves to a base URL (e.g. an imported
+     *  service alias). The host never names a raw origin. */
+    upstream?: string;
+    /** Headers forwarded to the upstream upgrade. Hop-by-hop / Sec-* are
+     *  stripped by the daemon. Cookies are NOT forwarded unless the
+     *  daemon was started with `--upstream-cookies`. */
+    headers?: Readonly<Record<string, string>>;
+    /** Subprotocols requested. Echoed in `protocol` on success. */
+    protocols?: readonly string[];
+    /** How long to wait for the upstream upgrade before erroring. The
+     *  message stream itself has no timeout (WS lives as long as either
+     *  end keeps it open). Default 30_000. */
+    openTimeoutMs?: number;
+}
+/**
+ * Bridged WS connection. Mirrors the surface of a browser WebSocket
+ * minus URL/protocol bookkeeping — the host already chose those when
+ * calling `forwardWebSocket`. Messages are typed as text (UTF-8 string)
+ * or binary (Uint8Array); the bridge preserves the upstream's framing.
+ */
+interface TunnelWebSocket {
+    /** True until `close` runs in either direction. */
+    readonly readyState: "open" | "closing" | "closed";
+    /** Selected subprotocol from the upstream's upgrade response, if any. */
+    readonly protocol: string | null;
+    /** Send a frame to the daemon's upstream. No-op when not open. */
+    send(data: string | Uint8Array): void;
+    /** Initiate a clean close. Idempotent. */
+    close(code?: number, reason?: string): void;
+    /** Subscribe to inbound frames. Returns an unsubscribe fn. */
+    onMessage(listener: (data: Buffer, isBinary: boolean) => void): () => void;
+    /** Subscribe to close. Fires exactly once (after either side closes
+     *  OR the tunnel itself drops). Returns an unsubscribe fn. */
+    onClose(listener: (code: number, reason: string) => void): () => void;
+    /** Subscribe to transport-level errors. Closes follow shortly. */
+    onError(listener: (err: Error) => void): () => void;
+}
 interface TunnelClientOptions {
     sink: FrameSink;
     /**
@@ -374,6 +722,10 @@ interface TunnelSpawnOptions {
     env?: Readonly<Record<string, string>>;
     /** Allocate a PTY on the daemon. Requires `hello.capabilities.pty`. */
     pty?: boolean;
+    /** Initial PTY column width (ignored when `pty` is false). Default 80. */
+    cols?: number;
+    /** Initial PTY row height (ignored when `pty` is false). Default 24. */
+    rows?: number;
 }
 /**
  * Minimal ChildProcess-shaped duck. Covers the surface our ACP arm
@@ -389,6 +741,8 @@ interface TunnelChildProcess {
     on(event: "exit", listener: (code: number | null, signal: string | null) => void): this;
     on(event: "error", listener: (err: Error) => void): this;
     kill(signal?: NodeJS.Signals | number): boolean;
+    /** Send a terminal resize to the daemon. No-op if the exec isn't PTY-backed. */
+    resize(cols: number, rows: number): void;
 }
 interface TunnelClient {
     /**
@@ -405,8 +759,31 @@ interface TunnelClient {
      * which this promise resolves to. Rejects on tunnel-transport
      * failure; the daemon-reported HTTP status (incl. 5xx) is returned
      * in the resolved value.
+     *
+     * Streaming responses (text/event-stream, NDJSON) are buffered into
+     * the returned Buffer. For real streaming, use `forwardHttpStream`.
      */
     forwardHttp(req: TunnelHttpRequest): Promise<TunnelHttpResponse>;
+    /**
+     * Stream an HTTP response through the tunnel. The promise resolves
+     * as soon as the response head (status + headers) arrives — the
+     * body chunks then flow through `body` (a ReadableStream) until the
+     * daemon's upstream closes. Required for SSE / NDJSON / long-poll
+     * upstreams where buffering until the end would defeat the point.
+     * For one-shot HTTP, prefer `forwardHttp`.
+     */
+    forwardHttpStream(req: TunnelHttpRequest): Promise<TunnelHttpStreamResponse>;
+    /**
+     * Open a bridged WebSocket through the tunnel. The promise resolves
+     * once the daemon has completed the upstream upgrade; from that
+     * point messages flow via the returned `TunnelWebSocket`.
+     *
+     * Rejects on:
+     *   - missing `hello.capabilities.wsForward` — older daemon, no bridge
+     *   - upstream upgrade failure (4xx/5xx) — `cause` carries the status
+     *   - timeout waiting for `ws_open_ack`
+     */
+    forwardWebSocket(req: TunnelWebSocketOpenRequest): Promise<TunnelWebSocket>;
     close(): Promise<void>;
 }
 declare function createTunnelClient(opts: TunnelClientOptions): TunnelClient;
@@ -439,4 +816,4 @@ interface WebSocketLike {
 }
 declare function wrapWebSocket(ws: WebSocketLike): FrameSink;
 
-export { type DaemonToHostFrame, type ErrorFrame, type ExitFrame, type FrameSink, type HelloFrame, type HostToDaemonFrame, type KillFrame, type PingFrame, type PongFrame, type ResizeFrame, type SpawnFrame, type SpawnedFrame, type StderrFrame, type StdinFrame, type StdoutFrame, TUNNEL_VERSION, type TunnelChildProcess, type TunnelClient, type TunnelClientOptions, type TunnelFrame, type TunnelServer, type TunnelServerOptions, type TunnelSpawnOptions, type WebSocketLike, createTunnelClient, createTunnelServer, decodeData, encodeData, encodeFrame, parseFrame, wrapWebSocket };
+export { DEFAULT_HTTP_FORWARD_TIMEOUT_MS, DEFAULT_WS_DIAL_TIMEOUT_MS, type DaemonToHostFrame, type ErrorFrame, type ExitFrame, type FrameSink, type HelloFrame, type HostToDaemonFrame, type KillFrame, type PingFrame, type PongFrame, type PtyProcess, type ReconnectSoonFrame, type ResizeFrame, type SpawnFrame, type SpawnedFrame, type StderrFrame, type StdinFrame, type StdoutFrame, TUNNEL_VERSION, type TunnelChildProcess, type TunnelClient, type TunnelClientOptions, type TunnelFrame, type TunnelHttpRequest, type TunnelHttpResponse, type TunnelHttpStreamResponse, type TunnelServer, type TunnelServerOptions, type TunnelSpawnOptions, type TunnelWebSocket, type TunnelWebSocketOpenRequest, type UpstreamWebSocket, type WebSocketLike, type WsCloseFrame, type WsMessageFrame, type WsOpenAckFrame, type WsOpenFrame, createTunnelClient, createTunnelServer, decodeData, encodeData, encodeFrame, parseFrame, wrapWebSocket };