@cleocode/runtime 2026.6.12 → 2026.6.14

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 } 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,18 @@ 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;
 }
 /**
  * A live HTTP server handle returned by {@link startHttpServer}.
@@ -115,14 +368,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 +393,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).
@@ -348,11 +632,38 @@ interface RpcServerHandle {
  * handler errors are caught and rendered as a protocol-level `E_RPC_INTERNAL`
  * error frame — never propagated as an unhandled rejection or `process.exit`.
  *
+ * ## Connection-scoped session binding (T11640 · Epic T11638)
+ *
+ * The daemon serves many connections over one process, so it cannot rely on the
+ * single-process session-context singleton for identity. Instead, a frame on a
+ * connection that declares a `sessionId` binds it into the `{connId → sessionId}`
+ * registry, and the whole dispatch runs inside {@link runWithConnectionHandle}
+ * so `core`'s `resolveCurrentSession` resolves THIS connection's session (its
+ * highest-precedence tier) rather than "whoever wrote the DB last". When a frame
+ * carries no `sessionId`, no binding is performed and resolution transparently
+ * falls through to the env / active tiers — preserving existing behavior for
+ * anonymous frames.
+ *
+ * ### Intra-connection bleed safety
+ *
+ * Frames on one connection are dispatched CONCURRENTLY (each `routeFrame` is
+ * fired without awaiting the prior one), and registry binding is last-write-wins.
+ * To stop a still-in-flight Frame A from resolving a sibling Frame B's session,
+ * the frame's OWN declared `sessionId` is snapshotted into the per-frame
+ * connection handle ({@link runWithConnectionHandle}'s third arg) — that snapshot
+ * is authoritative for the dispatch, so a later re-bind of the same `connId`
+ * cannot retroactively change who Frame A is. The registry binding remains only
+ * for the late-binding path used by frames that declare no session of their own.
+ *
  * @param handler - The injected transport-neutral gateway handler.
  * @param frame - A validated, version-matched request frame.
+ * @param connId - The opaque per-connection id (bound at accept-time). Omitted
+ *   only by direct/test callers that route a single frame outside a socket; a
+ *   fresh ephemeral id is minted so the call still runs in an isolated
+ *   connection-handle scope.
  * @returns The response or error frame to write back on the same connection.
  */
-declare function routeFrame(handler: GatewayHandler, frame: GatewayRpcRequestFrame): Promise<GatewayRpcResponseFrame | ReturnType<typeof buildErrorFrame>>;
+declare function routeFrame(handler: GatewayHandler, frame: GatewayRpcRequestFrame, connId?: string): Promise<GatewayRpcResponseFrame | ReturnType<typeof buildErrorFrame>>;
 /**
  * Start the CLI-RPC unix-socket server over the gateway.
  *
@@ -1004,6 +1315,112 @@ 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;
+
 /**
  * Singleton accessor for the gateway {@link BackgroundJobManager}.
  *
@@ -1481,6 +1898,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.
@@ -1503,6 +1965,103 @@ 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;
+}
+/**
+ * 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.
  *
@@ -1542,4 +2101,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 { type ErrorMeta as $, startHttpServer as A, statusForResponse as B, tickStreamSource as C, type GatewayOperationKey as D, type DecodeResult, type McpContent as E, type McpInputProperty as F, type GateDecision as G, type HttpServerHandle as H, type McpServerOptions as I, type McpTool as J, type McpToolResult as K, buildToolsList as L, LineBuffer, MCP_TOOL_PREFIX as M, NODE_PTY_INSTALL_HINT as N, callTool as O, exposedOperations as P, operationToMcpTool as Q, operationToToolName as R, type RpcServerHandle, type RpcServerOptions, SSE_HEADERS as S, startMcpServer as T, type UpgradableServer as U, toolNameToOperationKey as V, WS_PTY_PATH as W, BRAIN_DB_FILENAME as X, CLEO_DIR_NAME as Y, Dispatcher as Z, type DispatcherConfig as _, type GatewayStreamSource as a, type GatewayHandler as a0, type GatewayScope as a1, type GatewaySubsystemContext as a2, type GatewaySubsystemOptions as a3, OPERATIONS as a4, STRING_TO_EXIT as a5, type ServeGatewayHandle as a6, type ServeGatewayOptions as a7, type StreamResolution as a8, WORKFLOWS_SUBDIR as a9, setJobManager as aA, stampNexusMeta as aB, validateLabels as aC, validateRequiredParams as aD, validateSuggestedNext as aE, buildNexusMetaExtensions as aa, cleoErrorToEngineError as ab, compose as ac, createDispatchMeta as ad, createGatewayHandler as ae, defineGatewaySubsystem as af, deriveGatewayMatrix as ag, engineError as ah, formatSuggestedNext as ai, gatewaySubsystemName as aj, generateTemplateConfig as ak, getActiveDomains as al, getByDomain as am, getByGateway as an, getByTier as ao, getCounts as ap, getGatewayDomains as aq, getJobManager as ar, getTemplateForSubcommand as as, inferGateway as at, mapNumericExitCodeToString as au, parseIssueTemplates as av, pickDecoratorMetaExtensions as aw, resolve as ax, resolveStreamRoute as ay, serveGateway as az, type HttpServerOptions as b, buildErrorFrame, type HttpUnaryRequest as c, type HttpUnaryResult as d, decodeLine, type SseEmitter as e, encodeFrame, type SseFrame as f, type SseSource as g, type StreamSourceContext as h, type StreamSourceTeardown as i, type WsPtyEndpointHandle as j, type WsPtyOptions as k, attachWsPtyEndpoint as l, authorizeUpgrade as m, computeAcceptKey as n, createSseStream as o, decodeWsFrame as p, encodeSseFrame as q, encodeStreamEvent as r, routeFrame, encodeWsFrame as s, startRpcServer, isWsPtyPath as t, loadNodePty as u, parseHttpRoute as v, registerStreamSource as w, resolveStreamSource as x, routeUnary as y, scrubPtyEnv as z };

package/dist/gateway/rpc/index.js

@@ -5,7 +5,7 @@ import {
   encodeFrame,
   routeFrame,
   startRpcServer
-} from "../../chunk-5ZXRYEQ5.js";
+} from "../../chunk-KQBVXGOL.js";
 export {
   LineBuffer,
   buildErrorFrame,