@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/schedule/discover.js

@@ -1,52 +1,61 @@
 /**
- * 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.
+ * Routine discovery: an agent declares its named units of work by dropping files in `routines/`, mirroring
+ * `tools/` and `channels/`.
  */
 import { join } from "node:path";
-import { loadModuleDir, moduleInventory } from "../loader.js";
+import { loadModuleDir } from "../loader.js";
+import { readSecretDeclaration } from "../declared-secrets.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 assertInsideAgentDir(dir, "schedules");
-    const entries = await moduleInventory(join(dir, "schedules"));
-    return entries.map((entry) => entry.name);
-}
+import { isSafeScheduleName } from "./state.js";
 /**
- * Discover schedules in `<dir>/schedules/`: each file default-exports a `defineSchedule({...})`, named
- * from its filename. A file broken for ANY reason — a failed import, not a schedule (no cron/prompt), or
- * an invalid cron/tz — is ISOLATED into `failures` (skipped + reported, never a crash-loop, G2), the same
- * way `loadTools`/`loadChannels` isolate theirs. A duplicate name (foo.ts + foo.js) keeps the first and
- * reports the rest.
+ * Discover routines in `<dir>/routines/`: each file default-exports a `defineRoutine({...})`, named from its
+ * filename.
  */
-export async function loadSchedules(dir) {
-    await assertInsideAgentDir(dir, "schedules");
-    const { modules, failures } = await loadModuleDir(join(dir, "schedules"));
+export async function loadRoutines(dir) {
+    await assertInsideAgentDir(dir, "routines");
+    const { modules, failures } = await loadModuleDir(join(dir, "routines"));
     const byName = new Map();
+    const secrets = new Map();
     for (const { name, label, file, mod } of modules) {
         try {
-            const s = mod.default;
-            if (!s || typeof s.cron !== "string" || typeof s.prompt !== "string") {
-                throw new Error(`${label} must default-export defineSchedule({ cron, prompt })`);
+            const r = mod.default;
+            if (!r || typeof r.prompt !== "string") {
+                throw new Error(`${label} must default-export defineRoutine({ prompt, cron? })`);
+            }
+            const declaration = readSecretDeclaration(r, label);
+            if (declaration.error !== undefined)
+                throw new Error(declaration.error);
+            // NO CRON IS NOT AN ERROR: the routine is then reachable by name only (`POST /run`, the CLI, a scheduler
+            // that calls the route). A `tz` without one is, though — it would read as a time this routine does not have.
+            if (r.cron !== undefined && typeof r.cron !== "string")
+                throw new Error(`${label}: "cron" must be a string`);
+            if (r.cron === undefined && r.tz !== undefined) {
+                throw new Error(`${label}: "tz" means nothing without "cron" — remove it, or give this routine a cron`);
+            }
+            if (r.cron !== undefined) {
+                const err = cronError(r.cron, r.tz);
+                if (err)
+                    throw new Error(`${label}: invalid cron/tz — ${err}`);
+            }
+            // The name becomes a path segment (the fired-slot claims live under `claims/<name>/`), so anything that could
+            // leave that directory is refused here — where the author sees which file is wrong — rather than deeper.
+            if (!isSafeScheduleName(name)) {
+                throw new Error(`${label}: a routine name cannot be ".", ".." or contain a path separator`);
             }
-            const err = cronError(s.cron, s.tz);
-            if (err)
-                throw new Error(`${label}: invalid cron/tz — ${err}`);
-            // "wake" is reserved: the run audit records self-scheduled wake-ups under that name, so a schedule
-            // named wake would make `schedule history wake` an unreadable mix of two different things.
-            if (name === "wake")
-                throw new Error(`${label}: "wake" is a reserved schedule name (the self-scheduling audit uses it)`);
             if (byName.has(name))
-                throw new Error(`${label}: duplicate schedule name "${name}" — kept the first`);
-            byName.set(name, { name, cron: s.cron, tz: s.tz, prompt: s.prompt });
+                throw new Error(`${label}: duplicate routine name "${name}" — kept the first`);
+            byName.set(name, {
+                name,
+                prompt: r.prompt,
+                ...(r.cron !== undefined ? { cron: r.cron } : {}),
+                ...(r.tz !== undefined ? { tz: r.tz } : {}),
+            });
+            secrets.set(name, declaration.secrets);
         }
         catch (error) {
             failures.push({ label, file, message: error.message });
         }
     }
-    return { schedules: [...byName.values()], failures };
+    return { routines: [...byName.values()], secrets, failures };
 }

package/dist/schedule/routine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * WHICH conversation a routine's turns belong to: all of them, so a routine shares one continuing conversation —
+ * and without depending on engine session storage. The ONE spelling of it: the clock invokes through it,
+ * `fastagent routine run` reproduces a run with it, `POST /run` reports it as where to look, and
+ * `routine history` prints the command that opens it.
+ */
+export declare function routineSession(name: string): string;
+/** A named unit of work the definition owns. With a `cron`, a clock fires it; without one, only its name reaches it. */
+export interface Routine {
+    /**
+     * 5-field cron expression (`minute hour day-of-month month day-of-week`), or absent.
+     *
+     * ABSENT IS A REAL CHOICE, not an omission: the routine is then reachable only by name — `POST /run`, the CLI, a
+     * platform scheduler that calls the route. A time is one way to ask for work, not what the work is.
+     */
+    cron?: string;
+    /** IANA timezone for the cron (default "UTC"). Meaningless without `cron`. */
+    tz?: string;
+    /** The turn's text = the routine's instruction. */
+    prompt: string;
+    /** Env vars this routine declared — carried by `deploy`, asserted before the clock starts. */
+    secrets?: readonly string[];
+}
+/** What an author writes. `prompt` may be built FROM the declared secrets, which is the only reason a
+ *  routine file ever read the environment (a channel id, a target inbox). */
+export interface DefineRoutineOptions<S extends readonly string[]> {
+    cron?: string;
+    tz?: string;
+    prompt: string | ((secrets: Record<S[number], string>) => string);
+    /**
+     * Env vars this routine needs (`["SLACK_DIGEST_CHANNEL"]`), typed into the `prompt` builder.
+     * `deploy` carries them and the clock refuses to start while one is unset, naming this file
+     * (see src/declared-secrets.ts) — the guarantees a bare `process.env` read cannot have.
+     */
+    secrets?: S;
+}
+/** Type + completion for a routine file, and the ONE place a prompt builder is resolved (at load:
+ *  what the loader stores is always a string, so every consumer sees one shape). */
+export declare function defineRoutine<const S extends readonly string[] = readonly []>(routine: DefineRoutineOptions<S>): Routine;
+/** A loaded routine: its authored fields plus the name derived from its filename (authoritative). */
+export interface LoadedRoutine extends Routine {
+    name: string;
+}

package/dist/schedule/routine.js

@@ -0,0 +1,32 @@
+/**
+ * Routine authoring: `defineRoutine`.
+ *
+ * A ROUTINE IS THE UNIT OF WORK, and the only named one in the system: a prompt the definition owns, addressed by
+ * name. `cron` is a FIELD of it, not a second concept — with one, a clock fires it; without one, it is reached by
+ * name alone (`POST /run`).
+ *
+ * WHAT IT IS NOT: a wake-up. The agent can schedule work for itself too (the `wake` tool, schedule/wakeups.ts), and
+ * conceptually that is the same idea — work to be done later. Every operational difference between them follows
+ * from ONE root: a routine is written in the DEFINITION (versioned, reviewed, shipped with the image, addressable
+ * by name) and a wake-up is written into the STATE by a running agent (minted id, cancellable, aimed back at the
+ * conversation it came from, erased by the next release if it were a definition file). Code and data.
+ *
+ * A `prompt` may be a function of the file's declared `secrets` — the only reason such a file ever read the
+ * environment (src/declared-secrets.ts).
+ */
+import { secretValues } from "../declared-secrets.js";
+/**
+ * WHICH conversation a routine's turns belong to: all of them, so a routine shares one continuing conversation —
+ * and without depending on engine session storage. The ONE spelling of it: the clock invokes through it,
+ * `fastagent routine run` reproduces a run with it, `POST /run` reports it as where to look, and
+ * `routine history` prints the command that opens it.
+ */
+export function routineSession(name) {
+    return `routine:${name}`;
+}
+/** Type + completion for a routine file, and the ONE place a prompt builder is resolved (at load:
+ *  what the loader stores is always a string, so every consumer sees one shape). */
+export function defineRoutine(routine) {
+    const { prompt, ...rest } = routine;
+    return { ...rest, prompt: typeof prompt === "function" ? prompt(secretValues(routine.secrets)) : prompt };
+}

package/dist/schedule/run.d.ts

@@ -0,0 +1,55 @@
+import type { Agent } from "../agent.ts";
+import { type LoadedRoutine } from "./routine.ts";
+/**
+ * The 404 for a name this deployment does not declare — drift: a caller outliving the thing it calls. The names are
+ * listed so an operator can see whether it is a typo or a stale job without shelling in. The caller's name is CLIPPED
+ * before it goes back out: listing this deployment's own names is deliberate, quoting an unauthenticated caller's
+ * 4 KiB of body is not (`refuseNonJsonBody` states the same rule for the same table).
+ */
+export declare function unknownRoutine(name: string, routines: readonly LoadedRoutine[]): Response;
+/** The reply shape both doors answer with — one for the route, one for a host that has no route (AgentCore). */
+export interface RoutineRunReply {
+    name: string;
+    /** WHERE TO LOOK: the turn's output lives in this session's journal (`fastagent routine history`, `/control/*`). */
+    session: string;
+    ran: boolean;
+    /** Present when `ran: false` — today, the previous turn still holding this routine's one session. */
+    reason?: string;
+    /** Present when the turn RAN and did not finish. */
+    failed?: string;
+    ms: number;
+}
+/**
+ * Run one routine and say what happened. THE one implementation, because there are two doors and only one
+ * contract: `POST /run` on any host that publishes routes, and AgentCore's IAM-gated `routine-run` envelope on the
+ * host that publishes none. A second copy is how the two would come to answer differently.
+ */
+export declare function runRoutineByName(agent: Agent, routine: LoadedRoutine): Promise<RoutineRunReply>;
+/**
+ * Build the handler for `GET /routines` — what a caller may ask for by name.
+ *
+ * DISCOVERY, because the alternative was a 404. The names were already public: `POST /run` lists them when a caller
+ * gets one wrong, which is deliberate (an operator has to tell a typo from a stale caller) — so the only thing this
+ * adds is not having to guess wrong first. "Expose a declared prompt as an API" is half a sentence without it.
+ *
+ * NAMES AND SCHEDULES, NEVER PROMPTS. What a routine SAYS is the definition's content; handing it to an
+ * unauthenticated caller would publish the agent's behaviour, which is the one thing keeping the prompt out of the
+ * request body was for. `cron` is here because it answers "will this run on its own, or is my clock the only one?",
+ * which is a caller's question, not the definition's secret.
+ *
+ * Mounted exactly where `POST /run` is: it describes that route, so listing names a caller cannot use would be a
+ * catalogue of nothing.
+ */
+export declare function createRoutineListHandler(options: {
+    routines: readonly LoadedRoutine[];
+}): ((req: Request) => Promise<Response>) | undefined;
+/**
+ * Build the handler for `POST /run`, bound to what this serve loaded.
+ *
+ * `undefined` when the definition declares nothing runnable: a route that can only ever answer 404 is not a route,
+ * and the startup report names what is actually mounted.
+ */
+export declare function createRunHandler(options: {
+    agent: Agent;
+    routines: readonly LoadedRoutine[];
+}): ((req: Request) => Promise<Response>) | undefined;

package/dist/schedule/run.js

@@ -0,0 +1,146 @@
+/**
+ * `POST /run` — **an API**: run a unit of work this definition declares, by name.
+ *
+ * NOT A TIME TRIGGER, and the difference is the whole design. Occurrence semantics — a slot, a claim, a fire
+ * history, an overlap policy — exist exactly where fastagent OWNS the clock: the resident loop in `dev`/`start`,
+ * and AgentCore, where `deploy` writes the EventBridge rule, injects the instant and relays it through an ingress
+ * secret (channels/agentcore.ts). Both of those know which occurrence a run is for because they produced it.
+ *
+ * This route is the other case: somebody else's clock, CI job, button or script. It cannot be told which occurrence
+ * it means, and pretending otherwise was measurably worse than admitting it. The attempt cost four rounds — an
+ * instant dated ahead poisoned the claim gate permanently, one off the grid minted a claim no occurrence would ever
+ * match, an old one replayed history a turn at a time, and the grid arithmetic all three needed was ~6ms of
+ * synchronous CPU per request on an anonymous route. A platform cron drifting a few minutes then lost an occurrence
+ * outright (Railway documents "a few minutes" of variance; measured: 3 fires, 2 turns).
+ *
+ * So the contract is the one an API has:
+ *
+ *   - the body names WHAT to run and nothing else — the prompt stays in the definition, which is the whole reason
+ *     this exists beside `POST /invoke`, whose caller brings its own text and therefore its own behaviour
+ *   - the reply says what happened and WHERE TO LOOK (the session the turn ran in). Retry policy is the caller's,
+ *     because only the caller knows whether its work tolerates running twice
+ *   - it is exactly as exposed as `POST /invoke`: unauthenticated, full tool authority, `http.invoke: false` and a
+ *     gateway in front are the answers. The framework authenticates nothing (docs/design/session-control.md §14)
+ *
+ * AND NO IDEMPOTENCY KEY. A key would deduplicate the CALL, not the WORK: a turn that sent one message and then died
+ * would answer a keyed retry with "already ran" — safety exactly where it is absent, which is the same reason a failed
+ * fire is not retried (schedule/scheduler.ts). What makes a retry safe is idempotent WORK, which only the author can
+ * arrange.
+ *
+ * NAME IN THE BODY, not the path. A declared name is a filename (`每日简报`, `my schedule` are both legal), and a
+ * path segment would mean percent-encoding it — the cost the control plane pays for session ids and this route has
+ * no reason to. It also keeps the shape of `POST /invoke`, whose scope rides in the body for the same reason.
+ */
+import * as Effect from "effect/Effect";
+import { readBodyCapped, refuseNonJsonBody } from "../channels/body.js";
+import { text } from "../channels/respond.js";
+import { routineSession } from "./routine.js";
+import { runTurn } from "./scheduler.js";
+/** A trigger body is a name; the cap only has to admit that. */
+const MAX_RUN_BODY_BYTES = 4 * 1024;
+/**
+ * How much of a caller's `name` a 404 will quote back — the ONE thing this route echoes, because telling a typo
+ * from a stale caller needs the name and nothing else does. Long enough to recognise one, short enough not to be a
+ * page.
+ */
+const MAX_ECHOED_NAME = 64;
+/**
+ * The 404 for a name this deployment does not declare — drift: a caller outliving the thing it calls. The names are
+ * listed so an operator can see whether it is a typo or a stale job without shelling in. The caller's name is CLIPPED
+ * before it goes back out: listing this deployment's own names is deliberate, quoting an unauthenticated caller's
+ * 4 KiB of body is not (`refuseNonJsonBody` states the same rule for the same table).
+ */
+export function unknownRoutine(name, routines) {
+    return text(`no declared work named "${name.slice(0, MAX_ECHOED_NAME)}" (this deployment has: ${routines
+        .map((r) => r.name)
+        .join(", ")})\n`, 404);
+}
+/** The Effect boundary, in one place: the turn runs, and its outcome is what the caller reads. */
+const runOnce = (agent, routine) => Effect.runPromise(runTurn(agent, routine.name, routineSession(routine.name), routine.prompt));
+/**
+ * Run one routine and say what happened. THE one implementation, because there are two doors and only one
+ * contract: `POST /run` on any host that publishes routes, and AgentCore's IAM-gated `routine-run` envelope on the
+ * host that publishes none. A second copy is how the two would come to answer differently.
+ */
+export async function runRoutineByName(agent, routine) {
+    const session = routineSession(routine.name);
+    const { busy, failed, ms } = await runOnce(agent, routine);
+    // BUSY IS NOT A FAILURE and it is the one "did not run" this has: a declared unit of work has ONE session, so a
+    // call arriving while the previous turn holds it is refused by that session. Reported as itself, with what the
+    // caller needs in order to decide — try later — rather than as an error it would retry blindly.
+    if (busy) {
+        return {
+            name: routine.name,
+            session,
+            ran: false,
+            reason: `the previous turn of "${routine.name}" is still running`,
+            ms,
+        };
+    }
+    return { name: routine.name, session, ran: true, ...(failed !== undefined ? { failed } : {}), ms };
+}
+/**
+ * Build the handler for `GET /routines` — what a caller may ask for by name.
+ *
+ * DISCOVERY, because the alternative was a 404. The names were already public: `POST /run` lists them when a caller
+ * gets one wrong, which is deliberate (an operator has to tell a typo from a stale caller) — so the only thing this
+ * adds is not having to guess wrong first. "Expose a declared prompt as an API" is half a sentence without it.
+ *
+ * NAMES AND SCHEDULES, NEVER PROMPTS. What a routine SAYS is the definition's content; handing it to an
+ * unauthenticated caller would publish the agent's behaviour, which is the one thing keeping the prompt out of the
+ * request body was for. `cron` is here because it answers "will this run on its own, or is my clock the only one?",
+ * which is a caller's question, not the definition's secret.
+ *
+ * Mounted exactly where `POST /run` is: it describes that route, so listing names a caller cannot use would be a
+ * catalogue of nothing.
+ */
+export function createRoutineListHandler(options) {
+    const { routines } = options;
+    if (routines.length === 0)
+        return undefined;
+    const body = routines.map((r) => ({
+        name: r.name,
+        ...(r.cron !== undefined ? { cron: r.cron } : {}),
+        ...(r.tz !== undefined ? { tz: r.tz } : {}),
+    }));
+    // NO METHOD CHECK. The router dispatches `GET /routines` here and nothing else, so the only thing such a check
+    // could reach is HEAD — which `channels/serve.ts` deliberately answers with the GET route, the same way
+    // `GET /health` is HEAD-probeable. Checking would break that and buy nothing.
+    return async () => Response.json(body);
+}
+/**
+ * Build the handler for `POST /run`, bound to what this serve loaded.
+ *
+ * `undefined` when the definition declares nothing runnable: a route that can only ever answer 404 is not a route,
+ * and the startup report names what is actually mounted.
+ */
+export function createRunHandler(options) {
+    const { agent, routines } = options;
+    if (routines.length === 0)
+        return undefined;
+    return async (req) => {
+        if (req.method !== "POST")
+            return text("POST only\n", 405);
+        const wrongType = refuseNonJsonBody(req);
+        if (wrongType)
+            return wrongType;
+        const body = await readBodyCapped(req, MAX_RUN_BODY_BYTES);
+        if ("tooLarge" in body)
+            return text("body too large\n", 413);
+        let payload;
+        try {
+            payload = JSON.parse(body.text);
+        }
+        catch {
+            return text("invalid json\n", 400);
+        }
+        const { name } = (payload ?? {});
+        if (typeof name !== "string" || name === "") {
+            return text('need { "name": string } — e.g. {"name":"daily"}\n', 400);
+        }
+        const routine = routines.find((r) => r.name === name);
+        if (!routine)
+            return unknownRoutine(name, routines);
+        return Response.json(await runRoutineByName(agent, routine));
+    };
+}

package/dist/schedule/scheduler.d.ts

@@ -1,75 +1,64 @@
-/**
- * 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 * as Effect from "effect/Effect";
 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;
+import { PortFailure } from "../effect-port.ts";
+import { type LoadedRoutine } from "./routine.ts";
 export interface Scheduler {
-    /** Arm every schedule (catching up an overdue one once). Idempotent-ish: call once per process. */
+    /** Arm routines, account for a fire the previous run was killed in, and catch up overdue work once. */
     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. */
+    /** Cancel pending waits. */
     stop(): void;
 }
 export interface SchedulerOptions {
     agent: Agent;
     stateRoot: string;
-    schedules: LoadedSchedule[];
-    /** Injectable clock for tests; defaults to the wall clock. */
+    /** Every routine this serve loaded. Only the ones WITH a cron are armed — the rest are reached by name. */
+    routines: LoadedRoutine[];
+    /** Override wall-clock dates; elapsed time and waits use the Effect 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). */
+    /** External slot delivery owns cron timers and catch-up; local wake polling still runs. */
     externalClock?: boolean;
 }
-/** 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. */
+/**
+ * The iterator is a Promise port inside an uninterruptible claimed occurrence, including its cleanup.
+ *
+ * WHAT THE TURN SAID IS NOT LOGGED. It is already durable: every fire runs in the session named in the line below
+ * (`routine:<name>` for a cron, the asking conversation for a wake-up), and a session is persisted under
+ * EXPORTED for the API path (`POST /run`), which runs the same turn without a claim: it has no occurrence to
+ * claim, because nobody's grid produced it (schedule/run.ts). The resident clock's own claim/run/settle is
+ * {@link fireRoutineOnce}.
+ *
+ * `<stateRoot>/sessions/` like any other. Copying the reply into the log would be a second store of the same text,
+ * unstructured, in a stream with a wider audience and a bound that differs per host.
+ */
+export declare function runTurn(agent: Agent, label: string, session: string, prompt: string): Effect.Effect<{
+    busy: boolean;
+    failed: string | undefined;
+    ms: number;
+} | {
+    busy: boolean;
+    failed: string;
+    ms: number;
+}, never, never>;
 export interface ScheduleFireOutcome {
     fired: boolean;
-    /** Set when a slot-keyed fire was skipped because that slot (or a later one) was already claimed. */
+    /** A delivery whose slot was already claimed, or which is older than the newest claim (a stale replay). */
     skippedReason?: string;
     failed?: string;
+    /**
+     * The occurrence was claimed but the turn was refused because the previous one is still running — the overlap
+     * policy, not a fault. Reported apart from `failed` because an operator reacts to the two differently, and a
+     * clock that reads `failed` on a public route would be reading an error that is not one.
+     */
+    skipped?: true;
     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: {
+/** Shared resident/external claim → run → settle. */
+export declare function fireRoutineOnce(opts: {
     agent: Agent;
     stateRoot: string;
-    schedule: LoadedSchedule;
-    slot?: Date;
+    routine: LoadedRoutine;
+    /** The instant this fire is FOR. Two schedulers agree on it, which is what makes the claim exclude. */
+    slot: Date;
     now?: () => Date;
-}): Promise<ScheduleFireOutcome>;
-export declare function createScheduler({ agent, stateRoot, schedules, now, externalClock, }: SchedulerOptions): Scheduler;
+}): Effect.Effect<ScheduleFireOutcome, PortFailure>;
+export declare function createScheduler(options: SchedulerOptions): Effect.Effect<Scheduler>;