@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/scaffold/templates/SYSTEM.md

@@ -0,0 +1,12 @@
+# Standing instructions
+
+This file, `SYSTEM.md`, is your system prompt. It is read for every message along with the rest of your definition: `AGENTS.md` if there is one, `skills/` (capabilities you load when a task calls for them) and `prompts/` (prompt templates). An edit to any of them takes effect on your next message, no restart. Code in `src/` (tools, extensions, channels, schedules) loads when you start.
+
+Your definition is this directory: this file, `skills/`, `src/` and the config beside them. It is also your working directory, so a file you create lands here unless you put it elsewhere. Use only the tools actually listed in your system prompt.
+
+When your tools allow it, you can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
+
+- A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Read the `writing-great-skills` skill first; it is the guide to authoring skills well.
+- A standing instruction or fact → edit this file.
+
+Keep both lean: include only what changes your behavior, and delete what no longer earns its place.

package/dist/scaffold/templates/env.example

@@ -2,30 +2,24 @@
 # fastagent) and uncomment what you need. Everything here is OPTIONAL — the defaults work without a .env.
 
 # --- Model auth ---
-# Pick auth once: `fastagent login` (a subscription/OAuth provider like openai-codex, or an API key),
+# Pick auth once: `fastagent login` (an account such as ChatGPT for openai, or an API key),
 # or set a provider API key here — the variable name is provider-specific (e.g. OPENAI_API_KEY,
 # ANTHROPIC_API_KEY). `fastagent dev` then lets you choose a model from whatever you're logged into.
 # OPENAI_API_KEY=
 # ANTHROPIC_API_KEY=
 
-# --- Which agent (only when a workspace holds several) ---
-# FASTAGENT_AGENT names the agent directory to serve. It CANNOT be set here: placement resolves before
-# this file is read (it is what decides whose .env this is). Put it in your shell, an .envrc, or the
-# command: `FASTAGENT_AGENT=pm fastagent dev`.
-
 # --- Model selection (overrides fastagent.config) ---
 # Precedence: --model flag > FASTAGENT_MODEL > config — one chain, evaluated in whichever environment
-# is running. `fastagent dev` writes your first-run pick to fastagent.config; set it here to override
-# it. THIS FILE also declares the environment `fastagent deploy` resolves in, so a value here rides the
+# is running. THIS FILE also declares the environment `fastagent deploy` resolves in, so a value here rides the
 # release manifest into the deployment and a deployment can run a model the committed config does not
 # name. That recorded value outranks the deployed box's own .env, so switching models there means
 # editing this line and redeploying.
-# FASTAGENT_MODEL=openai-codex/gpt-5.5
+# FASTAGENT_MODEL=openai/gpt-5.5
 
 # --- Serving (fastagent start) ---
 # Port precedence: --port > PORT > config.http.port > 8787
 # PORT=8787
-# Machine-state root: sessions, schedule state, and channel state derive from it.
+# Machine-state root: the agent's storage, schedule state, and channel state live under it.
 # Default: <agent dir>/.state. Point it at a mounted volume so a redeploy that replaces the
 # directory keeps conversations.
 # FASTAGENT_STATE_DIR=/data/.state

package/dist/scaffold/templates/fastagent.config.ts

@@ -1,36 +1,24 @@
-// fastagent.config.ts — deployment choices only (model / http; code tools auto-discover from tools/).
-// Your agent's prompt lives in SYSTEM.md / APPEND_SYSTEM.md; its capabilities in skills/ + tools/ — never here.
-// An AGENTS.md in the WORKSPACE (the directory the agent is started in) is read as project context.
-// Model precedence: `--model` flag > FASTAGENT_MODEL env > this default.
-// No model is preset: `fastagent dev` shows the full model catalog (models you already have
-// credentials for come first; picking one that needs auth logs you in inline) and writes your choice
-// below. Or set it by hand to a "provider/modelId" (`fastagent models` lists them).
-// Self-hosted model (vLLM/Ollama/…) or your own gateway? Declare it in a models.json next to this
-// file and select it like any other spec — see docs/configuration.md "Custom model endpoints".
+// fastagent.config.ts — the agent's configuration: its default model and how it is served. Its prompt lives in
+// SYSTEM.md, its capabilities in skills/ and src/ (tools, extensions, channels, schedules) — never here.
 //
-// `satisfies` is what makes your editor complete these keys and describe them on hover — and what
-// turns a typo into an error you see while writing rather than one `fastagent dev` reports. The
-// import is TYPE-only: nothing is loaded at runtime. Every key is optional; the commented lines
-// below carry the default.
-import type { FastagentConfig } from "@fastagent-sh/fastagent";
+// Model precedence: `--model` flag > FASTAGENT_MODEL env > this default. No model is preset: `fastagent dev` shows
+// the model catalog (models you already have credentials for come first; picking one that needs auth logs you in
+// inline) and runs with your choice; set it below to keep it. `fastagent models` lists every "provider/modelId".
+// A self-hosted model (vLLM, Ollama, …) or your own gateway is a provider in code: `providers: [...]`, built with
+// pi-ai's `createProvider`.
+//
+// Every key is optional; the commented lines carry an example. `satisfies` is what makes your editor complete these
+// keys and turns a typo into an error you see while writing. The import is TYPE-only: nothing is loaded at runtime,
+// so the agent opens before `npm install` has run.
+import type { AgentConfig } from "@fastagent-sh/fastagent";
 
 export default {
-  // model: "openai-codex/gpt-5.5",
-  // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max); default "medium" (pi TUI parity)
-  // add `host: "127.0.0.1"` here to pin the bind address; default: `start` all interfaces (what containers
-  // need), `dev` loopback. `cors: ["https://your-app.example.com"]` pins which origins a browser may call
-  // this serve from. The default is `*` on every bind — any page your users visit can call this port and
-  // read the reply, a loopback bind included (it stops another machine, not your own browser).
-  // `invoke: false` withholds POST /invoke, for a serve meant to be reached only through its channels
-  // (POST /run goes with it; `run: true` keeps that one for a scheduler of yours that calls routines by name).
-  http: { port: 8787 },
-  // sessionControl: true, // serve /control/* for remote observation + steering (a Web panel, a desktop app)
-  // tools: [], // programmatically defined tools, appended after the coding ones — tools/ is the usual way
-  // deploy: what the agent needs on the box (so `fastagent deploy` doesn't need a hand-written Dockerfile
-  // or hand-set host variables). Uncomment as needed:
-  // deploy: {
-  //   secrets: ["GH_TOKEN"], // extra secret env vars your tools use — deploy reads their values from .secrets/.env
-  //   apt: ["git"],          // extra apt packages baked into the image (git, ripgrep, …; default repos only)
-  //   agentcore: { idleTimeoutSeconds: 180 }, // `deploy agentcore` only: idle microVM tail, 60–1209600s
-  // },
-} satisfies FastagentConfig;
+  // model: "openai/gpt-5.5",
+  // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max)
+  http: {
+    port: 8787, // the port a serve listens on, for its channels' webhooks and its health check
+    // api: false, // serve no Agent API under /v1, whatever key the environment holds; deploy gives none a key
+  },
+  // The commands the agent needs (CLIs, runtimes, apt packages) live in context.json: `fastagent env add gh`.
+  // deploy: { agentcore: { idleTimeoutSeconds: 180 } }, // `deploy agentcore` only: idle microVM tail, 60–1209600s
+} satisfies AgentConfig;

package/dist/scaffold/templates/gitignore

@@ -5,8 +5,15 @@
 # DIRECTORY, so a symlinked one (pnpm, a shared store) would show up as untracked.
 node_modules
 
-# machine state: sessions, channel state, schedule state
+# generated from src/ every time the agent opens
+.fastagent
+# machine state: the agent's storage, channel state, schedule state
 .state
+# where fastagent clones the agent's content (each clone is its repository's, not this one's). No trailing
+# slash: on a deployed host it is a link itself.
+/content
+# the directories of this machine the agent is bound to: this machine's, never the agent's
+/context.local.json
 .cache
 
 # fastagent reads the agent's env from .secrets/.env (which un-ignores its own .env.example). A bare

package/dist/scaffold/templates/skills/writing-great-skills/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: writing-great-skills
-description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
-disable-model-invocation: true
+description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable. Read it before writing or changing a skill.
 ---
 
 A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.

package/dist/scaffold/templates.d.ts

@@ -2,10 +2,15 @@
 export declare const baseTemplate: (name: string) => string;
 /** Read one file from a channel's scaffold bundle (src/channels/<kind>/scaffold/<name>). */
 export declare const channelTemplate: (kind: string, name: string) => string;
-/** The .ts files in a channel's bundle: `channel.*` are the channel templates (one per ingress —
- *  `channel.ts`, `channel.websocket.ts`); the rest are companion tools. */
+/** The .ts files in a channel's bundle: `channel.ts` is the channel template; the rest are companion tools. */
 export declare const channelBundleFiles: (kind: string) => string[];
-/** package.json for the complete agent. */
-export declare function packageJson(name: string, version: string): string;
+/**
+ * package.json for the complete agent: fastagent at this build's version, and the packages an agent's code is written
+ * against (its tools and extensions are pi-durable code, its providers pi-ai's) at the versions this build runs.
+ */
+export declare function packageJson(name: string, build: {
+    version: string;
+    harness: Record<string, string>;
+}): string;
 /** Sanitize a directory basename into a valid npm package name (lowercase, safe chars). */
 export declare function toPackageName(dir: string): string;

package/dist/scaffold/templates.js

@@ -9,16 +9,18 @@ export const baseTemplate = (name) => readFileSync(new URL(`./templates/${name}`
 const channelScaffoldDir = (kind) => new URL(`../channels/${kind}/scaffold/`, import.meta.url);
 /** Read one file from a channel's scaffold bundle (src/channels/<kind>/scaffold/<name>). */
 export const channelTemplate = (kind, name) => readFileSync(new URL(name, channelScaffoldDir(kind)), "utf8");
-/** The .ts files in a channel's bundle: `channel.*` are the channel templates (one per ingress —
- *  `channel.ts`, `channel.websocket.ts`); the rest are companion tools. */
+/** The .ts files in a channel's bundle: `channel.ts` is the channel template; the rest are companion tools. */
 export const channelBundleFiles = (kind) => readdirSync(channelScaffoldDir(kind)).filter((f) => f.endsWith(".ts"));
-/** package.json for the complete agent. */
-export function packageJson(name, version) {
+/**
+ * package.json for the complete agent: fastagent at this build's version, and the packages an agent's code is written
+ * against (its tools and extensions are pi-durable code, its providers pi-ai's) at the versions this build runs.
+ */
+export function packageJson(name, build) {
     return `${JSON.stringify({
         name,
         private: true,
         type: "module",
-        dependencies: { "@fastagent-sh/fastagent": `^${version}` },
+        dependencies: { "@fastagent-sh/fastagent": `^${build.version}`, ...build.harness },
     }, null, 2)}\n`;
 }
 /** Sanitize a directory basename into a valid npm package name (lowercase, safe chars). */

package/dist/scaffold/vendor-skill.d.ts

@@ -1,14 +1,11 @@
-import { type LoadedDefinition } from "../engines/pi/definition.ts";
 export interface VendoredSkill {
     /** The skill's real name (from SKILL.md frontmatter, per the Agent Skills spec). */
     name: string;
     description?: string;
-    /** Workspace-relative destination (e.g. `skills/pdf`). */
+    /** Agent-dir-relative destination (e.g. `skills/pdf`). */
     dest: string;
     /** The skill ships a `scripts/` dir (executable code) — a trust signal for the caller. */
     hasScripts: boolean;
-    /** Spec diagnostics for THIS skill from the runtime loader (e.g. name ≠ dir). */
-    diagnostics: LoadedDefinition["diagnostics"];
     /** True when an existing skill was overwritten (--update); false for a fresh vendor. */
     overwritten: boolean;
 }

package/dist/scaffold/vendor-skill.js

@@ -7,7 +7,7 @@ import { existsSync } from "node:fs";
 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 { readSkills } from "../harnesses/pi-durable/text.js";
 import { assertInsideAgentDir } from "../paths.js";
 /** Derive the destination skill name from a source ref: the last path segment, sans `#ref`. */
 function skillNameFromSource(source) {
@@ -131,17 +131,16 @@ export async function vendorSkill(agentDir, source, options = {}) {
     }
     if (overwritten)
         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(agentDir);
+    // Report via the loader the agent reads skills with, matching THIS skill by EXACT directory (a substring match
+    // would prefix-pollute a sibling `<name>-x` and break on Windows path separators). A skill it refuses is said by
+    // that loader, and is missing here.
     const rel = join("skills", name);
-    const skill = def.skills.find((sk) => relative(agentDir, dirname(sk.filePath)) === rel);
+    const skill = readSkills(agentDir).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(agentDir, dirname(d.path)) === rel),
         overwritten,
     };
 }

package/dist/schedule/cron.d.ts

@@ -9,3 +9,16 @@ export declare function nextRun(cron: string, tz: string | undefined, from: Date
  * constructing the Cron.
  */
 export declare function cronError(cron: string, tz: string | undefined): string | undefined;
+/**
+ * Why `cron`/`tz` cannot be something that recurs here, or undefined if it can: THE guard every recurring producer
+ * shares (a `schedules/` file, a recurring `wake`), because the agent can write both, and one written wrong must not
+ * run turns back to back. Two consecutive instants must be at least {@link MIN_RECURRING_GAP_MS} apart, which also
+ * refuses croner's six-field, per-second form.
+ *
+ * A function of the expression alone, so a file's verdict never flips with the time it is read. Two consecutive
+ * instants under 10 minutes apart are on one day or across one midnight, and the time-of-day fields repeat every day,
+ * so two days of the time-of-day form (the day fields made `*`, in UTC) hold every such gap. That is conservative:
+ * `0,55 0,23 * * 1` is refused for the 23:55 → 00:00 pair, though Tuesday never fires. A DST change only lengthens a
+ * gap (croner fires a repeated hour once). A year field is refused, since what repeats every year does not need one.
+ */
+export declare function recurringCronError(cron: string, tz: string | undefined): string | undefined;

package/dist/schedule/cron.js

@@ -29,3 +29,55 @@ export function cronError(cron, tz) {
         return e.message;
     }
 }
+/** The minimum gap between two consecutive fires of anything recurring: a schedule, or a recurring wake-up. */
+const MIN_RECURRING_GAP_MS = 10 * 60_000; // 10 minutes
+/** Where the check below starts: fixed, so its verdict is the cron's and never the hour it was asked in. */
+const ANCHOR = new Date("2024-01-01T00:00:00Z");
+const TWO_DAYS_MS = 2 * 24 * 60 * 60_000;
+/** One verdict per expression: the check walks up to ~300 instants, and every re-read of `schedules/` asks again. */
+const verdicts = new Map();
+/**
+ * Why `cron`/`tz` cannot be something that recurs here, or undefined if it can: THE guard every recurring producer
+ * shares (a `schedules/` file, a recurring `wake`), because the agent can write both, and one written wrong must not
+ * run turns back to back. Two consecutive instants must be at least {@link MIN_RECURRING_GAP_MS} apart, which also
+ * refuses croner's six-field, per-second form.
+ *
+ * A function of the expression alone, so a file's verdict never flips with the time it is read. Two consecutive
+ * instants under 10 minutes apart are on one day or across one midnight, and the time-of-day fields repeat every day,
+ * so two days of the time-of-day form (the day fields made `*`, in UTC) hold every such gap. That is conservative:
+ * `0,55 0,23 * * 1` is refused for the 23:55 → 00:00 pair, though Tuesday never fires. A DST change only lengthens a
+ * gap (croner fires a repeated hour once). A year field is refused, since what repeats every year does not need one.
+ */
+export function recurringCronError(cron, tz) {
+    const key = `${cron}\u0000${tz ?? ""}`;
+    if (!verdicts.has(key))
+        verdicts.set(key, judge(cron, tz));
+    return verdicts.get(key);
+}
+function judge(cron, tz) {
+    const invalid = cronError(cron, tz);
+    if (invalid)
+        return `invalid cron/tz: ${invalid}`;
+    const fields = cron.trim().split(/\s+/);
+    if (fields.length === 7)
+        return "a year field is not allowed: a recurring cron repeats every year";
+    const first = nextRun(cron, tz, ANCHOR);
+    if (!first || !nextRun(cron, tz, first))
+        return "this cron never fires, or fires only once";
+    // A nickname (`@hourly`) has no fields to separate, and is walked as it is.
+    const timeOfDay = fields.length === 5
+        ? `${fields[0]} ${fields[1]} * * *`
+        : fields.length === 6
+            ? `${fields[0]} ${fields[1]} ${fields[2]} * * *`
+            : cron;
+    const clock = new Cron(timeOfDay, { timezone: "UTC" });
+    const end = ANCHOR.getTime() + TWO_DAYS_MS;
+    for (let at = clock.nextRun(ANCHOR); at && at.getTime() < end;) {
+        const next = clock.nextRun(at);
+        if (next && next.getTime() - at.getTime() < MIN_RECURRING_GAP_MS) {
+            return `too frequent — it must fire at most every ${MIN_RECURRING_GAP_MS / 60_000} minutes`;
+        }
+        at = next;
+    }
+    return undefined;
+}

package/dist/schedule/eventbridge-cron.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A schedule's cron in EventBridge Scheduler's dialect: `cron(m h dom mon dow year)`, Quartz-flavoured, with exactly
+ * one of the two day fields `?` and 1 = Sunday. AgentCore fires each schedule from a recurring EventBridge schedule
+ * the container sets (schedule/wake-alarm.ts), so a schedule must translate to be one at all: discovery refuses one
+ * that does not, on every host, so that what runs locally also runs there.
+ */
+/**
+ * Translate a 5-field cron into EventBridge Scheduler's `cron(m h dom mon dow *)`, or say why it can't be. The two
+ * fire on the same instants in the same zone, with one exception at a DST change: a local time the spring change
+ * removes (02:30 in most of the US on that day) is skipped by EventBridge and run an hour later by croner, so such a
+ * schedule runs once more a year on a resident host. A time the autumn change repeats runs once in both.
+ */
+export declare function toEventBridgeCron(cron: string): {
+    expression: string;
+} | {
+    error: string;
+};

package/dist/schedule/eventbridge-cron.js

@@ -0,0 +1,88 @@
+/**
+ * A schedule's cron in EventBridge Scheduler's dialect: `cron(m h dom mon dow year)`, Quartz-flavoured, with exactly
+ * one of the two day fields `?` and 1 = Sunday. AgentCore fires each schedule from a recurring EventBridge schedule
+ * the container sets (schedule/wake-alarm.ts), so a schedule must translate to be one at all: discovery refuses one
+ * that does not, on every host, so that what runs locally also runs there.
+ */
+/**
+ * Remap ONE day-of-week field from standard cron numbering (0–7, 0 and 7 = Sunday) to EventBridge's (1–7,
+ * 1 = Sunday). Numeric items are EXPANDED to the days they select and written back as a list: endpoint-wise remapping
+ * cannot be right, since Sunday sits at both ends of one numbering and at the start of the other (`0-7` is every day,
+ * and remapping its endpoints gives `1-1`, Sundays only; `5-7` would wrap). Names mean the same day in both dialects
+ * and pass through.
+ */
+function mapDowField(dow) {
+    const days = new Set();
+    const named = [];
+    for (const item of dow.split(",")) {
+        const slash = item.split("/");
+        if (slash.length > 2 || slash.some((part) => part === "")) {
+            return { error: `malformed day-of-week token "${item}"` };
+        }
+        const [body, stepText] = slash;
+        if (stepText !== undefined && !/^\d+$/.test(stepText))
+            return { error: `malformed day-of-week step "${item}"` };
+        const endpoints = body === "*" ? ["0", "6"] : body.split("-");
+        if (endpoints.length > 2 || endpoints.some((part) => part === "")) {
+            return { error: `malformed day-of-week token "${item}"` };
+        }
+        if (endpoints.every((part) => !/^\d+$/.test(part))) {
+            named.push(item);
+            continue;
+        }
+        if (!endpoints.every((part) => /^\d+$/.test(part))) {
+            return { error: `day-of-week "${item}" mixes a name and a number` };
+        }
+        const from = Number(endpoints[0]);
+        // A single value with a step (`1/2`) runs to the end of the week, as in croner.
+        const to = endpoints.length === 2 ? Number(endpoints[1]) : stepText !== undefined ? 7 : from;
+        const step = stepText !== undefined ? Number(stepText) : 1;
+        if (from > 7 || to > 7 || from > to || step === 0)
+            return { error: `malformed day-of-week token "${item}"` };
+        for (let day = from; day <= to; day += step)
+            days.add(day % 7);
+    }
+    const numbers = [...days].map((day) => day + 1).sort((x, y) => x - y);
+    // Consecutive days back into ranges, for a readable expression.
+    const runs = [];
+    for (let i = 0; i < numbers.length;) {
+        let j = i;
+        while (j + 1 < numbers.length && numbers[j + 1] === numbers[j] + 1)
+            j++;
+        runs.push(j > i ? `${numbers[i]}-${numbers[j]}` : `${numbers[i]}`);
+        i = j + 1;
+    }
+    return { value: [...runs, ...named].join(",") };
+}
+/**
+ * Translate a 5-field cron into EventBridge Scheduler's `cron(m h dom mon dow *)`, or say why it can't be. The two
+ * fire on the same instants in the same zone, with one exception at a DST change: a local time the spring change
+ * removes (02:30 in most of the US on that day) is skipped by EventBridge and run an hour later by croner, so such a
+ * schedule runs once more a year on a resident host. A time the autumn change repeats runs once in both.
+ */
+export function toEventBridgeCron(cron) {
+    const fields = cron.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        return { error: `EventBridge supports 5-field cron only (got ${fields.length} fields)` };
+    }
+    const [min, hour, dom, mon, dow] = fields;
+    if (/[L#]/i.test(dow) || /[L#]/i.test(dom)) {
+        return { error: "L/# day forms don't translate to EventBridge numbering — set this schedule up manually" };
+    }
+    // `?` FIRST, and not as a synonym for `*`.
+    if (dom === "?" || dow === "?") {
+        return { expression: `cron(${min} ${hour} * ${mon} ? *)` };
+    }
+    if (dom !== "*" && dow !== "*") {
+        return {
+            error: "restricting BOTH day-of-month and day-of-week (cron OR semantics) is not expressible in EventBridge",
+        };
+    }
+    if (dow === "*") {
+        return { expression: `cron(${min} ${hour} ${dom} ${mon} ? *)` };
+    }
+    const mapped = mapDowField(dow);
+    if ("error" in mapped)
+        return mapped;
+    return { expression: `cron(${min} ${hour} ? ${mon} ${mapped.value} *)` };
+}

package/dist/schedule/schedule.d.ts

@@ -0,0 +1,23 @@
+/** As many schedules as one conversation may have pending wake-ups: the same bound on what the agent can set going. */
+export declare const MAX_SCHEDULES = 20;
+/** What an author writes. */
+export interface ScheduleConfig {
+    /** Five fields, minute first; checked when the definition is built. */
+    cron: string;
+    /** IANA timezone. Default: UTC. */
+    tz?: string;
+    /** What the agent is told when it fires: a text, or one made for the instant it fires for. */
+    prompt: string | ((fire: {
+        at: Date;
+    }) => string | Promise<string>);
+}
+/** A schedule as built: its name is its file's name. */
+export interface Schedule extends ScheduleConfig {
+    name: string;
+}
+/**
+ * Why `config` is not a schedule this agent can run, or undefined: the one rule the build applies. Its cron passes the
+ * guard a recurring wake-up passes, and is one AgentCore's clock (EventBridge) can express, so a schedule that runs
+ * locally also runs there.
+ */
+export declare function scheduleConfigProblem(config: ScheduleConfig): string | undefined;

package/dist/schedule/schedule.js

@@ -0,0 +1,34 @@
+/**
+ * A schedule: a prompt the definition runs on a cron, written in TypeScript as `defineSchedule` in `src/schedules/`
+ * (architecture.md §2), its name its file's. It is code, so it changes with a build and a deployment; the clock that
+ * fires it is scheduler.ts, or on AgentCore the recurring EventBridge schedule the container sets (wake-alarm.ts).
+ *
+ * WHAT IT IS NOT: a wake-up. The agent can schedule work for itself too (the `wake` tool, schedule/wakeups.ts). A
+ * schedule is written in the DEFINITION and a wake-up into the STATE by a running agent (minted id, cancellable, aimed
+ * back at the conversation it came from).
+ */
+import { recurringCronError } from "./cron.js";
+import { toEventBridgeCron } from "./eventbridge-cron.js";
+import { MAX_PENDING_WAKEUPS } from "./wakeups.js";
+/** As many schedules as one conversation may have pending wake-ups: the same bound on what the agent can set going. */
+export const MAX_SCHEDULES = MAX_PENDING_WAKEUPS;
+/**
+ * Why `config` is not a schedule this agent can run, or undefined: the one rule the build applies. Its cron passes the
+ * guard a recurring wake-up passes, and is one AgentCore's clock (EventBridge) can express, so a schedule that runs
+ * locally also runs there.
+ */
+export function scheduleConfigProblem(config) {
+    if (typeof config.prompt !== "string" && typeof config.prompt !== "function")
+        return "its prompt is a text or a function";
+    if (config.prompt === "")
+        return "its prompt is empty";
+    if (typeof config.cron !== "string")
+        return "its cron is a text";
+    const invalid = recurringCronError(config.cron, config.tz);
+    if (invalid !== undefined)
+        return invalid;
+    const translated = toEventBridgeCron(config.cron);
+    return "error" in translated
+        ? `AgentCore's clock (EventBridge) cannot express this cron: ${translated.error}`
+        : undefined;
+}

package/dist/schedule/scheduler.d.ts

@@ -1,44 +1,32 @@
 import * as Effect from "effect/Effect";
-import { type Agent } from "../agent.ts";
+import { type Agent } from "../agent-api.ts";
 import { PortFailure } from "../effect-port.ts";
-import { type LoadedRoutine } from "./routine.ts";
+import type { Schedule } from "./schedule.ts";
 export interface Scheduler {
-    /** Arm routines, account for a fire the previous run was killed in, and catch up overdue work once. */
+    /** Arm schedules, account for a fire the previous run was killed in, and catch up overdue work once. */
     start(): void;
     /** Cancel pending waits. */
     stop(): void;
 }
+/** All the scheduler asks of the agent. */
+export type ScheduledAgent = {
+    sessions: Pick<Agent["sessions"], "get" | "create">;
+    messages: Pick<Agent["messages"], "send" | "get">;
+};
 export interface SchedulerOptions {
-    agent: Agent;
+    agent: ScheduledAgent;
     stateRoot: string;
-    /** Every routine this serve loaded. Only the ones WITH a cron are armed — the rest are reached by name. */
-    routines: LoadedRoutine[];
+    /** The definition's schedules. */
+    schedules: readonly Schedule[];
+    /**
+     * Run a resident timer per schedule (default). Off where something outside the process delivers each instant as
+     * its own fire (AgentCore's recurring EventBridge schedules): one path per instant, so its delivery's reply says
+     * whether it ran.
+     */
+    localClock?: boolean;
     /** Override wall-clock dates; elapsed time and waits use the Effect clock. */
     now?: () => Date;
-    /** External slot delivery owns cron timers and catch-up; local wake polling still runs. */
-    externalClock?: boolean;
 }
-/**
- * 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;
     /** A delivery whose slot was already claimed, or which is older than the newest claim (a stale replay). */
@@ -47,18 +35,31 @@ export interface ScheduleFireOutcome {
     /**
      * 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.
+     * clock that reads `failed` would be reading an error that is not one.
      */
     skipped?: true;
     ms: number;
 }
 /** Shared resident/external claim → run → settle. */
-export declare function fireRoutineOnce(opts: {
-    agent: Agent;
+export declare function fireScheduleOnce(opts: {
+    agent: ScheduledAgent;
     stateRoot: string;
-    routine: LoadedRoutine;
+    schedule: Schedule;
     /** The instant this fire is FOR. Two schedulers agree on it, which is what makes the claim exclude. */
     slot: Date;
     now?: () => Date;
 }): Effect.Effect<ScheduleFireOutcome, PortFailure>;
+/**
+ * Fire `schedule` once, now, outside its clock (`fastagent schedules run`), the way its clock would: a newest claim no
+ * fire reported is accounted for first, as a boot does, then this instant is the slot, claimed and settled as any.
+ */
+export declare function fireScheduleNow(opts: {
+    agent: ScheduledAgent;
+    stateRoot: string;
+    schedule: Schedule;
+}): Effect.Effect<ScheduleFireOutcome & {
+    slot: Date;
+}, PortFailure>;
+/** Which session each schedule continues: one per schedule, so the agent sees what its earlier runs did. */
+export declare function scheduleSessions(stateRoot: string): import("../conversation-sessions.ts").ConversationSessions;
 export declare function createScheduler(options: SchedulerOptions): Effect.Effect<Scheduler>;