@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/deploy/container.d.ts

@@ -1,17 +1,38 @@
-/** What every deploy writes whoever wrote it before: build output, by its file name, never kept or reported stale. */
+/**
+ * What a deploy builds the image from beyond the program, in the build context: the instance configuration it delivers
+ * and the text that configuration names, the release manifest and the package list. FastAgent's own directory, so it is
+ * ignored by git and absent from the author's root, and the image copies it to {@link IMAGE_CONFIG_DIR}. A directory of
+ * its own, never a file in the program's: what an instance configuration names beside it (its text) is
+ * read from its own directory, and the program's directory holds the program's.
+ */
+export declare const DELIVERED_CONFIG_DIR = ".fastagent/deploy";
+/**
+ * The configuration a deploy delivers, with the public URL the host gives the box as its `http.publicUrl`, where the
+ * operator's configuration names none (a custom domain is theirs to name): the URL the box points its channels at.
+ */
+export declare function withPublicUrl(config: string | undefined, publicUrl: string): {
+    config: string;
+    publicUrl: string;
+};
+/** The `http.publicUrl` an operator's configuration names, if it does. */
+export declare function ownPublicUrl(config: string | undefined): string | undefined;
+/** The delivered configuration as the artifact a deploy writes, to rewrite it once the host has given the URL. */
+export declare function deliveredConfigArtifact(config: string): Artifact;
+/** What every deploy writes whoever wrote it before: build output, by its path, 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";
+/** Where a generated image holds the agent: the build context, which is the agent directory. */
+export declare const IMAGE_APP_DIR = "/app";
 /**
  * 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
+ * would see it: in the image's agent directory, with the storage and credential paths resolved by the same defaults
  * `prepareStartWorkspace` applies. A host's own shell does not reliably hand those over — its session may not start
  * in the server's directory, and the platform's variables are the only ones it inherits. `storage` names the root
- * outright for a shell that inherits none of them. The CLI is the one the server runs: the agent's own install when
+ * outright for a shell that inherits none of them; `program` is where the image has the agent, the generated one's
+ * by default. The CLI is the one the server runs: the agent's own install when
  * it has one (under Bun when the image is Bun's), else the pinned global.
  *
  * That own install may predate `login --stdio` (an agent pinned to an older release, deployed by a newer CLI). It then
@@ -19,7 +40,10 @@ export declare const IMAGE_DEFINITION_DIR = "/app/definition";
  * 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(args: readonly string[], storage?: string): string;
+export declare function boxLoginCommand(args: readonly string[], { storage, program }?: {
+    storage?: string;
+    program?: 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?". */
@@ -28,16 +52,12 @@ export declare function isGeneratedDockerignore(content: string): boolean;
 export interface ContainerInput {
     /** Stable for one release; generated once by the deploy preflight, never on container restart. */
     releaseId: string;
-    /** Whether the agent has a package.json (a code agent); else a pure markdown/skills agent. */
-    hasPackageJson: boolean;
     /** The package manager the generated image targets. */
     runtime: "node" | "bun";
     /** Whether the runtime's lockfile exists (package-lock.json for npm, bun.lock/bun.lockb for bun). */
     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;
     /**
      * 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`.
@@ -52,6 +72,11 @@ export interface ContainerInput {
      * interpolate the operator's shell.
      */
     modelSpec?: string;
+    /**
+     * The instance configuration the deployment delivers (`deploy --config`), as the file's text: the image copies it to
+     * {@link IMAGE_CONFIG_DIR}, and `start` reads it through `FASTAGENT_CONFIG`. Without one, `{}`: the program's defaults.
+     */
+    config?: string;
     /** 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. */

package/dist/deploy/container.js

@@ -1,16 +1,48 @@
 /** The portable container — Dockerfile + .dockerignore, host-neutral. */
-import { CONTENT_DIRNAME, LOCAL_CONTEXT_FILE, SECRETS_DIRNAME, STATE_DIRNAME } from "../paths.js";
+import { CONTENT_DIRNAME, INSTANCE_CONFIG_FILE, INSTANCES_DIRNAME, SECRETS_DIRNAME, STATE_DIRNAME } from "../paths.js";
 import { RUNTIME_FLOOR } from "../runtime.js";
-import { DEPLOYED_DEFINITION_DIR, RELEASE_FILE, parseDeploymentRelease } from "./workspace.js";
+import { RELEASE_FILE, parseDeploymentRelease } from "./workspace.js";
 import { MISE_ENVIRONMENT } from "../environment/mise.js";
 import { BOX_CLI_PREDATES } from "./box-shell.js";
+/**
+ * What a deploy builds the image from beyond the program, in the build context: the instance configuration it delivers
+ * and the text that configuration names, the release manifest and the package list. FastAgent's own directory, so it is
+ * ignored by git and absent from the author's root, and the image copies it to {@link IMAGE_CONFIG_DIR}. A directory of
+ * its own, never a file in the program's: what an instance configuration names beside it (its text) is
+ * read from its own directory, and the program's directory holds the program's.
+ */
+export const DELIVERED_CONFIG_DIR = `${INSTANCES_DIRNAME}/deploy`;
+const DELIVERED_CONFIG_FILE = `${DELIVERED_CONFIG_DIR}/${INSTANCE_CONFIG_FILE}`;
+const RELEASE_PATH = `${DELIVERED_CONFIG_DIR}/${RELEASE_FILE}`;
 /**
  * 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];
+const PACKAGES_PATH = `${DELIVERED_CONFIG_DIR}/${PACKAGES_FILE}`;
+/** Where a generated image has the instance configuration, read-only: the filesystem hierarchy's for configuration. */
+const IMAGE_CONFIG_DIR = "/etc/fastagent";
+/**
+ * The configuration a deploy delivers, with the public URL the host gives the box as its `http.publicUrl`, where the
+ * operator's configuration names none (a custom domain is theirs to name): the URL the box points its channels at.
+ */
+export function withPublicUrl(config, publicUrl) {
+    const values = (config === undefined ? {} : JSON.parse(config));
+    const own = ownPublicUrl(config);
+    if (own !== undefined)
+        return { config: config, publicUrl: own };
+    return { config: `${JSON.stringify({ ...values, http: { ...values.http, publicUrl } }, null, 2)}\n`, publicUrl };
+}
+/** The `http.publicUrl` an operator's configuration names, if it does. */
+export function ownPublicUrl(config) {
+    return config === undefined ? undefined : JSON.parse(config).http?.publicUrl;
+}
+/** The delivered configuration as the artifact a deploy writes, to rewrite it once the host has given the URL. */
+export function deliveredConfigArtifact(config) {
+    return { path: DELIVERED_CONFIG_FILE, content: config };
+}
+/** What every deploy writes whoever wrote it before: build output, by its path, never kept or reported stale. */
+export const BUILD_OUTPUTS = [RELEASE_PATH, PACKAGES_PATH, DELIVERED_CONFIG_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}.
@@ -21,16 +53,17 @@ const STDIO_PREDATED = JSON.stringify({
     reason: "failed",
     message: BOX_CLI_PREDATES,
 }).replaceAll('"', '\\"');
-/** Where a generated image keeps its storage (`FASTAGENT_STORAGE_DIR`); every host mounts its volume here. */
+/** Where a generated image keeps its storage (`FASTAGENT_ROOT`); 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";
+/** Where a generated image holds the agent: the build context, which is the agent directory. */
+export const IMAGE_APP_DIR = "/app";
 /**
  * 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
+ * would see it: in the image's agent directory, with the storage and credential paths resolved by the same defaults
  * `prepareStartWorkspace` applies. A host's own shell does not reliably hand those over — its session may not start
  * in the server's directory, and the platform's variables are the only ones it inherits. `storage` names the root
- * outright for a shell that inherits none of them. The CLI is the one the server runs: the agent's own install when
+ * outright for a shell that inherits none of them; `program` is where the image has the agent, the generated one's
+ * by default. The CLI is the one the server runs: the agent's own install when
  * it has one (under Bun when the image is Bun's), else the pinned global.
  *
  * That own install may predate `login --stdio` (an agent pinned to an older release, deployed by a newer CLI). It then
@@ -38,8 +71,8 @@ export const IMAGE_DEFINITION_DIR = "/app/definition";
  * 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(args, storage) {
-    for (const value of [...args, ...(storage ? [storage] : [])]) {
+export function boxLoginCommand(args, { storage, program = IMAGE_APP_DIR } = {}) {
+    for (const value of [...args, ...(storage ? [storage] : []), program]) {
         if (!/^[\w.@/-]+$/.test(value))
             throw new Error(`cannot pass ${JSON.stringify(value)} to a shell on the box`);
     }
@@ -47,10 +80,10 @@ export function boxLoginCommand(args, storage) {
         ...(storage
             ? [`root="${storage}"`, `export FASTAGENT_SECRETS_DIR="$root/.secrets"`]
             : [
-                `root="\${FASTAGENT_STORAGE_DIR:-${STORAGE_DIR}}"`,
+                `root="\${FASTAGENT_ROOT:-${STORAGE_DIR}}"`,
                 `export FASTAGENT_SECRETS_DIR="\${FASTAGENT_SECRETS_DIR:-$root/.secrets}"`,
             ]),
-        `cd "$root/${DEPLOYED_DEFINITION_DIR}" || exit 1`,
+        `cd "${program}" || 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(" ")}`,
@@ -85,9 +118,11 @@ 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";
+/** Where the build holds the package list while it installs them: not the program's directory. */
+const BUILD_PACKAGES = "/tmp/fastagent.packages";
 /**
  * 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
+ * definition, so it stays cached while the definition changes. It reads them from {@link PACKAGES_PATH}, 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.
@@ -101,10 +136,10 @@ function environmentLayer(dir) {
     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`,
+        `xargs -d '\\n' -a ${BUILD_PACKAGES} "$MISE" install --system`,
         `rm -rf ${BUILD_MISE_DIR}`,
     ];
-    return `COPY ${PACKAGES_FILE} ./
+    return `COPY ${PACKAGES_PATH} ${BUILD_PACKAGES}
 RUN ${steps.join(" \\\n && ")}
 `;
 }
@@ -113,27 +148,26 @@ RUN ${steps.join(" \\\n && ")}
  * (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`;
+/** Why the image builds `dist/` itself: an upload that follows `.gitignore` (`railway up`) drops it, and `start` needs it. */
+const BUILD_STEP_NOTE = "# `start` opens dist/, which an upload that follows .gitignore leaves out: build it here.";
+/**
+ * The instance configuration's layer, after the build: the directory
+ * the deploy wrote, read-only where the image's configuration goes, and named to `start`.
+ */
+const CONFIG_LAYER = `# The instance configuration \`deploy --config\` delivers ({} without one: the program's defaults).
+COPY ${DELIVERED_CONFIG_DIR}/ ${IMAGE_CONFIG_DIR}/
+ENV FASTAGENT_CONFIG=${IMAGE_CONFIG_DIR}/${INSTANCE_CONFIG_FILE}
+`;
 function dockerfile(input) {
-    // The build context is the agent directory, baked at IMAGE_DEFINITION_DIR; deps install (and the local bin lives)
+    // The build context is the agent directory, baked at IMAGE_APP_DIR; deps install (and the local bin lives)
     // there.
-    const dir = IMAGE_DEFINITION_DIR;
+    const dir = IMAGE_APP_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);
     // The caches stay off the volume: they are rebuildable, and a host mount is the slow disk.
-    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_IMAGE} has npm).
-FROM ${NODE_IMAGE}
-${apt}WORKDIR ${dir}
-${deployment}RUN npm i -g @fastagent-sh/fastagent@${input.version}
-COPY . .
-CMD ["fastagent", "start", "${dir}"]
-`;
-    }
+    const deployment = `ENV FASTAGENT_RELEASE_FILE=${IMAGE_CONFIG_DIR}/${RELEASE_FILE}\nENV FASTAGENT_ROOT=${STORAGE_DIR}\nENV npm_config_cache=/tmp/fastagent/npm\nENV BUN_INSTALL_CACHE_DIR=/tmp/fastagent/bun\n`;
     const environment = input.packages && input.packages.length > 0 ? environmentLayer(dir) : "";
     const isBun = input.runtime === "bun";
     const base = isBun ? `oven/bun:${input.bunVersion ?? "1"}` : NODE_IMAGE;
@@ -149,15 +183,16 @@ ${deployment}`;
     //
     // `*.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.
+    // not there yet and the build fails on a dependency the author can see sitting in the agent directory.
     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 package.json bun.lock* *.tgz ./
 RUN ${install}
 ${environment}COPY . .
-CMD ["bun", "run", "fastagent", "start", "${dir}"]
+${BUILD_STEP_NOTE}
+RUN bun run fastagent build
+${CONFIG_LAYER}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
@@ -166,7 +201,9 @@ CMD ["bun", "run", "fastagent", "start", "${dir}"]
     return `${head}COPY package.json package-lock.json* *.tgz ./
 RUN ${install}
 ${environment}COPY . .
-CMD ["./node_modules/.bin/fastagent", "start", "${dir}"]
+${BUILD_STEP_NOTE}
+RUN ./node_modules/.bin/fastagent build
+${CONFIG_LAYER}CMD ["./node_modules/.bin/fastagent", "start", "${dir}"]
 `;
 }
 /** Patterns are RECURSIVE (`**​/`) on purpose. */
@@ -180,8 +217,12 @@ const DOCKERIGNORE_BASE = `${GENERATED_DOCKERIGNORE_MARKER}. Delete this line to
 **/node_modules
 **/${SECRETS_DIRNAME}/**
 **/${STATE_DIRNAME}
+/${INSTANCES_DIRNAME}
+# what a deploy writes for the image: the delivered configuration and text, the release manifest, the package list
+!/${DELIVERED_CONFIG_DIR}
 /${CONTENT_DIRNAME}
-/${LOCAL_CONTEXT_FILE}
+# the project's own instance configuration: the development instance's, which a deploy does not carry
+/${INSTANCE_CONFIG_FILE}
 **/.cache
 **/.env
 **/.env.*
@@ -203,12 +244,12 @@ export function containerArtifacts(input) {
     };
     parseDeploymentRelease(JSON.stringify(release));
     return [
-        { path: RELEASE_FILE, content: `${JSON.stringify(release, null, 2)}\n` },
+        { path: RELEASE_PATH, content: `${JSON.stringify(release, null, 2)}\n` },
+        // Written without a configuration too, as none: one an earlier deploy delivered would otherwise ship again.
+        { path: DELIVERED_CONFIG_FILE, content: input.config ?? "{}\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: PACKAGES_PATH, 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: "Dockerfile.dockerignore", content: ignore },
     ];
 }

package/dist/deploy/delivered-text.d.ts

@@ -0,0 +1,13 @@
+import type { InstanceConfigSource } from "../harnesses/pi-durable/config.ts";
+/**
+ * Why the text `source` names cannot be delivered or would not open on the host, or undefined when it can and would:
+ * the open's own refusals (a path of the wrong kind, a name taken twice), and a path that is not strictly inside the
+ * configuration's directory, written relative to it, which the image could not reproduce.
+ */
+export declare function deliveredTextProblem(agentDir: string, source: InstanceConfigSource): string | undefined;
+/**
+ * Replace `.fastagent/deploy/` in `agentDir` with the text `source` names, whole: what an earlier deploy delivered and
+ * this one does not is gone, as the release manifest and the configuration are rewritten. The configuration's own file
+ * is written after, with the other build outputs. Answers how many paths were copied.
+ */
+export declare function deliverText(agentDir: string, source: InstanceConfigSource | undefined): Promise<number>;

package/dist/deploy/delivered-text.js

@@ -0,0 +1,86 @@
+/**
+ * The instance text a deploy delivers (agent-artifact.md §6.1): the files and directories the delivered configuration
+ * names, copied beside it into `.fastagent/deploy/` with their layout, so the paths the configuration wrote, relative to
+ * its file, resolve the same in the image's `/etc/fastagent/`. Only what is beside the configuration is delivered: a
+ * path elsewhere on this machine does not exist on the host.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { isUnderDir } from "../paths.js";
+import { openText } from "../harnesses/pi-durable/text.js";
+import { declareText } from "../harnesses/pi-durable/text-sources.js";
+import { DELIVERED_CONFIG_DIR } from "./container.js";
+/** What the configuration names beyond the program's own text, each kind with its sources. */
+function declared(agentDir, source) {
+    const text = declareText(agentDir, source);
+    return ["instructions", "skills", "prompts"].flatMap((kind) => text[kind].filter((entry) => entry.declaredBy !== undefined).map((entry) => ({ kind, source: entry })));
+}
+/** The first symbolic link under `root` that points at nothing, which `cp` would fail on after the person's steps. */
+function danglingLink(root) {
+    if (!statSync(root).isDirectory())
+        return undefined;
+    for (const entry of readdirSync(root, { recursive: true, withFileTypes: true })) {
+        const path = join(entry.parentPath, entry.name);
+        if (entry.isSymbolicLink() && !existsSync(path))
+            return path;
+    }
+    return undefined;
+}
+/**
+ * Why the text `source` names cannot be delivered or would not open on the host, or undefined when it can and would:
+ * the open's own refusals (a path of the wrong kind, a name taken twice), and a path that is not strictly inside the
+ * configuration's directory, written relative to it, which the image could not reproduce.
+ */
+export function deliveredTextProblem(agentDir, source) {
+    try {
+        openText(agentDir, source);
+        for (const { kind, source: entry } of declared(agentDir, source)) {
+            const at = `${source.label}: ${kind} "${entry.given}"`;
+            const { directory } = source;
+            const given = entry.given ?? "";
+            if (directory === undefined || isAbsolute(given) || given === "~" || given.startsWith("~/")) {
+                return `${at} is not relative to the configuration: a deploy delivers what is beside it, so write a relative path`;
+            }
+            if (!isUnderDir(entry.path, directory) || entry.path === directory) {
+                return `${at} is outside the configuration's directory (${directory}): a deploy delivers only what is inside it`;
+            }
+            if (isUnderDir(agentDir, entry.path)) {
+                return `${at} contains the agent directory ${agentDir}: it cannot be delivered into it`;
+            }
+            const dangling = danglingLink(entry.path);
+            if (dangling !== undefined)
+                return `${at} holds a symbolic link to nothing: ${dangling}`;
+        }
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+/**
+ * Replace `.fastagent/deploy/` in `agentDir` with the text `source` names, whole: what an earlier deploy delivered and
+ * this one does not is gone, as the release manifest and the configuration are rewritten. The configuration's own file
+ * is written after, with the other build outputs. Answers how many paths were copied.
+ */
+export async function deliverText(agentDir, source) {
+    // Copying is an act, not a finding: whatever the pre-flight only warned about (a generate-only run) must not be
+    // carried out, or a path outside the configuration's directory would be written outside `.fastagent/deploy/`.
+    const problem = source === undefined ? undefined : deliveredTextProblem(agentDir, source);
+    if (problem !== undefined)
+        throw new Error(problem);
+    const target = join(agentDir, DELIVERED_CONFIG_DIR);
+    if (source?.directory !== undefined && isUnderDir(source.directory, target)) {
+        throw new Error(`${source.label} is inside ${target}, which every deploy replaces: keep the configuration elsewhere`);
+    }
+    await rm(target, { recursive: true, force: true });
+    if (source?.directory === undefined)
+        return 0;
+    const entries = declared(agentDir, source);
+    for (const { source: entry } of entries) {
+        const to = join(target, relative(source.directory, entry.path));
+        await mkdir(dirname(to), { recursive: true });
+        await cp(entry.path, to, { recursive: true, dereference: true });
+    }
+    return entries.length;
+}

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

@@ -14,11 +14,8 @@ export interface DockerPlanInput extends ContainerInput {
     boxLogin?: string;
     /** Every declared channel and its ingress — the source of the ingress note. */
     channels: readonly DeclaredChannel[];
-    /** Generate an optional Cloudflare Quick Tunnel service in Compose. */
-    tunnel: boolean;
     /**
-     * The runbook's variable list (`deploymentSecrets`): what must have a value, then everything else the value file
-     * carries.
+     * The runbook's variable list (`deploymentSecrets`): the declared names, each hinted by the file that declared it.
      */
     secrets?: readonly DeploymentSecret[];
     /** The value file as the pre-flight resolved it (it follows `FASTAGENT_SECRETS_DIR`), agent-dir-relative. */
@@ -35,13 +32,15 @@ export interface DockerPlan {
 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";
 /** Whether a Compose file still opts into generated-drift warnings (drop the marker after taking ownership). */
 export declare function isGeneratedCompose(content: string): boolean;
-/** Whether an authoritative Compose file already carries the generated tunnel service contract. */
-export declare function composeHasTunnelService(content: string): boolean;
 /** Compose project names are lowercase [a-z0-9_-] and must start with an alphanumeric character. */
 export declare function toDockerProjectName(directoryName: string): string;
+/**
+ * What `--run` says of the webhook channels once Compose is up. Docker has no URL of its own: with `http.publicUrl`
+ * named in the delivered configuration the agent points its own channels there (its `/health` says how each went) and
+ * only Slack's Request URL is the operator's; without one, nothing can reach those paths yet.
+ */
+export declare function ingressNotes(channels: readonly DeclaredChannel[], publicUrl: string | undefined, healthUrl: string | undefined): string[];
 /** Compute local-Docker artifacts + the runbook; no Docker process is touched here. */
 export declare function planDockerDeploy(input: DockerPlanInput): DockerPlan;

package/dist/deploy/docker/plan.js

@@ -1,67 +1,27 @@
 import { webhookPaths } from "../channel-ingress.js";
+import { manualWebhookStep, webhookKinds } from "../../channels/webhooks.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentLoginCommand } from "../box-shell.js";
 import { SECRETS_DIRNAME } from "../../paths.js";
+import { stripEdges, stripEnd } from "../../strip-edges.js";
 const MOUNT = "/data";
 export const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
 export const DOCKER_VALUE_FILE = `${SECRETS_DIRNAME}/production/.env`;
 const GENERATED_COMPOSE_MARKER = "# Generated by `fastagent deploy docker`";
 export const MIN_DOCKER_COMPOSE_VERSION = "2.3.3";
-/** Pinned: generated deployment artifacts must not silently move when Cloudflare publishes `latest`. */
-export const CLOUDFLARED_IMAGE = "cloudflare/cloudflared:2026.7.1";
 /** Whether a Compose file still opts into generated-drift warnings (drop the marker after taking ownership). */
 export function isGeneratedCompose(content) {
     return content.startsWith(GENERATED_COMPOSE_MARKER);
 }
-/** Whether an authoritative Compose file already carries the generated tunnel service contract. */
-export function composeHasTunnelService(content) {
-    return /^[ \t]+tunnel:\s*(?:#.*)?$/m.test(content);
-}
 /** Compose project names are lowercase [a-z0-9_-] and must start with an alphanumeric character. */
 export function toDockerProjectName(directoryName) {
-    const slug = directoryName
-        .toLowerCase()
-        .replace(/[^a-z0-9_-]+/g, "-")
-        .replace(/^[-_]+|[-_]+$/g, "")
-        .slice(0, 54)
-        .replace(/[-_]+$/g, "");
+    const separator = (char) => char === "-" || char === "_";
+    const slug = stripEnd(stripEdges(directoryName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-"), separator).slice(0, 54), separator);
     return `fastagent-${slug || "agent"}`;
 }
-/** `${NAME:-}` without making JavaScript treat it as interpolation. */
-function composeInterpolation(name) {
-    return `\${${name}:-}`;
-}
 function composeYaml(input) {
-    // Compose sits beside the Dockerfile, in the agent directory, which is the build context.
-    const tunnelService = input.tunnel
-        ? `
-  # Cloudflare Quick Tunnel: ephemeral URL, generated only with \`deploy docker --tunnel\`.
-  # No restart policy on purpose: a new process gets a new URL and needs webhook re-registration.
-  tunnel:
-    image: ${CLOUDFLARED_IMAGE}
-    command:
-      - tunnel
-      - --no-autoupdate
-      - --url
-      - http://agent:${input.port}
-    depends_on:
-      - agent
-    environment:
-      # Docker Desktop may inject HTTP(S)_PROXY into containers. The origin is Docker-internal and must
-      # 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"
-`
-        : "";
     return `${GENERATED_COMPOSE_MARKER}. Edit freely — it is kept unless you pass --force.
-# Durable/public ingress remains yours; --tunnel optionally adds an ephemeral Quick Tunnel service.
+# Public ingress remains yours: add your own tunnel/proxy/DNS/TLS, and name its URL as http.publicUrl.
 name: ${input.projectName}
 
 services:
@@ -98,11 +58,33 @@ services:
         max-size: "10m"
         max-file: "3"
     restart: unless-stopped
-${tunnelService}
+
 volumes:
   state:
 `;
 }
+/**
+ * What `--run` says of the webhook channels once Compose is up. Docker has no URL of its own: with `http.publicUrl`
+ * named in the delivered configuration the agent points its own channels there (its `/health` says how each went) and
+ * only Slack's Request URL is the operator's; without one, nothing can reach those paths yet.
+ */
+export function ingressNotes(channels, publicUrl, healthUrl) {
+    const paths = webhookPaths(channels);
+    if (paths.length === 0)
+        return [];
+    if (publicUrl === undefined) {
+        return [
+            `${paths.join(", ")} receive nothing until a public URL reaches this container — configure your own ` +
+                `tunnel/proxy, point those webhook path(s) (or your remapped channel routes) at it and name its URL as ` +
+                `http.publicUrl in the configuration --config delivers, or set the channel's ingress to "connection" ` +
+                `where it has one`,
+        ];
+    }
+    return [
+        `the agent points its webhook channels at ${publicUrl} on every start; ${healthUrl ?? "its /health"} says how each went`,
+        ...(webhookKinds(channels).includes("slack") ? [manualWebhookStep("slack", publicUrl)] : []),
+    ];
+}
 /** Compute local-Docker artifacts + the runbook; no Docker process is touched here. */
 export function planDockerDeploy(input) {
     const composePath = DOCKER_COMPOSE_FILE;
@@ -121,17 +103,14 @@ export function planDockerDeploy(input) {
         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}`));
     }
     runbook.push(`# Run from the agent directory. The build bakes it as the definition and installs its`, `# package.json dependencies.`);
-    runbook.push(``, `# Before building a new definition release, run \`fastagent deploy docker\` to refresh its manifest.`, `# The Compose volume at ${MOUNT} retains the deployed definition, state and credentials.`, `# --pull: the base image is a floating tag, and a copy cached here may be older than the runtime floor.`, `${compose} build --pull`, `${compose} up -d`, `curl --fail http://127.0.0.1:${input.port}/health`, ...(input.boxLogin
+    runbook.push(``, `# Before building a new definition release, run \`fastagent deploy docker\` to refresh its manifest.`, `# The Compose volume at ${MOUNT} is the agent's working directory, and retains its state and credentials.`, `# --pull: the base image is a floating tag, and a copy cached here may be older than the runtime floor.`, `${compose} build --pull`, `${compose} up -d`, `curl --fail http://127.0.0.1:${input.port}/health`, ...(input.boxLogin
         ? [
             `# Model auth: once it is up, the deployment logs in to ${input.boxLogin} itself:`,
             `${deploymentLoginCommand("docker", input.boxLogin)}`,
         ]
         : []), ``, `# Operate it:`, `${compose} logs -f agent`, `${compose} ps`, `${compose} down        # stops containers; keeps the state volume`, `# ${compose} down -v   # DESTRUCTIVE: deletes 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; 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.`);
+    if (paths.length > 0) {
+        runbook.push(``, `# Public ingress is operator-owned: add your tunnel/proxy/DNS/TLS, then route the detected default`, `# endpoint(s) to the agent: ${paths.map((path) => `https://<your-domain>${path}`).join(", ")}.`, `# If your channels/*.ts glue remaps a route, use that path instead. Name that URL as http.publicUrl in the`, `# configuration \`--config\` delivers, and the agent points Telegram and Feishu/Lark at it on every start`, `# (Slack's Request URL stays yours to set).`);
     }
     runbook.push(`# Keep one agent replica: the local state volume is single-process; multiple replicas split/corrupt state.`);
     return { artifacts, composePath, runbook };