@fastagent-sh/fastagent 0.13.0 → 0.14.0

package/dist/cli/kernel.js

@@ -0,0 +1,190 @@
+/**
+ * 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 { Argument, Command, Help, InvalidArgumentError, Option } from "commander";
+import { errorPrefix } from "./fail.js";
+/**
+ * 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 function optionKey(flags) {
+    const long = flags
+        .split(/[\s,|]+/)
+        .filter((part) => part.startsWith("--"))
+        .at(-1);
+    if (!long)
+        throw new Error(`flag "${flags}" has no long form (clig: have full-length flags)`);
+    let name = long.replace(/^--/, "").replace(/[=<[].*$/, "");
+    if (name.startsWith("no-"))
+        name = name.slice(3);
+    return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+// Help styling (clig: formatting with intention): section headings are BOLD, nothing in help is
+// colored — the only color in the whole CLI is the red error prefix. The style is always embedded;
+// commander strips every SGR code from the assembled help whenever the target stream has no colors
+// (non-TTY pipe, NO_COLOR, TERM=dumb).
+const title = (s) => `\x1b[1m${s}\x1b[0m`; // bold — section headings
+/** The spec behind each registered command — how the Help renderer reaches Examples/notes. */
+const specOf = new WeakMap();
+/** Build the commander program for `specs`. The CLI entry parses with it; tests inject the IO seams. */
+export function buildProgram(specs, options = {}) {
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const program = new Command("fastagent");
+    program.description("Serve a file-defined agent — persona.md, skills/, tools/, channels/ — as a live service.");
+    // The exit-code policy: commander throws only for parse-level events — help/version displays carry
+    // exitCode 0 (→ 0), everything else it rejects is a usage error (→ 2). Runtime failures never pass
+    // through here; command bodies exit 1 themselves.
+    program.exitOverride((err) => exit(err.exitCode === 0 ? 0 : 2));
+    program.configureHelp({
+        ...(options.helpWidth !== undefined ? { helpWidth: options.helpWidth } : {}),
+        styleTitle: title,
+        // ONE renderer for the whole page: commander's standard sections, then our Examples/notes —
+        // rendered with the SAME helper (helpWidth, styleTitle), so custom sections wrap and style
+        // exactly like native ones on any terminal.
+        formatHelp: (cmd, helper) => Help.prototype.formatHelp.call(helper, cmd, helper) + extraSections(cmd, helper),
+    });
+    program.configureOutput({
+        ...(options.out ? { writeOut: options.out } : {}),
+        ...(options.err ? { writeErr: options.err } : {}),
+        ...(options.colors !== undefined
+            ? { getOutHasColors: () => options.colors, getErrHasColors: () => options.colors }
+            : {}),
+        // Every parse-level error carries the ONE unified prefix: bold-red `Error:` (plain when stderr
+        // has no colors). Command bodies get the same prefix through failStartup/failUsage.
+        outputError: (str, write) => write(str.startsWith("error:") ? `${errorPrefix(options.colors)}${str.slice("error:".length)}` : str),
+    });
+    program.showSuggestionAfterError(); // "did you mean models?" — suggest only, never run it (clig on DWIM)
+    program.showHelpAfterError("(run with --help for usage)");
+    if (options.version)
+        program.version(options.version, "-v, --version", "print the fastagent version");
+    if (options.examples || options.notes) {
+        specOf.set(program, { name: "fastagent", summary: "", examples: options.examples, notes: options.notes });
+    }
+    // Subcommands inherit exitOverride/output/suggestion settings at .command() time — register last.
+    for (const spec of specs)
+        register(program, spec);
+    return program;
+}
+function register(parent, spec) {
+    // Validate the spec's option references BEFORE handing anything to commander: every flag must
+    // have a long form (optionKey throws), and conflicts must name keys that exist on THIS command —
+    // commander matches conflicts by name at parse time, so a typo would otherwise silently never fire.
+    const keys = new Set((spec.flags ?? []).map((f) => optionKey(f.flags)));
+    for (const f of spec.flags ?? []) {
+        for (const target of f.conflicts ?? []) {
+            if (!keys.has(target)) {
+                throw new Error(`command "${spec.name}": "${f.flags}" conflicts with unknown option key "${target}"`);
+            }
+        }
+    }
+    const cmd = parent.command(spec.name);
+    specOf.set(cmd, spec);
+    cmd.summary(spec.summary);
+    cmd.description(spec.description ?? spec.summary);
+    for (const a of spec.args ?? []) {
+        const arg = new Argument(a.name, a.description);
+        if (a.default !== undefined)
+            arg.default(a.default);
+        if (a.choices)
+            arg.choices(a.choices);
+        // A required argument means a non-empty VALUE, not just a present token: `invoke ""` must be a
+        // usage error, not an empty turn (the old dispatch's falsy guards, kept at the parse boundary).
+        // choices args validate membership already ("" is never a member).
+        if (a.name.startsWith("<") && !a.choices) {
+            arg.argParser((value) => {
+                if (value.trim() === "")
+                    throw new InvalidArgumentError("must not be empty.");
+                return value;
+            });
+        }
+        cmd.addArgument(arg);
+    }
+    for (const f of spec.flags ?? []) {
+        const opt = new Option(f.flags, f.description);
+        if (f.hidden)
+            opt.hideHelp();
+        if (f.conflicts)
+            opt.conflicts(f.conflicts);
+        cmd.addOption(opt);
+    }
+    for (const sub of spec.subcommands ?? [])
+        register(cmd, sub);
+    const run = spec.run;
+    if (run) {
+        cmd.action(async (...invocation) => {
+            invocation.pop(); // the Command instance
+            const flags = invocation.pop();
+            await run(invocation, flags);
+        });
+    }
+}
+/**
+ * The Examples/notes sections a spec appends after commander's standard ones. Examples are
+ * preformatted (column-aligned `$ cmd   # note` lines); notes are logical prose the renderer
+ * reflows to `helper.helpWidth` — the exact width the sections above were wrapped to.
+ */
+function extraSections(cmd, helper) {
+    const spec = specOf.get(cmd);
+    if (!spec || ((spec.examples?.length ?? 0) === 0 && !spec.notes))
+        return "";
+    const width = helper.helpWidth ?? 80;
+    const lines = [];
+    if (spec.examples && spec.examples.length > 0) {
+        lines.push(helper.styleTitle("Examples:"));
+        // Inline, column-aligned notes (`$ cmd   # note`) — a note on its own line reads as a stray
+        // fragment when neighboring examples have none.
+        const w = Math.max(...spec.examples.map((e) => e.cmd.length));
+        for (const e of spec.examples) {
+            lines.push(e.note ? `  $ ${e.cmd.padEnd(w)}   # ${e.note}` : `  $ ${e.cmd}`);
+        }
+        lines.push("");
+    }
+    if (spec.notes) {
+        lines.push(...reflow(spec.notes, width, helper));
+        lines.push("");
+    }
+    return `\n${lines.join("\n")}`;
+}
+/**
+ * Reflow notes to the help width: plain lines are prose (joined and wrapped via the helper's own
+ * `boxWrap`); indented lines are preformatted (aligned tables like start's precedence chains) and
+ * pass through verbatim; blank lines separate paragraphs.
+ */
+function reflow(text, width, helper) {
+    const out = [];
+    let prose = [];
+    const flush = () => {
+        if (prose.length > 0) {
+            out.push(...helper.boxWrap(prose.join(" "), width).split("\n"));
+            prose = [];
+        }
+    };
+    for (const line of text.split("\n")) {
+        if (/^\s/.test(line)) {
+            flush();
+            out.push(line);
+        }
+        else if (line === "") {
+            flush();
+            out.push("");
+        }
+        else {
+            prose.push(line);
+        }
+    }
+    flush();
+    return out;
+}

package/dist/cli/program.d.ts

@@ -0,0 +1,11 @@
+import { type CommandSpec, type ProgramOptions } from "./kernel.ts";
+/** Registration order = help order — the ORIGINAL usage wall's order, kept verbatim (this is a
+ *  commander refactor of the same CLI, not a redesign). Exported for the kernel conformance tests. */
+export declare const specs: readonly CommandSpec[];
+/**
+ * The production program assembly (specs + the top-level examples/docs). Tests build through THIS —
+ * with their IO/width/color seams as overrides — so they exercise the real shape, not a lookalike.
+ */
+export declare function buildCliProgram(overrides?: ProgramOptions): import("commander").Command;
+/** Parse and run one CLI invocation (`argv` = process.argv). Usage errors exit 2 via the kernel policy. */
+export declare function runCli(argv: readonly string[]): Promise<void>;

package/dist/cli/program.js

@@ -0,0 +1,421 @@
+/**
+ * The fastagent command registry: every command as data ({@link CommandSpec}) with a lazy-imported
+ * implementation, so `fastagent <cmd>` pays only for the module graph that command actually uses.
+ * This file is the CLI surface's single source of truth — the overview and every per-command help
+ * render from these specs (no hand-maintained usage text).
+ */
+import { fastagentVersion } from "../version.js";
+import { buildProgram } from "./kernel.js";
+// Help groups (clig: most common commands first) — the authoring loop leads, operations close.
+// Shared flags — same name, same meaning, on every command that supports them (clig: consistency).
+const DIR_ARG = { name: "[dir]", description: "workspace directory", default: "." };
+const MODEL = {
+    flags: "--model <provider/modelId>",
+    description: "model override (precedence: --model > FASTAGENT_MODEL > config)",
+};
+const AUTH_PATH = {
+    flags: "--auth-path <file>",
+    description: "credentials file (default: <state root>/auth.json; env: FASTAGENT_AUTH_PATH)",
+};
+const JSON_FLAG = { flags: "--json", description: "machine-readable JSON output" };
+const NO_INPUT = {
+    flags: "--no-input",
+    description: "never prompt (CI/scripts) — missing information becomes an error instead of a question",
+};
+const PORT = { flags: "--port <n>", description: "HTTP port" };
+const TUNNEL = {
+    flags: "--tunnel",
+    description: "expose a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared) and auto-register " +
+        "webhook channels (telegram, feishu, lark; github prints the URL) — for hosting a bot from your " +
+        "own box without deploying (the quick-tunnel URL is ephemeral, not for production)",
+};
+const init = {
+    name: "init",
+    summary: "scaffold a runnable agent and install its dependencies",
+    description: "Scaffold a runnable agent in dir (default .) and run npm install. Default is a self-iterating " +
+        "agent: persona.md (its identity), a writing-great-skills example skill, a fetch-url code tool, " +
+        "config, package.json, .gitignore. Never overwrites existing files; an existing AGENTS.md is kept " +
+        "as project context.",
+    args: [DIR_ARG],
+    flags: [
+        { flags: "--minimal", description: "persona.md + the example skill + config only (no code tool / package.json)" },
+        { flags: "--no-install", description: "scaffold everything but skip npm install" },
+        { flags: "--flat", description: "force the flat layout (skip host-signal detection)", conflicts: ["agentDir"] },
+        { flags: "--agent-dir <name>", description: "force the agent kit into ./<name>" },
+    ],
+    examples: [
+        { cmd: "fastagent init my-agent", note: "a new agent dir, ready to dev" },
+        { cmd: "fastagent init", note: "initialize the current directory" },
+    ],
+    notes: 'Layout: flat by default ("a directory is an agent"); when an existing toolchain/deploy claims ' +
+        "the directory (tsconfig/framework config, a non-JS build manifest like " +
+        "go.mod/pyproject.toml/Cargo.toml, Dockerfile/fly/railway, or occupied tools/, channels/, or " +
+        "skills/), the kit goes into ./agent and config.agentDir points there — the reason is printed, " +
+        "no prompt.",
+    run: async (args, f) => (await import("./commands/init.js")).runInit(args[0], {
+        minimal: f.minimal === true,
+        install: f.install !== false,
+        flat: f.flat === true,
+        agentDir: f.agentDir,
+    }),
+};
+const dev = {
+    name: "dev",
+    summary: "serve the agent locally, restarting on code edits",
+    description: "Assemble the agent in dir (default .) and serve a local HTTP channel. persona.md/AGENTS.md/skills " +
+        "are re-read every turn (edits go live next turn); edits to code inputs — tools/, channels/, " +
+        "fastagent.config.*, package.json, .env — restart the worker. Files the agent writes as work " +
+        "product never trigger a restart.",
+    args: [DIR_ARG],
+    flags: [
+        PORT,
+        MODEL,
+        AUTH_PATH,
+        { flags: "--no-watch", description: "serve once, no file-watching" },
+        TUNNEL,
+        NO_INPUT,
+    ],
+    examples: [
+        { cmd: "fastagent dev" },
+        { cmd: "fastagent dev --tunnel", note: "public URL + auto-registered webhooks" },
+    ],
+    run: async (args, f) => (await import("./commands/dev.js")).runDev(args[0], {
+        port: f.port,
+        model: f.model,
+        authPath: f.authPath,
+        watch: f.watch !== false,
+        tunnel: f.tunnel === true,
+        input: f.input !== false,
+    }),
+};
+const chat = {
+    name: "chat",
+    summary: "open the SAME assembled agent in pi's interactive TUI",
+    description: "Open the SAME assembled agent in pi's interactive TUI (the real harness, not a crude REPL) — to " +
+        "try it locally before serving. Same model/tool/skill resolution as dev; pi handles login, " +
+        "sessions, and /resume natively.",
+    args: [DIR_ARG],
+    flags: [MODEL],
+    examples: [{ cmd: "fastagent chat" }],
+    run: async (args, f) => (await import("./commands/chat.js")).runChat(args[0], { model: f.model }),
+};
+const info = {
+    name: "info",
+    summary: "print what the directory assembles into, without serving",
+    description: "Print what dir (default .) ASSEMBLES into — model, persona, context files (AGENTS.md), skills, " +
+        "tools (+ collisions), channels, schedules, sessions, load diagnostics — WITHOUT serving. " +
+        "Read-only (never creates sessions / writes .gitignore); an unset model is reported, not fatal. " +
+        "Run it first when something looks off.",
+    args: [DIR_ARG],
+    flags: [JSON_FLAG, MODEL, AUTH_PATH, { flags: "--sessions-dir <dir>", description: "sessions directory override" }],
+    examples: [{ cmd: "fastagent info" }, { cmd: "fastagent info --json", note: "for CI" }],
+    run: async (args, f) => (await import("./commands/info.js")).runInfo(args[0], {
+        json: f.json === true,
+        model: f.model,
+        authPath: f.authPath,
+        sessionsDir: f.sessionsDir,
+    }),
+};
+const tool = {
+    name: "tool",
+    summary: "run one tool directly with JSON args — no model, no server, no tokens",
+    description: "Run one tool (from tools/ or config.tools) directly with JSON args — no model, no server, no " +
+        "tokens. Fast feedback while authoring a tool.",
+    args: [
+        { name: "<name>", description: "the tool name as served (see `fastagent info`)" },
+        { name: "[json-args]", description: "the tool's arguments as a JSON object", default: "{}" },
+        DIR_ARG,
+    ],
+    examples: [{ cmd: `fastagent tool add '{"a":2,"b":3}'` }],
+    notes: "Mounts the same tool set dev/start serve (defaults + config.tools + discovered tools/, " +
+        "deduped), so a shadowed or broken tool is surfaced here exactly as it would be when serving.",
+    run: async (args) => (await import("./commands/tool.js")).runTool(args[0], args[1], args[2]),
+};
+const invoke = {
+    name: "invoke",
+    summary: "run ONE turn against the assembled agent and exit",
+    description: "Run ONE turn against the assembled agent and exit — no server, no TUI. The reply streams to " +
+        "stdout, tool/diagnostics to stderr, a failed turn exits non-zero. The all-agent counterpart of " +
+        "`tool`, for CI smoke and quick checks. Same model resolution as dev.",
+    args: [{ name: "<message>", description: "the user message for the turn" }, DIR_ARG],
+    flags: [MODEL, AUTH_PATH, NO_INPUT],
+    examples: [{ cmd: `fastagent invoke "summarize today's inbox"` }],
+    run: async (args, f) => (await import("./commands/invoke.js")).runInvoke(args[0], args[1], {
+        model: f.model,
+        authPath: f.authPath,
+        input: f.input !== false,
+    }),
+};
+const fire = {
+    name: "fire",
+    summary: "run ONE schedule's turn immediately, without waiting for its cron",
+    description: "Run ONE schedule's turn immediately (authoring loop, like invoke) — fires schedules/<name>.ts now " +
+        "without waiting for its cron. Reply→stdout; does NOT advance the schedule's fire state.",
+    args: [{ name: "<name>", description: "the schedule name (schedules/<name>.ts)" }, DIR_ARG],
+    flags: [MODEL, AUTH_PATH, NO_INPUT],
+    examples: [{ cmd: "fastagent fire daily-digest" }],
+    run: async (args, f) => (await import("./commands/fire.js")).runFire(args[0], args[1], {
+        model: f.model,
+        authPath: f.authPath,
+        input: f.input !== false,
+    }),
+};
+const models = {
+    name: "models",
+    summary: 'list the available "provider/modelId" model specs',
+    description: 'List every registered "provider/modelId" spec — use one with --model or as `model` in fastagent.config.ts.',
+    args: [{ name: "[search]", description: "case-insensitive substring filter" }],
+    examples: [
+        { cmd: "fastagent models", note: "all specs" },
+        { cmd: "fastagent models claude", note: "filter; provider-name matches rank first" },
+    ],
+    run: async (args) => (await import("./commands/models.js")).runModels(args[0]),
+};
+const start = {
+    name: "start",
+    summary: "run the agent in production posture (same assembly as dev, no watching)",
+    description: "Run the agent in dir (default .) 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; " +
+        "model/http come from fastagent.config.ts (frozen by git).",
+    args: [DIR_ARG],
+    flags: [
+        PORT,
+        MODEL,
+        { flags: "--sessions-dir <dir>", description: "sessions directory override" },
+        AUTH_PATH,
+        TUNNEL,
+        NO_INPUT,
+    ],
+    examples: [
+        { cmd: "fastagent start" },
+        { cmd: "fastagent start --tunnel", note: "host a bot from your own box, no deploy" },
+    ],
+    notes: "Precedence chains:\n" +
+        "  port:     --port > PORT env > fastagent.config.ts http.port > 8787\n" +
+        "  state:    FASTAGENT_STATE_DIR > <dir>/.fastagent — the ONE machine-state\n" +
+        "            root (auth, sessions, channel state all derive from it); point\n" +
+        "            it at a mounted volume so a redeploy that replaces the\n" +
+        "            directory never wipes state\n" +
+        "  sessions: --sessions-dir > FASTAGENT_SESSIONS_DIR > <state>/sessions\n" +
+        "  auth:     --auth-path > FASTAGENT_AUTH_PATH > <state>/auth.json\n" +
+        "            (project-level; point it at ~/.fastagent/auth.json to share one\n" +
+        "            credential across projects)",
+    run: async (args, f) => (await import("./commands/start.js")).runStart(args[0], {
+        port: f.port,
+        model: f.model,
+        sessionsDir: f.sessionsDir,
+        authPath: f.authPath,
+        tunnel: f.tunnel === true,
+        input: f.input !== false,
+    }),
+};
+/** The retired app-creation flag — parsed so it can explain itself, hidden from help. */
+const CREATE_APP = { flags: "--create-app", description: "(retired)", hidden: true };
+const channelSub = (kind, summary, description, notes) => ({
+    name: kind,
+    summary,
+    description,
+    args: [DIR_ARG],
+    flags: [CREATE_APP],
+    examples: [{ cmd: `fastagent add ${kind}` }],
+    ...(notes ? { notes } : {}),
+    run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], { createApp: f.createApp === true }),
+});
+const add = {
+    name: "add",
+    summary: "connect a channel (github, telegram, feishu, lark) or vendor a skill",
+    description: "Scaffold channels/<kind>.ts — third-party adapter glue with the policy to edit (github maps " +
+        "events in on(); telegram/feishu/lark route in the optional route()) — or vendor an Agent Skills " +
+        "skill into skills/<name>/.",
+    subcommands: [
+        channelSub("github", "scaffold the GitHub webhook channel (issues/PRs → agent turns)", "Scaffold channels/github.ts — webhook adapter glue that maps repository events (issues, PRs, " +
+            "comments) to agent turns in its on() policy."),
+        channelSub("telegram", "scaffold the Telegram bot channel (durable turns, live preview)", "Scaffold channels/telegram.ts — the Telegram bot channel with durable turns, a live-preview " +
+            "message pump, and an optional route() policy."),
+        channelSub("feishu", "scaffold the Feishu channel AND create/configure the platform app", "Scaffold channels/feishu.ts AND create/configure the Feishu platform app (scan-to-create), " +
+            "writing credentials to .env.", "Feishu (open.feishu.cn) is the canonical implementation. `add feishu` also CREATES + " +
+            'configures the platform app (confirm a link in the app — the platform\'s "scan to create" ' +
+            "flow; one version-publish action remains) and writes credentials to .env; a persisted " +
+            "ID/Secret pair resumes missing-Token setup instead of creating another app."),
+        channelSub("lark", "scaffold the Lark (international) channel with guided credential setup", "Scaffold channels/lark.ts — the Lark international profile over the Feishu engine — and guide " +
+            "credential setup against the intl developer console.", "Lark international (open.larksuite.com) is Feishu's compatibility profile with degraded " +
+            "control-plane setup: opens the intl developer console only for a new/partial pair, validates " +
+            "App ID/Secret, then probes webhook-mode + Token automation; an explicit config-route 404 " +
+            "falls back to a hidden Token prompt + manual mode/URL setup."),
+        {
+            name: "skill",
+            summary: "vendor an Agent Skills skill into skills/<name>/ (copied in, git-tracked)",
+            args: [
+                {
+                    name: "[source]",
+                    description: "a git ref (owner/repo/path, github default), a local path (./x, /abs), or a bare name " +
+                        "from your global skill dirs (~/.agents/skills, ~/.pi/agent/skills)",
+                },
+                DIR_ARG,
+            ],
+            flags: [
+                { flags: "--update", description: "overwrite an existing skill (re-fetch from source); review with git diff" },
+            ],
+            examples: [
+                { cmd: "fastagent add skill anthropics/skills/document-skills/pdf" },
+                { cmd: "fastagent add skill ./my-skill --update" },
+            ],
+            notes: "Writing your own skill needs no command: create skills/<name>/SKILL.md with name + " +
+                "description frontmatter; it's auto-discovered. `add skill` is only for vendoring an " +
+                "existing one.",
+            run: async (args, f) => (await import("./commands/add.js")).runAddSkill(args[0], args[1], { update: f.update === true }),
+        },
+    ],
+};
+const deploy = {
+    name: "deploy",
+    summary: "generate deploy artifacts + a runbook for docker, fly, or railway (--run drives it)",
+    description: "Generate Dockerfile/.dockerignore plus the target config and print an ordered runbook. " +
+        "docker: fastagent.compose.yml, loopback port, persistent state volume. fly: fly.toml " +
+        "(autostop=suspend, state→volume). railway: railway.json (healthcheck /health); its " +
+        "volume/variables/App-Sleeping are dashboard/CLI steps the runbook states. Durable ingress " +
+        "remains operator-owned.",
+    args: [{ name: "<host>", description: "deploy target", choices: ["docker", "fly", "railway"] }, DIR_ARG],
+    flags: [
+        {
+            flags: "--run",
+            description: "drive the target CLI to completion. Docker runs `docker compose up -d --build`; with a tunnel " +
+                "service, reads its URL and registers webhooks. Fly/Railway provision app/service + volume + " +
+                "secrets + deploy + webhook setup. Carries your local credential (env key or OAuth auth.json). " +
+                "Stops at a gate (missing CLI/daemon/login/secret) with one actionable line. Without it: prints " +
+                "the runbook",
+        },
+        {
+            flags: "--tunnel",
+            description: "(docker only) add a Quick Tunnel service to generated Compose; generation-only unless combined " +
+                "with --run. Existing Compose stays authoritative",
+        },
+        { flags: "--force", description: "overwrite existing target config/Dockerfile/.dockerignore (else kept)" },
+        {
+            flags: "--stop",
+            description: "(fly only) autostop by stopping (cold start) instead of suspending (fast resume)",
+        },
+        {
+            flags: "--no-scale-to-zero",
+            description: "(fly only) keep one machine running when idle (min_machines_running=1)",
+        },
+        {
+            flags: "--into-linked",
+            description: "(railway --run) provision INTO the project this dir is already linked to (skip create); by " +
+                "default --run refuses a pre-existing link (could be unrelated/production)",
+        },
+        MODEL,
+        AUTH_PATH,
+    ],
+    examples: [
+        { cmd: "fastagent deploy fly --run", note: "provision + deploy + webhooks" },
+        { cmd: "fastagent deploy docker --tunnel --run", note: "Compose + a public URL" },
+        { cmd: "fastagent deploy railway", note: "print the runbook only" },
+    ],
+    notes: "Definition-read-only: the only writes are generated artifacts (never clobbered without " +
+        "--force). A routine redeploy of an already-provisioned agent is just the host's own command " +
+        "(e.g. `railway up`).",
+    run: async (args, f) => (await import("./commands/deploy.js")).runDeploy(args[0], args[1], {
+        run: f.run === true,
+        tunnel: f.tunnel === true,
+        force: f.force === true,
+        stop: f.stop === true,
+        scaleToZero: f.scaleToZero !== false,
+        intoLinked: f.intoLinked === true,
+        model: f.model,
+        authPath: f.authPath,
+    }),
+};
+const schedule = {
+    name: "schedule",
+    summary: "inspect and control time triggers: run audit, pending fires, cancel a wake-up",
+    subcommands: [
+        {
+            name: "history",
+            summary: 'print the run audit for a schedule (or "wake" for self-scheduled wake-ups)',
+            description: "Print the run audit for a schedule: when each run fired, completed/failed/deferred, duration, and " +
+                'the reply/error — the answer to "did last night\'s run silently fail?". Read-only.',
+            args: [
+                { name: "<name>", description: 'the schedule name, or "wake" for the agent\'s self-scheduled wake-ups' },
+                DIR_ARG,
+            ],
+            flags: [{ flags: "--json", description: "the full records (complete reply text)" }],
+            examples: [
+                { cmd: "fastagent schedule history daily-digest" },
+                { cmd: "fastagent schedule history wake --json", note: "the agent's own wake-ups" },
+            ],
+            run: async (args, flags) => (await import("./commands/schedule.js")).runScheduleHistory(args[0], args[1], flags.json === true),
+        },
+        {
+            name: "list",
+            summary: "everything that will fire: static schedules (next instant) + pending wake-ups",
+            description: "List everything that will fire, from BOTH producers: the static schedules/ files (name + next " +
+                "cron instant) and the agent's pending self-scheduled wake-ups. Read-only.",
+            args: [DIR_ARG],
+            flags: [JSON_FLAG],
+            examples: [{ cmd: "fastagent schedule list" }],
+            run: async (args, flags) => (await import("./commands/schedule.js")).runScheduleList(args[0], flags.json === true),
+        },
+        {
+            name: "cancel",
+            summary: "remove a pending wake-up — the operator's kill switch for a runaway recurring wake",
+            description: "Remove a pending wake-up — the operator's kill switch for a runaway recurring wake (the agent's own " +
+                "is the `unwake` tool). Not session-scoped: the operator owns the box.",
+            args: [{ name: "<id>", description: "the wake-up id (`fastagent schedule list` shows ids)" }, DIR_ARG],
+            examples: [{ cmd: "fastagent schedule cancel wake-1700000000000-ab12" }],
+            run: async (args) => (await import("./commands/schedule.js")).runScheduleCancel(args[0], args[1]),
+        },
+    ],
+};
+const login = {
+    name: "login",
+    summary: "authenticate a model provider (subscription/OAuth or API key)",
+    description: "Authenticate a model provider into the project-level <state root>/auth.json — default " +
+        "<cwd>/.fastagent/auth.json (run from $HOME for the global ~/.fastagent/auth.json): pick a method " +
+        "(subscription/OAuth or API key), then a provider that offers it (configured status shown). " +
+        "[provider] takes the method from what that provider supports, asked only when both.",
+    args: [{ name: "[provider]", description: "provider id (skip the provider menu)" }],
+    flags: [AUTH_PATH, NO_INPUT],
+    examples: [{ cmd: "fastagent login" }, { cmd: "fastagent login openai" }],
+    notes: "The positional is the PROVIDER (not a dir) — `cd` into your agent before logging in.",
+    run: async (args, f) => (await import("./commands/login.js")).runLogin(args[0], {
+        authPath: f.authPath,
+        input: f.input !== false,
+    }),
+};
+/** Registration order = help order — the ORIGINAL usage wall's order, kept verbatim (this is a
+ *  commander refactor of the same CLI, not a redesign). Exported for the kernel conformance tests. */
+export const specs = [
+    init,
+    models,
+    info,
+    tool,
+    invoke,
+    fire,
+    schedule,
+    dev,
+    chat,
+    start,
+    add,
+    deploy,
+    login,
+];
+/**
+ * The production program assembly (specs + the top-level examples/docs). Tests build through THIS —
+ * with their IO/width/color seams as overrides — so they exercise the real shape, not a lookalike.
+ */
+export function buildCliProgram(overrides = {}) {
+    return buildProgram(specs, {
+        examples: [
+            { cmd: "fastagent init my-agent && cd my-agent", note: "scaffold an agent" },
+            { cmd: "fastagent dev", note: "serve locally and iterate" },
+            { cmd: "fastagent deploy fly --run", note: "ship it" },
+        ],
+        notes: "Docs: https://github.com/fastagent-sh/fastagent",
+        ...overrides,
+    });
+}
+/** Parse and run one CLI invocation (`argv` = process.argv). Usage errors exit 2 via the kernel policy. */
+export async function runCli(argv) {
+    await buildCliProgram({ version: await fastagentVersion() }).parseAsync([...argv]);
+}

package/dist/cli/serve.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The serving spine shared by `dev` (its worker) and `start`: route assembly from discovered
+ * channels/, the Node host binding, the scheduler lifecycle, and the optional Cloudflare quick
+ * tunnel. Bodies moved verbatim from cli.ts; `values.tunnel` became a parameter.
+ */
+import type { Agent } from "../agent.ts";
+import { type Routes } from "../host/node.ts";
+/**
+ * The routes this deployment serves: a default `GET /health` plus the workspace's discovered
+ * `channels/` — or the default invoke channel at POST /invoke when none are declared.
+ */
+export declare function routesFor(workspaceDir: string, agent: Agent, stateRoot: string): Promise<Routes>;
+/** Serve `routes` via the Node host. serveNode owns binding; the CLI owns policy (errors, ready signal, log). */
+export declare function serve(routes: Routes, port: number, onListening?: (boundPort: number) => void): void;
+/**
+ * Start a Cloudflare tunnel + announce/register webhooks once the server is bound — unless this is a
+ * watch-supervisor worker, where the supervisor owns the long-lived tunnel so the public URL survives
+ * reloads.
+ */
+export declare function maybeTunnel(workspaceDir: string, boundPort: number, tunnel: boolean): void;
+/**
+ * Load and start the workspace's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
+ * there are static schedules OR `selfSchedule` is on (the scheduler also polls the agent's self-scheduled
+ * wake-ups, which the built-in `wake` tool creates only when opted in). Shares the SAME (trace-wrapped)
+ * agent the routes serve, so a scheduled turn is observed like any other. Best-effort stop on exit; dev's
+ * watch restart re-reads schedules with the worker (schedules are a code input). Single-process.
+ */
+export declare function startSchedules(workspaceDir: string, agent: Agent, stateRoot: string, selfSchedule: boolean): Promise<void>;