@fastagent-sh/fastagent 0.12.0

package/dist/collect.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Buffered consumption helper (caller-side, SPEC §7): reduce an AgentEvent stream to a final value,
+ * encoding the terminal discipline (failed → throw, missing terminal → error). Streaming consumers
+ * for-await themselves.
+ */
+import type { AgentEvent, Json } from "./agent.ts";
+/** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
+ *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
+export declare class AgentFailure extends Error {
+    readonly details: string;
+    readonly retryable: boolean;
+    /** Machine-readable failure subdivision (SPEC §8), when the engine set one. */
+    readonly code?: string;
+    constructor(details: string, retryable: boolean, code?: string);
+}
+export interface CollectResult {
+    text: string;
+    data?: Json;
+}
+export declare function collect(events: AsyncIterable<AgentEvent>): Promise<CollectResult>;

package/dist/collect.js

@@ -0,0 +1,27 @@
+/** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
+ *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
+export class AgentFailure extends Error {
+    details;
+    retryable;
+    /** Machine-readable failure subdivision (SPEC §8), when the engine set one. */
+    code;
+    constructor(details, retryable, code) {
+        super(details);
+        this.name = "AgentFailure";
+        this.details = details;
+        this.retryable = retryable;
+        this.code = code;
+    }
+}
+export async function collect(events) {
+    let text = "";
+    for await (const e of events) {
+        if (e.type === "text")
+            text += e.delta;
+        else if (e.type === "completed")
+            return { text, data: e.data };
+        else if (e.type === "failed")
+            throw new AgentFailure(e.details, e.retryable, e.code);
+    }
+    throw new Error("stream ended without a terminal event"); // violates SPEC MUST 1
+}

package/dist/core.d.ts

@@ -0,0 +1,10 @@
+export type { Agent, AgentEvent, ImageRef, Json, Prompt, Scope } from "./agent.ts";
+export { collect, AgentFailure, type CollectResult } from "./collect.ts";
+export type { ModuleLoadFailure } from "./loader.ts";
+export { createInvokeHandler, nodeListener } from "./channels/http.ts";
+export { readBodyCapped } from "./channels/body.ts";
+export { text, textHeaders } from "./channels/respond.ts";
+export { type ChannelContext, type ChannelHandler, type ChannelModule, type Routes, router, serveNode, } from "./host/node.ts";
+export { defineSchedule, type LoadedSchedule, type Schedule } from "./schedule/schedule.ts";
+export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.ts";
+export { createScheduler, scheduleSession, type Scheduler, type SchedulerOptions } from "./schedule/scheduler.ts";

package/dist/core.js

@@ -0,0 +1,8 @@
+export { collect, AgentFailure } from "./collect.js";
+export { createInvokeHandler, nodeListener } from "./channels/http.js";
+export { readBodyCapped } from "./channels/body.js";
+export { text, textHeaders } from "./channels/respond.js";
+export { router, serveNode, } from "./host/node.js";
+export { defineSchedule } from "./schedule/schedule.js";
+export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.js";
+export { createScheduler, scheduleSession } from "./schedule/scheduler.js";

package/dist/deploy/container.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The portable container — Dockerfile + .dockerignore, host-neutral. Every deploy target ships these
+ * unchanged; only the host config (fly.toml / railway.json) and the CLI sequence differ. The image
+ * runs `fastagent start /app` on `$PORT` with state under `$FASTAGENT_STATE_DIR` — standard container
+ * conventions, no host coupling. Extracted from the Fly plan when Railway became the second target.
+ */
+export interface Artifact {
+    path: string;
+    content: string;
+}
+/** Fixed first-line prefix of a fastagent-generated Dockerfile — the ONE source both the generator (the
+ *  `head` below) and the "is this ours?" check (cli deploy's kept-Dockerfile apt warn) share, so they
+ *  can't drift into detecting a marker the generator no longer writes. */
+export declare const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
+/** The ONE predicate for "did fastagent generate this Dockerfile?" — a generated file opens with the
+ *  marker, so a hand-written one (or a file where the marker was dropped to take ownership) reads false.
+ *  Both the "keep vs flag-as-stale" decision and the apt warning share this; a split would let them
+ *  disagree on the same file (e.g. a marker not at byte 0). */
+export declare function isGeneratedDockerfile(content: string): boolean;
+export interface ContainerInput {
+    /** Whether the workspace has a package.json (a code workspace); else a pure markdown/skills agent. */
+    hasPackageJson: boolean;
+    /** The package manager the generated image targets: `bun` (packageManager: bun / a bun lockfile) gets an
+     *  `oven/bun` base + `bun install` + `bun run fastagent`; otherwise npm on `node:22-slim`. */
+    runtime: "node" | "bun";
+    /** Whether the runtime's lockfile exists (package-lock.json for npm, bun.lock/bun.lockb for bun) — a
+     *  frozen/ci install needs it; without it the build resolves versions at build time (not reproducible). */
+    hasLockfile: boolean;
+    /** For `runtime: "bun"`, the `FROM oven/bun:<tag>` version (from packageManager `bun@x`), else `"1"`. */
+    bunVersion?: string;
+    /** This fastagent version, to PIN the global install on the markdown path (reproducible redeploys). */
+    version: string;
+    /** Extra apt packages (fastagent.config deploy.apt) baked in for the agent's tools — git, ripgrep, …. */
+    apt?: string[];
+    /**
+     * Repo-as-workspace layout: the agent kit's subdirectory relative to the repo root (e.g. "agent" —
+     * `config.agentDir` resolved). When set, the image bakes the WHOLE repo as the agent's cwd (§11 bake
+     * decision), installs the KIT's deps (not the host's — the agent installs those in its workspace at
+     * runtime when its job needs them), ships `.git` (write-back via commit/push needs it), and the
+     * artifacts are namespaced under the kit so they never collide with the host repo's own
+     * Dockerfile/.dockerignore. The runtime facts (hasPackageJson/runtime/hasLockfile) describe the KIT.
+     */
+    kitDir?: string;
+}
+/**
+ * The Dockerfile + ignore artifacts — spread into any host's artifact list. Kit layout ({@link
+ * ContainerInput.kitDir}): the Dockerfile is namespaced under the kit (`agent/Dockerfile`) so it never
+ * collides with the host repo's own. The ignore ships in TWO forms because context packing is
+ * host-CLI-owned and inconsistent: (1) a ROOT `.dockerignore` — the only form flyctl/railway's own
+ * context packers reliably read (kept if the host already has one — preflight then warns specifically
+ * about a .git exclude / missing recursive node_modules) — and (2) a
+ * per-Dockerfile `agent/Dockerfile.dockerignore` for plain docker/buildx builds. Whether `.git`
+ * actually reaches the box is host-CLI-dependent (some strip it from the upload regardless of any
+ * ignore file) — the runbook's write-back note carries the runtime-clone fallback.
+ */
+export declare function containerArtifacts(input: ContainerInput): Artifact[];

package/dist/deploy/container.js

@@ -0,0 +1,169 @@
+/**
+ * The portable container — Dockerfile + .dockerignore, host-neutral. Every deploy target ships these
+ * unchanged; only the host config (fly.toml / railway.json) and the CLI sequence differ. The image
+ * runs `fastagent start /app` on `$PORT` with state under `$FASTAGENT_STATE_DIR` — standard container
+ * conventions, no host coupling. Extracted from the Fly plan when Railway became the second target.
+ */
+/** Fixed first-line prefix of a fastagent-generated Dockerfile — the ONE source both the generator (the
+ *  `head` below) and the "is this ours?" check (cli deploy's kept-Dockerfile apt warn) share, so they
+ *  can't drift into detecting a marker the generator no longer writes. */
+export const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
+/** The ONE predicate for "did fastagent generate this Dockerfile?" — a generated file opens with the
+ *  marker, so a hand-written one (or a file where the marker was dropped to take ownership) reads false.
+ *  Both the "keep vs flag-as-stale" decision and the apt warning share this; a split would let them
+ *  disagree on the same file (e.g. a marker not at byte 0). */
+export function isGeneratedDockerfile(content) {
+    return content.startsWith(GENERATED_DOCKERFILE_MARKER);
+}
+/** The repo-as-workspace Dockerfile: bake the repo as cwd, install the kit's deps, run from the kit. */
+function kitDockerfile(input, kit) {
+    const apt = aptLayer(input.apt);
+    if (!input.hasPackageJson) {
+        // Markdown-only kit: no deps to install — the pinned global CLI serves the repo directly.
+        return `${GENERATED_DOCKERFILE_MARKER}. Repo-as-workspace: the whole repo is the agent's cwd; the kit lives in ${kit}/.
+FROM node:22-slim
+${apt}WORKDIR /app
+RUN npm i -g @fastagent-sh/fastagent@${input.version}
+COPY . .
+CMD ["fastagent", "start", "/app"]
+`;
+    }
+    const isBun = input.runtime === "bun";
+    const base = isBun ? `oven/bun:${input.bunVersion ?? "1"}` : "node:22-slim";
+    const head = `${GENERATED_DOCKERFILE_MARKER}. Repo-as-workspace: the whole repo is the agent's cwd; the kit lives in ${kit}/.
+# Only the KIT's deps are installed — the host repo's own deps are the agent's runtime concern (it can
+# install them in its workspace when its job needs them). .git IS shipped: write-back needs it.
+FROM ${base}
+${apt}WORKDIR /app
+`;
+    if (isBun) {
+        const install = input.hasLockfile ? "bun install --frozen-lockfile" : "bun install";
+        return `${head}COPY ${kit}/package.json ${kit}/bun.lock* ./${kit}/
+RUN cd ${kit} && ${install}
+COPY . .
+CMD ["sh", "-c", "cd ${kit} && bun run fastagent start /app"]
+`;
+    }
+    const install = input.hasLockfile ? "npm ci" : "npm install";
+    return `${head}COPY ${kit}/package.json ${kit}/package-lock.json* ./${kit}/
+RUN cd ${kit} && ${install}
+COPY . .
+CMD ["./${kit}/node_modules/.bin/fastagent", "start", "/app"]
+`;
+}
+/** The apt layer (cached right after FROM). Debian default repos only. */
+function aptLayer(packages) {
+    return packages && packages.length > 0
+        ? `RUN apt-get update \\
+ && apt-get install -y --no-install-recommends ${packages.join(" ")} \\
+ && rm -rf /var/lib/apt/lists/*
+`
+        : "";
+}
+function dockerfile(input) {
+    // apt layer right after FROM (cached across code changes): the agent's tools may shell out to git etc.,
+    // which node:22-slim lacks. Debian default repos only — a package needing a custom repo (gh) or a
+    // different base is the operator's own Dockerfile (kept if present). deploy.apt is package-name-validated.
+    const apt = aptLayer(input.apt);
+    // No package.json → pure markdown/skills agent: install the pinned CLI GLOBALLY and run `fastagent`
+    // from PATH. That needs npm + a global bin, which live on node:22-slim, NOT on oven/bun — so this path
+    // pins node:22-slim regardless of input.runtime (a stray bun lockfile with no package.json would
+    // otherwise select a bun base here and crash the `npm i -g` build). input.runtime is meaningful only
+    // for a code workspace, so the bun-vs-node base below is scoped to that path.
+    if (!input.hasPackageJson) {
+        return `${GENERATED_DOCKERFILE_MARKER}. The directory IS the agent — no build step.
+# npm-based (a markdown/skills agent installs the pinned CLI globally; node:22-slim has npm).
+FROM node:22-slim
+${apt}WORKDIR /app
+RUN npm i -g @fastagent-sh/fastagent@${input.version}
+COPY . .
+CMD ["fastagent", "start", "/app"]
+`;
+    }
+    const isBun = input.runtime === "bun";
+    const base = isBun ? `oven/bun:${input.bunVersion ?? "1"}` : "node:22-slim";
+    const note = isBun
+        ? "# Bun-based (packageManager: bun / a bun lockfile detected). fastagent runs under Bun (bun run)."
+        : "# npm-based — for pnpm/yarn, adapt the install line + the lockfile COPY (corepack enable, etc.).";
+    const head = `${GENERATED_DOCKERFILE_MARKER}. The directory IS the agent — no build step.
+${note}
+FROM ${base}
+${apt}WORKDIR /app
+`;
+    // Install ALL deps (no --omit=dev / --production): a repo-as-agent (e.g. an Astro site it operates on)
+    // needs its full toolchain — the build/check tools that live in devDependencies — to do its work, and
+    // we can't tell a repo-as-agent from a purpose-built workspace, so the safe default keeps everything.
+    if (isBun) {
+        // `--frozen-lockfile` needs bun.lock and hard-fails without it; fall back to a plain `bun install`
+        // (resolves at build time — not reproducible; the CLI warns to commit the lockfile).
+        // `bun run` executes the LOCAL node_modules/.bin entry only — never the registry. A bare
+        // `bunx fastagent` would fall back to installing the npm package named `fastagent`, which is an
+        // unrelated third-party package (ours is the scoped @fastagent-sh/fastagent).
+        const install = input.hasLockfile ? "bun install --frozen-lockfile" : "bun install";
+        return `${head}COPY package.json bun.lock* ./
+RUN ${install}
+COPY . .
+CMD ["bun", "run", "fastagent", "start", "/app"]
+`;
+    }
+    // `npm ci` requires a lockfile and hard-fails without one (a common `init --no-install` workspace);
+    // fall back to `npm install` when there is none so the build never breaks. Caveat: `npm install`
+    // resolves caret ranges at build time, so THIS branch is NOT reproducible — unlike the pinned
+    // `npm ci` (lockfile) and pinned global (markdown) paths. The CLI warns to commit a lockfile.
+    // The explicit local bin, not `npx fastagent`: npx falls back to fetching the npm package named
+    // `fastagent` when the dep is absent — an unrelated third-party package (ours is scoped). The local
+    // path fails fast and visibly instead.
+    const install = input.hasLockfile ? "npm ci" : "npm install";
+    return `${head}COPY package.json package-lock.json* ./
+RUN ${install}
+COPY . .
+CMD ["./node_modules/.bin/fastagent", "start", "/app"]
+`;
+}
+const DOCKERIGNORE = `node_modules
+.fastagent
+.env
+.env.*
+!.env.example
+*.log
+# .git is excluded to keep the image small. If your agent runs git on its OWN history
+# (git log/blame over the repo it ships in), delete the next line so that history is in the image.
+.git
+`;
+/** The kit-layout ignore: `.git` is deliberately NOT excluded (write-back wants it — though whether it
+ *  survives is host-CLI-dependent; see containerArtifacts). Patterns are RECURSIVE (`**​/`) on purpose —
+ *  dockerignore patterns are root-anchored (unlike .gitignore), so a bare `node_modules` would NOT
+ *  exclude `agent/node_modules`: the build machine's kit deps (macOS binaries!) would be uploaded by
+ *  `COPY . .` and clobber the image's freshly-installed linux ones. */
+const KIT_DOCKERIGNORE = `**/node_modules
+**/.fastagent
+**/.env
+**/.env.*
+!**/.env.example
+**/*.log
+# .git is DELIBERATELY shipped: the agent's write-back (commit/push) needs the repo's history+remote.
+`;
+/**
+ * The Dockerfile + ignore artifacts — spread into any host's artifact list. Kit layout ({@link
+ * ContainerInput.kitDir}): the Dockerfile is namespaced under the kit (`agent/Dockerfile`) so it never
+ * collides with the host repo's own. The ignore ships in TWO forms because context packing is
+ * host-CLI-owned and inconsistent: (1) a ROOT `.dockerignore` — the only form flyctl/railway's own
+ * context packers reliably read (kept if the host already has one — preflight then warns specifically
+ * about a .git exclude / missing recursive node_modules) — and (2) a
+ * per-Dockerfile `agent/Dockerfile.dockerignore` for plain docker/buildx builds. Whether `.git`
+ * actually reaches the box is host-CLI-dependent (some strip it from the upload regardless of any
+ * ignore file) — the runbook's write-back note carries the runtime-clone fallback.
+ */
+export function containerArtifacts(input) {
+    if (input.kitDir) {
+        return [
+            { path: `${input.kitDir}/Dockerfile`, content: kitDockerfile(input, input.kitDir) },
+            { path: ".dockerignore", content: KIT_DOCKERIGNORE },
+            { path: `${input.kitDir}/Dockerfile.dockerignore`, content: KIT_DOCKERIGNORE },
+        ];
+    }
+    return [
+        { path: "Dockerfile", content: dockerfile(input) },
+        { path: ".dockerignore", content: DOCKERIGNORE },
+    ];
+}

package/dist/deploy/fly/plan.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `fastagent deploy fly` — the Fly.io deploy PLAN, computed from the resolved definition. Pure: facts
+ * in, artifact contents + an ordered runbook out; the CLI (deploy side effects live there) writes the
+ * files and prints the runbook.
+ *
+ * fastagent owns the two ends only it can know — generate definition-aware artifacts (state root →
+ * volume, autostop tuned to the turn model, the exact secret list) and the post-deploy webhook step —
+ * and GUIDES the middle (flyctl app/volume/secrets/deploy) as a precise, values-resolved runbook. By
+ * default a coding agent (or you) runs flyctl from that runbook; `deploy fly --run` drives it from the
+ * CLI instead. This module stays pure either way — it produces the plan, never runs flyctl. The runbook
+ * is a FIRST-deploy sequence: `apps`/`volumes create` are one-time (marked so — re-running would make a
+ * second volume, the state split it warns against); a redeploy is `fly deploy` alone.
+ *
+ * autostop = "suspend": the machine snapshots and suspends when idle (Fly Proxy sees inbound load 0),
+ * resumes on the next webhook in ~hundreds of ms. A long turn interrupted by an idle-suspend whose
+ * snapshot is discarded replays on the next start (the Telegram L1 turn store) — at-least-once, the
+ * documented floor. State on the /data volume survives stop/suspend on the same machine.
+ */
+import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Artifact, type ContainerInput } from "../container.ts";
+export interface FlyPlanInput extends ContainerInput {
+    /** Fly app name — globally unique, lowercase; the CLI sanitizes it from the dir basename. */
+    appName: string;
+    /** The port the app listens on (config.http.port ?? 8787); fly.toml routes to it. */
+    port: number;
+    /**
+     * What satisfies model auth locally ({@link probeAuthSource}): an env-var name (`OPENAI_API_KEY`),
+     * `"OAuth"`/`"stored credential"` (a local login the server can't use), or undefined (unconfigured).
+     */
+    modelAuth: string | undefined;
+    /** Channels discovered in the workspace — each contributes its required secrets + webhook step. */
+    channels: ChannelKind[];
+    /** Extra secret env-var names (fastagent.config deploy.secrets) — added to the runbook's secret list. */
+    extraSecrets?: string[];
+    /** `auto_stop_machines` — `"suspend"` (default, fast resume) or `"stop"` (cold start). CLI `--stop`. */
+    autostop: "suspend" | "stop";
+    /** Allow scaling to zero when idle (default true → `min_machines_running=0`). CLI `--no-scale-to-zero`
+     *  forces one machine up; a github channel forces it too (fire-and-forget turns have no replay). */
+    scaleToZero: boolean;
+    /** Time triggers present (schedules/ or selfSchedule) — forces one machine up: cron/wake has no
+     *  external wake-up, so a scaled-to-zero box would sleep through them. */
+    hasTimeTriggers: boolean;
+}
+export interface FlyPlan {
+    /** fly.toml / Dockerfile / .dockerignore — written by the CLI (skipped if present unless --force). */
+    artifacts: Artifact[];
+    /** The ordered, values-resolved deploy runbook — printed to stdout for the coding agent to execute. */
+    runbook: string[];
+}
+/** Compute the Fly deploy plan from the resolved definition. */
+export declare function planFlyDeploy(input: FlyPlanInput): FlyPlan;
+/**
+ * The `app` name from an existing fly.toml's `app = "…"` line, or undefined if absent — the KEEP-mode
+ * single source (a user who renamed the app is not overridden by the basename guess). Accepts TOML's
+ * double OR single quotes; anything else (or no `app`) is undefined → the caller falls back to basename.
+ */
+export declare function parseFlyAppName(toml: string): string | undefined;
+/** The `primary_region` from a fly.toml, or undefined — `--run` passes it to `fly volumes create` so the
+ *  volume lands in the machine's region (fly.toml is the single source; see {@link parseFlyAppName}). */
+export declare function parseFlyRegion(toml: string): string | undefined;
+/** The `min_machines_running` from a fly.toml, or undefined — the KEEP-mode check reads it so a kept
+ *  file that still scales to zero can be warned about when time triggers (schedules/wake) exist. */
+export declare function parseFlyMinMachines(toml: string): number | undefined;
+/** Sanitize a directory basename into a Fly app name: lowercase, [a-z0-9-], must start with a letter. */
+export declare function toFlyAppName(basename: string): string;

package/dist/deploy/fly/plan.js

@@ -0,0 +1,142 @@
+import { containerArtifacts } from "../container.js";
+import { isEnvKey, requiredSecrets } from "../secrets.js";
+function flyToml(appName, port, hasGithub, autostop, scaleToZero, hasTimeTriggers) {
+    // min_machines_running: 1 (keep one up) when a github channel is present, TIME triggers exist, OR the
+    // operator opted out of scale-to-zero. GitHub's is a SAFETY default — its fire-and-forget turns have no
+    // replay, so scaling to zero could drop an in-flight review. Time triggers (schedules/wake) have no
+    // external wake-up at all — a scaled-to-zero box sleeps through the cron instant. Reason-tagged so the
+    // comment is honest.
+    const min = hasGithub
+        ? `  min_machines_running = 1         # github turns have no replay — don't scale to zero (an in-flight review would be lost)`
+        : hasTimeTriggers
+            ? `  min_machines_running = 1         # schedules/wake-ups need a running machine (no external wake-up for a cron instant)`
+            : !scaleToZero
+                ? `  min_machines_running = 1         # kept running (--no-scale-to-zero)`
+                : `  min_machines_running = 0         # scale to zero`;
+    const stopLine = autostop === "stop"
+        ? `  auto_stop_machines = "stop"      # stop on idle (cold start on the next webhook)`
+        : `  auto_stop_machines = "suspend"   # suspend on idle (fast resume on the next webhook)`;
+    return `# Generated by \`fastagent deploy fly\`. Edit freely — it is not regenerated unless you pass --force.
+app = "${appName}"
+primary_region = "iad"  # set your region (list: \`fly platform regions\`)
+
+[build]
+
+[env]
+  FASTAGENT_STATE_DIR = "/data"  # the ONE machine-state root — auth, sessions, channel state
+  PORT = "${port}"
+
+[http_service]
+  internal_port = ${port}
+  force_https = true
+${stopLine}
+  auto_start_machines = true
+${min}
+
+[mounts]
+  source = "data"
+  destination = "/data"            # FASTAGENT_STATE_DIR — persists across stop/suspend/redeploy
+
+[[vm]]
+  size = "shared-cpu-1x"
+  memory = "512mb"                 # suspend is not recommended above 2 GB
+`;
+}
+/** Compute the Fly deploy plan from the resolved definition. */
+export function planFlyDeploy(input) {
+    const { appName, port, modelAuth, channels, kitDir } = input;
+    // Kit layout: every artifact is namespaced under the kit (agent/fly.toml, agent/Dockerfile) so the
+    // host repo's own deploy files are never touched; the runbook passes explicit -c/--dockerfile flags
+    // (unambiguous across flyctl versions — no reliance on config-relative path resolution).
+    const flyTomlPath = kitDir ? `${kitDir}/fly.toml` : "fly.toml";
+    const artifacts = [
+        {
+            path: flyTomlPath,
+            content: flyToml(appName, port, channels.includes("github"), input.autostop, input.scaleToZero, input.hasTimeTriggers),
+        },
+        ...containerArtifacts(input),
+    ];
+    // The exact secret list the deployed machine needs, computed from the definition (host-neutral): the
+    // model key (when local auth is an env key) + every discovered channel's secrets. Names + hints as
+    // COMMENT lines (a `#` inside a `\`-continued command would break the shell), then one flat, executable
+    // `fly secrets set` the coding agent fills — `<value>` placeholders, never inline comments.
+    const secrets = requiredSecrets(modelAuth, channels, input.extraSecrets);
+    const deployCmd = kitDir
+        ? `fly deploy . --config ${kitDir}/fly.toml --dockerfile ${kitDir}/Dockerfile --app ${appName}`
+        : `fly deploy --app ${appName}`;
+    const runbook = [
+        `# Deploy "${appName}" to Fly.io. ${flyTomlPath} / Dockerfile(.dockerignore) are generated above.`,
+        `# Prereqs: flyctl installed (https://fly.io/docs/flyctl/install) and \`fly auth login\`.`,
+        ``,
+        `# One-time setup (skip on a redeploy — a second run makes a SECOND app/volume, splitting state).`,
+        `# Fly app names are GLOBALLY unique: if this fails as taken, set a unique "app" in fly.toml and`,
+        `# re-run \`fastagent deploy fly\` — the runbook follows fly.toml's app name.`,
+        `fly apps create ${appName}`,
+        `# volume persists FASTAGENT_STATE_DIR=/data (sessions, auth, channel state) across stop/suspend/redeploy.`,
+        `# <region> MUST equal primary_region in fly.toml (a volume in another region can't mount) — fly.toml`,
+        `# is the single source for the region; skip this if the volume exists (fly volumes list --app ${appName}):`,
+        `fly volumes create data --app ${appName} --region <region> --size 1`,
+    ];
+    if (secrets.length > 0) {
+        runbook.push(``, `# Secrets (replace each <value>):`, ...secrets.map((s) => `#   ${s.name}: ${s.hint}`), `fly secrets set --app ${appName} ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
+    }
+    if (kitDir) {
+        runbook.push(``, `# Repo-as-workspace: the build context is the REPO ROOT (the whole repo is the agent's cwd); the`, `# config/Dockerfile live under ${kitDir}/ so they never collide with the repo's own deploy files.`, `# Run this from the repo root:`);
+    }
+    runbook.push(deployCmd);
+    if (kitDir) {
+        runbook.push(``, `# Write-back mechanics: git ships in the image and GH_TOKEN-style creds ride config.deploy.secrets;`, `# the POLICY (push vs PR, identity, remote) lives in persona.md. CAVEAT — whether .git survives is`, `# host-CLI-dependent (some context packers strip it from the upload): verify \`git status\` on the`, `# box after the first deploy; if it is missing, have the agent \`git clone\` its repo in the`, `# workspace instead (same token). Un-pushed changes never survive a redeploy — the image is a`, `# snapshot; durability lives in git.`);
+    }
+    // Model-auth guidance: an env key becomes a secret above. Otherwise the plan can't read the local
+    // credential's VALUE to set as a secret — true for OAuth AND a stored API key (both are
+    // `AuthResult.source` non-env labels), so the wording doesn't prejudge whether it's migratable.
+    if (!isEnvKey(modelAuth)) {
+        runbook.push(``, modelAuth === undefined
+            ? `# Model auth: none found at the local auth path — a global \`fastagent login\` isn't read here; pass --auth-path <file> (e.g. ~/.fastagent/auth.json), or \`--run\` carries it automatically.`
+            : `# Model auth: your local auth is "${modelAuth}" — the plan can't read its value to set as a secret.`, `#   Set your provider API key as a Fly secret (fly secrets set KEY=...), OR place auth.json on the /data volume.`);
+    }
+    // The fastagent-only post-step: point each channel's webhook at the live URL. Only fastagent knows the routes.
+    // The URLs below assume each channel's DEFAULT route key (POST /telegram, POST /webhook). Reading the
+    // real key would mean executing the channel factory (getMe, state-dir creation) — wrong at plan time
+    // — so the runbook states the assumption instead of silently printing a stale path for remapped glue.
+    const post = [];
+    if (channels.includes("telegram")) {
+        post.push(`# After deploy — register the Telegram webhook. The path assumes the default route (POST /telegram);`, `# if you remapped it in channels/telegram.ts, use your path. secret_token MUST equal TELEGRAM_SECRET_TOKEN:`, `curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \\`, `  -d url=https://${appName}.fly.dev/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`);
+    }
+    if (channels.includes("github")) {
+        post.push(`# After deploy — set the GitHub webhook (repo Settings → Webhooks). Path assumes the default route`, `# (POST /webhook); if you remapped it in channels/github.ts, use your path:`, `#   Payload URL = https://${appName}.fly.dev/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
+    }
+    if (post.length > 0)
+        runbook.push(``, ...post);
+    // Single-machine tier: state lives on ONE volume tied to ONE machine. Scaling to multiple machines
+    // splits state (each gets its own volume) — that needs a shared/external backend, not this recipe.
+    runbook.push(``, `# Keep this a SINGLE machine: the /data volume (and all state on it) is tied to one machine.`, `# Multiple machines would each get their own volume and split sessions/turns — don't scale past 1.`);
+    return { artifacts, runbook };
+}
+/**
+ * The `app` name from an existing fly.toml's `app = "…"` line, or undefined if absent — the KEEP-mode
+ * single source (a user who renamed the app is not overridden by the basename guess). Accepts TOML's
+ * double OR single quotes; anything else (or no `app`) is undefined → the caller falls back to basename.
+ */
+export function parseFlyAppName(toml) {
+    return toml.match(/^\s*app\s*=\s*["']([^"']+)["']/m)?.[1];
+}
+/** The `primary_region` from a fly.toml, or undefined — `--run` passes it to `fly volumes create` so the
+ *  volume lands in the machine's region (fly.toml is the single source; see {@link parseFlyAppName}). */
+export function parseFlyRegion(toml) {
+    return toml.match(/^\s*primary_region\s*=\s*["']([^"']+)["']/m)?.[1];
+}
+/** The `min_machines_running` from a fly.toml, or undefined — the KEEP-mode check reads it so a kept
+ *  file that still scales to zero can be warned about when time triggers (schedules/wake) exist. */
+export function parseFlyMinMachines(toml) {
+    const m = toml.match(/^\s*min_machines_running\s*=\s*(\d+)/m)?.[1];
+    return m === undefined ? undefined : Number(m);
+}
+/** Sanitize a directory basename into a Fly app name: lowercase, [a-z0-9-], must start with a letter. */
+export function toFlyAppName(basename) {
+    const slug = basename
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return /^[a-z]/.test(slug) ? slug : `app-${slug || "agent"}`;
+}

package/dist/deploy/fly/run.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `fastagent deploy fly --run` — drive flyctl to completion. The middle of the deploy (app / volume /
+ * secrets / deploy) that the plain runbook hands to the operator; `--run` executes it instead, so a
+ * coding agent runs ONE command. Idempotent (app/volume check-then-act; channel secrets come from the
+ * local env — NOT minted — so a re-run sets the same values) and resumable: it STOPS at a human gate
+ * (not logged in, a missing secret value, a taken app name) with one actionable line and a non-zero
+ * exit, so the agent clears the gate and re-runs. A `generate` channel secret absent from `.env` is a
+ * gate too (`missingSecrets`), not a silent mint — fill it in `.env` (use the random string that
+ * `add <channel>` prints).
+ *
+ * flyctl is behind the shared {@link CliRunner} seam — production spawns `fly`, tests inject a fake that
+ * records the command sequence and scripts outputs. That seam is the benchmark: the agent's journey
+ * encoded as an asserted command sequence + gate behavior, validated without a real Fly account.
+ *
+ * Non-interactive incantations the agent would otherwise get wrong: `--remote-only` (build on Fly's
+ * builders — no local Docker in a sandbox), `--yes` (no prompts), `--ha=false` + the mounted volume
+ * (one machine, the single-machine tier). Secrets go in via `secrets import` over stdin, so values
+ * never land in argv/process listings.
+ */
+import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import type { CliRunner } from "../runner.ts";
+/**
+ * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
+ * FASTAGENT_AUTH_SEED materialization. ABSENT-ONLY by design: a present file (a refreshed volume copy)
+ * is never overwritten by the stale seed, so a box that ran its own OAuth refresh is not rolled back.
+ */
+export declare function authSeedBytes(seed: string | undefined, fileExists: boolean): Buffer | undefined;
+export interface FlyRunPlan {
+    appName: string;
+    region: string;
+    /** `KEY=value` secrets to set on Fly: model key (env auth) or `FASTAGENT_AUTH_SEED` (file auth) +
+     *  channel secrets. Set via stdin, never argv. */
+    secrets: Record<string, string>;
+    /** Required secret names with NO local value — the run gates on these before any side effect. */
+    missingSecrets: string[];
+    channels: ChannelKind[];
+    /** fly.toml path passed to `fly deploy -c` (relative to the run cwd = the workspace dir). */
+    flyConfig: string;
+}
+/** Done, or a gate the operator must clear before re-running (printed + non-zero exit by the CLI). */
+export type FlyRunOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    gate: string;
+};
+/**
+ * Run the deploy through `fly`. `log` reports progress; `registerTelegram(baseUrl)` performs the
+ * post-deploy webhook step (the CLI passes its telegram registrar). Every gate is fail-visible.
+ */
+export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<void>): Promise<FlyRunOutcome>;