@fastagent-sh/fastagent 0.12.0

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

@@ -0,0 +1,82 @@
+---
+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
+---
+
+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.
+
+**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.
+
+## Invocation
+
+Two choices, trading different costs:
+
+- A **model-invoked** skill keeps a **description**, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to **context load** — the description sits in the window every turn. Mechanics: omit `disable-model-invocation`, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
+- A **user-invoked** skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends **cognitive load**: _you_ are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped.
+
+Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
+
+When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each.
+
+## Writing the description
+
+A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body:
+
+- **Front-load the skill's leading word** — the description is where it does its invocation work.
+- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
+- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause.
+
+## Information hierarchy
+
+A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a **completion criterion**, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites **premature completion**.
+2. **In-skill reference** — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._
+3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully **external reference** that lives outside the skill system and any skill can point at.)
+
+A demanding completion criterion drives thorough **legwork** — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material.
+
+Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it.
+
+## When to split
+
+**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts:
+
+- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to be worth it.
+- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view encourages the agent to do more **legwork** on the current task.
+
+## Pruning
+
+Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit.
+
+Check every line for **relevance**: does it still bear on what the skill does?
+
+Then hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten.
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.
+
+It serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word appears. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably.
+
+Hunt for opportunities to refactor skills to use leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. Examples include:
+
+- "fast, deterministic, low-overhead" -> _tight_ — one quality restated across a phase — into a single pretrained word (a _tight_ loop).
+- "a loop you believe in" -> _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).
+
+You win twice over: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.
+
+## Failure modes
+
+Use these to diagnose issues the user may be having with the skill.
+
+- **Premature completion** — ending a step before it's genuinely done, attention slipping to _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut).
+- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.
+- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.
+- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs.
+- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.

package/dist/scaffold/templates/tools/fetch-url.ts

@@ -0,0 +1,27 @@
+import { defineTool, z } from "@fastagent-sh/fastagent";
+
+// A code tool: filename (fetch-url.ts) is the tool name. tools/ is auto-discovered,
+// so it needs no registration in fastagent.config. Test it without a model:
+//   fastagent tool fetch-url '{"url":"https://example.com"}'
+// Serving this behind a public channel? The URL then comes from untrusted users — add an
+// allowlist or block private-network addresses (localhost, 169.254.169.254, …) to prevent SSRF.
+const MAX_TEXT = 20_000; // keep a huge page from flooding the model's context
+
+export default defineTool({
+  description: "Fetch a web page and return its readable text (HTML stripped, truncated).",
+  input: z.object({ url: z.url({ protocol: /^https?$/ }).describe("The http(s) URL to fetch") }),
+  async execute({ url }) {
+    const res = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(15_000) });
+    if (!res.ok) throw new Error(`GET ${url} failed: ${res.status} ${res.statusText}`);
+    const html = await res.text();
+    // ponytail: naive tag strip — fine for articles and docs; swap in a readability library if it falls short.
+    const entities: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'", nbsp: " " };
+    const text = html
+      .replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, " ")
+      .replace(/<[^>]+>/g, " ")
+      .replace(/&(amp|lt|gt|quot|#39|nbsp);/g, (_, e) => entities[e] ?? " ")
+      .replace(/\s+/g, " ")
+      .trim();
+    return { url: res.url, text: text.slice(0, MAX_TEXT), truncated: text.length > MAX_TEXT };
+  },
+});

package/dist/scaffold/templates.d.ts

@@ -0,0 +1,17 @@
+/** Read a base workspace template (src/scaffold/templates/<name>). */
+export declare const baseTemplate: (name: string) => string;
+/** The persona template; in the agentDir layout a locator note is appended (anchor-free — no silent-miss
+ *  risk) so the self-iteration guidance ("write skills beside this file") points into the kit, not the
+ *  run root — a skill written to the root `skills/` would never be scanned. */
+export declare function personaTemplate(agentDir?: string): string;
+/** The config template; when the kit is placed in a subdirectory, `agentDir` is injected as the first key. */
+export declare function configTemplate(agentDir?: 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.ts` is the channel adapter; the rest are companion tools. */
+export declare const channelBundleFiles: (kind: string) => string[];
+/** package.json for the complete agent. The @fastagent-sh/fastagent range tracks THIS build's
+ *  version, and tool authors use its `z` re-export rather than installing a second zod copy. */
+export declare function packageJson(name: string, version: 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

@@ -0,0 +1,56 @@
+/**
+ * Scaffold template ACCESS (data, not logic): readers for the real files `init`/`add` write into a
+ * workspace, plus the parametric pieces. Base workspace templates live under ./templates/; each
+ * channel's bundle lives WITH the channel at ../channels/<kind>/scaffold/ (so a channel owns its
+ * starter kit and could ship as its own package). Both trees are excluded from this package's tsc +
+ * biome (they import the published @fastagent-sh/fastagent, not this source) and copied into dist/ by the build.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, resolve } from "node:path";
+/** Read a base workspace template (src/scaffold/templates/<name>). */
+export const baseTemplate = (name) => readFileSync(new URL(`./templates/${name}`, import.meta.url), "utf8");
+/** The persona template; in the agentDir layout a locator note is appended (anchor-free — no silent-miss
+ *  risk) so the self-iteration guidance ("write skills beside this file") points into the kit, not the
+ *  run root — a skill written to the root `skills/` would never be scanned. */
+export function personaTemplate(agentDir) {
+    const base = baseTemplate("persona.md");
+    if (!agentDir)
+        return base;
+    return `${base}\nNote: your definition lives under \`${agentDir}/\` relative to the workspace root — this file is \`${agentDir}/persona.md\`, and a new skill goes to \`${agentDir}/skills/<name>/SKILL.md\` (a \`skills/\` at the root is not scanned).\n`;
+}
+/** The config template; when the kit is placed in a subdirectory, `agentDir` is injected as the first key. */
+export function configTemplate(agentDir) {
+    const base = baseTemplate("fastagent.config.mjs");
+    if (!agentDir)
+        return base;
+    const out = base.replace("export default {\n", `export default {\n  agentDir: ${JSON.stringify(agentDir)}, // the agent's own surface (persona.md / skills / tools / channels) lives there\n`);
+    // Fail visibly if the template drifted and the anchor no longer matches — a config that silently
+    // doesn't point at the kit would assemble an EMPTY agent with no error. Check the OPERATION happened
+    // (out !== base), not a substring — a commented `agentDir:` example in the template would fool that.
+    if (out === base)
+        throw new Error("configTemplate: anchor not found in fastagent.config.mjs template");
+    return out;
+}
+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.ts` is the channel adapter; the rest are companion tools. */
+export const channelBundleFiles = (kind) => readdirSync(channelScaffoldDir(kind)).filter((f) => f.endsWith(".ts"));
+/** package.json for the complete agent. The @fastagent-sh/fastagent range tracks THIS build's
+ *  version, and tool authors use its `z` re-export rather than installing a second zod copy. */
+export function packageJson(name, version) {
+    return `${JSON.stringify({
+        name,
+        private: true,
+        type: "module",
+        dependencies: { "@fastagent-sh/fastagent": `^${version}` },
+    }, null, 2)}\n`;
+}
+/** Sanitize a directory basename into a valid npm package name (lowercase, safe chars). */
+export function toPackageName(dir) {
+    const base = basename(resolve(dir))
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]/g, "-")
+        .replace(/^[._-]+/, "");
+    return base || "agent";
+}

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

@@ -0,0 +1,24 @@
+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`). */
+    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;
+}
+/**
+ * Vendor an Agent Skills skill into `<workspace>/skills/<name>/` from a giget ref (github default), a
+ * local path, or a bare name (resolved against the local global skill dirs). Copy-in, git-tracked.
+ * Refuses to overwrite unless `options.update` (then a plain git-tracked overwrite, never a merge).
+ * Validates a staging copy with the runtime loader BEFORE replacing, so a bad fetch never destroys an
+ * existing skill.
+ */
+export declare function vendorSkill(workspaceDir: string, source: string, options?: {
+    update?: boolean;
+}): Promise<VendoredSkill>;

package/dist/scaffold/vendor-skill.js

@@ -0,0 +1,157 @@
+/**
+ * `fastagent add skill <source>`: vendor an Agent Skills skill into `<workspace>/skills/<name>/` —
+ * copy-in, git-tracked, never a runtime registry. Source is a giget ref (github default), a local
+ * path, or a bare name (resolved against the local global skill dirs as an add-time copy source only).
+ * Fetch → staging → validate → rollback-protected replace, so a bad fetch never destroys an existing
+ * skill.
+ */
+import { cp, mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+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 { assertInsideWorkspace } from "../workspace.js";
+/** Derive the destination skill name from a source ref: the last path segment, sans `#ref`. */
+function skillNameFromSource(source) {
+    const noRef = source.split("#")[0] ?? source;
+    return basename(noRef.replace(/\/+$/, ""));
+}
+/**
+ * The skills/ path must be safe to write through: never follow a symlink that escapes the workspace
+ * (mkdir would), and reject a plain file with one clear message.
+ */
+async function assertSkillsDirUsable(workspaceDir) {
+    await assertInsideWorkspace(workspaceDir, "skills");
+    const skillsDir = join(workspaceDir, "skills");
+    const st = await stat(skillsDir).catch(() => undefined);
+    if (st && !st.isDirectory()) {
+        throw new Error(`${skillsDir} exists and is not a directory — remove it (skills must be a directory)`);
+    }
+}
+/** A local source is an explicit path (./x, ../x, /abs); anything else is a giget ref or a bare name. */
+function isLocalSource(source) {
+    return source.startsWith("./") || source.startsWith("../") || source === "." || isAbsolute(source);
+}
+/** A bare name (no `/`, no `scheme:`) resolves against the local global skill dirs (see below). */
+function isBareName(source) {
+    return !source.includes("/") && !/^[a-z][a-z0-9+.-]*:/i.test(source);
+}
+/** Local "global" skill dirs, used ONLY as an add-time vendoring source (a bare `add skill <name>`
+ *  copies the match in, git-tracked) — nothing is loaded from here at run time. */
+function findGlobalSkillSource(name) {
+    for (const root of [join(homedir(), ".agents", "skills"), join(homedir(), ".pi", "agent", "skills")]) {
+        if (existsSync(join(root, name, "SKILL.md")))
+            return join(root, name);
+    }
+    return undefined;
+}
+/**
+ * Vendor an Agent Skills skill into `<workspace>/skills/<name>/` from a giget ref (github default), a
+ * local path, or a bare name (resolved against the local global skill dirs). Copy-in, git-tracked.
+ * Refuses to overwrite unless `options.update` (then a plain git-tracked overwrite, never a merge).
+ * Validates a staging copy with the runtime loader BEFORE replacing, so a bad fetch never destroys an
+ * existing skill.
+ */
+export async function vendorSkill(workspaceDir, source, options = {}) {
+    const name = skillNameFromSource(source);
+    if (name === "" || name === "." || name === "..") {
+        throw new Error(`cannot derive a skill name from "${source}" — point at a skill directory (…/skills/<name>)`);
+    }
+    const skillsDir = join(workspaceDir, "skills");
+    await assertSkillsDirUsable(workspaceDir);
+    const dest = join(skillsDir, name);
+    // A process can die between moving the old skill aside and installing staging. Never guess that an
+    // arbitrary hidden directory is ours or delete it: stop with the exact backup path for manual restore.
+    const skillEntries = await readdir(skillsDir).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const interrupted = skillEntries.filter((entry) => entry.startsWith(`.${name}.previous-`));
+    if (interrupted.length > 0) {
+        throw new Error(`found an interrupted skill update backup (${interrupted.join(", ")}) — inspect it, then restore it to skills/${name} or remove it before retrying`);
+    }
+    // Refuse to clobber unless --update; a git-tracked overwrite is safe (review with `git diff`, undo
+    // with `git checkout`).
+    const overwritten = existsSync(dest);
+    if (overwritten && !options.update) {
+        throw new Error(`skills/${name} already exists — re-run with --update to overwrite it (git tracks the change), or remove it`);
+    }
+    await mkdir(skillsDir, { recursive: true });
+    // Fetch into a STAGING dir (same filesystem → atomic rename), validate, and only THEN replace dest,
+    // so a failed/invalid fetch never destroys an existing skill. The leading "." keeps the loader from
+    // treating staging as a skill.
+    const staging = join(skillsDir, `.${name}.vendoring`);
+    await rm(staging, { recursive: true, force: true }); // clear any leftover from a prior crash
+    try {
+        if (isLocalSource(source)) {
+            const src = resolve(source);
+            if (!existsSync(join(src, "SKILL.md"))) {
+                throw new Error(`"${source}" has no SKILL.md — an Agent Skills skill is a directory containing SKILL.md`);
+            }
+            await cp(src, staging, { recursive: true });
+        }
+        else if (isBareName(source)) {
+            // bare name → vendor from a local global skill dir (add-time copy, not a runtime scan).
+            const src = findGlobalSkillSource(source);
+            if (!src) {
+                throw new Error(`no skill "${source}" in your global skill dirs (~/.agents/skills, ~/.pi/agent/skills) — ` +
+                    `give a git ref (owner/repo/path) or a local path instead`);
+            }
+            await cp(src, staging, { recursive: true });
+        }
+        else {
+            // giget defaults a BARE ref to its own template registry, not github — so default the provider to
+            // github for a plain `owner/repo/path` (an explicit `github:`/`gh:`/`gitlab:`… scheme is kept).
+            // Supports a subdir + #ref, fetched via the tar API (no git binary).
+            const ref = /^[a-z][a-z0-9+.-]*:/i.test(source) ? source : `github:${source}`;
+            // Lazy import: giget is only needed for a git ref, so the serve path (index.ts → init.ts) and the
+            // local/bare-name sources never load it.
+            const { downloadTemplate } = await import("giget");
+            await downloadTemplate(ref, { dir: staging, force: true });
+        }
+        if (!existsSync(join(staging, "SKILL.md"))) {
+            throw new Error(`"${source}" did not yield a SKILL.md — expected an Agent Skills skill directory`);
+        }
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true }); // failed/invalid: drop staging, leave dest intact
+        throw error;
+    }
+    // Install with rollback: move the old skill to a unique backup, then put staging in place. A failed
+    // second rename restores it; a process crash leaves a backup the next invocation reports without
+    // touching it.
+    const previous = join(skillsDir, `.${name}.previous-${randomUUID()}`);
+    if (overwritten)
+        await rename(dest, previous);
+    try {
+        await rename(staging, dest);
+    }
+    catch (error) {
+        if (overwritten) {
+            try {
+                await rename(previous, dest);
+            }
+            catch (restoreError) {
+                throw new AggregateError([error, restoreError], `skill update failed and ${previous} could not be restored`);
+            }
+        }
+        throw error;
+    }
+    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(workspaceDir);
+    const rel = join("skills", name);
+    const skill = def.skills.find((sk) => relative(workspaceDir, dirname(sk.filePath)) === rel);
+    return {
+        name: skill?.name ?? name,
+        description: skill?.description,
+        dest: rel,
+        hasScripts: existsSync(join(dest, "scripts")),
+        diagnostics: def.diagnostics.filter((d) => d.path !== undefined && relative(workspaceDir, dirname(d.path)) === rel),
+        overwritten,
+    };
+}

package/dist/schedule/audit.d.ts

@@ -0,0 +1,18 @@
+export interface RunRecord {
+    /** The schedule's name for a cron fire; `"wake"` for a self-scheduled wake-up (its session tells which). */
+    name: string;
+    session: string;
+    firedAt: string;
+    ms: number;
+    /** `deferred` = a wake into a busy session, re-scheduled (not a final outcome for that wake-up). */
+    outcome: "completed" | "failed" | "deferred";
+    /** The turn's full reply text (completed). Delivery is the agent's tools' job — this is the audit copy. */
+    reply?: string;
+    /** The failure details (failed). */
+    error?: string;
+}
+/** Append one run record. Total — an audit-write failure is logged and swallowed (never breaks a fire). */
+export declare function appendRun(stateRoot: string, record: RunRecord): void;
+/** Read the run history (optionally filtered by name), oldest first. A malformed line is skipped with a
+ *  warn (fail-visible, like the wakeups store); a missing file is an empty history (first run). */
+export declare function readRuns(stateRoot: string, name?: string): RunRecord[];

package/dist/schedule/audit.js

@@ -0,0 +1,57 @@
+/**
+ * The scheduler's run audit: ONE line per fired turn in `<stateRoot>/schedule/runs.jsonl` — the answer
+ * to cron's classic pain, "did last night's run silently fail?". Append-only JSONL (grows, never
+ * rewritten — the same shape as the core session store), carrying the FULL reply text: a run record is
+ * an immutable snapshot of what that fire produced, which the rolling session (where multiple fires
+ * interleave with user turns) cannot give you per-fire. Operational audit only — the conversational
+ * truth stays in the session store.
+ *
+ * Appending is TOTAL (failures are logged, never thrown): the audit must not be able to break a fire.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { log } from "../log.js";
+function runsPath(stateRoot) {
+    return join(stateRoot, "schedule", "runs.jsonl");
+}
+/** Append one run record. Total — an audit-write failure is logged and swallowed (never breaks a fire). */
+export function appendRun(stateRoot, record) {
+    try {
+        const path = runsPath(stateRoot);
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify(record)}\n`);
+    }
+    catch (e) {
+        log.warn(`[schedule] could not append the run audit (the fire itself is unaffected): ${String(e)}`);
+    }
+}
+/** Read the run history (optionally filtered by name), oldest first. A malformed line is skipped with a
+ *  warn (fail-visible, like the wakeups store); a missing file is an empty history (first run). */
+export function readRuns(stateRoot, name) {
+    let raw;
+    try {
+        raw = readFileSync(runsPath(stateRoot), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        throw new Error(`run audit ${runsPath(stateRoot)} is unreadable: ${String(e)}`, { cause: e });
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (typeof r.name !== "string" || typeof r.firedAt !== "string" || typeof r.outcome !== "string") {
+                throw new Error("missing fields");
+            }
+            if (name === undefined || r.name === name)
+                records.push(r);
+        }
+        catch {
+            log.warn(`[schedule] skipping a malformed run-audit line: ${line.slice(0, 80)}`);
+        }
+    }
+    return records;
+}

package/dist/schedule/cron.d.ts

@@ -0,0 +1,7 @@
+/** The next scheduled instant STRICTLY AFTER `from` (in `tz`, default UTC), or undefined if the
+ *  expression will never fire again. */
+export declare function nextRun(cron: string, tz: string | undefined, from: Date): Date | undefined;
+/** Why `cron`/`tz` is invalid (for load-time validation), or undefined if valid. croner validates the
+ *  timezone lazily (not at construction), so check it explicitly via Intl (throws on an unknown IANA
+ *  zone); the pattern is validated by constructing the Cron. Both turned into a message, never a throw. */
+export declare function cronError(cron: string, tz: string | undefined): string | undefined;

package/dist/schedule/cron.js

@@ -0,0 +1,33 @@
+/**
+ * The one place that touches the cron library (`croner`). The scheduler owns FIRE control (for
+ * durability / overdue catch-up), so it borrows only croner's next-instant computation, not its
+ * scheduling. croner is chosen for zero transitive dependencies + built-in IANA timezone/DST handling
+ * (wall-clock schedules like "daily 9am America/New_York" need DST-correct arithmetic that hand-rolling
+ * gets wrong at the spring-forward / fall-back boundary).
+ */
+import { Cron } from "croner";
+/** The next scheduled instant STRICTLY AFTER `from` (in `tz`, default UTC), or undefined if the
+ *  expression will never fire again. */
+export function nextRun(cron, tz, from) {
+    return new Cron(cron, { timezone: tz ?? "UTC" }).nextRun(from) ?? undefined;
+}
+/** Why `cron`/`tz` is invalid (for load-time validation), or undefined if valid. croner validates the
+ *  timezone lazily (not at construction), so check it explicitly via Intl (throws on an unknown IANA
+ *  zone); the pattern is validated by constructing the Cron. Both turned into a message, never a throw. */
+export function cronError(cron, tz) {
+    if (tz !== undefined) {
+        try {
+            new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        }
+        catch {
+            return `unknown timezone "${tz}"`;
+        }
+    }
+    try {
+        new Cron(cron, { timezone: tz ?? "UTC" });
+        return undefined;
+    }
+    catch (e) {
+        return e.message;
+    }
+}

package/dist/schedule/discover.d.ts

@@ -0,0 +1,17 @@
+import { type ModuleLoadFailure } from "../loader.ts";
+import type { LoadedSchedule } from "./schedule.ts";
+/** 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 declare function discoverScheduleFiles(dir: string): Promise<string[]>;
+/**
+ * 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.
+ */
+export declare function loadSchedules(dir: string): Promise<{
+    schedules: LoadedSchedule[];
+    failures: ModuleLoadFailure[];
+}>;

package/dist/schedule/discover.js

@@ -0,0 +1,64 @@
+/**
+ * Schedule discovery (the N axis, clock form): a workspace 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.
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { isModuleFile, loadModuleDir } from "../loader.js";
+import { assertInsideWorkspace } from "../workspace.js";
+import { cronError } from "./cron.js";
+/** Schedule file basenames under `<dir>/schedules/` — an existence probe listed WITHOUT importing
+ *  (deploy pre-flight's time-trigger detection; `fastagent info` uses {@link loadSchedules} instead,
+ *  since it also reports broken files and next instants). */
+export async function discoverScheduleFiles(dir) {
+    await assertInsideWorkspace(dir, "schedules");
+    let names;
+    try {
+        names = await readdir(join(dir, "schedules"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    return names
+        .filter(isModuleFile)
+        .map((n) => n.replace(/\.(ts|js|mjs)$/, ""))
+        .sort();
+}
+/**
+ * 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.
+ */
+export async function loadSchedules(dir) {
+    await assertInsideWorkspace(dir, "schedules");
+    const { modules, failures } = await loadModuleDir(join(dir, "schedules"));
+    const byName = 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 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 });
+        }
+        catch (error) {
+            failures.push({ label, file, message: error.message });
+        }
+    }
+    return { schedules: [...byName.values()], failures };
+}

package/dist/schedule/schedule.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Schedule authoring: `defineSchedule` (the authoring surface). Drop a file in `schedules/`,
+ * default-export `defineSchedule({...})`, and it is discovered, named from the filename, and run by the
+ * scheduler — a time-trigger (the N axis, clock form) that fires the agent on a cron.
+ *
+ *   // schedules/daily-digest.ts        → schedule "daily-digest"
+ *   export default defineSchedule({
+ *     cron: "0 9 * * *",
+ *     tz: "America/New_York",
+ *     prompt: "Generate today's digest and send it to the team Telegram.",
+ *   });
+ *
+ * A schedule carries NO session field: a session id is runtime conversational context (the K side —
+ * host-provided per invoke, core.md §10.1 / §7), not a build-time (M) value. The scheduler derives a
+ * stable per-schedule session from the name at runtime (like
+ * the telegram channel derives one from chat.id), so a schedule's turns share one continuing
+ * conversation, persisted by the core session store. Output is the AGENT's tools' job — the scheduler
+ * only fires and logs, it does not deliver.
+ */
+/** A time-triggered invocation: at each `cron` instant (in `tz`, default UTC) the scheduler invokes the
+ *  agent with `prompt`. */
+export interface Schedule {
+    /** 5-field cron expression (`minute hour day-of-month month day-of-week`). */
+    cron: string;
+    /** IANA timezone for the cron (default "UTC"). Wall-clock schedules (daily 9am) need it. */
+    tz?: string;
+    /** The turn's text = the job's instruction. The agent's tools decide where any output goes. */
+    prompt: string;
+}
+/** Identity function for typing + IDE completion (like `defineTool`/`defineConfig`). */
+export declare function defineSchedule(schedule: Schedule): Schedule;
+/** A loaded schedule: its authored fields plus the name derived from its filename (authoritative). */
+export interface LoadedSchedule extends Schedule {
+    name: string;
+}

package/dist/schedule/schedule.js

@@ -0,0 +1,23 @@
+/**
+ * Schedule authoring: `defineSchedule` (the authoring surface). Drop a file in `schedules/`,
+ * default-export `defineSchedule({...})`, and it is discovered, named from the filename, and run by the
+ * scheduler — a time-trigger (the N axis, clock form) that fires the agent on a cron.
+ *
+ *   // schedules/daily-digest.ts        → schedule "daily-digest"
+ *   export default defineSchedule({
+ *     cron: "0 9 * * *",
+ *     tz: "America/New_York",
+ *     prompt: "Generate today's digest and send it to the team Telegram.",
+ *   });
+ *
+ * A schedule carries NO session field: a session id is runtime conversational context (the K side —
+ * host-provided per invoke, core.md §10.1 / §7), not a build-time (M) value. The scheduler derives a
+ * stable per-schedule session from the name at runtime (like
+ * the telegram channel derives one from chat.id), so a schedule's turns share one continuing
+ * conversation, persisted by the core session store. Output is the AGENT's tools' job — the scheduler
+ * only fires and logs, it does not deliver.
+ */
+/** Identity function for typing + IDE completion (like `defineTool`/`defineConfig`). */
+export function defineSchedule(schedule) {
+    return schedule;
+}