@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/schedule/wake-alarm.js

@@ -1,28 +1,11 @@
 /**
- * Wake ALARMS for the AgentCore deployment: the piece that makes the agent's self-scheduled
- * wake-ups (`wake`) reliable on a host with NO resident process. The mechanism, end to end:
- *
- *   wake written → wakeups store save → the SINK here → POST the full pending set to the
- *   forwarder's reserved path → the forwarder (which has the AWS SDK + an IAM role) mirrors each
- *   pending wake-up into a ONE-SHOT EventBridge schedule (`at(fireAt)`, self-deleting) → at the
- *   instant, EventBridge pokes the forwarder → InvokeAgentRuntime wakes the container → the boot /
- *   30s wake pump finds the due entry and fires it (the existing overdue catch-up — no new fire
- *   path). A RECURRING wake re-arms itself: its claim advances `fireAt` in the store, which is a
- *   save, which re-runs this sink, which re-upserts its alarm for the next occurrence.
- *
- * The container itself never calls AWS (no SDK dependency, no SigV4, no credential chain): it only
- * POSTs to its own deployment's public forwarder URL, authenticated by a shared secret
- * (`FASTAGENT_WAKE_SECRET`, a CloudFormation NoEcho parameter both sides receive). The URL is not
- * baked anywhere — the forwarder INJECTS it into every envelope it forwards (it resolves its own
- * 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 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.
+ * Wake ALARMS for the AgentCore deployment: the piece that makes the agent's self-scheduled wake-ups (`wake`) reliable
+ * on a host with NO resident process.
  */
 import { readFileSync } from "node:fs";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import { PortFailure, portError, portJoin, portRequest } from "../effect-port.js";
 import { RESERVED_PATHS } from "../channels/agentcore-protocol.js";
 import { beginWork } from "../channels/busy.js";
 import { log } from "../log.js";
@@ -30,10 +13,8 @@ import { scheduleFile, writeScheduleFile } from "./state.js";
 import { listWakeups } from "./wakeups.js";
 const URL_FILE = "wake-alarm-url";
 /**
- * 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
- * container whose FIRST action is a wake fire (recurring advance → save → sink) knows the URL
- * before any envelope of its own has arrived.
+ * Persist the forwarder URL the adapter saw in an envelope (write-if-changed — envelopes arrive on every turn, the
+ * file should not churn).
  */
 export function rememberWakeAlarmUrl(stateRoot, url) {
     if (readWakeAlarmUrl(stateRoot) === url)
@@ -44,21 +25,24 @@ export function rememberWakeAlarmUrl(stateRoot, url) {
 export function readWakeAlarmUrl(stateRoot) {
     try {
         const v = JSON.parse(readFileSync(scheduleFile(stateRoot, URL_FILE), "utf8"));
-        return typeof v.url === "string" ? v.url : undefined;
+        if (typeof v?.url !== "string" || v.url === "")
+            throw new Error("expected a nonempty url string");
+        return v.url;
     }
-    catch {
-        return undefined; // absent/corrupt — the next envelope rewrites it
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw new Error(`wake-alarm URL ${scheduleFile(stateRoot, URL_FILE)} is unreadable: ${String(cause)}`, { cause });
     }
 }
-/** How many times one alarm sync is retried before giving up (each store mutation and every boot
- *  restart the cycle, and the pending store is the durable desired state — so "give up" means "until
- *  the next mirror", never "lost"). */
+/**
+ * How many times one alarm sync is retried before giving up (each store mutation and every boot restart the cycle, and
+ * the pending store is the durable desired state — so "give up" means "until the next mirror", never "lost").
+ */
 export const MAX_SYNC_ATTEMPTS = 5;
 const RETRY_BASE_MS = 2_000;
 const SYNC_TIMEOUT_MS = 10_000;
-/** Alarms due within this margin are NOT mirrored: the box is awake handling them right now (that is
- *  how their fireAt got written/claimed), and a past `at()` would only fail at the Scheduler API —
- *  filtering them client-side keeps every forwarder failure a REAL one worth retrying. */
+/** Alarms due within this margin are NOT mirrored. */
 const DUE_MARGIN_MS = 5_000;
 /** Pending wake-ups → the desired alarm set, minus already-due entries (see {@link DUE_MARGIN_MS}). */
 export function toAlarms(pending, now) {
@@ -67,83 +51,72 @@ export function toAlarms(pending, now) {
         .map((w) => ({ id: w.id, at: w.fireAt }));
 }
 /**
- * Build the wakeups sink for an AgentCore deployment (registered via `setWakeupsSink` by `start`
- * 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.
+ * Build the wakeups sink for an AgentCore deployment (registered via `setWakeupsSink` by `start` when
+ * `FASTAGENT_AGENTCORE=1` + `FASTAGENT_WAKE_SECRET` are present).
  */
 export function createWakeAlarmSink(options) {
-    const { secret, fetchImpl = fetch, now = () => new Date() } = options;
-    const delay = options.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-    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),
+    return Effect.gen(function* () {
+        const clock = yield* Clock.Clock;
+        const fork = Effect.runForkWith(yield* Effect.context());
+        const { secret, fetchImpl = fetch, now = () => new Date(clock.currentTimeMillisUnsafe()), delay: pause } = options;
+        const delay = (ms) => (pause ? portJoin(() => pause(ms)) : Effect.sleep(ms));
+        let running = false;
+        let dirty = false;
+        /** One POST of the CURRENT desired set. */
+        const attemptOnce = (stateRoot, attempt) => Effect.gen(function* () {
+            const alarms = yield* Effect.try({
+                try: () => toAlarms(listWakeups(stateRoot), now()),
+                catch: (cause) => new PortFailure(cause),
             });
-            if (res.ok)
+            // Nothing future to mirror: converged.
+            if (alarms.length === 0)
                 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 {
+            const url = yield* Effect.try({
+                try: () => readWakeAlarmUrl(stateRoot),
+                catch: (cause) => new PortFailure(cause),
+            });
+            if (!url) {
+                log.warn("[schedule] wake alarm skipped — forwarder URL not seen yet");
+                return true;
+            }
+            const body = { secret, alarms };
+            return yield* portRequest(async (signal) => {
+                const res = await fetchImpl(`${url.replace(/\/$/, "")}${RESERVED_PATHS.wakeAlarm}`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(body),
+                    signal,
+                });
+                return res;
+            }, SYNC_TIMEOUT_MS).pipe(Effect.match({
+                onSuccess: (res) => {
+                    if (res.ok)
+                        return true;
+                    log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: HTTP ${res.status}`);
+                    return false;
+                },
+                onFailure: (error) => {
+                    log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: ${String(error.cause)}`);
+                    return false;
+                },
+            }));
+        });
+        const reconcile = (stateRoot) => Effect.gen(function* () {
+            // Consecutive failures ACROSS passes, not within one.
+            let failures = 0;
             while (dirty && failures < MAX_SYNC_ATTEMPTS) {
                 dirty = false;
                 for (let attempt = 1; attempt <= MAX_SYNC_ATTEMPTS; attempt++) {
-                    if (await attemptOnce(stateRoot, attempt)) {
+                    if (yield* 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.
+                    yield* 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.
                     if (dirty)
                         break;
                 }
@@ -152,26 +125,23 @@ export function createWakeAlarmSink(options) {
                 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();
-        }
-    }
-    // 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;
-        running = true;
-        void reconcile(stateRoot);
-    };
+        });
+        // 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;
+            running = true;
+            fork(Effect.acquireUseRelease(Effect.sync(beginWork), () => 
+            // Claim notification precedes scheduler admission; retain busy ownership through that handoff.
+            Effect.yieldNow.pipe(Effect.andThen(reconcile(stateRoot)), Effect.catchCause((cause) => Effect.sync(() => {
+                // Store/clock faults cannot be repaired by another POST. A new mutation may retry the mirror.
+                log.error(`[schedule] wake alarm reconcile failed (alarms are stale until the next store change): ${String(portError(cause))}`);
+            }))), (done) => Effect.sync(() => {
+                running = false;
+                done();
+            })));
+        };
+    });
 }

package/dist/schedule/wakeups.d.ts

@@ -4,30 +4,27 @@ export interface Wakeup {
     session: string;
     /** The instruction for the woken turn. */
     prompt: string;
-    /** When to fire next (ISO). For a recurring wake this advances to the next cron instant on each fire. */
+    /** When to fire next (ISO). */
     fireAt: string;
-    /** RECURRING: the cron expression (5-field). Absent = one-shot (fires once, removed). */
+    /** RECURRING: the cron expression (5-field). */
     cron?: string;
     /** IANA timezone for `cron` (default UTC). */
     tz?: string;
-    /** ONE-SHOT ONLY: consecutive busy-defer attempts. A one-shot into a BUSY session (`code: session_busy`
-     *  — the turn never started) is deferred, bounded by {@link MAX_WAKE_ATTEMPTS}, then dropped. A RECURRING
-     *  occurrence never defers (this field never increments for it): a busy one is skipped on FIRST contact
-     *  — its claim already advanced the entry, and the next occurrence comes by definition. */
+    /** ONE-SHOT ONLY: consecutive busy-defer attempts. */
     attempts?: number;
 }
 /** The minimum delay a wake-up may be scheduled for — rejects a busy-loop (`wake in 1s`, then again…). */
 export declare const MIN_WAKE_MS = 60000;
-/** The cap on pending wake-ups PER SESSION — rejects one conversation's unbounded self-fan-out without
- *  letting it starve others' quota (a global cap would make one chatty session a DoS on everyone else's
- *  `wake`, since a multi-user deploy is one session per chat). */
+/**
+ * The cap on pending wake-ups PER SESSION — rejects one conversation's unbounded self-fan-out without letting it
+ * starve others' quota (a global cap would make one chatty session a DoS on everyone else's `wake`, since a multi-user
+ * deploy is one session per chat).
+ */
 export declare const MAX_PENDING_WAKEUPS = 20;
-/** How many times a busy/transient wake is retried (deferred) before being dropped. At the ~30s poll a
- *  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). */
+/** How many times a busy/transient wake is retried (deferred) before being dropped. */
 export declare const MAX_WAKE_ATTEMPTS = 120;
 export declare function setWakeupsSink(sink: ((stateRoot: string) => void) | undefined): void;
-/** The current pending wake-ups (`fastagent schedule list` uses this). */
+/** The current pending wake-ups — read by the wake-alarm sink, which mirrors them into an external clock. */
 export declare function listWakeups(stateRoot: string): Wakeup[];
 export type AddWakeupResult = {
     ok: true;
@@ -37,12 +34,7 @@ export type AddWakeupResult = {
     ok: false;
     error: string;
 };
-/**
- * Add a wake-up — one-shot (`fireAt`) or recurring (`cron`/`tz`, `fireAt` = the first instant) —
- * enforcing the guardrails (min delay / min recurring gap, per-session pending cap). Returns a
- * MODEL-facing error string on rejection (the `wake` tool passes it back so the model can adjust),
- * never throws for a bad request.
- */
+/** Add a wake-up — one-shot (`fireAt`) or recurring (`cron`/`tz`, `fireAt` = the first instant). */
 export declare function addWakeup(stateRoot: string, input: {
     session: string;
     prompt: string;
@@ -51,30 +43,22 @@ export declare function addWakeup(stateRoot: string, input: {
     tz?: string;
 }, now?: Date): AddWakeupResult;
 /**
- * Remove a wake-up by id. `session` (when given — the agent's `unwake`) must ALSO match, so a
- * conversation can only cancel its OWN wake-ups; the operator's `schedule cancel` passes none.
- * Returns whether anything was removed.
+ * Remove ONE pending wake-up, and only from the session that made it.
+ *
+ * SESSION-SCOPED WITH NO WAY AROUND IT, because `unwake` is the only caller: an agent cancels its own alarm, and
+ * cancelling another conversation's silently is a cost with no matching benefit. There is no operator command: a
+ * wake-up only fires while a serve is running, and a running serve is one whose
+ * session can be spoken to (`POST /invoke`, the control plane's `follow_up`, or the chat thread it lives in), so
+ * "the alarm is loose" and "the agent is unreachable" cannot both be true. The last resort is editing
+ * `<stateRoot>/schedule/wakeups.json`, which needs no command.
  */
-export declare function removeWakeup(stateRoot: string, id: string, session?: string): boolean;
+export declare function removeWakeup(stateRoot: string, id: string, session: string): boolean;
 /**
- * CLAIM the FIRST due wake-up (at or before `now`) in stored order, remove + return it, or undefined if
- * none is due. Stored order, not earliest-`fireAt`: the caller drains them all in one poll, so order among
- * due entries doesn't matter. One at a time on purpose — the caller fires it before claiming the next, so a
- * crash loses AT MOST one wake-up (claiming a whole due batch up front would lose the lot). Claim-before-fire
- * = a turn EXECUTES at most once per claim; a wake that couldn't start (busy session) is re-claimed via
- * {@link deferWakeup}.
+ * CLAIM the FIRST due wake-up (at or before `now`) in stored order, remove + return it, or undefined if none is due.
  */
 export declare function takeFirstDueWakeup(stateRoot: string, now?: Date): Wakeup | undefined;
 /**
- * Re-schedule a ONE-SHOT wake whose fire failed TRANSIENTLY (its session was busy — a channel is mid-turn
- * on it), deferred to `fireAt`. Returns false (dropped, NOT re-added) once attempts exceed
- * {@link MAX_WAKE_ATTEMPTS} — a one-shot has no "next time", so a busy-skip that just dropped it would lose
- * it forever; bounded retries, then give up visibly. A RECURRING occurrence is never deferred: its claim
- * already advanced the entry, and its next occurrence comes by definition — a busy one is skipped + audited.
- *
- * Known residual: between the claim (removed from the store) and this re-add there is a microtask-scale
- * window (the busy reject yields before any engine IO) where an `unwake` for this id reports "not found"
- * and the defer then resurrects it — the one-shot cousin of the recurring resurrection the advance-in-place
- * claim eliminated. Accepted: closing it needs a claim-lease with expiry, disproportionate to the window.
+ * Re-schedule a ONE-SHOT wake whose fire failed TRANSIENTLY (its session was busy — a channel is mid-turn on it),
+ * deferred to `fireAt`.
  */
 export declare function deferWakeup(stateRoot: string, w: Wakeup, fireAt: Date): boolean;

package/dist/schedule/wakeups.js

@@ -1,14 +1,6 @@
 /**
- * The agent's self-scheduled wake-ups — the SECOND producer of scheduled invocations (the first is the
- * author's `schedules/` files). The `wake` tool writes one here; the scheduler polls and fires it back
- * into the SAME session so the agent resumes the conversation it was in. Persisted
- * (`<stateRoot>/schedule/wakeups.json`) so a wake survives a restart. ONE-SHOT (`in`) or RECURRING
- * (`cron` — the entry keeps its id; each fire re-arms `fireAt` to the next cron instant).
- *
- * Guardrails (self-scheduling is a real runaway surface): a minimum one-shot delay (no busy-looping), a
- * minimum RECURRING gap (a high-frequency recurring burns tokens forever — stricter than one-shot), a
- * per-session pending cap (no fan-out, no cross-session quota DoS; a recurring occupies a slot for its
- * whole life), and the agent's `unwake` / the operator's `schedule cancel` as the kill switches.
+ * The agent's self-scheduled wake-ups — the SECOND producer of scheduled invocations (the first is the author's
+ * `routines/` files).
  */
 import { randomUUID } from "node:crypto";
 import { log } from "../log.js";
@@ -16,20 +8,17 @@ import { cronError, nextRun } from "./cron.js";
 import { readScheduleFile, scheduleFile, writeScheduleFile } from "./state.js";
 /** The minimum delay a wake-up may be scheduled for — rejects a busy-loop (`wake in 1s`, then again…). */
 export const MIN_WAKE_MS = 60_000; // 1 minute
-/** The cap on pending wake-ups PER SESSION — rejects one conversation's unbounded self-fan-out without
- *  letting it starve others' quota (a global cap would make one chatty session a DoS on everyone else's
- *  `wake`, since a multi-user deploy is one session per chat). */
+/**
+ * The cap on pending wake-ups PER SESSION — rejects one conversation's unbounded self-fan-out without letting it
+ * starve others' quota (a global cap would make one chatty session a DoS on everyone else's `wake`, since a multi-user
+ * deploy is one session per chat).
+ */
 export const MAX_PENDING_WAKEUPS = 20;
-/** How many times a busy/transient wake is retried (deferred) before being dropped. At the ~30s poll a
- *  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). */
+/** How many times a busy/transient wake is retried (deferred) before being dropped. */
 export const MAX_WAKE_ATTEMPTS = 120;
-/** The minimum gap between two consecutive fires of a RECURRING wake — stricter than the one-shot floor:
- *  a recurring runs forever, so a tight cron is a permanent token burner, not a one-time mistake. */
+/** The minimum gap between two consecutive fires of a RECURRING wake. */
 const MIN_RECURRING_GAP_MS = 10 * 60_000; // 10 minutes
-/** A stored entry is a real Wakeup: the fields are present and `fireAt` is a parseable date. A malformed
- *  one (bad/missing fireAt) would compare NaN <= now = false forever — never due, never cleared, but still
- *  eating the pending quota. So validate at this IO boundary and drop it (warn), like a corrupt file. */
+/** A stored entry is a real Wakeup: the fields are present and `fireAt` is a parseable date. */
 function isWakeup(e) {
     if (!e || typeof e !== "object")
         return false;
@@ -41,23 +30,11 @@ function isWakeup(e) {
         !Number.isNaN(Date.parse(w.fireAt)) &&
         (w.attempts === undefined || typeof w.attempts === "number") && // a non-number would make deferWakeup's count NaN
         (w.tz === undefined || typeof w.tz === "string") &&
-        // A stored cron must PARSE: a bad one would throw inside the claim's nextRun — before the advance-save
-        // — so its fireAt never moves, it stays first-due forever, and every wakeup behind it starves (a poison
-        // pill worse than the bad-fireAt zombie this validator already guards).
+        // A stored cron must PARSE: a bad one would throw inside the claim's nextRun.
         (w.cron === undefined ||
             (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. 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.
- */
+/** The wake-ALARM sink: notified after EVERY wakeups-store mutation. */
 let wakeupsSink;
 export function setWakeupsSink(sink) {
     wakeupsSink = sink;
@@ -67,8 +44,7 @@ function load(stateRoot) {
     if (v === undefined)
         return []; // absent (first run) or a corrupt file readScheduleFile already warned on
     if (!Array.isArray(v)) {
-        // Valid JSON but the wrong SHAPE (an object, say) — fail-visible, don't silently drop the whole store
-        // (a per-entry malformed drop already warns; a whole-store shape error must too).
+        // Valid JSON but the wrong SHAPE (an object, say).
         log.warn(`[schedule] wakeups store is not an array — ignoring it: ${JSON.stringify(v).slice(0, 80)}`);
         return [];
     }
@@ -90,25 +66,19 @@ function save(stateRoot, wakeups) {
         log.error(`[schedule] wake-alarm sink failed (store write is unaffected): ${String(e)}`);
     }
 }
-/** The current pending wake-ups (`fastagent schedule list` uses this). */
+/** The current pending wake-ups — read by the wake-alarm sink, which mirrors them into an external clock. */
 export function listWakeups(stateRoot) {
     return load(stateRoot);
 }
-/**
- * Add a wake-up — one-shot (`fireAt`) or recurring (`cron`/`tz`, `fireAt` = the first instant) —
- * enforcing the guardrails (min delay / min recurring gap, per-session pending cap). Returns a
- * MODEL-facing error string on rejection (the `wake` tool passes it back so the model can adjust),
- * never throws for a bad request.
- */
+/** Add a wake-up — one-shot (`fireAt`) or recurring (`cron`/`tz`, `fireAt` = the first instant). */
 export function addWakeup(stateRoot, input, now = new Date()) {
     let fireAtDate;
     if (input.cron !== undefined) {
         const err = cronError(input.cron, input.tz);
         if (err)
             return { ok: false, error: `invalid cron/tz: ${err}` };
-        // A recurring wake runs FOREVER — gate its frequency harder than a one-shot: the gap between the next
-        // two instants must be ≥ the recurring floor. (First-pair heuristic; an irregular cron with one tight
-        // pair can slip through — an accepted ceiling, the per-session cap still bounds total load.)
+        // A recurring wake runs FOREVER — gate its frequency harder than a one-shot: the gap between the next two
+        // instants must be ≥ the recurring floor.
         const first = nextRun(input.cron, input.tz, now);
         const second = first && nextRun(input.cron, input.tz, first);
         if (!first || !second)
@@ -132,9 +102,8 @@ export function addWakeup(stateRoot, input, now = new Date()) {
     const all = load(stateRoot);
     const mine = all.filter((w) => w.session === input.session);
     if (mine.length >= MAX_PENDING_WAKEUPS) {
-        // List what's pending WITH a prompt preview: "unwake one" is only actionable if the model has the
-        // ids AND can choose by meaning — both were returned when set, but that may be buried far back in
-        // the conversation.
+        // List what's pending WITH a prompt preview: "unwake one" is only actionable if the model has the ids AND can
+        // choose by meaning.
         const pending = mine
             .map((w) => `${w.id}${w.cron ? ` (recurring "${w.cron}")` : ""} at ${w.fireAt}: ${w.prompt.length > 60 ? `${w.prompt.slice(0, 60)}…` : w.prompt}`)
             .join("; ");
@@ -152,25 +121,25 @@ export function addWakeup(stateRoot, input, now = new Date()) {
     return { ok: true, id, fireAt };
 }
 /**
- * Remove a wake-up by id. `session` (when given — the agent's `unwake`) must ALSO match, so a
- * conversation can only cancel its OWN wake-ups; the operator's `schedule cancel` passes none.
- * Returns whether anything was removed.
+ * Remove ONE pending wake-up, and only from the session that made it.
+ *
+ * SESSION-SCOPED WITH NO WAY AROUND IT, because `unwake` is the only caller: an agent cancels its own alarm, and
+ * cancelling another conversation's silently is a cost with no matching benefit. There is no operator command: a
+ * wake-up only fires while a serve is running, and a running serve is one whose
+ * session can be spoken to (`POST /invoke`, the control plane's `follow_up`, or the chat thread it lives in), so
+ * "the alarm is loose" and "the agent is unreachable" cannot both be true. The last resort is editing
+ * `<stateRoot>/schedule/wakeups.json`, which needs no command.
  */
 export function removeWakeup(stateRoot, id, session) {
     const all = load(stateRoot);
-    const kept = all.filter((w) => !(w.id === id && (session === undefined || w.session === session)));
+    const kept = all.filter((w) => !(w.id === id && w.session === session));
     if (kept.length === all.length)
         return false;
     save(stateRoot, kept);
     return true;
 }
 /**
- * CLAIM the FIRST due wake-up (at or before `now`) in stored order, remove + return it, or undefined if
- * none is due. Stored order, not earliest-`fireAt`: the caller drains them all in one poll, so order among
- * due entries doesn't matter. One at a time on purpose — the caller fires it before claiming the next, so a
- * crash loses AT MOST one wake-up (claiming a whole due batch up front would lose the lot). Claim-before-fire
- * = a turn EXECUTES at most once per claim; a wake that couldn't start (busy session) is re-claimed via
- * {@link deferWakeup}.
+ * CLAIM the FIRST due wake-up (at or before `now`) in stored order, remove + return it, or undefined if none is due.
  */
 export function takeFirstDueWakeup(stateRoot, now = new Date()) {
     const all = load(stateRoot);
@@ -179,11 +148,8 @@ export function takeFirstDueWakeup(stateRoot, now = new Date()) {
         return undefined;
     const w = all[idx];
     if (w.cron !== undefined) {
-        // RECURRING claim = ADVANCE IN PLACE: the entry STAYS in the store with fireAt pushed to the next cron
-        // instant (attempts cleared). So (a) `unwake`/`schedule cancel` work at ANY moment — including inside
-        // the woken turn itself, the documented way to stop a done recurring job (a remove+re-add claim would
-        // resurrect what that turn just cancelled); and (b) a crash mid-fire loses at most ONE occurrence,
-        // never the recurrence — matching the static cron schedules' claim semantics.
+        // RECURRING claim = ADVANCE IN PLACE: the entry STAYS in the store with fireAt pushed to the next cron instant
+        // (attempts cleared).
         const next = nextRun(w.cron, w.tz, now);
         if (next)
             all[idx] = { ...w, fireAt: next.toISOString(), attempts: undefined };
@@ -197,16 +163,8 @@ export function takeFirstDueWakeup(stateRoot, now = new Date()) {
     return w;
 }
 /**
- * Re-schedule a ONE-SHOT wake whose fire failed TRANSIENTLY (its session was busy — a channel is mid-turn
- * on it), deferred to `fireAt`. Returns false (dropped, NOT re-added) once attempts exceed
- * {@link MAX_WAKE_ATTEMPTS} — a one-shot has no "next time", so a busy-skip that just dropped it would lose
- * it forever; bounded retries, then give up visibly. A RECURRING occurrence is never deferred: its claim
- * already advanced the entry, and its next occurrence comes by definition — a busy one is skipped + audited.
- *
- * Known residual: between the claim (removed from the store) and this re-add there is a microtask-scale
- * window (the busy reject yields before any engine IO) where an `unwake` for this id reports "not found"
- * and the defer then resurrects it — the one-shot cousin of the recurring resurrection the advance-in-place
- * claim eliminated. Accepted: closing it needs a claim-lease with expiry, disproportionate to the window.
+ * Re-schedule a ONE-SHOT wake whose fire failed TRANSIENTLY (its session was busy — a channel is mid-turn on it),
+ * deferred to `fireAt`.
  */
 export function deferWakeup(stateRoot, w, fireAt) {
     const attempts = (w.attempts ?? 0) + 1;

package/dist/secrets-gate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * THE GATE: refuse to run while a declaration for what is ABOUT TO RUN has no value.
+ *
+ * `declared-secrets.ts` answers "which env vars did this code declare, and which have no value" —
+ * a predicate. This module owns the three decisions that turn that predicate into a refusal, for all five call
+ * sites (the agent opener, the scheduler start, channel loading, `fastagent tool`, `fastagent routine run`):
+ *
+ *  1. WHICH declarations gate this run. A serve mounts every tool, schedule and channel, so all of
+ *     them gate it; `fastagent tool <name>` / `fire <name>` run exactly one owner, and requiring the
+ *     credentials of the ones they are not running blocks a machine that is configured correctly for
+ *     the job at hand. That is why declarations travel keyed BY OWNER.
+ *  2. ORDER against load failures. The refusal throws, and a caller that prints `failures` after it
+ *     gets a value back would lose them: a broken `tools/x.ts` beside an unset declaration would
+ *     stay invisible until the author fixed the environment and ran again. So the gate reports them
+ *     itself, on the refusal path, before throwing. A caller that also reports on its own success
+ *     path is correct; one that reports before gating merely repeats a line, which is cosmetic —
+ *     the signal cannot be lost either way.
+ *  3. The failure SHAPE. This throws a plain `Error` (a user-fixable startup problem). CLI commands
+ *     whose call is synchronous route it through the process boundary with `gateSecretsOrExit`
+ *     (cli/fail.ts) so the author sees the one line naming the file, never a Node stack.
+ */
+import { type DeclaredSecret } from "./declared-secrets.ts";
+import { type ModuleLoadFailure } from "./loader.ts";
+export declare function gateSecrets(input: {
+    /** Owner (tool / schedule / channel name) → what it declared, as the loaders return it. */
+    declared: ReadonlyMap<string, readonly DeclaredSecret[]>;
+    /** What could not be loaded from the same directory — reported before any refusal (decision 2). */
+    failures: readonly ModuleLoadFailure[];
+    /** The ONE owner about to run; omitted means every one of them is about to run. */
+    owner?: string;
+    env?: NodeJS.ProcessEnv;
+}): void;

package/dist/secrets-gate.js

@@ -0,0 +1,33 @@
+/**
+ * THE GATE: refuse to run while a declaration for what is ABOUT TO RUN has no value.
+ *
+ * `declared-secrets.ts` answers "which env vars did this code declare, and which have no value" —
+ * a predicate. This module owns the three decisions that turn that predicate into a refusal, for all five call
+ * sites (the agent opener, the scheduler start, channel loading, `fastagent tool`, `fastagent routine run`):
+ *
+ *  1. WHICH declarations gate this run. A serve mounts every tool, schedule and channel, so all of
+ *     them gate it; `fastagent tool <name>` / `fire <name>` run exactly one owner, and requiring the
+ *     credentials of the ones they are not running blocks a machine that is configured correctly for
+ *     the job at hand. That is why declarations travel keyed BY OWNER.
+ *  2. ORDER against load failures. The refusal throws, and a caller that prints `failures` after it
+ *     gets a value back would lose them: a broken `tools/x.ts` beside an unset declaration would
+ *     stay invisible until the author fixed the environment and ran again. So the gate reports them
+ *     itself, on the refusal path, before throwing. A caller that also reports on its own success
+ *     path is correct; one that reports before gating merely repeats a line, which is cosmetic —
+ *     the signal cannot be lost either way.
+ *  3. The failure SHAPE. This throws a plain `Error` (a user-fixable startup problem). CLI commands
+ *     whose call is synchronous route it through the process boundary with `gateSecretsOrExit`
+ *     (cli/fail.ts) so the author sees the one line naming the file, never a Node stack.
+ */
+import { allSecrets, describeSecrets, missingSecrets } from "./declared-secrets.js";
+import { reportModuleLoadFailures } from "./loader.js";
+export function gateSecrets(input) {
+    const scope = input.owner === undefined ? allSecrets(input.declared) : (input.declared.get(input.owner) ?? []);
+    const missing = missingSecrets(scope, input.env);
+    if (missing.length === 0)
+        return;
+    reportModuleLoadFailures(input.failures);
+    throw new Error(`missing required secrets: ${describeSecrets(missing)} — set them in .secrets/.env (or the ` +
+        `environment). Deployed, they travel as deploy secrets; a tool that should run WITHOUT the ` +
+        `value must not declare it.`);
+}