@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/dist/cli/commands/add.js

@@ -0,0 +1,142 @@
+/**
+ * `fastagent add <channel>|skill` — scaffold channel glue (`channels/<kind>.ts`) or vendor an Agent
+ * Skills skill. feishu/lark additionally CREATE OR RESUME the platform app (cli-add-feishu.ts).
+ */
+import { randomBytes } from "node:crypto";
+import { join, relative, resolve } from "node:path";
+import { onboardFeishuCloudApp } from "../../cli-add-feishu.js";
+import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
+import { detectRuntime, readPackageJson } from "../../runtime.js";
+import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, } from "../../scaffold/add-channel.js";
+import { vendorSkill } from "../../scaffold/vendor-skill.js";
+import { loadRootIgnore } from "../../workspace.js";
+import { failStartup, failUsage } from "../fail.js";
+/** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */
+export async function runAddChannel(channelKind, dirArg, opts) {
+    const target = resolve(dirArg);
+    // App creation is not a flag — it is what `add feishu` IS (the scan-to-create flow is the default
+    // and only path there). The retired --create-app spelling gets a pointer, not silence.
+    if (opts.createApp) {
+        if (channelKind === "feishu") {
+            console.error(`[fastagent] note: --create-app is retired — \`add feishu\` creates the app by default`);
+        }
+        else if (channelKind === "lark") {
+            failStartup(new Error("--create-app is retired — `add lark` now opens the developer console and guides credential setup by default"));
+        }
+        else {
+            failStartup(new Error("--create-app is retired — app creation is the default behavior of `add feishu`"));
+        }
+    }
+    // The channel (glue + companion tool) is agent surface — it lands in agentDir (config.agentDir, or
+    // target when flat), the same place dev/start discover channels/. .env(.example) and the secret
+    // hygiene stay at the run root, where .env is actually read.
+    const { config: addConfig } = await loadConfig(target).catch(failStartup);
+    const channelHome = resolveAgentDir(target, addConfig);
+    // Preconditions before the write, so a refusal is side-effect-free. feishu/lark are exceptions:
+    // their add is scaffold + ONBOARD THE APP, so an existing scaffold skips the write and continues (a
+    // failed or cancelled scan/paste flow must be re-runnable without hand-deleting glue); never touch it.
+    const file = join(channelHome, "channels", `${channelKind}.ts`);
+    if (await channelExists(channelHome, channelKind).catch(failStartup)) {
+        if (channelKind !== "feishu" && channelKind !== "lark") {
+            failStartup(new Error(`${relative(target, file)} already exists — edit it, or remove it to re-scaffold`));
+        }
+        console.error(`[fastagent] ${relative(target, file)} already exists — keeping it`);
+    }
+    else {
+        await assertChannelReady(channelHome).catch(failStartup);
+        await scaffoldChannel(channelHome, channelKind).catch(failStartup);
+        console.error(`[fastagent] created ${relative(target, file)}`);
+    }
+    if (await appendChannelEnv(target, channelKind).catch(failStartup)) {
+        console.error(`[fastagent] added ${channelKind} env vars to .env.example`);
+    }
+    // Secret hygiene: a channel's GENERATED secret (a random string the user contributes nothing to) is
+    // written into `.env` — but only when `.env` is already gitignored: the CLI must never materialize a
+    // secret into a committable file. Warn, not refuse, when it is exposed — channel glue may read a real
+    // env var instead.
+    const envIgnored = (await loadRootIgnore(target).catch(failStartup))?.ignores(".env") ?? false;
+    if (!envIgnored) {
+        console.error(`[fastagent] warn: .env is not gitignored — a deploy that copies the directory would ship a secret placed there; add .env to .gitignore/.fastagentignore, or use a real env var`);
+    }
+    // `add feishu`/`add lark` = scaffold + CREATE OR RESUME the app (cli-add-feishu.ts): feishu persists
+    // its irreversible App ID/Secret boundary internally; lark returns guided credentials for the
+    // generic .env write below.
+    let created;
+    if (channelKind === "feishu" || channelKind === "lark") {
+        created = await onboardFeishuCloudApp(target, channelKind, envIgnored).catch(failStartup);
+    }
+    const { env, steps } = channelSetup(channelKind);
+    const generated = Object.fromEntries(env.filter((e) => e.generate).map((e) => [e.name, randomBytes(24).toString("hex")]));
+    // Kind-neutral: every channel's generated secrets get the same treatment (github's webhook secret is
+    // the same class of value as telegram's); guided Lark credentials ride the same write as overwrites.
+    // Feishu's irreversible credentials were already staged inside cli-add-feishu.ts before bootstrap.
+    const dotEnv = envIgnored
+        ? await appendChannelDotEnv(target, channelKind, { ...generated, ...created }, Object.keys(created ?? {})).catch(failStartup)
+        : undefined;
+    if (dotEnv && dotEnv.written.length > 0) {
+        console.error(`[fastagent] wrote ${dotEnv.written.join(", ")} to .env`);
+    }
+    const install = detectRuntime(channelHome, await readPackageJson(channelHome)).runtime === "bun" ? "bun install" : "npm install";
+    // The kit's manifest lives in channelHome (agentDir when set) — point the install there, not the run root.
+    const installCmd = channelHome === target ? install : `(cd ${relative(target, channelHome)} && ${install})`;
+    console.error(`  next steps:`);
+    console.error(`    ${installCmd}                      # if @fastagent-sh/fastagent is not installed yet`);
+    for (const e of env) {
+        if (dotEnv?.alreadySet.includes(e.name))
+            continue; // the user already has it — nothing to do
+        if (dotEnv?.written.includes(e.name)) {
+            // Written, but its hint may still carry an action (github: paste the same value into the webhook
+            // UI) — keep the variable visible instead of silently absorbing it.
+            console.error(`    ${e.name} — ${e.generate ? "generated and " : ""}written to .env   # ${e.hint}`);
+            continue;
+        }
+        const value = e.generate ? `=${generated[e.name]}` : "";
+        const action = e.required ? "set" : "optionally set";
+        console.error(`    ${action} ${e.name}${value} in .env${envIgnored ? " (gitignored)" : ""}   # ${e.hint}`);
+    }
+    // Steps carry `{channel}`/`{tools}` path placeholders (their filenames are the scaffold's private
+    // knowledge) — resolve them to the real workspace-relative locations (agentDir-aware) here.
+    const kitPrefix = channelHome === target ? "" : `${relative(target, channelHome)}/`;
+    for (const s of steps) {
+        console.error(`    ${s.replace("{channel}", relative(target, file)).replace("{tools}", `${kitPrefix}tools`)}`);
+    }
+    if (channelKind !== "lark") {
+        console.error(`    fastagent dev --tunnel   # serve locally + a public URL, auto-registering the webhook`);
+    }
+    // The app-creation flow leaves keep-alive sockets behind (platform API fetches, the throwaway tunnel's
+    // health probes) that would hold the event loop open for a while — the work is done, exit crisply.
+    process.exit(0);
+}
+/** `fastagent add skill <source> [dir]`: vendor an Agent Skills skill into <dir>/skills/<name>/. */
+export async function runAddSkill(source, dirArg, opts) {
+    const target = resolve(dirArg);
+    if (!source) {
+        // A missing source is a usage error (exit 2), but the guide is worth more than a bare
+        // missing-argument line — the common path (writing your own skill) needs no command at all.
+        failUsage(`add a skill — two ways:\n` +
+            `  1. write your own (vibe): create skills/<name>/SKILL.md with name + description\n` +
+            `     frontmatter; it's auto-discovered. No command needed — this is the common path.\n` +
+            `  2. vendor an existing Agent Skills skill (copied in, git-tracked):\n` +
+            `       fastagent add skill <source> [dir]\n` +
+            `     source: a git ref (owner/repo/path, github default), a local path (./x, /abs), or a\n` +
+            `             bare name found in your global skill dirs (~/.agents/skills, ~/.pi/agent/skills)\n` +
+            `     --update overwrites an existing skill (re-fetch from source); review with git diff`);
+    }
+    // Skills are agent surface — vendored into agentDir/skills (config.agentDir, or target when flat).
+    const { config: skillConfig } = await loadConfig(target).catch(failStartup);
+    const skillHome = resolveAgentDir(target, skillConfig);
+    const { name, description, dest, hasScripts, diagnostics, overwritten } = await vendorSkill(skillHome, source, {
+        update: opts.update ?? false,
+    }).catch(failStartup);
+    console.error(`[fastagent] ${overwritten ? "updated" : "vendored"} skill "${name}" → ${dest}/`);
+    if (overwritten)
+        console.error(`  overwrote it — \`git diff ${dest}\` to review, \`git checkout ${dest}\` to revert`);
+    if (description)
+        console.error(`  ${description.length > 100 ? `${description.slice(0, 100)}…` : description}`);
+    for (const d of diagnostics)
+        console.error(`  warn: ${d.message}`);
+    if (hasScripts) {
+        console.error(`  warn: this skill ships scripts/ (executable code that runs in your agent) — review it before deploying`);
+    }
+    console.error(`  next: mention "${name}" in persona.md so the model knows when to use it; then \`fastagent dev\``);
+}

package/dist/cli/commands/chat.d.ts

@@ -0,0 +1,3 @@
+export declare function runChat(dirArg: string, opts: {
+    model?: string;
+}): Promise<void>;

package/dist/cli/commands/chat.js

@@ -0,0 +1,16 @@
+/** `fastagent chat [dir]`: open the SAME assembled agent in pi's interactive TUI. */
+import { resolve } from "node:path";
+import { loadDotEnv } from "../../env.js";
+import { installProxyFetch } from "../../proxy.js";
+import { failStartup } from "../fail.js";
+export async function runChat(dirArg, opts) {
+    const dir = resolve(dirArg);
+    loadDotEnv(dir);
+    installProxyFetch(); // model calls (and the login dialog) must go through the proxy too
+    // Run the chat process IN the workspace: pi resolves a session's cwd as `header.cwd ?? process.cwd()`,
+    // so aligning process.cwd() with the workspace keeps a cwd-less session on the workspace. `dir` is absolute.
+    process.chdir(dir);
+    // Lazy-import: chat pulls pi's interactive TUI module graph; headless start/dev never need it.
+    const { runPiChat } = await import("../../engines/pi/chat.js");
+    await runPiChat(dir, { model: opts.model }).catch(failStartup);
+}

package/dist/cli/commands/deploy.d.ts

@@ -0,0 +1,13 @@
+export type DeployHost = "docker" | "fly" | "railway";
+export interface DeployOptions {
+    run?: boolean;
+    tunnel?: boolean;
+    force?: boolean;
+    stop?: boolean;
+    /** false ⇔ `--no-scale-to-zero`. */
+    scaleToZero?: boolean;
+    intoLinked?: boolean;
+    model?: string;
+    authPath?: string;
+}
+export declare function runDeploy(host: DeployHost, dirArg: string, opts: DeployOptions): Promise<void>;

package/dist/cli/commands/deploy.js

@@ -0,0 +1,338 @@
+/**
+ * `fastagent deploy <host> [dir]`: generate host artifacts from the resolved definition and print an
+ * ordered deploy runbook. Host-scoped (`docker` | `fly` | `railway` — the extension seam). It does NOT
+ * run the host CLI by default: fastagent owns the definition-aware artifacts and precise runbook;
+ * Docker may opt into a generated ephemeral tunnel, while durable ingress stays operator-owned. The pre-flight
+ * (config/model/channels/container facts) is host-neutral; the host branch adds its config + run drive.
+ * Read-only on the definition; the only writes are generated artifacts (never clobbered without
+ * --force). `--run` drives the target CLI instead of printing.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { registerFeishuWebhook } from "../../channels/feishu/register-webhook.js";
+import { registerTelegramWebhook } from "../../channels/telegram/register-webhook.js";
+import { isGeneratedDockerfile } from "../../deploy/container.js";
+import { composeHasTunnelService, dockerWebhookPaths, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../deploy/docker/plan.js";
+import { deployDockerRun } from "../../deploy/docker/run.js";
+import { parseFlyAppName, parseFlyMinMachines, parseFlyRegion, planFlyDeploy, toFlyAppName, } from "../../deploy/fly/plan.js";
+import { deployFlyRun } from "../../deploy/fly/run.js";
+import { preflightDeploy } from "../../deploy/preflight.js";
+import { planRailwayDeploy } from "../../deploy/railway/plan.js";
+import { deployRailwayRun } from "../../deploy/railway/run.js";
+import { spawnRunner } from "../../deploy/runner.js";
+import { assembleSecrets } from "../../deploy/secrets.js";
+import { loadDotEnv } from "../../env.js";
+import { loadConfig, resolveAgentDir, resolveAuthPathOverride, resolveModelSpec } from "../../engines/pi/config.js";
+import { installProxyFetch } from "../../proxy.js";
+import { openExternalUrl } from "../../open-url.js";
+import { exists } from "../../scaffold/init.js";
+import { announceWebhooks } from "../../tunnel.js";
+import { failStartup, failUsage } from "../fail.js";
+export async function runDeploy(host, dirArg, opts) {
+    const target = resolve(dirArg);
+    if (opts.tunnel && host !== "docker") {
+        // A flag/host combination the parser cannot see (host is an argument) — usage class, exit 2.
+        failUsage(`deploy stopped: --tunnel is supported only by the local Docker target`);
+    }
+    loadDotEnv(target); // a custom provider/tool may read a key at config load
+    installProxyFetch(); // post-deploy channel API calls must honor HTTP(S)_PROXY under Node
+    const { config } = await loadConfig(target).catch(failStartup);
+    const agentDir = resolveAgentDir(target, config);
+    const modelSpec = resolveModelSpec(opts.model, config);
+    // The host-neutral pre-flight (model-travel gate, channel discovery, model-auth probe, container facts +
+    // their warnings) lives in deploy/preflight.ts — testable in isolation. The CLI prints its messages and
+    // stops on its gate; the host branch below adds only the host-specific artifacts + runbook + run drive.
+    const pre = await preflightDeploy({
+        target,
+        agentDir,
+        config,
+        modelSpec,
+        run: !!opts.run,
+        force: !!opts.force,
+        authPathOverride: resolveAuthPathOverride(opts.authPath),
+    }).catch(failStartup);
+    if (!pre.ok)
+        failStartup(new Error(`deploy stopped: ${pre.gate}`));
+    for (const m of pre.messages)
+        console.error(`[fastagent] ${m.level}: ${m.text}`);
+    const { channels, hasTimeTriggers, modelAuth, authPath, container, port, extraSecrets } = pre;
+    // 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(target));
+        const dockerPlan = (tunnel) => planDockerDeploy({ projectName, port, modelAuth, channels, tunnel, extraSecrets, ...container });
+        const requestedTunnel = !!opts.tunnel;
+        let plan = dockerPlan(requestedTunnel);
+        // An existing Compose file is authoritative: shape its comparison/runbook from the topology on disk,
+        // regardless of the current flag. `--force` is the explicit reset to the requested generated shape.
+        const composeFile = join(target, plan.composePath);
+        let keptWithoutRequestedTunnel = false;
+        if (!opts.force && (await exists(composeFile))) {
+            const existingHasTunnel = composeHasTunnelService(await readFile(composeFile, "utf8"));
+            plan = dockerPlan(existingHasTunnel);
+            keptWithoutRequestedTunnel = requestedTunnel && !existingHasTunnel;
+        }
+        await writeArtifacts(target, plan.artifacts, {
+            force: !!opts.force,
+            neverForce: container.kitDir ? [".dockerignore"] : [],
+        });
+        if (opts.run) {
+            return runDeployDocker({
+                target,
+                agentDir,
+                composeFile: plan.composePath,
+                port,
+                requireTunnel: requestedTunnel,
+                modelAuth,
+                authPath,
+                channels,
+                extraSecrets,
+            });
+        }
+        if (keptWithoutRequestedTunnel) {
+            console.error(`[fastagent] warn: --tunnel was requested but kept ${plan.composePath} has no "tunnel" service — ` +
+                `edit it, delete it and regenerate, or pass --force`);
+        }
+        console.log(plan.runbook.join("\n"));
+        return;
+    }
+    // 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(target)
+            .replace(/[^a-zA-Z0-9-]+/g, "-")
+            .replace(/^-+|-+$/g, "") || "agent";
+        const plan = planRailwayDeploy({ serviceName, modelAuth, channels, extraSecrets, hasTimeTriggers, ...container });
+        await writeArtifacts(target, plan.artifacts, {
+            force: !!opts.force,
+            neverForce: container.kitDir ? [".dockerignore"] : [],
+        });
+        if (opts.run) {
+            return runDeployRailway({
+                target,
+                name: serviceName,
+                modelAuth,
+                authPath,
+                channels,
+                extraSecrets,
+                intoLinked: !!opts.intoLinked,
+            });
+        }
+        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")) {
+        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.`);
+    }
+    // Two consistent modes. KEEP (no --force): an existing fly.toml is authoritative — not rewritten,
+    // and the runbook reads its `app=` (Fly app names are globally unique, so the basename guess may be
+    // taken and the user renamed it). --force: the template is authoritative — the WHOLE fly.toml resets
+    // (app→basename, region→iad, vm→defaults), so we do NOT round-trip `app` and warn that hand edits go.
+    // Kit layout: fly.toml lives under the kit (agent/fly.toml) — the host repo's own fly.toml (if any)
+    // belongs to the host's product deploy and is never read or written here.
+    const flyTomlPath = container.kitDir ? join(target, container.kitDir, "fly.toml") : join(target, "fly.toml");
+    const flyTomlExists = await exists(flyTomlPath);
+    const keptApp = flyTomlExists && !opts.force ? parseFlyAppName(await readFile(flyTomlPath, "utf8")) : undefined;
+    const appName = keptApp ?? toFlyAppName(basename(target));
+    if (keptApp)
+        console.error(`[fastagent] app: ${keptApp} (from fly.toml)`);
+    if (flyTomlExists && opts.force) {
+        console.error(`[fastagent] warn: --force resets fly.toml to defaults (app, region, vm) — re-apply any hand edits`);
+    }
+    // Autostop flags shape the GENERATED fly.toml only. In KEEP mode (fly.toml exists, no --force) it is
+    // not rewritten, so the flags would silently do nothing — surface that instead of a confusing no-op.
+    if (flyTomlExists && !opts.force && (opts.stop || opts.scaleToZero === false)) {
+        console.error(`[fastagent] warn: --stop/--no-scale-to-zero only shape a freshly generated fly.toml — yours exists and ` +
+            `was kept. Edit auto_stop_machines/min_machines_running in fly.toml, or pass --force to regenerate.`);
+    }
+    // KEEP mode + time triggers: the kept fly.toml may still scale to zero — which would sleep through every
+    // cron instant / wake-up. The generated plan can't fix a kept file, so surface it instead of the preflight
+    // note silently not applying (the author who deployed FIRST and added schedules LATER hits exactly this).
+    // Under `--run` this is a GATE (same discipline as the model-travel gate): a full deploy whose schedules
+    // silently never fire is worse than a crash-loop — nothing fails visibly when a cron instant passes on a
+    // sleeping machine, and unlike github's min=0 there is no legitimate trade to accept here.
+    if (flyTomlExists && !opts.force && hasTimeTriggers) {
+        const min = parseFlyMinMachines(await readFile(flyTomlPath, "utf8"));
+        if ((min ?? 0) === 0) {
+            // undefined = the line is absent — Fly's platform default for min_machines_running is 0, so a
+            // hand-written fly.toml without the line scales to zero exactly like an explicit 0.
+            const msg = `your kept fly.toml scales to zero (min_machines_running = ${min ?? "absent → platform default 0"}), but ` +
+                `schedules/self-scheduling need a running machine (no external wake-up). Set min_machines_running = 1, ` +
+                `or pass --force to regenerate.`;
+            if (opts.run)
+                failStartup(new Error(`deploy stopped: ${msg}`));
+            console.error(`[fastagent] warn: ${msg}`);
+        }
+    }
+    const plan = planFlyDeploy({
+        appName,
+        port,
+        modelAuth,
+        channels,
+        extraSecrets,
+        hasTimeTriggers,
+        ...container,
+        autostop: opts.stop ? "stop" : "suspend",
+        scaleToZero: opts.scaleToZero !== false,
+    });
+    await writeArtifacts(target, plan.artifacts, {
+        force: !!opts.force,
+        neverForce: container.kitDir ? [".dockerignore"] : [],
+    });
+    if (opts.run)
+        return runDeployFly({ target, appName, modelAuth, authPath, channels, flyTomlPath, extraSecrets });
+    console.log(plan.runbook.join("\n"));
+}
+/**
+ * Write each generated artifact. An existing file is KEPT unless --force — deploy NEVER clobbers a file
+ * without it (no silent data loss). A Dockerfile/Compose file WE generated is definition-derived, so a
+ * KEPT one that no longer matches what deploy would generate now (config/channel/lockfile/version drift —
+ * OR the user's own edits, which we can't distinguish) is flagged stale; --force regenerates it. A
+ * hand-written Dockerfile/Compose/ignore or fly.toml's app+region state is simply kept.
+ */
+async function writeArtifacts(target, artifacts, options) {
+    for (const a of artifacts) {
+        const abs = join(target, a.path);
+        // Host-owned paths (the root .dockerignore in the agentDir layout): --force means "MY generated
+        // artifact is authoritative", which never licenses clobbering the HOST's file — keep it always.
+        if (options.neverForce?.includes(a.path) && (await exists(abs))) {
+            console.error(`[fastagent] kept ${a.path} — the host repo's own file (never overwritten, even with --force); ` +
+                `see the preflight warnings for what it must contain`);
+            continue;
+        }
+        if (!options.force && (await exists(abs))) {
+            const existing = await readFile(abs, "utf8");
+            const generatedDrift = (a.path.endsWith("Dockerfile") && isGeneratedDockerfile(existing)) ||
+                (a.path.endsWith("fastagent.compose.yml") && isGeneratedCompose(existing));
+            if (generatedDrift && existing !== a.content) {
+                console.error(`[fastagent] kept ${a.path} — it no longer matches what deploy would generate (config changed, or ` +
+                    `you edited it); pass --force to regenerate.`);
+            }
+            else {
+                console.error(`[fastagent] kept ${a.path} (exists — pass --force to overwrite)`);
+            }
+            continue;
+        }
+        await mkdir(dirname(abs), { recursive: true }); // kit-layout artifacts live under agent/
+        await writeFile(abs, a.content);
+        console.error(`[fastagent] wrote ${a.path}`);
+    }
+}
+/**
+ * `deploy docker --run`: carry local credentials into Compose's child environment, then reconcile the
+ * user-owned local topology. Docker owns container/network/volume lifecycle. A Compose tunnel service,
+ * when present, yields an ephemeral URL that reuses the same webhook announcer as `dev --tunnel`.
+ */
+async function runDeployDocker(params) {
+    const { target, agentDir, composeFile, port, requireTunnel, modelAuth, authPath, channels, extraSecrets } = params;
+    const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
+        modelAuth,
+        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
+        channels,
+        extraSecrets,
+        env: process.env,
+    });
+    const outcome = await deployDockerRun({ composeFile, port, secrets, missingSecrets, needsModelCredential, requireTunnel }, spawnRunner("docker", target), (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, { openUrl: openExternalUrl });
+        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);
+    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)`);
+    }
+}
+/**
+ * `deploy fly --run`: drive flyctl to completion (idempotent, resumable). Gathers the secret VALUES
+ * from the local env — the model key (env auth) or the whole auth.json as a `FASTAGENT_AUTH_SEED` seed
+ * (OAuth/stored auth: the deployed box materializes it onto the /data volume on first boot, so a
+ * personal deploy runs on the SAME subscription) plus channel secrets — then runs the flyctl steps
+ * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the agent).
+ */
+async function runDeployFly(params) {
+    const { target, appName, modelAuth, authPath, channels, flyTomlPath, extraSecrets } = params;
+    const fly = spawnRunner("fly", target);
+    // 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,
+        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
+        channels,
+        extraSecrets,
+        env: process.env,
+    });
+    // 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 outcome = await deployFlyRun({ appName, region, secrets, missingSecrets, channels, flyConfig: "fly.toml" }, fly, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind));
+    if (!outcome.ok)
+        failStartup(new Error(`deploy stopped: ${outcome.gate}`));
+    console.error(`[fastagent] deployed → https://${appName}.fly.dev`);
+}
+/**
+ * `deploy railway --run`: drive the railway CLI to completion. Mirrors {@link runDeployFly} — same
+ * credential carry (env key OR the OAuth auth.json as `FASTAGENT_AUTH_SEED`) via {@link assembleSecrets},
+ * same runner seam (spawned `railway`, cwd = the workspace so `railway up`'s upload is the agent). The
+ * Railway-specific sequence (linked-check → init/add/volume when fresh → variables → up → domain →
+ * webhook) lives in {@link deployRailwayRun}; see there for why Railway differs from Fly.
+ */
+async function runDeployRailway(params) {
+    const { target, name, modelAuth, authPath, channels, extraSecrets, intoLinked } = params;
+    const railway = spawnRunner("railway", target);
+    // 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,
+        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
+        channels,
+        extraSecrets,
+        env: process.env,
+    });
+    // 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, intoLinked }, railway, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind));
+    if (!outcome.ok)
+        failStartup(new Error(`deploy stopped: ${outcome.gate}`));
+    console.error(`[fastagent] deployed → ${outcome.url}`);
+}

package/dist/cli/commands/dev.d.ts

@@ -0,0 +1,11 @@
+export interface DevOptions {
+    port?: string;
+    model?: string;
+    authPath?: string;
+    /** false ⇔ `--no-watch`. */
+    watch?: boolean;
+    tunnel?: boolean;
+    /** false ⇔ `--no-input`. */
+    input?: boolean;
+}
+export declare function runDev(dirArg: string, opts: DevOptions): Promise<void>;

package/dist/cli/commands/dev.js

@@ -0,0 +1,76 @@
+/**
+ * `fastagent dev`: a SUPERVISOR that spawns a worker (this command with FASTAGENT_DEV_WORKER set) to
+ * assemble + serve, restarting it on workspace edits. A fresh process per reload means what is served
+ * is always the latest code, including modules a tool/config imports.
+ */
+import { resolve } from "node:path";
+import { runDevSupervisor } from "../../dev-supervisor.js";
+import { loadDotEnv } from "../../env.js";
+import { resolveAuthPathOverride } from "../../engines/pi/config.js";
+import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
+import { log, setLogLevel } from "../../log.js";
+import { logAgentLoop } from "../../observe.js";
+import { installProxyFetch } from "../../proxy.js";
+import { failStartup } from "../fail.js";
+import { maybeTunnel, routesFor, serve, startSchedules } from "../serve.js";
+import { parsePort, reportAuth, resolveFirstRunModel } from "../shared.js";
+export async function runDev(dirArg, opts) {
+    const dir = resolve(dirArg);
+    setLogLevel("debug"); // dev posture: verbose, includes the debug turn trace (content) — supervisor and worker both
+    const isWorker = process.env.FASTAGENT_DEV_WORKER === "1";
+    // Pick a model interactively once, in the parent (both watch and --no-watch have a TTY); a spawned
+    // watch worker inherits the choice via FASTAGENT_MODEL, so it must not prompt again. Load .env and
+    // the proxy FIRST (as invoke/start do): the picker reads FASTAGENT_MODEL and provider keys from
+    // .env, and getAuth's OAuth refresh must go through HTTPS_PROXY. The worker re-loads both in serveOnce.
+    if (!isWorker) {
+        loadDotEnv(dir);
+        installProxyFetch();
+        await resolveFirstRunModel(dir, opts);
+    }
+    if (isWorker || opts.watch === false) {
+        await serveOnce(dir, opts);
+        return;
+    }
+    parsePort(opts.port, "--port", "flag"); // flag-shape check before spawning
+    await runDevSupervisor(dir, { tunnel: opts.tunnel ?? false });
+}
+/** Assemble the workspace agent and serve it once (the dev worker; also the --no-watch path). */
+async function serveOnce(dir, opts) {
+    const portFlag = parsePort(opts.port, "--port", "flag");
+    loadDotEnv(dir);
+    installProxyFetch();
+    const a = await createPiAgentFromWorkspace(dir, {
+        model: opts.model,
+        authPath: resolveAuthPathOverride(opts.authPath),
+        serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
+    }).catch(failStartup);
+    log.info(`[fastagent] dir:    ${dir}`);
+    if (a.agentDir !== dir)
+        log.info(`[fastagent] agent:  ${a.agentDir}`);
+    log.info(`[fastagent] config: ${a.configPath ?? "(zero-config)"}`);
+    log.info(`[fastagent] model:  ${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
+    await reportAuth(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.
+    const traced = logAgentLoop(a.agent);
+    const routes = await routesFor(a.agentDir, traced, a.stateRoot).catch(failStartup);
+    await startSchedules(a.agentDir, traced, a.stateRoot, a.config.selfSchedule ?? false);
+    serve(routes, portFlag ?? a.config.http?.port ?? 8787, (p) => maybeTunnel(a.agentDir, p, opts.tunnel ?? false));
+}
+/** The agents/skills/tools/collisions report lines. */
+function reportAgentsSkillsTools(a) {
+    log.info(`[fastagent] context: ${a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)"}`);
+    if (a.definition.persona)
+        log.info(`[fastagent] persona: persona.md`);
+    log.info(`[fastagent] skills: ${a.definition.skills.map((s) => s.name).join(", ") || "(none)"}`);
+    if (a.toolNames.length > 0)
+        log.info(`[fastagent] tools:  ${a.toolNames.join(", ")}`);
+    if (a.deferredToolNames.length > 0) {
+        log.info(`[fastagent] deferred: ${a.deferredToolNames.join(", ")} (activated via search_tools)`);
+    }
+    reportToolCollisions(a.toolCollisions);
+    reportModuleLoadFailures(a.toolFailures);
+    reportDefinitionWarnings(a.definition.collisions, a.definition.diagnostics);
+}

package/dist/cli/commands/fire.d.ts

@@ -0,0 +1,7 @@
+export interface FireOptions {
+    model?: string;
+    authPath?: string;
+    /** false ⇔ `--no-input`. */
+    input?: boolean;
+}
+export declare function runFire(name: string, dirArg: string, opts: FireOptions): Promise<void>;