@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/channels/lark/onboard.d.ts

@@ -1,10 +1,11 @@
-import type { FeishuGroupBehavior, FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
+import type { FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
 /** Guided Lark-international onboarding. */
 export declare const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=backend_oneclick";
 /** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
 export declare function larkEventSecurityUrl(appId: string): string;
 export interface LarkOnboardIO {
-    openUrl(url: string): void;
+    /** A page for the person, and what they do there. */
+    openUrl(url: string, action: string): void;
     note(message: string): void;
     prompt(message: string, opts?: {
         hidden?: boolean;
@@ -20,9 +21,10 @@ export interface LarkOnboardOptions {
     /** Existing active .env values. */
     existing?: Readonly<Record<string, string | undefined>>;
     ingress?: FeishuSubscriptionMode;
-    groupBehavior?: FeishuGroupBehavior;
     verifyCredentials(appId: string, appSecret: string): Promise<void>;
     bootstrapWebhook?(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
+    /** The command that continues an interrupted setup: the one that started it (`add lark`, `deploy <host> --run`). */
+    rerun?: string;
 }
 export interface LarkOnboardCredentials {
     LARK_APP_ID: string;

package/dist/channels/lark/onboard.js

@@ -4,35 +4,33 @@ export const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=b
 export function larkEventSecurityUrl(appId) {
     return `https://open.larksuite.com/app/${encodeURIComponent(appId)}/event?tab=safe`;
 }
-function required(value, name) {
+function required(value, name, rerun) {
     const trimmed = value?.trim();
     if (!trimmed)
-        throw new Error(`${name} is required — re-run \`fastagent add lark\` to continue setup`);
+        throw new Error(`${name} is required — re-run \`${rerun}\` to continue setup`);
     return trimmed;
 }
 /** Open the stable app console and collect everything the runtime needs. */
 export async function onboardLarkApp(io, opts) {
+    const rerun = opts.rerun ?? "fastagent add lark";
     const existingId = opts.existing?.LARK_APP_ID?.trim();
     const existingSecret = opts.existing?.LARK_APP_SECRET?.trim();
     const reuseExistingApp = Boolean(existingId && existingSecret);
     // Credentials are one App-scoped set.
     if (reuseExistingApp) {
-        io.note(`Reusing Lark app ${existingId}; opening its Events & Callbacks configuration directly.`);
+        io.note(`Reusing Lark app ${existingId}.`);
     }
     else {
-        io.note(`Create the app on Lark's one-click launcher. Opening ${LARK_CONSOLE_URL}`);
-        io.openUrl(LARK_CONSOLE_URL);
+        io.openUrl(LARK_CONSOLE_URL, "create the app on Lark's one-click launcher; LARK_APP_ID and LARK_APP_SECRET are under Credentials & Basic Info");
     }
-    const appId = required(reuseExistingApp ? existingId : await io.prompt("LARK_APP_ID (Credentials & Basic Info)", { hidden: false }), "LARK_APP_ID");
-    const appSecret = required(reuseExistingApp ? existingSecret : await io.prompt("LARK_APP_SECRET (Credentials & Basic Info)", { hidden: true }), "LARK_APP_SECRET");
+    const appId = required(reuseExistingApp ? existingId : await io.prompt("LARK_APP_ID (Credentials & Basic Info)", { hidden: false }), "LARK_APP_ID", rerun);
+    const appSecret = required(reuseExistingApp ? existingSecret : await io.prompt("LARK_APP_SECRET (Credentials & Basic Info)", { hidden: true }), "LARK_APP_SECRET", rerun);
     await opts.verifyCredentials(appId, appSecret);
     const eventSecurityUrl = larkEventSecurityUrl(appId);
-    io.note(`App ID / Secret verified. Opening Events & Callbacks → Security: ${eventSecurityUrl}`);
-    io.openUrl(eventSecurityUrl);
+    io.note("App ID / Secret verified.");
     if (opts.ingress === "websocket") {
-        io.note(opts.groupBehavior === "mentions"
-            ? "Choose long connection, subscribe im.message.receive_v1, then create + publish an app version. No Verification Token or Request URL is needed."
-            : "Choose long connection and subscribe im.message.receive_v1, but do not publish yet — context-aware group permission setup follows. No Verification Token or Request URL is needed.");
+        io.openUrl(eventSecurityUrl, "in Events & Callbacks, choose long connection and subscribe im.message.receive_v1, but do not publish yet: " +
+            "the permission check follows (no Verification Token or Request URL is needed)");
         return { LARK_APP_ID: appId, LARK_APP_SECRET: appSecret };
     }
     io.note("Trying automatic webhook-mode + Verification-Token bootstrap…");
@@ -43,11 +41,13 @@ export async function onboardLarkApp(io, opts) {
         io.note("Verification Token captured; Subscription mode changed to webhook in the app draft.");
     }
     else {
-        io.note(`${bootstrap.manualReason ?? "Automatic bootstrap unavailable."} Open Events & Callbacks → Encryption Strategy and copy the Verification Token. You must also switch Subscription mode to webhook when setting the Request URL.`);
+        io.note(bootstrap.manualReason ?? "Automatic bootstrap unavailable.");
+        io.openUrl(eventSecurityUrl, "in Events & Callbacks → Encryption Strategy, copy the Verification Token, and switch Subscription mode to " +
+            "webhook when setting the Request URL");
     }
     const verificationToken = required(bootstrap.token ||
         (reuseExistingApp ? opts.existing?.LARK_VERIFICATION_TOKEN?.trim() : undefined) ||
-        (await io.prompt("LARK_VERIFICATION_TOKEN (Events & Callbacks → Encryption Strategy)", { hidden: true })), "LARK_VERIFICATION_TOKEN");
+        (await io.prompt("LARK_VERIFICATION_TOKEN (Events & Callbacks → Encryption Strategy)", { hidden: true })), "LARK_VERIFICATION_TOKEN", rerun);
     return {
         LARK_APP_ID: appId,
         LARK_APP_SECRET: appSecret,

package/dist/channels/lark/scaffold/channel.ts

@@ -1,48 +1,71 @@
-import { larkChannel } from "@fastagent-sh/fastagent/lark";
-import { defineChannel } from "@fastagent-sh/fastagent";
+import { needs } from "@fastagent-sh/fastagent";
+import {
+  type LarkChannelOptions,
+  larkChannel,
+  larkIngress,
+  larkWebSocketChannel,
+} from "@fastagent-sh/fastagent/lark";
 
-// larkChannel is the branded compatibility adapter over fastagent's canonical Feishu engine, configured
-// with YOUR policy. fastagent discovers this file, mounts POST /lark, and pipes the agent + state home
-// to the adapter. Lark international (open.larksuite.com) only; a
-// Feishu tenant uses `fastagent add feishu` instead. Setup (developer console):
+// The branded Lark adapter over fastagent's canonical Feishu engine (verify + run + reply), configured
+// with YOUR policy. Lark international (open.larksuite.com) only; a Feishu tenant uses `fastagent add
+// feishu` instead.
+//
+// How it receives is LARK_INGRESS (webhook | websocket). Unset, `fastagent dev` connects OUT by
+// WebSocket (no public URL, no tunnel), and everything else — `fastagent start`, every deployment —
+// receives by webhook at POST /lark. Dev reads .secrets/.env; production reads
+// .secrets/production/.env. Interactive `deploy --run` guides creation of a separate production app;
+// if Lark refuses its config API, set the Request URL in the console once.
+//
+// `fastagent add lark` guides the console setup and validates the credentials. In the developer
+// console:
 //   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
 //   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
 //      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
-//      card scope ("Create and update card" — the live preview streams through a card). To answer bare
-//      messages in threads the Agent takes part in, and buffer other unsummoned group/thread context, also add the
-//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version. Add a
-//      message-read scope (e.g. `im:message:readonly`) too, so a thread's opening ask can carry the
-//      message it quotes; without it that quote degrades to a marker in the prompt.
-//   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
-//      .env; RECOMMENDED: set an Encrypt Key there and mirror it in LARK_ENCRYPT_KEY
-//   4. run `fastagent dev --tunnel`: it attempts to switch Subscription mode to webhook + register
-//      the URL automatically. If this app returns a config-API 404, do both BY HAND in the console
-//      with the server running (the platform verifies https://your.host/lark with a challenge).
-//   5. create a version and publish the app (a tenant admin approves it), then add the bot to a chat
-export default defineChannel({
-  // The env vars this channel needs. fastagent carries them to a deployed box and refuses to serve
-  // while one is unset — a bare process.env read gets neither guarantee. LARK_ENCRYPT_KEY is
-  // optional, so it is NOT declared here: an undeclared read stays undeclared on purpose.
-  secrets: ["LARK_APP_ID", "LARK_APP_SECRET", "LARK_VERIFICATION_TOKEN"],
-  channel: (secrets) =>
-    larkChannel({
-      appId: secrets.LARK_APP_ID,
-      appSecret: secrets.LARK_APP_SECRET,
-      verificationToken: secrets.LARK_VERIFICATION_TOKEN, // authenticates inbound events
-      encryptKey: process.env.LARK_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
-      // No session modes: a chat is one session and a thread is another, and where the answer goes follows
-      // from that (docs/design/participant-model.md).
-      // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
-      // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
-      // full details always go to the server log regardless.
-      onError: (failed) => `⚠️ ${failed.details}`,
-      // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
-      // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultLarkRoute:
-      // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
-      // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
-      // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
-      // Override to customise explicit routing, reusing the export:
-      //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
-      //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { text: `${larkEnvelope(e)}\n[extra]` },
-    }),
-});
+//      card scope ("Create and update card" — the live preview streams through a card). So the Agent
+//      hears its group chats, also add `im:message.group_msg` (sensitive), `im:message:readonly` and
+//      `im:chat.members:read`; for webhook, `application:application:patch` lets fastagent set the
+//      Request URL. What each is for is in the channel guide; the channel warns about any it lacks.
+//   3. Events & Callbacks → subscribe to `im.message.receive_v1`. For webhook, copy the Verification
+//      Token into .env (RECOMMENDED: set an Encrypt Key there and mirror it in LARK_ENCRYPT_KEY).
+//   4. create a version and publish the app (a tenant admin approves it), then add the bot to a chat
+
+// Your policy, the same whichever way the channel receives.
+const policy: Pick<LarkChannelOptions, "onError" | "route"> = {
+  // A chat is one conversation and a thread is another, each with a session of its own, and where the
+  // answer goes follows from that (docs/design/participant-model.md).
+  // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
+  // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
+  // full details always go to the server log regardless.
+  onError: (failed) => `⚠️ ${failed.details}`,
+  // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
+  // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultLarkRoute:
+  // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
+  // Agent takes part and exactly ONE human does. Other group/thread discussion is read from the
+  // platform by that place's next answered turn; @other-only messages are discussion, not asks.
+  // Override to customise explicit routing, reusing the export:
+  //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { conversation: `user:${e.sender?.sender_id?.open_id}` },
+  //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { text: `${larkEnvelope(e)}\n[extra]` },
+};
+
+// `needs` declares the env vars this channel reads: fastagent carries them to a deployed box and
+// refuses to serve while a required one is unset. LARK_ENCRYPT_KEY is optional.
+export default larkIngress() === "webhook"
+  ? needs(
+      [
+        "LARK_APP_ID",
+        "LARK_APP_SECRET",
+        "LARK_VERIFICATION_TOKEN",
+        { name: "LARK_ENCRYPT_KEY", description: "when set, plaintext events are refused", optional: true },
+      ],
+      (secrets) =>
+        larkChannel({
+          appId: secrets.LARK_APP_ID,
+          appSecret: secrets.LARK_APP_SECRET,
+          verificationToken: secrets.LARK_VERIFICATION_TOKEN, // authenticates inbound events
+          encryptKey: secrets.LARK_ENCRYPT_KEY,
+          ...policy,
+        }),
+    )
+  : needs(["LARK_APP_ID", "LARK_APP_SECRET"], (secrets) =>
+      larkWebSocketChannel({ appId: secrets.LARK_APP_ID, appSecret: secrets.LARK_APP_SECRET, ...policy }),
+    );

package/dist/channels/lark/scaffold/lark-send.ts

@@ -1,37 +1,42 @@
-import { defineTool, z } from "@fastagent-sh/fastagent";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { needs } from "@fastagent-sh/fastagent";
 import { larkTransport } from "@fastagent-sh/fastagent/lark";
 
 // Proactive delivery uses the mounted channel's credentials, gateway and token cache. With no
-// channel mounted (fire/invoke/tool), it reads LARK_APP_ID / LARK_APP_SECRET from the environment.
-
-export default defineTool({
-  description:
-    "Send a message to a Lark chat, OUTSIDE the normal reply path. Call it only for a turn NO " +
-    "channel is carrying — a scheduled or self-scheduled (wake) turn, whose plain reply goes " +
-    "nowhere — or to reach a chat OTHER than the one you are answering. In a normal chat turn the " +
-    "channel streams and delivers your reply itself, so do NOT call this to answer the current " +
-    "chat: it would post the message twice, outside the conversation thread. `chatId` (oc_…) names " +
-    "the DESTINATION and must come from your instructions (the asking message, the schedule prompt, " +
-    "or memory); the [lark: chat …] context line only identifies the chat you are answering — the " +
-    "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
-    "`markdown` (rendered as a card: headings, bold, code blocks, links).",
-  input: z.object({
-    chatId: z.string().describe("target chat id (oc_…)"),
-    text: z.string().optional().describe("plain text message to send"),
-    markdown: z.string().optional().describe("markdown to send as a card"),
+// channel mounted, it signs in with LARK_APP_ID / LARK_APP_SECRET itself.
+export default needs(["LARK_APP_ID", "LARK_APP_SECRET"], (secrets) =>
+  defineTool({
+    name: "lark_send",
+    description:
+      "Send a message to a Lark chat, OUTSIDE the normal reply path. Call it only for a message NO " +
+      "channel is carrying (a scheduled or self-scheduled one, whose plain reply goes " +
+      "nowhere) or to reach a chat OTHER than the one you are answering. In a normal chat turn the " +
+      "channel streams and delivers your reply itself, so do NOT call this to answer the current " +
+      "chat: it would post the message twice, outside the conversation thread. `chatId` (oc_…) names " +
+      "the DESTINATION and must come from your instructions (the asking message, the schedule prompt, " +
+      "or memory); the [lark: chat …] context line only identifies the chat you are answering, the " +
+      "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
+      "`markdown` (rendered as a card: headings, bold, code blocks, links).",
+    parameters: Type.Object({
+      chatId: Type.String({ description: "target chat id (oc_…)" }),
+      text: Type.Optional(Type.String({ description: "plain text message to send" })),
+      markdown: Type.Optional(Type.String({ description: "markdown to send as a card" })),
+    }),
+    execute: async ({ chatId, text, markdown }) => {
+      if ((text === undefined) === (markdown === undefined)) {
+        throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
+      }
+      const api = larkTransport({ appId: secrets.LARK_APP_ID, appSecret: secrets.LARK_APP_SECRET });
+      if (text !== undefined) await api.sendText({ chatId }, text);
+      else {
+        await api.sendMessage(
+          chatId,
+          "interactive",
+          JSON.stringify({ schema: "2.0", body: { elements: [{ tag: "markdown", content: markdown }] } }),
+        );
+      }
+      return { output: [{ type: "text", text: `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}` }] };
+    },
   }),
-  async execute({ chatId, text, markdown }, ctx) {
-    if ((text === undefined) === (markdown === undefined)) {
-      throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
-    }
-    const api = larkTransport(ctx.cwd);
-    if (text !== undefined) await api.sendText({ chatId }, text);
-    else {
-      await api.sendMessage(chatId, "interactive", JSON.stringify({
-        schema: "2.0",
-        body: { elements: [{ tag: "markdown", content: markdown }] },
-      }));
-    }
-    return `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}`;
-  },
-});
+);

package/dist/channels/lark/scaffold/lark-threads.ts

@@ -0,0 +1,25 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { sessionIdOf } from "@fastagent-sh/fastagent";
+import { larkThreads } from "@fastagent-sh/fastagent/lark";
+
+// Reads the threads (topics) of the Lark group chat this message was asked in, and no other chat's:
+// the channel names where the message runs, so the tool takes no chat id. It works in a group turn
+// served by `fastagent dev`/`start`.
+export default defineTool({
+  name: "lark_threads",
+  description:
+    "Read the threads (topics) of the Lark group chat you are answering in. Without `threadId`, list its recent " +
+    "threads, newest first, each with its id; with a `threadId` from that list, read that thread. Use " +
+    "it when a question here concerns something discussed in a thread, such as whether a problem raised there was " +
+    "resolved: the answer is often what a person wrote in the thread. Only this chat's threads can be read, and " +
+    "only in a group chat turn.",
+  parameters: Type.Object({
+    threadId: Type.Optional(Type.String({ description: "a thread id from the list (omt_…); omit it to list" })),
+  }),
+  execute: async ({ threadId }, api, context) => {
+    const threads = larkThreads(await sessionIdOf(api, context));
+    const text = threadId === undefined ? await threads.list() : await threads.read(threadId);
+    return { output: [{ type: "text", text }] };
+  },
+});

package/dist/channels/respond.d.ts

@@ -1,5 +1 @@
-/** Shared `text/plain` reply for channels + the host (error/status responses). */
-export declare const textHeaders: {
-    readonly "content-type": "text/plain";
-};
 export declare const text: (body: string, status: number) => Response;

package/dist/channels/respond.js

@@ -1,3 +1,3 @@
 /** Shared `text/plain` reply for channels + the host (error/status responses). */
-export const textHeaders = { "content-type": "text/plain" };
+const textHeaders = { "content-type": "text/plain" };
 export const text = (body, status) => new Response(body, { status, headers: textHeaders });

package/dist/channels/router.d.ts

@@ -0,0 +1,18 @@
+/**
+ * How a {@link Routes} table becomes one Fetch handler: the path rule and dispatch. Every route a serve answers
+ * verifies its own caller (a channel's platform signature, a host's IAM), or answers nothing worth guarding (the
+ * health check), so the router adds no guard of its own. Fetch-only, so any runtime can serve it; serve.ts binds it to
+ * node:http.
+ */
+import type { ChannelHandler, Routes } from "../channel.ts";
+/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
+export declare function parseRouteKey(key: string): {
+    method?: string;
+    path: string;
+};
+/** A route key is `"METHOD /path"` or `"/path"`, with a literal path. */
+export declare function assertRouteKey(key: string, describe: (problem: string) => string): void;
+/** Do these two keys fight over the same request? */
+export declare function routeKeysConflict(a: string, b: string): boolean;
+/** One handler over `routes`: a literal path, its method or any, HEAD answered from GET, else 405 or 404. */
+export declare function router(routes: Routes): ChannelHandler;

package/dist/channels/router.js

@@ -0,0 +1,68 @@
+import { text } from "./respond.js";
+/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
+export function parseRouteKey(key) {
+    const sp = key.indexOf(" ");
+    return sp === -1 ? { path: key } : { method: key.slice(0, sp).toUpperCase(), path: key.slice(sp + 1) };
+}
+/** A route key is `"METHOD /path"` or `"/path"`, with a literal path. */
+export function assertRouteKey(key, describe) {
+    const { method, path } = parseRouteKey(key);
+    if (method === "")
+        throw new Error(describe('a leading space is not a method — write "/path" for any method'));
+    if (!path.startsWith("/"))
+        throw new Error(describe('must start with "/"'));
+    // Asked of `URL` rather than by listing what it rewrites (`?`/`#`, `.`/`..`, `\`, `%2e`).
+    const arrives = new URL(path, "http://x").pathname;
+    if (arrives !== path) {
+        throw new Error(describe(`is not the path a request would carry — that request arrives as "${arrives}"`));
+    }
+}
+/** Do these two keys fight over the same request? */
+export function routeKeysConflict(a, b) {
+    const ka = parseRouteKey(a);
+    const kb = parseRouteKey(b);
+    if (ka.path !== kb.path)
+        return false;
+    return ka.method === undefined || kb.method === undefined || ka.method === kb.method;
+}
+/** Same status and headers, no content (RFC 9110's HEAD). */
+function withoutBody(res) {
+    void res.body?.cancel().catch(() => { });
+    return new Response(null, { status: res.status, statusText: res.statusText, headers: res.headers });
+}
+/** One handler over `routes`: a literal path, its method or any, HEAD answered from GET, else 405 or 404. */
+export function router(routes) {
+    const byKey = new Map();
+    const paths = new Set();
+    for (const [key, handler] of Object.entries(routes)) {
+        assertRouteKey(key, (problem) => `route "${key}" is not a valid route key — ${problem}`);
+        const shadowed = [...byKey.keys()].find((other) => routeKeysConflict(other, key));
+        if (shadowed) {
+            throw new Error(`route "${key}" conflicts with "${shadowed}" — one of them would never receive a request`);
+        }
+        // Stored normalised: `parseRouteKey` upper-cases the method, so `"get /x"` validates under `GET` and would
+        // otherwise be looked up under a name nothing stores.
+        const { method, path } = parseRouteKey(key);
+        byKey.set(method ? `${method} ${path}` : path, handler);
+        paths.add(path);
+    }
+    return (req) => {
+        // `URL` normalises the path (`/a/../x` → `/x`) and drops query/fragment.
+        const path = new URL(req.url).pathname;
+        const answer = () => {
+            const exact = byKey.get(`${req.method} ${path}`) ?? byKey.get(path);
+            if (exact)
+                return exact(req);
+            if (req.method === "HEAD") {
+                const get = byKey.get(`GET ${path}`);
+                if (get)
+                    return get(req);
+            }
+            return paths.has(path) ? text("method not allowed\n", 405) : text("not found\n", 404);
+        };
+        if (req.method !== "HEAD")
+            return answer();
+        const res = answer();
+        return res instanceof Promise ? res.then(withoutBody) : withoutBody(res);
+    };
+}

package/dist/channels/serve.d.ts

@@ -1,76 +1,11 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
-import type { ChannelHandler, Routes } from "../channel.ts";
-/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
-export declare function parseRouteKey(key: string): {
-    method?: string;
-    path: string;
-};
-/** A route key is `"METHOD /path"` or `"/path"`, with a literal path. */
-export declare function assertRouteKey(key: string, describe: (problem: string) => string): void;
-/** Do these two keys fight over the same request? */
-export declare function routeKeysConflict(a: string, b: string): boolean;
-/** A handler owning a path prefix and everything beneath it — the session control plane is the one user. */
-export interface PrefixMount {
-    /** Absolute, no trailing slash, and not `/` (`/control`). */
-    prefix: string;
-    handler: ChannelHandler;
-}
-/** Same status and headers, no content (RFC 9110's HEAD). */
-export declare function withoutBody(res: Response): Response;
-export declare function pathUnderPrefix(path: string, prefix: string): boolean;
-/**
- * Refuse a cross-origin allow-list that cannot match anything.
- *
- * ONE check for BOTH ways in: `http.cors` in a config file, and `corsOrigins` handed to `mountAgentService` by an
- * embedder. `allowedOrigin` compares exact strings, so `"https://app.example.com/"` — one trailing slash — never
- * matches and the front end is refused with nothing pointing at the rule. A rule that silently matches nothing is
- * worse than one that refuses to load.
- */
-export declare function assertCorsOrigins(origins: unknown, where: string): asserts origins is string[];
-/**
- * The tables a router composes, NAMED rather than ordered.
- *
- * Two same-typed positional arguments encoded which side of the trust axis a table was on, and getting them the
- * wrong way round type-checked: the AgentCore adapter passed its IAM-gated routes as `unverified` and they were
- * reported as unauthenticated for two commits. A caller now spells the axis at the call site.
- */
-export interface RouterSurface {
-    /** Routes that authenticate NOBODY — the router applies the JSON body gate and the cross-origin policy to them. */
-    unverified?: Routes;
-    /** Routes that verify their own caller (a channel's platform signature, a host's IAM). Neither guard applies. */
-    selfVerifying?: Routes;
-    /** Prefix-owning handlers. Always treated as unverified — the control plane is the only one. */
-    mounts?: readonly PrefixMount[];
-    /** `http.cors` — exact origins, or `["*"]`. Set, it REPLACES the `*` default; unset, the default stands. */
-    corsOrigins?: readonly string[];
-}
-/**
- * Compose the routes that AUTHENTICATE NOBODY, the self-verifying channel routes, and the {@link PrefixMount}s
- * into one handler.
- *
- * That is the axis, not authorship. Two things follow from it and nothing else does: whether a browser may drive
- * the route, and whether its body must declare JSON. A channel route is exempt from both because it checks its
- * platform's signature inside itself — a Telegram webhook is public on purpose. Ours check nothing, so the router
- * checks for them.
- *
- * TWO TABLES, not one table plus a list of which keys are which, so the three readers (browser reachability, the JSON
- * body gate, the startup report) cannot answer differently.
- *
- * CAVEAT, stated because we cannot enforce it: a CUSTOM channel that verifies nothing lands in `selfVerifying`
- * anyway and gets neither guard. That is decision B (docs/design/session-control.md §14) and it belongs to the
- * channel's author, who owns the credential the platform issued — but it is an assumption here, not a property.
- */
-export declare function router(surface: RouterSurface): ChannelHandler;
-/**
- * The node:http adapter for a Fetch handler — the embedded server uses it, and an embedder mounting fastagent on its
- * OWN node:http server can too.
- */
-export declare function nodeListener(handler: ChannelHandler): (req: IncomingMessage, res: ServerResponse) => void;
-export declare function serveNode(handler: ChannelHandler, options: {
+import type { ChannelHandler } from "../channel.ts";
+/** The totality boundary every serving path shares; `prepare` shapes the handler's response inside it. */
+export declare function totalFetch(handler: ChannelHandler, prepare?: (response: Response) => Response): (req: Request) => Promise<Response>;
+/** Serve `handler` on this runtime's own server: Node's `http.Server`, or `Bun.serve`. */
+export declare function serveHandler(handler: ChannelHandler, options: {
     port: number;
     host?: string;
 }): {
     listening: Promise<number>;
     close: () => Promise<void>;
-    closeAllConnections: () => void;
 };