@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/channels/kit/turn-store.js

@@ -1,82 +1,26 @@
 /**
- * Durable turn intent: the L1 half of durable execution (the L2 exactly-once / deterministic
- * step-replay layer is the K-axis backend — docs/design/core.md §11). Persists an accepted turn BEFORE
- * the webhook 200 (pre-ACK, like the telegram context-buffer) and removes it when the turn ENDS — the
- * runner's `finally`: a completed turn OR any caught error both remove it. Precisely, a completed turn's
- * removal fires at the `completed` event (the session is committed), which is BEFORE the reply reaches
- * the chat platform: so L1 recovers the ACKed-but-un-COMPLETED window, not un-DELIVERED. A crash in
- * that narrow tail (completed, session-committed, but the message not yet sent) leaves the answer in the
- * session history undelivered and is deliberately NOT replayed — replaying a session-committed turn
- * would double-append it; the asker re-asks (and sees the prior answer in history). L1's scope is the
- * INTERRUPTED-run window (the `finally` never runs); a caught error is NOT retried here — a `failed`
- * event already told the user, and a transport throw is dropped exactly like the pre-L1 in-memory queue
- * did (replaying it could double-send). Only an interrupted run leaves the record on disk — and
- * "interrupted" is not just a rare crash: `runStart` has no graceful drain (cli.ts), so a SIGTERM exits
- * mid-turn too, i.e. EVERY rolling deploy that catches an in-flight turn. Recovery re-enqueues it next start.
+ * Durable turn intent: the at-least-once half of durable execution. Exactly-once execution needs a different
+ * backend and is out of scope (docs/design/core.md §10).
  *
- * This recovers the ACKed-but-unfinished window the in-memory turn-queue drops (turn-queue.ts). Weigh
- * the trade before trusting it: the alternative (dropping the turn) fails VISIBLY and self-corrects
- * (the turn vanished, the asker re-asks); replay's sharpest cost is the opposite — invisible. It is
- * at-least-once, not exactly-once:
- *   - PRIMARY cost: replay re-runs the WHOLE turn, so every external side effect happens AGAIN — re-sent
- *     messages, re-fired tool actions — and nobody may notice (unlike the visible loss it replaces).
- *     And the trigger is not rare (above): it fires on every deploy that interrupts an in-flight turn,
- *     not just on crashes. So "safe only if the turn's tools are idempotent" is a bar to judge against
- *     DEPLOY frequency: it holds for a Q&A bot, and is the gate for adding side-effecting tools. (A
- *     mid-stream interruption also leaves an orphan "💭 Thinking…" preview — cosmetic.)
- *   - The pre-ACK window overlaps webhook redelivery: a crash AFTER the persist but BEFORE the 200
- *     means recovery replays the turn AND the platform (never-ACKed) redelivers the same event — same
- *     id, and unless the channel dedups accepted ids, the turn can run twice. Exactly-once (a persisted
- *     delivery key) is L2.
- *
- * Channel-neutral, generic over the record shape: the channel supplies its own record type (everything
- * its runner needs to re-execute the turn), the shape validator (state files are an IO boundary), the
- * arrival ordering for recovery, and its log label. Telegram, Feishu/Lark, and Slack consume it.
- *
- * ponytail: at-least-once with a per-turn EXECUTION ceiling. A poison turn that deterministically
- * crashes the process would replay forever under a container restart policy. The counter is bumped at
- * `startAttempt` — when a turn is about to RUN, not per restart cycle — so it counts a turn's OWN
- * execution attempts: `recover()` re-enqueues every surviving turn without touching its count, and a
- * poison turn at a session's head is dropped on its own N+1th run WITHOUT penalizing the never-run turns
- * queued behind it (they keep their full budget and get their turn once the poison one is gone). On drop,
- * the runner notifies the asker (the chain's end must get a signal — a log line the user can't see isn't).
- * The bump is the ONE post-ACK write that fails CLOSED (not best-effort): if it can't be persisted the
- * turn is DEFERRED — skipped this cycle and left on disk to replay on the next start — rather than run
- * untracked, because an unpersisted count lets recover() re-run a poison turn every restart (the ceiling
- * would never advance on disk). It replays on the next START — a restart is required; disk recovery alone
- * does not re-run a deferred turn — and the asker is NOT told (a transient system degrade, not a user-
- * actionable failure — telling them "ask again" would double-answer on that replay).
- * 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).
+ * ponytail: at-least-once with a per-turn EXECUTION ceiling ({@link MAX_TURN_ATTEMPTS}). A poison turn that
+ * deterministically crashes the process would otherwise replay forever under a container restart policy; a real
+ * exactly-once story needs the different backend above.
  */
 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.
- */
+/** How many times a turn may START without finishing before it is dropped rather than run again. */
 const MAX_TURN_ATTEMPTS = 3;
 /**
- * End an ANSWERED turn: drop its durable intent, then commit the discussion it folded in.
+ * An ANSWERED turn: record the reply for delivery, then commit the discussion it folded in. The intent is NOT
+ * dropped here — generating an answer is not the same event as that answer reaching the chat, and the runner drops
+ * the record only once delivery has settled.
  *
- * 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.
+ * Returns whether the answer became recoverable, so a caller does not claim a recovery that has nothing on disk.
  */
 export function commitAnsweredTurn(store, buffer, turn) {
-    store.remove(turn.id);
+    const recorded = store.answered(turn.id, turn.answer);
     buffer.commit(turn.bufferKey, turn.consumed);
+    return recorded;
 }
 export function createTurnStore(path, opts) {
     const { label, isRecord, order } = opts;
@@ -84,7 +28,9 @@ export function createTurnStore(path, opts) {
         const raw = loadStateFile(path);
         if (raw === undefined)
             return new Map();
-        if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && Object.values(raw).every(isRecord)) {
+        // `answer` belongs to the generic record, so its shape is checked here rather than in each channel's validator.
+        const valid = (t) => isRecord(t) && (t.answer === undefined || typeof t.answer === "string");
+        if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && Object.values(raw).every(valid)) {
             return new Map(Object.entries(raw));
         }
         log.warn(`${label} unexpected shape in ${path} — starting with no pending turns`);
@@ -92,20 +38,22 @@ export function createTurnStore(path, opts) {
     };
     const turns = load();
     const persist = () => saveStateFile(path, Object.fromEntries(turns));
-    // Post-ACK writes (remove, startAttempt) must not abort a turn: log a failed write, never throw.
+    // Post-ACK writes (remove, startAttempt) must not abort a turn: log a failed write, never throw. The result is
+    // returned because whether the write landed is what a caller may be reporting to the operator.
     const persistBestEffort = (what) => {
         try {
             persist();
+            return true;
         }
         catch (e) {
             log.error(`${label} turn-store ${what} write failed post-ACK: ${String(e)}`);
+            return false;
         }
     };
     return {
         add(rec) {
-            // Idempotent on re-add: a redelivery (pre-ACK crash → never-ACKed event replayed) re-submits an id
-            // already in the store. Skip it — the intent is already durable, and overwriting would RESET this
-            // turn's execution count, handing a poison turn a fresh ceiling budget.
+            // Idempotent on re-add: a redelivery (pre-ACK crash → never-ACKed event replayed) re-submits an id already in
+            // the store.
             if (turns.has(rec.id))
                 return;
             turns.set(rec.id, rec);
@@ -113,20 +61,32 @@ export function createTurnStore(path, opts) {
                 persist(); // pre-ACK: the transport maps this throw to HTTP/WS 500, so the platform redelivers
             }
             catch (e) {
-                // Roll the memory back so it matches disk (mirrors context-buffer.push): otherwise the phantom
-                // entry makes the redelivery's `add` short-circuit on `turns.has` — running the turn with its
-                // intent never persisted, defeating this module — and gets flushed later by an unrelated persist.
+                // Roll the memory back so it matches disk (mirrors context-buffer.push): otherwise the phantom entry makes
+                // the redelivery's `add` short-circuit on `turns.has`.
                 turns.delete(rec.id);
                 throw e;
             }
         },
+        answered(id, answer) {
+            const rec = turns.get(id);
+            if (!rec) {
+                // An untracked run (see startAttempt): there is no record to write the answer to, so a delivery that fails
+                // from here loses it. Said out loud, because the alternative is a silent gap under a "kept for retry" log.
+                log.warn(`${label} turn ${id} answered with no record on disk (untracked run) — its answer is not recoverable`);
+                return false;
+            }
+            turns.set(id, { ...rec, answer });
+            // Post-ACK, so it cannot throw: a failed write costs the recovery copy, not the delivery about to happen. It
+            // does decide the answer of this function — an answer only in memory survives nothing.
+            return persistBestEffort("answer (a crash before delivery would lose the answer)");
+        },
         remove(id) {
             if (turns.delete(id))
-                persistBestEffort("remove (a restart may replay an answered turn)");
+                persistBestEffort("remove (a restart may re-deliver an answered turn)");
         },
         recover() {
-            // The channel's arrival order, applied explicitly rather than leaning on JS object-key enumeration
-            // happening to survive the load's JSON round-trip.
+            // The channel's arrival order, applied explicitly rather than leaning on JS object-key enumeration happening to
+            // survive the load's JSON round-trip.
             return [...turns.values()].sort(order);
         },
         startAttempt(id) {
@@ -135,10 +95,11 @@ export function createTurnStore(path, opts) {
                 return "run"; // no record — run untracked (a redelivery double-run whose first run removed it)
             const attempts = rec.attempts + 1;
             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.
+                // 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 ` +
-                    `(session=${rec.session}) — it may be crashing the process, or was killed mid-run each time; notifying the asker`);
+                    `(session=${rec.session}) — it may be crashing the process, or was killed mid-run each time; it will not ` +
+                    `be run again`);
                 turns.delete(id);
                 persistBestEffort("drop");
                 return "exceeded";
@@ -148,12 +109,8 @@ export function createTurnStore(path, opts) {
                 persist();
             }
             catch (e) {
-                // The bump MUST be durable, unlike remove/drop: if it isn't, a restart's recover() reads the old
-                // count and RE-RUNS this turn — a poison turn would re-execute forever (the ceiling never advances
-                // on disk). Fail closed: roll the memory bump back (match disk) and DEFER — the record stays on
-                // disk with its old count and replays on the next start (a restart is required; disk recovery
-                // alone won't re-run it). Not a drop: under disk failure the removal couldn't persist anyway.
-                // The runner skips silently (no notify).
+                // The bump MUST be durable, unlike remove/drop: if it isn't, a restart's recover() reads the old count and
+                // RE-RUNS this turn.
                 turns.set(id, rec);
                 log.error(`${label} cannot persist turn ${id}'s attempt count — deferring it to the next start rather ` +
                     `than run it untracked (session=${rec.session}): ${String(e)}`);

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

@@ -1,8 +1,4 @@
-/**
- * Lark-international compatibility adapter. Feishu is the canonical protocol/runtime implementation;
- * 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.
- */
+/** Lark-international compatibility adapter. */
 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;

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

@@ -1,13 +1,5 @@
 import type { FeishuGroupBehavior, FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
-/**
- * Guided Lark-international onboarding. The intl cloud cannot complete the BOUND scan-to-create flow,
- * so a new/partial setup opens its unbound one-click launcher and collects one App-scoped credential
- * set; a complete existing ID/Secret pair resumes that App directly. Then optimistically run Feishu's
- * webhook-mode + Verification-Token bootstrap against THIS app: a successful PATCH captures the token
- * and flips Subscription mode; only a definitive config-route 404 falls back to the token the console
- * displays + a manual mode switch. IO is injected so the workflow is testable without a terminal or
- * browser.
- */
+/** 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;
@@ -25,7 +17,7 @@ interface LarkBootstrapResult {
     manualReason?: string;
 }
 export interface LarkOnboardOptions {
-    /** Existing active .env values. A complete credential pair is reused (and still validated). */
+    /** Existing active .env values. */
     existing?: Readonly<Record<string, string | undefined>>;
     ingress?: FeishuSubscriptionMode;
     groupBehavior?: FeishuGroupBehavior;
@@ -37,7 +29,6 @@ export interface LarkOnboardCredentials {
     LARK_APP_SECRET: string;
     LARK_VERIFICATION_TOKEN?: string;
 }
-/** Open the stable app console and collect everything the runtime needs. Cancellation is a visible
- * failure: the scaffold remains and `add lark` is deliberately re-runnable to resume onboarding. */
+/** Open the stable app console and collect everything the runtime needs. */
 export declare function onboardLarkApp(io: LarkOnboardIO, opts: LarkOnboardOptions): Promise<LarkOnboardCredentials>;
 export {};

package/dist/channels/lark/onboard.js

@@ -1,12 +1,4 @@
-/**
- * Guided Lark-international onboarding. The intl cloud cannot complete the BOUND scan-to-create flow,
- * so a new/partial setup opens its unbound one-click launcher and collects one App-scoped credential
- * set; a complete existing ID/Secret pair resumes that App directly. Then optimistically run Feishu's
- * webhook-mode + Verification-Token bootstrap against THIS app: a successful PATCH captures the token
- * and flips Subscription mode; only a definitive config-route 404 falls back to the token the console
- * displays + a manual mode switch. IO is injected so the workflow is testable without a terminal or
- * browser.
- */
+/** Guided Lark-international onboarding. */
 export 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 function larkEventSecurityUrl(appId) {
@@ -18,14 +10,12 @@ function required(value, name) {
         throw new Error(`${name} is required — re-run \`fastagent add lark\` to continue setup`);
     return trimmed;
 }
-/** Open the stable app console and collect everything the runtime needs. Cancellation is a visible
- * failure: the scaffold remains and `add lark` is deliberately re-runnable to resume onboarding. */
+/** Open the stable app console and collect everything the runtime needs. */
 export async function onboardLarkApp(io, opts) {
     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. Reuse only a COMPLETE ID/Secret pair; a partial pair starts a
-    // fresh launcher/input path, and its unrelated old Token must not be attached to the newly-entered App.
+    // Credentials are one App-scoped set.
     if (reuseExistingApp) {
         io.note(`Reusing Lark app ${existingId}; opening its Events & Callbacks configuration directly.`);
     }

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

@@ -1,4 +1,5 @@
 import { larkChannel } from "@fastagent-sh/fastagent/lark";
+import { defineChannel } from "@fastagent-sh/fastagent";
 
 // 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
@@ -18,23 +19,30 @@ import { larkChannel } from "@fastagent-sh/fastagent/lark";
 //      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 larkChannel({
-  appId: process.env.LARK_APP_ID ?? "", // missing → fails at startup (no replies could be sent)
-  appSecret: process.env.LARK_APP_SECRET ?? "",
-  verificationToken: process.env.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]` },
+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]` },
+    }),
 });

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

@@ -0,0 +1,31 @@
+import { larkWebSocketChannel } from "@fastagent-sh/fastagent/lark";
+import { defineChannel } from "@fastagent-sh/fastagent";
+
+// Lark WebSocket long connection: the process connects OUT to the platform, so no public URL,
+// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long
+// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process
+// running in production: scale-to-zero/App Sleeping would disconnect ingress.
+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.
+  secrets: ["LARK_APP_ID", "LARK_APP_SECRET"],
+  channel: (secrets) =>
+    larkWebSocketChannel({
+      appId: secrets.LARK_APP_ID,
+      appSecret: secrets.LARK_APP_SECRET,
+      // 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]` },
+    }),
+});

package/dist/channels/registration.d.ts

@@ -1,44 +1,18 @@
 /**
- * SHARED: the webhook registrars' outcome. A registrar reports its own FACT; what to do about it (gate
- * the deploy or not, and with what remediation) is the CALLER's policy — `deploy --run` gates on
- * "failed", the tunnel (a long-running dev process) ignores the result entirely.
+ * SHARED: the webhook registrars' outcome. A registrar reports its own FACT; what to do about it is the CALLER's
+ * policy — `deploy --run` gates on "failed", the tunnel ignores the result entirely.
  *
- * - "registered": the platform accepted the webhook / event URL.
- * - "manual": this run did not fail, but an operator-facing step remains (the registrar printed the
- *   instructions). Two sub-states differ on re-runnability: credentials not configured (re-run after
- *   setting .env DOES auto-register; on the deploy path this is pre-gated by missingSecrets and
- *   unreachable) and a cloud without the config API (the Lark cloud-lag 404 — no re-run can ever
- *   register it; the console is the only path).
- * - "failed": this run ends with the webhook NOT registered, and acting + re-running can fix it
- *   (a permanent config error, or the platform still unable to reach the URL when the retries ran out).
+ * - `registered`: the platform accepted the webhook / event URL.
+ * - `manual`: this run did not fail, but an operator-facing step remains (the registrar printed it). Re-runnability
+ *   differs by sub-state: credentials not configured re-registers on a re-run; a cloud without the config API never
+ *   will (the console is the only path).
+ * - `failed`: the webhook is NOT registered, and acting plus re-running can fix it.
  */
 export type RegistrationOutcome = "registered" | "manual" | "failed";
 export declare const REGISTRATION_RETRY_MS = 10000;
-/**
- * What `deploy --run` spends instead: 180s, because a host CLI returns before the deployment serves —
- * the same gap a tunnel has, on a scale no local signal reports (`docker compose --tunnel` is the one
- * host whose ingress does report it, and its driver waits on it the way the tunnel does).
- *
- * `railway up --ci` returns when the BUILD ends — container start, healthcheck and a freshly minted
- * domain's DNS all happen after that, and railway-deploy.live.test.ts allows 180s for exactly this.
- * Registration failure GATES the deploy (registration-gate.ts), so a budget shorter than the host's
- * own start-up turns a working deployment into a re-run instruction.
- *
- * N attempts buy (N - 1) waits — {@link retryWhile} only waits BETWEEN calls — so 180s of patience is
- * 19, not 18. At 18 the last call went out at t=170s and a host that started answering in the final
- * ten seconds was still reported as a deploy to re-run.
- */
+/** What `deploy --run` spends instead: 180s, because a host CLI returns before the deployment serves. */
 export declare const DEPLOY_REGISTRATION_ATTEMPTS = 19;
-/**
- * Call, and while `retryable` says the failure is the platform not reaching the URL YET, call again —
- * the one retry loop every registrar spends {@link REGISTRATION_ATTEMPTS} through. Retryability and
- * what a final failure MEANS stay with each platform (their vocabularies differ, and one registrar's
- * terminal state is another's `"manual"`); the counting, the announcement and the wait do not.
- *
- * `onRetry` runs BEFORE the wait — registrars announce there (a silent minute reads as a hang), and
- * `add slack` also drops its duplicate-guard marker so it never spans a sleep. The last error is
- * thrown, so a caller can tell "still unreachable" from "a config error" in one place.
- */
+/** Call, and while `retryable` says the failure is the platform not reaching the URL YET, call again. */
 export declare function retryWhile<T>(call: () => Promise<T>, retryable: (error: unknown) => boolean, options?: {
     attempts?: number;
     retryMs?: number;

package/dist/channels/registration.js

@@ -1,45 +1,14 @@
-/**
- * SHARED: how long a registrar waits for the PLATFORM to be able to reach a freshly minted public URL.
- * One judgement (a new tunnel's warm-up), so one pair of numbers — telegram, feishu, slack registration
- * and `add slack` all spend it.
- *
- * Sized for a tunnel, which is live before its URL is HANDED OVER — not before it is printed, which is
- * what this budget once had to absorb: a quick tunnel's hostname is published when the tunnel registers
- * an edge connection, seconds after cloudflared prints it, and no budget covers a platform that already
- * answered "cannot resolve" (#435). `startCloudflareTunnel` waits for that connection, so what is left
- * here is the platform's own warm-up. Applied by {@link retryWhile} as its default; a DEPLOY is slower
- * and its callers pass {@link DEPLOY_REGISTRATION_ATTEMPTS} instead.
- */
+/** SHARED: how long a registrar waits for the PLATFORM to be able to reach a freshly minted public URL. */
 const REGISTRATION_ATTEMPTS = 8;
 export const REGISTRATION_RETRY_MS = 10_000;
-/**
- * What `deploy --run` spends instead: 180s, because a host CLI returns before the deployment serves —
- * the same gap a tunnel has, on a scale no local signal reports (`docker compose --tunnel` is the one
- * host whose ingress does report it, and its driver waits on it the way the tunnel does).
- *
- * `railway up --ci` returns when the BUILD ends — container start, healthcheck and a freshly minted
- * domain's DNS all happen after that, and railway-deploy.live.test.ts allows 180s for exactly this.
- * Registration failure GATES the deploy (registration-gate.ts), so a budget shorter than the host's
- * own start-up turns a working deployment into a re-run instruction.
- *
- * N attempts buy (N - 1) waits — {@link retryWhile} only waits BETWEEN calls — so 180s of patience is
- * 19, not 18. At 18 the last call went out at t=170s and a host that started answering in the final
- * ten seconds was still reported as a deploy to re-run.
- */
+/** What `deploy --run` spends instead: 180s, because a host CLI returns before the deployment serves. */
 export const DEPLOY_REGISTRATION_ATTEMPTS = 19;
-/** Sleep on the GLOBAL timer (not `node:timers/promises`) so tests can drive it with fake timers — the
- *  same reason feishu-api.ts does. What must happen BEFORE this wait is the point of `onRetry`. */
-const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
- * Call, and while `retryable` says the failure is the platform not reaching the URL YET, call again —
- * the one retry loop every registrar spends {@link REGISTRATION_ATTEMPTS} through. Retryability and
- * what a final failure MEANS stay with each platform (their vocabularies differ, and one registrar's
- * terminal state is another's `"manual"`); the counting, the announcement and the wait do not.
- *
- * `onRetry` runs BEFORE the wait — registrars announce there (a silent minute reads as a hang), and
- * `add slack` also drops its duplicate-guard marker so it never spans a sleep. The last error is
- * thrown, so a caller can tell "still unreachable" from "a config error" in one place.
+ * Sleep on the GLOBAL timer (not `node:timers/promises`) so tests can drive it with fake timers — the same reason
+ * feishu-api.ts does.
  */
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Call, and while `retryable` says the failure is the platform not reaching the URL YET, call again. */
 export async function retryWhile(call, retryable, options = {}) {
     const attempts = options.attempts ?? REGISTRATION_ATTEMPTS;
     const retryMs = options.retryMs ?? REGISTRATION_RETRY_MS;

package/dist/channels/secret.js

@@ -1,9 +1,6 @@
 /**
- * The ONE constant-time comparison every shared-secret gate uses: a webhook secret token, a
- * signature, a bearer token, an envelope secret. Timing-safe on equal lengths; a length mismatch
- * answers false without leaking a prefix. Non-string input reads as no secret — and an EMPTY
- * expected value never matches, so a gate whose secret was never configured cannot be passed by
- * sending none.
+ * The ONE constant-time comparison every shared-secret gate uses: a webhook secret token, a signature, a bearer token,
+ * an envelope secret.
  */
 import { Buffer } from "node:buffer";
 import { timingSafeEqual } from "node:crypto";

package/dist/channels/serve.d.ts

@@ -1,68 +1,71 @@
 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. */
+/** 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.
- *
- * 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.
- */
+/** 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? Equal paths, and a method each answers; a key
- *  with no method answers all of them. */
+/** 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. Kept out of {@link Routes} so a key is always a literal path and collision checks stay
- *  comparisons. */
+/** 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`). 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. */
+    /** Absolute, no trailing slash, and not `/` (`/control`). */
     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. */
+/** Same status and headers, no content (RFC 9110's HEAD). */
 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.
+ * Refuse a cross-origin allow-list that cannot match anything.
  *
- * 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.
+ * 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.
  *
- * 404 and 405 stay distinct: a remote client reads 404 as "this serve predates the route" (version
- * skew) rather than as a fault.
+ * 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 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.
+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.
  *
- *  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;
+ * 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;
 /**
- * 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).
+ * 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: {
     port: number;
     host?: string;