@cleocode/runtime 2026.6.13 → 2026.6.15

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

@@ -1,12 +1,13 @@
 import { DomainHandler, Middleware, DispatchRequest, DispatchResponse, Gateway, GatewayStreamEvent, Source, DispatchResponseMeta, CanonicalDomain, Tier } from '@cleocode/contracts/gateway';
 import { BackgroundJobManager } from '@cleocode/core/store/background-jobs.js';
 import { Subsystem, OperationDef, SuggestedNextOp, Resolution } from '@cleocode/contracts';
-import { Server } from 'node:http';
+import { IncomingMessage, Server, ServerResponse } from 'node:http';
 import '@cleocode/contracts/operations/orchestrate';
 import * as _cleocode_core_internal from '@cleocode/core/internal';
 import { EngineResult, ProblemDetails } from '@cleocode/core';
 import { GatewayRpcRequestFrame, GatewayRpcErrorFrame, GatewayRpcErrorCode, GatewayRpcResponseFrame } from '@cleocode/contracts/gateway/rpc';
 import { Server as Server$1 } from 'node:net';
+import { Duplex } from 'node:stream';
 
 /**
  * Central Dispatcher -- Routes requests through middleware to domain handlers.
@@ -45,6 +46,246 @@ declare class Dispatcher {
     dispatch(request: DispatchRequest): Promise<DispatchResponse>;
 }
 
+/**
+ * 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.
  *
@@ -96,6 +337,33 @@ interface HttpServerOptions {
      * 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}.
@@ -115,14 +383,24 @@ interface HttpServerHandle {
     close(): Promise<void>;
 }
 /**
- * The result of parsing a request line into routing coordinates: either a
- * resolved unary triple or a rejection reason for the wire edge.
+ * 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;
@@ -130,12 +408,33 @@ type ParsedRoute = {
     message: string;
 };
 /**
- * Parse `POST /<gateway>/<domain>/<operation>` into a routing triple.
+ * 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:
  *
- * Rejects a non-POST method (`405`) and any path that does not resolve to a
- * known `(gateway, domain, operation)` triple (`404`). The gateway segment is
- * validated against the two CQRS gateways so a client cannot smuggle an
- * arbitrary value into the dispatch request.
+ *   - `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).
@@ -1031,6 +1330,239 @@ type SseSource = (emitter: SseEmitter) => SseTeardown | undefined;
  */
 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;
+
 /**
  * Singleton accessor for the gateway {@link BackgroundJobManager}.
  *
@@ -1508,6 +2040,51 @@ declare function getGatewayDomains(gateway: Gateway): string[];
  * Resolves a domain + operation to its registered definition.
  */
 declare function resolve(gateway: Gateway, domain: string, operation: string): Resolution | undefined;
+/**
+ * Infer the CQRS {@link Gateway} for a `(domain, operation)` pair from the
+ * registry, without the caller naming `query`/`mutate` up front.
+ *
+ * This backs the versioned `/v1/<domain>/<operation>` REST facade (T11919),
+ * where — unlike the legacy `/<gateway>/<domain>/<operation>` form — the client
+ * does not spell the gateway segment: the registry is the single source of truth
+ * for whether an operation is a read (`query`) or a write (`mutate`). Each
+ * `(domain, operation)` pair maps to exactly one gateway in {@link OPERATIONS},
+ * so the inference is unambiguous.
+ *
+ * @param domain - The canonical domain segment (e.g. `'tasks'`).
+ * @param operation - The operation segment (e.g. `'show'`).
+ * @returns The owning gateway, or `undefined` when no registered operation
+ *   matches the pair (the wire edge then renders a `404`).
+ */
+declare function inferGateway(domain: string, operation: string): Gateway | undefined;
+/**
+ * The result of resolving a streaming route: the owning gateway plus the matched
+ * {@link OperationDef} (so the caller has the op's tier/params on hand without a
+ * second lookup).
+ */
+interface StreamResolution {
+    /** The CQRS gateway the streaming op is registered under. */
+    gateway: Gateway;
+    /** The matched streaming operation definition. */
+    def: OperationDef;
+}
+/**
+ * Resolve a `(domain, operation)` pair to a registered **streaming** operation.
+ *
+ * Backs the `GET /v1/<domain>/<operation>` SSE route (T11921): the listener only
+ * opens a `text/event-stream` for a `(domain, operation)` pair that is BOTH
+ * registered AND explicitly flagged `streaming: true` in {@link OPERATIONS}. A
+ * unary-only op (or an unknown pair) resolves to `undefined`, so the listener
+ * never streams an operation that was not declared streamable — a GET to a
+ * unary op stays a `405` (method-not-allowed) rather than silently opening a
+ * never-ending stream.
+ *
+ * @param domain - The canonical domain segment (e.g. `'orchestrate'`).
+ * @param operation - The operation segment (e.g. `'events'`).
+ * @returns The streaming resolution, or `undefined` when no registered op
+ *   matches the pair OR the matched op is not flagged `streaming: true`.
+ */
+declare function resolveStreamRoute(domain: string, operation: string): StreamResolution | undefined;
 /**
  * Validates that all required parameters are present in the request.
  * Returns an array of missing parameter keys.
@@ -1530,6 +2107,114 @@ declare function getCounts(): {
     total: number;
 };
 
+/**
+ * Daemon-side gateway server bootstrap — the call-site `cleo daemon serve`
+ * drives (T11919).
+ *
+ * The HTTP gateway adapter (`./http/listen.ts`, T11254) and the supervised
+ * `defineGatewaySubsystem` unit (`./daemon-subsystem.ts`, T11451) both already
+ * exist, but nothing started them: the daemon had no `serve` call-site. This
+ * module is that thin bootstrap — it assembles a {@link SubsystemRegistry} with
+ * one scoped gateway subsystem hosting the HTTP transport (loopback by default)
+ * over an INJECTED {@link GatewayHandler}, starts it, and returns a live handle
+ * with the bound port + an idempotent `close()`.
+ *
+ * It carries NO `@cleocode/cleo` dependency and NO drizzle (the runtime
+ * invariant): the caller (`cleo daemon serve`) injects the assembled CLI gateway
+ * handler and the resolved bind coordinates. Secrets never touch the wire —
+ * sealed-handle resolution happens server-side inside the dispatched handler,
+ * exactly as it does for an in-process CLI call. The HTTP listener binds
+ * `127.0.0.1` by default (loopback only); exposing it on a public interface is
+ * an explicit caller decision.
+ *
+ * The streaming transports (SSE — T11921, WS — T11922) extend the SAME
+ * subsystem: when their listeners land they bind alongside the unary HTTP server
+ * here, so this bootstrap deliberately owns only transport assembly + lifecycle,
+ * leaving the per-route seam to the adapter (`parseHttpRoute`).
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway
+ *
+ * @task T11919
+ * @epic T11769
+ * @saga T10400
+ */
+
+/**
+ * Options for {@link serveGateway}.
+ *
+ * The caller injects the assembled {@link GatewayHandler} and resolves the bind
+ * coordinates so the runtime stays free of `@cleocode/paths`/`@cleocode/cleo`.
+ */
+interface ServeGatewayOptions {
+    /** The transport-neutral gateway handler every hosted transport routes through. */
+    handler: GatewayHandler;
+    /** TCP port to bind. `0` selects an ephemeral port (readable from the handle). */
+    port: number;
+    /** Host/interface to bind. Defaults to `127.0.0.1` (loopback only). */
+    host?: string;
+    /** The scope this gateway process serves. Defaults to `'global'`. */
+    scope?: GatewayScope;
+    /**
+     * Absolute path to the Studio static asset directory (T11979).
+     *
+     * When set, the HTTP server serves the bundled CLEO Web Studio at `/studio`
+     * using the `build/client/` static assets from an `adapter-node` Studio build.
+     * When `undefined`, `/studio` routes return a clean 503 "bundle absent" JSON
+     * envelope. The caller resolves this path (typically via
+     * `resolveStudioStaticDir` from `@cleocode/cleo`) so the runtime stays free of
+     * any path-resolution policy.
+     */
+    studioStaticDir?: string;
+}
+/**
+ * A live gateway server handle returned by {@link serveGateway}.
+ *
+ * Exposes the actually-bound `port`/`host` (resolved even when `0` was
+ * requested) and an idempotent {@link close} for deterministic teardown
+ * (daemon shutdown, tests). Mirrors the lower-level
+ * {@link import('./http/listen.js').HttpServerHandle} so a test can boot, probe,
+ * and tear down on an ephemeral port.
+ */
+interface ServeGatewayHandle {
+    /** The actually-bound HTTP port (resolved when `0` was requested). */
+    port: number;
+    /** Host/interface the HTTP listener is bound to. */
+    host: string;
+    /** The scope the gateway process serves. */
+    scope: GatewayScope;
+    /** Stop every bound listener (best-effort, idempotent); resolves once closed. */
+    close(): Promise<void>;
+}
+/**
+ * Boot the HTTP gateway as a supervised subsystem and return a live handle.
+ *
+ * Declares one scoped gateway subsystem hosting the HTTP transport (loopback
+ * default) over the injected handler via {@link defineGatewaySubsystem}, starts
+ * it, and reads the actually-bound port from the start context (so the caller —
+ * and tests — learn the ephemeral port when `0` was requested). The returned
+ * `close()` drives the subsystem's `shutdown(context)` so teardown is the same
+ * lifecycle the daemon registry uses for every other supervised concern.
+ *
+ * Using `defineGatewaySubsystem` directly (rather than a full
+ * `SubsystemRegistry`) keeps the bound HTTP handle in reach for the port
+ * resolution while still routing through the canonical start→shutdown contract.
+ *
+ * @param opts - The injected handler + resolved bind coordinates.
+ * @returns A promise resolving to the live {@link ServeGatewayHandle}.
+ *
+ * @example
+ * ```ts
+ * const handle = await serveGateway({
+ *   handler: createCliGatewayHandler(),
+ *   port: 0, // ephemeral
+ * });
+ * // POST http://127.0.0.1:${handle.port}/v1/tasks/show
+ * await handle.close();
+ * ```
+ */
+declare function serveGateway(opts: ServeGatewayOptions): Promise<ServeGatewayHandle>;
+
 /**
  * `@cleocode/runtime/gateway` — the transport-agnostic CQRS dispatch core.
  *
@@ -1569,4 +2254,4 @@ interface GatewayHandler {
  */
 declare function createGatewayHandler(config: DispatcherConfig): GatewayHandler;
 
-export { getByDomain as $, type GatewayHandler as A, BRAIN_DB_FILENAME as B, CLEO_DIR_NAME as C, Dispatcher as D, type DecodeResult, type ErrorMeta as E, type GatewayScope as F, type GatewayOperationKey as G, type HttpServerHandle as H, type GatewaySubsystemContext as I, type GatewaySubsystemOptions as J, STRING_TO_EXIT as K, buildNexusMetaExtensions as L, LineBuffer, MCP_TOOL_PREFIX as M, cleoErrorToEngineError as N, OPERATIONS as O, compose as P, createDispatchMeta as Q, createGatewayHandler as R, type RpcServerHandle, type RpcServerOptions, SSE_HEADERS as S, defineGatewaySubsystem as T, deriveGatewayMatrix as U, engineError as V, WORKFLOWS_SUBDIR as W, formatSuggestedNext as X, gatewaySubsystemName as Y, generateTemplateConfig as Z, getActiveDomains as _, type HttpServerOptions as a, getByGateway as a0, getByTier as a1, getCounts as a2, getGatewayDomains as a3, getJobManager as a4, getTemplateForSubcommand as a5, mapNumericExitCodeToString as a6, parseIssueTemplates as a7, pickDecoratorMetaExtensions as a8, resolve as a9, setJobManager as aa, stampNexusMeta as ab, validateLabels as ac, validateRequiredParams as ad, validateSuggestedNext as ae, type HttpUnaryRequest as b, buildErrorFrame, type HttpUnaryResult as c, type SseEmitter as d, decodeLine, type SseFrame as e, encodeFrame, type SseSource as f, createSseStream as g, encodeSseFrame as h, encodeStreamEvent as i, statusForResponse as j, type McpContent as k, type McpInputProperty as l, type McpServerOptions as m, type McpTool as n, type McpToolResult as o, parseHttpRoute as p, buildToolsList as q, routeUnary as r, routeFrame, startHttpServer as s, startRpcServer, callTool as t, exposedOperations as u, operationToMcpTool as v, operationToToolName as w, startMcpServer as x, toolNameToOperationKey as y, type DispatcherConfig as z };
+export { operationToMcpTool as $, registerStreamSource as A, resolveStreamSource as B, resolveStudioAssetPath as C, resolveStudioStaticDir as D, type DecodeResult, routeUnary as E, scrubPtyEnv as F, type GateDecision as G, type HttpServerHandle as H, serveStudioStatic as I, startHttpServer as J, statusForResponse as K, tickStreamSource as L, LineBuffer, writeBundleAbsentError as M, NODE_PTY_INSTALL_HINT as N, type GatewayOperationKey as O, MCP_TOOL_PREFIX as P, type McpContent as Q, type McpInputProperty as R, type RpcServerHandle, type RpcServerOptions, SSE_HEADERS as S, type McpServerOptions as T, type UpgradableServer as U, type McpTool as V, WS_PTY_PATH as W, type McpToolResult as X, buildToolsList as Y, callTool as Z, exposedOperations as _, type GatewayStreamSource as a, operationToToolName as a0, startMcpServer as a1, toolNameToOperationKey as a2, BRAIN_DB_FILENAME as a3, CLEO_DIR_NAME as a4, Dispatcher as a5, type DispatcherConfig as a6, type ErrorMeta as a7, type GatewayHandler as a8, type GatewayScope as a9, getTemplateForSubcommand as aA, inferGateway as aB, mapNumericExitCodeToString as aC, parseIssueTemplates as aD, pickDecoratorMetaExtensions as aE, resolve as aF, resolveStreamRoute as aG, serveGateway as aH, setJobManager as aI, stampNexusMeta as aJ, validateLabels as aK, validateRequiredParams as aL, validateSuggestedNext as aM, type GatewaySubsystemContext as aa, type GatewaySubsystemOptions as ab, OPERATIONS as ac, STRING_TO_EXIT as ad, type ServeGatewayHandle as ae, type ServeGatewayOptions as af, type StreamResolution as ag, WORKFLOWS_SUBDIR as ah, buildNexusMetaExtensions as ai, cleoErrorToEngineError as aj, compose as ak, createDispatchMeta as al, createGatewayHandler as am, defineGatewaySubsystem as an, deriveGatewayMatrix as ao, engineError as ap, formatSuggestedNext as aq, gatewaySubsystemName as ar, generateTemplateConfig as as, getActiveDomains as at, getByDomain as au, getByGateway as av, getByTier as aw, getCounts as ax, getGatewayDomains as ay, getJobManager as az, type HttpServerOptions as b, buildErrorFrame, type HttpUnaryRequest as c, type HttpUnaryResult as d, decodeLine, STUDIO_PREFIX as e, encodeFrame, type SseEmitter as f, type SseFrame as g, type SseSource as h, type StreamSourceContext as i, type StreamSourceTeardown as j, type StudioStaticOptions as k, type WsPtyEndpointHandle as l, type WsPtyOptions as m, attachWsPtyEndpoint as n, authorizeUpgrade as o, computeAcceptKey as p, createSseStream as q, decodeWsFrame as r, routeFrame, encodeSseFrame as s, startRpcServer, encodeStreamEvent as t, encodeWsFrame as u, isStudioPath as v, isWsPtyPath as w, loadNodePty as x, mimeType as y, parseHttpRoute as z };