@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/agent.d.ts

@@ -47,6 +47,16 @@ export type AgentEvent = {
     isError: boolean;
     content: Json;
 }
+/**
+ * Advisory, non-terminal (engines MAY emit it): the running tool `id`'s current status, one line, replacing the last.
+ * It may be a line of the tool's output so far (trust it like `tool_ended.content`), never the whole output;
+ * untruncated, so a consumer that shows it clips it.
+ */
+ | {
+    type: "tool_progress";
+    id: string;
+    text: string;
+}
 /**
  * Advisory, non-terminal (engines MAY emit it): a transient internal failure scheduled a retry with backoff — the
  * turn is still alive.

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/kit/preview-kit.d.ts

@@ -23,6 +23,8 @@ export declare const THINKING_PLACEHOLDER = "\uD83D\uDCAD Thinking\u2026";
 interface ToolLine {
     label: string;
     status: "running" | "ok" | "error";
+    /** The call's latest `tool_progress` text, shown while it runs. */
+    progress?: string;
 }
 /** The channel-neutral view STATE of one in-flight turn. */
 export interface TurnView {
@@ -38,7 +40,10 @@ export interface TurnView {
 }
 export declare function createTurnView(): TurnView;
 export declare function applyTurnEvent(view: TurnView, e: AgentEvent, now?: number): boolean;
-/** The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. */
+/**
+ * The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. A running call shows its latest
+ * progress after the mark (`🔧 Bash npm test … › 42 passed`); a finished one drops it.
+ */
 export declare function toolLines(view: TurnView): string;
 /** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe. */
 export declare function thinkingLine(view: TurnView, maxTail: number): string;

package/dist/channels/kit/preview-kit.js

@@ -36,6 +36,13 @@ export function applyTurnEvent(view, e, now = Date.now()) {
             view.toolById.set(e.id, line);
             return true;
         }
+        case "tool_progress": {
+            const line = view.toolById.get(e.id);
+            if (line?.status !== "running")
+                return closedRetry;
+            line.progress = e.text;
+            return true;
+        }
         case "tool_ended": {
             const line = view.toolById.get(e.id);
             if (line)
@@ -50,9 +57,17 @@ export function applyTurnEvent(view, e, now = Date.now()) {
     }
 }
 const TOOL_MARK = { running: "…", ok: "✓", error: "✗" };
-/** The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. */
+/**
+ * The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. A running call shows its latest
+ * progress after the mark (`🔧 Bash npm test … › 42 passed`); a finished one drops it.
+ */
 export function toolLines(view) {
-    return view.tools.map((t) => `🔧 ${t.label} ${TOOL_MARK[t.status]}`).join("\n");
+    return view.tools
+        .map((t) => {
+        const progress = t.status === "running" && t.progress ? ` › ${clip(t.progress, TOOL_PROGRESS_MAX)}` : "";
+        return `🔧 ${t.label} ${TOOL_MARK[t.status]}${progress}`;
+    })
+        .join("\n");
 }
 /** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe. */
 export function thinkingLine(view, maxTail) {
@@ -77,15 +92,17 @@ export function composeTurnBody(parts) {
 }
 /** Max length (code points) of a tool's arg preview. */
 const TOOL_ARG_MAX = 48;
+/** Max length (code points) of a running tool's progress line: one status, not its output. */
+const TOOL_PROGRESS_MAX = 64;
 /** Max length (code points) of a humanized tool label. */
 const TOOL_NAME_MAX = 80;
 /**
  * One-line, truncated at code-point boundaries: collapse whitespace so a multi-line command/arg stays on one line, and
  * never tear a surrogate pair mid-emoji.
  */
-function clip(s) {
+function clip(s, max = TOOL_ARG_MAX) {
     const one = s.replace(/\s+/g, " ").trim();
-    return truncateCodePointPrefix(one, TOOL_ARG_MAX);
+    return truncateCodePointPrefix(one, max);
 }
 /**
  * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md` rather than just

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/preview.js

@@ -119,7 +119,8 @@ function streamClassicSlackReply(events, api, target, formatError, initialPrevie
         let lastSent = "";
         const view = () => composeTurnBody([
             THINKING_PLACEHOLDER,
-            toolLines(turn),
+            // Tool names, arguments and progress lines are untrusted text, like the answer.
+            sanitizeSlackMarkdown(toolLines(turn)),
             turn.retrying ? RETRY_NOTICE : "",
             sanitizeSlackMarkdown(revealedAnswer(turn, CLASSIC_UPDATE_INTERVAL_MS, now())),
         ]);

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