@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/scaffold/init.js

@@ -1,71 +1,32 @@
-/**
- * Init: scaffold a runnable fastagent agent, offline. Default = a COMPLETE agent (persona.md +
- * the writing-great-skills skill + a fetch-url code tool + fastagent.config.mjs + package.json +
- * .gitignore + .secrets/); `--minimal` drops the code tool and package.json. persona.md is the agent's
- * identity (prompt segment ①); an existing AGENTS.md is never written or touched — it is project
- * context (②), kept as-is. skills/ and tools/ are the agent's self-editable capabilities (re-read each
- * turn).
- *
- * Placement — no detection and no prompt, just a default and one flag. By DEFAULT the whole agent —
- * definition, config, `.secrets/`, machinery — lands in `<dir>/fastagent/`; the surrounding tree gets
- * ZERO writes and becomes the workspace the agent works on. `--agent-dir <name>` picks another name for
- * that directory (`fastagent.config.*` is the marker of what IS an agent, never the name), and `--agent-dir .`
- * (spelled `--flat`) lands the identical shape in `dir` itself, for the case where the directory IS the
- * agent (a standalone agent repo, a monorepo package).
- *
- * Which of the two a served agent turns out to be is NOT decided here: the workspace is whatever
- * fastagent is later pointed at (resolvePlacement). This module only chooses where the files land — so
- * its one placement duty is to refuse a target that the lookup would not return (see below).
- *
- * Scope: init is best-effort atomic for ORDINARY inputs — it never overwrites existing files,
- * preflights non-directory scaffold parents, and rolls back a partial write (files AND the
- * `fastagent/` tree it created for them, so a retry sees a clean slate). It does not defend against
- * every pathological target state (TOCTOU, FIFOs, disk-full): recover by delete-and-retry.
- *
- * Sibling scaffold modules: add-channel.ts (`add <channel>`), vendor-skill.ts (`add skill`). The files
- * this module writes are real templates under templates/, read through templates.ts.
- */
+/** Init: scaffold a runnable fastagent agent, offline. */
 import { lstat, mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve, sep } from "node:path";
-import { AGENT_CONFIG_NAMES, DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentDefinitionOwner, agentsAt, displayPath, ensureSecretsDir, exists, } from "../paths.js";
+import { AGENT_CONFIG_FILE, DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentDefinitionOwner, agentsAt, displayPath, exists, } from "../paths.js";
 import { baseTemplate, packageJson, toPackageName } from "./templates.js";
 import { fastagentVersion } from "../version.js";
-/** The agent directory name for a raw `--agent-dir` value: the default when unset, and `./bot` read as
- *  `bot` — `basename` already says that is what it means, so rejecting the spelling would be pedantry. */
+/** The agent directory name for a raw `--agent-dir` value: the default when unset, and `./bot` read as `bot`. */
 export function agentDirName(raw) {
     if (raw === undefined)
         return DEFAULT_AGENT_DIRNAME;
     const trimmed = raw.replace(/^\.[/\\]/, "");
     return trimmed === "" ? raw : trimmed;
 }
-/** Why `name` cannot be an agent directory name, or undefined when it can. It must stay ONE segment
- *  inside the target: anything else (a separator, `..`, an absolute path) would land the agent where the
- *  one-level lookup cannot see it — an agent nothing would ever serve.
+/**
+ * Why `name` cannot be an agent directory name, or undefined when it can.
  *
- *  Returns the CONSTRAINT, not a sentence: the CLI prefixes the flag it owns and reports it as the usage
- *  error it is (exit 2), while {@link scaffoldAgent} prefixes the option name for a programmatic caller,
- *  who never passed a flag and should not be told to fix one. */
+ * `"."` is refused along with every path: the definition always lands in a SUBDIRECTORY, and the directory around it
+ * is the workspace. The subdirectory also carries its own `package.json`, so a `fastagent.config.ts` never loads under
+ * the host repo's module settings.
+ */
 export function agentDirNameError(name) {
-    if (name === "." || (name !== "" && name !== ".." && name === basename(name)))
+    if (name !== "" && name !== "." && name !== ".." && name === basename(name))
         return undefined;
-    return (`must be a single directory name (or "." for the target itself) — a path would put the agent outside ` +
-        `the target directory, where fastagent would not find it`);
+    return (`must be a single directory name — the definition lives in a subdirectory, and the directory around it is ` +
+        `the workspace the agent works on (a path, or ".", would put it elsewhere)`);
 }
-/**
- * Scaffold a runnable agent into `<dir>/<agentDir>/` — or into `dir` itself when `agentDir` is `"."`
- * (both created if missing). Default is a complete agent (persona.md + the writing-great-skills skill +
- * a code tool + package.json); `--minimal` drops the code tool and package.json.
- *
- * A SUBDIRECTORY target must be empty (any content there is an unfinished agent or something unrelated,
- * and landing persona.md beside it would be a silent mix), while `"."` is a directory being adopted —
- * content is expected. So `"."` KEEPS every file that already exists (reported, never overwritten, never
- * verified) and refuses only on a config, which means the directory is already an agent. An existing
- * AGENTS.md is untouched either way: that is the project's context, adopted as-is.
- */
+/** Scaffold a runnable agent into `<dir>/<agentDir>/` (both created if missing). */
 export async function scaffoldAgent(dir, options = {}) {
-    const minimal = options.minimal ?? false;
     const root = agentDirName(options.agentDir);
-    const flat = root === ".";
     const invalid = agentDirNameError(root);
     if (invalid)
         throw new Error(`agentDir "${root}" ${invalid}`);
@@ -74,45 +35,35 @@ export async function scaffoldAgent(dir, options = {}) {
         content: baseTemplate(`skills/writing-great-skills/${name}`),
     });
     const files = [
-        // ① identity. AGENTS.md is deliberately NOT scaffolded: a fresh agent has no project context, and
-        // an existing repo already owns its AGENTS.md (kept untouched, read as ② context from the workspace).
+        // ① identity.
         { rel: join(root, "persona.md"), content: baseTemplate("persona.md") },
-        // The example skill: how to author skills well — the core of self-iteration. Markdown, so it
-        // ships in --minimal too. Vendored verbatim from mattpocock/skills (MIT); LICENSE sits beside it.
+        // The example skill: how to author skills well — the core of self-iteration.
         skill("SKILL.md"),
         skill("GLOSSARY.md"),
         skill("LICENSE"),
-        { rel: join(root, "fastagent.config.mjs"), content: baseTemplate("fastagent.config.mjs") },
-        // Two ignore files, scaffolded ONCE and owned by the author from then on — no command rewrites,
-        // reads or verifies them. The agent's own covers node_modules/machinery/a stray .env; `.secrets/`
-        // carries its own because the root file is the one the author has reason to edit, and git's
-        // nested-ignore precedence keeps the credentials protected whatever happens up there.
+        { rel: join(root, AGENT_CONFIG_FILE), content: baseTemplate(AGENT_CONFIG_FILE) },
+        // Two ignore files, scaffolded ONCE and owned by the author from then on — no command rewrites, reads or verifies
+        // them.
         { rel: join(root, ".gitignore"), content: baseTemplate("gitignore") },
         { rel: join(root, SECRETS_DIRNAME, ".gitignore"), content: baseTemplate("secrets.gitignore") },
         { rel: join(root, SECRETS_DIRNAME, ".env.example"), content: baseTemplate("env.example") },
-    ];
-    if (!minimal) {
-        files.push({ rel: join(root, "tools", "fetch-url.ts"), content: baseTemplate("tools/fetch-url.ts") }, 
-        // The agent's own manifest, named after the directory it serves (`<dir>-agent`) — except when it
-        // IS that directory, where it takes the name straight.
+        { rel: join(root, "tools", "fetch-url.ts"), content: baseTemplate("tools/fetch-url.ts") },
+        // The agent's own manifest, named after the directory it serves. Its `type: module` is why the definition gets a
+        // subdirectory of its own: a config file under a host repo's CommonJS manifest does not load.
         {
             rel: join(root, "package.json"),
-            content: packageJson(flat ? toPackageName(dir) : `${toPackageName(dir)}-agent`, await fastagentVersion()),
-        });
-    }
-    // Inside another agent's DEFINITION (its `skills/`, `tools/`, `channels/` or `schedules/`): the outer
-    // agent would load the new one as its own content. Note what this deliberately ALLOWS — a package
-    // inside an agent's repository, which is the author's tree and not part of what that agent loads.
+            content: packageJson(`${toPackageName(dir)}-agent`, await fastagentVersion()),
+        },
+    ];
+    // Inside another agent's DEFINITION (its `skills/`, `tools/`, `channels/` or `routines/`): the outer agent would
+    // load the new one as its own content.
     const owner = agentDefinitionOwner(dir);
     if (owner) {
         throw new Error(`"${dir}" is inside the definition of the agent at ${owner} — an agent scaffolded here would be ` +
             `part of THAT agent's surface, not one of its own. Init outside it.`);
     }
-    // Preflight scaffold parent dirs FIRST: a pre-existing non-directory there would make mkdir fail
-    // mid-loop AFTER the first write, leaving a half-scaffold — and a file or symlink named `fastagent`
-    // must be named as such here, before the occupancy check below tries to read it as a directory
-    // (lstat, not stat: a symlinked parent must be rejected, not followed — it would write outside the
-    // agent dir).
+    // Preflight scaffold parent dirs FIRST: a pre-existing non-directory there would make mkdir fail mid-loop AFTER the
+    // first write, leaving a half-scaffold.
     const parents = new Set();
     for (const file of files) {
         let p = dirname(file.rel);
@@ -127,52 +78,32 @@ export async function scaffoldAgent(dir, options = {}) {
             throw new Error(`cannot scaffold: "${rel}" exists and is not a directory (a regular file or symlink) — remove it, or init elsewhere`);
         }
     }
-    // Refuse an occupied agent dir. A config inside means it IS an agent already (name the marker so the
-    // message is actionable); any other content means an unfinished agent or something unrelated, and
-    // landing persona.md beside it would be a silent mix. Only ENOENT reads as "empty" — any other fault
-    // (EACCES…) must surface here rather than as a raw errno mid-write.
-    // (AGENTS.md outside is NOT a marker — it is context, adopted untouched.)
-    // `.DS_Store`/`.gitkeep`/`.keep` are not evidence of anyone's content: Finder noise, and the standard
-    // way to commit an empty directory (someone reserving the name in git ahead of init).
+    // Refuse an occupied agent dir.
     const occupants = (await readdir(join(dir, root)).catch((e) => {
         if (e.code === "ENOENT")
             return [];
         throw e;
     })).filter((f) => ![".DS_Store", ".gitkeep", ".keep"].includes(f));
-    // Could `dir` still SELECT the agent this run creates? SIBLINGS are fine — several agents at one level
-    // is a supported shape (different roles driving one repository), picked between by FASTAGENT_AGENT or
-    // the default name. A SHADOW is not: a config AT `dir` wins over everything inside it, so scaffolding
-    // under one (or scaffolding one over existing children) makes an agent the lookup can never return.
-    // The target itself is never in the way — a config already there means "already an agent", which the
-    // refusal below says in those words.
+    // Could `dir` still SELECT the agent this run creates?
     const existing = agentsAt(dir).filter((a) => a !== resolve(dir, root));
-    const shadowed = flat
-        ? existing // the new agent lands AT `dir` and hides everything inside it
-        : existing.filter((a) => a === resolve(dir)); // an agent AT `dir` hides the new one inside it
+    const shadowed = existing.filter((a) => a === resolve(dir)); // an agent AT `dir` hides the new one inside it
     if (shadowed.length > 0) {
         throw new Error(`"${dir}" already resolves to ${shadowed.map((a) => displayPath(process.cwd(), a) ?? a).join(", ")} — ` +
-            `an agent scaffolded ${flat ? "here" : `in ./${root}/`} would be hidden by it and never served ` +
+            `an agent scaffolded in ./${root}/ would be hidden by it and never served ` +
             `from "${dir}" (an agent AT a directory wins over any inside it). Use that agent, move it away, ` +
             `or init in a different directory.`);
     }
-    // ONE coordinate system for both refusals — `displayPath` is the shared policy (relative inside the
-    // cwd, absolute when it climbs out); the earlier pair mixed an absolute path with a basename-relative
-    // one, in adjacent branches of the same command.
+    // ONE coordinate system for both refusals — `displayPath` is the shared policy (relative inside the cwd, absolute
+    // when it climbs out).
     const target = displayPath(process.cwd(), join(dir, root)) ?? join(dir, root);
-    const config = occupants.filter((f) => AGENT_CONFIG_NAMES.includes(f));
-    if (config.length > 0) {
-        throw new Error(`"${target}" already has ${config.join(", ")} — already a fastagent agent`);
+    if (occupants.includes(AGENT_CONFIG_FILE)) {
+        throw new Error(`"${target}" already has ${AGENT_CONFIG_FILE} — already a fastagent agent`);
     }
-    // Only a SUBDIRECTORY target must be empty. `.` is a directory being adopted — content is expected,
-    // and every existing file is kept below.
-    if (!flat && occupants.length > 0) {
+    if (occupants.length > 0) {
         throw new Error(`"${target}" already holds ${occupants.join(", ")} — move it away first, or run ` +
             `\`fastagent init\` in a different directory`);
     }
-    // Which directories were OURS to create? "Empty" is not ownership: a user may have pre-created any of
-    // them (`--agent-dir .` adopts a directory that can already carry an empty `skills/` or `.secrets/`),
-    // and the rollback below must delete only what THIS run made. Recorded before the first write, since
-    // afterwards the two are indistinguishable.
+    // Which directories were OURS to create?
     const preexisting = new Set();
     for (const rel of parents)
         if (await exists(join(dir, rel)))
@@ -180,42 +111,18 @@ export async function scaffoldAgent(dir, options = {}) {
     const agentDirExisted = await exists(join(dir, root));
     await mkdir(dir, { recursive: true });
     const created = [];
-    const kept = [];
-    // ONE rollback scope: any failure removes what THIS run created — files AND the directories it made
-    // for them. Leaving the empty dirs behind would be worse than untidy: the occupancy refusal above
-    // would then report the next `init` as occupied, blaming the user for our own debris.
-    //
-    // `wx` never clobbers. A subdirectory target was proven empty, so EEXIST means a concurrent writer —
-    // an error. `.` is a directory being adopted, so an existing `.gitignore`/`package.json` is the
-    // author's — keep it and report it.
+    // ONE rollback scope: any failure removes what THIS run created — files AND the directories it made for them.
+    // `wx` so a collision is a failure: the target was checked empty above, so anything here appeared mid-run.
     try {
         for (const file of files) {
             const abs = join(dir, file.rel);
-            // The secrets dir carries a mode; every other directory here is ordinary. `init` is usually the
-            // FIRST of the four writers to create it, and whoever creates it decides the mode for the rest.
-            if (basename(dirname(abs)) === SECRETS_DIRNAME)
-                await ensureSecretsDir(dirname(abs));
-            else
-                await mkdir(dirname(abs), { recursive: true });
-            try {
-                await writeFile(abs, file.content, { flag: "wx" });
-                created.push(file.rel);
-            }
-            catch (e) {
-                if (!flat || e.code !== "EEXIST")
-                    throw e;
-                kept.push(file.rel);
-            }
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, file.content, { flag: "wx" });
+            created.push(file.rel);
         }
     }
     catch (error) {
-        // Best-effort rollback of a partial scaffold: anything that won't delete is left behind (the
-        // original error below is the one worth surfacing — a cleanup failure must not mask it). Files
-        // first, then the directories THIS RUN created, deepest first; `rmdir` additionally removes only
-        // what is empty, so a pre-existing sibling inside one of ours is never touched. The agent root goes
-        // last, and only when this run created it — "empty" was never proof of ownership. (Reaching here at all takes a
-        // real fs fault: the occupancy refusal above proved the target empty, so nothing else can fail
-        // mid-loop. The covered case is a permission fault before the first write.)
+        // Best-effort rollback of a partial scaffold.
         for (const rel of created.reverse())
             await rm(join(dir, rel), { force: true }).catch(() => { });
         for (const rel of [...parents].sort((a, b) => b.split(sep).length - a.split(sep).length)) {
@@ -226,5 +133,5 @@ export async function scaffoldAgent(dir, options = {}) {
             await rmdir(join(dir, root)).catch(() => { });
         throw error;
     }
-    return { dir, complete: !minimal, agentDir: root, created, kept };
+    return { dir, agentDir: root, created };
 }

package/dist/scaffold/templates/env.example

@@ -14,8 +14,12 @@
 # command: `FASTAGENT_AGENT=pm fastagent dev`.
 
 # --- Model selection (overrides fastagent.config) ---
-# Precedence: --model flag > FASTAGENT_MODEL > config. `fastagent dev` writes your first-run pick to
-# fastagent.config; set it here to override per-environment.
+# 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
+# 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
 
 # --- Serving (fastagent start) ---
@@ -29,5 +33,3 @@
 # the volume so a rotated OAuth credential persists across restarts. Set HERE it moves only
 # auth.json — a value inside .env cannot relocate the .env being read.
 # FASTAGENT_SECRETS_DIR=/data/.secrets
-# Override just the sessions path (default: <state root>/sessions):
-# FASTAGENT_SESSIONS_DIR=/data/sessions

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

@@ -0,0 +1,36 @@
+// fastagent.config.ts — deployment choices only (model / http; code tools auto-discover from tools/).
+// Your agent's identity lives in persona.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".
+//
+// `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";
+
+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;

package/dist/scaffold/templates.d.ts

@@ -2,10 +2,10 @@
 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.ts` is the channel adapter; the rest are companion tools. */
+/** 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. */
 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. */
+/** package.json for the complete agent. */
 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

@@ -1,9 +1,6 @@
 /**
- * Scaffold template ACCESS (data, not logic): readers for the real files `init`/`add` write into an
- * agent dir, plus the parametric pieces. Base agent 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.
+ * Scaffold template ACCESS (data, not logic): readers for the real files `init`/`add` write into an agent dir, plus
+ * the parametric pieces.
  */
 import { readFileSync, readdirSync } from "node:fs";
 import { basename, resolve } from "node:path";
@@ -12,10 +9,10 @@ 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.ts` is the channel adapter; the rest are companion tools. */
+/** 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. */
 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. */
+/** package.json for the complete agent. */
 export function packageJson(name, version) {
     return `${JSON.stringify({
         name,

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

@@ -13,11 +13,8 @@ export interface VendoredSkill {
     overwritten: boolean;
 }
 /**
- * Vendor an Agent Skills skill into `<agent dir>/skills/<name>/` from a giget ref (github default), a
- * local path, or a bare name (resolved against the local global skill dirs). Copy-in, git-tracked.
- * Refuses to overwrite unless `options.update` (then a plain git-tracked overwrite, never a merge).
- * Validates a staging copy with the runtime loader BEFORE replacing, so a bad fetch never destroys an
- * existing skill.
+ * Vendor an Agent Skills skill into `<agent dir>/skills/<name>/` from a giget ref (github default), a local path, or a
+ * bare name (resolved against the local global skill dirs).
  */
 export declare function vendorSkill(agentDir: string, source: string, options?: {
     update?: boolean;

package/dist/scaffold/vendor-skill.js

@@ -1,9 +1,6 @@
 /**
- * `fastagent add skill <source>`: vendor an Agent Skills skill into `<agent dir>/skills/<name>/` —
- * copy-in, git-tracked, never a runtime registry. Source is a giget ref (github default), a local
- * path, or a bare name (resolved against the local global skill dirs as an add-time copy source only).
- * Fetch → staging → validate → rollback-protected replace, so a bad fetch never destroys an existing
- * skill.
+ * `fastagent add skill <source>`: vendor an Agent Skills skill into `<agent dir>/skills/<name>/` — copy-in,
+ * git-tracked, never a runtime registry.
  */
 import { cp, mkdir, readdir, rename, rm, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -18,8 +15,8 @@ function skillNameFromSource(source) {
     return basename(noRef.replace(/\/+$/, ""));
 }
 /**
- * The skills/ path must be safe to write through: never follow a symlink that escapes the agent dir
- * (mkdir would), and reject a plain file with one clear message.
+ * The skills/ path must be safe to write through: never follow a symlink that escapes the agent dir (mkdir would), and
+ * reject a plain file with one clear message.
  */
 async function assertSkillsDirUsable(agentDir) {
     await assertInsideAgentDir(agentDir, "skills");
@@ -37,8 +34,10 @@ function isLocalSource(source) {
 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. */
+/**
+ * Local "global" skill dirs, used ONLY as an add-time vendoring source (a bare `add skill <name>` copies the match in,
+ * git-tracked).
+ */
 function findGlobalSkillSource(name) {
     for (const root of [join(homedir(), ".agents", "skills"), join(homedir(), ".pi", "agent", "skills")]) {
         if (existsSync(join(root, name, "SKILL.md")))
@@ -47,11 +46,8 @@ function findGlobalSkillSource(name) {
     return undefined;
 }
 /**
- * Vendor an Agent Skills skill into `<agent dir>/skills/<name>/` from a giget ref (github default), a
- * local path, or a bare name (resolved against the local global skill dirs). Copy-in, git-tracked.
- * Refuses to overwrite unless `options.update` (then a plain git-tracked overwrite, never a merge).
- * Validates a staging copy with the runtime loader BEFORE replacing, so a bad fetch never destroys an
- * existing skill.
+ * Vendor an Agent Skills skill into `<agent dir>/skills/<name>/` from a giget ref (github default), a local path, or a
+ * bare name (resolved against the local global skill dirs).
  */
 export async function vendorSkill(agentDir, source, options = {}) {
     const name = skillNameFromSource(source);
@@ -61,8 +57,7 @@ export async function vendorSkill(agentDir, source, options = {}) {
     const skillsDir = join(agentDir, "skills");
     await assertSkillsDirUsable(agentDir);
     const dest = join(skillsDir, name);
-    // A process can die between moving the old skill aside and installing staging. Never guess that an
-    // arbitrary hidden directory is ours or delete it: stop with the exact backup path for manual restore.
+    // A process can die between moving the old skill aside and installing staging.
     const skillEntries = await readdir(skillsDir).catch((error) => {
         if (error.code === "ENOENT")
             return [];
@@ -72,16 +67,15 @@ export async function vendorSkill(agentDir, source, options = {}) {
     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`).
+    // 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.
+    // 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.
     const staging = join(skillsDir, `.${name}.vendoring`);
     await rm(staging, { recursive: true, force: true }); // clear any leftover from a prior crash
     try {
@@ -102,9 +96,7 @@ export async function vendorSkill(agentDir, source, options = {}) {
             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).
+            // giget defaults a BARE ref to its own template registry, not github.
             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.
@@ -119,9 +111,7 @@ export async function vendorSkill(agentDir, source, options = {}) {
         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.
+    // Install with rollback: move the old skill to a unique backup, then put staging in place.
     const previous = join(skillsDir, `.${name}.previous-${randomUUID()}`);
     if (overwritten)
         await rename(dest, previous);
@@ -141,8 +131,8 @@ 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).
+    // 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);
     const rel = join("skills", name);
     const skill = def.skills.find((sk) => relative(agentDir, dirname(sk.filePath)) === rel);

package/dist/schedule/cron.d.ts

@@ -1,7 +1,11 @@
-/** The next scheduled instant STRICTLY AFTER `from` (in `tz`, default UTC), or undefined if the
- *  expression will never fire again. */
+/**
+ * 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. */
+/**
+ * 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.
+ */
 export declare function cronError(cron: string, tz: string | undefined): string | undefined;

package/dist/schedule/cron.js

@@ -1,19 +1,17 @@
+/** The one place that touches the cron library (`croner`). */
+import { Cron } from "croner";
 /**
- * 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).
+ * The next scheduled instant STRICTLY AFTER `from` (in `tz`, default UTC), or undefined if the expression will never
+ * fire again.
  */
-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. */
+/**
+ * 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.
+ */
 export function cronError(cron, tz) {
     if (tz !== undefined) {
         try {

package/dist/schedule/discover.d.ts

@@ -1,17 +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[]>;
+import { type DeclaredSecret } from "../declared-secrets.ts";
+import type { LoadedRoutine } from "./routine.ts";
 /**
- * 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 declare function loadSchedules(dir: string): Promise<{
-    schedules: LoadedSchedule[];
+export declare function loadRoutines(dir: string): Promise<{
+    routines: LoadedRoutine[];
+    /** What each loaded routine declared it needs, BY ROUTINE NAME and attributed to its file. Per
+     *  routine because a caller that runs exactly ONE of them (`fastagent routine run`) must not be stopped
+     *  by a sibling's credential, and because two routines declaring the same variable would
+     *  otherwise blame whichever file was read first. The clock flattens it (it runs all of them).
+     *  Data, not a check — only a serving path asserts it (src/declared-secrets.ts). */
+    secrets: Map<string, DeclaredSecret[]>;
     failures: ModuleLoadFailure[];
 }>;