@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/deploy/build-context.js

@@ -1,11 +1,11 @@
 import { readdir } from "node:fs/promises";
-import { basename, isAbsolute, join, relative, sep } from "node:path";
+import { isAbsolute, relative, join, sep } from "node:path";
 import ignore from "ignore";
-import { exists, readTextIfExists, resolveSecretsDir, resolveStateRoot } from "../paths.js";
+import { AGENT_CONFIG_FILE, CONTENT_DIRNAME, LOCAL_CONTEXT_FILE, SECRETS_DIRNAME, exists, readTextIfExists, resolveSecretsDir, resolveStateRoot, } from "../paths.js";
 import { isGeneratedDockerignore } from "./container.js";
 /**
  * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore` matcher (the same
- * library the workspace ignore files use), so `!` negation and last-match-wins are the library's problem, not ours.
+ * library the scaffolded ignore files use), so `!` negation and last-match-wins are the library's problem, not ours.
  */
 function dockerignoreMatcher(text) {
     const anchored = text
@@ -38,22 +38,26 @@ async function entriesIfExists(path) {
         throw new Error(`cannot read ${path} to check what the image would ship: ${error.message}`);
     }
 }
-export async function buildContextPaths(workspace, agentDir, agentPrefix, authPath) {
+export async function buildContextPaths(agentDir, authPath) {
     const inContext = (p) => {
-        const rel = relative(workspace, p);
+        const rel = relative(agentDir, p);
         return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? undefined : rel.split(sep).join("/");
     };
     // The secrets DIR is the unit of RESPONSIBILITY, but never the unit of the leak QUESTION below.
     const secretsRel = inContext(resolveSecretsDir(agentDir));
     const authRel = inContext(authPath);
     const authElsewhere = authRel !== undefined && (secretsRel === undefined || !authRel.startsWith(`${secretsRel}/`));
-    const secretPaths = [...(secretsRel ? [secretsRel] : []), ...(authElsewhere ? [authRel] : [])];
+    const secretsDirs = [SECRETS_DIRNAME];
+    if (secretsRel && secretsRel !== SECRETS_DIRNAME && !secretsRel.startsWith(`${SECRETS_DIRNAME}/`)) {
+        secretsDirs.push(secretsRel);
+    }
+    const secretPaths = [...secretsDirs, ...(authElsewhere ? [authRel] : [])];
     // ONE rule for every checked path: a file that is not there cannot be baked, so gating on it would be a refusal
     // about a spelling rather than about what would ship (an agent that has never run `login` has no auth.json).
     const present = async (rels) => {
         const found = [];
         for (const rel of rels)
-            if (await exists(join(workspace, rel)))
+            if (await exists(join(agentDir, rel)))
                 found.push(rel);
         return found;
     };
@@ -61,20 +65,17 @@ export async function buildContextPaths(workspace, agentDir, agentPrefix, authPa
     // at warn level.
     const stateRel = inContext(resolveStateRoot(agentDir));
     // Existence gates the WARNING, never the generated exclude (same split as secretPaths vs leakCandidates).
-    const stateShips = stateRel !== undefined && (await exists(join(workspace, stateRel))) ? stateRel : undefined;
-    // The `.env` family at the two levels fastagent is RESPONSIBLE for: the agent dir and the workspace root.
-    const dotEnvFiles = async (relDir) => {
-        const names = (await entriesIfExists(join(workspace, relDir || "."))).map((entry) => entry.name);
-        // POSIX separators, like every other context-relative path here (`inContext`).
-        return names
-            .filter((n) => (n === ".env" || n.startsWith(".env.")) && n !== ".env.example")
-            .map((n) => join(relDir, n).split(sep).join("/"));
-    };
-    const envFiles = (await Promise.all([...new Set(["", agentPrefix])].map(dotEnvFiles))).flat();
+    const stateShips = stateRel !== undefined && (await exists(join(agentDir, stateRel))) ? stateRel : undefined;
+    const contentShips = (await exists(join(agentDir, CONTENT_DIRNAME))) ? CONTENT_DIRNAME : undefined;
+    const bindingsShip = (await exists(join(agentDir, LOCAL_CONTEXT_FILE))) ? LOCAL_CONTEXT_FILE : undefined;
+    // The `.env` family at the level fastagent is RESPONSIBLE for: the agent dir's root.
+    const envFiles = (await entriesIfExists(agentDir))
+        .map((entry) => entry.name)
+        .filter((n) => (n === ".env" || n.startsWith(".env.")) && n !== ".env.example");
     // Everything ACTUALLY inside the secrets dir, minus the two tracked scaffolds the image ships on purpose (they
     // carry no values; the generated ignore re-includes them by name).
     const secretDirFiles = async (dirRel) => {
-        const entries = await entriesIfExists(join(workspace, dirRel));
+        const entries = await entriesIfExists(join(agentDir, dirRel));
         const files = [];
         for (const entry of entries) {
             if (entry.name === ".gitignore" || entry.name === ".env.example")
@@ -87,21 +88,21 @@ export async function buildContextPaths(workspace, agentDir, agentPrefix, authPa
         return files;
     };
     const leakCandidates = [
-        ...(secretsRel ? await secretDirFiles(secretsRel) : []),
+        ...(await Promise.all(secretsDirs.map(secretDirFiles))).flat(),
         ...(await present(authElsewhere && authRel !== undefined ? [authRel] : [])),
         ...envFiles,
     ];
     // Same existence rule: a node_modules that is not there cannot be uploaded.
-    const depDirs = await present([...new Set([`${agentPrefix}node_modules`, "node_modules"])]);
+    const depDirs = await present(["node_modules"]);
     const machineryPaths = [...secretPaths, ...(stateRel ? [stateRel] : [])];
-    return { machineryPaths, leakCandidates, stateShips, depDirs };
+    return { machineryPaths, leakCandidates, stateShips, contentShips, bindingsShip, depDirs };
 }
 /** Interrogate BOTH ignore files deploy emits, when the author kept them. */
 export async function checkKeptIgnoreFiles(ctx, report) {
-    const { workspace, agentDir, agentPrefix, force } = ctx;
-    const { leakCandidates, stateShips, depDirs } = ctx.paths;
-    for (const rel of [".dockerignore", `${agentPrefix}Dockerfile.dockerignore`]) {
-        const kept = await readTextIfExists(join(workspace, rel));
+    const { agentDir, force } = ctx;
+    const { leakCandidates, stateShips, contentShips, bindingsShip, depDirs } = ctx.paths;
+    for (const rel of [".dockerignore", "Dockerfile.dockerignore"]) {
+        const kept = await readTextIfExists(join(agentDir, rel));
         if (kept === undefined)
             continue;
         // One WE generated is regenerated by this very run under --force, so checking the stale content on disk would
@@ -113,15 +114,13 @@ export async function checkKeptIgnoreFiles(ctx, report) {
             ? `Re-run with --force to regenerate it.`
             : `Add ${lines.map((p) => `\`${p}\``).join(" and ")} before deploying (the same lines the generated ${rel} writes).`;
         const excluded = dockerignoreMatcher(kept);
-        // Asked as a DIRECTORY (trailing slash), which is what it is.
-        if (excluded(`${basename(agentDir)}/`)) {
-            const text = `your ${rel} (kept) excludes \`${basename(agentDir)}\` — the build context would ship WITHOUT the ` +
-                `agent entirely (the deployed box has no prompt/config and crash-loops). Remove that rule ` +
-                `before deploying.`;
+        // The marker of an agent: without it the deployed box has no agent to open.
+        if (excluded(AGENT_CONFIG_FILE)) {
+            const text = `your ${rel} (kept) excludes \`${AGENT_CONFIG_FILE}\` — the image would ship WITHOUT the agent's ` +
+                `config (the deployed box has no agent to open and crash-loops). Remove that rule before deploying.`;
             report.issue(text);
         }
-        // Resolved paths, not spellings: dockerignore patterns are root-anchored (unlike .gitignore), so a bare
-        // `.secrets` line does not cover `fastagent/.secrets`.
+        // Resolved paths, not spellings: dockerignore patterns are root-anchored (unlike .gitignore).
         const leaks = leakCandidates.filter((p) => !excluded(p));
         if (leaks.length > 0) {
             const text = `your ${rel} (kept) does not exclude ${leaks.map((p) => `\`${p}\``).join(", ")} — the build ` +
@@ -131,7 +130,14 @@ export async function checkKeptIgnoreFiles(ctx, report) {
         if (stateShips && !excluded(`${stateShips}/sessions`)) {
             report.warn(`your ${rel} (kept) does not exclude \`${stateShips}\` — the build machine's sessions/channel state would ship in the image. ${remedy([`/${stateShips}`])}`);
         }
-        // Both the agent's own node_modules and the workspace's.
+        // An issue, not a warning: a release holding content/ is refused on the host, which links its own there.
+        if (contentShips && !excluded(`${contentShips}/x`)) {
+            report.issue(`your ${rel} (kept) does not exclude \`${contentShips}\` — this machine's clones of the agent's content would ship in the image. ${remedy([`/${contentShips}`])}`);
+        }
+        // A warning: the host reads it, and the paths it names (this machine's, the user's name in them) are not there.
+        if (bindingsShip && !excluded(bindingsShip)) {
+            report.warn(`your ${rel} (kept) does not exclude \`${bindingsShip}\` — the directories of this machine the agent is bound to would ship in the image, and the host would look for them at every start. ${remedy([`/${bindingsShip}`])}`);
+        }
         const unexcludedDeps = depDirs.filter((p) => !excluded(`${p}/.package-lock.json`));
         if (unexcludedDeps.length > 0) {
             report.warn(`your ${rel} does not exclude ${unexcludedDeps.map((p) => `\`${p}\``).join(" or ")} — the ` +
@@ -139,8 +145,8 @@ export async function checkKeptIgnoreFiles(ctx, report) {
                 `freshly-installed ones. ${remedy(unexcludedDeps.map((p) => `/${p}`))}`);
         }
         if (excluded(".git/HEAD")) {
-            report.note(`your ${rel} excludes .git — the baked copy ships WITHOUT history/remote, so the agent ` +
-                `cannot pull/commit/push it; it must \`git clone\` its repo in the workspace instead (or remove the .git line).`);
+            report.note(`your ${rel} excludes .git — the baked definition ships WITHOUT its history (remove the .git line ` +
+                `to ship it).`);
         }
     }
 }

package/dist/deploy/channel-ingress.d.ts

@@ -6,6 +6,11 @@ export interface Registrars {
     telegram: (baseUrl: string) => Promise<RegistrationOutcome>;
     slack?: (baseUrl: string) => Promise<RegistrationOutcome>;
     feishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>;
+    /**
+     * Where a channel's manual step goes beside the log, for a person who reads no log: a coding agent's user, through
+     * the deploy's ticket (its `afterwards`).
+     */
+    leave?: (step: string) => void;
 }
 /**
  * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool knows how to
@@ -38,7 +43,7 @@ export type PublicHealthProbe = (healthUrl: string) => Promise<boolean>;
  * failed" — a diagnosis that hides the actual cause.
  *
  * Asked ONLY when this deployment actually has a webhook to point, or a login on the box follows (the box must
- * have prepared its workspace and installed the CLI the login runs). A definition with neither (schedules only, the
+ * have prepared its storage and installed the CLI the login runs). A definition with neither (schedules only, the
  * built-in `POST /invoke`, or long-connection channels) needs no inbound reachability at all, and demanding it would
  * invent a failure for a deploy run from a network that cannot reach the platform's edge.
  */

package/dist/deploy/channel-ingress.js

@@ -2,6 +2,9 @@ import { registrationGate } from "./registration-gate.js";
 import { waitForHealth } from "../channels/wait-health.js";
 const feishuCloud = (kind, label) => ({
     path: `/${kind}`,
+    // The subscription mode is the published version's: a switch from long connection waits for the publish.
+    delivers: "delivers to this deployment once its published version is in webhook mode (after a first deploy, publish the " +
+        "version it opened)",
     register: (r, baseUrl) => r.feishu?.(baseUrl, kind),
     manual: (baseUrl) => `${kind}: set the event Request URL in the developer console (Events & Callbacks) → ${baseUrl}/${kind} (the app must be running when you save)`,
     runbook: (baseUrl) => [
@@ -14,6 +17,7 @@ const feishuCloud = (kind, label) => ({
 const INGRESS = {
     telegram: {
         path: "/telegram",
+        delivers: "now delivers to this deployment",
         register: (r, baseUrl) => r.telegram(baseUrl),
         manual: (baseUrl) => `telegram: set the webhook → ${baseUrl}/telegram (secret_token = TELEGRAM_SECRET_TOKEN)`,
         runbook: (baseUrl) => [
@@ -25,11 +29,12 @@ const INGRESS = {
     },
     slack: {
         path: "/slack",
+        delivers: "now delivers to this deployment",
         register: (r, baseUrl) => r.slack?.(baseUrl),
         manual: (baseUrl) => `slack: set Event Subscriptions → Request URL → ${baseUrl}/slack`,
         runbook: (baseUrl) => [
             `# Set Slack Event Subscriptions → Request URL (default route POST /slack; the running service`,
-            `# answers Slack's challenge), and match scopes/subscriptions to the app \`add slack --group-behavior\` created:`,
+            `# answers Slack's challenge), and match scopes/subscriptions to the app \`add slack\` created:`,
             `#   Request URL = ${baseUrl}/slack`,
         ],
     },
@@ -70,11 +75,15 @@ export async function pointChannelsAt(input) {
         input.log(`registering ${kind} webhook…`);
         outcomes.push({ kind, outcome: await running });
     }
+    // What the registrar said is in the log; the person who reads none gets the one route to set.
+    for (const { kind } of outcomes.filter(({ outcome }) => outcome === "manual")) {
+        input.registrars.leave?.(INGRESS[kind].manual(input.baseUrl));
+    }
     return outcomes;
 }
 /**
- * How long a just-deployed public URL gets to answer `/health`: the FIRST boot seeds the whole workspace onto the
- * volume before it binds a port, so this budget covers a copy on slow host storage, not a listen.
+ * How long a just-deployed public URL gets to answer `/health`: the boot publishes the definition onto the volume
+ * before it binds a port, so this budget covers a copy on slow host storage, not a listen.
  */
 const PUBLIC_HEALTH_TIMEOUT_MS = 180_000;
 /** How often the wait announces itself, so a crash-looping app is not three silent minutes. */
@@ -86,7 +95,7 @@ const WAIT_NOTICE_MS = 15_000;
  * failed" — a diagnosis that hides the actual cause.
  *
  * Asked ONLY when this deployment actually has a webhook to point, or a login on the box follows (the box must
- * have prepared its workspace and installed the CLI the login runs). A definition with neither (schedules only, the
+ * have prepared its storage and installed the CLI the login runs). A definition with neither (schedules only, the
  * built-in `POST /invoke`, or long-connection channels) needs no inbound reachability at all, and demanding it would
  * invent a failure for a deploy run from a network that cannot reach the platform's edge.
  */
@@ -151,7 +160,11 @@ function announce(log) {
 /** {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS. */
 export async function registerWebhooks(input) {
     const reg = registrationGate(input.log, input.retryHint);
-    for (const { kind, outcome } of await pointChannelsAt(input))
+    const outcomes = await pointChannelsAt(input);
+    for (const { kind, outcome } of outcomes)
         reg.track(kind, outcome);
+    for (const { kind } of outcomes.filter(({ outcome }) => outcome === "registered")) {
+        input.log(`the selected production ${kind} app ${INGRESS[kind].delivers}`);
+    }
     return reg.gate();
 }

package/dist/deploy/container.d.ts

@@ -1,7 +1,11 @@
+/** What every deploy writes whoever wrote it before: build output, by its file name, never kept or reported stale. */
+export declare const BUILD_OUTPUTS: readonly string[];
 export interface Artifact {
     path: string;
     content: string;
 }
+/** Where a generated image holds the definition: the build context, which is the agent directory. */
+export declare const IMAGE_DEFINITION_DIR = "/app/definition";
 /**
  * The shell command that runs `fastagent login --stdio <args>` inside a running generated image, as the server there
  * would see it: in the deployed agent directory, with the storage and credential paths resolved by the same defaults
@@ -15,7 +19,7 @@ export interface Artifact {
  * result line), so the command answers for it: one result line naming the mismatch, instead of a shell that ended
  * with nothing to say. No quote or backtick in it: hosts wrap this whole line in `sh -c '…'`.
  */
-export declare function boxLoginCommand(agent: string, args: readonly string[], storage?: string): string;
+export declare function boxLoginCommand(args: readonly string[], storage?: string): string;
 /** Fixed first-line prefix of a fastagent-generated Dockerfile. */
 export declare const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
 /** The ONE predicate for "did fastagent generate this Dockerfile?". */
@@ -34,8 +38,13 @@ export interface ContainerInput {
     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, …. */
+    /**
+     * The Debian packages the image installs: what FastAgent needs (git for content and a shipped `.git`, CA certificates
+     * and curl for mise), then the agent's `aptPackages`.
+     */
     apt?: string[];
+    /** The packages the agent declares, as mise is given them (`gh@2`): the image installs them with the agent's own mise. */
+    packages?: string[];
     /**
      * The model this deployment resolved, recorded in the release manifest — set only when the deployed environment's
      * VALUE FILE named it (a `config.model` needs nothing: the config ships too). The manifest is the carrier because
@@ -43,15 +52,19 @@ export interface ContainerInput {
      * interpolate the operator's shell.
      */
     modelSpec?: string;
-    /**
-     * Where deploy's artifacts and the agent's own files sit, relative to the BUILD CONTEXT (which is always the
-     * workspace).
-     */
-    agentPrefix: string;
-    /** Workspace-relative machinery paths the NAME-based excludes below would miss. */
+    /** The agent's name, recorded in the release manifest: the agent directory's own name. */
+    agent: string;
+    /** Agent-dir-relative machinery paths the NAME-based excludes below would miss. */
     machineryPaths?: string[];
-    /** Whether the baked workspace ships a `.git` (preflight fact). */
+    /** Whether the agent directory ships a `.git` (preflight fact). */
     shipsGit?: boolean;
 }
+/** Whether the image has git: FastAgent installs it for its own needs, or the agent declares it in `aptPackages`. */
+export declare function imageHasGit(input: Pick<ContainerInput, "apt">): boolean;
+/**
+ * The Node image an npm-based agent runs on: the newest of the floor's line. A floating tag, so every build pulls it
+ * (docker/run.ts, agentcore/run.ts): a copy cached before the floor's release would start a Node the CLI refuses.
+ */
+export declare const NODE_IMAGE: string;
 /** The Dockerfile + ignore artifacts — spread into any host's artifact list. */
 export declare function containerArtifacts(input: ContainerInput): Artifact[];

package/dist/deploy/container.js

@@ -1,16 +1,30 @@
 /** The portable container — Dockerfile + .dockerignore, host-neutral. */
-import { SECRETS_DIRNAME, STATE_DIRNAME } from "../paths.js";
-import { RELEASE_FILE, parseDeploymentRelease } from "./workspace.js";
-/** The result line for a box CLI that refused `login --stdio` as an unknown option (see {@link boxLoginCommand}). */
+import { CONTENT_DIRNAME, LOCAL_CONTEXT_FILE, SECRETS_DIRNAME, STATE_DIRNAME } from "../paths.js";
+import { RUNTIME_FLOOR } from "../runtime.js";
+import { DEPLOYED_DEFINITION_DIR, RELEASE_FILE, parseDeploymentRelease } from "./workspace.js";
+import { MISE_ENVIRONMENT } from "../environment/mise.js";
+import { BOX_CLI_PREDATES } from "./box-shell.js";
+/**
+ * The packages the image installs, one per line as mise is given them: build output every deploy writes beside the
+ * release manifest, so the layer that installs them is built again when they change and not when anything else does.
+ */
+const PACKAGES_FILE = "fastagent.packages";
+/** What every deploy writes whoever wrote it before: build output, by its file name, never kept or reported stale. */
+export const BUILD_OUTPUTS = [RELEASE_FILE, PACKAGES_FILE];
+/**
+ * The result line for a box CLI that refused this CLI's `login --stdio` as a usage error: an option it does not know
+ * (`--stdio` itself, or one added since, such as `--method`). See {@link boxLoginCommand}.
+ */
 const STDIO_PREDATED = JSON.stringify({
     type: "result",
     ok: false,
     reason: "failed",
-    message: "the fastagent installed in the agent on the box predates login --stdio: align the @fastagent-sh/fastagent " +
-        "version in the agent package.json with the CLI that deploys it, then redeploy",
+    message: BOX_CLI_PREDATES,
 }).replaceAll('"', '\\"');
 /** Where a generated image keeps its storage (`FASTAGENT_STORAGE_DIR`); every host mounts its volume here. */
 const STORAGE_DIR = "/data";
+/** Where a generated image holds the definition: the build context, which is the agent directory. */
+export const IMAGE_DEFINITION_DIR = "/app/definition";
 /**
  * The shell command that runs `fastagent login --stdio <args>` inside a running generated image, as the server there
  * would see it: in the deployed agent directory, with the storage and credential paths resolved by the same defaults
@@ -24,8 +38,8 @@ const STORAGE_DIR = "/data";
  * result line), so the command answers for it: one result line naming the mismatch, instead of a shell that ended
  * with nothing to say. No quote or backtick in it: hosts wrap this whole line in `sh -c '…'`.
  */
-export function boxLoginCommand(agent, args, storage) {
-    for (const value of [agent, ...args, ...(storage ? [storage] : [])]) {
+export function boxLoginCommand(args, storage) {
+    for (const value of [...args, ...(storage ? [storage] : [])]) {
         if (!/^[\w.@/-]+$/.test(value))
             throw new Error(`cannot pass ${JSON.stringify(value)} to a shell on the box`);
     }
@@ -36,7 +50,7 @@ export function boxLoginCommand(agent, args, storage) {
                 `root="\${FASTAGENT_STORAGE_DIR:-${STORAGE_DIR}}"`,
                 `export FASTAGENT_SECRETS_DIR="\${FASTAGENT_SECRETS_DIR:-$root/.secrets}"`,
             ]),
-        `cd "$root/base/${agent}" || exit 1`,
+        `cd "$root/${DEPLOYED_DEFINITION_DIR}" || exit 1`,
         `f=fastagent`,
         `if [ -x node_modules/.bin/fastagent ]; then f=node_modules/.bin/fastagent; if command -v bun >/dev/null; then f="bun run fastagent"; fi; fi`,
         `$f login --stdio ${args.join(" ")}`,
@@ -51,14 +65,15 @@ export const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
 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.
- */
+/** First line of a generated `.dockerignore`. */
 const GENERATED_DOCKERIGNORE_MARKER = "# Generated by `fastagent deploy`";
 export function isGeneratedDockerignore(content) {
     return content.startsWith(GENERATED_DOCKERIGNORE_MARKER);
 }
+/** Whether the image has git: FastAgent installs it for its own needs, or the agent declares it in `aptPackages`. */
+export function imageHasGit(input) {
+    return input.apt?.includes("git") === true;
+}
 /** The apt layer (cached right after FROM). */
 function aptLayer(packages) {
     return packages && packages.length > 0
@@ -68,47 +83,69 @@ function aptLayer(packages) {
 `
         : "";
 }
+/** mise's own directories for the build, thrown away with the layer: nothing of them is read at run time. */
+const BUILD_MISE_DIR = "/tmp/mise";
+/**
+ * The layer that installs the agent's packages, after its dependencies (the agent's own mise among them) and before the
+ * definition, so it stays cached while the definition changes. It reads them from {@link PACKAGES_FILE}, which deploy
+ * writes, rather than listing them: the Dockerfile is kept once written, and a list here would make every package
+ * change one that `--run` stops on. The packages go to mise's system directory (`--system`,
+ * /usr/local/share/mise/installs), which every mise reads beside its own data directory, so a start installs nothing.
+ */
+function environmentLayer(dir) {
+    const isolation = Object.entries(MISE_ENVIRONMENT)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(" ");
+    // The agent's own mise, by its package: the bin link is not reliable (mise.ts `miseBinary`).
+    const mise = `${dir}/node_modules/@jdxcode/mise-linux-$(case "$(uname -m)" in aarch64|arm64) echo arm64;; *) echo x64;; esac)/bin/mise`;
+    const steps = [
+        `export ${isolation} MISE_DATA_DIR=${BUILD_MISE_DIR} MISE_CACHE_DIR=${BUILD_MISE_DIR}/cache MISE_STATE_DIR=${BUILD_MISE_DIR}/state MISE="${mise}"`,
+        // One argument per line, read as it is: no quote or backslash in a package means anything to xargs.
+        `xargs -d '\\n' -a ${PACKAGES_FILE} "$MISE" install --system`,
+        `rm -rf ${BUILD_MISE_DIR}`,
+    ];
+    return `COPY ${PACKAGES_FILE} ./
+RUN ${steps.join(" \\\n && ")}
+`;
+}
+/**
+ * The Node image an npm-based agent runs on: the newest of the floor's line. A floating tag, so every build pulls it
+ * (docker/run.ts, agentcore/run.ts): a copy cached before the floor's release would start a Node the CLI refuses.
+ */
+export const NODE_IMAGE = `node:${RUNTIME_FLOOR.node.split(".")[0]}-slim`;
 function dockerfile(input) {
-    // 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) => `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.
+    // The build context is the agent directory, baked at IMAGE_DEFINITION_DIR; deps install (and the local bin lives)
+    // there.
+    const dir = IMAGE_DEFINITION_DIR;
+    const layoutNote = `The agent directory is baked at ${dir}`;
+    // apt layer right after FROM (cached across code changes): the agent's tools may shell out to git etc., which the
+    // slim image lacks.
     const apt = aptLayer(input.apt);
-    // 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=${STORAGE_DIR}\nENV npm_config_cache=/tmp/fastagent/npm\nENV BUN_INSTALL_CACHE_DIR=/tmp/fastagent/bun\n`;
+    const deployment = `ENV FASTAGENT_RELEASE_FILE=${dir}/${RELEASE_FILE}\nENV FASTAGENT_STORAGE_DIR=${STORAGE_DIR}\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
-${deployment}${pin}RUN npm i -g @fastagent-sh/fastagent@${input.version}
+# npm-based (a markdown/skills agent installs the pinned CLI globally; ${NODE_IMAGE} has npm).
+FROM ${NODE_IMAGE}
+${apt}WORKDIR ${dir}
+${deployment}RUN npm i -g @fastagent-sh/fastagent@${input.version}
 COPY . .
-CMD ["fastagent", "start", "/app"]
+CMD ["fastagent", "start", "${dir}"]
 `;
     }
+    const environment = input.packages && input.packages.length > 0 ? environmentLayer(dir) : "";
     const isBun = input.runtime === "bun";
-    const base = isBun ? `oven/bun:${input.bunVersion ?? "1"}` : "node:22-slim";
+    const base = isBun ? `oven/bun:${input.bunVersion ?? "1"}` : NODE_IMAGE;
     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}. ${layoutNote}
 ${note}
 FROM ${base}
-${apt}WORKDIR /app
-${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.
+${apt}WORKDIR ${dir}
+${deployment}`;
+    // Install ALL deps (no --omit=dev / --production): an agent's tools may need 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
@@ -117,42 +154,43 @@ ${deployment}${pin}`;
     if (isBun) {
         // `--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*")} ${into("*.tgz")} ./${prefix}
-RUN ${at(install)}
-COPY . .
-CMD ${bunCmd}
+        return `${head}COPY package.json bun.lock* *.tgz ./
+RUN ${install}
+${environment}COPY . .
+CMD ["bun", "run", "fastagent", "start", "${dir}"]
 `;
     }
     // `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*")} ${into("*.tgz")} ./${prefix}
-RUN ${at(install)}
-COPY . .
-CMD ["./${into("node_modules/.bin/fastagent")}", "start", "/app"]
+    return `${head}COPY package.json package-lock.json* *.tgz ./
+RUN ${install}
+${environment}COPY . .
+CMD ["./node_modules/.bin/fastagent", "start", "${dir}"]
 `;
 }
 /** 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.
-        .filter((p) => [`${input.agentPrefix}${SECRETS_DIRNAME}`, `${input.agentPrefix}${STATE_DIRNAME}`].every((covered) => p !== covered && !p.startsWith(`${covered}/`)))
+        // Skip what the name-based rules above already cover: the default `.secrets` / `.state` and anything inside them.
+        .filter((p) => [SECRETS_DIRNAME, 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("");
 const DOCKERIGNORE_BASE = `${GENERATED_DOCKERIGNORE_MARKER}. Delete this line to take ownership (deploy then keeps your file).
 **/node_modules
 **/${SECRETS_DIRNAME}/**
 **/${STATE_DIRNAME}
+/${CONTENT_DIRNAME}
+/${LOCAL_CONTEXT_FILE}
 **/.cache
 **/.env
 **/.env.*
 !**/.env.example
 !**/${SECRETS_DIRNAME}/.gitignore
 **/*.log
-# .git is deliberately shipped: the agent can pull to freshen content and push its work back
-# (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.
+# .git is deliberately shipped with the definition (the generated image installs the git binary
+# when this directory ships a .git; otherwise run "fastagent env add 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. */
 export function containerArtifacts(input) {
@@ -160,14 +198,17 @@ export function containerArtifacts(input) {
     const release = {
         version: 1,
         id: input.releaseId,
-        agent: input.agentPrefix.replace(/\/$/, ""),
+        agent: input.agent,
         ...(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: RELEASE_FILE, content: `${JSON.stringify(release, null, 2)}\n` },
+        // Written without packages too, empty: a list an earlier deploy left would otherwise outlive the last package.
+        { path: PACKAGES_FILE, content: (input.packages ?? []).map((spec) => `${spec}\n`).join("") },
+        { path: "Dockerfile", content: dockerfile(input) },
+        // Both names: BuildKit prefers the one beside the Dockerfile, the classic builder reads the context root's.
         { path: ".dockerignore", content: ignore },
-        { path: `${input.agentPrefix}Dockerfile.dockerignore`, content: ignore },
+        { path: "Dockerfile.dockerignore", content: ignore },
     ];
 }

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

@@ -21,18 +21,19 @@ export interface DockerPlanInput extends ContainerInput {
      * carries.
      */
     secrets?: readonly DeploymentSecret[];
-    /** The value file as the pre-flight resolved it (it follows `FASTAGENT_SECRETS_DIR`), workspace-relative. */
+    /** The value file as the pre-flight resolved it (it follows `FASTAGENT_SECRETS_DIR`), agent-dir-relative. */
     valueFile: string;
 }
 export interface DockerPlan {
     /** fastagent.compose.yml + the shared Dockerfile/ignore artifacts. */
     artifacts: Artifact[];
-    /** Compose file path relative to the workspace root (under the agent prefix). */
+    /** Compose file path relative to the agent directory. */
     composePath: string;
     /** Ordered local build/run/operate instructions. */
     runbook: string[];
 }
 export declare const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
+export declare const DOCKER_VALUE_FILE = ".secrets/production/.env";
 export declare const MIN_DOCKER_COMPOSE_VERSION = "2.3.3";
 /** Pinned: generated deployment artifacts must not silently move when Cloudflare publishes `latest`. */
 export declare const CLOUDFLARED_IMAGE = "cloudflare/cloudflared:2026.7.1";