@fastagent-sh/fastagent 0.29.0 → 0.30.1

package/dist/deploy/channel-ingress.js

@@ -1,12 +1,11 @@
+import { manualWebhookStep, webhookKinds, webhookPath, } from "../channels/webhooks.js";
 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) => [
         `# Set the ${label} event Request URL (developer console → Events & Callbacks). Default route`,
         `# POST /${kind}; the app must be RUNNING when you save (the console verifies with a challenge):`,
@@ -16,10 +15,8 @@ const feishuCloud = (kind, label) => ({
 /** Declaration order — the order every runbook and every driver reports in. */
 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) => [
             `# Register the Telegram webhook. The path assumes the default route (POST /telegram); if you`,
             `# remapped it in channels/telegram.ts, use your path. secret_token MUST equal TELEGRAM_SECRET_TOKEN:`,
@@ -28,30 +25,21 @@ 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`,
+        // The Request URL is the app's page, which a person sets (channel-setup.md §3): no credential here changes it.
+        register: () => undefined,
         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\` created:`,
+            `# answers Slack's challenge), and match scopes/subscriptions to the app \`channels setup slack\` created:`,
             `#   Request URL = ${baseUrl}/slack`,
         ],
     },
     feishu: feishuCloud("feishu", "Feishu"),
     lark: feishuCloud("lark", "Lark"),
 };
-/**
- * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool knows how to
- * instruct.
- */
-export function webhookKinds(channels) {
-    const declared = new Set(channels.filter((c) => c.ingress === "webhook").map((c) => c.name));
-    return Object.keys(INGRESS).filter((kind) => declared.has(kind));
-}
 /** Default route keys for {@link webhookKinds}, in the same order (the docker plan's ingress note). */
 export function webhookPaths(channels) {
-    return webhookKinds(channels).map((kind) => INGRESS[kind].path);
+    return webhookKinds(channels).map(webhookPath);
 }
 /**
  * The runbook block for every channel that needs a URL set by hand, `baseUrl` spelled the host's way (a literal
@@ -68,7 +56,7 @@ export async function pointChannelsAt(input) {
         // Calling IS the question: a channel whose registrar the caller did not wire returns undefined.
         const running = ingress.register(input.registrars, input.baseUrl);
         if (!running) {
-            input.log(ingress.manual(input.baseUrl));
+            input.log(manualWebhookStep(kind, input.baseUrl));
             outcomes.push({ kind, outcome: "manual" }); // a human's step — re-surfaced after registrar output
             continue;
         }
@@ -77,7 +65,7 @@ export async function pointChannelsAt(input) {
     }
     // 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));
+        input.registrars.leave?.(manualWebhookStep(kind, input.baseUrl));
     }
     return outcomes;
 }
@@ -134,9 +122,10 @@ export function loginGate(input) {
     const byHand = input.baseUrl === undefined ? [] : webhookRunbook(input.baseUrl, input.channels);
     for (const line of byHand)
         input.log(line);
-    // "No webhook was registered" would be about THIS run only: one an earlier deploy registered still points here.
-    return (`${input.notLoggedIn}. This deploy registered no webhook, and logging in registers none; any an earlier deploy ` +
-        `registered still points here, and every message it brings fails until the box is logged in. Once it is, ` +
+    // "Confirmed none" is about THIS run only: a channel the box or an earlier deploy pointed here still delivers.
+    return (`${input.notLoggedIn}. This deploy confirmed no webhook, and logging in confirms none; any already pointed here, ` +
+        `by the box itself or by an earlier deploy, still delivers, and every message it brings fails until the box is ` +
+        `logged in. Once it is, ` +
         `${input.afterLogin}` +
         (byHand.length > 0 ? `. The lines above point the channels by hand.` : ``));
 }
@@ -168,3 +157,111 @@ export async function registerWebhooks(input) {
     }
     return reg.gate();
 }
+/** How long a deploy waits for a box to end its own registration: the box's registrars retry for about 190 s. */
+const BOX_REGISTRATION_TIMEOUT_MS = 240_000;
+const readBoxWebhooks = async (healthUrl) => {
+    try {
+        const res = await fetch(healthUrl, { signal: AbortSignal.timeout(5000) });
+        const body = (await res.json());
+        return Array.isArray(body.webhooks)
+            ? body.webhooks
+            : undefined;
+    }
+    catch {
+        return undefined; // not routable, or not answering JSON yet: polled again until the deadline
+    }
+};
+/**
+ * What a box that points its own channels made of them (channel-setup.md §5): read from its `/health` until no channel
+ * is `pending`, then gated as {@link registerWebhooks} gates. Slack's Request URL no credential on the box can set, so
+ * `registrars.slack` sets it from this machine, as before.
+ */
+export async function confirmWebhooks(input) {
+    const kinds = webhookKinds(input.channels);
+    const reg = registrationGate(input.log, input.retryHint);
+    const outcomes = new Map();
+    if (kinds.includes("slack")) {
+        input.log(manualWebhookStep("slack", input.publicUrl));
+        outcomes.set("slack", "manual");
+    }
+    const own = kinds.filter((kind) => kind !== "slack");
+    if (own.length > 0) {
+        input.log(`waiting for the box to point ${own.join(", ")} at ${input.publicUrl}…`);
+        const probe = input.probe ?? readBoxWebhooks;
+        const deadline = Date.now() + (input.timeoutMs ?? BOX_REGISTRATION_TIMEOUT_MS);
+        for (;;) {
+            const read = await probe(`${input.baseUrl}/health`);
+            const ended = own.map((kind) => read?.find((entry) => entry.channel === kind));
+            if (ended.every((entry) => entry !== undefined && entry.outcome !== "pending")) {
+                for (const [i, kind] of own.entries())
+                    outcomes.set(kind, ended[i]?.outcome);
+                break;
+            }
+            if (Date.now() >= deadline) {
+                for (const [i, kind] of own.entries()) {
+                    if (ended[i] === undefined || ended[i]?.outcome === "pending") {
+                        input.log(`${kind}: the box did not report its registration within the wait — see its log`);
+                        outcomes.set(kind, "failed");
+                    }
+                    else {
+                        outcomes.set(kind, ended[i]?.outcome);
+                    }
+                }
+                break;
+            }
+            await new Promise((resolve) => setTimeout(resolve, input.intervalMs ?? 2_000));
+        }
+    }
+    for (const kind of kinds) {
+        if (outcomes.get(kind) === "registered" || kind === "slack")
+            continue;
+        // What the box said and why is in its log; the line a person acts on is said here.
+        input.log(manualWebhookStep(kind, input.publicUrl));
+        input.registrars.leave?.(manualWebhookStep(kind, input.publicUrl));
+    }
+    if (input.record !== undefined)
+        await recordConfirmed(input, kinds, outcomes, input.record);
+    for (const kind of kinds) {
+        const outcome = outcomes.get(kind);
+        reg.track(kind, outcome);
+        if (outcome === "registered")
+            input.log(`the selected production ${kind} app ${INGRESS[kind].delivers}`);
+    }
+    return reg.gate();
+}
+/**
+ * For each channel whose URL only a person sets (Slack; Lark without its config API), wait for the box to report it
+ * reached at the delivered URL, then record that URL in the binding, so every later deploy, CI included, reports it
+ * `registered` from the start (channel-setup.md §5).
+ */
+async function recordConfirmed(input, kinds, outcomes, record) {
+    const probe = input.probe ?? readBoxWebhooks;
+    const waiting = new Set(kinds.filter((k) => (k === "slack" || k === "lark") && outcomes.get(k) !== "failed"));
+    if (waiting.size === 0)
+        return;
+    const later = (kind) => `\`fastagent channels setup ${kind} --config <file> --record-url\``;
+    const manual = [...waiting].filter((kind) => outcomes.get(kind) === "manual");
+    if (manual.length > 0) {
+        input.log(`waiting up to ${Math.round(record.waitMs / 60_000)} min for ` +
+            `${manual.map((kind) => `${input.publicUrl}${webhookPath(kind)}`).join(" and ")} to be saved on the app's ` +
+            `page (the platform verifies it with this box); stop it any time and record it later with ${later(manual[0])}`);
+    }
+    // One deadline for every channel still waiting: each is recorded as the box reports it reached.
+    const deadline = Date.now() + record.waitMs;
+    for (;;) {
+        const read = await probe(`${input.baseUrl}/health`);
+        for (const kind of [...waiting]) {
+            if (read?.find((entry) => entry.channel === kind)?.outcome !== "registered")
+                continue;
+            waiting.delete(kind);
+            outcomes.set(kind, "registered");
+            const url = `${input.publicUrl}${webhookPath(kind)}`;
+            // The deployment is done and the platform reaches it: a record not written is said, never the deploy's failure.
+            await record.write(kind, url).then((where) => input.log(`${kind}: the platform reached the box at ${url}; recorded it in ${where}`), (error) => input.log(`${kind}: the platform reached the box at ${url}, but it was not recorded (${error.message}); ` +
+                `record it with ${later(kind)}`));
+        }
+        if (waiting.size === 0 || Date.now() >= deadline)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, input.intervalMs ?? 2_000));
+    }
+}

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;
@@ -156,7 +190,9 @@ ${deployment}`;
         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
@@ -165,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. */
@@ -179,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.*
@@ -202,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;