@cleocode/runtime 2026.10.4 → 2026.10.5

package/dist/gateway/http/index.d.ts

@@ -1,11 +1,897 @@
-export { G as GateDecision, a as GatewayStreamSource, H as HttpServerHandle, b as HttpServerOptions, c as HttpUnaryRequest, d as HttpUnaryResult, N as NODE_PTY_INSTALL_HINT, S as SSE_HEADERS, e as STUDIO_PREFIX, f as SseEmitter, g as SseFrame, h as SseSource, i as StreamSourceContext, j as StreamSourceTeardown, k as StudioStaticOptions, U as UpgradableServer, W as WS_PTY_PATH, l as WsPtyEndpointHandle, m as WsPtyOptions, n as attachWsPtyEndpoint, o as authorizeUpgrade, p as computeAcceptKey, q as createSseStream, r as decodeWsFrame, s as encodeSseFrame, t as encodeStreamEvent, u as encodeWsFrame, v as isStudioPath, w as isWsPtyPath, x as loadNodePty, y as mimeType, z as parseHttpRoute, A as registerStreamSource, B as resolveStreamSource, C as resolveStudioAssetPath, D as resolveStudioStaticDir, E as routeUnary, F as scrubPtyEnv, I as serveStudioStatic, J as startHttpServer, K as statusForResponse, L as tickStreamSource, M as writeBundleAbsentError } from '../rpc/index.js';
-import '@cleocode/contracts/gateway';
-import '@cleocode/core/store/background-jobs.js';
-import '@cleocode/contracts';
-import 'node:http';
-import '@cleocode/contracts/operations/orchestrate';
-import '@cleocode/core/internal';
-import '@cleocode/core';
-import '@cleocode/contracts/gateway/rpc';
-import 'node:net';
-import 'node:stream';
+import { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { Gateway, DispatchResponse, GatewayStreamEvent } from '@cleocode/contracts/gateway';
+import { Duplex } from 'node:stream';
+import { G as GatewayHandler } from '../../gateway-handler-DCU6E0a2.js';
+
+/**
+ * WebSocket terminal/PTY endpoint on the `/v1` gateway HTTP listener (T11922 ·
+ * M5 realtime transport, WS half).
+ *
+ * The SSE half (T11921) gives the gateway a SERVER→CLIENT push stream; this
+ * module adds the BIDIRECTIONAL realtime transport an interactive TUI / terminal
+ * session needs: a WebSocket upgrade on the SAME `node:http` listener
+ * ({@link import('./listen.js').startHttpServer}) that bridges a PTY both
+ * directions over WS frames.
+ *
+ * Design constraints (all four ACs of T11922):
+ *
+ *  - **AC1 — upgrade on the existing listener.** The WS endpoint is NOT a second
+ *    server: it attaches to the daemon's existing HTTP server via its
+ *    `'upgrade'` event ({@link attachWsPtyEndpoint}), so it inherits the loopback
+ *    bind + the daemon's lifecycle. The endpoint path is `/v1/terminal/pty`.
+ *  - **AC2 — bidirectional PTY bridge with backpressure.** Inbound WS frames are
+ *    written to the PTY stdin; PTY output is framed back to the client. A control
+ *    frame (`{type:'resize',cols,rows}`) resizes the PTY. Backpressure is honored
+ *    on the socket write path (pause-on-`false`-write, resume on `'drain'`).
+ *  - **AC3 — leak-free, deterministic teardown.** Every open/close/error/abort
+ *    path routes through ONE idempotent `teardown()` that kills the PTY, removes
+ *    its listeners, and ends the socket exactly once. A server `close()` tears
+ *    down every live session.
+ *  - **AC4 — auth/origin enforced at the upgrade edge; no secrets on the wire.**
+ *    The upgrade is rejected with a `401`/`403` BEFORE any PTY is spawned unless
+ *    it comes from loopback AND (when a token is configured) presents the bearer
+ *    token AND (when an origin allowlist is configured) presents an allowed
+ *    `Origin`. The spawned PTY runs under a MINIMAL, explicitly-constructed env
+ *    ({@link scrubPtyEnv}) — the daemon's secret-bearing `process.env` is NEVER
+ *    inherited, so a secret cannot be exfiltrated through the terminal stream.
+ *
+ * To keep the **publish surface clean** (D11142 dependency-discipline):
+ *  - There is NO `ws` dependency. The minimal RFC 6455 server framing needed
+ *    (accept handshake, decode masked client frames, encode unmasked server
+ *    frames, close/ping/pong) is implemented over the raw `node:net` socket the
+ *    `'upgrade'` event hands us. This adds ZERO weight to `@cleocode/runtime`.
+ *  - `node-pty` is an OPTIONAL, dynamically-loaded dependency (same pattern as
+ *    {@link import('../../../../core/src/llm/pi/gondolin-loader.js')} and
+ *    `packages/core/src/tools/pty.ts`): the npm specifier is held in a variable,
+ *    its shape is declared LOCALLY (no `import type`), and absence is a graceful
+ *    close frame ("PTY backend unavailable") — NOT a crash. The endpoint always
+ *    upgrades; it bridges a PTY only when the backend is present.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http/ws-pty
+ *
+ * @task T11922
+ * @epic T11769
+ * @saga T10400
+ * @see ./sse.ts — the SSE half (server→client push) on the same listener
+ */
+
+/** The canonical WS terminal/PTY endpoint path on the `/v1` facade. */
+declare const WS_PTY_PATH = "/v1/terminal/pty";
+/**
+ * The install hint surfaced to the client (as a WS close reason) when the PTY
+ * backend is unavailable. `node-pty` is OPTIONAL — the endpoint still upgrades
+ * and then closes cleanly with this reason rather than crashing the daemon.
+ */
+declare const NODE_PTY_INSTALL_HINT: string;
+/** A disposable subscription handle returned by `node-pty`'s event registrars. */
+interface PtyDisposable {
+    dispose(): void;
+}
+/** The minimal structural shape of a spawned `node-pty` process the bridge uses. */
+interface NodePtyProcess {
+    /** Subscribe to interleaved stdout/stderr output. */
+    onData(cb: (data: string) => void): PtyDisposable | undefined;
+    /** Subscribe to process exit. */
+    onExit(cb: (e: {
+        exitCode: number;
+        signal?: number;
+    }) => void): PtyDisposable | undefined;
+    /** Write to the PTY stdin. */
+    write(data: string): void;
+    /** Resize the PTY. */
+    resize(cols: number, rows: number): void;
+    /** Kill the underlying process (idempotent host-side; signal optional). */
+    kill(signal?: string): void;
+}
+/** The minimal structural shape of the `node-pty` module the bridge uses. */
+interface NodePtyModule {
+    spawn(file: string, args: readonly string[], options: {
+        readonly name?: string;
+        readonly cols?: number;
+        readonly rows?: number;
+        readonly cwd?: string;
+        readonly env?: Record<string, string>;
+    }): NodePtyProcess;
+}
+/**
+ * Attempt to lazily load `node-pty`. Returns `null` when the optional dep is not
+ * installed, fails to load, or does not expose the `spawn` surface — so the
+ * caller closes the WS cleanly with {@link NODE_PTY_INSTALL_HINT} instead of
+ * crashing. NEVER throws.
+ *
+ * The import specifier is held in a variable (passed to the {@link importer}
+ * seam) so bundlers / TS do not treat the missing optional dep as a hard,
+ * statically-resolved dependency (same technique as the gondolin loader).
+ *
+ * @returns The shape-checked module, or `null` when unavailable.
+ */
+declare function loadNodePty(): Promise<NodePtyModule | null>;
+/**
+ * Build the MINIMAL environment the bridged PTY runs under (AC4).
+ *
+ * Starts EMPTY, copies only the small {@link PASSTHROUGH_KEYS} allowlist from the
+ * parent, pins `PATH` to {@link TRUSTED_PATH}, and forces `TERM=xterm-256color`
+ * for a sane terminal. The daemon's secrets are NEVER forwarded.
+ *
+ * @param parentEnv - The parent process environment (defaults to `process.env`).
+ * @returns The scrubbed, secret-free env for the PTY.
+ */
+declare function scrubPtyEnv(parentEnv?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Derive the `Sec-WebSocket-Accept` response header value from a client
+ * `Sec-WebSocket-Key` per RFC 6455 §4.2.2 (SHA-1 of key + GUID, base64).
+ *
+ * @param key - The client's `Sec-WebSocket-Key` header value.
+ * @returns The base64 accept hash.
+ */
+declare function computeAcceptKey(key: string): string;
+/**
+ * Encode a WS data frame (server→client, UNMASKED per RFC 6455 §5.1). Used for
+ * `text` (PTY output) and `close` control frames.
+ *
+ * @param opcode - The WS opcode (e.g. {@link OPCODE_TEXT}).
+ * @param payload - The frame payload bytes.
+ * @returns The framed bytes ready to write to the socket.
+ */
+declare function encodeWsFrame(opcode: number, payload: Buffer): Buffer;
+/** One decoded inbound WS frame. */
+interface DecodedFrame {
+    /** The frame opcode. */
+    opcode: number;
+    /** The unmasked payload bytes. */
+    payload: Buffer;
+    /** Total bytes consumed from the input buffer (header + payload). */
+    consumed: number;
+}
+/**
+ * Decode a single inbound (client→server, MASKED) WS frame from a buffer.
+ *
+ * Returns `null` when the buffer does not yet hold a complete frame (the caller
+ * waits for more bytes). Client frames MUST be masked (RFC 6455 §5.3); the mask
+ * is applied to recover the payload. Fragmentation is not expected from a
+ * terminal client, so a non-FIN frame is decoded as-is (its opcode handled by
+ * the caller). NEVER throws on a partial buffer.
+ *
+ * @param buf - The accumulated inbound bytes.
+ * @returns The decoded frame, or `null` when more bytes are needed.
+ */
+declare function decodeWsFrame(buf: Buffer): DecodedFrame | null;
+/** Configuration for the WS terminal/PTY endpoint. */
+interface WsPtyOptions {
+    /**
+     * Optional bearer token an upgrade MUST present (as `Authorization: Bearer
+     * <token>` or `?token=<token>`). When omitted, no token is required (loopback
+     * is still enforced unconditionally).
+     */
+    token?: string;
+    /**
+     * Optional `Origin` allowlist. When non-empty, an upgrade MUST present an
+     * `Origin` header whose value is in the set, else it is rejected `403`. When
+     * omitted/empty, the `Origin` header is not checked (loopback already bounds
+     * the surface).
+     */
+    allowedOrigins?: readonly string[];
+    /** The shell launched for the PTY (default `process.env.SHELL` or `/bin/sh`). */
+    shell?: string;
+    /** Working directory for the PTY (default `process.cwd()`). */
+    cwd?: string;
+}
+/** The decision of the upgrade-edge gate. */
+type GateDecision = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    reason: string;
+};
+/**
+ * Authorize a WS upgrade at the edge (AC4) — BEFORE any PTY is spawned.
+ *
+ * Enforced unconditionally:
+ *  - the connection MUST originate from loopback (`127.0.0.1` / `::1`); a
+ *    non-loopback peer is rejected `403` (the gateway is local-process-facing).
+ *
+ * Enforced when configured:
+ *  - a `token` (matched against `Authorization: Bearer` or `?token=`); a missing
+ *    or mismatched token is rejected `401`.
+ *  - an `Origin` allowlist; a missing or disallowed `Origin` is rejected `403`.
+ *
+ * @param req - The inbound upgrade request.
+ * @param remoteAddress - The socket's remote address.
+ * @param opts - The endpoint auth configuration.
+ * @returns A {@link GateDecision} — `{ok:true}` to proceed, else a typed reject.
+ */
+declare function authorizeUpgrade(req: IncomingMessage, remoteAddress: string | undefined, opts: WsPtyOptions): GateDecision;
+/** Whether a request path is the WS terminal/PTY endpoint. */
+declare function isWsPtyPath(url: string | undefined): boolean;
+/**
+ * A handle returned by {@link attachWsPtyEndpoint} so the caller can detach the
+ * `'upgrade'` listener and tear down every live session on server close (AC3).
+ */
+interface WsPtyEndpointHandle {
+    /** The number of live WS-PTY sessions (for tests / health). */
+    readonly sessionCount: number;
+    /** Detach the listener and tear down every live session. Idempotent. */
+    close(): void;
+}
+/**
+ * The shape of the HTTP server's `'upgrade'` event surface this module needs.
+ * Declared structurally so the module does not couple to a concrete `Server`.
+ */
+interface UpgradableServer {
+    on(event: 'upgrade', listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): void;
+    removeListener(event: 'upgrade', listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): void;
+}
+/**
+ * Attach the WS terminal/PTY endpoint (AC1) to an existing HTTP server's
+ * `'upgrade'` event.
+ *
+ * Every upgrade to {@link WS_PTY_PATH} is gated ({@link authorizeUpgrade}, AC4)
+ * BEFORE any PTY is spawned; a rejected upgrade gets a raw `401`/`403` and the
+ * socket is destroyed. An accepted upgrade completes the RFC 6455 handshake and
+ * bridges a PTY bidirectionally ({@link bridgePty}, AC2). An upgrade to any OTHER
+ * path is left for other upgrade handlers (this listener only claims its own
+ * path and never destroys a foreign socket).
+ *
+ * Each live session is tracked so {@link WsPtyEndpointHandle.close} tears every
+ * one down deterministically on server close (AC3).
+ *
+ * @param server - The HTTP server whose `'upgrade'` event to attach to.
+ * @param opts - The endpoint auth + PTY configuration.
+ * @returns A handle to detach + tear down on server close.
+ */
+declare function attachWsPtyEndpoint(server: UpgradableServer, opts?: WsPtyOptions): WsPtyEndpointHandle;
+
+/**
+ * `node:http` server binding for the framework-agnostic HTTP gateway adapter.
+ *
+ * The HTTP adapter ({@link routeUnary} + the SSE primitives) is deliberately
+ * framework-agnostic — it owns NO port binding and NO `Request`/`Response`
+ * lifecycle, so an embedder (a SvelteKit route, a test harness) can drive it
+ * directly. The **daemon**, however, is itself the embedder: it must expose the
+ * gateway to external HTTP clients over a real listening socket. This module is
+ * that thin embedder — a minimal `node:http` server that parses the request URL
+ * into a `(gateway, domain, operation)` triple, reads the JSON body, and routes
+ * it through {@link routeUnary}. It deliberately stays in the runtime (no
+ * SvelteKit / no `@cleocode/cleo` / no drizzle dependency) so the daemon can
+ * host the gateway without reaching across a package boundary.
+ *
+ * Routing contract (intentionally minimal — the wire vocabulary is the same as
+ * every other transport, only the framing differs):
+ *
+ *   `POST /<gateway>/<domain>/<operation>`  with a JSON body → operation params
+ *
+ * where `<gateway>` is `query` | `mutate`. A non-POST method, an unparseable
+ * path, or a body that is not a JSON object is rejected at the wire edge with a
+ * LAFS-shaped error envelope — the injected {@link GatewayHandler} is never
+ * invoked with a malformed request.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http
+ *
+ * @task T11451
+ * @epic T11254
+ * @saga T11243 SG-RUNTIME-UNIFICATION
+ */
+
+/**
+ * Options for {@link startHttpServer}.
+ *
+ * Mirrors the connection-oriented {@link RpcServerOptions} shape: the caller
+ * resolves the bind coordinates so the runtime stays free of any
+ * `@cleocode/paths` dependency.
+ */
+interface HttpServerOptions {
+    /**
+     * TCP port to bind. `0` selects an ephemeral port (the bound port is then
+     * readable from {@link HttpServerHandle.port}).
+     */
+    port: number;
+    /**
+     * Host/interface to bind. Defaults to `127.0.0.1` (loopback only) — the
+     * gateway is local-process-facing; exposing it on a public interface is an
+     * explicit caller decision.
+     */
+    host?: string;
+    /**
+     * WebSocket terminal/PTY endpoint configuration (T11922 · M5 WS half). When
+     * provided, a WS upgrade handler for {@link WS_PTY_PATH} (`/v1/terminal/pty`)
+     * is attached to this server's `'upgrade'` event — gated at the edge (loopback
+     * + optional token/origin) and bridging a PTY bidirectionally over WS frames.
+     * When OMITTED, no upgrade handler is attached and the server stays a pure
+     * unary+SSE HTTP listener (the capability is opt-in — the daemon enables it
+     * explicitly). The optional `node-pty` backend is loaded dynamically; if it is
+     * absent, the endpoint still upgrades and reports a clean "PTY backend
+     * unavailable" close rather than crashing.
+     */
+    wsPty?: WsPtyOptions;
+    /**
+     * Studio static asset directory for the bundled Web Studio (T11979).
+     *
+     * When provided, requests whose path starts with `/studio` are served as
+     * static files from this directory (the `build/client/` output from an
+     * `adapter-node` Studio build), with SPA fallback to `index.html` for
+     * sub-routes. When `undefined` or the path does not exist on disk, a clean
+     * JSON 503 envelope is returned instead of a stack trace — allowing the
+     * gateway to start without a Studio bundle present (dev checkouts).
+     *
+     * The value is resolved and injected by the caller (`cleo daemon serve`)
+     * using {@link resolveStudioStaticDir} from `@cleocode/cleo` so the runtime
+     * layer stays free of any path-resolution logic.
+     */
+    studioStaticDir?: string;
+}
+/**
+ * A live HTTP server handle returned by {@link startHttpServer}.
+ *
+ * Exposes the bound {@link Server}, the actually-bound `port` (resolved even
+ * when `0` was requested), and an idempotent {@link close}. The adapter never
+ * calls `process.exit` — lifecycle stays with the caller (R3 contract).
+ */
+interface HttpServerHandle {
+    /** The bound `node:http` server. */
+    server: Server;
+    /** The actually-bound TCP port (resolved when `0` was requested). */
+    port: number;
+    /** Host/interface the server is bound to. */
+    host: string;
+    /** Close the server + all live connections; resolves once fully closed. */
+    close(): Promise<void>;
+}
+/**
+ * The result of parsing a request line into routing coordinates: a resolved
+ * unary triple, a recognized health probe, or a rejection for the wire edge.
+ */
+type ParsedRoute = {
+    ok: true;
+    kind: 'unary';
+    gateway: Gateway;
+    domain: string;
+    operation: string;
+} | {
+    ok: true;
+    kind: 'stream';
+    gateway: Gateway;
+    domain: string;
+    operation: string;
+} | {
+    ok: true;
+    kind: 'health';
+} | {
+    ok: false;
+    status: number;
+    code: string;
+    message: string;
+};
+/**
+ * Parse a gateway request line into a routing decision.
+ *
+ * Two POST routing vocabularies are accepted (the wire payload is identical to
+ * every other transport — only the framing differs):
+ *
+ *   - `POST /v1/<domain>/<operation>` — the **versioned REST facade** (T11919).
+ *     The gateway (`query` | `mutate`) is INFERRED from the registry, so the
+ *     client need not name it. An unregistered `(domain, operation)` pair is a
+ *     `404`.
+ *   - `POST /<gateway>/<domain>/<operation>` — the **legacy** form, where the
+ *     client names the gateway segment explicitly (validated against the two
+ *     CQRS gateways so a client cannot smuggle an arbitrary value).
+ *
+ * Two GET routing vocabularies are accepted:
+ *
+ *   - `GET /v1/health` — the liveness probe.
+ *   - `GET /v1/<domain>/<operation>` — the **SSE streaming** endpoint (T11921),
+ *     recognized only when the `(domain, operation)` pair is registered AND
+ *     flagged `streaming: true` in {@link OPERATIONS} (resolved via
+ *     {@link resolveStreamRoute}). The SAME pair is dispatched UNARY over POST,
+ *     so the streaming GET co-exists with the unary POST route. A GET to a
+ *     unary-only op is a `405` (method-not-allowed), distinguishing "route
+ *     exists, this method is unsupported" from "no such route" (`404`).
+ *
+ * A non-POST/GET method is rejected at the edge (`405`); a path that resolves to
+ * neither vocabulary is a `404`. The injected {@link GatewayHandler} is never
+ * invoked with a malformed request.
+ *
+ * @param method - The HTTP request method.
+ * @param url - The HTTP request URL (path + query).
+ * @returns The parsed route, or a typed rejection for the wire edge.
+ */
+declare function parseHttpRoute(method: string | undefined, url: string | undefined): ParsedRoute;
+/**
+ * Start a `node:http` server that hosts the gateway over HTTP for external
+ * clients.
+ *
+ * Binds {@link HttpServerOptions.port} on {@link HttpServerOptions.host}
+ * (default loopback), routes every `POST /<gateway>/<domain>/<operation>`
+ * through the injected {@link GatewayHandler} via {@link routeUnary}, and
+ * resolves once listening. The returned {@link HttpServerHandle} exposes an
+ * idempotent `close()` for deterministic teardown (daemon shutdown, tests). The
+ * adapter never calls `process.exit`.
+ *
+ * The caller assembles the handler (via `createGatewayHandler` with its domain
+ * handlers + middleware) and injects it here — this server never builds
+ * handlers itself, keeping the runtime free of any `@cleocode/cleo` dependency.
+ *
+ * @param handler - The transport-neutral gateway handler to route through.
+ * @param opts - Bind coordinates.
+ * @returns A promise resolving to the live {@link HttpServerHandle}.
+ */
+declare function startHttpServer(handler: GatewayHandler, opts: HttpServerOptions): Promise<HttpServerHandle>;
+
+/**
+ * Wire + lifecycle types for the `@cleocode/runtime/gateway/http` adapter.
+ *
+ * The HTTP transport carries the SAME gateway payloads as every other transport
+ * — request/response shapes are owned by `@cleocode/contracts/gateway` (R3-T2 ·
+ * T11446) and the streaming frame by `GatewayStreamEvent`. This module holds
+ * only the runtime-adapter-local option/handle shapes (mirroring the MCP and RPC
+ * adapters' `types.ts`), so the runtime stays framework-agnostic and free of any
+ * `@cleocode/cleo` / SvelteKit / drizzle dependency.
+ *
+ * @task T11450
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * Where on the wire the `(gateway, domain, operation)` triple of an HTTP unary
+ * request is sourced from. The adapter is framework-agnostic, so the embedder
+ * (SvelteKit route, daemon HTTP server, test harness) supplies the resolved
+ * coordinates explicitly rather than the adapter parsing a URL itself.
+ */
+interface HttpUnaryRequest {
+    /** CQRS gateway — `'mutate'` (write) or `'query'` (read). */
+    gateway: Gateway;
+    /** Target canonical domain (e.g. `'tasks'`). */
+    domain: string;
+    /** Domain operation name (e.g. `'show'`). */
+    operation: string;
+    /** Decoded JSON request body → operation params. */
+    params?: Record<string, unknown>;
+    /**
+     * Optional caller-supplied request id for tracing. When omitted the adapter
+     * mints a fresh UUID.
+     */
+    requestId?: string;
+    /** Bound session id, if any (forwarded into the dispatch request). */
+    sessionId?: string;
+}
+/**
+ * The result of routing one HTTP unary request through the gateway: the LAFS
+ * {@link DispatchResponse} JSON body plus the HTTP status the embedder should
+ * set (200 on success, 4xx/5xx mapped from the dispatch error).
+ *
+ * The adapter never writes the response itself (no framework coupling) — it
+ * returns this so the embedder serializes it onto its own `Response`.
+ */
+interface HttpUnaryResult {
+    /** HTTP status code derived from the dispatch outcome. */
+    status: number;
+    /** The LAFS envelope to serialize as the JSON response body. */
+    body: DispatchResponse;
+}
+
+/**
+ * HTTP transport adapter — serves gateway unary + SSE over HTTP.
+ *
+ * The fourth and final gateway transport (after CLI, MCP, RPC). Unlike the
+ * connection-oriented RPC/MCP adapters, the HTTP adapter is framework-agnostic
+ * by design: it does NOT bind a port or own a `Request`/`Response` lifecycle.
+ * Instead it exposes two pure routing primitives the embedder (a SvelteKit
+ * route handler, the daemon's HTTP server, a test harness) calls directly:
+ *
+ *   - {@link routeUnary} — one POST → `source: 'http'` {@link DispatchRequest}
+ *     → injected {@link GatewayHandler} → `{ status, body }` (LAFS envelope).
+ *   - the SSE primitives in `./sse.js` (`createSseStream`) for streaming ops.
+ *
+ * This keeps the runtime free of any HTTP-server / SvelteKit / `@cleocode/cleo`
+ * dependency: the embedder owns wire concerns (parsing the URL into a
+ * `(gateway, domain, operation)` triple, setting headers, `process.exit`,
+ * error-render at the edge), exactly mirroring how the CLI adapter wraps the
+ * same handler. There is NO `process.exit` and NO error-render in the handlers
+ * (R3 contract); the adapter never calls `process.exit` at all.
+ *
+ * The request `source` is forced to `'http'` regardless of what the embedder
+ * passes, so a client cannot impersonate another transport.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http
+ *
+ * @task T11450
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * Map a LAFS dispatch error code to an HTTP status code.
+ *
+ * The canonical machine-readable error code (`E_NOT_FOUND`, `E_VALIDATION_…`,
+ * `E_FORBIDDEN`, …) is the source of truth; the numeric LAFS exit code is a
+ * secondary hint. Unknown error codes fall back to `500`. A successful envelope
+ * is always `200`.
+ *
+ * @param response - The dispatch response.
+ * @returns The HTTP status the embedder should set.
+ */
+declare function statusForResponse(response: DispatchResponse): number;
+/**
+ * Route a single HTTP unary request through the gateway handler.
+ *
+ * Builds a `source: 'http'` {@link DispatchRequest} from the embedder-resolved
+ * `(gateway, domain, operation, params)` triple and delegates to the injected
+ * {@link GatewayHandler}. A thrown handler error is trapped and rendered as a
+ * `500` LAFS error envelope — never propagated as an unhandled rejection or
+ * `process.exit`. The `source` is always forced to `'http'`.
+ *
+ * @param handler - The injected transport-neutral gateway handler.
+ * @param req - The embedder-resolved unary request coordinates + body params.
+ * @returns The HTTP status + LAFS response body for the embedder to serialize.
+ */
+declare function routeUnary(handler: GatewayHandler, req: HttpUnaryRequest): Promise<HttpUnaryResult>;
+
+/**
+ * Server-Sent Events (SSE) wire primitives for the `@cleocode/runtime/gateway/http`
+ * adapter.
+ *
+ * The HTTP transport is the only gateway transport that streams: long-running
+ * and subscription operations emit a sequence of {@link GatewayStreamEvent}
+ * frames terminated by a `done` or `error` frame. This module owns ONLY the SSE
+ * wire encoding + the `ReadableStream` lifecycle plumbing; the actual frame
+ * production (polling a DB, tailing a job, etc.) lives in the caller's async
+ * source. Keeping the encode/stream concern here lets BOTH the gateway-routed
+ * streaming ops AND the existing Studio SSE endpoints (which carry their own
+ * domain event shapes) share one tested, leak-free stream builder.
+ *
+ * Two encoders are provided so an existing stream can adopt this plumbing
+ * WITHOUT changing its observed bytes:
+ *  - {@link encodeStreamEvent} — the canonical `data: <json>\n\n` form for
+ *    {@link GatewayStreamEvent} frames (gateway-routed streaming ops).
+ *  - {@link encodeSseFrame} — a generic `event:`/`id:`/`data:` writer for any
+ *    payload, so endpoints with a bespoke wire (a named `event:` field, a
+ *    `data:`-only frame) keep an IDENTICAL byte stream while still routing their
+ *    lifecycle through the shared, abort-safe builder.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http/sse
+ *
+ * @task T11450
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * One generic SSE frame: an optional named `event`, an optional `id`, and a
+ * `data` payload that is JSON-serialized.
+ *
+ * This is intentionally NOT {@link GatewayStreamEvent} — it is the raw wire
+ * shape so a bespoke endpoint can reproduce its exact existing bytes (e.g. a
+ * named `event: task-updated` line, or a `data:`-only frame with no `event`).
+ */
+interface SseFrame {
+    /** Optional SSE `event:` field name (omitted → a `data:`-only frame). */
+    event?: string;
+    /** Optional SSE `id:` field for client-side last-event-id resumption. */
+    id?: string;
+    /** The frame payload; JSON-serialized into the `data:` field. */
+    data: unknown;
+}
+/**
+ * Encode a generic {@link SseFrame} to its SSE wire bytes.
+ *
+ * Field order is `event:` (if present) → `id:` (if present) → `data:`, matching
+ * the SSE spec record layout, then a blank line. When `event` is omitted the
+ * frame is a `data:`-only record — byte-identical to a handwritten
+ * `data: <json>\n\n`.
+ *
+ * @param frame - The frame to serialize.
+ * @returns The SSE record as a string (UTF-8 caller-encoded).
+ */
+declare function encodeSseFrame(frame: SseFrame): string;
+/**
+ * Encode a canonical {@link GatewayStreamEvent} as a `data:`-only SSE record.
+ *
+ * Gateway-routed streaming ops carry the discriminator + sequence inside the
+ * JSON payload (`{ kind, seq, data, error, requestId }`), so no named SSE
+ * `event:` field is used — the client demultiplexes on `kind`/`seq`. The
+ * monotonic `seq` is also surfaced as the SSE `id:` so a reconnecting client can
+ * send `Last-Event-ID`.
+ *
+ * @param frame - The gateway stream event to serialize.
+ * @returns The SSE record as a string.
+ */
+declare function encodeStreamEvent(frame: GatewayStreamEvent): string;
+/** The standard SSE response headers (no caching, no proxy buffering). */
+declare const SSE_HEADERS: Readonly<Record<string, string>>;
+/**
+ * A push-style SSE controller handed to an {@link SseSource} so it can emit
+ * frames and close the stream without touching the underlying
+ * `ReadableStreamDefaultController`.
+ */
+interface SseEmitter {
+    /** Emit one generic SSE frame; a no-op once the stream is closed. */
+    send(frame: SseFrame): void;
+    /** Emit one canonical {@link GatewayStreamEvent}; a no-op once closed. */
+    sendStreamEvent(frame: GatewayStreamEvent): void;
+    /**
+     * Emit a pre-encoded SSE record verbatim; a no-op once closed. For endpoints
+     * that own their own wire encoder (e.g. a bespoke `data: <json>\n\n`) and want
+     * to keep emitting byte-identical records while still routing lifecycle
+     * through this builder.
+     */
+    sendRaw(record: string): void;
+    /** Whether the stream has been closed (client disconnect or `close()`). */
+    readonly closed: boolean;
+    /** Close the stream; idempotent. */
+    close(): void;
+}
+/**
+ * A teardown callback returned by an {@link SseSource}, invoked exactly once when
+ * the stream ends (client disconnect, `emitter.close()`, or producer completion).
+ */
+type SseTeardown = () => void;
+/**
+ * A frame source for {@link createSseStream}. Receives an {@link SseEmitter} and
+ * MAY return an {@link SseTeardown} callback (return nothing to skip teardown).
+ *
+ * The source is started SYNCHRONOUSLY inside `ReadableStream.start`, mirroring
+ * the existing Studio endpoints (which schedule timers inside `start`). A source
+ * may push frames immediately and/or schedule async work.
+ */
+type SseSource = (emitter: SseEmitter) => SseTeardown | undefined;
+/**
+ * Build a `text/event-stream` {@link ReadableStream} driven by an
+ * {@link SseSource}.
+ *
+ * This is the shared, abort-safe stream builder every SSE endpoint routes
+ * through. It guarantees:
+ *  - frames are dropped (never throw) after the stream closes;
+ *  - the source's teardown callback runs exactly once;
+ *  - an optional {@link AbortSignal} (the request's) closes the stream on client
+ *    disconnect, with its listener removed on teardown.
+ *
+ * The byte output is fully controlled by what the source emits — so an endpoint
+ * adopting this builder reproduces its prior wire exactly by emitting the same
+ * frames in the same order.
+ *
+ * @param source - The frame producer.
+ * @param signal - Optional request abort signal that closes the stream on
+ *   client disconnect.
+ * @returns A ReadableStream of UTF-8 SSE bytes for a `Response` body.
+ */
+declare function createSseStream(source: SseSource, signal?: AbortSignal): ReadableStream<Uint8Array>;
+
+/**
+ * Streaming-operation source adapters for the gateway HTTP/SSE transport (T11921).
+ *
+ * A streaming operation (`OperationDef.streaming === true`, served as
+ * `GET /v1/<domain>/<operation>`) needs a *producer*: an async source that tails
+ * an event origin (the agent/worker/board lifecycle bus) and feeds
+ * {@link GatewayStreamEvent} frames into the shared, abort-safe
+ * {@link createSseStream} builder. This module owns ONLY that producer concern —
+ * the wire encoding + stream lifecycle live in `./sse.ts`, and the route parsing
+ * lives in `./listen.ts`.
+ *
+ * The runtime is deliberately DB-free (the runtime invariant — no drizzle, no
+ * `@cleocode/cleo`), so a source here MUST NOT open a store directly. Instead the
+ * listener resolves a source by `<domain>.<operation>` key from the
+ * {@link STREAM_SOURCES} registry; an embedder that owns a richer origin (the
+ * daemon, a SvelteKit route) can inject its own source into the listener at
+ * boot. The default source shipped here is a bounded tick/heartbeat producer that
+ * proves the pipe end-to-end without reaching across the package boundary — and
+ * is exactly what the in-process test exercises.
+ *
+ * Secrets never touch the wire: a source emits only the public lifecycle payload
+ * it is handed; credential resolution (if any) happens server-side before the
+ * frame is built, exactly as it does for a unary dispatch.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http/stream-sources
+ *
+ * @task T11921
+ * @epic T11769
+ * @saga T10400
+ */
+
+/**
+ * The bind coordinates a {@link GatewayStreamSource} receives: the resolved
+ * `(domain, operation)` of the streaming route, the already-validated request
+ * params, and the request id (so emitted frames correlate back to the origin
+ * request).
+ */
+interface StreamSourceContext {
+    /** The canonical domain segment of the streaming route. */
+    domain: string;
+    /** The operation segment of the streaming route. */
+    operation: string;
+    /** The decoded query params for the streaming request. */
+    params: Record<string, unknown>;
+    /** The request id stamped on every emitted {@link GatewayStreamEvent}. */
+    requestId: string;
+}
+/**
+ * A teardown callback a {@link GatewayStreamSource} MAY return; invoked exactly
+ * once when the stream ends (client disconnect, terminal frame, completion).
+ */
+type StreamSourceTeardown = () => void;
+/**
+ * A producer for one streaming operation. Receives an {@link SseEmitter}
+ * (`sendStreamEvent` emits one canonical {@link GatewayStreamEvent}) plus the
+ * resolved {@link StreamSourceContext}, and MAY return a teardown callback.
+ *
+ * The source is started synchronously inside the stream builder, mirroring the
+ * Studio SSE endpoints; it may push frames immediately and/or schedule async
+ * work. It MUST drop frames once `emitter.closed` is true (the emitter already
+ * guards this) and MUST clean up timers/listeners in its teardown so a client
+ * disconnect closes the stream leak-free.
+ */
+type GatewayStreamSource = (emitter: SseEmitter, context: StreamSourceContext) => StreamSourceTeardown | undefined;
+/**
+ * The default `orchestrate.events` source: a bounded tick/heartbeat producer.
+ *
+ * Emits a monotonic sequence of `data` {@link GatewayStreamEvent} frames at
+ * {@link DEFAULT_TICK_INTERVAL_MS}, then a terminal `done` frame once the
+ * `ticks` budget is exhausted; a client disconnect tears the timer down before
+ * then. It carries no DB handle and no secret — each frame's payload is a public
+ * heartbeat (`{ tick, ts }`) standing in for an agent/worker/board lifecycle
+ * event until the daemon injects its real origin-tailing source.
+ *
+ * A first frame is emitted SYNCHRONOUSLY so a client (and the test) observes a
+ * well-formed `data:` frame immediately, without waiting a full interval.
+ *
+ * @param emitter - The SSE emitter for this stream.
+ * @param context - The resolved streaming-route context.
+ * @returns A teardown that clears the tick timer.
+ */
+declare const tickStreamSource: GatewayStreamSource;
+/**
+ * Register (or override) the {@link GatewayStreamSource} for a streaming op.
+ *
+ * Lets an embedder that owns a richer event origin (the daemon tailing the
+ * agent/worker/board lifecycle bus, a SvelteKit route reading a store) replace
+ * the default tick source for a given `(domain, operation)` without changing the
+ * listener. Idempotent — a later call wins.
+ *
+ * @param domain - The canonical domain of the streaming op.
+ * @param operation - The operation name of the streaming op.
+ * @param source - The producer to serve this streaming route with.
+ */
+declare function registerStreamSource(domain: string, operation: string, source: GatewayStreamSource): void;
+/**
+ * Resolve the {@link GatewayStreamSource} registered for a streaming op.
+ *
+ * @param domain - The canonical domain of the streaming op.
+ * @param operation - The operation name of the streaming op.
+ * @returns The registered source, or `undefined` when none is registered (the
+ *   listener then closes the stream with a single terminal `error` frame).
+ */
+declare function resolveStreamSource(domain: string, operation: string): GatewayStreamSource | undefined;
+
+/**
+ * Static file serving for the bundled CLEO Web Studio assets.
+ *
+ * The gateway HTTP server calls {@link serveStudioStatic} for any request whose
+ * path starts with the `/studio` prefix. The handler:
+ *
+ *  1. Strips the `/studio` prefix and resolves the remainder against the
+ *     `studioStaticDir` (the `build/client/` output of the Studio
+ *     `adapter-node` build bundled inside `@cleocode/cleo`).
+ *  2. Serves the matched file with the correct MIME type (inferred from the
+ *     extension via the built-in {@link MIME_TYPES} map).
+ *  3. Returns `index.html` for any path that does not resolve to a static file
+ *     — the SPA fallback that lets the SvelteKit client-side router handle
+ *     sub-routes.
+ *  4. Returns a clean JSON error envelope (not a stack trace) when
+ *     `studioStaticDir` is absent (dev checkout without a Studio build, or an
+ *     npm install where the postbuild copy was skipped).
+ *
+ * The handler deliberately has NO `process.exit`, NO drizzle, NO
+ * `@cleocode/cleo` dependency — it is a pure file-system responder that can be
+ * embedded in any `node:http` server (the gateway daemon, a test harness).
+ *
+ * The `build/client/` static tree is served under `/studio/` so all of its
+ * relative asset references (`/_app/immutable/...`) resolve correctly. The root
+ * `/studio` (no trailing slash) redirects to `/studio/` to keep the base URL
+ * consistent with the SvelteKit assets.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http
+ *
+ * @task T11979
+ * @epic T11261
+ */
+
+/** The URL prefix the Studio static handler claims. */
+declare const STUDIO_PREFIX = "/studio";
+/**
+ * Options for the Studio static handler, injected at server startup.
+ *
+ * The caller resolves the absolute path to the static asset directory and
+ * passes it here — the handler never reads environment variables or resolves
+ * paths itself, keeping concerns separated and the handler testable.
+ */
+interface StudioStaticOptions {
+    /**
+     * Absolute path to the Studio static asset directory. This is the
+     * `build/client/` subdirectory from an `adapter-node` Studio build, bundled
+     * inside `@cleocode/cleo` at `studio-dist/client/`.
+     *
+     * When `undefined` or the path does not exist on disk, every request under
+     * `/studio` returns a clean JSON 503 "bundle absent" envelope.
+     */
+    staticDir: string | undefined;
+}
+/**
+ * Determine whether a request path falls under the Studio prefix and should be
+ * handled by the static asset handler rather than the API gateway.
+ *
+ * @param pathname - The URL pathname (without query string).
+ * @returns `true` when the path is `/studio`, `/studio/`, or any
+ *   `/studio/<subpath>`.
+ */
+declare function isStudioPath(pathname: string): boolean;
+/**
+ * Resolve the file-system path for a Studio request within `staticDir`.
+ *
+ * Strips the `/studio` prefix and normalises the remainder; guards against
+ * path-traversal (a normalised path that escapes `staticDir` is rejected).
+ *
+ * @param staticDir - Absolute path to the Studio static asset directory.
+ * @param pathname - The request path (already verified to start with `/studio`).
+ * @returns The absolute candidate path, or `undefined` when path traversal is
+ *   detected.
+ */
+declare function resolveStudioAssetPath(staticDir: string, pathname: string): string | undefined;
+/**
+ * Infer the MIME type for a file from its extension.
+ *
+ * @param filePath - The file path (only the extension is used).
+ * @returns The appropriate `Content-Type` header value.
+ */
+declare function mimeType(filePath: string): string;
+/**
+ * Write the "bundle absent" JSON error envelope and close the response.
+ *
+ * Used when `staticDir` is `undefined` or does not exist on disk — the Studio
+ * build was not found. The response is a `503 Service Unavailable` with a clean
+ * LAFS-flavoured JSON body so clients can detect the condition programmatically.
+ *
+ * @param res - The server response to write to.
+ * @param hint - Optional developer hint (e.g. the expected bundle path).
+ */
+declare function writeBundleAbsentError(res: ServerResponse, hint?: string): void;
+/**
+ * Handle a single HTTP request whose path falls under `/studio`.
+ *
+ * Routing logic:
+ *  - `GET /studio` → 302 redirect to `/studio/` (keep asset refs consistent)
+ *  - `GET /studio/<static-asset>` → serve the file from `staticDir`
+ *  - `GET /studio/*` (no matching file) → serve `index.html` (SPA fallback)
+ *  - Any request when `staticDir` is absent → 503 JSON envelope
+ *  - Non-GET method → 405 JSON envelope (Studio is read-only from the gateway)
+ *
+ * @param req - The inbound HTTP request.
+ * @param res - The outbound HTTP response.
+ * @param opts - Static handler options (resolved at server startup).
+ * @returns A promise that resolves once the response has been written.
+ */
+declare function serveStudioStatic(req: IncomingMessage, res: ServerResponse, opts: StudioStaticOptions): Promise<void>;
+/**
+ * Resolve the bundled Studio static directory from the `@cleocode/cleo` package
+ * location.
+ *
+ * When running from an npm install, the Studio build is bundled at
+ * `<cleo-package-root>/studio-dist/client/`. When running from a monorepo dev
+ * checkout, the directory may not exist (developers must run
+ * `pnpm --filter @cleocode/studio run build` manually) — `undefined` is
+ * returned in that case, and the gateway handler will serve the bundle-absent
+ * error instead of crashing.
+ *
+ * @param cleoPackageDir - Absolute path to the `@cleocode/cleo` package root.
+ *   Typically derived from `import.meta.url` at the call site.
+ * @returns The absolute path to `studio-dist/client/`, or `undefined` if the
+ *   directory does not exist.
+ */
+declare function resolveStudioStaticDir(cleoPackageDir: string): string | undefined;
+
+export { type GateDecision, type GatewayStreamSource, type HttpServerHandle, type HttpServerOptions, type HttpUnaryRequest, type HttpUnaryResult, NODE_PTY_INSTALL_HINT, SSE_HEADERS, STUDIO_PREFIX, type SseEmitter, type SseFrame, type SseSource, type StreamSourceContext, type StreamSourceTeardown, type StudioStaticOptions, type UpgradableServer, WS_PTY_PATH, type WsPtyEndpointHandle, type WsPtyOptions, attachWsPtyEndpoint, authorizeUpgrade, computeAcceptKey, createSseStream, decodeWsFrame, encodeSseFrame, encodeStreamEvent, encodeWsFrame, isStudioPath, isWsPtyPath, loadNodePty, mimeType, parseHttpRoute, registerStreamSource, resolveStreamSource, resolveStudioAssetPath, resolveStudioStaticDir, routeUnary, scrubPtyEnv, serveStudioStatic, startHttpServer, statusForResponse, tickStreamSource, writeBundleAbsentError };