@fastagent-sh/fastagent 0.29.0 → 0.30.1

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 };

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

@@ -1,6 +1,4 @@
 import type { BoxLoginStep } from "../box-shell.ts";
-import type { DeclaredChannel } from "../../channels/discover.ts";
-import type { RegistrationOutcome } from "../../channels/registration.ts";
 import { type CliRunner } from "../runner.ts";
 export interface DockerRunPlan {
     /** Compose file relative to the runner cwd (the agent directory). */
@@ -8,20 +6,10 @@ export interface DockerRunPlan {
     /** Container port from config; used to ask Compose for the effective published host port. */
     port: number;
     /**
-     * What `--run` assembled. The container reads the value file itself through the generated `env_file`, so nothing
-     * travels through this process: the names are reported to the operator and otherwise unused.
+     * Make sure the value file Compose reads by `env_file:` holds a value for every name the deployment needs, asking for
+     * the ones it lacks: resolves a gate line, or undefined. Nothing travels through this process.
      */
-    secrets: Record<string, string>;
-    /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
-    missingSecrets: string[];
-    /** That value file, agent-dir-relative, so the gate names the file this deploy actually read. */
-    valueFile: string;
-    /** Register the deployment's webhooks against the tunnel URL, reporting what each registrar answered. */
-    announce: DockerAnnounce;
-    /** Every declared channel and its ingress: which of them a failed login leaves unregistered. */
-    channels: readonly DeclaredChannel[];
-    /** `--tunnel` was requested for this run; a kept Compose file must actually contain that service. */
-    requireTunnel: boolean;
+    provideSecrets: () => Promise<string | undefined>;
     /**
      * Log the box in (`fastagent login --deployment`) once it is up and before any webhook is pointed at it: a channel pointed at
      * a box with no model credential answers every message with a failure. Resolves a gate line, or undefined.
@@ -31,23 +19,13 @@ export interface DockerRunPlan {
 export type DockerRunOutcome = {
     ok: true;
     url?: string;
-    tunnelUrl?: string;
 }
-/**
- * `url`/`tunnelUrl` travel with a gate too: Compose is up, so the operator still needs to know where it is and what
- * to re-run.
- */
+/** `url` travels with a gate too: Compose is up, so the operator still needs to know where. */
  | {
     ok: false;
     gate: string;
     url?: string;
-    tunnelUrl?: string;
 };
-/** Register the deployment's webhooks against its public URL, reporting what each registrar answered. */
-type DockerAnnounce = (baseUrl: string) => Promise<{
-    kind: string;
-    outcome: RegistrationOutcome;
-}[]>;
 /**
  * `stillStarting` answers whether the agent container is still up; a probe that ignores it simply waits out its whole
  * budget.
@@ -58,12 +36,6 @@ export type DockerHealthProbe = (healthUrl: string, stillStarting: () => Promise
  * publish free", asked before `up`, because afterwards a `/health` that answers cannot say whose it is.
  */
 export type HostPortProbe = (host: string, port: number) => Promise<boolean>;
-/** A published Quick Tunnel URL, and whether its tunnel ever reported an edge connection. */
-export interface ComposeTunnel {
-    url: string;
-    connected: boolean;
-}
-export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string) => Promise<ComposeTunnel | undefined>;
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
 export declare function localUrlFromComposePort(stdout: string): string | undefined;
 /**
@@ -75,14 +47,4 @@ export declare function agentPublishedPorts(stdout: string): {
     host: string;
     port: number;
 }[];
-/**
- * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel reports an edge
- * connection.
- */
-export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile: string, options?: {
-    attempts?: number;
-    intervalMs?: number;
-    sleep?: (ms: number) => Promise<void>;
-}): Promise<ComposeTunnel | undefined>;
-export declare function deployDockerRun(plan: DockerRunPlan, docker: CliRunner, log: (message: string) => void, healthProbe?: DockerHealthProbe, tunnelUrlProbe?: DockerTunnelUrlProbe, hostPortBusy?: HostPortProbe): Promise<DockerRunOutcome>;
-export {};
+export declare function deployDockerRun(plan: DockerRunPlan, docker: CliRunner, log: (message: string) => void, healthProbe?: DockerHealthProbe, hostPortBusy?: HostPortProbe): Promise<DockerRunOutcome>;

package/dist/deploy/docker/run.js

@@ -1,12 +1,8 @@
 /** `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally. */
 import { connect } from "node:net";
 import { waitForHealth } from "../../channels/wait-health.js";
-import { loginGate } from "../channel-ingress.js";
-import { TUNNEL_DNS_LAG_MS, hasTunnelConnection, parseTunnelUrl } from "../../tunnel.js";
-import { registrationGate } from "../registration-gate.js";
 import { MIN_DOCKER_COMPOSE_VERSION } from "./plan.js";
 import { readOutput } from "../runner.js";
-import { missingValuesGate } from "../secrets.js";
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
 export function localUrlFromComposePort(stdout) {
     const line = stdout
@@ -52,29 +48,6 @@ export function agentPublishedPorts(stdout) {
     });
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/**
- * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel reports an edge
- * connection.
- */
-export async function waitForComposeTunnelUrl(docker, composeFile, options = {}) {
-    const compose = ["compose", "-f", composeFile];
-    const attempts = options.attempts ?? 60;
-    let assigned;
-    for (let attempt = 0; attempt < attempts; attempt++) {
-        const logs = await docker([...compose, "logs", "--no-color", "tunnel"], { capture: true });
-        if (logs.code === 0) {
-            assigned ??= parseTunnelUrl(logs.stdout);
-            if (assigned && hasTunnelConnection(logs.stdout)) {
-                await (options.sleep ?? sleep)(TUNNEL_DNS_LAG_MS);
-                return { url: assigned, connected: true };
-            }
-        }
-        if (attempt + 1 < attempts)
-            await (options.sleep ?? sleep)(options.intervalMs ?? 500);
-    }
-    return assigned ? { url: assigned, connected: false } : undefined;
-}
-const defaultTunnelUrlProbe = (docker, composeFile) => waitForComposeTunnelUrl(docker, composeFile);
 /**
  * `/health` asked from inside the agent container, for a topology that publishes no host port. The image always has
  * node or bun (the generated Dockerfile's base), and both have `fetch`; nothing else is assumed installed.
@@ -92,7 +65,7 @@ async function containerHealthy(docker, compose, port, stillStarting) {
     }
     return false;
 }
-export async function deployDockerRun(plan, docker, log, healthProbe = defaultHealthProbe, tunnelUrlProbe = defaultTunnelUrlProbe, hostPortBusy = defaultHostPortBusy) {
+export async function deployDockerRun(plan, docker, log, healthProbe = defaultHealthProbe, hostPortBusy = defaultHostPortBusy) {
     const gate = (message) => ({ ok: false, gate: message });
     const compose = ["compose", "-f", plan.composeFile];
     // CLI/plugin gate first: unlike a daemon error, spawn ENOENT becomes 127 at the shared runner seam.
@@ -103,17 +76,10 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if (version.code !== 0) {
         return gate("Docker Compose plugin is unavailable — install/enable `docker compose`, then re-run");
     }
-    // The values gate precedes the first side effect (build/create).
-    const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
-    if (missingValues)
-        return gate(missingValues);
-    // Name what the container must find, and WHERE — the generated Compose reads the value file itself, so this run
-    // hands Compose nothing. Saying "passing N secrets to Compose" would be false, and doubly so on a hand-owned
-    // Compose file that has no `env_file` entry at all.
-    const secretNames = Object.keys(plan.secrets);
-    if (secretNames.length > 0) {
-        log(`${secretNames.length} value(s) the container reads from ${plan.valueFile}: ${secretNames.join(", ")}`);
-    }
+    // The values come before the first side effect (build/create).
+    const secretsGate = await plan.provideSecrets();
+    if (secretsGate !== undefined)
+        return gate(secretsGate);
     if ((await docker(["info"], { capture: true })).code !== 0) {
         return gate("Docker daemon is unavailable — start Docker Engine/Desktop, then re-run");
     }
@@ -127,11 +93,6 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if (!services.includes("agent")) {
         return gate(`Compose file must keep the "agent" service for \`fastagent deploy docker --run\``);
     }
-    const hasTunnel = services.includes("tunnel");
-    if (plan.requireTunnel && !hasTunnel) {
-        return gate(`--tunnel was requested but the kept ${plan.composeFile} has no "tunnel" service — ` +
-            `edit it, delete it and regenerate, or pass --force`);
-    }
     // A port something else already serves would answer the `/health` this run waits for, and the run would report that
     // process's answer as the agent's. A container this project already runs holds its own port, so only a first start
     // (or a start after `down`) asks. Before the first side effect: a refusal leaves nothing to undo.
@@ -146,19 +107,12 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
                 if (await hostPortBusy(host, port)) {
                     return gate(`${host}:${port} is already in use by another process, so the agent's published port is not free and a ` +
                         `health check there would answer for that process, not for the agent — stop it, or move the agent: ` +
-                        `edit the published port in ${plan.composeFile}, or change http.port in fastagent.config.ts and re-run ` +
+                        `edit the published port in ${plan.composeFile}, or change defaults.http.port in fastagent.config.ts and re-run ` +
                         `with --force (a generated Compose file is kept otherwise)`);
                 }
             }
         }
     }
-    // Quick Tunnel logs are the control-plane output (the assigned URL).
-    if (hasTunnel) {
-        log("recreating the ephemeral tunnel service…");
-        if ((await docker([...compose, "rm", "-s", "-f", "tunnel"])).code !== 0) {
-            return gate(`could not recreate the tunnel service — inspect \`docker compose -f ${plan.composeFile} ps\``);
-        }
-    }
     log(`building and reconciling ${plan.composeFile}…`);
     // `--pull`: the base image is a floating tag, and a copy cached here may be older than the runtime floor.
     if ((await docker([...compose, "build", "--pull"])).code !== 0) {
@@ -173,9 +127,6 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if (running.code !== 0 || !runningServices.includes("agent")) {
         return gate(`the Compose service "agent" is not running — inspect with \`docker compose -f ${plan.composeFile} logs agent\``);
     }
-    if (hasTunnel && !runningServices.includes("tunnel")) {
-        return gate(`the Compose service "tunnel" is not running — inspect with \`docker compose -f ${plan.composeFile} logs tunnel\``);
-    }
     // A user-owned topology may deliberately remove the host port and expose only through its own ingress.
     const published = await docker([...compose, "port", "agent", String(plan.port)], { capture: true });
     const url = published.code === 0 ? localUrlFromComposePort(published.stdout) : undefined;
@@ -208,33 +159,7 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     }
     // `url` travels with this gate: Compose is up, and the operator needs to know where.
     const notLoggedIn = await plan.boxLogin?.run();
-    if (notLoggedIn) {
-        // Only a tunnel is ours to announce; without one, the webhooks were never this run's to register.
-        const afterLogin = "re-run `fastagent deploy docker --run` (it keeps the login and announces the tunnel)";
-        const channels = hasTunnel ? plan.channels : [];
-        return { ok: false, gate: loginGate({ notLoggedIn, channels, log, afterLogin }), url };
-    }
-    if (!hasTunnel)
-        return { ok: true, url };
-    log("waiting for the Compose tunnel service to publish its Quick Tunnel URL…");
-    const tunnel = await tunnelUrlProbe(docker, plan.composeFile);
-    if (!tunnel) {
-        return gate(`tunnel did not publish a Quick Tunnel URL — inspect \`docker compose -f ${plan.composeFile} logs tunnel\``);
-    }
-    // The same sentence `startCloudflareTunnel` prints for the same state, and needed MORE here.
-    if (!tunnel.connected) {
-        log(`warn: the tunnel service never reported an edge connection for ${tunnel.url} — announcing it anyway. ` +
-            `Nothing reaches a tunnel that has not connected, so a webhook registration that cannot resolve the ` +
-            `host is this, not the platform. Inspect \`docker compose -f ${plan.composeFile} logs tunnel\`.`);
-    }
-    const tunnelUrl = tunnel.url;
-    // Registration lives HERE, like every other host's driver, and not at the CLI: this is the layer that owns the
-    // outcome, so it is the layer that can gate on one.
-    const reg = registrationGate(log, `re-run this deploy to retry registration (Compose is already up)`);
-    for (const { kind, outcome } of await plan.announce(tunnelUrl))
-        reg.track(kind, outcome);
-    const blocked = reg.gate();
-    if (blocked)
-        return { ok: false, gate: blocked, url, tunnelUrl };
-    return { ok: true, url, tunnelUrl };
+    if (notLoggedIn)
+        return { ok: false, gate: notLoggedIn, url };
+    return { ok: true, url };
 }

package/dist/deploy/file-store.d.ts

@@ -0,0 +1,2 @@
+import type { SecretStore } from "./secret-store.ts";
+export declare function fileStore(agentDir: string, file: string): SecretStore;

package/dist/deploy/file-store.js

@@ -0,0 +1,17 @@
+/** A value file as a deployment's store: Docker's (Compose reads it by `env_file:`), and what `start` reads. */
+import { loadEnvValues, writeValues } from "../value-file.js";
+export function fileStore(agentDir, file) {
+    return {
+        async exists() {
+            return true;
+        },
+        async ensure() { },
+        async names() {
+            return new Set([...loadEnvValues(file)].filter(([, value]) => value.trim() !== "").map(([name]) => name));
+        },
+        async write(values) {
+            const names = Object.keys(values);
+            await writeValues(agentDir, "deployment", names.map((name) => ({ name, value: values[name] })), names, file);
+        },
+    };
+}

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

@@ -18,12 +18,13 @@ export interface FlyPlanInput extends ContainerInput {
      */
     channels: readonly DeclaredChannel[];
     /**
-     * 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[];
     /** `schedules/` declares a schedule — one of the things that forces a machine up (deploy/residency.ts). */
     hasCron: boolean;
+    /** The `http.publicUrl` the image delivers, where the platforms reach the box; default the app's own URL. */
+    publicUrl?: string;
 }
 export interface FlyPlan {
     /** fly.toml / Dockerfile / .dockerignore — written by the CLI (skipped if present unless --force). */

package/dist/deploy/fly/plan.js

@@ -1,7 +1,9 @@
+import { webhookKinds } from "../../channels/webhooks.js";
 import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts, imageHasGit } from "../container.js";
 import { deploymentLoginCommand } from "../box-shell.js";
 import { WAKEUPS_WHEN_ASLEEP, residencyFor } from "../residency.js";
+import { stripEdges } from "../../strip-edges.js";
 function flyToml(appName, port, residency) {
     // WHY is residency.ts's to decide; the SETTING and its wording are Fly's. Anything else is an edit to the
     // generated file, which is the artifact's job.
@@ -65,7 +67,7 @@ export function planFlyDeploy(input) {
         `# Fly app names are GLOBALLY unique: if this fails as taken, set a unique "app" in fly.toml and`,
         `# re-run \`fastagent deploy fly\` — the runbook follows fly.toml's app name.`,
         `fly apps create ${appName}`,
-        `# The volume (definition, state, credentials — kept across stop/suspend/redeploy) is created by the deploy`,
+        `# The volume (the agent's working directory, state, credentials — kept across stop/suspend/redeploy) is created by the deploy`,
         `# below, in primary_region and sized by [mounts].initial_size. Creating it yourself first pins it to a host`,
         `# picked without the machine, which can fail the deploy with "insufficient resources … existing volume".`,
         ``,
@@ -77,18 +79,30 @@ export function planFlyDeploy(input) {
         `fly ips allocate-v6 --app ${appName}`,
     ];
     if (secrets.length > 0) {
-        runbook.push(``, `# Secrets (replace each <value>):`, ...secrets.map((s) => `#   ${s.name}: ${s.hint}`), `fly secrets set --app ${appName} ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
+        runbook.push(``, `# Secrets the app needs a value for. \`fastagent secrets push fly\` sets the ones a value file holds and`, `# \`fastagent secrets set fly <NAME>\` one typed without echo; or with flyctl (replace each <value>):`, ...secrets.map((s) => `#   ${s.name}: ${s.hint}`), `fly secrets set --app ${appName} ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
     runbook.push(``, `# The build context is the agent directory, baked as the definition.`, `# Before a new definition release, run \`fastagent deploy fly\` to refresh the release manifest.`, `# Run this from the agent directory:`, deployCmd);
-    runbook.push(``, `# The volume keeps .state and .secrets across restarts and deploys; each release replaces /data/definition.`, imageHasGit(input)
+    runbook.push(``, `# The volume is the agent's working directory: it keeps its work, .state and .secrets across restarts and deploys.`, imageHasGit(input)
         ? `# Git is installed (the definition ships its .git, github content is cloned here, or context.json declares it in aptPackages).`
         : `# To give the agent git, declare it: fastagent env add apt:git`);
     // The credential is created on the box, never carried: the box is then the only holder of its grant.
     if (input.boxLogin) {
         runbook.push(``, `# Model auth: once it is up, the deployment logs in to ${input.boxLogin} itself (from the agent directory):`, `${deploymentLoginCommand("fly", input.boxLogin)}`);
     }
-    // The fastagent-only post-step: point each channel at the live URL.
-    const steps = webhookRunbook(`https://${appName}.fly.dev`, channels);
+    // The box points the channels its own credentials can at its `http.publicUrl`; only Slack's is a person's step.
+    const appUrl = `https://${appName}.fly.dev`;
+    const publicUrl = input.publicUrl ?? appUrl;
+    const own = webhookKinds(channels).filter((kind) => kind !== "slack");
+    const steps = [
+        ...(own.length > 0
+            ? [
+                `# The box points ${own.join(", ")} at ${publicUrl} itself, on every start; its /health says how each`,
+                `# one went (a step only a person can take, Lark's console where its config API answers 404, is in its log):`,
+                `curl -fsS ${appUrl}/health`,
+            ]
+            : []),
+        ...webhookRunbook(publicUrl, channels.filter((channel) => channel.name === "slack")),
+    ];
     const post = steps.length > 0 ? [`# After deploy:`, ...steps] : [];
     if (post.length > 0)
         runbook.push(``, ...post);
@@ -107,9 +121,6 @@ export function parseFlyMinMachines(toml) {
 }
 /** Sanitize a directory basename into a Fly app name: lowercase, [a-z0-9-], must start with a letter. */
 export function toFlyAppName(basename) {
-    const slug = basename
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
+    const slug = stripEdges(basename.toLowerCase().replace(/[^a-z0-9]+/g, "-"), (char) => char === "-");
     return /^[a-z]/.test(slug) ? slug : `app-${slug || "agent"}`;
 }

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

@@ -1,16 +1,21 @@
 /** `fastagent deploy fly --run` — drive flyctl to completion. */
 import type { BoxLoginStep } from "../box-shell.ts";
-import { type PublicHealthProbe, type Registrars } from "../channel-ingress.ts";
+import { type BoxWebhooksProbe, type UrlRecorder, type PublicHealthProbe, type Registrars } from "../channel-ingress.ts";
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type CliRunner } from "../runner.ts";
+import type { SecretStore } from "../secret-store.ts";
 export interface FlyRunPlan {
+    /** At a terminal with a `--config` file: record each URL a person set once the box confirms it. */
+    recordUrl?: UrlRecorder;
+    /** The `http.publicUrl` the image delivers, where the platforms reach the box; default the app's own URL. */
+    publicUrl?: string;
     appName: string;
-    /** `KEY=value` secrets to set on Fly: the value file's variables. */
-    secrets: Record<string, string>;
-    /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
-    missingSecrets: string[];
-    /** That value file, agent-dir-relative, so the gate names the file this deploy actually read. */
-    valueFile: string;
+    /**
+     * Make sure the app holds a value for every name the deployment needs, through whoever can supply one
+     * (secret-store.ts): resolves a gate line, or undefined. It runs once the app exists, since only then can Fly say
+     * which names it has.
+     */
+    provideSecrets: (store: SecretStore) => Promise<string | undefined>;
     /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
     channels: readonly DeclaredChannel[];
     /** fly.toml path passed to `fly deploy -c` (relative to the run cwd = the agent directory). */
@@ -37,4 +42,9 @@ export type FlyRunOutcome = {
     ok: false;
     gate: string;
 };
-export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registrars: Registrars, healthProbe?: PublicHealthProbe): Promise<FlyRunOutcome>;
+export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, 
+/** Slack's, which this machine still sets (its Request URL no credential on the box can change). */
+registrars: Pick<Registrars, "leave">, healthProbe?: PublicHealthProbe, boxWebhooks?: {
+    probe: BoxWebhooksProbe;
+    intervalMs?: number;
+}): Promise<FlyRunOutcome>;

package/dist/deploy/fly/run.js

@@ -1,6 +1,7 @@
-import { loginGate, publicHealthGate, registerWebhooks, } from "../channel-ingress.js";
+import { confirmWebhooks, loginGate, publicHealthGate, } from "../channel-ingress.js";
 import { readOutput } from "../runner.js";
-import { hostSignedOutGate, missingValuesGate } from "../secrets.js";
+import { hostSignedOutGate } from "../secrets.js";
+import { ensureFlyApp, flyStore } from "./store.js";
 /**
  * The `Type` values that put an app on `https://<app>.fly.dev`, BY FAMILY — one entry per allocate command, because
  * that is the granularity the answer is acted on at.
@@ -17,23 +18,10 @@ function ingressAddresses(stdout) {
     const has = (types) => entries.some((entry) => typeof entry?.Address === "string" && entry.Address !== "" && types.includes(entry.Type));
     return { v4: has(INGRESS_TYPES.v4), v6: has(INGRESS_TYPES.v6) };
 }
-/**
- * Whether `fly apps list --json` lists an app called `name`. flyctl capitalizes the field, and an
- * offline fixture can only repeat what we already believe, so a change in flyctl's output is not caught here.
- */
-function listHasName(stdout, name) {
-    const entries = JSON.parse(stdout);
-    if (!Array.isArray(entries))
-        throw new Error(`expected a JSON array, got ${typeof entries}`);
-    return entries.some((o) => o.Name === name);
-}
-export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
+export async function deployFlyRun(plan, fly, log, 
+/** Slack's, which this machine still sets (its Request URL no credential on the box can change). */
+registrars, healthProbe, boxWebhooks) {
     const gate = (g) => ({ ok: false, gate: g });
-    // 1. Gate missing required secret VALUES before any side effect (no half-created infra), and before asking a
-    // person to sign in for a deploy that would stop here anyway.
-    const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
-    if (missingValues)
-        return gate(missingValues);
     // 2.
     if ((await fly(["auth", "whoami"], { capture: true })).code !== 0) {
         const failed = plan.hostLogin
@@ -43,19 +31,14 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
             return gate(failed);
     }
     // 3.
-    const appExists = await readOutput(fly, "fly", ["apps", "list", "--json"], (out) => listHasName(out, plan.appName));
-    if ("gate" in appExists)
-        return gate(appExists.gate);
-    if (appExists.value) {
-        log(`app ${plan.appName} exists — skipping create`);
-    }
-    else {
-        log(`creating app ${plan.appName}…`);
-        if ((await fly(["apps", "create", plan.appName])).code !== 0) {
-            return gate(`\`fly apps create ${plan.appName}\` failed — Fly app names are globally unique and it may be taken. ` +
-                `Set a unique \`app\` in fly.toml and re-run.`);
-        }
-    }
+    const appGate = await ensureFlyApp(fly, plan.appName, log);
+    if (appGate !== undefined)
+        return gate(appGate);
+    // 3b. Secrets, before anything else is set up for an app that cannot run without them: the names the app holds, the
+    // gaps filled (staged: the deploy below applies them).
+    const secretsGate = await plan.provideSecrets(flyStore(fly, plan.appName, log, { stage: true }));
+    if (secretsGate !== undefined)
+        return gate(secretsGate);
     // 4. NO volume step: `fly deploy` creates it from [mounts] on a first deploy, and only it can tell the scheduler
     // which machine (guest size + image) must fit on the host the volume is pinned to. Pre-creating one here placed it
     // blind, and a host with disk but no compute failed the deploy with `insufficient resources … with existing volume`.
@@ -78,15 +61,6 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
             return gate(`\`fly ${allocate.join(" ")}\` failed — see the flyctl output above`);
         }
     }
-    // 6. Secrets — staged (no deploy yet; we deploy with fly.toml next). Values over stdin, not argv.
-    const keys = Object.keys(plan.secrets);
-    if (keys.length > 0) {
-        log(`setting ${keys.length} secret(s): ${keys.join(", ")}`);
-        const input = `${keys.map((k) => `${k}=${plan.secrets[k]}`).join("\n")}\n`;
-        if ((await fly(["secrets", "import", "--stage", "-a", plan.appName], { input })).code !== 0) {
-            return gate("`fly secrets import` failed — see the flyctl output above");
-        }
-    }
     // 7.
     log("deploying (remote build)…");
     const deployArgs = [
@@ -128,13 +102,21 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
             afterLogin: "re-run `fastagent deploy fly --run` (it keeps the login)",
         }));
     }
-    // 9.
-    const registrationGateMsg = await registerWebhooks({
+    // 9. The box points its own channels at the `http.publicUrl` this deploy delivered; this reads what it made of them.
+    const registrationGateMsg = await confirmWebhooks({
         baseUrl,
+        publicUrl: plan.publicUrl ?? baseUrl,
         channels: plan.channels,
         registrars,
         log,
+        ...(plan.recordUrl === undefined ? {} : { record: plan.recordUrl }),
         retryHint: "re-run to retry registration (steps already done are skipped)",
+        ...(boxWebhooks === undefined
+            ? {}
+            : {
+                probe: boxWebhooks.probe,
+                ...(boxWebhooks.intervalMs === undefined ? {} : { intervalMs: boxWebhooks.intervalMs }),
+            }),
     });
     if (registrationGateMsg)
         return gate(registrationGateMsg);

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

@@ -0,0 +1,12 @@
+/** Fly's secrets as a deployment's store: `fly secrets list` for the names, `fly secrets set NAME=-` to set each. */
+import type { SecretStore } from "../secret-store.ts";
+import { type CliRunner } from "../runner.ts";
+/** Create the app when `fly apps list` does not show it. Resolves the gate line when it cannot be made. */
+export declare function ensureFlyApp(fly: CliRunner, app: string, log: (message: string) => void): Promise<string | undefined>;
+/**
+ * `stage`: set the secrets without deploying them, for a deploy that follows (`fly deploy` applies staged ones); off, a
+ * running app restarts on them at once.
+ */
+export declare function flyStore(fly: CliRunner, app: string, log: (message: string) => void, options: {
+    stage: boolean;
+}): SecretStore;