@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/channels/{context-buffer.js → kit/context-buffer.js}

@@ -4,7 +4,7 @@
  * un-summoned messages per conversation "place", kept under a char budget and folded into the next
  * answered turn in that place, so a summoned agent has the discussion it didn't see turn-by-turn.
  *
- * Channel-neutral and generic over the entry shape (like ../turn-store.ts): the channel supplies its
+ * Channel-neutral and generic over the entry shape (like ../kit/turn-store.ts): the channel supplies its
  * entry type, the shape validator (state files are an IO boundary — valid JSON of the WRONG shape
  * must degrade exactly like a corrupt file: warn + empty, never flow in as trusted data), the
  * fold-line renderer, and its log label. What stays per channel: the entry type itself, place-key
@@ -21,7 +21,7 @@
  *    message that arrives while the turn runs survives for the next answered turn (a whole-bucket
  *    delete would lose it).
  */
-import { log } from "../log.js";
+import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
 /** Char budget for the per-place buffer — bounds the cost of folding it into a prompt; when exceeded
  *  the OLDEST un-summoned messages are dropped (not a time window: a quiet group keeps its
@@ -39,6 +39,17 @@ export const BUFFER_LINE_MAX_CHARS = 280;
  *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
  *  each channel's attachment collector caps against this. */
 export const BUFFER_ATTACH_MAX = 3;
+/**
+ * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is
+ * empty. One renderer for every channel: what the agent is told about un-summoned discussion should
+ * not depend on which chat platform delivered it, and three copies of the literal is how that drifts.
+ *
+ * A channel that folds a SECOND source (feishu's originating room) labels that one itself — it is a
+ * different claim about a different place, not this block with another name.
+ */
+export function discussionBlock(text) {
+    return text ? `[recent group discussion:\n${text}\n]\n\n` : "";
+}
 export function createContextBuffer(options) {
     const { path, label, isEntry, line } = options;
     const load = () => {

package/dist/channels/{invoke-turn-kit.d.ts → kit/invoke-turn-kit.d.ts}

@@ -7,10 +7,14 @@
  *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
  *     {@link missingAttachmentsNote}, {@link attributedFileName}.
  *
+ * None of it asks what the agent can DO with an attachment. A channel resolves platform resources and
+ * states what it found; deciding whether to open a file is the agent's, and one assembled without a
+ * file tool answers that it cannot — visibly, at the moment it is asked.
+ *
  * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
  * message-scoped Feishu keys, Slack file objects) are real differences.
  */
-import { type Agent, type AgentEvent, type Prompt, type Scope } from "../agent.ts";
+import { type Agent, type AgentEvent, type Prompt, type Scope } from "../../agent.ts";
 /** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
  *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
  *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
@@ -49,8 +53,15 @@ export interface ManifestFile {
     size: number;
     path: string;
 }
-/** The downloaded-file manifest appended to the prompt — the agent reads the paths with its tools.
- *  Empty input renders nothing. */
+/**
+ * The downloaded-file manifest appended to the prompt: name, size, path. Empty input renders nothing.
+ *
+ * It STATES, it does not instruct. The earlier wording ("read them with your tools") was an
+ * assumption about the reader, and an assumption has to be verified — which is where a capability
+ * flag threaded through eight files came from. An agent with a file tool decides for itself whether
+ * to open one, and how much of it; an agent without one says so. Neither needs this line to have
+ * guessed first.
+ */
 export declare function attachedFilesManifest(files: readonly ManifestFile[]): string;
 /** Decorate a background file's display name with its attribution ("the file Bob sent" resolves),
  *  the way the fold attributes text lines. */

package/dist/channels/{invoke-turn-kit.js → kit/invoke-turn-kit.js}

@@ -7,12 +7,16 @@
  *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
  *     {@link missingAttachmentsNote}, {@link attributedFileName}.
  *
+ * None of it asks what the agent can DO with an attachment. A channel resolves platform resources and
+ * states what it found; deciding whether to open a file is the agent's, and one assembled without a
+ * file tool answers that it cannot — visibly, at the moment it is asked.
+ *
  * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
  * message-scoped Feishu keys, Slack file objects) are real differences.
  */
-import { SESSION_BUSY_CODE } from "../agent.js";
-import { log } from "../log.js";
-// Each retry is a lease-check-level reject (tryAcquire runs before harness assembly) — waiting is nearly
+import { SESSION_BUSY_CODE } from "../../agent.js";
+import { log } from "../../log.js";
+// Each retry is a lease-check-level reject (tryAcquire runs before the session is bound) — waiting is nearly
 // free, and the loop exits within one delay of the holder finishing. So the cap is sized to outlast a
 // real tool-using wake turn (minutes), not to be short: 10 min. CEILING: a holder that runs longer than
 // this still surfaces the busy error to the user — the bound exists so a stuck lease can't hang a chat
@@ -59,11 +63,18 @@ scope, prompt, options) {
         await new Promise((r) => setTimeout(r, busyRetry.delayMs));
     }
 }
-/** The downloaded-file manifest appended to the prompt — the agent reads the paths with its tools.
- *  Empty input renders nothing. */
+/**
+ * The downloaded-file manifest appended to the prompt: name, size, path. Empty input renders nothing.
+ *
+ * It STATES, it does not instruct. The earlier wording ("read them with your tools") was an
+ * assumption about the reader, and an assumption has to be verified — which is where a capability
+ * flag threaded through eight files came from. An agent with a file tool decides for itself whether
+ * to open one, and how much of it; an agent without one says so. Neither needs this line to have
+ * guessed first.
+ */
 export function attachedFilesManifest(files) {
     return files.length
-        ? `\n\n[attached files — read them with your tools:\n${files.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
+        ? `\n\n[attached files:\n${files.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
         : "";
 }
 /** Decorate a background file's display name with its attribution ("the file Bob sent" resolves),

package/dist/channels/{preview-kit.d.ts → kit/preview-kit.d.ts}

@@ -8,11 +8,13 @@
  * everything platform-independent lives here, so a new event type or a wording change lands in ONE
  * place instead of one hunk per channel.
  */
-import type { AgentEvent, Json } from "../agent.ts";
+import type { AgentEvent, Json } from "../../agent.ts";
 /** A terminal failure, as a channel hands it to its `onError`. */
 export interface ChannelFailure {
     details: string;
     retryable: boolean;
+    /** The engine's failure code, when it set one. */
+    code?: string;
 }
 /** The customer-facing default: neutral, no leaked internals. Differentiate on retryability and always
  *  offer a next step (Slack agent-design: never leave the user with a dead-end "something went wrong").

package/dist/channels/{seen.js → kit/seen.js}

@@ -1,5 +1,5 @@
 /** Best-effort bounded durable dedup ring, recorded only after the caller's pre-ACK side effect is durable. */
-import { log } from "../log.js";
+import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
 export function createSeenRing(path, label, cap = 2000) {
     const raw = loadStateFile(path);

package/dist/channels/kit/signature.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The replay window every signed webhook ingress needs. A signature covers its timestamp but proves
+ * nothing about it, so without a window a captured body plus its signed headers replays forever.
+ * The window LENGTH is the caller's: it is set by the platform's own redelivery schedule, not by us.
+ */
+/**
+ * Whether a Unix-SECONDS timestamp header is within `maxAgeS` of now, in either direction (a clock
+ * ahead of ours is as suspect as one behind). Non-numeric is not fresh: the header is part of the
+ * signed material, so a value the signature commits to but this cannot read is a reason to refuse,
+ * not to wave through.
+ */
+export declare function signatureIsFresh(timestamp: string, maxAgeS: number, nowMs?: number): boolean;

package/dist/channels/kit/signature.js

@@ -0,0 +1,17 @@
+/**
+ * The replay window every signed webhook ingress needs. A signature covers its timestamp but proves
+ * nothing about it, so without a window a captured body plus its signed headers replays forever.
+ * The window LENGTH is the caller's: it is set by the platform's own redelivery schedule, not by us.
+ */
+/**
+ * Whether a Unix-SECONDS timestamp header is within `maxAgeS` of now, in either direction (a clock
+ * ahead of ours is as suspect as one behind). Non-numeric is not fresh: the header is part of the
+ * signed material, so a value the signature commits to but this cannot read is a reason to refuse,
+ * not to wave through.
+ */
+export function signatureIsFresh(timestamp, maxAgeS, nowMs = Date.now()) {
+    if (!/^\d+$/.test(timestamp))
+        return false;
+    const seconds = Number(timestamp);
+    return Number.isSafeInteger(seconds) && Math.abs(Math.floor(nowMs / 1000) - seconds) <= maxAgeS;
+}

package/dist/channels/{state.js → kit/state.js}

@@ -12,9 +12,9 @@
  * is an ENVIRONMENT error the operator must fix: it throws, and construction fails loudly — booting
  * with silently-empty state would hide real data behind a config mistake.
  */
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { log } from "../log.js";
+import { mkdirSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { log } from "../../log.js";
 /** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
 export function ensureStateHome(dir) {
     mkdirSync(dir, { recursive: true });
@@ -43,8 +43,5 @@ export function loadStateFile(path) {
     }
 }
 export function saveStateFile(path, value) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp`;
-    writeFileSync(tmp, JSON.stringify(value));
-    renameSync(tmp, path);
+    writeFileAtomic(path, JSON.stringify(value));
 }

package/dist/channels/{stop-command.d.ts → kit/stop-command.d.ts}

@@ -1,4 +1,4 @@
-import { type SessionControl } from "../session.ts";
+import { type SessionControl } from "../../session.ts";
 /** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
 export declare function isStopText(text: string): boolean;
 /** Dispatch `abort` for the session and map the outcome to the customer-facing line. Never throws;

package/dist/channels/{stop-command.js → kit/stop-command.js}

@@ -6,8 +6,8 @@
  * at-least-once floor; and the hub stays gated by `config.sessionControl`, so without it the command
  * degrades to a visible "not enabled" notice, never a silent ignore.
  */
-import { log } from "../log.js";
-import { NO_ACTIVE_RUN_CODE } from "../session.js";
+import { log } from "../../log.js";
+import { NO_ACTIVE_RUN_CODE } from "../../session.js";
 /** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
 export function isStopText(text) {
     return /^(stop|cancel)[.!]?$/i.test(text.trim());
@@ -21,16 +21,16 @@ export async function dispatchStop(control, session, label) {
     if (!control)
         return STOP_UNAVAILABLE_NOTICE;
     try {
-        const result = await control.dispatch(session, { type: "abort" });
+        const result = await control.sessions.get(session).abort();
         if (result.ok)
             return STOPPED_NOTICE;
         if (result.error.code === NO_ACTIVE_RUN_CODE)
             return NOTHING_RUNNING_NOTICE;
-        log.warn(`${label} stop dispatch rejected for ${session}: ${result.error.code} — ${result.error.message}`);
+        log.warn(`${label} stop rejected for ${session}: ${result.error.code} — ${result.error.message}`);
         return `⚠️ Could not stop (${result.error.code}).`;
     }
     catch (error) {
-        log.warn(`${label} stop dispatch failed for ${session}: ${String(error)}`);
+        log.warn(`${label} stop failed for ${session}: ${String(error)}`);
         return "⚠️ Could not stop — see the server logs.";
     }
 }

package/dist/channels/{tasks.d.ts → kit/tasks.d.ts}

@@ -4,4 +4,4 @@ export interface TaskTracker {
     /** Resolves when every currently-tracked task has settled. */
     drain(): Promise<void>;
 }
-export declare function createTaskTracker(): TaskTracker;
+export declare function createTaskTracker(label: string): TaskTracker;

package/dist/channels/{tasks.js → kit/tasks.js}

@@ -2,10 +2,16 @@
  * SHARED fire-and-forget side-task tracking. Channels launch work off the request path (stop
  * feedback, DM welcomes) that must not block the transport ACK but MUST be drained on shutdown
  * (`turnsIdle`) — otherwise a reply in flight when the process exits is silently dropped. Error
- * handling stays with the caller: track() only guarantees the drain sees the task settle.
+ * handling stays with the caller: track() only guarantees the drain sees the task SETTLE, and settle
+ * includes reject. A caller that handles its error on a separate branch (`p.catch(log); track(p)`)
+ * still hands us a promise that rejects, and a drain that propagated it would fail the channel's whole
+ * `turnsIdle` over one side task. A rejection that reaches us is logged — we
+ * cannot tell a missing `.catch` from one on a separate branch, so the line is a visibility floor
+ * rather than a diagnosis, and without it a dropped side task leaves no trace anywhere.
  */
-import { beginWork } from "./busy.js";
-export function createTaskTracker() {
+import { beginWork } from "../busy.js";
+import { log } from "../../log.js";
+export function createTaskTracker(label) {
     const tasks = new Set();
     return {
         track(task) {
@@ -18,8 +24,8 @@ export function createTaskTracker() {
                 workDone();
                 tasks.delete(task);
             })
-                .catch(() => { }); // the caller's chain owns the error
+                .catch((error) => log.warn(`${label} side task rejected: ${String(error)}`));
         },
-        drain: () => Promise.all(tasks).then(() => undefined),
+        drain: () => Promise.allSettled(tasks).then(() => undefined),
     };
 }

package/dist/channels/{thread-participants.js → kit/thread-participants.js}

@@ -19,7 +19,7 @@
  * - Keyed by `thread_id`, never a reply-chain root: Feishu's `root_id` moves with the chain, so it
  *   cannot identify a side conversation at all.
  */
-import { log } from "../log.js";
+import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
 /** Cap on remembered threads. Losing one costs a mention to re-enter that thread, so an unbounded file
  *  buys little — and a merge that carries new information rewrites the whole map synchronously, so the

package/dist/channels/{turn-queue.js → kit/turn-queue.js}

@@ -10,8 +10,8 @@
  * process-crash recovery, at-least-once). Exactly-once / deterministic step-replay (L2) is the K-axis
  * backend — an external queue with distributed locking (SPEC §11) — not this in-memory queue.
  */
-import { log } from "../log.js";
-import { beginWork } from "./busy.js";
+import { log } from "../../log.js";
+import { beginWork } from "../busy.js";
 export function createTurnQueue(opts) {
     const { label, run, onQueuedBehind } = opts;
     // Per-session serial chains: a second turn for the same session waits its turn (FIFO) instead of

package/dist/channels/{turn-store.d.ts → kit/turn-store.d.ts}

@@ -1,3 +1,4 @@
+import type { ContextBuffer } from "./context-buffer.ts";
 /** What every persisted turn record carries regardless of channel: identity, the session whose FIFO
  *  chain it runs on, and how many times it has STARTED executing without finishing (0 until its first
  *  run; bumped at each `startAttempt`). The channel's record type extends this with everything its
@@ -20,14 +21,14 @@ export interface TurnStore<T extends TurnRecordBase> {
     recover(): T[];
     /** Called when a turn is about to RUN (dequeued). Returns:
      *   - "run": bumped its persisted execution count; go ahead.
-     *   - "exceeded": over `maxAttempts` starts without finishing (killed mid-run every time, whatever the
-     *     cause); the record is dropped and the runner notifies the asker.
+     *   - "exceeded": over {@link MAX_TURN_ATTEMPTS} starts without finishing (killed mid-run every time,
+     *     whatever the cause); the record is dropped and the runner notifies the asker.
      *   - "defer": the bump could not be persisted — skip this cycle (fail closed: an unpersisted count
      *     would let a poison turn re-run forever); the record stays on disk and replays on the next start
      *     (a restart is required — disk recovery alone does not re-run it). The runner does NOT notify.
      *  An id with no record returns "run" (untracked): a completed turn's `remove` cleared it, so the
      *  redelivery-double-run tail (see the header's pre-ACK window) lands here. */
-    startAttempt(id: string, maxAttempts: number): "run" | "exceeded" | "defer";
+    startAttempt(id: string): "run" | "exceeded" | "defer";
 }
 export interface TurnStoreOptions<T extends TurnRecordBase> {
     /** Log prefix naming the consumer (e.g. "[telegram]") — the store itself is channel-neutral. */
@@ -39,4 +40,19 @@ export interface TurnStoreOptions<T extends TurnRecordBase> {
      *  (telegram: numeric update_id; lark: an explicit per-record seq). */
     order: (a: T, b: T) => number;
 }
+/**
+ * End an ANSWERED turn: drop its durable intent, then commit the discussion it folded in.
+ *
+ * The ORDER is the safety property, which is why this is a function and not two lines at each call
+ * site. A crash between the two writes may re-fold already-answered context into the next summon —
+ * additive and harmless. The reverse order leaves intent on disk with its context already consumed,
+ * so the replay runs the same turn with its context stripped.
+ *
+ * Called from the turn's `completed` event, when the fold provably lives in the durable session.
+ */
+export declare function commitAnsweredTurn<T extends TurnRecordBase, E>(store: TurnStore<T>, buffer: ContextBuffer<E>, turn: {
+    id: string;
+    bufferKey: string;
+    consumed: E[];
+}): void;
 export declare function createTurnStore<T extends TurnRecordBase>(path: string, opts: TurnStoreOptions<T>): TurnStore<T>;

package/dist/channels/{turn-store.js → kit/turn-store.js}

@@ -49,8 +49,35 @@
  * Single-process, single-writer: same durability model as state.ts (crash-safe via atomic rename;
  * power-loss is best-effort — no fsync, consistent with the rest of the channel's state).
  */
-import { log } from "../log.js";
+import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
+/**
+ * How many times a turn may START without finishing before it is dropped rather than run again — the
+ * poison-turn ceiling described at length above. One value for every channel: it prices replay against
+ * DEPLOY frequency, which is a property of how fastagent is operated, not of which chat platform is in
+ * front of it.
+ *
+ * Known limitation: the count cannot tell a self-inflicted crash from an external SIGTERM (there is no
+ * graceful drain), so a legitimately long turn interrupted by this many successive deploys is dropped
+ * as if it were poison. Three is a bet that such a turn is an outlier, not a defence against one:
+ * catching SIGTERM to spare it would reintroduce the drain the design refuses — raise this constant
+ * instead if such turns are expected.
+ */
+const MAX_TURN_ATTEMPTS = 3;
+/**
+ * End an ANSWERED turn: drop its durable intent, then commit the discussion it folded in.
+ *
+ * The ORDER is the safety property, which is why this is a function and not two lines at each call
+ * site. A crash between the two writes may re-fold already-answered context into the next summon —
+ * additive and harmless. The reverse order leaves intent on disk with its context already consumed,
+ * so the replay runs the same turn with its context stripped.
+ *
+ * Called from the turn's `completed` event, when the fold provably lives in the durable session.
+ */
+export function commitAnsweredTurn(store, buffer, turn) {
+    store.remove(turn.id);
+    buffer.commit(turn.bufferKey, turn.consumed);
+}
 export function createTurnStore(path, opts) {
     const { label, isRecord, order } = opts;
     const load = () => {
@@ -102,12 +129,12 @@ export function createTurnStore(path, opts) {
             // happening to survive the load's JSON round-trip.
             return [...turns.values()].sort(order);
         },
-        startAttempt(id, maxAttempts) {
+        startAttempt(id) {
             const rec = turns.get(id);
             if (!rec)
                 return "run"; // no record — run untracked (a redelivery double-run whose first run removed it)
             const attempts = rec.attempts + 1;
-            if (attempts > maxAttempts) {
+            if (attempts > MAX_TURN_ATTEMPTS) {
                 // State the fact, not a cause the counter can't prove: a turn killed mid-run every time bumps
                 // this whether IT poisoned the process or a deploy/OOM took it down each time.
                 log.error(`${label} dropping turn ${id} after starting ${rec.attempts} time(s) without finishing ` +

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

@@ -3,7 +3,7 @@
  * this module binds it to Lark's cloud profile and exposes natural Lark-branded public names. Lark's
  * weaker control-plane capabilities live in onboarding/registration, not in a fork of the turn engine.
  */
-import type { ChannelModule, LongConnectionChannelModule } from "../../host/node.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
 import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, type FeishuWebSocketChannelOptions, defaultFeishuRoute } from "../feishu/feishu.ts";
 export type LarkChannelOptions = FeishuChannelOptions;
 export type LarkWebSocketChannelOptions = FeishuWebSocketChannelOptions;

package/dist/channels/serve.d.ts

@@ -0,0 +1,73 @@
+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).
+ *  An empty method (`" /x"`) parses as `""`, which {@link assertRouteKey} refuses — see there. */
+export declare function parseRouteKey(key: string): {
+    method?: string;
+    path: string;
+};
+/**
+ * A route key is `"METHOD /path"` or `"/path"`, with a literal path.
+ *
+ * Every rule here exists because breaking it costs SOMEONE ELSE. Two keys naming one route, a route
+ * under a mount, a path a URL rewrites (`/a/../x` and `/x` are one route spelled two ways, while
+ * the conflict check compares strings) — in each case a channel goes dark and its author did
+ * nothing wrong.
+ *
+ * Mistakes that only cost their own author a debugging session are NOT policed: `:id` and `*` are
+ * literal path characters here, so such a key simply never matches, and an unusual method is the
+ * same. Refusing those would trade a working capability for a lecture.
+ */
+export declare function assertRouteKey(key: string, describe: (problem: string) => string): void;
+/** Do these two keys fight over the same request? Equal paths, and a method each answers; a key
+ *  with no method answers all of them. */
+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. Kept out of {@link Routes} so a key is always a literal path and collision checks stay
+ *  comparisons. */
+export interface PrefixMount {
+    /** Absolute, no trailing slash, and not `/` (`/control`). Owns `/control` and everything below it.
+     *  The root is excluded deliberately: a handler owning every path is that handler, and routing to
+     *  it through here would only add a table nothing can reach. */
+    prefix: string;
+    handler: ChannelHandler;
+}
+/** Same status and headers, no content (RFC 9110's HEAD). The discarded body is cancelled, or a
+ *  streaming producer keeps running with no reader. Shared with the control plane, which answers
+ *  HEAD too. */
+export declare function withoutBody(res: Response): Response;
+/** Is `path` inside `prefix`? Segment-wise, so `/controlled` is not inside `/control`. */
+export declare function pathUnderPrefix(path: string, prefix: string): boolean;
+/**
+ * Compose a {@link Routes} table and its {@link PrefixMount}s into one handler.
+ *
+ * Refuses at assembly anything that could not receive a request: a key naming the same route as
+ * another (`"/x"` and `"GET /x"`), a route inside a mount, two mounts claiming the same ground. A
+ * channel must never go dark unannounced.
+ *
+ * 404 and 405 stay distinct: a remote client reads 404 as "this serve predates the route" (version
+ * skew) rather than as a fault.
+ */
+export declare function router(routes: Routes, mounts?: readonly PrefixMount[]): 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.
+ *
+ *  Takes the same {@link ChannelHandler} `serveNode` does, so both doors accept the same thing: a
+ *  handler may answer synchronously, and `router()` returns exactly that. Requiring a Promise here
+ *  made the most natural mount — `nodeListener(router(routes))`, the whole agent on the app's own
+ *  server — a type error. */
+export declare function nodeListener(handler: ChannelHandler): (req: IncomingMessage, res: ServerResponse) => void;
+/**
+ * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
+ * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
+ * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
+ * `host` is the bind address; unset means all interfaces (what containers need).
+ */
+export declare function serveNode(handler: ChannelHandler, options: {
+    port: number;
+    host?: string;
+}): {
+    listening: Promise<number>;
+    close: () => Promise<void>;
+    closeAllConnections: () => void;
+};