@fastagent-sh/fastagent 0.22.1 → 0.23.0

package/dist/channels/agentcore-protocol.d.ts

@@ -84,7 +84,8 @@ export type AgentcoreEnvelope = {
 }
 /**
  * The deploy driver's post-deploy verification (relayed by the forwarder's reserved probe path, which answers on
- * EVERY forwarder topology — schedule-only URLs refuse ordinary public traffic).
+ * EVERY forwarder topology — schedule-only URLs refuse ordinary public traffic). Also accepted from the IAM door,
+ * where it only opens the workspace (`login --deployment` needs one) and does not construct the channels.
  */
  | {
     kind: "probe";

package/dist/channels/agentcore-service.js

@@ -91,26 +91,18 @@ export function deferAgentcoreService(stages) {
 export async function mountAgentcoreService(opened, options = {}) {
     const { agentDir, workspace, stateRoot, sessionControl } = opened;
     const agent = options.wrapAgent?.(opened.agent) ?? opened.agent;
-    // NO control plane on this host, and `sessionControl: true` cannot change that.
+    // NO control plane on this host, and `sessionControl: true` cannot change that. The only public way in is the
+    // forwarder's Function URL, which relays an arbitrary `rawPath` verbatim as a webhook envelope and attaches the
+    // ingress secret ITSELF (deploy/agentcore/forwarder.js), so every anonymous caller arrives as trusted ingress. A
+    // channel route survives that because it checks its platform's signature; `/control/*` has no such check.
     //
-    // The only public way in is the forwarder's Function URL, which relays an arbitrary `rawPath` verbatim as a
-    // webhook envelope (deploy/agentcore/forwarder.js) and attaches the ingress secret ITSELF — so every anonymous
-    // caller arrives as trusted ingress. A channel route survives that because the platform's signature is checked
-    // inside it; `/control/*` has no such check, and mounting it here made `GET /control/sessions` and
-    // `DELETE /control/sessions/{id}` answerable from the public URL with no credential at all.
+    // The recipe if it is ever wanted: a `kind: "control"` envelope on the IAM-gated `InvokeAgentRuntime`, which the
+    // forwarder never emits (the way `kind: "invoke"` runs a turn without the ingress secret). The envelope is
+    // request/response with a buffered body, so the long-lived `GET /control/sessions/{id}/events` stream a client
+    // renders from could not ride it.
     //
-    // It is NOT that the two callers cannot be told apart. AWS already separates them and we already use that:
-    // `InvokeAgentRuntime` is IAM-gated, the forwarder builds its own envelopes and emits exactly four kinds, so a
-    // kind it never sends can only have come from a direct IAM call — which is how `kind: "invoke"` runs a turn here
-    // without the ingress secret. Adding `kind: "control"` on the same footing is small, and is the recipe if this is
-    // ever wanted.
-    //
-    // It is not built because nothing asks for it: `connectSessionControl` has no caller in this repo, and the
-    // envelope is request/response with a buffered body (see the webhook reply), so the one route a GUI actually
-    // renders from — the long-lived `GET /control/sessions/{id}/events` stream — could not ride it anyway. Half a
-    // control plane, for nobody, on a third transport.
-    // Every config key that cannot mean anything on this host says so. Silence here is how an operator concludes a
-    // setting took effect — `sessionControl` was the one that already warned, and the other two were just as inert.
+    // Every config key that cannot mean anything on this host says so: silence is how an operator concludes a setting
+    // took effect.
     if (opened.http?.cors) {
         log.warn("[fastagent] agentcore: http.cors has no effect here — no browser reaches this container. Its ingress is the " +
             "forwarder's Function URL (webhooks) and the Runtime's IAM-gated API, neither of which is a page.");

package/dist/channels/agentcore.js

@@ -66,8 +66,10 @@ export function agentcoreRoutes(options) {
         // The forwarder, or another IAM principal? See `fromForwarder` for what that actually decides.
         const trusted = fromForwarder(envelope, ingressSecret);
         if (!trusted) {
-            // The IAM door's kinds: AWS authenticated this caller, so no ingress secret is expected or wanted.
-            if (envelope.kind !== "invoke" && envelope.kind !== "routine-run") {
+            // The IAM door's kinds: AWS authenticated this caller, so no ingress secret is expected or wanted. A `probe`
+            // here only opens the workspace (the deferred wrapper did that before this line) and says so: it is how
+            // `login --deployment` gets a workspace to log in, after a reset, on a runtime nothing has invoked yet.
+            if (envelope.kind !== "invoke" && envelope.kind !== "routine-run" && envelope.kind !== "probe") {
                 log.warn(`[agentcore] rejected an unauthenticated "${envelope.kind}" envelope`);
                 return text("forbidden\n", 403);
             }
@@ -179,7 +181,8 @@ export function agentcoreRoutes(options) {
                 return json({ ok: true }, 200);
             }
             case "probe": {
-                // The structured verdict (transport-200 — see the envelope doc).
+                // The structured verdict (transport-200 — see the envelope doc). From the IAM door (untrusted) nothing was
+                // activated, so `ok` says only that the definition opened; channel construction is the forwarder probe's.
                 return json(constructionError === undefined
                     ? { ok: true }
                     : { ok: false, error: `channel construction failed: ${constructionError}` }, 200);

package/dist/channels/control.js

@@ -9,6 +9,11 @@ import { text } from "./respond.js";
 export const CONTROL_PREFIX = "/control";
 /** The one variable segment in this plane's paths: a percent-encoded session id. */
 const SESSION_SEGMENT = "{session}";
+/**
+ * What `.../image` may answer under the image's own type. `mimeType` is whatever the prompt's sender wrote, and served
+ * as-is a `text/html` or `image/svg+xml` "image" would run script on whatever origin fronts this plane.
+ */
+const RASTER_IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
 const json = (value, status = 200) => new Response(`${JSON.stringify(value)}\n`, { status, headers: { "content-type": "application/json" } });
 /** The plane as one mounted sub-application rather than routes sharing a prefix. */
 function planeApp(routes) {
@@ -267,6 +272,24 @@ export function controlPlaneRoutes(control) {
             const since = url.searchParams.get("since") ?? undefined;
             return json(await control.sessions.get(session).entries(since !== undefined ? { since } : undefined));
         },
+        // Raw bytes, not JSON-wrapped base64: a client can hand the response straight to an <img>. The ref names a
+        // durable entry, so the answer never changes. `ref` rides the query because this router has one path variable.
+        [`GET /control/sessions/${SESSION_SEGMENT}/image`]: async (_req, url, session) => {
+            const ref = url.searchParams.get("ref");
+            if (ref === null)
+                return text("expected ?ref=, an images[].ref from entries()\n", 400);
+            const image = await control.sessions.get(session).image(ref);
+            // The local call RETURNS undefined, so this is a 2xx (§13); a 404 stays "this serve predates the route".
+            if (!image)
+                return new Response(null, { status: 204 });
+            return new Response(Buffer.from(image.data, "base64"), {
+                headers: {
+                    "content-type": RASTER_IMAGE_TYPES.has(image.mimeType) ? image.mimeType : "application/octet-stream",
+                    "x-content-type-options": "nosniff",
+                    "cache-control": "private, max-age=31536000, immutable",
+                },
+            });
+        },
         // The run actions.
         [`POST /control/sessions/${SESSION_SEGMENT}/actions`]: async (req, _url, session) => {
             const read = await readJson(req);

package/dist/channels/slack/config-api.d.ts

@@ -21,8 +21,8 @@ export declare class SlackConfigApiError extends Error {
 export declare function isSlackRequestUrlUnverified(error: unknown): boolean;
 /** Whether a manifest write was refused because the app has token rotation on, which Slack never lets off again. */
 export declare function isSlackRotationLocked(error: unknown): boolean;
-/** The upgrade every rotating-app refusal points at. */
-export declare const SLACK_ROTATING_APP_UPGRADE = "this app has token rotation on, which this release no longer uses and Slack cannot turn off \u2014 create a new app (docs/slack.md \u2192 \"Upgrading from a rotating-token app\")";
+/** The remedy every rotating-app refusal points at. */
+export declare const SLACK_ROTATING_APP_REMEDY = "this app has token rotation on, which FastAgent does not support and Slack cannot turn off \u2014 create a new app (docs/slack.md \u2192 \"If token rotation is on\")";
 export interface SlackAppCredentials {
     appId: string;
     clientId: string;

package/dist/channels/slack/config-api.js

@@ -31,8 +31,8 @@ export function isSlackRotationLocked(error) {
     return (error.code === "cannot_disable_once_enabled" ||
         error.errors.some((e) => e.message?.includes("cannot_disable_once_enabled") || e.pointer?.endsWith("token_rotation_enabled")));
 }
-/** The upgrade every rotating-app refusal points at. */
-export const SLACK_ROTATING_APP_UPGRADE = 'this app has token rotation on, which this release no longer uses and Slack cannot turn off — create a new app (docs/slack.md → "Upgrading from a rotating-token app")';
+/** The remedy every rotating-app refusal points at. */
+export const SLACK_ROTATING_APP_REMEDY = 'this app has token rotation on, which FastAgent does not support and Slack cannot turn off — create a new app (docs/slack.md → "If token rotation is on")';
 async function slackJson(method, body, options = {}) {
     const fetchFn = options.fetch ?? globalThis.fetch;
     let response;

package/dist/channels/slack/onboard.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { retryWhile } from "../registration.js";
-import { createSlackApp, exchangeSlackOAuthCode, isSlackRequestUrlUnverified, isSlackRotationLocked, SLACK_ROTATING_APP_UPGRADE, SlackConfigApiError, updateSlackAppManifest, } from "./config-api.js";
+import { createSlackApp, exchangeSlackOAuthCode, isSlackRequestUrlUnverified, isSlackRotationLocked, SLACK_ROTATING_APP_REMEDY, SlackConfigApiError, updateSlackAppManifest, } from "./config-api.js";
 import { buildSlackManifest, slackBotScopes } from "./manifest.js";
 import { configTokenExpiry, currentSlackConfigToken, writeSlackOnboardingState, } from "./onboarding-state.js";
 /** Create/resume one internal Slack app and complete its workspace OAuth installation. */
@@ -76,7 +76,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
         catch (error) {
             // A resume of an app created with rotation on: the manifest is refused for good, so say what fixes it.
             if (isSlackRotationLocked(error))
-                throw new Error(SLACK_ROTATING_APP_UPGRADE, { cause: error });
+                throw new Error(SLACK_ROTATING_APP_REMEDY, { cause: error });
             throw error;
         }
     }

package/dist/channels/slack/register-webhook.js

@@ -1,5 +1,5 @@
 import { retryWhile } from "../registration.js";
-import { SLACK_ROTATING_APP_UPGRADE, isSlackRequestUrlUnverified, isSlackRotationLocked, updateSlackAppManifest, } from "./config-api.js";
+import { SLACK_ROTATING_APP_REMEDY, isSlackRequestUrlUnverified, isSlackRotationLocked, updateSlackAppManifest, } from "./config-api.js";
 import { buildSlackManifest } from "./manifest.js";
 import { currentSlackConfigToken, readSlackOnboardingState } from "./onboarding-state.js";
 /** Update one onboarded internal Slack app without sending its configuration credential to the host. */
@@ -53,7 +53,7 @@ export async function registerSlackWebhook(baseUrl, options) {
     }
     catch (error) {
         if (isSlackRotationLocked(error)) {
-            note(`[fastagent] slack: ${SLACK_ROTATING_APP_UPGRADE}, or ${consoleFallback}`);
+            note(`[fastagent] slack: ${SLACK_ROTATING_APP_REMEDY}, or ${consoleFallback}`);
             return "failed";
         }
         note(isSlackRequestUrlUnverified(error)

package/dist/channels/slack/slack-api.js

@@ -135,12 +135,12 @@ async function readBytesCapped(response) {
     }
     return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
 }
-/** A rotating token (an app created by a release up to 0.20) would work for up to 12 hours and then
- *  fail as `token_expired`, far from the cause — refuse it where the token enters, on both paths. */
+/** A rotating token (an app with token rotation on) would work for up to 12 hours and then fail as
+ *  `token_expired`, far from the cause — refuse it where the token enters, on both paths. */
 function assertLongLivedBotToken(botToken) {
     if (botToken.startsWith("xoxe.")) {
-        throw new Error("got a rotating Slack bot token (xoxe.…); this release uses a long-lived xoxb- token — " +
-            'create a new app (docs/slack.md → "Upgrading from a rotating-token app")');
+        throw new Error("got a rotating Slack bot token (xoxe.…); FastAgent needs a long-lived xoxb- token — " +
+            'create a new app (docs/slack.md → "If token rotation is on")');
     }
 }
 export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" }) {

package/dist/cli/add-feishu.js

@@ -251,8 +251,10 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         const cfg = await api.getAppConfig(appId);
         token = cfg.verificationToken;
     }
-    catch {
-        // the read surface is best-effort — the bootstrap below is the real path
+    catch (error) {
+        // Best-effort read; the bootstrap below is the real path. Said, because that path can take minutes and the reason
+        // it was needed would otherwise be invisible.
+        console.error(`[fastagent] could not read the app's Verification Token directly: ${error.message}`);
     }
     if (!token) {
         console.error(`[fastagent] capturing the Verification Token — a throwaway webhook registration delivers it (spinning up a temporary tunnel; can take a few minutes on a slow edge)…`);

package/dist/cli/auth-view.d.ts

@@ -1,10 +1,19 @@
 /** CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). */
-/** A stored credential as `reportAuth` needs it: just its kind, for the status line. */
-export interface StoredCredentialInfo {
-    type: string;
-}
-/** Format the auth status for `spec`'s provider. */
-export declare function formatAuthReport(provider: string, authPath: string, source: string | undefined, stored: StoredCredentialInfo | undefined): {
+/**
+ * Format the auth status for a provider, from `AgentModels.authStatus`'s answer. `deployed`: this process is a
+ * deployed box, which logs in from the owner's workspace (`fastagent login --deployment`), never by a login run on it
+ * by hand.
+ */
+export declare function formatAuthReport(status: {
+    provider: string;
+    path: string;
+    source?: string;
+    /** Why resolving the credential failed, when it did: said, because "expired" is only one of the reasons. */
+    error?: string;
+    stored?: string;
+    shadowed?: string;
+    deployed?: boolean;
+}): {
     line: string;
     warn?: string;
 };

package/dist/cli/auth-view.js

@@ -1,16 +1,32 @@
 /** CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). */
-/** Format the auth status for `spec`'s provider. */
-export function formatAuthReport(provider, authPath, source, stored) {
-    if (source !== undefined)
-        return { line: `auth:   ${source} (${provider}) — ${authPath}` };
+/**
+ * Format the auth status for a provider, from `AgentModels.authStatus`'s answer. `deployed`: this process is a
+ * deployed box, which logs in from the owner's workspace (`fastagent login --deployment`), never by a login run on it
+ * by hand.
+ */
+export function formatAuthReport(status) {
+    const { provider, path, source, error, stored, shadowed, deployed = false } = status;
+    const because = error === undefined ? "" : ` (${error})`;
+    const login = (name) => deployed ? `\`${name} --deployment\` from the workspace this was deployed from` : `\`${name}\``;
+    if (source !== undefined) {
+        const line = `auth:   ${source} (${provider}) — ${path}`;
+        if (shadowed === undefined)
+            return { line };
+        // A stored credential owns its provider in pi, so a key added to the environment later is silently unused.
+        return {
+            line,
+            warn: `${shadowed} is set but unused: the stored ${provider} ${stored} credential in ${path} outranks it. To run ` +
+                `on ${shadowed}, log in with it instead: ${login(`fastagent login ${provider}`)}, choosing "API key"`,
+        };
+    }
     if (stored) {
         return {
-            line: `auth:   stored ${provider} ${stored.type}, expired/unusable — ${authPath}`,
-            warn: `the "${provider}" login is expired or unusable — run \`fastagent login\` to refresh it`,
+            line: `auth:   stored ${provider} ${stored}, expired/unusable — ${path}`,
+            warn: `the "${provider}" login is expired or unusable${because} — run ${login("fastagent login")} to replace it`,
         };
     }
     return {
-        line: `auth:   (none found) — ${authPath}`,
-        warn: `no credentials for "${provider}" — run \`fastagent login\`, or set the provider's API key in .env; invokes will fail until then`,
+        line: `auth:   (none found) — ${path}`,
+        warn: `no credentials for "${provider}"${because} — run ${login("fastagent login")}, or set the provider's API key in ${deployed ? "the deployment's value file" : ".env"}; invokes will fail until then`,
     };
 }

package/dist/cli/box-login.d.ts

@@ -0,0 +1,33 @@
+import { type BoxShell } from "../deploy/box-shell.ts";
+import type { DeployHost } from "../deploy/hosts.ts";
+import type { LoginIO } from "../engines/pi/login.ts";
+import type { ResolvedPlacement } from "../paths.ts";
+export interface BoxLoginRequest {
+    host: DeployHost;
+    shell: BoxShell;
+    placement: ResolvedPlacement;
+    /** Skip the provider menu. */
+    provider?: string;
+    /** Keep a credential the box already holds for `provider` (a redeploy), instead of replacing it. */
+    ifMissing?: boolean;
+    /** false: never ask; a box without the credential is a failure naming the command to run in a terminal. */
+    input: boolean;
+}
+/**
+ * Run the login on the box and report its outcome. Resolves `undefined` once the box reports a credential for the
+ * provider (logged in now, or kept), else with the one line saying why not and what to run.
+ */
+export declare function loginOnBox(request: BoxLoginRequest): Promise<string | undefined>;
+/**
+ * A browser OAuth flow sends the owner's browser back to its `redirect_uri`: a localhost address, which on the owner's
+ * machine has nothing of the box behind it. So catch it here. While an authorization URL naming such a redirect is
+ * open, listen on that address (the port the provider fixed, loopback only, as pi's own flows do), and answer the
+ * next text prompt with the URL the browser brought back, exactly what the person would paste. The terminal prompt
+ * stays up meanwhile: a taken port, or a browser on another machine, still leaves pasting.
+ *
+ * ponytail: "the next text prompt" is the one after the URL. pi's browser flows (Anthropic, Codex) ask exactly one,
+ * the paste; a flow that asked something else in between would get the URL as that answer and reject it.
+ */
+export declare function catchingRedirect(io: LoginIO): LoginIO & {
+    close(): void;
+};

package/dist/cli/box-login.js

@@ -0,0 +1,162 @@
+/**
+ * Logging a deployment in on the deployment itself: `fastagent login --stdio` runs on the box through the host's own
+ * owner-authenticated shell (deploy/box-shell.ts), and this terminal renders it (login-relay.ts). The box creates and
+ * keeps the credential, so it is the only holder of its grant, and logging in again replaces it there. Nothing is
+ * copied from this machine.
+ */
+import { createServer } from "node:http";
+import { basename } from "node:path";
+import { deploymentLoginCommand } from "../deploy/box-shell.js";
+import { boxLoginCommand } from "../deploy/container.js";
+import { relayLogin } from "./login-relay.js";
+import { terminalLoginIO } from "./shared.js";
+/**
+ * Run the login on the box and report its outcome. Resolves `undefined` once the box reports a credential for the
+ * provider (logged in now, or kept), else with the one line saying why not and what to run.
+ */
+export async function loginOnBox(request) {
+    const { host, shell, placement, provider } = request;
+    const retry = deploymentLoginCommand(host, provider);
+    const args = [
+        ...(provider ? [provider] : []),
+        ...(request.ifMissing ? ["--if-missing"] : []),
+        ...(request.input ? [] : ["--no-input"]),
+    ];
+    let command;
+    try {
+        command = boxLoginCommand(basename(placement.agentDir), args, shell.storage);
+    }
+    catch (error) {
+        return error.message;
+    }
+    // A wake that fails is this login's answer, in one line, like an `open` that fails below.
+    const woken = await shell.wake?.().catch((error) => error);
+    if (woken instanceof Error)
+        return woken.message;
+    const channel = await shell.open(command).catch((error) => error);
+    if (channel instanceof Error)
+        return channel.message;
+    const io = catchingRedirect(terminalLoginIO());
+    const result = await relayLogin(channel.output, channel.input, io, (line) => console.error(line)).finally(io.close);
+    const closed = await channel.closed;
+    if (!closed.opened)
+        return closed.error;
+    if (!result) {
+        return (`the ${host} shell ended without a login result (${closed.how}) — nothing on the box says it is logged in. ` +
+            `See the output above, then run \`${retry}\``);
+    }
+    if (result.ok) {
+        console.error("kept" in result
+            ? `[fastagent] the deployment already authenticates ${result.provider} (${result.kept}) — kept`
+            : `[fastagent] logged in to ${result.provider} (${result.method}) on the deployment — saved to ${result.path} there`);
+        return undefined;
+    }
+    if (result.reason === "missing")
+        return `not logged in: ${result.message} — run \`${retry}\` in a terminal`;
+    if (result.reason === "cancelled")
+        return `login on the deployment cancelled — run \`${retry}\` to log it in`;
+    return `login on the deployment failed: ${result.message}`;
+}
+const CAUGHT_PAGE = "<!doctype html><meta charset=utf-8><title>fastagent</title>" +
+    "<p>fastagent received the sign-in and sent it to your deployment. Return to your terminal.</p>";
+/**
+ * A browser OAuth flow sends the owner's browser back to its `redirect_uri`: a localhost address, which on the owner's
+ * machine has nothing of the box behind it. So catch it here. While an authorization URL naming such a redirect is
+ * open, listen on that address (the port the provider fixed, loopback only, as pi's own flows do), and answer the
+ * next text prompt with the URL the browser brought back, exactly what the person would paste. The terminal prompt
+ * stays up meanwhile: a taken port, or a browser on another machine, still leaves pasting.
+ *
+ * ponytail: "the next text prompt" is the one after the URL. pi's browser flows (Anthropic, Codex) ask exactly one,
+ * the paste; a flow that asked something else in between would get the URL as that answer and reject it.
+ */
+export function catchingRedirect(io) {
+    let server;
+    let caught;
+    let deliver;
+    const close = () => {
+        server?.close();
+        server = undefined;
+    };
+    const listen = (authUrl) => {
+        let redirect;
+        let state;
+        try {
+            const authorize = new URL(authUrl);
+            redirect = new URL(authorize.searchParams.get("redirect_uri") ?? "");
+            state = authorize.searchParams.get("state");
+        }
+        catch {
+            return; // no redirect to catch (a device-code page, or not a URL we can read)
+        }
+        if (redirect.protocol !== "http:" || !["localhost", "127.0.0.1"].includes(redirect.hostname))
+            return;
+        // The flow's `state` is what tells its redirect from anything else that can reach a loopback port: any page open
+        // in the browser can request it, and a forged hit taken as the answer would end this login in "State mismatch" and
+        // close the port before the real one arrives. Without one there is nothing to tell them apart: leave it to pasting.
+        if (!state)
+            return;
+        close();
+        const listening = createServer((req, res) => {
+            const got = new URL(req.url ?? "/", redirect);
+            if (got.pathname !== redirect.pathname ||
+                !got.searchParams.has("code") ||
+                got.searchParams.get("state") !== state) {
+                res.writeHead(404).end();
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(CAUGHT_PAGE);
+            close();
+            if (deliver)
+                deliver(got.toString());
+            else
+                caught = got.toString();
+        });
+        listening.on("error", (error) => {
+            if (server === listening)
+                server = undefined;
+            io.note(`could not listen on ${redirect.host} for the browser's redirect (${error.code ?? error.message}) — after ` +
+                `signing in, paste the address the browser lands on`);
+        });
+        listening.listen(Number(redirect.port || 80), "127.0.0.1");
+        listening.unref();
+        server = listening;
+    };
+    return {
+        select: io.select,
+        note: io.note,
+        close,
+        openUrl(url) {
+            listen(url);
+            io.openUrl(url);
+        },
+        async prompt(message, opts) {
+            if (caught !== undefined) {
+                const url = caught;
+                caught = undefined;
+                return url;
+            }
+            if (!server)
+                return io.prompt(message, opts);
+            const typed = new AbortController();
+            const signal = opts?.signal ? AbortSignal.any([opts.signal, typed.signal]) : typed.signal;
+            const fromBrowser = new Promise((resolve) => {
+                deliver = resolve;
+            });
+            try {
+                // Settle the race BEFORE aborting the terminal prompt: aborting it settles its promise too.
+                const won = await Promise.race([
+                    io.prompt(message, { ...opts, signal }).then((value) => ({ typed: value })),
+                    fromBrowser.then((url) => ({ url })),
+                ]);
+                if ("typed" in won)
+                    return won.typed;
+                typed.abort();
+                io.note("received the browser's redirect");
+                return won.url;
+            }
+            finally {
+                deliver = undefined;
+            }
+        },
+    };
+}

package/dist/cli/commands/deploy/agentcore.js

@@ -5,22 +5,47 @@
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
-import { FORWARDER_FILE, TEMPLATE_FILE, agentcoreName, forwarderLogGroup, ingressSessionId, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../../deploy/agentcore/plan.js";
-import { deployAgentcoreRun } from "../../../deploy/agentcore/run.js";
-import { spawnRunner } from "../../../deploy/runner.js";
+import { FORWARDER_FILE, TEMPLATE_FILE, agentcoreName, agentcoreStackName, forwarderLogGroup, ingressSessionId, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../../deploy/agentcore/plan.js";
+import { deployAgentcoreRun, pickStackOutputs } from "../../../deploy/agentcore/run.js";
+import { awsCli, awsJson } from "../../../deploy/agentcore/aws-cli.js";
+import { agentcoreShell } from "../../../deploy/agentcore/shell.js";
+import { awsRunner, spawnRunner } from "../../../deploy/runner.js";
 import { SECRET_FILE_MODE, exists } from "../../../paths.js";
 import { loadRoutines } from "../../../schedule/discover.js";
+import { assembleSecrets } from "../../../deploy/secrets.js";
 import { failStartup } from "../../fail.js";
-import { carryCredentials, gateOnModelCredential, registrarsFor } from "./shared.js";
+import { isInteractive } from "../../shared.js";
+import { boxLoginStep, registrarsFor } from "./shared.js";
 /** A copy/paste-safe POSIX shell argument for the command hints deploy prints. */
 function shellArg(value) {
     return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 export const agentcoreHost = {
     isOurs: (path, content) => path.endsWith(TEMPLATE_FILE) && isGeneratedAgentcoreTemplate(content),
+    artifact: TEMPLATE_FILE,
+    async shell({ workspace }) {
+        const name = agentcoreName(basename(workspace));
+        const stack = agentcoreStackName(name);
+        const aws = awsRunner(workspace);
+        const read = await awsCli(aws).read(["cloudformation", "describe-stacks", "--stack-name", stack, "--query", "Stacks[0].Outputs", "--output", "json"], awsJson(pickStackOutputs));
+        if ("absent" in read)
+            throw new Error(`no AgentCore stack ${stack} in this account/region — deploy it first`);
+        if ("unreadable" in read)
+            throw new Error(`could not read AgentCore stack ${stack}: ${read.unreadable}`);
+        const runtimeArn = read.ok.RuntimeArn;
+        if (!runtimeArn)
+            throw new Error(`stack ${stack} has no RuntimeArn output — redeploy it`);
+        return agentcoreShell(runtimeArn, ingressSessionId(name), aws);
+    },
     async deploy(ctx) {
         const { opts, agentDir, workspace, config, channels, longConnectionChannels, pre, write } = ctx;
-        const { modelAuth, modelKeyInDefinition, authPath, container, declaredSecrets, values, valueFile } = pre;
+        const { modelAuth, boxLogin, container, declaredSecrets, values, valueFile } = pre;
+        if (boxLogin) {
+            console.error(`[fastagent] note: AgentCore resets the runtime's storage on every deploy AND after 14 idle days, and the ` +
+                `${boxLogin} login with it: every deploy of this agent ends with a login on the runtime, and after an idle ` +
+                `reset every turn fails until \`fastagent login ${boxLogin} --deployment agentcore\` (the runtime's log says ` +
+                `so). For an agent that must keep answering unattended, set ${boxLogin}'s API key in ${valueFile}.`);
+        }
         // Long-connection channels are STRUCTURALLY unsupported: the connection is the ingress, and a reclaimed session
         // has nothing to wake it.
         if (longConnectionChannels.length > 0) {
@@ -54,7 +79,7 @@ export const agentcoreHost = {
         }
         const plan = planAgentcoreDeploy({
             name: acName,
-            modelAuth,
+            boxLogin,
             channels,
             secrets: pre.secrets,
             // ONLY THE ONES WITH A CRON become rules. A routine without one is reached by NAME, through this host's
@@ -98,8 +123,8 @@ export const agentcoreHost = {
                 agentPrefix: container.agentPrefix,
                 name: acName,
                 modelAuth,
-                modelKeyInDefinition,
-                authPath,
+                boxLogin,
+                input: opts.input !== false && isInteractive(),
                 channels,
                 declaredSecrets,
                 values,
@@ -114,12 +139,23 @@ export const agentcoreHost = {
 /** `deploy agentcore --run`: drive aws + docker to completion. */
 async function runDeployAgentcore(params) {
     const { agentDir, workspace, agentPrefix, name, channels, topology } = params;
-    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    // Decided before the first side effect: the deploy resets the runtime's storage and the login with it, so with nobody
+    // to log it in again it would end at "not logged in" AFTER replacing a runtime that was serving, with the webhooks
+    // a previous deploy registered still pointing at it.
+    if (params.boxLogin && !params.input) {
+        failStartup(new Error(`deploy stopped: every AgentCore deploy wipes the runtime's ${params.boxLogin} login, and without a terminal ` +
+            `nobody can log it in again — run this deploy in a terminal, or set ${params.boxLogin}'s API key in ` +
+            `${params.valueFile}`));
+    }
+    const { secrets, missingSecrets } = assembleSecrets({
+        modelAuth: params.modelAuth,
+        declared: params.declaredSecrets,
+        values: params.values,
+    });
     // The wake-alarm shared secret (container ↔ forwarder).
     secrets.FASTAGENT_WAKE_SECRET = crypto.randomUUID();
     // The forwarder→runtime ingress secret: what makes an envelope the forwarder's rather than any IAM principal's.
     secrets.FASTAGENT_INGRESS_SECRET = crypto.randomUUID();
-    gateOnModelCredential(needsModelCredential);
     // The params temp dir holds the ONE file carrying secret values (file:// parameter-overrides — never argv);
     // 0700/0600 and removed after the run, success or gate.
     const paramsDir = await mkdtemp(join(tmpdir(), "fastagent-agentcore-"));
@@ -138,7 +174,8 @@ async function runDeployAgentcore(params) {
             valueFile: params.valueFile,
             channels,
             topology,
-        }, spawnRunner("aws", workspace), spawnRunner("docker", workspace), (m) => console.error(`[fastagent] ${m}`), async (content) => {
+            ...boxLoginStep("agentcore", params, (runtimeArn) => agentcoreShell(runtimeArn, ingressSessionId(name), awsRunner(workspace))),
+        }, awsRunner(workspace), spawnRunner("docker", workspace), (m) => console.error(`[fastagent] ${m}`), async (content) => {
             const path = join(paramsDir, "params.json");
             await writeFile(path, content, { mode: SECRET_FILE_MODE });
             return path;