@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/scaffold/vendor-skill.js

@@ -1,5 +1,5 @@
 /**
- * `fastagent add skill <source>`: vendor an Agent Skills skill into `<workspace>/skills/<name>/` —
+ * `fastagent add skill <source>`: vendor an Agent Skills skill into `<agent dir>/skills/<name>/` —
  * copy-in, git-tracked, never a runtime registry. Source is a giget ref (github default), a local
  * path, or a bare name (resolved against the local global skill dirs as an add-time copy source only).
  * Fetch → staging → validate → rollback-protected replace, so a bad fetch never destroys an existing
@@ -11,19 +11,19 @@ import { randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { loadAgentDefinition } from "../engines/pi/definition.js";
-import { assertInsideWorkspace } from "../workspace.js";
+import { assertInsideAgentDir } from "../paths.js";
 /** Derive the destination skill name from a source ref: the last path segment, sans `#ref`. */
 function skillNameFromSource(source) {
     const noRef = source.split("#")[0] ?? source;
     return basename(noRef.replace(/\/+$/, ""));
 }
 /**
- * The skills/ path must be safe to write through: never follow a symlink that escapes the workspace
+ * The skills/ path must be safe to write through: never follow a symlink that escapes the agent dir
  * (mkdir would), and reject a plain file with one clear message.
  */
-async function assertSkillsDirUsable(workspaceDir) {
-    await assertInsideWorkspace(workspaceDir, "skills");
-    const skillsDir = join(workspaceDir, "skills");
+async function assertSkillsDirUsable(agentDir) {
+    await assertInsideAgentDir(agentDir, "skills");
+    const skillsDir = join(agentDir, "skills");
     const st = await stat(skillsDir).catch(() => undefined);
     if (st && !st.isDirectory()) {
         throw new Error(`${skillsDir} exists and is not a directory — remove it (skills must be a directory)`);
@@ -47,19 +47,19 @@ function findGlobalSkillSource(name) {
     return undefined;
 }
 /**
- * Vendor an Agent Skills skill into `<workspace>/skills/<name>/` from a giget ref (github default), a
+ * Vendor an Agent Skills skill into `<agent dir>/skills/<name>/` from a giget ref (github default), a
  * local path, or a bare name (resolved against the local global skill dirs). Copy-in, git-tracked.
  * Refuses to overwrite unless `options.update` (then a plain git-tracked overwrite, never a merge).
  * Validates a staging copy with the runtime loader BEFORE replacing, so a bad fetch never destroys an
  * existing skill.
  */
-export async function vendorSkill(workspaceDir, source, options = {}) {
+export async function vendorSkill(agentDir, source, options = {}) {
     const name = skillNameFromSource(source);
     if (name === "" || name === "." || name === "..") {
         throw new Error(`cannot derive a skill name from "${source}" — point at a skill directory (…/skills/<name>)`);
     }
-    const skillsDir = join(workspaceDir, "skills");
-    await assertSkillsDirUsable(workspaceDir);
+    const skillsDir = join(agentDir, "skills");
+    await assertSkillsDirUsable(agentDir);
     const dest = join(skillsDir, name);
     // A process can die between moving the old skill aside and installing staging. Never guess that an
     // arbitrary hidden directory is ours or delete it: stop with the exact backup path for manual restore.
@@ -143,15 +143,15 @@ export async function vendorSkill(workspaceDir, source, options = {}) {
         await rm(previous, { recursive: true, force: true });
     // Report via the runtime loader, matching THIS skill by EXACT directory (a substring match would
     // prefix-pollute a sibling `<name>-x` and break on Windows path separators).
-    const def = await loadAgentDefinition(workspaceDir);
+    const def = await loadAgentDefinition(agentDir);
     const rel = join("skills", name);
-    const skill = def.skills.find((sk) => relative(workspaceDir, dirname(sk.filePath)) === rel);
+    const skill = def.skills.find((sk) => relative(agentDir, dirname(sk.filePath)) === rel);
     return {
         name: skill?.name ?? name,
         description: skill?.description,
         dest: rel,
         hasScripts: existsSync(join(dest, "scripts")),
-        diagnostics: def.diagnostics.filter((d) => d.path !== undefined && relative(workspaceDir, dirname(d.path)) === rel),
+        diagnostics: def.diagnostics.filter((d) => d.path !== undefined && relative(agentDir, dirname(d.path)) === rel),
         overwritten,
     };
 }

package/dist/schedule/discover.js

@@ -1,5 +1,5 @@
 /**
- * Schedule discovery (the N axis, clock form): a workspace declares its time-triggers by dropping files
+ * Schedule discovery (the N axis, clock form): an agent declares its time-triggers by dropping files
  * in `schedules/`, mirroring `tools/` and `channels/`. Each file default-exports `defineSchedule({...})`,
  * 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.
@@ -7,13 +7,13 @@
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { isModuleFile, loadModuleDir } from "../loader.js";
-import { assertInsideWorkspace } from "../workspace.js";
+import { assertInsideAgentDir } from "../paths.js";
 import { cronError } from "./cron.js";
 /** Schedule file basenames under `<dir>/schedules/` — an existence probe listed WITHOUT importing
  *  (deploy pre-flight's time-trigger detection; `fastagent info` uses {@link loadSchedules} instead,
  *  since it also reports broken files and next instants). */
 export async function discoverScheduleFiles(dir) {
-    await assertInsideWorkspace(dir, "schedules");
+    await assertInsideAgentDir(dir, "schedules");
     let names;
     try {
         names = await readdir(join(dir, "schedules"));
@@ -36,7 +36,7 @@ export async function discoverScheduleFiles(dir) {
  * reports the rest.
  */
 export async function loadSchedules(dir) {
-    await assertInsideWorkspace(dir, "schedules");
+    await assertInsideAgentDir(dir, "schedules");
     const { modules, failures } = await loadModuleDir(join(dir, "schedules"));
     const byName = new Map();
     for (const { name, label, file, mod } of modules) {

package/dist/schedule/scheduler.d.ts

@@ -32,5 +32,44 @@ export interface SchedulerOptions {
     schedules: LoadedSchedule[];
     /** Injectable clock for tests; defaults to the wall clock. */
     now?: () => Date;
+    /** External-clock mode (the AgentCore deployment): cron slots are DELIVERED by an external
+     *  scheduler through the serving surface ({@link fireScheduleOnce} with a `slot`), so `start()`
+     *  arms NO cron timers and does NO boot catch-up — delivery, including for instants that passed
+     *  while this process was down, is the external clock's job; the adapter's slot-idempotent claim
+     *  is the duplicate guard. The wake-up poll still runs (degraded: it only fires while the
+     *  process happens to be awake — the deploy path warns about this). */
+    externalClock?: boolean;
 }
-export declare function createScheduler({ agent, stateRoot, schedules, now }: SchedulerOptions): Scheduler;
+/** One schedule fire's outcome, for the external caller (the AgentCore adapter returns it to the
+ *  triggering clock's logs). The resident scheduler ignores it beyond completion. */
+export interface ScheduleFireOutcome {
+    fired: boolean;
+    /** Set when a slot-keyed fire was skipped because that slot (or a later one) was already claimed. */
+    skippedReason?: string;
+    failed?: string;
+    ms: number;
+}
+/**
+ * Fire ONE schedule's turn: claim (persist lastFired BEFORE invoking, so a crash mid-turn does not
+ * re-fire on restart), run, audit. Shared by the resident scheduler's timers and the external-clock
+ * serving surface (the AgentCore adapter).
+ *
+ * `slot` is the external clock's idempotency key — the cron instant this fire is FOR. External
+ * delivery (EventBridge-style) is at-least-once, so a duplicate slot must not double-fire: when
+ * lastFired ≥ slot the fire is SKIPPED (at-most-once per slot, same trade as the resident claim —
+ * "a digest late once" beats "twice"). The resident scheduler omits `slot`: its timers fire each
+ * slot exactly once, so the unconditional claim is already correct.
+ *
+ * A state fault while claiming (loadFires/saveFires — both before the invoke, so nothing ran)
+ * THROWS: the resident path catches it at its single skip+audit boundary ({@link createScheduler}'s
+ * fireThenReArm — skipping rather than firing unclaimed also avoids an infinite catch-up loop on
+ * restart), and the external path lets it surface as a failed request (visible in the clock's logs).
+ */
+export declare function fireScheduleOnce(opts: {
+    agent: Agent;
+    stateRoot: string;
+    schedule: LoadedSchedule;
+    slot?: Date;
+    now?: () => Date;
+}): Promise<ScheduleFireOutcome>;
+export declare function createScheduler({ agent, stateRoot, schedules, now, externalClock, }: SchedulerOptions): Scheduler;

package/dist/schedule/scheduler.js

@@ -13,6 +13,7 @@
  *    "a digest late once" beats "twice"). Strict at-least-once (a per-turn WAL) is a later tier.
  */
 import { SESSION_BUSY_CODE } from "../agent.js";
+import { beginWork } from "../channels/busy.js";
 import { log } from "../log.js";
 import { appendRun } from "./audit.js";
 import { nextRun } from "./cron.js";
@@ -29,63 +30,89 @@ const MAX_WAIT_MS = 6 * 60 * 60 * 1000; // 6h
 // How often to poll the agent's self-scheduled wake-ups (wakeups.ts). A wake fires within this of its
 // due time — fine for "wake me in N minutes"; cheap (reads a small JSON, writes only when one is due).
 const WAKEUP_POLL_MS = 30 * 1000;
-export function createScheduler({ agent, stateRoot, schedules, now = () => new Date() }) {
-    const timers = new Map();
-    let wakeupTimer;
-    let stopped = false;
-    /** Drive ONE turn (a cron fire or a wake-up) and log its outcome. Total — never throws (its callers are
-     *  void-scheduled). Output is the agent's tools' job; this only fires and logs. Returns the turn's audit
-     *  material — `failed` (details, if it failed), the accumulated `reply` text, `ms` — plus `busy`: whether
-     *  it failed specifically because the session was BUSY (the turn never started) — the ONLY replay-safe
-     *  reason to re-fire a wake-up; every other outcome is terminal (side effects may have run). */
-    async function runTurn(label, session, prompt) {
-        const startedAt = Date.now();
-        log.info(`[schedule] ${label} firing (session=${session})`);
-        try {
-            let failed;
-            let busy = false;
-            let reply = "";
-            for await (const e of agent.invoke({ session }, { text: prompt })) {
-                if (e.type === "text")
-                    reply += e.delta;
-                if (e.type === "failed") {
-                    failed = e.details;
-                    busy = e.code === SESSION_BUSY_CODE; // structured (SPEC §8), not a details-text match
-                }
+/** Drive ONE turn (a cron fire or a wake-up) and log its outcome. Total — never throws (its callers are
+ *  void-scheduled). Output is the agent's tools' job; this only fires and logs. Returns the turn's audit
+ *  material — `failed` (details, if it failed), the accumulated `reply` text, `ms` — plus `busy`: whether
+ *  it failed specifically because the session was BUSY (the turn never started) — the ONLY replay-safe
+ *  reason to re-fire a wake-up; every other outcome is terminal (side effects may have run). Module-level
+ *  (not a scheduler closure) so {@link fireScheduleOnce} — the external-clock fire path — shares it. */
+async function runTurn(agent, label, session, prompt) {
+    const startedAt = Date.now();
+    log.info(`[schedule] ${label} firing (session=${session})`);
+    try {
+        let failed;
+        let busy = false;
+        let reply = "";
+        for await (const e of agent.invoke({ session }, { text: prompt })) {
+            if (e.type === "text")
+                reply += e.delta;
+            if (e.type === "failed") {
+                failed = e.details;
+                busy = e.code === SESSION_BUSY_CODE; // structured (SPEC §8), not a details-text match
             }
-            if (failed)
-                log.error(`[schedule] ${label} failed (${Date.now() - startedAt}ms): ${failed}`);
-            else
-                log.info(`[schedule] ${label} completed (${Date.now() - startedAt}ms)`);
-            return { busy: failed !== undefined && busy, failed, reply, ms: Date.now() - startedAt };
-        }
-        catch (e) {
-            // invoke shouldn't throw (SPEC MUST 2 turns failures into events), but stay total regardless. A throw
-            // is not the busy case, so don't defer on it.
-            log.error(`[schedule] ${label} errored (${Date.now() - startedAt}ms): ${String(e)}`);
-            return { busy: false, failed: String(e), reply: "", ms: Date.now() - startedAt };
         }
+        if (failed)
+            log.error(`[schedule] ${label} failed (${Date.now() - startedAt}ms): ${failed}`);
+        else
+            log.info(`[schedule] ${label} completed (${Date.now() - startedAt}ms)`);
+        return { busy: failed !== undefined && busy, failed, reply, ms: Date.now() - startedAt };
     }
-    /** Fire one schedule's turn: claim the slot (persist lastFired BEFORE invoking) so a crash mid-turn
-     *  does not re-fire this slot on restart, then run the turn. A state fault while claiming (loadFires or
-     *  saveFires — both before the invoke, so nothing ran) THROWS to the single skip+audit boundary in
-     *  {@link fireThenReArm}; skipping rather than firing unclaimed also avoids an infinite catch-up loop
-     *  on restart. */
+    catch (e) {
+        // invoke shouldn't throw (SPEC MUST 2 turns failures into events), but stay total regardless. A throw
+        // is not the busy case, so don't defer on it.
+        log.error(`[schedule] ${label} errored (${Date.now() - startedAt}ms): ${String(e)}`);
+        return { busy: false, failed: String(e), reply: "", ms: Date.now() - startedAt };
+    }
+}
+/**
+ * Fire ONE schedule's turn: claim (persist lastFired BEFORE invoking, so a crash mid-turn does not
+ * re-fire on restart), run, audit. Shared by the resident scheduler's timers and the external-clock
+ * serving surface (the AgentCore adapter).
+ *
+ * `slot` is the external clock's idempotency key — the cron instant this fire is FOR. External
+ * delivery (EventBridge-style) is at-least-once, so a duplicate slot must not double-fire: when
+ * lastFired ≥ slot the fire is SKIPPED (at-most-once per slot, same trade as the resident claim —
+ * "a digest late once" beats "twice"). The resident scheduler omits `slot`: its timers fire each
+ * slot exactly once, so the unconditional claim is already correct.
+ *
+ * A state fault while claiming (loadFires/saveFires — both before the invoke, so nothing ran)
+ * THROWS: the resident path catches it at its single skip+audit boundary ({@link createScheduler}'s
+ * fireThenReArm — skipping rather than firing unclaimed also avoids an infinite catch-up loop on
+ * restart), and the external path lets it surface as a failed request (visible in the clock's logs).
+ */
+export async function fireScheduleOnce(opts) {
+    const { agent, stateRoot, schedule: s, slot, now = () => new Date() } = opts;
+    const fires = loadFires(stateRoot);
+    const last = fires[s.name];
+    if (slot && last && new Date(last).getTime() >= slot.getTime()) {
+        const reason = `slot ${slot.toISOString()} already fired (lastFired=${last})`;
+        log.info(`[schedule] ${s.name}: skipping — ${reason}`);
+        return { fired: false, skippedReason: reason, ms: 0 };
+    }
+    // An external delivery claims the cron instant it represents, not its (possibly much later)
+    // delivery time. Otherwise a delayed fire can make the next distinct slot look like a duplicate.
+    fires[s.name] = (slot ?? now()).toISOString();
+    saveFires(stateRoot, fires);
+    const firedAt = now().toISOString();
+    const r = await runTurn(agent, s.name, scheduleSession(s.name), s.prompt);
+    appendRun(stateRoot, {
+        name: s.name,
+        session: scheduleSession(s.name),
+        firedAt,
+        ms: r.ms,
+        outcome: r.failed ? "failed" : "completed",
+        reply: r.failed ? undefined : r.reply,
+        error: r.failed,
+    });
+    return { fired: true, failed: r.failed, ms: r.ms };
+}
+export function createScheduler({ agent, stateRoot, schedules, now = () => new Date(), externalClock = false, }) {
+    const timers = new Map();
+    let wakeupTimer;
+    let stopped = false;
+    /** The resident fire path — the shared claim+run+audit, without a slot (see {@link fireScheduleOnce}). */
     async function fire(s) {
-        const fires = loadFires(stateRoot);
-        fires[s.name] = now().toISOString();
-        saveFires(stateRoot, fires);
-        const firedAt = now().toISOString();
-        const r = await runTurn(s.name, scheduleSession(s.name), s.prompt);
-        appendRun(stateRoot, {
-            name: s.name,
-            session: scheduleSession(s.name),
-            firedAt,
-            ms: r.ms,
-            outcome: r.failed ? "failed" : "completed",
-            reply: r.failed ? undefined : r.reply,
-            error: r.failed,
-        });
+        await fireScheduleOnce({ agent, stateRoot, schedule: s, now });
     }
     /**
      * The woken turn's prompt arrives ENVELOPED: without it the model sees its own instruction as a bare
@@ -118,7 +145,10 @@ export function createScheduler({ agent, stateRoot, schedules, now = () => new D
                 break;
             const label = `wake ${w.id.slice(0, 8)}`;
             const firedAt = now().toISOString();
-            const r = await runTurn(label, w.session, wakeEnvelope(w));
+            // A wake turn runs in the BACKGROUND (no open request tracks it) — count it as in-flight work
+            // (busy.ts) so a serving surface that must not idle mid-turn (the AgentCore /ping) sees it.
+            const workDone = beginWork();
+            const r = await runTurn(agent, label, w.session, wakeEnvelope(w)).finally(workDone);
             // Busy handling differs by kind (busy = the turn never started — replay-safe; every other outcome is
             // terminal for this occurrence, since a turn that DID start may have run side effects). ONE-SHOT: defer (bounded) — it has no "next time", dropping it
             // would lose it forever. RECURRING: the claim already ADVANCED the entry to the next instant (see
@@ -215,9 +245,12 @@ export function createScheduler({ agent, stateRoot, schedules, now = () => new D
     return {
         start() {
             stopped = false;
-            const fires = loadFires(stateRoot);
+            // External-clock mode: no cron timers, no boot catch-up — slot delivery (including instants
+            // that passed while this process was down) belongs to the external clock; only the wake-up
+            // pump below runs. See SchedulerOptions.externalClock.
+            const fires = externalClock ? {} : loadFires(stateRoot);
             const current = now();
-            for (const s of schedules) {
+            for (const s of externalClock ? [] : schedules) {
                 // Anchor on the last fire (catch-up basis), or `now` on a first-ever run so a brand-new schedule
                 // never back-fires before the process first booted.
                 const lastFired = fires[s.name];

package/dist/schedule/state.js

@@ -3,7 +3,7 @@
  * files, atomic (tmp+rename) so a crash never leaves a torn file:
  *  - `fires.json` — schedule name → last-fired ISO (durability for the cron catch-up-once);
  *  - `wakeups.json` — the agent's pending self-scheduled one-shot wake-ups (wakeups.ts).
- * The root state dir already self-ignores (`.fastagent/.gitignore`), so no per-dir .gitignore.
+ * No .gitignore is written here: the agent's own (scaffolded by `init`) excludes `.state/`.
  *
  * ponytail: this atomic read/write duplicates channels/telegram/state.ts's primitive (both KB-JSON
  * tmp+rename). Extract a neutral src/state.ts and have both import it when a third consumer appears.

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

@@ -0,0 +1,47 @@
+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[];
+}
+/**
+ * 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.
+ */
+export declare function rememberWakeAlarmUrl(stateRoot: string, url: string): void;
+/** The persisted forwarder URL, or undefined before the first envelope ever seen. */
+export declare function readWakeAlarmUrl(stateRoot: string): string | undefined;
+/** 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 declare const MAX_SYNC_ATTEMPTS = 5;
+/** Pending wake-ups → the desired alarm set, minus already-due entries (see {@link DUE_MARGIN_MS}). */
+export declare function toAlarms(pending: Wakeup[], now: Date): WakeAlarm[];
+/**
+ * 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.
+ */
+export declare function createWakeAlarmSink(options: {
+    secret: string;
+    fetchImpl?: typeof fetch;
+    /** Injectable clock (tests); defaults to the wall clock. */
+    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;

package/dist/schedule/wake-alarm.js

@@ -0,0 +1,136 @@
+/**
+ * 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 full pending set travels each time) 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 { 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
+ * 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.
+ */
+export function rememberWakeAlarmUrl(stateRoot, url) {
+    if (readWakeAlarmUrl(stateRoot) === url)
+        return;
+    writeScheduleFile(scheduleFile(stateRoot, URL_FILE), { url });
+}
+/** The persisted forwarder URL, or undefined before the first envelope ever seen. */
+export function readWakeAlarmUrl(stateRoot) {
+    try {
+        const v = JSON.parse(readFileSync(scheduleFile(stateRoot, URL_FILE), "utf8"));
+        return typeof v.url === "string" ? v.url : undefined;
+    }
+    catch {
+        return undefined; // absent/corrupt — the next envelope rewrites it
+    }
+}
+/** 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. */
+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) {
+    return pending
+        .filter((w) => Date.parse(w.fireAt) > now.getTime() + DUE_MARGIN_MS)
+        .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.
+ */
+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) {
+        // 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();
+        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}`);
+                }
+                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`);
+        }
+        finally {
+            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)");
+            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);
+    };
+}
+/**
+ * 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,9 +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;
-/** 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. */
-export declare const MIN_RECURRING_GAP_MS: number;
+export declare function setWakeupsSink(sink: ((stateRoot: string, pending: Wakeup[]) => 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

@@ -26,7 +26,7 @@ export const MAX_PENDING_WAKEUPS = 20;
 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. */
-export const MIN_RECURRING_GAP_MS = 10 * 60_000; // 10 minutes
+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. */
@@ -47,6 +47,18 @@ function isWakeup(e) {
         (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 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.
+ */
+let wakeupsSink;
+export function setWakeupsSink(sink) {
+    wakeupsSink = sink;
+}
 function load(stateRoot) {
     const v = readScheduleFile(scheduleFile(stateRoot, "wakeups"));
     if (v === undefined)
@@ -68,6 +80,12 @@ function load(stateRoot) {
 }
 function save(stateRoot, wakeups) {
     writeScheduleFile(scheduleFile(stateRoot, "wakeups"), wakeups);
+    try {
+        wakeupsSink?.(stateRoot, wakeups);
+    }
+    catch (e) {
+        log.error(`[schedule] wake-alarm sink failed (store write is unaffected): ${String(e)}`);
+    }
 }
 /** The current pending wake-ups (`fastagent schedule list` uses this). */
 export function listWakeups(stateRoot) {

package/dist/session-remote.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The remote `SessionControl` — the client half of the Phase 3 transport (design §13). Engine- and
+ * server-neutral: speaks only the wire protocol `controlRoutes` serves (HTTP JSON + SSE with the
+ * {sessionId, epoch, seq, event} envelope) and re-exposes the SAME `SessionControl` interface, so
+ * local and remote consumers are isomorphic — client code does not change when the agent moves out
+ * of process.
+ *
+ * Envelope consumption is internal: a seq gap (loss in transit on this connection) — and any
+ * mid-stream transport failure, a server restart included (its connections drop) — THROWS from
+ * the events iterator, so the consumer's failure handling and budget own it; only the consumer's
+ * own detach reads as a clean end. Recovery is the standard reconnect steps (`entries({ since })`
+ * → `state()` → resubscribe), exactly as after any disconnect. The envelope's `epoch` is
+ * informational for consumers that correlate ACROSS connections — within one connection it cannot
+ * change, so this client does not compare it. Nothing here retries silently: a broken stream is
+ * visible as a thrown iteration error, a failed request as a rejected promise.
+ */
+import type { Agent } from "./agent.ts";
+import type { SessionControl } from "./session.ts";
+/** A control request the server answered with a non-2xx status. Carries the STRUCTURED status so a
+ *  consumer distinguishing auth failure (401 — stale token, unrecoverable) from transient transport
+ *  trouble branches on `status`, never on message prose. */
+export declare class ControlRequestError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+/** Connection parameters shared by BOTH remote planes (`connectSessionControl` and
+ *  `connectAgent`) — plane-neutral on purpose: one endpoint, one token, two contracts. */
+export interface RemoteEndpointOptions {
+    /** Base URL of the serving process (e.g. `http://127.0.0.1:8787`); `/control/*` is appended. */
+    url: string;
+    /** The shared bearer secret (`<stateRoot>/control.json` on the serving machine). */
+    token: string;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Connect and return a remote `SessionControl`. Async because `capabilities()` is synchronous in
+ * the contract: the static declaration is fetched ONCE here and served from memory — which also
+ * makes a wrong URL/token fail at connect time, not on first use.
+ */
+export declare function connectSessionControl(options: RemoteEndpointOptions): Promise<SessionControl>;
+/**
+ * The remote DATA plane: an `Agent` whose `invoke` drives `POST /control/invoke` on a serving
+ * process — paired with {@link connectSessionControl}, a client holds a full remote fastagent
+ * instance through the same two contracts local code uses. A REAL Agent, failure discipline
+ * included: SPEC MUST 2 forbids iteration throws, so every failure — transport (401/refused/
+ * dropped mid-stream), protocol, and the images precheck — becomes a terminal `failed` event
+ * (`retryable` from the HTTP status where one exists; network trouble is retryable). Breaking out
+ * of iteration disconnects the request, which cancels the run (SPEC cancellation semantics travel
+ * the wire). The invoke wire is text-only for now: a prompt with images fails visibly instead of
+ * silently dropping them (steer/follow_up on the control plane carry full Prompts).
+ */
+export declare function connectAgent(options: RemoteEndpointOptions): Agent;