@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/deploy/agentcore/store.js

@@ -0,0 +1,115 @@
+/**
+ * AgentCore's values as a deployment's store: one Secrets Manager secret per deployment, a JSON object of NAME → value
+ * that the container reads on its first invocation (runtime-secrets.ts). It lives outside the stack, as the ECR
+ * repository and the artifact bucket do: its values must exist before the first deploy, and a stack update must not be
+ * what rewrites them.
+ *
+ * Reading goes around `awsCli().read`, whose unreadable answer quotes stdout: here stdout is every value.
+ */
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SECRET_FILE_MODE } from "../../paths.js";
+import { awsCli, awsJson } from "./aws-cli.js";
+const describe = (secretName, ...query) => [
+    "secretsmanager",
+    "describe-secret",
+    "--secret-id",
+    secretName,
+    ...query,
+];
+/** The values the secret holds now. A secret that is not a JSON object of strings is refused, naming nothing in it. */
+function parseValues(secretString) {
+    let parsed;
+    try {
+        parsed = JSON.parse(secretString);
+    }
+    catch {
+        throw new Error("its value is not JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("its value is not a JSON object of NAME → value");
+    }
+    for (const [name, value] of Object.entries(parsed)) {
+        if (typeof value !== "string")
+            throw new Error(`its value for ${name} is not a string`);
+    }
+    return parsed;
+}
+export function agentcoreSecretStore(aws, secretName, log) {
+    const cli = awsCli(aws);
+    const current = async () => {
+        const { code, stdout, stderr } = await aws(["secretsmanager", "get-secret-value", "--secret-id", secretName, "--query", "SecretString", "--output", "text"], { capture: true, captureStderr: true });
+        if (code !== 0) {
+            throw new Error(`\`aws secretsmanager get-secret-value\` failed: ${(stderr ?? "").trim().slice(0, 300)}`);
+        }
+        try {
+            return parseValues(stdout.trim());
+        }
+        catch (error) {
+            throw new Error(`the secret ${secretName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const store = {
+        async exists() {
+            const read = await cli.read(describe(secretName, "--output", "json"), awsJson((parsed) => parsed ?? undefined));
+            if ("unreadable" in read)
+                throw new Error(`could not read secret ${secretName}: ${read.unreadable}`);
+            if ("absent" in read)
+                return false;
+            if (read.ok.DeletedDate !== undefined) {
+                throw new Error(`secret ${secretName} is scheduled for deletion: \`aws secretsmanager restore-secret --secret-id ${secretName}\` ` +
+                    `brings it back, or wait for the deletion and re-run`);
+            }
+            return true;
+        },
+        async ensure() {
+            if (await store.exists())
+                return;
+            log(`creating secret ${secretName}…`);
+            const created = await cli.write([
+                "secretsmanager",
+                "create-secret",
+                "--name",
+                secretName,
+                "--description",
+                "FastAgent deployment values",
+                "--secret-string",
+                "{}",
+            ]);
+            if (!("done" in created)) {
+                throw new Error(`\`aws secretsmanager create-secret\` failed: ${"refused" in created ? created.refused : ""}`);
+            }
+        },
+        async names() {
+            return new Set(Object.keys(await current()));
+        },
+        async write(values) {
+            const names = Object.keys(values);
+            log(`setting ${names.length} value(s) in ${secretName}: ${names.join(", ")}`);
+            // Read, merge, write: one operator at a time, as every host's store assumes.
+            const merged = { ...(await current()), ...values };
+            // Over a file only this process can read, never argv.
+            const dir = await mkdtemp(join(tmpdir(), "fastagent-secret-"));
+            try {
+                const file = join(dir, "secret.json");
+                await writeFile(file, JSON.stringify(merged), { mode: SECRET_FILE_MODE });
+                const { code, stderr } = await aws(["secretsmanager", "put-secret-value", "--secret-id", secretName, "--secret-string", `file://${file}`], { capture: true, captureStderr: true });
+                if (code !== 0) {
+                    throw new Error(`\`aws secretsmanager put-secret-value\` failed: ${(stderr ?? "").trim().slice(0, 300)}`);
+                }
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+        },
+        async arn() {
+            const read = await cli.read(describe(secretName, "--query", "ARN", "--output", "text"), (stdout) => stdout.trim() || undefined);
+            if (!("ok" in read)) {
+                throw new Error(`could not read the ARN of secret ${secretName}: ${"unreadable" in read ? read.unreadable : "absent"}`);
+            }
+            return read.ok;
+        },
+    };
+    return store;
+}

package/dist/deploy/api.d.ts

@@ -1,34 +1,34 @@
-import type { AgentConfig } from "../harnesses/pi-durable/define.ts";
-/** Whether the deployment serves the API (and whether this deploy gives it its key), and why not when it does not. */
+import type { EffectiveConfig } from "../harnesses/pi-durable/config.ts";
+/** Whether the deployment serves the API, and why not when it does not. */
 export type DeploymentApi = {
     served: true;
-    generatesKey: boolean;
 } | {
     served: false;
     why: string;
 };
 /**
- * Decide the API for one deploy, writing nothing: a deploy the pre-flight refuses leaves the value file as it was.
- * Turned off, it is off on the deployment too, a key the values or the host still hold included: the serve reads the
- * same setting.
+ * Decide the API for one deploy, writing nothing. Turned off, it is off on the deployment too, a key the target still
+ * holds included: the serve reads the same setting.
  */
 export declare function deploymentApi(input: {
-    config: AgentConfig;
+    config: EffectiveConfig;
     /** The host serves the API at all: not AgentCore, reached only through `/invocations`. */
     hostServes: boolean;
-    values: ReadonlyMap<string, string>;
 }): DeploymentApi;
-/**
- * Give the deployment its key: into the value file, from which it travels with the other values, once the pre-flight
- * passes (a host's own check may still stop this deploy; the key stays for the next). Answers a secrets directory it
- * wrote into that git may track.
- */
-export declare function writeApiKey(agentDir: string): Promise<string | undefined>;
+/** A key for the Agent API, made here: FastAgent mints it, so no person holds it before the deploy. */
+export declare function mintApiKey(): {
+    name: string;
+    make(): string;
+};
 /**
  * What a deploy says of the API, once the host has said where the deployment is reached (when it knows). The check
  * names the agent's directory when the command runs elsewhere, since that is where `invoke --url` finds the key.
+ * `keyInFile`: this machine's production value file holds a key, which `invoke --url` then reads. `run`: the deploy
+ * has set the key (or found one) on the target; without it, nothing was set.
  */
 export declare function apiReport(api: DeploymentApi, where: {
     valueFile: string;
     agentArg: string | undefined;
+    keyInFile: boolean;
+    run: boolean;
 }, reachedAt: string | undefined): string[];

package/dist/deploy/api.js

@@ -1,50 +1,52 @@
 /**
  * A deployment's Agent API (SPEC.md §9.5, §9.6): served under `/v1` on every host but AgentCore, unless the
- * definition turns it off (`http.api: false`), behind a key `deploy` generates into the value file the first time,
- * which then travels with every other value. And what a deploy reports of it.
+ * definition turns it off (`http.api: false`), behind a key the deploy mints and sets on the target the first time
+ * neither the target nor the production value file has one. And what a deploy reports of it.
  */
 import { randomBytes } from "node:crypto";
 import { API_PREFIX } from "../http/contract.js";
-import { API_KEY_VARIABLE, API_TURNED_OFF, apiKeysFrom, apiTurnedOff } from "../http/server.js";
-import { writeValues } from "../value-file.js";
+import { API_KEY_VARIABLE, API_TURNED_OFF, apiTurnedOff } from "../http/server.js";
 /**
- * Decide the API for one deploy, writing nothing: a deploy the pre-flight refuses leaves the value file as it was.
- * Turned off, it is off on the deployment too, a key the values or the host still hold included: the serve reads the
- * same setting.
+ * Decide the API for one deploy, writing nothing. Turned off, it is off on the deployment too, a key the target still
+ * holds included: the serve reads the same setting.
  */
 export function deploymentApi(input) {
-    const { config, hostServes, values } = input;
+    const { config, hostServes } = input;
     if (!hostServes)
         return { served: false, why: "this host reaches the agent only through its own invocations" };
     if (apiTurnedOff(config))
         return { served: false, why: API_TURNED_OFF };
-    return { served: true, generatesKey: apiKeysFrom(values.get(API_KEY_VARIABLE)).length === 0 };
+    return { served: true };
 }
-/**
- * Give the deployment its key: into the value file, from which it travels with the other values, once the pre-flight
- * passes (a host's own check may still stop this deploy; the key stays for the next). Answers a secrets directory it
- * wrote into that git may track.
- */
-export async function writeApiKey(agentDir) {
-    const key = randomBytes(32).toString("base64url");
-    // Named in `overwrite`: a line that holds no key (empty, or only commas) is replaced, not kept as set.
-    const { unprotectedSecretsDir } = await writeValues(agentDir, "Agent API", [{ name: API_KEY_VARIABLE, value: key }], [API_KEY_VARIABLE]);
-    return unprotectedSecretsDir;
+/** A key for the Agent API, made here: FastAgent mints it, so no person holds it before the deploy. */
+export function mintApiKey() {
+    return { name: API_KEY_VARIABLE, make: () => randomBytes(32).toString("base64url") };
 }
 /**
  * What a deploy says of the API, once the host has said where the deployment is reached (when it knows). The check
  * names the agent's directory when the command runs elsewhere, since that is where `invoke --url` finds the key.
+ * `keyInFile`: this machine's production value file holds a key, which `invoke --url` then reads. `run`: the deploy
+ * has set the key (or found one) on the target; without it, nothing was set.
  */
 export function apiReport(api, where, reachedAt) {
     if (!api.served)
         return [`Agent API: not served — ${api.why}`];
-    const { valueFile, agentArg } = where;
+    const { valueFile, agentArg, keyInFile, run } = where;
     const base = reachedAt ?? "<the deployment's URL>";
+    if (!keyInFile && !run) {
+        return [
+            `Agent API: ${base}${API_PREFIX}, behind ${API_KEY_VARIABLE}, which --run makes and sets on the target when ` +
+                `neither it nor ${valueFile} has one`,
+        ];
+    }
+    if (!keyInFile) {
+        return [
+            `Agent API: ${base}${API_PREFIX}, behind ${API_KEY_VARIABLE} on the target; ${valueFile} holds none, so pass the key ` +
+                `to \`fastagent invoke --url\` with --key`,
+        ];
+    }
     return [
-        ...(api.generatesKey
-            ? [`Agent API: generated ${API_KEY_VARIABLE} in ${valueFile}; it travels with the other values`]
-            : []),
-        `Agent API: ${base}${API_PREFIX}, behind ${API_KEY_VARIABLE} in ${valueFile}`,
+        `Agent API: ${base}${API_PREFIX}, behind ${API_KEY_VARIABLE} (in ${valueFile})`,
         `check it: fastagent invoke --url ${base} "hello"${agentArg === undefined ? "" : ` ${agentArg}`}`,
     ];
 }

package/dist/deploy/box-shell.d.ts

@@ -21,9 +21,11 @@ export interface BoxShell {
     wake?(): Promise<void>;
     /**
      * The box's storage root, for a shell that does not carry the server's environment (AgentCore's). Unset: the
-     * shell sees `FASTAGENT_STORAGE_DIR` as the server does, or the image's default.
+     * shell sees `FASTAGENT_ROOT` as the server does, or the image's default.
      */
     storage?: string;
+    /** Where the box's image has the agent. Unset: where a generated image has it. */
+    program?: string;
 }
 /** A host CLI that runs a command on the box itself: `bin ...args(command)`, run from `cwd`. */
 export declare function processShell(bin: string, args: (command: string) => string[], cwd: string): BoxShell;

package/dist/deploy/build-context.d.ts

@@ -5,12 +5,12 @@ export interface BuildContextPaths {
     machineryPaths: string[];
     /** Credential files that exist right now — a kept ignore file that lets one through bakes it. */
     leakCandidates: string[];
-    /** The state root, when it exists inside the context. */
+    /** A state root of the agent's own choosing inside the context, when it exists. */
     stateShips?: string;
-    /** `content/`, when it exists: this machine's clones. */
+    /** `.fastagent/`, when it exists: the local instances' state and clones, and a build's staging. */
+    instancesShip?: string;
+    /** `content/`, when it exists: clones in the root, which a host refuses in a release. */
     contentShips?: string;
-    /** `context.local.json`, when it exists: the directories of this machine the agent is bound to. */
-    bindingsShip?: string;
     /** The agent's node_modules, when it exists. */
     depDirs: string[];
 }

package/dist/deploy/build-context.js

@@ -1,8 +1,8 @@
 import { readdir } from "node:fs/promises";
 import { isAbsolute, relative, join, sep } from "node:path";
 import ignore from "ignore";
-import { AGENT_CONFIG_FILE, CONTENT_DIRNAME, LOCAL_CONTEXT_FILE, SECRETS_DIRNAME, exists, readTextIfExists, resolveSecretsDir, resolveStateRoot, } from "../paths.js";
-import { isGeneratedDockerignore } from "./container.js";
+import { AGENT_CONFIG_FILE, CONTENT_DIRNAME, INSTANCES_DIRNAME, SECRETS_DIRNAME, exists, readTextIfExists, resolveSecretsDir, resolveStateRoot, } from "../paths.js";
+import { DELIVERED_CONFIG_DIR, isGeneratedDockerignore } from "./container.js";
 /**
  * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore` matcher (the same
  * library the scaffolded ignore files use), so `!` negation and last-match-wins are the library's problem, not ours.
@@ -64,10 +64,11 @@ export async function buildContextPaths(agentDir, authPath) {
     // State gets the same treatment (a custom in-tree FASTAGENT_STATE_DIR is invisible to the name-based `**/.state`),
     // at warn level.
     const stateRel = inContext(resolveStateRoot(agentDir));
+    const inInstances = stateRel !== undefined && (stateRel === INSTANCES_DIRNAME || stateRel.startsWith(`${INSTANCES_DIRNAME}/`));
     // Existence gates the WARNING, never the generated exclude (same split as secretPaths vs leakCandidates).
-    const stateShips = stateRel !== undefined && (await exists(join(agentDir, stateRel))) ? stateRel : undefined;
+    const stateShips = stateRel !== undefined && !inInstances && (await exists(join(agentDir, stateRel))) ? stateRel : undefined;
+    const instancesShip = (await exists(join(agentDir, INSTANCES_DIRNAME))) ? INSTANCES_DIRNAME : undefined;
     const contentShips = (await exists(join(agentDir, CONTENT_DIRNAME))) ? CONTENT_DIRNAME : undefined;
-    const bindingsShip = (await exists(join(agentDir, LOCAL_CONTEXT_FILE))) ? LOCAL_CONTEXT_FILE : undefined;
     // The `.env` family at the level fastagent is RESPONSIBLE for: the agent dir's root.
     const envFiles = (await entriesIfExists(agentDir))
         .map((entry) => entry.name)
@@ -94,13 +95,13 @@ export async function buildContextPaths(agentDir, authPath) {
     ];
     // Same existence rule: a node_modules that is not there cannot be uploaded.
     const depDirs = await present(["node_modules"]);
-    const machineryPaths = [...secretPaths, ...(stateRel ? [stateRel] : [])];
-    return { machineryPaths, leakCandidates, stateShips, contentShips, bindingsShip, depDirs };
+    const machineryPaths = [...secretPaths, ...(stateRel && !inInstances ? [stateRel] : [])];
+    return { machineryPaths, leakCandidates, stateShips, instancesShip, contentShips, depDirs };
 }
 /** Interrogate BOTH ignore files deploy emits, when the author kept them. */
 export async function checkKeptIgnoreFiles(ctx, report) {
     const { agentDir, force } = ctx;
-    const { leakCandidates, stateShips, contentShips, bindingsShip, depDirs } = ctx.paths;
+    const { leakCandidates, stateShips, instancesShip, contentShips, depDirs } = ctx.paths;
     for (const rel of [".dockerignore", "Dockerfile.dockerignore"]) {
         const kept = await readTextIfExists(join(agentDir, rel));
         if (kept === undefined)
@@ -130,14 +131,13 @@ export async function checkKeptIgnoreFiles(ctx, report) {
         if (stateShips && !excluded(`${stateShips}/sessions`)) {
             report.warn(`your ${rel} (kept) does not exclude \`${stateShips}\` — the build machine's sessions/channel state would ship in the image. ${remedy([`/${stateShips}`])}`);
         }
+        if (instancesShip && !excluded(`${instancesShip}/dev/content/x`)) {
+            report.warn(`your ${rel} (kept) does not exclude \`${instancesShip}\` — the build machine's sessions, channel state and clones of the agent's content would ship in the image. ${remedy([`/${instancesShip}`, `!/${DELIVERED_CONFIG_DIR}`])}`);
+        }
         // An issue, not a warning: a release holding content/ is refused on the host, which links its own there.
         if (contentShips && !excluded(`${contentShips}/x`)) {
             report.issue(`your ${rel} (kept) does not exclude \`${contentShips}\` — this machine's clones of the agent's content would ship in the image. ${remedy([`/${contentShips}`])}`);
         }
-        // A warning: the host reads it, and the paths it names (this machine's, the user's name in them) are not there.
-        if (bindingsShip && !excluded(bindingsShip)) {
-            report.warn(`your ${rel} (kept) does not exclude \`${bindingsShip}\` — the directories of this machine the agent is bound to would ship in the image, and the host would look for them at every start. ${remedy([`/${bindingsShip}`])}`);
-        }
         const unexcludedDeps = depDirs.filter((p) => !excluded(`${p}/.package-lock.json`));
         if (unexcludedDeps.length > 0) {
             report.warn(`your ${rel} does not exclude ${unexcludedDeps.map((p) => `\`${p}\``).join(" or ")} — the ` +

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

@@ -1,10 +1,9 @@
 /** HOW A RUNNING CHANNEL IS REACHED — the URL-neutral half of "point this channel at the agent". */
 import type { DeclaredChannel } from "../channels/discover.ts";
 import type { RegistrationOutcome } from "../channels/registration.ts";
-import type { ChannelKind } from "../scaffold/add-channel.ts";
+import { type WebhookKind, type WebhookRegistration } from "../channels/webhooks.ts";
 export interface Registrars {
     telegram: (baseUrl: string) => Promise<RegistrationOutcome>;
-    slack?: (baseUrl: string) => Promise<RegistrationOutcome>;
     feishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>;
     /**
      * Where a channel's manual step goes beside the log, for a person who reads no log: a coding agent's user, through
@@ -12,11 +11,6 @@ export interface Registrars {
      */
     leave?: (step: string) => void;
 }
-/**
- * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool knows how to
- * instruct.
- */
-export declare function webhookKinds(channels: readonly DeclaredChannel[]): ChannelKind[];
 /** Default route keys for {@link webhookKinds}, in the same order (the docker plan's ingress note). */
 export declare function webhookPaths(channels: readonly DeclaredChannel[]): string[];
 /**
@@ -31,7 +25,7 @@ export declare function pointChannelsAt(input: {
     registrars: Registrars;
     log: (msg: string) => void;
 }): Promise<{
-    kind: ChannelKind;
+    kind: WebhookKind;
     outcome: RegistrationOutcome;
 }[]>;
 /** Poll a public `/health` until it answers 200; false on timeout. Injected by tests. */
@@ -70,7 +64,7 @@ export declare function loginGate(input: {
     log: (msg: string) => void;
     /** What THIS host does about its webhooks once the box is logged in — the only per-host words in the gate. */
     afterLogin: string;
-    /** Where the channels point; unset when the host has not minted it yet (Docker's tunnel is read after). */
+    /** Where the channels point, for the lines that point them by hand; unset when the host has none to print. */
     baseUrl?: string;
 }): string;
 /** {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS. */
@@ -82,3 +76,35 @@ export declare function registerWebhooks(input: {
     /** How THIS host retries — the only per-host words in the gate. */
     retryHint: string;
 }): Promise<string | undefined>;
+/** A box's `/health` webhooks, or undefined while it cannot be read. Injected by tests. */
+export type BoxWebhooksProbe = (healthUrl: string) => Promise<readonly {
+    channel: string;
+    outcome: WebhookRegistration["outcome"];
+}[] | undefined>;
+/**
+ * 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 declare function confirmWebhooks(input: {
+    /** Where this machine reaches the box's `/health`: the host's own URL. */
+    baseUrl: string;
+    /** Where the platforms reach it, the delivered `http.publicUrl` (a custom domain, say): every step names this one. */
+    publicUrl: string;
+    channels: readonly DeclaredChannel[];
+    registrars: Pick<Registrars, "leave">;
+    log: (msg: string) => void;
+    retryHint: string;
+    probe?: BoxWebhooksProbe;
+    timeoutMs?: number;
+    intervalMs?: number;
+    /** At a terminal with a `--config` file: record each URL a person set once the box confirms it. */
+    record?: UrlRecorder;
+}): Promise<string | undefined>;
+/** Where a deploy at a terminal records the URL a person set once the box confirms it (`channels.<name>.app.url`). */
+export interface UrlRecorder {
+    /** How long to wait for the person to save the URL on the app's page. */
+    waitMs: number;
+    /** Write `url` into the binding of `kind` in the configuration `--config` names; resolves where it wrote. */
+    write(kind: WebhookKind, url: string): Promise<string>;
+}

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