@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/cli/shared.js

@@ -6,14 +6,15 @@ import { readFile, writeFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
-import { fastagentCredentialStore } from "../engines/pi/auth.js";
-import { isValidPort, listModels, loadConfig, providerOf, resolveAuthLayers, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
+import { isValidPort, listModels, loadConfig, providerOf, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
 import { readMachine, withMachine } from "../engines/pi/machine.js";
-import { createPiModelRuntime, probeAuthSource, providerAuthStatuses } from "../engines/pi/models.js";
+import { providerAuthStatuses } from "../engines/pi/models.js";
+import { agentModels } from "../engines/pi/agent-models.js";
 import { formatAuthReport } from "./auth-view.js";
 import { CODING_TOOL_NAMES } from "../engines/pi/create.js";
-import { reportFindingsIfChanged, reportToolCollisions } from "../engines/pi/report.js";
+import { describeIndirectTools, reportFindingsIfChanged, reportToolCollisions } from "../engines/pi/report.js";
+import { isDeployedWorkspace } from "../paths.js";
 import { log } from "../log.js";
 import { enterAgentEnv } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
@@ -23,7 +24,7 @@ import { failStartup, failUsage, placementOrExit } from "./fail.js";
 export async function enterAgentCommand(dirArg, opts) {
     const placement = placementOrExit(resolve(dirArg));
     enterAgentEnv(placement.agentDir);
-    await resolveFirstRunModel(placement.agentDir, opts);
+    await resolveFirstRunModel(placement, opts);
     return placement;
 }
 /** The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). */
@@ -37,7 +38,7 @@ export async function reportAssembly(a, extras = {}) {
     for (const [label, value] of extras.beforeModel ?? [])
         reportLine(label, value);
     reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
-    await reportAuth(a.agentDir, a.modelSpec, a.auth);
+    await reportAuth(a.models, a.modelSpec);
     reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
     if (a.definition.persona)
         reportLine("persona", "persona.md");
@@ -47,9 +48,8 @@ export async function reportAssembly(a, extras = {}) {
     reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
     if (a.toolNames.length > 0)
         reportLine("tools", a.toolNames.join(", "));
-    if (a.deferredToolNames.length > 0) {
-        reportLine("deferred", `${a.deferredToolNames.join(", ")} (activated via search_tools)`);
-    }
+    if (a.indirectTools.length > 0)
+        reportLine("indirect", describeIndirectTools(a.indirectTools));
     reportToolCollisions(a.toolCollisions);
     for (const [label, value] of extras.afterTools ?? [])
         reportLine(label, value);
@@ -87,26 +87,18 @@ export function parseBind(value) {
     return bindAddress(trimmed); // a name never travels past this point — see bind.ts
 }
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. */
-export async function reportAuth(agentDir, modelSpec, auth) {
+export async function reportAuth(models, modelSpec) {
     const provider = providerOf(modelSpec);
-    const { path: authPath, fallback: fallbackAuthPath } = auth;
-    const models = await createPiModelRuntime({ agentDir, auth }).catch(failStartup);
-    const source = await probeAuthSource(models, modelSpec);
-    // One refresh-FREE read per layer, serving both questions below. A read failure is already warned about by the
-    // store itself; this line degrades to "nothing stored" rather than taking down the startup report.
-    const readFrom = (path) => fastagentCredentialStore(path)
-        .read(provider)
-        .catch(() => undefined);
-    const inPrimary = await readFrom(authPath);
-    const inFallback = inPrimary || fallbackAuthPath === undefined ? undefined : await readFrom(fallbackAuthPath);
-    // Name the layer the credential actually came from: "which file do I edit" is the question this line answers, and
-    // a global credential lives in a file the agent dir does not contain. With NEITHER layer holding it, the answer is
-    // the primary — that is the file the `fastagent login` this report recommends writes.
-    const found = fallbackAuthPath !== undefined && inFallback ? fallbackAuthPath : authPath;
-    // Only when nothing satisfies auth does the stored credential matter: it tells "nothing stored" from "stored but
-    // unusable".
-    const stored = source === undefined ? (inPrimary ?? inFallback) : undefined;
-    const report = formatAuthReport(provider, found, source, stored);
+    // No files: the opener was handed a credential store, which is its caller's to describe.
+    if (models.auth === undefined) {
+        log.info(`[fastagent] auth:   the caller's credential store (${provider})`);
+        return;
+    }
+    // The agent's own model environment, the one its turns run on and a deployed box's `login --if-missing` asks: the
+    // line cannot name a file, or a source, other than the ones the runtime uses.
+    const modelId = modelSpec.slice(provider.length + 1);
+    const status = await models.authStatus(provider, modelId).catch(failStartup);
+    const report = formatAuthReport({ provider, path: models.auth.path, ...status, deployed: isDeployedWorkspace() });
     log.info(`[fastagent] ${report.line}`);
     if (report.warn)
         log.warn(`[fastagent] ${report.warn}`);
@@ -114,7 +106,7 @@ export async function reportAuth(agentDir, modelSpec, auth) {
 /**
  * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE funnel, no dead ends.
  */
-async function resolveFirstRunModel(agentDir, options = {}) {
+async function resolveFirstRunModel({ agentDir, workspace }, options = {}) {
     const { config, path: configPath } = await loadConfig(agentDir).catch(failStartup);
     if (resolveModelSpec(options.model, config))
         return; // already set (flag > FASTAGENT_MODEL > config)
@@ -122,11 +114,11 @@ async function resolveFirstRunModel(agentDir, options = {}) {
         return; // --no-input: never prompt (clig) — the opener raises the clear error
     if (!isInteractive())
         return; // CI/deploy: the opener throws the actionable missing-model error
-    const auth = resolveAuthLayers(agentDir);
+    const environment = agentModels(agentDir, {}, { cwd: workspace });
     // The picker lists the AGENT's surface: built-ins plus whatever its models.json declares, so a self-hosted endpoint
     // is pickable on first run instead of being invisible until hand-set.
-    const models = await createPiModelRuntime({ agentDir, auth }).catch(failStartup);
-    const chosen = await pickWithCredentials(models, auth.path, agentDir);
+    const models = await environment.runtime().catch(failStartup);
+    const chosen = await pickWithCredentials(models, environment.auth.path, agentDir);
     if (chosen === undefined)
         return; // cancelled (or auth probe failed): the caller raises its clear missing-model error
     process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
@@ -197,10 +189,10 @@ export function terminalLoginIO() {
 }
 /** Best-effort persist the picked model so the next run does not prompt. */
 async function persistModelChoice(agentDir, configPath, spec) {
-    const hint = () => console.error(
+    const hint = (why = "") => console.error(
     // The pick lives in THIS process's environment only, so it serves this run and nothing that outlives it: a
     // deployment resolves in the environment being deployed, where this machine's variables do not exist.
-    `[fastagent] picked ${spec} — set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
+    `[fastagent] picked ${spec} — set \`model: ${JSON.stringify(spec)}\` in your config to persist${why}`);
     if (!configPath)
         return hint();
     try {
@@ -210,7 +202,8 @@ async function persistModelChoice(agentDir, configPath, spec) {
         await writeFile(configPath, replaced);
         console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(agentDir, configPath)}`);
     }
-    catch {
-        hint();
+    catch (error) {
+        // The run goes on with the pick either way; the reason the file was not written is what the author needs to fix.
+        hint(` (could not write ${configPath}: ${error.message})`);
     }
 }

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

@@ -1,6 +1,6 @@
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
-import { type DeploymentSecret } from "../secrets.ts";
+import type { DeploymentSecret } from "../secrets.ts";
 /** The one schedule fact the plan needs (from loadRoutines) — name + cron + tz. */
 export interface ScheduleFact {
     name: string;
@@ -10,8 +10,6 @@ export interface ScheduleFact {
 export interface AgentcorePlanInput extends ContainerInput {
     /** Base name (dir basename) — shapes the runtime name, stack name, ECR repo, session id. */
     name: string;
-    /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
-    modelAuth: string | undefined;
     /**
      * Every declared channel and its ingress — the source of the webhook steps, and whether the
      * forwarder is needed at all (ANY webhook channel requires it, customs included).
@@ -30,6 +28,12 @@ export interface AgentcorePlanInput extends ContainerInput {
      * {@link DEFAULT_IDLE_TIMEOUT_SECONDS}.
      */
     idleTimeoutSeconds?: number;
+    /**
+     * The provider the runtime logs in to itself (`fastagent login --deployment`) after every deploy and every 14-day
+     * idle reset: its storage, and
+     * the login with it, resets each time.
+     */
+    boxLogin?: string;
 }
 export interface AgentcorePlan {
     /** template + forwarder + Dockerfile/.dockerignore — written by the CLI (kept unless --force). */
@@ -69,18 +73,13 @@ export declare function wakeAlarmPrefix(name: string): string;
 /** Account-suffixed artifact bucket for S3's global namespace. */
 export declare function deploymentBucketName(name: string, account: string): string;
 /**
- * AgentCore env values max 2048 chars — a 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 declare const CARRIER_CHUNK_SIZE = 2000;
 export declare 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 declare const CARRIERS: readonly [{
-    readonly param: "FastagentAuthSeed";
-    readonly env: "FASTAGENT_AUTH_SEED";
-    readonly what: "base64 auth.json";
-}, {
     readonly param: "FastagentEnv";
     readonly env: "FASTAGENT_ENV";
     readonly what: "base64 JSON of the value file's variables";

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