@fastagent-sh/fastagent 0.29.0 → 0.30.0

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

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;