@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/cli/program.js

@@ -1,14 +1,11 @@
 /**
- * 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).
+ * 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.
  */
 import { fastagentVersion } from "../version.js";
 import { buildProgram } from "./kernel.js";
 import { DEPLOY_HOSTS } from "../deploy/hosts.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 (the agent is here, or in a directory inside it)",
@@ -18,10 +15,6 @@ 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: <agent dir>/.secrets/auth.json; env: FASTAGENT_AUTH_PATH)",
-};
 const JSON_FLAG = { flags: "--json", description: "machine-readable JSON output" };
 const NO_INPUT = {
     flags: "--no-input",
@@ -30,54 +23,48 @@ const NO_INPUT = {
 const PORT = { flags: "--port <n>", description: "HTTP port" };
 const BIND = {
     flags: "--bind <addr>",
-    description: "bind address (default: all interfaces; 127.0.0.1 keeps it off the LAN)",
+    description: "bind address (dev defaults to 127.0.0.1; start defaults to all interfaces, which containers need)",
+};
+const NO_INVOKE = {
+    flags: "--no-invoke",
+    description: "do not serve POST /invoke on this run, nor POST /run — both are unauthenticated and run a turn with the " +
+        "agent's full tools, so a serve meant to be reached only through its channels' signed webhooks should withhold " +
+        "them (fastagent.config.ts http.invoke: false is the same choice, but it travels into a deployed image; this " +
+        "flag outranks http.run: true, because a flag is what a definition you cannot edit still answers to)",
 };
 const TUNNEL = {
     flags: "--tunnel",
     description: "expose a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared) and auto-register " +
-        "webhook channels (telegram, onboarded slack, feishu, lark; github/manual slack print the URL) — for hosting a bot from your " +
+        "webhook channels (telegram, onboarded slack, feishu, lark; manual slack 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 and run npm install. By default the agent goes into ./fastagent/ in dir " +
-        "(default .; --agent-dir names it otherwise) — the rest of the directory gets zero writes, and it is " +
-        "the WORKSPACE the agent works ON when you point fastagent there. Default content is a " +
+    description: "Scaffold a runnable agent and run npm install. The agent ALWAYS goes into a subdirectory of dir " +
+        "(default .): ./fastagent/, or --agent-dir <name> — the rest of the directory gets zero writes, and " +
+        "it is the WORKSPACE the agent works ON when you point fastagent there. Content is a " +
         "self-iterating agent: persona.md (its identity), a writing-great-skills " +
         "example skill, a fetch-url code tool, config, package.json, .gitignore. 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: "--agent-dir <name>", description: "name the agent directory (default fastagent; . = dir itself)" },
-        {
-            flags: "--flat",
-            description: "alias for --agent-dir . — the directory IS the agent; keeps existing files",
-            // Two spellings of ONE knob: `--flat --agent-dir bot` names the same thing twice with different
-            // values, which is a usage error, not a precedence question to settle silently.
-            conflicts: ["agentDir"],
-        },
+        { flags: "--agent-dir <name>", description: "name the agent directory (default fastagent)" },
     ],
     examples: [
         { cmd: "fastagent init", note: "the agent lands in ./fastagent/" },
         { cmd: "fastagent init my-project", note: "my-project/fastagent/ (created)" },
         { cmd: "fastagent init . --agent-dir bot", note: "./bot/ — any name works" },
-        { cmd: "fastagent init . --flat", note: "this repo IS the agent" },
     ],
-    notes: "An agent is a directory holding a fastagent.config.* — never its NAME, so --agent-dir can call it " +
+    notes: "An agent is a directory holding a fastagent.config.ts — never its NAME, so --agent-dir can call it " +
         "anything (the name decides only which agent answers when a workspace holds several: see " +
         "FASTAGENT_AGENT). What the agent works ON (its cwd, where its AGENTS.md context is read from) is " +
-        "whatever directory you later point fastagent at: point at the project and the agent inside it " +
-        "serves with the project as its workspace; point at the agent directory (all a deployed box may " +
-        "hold) and it works on itself. A directory resolves to ONE agent, at it or one level inside.",
+        "the agent directory's parent — the project you ran init in — whether you point fastagent at the " +
+        "project or at the agent directory. A directory resolves to ONE agent, at it or one level inside.",
     run: async (args, f) => (await import("./commands/init.js")).runInit(args[0], {
-        minimal: f.minimal === true,
         install: f.install !== false,
-        // `--flat` is the spelling for the common case of the same knob (they conflict, so only one is
-        // ever set); both land in ONE value, so the scaffolder never sees two ways to say ".".
-        agentDir: f.flat === true ? "." : typeof f.agentDir === "string" ? f.agentDir : undefined,
+        agentDir: typeof f.agentDir === "string" ? f.agentDir : undefined,
     }),
 };
 const dev = {
@@ -85,16 +72,16 @@ const 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, .secrets/.env — restart the worker. Files the agent writes as " +
+        "fastagent.config.ts, package.json, .secrets/.env — restart the worker. Files the agent writes as " +
         "work product never trigger a restart.",
     args: [DIR_ARG],
     flags: [
         PORT,
         BIND,
         MODEL,
-        AUTH_PATH,
         { flags: "--no-watch", description: "serve once, no file-watching" },
         TUNNEL,
+        NO_INVOKE,
         NO_INPUT,
     ],
     examples: [
@@ -105,31 +92,12 @@ const dev = {
         port: f.port,
         bind: f.bind,
         model: f.model,
-        authPath: f.authPath,
         watch: f.watch !== false,
         tunnel: f.tunnel === true,
+        ...(f.invoke === false ? { invoke: false } : {}),
         input: f.input !== false,
     }),
 };
-const attach = {
-    name: "attach",
-    summary: "watch a session's live events from a running serve and steer it",
-    description: "Attach to a session served by a running dev/start with `sessionControl: true` in the config: " +
-        "stream its live events (text, tools, run boundaries), steer the active run by typing — or, with " +
-        "no run active, start one (detaching cancels a run YOU started) — /abort to stop a run. Discovers " +
-        "the local endpoint from <stateRoot>/control.json; --url/--token reach a remote serve. The same " +
-        "wire protocol a Web panel or desktop app uses.",
-    args: [{ name: "<session>", description: "the session id to attach to" }, DIR_ARG],
-    flags: [
-        { flags: "--url <url>", description: "control endpoint (skip control.json discovery)" },
-        { flags: "--token <token>", description: "bearer token for --url" },
-    ],
-    examples: [{ cmd: "fastagent attach tg-chat-42" }],
-    run: async (args, f) => (await import("./commands/attach.js")).runAttach(args[0], args[1], {
-        url: f.url,
-        token: f.token,
-    }),
-};
 const chat = {
     name: "chat",
     summary: "open the SAME assembled agent in pi's interactive TUI",
@@ -137,12 +105,9 @@ const chat = {
         "try it locally before serving. Same model/tool/skill/auth resolution as dev; pi handles " +
         "rendering, sessions, and /resume natively (its /login writes to the same fastagent auth file).",
     args: [DIR_ARG],
-    flags: [MODEL, AUTH_PATH],
+    flags: [MODEL],
     examples: [{ cmd: "fastagent chat" }],
-    run: async (args, f) => (await import("./commands/chat.js")).runChat(args[0], {
-        model: f.model,
-        authPath: f.authPath,
-    }),
+    run: async (args, f) => (await import("./commands/chat.js")).runChat(args[0], { model: f.model }),
 };
 const info = {
     name: "info",
@@ -152,13 +117,11 @@ const info = {
         "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" }],
+    flags: [JSON_FLAG, MODEL],
     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 = {
@@ -183,25 +146,10 @@ const invoke = {
         "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],
+    flags: [MODEL, 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,
     }),
 };
@@ -223,37 +171,33 @@ const start = {
         "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,
-        BIND,
-        MODEL,
-        { flags: "--sessions-dir <dir>", description: "sessions directory override" },
-        AUTH_PATH,
-        TUNNEL,
-        NO_INPUT,
-    ],
+    flags: [PORT, BIND, MODEL, TUNNEL, NO_INVOKE, 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" +
-        "  bind:     --bind > fastagent.config.ts http.host > all interfaces\n" +
+        "  bind:     --bind > all interfaces (dev: 127.0.0.1)\n" +
+        "  /invoke:  --no-invoke > fastagent.config.ts http.invoke > served\n" +
+        "  /run:     --no-invoke > fastagent.config.ts http.run > http.invoke\n" +
+        "            (with GET /routines; both only where routines/ declares something)\n" +
         "  state:    FASTAGENT_STATE_DIR > <agent dir>/.state — mutable machine state\n" +
         "            (sessions, channel state, schedule state); point it at a mounted\n" +
         "            volume so a redeploy that replaces the directory never wipes it\n" +
         "  secrets:  FASTAGENT_SECRETS_DIR > <agent dir>/.secrets — .env + auth.json\n" +
-        "  sessions: --sessions-dir > FASTAGENT_SESSIONS_DIR > <state>/sessions\n" +
-        "  auth:     --auth-path > FASTAGENT_AUTH_PATH > <secrets>/auth.json\n" +
+        "  sessions: <state>/sessions — no separate knob; move the state root\n" +
+        "  auth:     FASTAGENT_AUTH_PATH > <secrets>/auth.json\n" +
         "            (project-level; point it at ~/.fastagent/.secrets/auth.json to\n" +
-        "            share one credential across projects)",
+        "            share one credential across projects)\n" +
+        "  endpoints: FASTAGENT_MODELS_PATH > ~/.fastagent/models.json, under the agent's\n" +
+        "            own models.json (the machine's; it does not ship with a deploy)",
     run: async (args, f) => (await import("./commands/start.js")).runStart(args[0], {
         port: f.port,
         bind: f.bind,
         model: f.model,
-        sessionsDir: f.sessionsDir,
-        authPath: f.authPath,
         tunnel: f.tunnel === true,
+        ...(f.invoke === false ? { invoke: false } : {}),
         input: f.input !== false,
     }),
 };
@@ -295,13 +239,10 @@ const channelSub = (kind, summary, description, notes) => ({
 });
 const add = {
     name: "add",
-    summary: "connect a channel (github, telegram, slack, feishu, lark) or vendor a skill",
-    description: "Scaffold channels/<kind>.ts — first-party adapter glue with the policy to edit (github maps " +
-        "events in on(); telegram/slack/feishu/lark route in the optional route()) — or vendor an Agent Skills " +
-        "skill into skills/<name>/.",
+    summary: "connect a channel (telegram, slack, feishu, lark) or vendor a skill",
+    description: "Scaffold channels/<kind>.ts — first-party adapter glue with the policy to edit 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("slack", "scaffold the Slack Events API channel (files, threads, context, live preview)", "Choose group visibility, scaffold channels/slack.ts plus slack-send.ts, create a single-workspace " +
@@ -369,21 +310,11 @@ const deploy = {
                 "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,
         NO_INPUT,
     ],
     examples: [
@@ -399,55 +330,82 @@ const deploy = {
         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,
         input: f.input !== false,
     }),
 };
-const schedule = {
-    name: "schedule",
-    summary: "inspect and control time triggers: run audit, pending fires, cancel a wake-up",
+const routine = {
+    name: "routine",
+    summary: "run and inspect the units of work this definition declares: run now, fire history, what exists",
     subcommands: [
+        {
+            name: "run",
+            summary: "run ONE routine's turn immediately, without waiting for a clock",
+            description: "Run ONE routine's turn immediately (authoring loop, like invoke) — runs routines/<name>.ts now, " +
+                "whether or not it declares a cron. Reply→stdout; does NOT advance its fire state.",
+            args: [{ name: "<name>", description: "the routine name (routines/<name>.ts)" }, DIR_ARG],
+            flags: [MODEL, NO_INPUT],
+            examples: [{ cmd: "fastagent routine run daily-digest" }],
+            run: async (args, f) => (await import("./commands/routine-run.js")).runRoutine(args[0], args[1], {
+                model: f.model,
+                input: f.input !== false,
+            }),
+        },
         {
             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),
+            summary: "print the recent fires of a routine",
+            description: "Print a routine's recent fires: when each fired, completed/failed/skipped/interrupted, and how long it " +
+                'took — the answer to "did last night\'s run silently fail?". What the run SAID is in its session, a ' +
+                "JSON-lines journal under the state root's sessions/ — which this command points at. Read-only.",
+            args: [{ name: "<name>", description: "the routine name" }, DIR_ARG],
+            flags: [{ flags: "--json", description: "the full records" }],
+            examples: [{ cmd: "fastagent routine history daily-digest" }],
+            run: async (args, flags) => (await import("./commands/routine.js")).runRoutineHistory(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.",
+            summary: "every declared routine, and when (or whether) a clock fires it",
+            description: "List the routines this definition declares: the next cron instant for each that has one, and " +
+                '"on demand" for each that does not — those are reached by name (POST /run, `routine run`). The agent\'s ' +
+                "own pending wake-ups are listed too, prefixed `wake`: a different owner (the STATE, not the " +
+                "definition), and only the agent cancels them (the `unwake` tool). 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]),
+            examples: [{ cmd: "fastagent routine list" }],
+            run: async (args, flags) => (await import("./commands/routine.js")).runRoutineList(args[0], flags.json === true),
         },
     ],
 };
+const destroy = {
+    name: "destroy",
+    summary: "delete every AWS resource `deploy agentcore` created for a workspace",
+    description: "AgentCore only, and it exists because `aws cloudformation delete-stack` is not enough: the S3 " +
+        "artifact bucket and the ECR repository have to exist BEFORE the stack that reads from them, BOTH " +
+        "log groups (the forwarder's and the runtime's own stdout) are created by AWS on first write so no " +
+        "template mentions them, and a wake alarm is minted at runtime by the container — a schedule that " +
+        "keeps retrying into a deleted Lambda. " +
+        "Derives the same names from dir that deploy did. Without --run it deletes nothing and reports what " +
+        "is out there.",
+    args: [{ name: "<host>", description: "deployed host", choices: ["agentcore"] }, DIR_ARG],
+    flags: [{ flags: "--run", description: "actually delete. Without it, this is a read-only inventory" }],
+    // The other hosts need no command of their own, and saying which one to use belongs where it can be READ:
+    // `<host>` has `choices`, so a `destroy fly` never reaches the command body.
+    examples: [
+        { cmd: "fastagent destroy agentcore", note: "what would be deleted" },
+        { cmd: "fastagent destroy agentcore --run", note: "delete it" },
+    ],
+    notes: "A bucket holding anything other than the forwarder's zips is reported and KEPT: an older deploy " +
+        "wrote agent state there, and it may be the only copy. Everything else is deleted unconditionally, " +
+        "including the agent's session storage on the AgentCore runtime — this host keeps it inside the " +
+        "stack, so there is no way to delete the deployment and keep the conversations. The other hosts need " +
+        "no command here: `fly apps destroy`, `railway down`, `docker compose -f fastagent.compose.yml down -v`. " +
+        "AWS ONLY: the " +
+        "webhook registrations `deploy --run` made with Telegram/Slack/Feishu still point at the deleted " +
+        "Function URL, and clearing them is a call to those platforms (for Telegram, deleteWebhook).",
+    run: async (args, f) => (await import("./commands/destroy.js")).runDestroy(args[0], args[1], {
+        run: f.run === true,
+    }),
+};
 const logs = {
     name: "logs",
     summary: "find and tail a deployed host's application logs",
@@ -480,39 +438,44 @@ const login = {
         "agent it writes the global ~/.fastagent/.secrets/auth.json, and says so): 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.",
+        "what that provider supports, asked only when both. An agent READS the global store for any provider " +
+        "its own file does not have, so `-g` logs in once for every agent on this machine.",
     args: [{ name: "[provider]", description: "provider id (skip the provider menu)" }],
-    flags: [AUTH_PATH, NO_INPUT],
-    examples: [{ cmd: "fastagent login" }, { cmd: "fastagent login openai" }],
+    flags: [
+        {
+            flags: "-g, --global",
+            description: `store in ~/.fastagent/.secrets/auth.json — every agent here reads it for providers its own file lacks`,
+        },
+        NO_INPUT,
+    ],
+    examples: [{ cmd: "fastagent login" }, { cmd: "fastagent login openai" }, { cmd: "fastagent login openai -g" }],
     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,
+        global: f.global === true,
         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. */
+/**
+ * Registration order = help order — the ORIGINAL usage wall's order, kept verbatim (this is a commander refactor of
+ * the same CLI, not a redesign).
+ */
 export const specs = [
     init,
     models,
     info,
     tool,
     invoke,
-    fire,
-    schedule,
+    routine,
     dev,
     chat,
-    attach,
     start,
     add,
     deploy,
     logs,
+    destroy,
     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.
- */
+/** The production program assembly (specs + the top-level examples/docs). */
 export function buildCliProgram(overrides = {}) {
     return buildProgram(specs, {
         examples: [
@@ -524,7 +487,7 @@ export function buildCliProgram(overrides = {}) {
         ...overrides,
     });
 }
-/** Parse and run one CLI invocation (`argv` = process.argv). Usage errors exit 2 via the kernel policy. */
+/** Parse and run one CLI invocation (`argv` = process.argv). */
 export async function runCli(argv) {
     await buildCliProgram({ version: await fastagentVersion() }).parseAsync([...argv]);
 }

package/dist/cli/serve.d.ts

@@ -1,26 +1,30 @@
 import type { Agent } from "../agent.ts";
-import type { AgentService, MountAgentServiceOptions } from "../service.ts";
+import type { ChannelHandler } from "../channel.ts";
+import { type AgentService, type MountableAgent, type MountAgentServiceOptions } from "../service.ts";
+/** Refuse `--tunnel` with a `--bind` that cloudflared cannot reach. */
+export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean): void;
 /**
- * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
- * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
- * `127.0.0.2` bind, loopback though it is — would leave the tunnel up and 502ing every request.
- * Checked BEFORE the bind (the flag alone pre-spawn in `dev`, again once config is loaded, since
- * `http.host` can carry the address), so the failure is clean rather than a live-but-broken public URL.
- * `source` decides the exit code, per fail.ts: a flag COMBINATION is a usage error (2), a value that
- * came from config is broken runtime configuration (1).
- */
-export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean, source: "flag" | "config"): void;
-/**
- * The bind address a serve uses: the flag, else `http.host` from the config — through `bindAddress`,
- * so a configured `localhost` is an ADDRESS by the time anything binds, renders or dials it — checked
- * against `--tunnel` with the exit code the SOURCE of the value earns (serve.ts assertTunnelBindable).
+ * Apply the flags that override what the definition said, for THIS run only.
+ *
+ * ONE place, because `dev` and `start` both do it and a mapping two call sites must each remember is one a third
+ * will not.
+ *
+ * `--no-invoke` outranks `http.invoke`: a config value travels into a deployed image, so "do not publish a turn
+ * endpoint on this tunnel" has to be sayable without editing the definition.
+ *
+ * It takes `POST /run` WITH it, including over a definition that said `http.run: true`. Both routes start a
+ * turn for an anonymous caller, and the flag's whole reason for existing is the case where the definition cannot be
+ * edited — `dev --tunnel --no-invoke` leaving the other one published at the tunnel URL would be the flag failing at
+ * exactly the job it was added for.
  */
-export declare function resolveBindHost(bindFlag: string | undefined, configured: string | undefined, tunnel: boolean): string | undefined;
+export declare function withRunOverrides<T extends MountableAgent>(opened: T, run: {
+    invoke?: boolean;
+}): T;
 /** What the CLI adds to the assembly: its shutdown grace, and exit on a connection that drops. */
 export declare function cliMountOptions(wrapAgent: (agent: Agent) => Agent): MountAgentServiceOptions;
 /**
- * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the
- * tail dev's worker and start share once the service is assembled.
+ * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the tail dev's worker
+ * and start share once the service is assembled.
  */
 export declare function serveService(service: AgentService, bind: {
     port: number;
@@ -30,36 +34,48 @@ export declare function serveService(service: AgentService, bind: {
     agentDir: string;
     stateRoot: string;
 }): void;
-/**
- * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
- * what mounted. One function because both commands must say the same thing at the same moment —
- * after readiness, never at socket bind.
- */
+/** The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and what mounted. */
 export declare function reportServing(service: AgentService, host: string | undefined, boundPort: number): void;
+/** The line that names WHERE the serve is — every posture reports it, including AgentCore's own surface. */
+export declare function bindLine(host: string | undefined, boundPort: number): string;
 /**
- * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
- * ONE function because they are one message — they were two, and `--bind` updated the first while the
- * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
- * neither can be changed without the other in view, and the address has a single derivation.
+ * The startup lines for a serve of OUR surface: the bind report, and the curl the reader copies.
  *
- * A wildcard bind is every interface, and naming one address there would understate it — but the curl
- * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ * `servesInvoke` is `AgentService.unverifiedRoutes`, never a guess from the route table: `http.invoke: false` leaves no
+ * `/invoke` to curl, and a channel may serve that path with a protocol of its own — both would turn this line into
+ * a copyable request that fails.
  */
-export declare function readyAddressLines(host: string | undefined, boundPort: number, builtinInvoke: boolean): string[];
+export declare function readyAddressLines(host: string | undefined, boundPort: number, servesInvoke: boolean): string[];
 /**
- * Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the control plane
- * once the port is known, and say what reaches it. Returns the file's removal — wired into the
- * shutdown so a stale file cannot point a client at a dead port (`attach` then fails with "cannot
- * read", accurate, instead of a stale token's misleading 401/ECONNREFUSED). A hard exit leaves the
- * file behind: advisory, overwritten by the next boot.
+ * Say what this port exposes and how far it reaches.
  *
- * Here and not in the assembly: the file, its permissions and the warnings are how THIS process's
- * operator finds and protects the plane. An embedder distributes `service.control` itself.
+ * NOTHING fastagent serves is authenticated — authentication belongs to the deployment (a gateway, a private
+ * network, AgentCore's IAM, an embedder's middleware). Two of the three warnings fire at a REACH the operator did
+ * not get by default: a bind off this machine, and `--tunnel`'s public URL.
+ *
+ * The cross-origin one is UNCONDITIONAL, including on a loopback `dev`, because the grant is. `*` is the default
+ * (`channels/serve.ts`), so a page the developer merely visits can drive this port from their browser and read the
+ * reply, loopback bind or not. Nobody opts into a default, so the one posture the decision costs is the one that
+ * has to hear about it.
+ *
+ * WHAT IS EXPOSED is read off `AgentService.unverifiedRoutes`, never assumed and never guessed from the route table.
+ * `POST /invoke` is on most serves but not all: AgentCore answers the Runtime's `/invocations` behind IAM,
+ * `http.invoke: false` withholds it, and a channel may serve that path itself — in which case the caller it is
+ * open to is the platform that signs its requests, not anyone at all. A warning naming an endpoint this process
+ * does not serve is how an operator learns to skim past all of them — the same reason `preflightDeploy` takes
+ * `publicUrl`.
  */
-export declare function announceControl(control: {
-    token: string;
-    prefix: string;
-} | undefined, stateRoot: string, bind: {
+export declare function announceControl(service: Pick<AgentService, "controlPrefix" | "unverifiedRoutes" | "corsOrigins">, bind: {
     host?: string;
     tunnel: boolean;
-}, boundPort: number): () => void;
+}): void;
+/** Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment. */
+export declare function serve(handler: ChannelHandler, bind: {
+    port: number;
+    host?: string;
+}, hooks?: {
+    /** Awaited before anything is reported ready — see the listening handler. */
+    ready?: Promise<void>;
+    onListening?: (boundPort: number) => void;
+    onShutdown?: () => Promise<void> | void;
+}): void;