@fastagent-sh/fastagent 0.12.0

package/dist/schedule/scheduler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The scheduler: a time-trigger that fires the agent on each schedule's cron. SINGLE-PROCESS (like all
+ * fastagent state today) — a deployment with schedules must keep one machine running, since cron has no
+ * external wake-up (`deploy` enforces that). Started/stopped by the serve path (dev/start).
+ *
+ * Fire model:
+ *  - **stable session per schedule** (`schedule:<name>`), so a schedule's turns share one continuing
+ *    conversation persisted by the core session store; the scheduler is ZERO-touch on session storage.
+ *  - **output is the agent's tools' job** — the scheduler only fires and logs the outcome.
+ *  - **durability = catch up ONCE** (`state.ts`): on start, if the next instant after the last fire is
+ *    already past (the process was down across it), fire once and advance — not once per missed slot.
+ *    lastFired is claimed BEFORE the invoke (at-most-once per slot: a crash mid-turn won't re-fire it;
+ *    "a digest late once" beats "twice"). Strict at-least-once (a per-turn WAL) is a later tier.
+ */
+import { type Agent } from "../agent.ts";
+import type { LoadedSchedule } from "./schedule.ts";
+/** A schedule's turns share this stable session — a continuing conversation, like the telegram channel's
+ *  per-chat session. Derived at RUNTIME from the name (never an authored field). */
+export declare function scheduleSession(name: string): string;
+export interface Scheduler {
+    /** Arm every schedule (catching up an overdue one once). Idempotent-ish: call once per process. */
+    start(): void;
+    /** Clear all armed timers. Does NOT drain an in-flight fire (SIGTERM exits mid-turn by design; the
+     *  interrupted turn is not re-fired — lastFired was already claimed). A catch-up fire in flight has NO
+     *  timer entry to clear either (the overdue branch fires directly, without arming), so `stop()` simply
+     *  lets it run out or be cut by process exit — same non-drain, and its claim is already persisted. */
+    stop(): void;
+}
+export interface SchedulerOptions {
+    agent: Agent;
+    stateRoot: string;
+    schedules: LoadedSchedule[];
+    /** Injectable clock for tests; defaults to the wall clock. */
+    now?: () => Date;
+}
+export declare function createScheduler({ agent, stateRoot, schedules, now }: SchedulerOptions): Scheduler;

package/dist/schedule/scheduler.js

@@ -0,0 +1,253 @@
+/**
+ * The scheduler: a time-trigger that fires the agent on each schedule's cron. SINGLE-PROCESS (like all
+ * fastagent state today) — a deployment with schedules must keep one machine running, since cron has no
+ * external wake-up (`deploy` enforces that). Started/stopped by the serve path (dev/start).
+ *
+ * Fire model:
+ *  - **stable session per schedule** (`schedule:<name>`), so a schedule's turns share one continuing
+ *    conversation persisted by the core session store; the scheduler is ZERO-touch on session storage.
+ *  - **output is the agent's tools' job** — the scheduler only fires and logs the outcome.
+ *  - **durability = catch up ONCE** (`state.ts`): on start, if the next instant after the last fire is
+ *    already past (the process was down across it), fire once and advance — not once per missed slot.
+ *    lastFired is claimed BEFORE the invoke (at-most-once per slot: a crash mid-turn won't re-fire it;
+ *    "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 { log } from "../log.js";
+import { appendRun } from "./audit.js";
+import { nextRun } from "./cron.js";
+import { loadFires, saveFires } from "./state.js";
+import { deferWakeup, takeFirstDueWakeup } from "./wakeups.js";
+/** A schedule's turns share this stable session — a continuing conversation, like the telegram channel's
+ *  per-chat session. Derived at RUNTIME from the name (never an authored field). */
+export function scheduleSession(name) {
+    return `schedule:${name}`;
+}
+// A single setTimeout maxes out at ~24.8 days and drifts over long sleeps; cap each wait so a long
+// interval (or a suspended machine) re-checks against the wall clock rather than firing wildly early/late.
+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
+                }
+            }
+            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 };
+        }
+    }
+    /** 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. */
+    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,
+        });
+    }
+    /**
+     * The woken turn's prompt arrives ENVELOPED: without it the model sees its own instruction as a bare
+     * user message — in a chat session it may answer a "user" who said nothing — and it has no way to know
+     * the wake-up's id (buried in a long-past tool result), which `unwake` needs. Static cron fires stay raw
+     * on purpose: their prompt is the AUTHOR's instruction in a dedicated `schedule:<name>` session, where
+     * every turn is a fire and an envelope would only dilute it.
+     */
+    function wakeEnvelope(w) {
+        const tag = w.cron
+            ? `[wake-up ${w.id} fired — YOUR recurring self-scheduled turn (cron "${w.cron}"${w.tz ? ` ${w.tz}` : ""}), not a user message; unwake({ id: "${w.id}" }) stops it]`
+            : `[wake-up ${w.id} fired — YOUR self-scheduled turn, not a user message]`;
+        return `${tag} ${w.prompt}`;
+    }
+    /**
+     * Fire every due self-scheduled wake-up, ONE at a time (claim → fire → claim next) so a crash loses at
+     * most one occurrence. Each fires back into the session it was set in. Busy handling splits by kind: a
+     * ONE-SHOT that failed because the session was BUSY (`code: session_busy` — the turn never started; the
+     * very case "wake me in 10 min" hits while the user is still chatting) is deferred to the next poll,
+     * bounded, because a dropped one-shot has no "next time"; a RECURRING busy occurrence is skipped
+     * immediately (its claim already advanced the entry — the next occurrence comes by definition). Any
+     * other failure is terminal for that occurrence (the turn ran — re-running risks duplicate side effects).
+     */
+    async function pollWakeups() {
+        for (;;) {
+            if (stopped)
+                break; // stop() must halt an in-flight drain, like it clears the cron timers
+            const w = takeFirstDueWakeup(stateRoot, now());
+            if (!w)
+                break;
+            const label = `wake ${w.id.slice(0, 8)}`;
+            const firedAt = now().toISOString();
+            const r = await runTurn(label, w.session, wakeEnvelope(w));
+            // 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
+            // takeFirstDueWakeup), so a busy occurrence is simply SKIPPED and audited — the next one comes by
+            // definition, and never touching the stored entry here is what keeps unwake/cancel race-free.
+            let kept = false;
+            if (r.busy && !w.cron) {
+                kept = deferWakeup(stateRoot, w, new Date(now().getTime() + WAKEUP_POLL_MS));
+                if (kept)
+                    log.info(`[schedule] ${label}: session busy — retrying next poll`);
+                else
+                    log.error(`[schedule] ${label}: dropped after too many busy retries`);
+            }
+            else if (r.busy && w.cron) {
+                log.error(`[schedule] ${label}: occurrence skipped (session busy); next fires per cron`);
+            }
+            // Audit honesty: `deferred` ONLY when the same occurrence was actually re-scheduled. A busy one-shot
+            // dropped at the ceiling, and a busy recurring occurrence (skipped — its recurrence survives), are
+            // both FINAL for that occurrence → `failed`.
+            appendRun(stateRoot, {
+                name: "wake",
+                session: w.session,
+                firedAt,
+                ms: r.ms,
+                outcome: r.busy ? (kept ? "deferred" : "failed") : r.failed ? "failed" : "completed",
+                reply: r.failed || r.busy ? undefined : r.reply,
+                error: r.busy
+                    ? kept
+                        ? undefined
+                        : w.cron
+                            ? "occurrence skipped (session busy); the recurrence continues"
+                            : "dropped after too many busy retries"
+                    : r.failed,
+            });
+        }
+    }
+    /** Drain due wake-ups, then chain the next poll AFTER — never overlapping two drains. TOTAL: a state-IO
+     *  fault (an unreadable store) is caught + logged and the chain continues, never a crash / a silent stop
+     *  (this is `void`-scheduled, so an escaping throw would be an unhandled rejection). */
+    async function pumpWakeups() {
+        if (stopped)
+            return;
+        try {
+            await pollWakeups();
+        }
+        catch (e) {
+            log.error(`[schedule] wake-up poll failed (continuing next poll): ${String(e)}`);
+        }
+        if (stopped)
+            return;
+        wakeupTimer = setTimeout(() => void pumpWakeups(), WAKEUP_POLL_MS);
+    }
+    /** Arm a timer for `at`, capped so a long wait re-checks the wall clock instead of trusting one sleep. */
+    function arm(s, at) {
+        if (stopped)
+            return;
+        const delay = Math.min(Math.max(0, at.getTime() - now().getTime()), MAX_WAIT_MS);
+        timers.set(s.name, setTimeout(() => {
+            if (stopped)
+                return;
+            if (now().getTime() >= at.getTime())
+                void fireThenReArm(s);
+            else
+                arm(s, at); // woke early (the cap) — keep waiting for the real instant
+        }, delay));
+    }
+    /** Fire, then arm the NEXT run computed from now — so a slow fire never double-fires the same slot and
+     *  missed slots collapse to the single catch-up already done. TOTAL, like pumpWakeups: this is
+     *  void-scheduled from a timer, so an escaping throw (a state-IO fault while claiming — an unreadable
+     *  fires.json, an unpersistable claim) would be an unhandled rejection = the WHOLE service crashing over
+     *  one skipped fire. Log it and keep the schedule armed instead; boot-time state faults still fail `start()`
+     *  loudly (an operator fixes those before serving). */
+    async function fireThenReArm(s) {
+        try {
+            await fire(s);
+        }
+        catch (e) {
+            // Audited too (appendRun is total, and runs.jsonl ≠ the broken state file) — a skipped fire must
+            // show up in `schedule history`, not only in stderr.
+            log.error(`[schedule] ${s.name}: fire failed (skipping this run, schedule stays armed): ${String(e)}`);
+            appendRun(stateRoot, {
+                name: s.name,
+                session: scheduleSession(s.name),
+                firedAt: now().toISOString(),
+                ms: 0,
+                outcome: "failed",
+                error: `run skipped — fire failed: ${String(e)}`,
+            });
+        }
+        const due = nextRun(s.cron, s.tz, now());
+        if (due)
+            arm(s, due);
+    }
+    return {
+        start() {
+            stopped = false;
+            const fires = loadFires(stateRoot);
+            const current = now();
+            for (const s of 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];
+                const anchor = lastFired ? new Date(lastFired) : current;
+                const due = nextRun(s.cron, s.tz, anchor);
+                if (!due) {
+                    log.warn(`[schedule] ${s.name}: cron "${s.cron}" will never fire again — not armed`);
+                    continue;
+                }
+                if (due.getTime() <= current.getTime()) {
+                    log.info(`[schedule] ${s.name}: catching up a missed run`);
+                    void fireThenReArm(s); // overdue → fire once, then arm the next
+                }
+                else {
+                    arm(s, due);
+                }
+            }
+            // Self-scheduled wake-ups: drain now (catch any overdue while the process was down), then chain the
+            // next poll AFTER this drain finishes — a CHAIN, not setInterval, so a wake turn longer than the poll
+            // interval never overlaps two drains (which would break the one-at-a-time claim→fire→claim promise).
+            void pumpWakeups();
+        },
+        stop() {
+            stopped = true;
+            for (const t of timers.values())
+                clearTimeout(t);
+            timers.clear();
+            if (wakeupTimer)
+                clearTimeout(wakeupTimer);
+            wakeupTimer = undefined;
+        },
+    };
+}

package/dist/schedule/state.d.ts

@@ -0,0 +1,14 @@
+/** Path of a JSON file under `<stateRoot>/schedule/`. */
+export declare function scheduleFile(stateRoot: string, name: string): string;
+/**
+ * Read a JSON state file. Missing is normal (first run → undefined); a corrupt file degrades visibly
+ * (warn + undefined) — schedule state is recoverable, not worth refusing to boot over; an unreadable
+ * file (permissions/IO) throws — a real environment fault the operator must fix, not hide behind empty
+ * state. The caller owns shape validation (an IO boundary).
+ */
+export declare function readScheduleFile(path: string): unknown;
+export declare function writeScheduleFile(path: string, value: unknown): void;
+/** name → last-fired ISO timestamp. */
+export type Fires = Record<string, string>;
+export declare function loadFires(stateRoot: string): Fires;
+export declare function saveFires(stateRoot: string, fires: Fires): void;

package/dist/schedule/state.js

@@ -0,0 +1,56 @@
+/**
+ * Durable scheduler state for a SINGLE-PROCESS deployment, under `<stateRoot>/schedule/`. Small JSON
+ * 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.
+ *
+ * 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.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { log } from "../log.js";
+/** Path of a JSON file under `<stateRoot>/schedule/`. */
+export function scheduleFile(stateRoot, name) {
+    return join(stateRoot, "schedule", `${name}.json`);
+}
+/**
+ * Read a JSON state file. Missing is normal (first run → undefined); a corrupt file degrades visibly
+ * (warn + undefined) — schedule state is recoverable, not worth refusing to boot over; an unreadable
+ * file (permissions/IO) throws — a real environment fault the operator must fix, not hide behind empty
+ * state. The caller owns shape validation (an IO boundary).
+ */
+export function readScheduleFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw new Error(`schedule state ${path} is unreadable — fix permissions/disk and restart: ${String(e)}`, {
+            cause: e,
+        });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        log.warn(`[schedule] corrupt state file ${path} — ignoring: ${String(e)}`);
+        return undefined;
+    }
+}
+export function writeScheduleFile(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(value));
+    renameSync(tmp, path);
+}
+export function loadFires(stateRoot) {
+    const v = readScheduleFile(scheduleFile(stateRoot, "fires"));
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+export function saveFires(stateRoot, fires) {
+    writeScheduleFile(scheduleFile(stateRoot, "fires"), fires);
+}

package/dist/schedule/wakeups.d.ts

@@ -0,0 +1,82 @@
+export interface Wakeup {
+    id: string;
+    /** The session to fire back into (the conversation the `wake` call ran in). */
+    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. */
+    fireAt: string;
+    /** RECURRING: the cron expression (5-field). Absent = one-shot (fires once, removed). */
+    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. */
+    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). */
+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). */
+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;
+/** The current pending wake-ups (`fastagent schedule list` uses this). */
+export declare function listWakeups(stateRoot: string): Wakeup[];
+export type AddWakeupResult = {
+    ok: true;
+    id: string;
+    fireAt: string;
+} | {
+    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.
+ */
+export declare function addWakeup(stateRoot: string, input: {
+    session: string;
+    prompt: string;
+    fireAt?: Date;
+    cron?: string;
+    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.
+ */
+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}.
+ */
+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 harness 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.
+ */
+export declare function deferWakeup(stateRoot: string, w: Wakeup, fireAt: Date): boolean;

package/dist/schedule/wakeups.js

@@ -0,0 +1,196 @@
+/**
+ * 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.
+ */
+import { randomUUID } from "node:crypto";
+import { log } from "../log.js";
+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). */
+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). */
+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
+/** 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. */
+function isWakeup(e) {
+    if (!e || typeof e !== "object")
+        return false;
+    const w = e;
+    return (typeof w.id === "string" &&
+        typeof w.session === "string" &&
+        typeof w.prompt === "string" &&
+        typeof w.fireAt === "string" &&
+        !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).
+        (w.cron === undefined ||
+            (typeof w.cron === "string" && cronError(w.cron, typeof w.tz === "string" ? w.tz : undefined) === undefined)));
+}
+function load(stateRoot) {
+    const v = readScheduleFile(scheduleFile(stateRoot, "wakeups"));
+    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).
+        log.warn(`[schedule] wakeups store is not an array — ignoring it: ${JSON.stringify(v).slice(0, 80)}`);
+        return [];
+    }
+    const valid = [];
+    for (const e of v) {
+        if (isWakeup(e))
+            valid.push(e);
+        else
+            log.warn(`[schedule] dropping a malformed wake-up entry: ${JSON.stringify(e)}`);
+    }
+    return valid;
+}
+function save(stateRoot, wakeups) {
+    writeScheduleFile(scheduleFile(stateRoot, "wakeups"), wakeups);
+}
+/** The current pending wake-ups (`fastagent schedule list` uses this). */
+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.
+ */
+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.)
+        const first = nextRun(input.cron, input.tz, now);
+        const second = first && nextRun(input.cron, input.tz, first);
+        if (!first || !second)
+            return { ok: false, error: "this cron never fires (or fires only once) — use `in` for a one-shot." };
+        if (second.getTime() - first.getTime() < MIN_RECURRING_GAP_MS) {
+            return {
+                ok: false,
+                error: `too frequent — a recurring wake must fire at most every ${MIN_RECURRING_GAP_MS / 60_000} minutes.`,
+            };
+        }
+        fireAtDate = first; // DERIVED from the cron — a caller-passed fireAt can't disagree with the schedule
+    }
+    else {
+        if (!input.fireAt)
+            return { ok: false, error: "a one-shot wake needs its fire time (`in`)." };
+        if (input.fireAt.getTime() < now.getTime() + MIN_WAKE_MS) {
+            return { ok: false, error: `too soon — the minimum wake delay is ${MIN_WAKE_MS / 1000}s.` };
+        }
+        fireAtDate = input.fireAt;
+    }
+    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.
+        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("; ");
+        return {
+            ok: false,
+            error: `too many pending wake-ups for this conversation (${MAX_PENDING_WAKEUPS}) — wait for some to fire, or unwake one. Pending: ${pending}`,
+        };
+    }
+    const id = randomUUID();
+    const fireAt = fireAtDate.toISOString();
+    save(stateRoot, [
+        ...all,
+        { id, session: input.session, prompt: input.prompt, fireAt, cron: input.cron, tz: input.tz },
+    ]);
+    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.
+ */
+export function removeWakeup(stateRoot, id, session) {
+    const all = load(stateRoot);
+    const kept = all.filter((w) => !(w.id === id && (session === undefined || 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}.
+ */
+export function takeFirstDueWakeup(stateRoot, now = new Date()) {
+    const all = load(stateRoot);
+    const idx = all.findIndex((w) => new Date(w.fireAt).getTime() <= now.getTime());
+    if (idx === -1)
+        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.
+        const next = nextRun(w.cron, w.tz, now);
+        if (next)
+            all[idx] = { ...w, fireAt: next.toISOString(), attempts: undefined };
+        else
+            all.splice(idx, 1); // the cron has no next instant — this is its final occurrence
+        save(stateRoot, all);
+        return { ...w }; // THIS occurrence (original fireAt); the store already holds the next
+    }
+    all.splice(idx, 1);
+    save(stateRoot, all);
+    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 harness 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.
+ */
+export function deferWakeup(stateRoot, w, fireAt) {
+    const attempts = (w.attempts ?? 0) + 1;
+    if (attempts > MAX_WAKE_ATTEMPTS)
+        return false;
+    save(stateRoot, [...load(stateRoot), { ...w, fireAt: fireAt.toISOString(), attempts }]);
+    return true;
+}

package/dist/telegram.d.ts

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
+export { telegramChannel, defaultTelegramRoute, telegramEnvelope, type TelegramChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";

package/dist/telegram.js

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
+export { telegramChannel, defaultTelegramRoute, telegramEnvelope, } from "./channels/telegram/telegram.js";