@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/channels/control.js

@@ -1,4 +1,4 @@
-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";
@@ -7,6 +7,14 @@ 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.
@@ -26,23 +34,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 +98,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 +128,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 +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 {
@@ -162,33 +198,69 @@ 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)
@@ -202,66 +274,137 @@ export function controlPlaneRoutes(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

@@ -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[];
 }>;
 /**

package/dist/channels/discover.js

@@ -5,10 +5,9 @@
  * Engine-neutral, and living here rather than under `engines/` because of it: reading `channels/*.ts`
  * is the Channel contract plus a directory, with no engine in sight.
  */
-import { readdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { assertRouteKey, routeKeysConflict } from "./serve.js";
-import { isModuleFile, loadModuleDir } from "../loader.js";
+import { loadModuleDir, moduleInventory } from "../loader.js";
 import { assertInsideAgentDir } from "../paths.js";
 function longConnectionModule(value) {
     return value !== null && typeof value === "object" && typeof value.connect === "function";
@@ -18,28 +17,29 @@ function validateLongConnectionModule(value, label) {
         throw new Error(`${label}: long-connection channel name must be a non-empty string`);
     }
 }
+/** 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 function declaredChannels(names, ingress = "webhook") {
+    return names.map((name) => ({ name, ingress }));
+}
 /**
  * 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 async function inspectChannels(dir) {
     await assertInsideAgentDir(dir, "channels");
     const { modules, failures } = await loadModuleDir(join(dir, "channels"));
     const channels = [];
-    const routeChannels = [];
-    const longConnectionChannels = [];
     for (const { name, label, file, mod } of modules) {
         try {
             if (typeof mod.default === "function") {
-                channels.push(name);
-                routeChannels.push(name);
+                channels.push({ name, ingress: "webhook" });
                 continue;
             }
             if (longConnectionModule(mod.default)) {
                 validateLongConnectionModule(mod.default, label);
-                channels.push(name);
-                longConnectionChannels.push(name);
+                channels.push({ name, ingress: "long-connection" });
                 continue;
             }
             throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
@@ -48,7 +48,7 @@ export async function inspectChannels(dir) {
             failures.push({ label, file, message: error.message });
         }
     }
-    return { channels, routeChannels, longConnectionChannels, failures };
+    return { channels, failures };
 }
 /**
  * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
@@ -56,19 +56,8 @@ export async function inspectChannels(dir) {
  */
 export async function discoverChannelFiles(dir) {
     await assertInsideAgentDir(dir, "channels");
-    let names;
-    try {
-        names = await readdir(join(dir, "channels"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-    return names
-        .filter(isModuleFile)
-        .map((name) => name.replace(/\.(ts|js|mjs)$/, ""))
-        .sort();
+    const entries = await moduleInventory(join(dir, "channels"));
+    return entries.map((entry) => entry.name);
 }
 function validateRoutes(value, label) {
     if (value === null || typeof value !== "object" || value instanceof Map) {

package/dist/channels/feishu/feishu-api.js

@@ -20,7 +20,7 @@
  * here are shape-compatible with the SDK's `client.im.*` style, so the policy layer survives that swap.
  */
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { attachmentPath } from "../kit/attachment-path.js";
 import { utf8Prefix } from "../kit/text.js";
 /** Per-attempt timeout for a JSON API call — small JSON round-trips, so 30s is generous. */
 const API_TIMEOUT_MS = 30_000;
@@ -283,13 +283,10 @@ export function createFeishuApi(opts) {
         },
         async fetchFile(messageId, fileKey, name, chatId, filesDir) {
             const { bytes } = await api.downloadResource(messageId, fileKey, "file");
-            // The name is external input destined for a filesystem path — keep only its basename-safe core.
-            const safe = name.replace(/[/\\]/g, "_").replace(/^\.+/, "_") || "file";
-            const dir = join(filesDir, chatId);
-            await mkdir(dir, { recursive: true });
-            const dest = join(dir, safe);
-            await writeFile(dest, bytes);
-            return { path: dest, name: safe, size: bytes.byteLength };
+            const dest = attachmentPath(filesDir, chatId, name);
+            await mkdir(dest.dir, { recursive: true });
+            await writeFile(dest.path, bytes);
+            return { path: dest.path, name: dest.name, size: bytes.byteLength };
         },
         async getAppConfig(appId) {
             // v6 app detail — the one read surface that returns the event-security material (under data.app).