@fastagent-sh/fastagent 0.22.0 → 0.23.0

package/dist/deploy/agentcore/plan.js

@@ -5,7 +5,7 @@ import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
 import { SECRETS_DIRNAME } from "../../paths.js";
 import { webhookKinds, webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
-import { isEnvKey } from "../secrets.js";
+import { deploymentLoginCommand } from "../box-shell.js";
 function agentcoreTopology(input) {
     return { webhooks: input.channels.some((channel) => channel.ingress === "webhook") };
 }
@@ -33,15 +33,13 @@ export function deploymentBucketName(name, account) {
     return `fa-${name}-${account}`;
 }
 /**
- * AgentCore env values max 2048 chars — a real OAuth auth.json's base64 exceeds it, so each carrier is CHUNKED across
- * `<NAME>` + `_2`… (collectChunked reassembles at boot): FASTAGENT_AUTH_SEED for the credential, FASTAGENT_ENV for the
- * value file's variables.
+ * 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 two chunked carriers: CloudFormation parameter prefix → container env-var name. */
+/** The template's chunked carrier: CloudFormation parameter prefix → container env-var name. */
 export const CARRIERS = [
-    { param: "FastagentAuthSeed", env: "FASTAGENT_AUTH_SEED", what: "base64 auth.json" },
     { 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. */
@@ -216,7 +214,7 @@ function template(input, translated, topology) {
         `        FASTAGENT_STATE_DIR: ${MOUNT}/.state`,
         `        FASTAGENT_SECRETS_DIR: ${SECRETS_DIR}`,
     ];
-    // Both carriers are chunked (env values max 2048 chars — see CARRIER_CHUNK_SIZE): N parameters, each riding its
+    // 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) {
@@ -381,12 +379,8 @@ export function planAgentcoreDeploy(input) {
     const wakeSecretHint = " FastagentWakeSecret=<any random string>";
     runbook.push(`#      FastagentWakeSecret: the wake-alarm shared secret — any random string (\`--run\` mints one)`);
     runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${prefix}${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`);
-    // Model-auth guidance mirrors the other hosts: an env key became a parameter above; OAuth/stored can't be read at
-    // plan time — `--run` carries it as FastagentAuthSeed.
-    if (!isEnvKey(input.modelAuth)) {
-        runbook.push(``, input.modelAuth === undefined
-            ? `# Model auth: none found at the local auth path — set FASTAGENT_AUTH_PATH, or \`--run\` carries it`
-            : `# Model auth: your local auth is "${input.modelAuth}" — the plan can't read its value; \`--run\` carries it`, `#   as the FastagentAuthSeed parameter (base64 of auth.json), materialized on first boot.`);
+    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 this workspace — before pointing any webhook at it:`, `${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).
@@ -403,6 +397,6 @@ export function planAgentcoreDeploy(input) {
     }
     runbook.push(``, `# Wake-ups: the agent's own follow-up turns (the wake tool) are EventBridge-backed — each pending wake-up is mirrored`, `#   (via the forwarder, authenticated by FastagentWakeSecret) into a self-deleting one-shot`, `#   schedule (fa-${name}-wk-*) that wakes the container at the right instant. Reliable even when`, `#   the compute is reclaimed. The forwarder supplies the callback URL; use the deployment's`, `#   fixed runtime session id for programmatic calls too.`);
     runbook.push(``, `# Invoke the agent programmatically (reuse the deployment session; conversations remain separate):`, `aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}" \\`, `  --payload '{"kind":"invoke","session":"cli","text":"hello"}' --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 base/ (including unfinished work), .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,`, `# and the model credential is re-seeded from FASTAGENT_AUTH_SEED. Deploying IS re-authenticating.`, `# An OAuth refresh token is single-use and shared with your machine, so the box can lose model`, `# access between deploys — deploy again to refresh it, or use a provider API key.`, `# 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 workspace; 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. It keeps base/ (including unfinished work), .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 workspace; use the fixed runtime session id printed above for every entry point.`);
     return { artifacts, runbook, untranslatableSchedules: untranslatable, topology };
 }

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

@@ -1,3 +1,5 @@
+/** `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 { CliRunner } from "../runner.ts";
@@ -16,7 +18,7 @@ export interface AgentcoreRunPlan {
      * region`.
      */
     region?: string;
-    /** Env-var name → value: the value file's carried variables, plus FASTAGENT_AUTH_SEED for a file credential. */
+    /** 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[];
@@ -29,6 +31,11 @@ export interface AgentcoreRunPlan {
      * forwarder (and its artifact bucket parameters) exists.
      */
     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.
+     */
+    boxLogin?: BoxLoginStep<[runtimeArn: string]>;
 }
 export type AgentcoreRunOutcome = {
     ok: true;

package/dist/deploy/agentcore/run.js

@@ -1,6 +1,5 @@
-/** `fastagent deploy agentcore --run` — drive the AWS CLI + Docker to completion. */
 import { RESERVED_PATHS } from "../../channels/agentcore-protocol.js";
-import { registerWebhooks } from "../channel-ingress.js";
+import { loginGate, registerWebhooks } from "../channel-ingress.js";
 import { awsCli, awsJson } from "./aws-cli.js";
 import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
@@ -97,11 +96,10 @@ const MINTED_PARAMS = {
     FASTAGENT_INGRESS_SECRET: "FastagentIngressSecret",
     FASTAGENT_WAKE_SECRET: "FastagentWakeSecret",
 };
-/** What each carrier holds for this deploy: the credential seed, and every other variable as one encoded object. */
+/** What each carrier holds for this deploy: every variable but the minted ones, as one encoded object. */
 function carrierValues(secrets) {
-    const { FASTAGENT_AUTH_SEED: seed = "", ...rest } = secrets;
-    const carried = Object.fromEntries(Object.entries(rest).filter(([name]) => !(name in MINTED_PARAMS)));
-    return { FASTAGENT_AUTH_SEED: seed, FASTAGENT_ENV: encodeCarriedEnv(carried) };
+    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) {
@@ -170,10 +168,6 @@ probe = {}) {
     // 3b.
     const capacity = CARRIER_CHUNK_SIZE * CARRIER_MAX_CHUNKS;
     const carried = carrierValues(plan.secrets);
-    if (carried.FASTAGENT_AUTH_SEED.length > capacity) {
-        return gate(`your auth.json is too large to carry (${carried.FASTAGENT_AUTH_SEED.length} chars base64 > ${capacity}) — ` +
-            `slim it (keep only the model's credential), or set a provider API key in .env instead`);
-    }
     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`);
@@ -224,6 +218,8 @@ probe = {}) {
     ], (stdout) => stdout.trim() || undefined);
     const stackStatus = await readStackStatus();
     const status = "ok" in stackStatus ? stackStatus.ok : "";
+    // A stack that held state: an earlier deploy served from it, and may have registered webhooks at its forwarder.
+    const redeploy = status !== "" && !EMPTY_STACK_STATUSES.has(status);
     // The only answers the build can invalidate: one still in flight (a first create rolling back is exactly what step 7
     // exists for, and minutes of arm64 build are long enough for it to settle), and one we never got.
     const settling = status.endsWith("_IN_PROGRESS") || "unreadable" in stackStatus;
@@ -233,11 +229,9 @@ probe = {}) {
         log(`warn: could not read stack ${stack} (${stackStatus.unreadable}) — if it exists, this deploy resets its ` +
             `managed SessionStorage (${MOUNT}) and a failed first create will not be cleared`);
     }
-    else if (status !== "" && !EMPTY_STACK_STATUSES.has(status)) {
+    else if (redeploy) {
         log(`warn: this is a REDEPLOY and AWS resets managed SessionStorage (${MOUNT}) on every runtime version update — ` +
-            `sessions, channel state and pending wake-ups start blank` +
-            // Only the carried auth.json is re-seeded; a provider API key deployment has no such step to blame.
-            `${carried.FASTAGENT_AUTH_SEED ? ", and the model credential is re-seeded from FASTAGENT_AUTH_SEED" : ""}. ` +
+            `sessions, channel state and pending wake-ups start blank. ` +
             `Cross-deploy memory needs a real volume: \`deploy fly\` or \`deploy railway\`.`);
     }
     // 4.
@@ -394,6 +388,18 @@ probe = {}) {
             return gate(verdict.gate);
         log("runtime verified (workspace ready, channels constructed)");
     }
+    const notLoggedIn = await plan.boxLogin?.run(runtimeArn);
+    if (notLoggedIn) {
+        return gate(loginGate({
+            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)" }),
+        }));
+    }
     // 9.
     const registrationGateMsg = url
         ? await registerWebhooks({

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

@@ -0,0 +1,25 @@
+import type { BoxChannel, BoxShell } from "../box-shell.ts";
+import type { CliRunner } from "../runner.ts";
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/** A presigned `wss://` URL for one shell on one runtime session: the SDK's `connectShellPresigned`. */
+export declare function presignShellUrl(input: {
+    runtimeArn: string;
+    sessionId: string;
+    shellId: string;
+    credentials: AwsCredentials;
+    now?: Date;
+}): Promise<string>;
+/** What a status frame says: `undefined` for the connection confirmation, else how the shell exited. */
+export declare function shellExit(status: string): string | undefined;
+/** Open `command` in a new shell on `url`: stdin/stdout as streams, the other channels folded in. */
+export declare function openShellChannel(url: string, command: string): BoxChannel;
+/**
+ * The shell `login --deployment` opens on an AgentCore runtime, on the session its server runs in. `wake` first sends
+ * that session an IAM `probe`: the runtime prepares its workspace only on an invocation, and after a deploy or an idle
+ * reset nothing may have invoked it yet, which would leave the login no agent directory to run in.
+ */
+export declare function agentcoreShell(runtimeArn: string, sessionId: string, aws: CliRunner): BoxShell;

package/dist/deploy/agentcore/shell.js

@@ -0,0 +1,202 @@
+/**
+ * A shell into the AgentCore runtime, for `fastagent login --deployment agentcore`: `InvokeAgentRuntimeCommandShell`,
+ * a WebSocket to an interactive shell inside the running session. Opened on the fixed ingress session, so the shell
+ * sees the same `/mnt/data` the server does.
+ *
+ * Authenticated with the same AWS credentials `deploy agentcore` uses, read from the AWS CLI
+ * (`aws configure export-credentials`), so profiles, SSO and `aws login` all work with nothing else installed. The
+ * URL is presigned (SigV4 in the query string, the SDK's `connectShellPresigned`), which needs no custom upgrade
+ * header.
+ *
+ * The wire (the TypeScript SDK's `shell/protocol.ts`, the Kubernetes v5 channel protocol): every binary frame is one
+ * channel byte then payload — 0 stdin, 1 stdout, 2 stderr, 3 status JSON, 5 heartbeat, 0xFF close. The shell is a
+ * 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 { 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 { awsCli, awsJson } from "./aws-cli.js";
+import { MOUNT } from "./plan.js";
+const STDIN = 0x00;
+const STDOUT = 0x01;
+const STDERR = 0x02;
+const STATUS = 0x03;
+const HEARTBEAT = 0x05;
+/** The service closes a connection whose frame is larger (code 1009). */
+const MAX_PAYLOAD = 64 * 1024 - 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). */
+const PRESIGN_SECONDS = 300;
+/** The AWS CLI's own credentials, the same ones every `deploy agentcore` call runs with. */
+async function awsCliCredentials(aws) {
+    const read = await awsCli(aws).read(["configure", "export-credentials", "--format", "process"], awsJson((parsed) => {
+        const p = parsed;
+        if (typeof p?.AccessKeyId !== "string" || typeof p.SecretAccessKey !== "string")
+            return undefined;
+        return {
+            accessKeyId: p.AccessKeyId,
+            secretAccessKey: p.SecretAccessKey,
+            ...(typeof p.SessionToken === "string" ? { sessionToken: p.SessionToken } : {}),
+        };
+    }));
+    if ("ok" in read)
+        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];
+    if (!region)
+        throw new Error(`not an AgentCore runtime ARN: ${runtimeArn}`);
+    return region;
+}
+/** A presigned `wss://` URL for one shell on one runtime session: the SDK's `connectShellPresigned`. */
+export async function presignShellUrl(input) {
+    const region = regionOf(input.runtimeArn);
+    const hostname = `bedrock-agentcore.${region}.amazonaws.com${region.startsWith("cn-") ? ".cn" : ""}`;
+    const url = new URL(`https://${hostname}/runtimes/${encodeURIComponent(input.runtimeArn)}/ws/shells`);
+    url.searchParams.set("shellId", input.shellId);
+    url.searchParams.set("X-Amzn-Bedrock-AgentCore-Runtime-Session-Id", input.sessionId);
+    const signed = await new SignatureV4({
+        credentials: input.credentials,
+        region,
+        service: "bedrock-agentcore",
+        sha256: Sha256,
+    }).presign({
+        method: "GET",
+        protocol: "https:",
+        hostname,
+        path: url.pathname,
+        query: Object.fromEntries(url.searchParams),
+        headers: { host: hostname },
+    }, { expiresIn: PRESIGN_SECONDS, ...(input.now ? { signingDate: input.now } : {}) });
+    const query = Object.entries(signed.query ?? {})
+        .map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`)
+        .join("&");
+    return `wss://${hostname}${signed.path}?${query}`;
+}
+/** What a status frame says: `undefined` for the connection confirmation, else how the shell exited. */
+export function shellExit(status) {
+    const s = JSON.parse(status);
+    if (s.metadata?.shellId)
+        return undefined;
+    return s.status === "Success" ? "exit 0" : `exit ${s.details?.causes?.[0]?.message ?? "(unknown)"}`;
+}
+/** 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);
+    ws.binaryType = "arraybuffer";
+    const frame = (channel, payload = Buffer.alloc(0)) => ws.send(Buffer.concat([Buffer.from([channel]), payload]));
+    const stdin = (bytes) => {
+        for (let at = 0; at < bytes.length; at += MAX_PAYLOAD)
+            frame(STDIN, bytes.subarray(at, at + MAX_PAYLOAD));
+    };
+    let exit;
+    let failure;
+    let keepalive;
+    const opened = new Promise((resolve) => {
+        ws.addEventListener("open", () => resolve(true), { once: true });
+        ws.addEventListener("close", () => resolve(false), { once: true });
+    });
+    ws.addEventListener("open", () => {
+        stdin(Buffer.from(`stty raw -echo 2>/dev/null; exec sh -c '${command}'\n`));
+        keepalive = setInterval(() => {
+            ping(ws);
+            frame(HEARTBEAT);
+        }, KEEPALIVE_MS);
+    });
+    ws.addEventListener("message", (event) => {
+        const data = Buffer.from(event.data);
+        const payload = data.subarray(1);
+        if (data[0] === STDOUT)
+            output.write(payload);
+        else if (data[0] === STDERR)
+            process.stderr.write(payload);
+        else if (data[0] === STATUS)
+            exit = shellExit(payload.toString("utf8")) ?? exit;
+    });
+    ws.addEventListener("error", (event) => {
+        failure = event.message || "connection failed";
+    });
+    const closed = new Promise((resolve) => {
+        ws.addEventListener("close", async (event) => {
+            clearInterval(keepalive);
+            output.end();
+            if (!(await opened)) {
+                resolve({
+                    opened: false,
+                    error: `could not open a shell on the AgentCore runtime (${failure ?? `closed ${event.code}`}) — it needs ` +
+                        `bedrock-agentcore:InvokeAgentRuntimeCommandShell, and a runtime created or redeployed after 2026-06-05`,
+                });
+                return;
+            }
+            resolve({ opened: true, how: exit ?? `WebSocket closed ${event.code}${event.reason ? ` ${event.reason}` : ""}` });
+        });
+    });
+    const input = new Writable({
+        write(chunk, _encoding, done) {
+            void opened.then((open) => {
+                if (open && ws.readyState === WebSocket.OPEN)
+                    stdin(chunk);
+                done();
+            });
+        },
+    });
+    return { output, input, closed };
+}
+/**
+ * The shell `login --deployment` opens on an AgentCore runtime, on the session its server runs in. `wake` first sends
+ * that session an IAM `probe`: the runtime prepares its workspace only on an invocation, and after a deploy or an idle
+ * reset nothing may have invoked it yet, which would leave the login no agent directory to run in.
+ */
+export function agentcoreShell(runtimeArn, sessionId, aws) {
+    return {
+        storage: MOUNT,
+        async wake() {
+            const dir = await mkdtemp(join(tmpdir(), "fastagent-agentcore-wake-"));
+            try {
+                const reply = join(dir, "reply.json");
+                const args = ["bedrock-agentcore", "invoke-agent-runtime", "--agent-runtime-arn", runtimeArn];
+                args.push("--runtime-session-id", sessionId, "--payload", '{"kind":"probe"}');
+                args.push("--cli-binary-format", "raw-in-base64-out", reply);
+                const sent = await awsCli(aws).present(args);
+                if (!("ok" in sent)) {
+                    const why = "absent" in sent ? "the runtime is not there" : sent.unreadable;
+                    throw new Error(`could not open the AgentCore runtime's workspace (${why})`);
+                }
+                const answer = await readFile(reply, "utf8");
+                if (!/"ok"\s*:\s*true/.test(answer)) {
+                    throw new Error(`the AgentCore runtime did not open its workspace: ${answer.trim().slice(0, 300)}`);
+                }
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+        },
+        async open(command) {
+            const credentials = await awsCliCredentials(aws);
+            return openShellChannel(await presignShellUrl({ runtimeArn, sessionId, shellId: randomUUID(), credentials }), command);
+        },
+    };
+}

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

@@ -0,0 +1,43 @@
+import type { Readable, Writable } from "node:stream";
+/** One open session on the box, running one command. */
+export interface BoxChannel {
+    /** What the command writes to its stdout. Ends when the session does. */
+    output: Readable;
+    /** The command's stdin. */
+    input: Writable;
+    /** How the session ended, or why it never opened. */
+    closed: Promise<{
+        opened: true;
+        how: string;
+    } | {
+        opened: false;
+        error: string;
+    }>;
+}
+export interface BoxShell {
+    /** Run `command` (one POSIX shell line) on the box. Its stderr goes to this process's stderr. */
+    open(command: string): Promise<BoxChannel>;
+    /** Make sure there is a running machine to open the shell on (a host that suspends idle machines). */
+    wake?(): Promise<void>;
+    /**
+     * The box's storage root, for a shell that does not carry the server's environment (AgentCore's). Unset: the
+     * shell sees `FASTAGENT_STORAGE_DIR` as the server does, or the image's default.
+     */
+    storage?: string;
+}
+/** A host CLI that runs a command on the box itself: `bin ...args(command)`, run from `cwd`. */
+export declare function processShell(bin: string, args: (command: string) => string[], cwd: string): BoxShell;
+/**
+ * The command that logs a deployment in, as every message and runbook names it: with the provider when it is known,
+ * because the model needs THAT one, and a menu invites another.
+ */
+export declare function deploymentLoginCommand(host: string, provider?: string): string;
+/**
+ * The login a host driver runs on the box it just deployed, before any webhook points at it. `run` resolves a gate line,
+ * or undefined once the box authenticates; `command` is how a person runs the same login, for the manual route.
+ * ONE value, so a driver cannot have the step without its command.
+ */
+export interface BoxLoginStep<Args extends unknown[] = []> {
+    command: string;
+    run: (...args: Args) => Promise<string | undefined>;
+}

package/dist/deploy/box-shell.js

@@ -0,0 +1,28 @@
+/**
+ * A running box's owner-authenticated shell, as a byte channel: what `fastagent login --deployment` speaks through.
+ * Host-neutral: Docker, Fly and Railway open it by running their own CLI (`processShell`); AgentCore opens a
+ * WebSocket (`agentcore/shell.ts`). Whoever opens one only writes bytes in and reads bytes out.
+ */
+import { spawn } from "node:child_process";
+/** A host CLI that runs a command on the box itself: `bin ...args(command)`, run from `cwd`. */
+export function processShell(bin, args, cwd) {
+    return {
+        async open(command) {
+            const child = spawn(bin, args(command), { cwd, stdio: ["pipe", "pipe", "inherit"] });
+            // The box may exit before reading an answer; its result (or its absence) is what gets reported, not the EPIPE.
+            child.stdin.on("error", () => { });
+            const closed = new Promise((resolve) => {
+                child.on("error", (error) => resolve({ opened: false, error: `could not run ${bin}: ${error.message}` }));
+                child.on("close", (code, signal) => resolve({ opened: true, how: signal ? `signal ${signal}` : `exit ${code}` }));
+            });
+            return { output: child.stdout, input: child.stdin, closed };
+        },
+    };
+}
+/**
+ * The command that logs a deployment in, as every message and runbook names it: with the provider when it is known,
+ * because the model needs THAT one, and a menu invites another.
+ */
+export function deploymentLoginCommand(host, provider) {
+    return `fastagent login ${provider ? `${provider} ` : ""}--deployment ${host}`;
+}

package/dist/deploy/build-context.js

@@ -1,8 +1,3 @@
-/**
- * What a deploy's BUILD CONTEXT (the workspace) holds that must not ship, and whether an ignore file the author kept
- * still keeps it out. A kept workspace-root `.dockerignore` silently replaces the generated one's protections, so the
- * pre-flight asks it the same questions the generated one answers by construction.
- */
 import { readdir } from "node:fs/promises";
 import { basename, isAbsolute, join, relative, sep } from "node:path";
 import ignore from "ignore";
@@ -29,6 +24,20 @@ function dockerignoreMatcher(text) {
     const matcher = ignore({ ignorecase: false }).add(anchored);
     return (path) => matcher.ignores(path);
 }
+/**
+ * A directory's entries, or none when it does not exist. Any other failure throws: the leak scan would otherwise pass
+ * on a directory it never read, and a credential inside it would ship without a word.
+ */
+async function entriesIfExists(path) {
+    try {
+        return await readdir(path, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw new Error(`cannot read ${path} to check what the image would ship: ${error.message}`);
+    }
+}
 export async function buildContextPaths(workspace, agentDir, agentPrefix, authPath) {
     const inContext = (p) => {
         const rel = relative(workspace, p);
@@ -55,7 +64,7 @@ export async function buildContextPaths(workspace, agentDir, agentPrefix, authPa
     const stateShips = stateRel !== undefined && (await exists(join(workspace, stateRel))) ? stateRel : undefined;
     // The `.env` family at the two levels fastagent is RESPONSIBLE for: the agent dir and the workspace root.
     const dotEnvFiles = async (relDir) => {
-        const names = await readdir(join(workspace, relDir || ".")).catch(() => []);
+        const names = (await entriesIfExists(join(workspace, relDir || "."))).map((entry) => entry.name);
         // POSIX separators, like every other context-relative path here (`inContext`).
         return names
             .filter((n) => (n === ".env" || n.startsWith(".env.")) && n !== ".env.example")
@@ -65,7 +74,7 @@ export async function buildContextPaths(workspace, agentDir, agentPrefix, authPa
     // Everything ACTUALLY inside the secrets dir, minus the two tracked scaffolds the image ships on purpose (they
     // carry no values; the generated ignore re-includes them by name).
     const secretDirFiles = async (dirRel) => {
-        const entries = await readdir(join(workspace, dirRel), { withFileTypes: true }).catch(() => []);
+        const entries = await entriesIfExists(join(workspace, dirRel));
         const files = [];
         for (const entry of entries) {
             if (entry.name === ".gitignore" || entry.name === ".env.example")

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

@@ -37,7 +37,8 @@ export type PublicHealthProbe = (healthUrl: string) => Promise<boolean>;
  * report success. The channels that DO verify (Slack/Feishu challenge) would fail here too, but as "registration
  * failed" — a diagnosis that hides the actual cause.
  *
- * Asked ONLY when this deployment actually has a webhook to point. A definition with none (schedules only, the
+ * Asked ONLY when this deployment actually has a webhook to point, or a login on the box follows (the box must
+ * have prepared its workspace and installed the CLI the login runs). A definition with neither (schedules only, the
  * built-in `POST /invoke`, or long-connection channels) needs no inbound reachability at all, and demanding it would
  * invent a failure for a deploy run from a network that cannot reach the platform's edge.
  */
@@ -48,7 +49,25 @@ export declare function publicHealthGate(input: {
     /** How THIS host is inspected and re-run — the only per-host words in the gate. */
     inspectHint: string;
     probe?: PublicHealthProbe;
+    /** The login that follows on the box (`fastagent login --deployment <host>`), when one does. */
+    login?: string;
 }): Promise<string | undefined>;
+/**
+ * The gate when the login on the box did not happen. It stops the run BEFORE registration (a channel pointed at a box
+ * with no model credential fails every message), so the login it asks for does not register anything by itself: with
+ * a webhook to point, the refusal says what comes after the login, and prints the lines to do it by hand when the
+ * URL is known.
+ */
+export declare function loginGate(input: {
+    /** What the login reported, ending with the command to run. */
+    notLoggedIn: string;
+    channels: readonly DeclaredChannel[];
+    log: (msg: string) => void;
+    /** What THIS host does about its webhooks once the box is logged in — the only per-host words in the gate. */
+    afterLogin: string;
+    /** Where the channels point; unset when the host has not minted it yet (Docker's tunnel is read after). */
+    baseUrl?: string;
+}): string;
 /** {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS. */
 export declare function registerWebhooks(input: {
     baseUrl: string;

package/dist/deploy/channel-ingress.js

@@ -85,24 +85,51 @@ const WAIT_NOTICE_MS = 15_000;
  * report success. The channels that DO verify (Slack/Feishu challenge) would fail here too, but as "registration
  * failed" — a diagnosis that hides the actual cause.
  *
- * Asked ONLY when this deployment actually has a webhook to point. A definition with none (schedules only, the
+ * Asked ONLY when this deployment actually has a webhook to point, or a login on the box follows (the box must
+ * have prepared its workspace and installed the CLI the login runs). A definition with neither (schedules only, the
  * built-in `POST /invoke`, or long-connection channels) needs no inbound reachability at all, and demanding it would
  * invent a failure for a deploy run from a network that cannot reach the platform's edge.
  */
 export async function publicHealthGate(input) {
-    if (webhookKinds(input.channels).length === 0)
+    if (webhookKinds(input.channels).length === 0 && input.login === undefined)
         return undefined;
     const healthUrl = `${input.baseUrl}/health`;
     input.log(`waiting for ${healthUrl} (up to ${PUBLIC_HEALTH_TIMEOUT_MS / 1000}s)…`);
     const probe = input.probe ?? ((url) => waitForHealth(url, PUBLIC_HEALTH_TIMEOUT_MS, 500, announce(input.log)));
     if (await probe(healthUrl))
         return undefined;
-    // The infrastructure is up and only the webhook is missing, so hand over the manual route rather than leaving
-    // `re-run` as the only way out (a Fly re-run repeats the remote build).
-    for (const line of webhookRunbook(input.baseUrl, input.channels))
+    // The infrastructure is up and only activation is missing, so hand over the manual route rather than leaving
+    // `re-run` as the only way out (a Fly re-run repeats the remote build). The login comes first: a channel pointed at
+    // a box with no model credential fails every message.
+    const steps = [
+        ...(input.login !== undefined ? [`# First, log the box in: ${input.login}`] : []),
+        ...webhookRunbook(input.baseUrl, input.channels),
+    ];
+    for (const line of steps)
+        input.log(line);
+    const byHand = webhookKinds(input.channels).length > 0
+        ? `To finish by hand once it answers, use the lines above.`
+        : `Once it answers, log it in: ${input.login}.`;
+    return (`the deployed agent did not become healthy at ${healthUrl}, so it was not activated — ${input.inspectHint}. ` +
+        byHand);
+}
+/**
+ * The gate when the login on the box did not happen. It stops the run BEFORE registration (a channel pointed at a box
+ * with no model credential fails every message), so the login it asks for does not register anything by itself: with
+ * a webhook to point, the refusal says what comes after the login, and prints the lines to do it by hand when the
+ * URL is known.
+ */
+export function loginGate(input) {
+    if (webhookKinds(input.channels).length === 0)
+        return input.notLoggedIn;
+    const byHand = input.baseUrl === undefined ? [] : webhookRunbook(input.baseUrl, input.channels);
+    for (const line of byHand)
         input.log(line);
-    return (`the deployed agent did not become healthy at ${healthUrl}, so no webhook was registered — ${input.inspectHint}. ` +
-        `To point the channels by hand instead, use the lines above.`);
+    // "No webhook was registered" would be about THIS run only: one an earlier deploy registered still points here.
+    return (`${input.notLoggedIn}. This deploy registered no webhook, and logging in registers none; any an earlier deploy ` +
+        `registered still points here, and every message it brings fails until the box is logged in. Once it is, ` +
+        `${input.afterLogin}` +
+        (byHand.length > 0 ? `. The lines above point the channels by hand.` : ``));
 }
 /**
  * Keep the wait visible. This occupies `waitForHealth`'s liveness slot without answering it: neither Fly nor Railway

package/dist/deploy/container.d.ts

@@ -2,6 +2,20 @@ export interface Artifact {
     path: string;
     content: string;
 }
+/**
+ * The shell command that runs `fastagent login --stdio <args>` inside a running generated image, as the server there
+ * would see it: in the deployed agent directory, with the storage and credential paths resolved by the same defaults
+ * `prepareStartWorkspace` applies. A host's own shell does not reliably hand those over — its session may not start
+ * in the server's directory, and the platform's variables are the only ones it inherits. `storage` names the root
+ * outright for a shell that inherits none of them. The CLI is the one the server runs: the agent's own install when
+ * it has one (under Bun when the image is Bun's), else the pinned global.
+ *
+ * That own install may predate `login --stdio` (an agent pinned to an older release, deployed by a newer CLI). It then
+ * refuses the flag as a usage error, exit 2, which a `login --stdio` that ran never gives (it answers 0 or 1 after its
+ * result line), so the command answers for it: one result line naming the mismatch, instead of a shell that ended
+ * with nothing to say. No quote or backtick in it: hosts wrap this whole line in `sh -c '…'`.
+ */
+export declare function boxLoginCommand(agent: string, args: readonly string[], storage?: string): string;
 /** Fixed first-line prefix of a fastagent-generated Dockerfile. */
 export declare const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
 /** The ONE predicate for "did fastagent generate this Dockerfile?". */