@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/channels/control.js

@@ -1,12 +1,21 @@
-import { INVALID_COMMAND_CODE } from "../session.js";
-import { timingSafeEqual } from "node:crypto";
+import { INVALID_COMMAND_CODE, SESSIONS_UNAVAILABLE_CODE, UNSUPPORTED_CAPABILITY_CODE, UPDATE_FIELDS, } from "../session.js";
 import { parseRouteKey, withoutBody } from "./serve.js";
 import { log } from "../log.js";
 import { readBodyCapped } from "./body.js";
-import { MAX_BODY_BYTES, createInvokeHandler, sseHeartbeat } from "./http.js";
+import { MAX_BODY_BYTES, createInvokeHandler } from "./http.js";
+import { sseResponse } from "./sse.js";
 import { text } from "./respond.js";
+import { secretEquals } from "./secret.js";
 /** The prefix this plane OWNS: everything under it is the plane's to answer. */
 const CONTROL_PREFIX = "/control";
+/** The one variable segment in this plane's paths: a percent-encoded session id. Written into route
+ *  keys so the table reads like the URLs it serves. */
+const SESSION_SEGMENT = "{session}";
+/** The token, when the DEPLOYER owns it rather than the box (`mountSessionControl` reads it, `deploy`
+ *  carries it). Declared here with the prefix because both are the plane's public names: the serving
+ *  side and the deploy side must spell it identically, and a rename that hits only one of them fails
+ *  silently — the box mints its own and every caller the runbook told gets a 401. */
+export const CONTROL_TOKEN_ENV = "FASTAGENT_CONTROL_TOKEN";
 const json = (value, status = 200) => new Response(`${JSON.stringify(value)}\n`, { status, headers: { "content-type": "application/json" } });
 /**
  * The plane as one mounted sub-application rather than routes sharing a prefix.
@@ -26,23 +35,58 @@ const json = (value, status = 200) => new Response(`${JSON.stringify(value)}\n`,
  * the WRITE routes unreachable while reads work.
  */
 function planeApp(routes) {
-    // Normalised keys (see serve.ts): the method is upper-cased when parsed.
-    const byKey = new Map(Object.entries(routes).map(([key, handler]) => {
+    /** A route key's path split into segments, with `{session}` marked. Paths are matched SEGMENT BY
+     *  SEGMENT rather than by regex because a session id is an opaque Caller string: percent-encoded
+     *  it can contain anything, and `URL.pathname` leaves `%2F` encoded — so splitting on `/` cannot
+     *  be fooled by an id that contains one. */
+    const compiled = Object.entries(routes).map(([key, handler]) => {
         const { method, path } = parseRouteKey(key);
-        return [method ? `${method} ${path}` : path, handler];
-    }));
-    const methodsByPath = new Map();
-    for (const key of Object.keys(routes)) {
-        const { method, path } = parseRouteKey(key);
-        const methods = methodsByPath.get(path) ?? new Set();
-        if (method)
-            methods.add(method);
-        methodsByPath.set(path, methods);
-    }
+        return { method, path, segments: path.split("/"), handler };
+    });
+    const match = (path) => {
+        const segments = path.split("/");
+        const hits = [];
+        for (const route of compiled) {
+            if (route.segments.length !== segments.length)
+                continue;
+            let session;
+            let ok = true;
+            for (const [i, expected] of route.segments.entries()) {
+                const actual = segments[i];
+                if (expected === SESSION_SEGMENT) {
+                    // The one place a path segment becomes a Caller id again. An empty segment is not an id —
+                    // it would address a session no other call can name.
+                    if (actual === "") {
+                        ok = false;
+                        break;
+                    }
+                    try {
+                        session = decodeURIComponent(actual);
+                    }
+                    catch {
+                        // `%zz` and friends: not an id any client could have produced, so this path matches
+                        // nothing and falls through to the plane's own 404. Decoding runs BEFORE the try that
+                        // guards the handlers, so letting it throw would leave the boundary entirely — no CORS
+                        // headers, no log line, and a rejected promise for an embedder mounting this handler
+                        // directly. The query-parameter form this replaced decoded leniently and could not.
+                        ok = false;
+                        break;
+                    }
+                }
+                else if (expected !== actual) {
+                    ok = false;
+                    break;
+                }
+            }
+            if (ok)
+                hits.push({ route, session });
+        }
+        return hits;
+    };
     // Per PATH, stating what it actually serves — omitting a method it does serve has the browser
     // refuse a call that would have worked. `HEAD` is that case: every GET route answers it.
-    const allowMethods = (path, requested) => {
-        const methods = new Set(methodsByPath.get(path) ?? []);
+    const allowMethods = (hits, requested) => {
+        const methods = new Set(hits.flatMap((h) => (h.route.method ? [h.route.method] : [])));
         if (methods.has("GET"))
             methods.add("HEAD");
         // The requested method is always allowed, even where this path does not serve it: preflight is a
@@ -55,22 +99,18 @@ function planeApp(routes) {
     };
     return async (req) => {
         const path = new URL(req.url).pathname;
-        const known = methodsByPath.has(path);
+        const hits = match(path);
         const answer = async () => {
             // A preflight carries no token — that is its purpose — so it is answered before auth, and for
             // ANY path under the prefix: gating it would stop the request the 404 below is waiting for.
             if (req.method === "OPTIONS")
                 return new Response(null, { status: 204 });
-            const handler = byKey.get(`${req.method} ${path}`) ?? byKey.get(path);
-            if (handler)
-                return await handler(req);
-            if (known && req.method === "HEAD") {
-                const get = byKey.get(`GET ${path}`);
-                if (get)
-                    return await get(req);
-            }
+            const hit = hits.find((h) => h.route.method === req.method) ??
+                (req.method === "HEAD" ? hits.find((h) => h.route.method === "GET") : undefined);
+            if (hit)
+                return await hit.route.handler(req, hit.session ?? "");
             // 404 vs 405 as in the host router: a client reads 404 as "this serve predates the route".
-            if (known)
+            if (hits.length > 0)
                 return text("method not allowed\n", 405);
             return text("not found\n", 404);
         };
@@ -89,34 +129,31 @@ function planeApp(routes) {
         // THE single exit. Every reply above — route, preflight, 404, 405, 500 — leaves through here.
         res.headers.set("access-control-allow-origin", "*");
         res.headers.set("access-control-allow-headers", "authorization, content-type");
-        res.headers.set("access-control-allow-methods", allowMethods(path, req.headers.get("access-control-request-method")));
+        res.headers.set("access-control-allow-methods", allowMethods(hits, req.headers.get("access-control-request-method")));
         return res;
     };
 }
 // ONE constant for every Prompt-bearing wire surface (imported from the invoke channel — the two
-// caps cannot drift apart): commands carry Prompts, which may ride base64 images.
-const DISPATCH_BODY_LIMIT = MAX_BODY_BYTES;
+// caps cannot drift apart): actions carry Prompts, which may ride base64 images.
+const ACTION_BODY_LIMIT = MAX_BODY_BYTES;
 /**
  * Parse-don't-validate at the wire: a remote client can send any JSON, and the hub's inner layers
- * trust command shapes (a malformed `steer` would surface as an ENGINE failure misclassified as
- * `run_command_failed`). Returns the typed command, or undefined for anything malformed — which
+ * trust action shapes (a malformed `steer` would surface as an ENGINE failure misclassified as
+ * `run_command_failed`). Returns the typed action, or undefined for anything malformed — which
  * answers protocol-level `invalid_command`, same responsibility as the hub's unknown-type default.
  */
-function parseWireCommand(raw) {
-    // COMPILE-TIME drift guard, variant level: this switch hand-mirrors the SessionCommand union,
-    // and a new variant added in session.ts would otherwise compile clean while the wire answers it
+function parseWireAction(raw) {
+    // COMPILE-TIME drift guard, variant level: this switch hand-mirrors the SessionAction union, and a
+    // new variant added in session.ts would otherwise compile clean while the wire answers it
     // `invalid_command` — silently breaking local/remote isomorphism. A new variant must break THIS
     // line first, forcing the decision of how the wire carries it.
-    const _commandDriftGuard = {
+    const _actionDriftGuard = {
         steer: true,
         follow_up: true,
         abort: true,
         compact: true,
-        set_model: true,
-        set_thinking: true,
-        navigate: true,
     };
-    void _commandDriftGuard;
+    void _actionDriftGuard;
     if (typeof raw !== "object" || raw === null)
         return undefined;
     const c = raw;
@@ -134,8 +171,8 @@ function parseWireCommand(raw) {
         // failure this parser exists to prevent (ImageRef shape from src/session.ts's Prompt).
         return images === undefined || (Array.isArray(images) && images.every(imageOk));
     };
-    // REBUILD, never pass raw through: "typed command out" must be construction, not assertion — a
-    // passed-through object would carry arbitrary extra keys into the engine.
+    // REBUILD, never pass raw through: "typed out" must be construction, not assertion — a passed-
+    // through object would carry arbitrary extra keys into the engine.
     const rebuildPrompt = (p) => {
         const images = p.images;
         return {
@@ -162,159 +199,216 @@ function parseWireCommand(raw) {
             return c.instructions === undefined || typeof c.instructions === "string"
                 ? { type: "compact", instructions: c.instructions }
                 : undefined;
-        case "set_model":
-            return typeof c.model === "string" ? { type: "set_model", model: c.model } : undefined;
-        case "set_thinking":
-            return typeof c.level === "string" ? { type: "set_thinking", level: c.level } : undefined;
-        case "navigate":
-            return typeof c.targetId === "string" ? { type: "navigate", targetId: c.targetId } : undefined;
         default:
             return undefined;
     }
 }
 /**
- * Create the control plane as a mountable prefix owner: `GET
- * /control/capabilities|commands|state|entries|events` + `POST /control/dispatch`, all
- * bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
- * The plane OWNS {@link CONTROL_PREFIX}: it is mounted as one sub-application, answers its own
- * 404/405/preflight, and puts CORS headers on every reply — see {@link planeApp}.
+ * Parse a PATCH body into a session update — or into the REASON it is not one, because the two
+ * reasons are different answers to the client. An unknown KEY means this serve does not have that
+ * field (a newer client talking to an older serve, or a typo), and the client's move is to drop it:
+ * `unsupported_capability`, the same code the in-process path answers, so the two planes stay
+ * isomorphic. A wrong VALUE TYPE is a malformed payload: `invalid_command`. Neither is dropped
+ * silently, which would answer `ok: true` for a patch that set nothing.
+ */
+function parseWireUpdate(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        return { code: INVALID_COMMAND_CODE, message: "expected an object of session properties" };
+    }
+    const c = raw;
+    const unknown = Object.keys(c).filter((key) => !UPDATE_FIELDS.includes(key));
+    if (unknown.length > 0) {
+        return {
+            code: UNSUPPORTED_CAPABILITY_CODE,
+            message: `update field(s) ${unknown.join(", ")} — capabilities().updatable lists what this serve sets`,
+        };
+    }
+    const patch = {};
+    // The field list is the CONTRACT's (`UPDATE_FIELDS`), not a copy: a field added to SessionUpdate
+    // travels here without anyone remembering to, and one removed cannot linger.
+    for (const field of UPDATE_FIELDS) {
+        const value = c[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string") {
+            return { code: INVALID_COMMAND_CODE, message: `${field} must be a string` };
+        }
+        patch[field] = value;
+    }
+    return { patch };
+}
+/**
+ * Create the control plane as a mountable prefix owner — a RESTful surface over
+ * {@link CONTROL_PREFIX}: sessions are a collection, a session is a resource, its history and event
+ * stream are sub-resources, and the things that HAPPEN to a run are posted to `…/actions`.
+ * The plane OWNS the prefix: it answers its own 404/405/preflight and puts CORS headers on every
+ * reply — see {@link planeApp}.
  */
 export function createControlPlane(control, options) {
     return mountControlPlane(controlPlaneRoutes(control, options));
 }
 /** Mount a plane route table as a {@link PrefixMount} — the plane owns a PREFIX, while a route
- *  table is a set of literal paths. */
+ *  table is a set of paths, at most one segment of which is a session id. */
 export function mountControlPlane(routes) {
     return { prefix: CONTROL_PREFIX, handler: planeApp(routes) };
 }
-/** The plane's route table. Exported so the conformance sweeps derive their route list from what is
- *  actually mounted, rather than from a hand-kept copy that cannot notice a new route. */
+/**
+ * The plane's route table. Exported so the conformance sweeps derive their route list from what is
+ * actually mounted, rather than from a hand-kept copy that cannot notice a new route.
+ *
+ * The shape mirrors the contract: a collection, a resource, its sub-resources, and one action
+ * endpoint. What a session IS gets `GET`; what a session HAS gets `PATCH` (properties, last-wins);
+ * what happens TO a run gets `POST …/actions` (not a property — an event in time). `PUT` on a
+ * session id is the fork, and it is a PUT because a fork is idempotent by construction: the id is
+ * the caller's, the body says where the history came from, and repeating it changes nothing.
+ */
 export function controlPlaneRoutes(control, options) {
     const { token } = options;
     if (!token)
         throw new Error("createControlPlane: a bearer token is required (empty tokens are not a mode)");
     const epoch = crypto.randomUUID();
-    // Timing-safe: the bearer token is this surface's ONLY auth (and the --tunnel warning names it
-    // as the sole protection on a public URL) — a plain === would leak byte-by-byte via timing.
-    const expected = Buffer.from(`Bearer ${token}`);
-    const authed = (req) => {
-        const header = Buffer.from(req.headers.get("authorization") ?? "");
-        return header.length === expected.length && timingSafeEqual(header, expected);
-    };
+    // The bearer token is this surface's ONLY auth (and the --tunnel warning names it as the sole
+    // protection on a public URL).
+    const expected = `Bearer ${token}`;
+    const authed = (req) => secretEquals(req.headers.get("authorization"), expected);
     const invokeHandler = options.agent ? createInvokeHandler(options.agent) : undefined;
-    /** Wrap a handler with auth + the session query param most routes need. */
-    const guard = (handler) => (req) => {
+    /** Authenticate, then hand the handler the pieces every route wants: the request, the URL (for
+     *  query parameters), and the session the PATH named — `""` on the routes that have no id in
+     *  them, which those handlers never read. */
+    const guard = (handler) => (req, session) => {
         if (!authed(req))
             return text("unauthorized\n", 401);
-        return handler(req, new URL(req.url));
+        return handler(req, new URL(req.url), session);
+    };
+    /** Read a JSON body under the shared cap. Answers the Response to send on failure, so a route can
+     *  `if ("error" in read) return read.error`. */
+    const readJson = async (req) => {
+        const body = await readBodyCapped(req, ACTION_BODY_LIMIT);
+        // The 413 names the ceiling: the docs promise images on this plane, and an unexplained
+        // rejection would send a client author hunting everywhere but the cap. Derived from the
+        // constant — a hardcoded "1 MiB" would lie the day the cap changes.
+        if ("tooLarge" in body) {
+            return {
+                error: text(`body too large (limit ${MAX_BODY_BYTES >> 20} MiB — images count base64-inflated)\n`, 413),
+            };
+        }
+        // An empty body is an empty object: `POST …/actions` always carries one, but `PATCH` with
+        // nothing to set is a legal no-op and a client should not have to send `{}` to say so.
+        if (body.text.trim() === "")
+            return { value: {} };
+        try {
+            return { value: JSON.parse(body.text) };
+        }
+        catch {
+            return { error: text("invalid JSON\n", 400) };
+        }
     };
-    // Extraction only — each route still answers its own 400 (the name must not imply enforcement).
-    const sessionParam = (url) => url.searchParams.get("session") ?? undefined;
     return {
+        // The DATA plane, at the prefix rather than under a session: its body already carries the scope
+        // (SPEC `invoke(scope, prompt)`), so a session in the path would be a second place to say it —
+        // and two places to say one thing is a place for them to disagree.
         ...(invokeHandler ? { "POST /control/invoke": guard((req) => invokeHandler(req)) } : {}),
         "GET /control/capabilities": guard(() => json(control.capabilities())),
         "GET /control/commands": guard(async () => json(await control.commands())),
-        "GET /control/state": guard(async (_req, url) => {
-            const session = sessionParam(url);
-            if (!session)
-                return text("missing ?session\n", 400);
-            return json(await control.state(session));
-        }),
-        "GET /control/entries": guard(async (_req, url) => {
-            const session = sessionParam(url);
-            if (!session)
-                return text("missing ?session\n", 400);
-            const since = url.searchParams.get("since") ?? undefined;
-            return json(await control.entries(session, since !== undefined ? { since } : undefined));
-        }),
-        "POST /control/dispatch": guard(async (req) => {
-            const body = await readBodyCapped(req, DISPATCH_BODY_LIMIT);
-            // The 413 names the ceiling: the docs promise images on this plane, and an unexplained
-            // rejection would send a client author hunting everywhere but the cap.
-            if ("tooLarge" in body) {
-                // Derived from the constant — a hardcoded "1 MiB" would lie the day the cap changes.
-                return text(`body too large (limit ${MAX_BODY_BYTES >> 20} MiB — images count base64-inflated)\n`, 413);
-            }
-            let parsed;
+        // The DEPLOYMENT's conversation list — and the one read that may fail: `[]` is what an empty
+        // deployment answers, so a store that cannot be enumerated gets a coded non-2xx instead. 503 +
+        // the code, because the alternative (#309's lesson) is a client that can only classify a bare
+        // 500 as "the endpoint is unreachable" and burns its reconnect budget on a condition
+        // reconnecting cannot fix.
+        "GET /control/sessions": guard(async () => {
             try {
-                parsed = JSON.parse(body.text);
+                return json(await control.sessions.list());
             }
-            catch {
-                return text("invalid JSON\n", 400);
+            catch (error) {
+                // ONLY a store fault becomes the retryable code. A TypeError from our own row building is a
+                // bug, and answering `retryable: true` for it has a client poll forever on something no
+                // retry can fix — so it goes back to the plane's totality boundary, which logs it and
+                // answers 500. An IO error carries an ERRNO `code` (EACCES, ENOTDIR); that is the shape of a
+                // condition the operator can act on.
+                //
+                // The errno SHAPE, not merely "has a string code": Node's own argument-validation errors are
+                // TypeErrors carrying `ERR_INVALID_ARG_TYPE`/`ERR_OUT_OF_RANGE`, so a bug in row building
+                // would otherwise be handed to a client as retryable — the exact case this excludes. Read
+                // through `?.` because a thrown null must reach the boundary as itself, not as a TypeError
+                // from this line that replaces it in the log.
+                const code = error?.code;
+                if (typeof code !== "string" || !/^E[A-Z]+$/.test(code))
+                    throw error;
+                // Logged as well as answered: the catch would otherwise be the one place a store fault is
+                // invisible on the server, since it preempts the boundary that does the logging.
+                log.error(`[control] GET /control/sessions failed: ${String(error)}`);
+                return json({ code: SESSIONS_UNAVAILABLE_CODE, message: String(error), retryable: true }, 503);
             }
-            if (typeof parsed.session !== "string") {
-                return text("expected { session: string, command: SessionCommand }\n", 400);
+        }),
+        // PUT, because a fork is idempotent: this id, holding the history that was at `from`@`at`.
+        // Repeating it answers ok and writes nothing; naming an id that holds a different history is a
+        // conflict, not an overwrite.
+        [`PUT /control/sessions/${SESSION_SEGMENT}`]: guard(async (req, _url, session) => {
+            const read = await readJson(req);
+            if ("error" in read)
+                return read.error;
+            // `JSON.parse("null")` is null, and a body is whatever the client sent: reaching into it
+            // unguarded turns a malformed request into a 500 the client cannot act on.
+            const body = read.value;
+            if (typeof body?.from !== "string" || typeof body.at !== "string") {
+                return text("expected { from: string, at: string }\n", 400);
+            }
+            return json(await control.sessions.fork({ from: body.from, at: body.at, into: session }));
+        }),
+        [`GET /control/sessions/${SESSION_SEGMENT}`]: guard(async (_req, _url, session) => json(await control.sessions.get(session).state())),
+        // PATCH, because these are session PROPERTIES: last-wins, durable, applied by the next turn.
+        [`PATCH /control/sessions/${SESSION_SEGMENT}`]: guard(async (req, _url, session) => {
+            const read = await readJson(req);
+            if ("error" in read)
+                return read.error;
+            const parsed = parseWireUpdate(read.value);
+            // A protocol-level answer carrying the SAME code the hub would have used — the wire must not
+            // be where a client loses the difference between "drop that field" and "fix that value".
+            if (!("patch" in parsed)) {
+                return json({ ok: false, error: { ...parsed, retryable: false } });
             }
-            const command = parseWireCommand(parsed.command);
-            if (!command) {
-                // Malformed shape = a protocol-level answer, mirrored from the hub's unknown-type default.
+            return json(await control.sessions.get(session).update(parsed.patch));
+        }),
+        [`DELETE /control/sessions/${SESSION_SEGMENT}`]: guard(async (_req, _url, session) => json(await control.sessions.get(session).delete())),
+        [`GET /control/sessions/${SESSION_SEGMENT}/entries`]: guard(async (_req, url, session) => {
+            const since = url.searchParams.get("since") ?? undefined;
+            return json(await control.sessions.get(session).entries(since !== undefined ? { since } : undefined));
+        }),
+        // The run actions. Not PATCH: none of them SETS anything — they join, queue, stop, or summarize,
+        // and the outcome arrives on the event stream rather than in the resource's next read.
+        [`POST /control/sessions/${SESSION_SEGMENT}/actions`]: guard(async (req, _url, session) => {
+            const read = await readJson(req);
+            if ("error" in read)
+                return read.error;
+            const action = parseWireAction(read.value);
+            if (!action) {
                 return json({
                     ok: false,
-                    error: { code: INVALID_COMMAND_CODE, message: "malformed command", retryable: false },
+                    error: { code: INVALID_COMMAND_CODE, message: "malformed action", retryable: false },
                 });
             }
+            const s = control.sessions.get(session);
             // The result rides HTTP 200 either way: `ok: false` is a protocol-level answer (rejected
             // before acceptance), not a transport failure.
-            return json(await control.dispatch(parsed.session, command));
+            switch (action.type) {
+                case "steer":
+                    return json(await s.steer(action.prompt));
+                case "follow_up":
+                    return json(await s.followUp(action.prompt));
+                case "abort":
+                    return json(await s.abort());
+                case "compact":
+                    return json(await s.compact(action.instructions !== undefined ? { instructions: action.instructions } : {}));
+            }
         }),
-        "GET /control/events": guard((_req, url) => {
-            const session = sessionParam(url);
-            if (!session)
-                return text("missing ?session\n", 400);
-            const iterator = control.events(session)[Symbol.asyncIterator]();
-            // EAGER registration: issue the first pull NOW, before the Response (and thus the client's
-            // fetch resolution) exists — hub subscription is registered synchronously inside next(), so
-            // "the client saw response headers" implies "events from that moment on will be delivered".
-            // Shrinks the subscribe/backfill race to network reordering instead of a full pull cycle.
-            let pending = iterator.next();
-            // Observed here so a client that disconnects BEFORE the first pull cannot turn a rejecting
-            // events iterator (this is the neutral contract face — any implementation may reject) into a
-            // process-killing unhandledRejection; awaiting `pending` at pull still surfaces the error.
-            pending.catch(() => { });
+        [`GET /control/sessions/${SESSION_SEGMENT}/events`]: guard((_req, _url, session) => {
             let seq = 0;
-            let stopHeartbeat = () => { };
-            const encoder = new TextEncoder();
-            const stream = new ReadableStream({
-                start(controller) {
-                    stopHeartbeat = sseHeartbeat(controller);
-                },
-                async pull(controller) {
-                    let next;
-                    try {
-                        next = await (pending ?? iterator.next());
-                    }
-                    catch (error) {
-                        // A rejecting implementation (the neutral contract permits it) must not leak its
-                        // subscription: an errored stream never gets cancel(), so the unsubscribe and the
-                        // heartbeat teardown happen HERE.
-                        stopHeartbeat();
-                        void iterator.return?.(undefined)?.catch?.(() => { });
-                        controller.error(error);
-                        return;
-                    }
-                    pending = undefined;
-                    if (next.done) {
-                        stopHeartbeat();
-                        controller.close();
-                        return;
-                    }
-                    const wire = { sessionId: session, epoch, seq: seq++, event: next.value };
-                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(wire)}\n\n`));
-                },
-                cancel() {
-                    stopHeartbeat();
-                    // Same neutral-contract defense as the pull error path: a rejecting return() on client
-                    // disconnect must not become a process-level unhandledRejection.
-                    void iterator.return?.(undefined)?.catch?.(() => { });
-                },
-            });
-            return new Response(stream, {
-                headers: {
-                    "content-type": "text/event-stream",
-                    "cache-control": "no-cache",
-                    connection: "keep-alive",
-                },
-            });
+            return sseResponse(control.sessions.get(session).events(), (event) => ({
+                sessionId: session,
+                epoch,
+                seq: seq++,
+                event,
+            }));
         }),
     };
 }

package/dist/channels/discover.d.ts

@@ -10,15 +10,37 @@ export interface LoadedLongConnectionChannel {
     name: string;
     connect(signal: AbortSignal): LongConnection;
 }
+/**
+ * HOW A CHANNEL IS REACHED — the authored structural fact, and the ONE shape it travels in.
+ *
+ * A webhook channel is reached at a URL someone must set; a long-connection channel dials out, so
+ * there is no URL and setting one breaks it (Telegram answers `getUpdates` with 409 once a webhook
+ * exists). Everything downstream — which secrets to carry, what the runbook says, what `--run` and
+ * `--tunnel` register — is a question about THIS.
+ *
+ * It is one list because it used to be three (`channels` + `routeChannels` + `longConnectionChannels`,
+ * two of them including custom channels and one not), and every consumer re-derived the answer from
+ * whichever pair it happened to hold. Two deploys shipped a webhook for a long-connection channel
+ * that way. A list of pairs cannot be recombined wrongly, and a consumer that needs a subset asks for
+ * it here rather than trusting its caller to have filtered.
+ */
+export type ChannelIngress = "webhook" | "long-connection";
+/** One channel a directory declares, with the ingress its module shape says it has. `name` is the
+ *  basename, which is a {@link ChannelKind} for the first-party ones and anything for a custom one. */
+export interface DeclaredChannel {
+    name: string;
+    ingress: ChannelIngress;
+}
+/** Declared channels from basenames that share one ingress: the serving surface's mounted route list
+ *  (a long-connection channel mounts no HTTP route, so every route IS a webhook channel), and fixtures. */
+export declare function declaredChannels(names: readonly string[], ingress?: ChannelIngress): DeclaredChannel[];
 /**
  * Import channel files without mounting route factories or opening connections. Deployment needs only
- * the authored structural fact: function exports are route channels; `{ connect() }` exports are
+ * the authored structural fact: function exports are webhook channels; `{ connect() }` exports are
  * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
  */
 export declare function inspectChannels(dir: string): Promise<{
-    channels: string[];
-    routeChannels: string[];
-    longConnectionChannels: string[];
+    channels: DeclaredChannel[];
     failures: ModuleLoadFailure[];
 }>;
 /**
@@ -31,7 +53,6 @@ export declare function loadChannels(dir: string, ctx: ChannelContext): Promise<
     routes: Routes;
     longConnections: LoadedLongConnectionChannel[];
     routeChannels: string[];
-    longConnectionChannels: string[];
     collisions: ChannelCollision[];
     failures: ModuleLoadFailure[];
 }>;