@cleocode/runtime 2026.10.4 → 2026.10.5

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

@@ -1,481 +1,7 @@
-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 { 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.
- *
- * The dispatcher is the single entry point for the CLI adapter.
- * It resolves operations, validates parameters, runs the middleware pipeline,
- * and delegates to the appropriate domain handler.
- *
- * Flow: DispatchRequest → resolve → param validation → middleware → handler
- *
- * ## T1088 — Dialectic Evaluator Hook (PSYCHE Wave 3)
- *
- * After each successful mutate operation, the dispatcher fires a background
- * `evaluateDialectic` call via `setImmediate` if all of the following apply:
- *
- *   1. The response indicates `success: true`.
- *   2. The request gateway is `"mutate"` (state-modifying user-facing commands).
- *   3. A `sessionId` is present on the request (identifies conversation context).
- *   4. The in-memory rate limiter allows the evaluation (1 per 10s per session).
- *
- * Errors from the background evaluation are caught and logged at `warn` level
- * so they never affect the caller.
- *
- * ## T12024 — Bounded deadline for background LLM calls
- *
- * The dialectic evaluation makes an HTTP call to an LLM backend (Ollama,
- * Anthropic, etc.) which keeps the Node.js event loop alive. After the CLI
- * success-path `finally` tears down workers and databases via
- * `shutdownCliRuntime`, the pending HTTP connection is the sole remaining
- * reference — preventing the process from draining the loop and exiting rc:0.
- *
- * Each evaluation now runs against an unrefed deadline so the deadline
- * timer itself never holds the loop open, while the abort signal cancels the
- * underlying HTTP request when the deadline fires, releasing the connection
- * and allowing natural exit. The timeout is generous enough for normal
- * responses but prevents hung connections from blocking shutdown.
- *
- * @epic T4820
- * @task T1088
- * @task T12024
- */
-
-interface DispatcherConfig {
-    handlers: Map<string, DomainHandler>;
-    middlewares?: Middleware[];
-}
-declare class Dispatcher {
-    private handlers;
-    private pipeline;
-    constructor(config: DispatcherConfig);
-    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.
- *
- * 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>;
+import { Server } from 'node:net';
+import { G as GatewayHandler } from '../../gateway-handler-DCU6E0a2.js';
+import '@cleocode/contracts/gateway';
 
 /**
  * NDJSON codec for the CLI-RPC transport.
@@ -611,7 +137,7 @@ interface RpcServerOptions {
  */
 interface RpcServerHandle {
     /** The bound `node:net` server. */
-    server: Server$1;
+    server: Server;
     /** Absolute path of the bound unix socket. */
     socketPath: string;
     /** Close the server + all live connections; resolves once fully closed. */
@@ -713,1561 +239,4 @@ declare function routeFrame(handler: GatewayHandler, frame: GatewayRpcRequestFra
  */
 declare function startRpcServer(handler: GatewayHandler, opts: RpcServerOptions): Promise<RpcServerHandle>;
 
-/**
- * The gateway as a supervised **daemon subsystem**.
- *
- * R3-T7 (this task) closes the loop between the two R-track halves: the R3
- * gateway (dispatcher + the four transport adapters) and the R2 daemon
- * (`defineSubsystem` + the `SubsystemRegistry`). It expresses the
- * external-facing gateway as a uniform {@link Subsystem} so the R2 daemon
- * registry drives its `start → healthProbe → shutdown` lifecycle exactly like
- * every other long-running concern (Studio supervision, the GC cron, …). One
- * gateway subsystem is registered per scope (project / global) → one
- * external-facing gateway process per scope.
- *
- * Which transports the daemon hosts:
- *  - the **RPC unix socket** (`@cleocode/runtime/gateway/rpc`) — the canonical
- *    local-client wire: the `cleo` CLI, Studio's server process, and test
- *    harnesses open it to dispatch without paying a cold `cleo` spawn.
- *  - the **HTTP server** (`@cleocode/runtime/gateway/http` via the daemon-local
- *    `startHttpServer` embedder) — for external clients that speak HTTP rather
- *    than the unix-socket NDJSON wire.
- *
- * The CLI and MCP adapters are intentionally NOT hosted by the daemon: the CLI
- * adapter is in-process to the `cleo` binary, and the MCP adapter is a stdio
- * server an MCP client spawns and owns — neither is a long-lived,
- * daemon-supervised listener. The two external-facing listeners (RPC + HTTP)
- * are the ones the daemon owns.
- *
- * This subsystem adds NO behavior to the adapters themselves — it only wires
- * their existing `start*Server` / `close()` lifecycle (and their already-merged
- * routing) into the daemon registry's uniform lifecycle. It carries NO
- * `@cleocode/cleo` dependency and NO drizzle-orm (the runtime invariant): the
- * caller injects the assembled {@link GatewayHandler} and the resolved bind
- * coordinates; this module only orchestrates listeners.
- *
- * @packageDocumentation
- * @module @cleocode/runtime/gateway
- *
- * @task T11451 (R3-T7)
- * @epic T11254
- * @saga T11243 SG-RUNTIME-UNIFICATION
- */
-
-/** The scope a single gateway process serves — one external-facing process per scope. */
-type GatewayScope = 'project' | 'global';
-/**
- * Configuration for one scoped gateway subsystem.
- *
- * The caller injects the assembled, transport-neutral {@link GatewayHandler}
- * (built with `createGatewayHandler` from its domain handlers + middleware) and
- * the resolved bind coordinates for each hosted transport. The runtime never
- * resolves paths/ports itself — that keeps it free of `@cleocode/paths` and of
- * any policy decision about where a scope's socket/port lives.
- */
-interface GatewaySubsystemOptions {
-    /** The scope this gateway process serves (`project` | `global`). */
-    scope: GatewayScope;
-    /** The transport-neutral gateway handler every hosted transport routes through. */
-    handler: GatewayHandler;
-    /**
-     * RPC unix-socket transport options. When omitted, the RPC transport is not
-     * hosted (a deployment that only wants HTTP). At least one transport MUST be
-     * configured.
-     */
-    rpc?: RpcServerOptions;
-    /**
-     * HTTP transport options. When omitted, the HTTP transport is not hosted (a
-     * deployment that only wants the local RPC socket). At least one transport
-     * MUST be configured.
-     */
-    http?: HttpServerOptions;
-}
-/**
- * The live context a started gateway subsystem threads from `start` into
- * `healthProbe`/`shutdown`: the bound transport handles plus the owning pid.
- *
- * `void`-typed contexts are common for subsystems, but the gateway needs to
- * carry its bound handles so `shutdown` can close exactly what `start` opened
- * (and `healthProbe` can report the bound coordinates).
- */
-interface GatewaySubsystemContext {
-    /** The OS pid hosting the listeners (this daemon process). */
-    readonly pid: number;
-    /** The bound RPC server handle, when the RPC transport is hosted. */
-    readonly rpc?: RpcServerHandle;
-    /** The bound HTTP server handle, when the HTTP transport is hosted. */
-    readonly http?: HttpServerHandle;
-}
-/**
- * The stable subsystem name (and supervised `child_id`) of a scoped gateway.
- *
- * Suffixed with the scope so a single daemon process supervising both scopes
- * (project + global) registers two distinct, non-colliding subsystems. The
- * `child_id` matches the id the Rust supervisor tracks the listener under.
- *
- * @param scope - The gateway scope.
- * @returns The subsystem name, e.g. `gateway-project`.
- */
-declare function gatewaySubsystemName(scope: GatewayScope): string;
-/**
- * Declare the external-facing gateway as a supervised daemon {@link Subsystem}.
- *
- * The returned subsystem (frozen by {@link defineSubsystem}) is registered with
- * a `SubsystemRegistry`, which then drives its lifecycle uniformly:
- *
- *  - `start()`       — binds the configured transports (RPC unix socket and/or
- *    HTTP server) over the injected handler, in a fixed order (RPC then HTTP).
- *    If the second listener fails to bind, the first is rolled back so a failed
- *    start leaves no half-open listener — then the error is re-thrown for the
- *    registry's `onError` sink.
- *  - `healthProbe()` — reports a single {@link SubsystemHealth} row keyed on the
- *    scoped `child_id`, `running` while the configured listeners are live, with
- *    a `detail` summarizing the bound coordinates. Projects losslessly onto the
- *    supervisor's `ChildStatus`.
- *  - `shutdown()`    — closes every bound listener (best-effort, idempotent) in
- *    reverse bind order (HTTP then RPC).
- *
- * One subsystem instance is declared per scope, so registering the project and
- * global gateways yields two supervised listeners → one external-facing gateway
- * process surface per scope (AC1).
- *
- * @param opts - The scoped gateway configuration (handler + per-transport bind
- *   coordinates).
- * @returns A frozen {@link Subsystem} ready to `register()` with a
- *   `SubsystemRegistry`.
- * @throws {TypeError} When neither the RPC nor the HTTP transport is configured
- *   (a gateway with no hosted transport serves nothing).
- *
- * @example
- * ```ts
- * const registry = new SubsystemRegistry();
- * registry.register(
- *   defineGatewaySubsystem({
- *     scope: 'project',
- *     handler: createGatewayHandler(dispatcherConfig),
- *     rpc: { socketPath: '/run/cleo/cleo-gateway-rpc-project.sock' },
- *     http: { port: 7777 },
- *   }),
- * );
- * await registry.startAll();        // binds the RPC socket + HTTP server
- * const health = await registry.aggregateHealth();
- * await registry.shutdownAll();     // closes both listeners
- * ```
- */
-declare function defineGatewaySubsystem(opts: GatewaySubsystemOptions): Subsystem<GatewaySubsystemContext>;
-
-/**
- * Centralized engine error helper for the transport-agnostic gateway.
- *
- * Every domain handler (and the engine barrel) imports `engineError()` /
- * `engineSuccess()` from this module to produce consistently typed error
- * results with correct exit codes and pino logging.
- *
- * The STRING_TO_EXIT map is the canonical mapping from string error codes
- * to numeric exit codes. It mirrors ERROR_CODE_TO_EXIT in cli.ts.
- *
- * @remarks
- * Relocated from `packages/cleo/src/dispatch/engines/_error.ts` into
- * `@cleocode/runtime/gateway` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION) so the
- * runtime owns the shared handler dependencies and can assemble the handler map
- * without importing `@cleocode/cleo`. A thin re-export shim remains at the old
- * `engines/_error.ts` path so in-package import sites compile unchanged.
- *
- * Error codes are organized into numeric ranges:
- * - 1-9: General errors (invalid input, file, dependency, validation)
- * - 10-19: Hierarchy errors (parent, depth, siblings, circular deps)
- * - 20-29: Concurrency errors (checksum, modification, collision)
- * - 30-39: Session errors (scope, claims, active task)
- * - 40-47: Verification errors (gates, agents, rounds)
- * - 50-54: Context safeguard (warning through emergency)
- * - 60-67: Orchestrator / protocol errors
- * - 70-79: Nexus errors
- * - 80-94: Lifecycle, artifact, provenance errors
- * - 95-99: Adapter errors
- * - 100+: Special informational codes (not errors)
- */
-
-/**
- * Canonical mapping from string error codes to numeric exit codes.
- *
- * Source of truth: src/types/exit-codes.ts (ExitCode enum).
- * Must stay in sync with ERROR_CODE_TO_EXIT in src/dispatch/adapters/cli.ts.
- */
-declare const STRING_TO_EXIT: Record<string, number>;
-/**
- * Create a typed engine error result with pino logging and correct exit code.
- *
- * @remarks
- * The exit code is derived from the {@link STRING_TO_EXIT} mapping. If the
- * code is not found in the map, exit code 1 (general error) is used.
- * Pino logging is automatically triggered at the appropriate level
- * (error for internal issues, warn for user/domain errors, debug for
- * informational codes). Logging is suppressed under Vitest to keep
- * test output clean.
- *
- * @param code - String error code (e.g., 'E_NOT_FOUND')
- * @param message - Human-readable error message
- * @param options - Optional details, fix command, and alternatives
- * @returns EngineResult with success=false and properly structured error
- *
- * @example
- * ```typescript
- * import { engineError } from './_error.js';
- *
- * return engineError('E_NOT_FOUND', `Task ${id} not found`, {
- *   fix: `cleo show ${id}`,
- *   details: { taskId: id },
- * });
- * ```
- */
-declare function engineError<T>(code: string, message: string, options?: {
-    exitCode?: number;
-    details?: Record<string, unknown>;
-    fix?: string;
-    alternatives?: Array<{
-        action: string;
-        command: string;
-    }>;
-    problemDetails?: ProblemDetails;
-}): EngineResult<T>;
-
-/**
- * Minimal meta shape carrying the request ID for RFC 7807 `instance` population.
- *
- * Callers may pass the dispatch-layer `DispatchRequest.requestId` (or any
- * other correlation identifier) so that the resulting `problemDetails.instance`
- * URI uniquely identifies the specific error occurrence.
- */
-interface ErrorMeta {
-    /** Unique request identifier (used as the RFC 7807 `instance` field). */
-    requestId?: string;
-}
-/**
- * Convert any caught value into an {@link EngineResult}, forwarding the rich
- * `fix`, `details`, and `alternatives` fields when the caught value is a
- * `CleoError` (or structurally compatible object).
- *
- * @remarks
- * This is the canonical catch-block helper for all dispatch engines. It
- * replaces the previous pattern of:
- * ```typescript
- * const code = (err as { code?: number })?.code;
- * if (code === 4) return engineError('E_NOT_FOUND', …);
- * …
- * ```
- * with a single call that preserves every field the core layer attached.
- *
- * The `fallbackCode` is used when the numeric `err.code` is not present in
- * the {@link STRING_TO_EXIT} mapping (e.g. unknown exit codes, plain `Error`
- * instances, or values thrown by non-CLEO code).
- *
- * RFC 7807 `problemDetails` is always populated from the resolved code, message,
- * and exit code. The optional `meta.requestId` is forwarded to the `instance`
- * field so every error occurrence is uniquely identifiable.
- *
- * @param err - The caught value (unknown type)
- * @param fallbackCode - String error code to use when mapping fails
- * @param fallbackMessage - Human-readable message when `err.message` is absent
- * @param meta - Optional dispatch meta carrying `requestId` for RFC 7807 `instance`
- * @returns EngineResult with all available rich fields propagated
- *
- * @example
- * ```typescript
- * import { cleoErrorToEngineError } from './_error.js';
- *
- * } catch (err: unknown) {
- *   return cleoErrorToEngineError(err, 'E_NOT_INITIALIZED', 'Task database not initialized');
- * }
- * ```
- *
- * @example With requestId for RFC 7807 instance field:
- * ```typescript
- * } catch (err: unknown) {
- *   return cleoErrorToEngineError(err, 'E_NOT_FOUND', 'Not found', { requestId });
- * }
- * ```
- */
-declare function cleoErrorToEngineError<T>(err: unknown, fallbackCode: string, fallbackMessage: string, meta?: ErrorMeta): EngineResult<T>;
-
-/**
- * Parse all templates from the repo's .github/ISSUE_TEMPLATE/ directory.
- *
- * @remarks
- * Delegates to the core template parser and adapts the result to the
- * dispatch EngineResult type.
- *
- * @param projectRoot - Absolute path to the project root
- * @returns EngineResult containing the parsed template configuration
- *
- * @example
- * ```typescript
- * const result = parseIssueTemplates('/path/to/project');
- * if (result.success) {
- *   console.log(result.data.templates);
- * }
- * ```
- */
-declare function parseIssueTemplates(projectRoot: string): EngineResult<_cleocode_core_internal.TemplateConfig>;
-/**
- * Get template config for a specific subcommand (bug/feature/help).
- *
- * @remarks
- * Looks up a specific template by subcommand name from the project's
- * issue template directory.
- *
- * @param projectRoot - Absolute path to the project root
- * @param subcommand - Template subcommand identifier (e.g. "bug", "feature")
- * @returns EngineResult containing the matched issue template
- *
- * @example
- * ```typescript
- * const result = getTemplateForSubcommand('/path/to/project', 'bug');
- * ```
- */
-declare function getTemplateForSubcommand(projectRoot: string, subcommand: string): EngineResult<_cleocode_core_internal.IssueTemplate>;
-/**
- * Generate and cache the config as .cleo/issue-templates.json.
- *
- * @remarks
- * Parses all templates and writes the resulting config to disk for caching.
- *
- * @param projectRoot - Absolute path to the project root
- * @returns EngineResult containing the generated template configuration
- *
- * @example
- * ```typescript
- * const result = await generateTemplateConfig('/path/to/project');
- * ```
- */
-declare function generateTemplateConfig(projectRoot: string): Promise<EngineResult<_cleocode_core_internal.TemplateConfig>>;
-/**
- * Validate that labels exist on a GitHub repo.
- *
- * @remarks
- * Compares a set of required labels against the labels found on the repo.
- *
- * @param labels - Labels required by the template
- * @param repoLabels - Labels that exist on the GitHub repo
- * @returns EngineResult with existing and missing label lists
- *
- * @example
- * ```typescript
- * const result = validateLabels(['bug', 'enhancement'], repoLabels);
- * ```
- */
-declare function validateLabels(labels: string[], repoLabels: string[]): EngineResult<{
-    existing: string[];
-    missing: string[];
-}>;
-
-/**
- * Shared exit-code mapping utilities for the transport-agnostic gateway.
- *
- * Provides a canonical reverse lookup from numeric exit code to string error code,
- * shared between the gateway engine helpers and every transport adapter (CLI,
- * MCP, RPC, HTTP).
- *
- * @remarks
- * Relocated from `packages/cleo/src/dispatch/lib/exit-codes.ts` into
- * `@cleocode/runtime/gateway` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION) so the
- * runtime can host the shared handler dependencies without importing
- * `@cleocode/cleo`. A thin re-export shim remains at the old path.
- *
- * The forward mapping (string → number) lives in `engine-error.ts` as
- * `STRING_TO_EXIT`. This module derives the inverse on first call and memoises
- * it so engines can resolve a caught `CleoError.code` (numeric) to the
- * string code expected by `engineError()`.
- *
- * @task T374
- * @task T11455
- * @epic T335
- */
-/**
- * Map a numeric CleoError exit code to the canonical string engine error code.
- *
- * @remarks
- * Returns `undefined` when the numeric code is not present in the
- * `STRING_TO_EXIT` map, allowing callers to fall back to their own default.
- *
- * @param numericCode - Numeric exit code from a caught `CleoError.code`
- * @returns Canonical string error code (e.g. `'E_NOT_FOUND'`), or `undefined`
- *
- * @example
- * ```typescript
- * import { mapNumericExitCodeToString } from '../lib/exit-codes.js';
- *
- * const code = mapNumericExitCodeToString(4) ?? 'E_NOT_INITIALIZED';
- * // → 'E_NOT_FOUND'
- * ```
- */
-declare function mapNumericExitCodeToString(numericCode: number | undefined): string | undefined;
-
-/**
- * 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;
-
-/**
- * Singleton accessor for the gateway {@link BackgroundJobManager}.
- *
- * @remarks
- * Relocated from `packages/cleo/src/dispatch/lib/job-manager-accessor.ts` into
- * `@cleocode/runtime/gateway` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION) so the
- * `admin` domain handler resolves the job-manager singleton from the runtime
- * layer rather than a cleo-internal path. A thin re-export shim remains at the
- * old path so any existing import site compiles unchanged.
- *
- * Long-lived hosts (e.g. the daemon) call {@link setJobManager} once at startup;
- * short-lived CLI invocations leave the singleton `null`, and consumers handle
- * the absence gracefully.
- *
- * @task T4820
- * @task T11455
- */
-
-/**
- * Register the process-wide {@link BackgroundJobManager} singleton.
- *
- * @param manager - The manager to expose, or null to unregister a stopped host.
- * @remarks Hosts unregister before closing their store; absence is reported explicitly.
- */
-declare function setJobManager(manager: BackgroundJobManager | null): void;
-/**
- * Retrieve the registered {@link BackgroundJobManager} singleton.
- *
- * @returns The registered manager, or `null` when running in a short-lived
- * host (e.g. a one-shot CLI invocation) that never called {@link setJobManager}.
- */
-declare function getJobManager(): BackgroundJobManager | null;
-
-/**
- * MCP wire types for the `@cleocode/runtime/gateway/mcp` transport adapter.
- *
- * A deliberately-minimal subset of the Model Context Protocol shapes the
- * adapter needs — no external MCP SDK dependency. Mirrors the legacy
- * `@cleocode/mcp-adapter` `types.ts` so the wire surface is unchanged.
- *
- * @task T11448
- * @epic T11254
- * @saga T11243
- */
-/** JSON Schema property descriptor surfaced for a single tool input field. */
-interface McpInputProperty {
-    /** JSON Schema primitive type (`'string'`, `'number'`, …). */
-    type: string;
-    /** Human-readable description shown in MCP clients. */
-    description: string;
-    /** Allowed values (JSON Schema `enum`) for finite-domain string params. */
-    enum?: readonly string[];
-}
-/**
- * MCP tool definition shape (minimal — no external MCP SDK dependency).
- * Structurally compatible with the legacy `@cleocode/mcp-adapter` `McpTool`.
- */
-interface McpTool {
-    /** Stable tool name (snake_case, e.g. `cleo_sentient_status`). */
-    name: string;
-    /** Human-readable description shown in MCP clients. */
-    description: string;
-    /** JSON Schema for the tool's input parameters. */
-    inputSchema: {
-        type: 'object';
-        properties: Record<string, McpInputProperty>;
-        required?: string[];
-    };
-}
-/** A single content block returned by a tool handler. */
-interface McpContent {
-    type: 'text';
-    text: string;
-}
-/** Result returned by a tool handler over the MCP wire. */
-interface McpToolResult {
-    content: McpContent[];
-    isError?: boolean;
-}
-
-/**
- * MCP stdio transport adapter — routes `tools/call` through the gateway.
- *
- * Serves the Model Context Protocol over stdio (newline-delimited JSON-RPC 2.0)
- * so any MCP-compatible client (Claude Code, LLM-agnostic tools) can discover
- * and invoke CLEO operations. Unlike the legacy standalone `@cleocode/mcp-adapter`
- * — which called the `@cleocode/core` SDK directly — this adapter is a thin
- * TRANSPORT over the unified gateway:
- *
- *   MCP `tools/call` { name, arguments }
- *     → {@link GatewayOperationKey} (via the `mcpExposed` registry subset)
- *     → DispatchRequest { source: 'mcp', gateway, domain, operation, params }
- *     → injected {@link GatewayHandler}.handle()
- *     → DispatchResponse (LAFS envelope)  →  MCP tool result (JSON text content)
- *
- * The adapter owns ONLY wire concerns: JSON-RPC framing, the stdio read loop,
- * `tools/list` generation, error rendering, and `process.exit` on stream close.
- * All domain logic (resolution, validation, middleware, handler execution) lives
- * behind the {@link GatewayHandler} — exactly mirroring how the CLI adapter
- * wraps the same handler. `process.exit` and error-render stay HERE, never in
- * the handlers (R3-T4 contract).
- *
- * `tools/list` is generated from the OPERATIONS registry behind the default-deny
- * `mcpExposed` flag, so the external tool surface is identical to the historical
- * standalone adapter (no behavior change).
- *
- * @task T11448
- * @epic T11254
- * @saga T11243
- */
-
-/**
- * Route a single MCP `tools/call` through the gateway handler.
- *
- * Resolves the tool name to a `(domain, operation)` key against the exposed
- * (`mcpExposed`) registry subset, builds a `source: 'mcp'` {@link DispatchRequest},
- * and delegates to the injected {@link GatewayHandler}. Unknown tool names and
- * thrown handler errors are rendered as MCP error results — never propagated as
- * `process.exit` from this layer.
- *
- * @param handler - The injected transport-neutral gateway handler.
- * @param toolName - The MCP `tools/call` tool name.
- * @param args - The parsed tool arguments (already JSON-decoded by the client).
- * @returns An MCP {@link McpToolResult}.
- */
-declare function callTool(handler: GatewayHandler, toolName: string, args: Record<string, unknown>): Promise<McpToolResult>;
-/**
- * Options for {@link startMcpServer}.
- */
-interface McpServerOptions {
-    /** Inbound stream (defaults to `process.stdin`). */
-    input?: NodeJS.ReadableStream;
-    /** Outbound stream (defaults to `process.stdout`). */
-    output?: NodeJS.WritableStream;
-    /**
-     * Whether to call `process.exit(0)` when the input stream closes.
-     * Defaults to `true` (production stdio). Tests pass `false`.
-     */
-    exitOnClose?: boolean;
-}
-/**
- * Start the MCP stdio server over the gateway.
- *
- * Reads newline-delimited JSON-RPC 2.0 requests from the input stream, routes
- * `tools/call` through the injected {@link GatewayHandler}, and writes responses
- * to the output stream. Each inbound line must be one complete JSON-RPC request.
- *
- * The caller assembles the {@link GatewayHandler} (via `createGatewayHandler`
- * with its domain handlers + middleware) and injects it here — this adapter
- * 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 - Optional stream + lifecycle overrides (defaults to stdio).
- */
-declare function startMcpServer(handler: GatewayHandler, opts?: McpServerOptions): void;
-
-/**
- * MCP tool-name <-> gateway-operation mapping.
- *
- * The MCP wire protocol identifies a tool by a single flat `name` string
- * (snake_case, e.g. `cleo_sentient_propose_list`), whereas the gateway routes
- * on a `(gateway, domain, operation)` triple (e.g.
- * `query / sentient / propose.list`). This module is the bijective bridge
- * between the two surfaces:
- *
- *   gateway op  →  MCP tool name   {@link operationToToolName}
- *   MCP tool name  →  domain+operation   {@link toolNameToOperationKey}
- *
- * ## Naming convention (frozen — matches the legacy `@cleocode/mcp-adapter`)
- *
- * `cleo_<domain>_<operation>` where every `.` and `-` in the dotted operation
- * name becomes `_`. The three historically-exposed tools therefore map as:
- *
- *   | gateway op                  | MCP tool name                  |
- *   |-----------------------------|--------------------------------|
- *   | `sentient` · `status`       | `cleo_sentient_status`         |
- *   | `sentient` · `propose.list` | `cleo_sentient_propose_list`   |
- *   | `sentient` · `propose.enable` | `cleo_sentient_propose_enable` |
- *
- * Preserving this exact mapping is what guarantees R3-T4's "no behavior change
- * to the MCP tool surface" acceptance criterion.
- *
- * @task T11448
- * @epic T11254
- * @saga T11243
- */
-
-/** Prefix every CLEO MCP tool name carries. */
-declare const MCP_TOOL_PREFIX = "cleo_";
-/**
- * Identifies a gateway operation by its `(domain, operation)` pair. The CQRS
- * gateway resolves which `Gateway` ('query' | 'mutate') the pair belongs to via
- * the operation registry, so the MCP adapter does not need to carry it.
- */
-interface GatewayOperationKey {
-    /** Canonical domain (e.g. `'sentient'`). */
-    readonly domain: string;
-    /** Dotted operation name (e.g. `'propose.list'`). */
-    readonly operation: string;
-}
-/**
- * Derive the flat MCP tool name for a gateway operation.
- *
- * @param op - An {@link OperationDef} (or any object carrying `domain` +
- *   `operation`) from the registry.
- * @returns The MCP tool name, e.g. `'cleo_sentient_propose_list'`.
- */
-declare function operationToToolName(op: Pick<OperationDef, 'domain' | 'operation'>): string;
-/**
- * Resolve an MCP tool name back to its `(domain, operation)` gateway key.
- *
- * The reverse of {@link operationToToolName} cannot recover dots vs dashes from
- * the snake_case wire form, so resolution is performed against the provided
- * `exposed` set (the same `mcpExposed: true` subset used to build `tools/list`).
- * This keeps the mapping exact and rejects unknown tool names.
- *
- * @param toolName - The MCP `tools/call` tool name.
- * @param exposed - The exposed operation defs (the `mcpExposed` subset).
- * @returns The matching {@link GatewayOperationKey}, or `undefined` when the
- *   tool name does not correspond to any exposed operation.
- */
-declare function toolNameToOperationKey(toolName: string, exposed: readonly OperationDef[]): GatewayOperationKey | undefined;
-
-/**
- * MCP `tools/list` generation from the OPERATIONS registry.
- *
- * The MCP tool surface is **default-deny**: only {@link OperationDef} entries
- * that explicitly set `mcpExposed: true` are surfaced. This replaces the legacy
- * `@cleocode/mcp-adapter`'s hand-maintained `ALL_TOOLS` array with a single
- * generation point driven by the canonical registry — promoting a new tool is
- * now one `mcpExposed: true` edit in `@cleocode/contracts`, not a fork-and-copy
- * into a standalone adapter.
- *
- * @task T11448
- * @epic T11254
- * @saga T11243
- */
-
-/**
- * The subset of OPERATIONS surfaced over MCP (default-deny `mcpExposed` filter).
- *
- * @returns Every {@link OperationDef} with `mcpExposed === true`, in registry
- *   order. Empty when no operation opts in.
- */
-declare function exposedOperations(): OperationDef[];
-/**
- * Convert a single exposed {@link OperationDef} into its MCP tool definition.
- *
- * @param op - An operation with `mcpExposed === true`.
- * @returns The MCP {@link McpTool} (name + description + inputSchema).
- */
-declare function operationToMcpTool(op: OperationDef): McpTool;
-/**
- * Generate the full MCP `tools/list` payload from the registry.
- *
- * @returns Every exposed operation rendered as an {@link McpTool}, in registry
- *   order (stable across calls).
- */
-declare function buildToolsList(): McpTool[];
-
-/**
- * Dispatch-local metadata factory.
- *
- * Generates LAFS-conformant metadata for dispatch layer responses.
- * Generates LAFS-conformant metadata for dispatch responses.
- *
- * @task T4772
- */
-
-/**
- * Create metadata for a dispatch response.
- *
- * @param gateway   - Gateway name (e.g., 'query', 'mutate')
- * @param domain    - Domain name (e.g., 'tasks', 'session')
- * @param operation - Operation name (e.g., 'show', 'list')
- * @param startTime - Timestamp from Date.now() at start of request
- * @param source    - Where the request originated
- * @param requestId - Optional pre-generated request ID
- * @param sessionId - Optional session ID to include in metadata
- * @param originSessionId - Optional root workflow/saga session ID
- * @param executionSessionId - Optional execution-attempt session ID
- * @returns Metadata conforming to DispatchResponse['meta']
- *
- * @task T4772
- * @task T4959
- */
-declare function createDispatchMeta(gateway: string, domain: string, operation: string, startTime: number, source?: Source, requestId?: string, sessionId?: string | null, originSessionId?: string | null, executionSessionId?: string | null): DispatchResponse['meta'];
-
-/**
- * nexus-decorator — stamps `meta._nexus` on every nexus-domain dispatch response.
- *
- * Wave 2 of the Nexus Restructure (T9146). Reads `getNexusDescriptor(opId)` from
- * the W1 SSoT (`NEXUS_SCOPE_MAP`) and injects the namespaced `_nexus` block into
- * `DispatchResponse['meta']`.
- *
- * Usage:
- * ```ts
- * const decorated = stampNexusMeta(response, operation, params);
- * ```
- *
- * The `suggestedNext` field uses a structured form (not literal display strings).
- * Display strings are derived by `formatSuggestedNext()` for human/markdown renderers.
- *
- * Typed-registry gate: `validateSuggestedNext()` fails the build (throws at import-time
- * in test mode) if any `suggestedNext.op` is absent from `NEXUS_SCOPE_MAP`.
- *
- * @remarks
- * Relocated from `packages/cleo/src/dispatch/nexus-decorator.ts` into
- * `@cleocode/runtime/gateway` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION) so the
- * nexus domain handler can import it from the runtime layer rather than a
- * cleo-internal path. The module is pure (`@cleocode/contracts` only). A thin
- * re-export shim remains at the old path for the renderer / CLI import sites.
- *
- * @task T9146
- * @task T11455
- * @module runtime/gateway/nexus-decorator
- */
-
-/**
- * Assert that every `suggestedNext.op` in a list resolves to a known
- * NEXUS_SCOPE_MAP entry.
- *
- * Throws `TypeError` at runtime (caught by tests and CI) if an unknown op
- * is referenced — acting as a build-time gate when imported in test suites.
- *
- * @throws {TypeError} if any `op` is absent from `NEXUS_SCOPE_MAP`
- * @task T9146
- */
-declare function validateSuggestedNext(suggestions: ReadonlyArray<SuggestedNextOp>): void;
-/**
- * Derive a human-readable display string from a {@link SuggestedNextOp}.
- *
- * Example: `"cleo nexus context --project-id myproj (read-only, no confirmation needed)"`
- */
-declare function formatSuggestedNext(s: SuggestedNextOp): string;
-/**
- * Stamp `meta._nexus` onto a nexus-domain {@link DispatchResponse}.
- *
- * Call this after every nexus handler produces its `DispatchResponse`. The
- * function is a pure transformer — it returns a new object with `meta._nexus`
- * merged in.
- *
- * @param response  - The original dispatch response from the nexus handler.
- * @param operation - The nexus operation key (must be a `keyof NexusOps`).
- * @param params    - Raw params passed to the handler (used for binding-source resolution).
- * @param isTopLevel - Whether this is a top-level CLI invocation (not a sub-call).
- * @returns A new `DispatchResponse` with `meta._nexus` populated.
- *
- * @task T9146
- */
-declare function stampNexusMeta(response: DispatchResponse, operation: string, params: Record<string, unknown>, isTopLevel?: boolean): DispatchResponse;
-/**
- * Pick the decorator-stamped fields (`_nexus`, `deprecated`) from a dispatch
- * response's `meta` so they can be forwarded via `cliOutput`'s `extensions`
- * option into the emitted LAFS envelope.
- *
- * Without this, `cliOutput(response.data, ...)` discards `response.meta._nexus`
- * + `response.meta.deprecated` (T9393 defect). Canonical CLI meta fields
- * (`operation`, `requestId`, `timestamp`) are intentionally NOT forwarded —
- * those are produced by {@link createCliMeta} on the CLI side.
- *
- * @task T9393
- */
-declare function pickDecoratorMetaExtensions(responseMeta: DispatchResponseMeta | undefined): Record<string, unknown>;
-/**
- * Build CLI envelope extensions for nexus commands that bypass the dispatcher
- * (e.g. `cleo nexus status` SSoT-EXEMPT path). Runs the same {@link stampNexusMeta}
- * logic against a synthetic response so the resulting envelope still carries
- * `meta._nexus` (and `meta.deprecated` for alias shims).
- *
- * Use this only where the command does NOT call `dispatchRaw`. When you have a
- * real dispatch response, use {@link pickDecoratorMetaExtensions} on
- * `response.meta` instead — that path already ran the decorator.
- *
- * @task T9393
- */
-declare function buildNexusMetaExtensions(operation: string, params?: Record<string, unknown>): Record<string, unknown>;
-
-/**
- * Gateway-level path constants shared by domain handlers.
- *
- * @remarks
- * The `orchestrate` and `admin` (smoke-provider) domain handlers join a handful
- * of well-known `.cleo/` path segments when locating workflow definitions and
- * the BRAIN database. Those constants were previously defined in
- * `packages/cleo/src/cli/paths.ts` (a CLI-internal leaf), which coupled the
- * handler subgraph to `@cleocode/cleo`.
- *
- * To let `@cleocode/runtime` assemble the handler map WITHOUT importing
- * `@cleocode/cleo` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION), the constants the
- * handlers actually consume are hosted here as the canonical source. The
- * CLI-side `cli/paths.ts` re-exports them so the rest of the CLI (backup /
- * restore / doctor) keeps importing from its established surface — there is a
- * single definition, no drift.
- *
- * @task T090
- * @task T11455
- */
-/** Name of the project-local CLEO data directory (`.cleo`). */
-declare const CLEO_DIR_NAME: ".cleo";
-/** Subdirectory under `.cleo/` that stores CANT workflow definitions. */
-declare const WORKFLOWS_SUBDIR: "workflows";
-/** Project-local SQLite database filename for cognitive memory (BRAIN). */
-declare const BRAIN_DB_FILENAME: "brain.db";
-
-/**
- * Unified CQRS Dispatch Layer -- Middleware Pipeline
- *
- * Provides compose() to chain multiple Middleware functions together
- * into a single executable pipeline.
- *
- * @epic T4820
- * @task T4815
- */
-
-/**
- * Composes an array of Middleware functions into a single Middleware function.
- * Execution flows through the array from first to last, and returns bubble
- * back up from last to first.
- *
- * @remarks
- * Uses an index-tracked dispatch function to prevent `next()` from being
- * called multiple times within a single middleware. If the array is empty,
- * a passthrough middleware that immediately calls `next()` is returned.
- *
- * @param middlewares - Array of middleware functions to chain
- * @returns A single composed Middleware function
- *
- * @example
- * ```typescript
- * import { compose } from './pipeline.js';
- *
- * const pipeline = compose([sanitizer, rateLimiter, protocolEnforcement]);
- * const response = await pipeline(request, handler);
- * ```
- */
-declare function compose(middlewares: Middleware[]): Middleware;
-
-/**
- * Unified CQRS Dispatch Layer -- Operation Registry (shim)
- *
- * The `OPERATIONS` data array was relocated to
- * `@cleocode/contracts/dispatch/operations-registry` in T10061 / T9833b
- * (E-CLI-BOUNDARY · Saga T9831 SG-ARCH-SOLID). This file is now a thin
- * re-export shim that:
- *
- *   1. Re-exports `OPERATIONS` from contracts so every downstream consumer
- *      that already imports `{ OPERATIONS }` from this path continues to
- *      compile unchanged.
- *   2. Keeps the pure utility / derivation functions (`resolve`,
- *      `validateRequiredParams`, `getByDomain`, etc.) that operate on
- *      the data and are rightly colocated with the CLI package.
- *
- * @epic T4820
- * @task T4814, T5241, T5615, T10061
- */
-
-/** The single source of truth for all operations in CLEO (data lives in @cleocode/contracts). */
-declare const OPERATIONS: OperationDef[];
-/**
- * Derive a gateway operation matrix from the registry.
- *
- * Returns `Record<string, string[]>` containing:
- * - All canonical domains with their operations
- *
- * This is the SINGLE derivation point — gateways use this instead of
- * maintaining independent operation lists.
- */
-declare function deriveGatewayMatrix(gateway: Gateway): Record<string, string[]>;
-/**
- * Get all accepted domain names for a gateway (canonical only).
- */
-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.
- */
-declare function validateRequiredParams(def: OperationDef, params?: Record<string, unknown>): string[];
-/** Get all operations for a specific canonical domain. */
-declare function getByDomain(domain: CanonicalDomain): OperationDef[];
-/** Get all operations for a specific gateway. */
-declare function getByGateway(gateway: Gateway): OperationDef[];
-/** Get all operations available at or below a specific tier. */
-declare function getByTier(tier: Tier): OperationDef[];
-/** Get a list of canonical domains that actually have operations registered. */
-declare function getActiveDomains(): CanonicalDomain[];
-/**
- * Returns summary counts of operations for module validation.
- */
-declare function getCounts(): {
-    query: number;
-    mutate: number;
-    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.
- *
- * Relocated from `packages/cleo/src/dispatch` (R3-T3 · T11447 ·
- * SG-RUNTIME-UNIFICATION) so the dispatcher is owned by the runtime layer and
- * can be driven by ANY transport adapter — CLI, MCP, RPC, HTTP — not just the
- * CLI. Mirrors the `@cleocode/runtime/daemon` subpath (R2).
- *
- * The CLI adapter (`packages/cleo/src/dispatch/adapters/cli.ts`) and the
- * domain handlers + transport-specific middleware stay in `packages/cleo`; they
- * are INJECTED into the {@link Dispatcher} via {@link DispatcherConfig}. The
- * gateway contract itself lives in `@cleocode/contracts/gateway` (R3-T2).
- *
- * `packages/cleo/src/dispatch/{dispatcher,registry,lib/meta,middleware/pipeline}.ts`
- * remain as thin re-export shims pointing here, so the in-package import sites
- * (cli adapter, ~18 registry consumers, getCliDispatcher) compile unchanged.
- *
- * @epic T4820
- * @task T11447
- * @saga T11243
- */
-
-/**
- * Transport-agnostic gateway entrypoint. Wraps a configured {@link Dispatcher}
- * (`compose(middlewares) → DomainHandler`) behind a single `handle()` call that
- * every transport adapter (CLI/MCP/RPC/HTTP) invokes uniformly. The adapter
- * owns wire concerns (error-render, `process.exit`, serialization); the handler
- * only resolves, validates, runs middleware, and returns a {@link DispatchResponse}.
- */
-interface GatewayHandler {
-    /** Route one gateway request through the dispatch pipeline. */
-    handle(req: DispatchRequest): Promise<DispatchResponse>;
-}
-/**
- * Build a {@link GatewayHandler} from a {@link DispatcherConfig} (injected
- * domain handlers + middleware). The returned handler is transport-neutral.
- */
-declare function createGatewayHandler(config: DispatcherConfig): GatewayHandler;
-
-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 };
+export { type DecodeResult, LineBuffer, type RpcServerHandle, type RpcServerOptions, buildErrorFrame, decodeLine, encodeFrame, routeFrame, startRpcServer };