@fastagent-sh/fastagent 0.12.1 → 0.14.0

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>;

package/dist/cli/serve.js

@@ -0,0 +1,90 @@
+import { createInvokeHandler } from "../channels/http.js";
+import { text } from "../channels/respond.js";
+import { loadChannels } from "../engines/pi/channel.js";
+import { reportModuleLoadFailures } from "../engines/pi/report.js";
+import { parseRouteKey, router, serveNode } from "../host/node.js";
+import { log } from "../log.js";
+import { openExternalUrl } from "../open-url.js";
+import { loadSchedules } from "../schedule/discover.js";
+import { createScheduler } from "../schedule/scheduler.js";
+import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
+import { failStartup } from "./fail.js";
+/**
+ * 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 async function routesFor(workspaceDir, agent, stateRoot) {
+    const { routes, collisions, failures } = await loadChannels(workspaceDir, { agent, stateRoot });
+    for (const c of collisions) {
+        console.error(`[fastagent] warn: channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
+    }
+    reportModuleLoadFailures(failures);
+    if (failures.length > 0 || collisions.length > 0) {
+        throw new Error(`channel setup is invalid (${failures.length} load failure(s), ${collisions.length} route collision(s)) — ` +
+            `fix it, or rename an intentionally disabled file to *.disabled`);
+    }
+    const channels = Object.keys(routes).length > 0 ? routes : { "POST /invoke": createInvokeHandler(agent) };
+    // Add a default GET /health unless a channel already covers it (overlap, not exact-key: an
+    // any-method `/health` also handles GET, so the built-in steps aside).
+    const healthCovered = Object.keys(channels).some((k) => {
+        const e = parseRouteKey(k);
+        return e.path === "/health" && (e.method === undefined || e.method === "GET");
+    });
+    return healthCovered ? channels : { "GET /health": () => text("ok\n", 200), ...channels };
+}
+/** Serve `routes` via the Node host. serveNode owns binding; the CLI owns policy (errors, ready signal, log). */
+export function serve(routes, port, onListening) {
+    serveNode(router(routes), { port }).listening.then((boundPort) => {
+        process.send?.({ type: "ready", port: boundPort }); // tell the dev supervisor we bound + on which port
+        log.info(`[fastagent] http channel on :${boundPort}`);
+        log.info(`[fastagent] routes: ${Object.keys(routes).join(", ") || "(none)"}`);
+        onListening?.(boundPort);
+    }, (error) => {
+        if (error.code === "EADDRINUSE")
+            failStartup(new Error(`port ${port} is already in use; choose another with --port`));
+        failStartup(new Error(`cannot bind http channel on :${port}: ${error.message}`));
+    });
+}
+/**
+ * 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 function maybeTunnel(workspaceDir, boundPort, tunnel) {
+    if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
+        return;
+    void startCloudflareTunnel(boundPort).then((t) => {
+        if (!t)
+            return;
+        void announceWebhooks(workspaceDir, t.url, { openUrl: openExternalUrl });
+        // Single-process (start / --no-watch): close the tunnel on exit (watch mode's supervisor owns its own).
+        const cleanup = () => {
+            t.close();
+            process.exit(0);
+        };
+        process.once("SIGINT", cleanup);
+        process.once("SIGTERM", cleanup);
+    });
+}
+/**
+ * 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 async function startSchedules(workspaceDir, agent, stateRoot, selfSchedule) {
+    const { schedules, failures } = await loadSchedules(workspaceDir).catch(failStartup);
+    reportModuleLoadFailures(failures);
+    // Nothing to run when there are neither static `schedules/` nor self-scheduling (the `wake` tool, and
+    // thus any wake-up to poll, is mounted only when config.selfSchedule is on) — skip the poller entirely.
+    if (schedules.length === 0 && !selfSchedule)
+        return;
+    const scheduler = createScheduler({ agent, stateRoot, schedules });
+    scheduler.start();
+    if (schedules.length > 0)
+        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}`);
+    const stop = () => scheduler.stop();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+}

package/dist/cli/shared.d.ts

@@ -0,0 +1,24 @@
+/** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
+export declare function isInteractive(): boolean;
+/**
+ * Parse + range-check a port string (CLI flag or env). Empty/whitespace is "not set" → undefined, so
+ * the `??` chain falls through instead of binding port 0 (`Number("")` is 0). The exit code follows
+ * RESPONSIBILITY, not the layer that discovers the problem: a bad `--port` is a usage error (2), a
+ * bad `PORT` env is broken runtime configuration (1).
+ */
+export declare function parsePort(value: string | undefined, source: string, from: "flag" | "env"): number | undefined;
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
+export declare function reportAuth(modelSpec: string, authPath: string): Promise<void>;
+/**
+ * First-run model resolution for the serving commands. When no model is set (flag/env/config), and
+ * we're on a TTY, pick one from the providers the user is logged into and persist the choice. A no-op
+ * when a model is already set; on a non-TTY (CI/deploy), or with `--no-input`, or with nothing
+ * configured it stays silent and lets the opener raise its clear "missing model" error. The pick is
+ * exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it, and best-effort written back to
+ * the config so the next run is quiet.
+ */
+export declare function resolveFirstRunModel(workspaceDir: string, options?: {
+    model?: string;
+    authPath?: string;
+    input?: boolean;
+}): Promise<void>;