@fastagent-sh/fastagent 0.13.0 → 0.14.0

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));
+}

package/dist/cli/fail.d.ts

@@ -0,0 +1,19 @@
+/** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
+export declare function stderrHasColors(): boolean;
+/**
+ * The ONE error prefix every error message carries — bold red when stderr renders color, plain
+ * otherwise. Errors are the only place the CLI uses color at all.
+ */
+export declare function errorPrefix(colors?: boolean): string;
+/**
+ * User-fixable startup problems (missing model / bad config / broken definition) are thrown as plain
+ * `Error` — print just the message. Anything else (TypeError, non-Error) is a bug: keep the stack.
+ * Shared by the kernel and the command modules; exit 1 (runtime failure).
+ */
+export declare function failStartup(error: unknown): never;
+/**
+ * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination
+ * discovered in a command body): print the message and exit 2 — the same class as a parse error.
+ * Exit codes follow responsibility, not the layer that happens to discover the problem.
+ */
+export declare function failUsage(message: string): never;

package/dist/cli/fail.js

@@ -0,0 +1,32 @@
+/** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
+export function stderrHasColors() {
+    return process.stderr.isTTY === true && (process.stderr.hasColors?.() ?? false);
+}
+/**
+ * The ONE error prefix every error message carries — bold red when stderr renders color, plain
+ * otherwise. Errors are the only place the CLI uses color at all.
+ */
+export function errorPrefix(colors = stderrHasColors()) {
+    return colors ? "\x1b[1;31mError:\x1b[0m" : "Error:";
+}
+/**
+ * User-fixable startup problems (missing model / bad config / broken definition) are thrown as plain
+ * `Error` — print just the message. Anything else (TypeError, non-Error) is a bug: keep the stack.
+ * Shared by the kernel and the command modules; exit 1 (runtime failure).
+ */
+export function failStartup(error) {
+    if (error instanceof Error && error.constructor === Error)
+        console.error(`${errorPrefix()} ${error.message}`);
+    else
+        console.error(errorPrefix(), error);
+    process.exit(1);
+}
+/**
+ * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination
+ * discovered in a command body): print the message and exit 2 — the same class as a parse error.
+ * Exit codes follow responsibility, not the layer that happens to discover the problem.
+ */
+export function failUsage(message) {
+    console.error(`${errorPrefix()} ${message}`);
+    process.exit(2);
+}

package/dist/cli/kernel.d.ts

@@ -0,0 +1,89 @@
+/**
+ * CLI kernel — commands as data. A {@link CommandSpec} carries everything the CLI surface needs
+ * (summary, args/flags, examples, narrative notes, a lazy `run`), and {@link buildProgram} renders
+ * the set through commander. Commander is called ONLY from this module; the notation specs are
+ * written in — docopt-style argument brackets (`<required>`/`[optional]`), the flag DSL
+ * (`--auth-path <file>`, `--no-x` negation), and the derived option keys ({@link optionKey}) — is a
+ * contract this module owns and validates at build time. Replacing the parser means re-implementing
+ * that notation here (one module), not editing the specs.
+ *
+ * Follows clig.dev: per-command help in four spellings (`-h`/`--help`/`help <cmd>`/bare-with-missing-args),
+ * examples in help, "did you mean" suggestions (never auto-run), and one exit-code policy — 0 success,
+ * 1 runtime failure (owned by the command bodies), 2 usage error (anything the parser itself rejects).
+ */
+import { Command } from "commander";
+/** One positional argument, in commander syntax: `<name>` required, `[dir]` optional. */
+export interface ArgSpec {
+    name: string;
+    description: string;
+    default?: string;
+    /** Closed value set — the parser rejects anything else as a usage error (exit 2). */
+    choices?: string[];
+}
+/** One flag, in the flag DSL: `--json`, or `--auth-path <file>` for a value-taking flag. */
+export interface FlagSpec {
+    flags: string;
+    description: string;
+    /** Parses but does not appear in help — for retired flags that should still explain themselves. */
+    hidden?: boolean;
+    /** Mutually exclusive with these {@link optionKey} values — validated at build time. */
+    conflicts?: string[];
+}
+export interface ExampleSpec {
+    cmd: string;
+    note?: string;
+}
+export interface CommandSpec {
+    name: string;
+    /** One line for the command list in the parent help. */
+    summary: string;
+    /** Longer description for the command's own help; defaults to `summary`. */
+    description?: string;
+    args?: ArgSpec[];
+    flags?: FlagSpec[];
+    /** Shown in an "Examples:" section of the command's help — clig: users reach for examples first. */
+    examples?: ExampleSpec[];
+    /** Narrative help (behavior, precedence rules, caveats) appended after the generated sections. */
+    notes?: string;
+    /** A group command (e.g. `schedule`) declares subcommands instead of `run`. */
+    subcommands?: CommandSpec[];
+    /**
+     * The implementation: positional args in declaration order (an optional arg without a default is
+     * `undefined`), then the parsed flags. Lazy-import the actual work so `fastagent <cmd>` pays only
+     * for the modules that command uses. Runtime failures exit 1 from inside (fail visibly).
+     */
+    run?: (args: (string | undefined)[], flags: Record<string, unknown>) => Promise<void> | void;
+}
+/** Program-level configuration. Output/exit/width seams let tests drive the program in-process. */
+export interface ProgramOptions {
+    /** Printed by `-v`/`--version`. */
+    version?: string;
+    /** Top-level Examples — rendered by the same Help pipeline as every command's. */
+    examples?: ExampleSpec[];
+    /** Top-level closing prose (the docs link) — reflowed like any notes. */
+    notes?: string;
+    /**
+     * Fixed help width — a TEST seam. Production omits it: commander then adapts to the terminal
+     * (and falls back to 80 when piped), the modern behavior. Our verbatim Examples/notes text is
+     * hand-wrapped at ≤78 columns so it reads well at any width ≥ 80 (prose caps, like man pages).
+     */
+    helpWidth?: number;
+    /**
+     * Force help colors on/off — a TEST seam. Production omits it: commander detects per stream
+     * (color TTY → on; pipe, NO_COLOR, TERM=dumb → off) and strips every SGR code when off.
+     */
+    colors?: boolean;
+    out?: (chunk: string) => void;
+    err?: (chunk: string) => void;
+    exit?: (code: number) => never;
+}
+/**
+ * The option key a flag string yields on the parsed-flags record — THE naming rule specs rely on:
+ * camelCase of the long name (`--auth-path` → `authPath`); a `--no-x` flag negates and stores under
+ * `x` (absent ⇒ `x !== false`). Owned and enforced here so `conflicts` references and run-body reads
+ * answer to one authority, not to an implicit parser behavior. Throws on a flag without a long form
+ * (clig: every flag has a full-length spelling).
+ */
+export declare function optionKey(flags: string): string;
+/** Build the commander program for `specs`. The CLI entry parses with it; tests inject the IO seams. */
+export declare function buildProgram(specs: readonly CommandSpec[], options?: ProgramOptions): Command;