@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/cli/commands/deploy.js

@@ -8,7 +8,7 @@
  * --force). `--run` drives the target CLI instead of printing.
  */
 import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
-import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { registerFeishuWebhook } from "../../channels/feishu/register-webhook.js";
@@ -17,8 +17,9 @@ import { registerSlackWebhook } from "../../channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "../../channels/telegram/register-webhook.js";
 import { FORWARDER_FILE, TEMPLATE_FILE, agentcoreName, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../deploy/agentcore/plan.js";
 import { deployAgentcoreRun } from "../../deploy/agentcore/run.js";
+import { webhookPaths } from "../../deploy/channel-ingress.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "../../deploy/container.js";
-import { composeHasTunnelService, dockerWebhookPaths, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../deploy/docker/plan.js";
+import { composeHasTunnelService, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../deploy/docker/plan.js";
 import { deployDockerRun } from "../../deploy/docker/run.js";
 import { isGeneratedFlyToml, parseFlyAppName, parseFlyMinMachines, parseFlyRegion, planFlyDeploy, toFlyAppName, } from "../../deploy/fly/plan.js";
 import { deployFlyRun } from "../../deploy/fly/run.js";
@@ -29,18 +30,120 @@ import { spawnRunner } from "../../deploy/runner.js";
 import { assembleSecrets } from "../../deploy/secrets.js";
 import { loadDotEnv } from "../../env.js";
 import { loadConfig, resolveModelSpec } from "../../engines/pi/config.js";
-import { resolveStateRoot } from "../../paths.js";
+import { resolveStateRoot, exists } from "../../paths.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { installProxyFetch } from "../../proxy.js";
 import { openExternalUrl } from "../../open-url.js";
-import { exists } from "../../paths.js";
 import { announceWebhooks } from "../../tunnel.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 import { resolveFirstRunModel } from "../shared.js";
+/** The deploy targets, as a value: {@link HOST_ONLY_FLAGS} is checked against this list by a test, and
+ *  a type alone cannot be enumerated at runtime. NOT the only copy — `cli/program.ts` repeats it as the
+ *  `<host>` argument's `choices`, because that file may not import a command module at load time (its
+ *  per-command imports are lazy). Adding a host means editing both; the type there rides in on a
+ *  `import type`, which costs nothing at runtime. */
+export const DEPLOY_HOSTS = ["docker", "fly", "railway", "agentcore"];
+/** The registrars every host driver gets. One wiring: a channel's credentials are the channel's, not
+ *  the host's, so which of them can run end-to-end never varies by deployment target. */
+function registrarsFor(agentDir) {
+    return {
+        telegram: (baseUrl) => registerTelegramWebhook(baseUrl),
+        slack: (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir) }),
+        feishu: (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind),
+    };
+}
 /** A copy/paste-safe POSIX shell argument for the command hints deploy prints. */
 function shellArg(value) {
     return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 }
+/** Infers `Owner` from the literal's own `owner`, so each row carries its exhaustiveness itself. The
+ *  alternative — annotating the array as a tuple of `HostOnlyFlag<"fly"> | …` — put the whole guarantee
+ *  in one annotation that a third rule invites relaxing to `HostOnlyFlag<DeployHost>[]`, where
+ *  `Exclude<DeployHost, DeployHost>` collapses to `never` and every `instead` type-checks empty. */
+const hostOnlyFlag = (rule) => rule;
+/**
+ * ONE table for "this flag belongs to that host", because the fact is symmetric and was not stored
+ * that way: each host branch stated the OTHER hosts' flags in its own words, so the same sentence
+ * existed three times per flag and had already drifted (`Railway-only` twice, `railway-only` once).
+ *
+ * Every row is a flag that only WARNS elsewhere. `--tunnel` is host-only too and is deliberately not
+ * here: it is a usage GATE (`failUsage`, exit 2) raised in `runDeploy`, not a warning — moving it in
+ * would downgrade a refusal to a line of advice.
+ *
+ * Exported for the exhaustiveness test: the type stops a missing `instead` line, and the test stops it
+ * from being typed away.
+ */
+export const HOST_ONLY_FLAGS = [
+    hostOnlyFlag({
+        flag: "--stop/--no-scale-to-zero",
+        owner: "fly",
+        passed: (opts) => opts.stop === true || opts.scaleToZero === false,
+        instead: {
+            docker: "local Compose stays running",
+            railway: "Railway's App Sleeping is a dashboard toggle (the runbook states the manual step)",
+            agentcore: "AgentCore's idle/lifetime policy lives in the template's LifecycleConfiguration",
+        },
+    }),
+    hostOnlyFlag({
+        flag: "--into-linked",
+        owner: "railway",
+        passed: (opts) => opts.intoLinked === true,
+        instead: {
+            docker: "ignored for local Docker",
+            agentcore: "ignored for AgentCore",
+            fly: "fly --run is idempotent — it reuses an existing app/volume",
+        },
+    }),
+];
+/** Exported for its own test: nothing covered these six sentences, which is how three of them came to
+ *  disagree about the spelling of a host name. */
+export function warnHostOnlyFlags(host, opts) {
+    for (const rule of HOST_ONLY_FLAGS) {
+        if (host === rule.owner || !rule.passed(opts))
+            continue;
+        // The `continue` above is exactly the key set `instead` is typed over, but TS cannot narrow a
+        // union member out through a comparison against a per-rule literal, so the read needs a cast —
+        // and a cast is how a hole would reach the operator as the word "undefined". Unreachable while
+        // the rows stay exhaustive, which is what the table's own test asserts.
+        const instead = rule.instead[host];
+        // THROWN, not `failStartup`ed, though every other failure in this file exits through that: an
+        // incomplete table is a bug, and fail.ts prints a plain Error's message WITHOUT its stack (it
+        // reserves that shape for user-fixable problems) while exiting the process — which in the test
+        // that covers this table would kill the worker instead of reporting which row is short.
+        if (instead === undefined) {
+            throw new Error(`deploy: HOST_ONLY_FLAGS has no "instead" line for ${host} on ${rule.flag}`);
+        }
+        // A colon, not "is": one row names a single flag and the other names a pair, and no verb agrees
+        // with both (the hand-written copies this replaced said "is" and "are" respectively).
+        console.error(`[fastagent] warn: ${rule.flag}: ${rule.owner}-only — ${instead}`);
+    }
+}
+/**
+ * The `--run` credential carry, for every host: the local model credential (an env key, or the whole
+ * auth.json as a `FASTAGENT_AUTH_SEED`) plus channel secrets, read through the one environment that
+ * accounts for Slack's rotated bot token. Four drivers assembled this identically; a fifth would have
+ * had to remember the `deployEnvironment` wrapper, which is invisible when forgotten (a rotated token
+ * silently deploys stale).
+ */
+async function carryCredentials(params) {
+    const { agentDir, modelAuth, modelKeyInDefinition, authPath, channels, extraSecrets } = params;
+    return assembleSecrets({
+        modelAuth,
+        modelKeyInDefinition,
+        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
+        channels,
+        extraSecrets,
+        env: deployEnvironment(agentDir, channels),
+    });
+}
+/** Gate a `--run` that has no model credential to carry. Its remediation is `fastagent login`, which
+ *  is why it is separate from `missingSecrets` (a `.env` fix) rather than folded into it. Docker states
+ *  the same gate inside its driver, where it belongs after the daemon check. */
+function gateOnModelCredential(needsModelCredential) {
+    if (!needsModelCredential)
+        return;
+    failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
+}
 export async function runDeploy(host, dirArg, opts) {
     // ONE deploy semantic: bake the WORKSPACE (WYSIWYG). Artifacts land under the agent dir
     // (`fastagent/`) plus the one workspace-root `.dockerignore` the packers require; host CLIs run
@@ -76,30 +179,26 @@ export async function runDeploy(host, dirArg, opts) {
         failStartup(new Error(`deploy stopped: ${pre.gate}`));
     for (const m of pre.messages)
         console.error(`[fastagent] ${m.level}: ${m.text}`);
-    const { channels, routeChannels, longConnectionChannels, hasTimeTriggers, modelAuth, modelKeyInDefinition, authPath, container, port, extraSecrets, } = pre;
-    const hasDeclaredChannels = routeChannels.length + longConnectionChannels.length > 0;
+    const { channels, hasTimeTriggers, modelAuth, modelKeyInDefinition, authPath, container, port, extraSecrets } = pre;
+    const webhookChannels = channels.filter((channel) => channel.ingress === "webhook");
+    const longConnectionChannels = channels.filter((channel) => channel.ingress === "long-connection");
+    const hasDeclaredChannels = channels.length > 0;
+    warnHostOnlyFlags(host, opts);
     // Docker: one app service + loopback port + state volume. `--tunnel` shapes the generated topology
     // with an optional Quick Tunnel service; `--run` alone decides whether Docker receives side effects.
     if (host === "docker") {
-        if (opts.stop || opts.scaleToZero === false) {
-            console.error(`[fastagent] warn: --stop/--no-scale-to-zero are Fly-only — local Compose stays running`);
-        }
-        if (opts.intoLinked) {
-            console.error(`[fastagent] warn: --into-linked is Railway-only — ignored for local Docker`);
-        }
         const projectName = toDockerProjectName(basename(workspace));
         const dockerPlan = (tunnel) => planDockerDeploy({
             projectName,
             port,
             modelAuth,
             channels,
-            longConnectionChannels,
             tunnel,
             extraSecrets,
             ...container,
         });
-        const requestedTunnel = !!opts.tunnel && (!hasDeclaredChannels || routeChannels.length > 0);
-        if (opts.tunnel && hasDeclaredChannels && routeChannels.length === 0) {
+        const requestedTunnel = !!opts.tunnel && (!hasDeclaredChannels || webhookChannels.length > 0);
+        if (opts.tunnel && hasDeclaredChannels && webhookChannels.length === 0) {
             console.error(`[fastagent] note: --tunnel skipped — every channel uses a long connection`);
         }
         let plan = dockerPlan(requestedTunnel);
@@ -129,7 +228,6 @@ export async function runDeploy(host, dirArg, opts) {
                 modelKeyInDefinition,
                 authPath,
                 channels,
-                longConnectionChannels,
                 extraSecrets,
             });
         }
@@ -143,10 +241,6 @@ export async function runDeploy(host, dirArg, opts) {
     // Railway: thin config file, scale-to-zero is a manual dashboard step, the URL is minted (see
     // planRailwayDeploy). --run drives the railway CLI to completion; otherwise print the runbook.
     if (host === "railway") {
-        if (opts.stop || opts.scaleToZero === false) {
-            console.error(`[fastagent] warn: --stop/--no-scale-to-zero are Fly-only — Railway's App Sleeping is a dashboard toggle ` +
-                `(the runbook states the manual step).`);
-        }
         // Railway service names are project-scoped (not globally unique like a Fly app); slug the dir
         // basename so a name with spaces/odd chars can't break the `railway add --service <name>` command.
         const serviceName = basename(workspace)
@@ -156,7 +250,6 @@ export async function runDeploy(host, dirArg, opts) {
             serviceName,
             modelAuth,
             channels,
-            longConnectionChannels,
             extraSecrets,
             hasTimeTriggers,
             ...container,
@@ -180,7 +273,6 @@ export async function runDeploy(host, dirArg, opts) {
                 modelKeyInDefinition,
                 authPath,
                 channels,
-                longConnectionChannels,
                 extraSecrets,
                 intoLinked: !!opts.intoLinked,
                 dockerfilePath: dockerfilePathVar(pre.container.agentPrefix),
@@ -192,18 +284,11 @@ export async function runDeploy(host, dirArg, opts) {
     // AgentCore: one CloudFormation stack (runtime + forwarder Lambda + EventBridge schedules); no
     // public URL and no resident process — see deploy/agentcore/plan.ts for the topology decisions.
     if (host === "agentcore") {
-        if (opts.stop || opts.scaleToZero === false) {
-            console.error(`[fastagent] warn: --stop/--no-scale-to-zero are Fly-only — AgentCore's idle/lifetime policy lives in ` +
-                `the template's LifecycleConfiguration.`);
-        }
-        if (opts.intoLinked) {
-            console.error(`[fastagent] warn: --into-linked is Railway-only — ignored for AgentCore`);
-        }
         // Long-connection channels are STRUCTURALLY unsupported: the connection is the ingress, and a
         // reclaimed session has nothing to wake it — events in the gap are silently lost. `--run` gates
         // (deploying a channel that can't connect); generate-only warns and prints the runbook.
         if (longConnectionChannels.length > 0) {
-            const msg = `long-connection channel (${longConnectionChannels.join(", ")}) cannot run on AgentCore — there is no ` +
+            const msg = `long-connection channel (${longConnectionChannels.map((c) => c.name).join(", ")}) cannot run on AgentCore — there is no ` +
                 `resident process to hold the connection, and nothing wakes a reclaimed session. Switch the channel ` +
                 `to webhook mode (its events then ride the forwarder like every other channel).`;
             if (opts.run)
@@ -230,7 +315,6 @@ export async function runDeploy(host, dirArg, opts) {
             name: acName,
             modelAuth,
             channels,
-            routeChannels,
             extraSecrets,
             schedules: loaded.schedules.map((s) => ({ name: s.name, cron: s.cron, tz: s.tz })),
             selfSchedule: !!config.selfSchedule,
@@ -247,7 +331,7 @@ export async function runDeploy(host, dirArg, opts) {
         // Host capability limit, stated at plan time. GitHub's own webhook contract is 25 MiB, but a
         // Lambda Function URL request caps at 6 MB — so on this host a large payload cannot arrive at
         // all. Better a sentence here than an opaque 502 the first time someone pushes a big diff.
-        if (channels.includes("github")) {
+        if (channels.some((channel) => channel.name === "github")) {
             console.error(`[fastagent] note: on AgentCore a webhook body is capped at ~${Math.round(MAX_WEBHOOK_BODY_BYTES / (1 << 20))} MiB ` +
                 `(the forwarder's Function URL limit); the GitHub channel accepts 25 MiB on a resident host, so the largest ` +
                 `payloads are rejected here rather than delivered`);
@@ -287,20 +371,17 @@ export async function runDeploy(host, dirArg, opts) {
                 selfSchedule: !!config.selfSchedule,
                 // Same predicate the template uses for the forwarder resource — kept in one expression so
                 // the run path and the topology cannot disagree about whether a forwarder exists.
-                needsForwarder: routeChannels.length > 0 || loaded.schedules.length > 0 || !!config.selfSchedule,
+                needsForwarder: webhookChannels.length > 0 || loaded.schedules.length > 0 || !!config.selfSchedule,
             });
         }
         console.log(plan.runbook.join("\n"));
         return;
     }
     // host === "fly".
-    if (opts.intoLinked) {
-        console.error(`[fastagent] warn: --into-linked is railway-only (fly --run is idempotent — it reuses an existing app/volume)`);
-    }
     // The replay floor that makes scale-to-zero safe is Telegram-only (its L1 turn store). GitHub turns
     // are fire-and-forget (no replay), so the generated fly.toml keeps one machine running for them —
     // a note, not a warn, since the plan already did the safe thing (definition-aware autostop).
-    if (channels.includes("github")) {
+    if (channels.some((channel) => channel.name === "github")) {
         console.error(`[fastagent] note: github turns have no replay — the generated fly.toml uses min_machines_running=1 ` +
             `(no scale-to-zero) so autostop can't drop an in-flight review. Set it to 0 to accept that trade.`);
     }
@@ -344,7 +425,7 @@ export async function runDeploy(host, dirArg, opts) {
             // hand-written fly.toml without the line scales to zero exactly like an explicit 0.
             const reason = hasTimeTriggers
                 ? `schedules/self-scheduling need a running machine (no external wake-up)`
-                : `long-connection channel (${longConnectionChannels.join(", ")}) needs an always-on outbound connection`;
+                : `long-connection channel (${longConnectionChannels.map((c) => c.name).join(", ")}) needs an always-on outbound connection`;
             const msg = `your kept fly.toml scales to zero (min_machines_running = ${min ?? "absent → platform default 0"}), but ` +
                 `${reason}. Set min_machines_running = 1, or pass --force to regenerate.`;
             if (opts.run)
@@ -357,7 +438,6 @@ export async function runDeploy(host, dirArg, opts) {
         port,
         modelAuth,
         channels,
-        longConnectionChannels,
         extraSecrets,
         hasTimeTriggers,
         ...container,
@@ -377,30 +457,13 @@ export async function runDeploy(host, dirArg, opts) {
             modelKeyInDefinition,
             authPath,
             channels,
-            longConnectionChannels,
             flyTomlPath,
             extraSecrets,
         });
     }
     console.log(plan.runbook.join("\n"));
 }
-/**
- * Write each generated artifact, under ONE ownership rule: **deploy only ever overwrites its own
- * output.** Each generated file opens with a marker, so a file on disk is either OURS (a previous
- * `deploy` wrote it) or the author's — and `--force` means "my generated artifact is authoritative",
- * which never licenses clobbering a file we did not write. To hand a path back to fastagent, delete it.
- *
- * That single rule replaced a second mechanism (a per-host list of paths exempt from `--force`), which
- * only described one shape: with the agent inside the workspace, the root `.dockerignore` is the
- * WORKSPACE's file and was listed; with the agent flat, the list was empty — so `--force` would have
- * overwritten a hand-written root `Dockerfile` in a repository `init --flat` had explicitly adopted.
- * Ownership is a property of the file, not of where the agent sits.
- *
- * A KEPT file of OURS that no longer matches what deploy would generate now (config/channel/lockfile/
- * version drift — or the author's edits, which we cannot tell apart) is flagged stale; `--force`
- * regenerates that one.
- */
-/** Did fastagent generate the file at `path`? ONE table for all five artifact kinds: a kind missing from
+/** Did fastagent generate the file at `path`? ONE table for every artifact kind: a kind missing from
  *  it is permanently classified as the author's, which silently turns `--force` into a no-op for that
  *  file (`fly.toml` and `railway.json` were, until the marker predicates below existed). */
 function isOurArtifact(path, content) {
@@ -419,10 +482,24 @@ function isOurArtifact(path, content) {
     return false;
 }
 /**
- * Write the plan's artifacts under `target`, honouring the ownership rule: a file we did not generate is
- * never touched, ours is kept unless `--force`. Exported for its own test — this is a four-branch state
- * machine over (exists, ours, force) that used to be proven by spawning the CLI eight times, which is
- * command LOGIC re-run through a subprocess (see vitest.config.ts) and the suite's slowest test.
+ * Write each generated artifact under `target`, under ONE ownership rule: **deploy only ever overwrites
+ * its own output.** Each generated file opens with a marker, so a file on disk is either OURS (a previous
+ * `deploy` wrote it) or the author's — and `--force` means "my generated artifact is authoritative",
+ * which never licenses clobbering a file we did not write. To hand a path back to fastagent, delete it.
+ *
+ * That single rule replaced a second mechanism (a per-host list of paths exempt from `--force`), which
+ * only described one shape: with the agent inside the workspace, the root `.dockerignore` is the
+ * WORKSPACE's file and was listed; with the agent flat, the list was empty — so `--force` would have
+ * overwritten a hand-written root `Dockerfile` in a repository `init --flat` had explicitly adopted.
+ * Ownership is a property of the file, not of where the agent sits.
+ *
+ * A KEPT file of OURS that no longer matches what deploy would generate now (config/channel/lockfile/
+ * version drift — or the author's edits, which we cannot tell apart) is flagged stale; `--force`
+ * regenerates that one.
+ *
+ * Exported for its own test — this is a four-branch state machine over (exists, ours, force) that used
+ * to be proven by spawning the CLI eight times, which is command LOGIC re-run through a subprocess
+ * (see vitest.config.ts) and the suite's slowest test.
  */
 export async function writeArtifacts(target, artifacts, options) {
     for (const a of artifacts) {
@@ -461,7 +538,7 @@ export async function writeArtifacts(target, artifacts, options) {
     }
 }
 function deployEnvironment(agentDir, channels) {
-    if (!channels.includes("slack"))
+    if (!channels.some((channel) => channel.name === "slack"))
         return process.env;
     const latest = readSlackBotAuthEnv(join(resolveStateRoot(agentDir), "channels", "slack", "bot-auth.json"));
     return { ...process.env, ...latest };
@@ -472,37 +549,43 @@ function deployEnvironment(agentDir, channels) {
  * when present, yields an ephemeral URL that reuses the same webhook announcer as `dev --tunnel`.
  */
 async function runDeployDocker(params) {
-    const { agentDir, workspace, composeFile, port, requireTunnel, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, extraSecrets, } = params;
-    const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
-        modelAuth,
-        modelKeyInDefinition,
-        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
-        channels,
-        longConnectionChannels,
-        extraSecrets,
-        env: deployEnvironment(agentDir, channels),
-    });
-    const outcome = await deployDockerRun({ composeFile, port, secrets, missingSecrets, needsModelCredential, requireTunnel }, spawnRunner("docker", workspace), (message) => console.error(`[fastagent] ${message}`));
-    if (!outcome.ok)
-        failStartup(new Error(`deploy stopped: ${outcome.gate}`));
-    const compose = `docker compose -f ${composeFile}`;
-    console.error(`[fastagent] running${outcome.url ? ` → ${outcome.url}` : ""}`);
-    console.error(`[fastagent] logs: ${compose} logs -f agent`);
-    console.error(`[fastagent] stop: ${compose} down (state volume is kept)`);
-    if (outcome.tunnelUrl) {
-        // Docker Desktop commonly injects a host proxy. The Quick Tunnel hostname may be resolvable only
-        // through it, exactly like provider/channel APIs; use the same Node dispatcher as dev/start/login.
-        installProxyFetch();
-        await announceWebhooks(agentDir, outcome.tunnelUrl, {
+    const { agentDir, workspace, composeFile, port, requireTunnel, channels } = params;
+    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    const outcome = await deployDockerRun({
+        composeFile,
+        port,
+        secrets,
+        missingSecrets,
+        needsModelCredential,
+        requireTunnel,
+        announce: (tunnelUrl) => announceWebhooks(agentDir, tunnelUrl, channels, {
             openUrl: openExternalUrl,
-            routeChannels: channels.filter((kind) => !longConnectionChannels.includes(kind)),
             stateRoot: resolveStateRoot(agentDir),
-        });
+        }),
+    }, spawnRunner("docker", workspace), (message) => console.error(`[fastagent] ${message}`));
+    const compose = `docker compose -f ${composeFile}`;
+    // Compose reached "up" iff the driver could report where it is. The gates before that point
+    // (no Docker CLI, no daemon, missing secrets) must not be preceded by `docker compose logs`
+    // instructions for containers that do not exist; the health-check gate names its own logs command.
+    const isUp = outcome.ok || outcome.url !== undefined || outcome.tunnelUrl !== undefined;
+    if (outcome.url)
+        console.error(`[fastagent] running → ${outcome.url}`);
+    if (isUp) {
+        console.error(`[fastagent] logs: ${compose} logs -f agent`);
+        console.error(`[fastagent] stop: ${compose} down (state volume is kept)`);
+    }
+    // BEFORE failStartup: a registration gate says "re-run this deploy", and a re-run rebuilds the
+    // tunnel service — the operator needs to know the URL will be a different one, or they will read
+    // the retry as re-registering the same address.
+    if (outcome.tunnelUrl) {
         console.error(`[fastagent] note: Quick Tunnel URLs are ephemeral — after the tunnel container/Docker daemon ` +
             `restarts, re-run this deploy so webhooks receive the new URL`);
-        return;
     }
-    const paths = dockerWebhookPaths(channels.filter((kind) => !longConnectionChannels.includes(kind)));
+    if (!outcome.ok)
+        failStartup(new Error(`deploy stopped: ${outcome.gate}`));
+    if (outcome.tunnelUrl)
+        return;
+    const paths = webhookPaths(channels);
     if (paths.length > 0) {
         console.error(`[fastagent] note: public ingress is operator-owned — configure your tunnel/proxy, then wire the ` +
             `default webhook path(s): ${paths.join(", ")} (or your remapped channel routes)`);
@@ -516,37 +599,24 @@ async function runDeployDocker(params) {
  * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the whole workspace).
  */
 async function runDeployFly(params) {
-    const { agentDir, workspace, agentPrefix, appName, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, flyTomlPath, extraSecrets, } = params;
+    const { agentDir, workspace, agentPrefix, appName, channels, flyTomlPath } = params;
     const fly = spawnRunner("fly", workspace);
     // Fail fast if flyctl is absent (spawn ENOENT → 127), with the install link — not a confusing auth gate.
     if ((await fly(["version"], { capture: true })).code === 127) {
         failStartup(new Error(`flyctl not found — install it: https://fly.io/docs/flyctl/install, then re-run`));
     }
     const region = parseFlyRegion(await readFile(flyTomlPath, "utf8")) ?? "iad";
-    const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
-        modelAuth,
-        modelKeyInDefinition,
-        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
-        channels,
-        longConnectionChannels,
-        extraSecrets,
-        env: deployEnvironment(agentDir, channels),
-    });
-    // Model credential has its OWN remediation (login), distinct from a missing secret's (.env) — gate it
-    // here, not through missingSecrets, so the message isn't a contradictory mash of both.
-    if (needsModelCredential) {
-        failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
-    }
+    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    gateOnModelCredential(needsModelCredential);
     const outcome = await deployFlyRun({
         appName,
         region,
         secrets,
         missingSecrets,
         channels,
-        longConnectionChannels,
         flyConfig: `${agentPrefix}fly.toml`,
         dockerfile: `${agentPrefix}Dockerfile`,
-    }, fly, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir) }));
+    }, fly, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → https://${appName}.fly.dev`);
@@ -559,15 +629,8 @@ async function runDeployFly(params) {
  * file (secret values off argv) is created here — 0600, removed after the run either way.
  */
 async function runDeployAgentcore(params) {
-    const { agentDir, workspace, agentPrefix, name, modelAuth, modelKeyInDefinition, authPath, channels, extraSecrets, selfSchedule, } = params;
-    const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
-        modelAuth,
-        modelKeyInDefinition,
-        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
-        channels,
-        extraSecrets,
-        env: deployEnvironment(agentDir, channels),
-    });
+    const { agentDir, workspace, agentPrefix, name, channels, selfSchedule } = params;
+    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
     // The wake-alarm shared secret (container ↔ forwarder). Minted fresh each run — both sides receive
     // the SAME parameter, so rotation is atomic; it never needs to be remembered locally.
     if (selfSchedule)
@@ -576,9 +639,7 @@ async function runDeployAgentcore(params) {
     // principal's. Minted fresh each run — both sides receive the SAME parameter, so rotation is atomic.
     if (params.needsForwarder)
         secrets.FASTAGENT_INGRESS_SECRET = crypto.randomUUID();
-    if (needsModelCredential) {
-        failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
-    }
+    gateOnModelCredential(needsModelCredential);
     // The params temp dir holds the ONE file carrying secret values (file:// parameter-overrides —
     // never argv); 0700/0600 and removed after the run, success or gate.
     const paramsDir = await mkdtemp(join(tmpdir(), "fastagent-agentcore-"));
@@ -601,13 +662,12 @@ async function runDeployAgentcore(params) {
         }, spawnRunner("aws", workspace), spawnRunner("docker", workspace), (m) => console.error(`[fastagent] ${m}`), async (content) => {
             const path = join(paramsDir, "params.json");
             await writeFile(path, content, { mode: 0o600 });
-            await chmod(path, 0o600);
             return path;
         }, async (bytes) => {
             const path = join(paramsDir, "forwarder.zip");
             await writeFile(path, bytes);
             return path;
-        }, (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir) }));
+        }, registrarsFor(agentDir));
         if (!outcome.ok)
             failStartup(new Error(`deploy stopped: ${outcome.gate}`));
         console.error(`[fastagent] deployed → ${outcome.runtimeArn}`);
@@ -634,26 +694,15 @@ async function runDeployAgentcore(params) {
  * webhook) lives in {@link deployRailwayRun}; see there for why Railway differs from Fly.
  */
 async function runDeployRailway(params) {
-    const { agentDir, workspace, name, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, extraSecrets, intoLinked, dockerfilePath, } = params;
+    const { agentDir, workspace, name, channels, intoLinked, dockerfilePath } = params;
     const railway = spawnRunner("railway", workspace);
     // Fail fast if the railway CLI is absent (spawn ENOENT → 127), with the install link.
     if ((await railway(["--version"], { capture: true })).code === 127) {
         failStartup(new Error(`railway CLI not found — install it: https://docs.railway.com/guides/cli, then re-run`));
     }
-    const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
-        modelAuth,
-        modelKeyInDefinition,
-        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
-        channels,
-        longConnectionChannels,
-        extraSecrets,
-        env: deployEnvironment(agentDir, channels),
-    });
-    // Model credential has its OWN remediation (login), distinct from a missing secret's (.env).
-    if (needsModelCredential) {
-        failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
-    }
-    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, longConnectionChannels, intoLinked, dockerfilePath }, railway, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir) }));
+    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    gateOnModelCredential(needsModelCredential);
+    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, intoLinked, dockerfilePath }, railway, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → ${outcome.url}`);

package/dist/cli/commands/dev.js

@@ -6,19 +6,15 @@
 import { resolve } from "node:path";
 import { runDevSupervisor } from "../../dev-supervisor.js";
 import { loadDotEnv } from "../../env.js";
-import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
-import { reportModuleLoadFailures } from "../../log.js";
-import { CODING_TOOL_NAMES } from "../../engines/pi/create.js";
+import { setLogLevel } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { mountAgentService } from "../../service.js";
-import { setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
-import { workspaceHint } from "../../paths.js";
 import { bindAddress } from "../../bind.js";
 import { failStartup, placementOrExit } from "../fail.js";
 import { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
-import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { parseBind, parsePort, reportAssembly, resolveFirstRunModel } from "../shared.js";
 export async function runDev(dirArg, opts) {
     const dir = resolve(dirArg);
     const placement = placementOrExit(dir);
@@ -54,15 +50,8 @@ async function serveOnce(dir, opts) {
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
         serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
     }).catch(failStartup);
-    reportLine("agent", a.agentDir);
-    reportLine("workspace", a.workspace);
-    reportWorkspaceHint(workspaceHint(a));
-    reportLine("config", a.configPath ?? "(none)");
-    reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
-    await reportAuth(a.agentDir, a.modelSpec, a.authPath);
-    reportAgentsSkillsTools(a);
-    // Trace each turn's agent loop (tool calls + reply) to the log at debug level — shown in dev, gated
-    // out in start (level info), keeping end-user content out of production logs. Wired in both postures.
+    // The same report `start` prints; `config:` is dev's own extra (see reportAssembly on the asymmetry).
+    await reportAssembly(a, { beforeModel: [["config", a.configPath ?? "(none)"]] });
     // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
     // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
     const configured = a.config.http?.host;
@@ -89,19 +78,3 @@ async function serveOnce(dir, opts) {
         onShutdown: () => service.close(),
     });
 }
-/** The agents/skills/tools/collisions report lines. */
-function reportAgentsSkillsTools(a) {
-    reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
-    if (a.definition.persona)
-        reportLine("persona", "persona.md");
-    reportLine("skills", a.definition.skills.map((s) => s.name).join(", ") || "(none)");
-    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
-    if (a.toolNames.length > 0)
-        reportLine("tools", a.toolNames.join(", "));
-    if (a.deferredToolNames.length > 0) {
-        reportLine("deferred", `${a.deferredToolNames.join(", ")} (activated via search_tools)`);
-    }
-    reportToolCollisions(a.toolCollisions);
-    reportModuleLoadFailures(a.toolFailures);
-    reportFindingsIfChanged(a.definition.dir, a.definition);
-}

package/dist/cli/commands/info.js

@@ -8,8 +8,7 @@ import { resolveStateRoot, workspaceHint } from "../../paths.js";
 import { CODING_TOOL_NAMES, resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
 import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
-import { reportModuleLoadFailures } from "../../log.js";
-import { log } from "../../log.js";
+import { reportModuleLoadFailures, log } from "../../log.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { failStartup, placementOrExit } from "../fail.js";

package/dist/cli/commands/init.js

@@ -7,10 +7,9 @@
  */
 import { spawn } from "node:child_process";
 import { basename, join, resolve } from "node:path";
-import { DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentsAt } from "../../paths.js";
+import { DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentsAt, displayPath } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
 import { agentDirName, agentDirNameError, scaffoldAgent } from "../../scaffold/init.js";
-import { displayPath } from "../../paths.js";
 import { failStartup, failUsage } from "../fail.js";
 export async function runInit(dirArg, opts) {
     const dir = resolve(dirArg);