@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/credentials-page.js

@@ -0,0 +1,185 @@
+/**
+ * The page where a person pastes the values a channel's setup needs, for a setup that has no terminal (a coding agent's
+ * `--json`): loopback only, one use, and each value goes from the browser to this process and nowhere else (see
+ * setup-page.ts for why it is never the agent's conversation). Each value is checked as it is pasted and handed to
+ * `accept` at once, so a step that passed stays accepted when another is refused: the form then asks only for what is left.
+ */
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { SetupRefused } from "./channels/setup.js";
+import { field, formCard, openButton, privacy, prose, refusal, sendPage, setupRequestUrl, statusCard, step, submit, } from "./setup-page.js";
+function readBody(request) {
+    return new Promise((resolve) => {
+        let body = "";
+        let tooLarge = false;
+        request.on("data", (chunk) => {
+            if (tooLarge)
+                return;
+            body += String(chunk);
+            if (Buffer.byteLength(body) > 16 * 1024)
+                tooLarge = true;
+        });
+        request.on("end", () => resolve(tooLarge ? undefined : body));
+        request.on("error", () => resolve(undefined));
+    });
+}
+// A browser can leave during validation, before either response event can be subscribed to.
+function afterResponse(response, complete) {
+    if (response.destroyed || response.writableFinished)
+        complete();
+    else
+        response.once("close", complete);
+}
+export async function startCredentialsPage(input) {
+    const path = `/setup/${randomBytes(24).toString("hex")}`;
+    const { promise: done, resolve, reject } = Promise.withResolvers();
+    const accepted = new Set();
+    let checking = false;
+    let used = false;
+    let port = 0;
+    const form = (problem) => formCard(input.title, input.steps
+        .map(({ label, guide, fields }, index) => {
+        if (accepted.has(index))
+            return step(index + 1, label, prose(`Saved.`));
+        const here = problem?.step === index ? problem.refusal : undefined;
+        return step(index + 1, label, prose(guide.instructions) +
+            (guide.url === undefined ? "" : openButton("Open", guide.url)) +
+            (here === undefined
+                ? ""
+                : refusal(here.message, here.fix === undefined ? undefined : ` ${here.fix}`, here.why)) +
+            fields
+                .map((one, position) => field({
+                id: one.name,
+                label: one.label,
+                secret: one.secret ?? true,
+                invalid: here !== undefined,
+                autofocus: here !== undefined && position === 0,
+            }))
+                .join(""));
+    })
+        .join("") +
+        submit("Save and check") +
+        privacy());
+    const server = createServer(async (request, response) => {
+        const url = setupRequestUrl(request, response);
+        if (url === undefined)
+            return;
+        const host = request.headers.host ?? "";
+        if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+            response.writeHead(421).end("misdirected request\n");
+            return;
+        }
+        if (url.pathname !== path || (request.method !== "GET" && request.method !== "POST")) {
+            response.writeHead(404).end("not found\n");
+            return;
+        }
+        const expired = () => sendPage(response, 404, {
+            title: "FastAgent setup",
+            card: statusCard({
+                state: "failed",
+                heading: "This page is no longer in use",
+                next: "Go back to your coding agent.",
+            }),
+        });
+        if (used) {
+            expired();
+            return;
+        }
+        if (request.method === "GET") {
+            sendPage(response, 200, { title: `${input.title} — FastAgent`, card: form() });
+            return;
+        }
+        const site = request.headers["sec-fetch-site"];
+        if (site !== undefined && site !== "same-origin") {
+            response.writeHead(403).end("forbidden\n");
+            return;
+        }
+        const body = await readBody(request);
+        if (body === undefined) {
+            response.writeHead(413).end("payload too large\n");
+            return;
+        }
+        if (used) {
+            expired();
+            return;
+        }
+        if (checking) {
+            response.writeHead(409).end("another submission is being checked\n");
+            return;
+        }
+        checking = true;
+        const pasted = new URLSearchParams(body);
+        try {
+            for (const [index, { fields }] of input.steps.entries()) {
+                if (accepted.has(index))
+                    continue;
+                try {
+                    const values = {};
+                    for (const { name, label } of fields) {
+                        const value = (pasted.get(name) ?? "").trim();
+                        if (value === "")
+                            throw new SetupRefused(`${label} is needed.`);
+                        values[name] = value;
+                    }
+                    await input.accept(index, values);
+                    accepted.add(index);
+                }
+                catch (error) {
+                    // Only a refusal stays on the form; infrastructure and persistence errors end the setup.
+                    if (!(error instanceof SetupRefused))
+                        throw error;
+                    checking = false;
+                    sendPage(response, 200, { title: `${input.title} — FastAgent`, card: form({ step: index, refusal: error }) });
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            checking = false;
+            used = true;
+            afterResponse(response, () => reject(error));
+            sendPage(response, 200, {
+                title: "Setup stopped — FastAgent",
+                card: statusCard({
+                    state: "failed",
+                    heading: "Setup stopped",
+                    lede: error instanceof Error ? error.message : String(error),
+                    next: "Go back to your coding agent.",
+                }),
+            });
+            return;
+        }
+        used = true;
+        afterResponse(response, resolve);
+        sendPage(response, 200, {
+            title: `${input.doneHeading} — FastAgent`,
+            card: statusCard({
+                state: "done",
+                heading: input.doneHeading,
+                lede: "Your coding agent will say if anything is left to do.",
+                next: "Go back to your coding agent.",
+            }),
+        });
+    });
+    await new Promise((resolveListening, rejectListening) => {
+        server.once("error", rejectListening);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", rejectListening);
+            resolveListening();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        server.close();
+        throw new Error("the credentials page did not receive a local TCP port");
+    }
+    port = address.port;
+    return {
+        url: `http://127.0.0.1:${port}${path}`,
+        done,
+        close: () => new Promise((resolveClosed) => {
+            server.close(() => resolveClosed());
+            server.closeAllConnections();
+        }),
+    };
+}

package/dist/declared-secrets.d.ts

@@ -19,19 +19,26 @@ export interface DeclaredSecret {
     name: string;
     /** Where it was declared: "src/tools/x-post.ts", "fastagent.config.ts providers[0]", "context.json" — printed in
      *  runbooks and failures, so it must name a place the author can open. */
-    source: string;
+    declaredIn: string;
     /** What it is for, when the declaration says (`context.json`'s variables do): printed beside it in runbooks. */
     description?: string;
     /** The code runs without it: no start is refused for its absence. */
-    optional?: boolean;
+    optional: boolean;
+    /** Declared by one way of a channel that receives either way (`byIngress`): read only when it receives that way. */
+    when?: {
+        channel: string;
+        ingress: "webhook" | "connection";
+    };
 }
 /** Whether `name` has the shape of an env-var name ({@link ENV_NAME}). */
 export declare function isEnvName(name: string): boolean;
 /** Declared names as a stable list, first declaration winning — the form a carrier iterates. */
 export declare function dedupeSecrets(declared: readonly DeclaredSecret[]): DeclaredSecret[];
+/** The values of `secrets` that are set: what an environment is made of, since a name given no value is not one. */
+export declare function definedValues(secrets: Readonly<Record<string, string | undefined>>): Record<string, string>;
 /** Required names with no value in `env` — empty string counts as missing (an unset `.env` line). A name some
  *  declaration requires is required, whatever another says. */
-export declare function missingSecrets(declared: readonly DeclaredSecret[], env?: NodeJS.ProcessEnv): DeclaredSecret[];
+export declare function missingSecrets(declared: readonly DeclaredSecret[], env: NodeJS.ProcessEnv): DeclaredSecret[];
 /** "X_API_KEY, X_API_SECRET (src/tools/x-post.ts); SLACK_TOKEN (src/channels/slack.ts)" — grouped by the
  *  file to open, since that is the unit the author fixes. */
 export declare function describeSecrets(declared: readonly DeclaredSecret[]): string;

package/dist/declared-secrets.js

@@ -30,17 +30,21 @@ export function dedupeSecrets(declared) {
     const seen = new Set();
     return declared.filter((s) => !seen.has(s.name) && seen.add(s.name));
 }
+/** The values of `secrets` that are set: what an environment is made of, since a name given no value is not one. */
+export function definedValues(secrets) {
+    return Object.fromEntries(Object.entries(secrets).filter((entry) => entry[1] !== undefined));
+}
 /** Required names with no value in `env` — empty string counts as missing (an unset `.env` line). A name some
  *  declaration requires is required, whatever another says. */
-export function missingSecrets(declared, env = process.env) {
-    return dedupeSecrets(declared.filter((s) => s.optional !== true)).filter((s) => !env[s.name]);
+export function missingSecrets(declared, env) {
+    return dedupeSecrets(declared.filter((s) => !s.optional)).filter((s) => !env[s.name]);
 }
 /** "X_API_KEY, X_API_SECRET (src/tools/x-post.ts); SLACK_TOKEN (src/channels/slack.ts)" — grouped by the
  *  file to open, since that is the unit the author fixes. */
 export function describeSecrets(declared) {
     const bySource = new Map();
-    for (const { name, source } of dedupeSecrets(declared)) {
-        bySource.set(source, [...(bySource.get(source) ?? []), name]);
+    for (const { name, declaredIn } of dedupeSecrets(declared)) {
+        bySource.set(declaredIn, [...(bySource.get(declaredIn) ?? []), name]);
     }
     return [...bySource].map(([source, names]) => `${names.join(", ")} (${source})`).join("; ");
 }

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

@@ -1,11 +1,14 @@
 /**
  * `destroy agentcore`: removing what a deploy created, INCLUDING the parts the stack does not own.
  *
- * `aws cloudformation delete-stack` is the obvious move and it leaves three of the four behind, each for its own
+ * `aws cloudformation delete-stack` is the obvious move and it leaves most of them behind, each for its own
  * reason:
  *
  * - the S3 artifact bucket and the ECR repository must exist BEFORE the stack (it reads the forwarder's zip and
  *   the runtime's image from them), so they cannot be stack resources;
+ * - the Secrets Manager secret holds the deployment's values, which must exist before the first deploy and survive a
+ *   stack update, so it is no stack resource either; it is deleted without a recovery window, since a window would
+ *   keep its name from the next deployment of the agent (its values are pushed again from their source);
  * - the forwarder's log group is created by AWS on the Lambda's first WRITE, so no template ever mentions it —
  *   and the deploy put a 14-day retention on it, i.e. it holds data;
  * - the EventBridge schedules are minted at RUNTIME by the container: a recurring one per `schedules/` file, which

package/dist/deploy/agentcore/destroy.js

@@ -1,5 +1,5 @@
 import { awsCli, awsJson, parseLogGroupNames } from "./aws-cli.js";
-import { agentcoreRepoName, agentcoreStackName, deploymentBucketName, forwarderLogGroup, runtimeLogGroupPrefix, recurringSchedulePrefix, toRuntimeName, wakeAlarmPrefix, } from "./plan.js";
+import { agentcoreRepoName, agentcoreSecretName, agentcoreStackName, deploymentBucketName, forwarderLogGroup, runtimeLogGroupPrefix, recurringSchedulePrefix, toRuntimeName, wakeAlarmPrefix, } from "./plan.js";
 /** S3 deletes at most 1000 keys per call. */
 const DELETE_BATCH = 1000;
 /**
@@ -109,6 +109,19 @@ export async function destroyAgentcoreDeployment(plan, runner, announce = () =>
         return gate(`could not tell whether repository ${repo} exists in ${region}: ${repoRead.unreadable}`);
     }
     const repoExists = "ok" in repoRead;
+    const secretName = agentcoreSecretName(plan.name);
+    const secretRead = await aws.present([
+        "secretsmanager",
+        "describe-secret",
+        "--secret-id",
+        secretName,
+        "--output",
+        "json",
+    ]);
+    if ("unreadable" in secretRead) {
+        return gate(`could not tell whether secret ${secretName} exists in ${region}: ${secretRead.unreadable}`);
+    }
+    const secretExists = "ok" in secretRead;
     // BOTH LOG GROUPS. AWS creates each on the first WRITE, so neither is a stack resource — same reason, twice —
     // and the runtime's holds the agent's own stdout/stderr, i.e. what it said in every conversation. `deploy`'s
     // runbook already knows there are two: it sets a retention on each.
@@ -173,6 +186,8 @@ export async function destroyAgentcoreDeployment(plan, runner, announce = () =>
         found.push(`bucket ${bucket} (${keys.length} object version(s))`);
     if (repoExists)
         found.push(`repository ${repo}`);
+    if (secretExists)
+        found.push(`secret ${secretName} (its values are deleted for good, with no recovery window)`);
     for (const name of listedGroups)
         found.push(`log group ${name}`);
     // The one thing this command refuses to delete.
@@ -245,6 +260,15 @@ export async function destroyAgentcoreDeployment(plan, runner, announce = () =>
     if (repoExists) {
         await attempt(`repository ${repo}`, ["ecr", "delete-repository", "--repository-name", repo, "--force"]);
     }
+    if (secretExists) {
+        await attempt(`secret ${secretName}`, [
+            "secretsmanager",
+            "delete-secret",
+            "--secret-id",
+            secretName,
+            "--force-delete-without-recovery",
+        ]);
+    }
     for (const name of logGroups) {
         await attempt(`log group ${name}`, ["logs", "delete-log-group", "--log-group-name", name]);
     }

package/dist/deploy/agentcore/forwarder.js

@@ -1,6 +1,6 @@
 // Generated by `fastagent deploy agentcore` — the deployment's only ingress.
 // (Inside fastagent this file IS the source; the sentence below applies to the copy it is emitted as,
-// the agent directory's `lambda/index.js`.)
+// the agent directory's `agentcore/forwarder/index.js`.)
 // REGENERATED ON EVERY DEPLOY; edits here are overwritten and never deployed. `--run` builds the
 // Lambda package from fastagent's own copy of this source, so this file is the readable MIRROR of
 // what runs (and what the manual runbook zips) — not an input you can change.

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

@@ -10,8 +10,7 @@ export interface AgentcorePlanInput 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[];
     /**
@@ -51,7 +50,7 @@ export declare const SECRETS_DIR = "/mnt/data/.secrets";
 export declare const DEFAULT_IDLE_TIMEOUT_SECONDS = 180;
 /** One session's compute lifetime — AWS's own default. Both lifecycle fields cap at 1209600 (14 d). */
 export declare const MAX_LIFETIME_SECONDS = 28800;
-export declare const FORWARDER_FILE = "lambda/index.js";
+export declare const FORWARDER_FILE = "agentcore/forwarder/index.js";
 /**
  * Where the forwarder puts the one-shot schedule for a wake-up. The id inside the name is minted in the
  * container, so this prefix is the only handle anything outside has on the alarms a deployment has pending.
@@ -64,23 +63,10 @@ export declare function wakeAlarmPrefix(name: string): string;
 export declare function recurringSchedulePrefix(name: string): string;
 /** Account-suffixed artifact bucket for S3's global namespace. */
 export declare function deploymentBucketName(name: string, account: string): string;
-/**
- * AgentCore env values max 2048 chars — a value file's variables easily exceed it, so the carrier is CHUNKED across
- * `<NAME>` + `_2`… (collectChunked reassembles at boot).
- */
-export declare const CARRIER_CHUNK_SIZE = 2000;
-export declare const CARRIER_MAX_CHUNKS = 4;
-/** The template's chunked carrier: CloudFormation parameter prefix → container env-var name. */
-export declare const CARRIERS: readonly [{
-    readonly param: "FastagentEnv";
-    readonly env: "FASTAGENT_ENV";
-    readonly what: "base64 JSON of the value file's variables";
-}];
-/** Chunk `i` (0-based) of a carrier: its parameter and env-var names. */
-export declare function carrierChunk(carrier: (typeof CARRIERS)[number], i: number): {
-    param: string;
-    env: string;
-};
+/** The Secrets Manager secret holding a deployment's values: one JSON object of NAME → value (agent-artifact.md §6.2). */
+export declare function agentcoreSecretName(name: string): string;
+/** The environment variable that tells the container which secret to read at its first invocation. */
+export declare const SECRET_ARN_ENV = "FASTAGENT_SECRET_ARN";
 /** The generated template's filename (namespaced under the kit in the agentDir layout). */
 export declare const TEMPLATE_FILE = "agentcore.template.yaml";
 /** The generated template's first-line marker. */
@@ -122,7 +108,7 @@ export declare const PROBE_PAYLOAD: string;
 export declare function ingressSessionId(name: string): string;
 /**
  * The forwarder Lambda source — `forwarder.js` beside this file, the ONE text both the deployment package and the
- * readable `lambda/index.js` artifact are generated from.
+ * readable `agentcore/forwarder/index.js` artifact are generated from.
  */
 export declare function forwarderSource(): string;
 /** Compute the AgentCore deploy plan from the resolved definition. */

package/dist/deploy/agentcore/plan.js

@@ -2,9 +2,11 @@
 import { readFileSync } from "node:fs";
 import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
 import { SECRETS_DIRNAME } from "../../paths.js";
-import { webhookKinds, webhookRunbook } from "../channel-ingress.js";
+import { webhookKinds } from "../../channels/webhooks.js";
+import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentLoginCommand } from "../box-shell.js";
+import { stripEdges } from "../../strip-edges.js";
 function agentcoreTopology(input) {
     return { webhooks: input.channels.some((channel) => channel.ingress === "webhook") };
 }
@@ -19,7 +21,7 @@ export const SECRETS_DIR = `${MOUNT}/${SECRETS_DIRNAME}`;
 export const DEFAULT_IDLE_TIMEOUT_SECONDS = 180;
 /** One session's compute lifetime — AWS's own default. Both lifecycle fields cap at 1209600 (14 d). */
 export const MAX_LIFETIME_SECONDS = 28800;
-export const FORWARDER_FILE = "lambda/index.js";
+export const FORWARDER_FILE = "agentcore/forwarder/index.js";
 /**
  * Where the forwarder puts the one-shot schedule for a wake-up. The id inside the name is minted in the
  * container, so this prefix is the only handle anything outside has on the alarms a deployment has pending.
@@ -38,22 +40,12 @@ export function recurringSchedulePrefix(name) {
 export function deploymentBucketName(name, account) {
     return `fa-${name}-${account}`;
 }
-/**
- * AgentCore env values max 2048 chars — a value file's variables easily exceed it, so the carrier is CHUNKED across
- * `<NAME>` + `_2`… (collectChunked reassembles at boot).
- */
-export const CARRIER_CHUNK_SIZE = 2000;
-export const CARRIER_MAX_CHUNKS = 4;
-/** The template's chunked carrier: CloudFormation parameter prefix → container env-var name. */
-export const CARRIERS = [
-    { param: "FastagentEnv", env: "FASTAGENT_ENV", what: "base64 JSON of the value file's variables" },
-];
-/** Chunk `i` (0-based) of a carrier: its parameter and env-var names. */
-export function carrierChunk(carrier, i) {
-    return i === 0
-        ? { param: carrier.param, env: carrier.env }
-        : { param: `${carrier.param}${i + 1}`, env: `${carrier.env}_${i + 1}` };
+/** The Secrets Manager secret holding a deployment's values: one JSON object of NAME → value (agent-artifact.md §6.2). */
+export function agentcoreSecretName(name) {
+    return `fastagent/${name}`;
 }
+/** The environment variable that tells the container which secret to read at its first invocation. */
+export const SECRET_ARN_ENV = "FASTAGENT_SECRET_ARN";
 /** The generated template's filename (namespaced under the kit in the agentDir layout). */
 export const TEMPLATE_FILE = "agentcore.template.yaml";
 /** The generated template's first-line marker. */
@@ -64,14 +56,11 @@ export function isGeneratedAgentcoreTemplate(content) {
 }
 /** Deployment base name from the agent directory's name — the ONE mapping used to find its stack later. */
 export function agentcoreName(agentDirName) {
-    return (agentDirName
-        .toLowerCase()
-        .replace(/[^a-z0-9-]+/g, "-")
-        .replace(/^-+|-+$/g, "") || "agent");
+    return stripEdges(agentDirName.toLowerCase().replace(/[^a-z0-9-]+/g, "-"), (char) => char === "-") || "agent";
 }
 /** Runtime name (`[a-zA-Z][a-zA-Z0-9_]{0,47}`) from a dir basename. */
 export function toRuntimeName(basename) {
-    const slug = basename.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+    const slug = stripEdges(basename.replace(/[^a-zA-Z0-9]+/g, "_"), (char) => char === "_");
     return (/^[a-zA-Z]/.test(slug) ? slug : `agent_${slug || "fastagent"}`).slice(0, 48);
 }
 /** The forwarder Lambda's name — and therefore its log group, which AWS derives from it. */
@@ -119,7 +108,7 @@ export function ingressSessionId(name) {
 }
 /**
  * The forwarder Lambda source — `forwarder.js` beside this file, the ONE text both the deployment package and the
- * readable `lambda/index.js` artifact are generated from.
+ * readable `agentcore/forwarder/index.js` artifact are generated from.
  */
 export function forwarderSource() {
     return readFileSync(new URL("./forwarder.js", import.meta.url), "utf8");
@@ -129,30 +118,20 @@ function template(input, topology) {
     const runtimeName = toRuntimeName(input.name);
     const idleTimeout = input.idleTimeoutSeconds ?? DEFAULT_IDLE_TIMEOUT_SECONDS;
     const forwarderFnArn = `!Sub arn:aws:lambda:\${AWS::Region}:\${AWS::AccountId}:function:fastagent-${input.name}-forwarder`;
-    // Secret env vars ride CFN NoEcho parameters.
     const params = [
         `  ImageUri:`,
         `    Type: String`,
         `    Description: ECR image URI (linux/arm64) — <account>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>`,
     ];
-    params.push(`  ForwarderBucket:`, `    Type: String`, `    Description: S3 bucket holding the forwarder deployment package (created outside this stack)`, `  ForwarderS3Key:`, `    Type: String`, `    Description: content-hashed key of the forwarder .zip in ForwarderBucket`);
+    params.push(`  SecretArn:`, `    Type: String`, `    Description: ARN of the Secrets Manager secret holding the deployment's values (created outside this stack by \`fastagent secrets\`; the runtime reads it on its first invocation)`, `  ForwarderBucket:`, `    Type: String`, `    Description: S3 bucket holding the forwarder deployment package (created outside this stack)`, `  ForwarderS3Key:`, `    Type: String`, `    Description: content-hashed key of the forwarder .zip in ForwarderBucket`);
     const envLines = [
         `        PORT: "8080"`, // the Runtime service contract's fixed port (config.http.port does not apply here)
         `        FASTAGENT_AGENTCORE: "1"`, // serve mounts /invocations + /ping, arms no resident cron
-        `        FASTAGENT_STORAGE_DIR: ${MOUNT}`,
+        `        FASTAGENT_ROOT: ${MOUNT}`,
         `        FASTAGENT_STATE_DIR: ${MOUNT}/.state`,
         `        FASTAGENT_SECRETS_DIR: ${SECRETS_DIR}`,
+        `        ${SECRET_ARN_ENV}: !Ref SecretArn`,
     ];
-    // The carrier is chunked (env values max 2048 chars — see CARRIER_CHUNK_SIZE): N parameters, each riding its
-    // own env var; `start` reassembles them. ONE parameter set for every variable, so the template does not change
-    // when the value file gains a name.
-    for (const carrier of CARRIERS) {
-        for (let i = 0; i < CARRIER_MAX_CHUNKS; i++) {
-            const { param, env } = carrierChunk(carrier, i);
-            params.push(`  ${param}:`, `    Type: String`, `    Default: ""`, `    NoEcho: true`, `    Description: ${carrier.what} carried by --run, chunk ${i + 1}/${CARRIER_MAX_CHUNKS} (env values cap at 2048 chars); empty = unused`);
-            envLines.push(`        ${env}: !Ref ${param}`);
-        }
-    }
     // IAM invocation permission does not prove forwarder origin. Internal envelopes need a secret.
     params.push(`  FastagentIngressSecret:`, `    Type: String`, `    NoEcho: true`, `    Description: shared secret authenticating forwarder→runtime envelopes (any random string; --run mints one)`);
     envLines.push(`        FASTAGENT_INGRESS_SECRET: !Ref FastagentIngressSecret`);
@@ -199,6 +178,9 @@ function template(input, topology) {
         `              - Effect: Allow # AgentCore workload identity (the platform mints one per runtime)`,
         `                Action: [bedrock-agentcore:GetWorkloadAccessToken]`,
         `                Resource: "*"`,
+        `              - Effect: Allow # the deployment's values: this one secret, read on the first invocation`,
+        `                Action: [secretsmanager:GetSecretValue]`,
+        `                Resource: !Ref SecretArn`,
         ``,
         `  Runtime:`,
         `    Type: AWS::BedrockAgentCore::Runtime`,
@@ -251,7 +233,12 @@ export function planAgentcoreDeploy(input) {
         `# Prereqs: AWS CLI v2 with credentials + a region where AgentCore is available, and Docker with buildx`,
         `# (the image MUST be linux/arm64 — the one host whose build runs on YOUR machine, not remotely).`,
         ``,
-        `# 1. ECR repository + the forwarder artifact bucket (one-time; skip what exists).`,
+        `# 0. First use of AgentCore in this account only: the runtime needs its service-linked role, and without it`,
+        `#    CloudFormation fails at the runtime, after the build, with a bare AccessDenied. Skip if \`aws iam get-role`,
+        `#    --role-name AWSServiceRoleForBedrockAgentCoreRuntimeIdentity\` finds it.`,
+        `aws iam create-service-linked-role --aws-service-name runtime-identity.bedrock-agentcore.amazonaws.com`,
+        ``,
+        `# 1. ECR repository, the forwarder artifact bucket and the deployment's values secret (one-time; skip what exists).`,
         `aws ecr create-repository --repository-name ${repo}`,
         `aws s3api create-bucket --bucket ${bucketHint} --region us-east-1   # us-east-1 ONLY`,
         `aws s3api create-bucket --bucket ${bucketHint} --region <region> \\   # every OTHER region`,
@@ -259,10 +246,16 @@ export function planAgentcoreDeploy(input) {
         `aws s3api put-public-access-block --bucket ${bucketHint} \\`,
         `  --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true`,
         ``,
+        `aws secretsmanager create-secret --name ${agentcoreSecretName(name)} --secret-string '{}'`,
+        ...(secrets.length > 0
+            ? [`#    Its values, one command each (or \`fastagent secrets push agentcore\` for a file or the environment):`]
+            : []),
+        ...secrets.map((s) => `#      fastagent secrets set agentcore ${s.name}   # ${s.hint}`),
+        ``,
         `# 1b. Package the forwarder and upload it. Name the object by its CONTENT (a hash/date):`,
         `#     CloudFormation rolls the function only when the ForwarderS3Key VALUE changes.`,
-        `(cd lambda && zip -q forwarder.zip index.js)`,
-        `aws s3 cp lambda/forwarder.zip s3://${bucketHint}/forwarder/<hash>.zip`,
+        `(cd agentcore/forwarder && zip -q forwarder.zip index.js)`,
+        `aws s3 cp agentcore/forwarder/forwarder.zip s3://${bucketHint}/forwarder/<hash>.zip`,
         ``,
         `# 2. Build (linux/arm64) + push. Use a UNIQUE tag per deploy (a git sha / date): CloudFormation only`,
         `#    rolls the runtime when the ImageUri VALUE changes — re-pushing the same tag deploys nothing.`,
@@ -271,19 +264,17 @@ export function planAgentcoreDeploy(input) {
         ``,
         `# 3. Deploy the stack (runtime + ingress in one template).`,
     ];
-    if (secrets.length > 0) {
-        runbook.push(`#    Variables ride ONE NoEcho parameter, FastagentEnv: base64 of a JSON object {"NAME": "value", …},`, `#    split every ${CARRIER_CHUNK_SIZE} chars across FastagentEnv, FastagentEnv2 … (\`--run\` builds it):`, ...secrets.map((s) => `#      ${s.name}: ${s.hint}`));
-    }
+    runbook.push(`#    SecretArn: the ARN of the secret made in step 1 (aws secretsmanager describe-secret --secret-id ${agentcoreSecretName(name)} --query ARN)`);
     const wakeSecretHint = " FastagentWakeSecret=<any random string> FastagentIngressSecret=<another random string>";
     runbook.push(`#      FastagentWakeSecret: the wake-alarm shared secret — any random string (\`--run\` mints one)`);
     runbook.push(`#      FastagentIngressSecret: what proves an envelope came from the forwarder — another random string, kept for the activation below`);
-    runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${TEMPLATE_FILE} \\`, `  --capabilities CAPABILITY_IAM \\`, `  --parameter-overrides ImageUri=${image} ForwarderBucket=${bucketHint} ForwarderS3Key=forwarder/<hash>.zip${secrets.length > 0 ? " FastagentEnv=<base64 JSON>" : ""}${wakeSecretHint}`, ``, `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`, `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, `# The ingress transport is a separate Lambda and therefore a separate log source:`, `fastagent logs agentcore --source forwarder --follow`, ``, `# 6. Set a log retention period on EVERY group this stack writes to. Each is created by the service that`, `#    writes it, not by this template, and CloudWatch keeps log data indefinitely by default — which is`, `#    forever-billed storage, and the logs are where WHY a scheduled turn failed is recorded. Logs are the`, `#    ONE state path this host does not reclaim on its own.`, `aws logs put-retention-policy --log-group-name <the group \`fastagent logs agentcore\` resolves> --retention-in-days 14`, `# The forwarder is a separate Lambda, so its group is separate and defaults the same way:`, `aws logs put-retention-policy --log-group-name ${forwarderLogGroup(input.name)} --retention-in-days 14`);
+    runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${TEMPLATE_FILE} \\`, `  --capabilities CAPABILITY_IAM \\`, `  --parameter-overrides ImageUri=${image} SecretArn=<arn> ForwarderBucket=${bucketHint} ForwarderS3Key=forwarder/<hash>.zip${wakeSecretHint}`, ``, `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`, `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, `# The ingress transport is a separate Lambda and therefore a separate log source:`, `fastagent logs agentcore --source forwarder --follow`, ``, `# 6. Set a log retention period on EVERY group this stack writes to. Each is created by the service that`, `#    writes it, not by this template, and CloudWatch keeps log data indefinitely by default — which is`, `#    forever-billed storage, and the logs are where WHY a scheduled turn failed is recorded. Logs are the`, `#    ONE state path this host does not reclaim on its own.`, `aws logs put-retention-policy --log-group-name <the group \`fastagent logs agentcore\` resolves> --retention-in-days 14`, `# The forwarder is a separate Lambda, so its group is separate and defaults the same way:`, `aws logs put-retention-policy --log-group-name ${forwarderLogGroup(input.name)} --retention-in-days 14`);
     if (input.boxLogin) {
-        runbook.push(``, `# Model auth: after EVERY deploy and after 14 idle days (each storage reset wipes the last login),`, `# log the runtime in to ${input.boxLogin} from the agent directory — before pointing any webhook at it:`, `${deploymentLoginCommand("agentcore", input.boxLogin)}`);
+        runbook.push(``, `# Model auth: after EVERY deploy and after 14 idle days (each storage reset wipes the last login),`, `# log the runtime in to ${input.boxLogin} from the agent directory, once the probe below has opened it (a message`, `# that reaches the runtime before the login fails):`, `${deploymentLoginCommand("agentcore", input.boxLogin)}`);
     }
-    // Post-deploy webhook registration — the shared channel-ingress steps, pointed at the forwarder's Function URL
-    // (read from the stack outputs).
-    const post = webhookRunbook(`<ForwarderUrl>`, channels);
+    // The runtime points the channels its own credentials can at the forwarder's Function URL as the probe below wakes
+    // it; only Slack's URL, and Lark's where its config API answers 404, is a person's step.
+    const post = webhookRunbook(`<ForwarderUrl>`, channels.filter((channel) => channel.name === "slack"));
     // AgentCore asides the shared steps cannot carry: nothing else routes through a forwarder, and nothing else has a
     // compute ceiling.
     if (webhookKinds(channels).some((kind) => kind === "feishu" || kind === "lark")) {
@@ -291,8 +282,15 @@ export function planAgentcoreDeploy(input) {
     }
     if (post.length > 0)
         runbook.push(``, ...post);
-    runbook.push(``, `# Schedules and wake-ups are EventBridge-backed: the container mirrors (via the forwarder, authenticated by`, `#   FastagentWakeSecret) each schedule into a recurring EventBridge schedule (${recurringSchedulePrefix(name)}*) and each pending`, `#   wake-up into a self-deleting one-shot (${wakeAlarmPrefix(name)}*), which wake it even when the compute is reclaimed.`, `#   So a schedule written or edited on the runtime takes effect without a deploy. The container sets them only`, `#   once an envelope has reached it THROUGH THE FORWARDER, which tells it where the forwarder is; an`, `#   invoke-agent-runtime call does not (that door is IAM's, and does not carry it). \`--run\` does this with its`, `#   probe. After a manual deploy, do it once, or no schedule fires until a webhook arrives:`, `curl -fsS -X POST "<ForwarderUrl>/__fastagent/probe" -d '{"auth":"<FastagentIngressSecret>"}'`);
+    const own = webhookKinds(channels).filter((kind) => kind !== "slack");
+    runbook.push(``, `# Schedules and wake-ups are EventBridge-backed: the container mirrors (via the forwarder, authenticated by`, `#   FastagentWakeSecret) each schedule into a recurring EventBridge schedule (${recurringSchedulePrefix(name)}*) and each pending`, `#   wake-up into a self-deleting one-shot (${wakeAlarmPrefix(name)}*), which wake it even when the compute is reclaimed.`, `#   So a schedule written or edited on the runtime takes effect without a deploy. The container sets them only`, `#   once an envelope has reached it THROUGH THE FORWARDER, which tells it where the forwarder is; an`, `#   invoke-agent-runtime call does not (that door is IAM's, and does not carry it). \`--run\` does this with its`, `#   probe. After a manual deploy, do it once, or no schedule fires until a webhook arrives:`, `curl -fsS -X POST "<ForwarderUrl>/__fastagent/probe" -d '{"auth":"<FastagentIngressSecret>"}'`, ...(own.length > 0
+        ? [
+            `# The same envelope makes the runtime point ${own.join(", ")} at <ForwarderUrl> (or the configuration's`,
+            `# http.publicUrl) itself, on every start; the answer's "webhooks" says how each one went, "pending" until it ends`,
+            `# (a step only a person can take is in the runtime's log). Repeat the call to read it again.`,
+        ]
+        : []));
     runbook.push(``, `# Check that the deployed agent opens ({"ok":true}); it is reached through its channels, not this call:`, `aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}" \\`, `  --payload '${PROBE_PAYLOAD}' --cli-binary-format raw-in-base64-out /dev/stdout`);
-    runbook.push(``, `# Stop the fixed runtime session after redeploy so the next call uses the new image.`, `# \`--run\` does this automatically. In-flight turns are interrupted.`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`, ``, `# Redeploy = \`fastagent deploy agentcore\` (a new definition needs a fresh release manifest) + step 1b`, `# (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is managed SessionStorage. It keeps definition/ (with what the agent wrote there), .state/`, `# and .secrets/ across compute stop/resume — an idle-reclaimed agent resumes with its memory. AWS`, `# RESETS it on every runtime version update (i.e. every deploy) and after 14 idle days, so a deploy`, `# replaces the state along with the image: sessions, channel state and pending wake-ups start blank.`, `# A provider API key in the value file travels with every deploy; a login on the runtime survives neither reset.`, `# Cross-deploy memory needs EFS or S3 Files, which are VPC-only (a NAT gateway for model/channel`, `# egress, ~$33/mo standing): use \`deploy fly\` or \`deploy railway\` for a real volume instead.`, `# Keep one runtime writer per agent; use the fixed runtime session id printed above for every entry point.`);
+    runbook.push(``, `# Stop the fixed runtime session after redeploy so the next call uses the new image.`, `# \`--run\` does this automatically. In-flight turns are interrupted.`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`, ``, `# Redeploy = \`fastagent deploy agentcore\` (a new definition needs a fresh release manifest) + step 1b`, `# (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is managed SessionStorage, the agent's working directory. It keeps what the agent wrote there, .state/`, `# and .secrets/ across compute stop/resume — an idle-reclaimed agent resumes with its memory. AWS`, `# RESETS it on every runtime version update (i.e. every deploy) and after 14 idle days, so a deploy`, `# replaces the state along with the image: sessions, channel state and pending wake-ups start blank.`, `# A provider API key in the deployment's secret survives every deploy; a login on the runtime survives neither reset.`, `# Cross-deploy memory needs EFS or S3 Files, which are VPC-only (a NAT gateway for model/channel`, `# egress, ~$33/mo standing): use \`deploy fly\` or \`deploy railway\` for a real volume instead.`, `# Keep one runtime writer per agent; use the fixed runtime session id printed above for every entry point.`);
     return { artifacts, runbook, topology };
 }