@fastagent-sh/fastagent 0.22.1 → 0.23.0

package/dist/cli/commands/models.js

@@ -1,9 +1,42 @@
-/** `fastagent models [search]`: print every registered "provider/modelId"; `[search]` filters by substring. */
+/**
+ * `fastagent models [search]`: print every "provider/modelId" the agent here (or, outside one or with `-g`, this
+ * machine) can name; `[search]` filters by substring. `--refresh` first fetches the model catalog into that scope's
+ * `models-store.json`.
+ */
+import { join } from "node:path";
+import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import { formatModelsCommand } from "../models-view.js";
 import { listModels } from "../../engines/pi/config.js";
-import { createPiModels } from "../../engines/pi/models.js";
-export function runModels(search) {
-    const { lines, error } = formatModelsCommand(listModels(createPiModels()), search);
+import { createPiModelRuntime, globalCatalogPath, machineModelRuntime, refreshGlobalModelCatalog, } from "../../engines/pi/models.js";
+import { refreshModelCatalog } from "../../engines/pi/open.js";
+import { AGENT_MODEL_CATALOG_FILE, findAgentDir, globalHome, placementDeadEnd } from "../../paths.js";
+import { enterAgentEnv } from "../../env.js";
+import { failStartup, placementOrExit } from "../fail.js";
+export async function runModels(search, opts = {}) {
+    const cwd = process.cwd();
+    const agentDir = opts.global ? undefined : findAgentDir(cwd);
+    // "Outside an agent" must mean exactly that, as for `login`: inside an agent's subdirectory, or among several agents
+    // with no default, falling back to the machine would list without the agent's own catalog and models.json, and a
+    // refresh would record the models where no deploy carries them. Refused either way; `-g` asks for the machine.
+    if (!opts.global && !agentDir && placementDeadEnd(cwd))
+        placementOrExit(cwd);
+    if (opts.refresh) {
+        // pi fetches a provider's catalog only with a usable credential for it: the scope's own credentials and `.env`
+        // keys, as `login` reads them.
+        enterAgentEnv(agentDir ?? globalHome());
+        if (agentDir) {
+            await refreshModelCatalog(agentDir).catch(failStartup);
+            console.error(`[fastagent] refreshed ${join(agentDir, AGENT_MODEL_CATALOG_FILE)} — commit it: it ships with a deploy`);
+        }
+        else {
+            await refreshGlobalModelCatalog().catch(failStartup);
+            console.error(`[fastagent] refreshed ${globalCatalogPath()} — every agent on this machine reads it`);
+        }
+    }
+    const models = await (agentDir
+        ? createPiModelRuntime({ agentDir, credentials: new InMemoryCredentialStore() })
+        : machineModelRuntime()).catch(failStartup);
+    const { lines, error } = formatModelsCommand(listModels(models), search);
     for (const spec of lines)
         console.log(spec);
     if (error)

package/dist/cli/commands/routine-run.js

@@ -36,11 +36,11 @@ export async function runRoutine(name, dirArg, opts) {
     // were printed above: its guarantee must not depend on this call site remembering (a repeated line
     // on the refusal path is the cheaper failure).
     gateSecretsOrExit({ declared: secrets, failures, owner: name });
-    const { agent, modelSpec, auth } = await createPiAgentFromDir(placement.agentDir, {
+    const { agent, modelSpec, models } = await createPiAgentFromDir(placement.agentDir, {
         model: opts.model,
     }).catch(failStartup);
     console.error(`[fastagent] routine run: ${name} (${modelSpec})`);
-    await reportAuth(placement.agentDir, modelSpec, auth);
+    await reportAuth(models, modelSpec);
     const exitCode = await runInvokeStream(agent.invoke({ session: routineSession(name) }, { text: routine.prompt }), (text) => process.stdout.write(text), (line) => console.error(line));
     process.stdout.write("\n");
     process.exit(exitCode);

package/dist/cli/commands/start.d.ts

@@ -28,11 +28,6 @@ export interface PreparedWorkspace {
  * volume.
  */
 export declare function prepareStartWorkspace(dirArg: string): Promise<PreparedWorkspace>;
-/**
- * Stage two — RUN in the prepared workspace: install the agent's dependencies, then open through the workspace's own
- * FastAgent install.
- */
-export declare function openPreparedWorkspace(prepared: PreparedWorkspace, opts: StartOptions): Promise<StartedService>;
 export declare function openStartService(dirArg: string, opts: StartOptions): Promise<StartedService>;
 /** Internal entry loaded from the active workspace's installed package after storage initialization. */
 export declare function openPreparedStartService(dirArg: string, opts: StartOptions): Promise<StartedService>;

package/dist/cli/commands/start.js

@@ -12,11 +12,9 @@ import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import * as Effect from "effect/Effect";
-import { writeFileAtomic } from "../../atomic-write.js";
-import { applyCarriedEnv, authSeedBytes, collectAuthSeed } from "../../deploy/secrets.js";
+import { applyCarriedEnv } from "../../deploy/secrets.js";
 import { applyReleaseEnv, installAgentDependencies, parseDeploymentRelease, prepareDeployment, } from "../../deploy/workspace.js";
-import { resolveAuthPath } from "../../engines/pi/config.js";
-import { SECRET_FILE_MODE, resolveSecretsDir, isAgentcoreRuntime, isUnderDir, exists } from "../../paths.js";
+import { resolveSecretsDir, isAgentcoreRuntime, isUnderDir, exists } from "../../paths.js";
 import { log, setLogLevel } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { DEFAULT_HTTP_PORT, mountAgentService } from "../../service.js";
@@ -100,7 +98,7 @@ export async function prepareStartWorkspace(dirArg) {
  * Stage two — RUN in the prepared workspace: install the agent's dependencies, then open through the workspace's own
  * FastAgent install.
  */
-export async function openPreparedWorkspace(prepared, opts) {
+async function openPreparedWorkspace(prepared, opts) {
     let open = openPreparedStartService;
     if (prepared.deployed) {
         const { root, agent } = prepared.deployed;
@@ -126,7 +124,6 @@ export async function openStartService(dirArg, opts) {
 /** Internal entry loaded from the active workspace's installed package after storage initialization. */
 export async function openPreparedStartService(dirArg, opts) {
     const placement = await enterAgentCommand(dirArg, opts);
-    await maybeSeedAuth(resolveAuthPath(placement.agentDir));
     const opened = await createPiAgentFromDir(placement.agentDir, {
         model: opts.model,
         serving: true,
@@ -152,13 +149,6 @@ export async function openPreparedStartService(dirArg, opts) {
         : mountAgentService(mountable, cliMountOptions(() => traced)));
     return { ...service, stateRoot, port: config.http?.port ?? DEFAULT_HTTP_PORT };
 }
-async function maybeSeedAuth(authPath) {
-    const bytes = authSeedBytes(collectAuthSeed(process.env), await exists(authPath));
-    if (!bytes)
-        return;
-    writeFileAtomic(authPath, bytes, SECRET_FILE_MODE); // creates the directory it needs
-    log.info(`[fastagent] seeded ${authPath} from FASTAGENT_AUTH_SEED (first boot)`);
-}
 /**
  * Install the wake-ALARM sink before the scheduler starts: the first wake poll may advance a recurring entry, and that
  * save must already re-arm its alarm.

package/dist/cli/kernel.d.ts

@@ -12,6 +12,8 @@ interface ArgSpec {
 export interface FlagSpec {
     flags: string;
     description: string;
+    /** Parsed but left out of help: an internal seam between two fastagent processes, not a user-facing flag. */
+    hidden?: boolean;
 }
 interface ExampleSpec {
     cmd: string;

package/dist/cli/kernel.js

@@ -62,7 +62,7 @@ function register(parent, spec) {
         cmd.addArgument(arg);
     }
     for (const f of spec.flags ?? [])
-        cmd.addOption(new Option(f.flags, f.description));
+        cmd.addOption(new Option(f.flags, f.description).hideHelp(f.hidden === true));
     for (const sub of spec.subcommands ?? [])
         register(cmd, sub);
     const run = spec.run;

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

@@ -0,0 +1,38 @@
+import type { Readable, Writable } from "node:stream";
+import type { LoginIO, LoginMethod } from "../engines/pi/login.ts";
+/** How a login on the box ended, as the box reports it. */
+export type RelayResult = 
+/** Logged in now: `method` is how, `path` where the box saved it. */
+{
+    ok: true;
+    provider: string;
+    method: LoginMethod;
+    path: string;
+}
+/**
+ * `--if-missing`: the box already authenticates the provider and was left alone. `source` is what does it, as the
+ * box's startup report names it (`OAuth`, `stored credential`, or an environment variable such as `OPENAI_API_KEY`).
+ */
+ | {
+    ok: true;
+    provider: string;
+    kept: string;
+} | {
+    ok: false;
+    reason: "cancelled" | "missing" | "failed";
+    message: string;
+};
+/**
+ * The box half: a {@link LoginIO} over `input`/`output`. Once `input` ends (the session dropped), every pending and
+ * later question reads as backed out, so the flow ends in `LoginCancelled` instead of waiting forever.
+ */
+export declare function stdioLoginIO(input: Readable, output: Writable): {
+    io: LoginIO;
+    result(result: RelayResult): void;
+};
+/**
+ * The terminal half: drive `io` from what the box sends on `from`, answering on `to`. Resolves with the box's
+ * `result` line when `from` ends, or `undefined` when it ended without one. A line that is not the wire (a host
+ * CLI's banner, a shell's error) goes to `passthrough`, so nothing the box printed is lost.
+ */
+export declare function relayLogin(from: Readable, to: Writable, io: LoginIO, passthrough: (line: string) => void): Promise<RelayResult | undefined>;

package/dist/cli/login-relay.js

@@ -0,0 +1,121 @@
+/**
+ * `fastagent login` split across a process boundary: the flow runs on a deployed box, and the owner's terminal renders
+ * it. The wire is {@link LoginIO} itself, one JSON object per line: the box sends what the flow asks and says
+ * (`select`, `prompt`, `abort`, `note`, `open`) and ends with ONE `result` line; the terminal answers each question by
+ * its id. The box holds the PKCE verifier and writes the credential; the terminal only shows and answers.
+ *
+ * The `result` line is the only success signal. A host's shell can drop the session and still exit 0 (Railway was
+ * seen doing so), so an ended stream without that line is a failure, whatever the exit code says.
+ */
+import { createInterface } from "node:readline";
+const send = (out, message) => void out.write(`${JSON.stringify(message)}\n`);
+/**
+ * The box half: a {@link LoginIO} over `input`/`output`. Once `input` ends (the session dropped), every pending and
+ * later question reads as backed out, so the flow ends in `LoginCancelled` instead of waiting forever.
+ */
+export function stdioLoginIO(input, output) {
+    const pending = new Map();
+    let closed = false;
+    let nextId = 1;
+    const lines = createInterface({ input });
+    lines.on("line", (line) => {
+        const answer = JSON.parse(line);
+        pending.get(answer.id)?.(answer.value ?? undefined);
+        pending.delete(answer.id);
+    });
+    lines.on("close", () => {
+        closed = true;
+        for (const settle of pending.values())
+            settle(undefined);
+        pending.clear();
+    });
+    const ask = (message, signal) => {
+        if (closed)
+            return Promise.resolve(undefined);
+        const id = nextId++;
+        return new Promise((resolve) => {
+            pending.set(id, resolve);
+            send(output, message(id));
+            signal?.addEventListener("abort", () => {
+                if (!pending.delete(id))
+                    return;
+                send(output, { type: "abort", id });
+                resolve(undefined);
+            }, { once: true });
+        });
+    };
+    return {
+        io: {
+            select: (message, options) => ask((id) => ({ type: "select", id, message, options })),
+            prompt: (message, opts) => ask((id) => ({ type: "prompt", id, message, hidden: opts?.hidden === true }), opts?.signal),
+            note: (message) => send(output, { type: "note", message }),
+            openUrl: (url) => send(output, { type: "open", url }),
+        },
+        result: (result) => {
+            send(output, { type: "result", ...result });
+            lines.close(); // nothing more is read; lets the process exit once stdout drains
+        },
+    };
+}
+/**
+ * The terminal half: drive `io` from what the box sends on `from`, answering on `to`. Resolves with the box's
+ * `result` line when `from` ends, or `undefined` when it ended without one. A line that is not the wire (a host
+ * CLI's banner, a shell's error) goes to `passthrough`, so nothing the box printed is lost.
+ */
+export function relayLogin(from, to, io, passthrough) {
+    // The box may exit before reading an answer; its result (or its absence) is what gets reported, not the EPIPE.
+    to.on("error", () => { });
+    const answer = (id, value) => send(to, { id, value: value ?? null });
+    const prompts = new Map();
+    let result;
+    const lines = createInterface({ input: from });
+    lines.on("line", (line) => {
+        const message = parse(line);
+        if (message === undefined)
+            return passthrough(line);
+        switch (message.type) {
+            case "select":
+                void io.select(message.message, message.options).then((value) => answer(message.id, value));
+                return;
+            case "prompt": {
+                const controller = new AbortController();
+                prompts.set(message.id, controller);
+                void io.prompt(message.message, { hidden: message.hidden, signal: controller.signal }).then((value) => {
+                    prompts.delete(message.id);
+                    if (!controller.signal.aborted)
+                        answer(message.id, value);
+                });
+                return;
+            }
+            case "abort":
+                prompts.get(message.id)?.abort();
+                return;
+            case "note":
+                return io.note(message.message);
+            case "open":
+                return io.openUrl(message.url);
+            case "result": {
+                const { type: _, ...rest } = message;
+                result = rest;
+                return;
+            }
+        }
+    });
+    return new Promise((resolve) => lines.on("close", () => {
+        for (const controller of prompts.values())
+            controller.abort();
+        resolve(result);
+    }));
+}
+const WIRE_TYPES = new Set(["select", "prompt", "abort", "note", "open", "result"]);
+function parse(line) {
+    if (!line.startsWith("{"))
+        return undefined;
+    try {
+        const value = JSON.parse(line);
+        return typeof value.type === "string" && WIRE_TYPES.has(value.type) ? value : undefined;
+    }
+    catch {
+        return undefined; // not ours: a host CLI printed a line that happens to start with "{"
+    }
+}

package/dist/cli/program.js

@@ -156,13 +156,30 @@ const invoke = {
 const models = {
     name: "models",
     summary: 'list the available "provider/modelId" model specs',
-    description: 'List every registered "provider/modelId" spec — use one with --model or as `model` in fastagent.config.ts.',
+    description: 'List every "provider/modelId" spec the agent in this directory can name (pi\'s built-ins, the model ' +
+        "catalogs and models.json files, its own over the machine's) — use one with --model or as `model` in " +
+        "fastagent.config.ts. Outside an agent, or with -g, list the machine's.",
     args: [{ name: "[search]", description: "case-insensitive substring filter" }],
+    flags: [
+        {
+            flags: "--refresh",
+            description: "fetch the model catalog first, into the agent's models-store.json (with -g, the machine's)",
+        },
+        { flags: "-g, --global", description: "the machine's catalog, ~/.fastagent/models-store.json" },
+    ],
     examples: [
         { cmd: "fastagent models", note: "all specs" },
         { cmd: "fastagent models claude", note: "filter; provider-name matches rank first" },
+        { cmd: "fastagent models --refresh", note: "models newer than the installed pi" },
     ],
-    run: async (args) => (await import("./commands/models.js")).runModels(args[0]),
+    notes: "A refresh asks pi.dev for the providers the scope's credentials authenticate (the agent's, or with -g the " +
+        "global auth.json and environment) and writes the answer to models-store.json. The agent's is part of the " +
+        "definition: commit it, and it ships with a deploy. The machine's (-g) is read by every agent here and does " +
+        "not ship. Nothing refreshes on its own.",
+    run: async (args, f) => (await import("./commands/models.js")).runModels(args[0], {
+        refresh: f.refresh === true,
+        global: f.global === true,
+    }),
 };
 const start = {
     name: "start",
@@ -300,7 +317,8 @@ const deploy = {
             description: "drive the target CLI to completion. Docker runs `docker compose up -d --build`; with a tunnel " +
                 "service, reads its URL and registers webhooks. Fly/Railway provision app/service + volume + " +
                 "secrets + deploy + webhook setup. AgentCore builds/pushes the arm64 image and deploys the " +
-                "stack (aws + docker CLIs). Carries your local credential (env key or OAuth auth.json). " +
+                "stack (aws + docker CLIs). A model key in the value file travels; any other credential is a login on " +
+                "the deployment itself, which --run starts once the box is up (fastagent login --deployment). " +
                 "Stops at a gate (missing CLI/daemon/login/secret) with one actionable line. Without it: prints " +
                 "the runbook",
         },
@@ -438,21 +456,41 @@ const login = {
         "agent it writes the global ~/.fastagent/.secrets/auth.json, and says so): pick a method " +
         "(subscription/OAuth or API " +
         "key), then a provider that offers it (configured status shown). [provider] takes the method from " +
-        "what that provider supports, asked only when both. An agent READS the global store for any provider " +
-        "its own file does not have, so `-g` logs in once for every agent on this machine.",
+        "what that provider supports, asked only when both. An agent READS the global store for a provider it has " +
+        "no other credential for (its own file, a models.json key, an env variable), so `-g` logs in once for every " +
+        "agent on this machine; it warns when an env variable already authenticates the provider.",
     args: [{ name: "[provider]", description: "provider id (skip the provider menu)" }],
     flags: [
         {
             flags: "-g, --global",
-            description: `store in ~/.fastagent/.secrets/auth.json — every agent here reads it for providers its own file lacks`,
+            description: `store in ~/.fastagent/.secrets/auth.json — every agent here reads it for a provider it has no other credential for`,
+        },
+        {
+            flags: "--deployment [host]",
+            description: "log in this agent's deployment instead, on the box itself (docker, fly, railway, agentcore); the host may be left out " +
+                "when the agent dir holds one host's deploy artifacts",
         },
+        { flags: "--stdio", description: "the box's half of --deployment", hidden: true },
+        { flags: "--if-missing", description: "with --stdio: keep a stored credential for the provider", hidden: true },
         NO_INPUT,
     ],
-    examples: [{ cmd: "fastagent login" }, { cmd: "fastagent login openai" }, { cmd: "fastagent login openai -g" }],
-    notes: "The positional is the PROVIDER (not a dir) — `cd` into your agent before logging in.",
+    examples: [
+        { cmd: "fastagent login" },
+        { cmd: "fastagent login openai" },
+        { cmd: "fastagent login openai -g" },
+        { cmd: "fastagent login openai-codex --deployment fly", note: "on the box" },
+    ],
+    notes: "The positional is the PROVIDER (not a dir) — `cd` into your agent before logging in. " +
+        "--deployment runs the login on the deployed box through the host's own shell (docker compose exec, fly ssh, " +
+        "railway ssh, AgentCore's command shell); this terminal shows it, opens the browser, and catches the browser's " +
+        "return to localhost (or asks you to paste that address when its port is taken). The box keeps the credential, " +
+        "so it is the only holder of that grant, and logging in again replaces it there.",
     run: async (args, f) => (await import("./commands/login.js")).runLogin(args[0], {
         global: f.global === true,
         input: f.input !== false,
+        ...(f.deployment !== undefined ? { deployment: f.deployment } : {}),
+        stdio: f.stdio === true,
+        ifMissing: f.ifMissing === true,
     }),
 };
 /**

package/dist/cli/shared.d.ts

@@ -1,8 +1,8 @@
-import { type AuthLayers } from "../engines/pi/config.ts";
 import { type LoginIO } from "../engines/pi/login.ts";
+import { type AgentModels } from "../engines/pi/agent-models.ts";
 import type { LoadedDefinition } from "../engines/pi/definition.ts";
 import type { ToolCollision } from "../engines/pi/tool.ts";
-import type { ResolvedPlacement } from "../paths.ts";
+import { type ResolvedPlacement } from "../paths.ts";
 /** How every command that runs the model enters its agent directory, in the one order that works. */
 export declare function enterAgentCommand(dirArg: string, opts: {
     model?: string;
@@ -13,7 +13,7 @@ export interface ReportableAssembly {
     agentDir: string;
     workspace: string;
     modelSpec: string;
-    auth: AuthLayers;
+    models: AgentModels;
     config: {
         thinkingLevel?: string;
     };
@@ -39,6 +39,6 @@ export declare function parsePort(value: string | undefined, source: string, fro
  */
 export declare function parseBind(value: string | undefined): string | undefined;
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. */
-export declare function reportAuth(agentDir: string, modelSpec: string, auth: AuthLayers): Promise<void>;
+export declare function reportAuth(models: AgentModels, modelSpec: string): Promise<void>;
 /** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. */
 export declare function terminalLoginIO(): LoginIO;

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 { isDeployedWorkspace } from "../paths.js";
 import { log } from "../log.js";
 import { enterAgentEnv } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
@@ -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");
@@ -87,26 +88,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}`);
@@ -122,11 +115,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);
     // 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 +190,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 +203,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";