@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/dist/cli/commands/fire.js

@@ -0,0 +1,45 @@
+/**
+ * `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 { relative, resolve, sep } from "node:path";
+import { loadDotEnv } from "../../env.js";
+import { loadConfig, resolveAgentDir, resolveAuthPathOverride } from "../../engines/pi/config.js";
+import { reportModuleLoadFailures } from "../../engines/pi/report.js";
+import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
+import { runInvokeStream } from "../../invoke-stream.js";
+import { installProxyFetch } from "../../proxy.js";
+import { loadSchedules } from "../../schedule/discover.js";
+import { scheduleSession } from "../../schedule/scheduler.js";
+import { failStartup } from "../fail.js";
+import { reportAuth, resolveFirstRunModel } from "../shared.js";
+export async function runFire(name, dirArg, opts) {
+    const fireDir = resolve(dirArg);
+    loadDotEnv(fireDir);
+    installProxyFetch();
+    await resolveFirstRunModel(fireDir, opts);
+    // Schedules are agent surface — discover them where dev/start/`schedule list` do (agentDir), not the
+    // run root, so `fire` sees the same set the scheduler serves in the kit layout.
+    const { config: fireConfig } = await loadConfig(fireDir).catch(failStartup);
+    const fireAgentDir = resolveAgentDir(fireDir, fireConfig);
+    const { schedules, failures } = await loadSchedules(fireAgentDir).catch(failStartup);
+    reportModuleLoadFailures(failures);
+    const schedule = schedules.find((s) => s.name === name);
+    if (!schedule) {
+        // Name the discovery path in the kit layout: a schedule misplaced at the run root should read as
+        // "wrong place", not "broken file".
+        const looked = fireAgentDir === fireDir ? "" : ` (looked in ${relative(fireDir, fireAgentDir).split(sep).join("/")}/schedules)`;
+        failStartup(new Error(`unknown schedule "${name}"${looked}. available: ${schedules.map((s) => s.name).join(", ") || "(none)"}`));
+    }
+    const { agent, modelSpec, authPath } = await createPiAgentFromWorkspace(fireDir, {
+        model: opts.model,
+        authPath: resolveAuthPathOverride(opts.authPath),
+    }).catch(failStartup);
+    console.error(`[fastagent] fire: ${name} (${modelSpec})`);
+    await reportAuth(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/info.d.ts

@@ -0,0 +1,7 @@
+export interface InfoOptions {
+    json?: boolean;
+    model?: string;
+    authPath?: string;
+    sessionsDir?: string;
+}
+export declare function runInfo(dirArg: string, opts: InfoOptions): Promise<void>;

package/dist/cli/commands/info.js

@@ -0,0 +1,108 @@
+/** `fastagent info [dir] [--json]`: print what the directory ASSEMBLES into, WITHOUT booting a server. Read-only. */
+import { resolve } from "node:path";
+import { loadDotEnv } from "../../env.js";
+import { discoverChannelFiles } from "../../engines/pi/channel.js";
+import { defaultAuthPath, defaultSessionsDir, loadConfig, resolveAgentDir, resolveAuthPathOverride, resolveModelSpec, resolveSessionsDirOverride, resolveStateRoot, } from "../../engines/pi/config.js";
+import { resolveWorkspaceTools } from "../../engines/pi/create.js";
+import { loadAgentDefinition } from "../../engines/pi/definition.js";
+import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { log } from "../../log.js";
+import { nextRun } from "../../schedule/cron.js";
+import { loadSchedules } from "../../schedule/discover.js";
+import { failStartup } from "../fail.js";
+export async function runInfo(dirArg, opts) {
+    const dir = resolve(dirArg);
+    loadDotEnv(dir); // skills/tools may read env at load time
+    const { config, path: configPath } = await loadConfig(dir).catch(failStartup);
+    const modelSpec = resolveModelSpec(opts.model, config);
+    // dir = the run root (cwd, whose AGENTS.md is ② context); the agent's own surface lives in agentDir.
+    const agentDir = resolveAgentDir(dir, config);
+    const definition = await loadAgentDefinition(agentDir, { cwd: dir }).catch(failStartup);
+    // A tool that fails to load, for any reason (a missing dep, a top-level throw, or just not being a
+    // tool), is isolated the same way everywhere (G2): info, dev, AND start report it and keep going with
+    // the tools that loaded. The `error`/`.catch` below only fires for a whole-load fault (an unreadable
+    // tools/ dir), not a single bad file.
+    const tools = await resolveWorkspaceTools(config, agentDir, dir)
+        .then((r) => ({
+        names: r.toolNames,
+        deferred: r.deferredToolNames,
+        collisions: r.toolCollisions,
+        failures: r.toolFailures,
+        error: undefined,
+    }))
+        .catch((e) => ({
+        names: [],
+        deferred: [],
+        collisions: [],
+        failures: [],
+        error: e.message,
+    }));
+    const channels = await discoverChannelFiles(agentDir).catch(failStartup);
+    // Loaded (imported + validated), not just discovered: info's job is "fix only what it reports", so a
+    // broken schedule file (bad cron/tz, failed import) must show up HERE, not first at dev/start — and
+    // loading is what makes the next fire instant printable. Consistent with tools (info imports those too).
+    const sched = await loadSchedules(agentDir).catch(failStartup);
+    const schedules = sched.schedules.map((s) => ({
+        name: s.name,
+        cron: s.cron,
+        tz: s.tz ?? null,
+        next: nextRun(s.cron, s.tz, new Date())?.toISOString() ?? null,
+    }));
+    // The default sessions/auth paths WITHOUT creating anything (info is read-only; dev/start mkdir/login
+    // create them, info must not).
+    const stateRoot = resolveStateRoot(dir);
+    const sessionsDir = resolveSessionsDirOverride(opts.sessionsDir) ?? defaultSessionsDir(stateRoot);
+    const authPath = resolveAuthPathOverride(opts.authPath) ?? defaultAuthPath(stateRoot);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            dir,
+            agentDir,
+            configPath: configPath ?? null,
+            model: modelSpec ?? null,
+            thinkingLevel: config.thinkingLevel ?? null,
+            context: definition.contextFiles.map((f) => f.path),
+            persona: definition.persona !== undefined,
+            skills: definition.skills.map((skill) => ({ name: skill.name, description: skill.description })),
+            tools: tools.names,
+            deferredTools: tools.deferred,
+            toolError: tools.error ?? null,
+            channels,
+            schedules,
+            scheduleFailures: sched.failures,
+            selfSchedule: config.selfSchedule ?? false,
+            stateRoot,
+            sessionsDir,
+            authPath,
+            diagnostics: definition.diagnostics,
+            skillCollisions: definition.collisions,
+            toolCollisions: tools.collisions,
+            toolFailures: tools.failures,
+        }, null, 2));
+        return;
+    }
+    console.log(`dir:      ${dir}`);
+    if (agentDir !== dir)
+        console.log(`agent:    ${agentDir}`);
+    console.log(`config:   ${configPath ?? "(none)"}`);
+    console.log(`model:    ${modelSpec ?? "(not set — pass --model, set FASTAGENT_MODEL, or config.model)"}`);
+    if (config.thinkingLevel)
+        console.log(`thinking: ${config.thinkingLevel}`);
+    console.log(`context:  ${definition.contextFiles.map((f) => f.path).join(", ") || "(none)"}`);
+    console.log(`persona:  ${definition.persona ? "persona.md" : "(none)"}`);
+    console.log(`skills:   ${definition.skills.map((skill) => skill.name).join(", ") || "(none)"}`);
+    console.log(`tools:    ${tools.error ? "(could not load — see warning below)" : tools.names.join(", ") || "(none)"}`);
+    if (tools.deferred.length > 0)
+        console.log(`deferred: ${tools.deferred.join(", ")} (activated via search_tools)`);
+    console.log(`channels: ${channels.join(", ") || "(none)"}`);
+    console.log(`schedules: ${schedules.map((s) => `${s.name} (next ${s.next ?? "never"})`).join(", ") || "(none)"}`);
+    console.log(`selfSchedule: ${config.selfSchedule ? "on (mounts the wake tool when serving)" : "off"}`);
+    console.log(`state:    ${stateRoot}`);
+    console.log(`sessions: ${sessionsDir}`);
+    console.log(`auth:     ${authPath}`);
+    reportToolCollisions(tools.collisions);
+    reportModuleLoadFailures(tools.failures);
+    reportModuleLoadFailures(sched.failures);
+    if (tools.error)
+        log.warn(`[fastagent] ${tools.error}`);
+    reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+}

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

@@ -0,0 +1,8 @@
+export interface InitOptions {
+    minimal: boolean;
+    /** false ⇔ `--no-install`. */
+    install: boolean;
+    flat: boolean;
+    agentDir?: string;
+}
+export declare function runInit(dirArg: string, opts: InitOptions): Promise<void>;

package/dist/cli/commands/init.js

@@ -0,0 +1,81 @@
+/**
+ * `fastagent init [dir]`: scaffold a runnable agent and install its dependencies. Layout: flags force;
+ * otherwise the jurisdiction rule decides (see detectHostSignals) and the reason is printed.
+ * Deliberately no prompt — non-interactive executors (coding agents) get a deterministic default they
+ * can read and override.
+ */
+import { spawn } from "node:child_process";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { detectHostSignals, nextStepCd, scaffoldWorkspace } from "../../scaffold/init.js";
+import { failStartup, failUsage } from "../fail.js";
+export async function runInit(dirArg, opts) {
+    const dir = resolve(dirArg);
+    let agentDir;
+    let signals = [];
+    if (opts.agentDir) {
+        // Same containment contract loadConfig enforces on config.agentDir: an escaping value would write
+        // the kit outside the workspace AND produce a config that can never load — refuse up front.
+        // POSIX-normalized: this lands verbatim in the generated config (agentDir: "./a/b") and the persona
+        // locator note — a Windows `relative()` would write backslashes into both.
+        const rel = relative(dir, resolve(dir, opts.agentDir)).split(sep).join("/");
+        if (rel === "" || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) {
+            // An invalid flag VALUE is a usage error (exit 2), same class as a value the parser rejects.
+            failUsage(`--agent-dir ("${opts.agentDir}") must be a subdirectory of ${dir}`);
+        }
+        agentDir = `./${rel}`;
+    }
+    else if (!opts.flat) {
+        signals = await detectHostSignals(dir).catch(failStartup);
+        if (signals.length > 0)
+            agentDir = "./agent";
+    }
+    const { complete, created, skipped, patched, intoNonEmpty, warnings } = await scaffoldWorkspace(dir, {
+        minimal: opts.minimal,
+        agentDir,
+    }).catch(failStartup);
+    // The layout reason prints only once the scaffold actually happened — an "already a workspace" refusal
+    // must not be preceded by an announced decision that then never takes place.
+    if (signals.length > 0) {
+        console.error(`[fastagent] found ${signals.join(", ")} — an existing toolchain/deploy claims this directory, so the agent kit goes into ./agent (its own namespace; config.agentDir points there). cwd stays this directory. Override: --flat`);
+    }
+    console.error(`[fastagent] initialized ${dir}${complete ? "" : " (minimal)"}${agentDir ? ` — agent kit in ${agentDir}` : ""}`);
+    if (created.length > 0)
+        console.error(`  created: ${created.join(", ")}`);
+    if (skipped.length > 0)
+        console.error(`  kept existing: ${skipped.join(", ")}`);
+    if (patched.length > 0)
+        console.error(`  updated: ${patched.join(", ")} (missing fastagent excludes appended)`);
+    if (intoNonEmpty && !agentDir) {
+        console.error(`  note: scaffolded flat into a non-empty directory (nothing claims it — the directory is the agent); use --agent-dir <name> to put the kit in a subdir instead`);
+    }
+    for (const w of warnings)
+        console.error(`[fastagent] warn: ${w}`);
+    // Install deps only for a complete agent whose package.json we just wrote (a kept one is not ours).
+    // The manifest lives with the kit (agentDir when set), so the install runs there — never against a
+    // host repo's own package.json.
+    const kitDir = resolve(dir, agentDir ?? ".");
+    const willInstall = complete && opts.install && created.includes(join(agentDir ?? ".", "package.json"));
+    let installFailed = false;
+    if (willInstall) {
+        console.error(`[fastagent] installing dependencies (npm install${agentDir ? ` in ${agentDir}` : ""})…`);
+        installFailed = (await npmInstall(kitDir)) !== 0;
+        if (installFailed)
+            console.error(`[fastagent] warn: npm install failed — run it manually in ${kitDir} before \`fastagent dev\``);
+    }
+    console.error(`  next steps:`);
+    const cdTarget = nextStepCd(process.cwd(), dir);
+    if (cdTarget)
+        console.error(`    cd ${cdTarget}`);
+    if (complete && (!opts.install || installFailed))
+        console.error(`    ${agentDir ? `(cd ${agentDir} && npm install)` : "npm install"}`);
+    console.error(`    fastagent dev   # serve locally and iterate`);
+    console.error(`    fastagent add skill <owner/repo/path>   # vendor more skills from GitHub`);
+}
+/** Run `npm install` in `cwd` (inherit stdio). Returns the exit code. */
+function npmInstall(cwd) {
+    return new Promise((resolveCode) => {
+        const child = spawn("npm", ["install"], { cwd, stdio: "inherit" });
+        child.on("close", (code) => resolveCode(code ?? 1));
+        child.on("error", () => resolveCode(1));
+    });
+}

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

@@ -0,0 +1,7 @@
+export interface InvokeOptions {
+    model?: string;
+    authPath?: string;
+    /** false ⇔ `--no-input`. */
+    input?: boolean;
+}
+export declare function runInvoke(message: string, dirArg: string, opts: InvokeOptions): Promise<void>;

package/dist/cli/commands/invoke.js

@@ -0,0 +1,29 @@
+/** `fastagent invoke <message> [dir]`: run ONE turn against the assembled agent, then exit. */
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { loadDotEnv } from "../../env.js";
+import { resolveAuthPathOverride } from "../../engines/pi/config.js";
+import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
+import { runInvokeStream } from "../../invoke-stream.js";
+import { installProxyFetch } from "../../proxy.js";
+import { failStartup } from "../fail.js";
+import { reportAuth, resolveFirstRunModel } from "../shared.js";
+export async function runInvoke(message, dirArg, opts) {
+    const invokeDir = resolve(dirArg);
+    loadDotEnv(invokeDir);
+    installProxyFetch();
+    await resolveFirstRunModel(invokeDir, opts);
+    const { agent, modelSpec, authPath } = await createPiAgentFromWorkspace(invokeDir, {
+        model: opts.model,
+        authPath: resolveAuthPathOverride(opts.authPath),
+    }).catch(failStartup);
+    console.error(`[fastagent] invoke: ${invokeDir} (${modelSpec})`);
+    await reportAuth(modelSpec, authPath);
+    // Fresh session per invoke (one-shot, no resume). runInvokeStream maps events→IO: reply→stdout,
+    // tool/failure→stderr, exit 1 iff the turn failed (so CI can gate on it).
+    const exitCode = await runInvokeStream(agent.invoke({ session: randomUUID() }, { text: message }), (text) => process.stdout.write(text), (line) => console.error(line));
+    process.stdout.write("\n");
+    // Always exit explicitly: the undici proxy agent's keep-alive sockets would otherwise hold the
+    // event loop open after a successful one-shot turn.
+    process.exit(exitCode);
+}

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

@@ -0,0 +1,6 @@
+export interface LoginOptions {
+    authPath?: string;
+    /** false ⇔ `--no-input`. */
+    input?: boolean;
+}
+export declare function runLogin(provider: string | undefined, opts: LoginOptions): Promise<void>;

package/dist/cli/commands/login.js

@@ -0,0 +1,63 @@
+/**
+ * `fastagent login [provider]`: authenticate a model provider into the project-level auth file
+ * (`<cwd>/.fastagent/auth.json`) by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`. The positional is
+ * the PROVIDER (not a dir), so the project is cwd — `cd` into your agent before logging in (running it
+ * from $HOME writes the global `~/.fastagent/auth.json`).
+ *
+ * Creates and self-ignores `<cwd>/.fastagent/` (the credential's gitignored home) BEFORE the auth flow,
+ * so the secret can never land untracked — a flow that then fails (bad provider, abort) leaves that
+ * empty state dir behind, by design (no secret without its `.gitignore`). Skipped for the HOME-global dir.
+ */
+import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
+import { loadDotEnv } from "../../env.js";
+import { defaultAuthPath, resolveAuthPathOverride, resolveStateRoot } from "../../engines/pi/config.js";
+import { ensureStateRootSelfIgnored, isUnderDir } from "../../engines/pi/definition.js";
+import { loginFlow } from "../../engines/pi/login.js";
+import { openExternalUrl } from "../../open-url.js";
+import { installProxyFetch } from "../../proxy.js";
+import { failStartup } from "../fail.js";
+import { isInteractive } from "../shared.js";
+export async function runLogin(provider, opts) {
+    const loginDir = process.cwd();
+    loadDotEnv(loginDir); // FASTAGENT_AUTH_PATH / a proxy (HTTPS_PROXY) may be configured in the project .env
+    installProxyFetch(); // the OAuth token exchange must go through HTTPS_PROXY (region-locked providers)
+    const stateRoot = resolveStateRoot(loginDir);
+    const authPath = resolveAuthPathOverride(opts.authPath) ?? defaultAuthPath(stateRoot);
+    // login is the command that CREATES the credential file, so the leak guard binds HERE too (not only
+    // in the opener): on an adapted project dir, a `login` before the first dev/start would otherwise
+    // leave the secret untracked-but-committable. Unlike the opener (which populates the WHOLE root, so
+    // it always self-ignores an in-tree root), login writes ONLY auth.json — so guard iff the credential
+    // actually lands under the in-tree root. An external `--auth-path`/`FASTAGENT_AUTH_PATH` writes
+    // nothing in-tree (don't create an empty `.fastagent`); the guard also skips the HOME-global root.
+    if (isUnderDir(authPath, stateRoot))
+        await ensureStateRootSelfIgnored(loginDir, stateRoot);
+    // login is inherently interactive — loginFlow renders provider/method menus and opens a browser (or
+    // prompts for a key). In a non-TTY (a pipe, CI, a coding-agent shell) the menu can't receive keystrokes
+    // and would hang; --no-input asks for the same posture explicitly. Fail fast with the reason instead
+    // of stalling on an unanswerable prompt. (After the secret-hygiene self-ignore above, which is cheap
+    // prep, so a later terminal login is safe.)
+    if (opts.input === false || !isInteractive()) {
+        failStartup(new Error(`login is interactive (it shows a menu and opens a browser) — run it in a terminal, not a pipe/CI`));
+    }
+    const io = terminalLoginIO();
+    const result = await loginFlow(io, { provider, authPath }).catch(failStartup);
+    console.error(`[fastagent] logged in to ${result.provider} (${result.method}) — saved to ${authPath}`);
+    process.exit(0); // the undici proxy agent's keep-alive sockets would otherwise hold the event loop open
+}
+/** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. */
+function terminalLoginIO() {
+    return {
+        async select(message, options) {
+            const r = await (options.length > 7 ? autocomplete : select)({ message, options });
+            return isCancel(r) ? undefined : r;
+        },
+        async prompt(message, opts) {
+            const r = opts?.hidden
+                ? await password({ message, signal: opts.signal })
+                : await clackText({ message, signal: opts?.signal });
+            return isCancel(r) ? undefined : r;
+        },
+        note: (message) => clackLog.info(message),
+        openUrl: openExternalUrl,
+    };
+}

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

@@ -0,0 +1 @@
+export declare function runModels(search: string | undefined): void;

package/dist/cli/commands/models.js

@@ -0,0 +1,15 @@
+/**
+ * `fastagent models [search]`: print every registered "provider/modelId"; `[search]` filters by
+ * substring. This module pulls the pi model catalog (heavy) — it is lazy-imported by the spec, so
+ * only an actual `models` invocation pays for it.
+ */
+import { formatModelsCommand } from "../../cli-models.js";
+import { listModels } from "../../engines/pi/config.js";
+import { createPiModels } from "../../engines/pi/models.js";
+export function runModels(search) {
+    const { lines, error } = formatModelsCommand(listModels(createPiModels()), search);
+    for (const spec of lines)
+        console.log(spec);
+    if (error)
+        console.error(error);
+}

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

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

@@ -0,0 +1,89 @@
+/**
+ * `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 { loadConfig, resolveAgentDir, resolveStateRoot } from "../../engines/pi/config.js";
+import { reportModuleLoadFailures } from "../../engines/pi/report.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 } 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 target = 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 target = resolve(dirArg);
+    loadDotEnv(target);
+    const { config } = await loadConfig(target).catch(failStartup);
+    const agentDir = resolveAgentDir(target, config);
+    const { schedules, failures } = await loadSchedules(agentDir).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 target = 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/cli/commands/start.d.ts

@@ -0,0 +1,10 @@
+export interface StartOptions {
+    port?: string;
+    model?: string;
+    sessionsDir?: string;
+    authPath?: string;
+    tunnel?: boolean;
+    /** false ⇔ `--no-input`. */
+    input?: boolean;
+}
+export declare function runStart(dirArg: string, opts: StartOptions): Promise<void>;

package/dist/cli/commands/start.js

@@ -0,0 +1,90 @@
+/**
+ * `fastagent start [dir]`: run the agent in production posture — the SAME assembly as dev (your
+ * directory is the agent), just no file-watching. No build step: start reads the definition directly.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { authSeedBytes } from "../../deploy/fly/run.js";
+import { loadDotEnv } from "../../env.js";
+import { defaultAuthPath, resolveAuthPathOverride, resolveSessionsDirOverride, resolveStateRoot, } from "../../engines/pi/config.js";
+import { isUnderDir } from "../../engines/pi/definition.js";
+import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
+import { log, setLogLevel } from "../../log.js";
+import { logAgentLoop } from "../../observe.js";
+import { installProxyFetch } from "../../proxy.js";
+import { exists } from "../../scaffold/init.js";
+import { failStartup } from "../fail.js";
+import { maybeTunnel, routesFor, serve, startSchedules } from "../serve.js";
+import { parsePort, reportAuth, resolveFirstRunModel } from "../shared.js";
+export async function runStart(dirArg, opts) {
+    const dir = resolve(dirArg);
+    setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
+    const portFlag = parsePort(opts.port, "--port", "flag");
+    loadDotEnv(dir);
+    installProxyFetch();
+    await resolveFirstRunModel(dir, opts);
+    // A `deploy --run` may carry the operator's local credential as FASTAGENT_AUTH_SEED —
+    // materialize it onto the writable state root BEFORE the opener resolves auth (once, absent-only).
+    const authPathOverride = resolveAuthPathOverride(opts.authPath);
+    await maybeSeedAuth(authPathOverride ?? defaultAuthPath(resolveStateRoot(dir)));
+    // The same opener dev uses (single assembly source), just no watch.
+    const sessionsDirOverride = resolveSessionsDirOverride(opts.sessionsDir);
+    const { agent, definition, agentDir, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await createPiAgentFromWorkspace(dir, {
+        model: opts.model,
+        sessionsDir: sessionsDirOverride,
+        authPath: authPathOverride,
+        serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
+    }).catch(failStartup);
+    log.info(`[fastagent] start:  ${dir}`);
+    if (agentDir !== dir)
+        log.info(`[fastagent] agent:  ${agentDir}`);
+    log.info(`[fastagent] model:  ${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
+    await reportAuth(modelSpec, authPath);
+    log.info(`[fastagent] context: ${definition.contextFiles.map((f) => f.path).join(", ") || "(none)"}`);
+    if (definition.persona)
+        log.info(`[fastagent] persona: persona.md`);
+    log.info(`[fastagent] skills: ${definition.skills.map((s) => s.name).join(", ") || "(none)"}`);
+    if (toolNames.length > 0)
+        log.info(`[fastagent] tools:  ${toolNames.join(", ")}`);
+    if (deferredToolNames.length > 0) {
+        log.info(`[fastagent] deferred: ${deferredToolNames.join(", ")} (activated via search_tools)`);
+    }
+    reportToolCollisions(toolCollisions);
+    reportModuleLoadFailures(toolFailures);
+    log.info(`[fastagent] state:  ${stateRoot}`);
+    log.info(`[fastagent] sessions: ${sessionsDir}`);
+    // State defaults under the definition dir, which a redeploy may replace wholesale. Gate on where the
+    // root ACTUALLY resolved (in-tree?), not on the raw env var: an empty `FASTAGENT_STATE_DIR=""` reads
+    // as unset (resolveStateRoot) and still lands in-tree, so a raw `=== undefined` check would wrongly
+    // silence the warning. A sessions/auth override to a volume does not help — channel state (the
+    // telegram turn/context files replay depends on) is still in-tree.
+    if (isUnderDir(stateRoot, dir)) {
+        log.info(`[fastagent] note: state (auth, sessions, channel state) lives under the definition dir; point ` +
+            `FASTAGENT_STATE_DIR at a persistent volume so a redeploy that replaces the dir does not wipe it.`);
+    }
+    reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+    // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
+    const traced = logAgentLoop(agent);
+    const routes = await routesFor(agentDir, traced, stateRoot).catch(failStartup);
+    await startSchedules(agentDir, traced, stateRoot, config.selfSchedule ?? false);
+    serve(routes, portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, (p) => maybeTunnel(agentDir, p, opts.tunnel ?? false));
+    // No graceful drain: webhook turns run fire-and-forget; SIGTERM just exits mid-turn. Whether an
+    // in-flight turn is LOST depends on the channel: the Telegram channel persists turn intent pre-ACK
+    // and replays it next start (turn-store.ts, L1 durable execution, at-least-once); HTTP and other
+    // channels have no such layer, so their in-flight turns are still lost (the asker re-invokes).
+}
+/**
+ * Materialize `FASTAGENT_AUTH_SEED` (base64 of an auth.json, set by `deploy --run`) onto the
+ * writable state root ONCE — only when the seed is set AND the auth file is absent, so a refreshed
+ * volume copy is never clobbered by the stale seed. Lets a deploy carry the operator's local
+ * OAuth/API credential so the box runs on the SAME subscription. No-op locally (the seed is unset).
+ */
+async function maybeSeedAuth(authPath) {
+    const bytes = authSeedBytes(process.env.FASTAGENT_AUTH_SEED, await exists(authPath));
+    if (!bytes)
+        return;
+    await mkdir(dirname(authPath), { recursive: true });
+    await writeFile(authPath, bytes);
+    log.info(`[fastagent] seeded ${authPath} from FASTAGENT_AUTH_SEED (first boot)`);
+}

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

@@ -0,0 +1 @@
+export declare function runTool(name: string, argsJson: string, dirArg: string): Promise<void>;

package/dist/cli/commands/tool.js

@@ -0,0 +1,37 @@
+/** `fastagent tool <name> '<json>' [dir]`: run one tool's body directly with JSON args — no model. */
+import { resolve } from "node:path";
+import { loadDotEnv } from "../../env.js";
+import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
+import { resolveWorkspaceTools } from "../../engines/pi/create.js";
+import { reportModuleLoadFailures } from "../../engines/pi/report.js";
+import { failStartup, failUsage } from "../fail.js";
+export async function runTool(name, argsJson, dirArg) {
+    const toolDir = resolve(dirArg);
+    loadDotEnv(toolDir); // a tool may read a key from .env
+    const { config } = await loadConfig(toolDir).catch(failStartup);
+    // The same tool set dev/start mount (defaults + config.tools + discovered, deduped), so the runner
+    // exercises exactly what gets served — a shadowed tool is surfaced, not silently run. Resolve agentDir
+    // like the openers so `fastagent tool` finds the SAME tools/ as dev/start when config.agentDir is set.
+    const agentDir = resolveAgentDir(toolDir, config);
+    const { tools, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, toolDir).catch(failStartup);
+    for (const c of toolCollisions) {
+        console.error(`[fastagent] warn: tool "${c.name}" (${c.source}) is shadowed by a default/config tool — not mounted`);
+    }
+    reportModuleLoadFailures(toolFailures);
+    const tool = tools.find((t) => t.name === name);
+    if (!tool) {
+        failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
+    }
+    let args;
+    try {
+        args = JSON.parse(argsJson);
+    }
+    catch {
+        failUsage(`invalid JSON args: ${argsJson}`); // malformed input syntax = usage error, exit 2
+    }
+    const result = await tool.execute(`cli-${name}`, args).catch(failStartup);
+    const out = result?.details !== undefined
+        ? result.details
+        : (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");
+    console.log(typeof out === "string" ? out : JSON.stringify(out, null, 2));
+}