@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/scaffold/add-channel.js

@@ -7,7 +7,7 @@
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { detectRuntime } from "../runtime.js";
-import { SECRETS_DIRNAME, assertInsideAgentDir, exists } from "../paths.js";
+import { SECRETS_DIRNAME, assertInsideAgentDir, ensureSecretsDir, exists } from "../paths.js";
 import { baseTemplate, channelBundleFiles, channelTemplate } from "./templates.js";
 import { dotEnvPath, envExamplePath, parseEnvContent } from "../env.js";
 const CHANNEL_SCAFFOLDS = {
@@ -44,28 +44,12 @@ const CHANNEL_SCAFFOLDS = {
     },
     slack: {
         env: [
-            { name: "SLACK_BOT_TOKEN", hint: "Slack app → rotating Bot User OAuth access token", required: true },
-            {
-                name: "SLACK_BOT_REFRESH_TOKEN",
-                hint: "Slack OAuth bot refresh token (required when token rotation is enabled)",
-                required: false,
-            },
-            {
-                name: "SLACK_BOT_TOKEN_EXPIRES_AT",
-                hint: "Slack rotating bot access-token expiry (epoch milliseconds)",
-                required: false,
-            },
-            { name: "SLACK_CLIENT_ID", hint: "Slack app OAuth client ID (for bot-token rotation)", required: false },
-            {
-                name: "SLACK_CLIENT_SECRET",
-                hint: "Slack app OAuth client secret (for bot-token rotation)",
-                required: false,
-            },
+            { name: "SLACK_BOT_TOKEN", hint: "Slack app → OAuth & Permissions → Bot User OAuth Token", required: true },
             { name: "SLACK_SIGNING_SECRET", hint: "Slack app → Basic Information → App Credentials", required: true },
         ],
         steps: [
             "Slack Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history, files:read, files:write, channels:history, groups:history, mpim:history",
-            "enable Agents (agent_view) and token rotation; subscribe app_home_opened, app_context_changed, app_mention, message.im, message.channels, message.groups, message.mpim; set Request URL to <public-url>/slack",
+            "enable Agents (agent_view) and leave token rotation OFF (it cannot be turned off again); subscribe app_home_opened, app_context_changed, app_mention, message.im, message.channels, message.groups, message.mpim; set Request URL to <public-url>/slack",
             "reinstall the app after changing scopes, then invite it to each channel it should read",
             "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
         ],
@@ -172,7 +156,7 @@ export function channelSetup(kind, ingress = "webhook", groupBehavior) {
             env: setup.env,
             steps: [
                 "Slack Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history, files:read, files:write (no channel/group/mpim history scopes)",
-                "enable Agents (agent_view) and token rotation; subscribe app_home_opened, app_context_changed, app_mention, and message.im; set Request URL to <public-url>/slack",
+                "enable Agents (agent_view) and leave token rotation OFF (it cannot be turned off again); subscribe app_home_opened, app_context_changed, app_mention, and message.im; set Request URL to <public-url>/slack",
                 "group behavior: mention-only — bare thread replies and unsummoned group context remain disabled",
                 ...setup.steps.slice(2),
             ],
@@ -229,7 +213,7 @@ function mentionsEnvName(content, name) {
 export async function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
     const file = dotEnvPath(dir);
     const secretsDir = dirname(file);
-    await mkdir(secretsDir, { recursive: true });
+    await ensureSecretsDir(secretsDir);
     // THE one exception to "fastagent has no opinion about git": the directory it writes secrets into
     // carries its own `.gitignore`. `init` writes it, and so does this — the reachable case where it is
     // missing (a hand-made agent) is exactly the one where the next line mints an unrecoverable app
@@ -340,55 +324,54 @@ export async function scaffoldChannel(dir, kind, options = {}) {
         throw new Error(`${file} already exists — edit it, or remove it to re-scaffold`);
     }
     await mkdir(channelsDir, { recursive: true });
-    // `channel.ts` is THE adapter (→ channels/<kind>.ts); any other .ts in the bundle is a companion tool
-    // (→ tools/<name>, never clobbering an authored one).
+    let content = channelTemplate(kind, "channel.ts");
+    if ((kind === "feishu" || kind === "lark") && options.ingress === "websocket") {
+        const factory = `${kind}Channel`;
+        const wsFactory = `${kind}WebSocketChannel`;
+        let configured = content
+            .replace(`import { ${factory} }`, `import { ${wsFactory} }`)
+            .replace(`export default ${factory}({`, `export default ${wsFactory}({`);
+        if (configured === content)
+            throw new Error(`${kind} channel template has no factory anchors`);
+        const prefix = kind === "feishu" ? "FEISHU" : "LARK";
+        const exportAt = configured.indexOf("export default");
+        const importEnd = configured.indexOf("\n\n");
+        if (exportAt < 0 || importEnd < 0)
+            throw new Error(`${kind} channel template header anchors are missing`);
+        const brand = kind === "feishu" ? "Feishu" : "Lark";
+        configured =
+            `${configured.slice(0, importEnd)}\n\n` +
+                `// ${brand} WebSocket long connection: the process connects OUT to the platform, so no public URL,\n` +
+                `// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long\n` +
+                `// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process\n` +
+                `// running in production: scale-to-zero/App Sleeping would disconnect ingress.\n` +
+                configured.slice(exportAt);
+        configured = configured
+            .split("\n")
+            .filter((line) => !line.includes(`verificationToken: process.env.${prefix}_VERIFICATION_TOKEN`) &&
+            !line.includes(`encryptKey: process.env.${prefix}_ENCRYPT_KEY`))
+            .join("\n");
+        content = configured;
+    }
+    await writeFile(file, content, { flag: "wx" });
+    return file;
+}
+/**
+ * The bundle's companion tools (every `.ts` beside `channel.ts` → `tools/<name>`). Unlike the channel
+ * file they are the package's, not authored glue, so they are written on EVERY add: re-running
+ * `add <kind>` is how an upgraded tool reaches an existing agent.
+ */
+export async function scaffoldCompanionTools(dir, kind) {
+    const written = [];
     for (const name of channelBundleFiles(kind)) {
-        let content = channelTemplate(kind, name);
-        if (name === "channel.ts") {
-            if ((kind === "feishu" || kind === "lark") && options.ingress === "websocket") {
-                const factory = `${kind}Channel`;
-                const wsFactory = `${kind}WebSocketChannel`;
-                let configured = content
-                    .replace(`import { ${factory} }`, `import { ${wsFactory} }`)
-                    .replace(`export default ${factory}({`, `export default ${wsFactory}({`);
-                if (configured === content)
-                    throw new Error(`${kind} channel template has no factory anchors`);
-                const prefix = kind === "feishu" ? "FEISHU" : "LARK";
-                const exportAt = configured.indexOf("export default");
-                const importEnd = configured.indexOf("\n\n");
-                if (exportAt < 0 || importEnd < 0)
-                    throw new Error(`${kind} channel template header anchors are missing`);
-                const brand = kind === "feishu" ? "Feishu" : "Lark";
-                configured =
-                    `${configured.slice(0, importEnd)}\n\n` +
-                        `// ${brand} WebSocket long connection: the process connects OUT to the platform, so no public URL,\n` +
-                        `// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long\n` +
-                        `// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process\n` +
-                        `// running in production: scale-to-zero/App Sleeping would disconnect ingress.\n` +
-                        configured.slice(exportAt);
-                configured = configured
-                    .split("\n")
-                    .filter((line) => !line.includes(`verificationToken: process.env.${prefix}_VERIFICATION_TOKEN`) &&
-                    !line.includes(`encryptKey: process.env.${prefix}_ENCRYPT_KEY`))
-                    .join("\n");
-                content = configured;
-            }
-            if (kind === "slack" && options.groupBehavior === "mentions") {
-                const configured = content.replace('groupBehavior: "context"', 'groupBehavior: "mentions"');
-                if (configured === content)
-                    throw new Error("slack channel template has no groupBehavior anchor");
-                content = configured;
-            }
-            await writeFile(file, content, { flag: "wx" });
+        if (name === "channel.ts")
             continue;
-        }
-        const toolFile = join(dir, "tools", name);
-        if (!(await exists(toolFile))) {
-            await mkdir(join(dir, "tools"), { recursive: true });
-            await writeFile(toolFile, content, { flag: "wx" });
-        }
+        const file = join(dir, "tools", name);
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, channelTemplate(kind, name));
+        written.push(file);
     }
-    return file;
+    return written;
 }
 /**
  * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares

package/dist/scaffold/init.js

@@ -27,7 +27,7 @@
  */
 import { lstat, mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve, sep } from "node:path";
-import { AGENT_CONFIG_NAMES, DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentDefinitionOwner, agentsAt, displayPath, exists, } from "../paths.js";
+import { AGENT_CONFIG_NAMES, DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentDefinitionOwner, agentsAt, displayPath, ensureSecretsDir, exists, } from "../paths.js";
 import { baseTemplate, packageJson, toPackageName } from "./templates.js";
 import { fastagentVersion } from "../version.js";
 /** The agent directory name for a raw `--agent-dir` value: the default when unset, and `./bot` read as
@@ -191,7 +191,12 @@ export async function scaffoldAgent(dir, options = {}) {
     try {
         for (const file of files) {
             const abs = join(dir, file.rel);
-            await mkdir(dirname(abs), { recursive: true });
+            // The secrets dir carries a mode; every other directory here is ordinary. `init` is usually the
+            // FIRST of the four writers to create it, and whoever creates it decides the mode for the rest.
+            if (basename(dirname(abs)) === SECRETS_DIRNAME)
+                await ensureSecretsDir(dirname(abs));
+            else
+                await mkdir(dirname(abs), { recursive: true });
             try {
                 await writeFile(abs, file.content, { flag: "wx" });
                 created.push(file.rel);

package/dist/scaffold/templates/tools/fetch-url.ts

@@ -3,8 +3,6 @@ import { defineTool, z } from "@fastagent-sh/fastagent";
 // A code tool: filename (fetch-url.ts) is the tool name. tools/ is auto-discovered,
 // so it needs no registration in fastagent.config. Test it without a model:
 //   fastagent tool fetch-url '{"url":"https://example.com"}'
-// Serving this behind a public channel? The URL then comes from untrusted users — add an
-// allowlist or block private-network addresses (localhost, 169.254.169.254, …) to prevent SSRF.
 const MAX_TEXT = 20_000; // keep a huge page from flooding the model's context
 
 export default defineTool({

package/dist/schedule/discover.js

@@ -4,9 +4,8 @@
  * named from its filename. This is the FILE producer of scheduled invocations (the author's, declarative,
  * git-tracked, deploy-guaranteed); the agent's `wake` tool is the second producer.
  */
-import { readdir } from "node:fs/promises";
 import { join } from "node:path";
-import { isModuleFile, loadModuleDir } from "../loader.js";
+import { loadModuleDir, moduleInventory } from "../loader.js";
 import { assertInsideAgentDir } from "../paths.js";
 import { cronError } from "./cron.js";
 /** Schedule file basenames under `<dir>/schedules/` — an existence probe listed WITHOUT importing
@@ -14,19 +13,8 @@ import { cronError } from "./cron.js";
  *  since it also reports broken files and next instants). */
 export async function discoverScheduleFiles(dir) {
     await assertInsideAgentDir(dir, "schedules");
-    let names;
-    try {
-        names = await readdir(join(dir, "schedules"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-    return names
-        .filter(isModuleFile)
-        .map((n) => n.replace(/\.(ts|js|mjs)$/, ""))
-        .sort();
+    const entries = await moduleInventory(join(dir, "schedules"));
+    return entries.map((entry) => entry.name);
 }
 /**
  * Discover schedules in `<dir>/schedules/`: each file default-exports a `defineSchedule({...})`, named

package/dist/schedule/wake-alarm.d.ts

@@ -1,16 +1,5 @@
-import type { Wakeup } from "./wakeups.ts";
-/** The forwarder's reserved wake-alarm path — never forwarded to channel routes. */
-export declare const WAKE_ALARM_PATH = "/__fastagent/wake-alarm";
-/** One desired alarm: mirror of a pending wake-up (id names the EventBridge schedule; at = fireAt). */
-export interface WakeAlarm {
-    id: string;
-    at: string;
-}
-/** The wire shape the sink POSTs to {@link WAKE_ALARM_PATH} (the forwarder validates `secret`). */
-export interface WakeAlarmRequest {
-    secret: string;
-    alarms: WakeAlarm[];
-}
+import { type WakeAlarm } from "../channels/agentcore-protocol.ts";
+import { type Wakeup } from "./wakeups.ts";
 /**
  * Persist the forwarder URL the adapter saw in an envelope (write-if-changed — envelopes arrive on
  * every turn, the file should not churn). Durable under <stateRoot>/schedule/ so a freshly booted
@@ -31,6 +20,17 @@ export declare function toAlarms(pending: Wakeup[], now: Date): WakeAlarm[];
  * when `FASTAGENT_AGENTCORE=1` + `FASTAGENT_WAKE_SECRET` are present). Fire-and-forget by contract:
  * failures are logged, never thrown — a broken alarm degrades to the pre-alarm behavior (the wake
  * still fires on the next time the box happens to be awake), it must never break the store write.
+ *
+ * A single-flight RECONCILER, not a per-mutation delivery: a notification only marks the desired
+ * state dirty, and the loop re-derives it from the store before every attempt. So a mutation during
+ * a retry needs no ordering rule — there is one desired state, never two snapshots to rank — and the
+ * {@link DUE_MARGIN_MS} filter is re-applied with a fresh clock, which a captured payload could not
+ * do: entries that became due mid-retry would keep being POSTed with a past `at()`, a rejection no
+ * number of retries could clear.
+ *
+ * Assumes ONE sink per process over ONE state root (what `start` builds): the loop keeps the root of
+ * the call that started it, and its dirty flag is shared, so a second root would fold into the first
+ * one's pass.
  */
 export declare function createWakeAlarmSink(options: {
     secret: string;
@@ -39,9 +39,4 @@ export declare function createWakeAlarmSink(options: {
     now?: () => Date;
     /** Injectable retry pause (tests); defaults to exponential-ish backoff off RETRY_BASE_MS. */
     delay?: (ms: number) => Promise<void>;
-}): (stateRoot: string, pending: Wakeup[]) => void;
-/**
- * One boot-time reconcile: pending wake-ups may exist while their alarms were lost (a deploy
- * replaced the forwarder, a sink call failed) — re-mirror the current set once at start.
- */
-export declare function reconcileWakeAlarms(stateRoot: string, sink: (stateRoot: string, pending: Wakeup[]) => void): void;
+}): (stateRoot: string) => void;

package/dist/schedule/wake-alarm.js

@@ -17,17 +17,17 @@
  * Function URL at cold start), and the adapter persists it here; every wake write happens inside a
  * turn, and every ingress turn arrived through an envelope, so the URL is always known by then.
  *
- * Reconciliation is DECLARATIVE (the full pending set travels each time) and deletion is lazy: a
+ * Reconciliation is DECLARATIVE (the sink is told only THAT the store changed and reads the full
+ * pending set back per attempt, so no retry ever carries a stale view) and deletion is lazy: a
  * cancelled wake-up's alarm still fires its poke, finds nothing due, and self-deletes — a harmless
  * wasted wake-up of the box, traded for never needing list/delete choreography.
  */
 import { readFileSync } from "node:fs";
+import { RESERVED_PATHS } from "../channels/agentcore-protocol.js";
 import { beginWork } from "../channels/busy.js";
 import { log } from "../log.js";
 import { scheduleFile, writeScheduleFile } from "./state.js";
 import { listWakeups } from "./wakeups.js";
-/** The forwarder's reserved wake-alarm path — never forwarded to channel routes. */
-export const WAKE_ALARM_PATH = "/__fastagent/wake-alarm";
 const URL_FILE = "wake-alarm-url";
 /**
  * Persist the forwarder URL the adapter saw in an envelope (write-if-changed — envelopes arrive on
@@ -71,66 +71,107 @@ export function toAlarms(pending, now) {
  * when `FASTAGENT_AGENTCORE=1` + `FASTAGENT_WAKE_SECRET` are present). Fire-and-forget by contract:
  * failures are logged, never thrown — a broken alarm degrades to the pre-alarm behavior (the wake
  * still fires on the next time the box happens to be awake), it must never break the store write.
+ *
+ * A single-flight RECONCILER, not a per-mutation delivery: a notification only marks the desired
+ * state dirty, and the loop re-derives it from the store before every attempt. So a mutation during
+ * a retry needs no ordering rule — there is one desired state, never two snapshots to rank — and the
+ * {@link DUE_MARGIN_MS} filter is re-applied with a fresh clock, which a captured payload could not
+ * do: entries that became due mid-retry would keep being POSTed with a past `at()`, a rejection no
+ * number of retries could clear.
+ *
+ * Assumes ONE sink per process over ONE state root (what `start` builds): the loop keeps the root of
+ * the call that started it, and its dirty flag is shared, so a second root would fold into the first
+ * one's pass.
  */
 export function createWakeAlarmSink(options) {
     const { secret, fetchImpl = fetch, now = () => new Date() } = options;
     const delay = options.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-    // Supersession token: a newer mutation's sync REPLACES an older one still retrying — without it,
-    // an old in-flight set could win the race and mirror stale state.
-    let latest;
-    async function sync(url, body, token) {
+    let running = false;
+    let dirty = false;
+    /** One POST of the CURRENT desired set. Returns false to retry, true when there is nothing left
+     *  to do (converged, or nothing this loop can act on). */
+    async function attemptOnce(stateRoot, attempt) {
+        const alarms = toAlarms(listWakeups(stateRoot), now());
+        // Nothing future to mirror: converged. Deletion is lazy by design — alarms already mirrored for
+        // cancelled wake-ups fire, find nothing, self-delete — so an empty set is never POSTed.
+        if (alarms.length === 0)
+            return true;
+        const url = readWakeAlarmUrl(stateRoot);
+        if (!url) {
+            // Before the first envelope, or an unreadable state mount (readWakeAlarmUrl folds both into
+            // undefined). The wake itself is stored; the next store mutation or boot re-mirrors it.
+            log.warn("[schedule] wake alarm skipped — forwarder URL unavailable (not seen yet, or unreadable)");
+            return true;
+        }
+        const body = { secret, alarms };
+        try {
+            const res = await fetchImpl(`${url.replace(/\/$/, "")}${RESERVED_PATHS.wakeAlarm}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(SYNC_TIMEOUT_MS),
+            });
+            if (res.ok)
+                return true;
+            log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: HTTP ${res.status}`);
+        }
+        catch (e) {
+            log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: ${String(e)}`);
+        }
+        return false;
+    }
+    async function reconcile(stateRoot) {
         // Counted as in-flight work: the retry loop is exactly the window where the box must not be
         // reclaimed — idle away mid-retry and a pending wake has no alarm until the next boot.
         const workDone = beginWork();
+        // Consecutive failures ACROSS passes, not within one. A mid-retry mutation restarts the attempt
+        // sequence (the backoff and the log's `n/N` are about the new desired set), but it must not renew
+        // the budget: a store mutating faster than the backoff would keep the loop alive forever, and the
+        // one loud line saying the forwarder is down — the per-attempt warns are filterable — would never
+        // be reached. This counter is the thing that survives to reach it.
+        let failures = 0;
         try {
-            for (let attempt = 1; attempt <= MAX_SYNC_ATTEMPTS; attempt++) {
-                if (latest !== token)
-                    return; // superseded by a newer set — that sync owns correctness now
-                try {
-                    const res = await fetchImpl(`${url.replace(/\/$/, "")}${WAKE_ALARM_PATH}`, {
-                        method: "POST",
-                        headers: { "content-type": "application/json" },
-                        body: JSON.stringify(body),
-                        signal: AbortSignal.timeout(SYNC_TIMEOUT_MS),
-                    });
-                    if (res.ok)
-                        return;
-                    log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: HTTP ${res.status}`);
+            while (dirty && failures < MAX_SYNC_ATTEMPTS) {
+                dirty = false;
+                for (let attempt = 1; attempt <= MAX_SYNC_ATTEMPTS; attempt++) {
+                    if (await attemptOnce(stateRoot, attempt)) {
+                        failures = 0;
+                        break;
+                    }
+                    failures++;
+                    if (attempt === MAX_SYNC_ATTEMPTS || failures >= MAX_SYNC_ATTEMPTS)
+                        break;
+                    await delay(RETRY_BASE_MS * attempt);
+                    // A mutation landed mid-retry: the desired state moved, so this budget is spent on a set
+                    // that no longer exists. Restart the attempt count against the new one.
+                    if (dirty)
+                        break;
                 }
-                catch (e) {
-                    log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: ${String(e)}`);
-                }
-                await delay(RETRY_BASE_MS * attempt);
             }
-            log.error(`[schedule] wake alarm sync FAILED after ${MAX_SYNC_ATTEMPTS} attempts — pending wake-ups have no ` +
-                `external alarm until the next store change or boot re-mirrors them`);
+            if (failures >= MAX_SYNC_ATTEMPTS) {
+                log.error(`[schedule] wake alarm sync FAILED after ${MAX_SYNC_ATTEMPTS} attempts — pending wake-ups have no ` +
+                    `external alarm until the next store change or boot re-mirrors them`);
+            }
+        }
+        catch (e) {
+            // The END of the error path: nothing awaits this loop, so an escape is an unhandled rejection
+            // that kills the container. `listWakeups` throws by design on an unreadable store (state.ts),
+            // exactly the fault a wake alarm cannot fix — report it and leave the store write untouched,
+            // which is this sink's whole contract. The next mutation or boot re-runs the mirror.
+            log.error(`[schedule] wake alarm reconcile failed (alarms are stale until the next store change): ${String(e)}`);
         }
         finally {
+            running = false;
             workDone();
         }
     }
-    return (stateRoot, pending) => {
-        const url = readWakeAlarmUrl(stateRoot);
-        if (!url) {
-            // First-ever boot before any envelope: nothing to call yet. The wake itself is stored; the
-            // alarm catches up on the next store mutation after an envelope has arrived.
-            log.warn("[schedule] wake alarm skipped — forwarder URL not seen yet (it arrives with the first envelope)");
+    // Single-flight: a save arriving while the loop runs only marks it dirty, so a burst coalesces
+    // into one more pass instead of one concurrent loop each.
+    return (stateRoot) => {
+        dirty = true;
+        if (running)
             return;
-        }
-        const alarms = toAlarms(pending, now());
-        if (alarms.length === 0)
-            return; // nothing future to mirror (deletion is lazy by design)
-        const token = Symbol("wake-alarm-sync");
-        latest = token;
-        void sync(url, { secret, alarms }, token);
+        running = true;
+        void reconcile(stateRoot);
     };
 }
-/**
- * One boot-time reconcile: pending wake-ups may exist while their alarms were lost (a deploy
- * replaced the forwarder, a sink call failed) — re-mirror the current set once at start.
- */
-export function reconcileWakeAlarms(stateRoot, sink) {
-    const pending = listWakeups(stateRoot);
-    if (pending.length > 0)
-        sink(stateRoot, pending);
-}

package/dist/schedule/wakeups.d.ts

@@ -26,7 +26,7 @@ export declare const MAX_PENDING_WAKEUPS = 20;
  *  wake into an active conversation fires in the first gap between the user's turns; this generous
  *  ceiling (~1h) only gives up on a pathologically stuck session (then logs, operator-visible). */
 export declare const MAX_WAKE_ATTEMPTS = 120;
-export declare function setWakeupsSink(sink: ((stateRoot: string, pending: Wakeup[]) => void) | undefined): void;
+export declare function setWakeupsSink(sink: ((stateRoot: string) => void) | undefined): void;
 /** The current pending wake-ups (`fastagent schedule list` uses this). */
 export declare function listWakeups(stateRoot: string): Wakeup[];
 export type AddWakeupResult = {

package/dist/schedule/wakeups.js

@@ -48,12 +48,15 @@ function isWakeup(e) {
             (typeof w.cron === "string" && cronError(w.cron, typeof w.tz === "string" ? w.tz : undefined) === undefined)));
 }
 /**
- * The wake-ALARM sink: notified after EVERY wakeups-store mutation with the new pending set. The
- * AgentCore deployment registers one (schedule/wake-alarm.ts) that mirrors pending wake-ups into
- * one-shot EventBridge schedules — the external clock that makes `wake` reliable on a host with no
- * resident process. Neutral seam: this module knows only "someone wants to observe changes"; a
- * resident host registers nothing and behaves exactly as before. The sink is fire-and-forget and
- * must own its errors; a throw is caught here so a broken alarm never corrupts a store write.
+ * The wake-ALARM sink: notified after EVERY wakeups-store mutation. A notification, not a delivery
+ * — it carries no set, because the sink reconciles by re-reading the store, and handing it a set
+ * captured here would go stale in its retries. The AgentCore deployment registers one
+ * (schedule/wake-alarm.ts) that mirrors pending wake-ups into one-shot EventBridge schedules — the
+ * external clock that makes `wake` reliable on a host with no resident process. Neutral seam: this
+ * module knows only "someone wants to observe changes"; a resident host registers nothing and
+ * behaves exactly as before. The sink is fire-and-forget and must own its errors. The guard below
+ * catches a SYNCHRONOUS throw so a broken alarm never corrupts a store write; an async sink returns
+ * before it does any work, so its rejections are ITS to terminate — nothing here can see them.
  */
 let wakeupsSink;
 export function setWakeupsSink(sink) {
@@ -81,7 +84,7 @@ function load(stateRoot) {
 function save(stateRoot, wakeups) {
     writeScheduleFile(scheduleFile(stateRoot, "wakeups"), wakeups);
     try {
-        wakeupsSink?.(stateRoot, wakeups);
+        wakeupsSink?.(stateRoot);
     }
     catch (e) {
         log.error(`[schedule] wake-alarm sink failed (store write is unaffected): ${String(e)}`);

package/dist/service.d.ts

@@ -1,8 +1,24 @@
+/**
+ * The product, as one call: an agent directory becomes a live service.
+ *
+ * That phrase is the promise on the README, and until this existed only the CLI could keep it. The
+ * assembly parts live here too — `routesFor`, `mountSessionControl`, `startSchedules` — because a
+ * public entry may not reach into `cli/`: that directory decides process-level things (`fail.ts`
+ * calls `process.exit`) which a library mounted inside someone's app does not get to decide.
+ * Everything else was parts: assemble the agent, discover channels, mount the control plane, start
+ * schedules, open long connections, compose a router. An embedder had to know that list and get its
+ * order right, and getting it wrong is silent: a plane that 404s while advertising itself, a
+ * schedule that never fires.
+ *
+ * So the assembly lives here, and `dev`/`start` are callers. AgentCore is the one exception, and a
+ * substantive one: its channels load lazily after a state-snapshot restore, so it cannot use an
+ * assembly that discovers them eagerly (cli/commands/start.ts says so at the branch).
+ */
 import type { Agent } from "./agent.ts";
+import { type PrefixMount } from "./channels/serve.ts";
 import { type LoadedLongConnectionChannel } from "./channels/discover.ts";
 import type { SessionControl } from "./session.ts";
 import type { ChannelHandler, Routes } from "./channel.ts";
-import { type PrefixMount } from "./channels/serve.ts";
 import type { LoadedSchedule } from "./schedule/schedule.ts";
 export interface ServingSurface {
     routes: Routes;
@@ -12,7 +28,6 @@ export interface ServingSurface {
     /** Route-channel basenames; the tunnel registers only this subset. */
     routeChannels: string[];
     builtinInvoke: boolean;
-    /** Marks the built-in health route ready after every long-connection channel first connects. */
     /** Flip health between 200 and 503. Two-way on purpose: a long connection that dies after coming
      *  up leaves the surface serving something it no longer has, and a load balancer should hear it. */
     setReady(value: boolean): void;
@@ -36,20 +51,17 @@ export declare function routesFor(agentDir: string, agent: Agent, stateRoot: str
  * load after this ran against an empty base.
  */
 export declare function assertNoControlPlaneCollision(channelRoutes: Routes, plane: PrefixMount): void;
-export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
-    tunnel?: boolean;
+export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, options?: {
     agent?: Agent;
-    host?: string;
 }): {
     routes: Routes;
     mounts: PrefixMount[];
-    /** The plane's bearer token and prefix — how an embedder distributes access without a discovery file. */
+    /** The plane's bearer token and prefix — how a caller distributes access (the CLI writes it to
+     *  `<stateRoot>/control.json` for local discovery; an embedder hands it out itself). */
     control?: {
         token: string;
         prefix: string;
     };
-    /** Write the local discovery file; returns its removal. Installs no signal handlers. */
-    announce: (boundPort: number) => () => void;
 };
 /**
  * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
@@ -89,20 +101,14 @@ export interface AgentService {
      *  fails to come up, after closing the service: a host must not report itself serving while a
      *  declared channel is dead, and health answers 503 until this resolves. */
     ready: Promise<void>;
-    /** The control plane's bearer token and prefix, when `sessionControl` is on — how an embedder
-     *  hands access to a client without a discovery file. */
+    /** The control plane's bearer token and prefix, when `sessionControl` is on — how a caller hands
+     *  access to a client. The CLI writes it to `<stateRoot>/control.json` for `fastagent attach`; an
+     *  embedder mounted inside a larger app has no port of its own to describe and distributes it
+     *  itself. */
     control?: {
         token: string;
         prefix: string;
     };
-    /** Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the plane,
-     *  once the port is known. Optional: an embedder mounted inside a larger app has no port of its
-     *  own to describe and uses {@link AgentService.control} instead.
-     *
-     *  Removed by `close()`. Not by an `exit` handler: installing one is a decision about the whole
-     *  process, which a mounted library does not get to make. A hard exit therefore leaves the file
-     *  behind — advisory, overwritten by the next boot, and the client's own error stays honest. */
-    announce(boundPort: number): void;
     /** Stop long connections and schedules. Idempotent; also runs when `options.signal` aborts. */
     close(): Promise<void>;
 }
@@ -112,12 +118,6 @@ export interface MountAgentServiceOptions {
      *  must get the SAME one, which is why this is a hook rather than the caller's own call. `dev`
      *  passes `logAgentLoop`. */
     wrapAgent?: (agent: Agent) => Agent;
-    /** Passed through to the control plane mount: `--tunnel` widens its warning, `host` names the
-     *  bind address in the discovery file. */
-    control?: {
-        tunnel?: boolean;
-        host?: string;
-    };
     /** Aborting this closes the service, exactly like calling {@link AgentService.close}. */
     signal?: AbortSignal;
     /** Called when a long connection ends on its own — a dropped socket-mode channel, say. The CLI