@fastagent-sh/fastagent 0.29.0 → 0.30.1

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

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

@@ -1,9 +1,10 @@
 /** `fastagent deploy agentcore --run` — drive the AWS CLI + Docker to completion. */
 import type { BoxLoginStep } from "../box-shell.ts";
 import type { DeclaredChannel } from "../../channels/discover.ts";
-import { type Registrars } from "../channel-ingress.ts";
+import { type Registrars, type UrlRecorder } from "../channel-ingress.ts";
 import type { CliRunner } from "../runner.ts";
 import { type AgentcoreTopology } from "./plan.ts";
+import type { SecretStore } from "../secret-store.ts";
 export interface AgentcoreRunPlan {
     /** The base name — stack `fastagent-<name>`, ECR repo `fastagent/<name>`. */
     name: string;
@@ -18,12 +19,12 @@ export interface AgentcoreRunPlan {
      * region`.
      */
     region?: string;
-    /** Env-var name → value: the value file's carried variables. */
-    secrets: Record<string, string>;
-    /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
-    missingSecrets: string[];
-    /** That value file, agent-dir-relative, so the gate names the file this deploy actually read. */
-    valueFile: string;
+    /** Makes the secret hold every value the deployment needs (secrets-step.ts), or says what is missing. */
+    provideSecrets: (store: SecretStore) => Promise<string | undefined>;
+    /** What proves an envelope came from the forwarder: minted by the deploy, a stack parameter. */
+    ingressSecret: string;
+    /** The wake-alarm shared secret between the container and the forwarder: minted by the deploy, a stack parameter. */
+    wakeSecret: string;
     /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
     channels: readonly DeclaredChannel[];
     /**
@@ -32,10 +33,14 @@ export interface AgentcoreRunPlan {
      */
     topology: AgentcoreTopology;
     /**
-     * Log the runtime in (`fastagent login --deployment`) once the probe verified it and before any webhook points at
-     * it. Resolves a gate line, or undefined.
+     * Log the runtime in (`fastagent login --deployment`) once the probe verified it and before the deploy reads its
+     * webhooks. Resolves a gate line, or undefined.
      */
     boxLogin?: BoxLoginStep<[runtimeArn: string]>;
+    /** The `http.publicUrl` the configuration names (a custom domain); default the forwarder's URL. */
+    publicUrl?: string;
+    /** At a terminal with a `--config` file: record each URL a person set once the box confirms it. */
+    recordUrl?: UrlRecorder;
 }
 export type AgentcoreRunOutcome = {
     ok: true;
@@ -57,7 +62,10 @@ export type AgentcoreRunOutcome = {
  */
 export declare function pickStackOutputs(parsed: unknown): Record<string, string> | undefined;
 /** The `--parameter-overrides file://` payload: a JSON array of "Key=Value" strings. */
-export declare function paramsFileContent(imageUri: string, secrets: Record<string, string>, forwarder: {
+export declare function paramsFileContent(imageUri: string, secretArn: string, minted: {
+    ingressSecret: string;
+    wakeSecret: string;
+}, forwarder: {
     bucket: string;
     key: string;
 }): string;

package/dist/deploy/agentcore/run.js

@@ -1,11 +1,12 @@
 import { RESERVED_PATHS } from "../../channels/agentcore-protocol.js";
-import { loginGate, registerWebhooks } from "../channel-ingress.js";
+import { confirmWebhooks, loginGate, } from "../channel-ingress.js";
 import { awsCli, awsJson } from "./aws-cli.js";
 import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
-import { CARRIERS, CARRIER_CHUNK_SIZE, CARRIER_MAX_CHUNKS, MOUNT, agentcoreRepoName, agentcoreStackName, carrierChunk, deploymentBucketName, forwarderSource, ingressSessionId, } from "./plan.js";
+import { MOUNT, agentcoreRepoName, agentcoreSecretName, agentcoreStackName, deploymentBucketName, forwarderSource, ingressSessionId, } from "./plan.js";
 import { zipSingleFile } from "./zip.js";
-import { encodeCarriedEnv, missingValuesGate } from "../secrets.js";
+import { RUNTIME_IDENTITY_ROLE, ensureServiceLinkedRole } from "./slr.js";
+import { agentcoreSecretStore } from "./store.js";
 /** AWS keys are typed, so a coding agent's user signs the CLI in at a terminal of their own. */
 const AWS_SIGN_IN = "run `aws configure` (or `aws sso login`) in a terminal of your own, where the keys are typed, then re-run";
 /**
@@ -23,23 +24,51 @@ const EMPTY_STACK_STATUSES = new Set([
     "REVIEW_IN_PROGRESS",
     "DELETE_COMPLETE",
 ]);
+/**
+ * How often the deploy asks the runtime how its webhooks went. Each ask is a Lambda and an `InvokeAgentRuntime` that
+ * keeps the microVM up and is billed, where another host's `/health` costs nothing.
+ */
+const WEBHOOKS_INTERVAL_MS = 5_000;
 /** Budget for image pull, storage initialization and channel construction. */
 const PROBE_TIMEOUT_MS = 240_000;
 const PROBE_INTERVAL_MS = 3_000;
+/** One call to the forwarder's reserved probe path. */
+async function askProbe(probeUrl, auth, fetchImpl) {
+    const res = await fetchImpl(probeUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ auth }),
+        signal: AbortSignal.timeout(65_000),
+    });
+    return { status: res.status, body: await res.text() };
+}
+/**
+ * The runtime's own report of its webhook channels, through the probe: the container has no `/health` of its own to
+ * read, and the forwarder relays only this path. The address it is handed is the other hosts' `/health`, which this
+ * one has no use for.
+ */
+function forwarderWebhooks(probeUrl, auth, fetchImpl) {
+    return async () => {
+        try {
+            const { status, body } = await askProbe(probeUrl, auth, fetchImpl);
+            const verdict = status === 200 ? JSON.parse(body) : undefined;
+            return verdict?.ok === true && Array.isArray(verdict.webhooks)
+                ? verdict.webhooks
+                : undefined;
+        }
+        catch {
+            return undefined; // polled again until the deadline
+        }
+    };
+}
 /** Drive the forwarder's reserved probe path until it answers, and read the runtime's STRUCTURED verdict. */
 async function probeRuntime(probeUrl, auth, fetchImpl, timeoutMs = PROBE_TIMEOUT_MS, intervalMs = PROBE_INTERVAL_MS) {
     const deadline = Date.now() + timeoutMs;
     let last;
     for (;;) {
         try {
-            const res = await fetchImpl(probeUrl, {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify({ auth }),
-                signal: AbortSignal.timeout(65_000),
-            });
-            const bodyText = await res.text();
-            if (res.status === 200) {
+            const { status, body: bodyText } = await askProbe(probeUrl, auth, fetchImpl);
+            if (status === 200) {
                 let verdict;
                 try {
                     verdict = JSON.parse(bodyText);
@@ -55,7 +84,7 @@ async function probeRuntime(probeUrl, auth, fetchImpl, timeoutMs = PROBE_TIMEOUT
                 }
             }
             const firstLine = bodyText.trim().split("\n")[0] ?? "";
-            last = `${res.status}${firstLine ? ` ${firstLine}` : ""}`;
+            last = `${status}${firstLine ? ` ${firstLine}` : ""}`;
         }
         catch {
             // not routable yet (Function URL DNS, cold start) — keep polling until the deadline
@@ -93,32 +122,16 @@ export function pickStackOutputs(parsed) {
     }
     return out;
 }
-/** The secrets `--run` mints for this host, each with the template parameter of its own. */
-const MINTED_PARAMS = {
-    FASTAGENT_INGRESS_SECRET: "FastagentIngressSecret",
-    FASTAGENT_WAKE_SECRET: "FastagentWakeSecret",
-};
-/** What each carrier holds for this deploy: every variable but the minted ones, as one encoded object. */
-function carrierValues(secrets) {
-    const carried = Object.fromEntries(Object.entries(secrets).filter(([name]) => !(name in MINTED_PARAMS)));
-    return { FASTAGENT_ENV: encodeCarriedEnv(carried) };
-}
 /** The `--parameter-overrides file://` payload: a JSON array of "Key=Value" strings. */
-export function paramsFileContent(imageUri, secrets, forwarder) {
-    const params = [`ImageUri=${imageUri}`, `ForwarderBucket=${forwarder.bucket}`, `ForwarderS3Key=${forwarder.key}`];
-    for (const [name, param] of Object.entries(MINTED_PARAMS)) {
-        if (secrets[name] !== undefined)
-            params.push(`${param}=${secrets[name]}`);
-    }
-    // Every chunk is written, empty ones included: an omitted parameter keeps its PREVIOUS value on a stack update.
-    const values = carrierValues(secrets);
-    for (const carrier of CARRIERS) {
-        const value = values[carrier.env];
-        for (let i = 0; i < CARRIER_MAX_CHUNKS; i++) {
-            params.push(`${carrierChunk(carrier, i).param}=${value.slice(i * CARRIER_CHUNK_SIZE, (i + 1) * CARRIER_CHUNK_SIZE)}`);
-        }
-    }
-    return `${JSON.stringify(params)}\n`;
+export function paramsFileContent(imageUri, secretArn, minted, forwarder) {
+    return `${JSON.stringify([
+        `ImageUri=${imageUri}`,
+        `SecretArn=${secretArn}`,
+        `ForwarderBucket=${forwarder.bucket}`,
+        `ForwarderS3Key=${forwarder.key}`,
+        `FastagentIngressSecret=${minted.ingressSecret}`,
+        `FastagentWakeSecret=${minted.wakeSecret}`,
+    ])}\n`;
 }
 /** Run the deploy through `aws` + `docker`. */
 export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registrars, 
@@ -163,21 +176,6 @@ probe = {}) {
     if ((await docker(["buildx", "version"], { capture: true })).code !== 0) {
         return gate("docker buildx not available — the image must be linux/arm64 (cross-built); install buildx, then re-run");
     }
-    // 3. Gate missing required secret VALUES before any side effect (no half-created infra).
-    const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
-    if (missingValues)
-        return gate(missingValues);
-    // 3b.
-    const capacity = CARRIER_CHUNK_SIZE * CARRIER_MAX_CHUNKS;
-    const carried = carrierValues(plan.secrets);
-    if (carried.FASTAGENT_ENV.length > capacity) {
-        return gate(`the variables in ${plan.valueFile} are too large to carry (${carried.FASTAGENT_ENV.length} chars encoded > ` +
-            `${capacity}) — move what the deployment does not need out of that file`);
-    }
-    // Name what travels from the value file onto the runtime.
-    const secretNames = Object.keys(plan.secrets);
-    if (secretNames.length > 0)
-        log(`carrying ${secretNames.length} secret(s): ${secretNames.join(", ")}`);
     // 3c. Say what this deploy is ABOUT TO TOUCH while it can still be stopped for free: until here the account and
     // region only surfaced several hundred log lines in, inside the ECR image URI.
     const source = plan.region ? "the environment" : "aws configure";
@@ -203,7 +201,12 @@ probe = {}) {
             `cloudformation deploy fails minutes from now, after the image build: ` +
             `https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html`);
     }
-    // 3d. Read the stack here, for the two questions that both depend on it: does this deploy destroy the agent's
+    // 3d. The role the runtime needs in this account, made if a first deploy finds it missing: a stop here costs nothing,
+    // and the same fault found by CloudFormation costs the build.
+    const roleGate = await ensureServiceLinkedRole(cli, RUNTIME_IDENTITY_ROLE, log);
+    if (roleGate !== undefined)
+        return gate(roleGate);
+    // 3e. Read the stack here, for the two questions that both depend on it: does this deploy destroy the agent's
     // memory (below), and is there a failed first create to clear (step 7)? The destructive one is only worth saying
     // while the multi-minute build has not run yet, and step 7 reuses this answer unless it was still in flight.
     // An unanswered question must not read as "a first deploy, nothing to lose": `sts get-caller-identity` succeeding
@@ -236,6 +239,18 @@ probe = {}) {
             `sessions, channel state and pending wake-ups start blank. ` +
             `Cross-deploy memory needs a real volume: \`deploy fly\` or \`deploy railway\`.`);
     }
+    // 3f. The deployment's values, after the only questions that precede a write and before the build: the secret the stack reads, made to hold every name the definition
+    // requires (a coding agent's run, with nobody to ask, stops here naming the commands).
+    const secretStore = agentcoreSecretStore(aws, agentcoreSecretName(plan.name), log);
+    try {
+        await secretStore.ensure();
+    }
+    catch (error) {
+        return gate(error instanceof Error ? error.message : String(error));
+    }
+    const secretsGate = await plan.provideSecrets(secretStore);
+    if (secretsGate !== undefined)
+        return gate(secretsGate);
     // 4.
     const registry = `${account}.dkr.ecr.${region}.amazonaws.com`;
     const image = `${registry}/${repo}:${plan.tag}`;
@@ -306,7 +321,7 @@ probe = {}) {
     if ((await docker(buildArgs)).code !== 0) {
         return gate("`docker buildx build` failed — see the output above; fix and re-run");
     }
-    // 7. The 3d answer stands unless it was still settling then — a second read is the narrow exception, not the rule.
+    // 7. The 3e answer stands unless it was still settling then — a second read is the narrow exception, not the rule.
     const beforeDeploy = settling ? await readStackStatus() : stackStatus;
     if ("ok" in beforeDeploy && beforeDeploy.ok === "ROLLBACK_COMPLETE") {
         log(`stack ${stack} is ROLLBACK_COMPLETE (a failed first create) — deleting it before re-creating…`);
@@ -318,7 +333,14 @@ probe = {}) {
         }
     }
     log(`deploying stack ${stack}…`);
-    const paramsPath = await writeSecretFile(paramsFileContent(image, plan.secrets, forwarderParams));
+    let secretArn;
+    try {
+        secretArn = await secretStore.arn();
+    }
+    catch (error) {
+        return gate(error instanceof Error ? error.message : String(error));
+    }
+    const paramsPath = await writeSecretFile(paramsFileContent(image, secretArn, plan, forwarderParams));
     const deployed = await aws([
         "cloudformation",
         "deploy",
@@ -386,7 +408,7 @@ probe = {}) {
     // Verify storage initialization and channel construction before registering webhooks.
     if (url) {
         log("probing the deployed runtime (storage initialization + channel construction)…");
-        const verdict = await probeRuntime(`${url}${RESERVED_PATHS.probe}`, plan.secrets.FASTAGENT_INGRESS_SECRET ?? "", probe.fetchImpl ?? fetch, probe.timeoutMs, probe.intervalMs);
+        const verdict = await probeRuntime(`${url}${RESERVED_PATHS.probe}`, plan.ingressSecret, probe.fetchImpl ?? fetch, probe.timeoutMs, probe.intervalMs);
         if (!verdict.ok)
             return gate(verdict.gate);
         log("runtime verified (storage ready, channels constructed)");
@@ -397,22 +419,23 @@ probe = {}) {
             notLoggedIn,
             channels: plan.channels,
             log,
-            // The forwarder URL outlives a redeploy, so the webhooks an earlier deploy registered already point at it.
-            ...(redeploy
-                ? { afterLogin: "they work again: the forwarder URL is unchanged, so nothing needs pointing" }
-                : { baseUrl: url, afterLogin: "point the channels by hand (a redeploy would wipe that login again)" }),
+            // The runtime points its own channels at the forwarder URL as the probe wakes it, login or not.
+            afterLogin: "they work again: the runtime has pointed its own channels, so nothing needs pointing",
         }));
     }
-    // 9.
-    const registrationGateMsg = url
-        ? await registerWebhooks({
-            baseUrl: url,
-            channels: plan.channels,
-            registrars,
-            log,
-            retryHint: "re-run to retry registration (steps already done are skipped)",
-        })
-        : undefined;
+    // 9. The runtime points its own channels as the probe wakes it; this reads what it made of them.
+    const registrationGateMsg = await confirmWebhooks({
+        baseUrl: url,
+        publicUrl: plan.publicUrl ?? url,
+        channels: plan.channels,
+        registrars,
+        log,
+        ...(plan.recordUrl === undefined ? {} : { record: plan.recordUrl }),
+        retryHint: "re-run to retry registration (steps already done are skipped)",
+        probe: forwarderWebhooks(`${url}${RESERVED_PATHS.probe}`, plan.ingressSecret, probe.fetchImpl ?? fetch),
+        intervalMs: probe.intervalMs ?? WEBHOOKS_INTERVAL_MS,
+        ...(probe.timeoutMs === undefined ? {} : { timeoutMs: probe.timeoutMs }),
+    });
     if (registrationGateMsg)
         return gate(registrationGateMsg);
     return { ok: true, runtimeArn, url };

package/dist/deploy/agentcore/runtime-secrets.d.ts

@@ -0,0 +1,7 @@
+/** The secret's JSON object, every value a string. */
+export declare function readSecretValues(secretArn: string): Promise<Record<string, string>>;
+/**
+ * Put the secret's values into `env`, unless the platform set the name itself (the platform's variables win, as they do
+ * over a value file anywhere). Without `FASTAGENT_SECRET_ARN` there is nothing to read.
+ */
+export declare function applyRuntimeSecrets(env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/deploy/agentcore/runtime-secrets.js

@@ -0,0 +1,108 @@
+/**
+ * What the AgentCore container does with its deployment's values: read the Secrets Manager secret `FASTAGENT_SECRET_ARN`
+ * names and put each name it holds into the environment (agent-artifact.md §6.2).
+ *
+ * The runtime has no way to reference a secret from an environment variable, so the container reads it itself, on its
+ * first invocation. Its credentials are the execution role's, from the microVM's instance-metadata service (IMDSv2); the
+ * request is SigV4-signed with the signer `shell.ts` already uses, so no AWS SDK is installed in the image.
+ */
+import { SignatureV4 } from "@smithy/signature-v4";
+import { SECRET_ARN_ENV } from "./plan.js";
+import { Sha256 } from "./sigv4.js";
+const IMDS = "http://169.254.169.254/latest";
+const TIMEOUT_MS = 5_000;
+async function imdsText(url, init) {
+    const response = await fetch(url, { ...init, signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!response.ok)
+        throw new Error(`${init.method ?? "GET"} ${url} answered ${response.status}`);
+    return response.text();
+}
+/** The execution role's credentials, as the metadata service hands them to the microVM. */
+async function roleCredentials() {
+    const token = await imdsText(`${IMDS}/api/token`, {
+        method: "PUT",
+        headers: { "x-aws-ec2-metadata-token-ttl-seconds": "60" },
+    });
+    const headers = { "x-aws-ec2-metadata-token": token };
+    const role = (await imdsText(`${IMDS}/meta-data/iam/security-credentials/`, { headers })).trim();
+    const parsed = JSON.parse(await imdsText(`${IMDS}/meta-data/iam/security-credentials/${role}`, { headers }));
+    const { AccessKeyId, SecretAccessKey, Token } = (parsed ?? {});
+    if (typeof AccessKeyId !== "string" || typeof SecretAccessKey !== "string" || typeof Token !== "string") {
+        throw new Error(`the metadata service's credentials for ${role} are not an access key, a secret and a token`);
+    }
+    return { accessKeyId: AccessKeyId, secretAccessKey: SecretAccessKey, sessionToken: Token };
+}
+/** `arn:<partition>:secretsmanager:<region>:<account>:secret:<name>-<suffix>` → its region. */
+function regionOf(secretArn) {
+    const [, , service, region] = secretArn.split(":");
+    if (service !== "secretsmanager" || !region)
+        throw new Error(`${SECRET_ARN_ENV} is not a Secrets Manager ARN`);
+    return region;
+}
+/** The secret's JSON object, every value a string. */
+export async function readSecretValues(secretArn) {
+    const region = regionOf(secretArn);
+    const hostname = `secretsmanager.${region}.amazonaws.com`;
+    const body = JSON.stringify({ SecretId: secretArn });
+    const signed = await new SignatureV4({
+        service: "secretsmanager",
+        region,
+        credentials: await roleCredentials(),
+        sha256: Sha256,
+    }).sign({
+        method: "POST",
+        protocol: "https:",
+        hostname,
+        path: "/",
+        body,
+        headers: {
+            host: hostname,
+            "content-type": "application/x-amz-json-1.1",
+            "x-amz-target": "secretsmanager.GetSecretValue",
+        },
+    });
+    const response = await fetch(`https://${hostname}/`, {
+        method: "POST",
+        headers: signed.headers,
+        body,
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    const answer = await response.text();
+    // Never the parser's message: it quotes the text around the error, and this document holds every value.
+    if (!response.ok)
+        throw new Error(`GetSecretValue answered ${response.status}: ${answer.slice(0, 200)}`);
+    let values;
+    try {
+        values = JSON.parse(JSON.parse(answer).SecretString ?? "");
+    }
+    catch {
+        throw new Error(`the secret ${secretArn} is not a JSON object of values`);
+    }
+    if (values === null || typeof values !== "object" || Array.isArray(values)) {
+        throw new Error(`the secret ${secretArn} is not a JSON object of values`);
+    }
+    for (const [name, value] of Object.entries(values)) {
+        if (typeof value !== "string")
+            throw new Error(`the secret ${secretArn}: ${name} is not a string`);
+    }
+    return values;
+}
+/**
+ * Put the secret's values into `env`, unless the platform set the name itself (the platform's variables win, as they do
+ * over a value file anywhere). Without `FASTAGENT_SECRET_ARN` there is nothing to read.
+ */
+export async function applyRuntimeSecrets(env = process.env) {
+    const arn = env[SECRET_ARN_ENV];
+    if (!arn)
+        return;
+    let values;
+    try {
+        values = await readSecretValues(arn);
+    }
+    catch (error) {
+        throw new Error(`could not read the deployment's values from ${arn}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const [name, value] of Object.entries(values))
+        if (!(name in env))
+            env[name] = value;
+}