@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/cli/commands/fire.js

@@ -1,38 +0,0 @@
-/**
- * `fastagent fire <name> [dir]`: run ONE schedule's turn immediately — the authoring loop for schedules
- * (like `invoke` is for a prompt). Fires `schedules/<name>.ts` now, without waiting for its cron, using
- * the schedule's stable session (faithful to the served behavior). Does NOT advance the schedule's fire
- * state — a test run must never make the scheduler skip the real next run.
- */
-import { join } from "node:path";
-import { displayPath } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../loader.js";
-import { createPiAgentFromDir } from "../../engines/pi/open.js";
-import { runInvokeStream } from "../invoke-stream.js";
-import { loadSchedules } from "../../schedule/discover.js";
-import { scheduleSession } from "../../schedule/scheduler.js";
-import { failStartup } from "../fail.js";
-import { enterAgentCommand, reportAuth } from "../shared.js";
-export async function runFire(name, dirArg, opts) {
-    const placement = await enterAgentCommand(dirArg, opts);
-    // Schedules are agent surface — discover them where dev/start/`schedule list` do (the agent
-    // dir), so `fire` sees the same set the scheduler serves.
-    const { schedules, failures } = await loadSchedules(placement.agentDir).catch(failStartup);
-    reportModuleLoadFailures(failures);
-    const schedule = schedules.find((s) => s.name === name);
-    if (!schedule) {
-        // Name the discovery path: a schedule misplaced in the workspace (outside the agent dir)
-        // should read as "wrong place", not "broken file".
-        failStartup(new Error(`unknown schedule "${name}" (looked in ${displayPath(process.cwd(), join(placement.agentDir, "schedules")) ?? "schedules"}). ` +
-            `available: ${schedules.map((s) => s.name).join(", ") || "(none)"}`));
-    }
-    const { agent, modelSpec, authPath } = await createPiAgentFromDir(placement.workspace, {
-        model: opts.model,
-        authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
-    }).catch(failStartup);
-    console.error(`[fastagent] fire: ${name} (${modelSpec})`);
-    await reportAuth(placement.agentDir, modelSpec, authPath);
-    const exitCode = await runInvokeStream(agent.invoke({ session: scheduleSession(name) }, { text: schedule.prompt }), (text) => process.stdout.write(text), (line) => console.error(line));
-    process.stdout.write("\n");
-    process.exit(exitCode);
-}

package/dist/cli/commands/schedule.d.ts

@@ -1,12 +0,0 @@
-/**
- * `fastagent schedule history <name> [dir]`: print the run audit for one schedule (or "wake") — fired
- * time, outcome, duration, reply/error. Read-only (reads `<stateRoot>/schedule/runs.jsonl`); the answer
- * to "did last night's run silently fail?". Text mode previews the reply/error; --json is the full record.
- */
-export declare function runScheduleHistory(name: string, dirArg: string, json: boolean): void;
-/** `fastagent schedule list [dir]`: everything that will fire — BOTH producers: the static `schedules/`
- *  files (with their next instant) and the agent's pending self-scheduled wake-ups. Read-only. */
-export declare function runScheduleList(dirArg: string, json: boolean): Promise<void>;
-/** `fastagent schedule cancel <id> [dir]`: remove a pending wake-up — the operator's kill switch (the
- *  agent's own is the `unwake` tool). Unlike unwake it is NOT session-scoped: the operator owns the box. */
-export declare function runScheduleCancel(id: string, dirArg: string): void;

package/dist/cli/commands/schedule.js

@@ -1,87 +0,0 @@
-/**
- * `fastagent schedule history|list|cancel` — the operator's surface over schedule state. history and
- * list are read-only; cancel is the kill switch for a pending wake-up (the agent's own is the `unwake`
- * tool). All three read the SAME state root the scheduler writes (FASTAGENT_STATE_DIR may live in .env).
- */
-import { resolve } from "node:path";
-import { loadDotEnv } from "../../env.js";
-import { resolveStateRoot } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../loader.js";
-import { readRuns } from "../../schedule/audit.js";
-import { nextRun } from "../../schedule/cron.js";
-import { loadSchedules } from "../../schedule/discover.js";
-import { listWakeups, removeWakeup } from "../../schedule/wakeups.js";
-import { failStartup, placementOrExit } from "../fail.js";
-/**
- * `fastagent schedule history <name> [dir]`: print the run audit for one schedule (or "wake") — fired
- * time, outcome, duration, reply/error. Read-only (reads `<stateRoot>/schedule/runs.jsonl`); the answer
- * to "did last night's run silently fail?". Text mode previews the reply/error; --json is the full record.
- */
-export function runScheduleHistory(name, dirArg, json) {
-    const { agentDir: target } = placementOrExit(resolve(dirArg));
-    loadDotEnv(target); // FASTAGENT_STATE_DIR may live in .env — read the SAME state root the scheduler wrote
-    const runs = readRuns(resolveStateRoot(target), name);
-    if (json) {
-        console.log(JSON.stringify(runs, null, 2));
-        return;
-    }
-    if (runs.length === 0) {
-        console.error(`no recorded runs for "${name}" (state: ${resolveStateRoot(target)})`);
-        return;
-    }
-    // The question is "did LAST NIGHT's run fail?" — so text mode tails the most recent runs (chronological
-    // within the tail); --json above returns the full history.
-    const TAIL = 20;
-    const shown = runs.slice(-TAIL);
-    if (runs.length > shown.length) {
-        console.error(`(showing the last ${shown.length} of ${runs.length} runs — --json for all)`);
-    }
-    for (const r of shown) {
-        const detail = r.error ?? r.reply ?? "";
-        const preview = detail.replace(/\s+/g, " ").slice(0, 100);
-        console.log(`${r.firedAt}  ${r.outcome.padEnd(9)} ${String(r.ms).padStart(6)}ms  ${preview}`);
-    }
-}
-/** `fastagent schedule list [dir]`: everything that will fire — BOTH producers: the static `schedules/`
- *  files (with their next instant) and the agent's pending self-scheduled wake-ups. Read-only. */
-export async function runScheduleList(dirArg, json) {
-    const { agentDir: target } = placementOrExit(resolve(dirArg));
-    loadDotEnv(target);
-    const { schedules, failures } = await loadSchedules(target).catch(failStartup);
-    reportModuleLoadFailures(failures);
-    const wakeups = listWakeups(resolveStateRoot(target));
-    if (json) {
-        console.log(JSON.stringify({
-            schedules: schedules.map((s) => ({ ...s, next: nextRun(s.cron, s.tz, new Date())?.toISOString() })),
-            wakeups,
-        }, null, 2));
-        return;
-    }
-    if (schedules.length === 0 && wakeups.length === 0) {
-        console.error(`nothing scheduled — no schedules/ files, no pending wake-ups (state: ${resolveStateRoot(target)})`);
-        return;
-    }
-    for (const s of schedules) {
-        const next = nextRun(s.cron, s.tz, new Date())?.toISOString() ?? "(never)";
-        console.log(`schedule  ${s.name.padEnd(20)} ${next}  cron ${s.cron}${s.tz ? ` ${s.tz}` : ""}`);
-    }
-    for (const w of wakeups) {
-        const kind = w.cron ? `cron ${w.cron}${w.tz ? ` ${w.tz}` : ""}` : "one-shot";
-        console.log(`wake      ${w.id}  ${w.fireAt}  ${kind}  session=${w.session}  ${w.prompt.slice(0, 60)}`);
-    }
-}
-/** `fastagent schedule cancel <id> [dir]`: remove a pending wake-up — the operator's kill switch (the
- *  agent's own is the `unwake` tool). Unlike unwake it is NOT session-scoped: the operator owns the box. */
-export function runScheduleCancel(id, dirArg) {
-    const { agentDir: target } = placementOrExit(resolve(dirArg));
-    loadDotEnv(target);
-    if (removeWakeup(resolveStateRoot(target), id)) {
-        // ponytail: the store's load→save is lock-free — a serving scheduler's claim-advance can race this
-        // write (window = ms around each fire). Tell the operator to verify; a lockfile/CAS is the upgrade
-        // path if it ever bites.
-        console.error(`[fastagent] cancelled wake-up ${id} — if a server is running, verify with \`fastagent schedule list\``);
-    }
-    else {
-        failStartup(new Error(`no pending wake-up ${id} (state: ${resolveStateRoot(target)}) — \`fastagent schedule list\` shows ids`));
-    }
-}

package/dist/github.d.ts

@@ -1,3 +0,0 @@
-/** `@fastagent-sh/fastagent/github` — the GitHub channel subpath export, kept off the root surface. */
-export { githubChannel, type GithubChannelOptions, type GithubEvent, type Intent, } from "./channels/github/github.ts";
-export type { Schema } from "@octokit/webhooks-types";

package/dist/github.js

@@ -1,2 +0,0 @@
-/** `@fastagent-sh/fastagent/github` — the GitHub channel subpath export, kept off the root surface. */
-export { githubChannel, } from "./channels/github/github.js";

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

@@ -1,23 +0,0 @@
-// fastagent.config.mjs — 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".
-export default {
-  // model: "openai-codex/gpt-5.5",
-  // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max); default "medium" (pi TUI parity)
-  http: { port: 8787 },
-  // selfSchedule: true, // mount the built-in `wake` tool: the agent schedules its own follow-up turns
-  //                     // ("check the deploy in 10 min"). Cron jobs need no opt-in — drop a schedules/<name>.ts.
-  // sessionControl: true, // serve /control/* for remote observation + steering (fastagent attach / Web panel)
-  // 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 carries them from your local env
-  //   apt: ["git"],          // extra apt packages baked into the image (git, ripgrep, …; default repos only)
-  // },
-};

package/dist/schedule/audit.d.ts

@@ -1,18 +0,0 @@
-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

@@ -1,57 +0,0 @@
-/**
- * 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/schedule.d.ts

@@ -1,35 +0,0 @@
-/**
- * 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

@@ -1,23 +0,0 @@
-/**
- * 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;
-}