@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/deploy/container.js

@@ -1,35 +1,21 @@
-/**
- * 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 machinery under `$FASTAGENT_STATE_DIR` /
- * `$FASTAGENT_SECRETS_DIR` — standard container conventions, no host coupling.
- *
- * ONE deploy semantic: bake the WORKSPACE as the image (`COPY . .` — what you see is what ships),
- * with the agent at `./fastagent` inside it. The resolver in the image finds it exactly like dev does.
- * Deps install under `/app/fastagent`, and the Dockerfile lives there too — namespaced so it never
- * collides with one the workspace already owns.
- */
+/** The portable container — Dockerfile + .dockerignore, host-neutral. */
 import { SECRETS_DIRNAME, STATE_DIRNAME } from "../paths.js";
-/** 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. */
+import { RELEASE_FILE, parseDeploymentRelease } from "./workspace.js";
+/** Fixed first-line prefix of a fastagent-generated Dockerfile. */
 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). */
+/** The ONE predicate for "did fastagent generate this Dockerfile?". */
 export function isGeneratedDockerfile(content) {
     return content.startsWith(GENERATED_DOCKERFILE_MARKER);
 }
-/** First line of a generated `.dockerignore` — and, for the workspace-root one, the single artifact
- *  deploy writes outside the agent dir. The marker is what splits the two cases: ours is refreshed
- *  (regenerated under `--force`), yours is kept. */
+/**
+ * First line of a generated `.dockerignore` — and, for the workspace-root one, the single artifact deploy writes
+ * outside the agent dir.
+ */
 const GENERATED_DOCKERIGNORE_MARKER = "# Generated by `fastagent deploy`";
-/** Did fastagent generate this `.dockerignore`? (Same ownership rule as {@link isGeneratedDockerfile}.) */
 export function isGeneratedDockerignore(content) {
     return content.startsWith(GENERATED_DOCKERIGNORE_MARKER);
 }
-/** The apt layer (cached right after FROM). Debian default repos only. */
+/** The apt layer (cached right after FROM). */
 function aptLayer(packages) {
     return packages && packages.length > 0
         ? `RUN apt-get update \\
@@ -39,46 +25,30 @@ function aptLayer(packages) {
         : "";
 }
 function dockerfile(input) {
-    // The whole workspace is baked at /app; deps install (and the local bin lives) under the agent, which
-    // is either a subdirectory of it or /app itself. `into` prefixes a path, `at` runs a command there.
+    // The whole workspace is baked at /app; deps install (and the local bin lives) under the agent, which is always a
+    // SUBDIRECTORY of it (the workspace is the agent dir's parent), so the prefix is never empty.
     const prefix = input.agentPrefix;
+    const dir = prefix.replace(/\/$/, "");
     const into = (p) => `${prefix}${p}`;
     // A build step that must run IN the agent dir (`RUN` already gets a shell from docker).
-    const at = (cmd) => (prefix ? `cd ${prefix.replace(/\/$/, "")} && ${cmd}` : cmd);
-    // The entrypoint. Only the BUN path needs a working directory (`bun run` resolves the script from the
-    // package.json beside it), and a `cd` there means a shell — with `exec`, or sh stays PID 1 and swallows
-    // the container's SIGTERM. The npm path needs no shell at all: the binary path is context-relative and
-    // `start /app` is absolute, so exec form is both correct and signal-clean. (A `cd` on that path was a
-    // bug: after `cd fastagent`, `./fastagent/node_modules/...` resolves one level too deep.)
-    const bunCmd = prefix
-        ? `["sh", "-c", "cd ${prefix.replace(/\/$/, "")} && exec bun run fastagent start /app"]`
-        : `["bun", "run", "fastagent", "start", "/app"]`;
-    const layoutNote = prefix
-        ? `The whole directory is the agent's workspace; the agent itself lives in ${prefix}`
-        : `The directory IS the agent — it is also its own workspace.`;
-    // 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 at = (cmd) => `cd ${dir} && ${cmd}`;
+    // The entrypoint.
+    const bunCmd = `["sh", "-c", "cd ${dir} && exec bun run fastagent start /app"]`;
+    const layoutNote = `The whole directory is the agent's workspace; the agent itself lives in ${prefix}`;
+    // apt layer right after FROM (cached across code changes): the agent's tools may shell out to git etc., which
+    // node:22-slim lacks.
     const apt = aptLayer(input.apt);
-    // PIN the agent into the image. The container re-resolves placement at `/app` (the baked workspace),
-    // and a workspace may hold SEVERAL agents — all of which ship, since the build context is the whole
-    // tree. Without this the image would pick by the container's own rules (the `fastagent`-named one, or
-    // nothing) instead of the agent this deploy was FOR: the artifact would depend on the builder's
-    // environment, which is the one thing it must never do. Baked whenever the agent sits inside the
-    // workspace, single agent or not — the value is a fact of this image, and asserting it means a build
-    // context that dropped the agent fails loudly rather than serving a sibling.
-    const pin = prefix ? `ENV FASTAGENT_AGENT=${prefix.replace(/\/$/, "")}\n` : "";
-    // 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 agent, so the bun-vs-node base below is scoped to that path.
+    // PIN the agent into the image.
+    const pin = `ENV FASTAGENT_AGENT=${dir}\n`;
+    // The caches stay off the volume: they are rebuildable, and a host mount is the slow disk.
+    const deployment = `ENV FASTAGENT_RELEASE_FILE=/app/${into(RELEASE_FILE)}\nENV FASTAGENT_STORAGE_DIR=/data\nENV npm_config_cache=/tmp/fastagent/npm\nENV BUN_INSTALL_CACHE_DIR=/tmp/fastagent/bun\n`;
+    // No package.json → pure markdown/skills agent: install the pinned CLI GLOBALLY and run `fastagent` from PATH.
     if (!input.hasPackageJson) {
         return `${GENERATED_DOCKERFILE_MARKER}. ${layoutNote}
 # npm-based (a markdown/skills agent installs the pinned CLI globally; node:22-slim has npm).
 FROM node:22-slim
 ${apt}WORKDIR /app
-${pin}RUN npm i -g @fastagent-sh/fastagent@${input.version}
+${deployment}${pin}RUN npm i -g @fastagent-sh/fastagent@${input.version}
 COPY . .
 CMD ["fastagent", "start", "/app"]
 `;
@@ -92,56 +62,37 @@ CMD ["fastagent", "start", "/app"]
 ${note}
 FROM ${base}
 ${apt}WORKDIR /app
-${pin}`;
-    // 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 agent, so the safe default keeps everything.
-    // Only the AGENT's deps are installed — the workspace's own deps are the agent's runtime concern
-    // (it can install them in its workspace when its job needs them).
+${deployment}${pin}`;
+    // Install ALL deps (no --omit=dev / --production): a repo-as-agent (e.g. an Astro site it operates on) needs its
+    // full toolchain.
+    //
+    // `*.tgz` RIDES ALONG with the manifest, because the install layer runs BEFORE `COPY . .` and a
+    // `"dep": "file:./something.tgz"` resolves against the directory it is installing in. Without this the file is
+    // not there yet and the build fails on a dependency the author can see sitting in the agent directory. It is
+    // also what lets a live probe deploy the CHECKOUT (`npm pack` output) rather than the published release.
     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).
+        // `--frozen-lockfile` needs bun.lock and hard-fails without it.
         const install = input.hasLockfile ? "bun install --frozen-lockfile" : "bun install";
-        return `${head}COPY ${into("package.json")} ${into("bun.lock*")} ./${prefix}
+        return `${head}COPY ${into("package.json")} ${into("bun.lock*")} ${into("*.tgz")} ./${prefix}
 RUN ${at(install)}
 COPY . .
 CMD ${bunCmd}
 `;
     }
-    // `npm ci` requires a lockfile and hard-fails without one (a common `init --no-install` agent);
-    // 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.
+    // `npm ci` requires a lockfile and hard-fails without one (a common `init --no-install` agent); fall back to `npm
+    // install` when there is none so the build never breaks.
     const install = input.hasLockfile ? "npm ci" : "npm install";
-    return `${head}COPY ${into("package.json")} ${into("package-lock.json*")} ./${prefix}
+    return `${head}COPY ${into("package.json")} ${into("package-lock.json*")} ${into("*.tgz")} ./${prefix}
 RUN ${at(install)}
 COPY . .
 CMD ["./${into("node_modules/.bin/fastagent")}", "start", "/app"]
 `;
 }
-/** Patterns are RECURSIVE (`**​/`) on purpose — dockerignore patterns are root-anchored (unlike
- *  .gitignore), and a baked workspace can hold nested projects: a bare `node_modules` would upload
- *  their build-machine deps (macOS binaries!) and a bare `.env` would bake their secrets into the
- *  image. `.secrets`/`.state` are fastagent machinery — credential contents travel through the host's
- *  secret store and state lives on the volume, so neither may enter an image. The two tracked secrets
- *  scaffolds (`.env.example` + `.gitignore`) are the narrow exception: they carry no values and must stay
- *  beside the shipped `.git`, or the image starts with tracked deletions. `.cache` is generic hygiene
- *  (a baked project's own build cache), not a fastagent directory.
- *  `.git` is deliberately SHIPPED: the deployed agent's write-back (pull/commit/push) needs the
- *  repo's history+remote — the WYSIWYG bake's freshness/durability loop runs through git, driven by
- *  the agent itself, not by deploy machinery. Shipping `.git` is only half of that loop: preflight
- *  bakes the git BINARY into the generated image iff the workspace ships a `.git` (the `shipsGit`
- *  fact); a non-git workspace that still needs git declares config.deploy.apt. */
+/** Patterns are RECURSIVE (`**​/`) on purpose. */
 const dockerignore = (input) => DOCKERIGNORE_BASE +
     (input.machineryPaths ?? [])
-        // Skip what the name-based rules above already cover: the default `<agent>/.secrets` / `<agent>/.state`
-        // and anything inside them. What remains is a relocated dir whose NAME those rules cannot match.
+        // Skip what the name-based rules above already cover: the default `<agent>/.secrets` / `<agent>/.state` and
+        // anything inside them.
         .filter((p) => [`${input.agentPrefix}${SECRETS_DIRNAME}`, `${input.agentPrefix}${STATE_DIRNAME}`].every((covered) => p !== covered && !p.startsWith(`${covered}/`)))
         .map((p) => `# resolved machinery path (FASTAGENT_SECRETS_DIR / FASTAGENT_AUTH_PATH / FASTAGENT_STATE_DIR)\n/${p}\n`)
         .join("");
@@ -159,20 +110,18 @@ const DOCKERIGNORE_BASE = `${GENERATED_DOCKERIGNORE_MARKER}. Delete this line to
 # (the generated image installs the git binary when this directory ships a .git; otherwise
 # add deploy.apt ["git"]). For a smaller image with no git needs, add a ".git" line here.
 `;
-/**
- * The Dockerfile + ignore artifacts — spread into any host's artifact list. Everything is prefixed with
- * {@link ContainerInput.agentPrefix}, so a NESTED agent's Dockerfile lands under `fastagent/` (never
- * colliding with one the workspace already owns) while an agent that IS the workspace lands it at the root, where it IS
- * the agent's own file. 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 workspace already has one — preflight then checks the machinery/secret
- * excludes it must carry) — and (2) a per-Dockerfile `Dockerfile.dockerignore` for plain docker/buildx
- * builds. When the agent sits inside the workspace that root file is the ONE write deploy makes outside the agent dir, and
- * only at deploy time — without it the host CLI's packer would bake `.secrets/` into the image.
- */
+/** The Dockerfile + ignore artifacts — spread into any host's artifact list. */
 export function containerArtifacts(input) {
     const ignore = dockerignore(input);
+    const release = {
+        version: 1,
+        id: input.releaseId,
+        agent: input.agentPrefix.replace(/\/$/, ""),
+        ...(input.modelSpec !== undefined ? { model: input.modelSpec } : {}),
+    };
+    parseDeploymentRelease(JSON.stringify(release));
     return [
+        { path: `${input.agentPrefix}${RELEASE_FILE}`, content: `${JSON.stringify(release, null, 2)}\n` },
         { path: `${input.agentPrefix}Dockerfile`, content: dockerfile(input) },
         { path: ".dockerignore", content: ignore },
         { path: `${input.agentPrefix}Dockerfile.dockerignore`, content: ignore },

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

@@ -1,24 +1,25 @@
-/**
- * `fastagent deploy docker` — the local-Docker plan. The application image stays ingress-neutral:
- * this target generates only the shared Dockerfile plus a small Compose service for the FastAgent
- * process, its loopback port, exact environment-variable names, and one persistent state volume.
- * `--tunnel` can add an ephemeral Cloudflare Quick Tunnel service; durable ingress remains operator-owned.
- */
+/** `fastagent deploy docker` — the local-Docker plan. */
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
+import { type DeploymentSecret } from "../secrets.ts";
 export interface DockerPlanInput extends ContainerInput {
     /** Stable Compose project name, sanitized by {@link toDockerProjectName}. */
     projectName: string;
-    /** Container + default host port. The host binding is loopback-only by default. */
+    /** Container + default host port. */
     port: number;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** Every declared channel and its ingress — the source of the secret list and the ingress note. */
+    /** Every declared channel and its ingress — the source of the ingress note. */
     channels: readonly DeclaredChannel[];
-    /** Generate an optional Cloudflare Quick Tunnel service in Compose. Generation only; `--run` starts it. */
+    /** Generate an optional Cloudflare Quick Tunnel service in Compose. */
     tunnel: boolean;
-    /** Extra environment-variable names declared in config.deploy.secrets. */
-    extraSecrets?: string[];
+    /**
+     * The runbook's variable list (`deploymentSecrets`): what must have a value, then everything else the value file
+     * carries.
+     */
+    secrets?: readonly DeploymentSecret[];
+    /** The value file as the pre-flight resolved it (it follows `FASTAGENT_SECRETS_DIR`), workspace-relative. */
+    valueFile: string;
 }
 export interface DockerPlan {
     /** fastagent.compose.yml + the shared Dockerfile/ignore artifacts. */

package/dist/deploy/docker/plan.js

@@ -1,6 +1,7 @@
 import { webhookPaths } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
-import { deploymentSecrets, isEnvKey } from "../secrets.js";
+import { isEnvKey } from "../secrets.js";
+import { SECRETS_DIRNAME } from "../../paths.js";
 const MOUNT = "/data";
 const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
 const GENERATED_COMPOSE_MARKER = "# Generated by `fastagent deploy docker`";
@@ -30,14 +31,9 @@ function composeInterpolation(name) {
     return `\${${name}:-}`;
 }
 function composeYaml(input) {
-    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
-    // Always leave the auth-seed seam in the committed topology. `--run` uses it for OAuth/stored auth;
-    // it is empty otherwise. Values never land in this file — Compose interpolates them at invocation.
-    const envNames = [...new Set([...secrets.map((secret) => secret.name), "FASTAGENT_AUTH_SEED"])];
-    const secretEnv = envNames.map((name) => `      ${name}: "${composeInterpolation(name)}"`).join("\n");
-    // Compose sits beside the Dockerfile, under the agent prefix; the build context is always the
-    // WORKSPACE, so it climbs back out of the prefix (`..` per level, `.` when there is none).
-    const context = input.agentPrefix ? ".." : ".";
+    // Compose sits beside the Dockerfile, under the agent prefix; the build context is always the WORKSPACE, so it
+    // climbs back out of the one-level prefix deploy requires.
+    const context = "..";
     const dockerfile = `${input.agentPrefix}Dockerfile`;
     const tunnelService = input.tunnel
         ? `
@@ -57,6 +53,12 @@ function composeYaml(input) {
       # bypass it; preserve any operator NO_PROXY entries after the required service/loopback names.
       NO_PROXY: "agent,localhost,127.0.0.1,${composeInterpolation("NO_PROXY")}"
       no_proxy: "agent,localhost,127.0.0.1,${composeInterpolation("no_proxy")}"
+    # Quieter than the agent, but bounded for the same reason: nothing else on this host bounds it.
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
     restart: "no"
 `
         : "";
@@ -71,14 +73,36 @@ services:
       dockerfile: ${dockerfile}
     ports:
       - "127.0.0.1:${input.port}:${input.port}"
+    # The deployed environment's own declaration, read by the container itself. \`env_file\`, not per-name
+    # \${NAME:-} interpolation: interpolation resolves from the SHELL or the project .env, which is exactly the
+    # source a deployment must not have. A FIXED path, never the builder's FASTAGENT_SECRETS_DIR — this file is a
+    # committed artifact and must mean the same thing on every machine. \`deploy\` creates it if it is missing.
+    env_file:
+      - ${SECRETS_DIRNAME}/.env
     environment:
       PORT: "${input.port}"
-      # Machinery on the ONE state volume: mutable state and (seeded, possibly rotated) secrets.
+      # Machinery on the ONE state volume: mutable state and (seeded, possibly rotated) secrets. Pinned AFTER
+      # env_file so a local path in that file (the scaffold lists these) cannot send the container's state, sessions
+      # or credentials somewhere outside the volume — or at a host path that does not exist here at all.
       FASTAGENT_STATE_DIR: "${MOUNT}/.state"
       FASTAGENT_SECRETS_DIR: "${MOUNT}/.secrets"
-${secretEnv}
+      FASTAGENT_AUTH_PATH: "${MOUNT}/.secrets/auth.json"
+      # The ONE value that is not in the value file: \`--run\` mints it from the local auth.json. Left as a seam in
+      # the committed topology so a hand-run \`up\` can supply it the same way — from the ENVIRONMENT of that \`up\`.
+      # Writing this one key into the value file does nothing: \`environment:\` is applied after \`env_file\`, so the
+      # line below would blank it and the container would start without seeding auth.json.
+      FASTAGENT_AUTH_SEED: "${composeInterpolation("FASTAGENT_AUTH_SEED")}"
     volumes:
       - state:${MOUNT}
+    # The agent's log is where a failure's reason is recorded (a scheduled fire logs the detail; what the turn
+    # SAID is in its session, not here), and Docker's default json-file driver never rotates — so on this host
+    # the bound has to be written down. Fly and Railway bound their own log retention; AgentCore does NOT
+    # (CloudWatch keeps data indefinitely until an operator sets a retention policy — its runbook says so).
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
     restart: unless-stopped
 ${tunnelService}
 volumes:
@@ -89,33 +113,28 @@ volumes:
 export function planDockerDeploy(input) {
     const composePath = `${input.agentPrefix}${DOCKER_COMPOSE_FILE}`;
     const artifacts = [{ path: composePath, content: composeYaml(input) }, ...containerArtifacts(input)];
+    // One spelling for every command: the generated file names the value file itself (`env_file`), so no command
+    // needs a flag to reach the deployed environment's declaration.
     const compose = `docker compose -f ${composePath}`;
-    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
-    const required = secrets.filter((secret) => secret.required);
-    const optional = secrets.filter((secret) => !secret.required);
+    const secrets = input.secrets ?? [];
     const paths = webhookPaths(input.channels);
     const runbook = [
         `# Run FastAgent in local Docker. ${composePath} / Dockerfile(.dockerignore) are generated above.`,
         `# Existing artifacts are authoritative and kept; edit Dockerfile or ${composePath} freely.`,
         `# Prereqs: Docker Engine/Desktop with Compose >= ${MIN_DOCKER_COMPOSE_VERSION} (\`docker compose version\`).`,
     ];
-    if (required.length > 0) {
-        runbook.push(`# Required environment values (put them in the agent's .secrets/.env or export them):`, ...required.map((secret) => `#   ${secret.name}: ${secret.hint}`));
-    }
-    if (optional.length > 0) {
-        runbook.push(`# Optional environment values:`, ...optional.map((secret) => `#   ${secret.name}: ${secret.hint}`));
+    if (secrets.length > 0) {
+        runbook.push(`# Environment: the container reads ${input.valueFile} whole (Compose \`env_file\`) — that file declares the`, `# deployed environment (in CI, write it before running the command):`, ...secrets.map((secret) => `#   ${secret.name}: ${secret.hint}`));
     }
     if (!isEnvKey(input.modelAuth)) {
         runbook.push(input.modelAuth === undefined
             ? `# Model auth: none found locally — run \`fastagent login\` or set a provider API key before --run.`
             : `# Model auth: local source is "${input.modelAuth}" — \`--run\` carries auth.json as FASTAGENT_AUTH_SEED.`, `# For a manual Compose run, provide a provider API key or set FASTAGENT_AUTH_SEED yourself.`);
     }
-    runbook.push(input.agentPrefix
-        ? `# Run from the WORKSPACE ROOT (the directory containing ${input.agentPrefix}).`
-        : `# Run from this directory — it is both the agent and its workspace.`, `# The build bakes the whole directory as the agent's workspace; only the agent's own`, `# dependencies (${input.agentPrefix}package.json) are installed.`);
-    runbook.push(``, `# Build/create/reconcile the service. Re-running this is the complete local redeploy; state stays`, `# in the Compose volume mounted at ${MOUNT}.`, `${compose} up -d --build`, `curl --fail http://127.0.0.1:${input.port}/health`, ``, `# Operate it:`, `${compose} logs -f agent`, `${compose} ps`, `${compose} down        # stops containers; keeps the state volume`, `# ${compose} down -v   # DESTRUCTIVE: also deletes auth, sessions, and channel state`);
+    runbook.push(`# Run from the WORKSPACE ROOT (the directory containing ${input.agentPrefix}).`, `# The build bakes the whole directory as the agent's workspace; only the agent's own`, `# dependencies (${input.agentPrefix}package.json) are installed.`);
+    runbook.push(``, `# Before building a new definition release, run \`fastagent deploy docker\` to refresh its manifest.`, `# The Compose volume at ${MOUNT} retains the workspace, state and credentials.`, `${compose} up -d --build`, `curl --fail http://127.0.0.1:${input.port}/health`, ``, `# Operate it:`, `${compose} logs -f agent`, `${compose} ps`, `${compose} down        # stops containers; keeps the state volume`, `# ${compose} down -v   # DESTRUCTIVE: deletes workspace, credentials and all agent state`);
     if (input.tunnel) {
-        runbook.push(``, `# Quick Tunnel: \`--run\` starts the Compose tunnel service and reads its ephemeral public URL.`, `# Telegram/Feishu/Lark and locally onboarded Slack auto-register; GitHub/manual Slack print console URLs. Re-run after the`, `# tunnel container/Docker daemon restarts: a new Quick Tunnel URL must replace the old webhook URL.`, `${compose} logs -f tunnel`);
+        runbook.push(``, `# Quick Tunnel: \`--run\` starts the Compose tunnel service and reads its ephemeral public URL.`, `# Telegram/Feishu/Lark and locally onboarded Slack auto-register; manual Slack prints its console URL. Re-run after the`, `# tunnel container/Docker daemon restarts: a new Quick Tunnel URL must replace the old webhook URL.`, `${compose} logs -f tunnel`);
     }
     else if (paths.length > 0) {
         runbook.push(``, `# Public ingress is operator-owned: add your tunnel/proxy/DNS/TLS, then configure the`, `# detected default endpoint(s): ${paths.map((path) => `https://<your-domain>${path}`).join(", ")}.`, `# If your channels/*.ts glue remaps a route, use that path instead.`);

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

@@ -5,15 +5,19 @@ export interface DockerRunPlan {
     composeFile: string;
     /** Container port from config; used to ask Compose for the effective published host port. */
     port: number;
-    /** Values interpolated by Compose. Keys/values are passed in the child environment, never argv. */
+    /**
+     * What `--run` assembled. The container reads the value file itself through the generated `env_file`, so the only
+     * entry that has to travel through this process is `FASTAGENT_AUTH_SEED`, which is minted here; the rest is
+     * reported to the operator and otherwise unused.
+     */
     secrets: Record<string, string>;
-    /** Required names with no local value; gate before build/create. */
+    /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
     missingSecrets: string[];
+    /** That value file, workspace-relative, so the gate names the file this deploy actually read. */
+    valueFile: string;
     /** Neither an env-key credential nor a readable auth.json is available. */
     needsModelCredential: boolean;
-    /** Register the deployment's webhooks against the tunnel URL, reporting what each registrar
-     *  answered. REQUIRED, not optional: an absent one would delete this whole step in silence, which
-     *  is the failure this driver's gate exists to end. A topology with no tunnel never calls it. */
+    /** Register the deployment's webhooks against the tunnel URL, reporting what each registrar answered. */
     announce: DockerAnnounce;
     /** `--tunnel` was requested for this run; a kept Compose file must actually contain that service. */
     requireTunnel: boolean;
@@ -23,24 +27,27 @@ export type DockerRunOutcome = {
     url?: string;
     tunnelUrl?: string;
 }
-/** `url`/`tunnelUrl` travel with a gate too: Compose is up, so the operator still needs to know
- *  where it is and what to re-run. */
+/**
+ * `url`/`tunnelUrl` travel with a gate too: Compose is up, so the operator still needs to know where it is and what
+ * to re-run.
+ */
  | {
     ok: false;
     gate: string;
     url?: string;
     tunnelUrl?: string;
 };
-/** Register the deployment's webhooks against its public URL, reporting what each registrar
- *  answered. Injected so the driver stays free of channel specifics — and so a test can fail one. */
+/** Register the deployment's webhooks against its public URL, reporting what each registrar answered. */
 type DockerAnnounce = (baseUrl: string) => Promise<{
     kind: string;
     outcome: RegistrationOutcome;
 }[]>;
-export type DockerHealthProbe = (healthUrl: string) => Promise<boolean>;
-/** A published Quick Tunnel URL, and whether its tunnel ever reported an edge connection. Both, because
- *  a URL that never connected still gets served (retrying meets the same network) and the operator has
- *  to be told which of the two they are looking at. */
+/**
+ * `stillStarting` answers whether the agent container is still up; a probe that ignores it simply waits out its whole
+ * budget.
+ */
+export type DockerHealthProbe = (healthUrl: string, stillStarting: () => Promise<boolean>) => Promise<boolean>;
+/** A published Quick Tunnel URL, and whether its tunnel ever reported an edge connection. */
 export interface ComposeTunnel {
     url: string;
     connected: boolean;
@@ -49,23 +56,13 @@ export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string, env:
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
 export declare function localUrlFromComposePort(stdout: string): string | undefined;
 /**
- * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel
- * reports an edge connection. Waiting for the second is the same requirement `startCloudflareTunnel`
- * has and for the same reason — the hostname does not exist until then (#435), and this driver hands
- * the URL straight to `announce`. Returns a URL that never connected rather than nothing: the
- * registrars downstream report their own outcome, and a gate saying "no URL" would misname it — but it
- * says WHICH it is returning, because the caller owes the operator that sentence.
+ * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel reports an edge
+ * connection.
  */
 export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv, options?: {
     attempts?: number;
     intervalMs?: number;
     sleep?: (ms: number) => Promise<void>;
 }): Promise<ComposeTunnel | undefined>;
-/**
- * Drive Docker Compose. A custom Compose file remains authoritative: the driver invokes it as-is and
- * only assumes the generated service contract (`agent`, config's container port) for optional URL/
- * readiness reporting. If the service intentionally has no host-published port, a successful running
- * service is still success (an operator-owned sidecar/reverse proxy may be its only ingress).
- */
 export declare function deployDockerRun(plan: DockerRunPlan, docker: CliRunner, log: (message: string) => void, healthProbe?: DockerHealthProbe, tunnelUrlProbe?: DockerTunnelUrlProbe): Promise<DockerRunOutcome>;
 export {};

package/dist/deploy/docker/run.js

@@ -1,12 +1,9 @@
-/**
- * `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally.
- * Compose owns container/network/volume lifecycle; this driver owns only actionable gates, secret/auth
- * carry through the child environment (never argv), and a readiness check on the published loopback port.
- */
+/** `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally. */
 import { waitForHealth } from "../../channels/wait-health.js";
 import { TUNNEL_DNS_LAG_MS, hasTunnelConnection, parseTunnelUrl } from "../../tunnel.js";
 import { registrationGate } from "../registration-gate.js";
 import { MIN_DOCKER_COMPOSE_VERSION } from "./plan.js";
+import { missingValuesGate } from "../secrets.js";
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
 export function localUrlFromComposePort(stdout) {
     const line = stdout
@@ -16,15 +13,15 @@ export function localUrlFromComposePort(stdout) {
     const port = line?.match(/:(\d+)$/)?.[1];
     return port ? `http://127.0.0.1:${port}` : undefined;
 }
-const defaultHealthProbe = (healthUrl) => waitForHealth(healthUrl, 30_000, 500);
+/**
+ * The FIRST boot seeds the whole workspace onto the volume (the image's `node_modules` included) before it binds a
+ * port, so this budget covers a copy on a slow Docker Desktop disk, not a listen.
+ */
+const defaultHealthProbe = (healthUrl, stillStarting) => waitForHealth(healthUrl, 180_000, 500, stillStarting);
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
- * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel
- * reports an edge connection. Waiting for the second is the same requirement `startCloudflareTunnel`
- * has and for the same reason — the hostname does not exist until then (#435), and this driver hands
- * the URL straight to `announce`. Returns a URL that never connected rather than nothing: the
- * registrars downstream report their own outcome, and a gate saying "no URL" would misname it — but it
- * says WHICH it is returning, because the caller owes the operator that sentence.
+ * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel reports an edge
+ * connection.
  */
 export async function waitForComposeTunnelUrl(docker, composeFile, env, options = {}) {
     const compose = ["compose", "-f", composeFile];
@@ -45,16 +42,13 @@ export async function waitForComposeTunnelUrl(docker, composeFile, env, options
     return assigned ? { url: assigned, connected: false } : undefined;
 }
 const defaultTunnelUrlProbe = (docker, composeFile, env) => waitForComposeTunnelUrl(docker, composeFile, env);
-/**
- * Drive Docker Compose. A custom Compose file remains authoritative: the driver invokes it as-is and
- * only assumes the generated service contract (`agent`, config's container port) for optional URL/
- * readiness reporting. If the service intentionally has no host-published port, a successful running
- * service is still success (an operator-owned sidecar/reverse proxy may be its only ingress).
- */
 export async function deployDockerRun(plan, docker, log, healthProbe = defaultHealthProbe, tunnelUrlProbe = defaultTunnelUrlProbe) {
     const gate = (message) => ({ ok: false, gate: message });
     const compose = ["compose", "-f", plan.composeFile];
-    const env = plan.secrets;
+    // The ONE value that is not in the value file, so the ONE that has to cross this process. Set even when absent, so
+    // a same-named variable in the builder's shell cannot interpolate into the container in its place — `spawnRunner`
+    // merges over `process.env`.
+    const env = { FASTAGENT_AUTH_SEED: plan.secrets.FASTAGENT_AUTH_SEED ?? "" };
     // CLI/plugin gate first: unlike a daemon error, spawn ENOENT becomes 127 at the shared runner seam.
     const version = await docker(["compose", "version"], { capture: true });
     if (version.code === 127) {
@@ -67,14 +61,20 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if (plan.needsModelCredential) {
         return gate("no model credential — run `fastagent login`, or set a provider API key in .env, then re-run");
     }
-    if (plan.missingSecrets.length > 0) {
-        return gate(`no local value for: ${plan.missingSecrets.join(", ")} — set them in .env (or the environment) and re-run`);
+    const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
+    if (missingValues)
+        return gate(missingValues);
+    // Name what the container must find, and WHERE — the generated Compose reads the value file itself, so this run
+    // hands Compose nothing but the seed. Saying "passing N secrets to Compose" would be false, and doubly so on a
+    // hand-owned Compose file that has no `env_file` entry at all.
+    const secretNames = Object.keys(plan.secrets).filter((name) => name !== "FASTAGENT_AUTH_SEED");
+    if (secretNames.length > 0) {
+        log(`${secretNames.length} value(s) the container reads from ${plan.valueFile}: ${secretNames.join(", ")}`);
     }
     if ((await docker(["info"], { capture: true })).code !== 0) {
         return gate("Docker daemon is unavailable — start Docker Engine/Desktop, then re-run");
     }
-    // The file on disk is authoritative. Inspect its actual services before any build/create side effect,
-    // both to protect the `agent` run contract and to catch `--tunnel` against a kept non-tunnel topology.
+    // The file on disk is authoritative.
     const configured = await docker([...compose, "config", "--services"], { capture: true, env });
     if (configured.code !== 0) {
         return gate(`could not load ${plan.composeFile} — generated files require Docker Compose >= ` +
@@ -89,9 +89,7 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
         return gate(`--tunnel was requested but the kept ${plan.composeFile} has no "tunnel" service — ` +
             `edit it, delete it and regenerate, or pass --force`);
     }
-    // Quick Tunnel logs are the control-plane output (the assigned URL). Remove its old container first so
-    // a rerun cannot read a stale URL from accumulated logs; `up` below creates one fresh tunnel, then the
-    // CLI registers that URL. The app container/volume are untouched.
+    // Quick Tunnel logs are the control-plane output (the assigned URL).
     if (hasTunnel) {
         log("recreating the ephemeral tunnel service…");
         if ((await docker([...compose, "rm", "-s", "-f", "tunnel"], { env })).code !== 0) {
@@ -102,8 +100,7 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if ((await docker([...compose, "up", "-d", "--build"], { env })).code !== 0) {
         return gate(`\`docker compose up\` failed — see the Docker output above; fix ${plan.composeFile} and re-run`);
     }
-    // Detached `up` can return 0 just before a bad command exits. Verify the expected service is actually
-    // running so a broken custom Dockerfile/CMD cannot look deployed. Compose restart loops are excluded.
+    // Detached `up` can return 0 just before a bad command exits.
     const running = await docker([...compose, "ps", "--status", "running", "--services"], {
         capture: true,
         env,
@@ -116,7 +113,6 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
         return gate(`the Compose service "tunnel" is not running — inspect with \`docker compose -f ${plan.composeFile} logs tunnel\``);
     }
     // A user-owned topology may deliberately remove the host port and expose only through its own ingress.
-    // In that case Compose `port` is absent/non-zero: service-running is the available readiness floor.
     const published = await docker([...compose, "port", "agent", String(plan.port)], { capture: true, env });
     const url = published.code === 0 ? localUrlFromComposePort(published.stdout) : undefined;
     if (!url) {
@@ -124,7 +120,17 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     }
     else {
         const healthUrl = `${url}/health`;
-        if (!(await healthProbe(healthUrl))) {
+        // Throttled, and an unreadable answer reads as "still starting": the health poll runs twice a second, and a
+        // `compose ps` per poll would cost more than the wait it shortens.
+        let lastCheck = Date.now();
+        const stillStarting = async () => {
+            if (Date.now() - lastCheck < 5_000)
+                return true;
+            lastCheck = Date.now();
+            const ps = await docker([...compose, "ps", "--status", "running", "--services"], { capture: true, env });
+            return ps.code !== 0 || ps.stdout.split(/\s+/).includes("agent");
+        };
+        if (!(await healthProbe(healthUrl, stillStarting))) {
             return gate(`agent did not become healthy at ${healthUrl} — inspect \`docker compose -f ${plan.composeFile} logs agent\``);
         }
     }
@@ -135,19 +141,15 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if (!tunnel) {
         return gate(`tunnel did not publish a Quick Tunnel URL — inspect \`docker compose -f ${plan.composeFile} logs tunnel\``);
     }
-    // The same sentence `startCloudflareTunnel` prints for the same state, and needed MORE here: this
-    // cloudflared runs in a container, so the author cannot see the logs that would explain the
-    // registration failures about to follow. Silence sends them to debug the platform for what is a
-    // local tunnel that never came up.
+    // The same sentence `startCloudflareTunnel` prints for the same state, and needed MORE here.
     if (!tunnel.connected) {
         log(`warn: the tunnel service never reported an edge connection for ${tunnel.url} — announcing it anyway. ` +
             `Nothing reaches a tunnel that has not connected, so a webhook registration that cannot resolve the ` +
             `host is this, not the platform. Inspect \`docker compose -f ${plan.composeFile} logs tunnel\`.`);
     }
     const tunnelUrl = tunnel.url;
-    // Registration lives HERE, like every other host's driver, and not at the CLI: this is the layer
-    // that owns the outcome, so it is the layer that can gate on one. While it sat above, docker was
-    // the one target whose `--run` could exit 0 with a webhook that never registered.
+    // Registration lives HERE, like every other host's driver, and not at the CLI: this is the layer that owns the
+    // outcome, so it is the layer that can gate on one.
     const reg = registrationGate(log, `re-run this deploy to retry registration (Compose is already up)`);
     for (const { kind, outcome } of await plan.announce(tunnelUrl))
         reg.track(kind, outcome);