@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/channels/control.d.ts

@@ -1,17 +1,47 @@
-import { type SessionControl, type SessionEvent } from "../session.ts";
+/**
+ * The session control plane over HTTP + SSE — the Phase 3 transport (design §13). Engine-neutral:
+ * consumes only the `SessionControl` contract. One transport serves every remote consumer (Web
+ * panel, desktop app, `fastagent attach`); the embedded API stays semantic-only and the ENVELOPE
+ * lives here: `id` (request correlation — implicit in HTTP), `epoch` (serving-process incarnation
+ * — INFORMATIONAL, for consumers correlating across connections; a restart surfaces as its
+ * connections dropping, so no one fences on it), `seq` (per-connection monotonic, detects loss in
+ * transit).
+ *
+ * SECURITY: these routes steer and stop runs, rewrite session properties, and delete records — a
+ * remote-control surface. The bearer token is REQUIRED (there is no unauthenticated mode) and is the only auth the framework owns; anything
+ * beyond a shared secret (principals, per-permission split, audit) is the wrapping host's job
+ * (design §14). Locally the serving process generates a per-boot token and writes it to
+ * `<stateRoot>/control.json` for local discovery — filesystem permissions guard the token, and the
+ * token guards the routes. That premise is shared-filesystem: a deployment breaks it, so there the
+ * DEPLOYER supplies the token ({@link CONTROL_TOKEN_ENV}) and both sides know it. How far those routes REACH is the bind address: all interfaces by
+ * default (containers require it), so the port is LAN-reachable and the mount warns accordingly —
+ * `--bind 127.0.0.1` (or `http.host`) closes exactly that reach, and the warning goes quiet because
+ * there is none left to state.
+ */
 import type { Agent } from "../agent.ts";
-import type { Routes } from "../host/node.ts";
+import { type SessionControl, type SessionEvent } from "../session.ts";
+import { type PrefixMount } from "./serve.ts";
+/** A plane handler: the request, plus the session id the path named (`""` where the path has none). */
+type PlaneHandler = (req: Request, session: string) => Response | Promise<Response>;
+/** The plane's route table: `"<METHOD> <path>"` → handler, where at most one path segment is
+ *  {@link SESSION_SEGMENT}. */
+export type PlaneRoutes = Record<string, PlaneHandler>;
+/** 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 declare const CONTROL_TOKEN_ENV = "FASTAGENT_CONTROL_TOKEN";
 /** The SSE payload: one control-plane event in its transport envelope. */
 export interface WireEvent {
     sessionId: string;
-    /** Serving-process incarnation (per `controlRoutes` call). A change means the server restarted:
+    /** Serving-process incarnation (per `createControlPlane` call). A change means the server restarted:
      *  live continuity is gone — run the reconnect steps (entries cursor + state). */
     epoch: string;
     /** Per-connection monotonic counter. A gap means events were lost in transit on THIS connection. */
     seq: number;
     event: SessionEvent;
 }
-export interface ControlRoutesOptions {
+export interface ControlPlaneOptions {
     /** Shared bearer secret, required on every route. Never optional: an unauthenticated
      *  remote-control endpoint must not be constructible by omission. */
     token: string;
@@ -22,7 +52,25 @@ export interface ControlRoutesOptions {
     agent?: Agent;
 }
 /**
- * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
- * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ * 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 declare function createControlPlane(control: SessionControl, options: ControlPlaneOptions): PrefixMount;
+/** Mount a plane route table as a {@link PrefixMount} — the plane owns a PREFIX, while a route
+ *  table is a set of paths, at most one segment of which is a session id. */
+export declare function mountControlPlane(routes: PlaneRoutes): PrefixMount;
+/**
+ * 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 declare function controlRoutes(control: SessionControl, options: ControlRoutesOptions): Routes;
+export declare function controlPlaneRoutes(control: SessionControl, options: ControlPlaneOptions): PlaneRoutes;
+export {};

package/dist/channels/control.js

@@ -1,33 +1,158 @@
-import { INVALID_COMMAND_CODE } from "../session.js";
+import { INVALID_COMMAND_CODE, SESSIONS_UNAVAILABLE_CODE, UNSUPPORTED_CAPABILITY_CODE, UPDATE_FIELDS, } from "../session.js";
 import { timingSafeEqual } from "node:crypto";
+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 { text } from "./respond.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.
+ *
+ * CORS belongs to every reply that leaves the plane — including the ones no route produces (an
+ * unknown path, an unserved method, a throwing handler). As separate routes those came from the
+ * host, outside anything the plane could decorate. Owning the prefix makes them its own answers,
+ * headers applied at the single exit they share.
+ *
+ * `*` is the right origin: authorisation is the bearer token — never the origin, never a cookie —
+ * so an origin that cannot present it gets 401 either way, and a deployment cannot know the origins
+ * of the GUIs that will manage it (§14's asymmetry).
+ *
+ * `authorization` is not CORS-safelisted, so EVERY call preflights, including a plain GET.
+ * `content-type` is not either (only three values are, and `application/json` is not among them),
+ * so a browser POSTing to dispatch/invoke names it — allowing just `authorization` leaves precisely
+ * the WRITE routes unreachable while reads work.
+ */
+function planeApp(routes) {
+    /** 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, 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 = (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
+        // gate applied BEFORE the request exists, so refusing there means the real request is never sent
+        // and the client sees an opaque network error. Allowing it lets the plane's own 404/405 arrive,
+        // with these headers and an explanation.
+        if (requested)
+            methods.add(requested.toUpperCase());
+        return [...methods, "OPTIONS"].join(", ");
+    };
+    return async (req) => {
+        const path = new URL(req.url).pathname;
+        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 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 (hits.length > 0)
+                return text("method not allowed\n", 405);
+            return text("not found\n", 404);
+        };
+        let res;
+        try {
+            // HEAD carries no content, whichever branch answered — including this plane's own 404/405.
+            const answered = await answer();
+            res = req.method === "HEAD" ? withoutBody(answered) : answered;
+        }
+        catch (error) {
+            // The plane's own totality boundary: a rejecting handler (`commands()` on an unreadable
+            // definition) must still answer with the headers; the message stays internal.
+            log.error(`[control] ${req.method} ${path} failed: ${String(error)}`);
+            res = text("internal error\n", 500);
+        }
+        // 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(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;
@@ -45,8 +170,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 {
@@ -73,24 +198,73 @@ 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;
     }
 }
 /**
- * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
- * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ * 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.
  */
-export function controlRoutes(control, options) {
+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 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 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("controlRoutes: a bearer token is required (empty tokens are not a mode)");
+        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.
@@ -100,66 +274,137 @@ export function controlRoutes(control, options) {
         return header.length === expected.length && timingSafeEqual(header, 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]();
+        [`GET /control/sessions/${SESSION_SEGMENT}/events`]: guard((_req, _url, session) => {
+            const iterator = control.sessions.get(session).events()[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".

package/dist/channels/discover.d.ts

@@ -0,0 +1,59 @@
+import type { ChannelContext, LongConnection, Routes } from "../channel.ts";
+import { type ModuleLoadFailure } from "../loader.ts";
+/** A dropped route: two channels claim the same key. Surfaced, never silent. */
+export interface ChannelCollision {
+    route: string;
+    source: string;
+}
+/** A long-connection module bound to the same context route factories receive. Internal serving shape. */
+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 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: DeclaredChannel[];
+    failures: ModuleLoadFailure[];
+}>;
+/**
+ * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
+ * WITHOUT importing. A symlinked channels directory must remain inside the agent dir.
+ */
+export declare function discoverChannelFiles(dir: string): Promise<string[]>;
+/** Discover, validate, and bind all channel modules. No long connection is opened here; the CLI owns it. */
+export declare function loadChannels(dir: string, ctx: ChannelContext): Promise<{
+    routes: Routes;
+    longConnections: LoadedLongConnectionChannel[];
+    routeChannels: string[];
+    longConnectionChannels: string[];
+    collisions: ChannelCollision[];
+    failures: ModuleLoadFailure[];
+}>;