@fastagent-sh/fastagent 0.29.0 → 0.30.1

package/dist/deploy/agentcore/shell.js

@@ -13,14 +13,15 @@
  * terminal, so the command switches it to raw, no echo (answers are not echoed back, and a long line is not cut by
  * the terminal's line editor) before handing it to `exec`.
  */
-import { createHash, createHmac, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { PassThrough, Writable } from "node:stream";
 import { SignatureV4 } from "@smithy/signature-v4";
-import { WebSocket, ping } from "undici";
+import { RuntimeWebSocket, pinger } from "../../runtime-websocket.js";
 import { awsCli, awsJson } from "./aws-cli.js";
+import { Sha256 } from "./sigv4.js";
 import { MOUNT, PROBE_PAYLOAD } from "./plan.js";
 const STDIN = 0x00;
 const STDOUT = 0x01;
@@ -29,6 +30,7 @@ const STATUS = 0x03;
 const HEARTBEAT = 0x05;
 /** The service closes a connection whose frame is larger (code 1009). */
 const MAX_PAYLOAD = 64 * 1024 - 1;
+const WS_OPEN = 1;
 /** The SDK's interval; a connection with no ping for ~60s is dropped by the service. */
 const KEEPALIVE_MS = 30_000;
 /** The longest a presigned shell URL may live (the SDK refuses more). */
@@ -49,20 +51,6 @@ async function awsCliCredentials(aws) {
         return read.ok;
     throw new Error(`could not read AWS credentials from the AWS CLI (${"absent" in read ? "none configured" : read.unreadable})`);
 }
-/** SHA-256 / HMAC-SHA-256 over node:crypto, in the shape SigV4's signer takes. */
-class Sha256 {
-    hash;
-    constructor(secret) {
-        const key = secret instanceof ArrayBuffer ? Buffer.from(secret) : secret;
-        this.hash = key === undefined ? createHash("sha256") : createHmac("sha256", key);
-    }
-    update(data) {
-        this.hash.update(data instanceof ArrayBuffer ? Buffer.from(data) : data);
-    }
-    async digest() {
-        return new Uint8Array(this.hash.digest());
-    }
-}
 /** The runtime's region, from its ARN (`arn:<partition>:bedrock-agentcore:<region>:<account>:runtime/<id>`). */
 function regionOf(runtimeArn) {
     const region = runtimeArn.split(":")[3];
@@ -105,7 +93,12 @@ export function shellExit(status) {
 /** Open `command` in a new shell on `url`: stdin/stdout as streams, the other channels folded in. */
 export function openShellChannel(url, command) {
     const output = new PassThrough();
-    const ws = new WebSocket(url);
+    const ws = new RuntimeWebSocket(url);
+    const ping = pinger(ws);
+    if (ping === undefined) {
+        ws.close();
+        throw new Error("this runtime cannot send WebSocket pings, and the AgentCore service drops a shell connection that has none for about a minute");
+    }
     ws.binaryType = "arraybuffer";
     const frame = (channel, payload = Buffer.alloc(0)) => ws.send(Buffer.concat([Buffer.from([channel]), payload]));
     const stdin = (bytes) => {
@@ -122,7 +115,7 @@ export function openShellChannel(url, command) {
     ws.addEventListener("open", () => {
         stdin(Buffer.from(`stty raw -echo 2>/dev/null; exec sh -c '${command}'\n`));
         keepalive = setInterval(() => {
-            ping(ws);
+            ping();
             frame(HEARTBEAT);
         }, KEEPALIVE_MS);
     });
@@ -157,7 +150,7 @@ export function openShellChannel(url, command) {
     const input = new Writable({
         write(chunk, _encoding, done) {
             void opened.then((open) => {
-                if (open && ws.readyState === WebSocket.OPEN)
+                if (open && ws.readyState === WS_OPEN)
                     stdin(chunk);
                 done();
             });

package/dist/deploy/agentcore/sigv4.d.ts

@@ -0,0 +1,7 @@
+/** SHA-256 / HMAC-SHA-256 over node:crypto, in the shape SigV4's signer takes. */
+export declare class Sha256 {
+    private readonly hash;
+    constructor(secret?: string | ArrayBuffer | ArrayBufferView);
+    update(data: string | ArrayBuffer | ArrayBufferView): void;
+    digest(): Promise<Uint8Array>;
+}

package/dist/deploy/agentcore/sigv4.js

@@ -0,0 +1,15 @@
+import { createHash, createHmac } from "node:crypto";
+/** SHA-256 / HMAC-SHA-256 over node:crypto, in the shape SigV4's signer takes. */
+export class Sha256 {
+    hash;
+    constructor(secret) {
+        const key = secret instanceof ArrayBuffer ? Buffer.from(secret) : secret;
+        this.hash = key === undefined ? createHash("sha256") : createHmac("sha256", key);
+    }
+    update(data) {
+        this.hash.update(data instanceof ArrayBuffer ? Buffer.from(data) : data);
+    }
+    async digest() {
+        return new Uint8Array(this.hash.digest());
+    }
+}

package/dist/deploy/agentcore/slr.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The service-linked role AgentCore's runtime needs in the account, checked before a deploy builds anything. Without it
+ * CloudFormation fails at the runtime, minutes after the image push, with a bare `AccessDenied` that names nothing.
+ *
+ * Read first, create only when it is absent: IAM authorizes `CreateServiceLinkedRole` before it says a role already
+ * exists, so creating unconditionally would refuse a deployer who lacks that permission in every account where the role
+ * is long since there. A read that cannot be answered warns and goes on, as the region probe does.
+ */
+import type { AwsCli } from "./aws-cli.ts";
+export interface ServiceLinkedRole {
+    /** The service principal the role is created for. */
+    service: string;
+    /** The role's name, which is what `iam get-role` takes. */
+    name: string;
+}
+export declare const RUNTIME_IDENTITY_ROLE: ServiceLinkedRole;
+/** A gate line when the role is absent and cannot be made, else undefined. */
+export declare function ensureServiceLinkedRole(cli: AwsCli, role: ServiceLinkedRole, log: (message: string) => void): Promise<string | undefined>;

package/dist/deploy/agentcore/slr.js

@@ -0,0 +1,27 @@
+export const RUNTIME_IDENTITY_ROLE = {
+    service: "runtime-identity.bedrock-agentcore.amazonaws.com",
+    name: "AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
+};
+/** A gate line when the role is absent and cannot be made, else undefined. */
+export async function ensureServiceLinkedRole(cli, role, log) {
+    const found = await cli.present(["iam", "get-role", "--role-name", role.name]);
+    if ("ok" in found)
+        return undefined;
+    if ("unreadable" in found) {
+        log(`warn: could not check for the service-linked role ${role.name} (${found.unreadable.split("\n")[0]}) — if the ` +
+            `account has never used AgentCore and this principal may not create it, cloudformation deploy fails at the ` +
+            `runtime, after the image build`);
+        return undefined;
+    }
+    log(`creating the service-linked role ${role.name}…`);
+    const created = await cli.write(["iam", "create-service-linked-role", "--aws-service-name", role.service]);
+    if ("done" in created)
+        return undefined;
+    // Made by another deploy between the read and the write: it is there, which is all that is wanted.
+    if ("refused" in created && /has been taken/i.test(created.refused))
+        return undefined;
+    const why = "refused" in created ? created.refused : "it was not found";
+    return (`the service-linked role ${role.name} that AgentCore's runtime needs does not exist in this account, and it could ` +
+        `not be created (${why}) — have someone with iam:CreateServiceLinkedRole run ` +
+        `\`aws iam create-service-linked-role --aws-service-name ${role.service}\`, then re-run`);
+}

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

@@ -0,0 +1,7 @@
+import type { CliRunner } from "../runner.ts";
+import type { SecretStore } from "../secret-store.ts";
+export interface AgentcoreSecretStore extends SecretStore {
+    /** The secret's ARN, which the stack takes as its `SecretArn` parameter. */
+    arn(): Promise<string>;
+}
+export declare function agentcoreSecretStore(aws: CliRunner, secretName: string, log: (message: string) => void): AgentcoreSecretStore;

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,9 +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 { MCP_FILE } from "../mcp/config.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.
@@ -65,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)
@@ -95,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)
@@ -121,9 +121,6 @@ export async function checkKeptIgnoreFiles(ctx, report) {
                 `config (the deployed box has no agent to open and crash-loops). Remove that rule before deploying.`;
             report.issue(text);
         }
-        if (excluded(MCP_FILE) && (await exists(join(agentDir, MCP_FILE)))) {
-            report.issue(`your ${rel} excludes ${MCP_FILE}; the deployment would lose its MCP servers. Remove that rule before deploying.`);
-        }
         // Resolved paths, not spellings: dockerignore patterns are root-anchored (unlike .gitignore).
         const leaks = leakCandidates.filter((p) => !excluded(p));
         if (leaks.length > 0) {
@@ -134,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>;
+}