@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/cli/commands/login.js

@@ -1,17 +1,27 @@
 /**
  * `fastagent login [provider]`: authenticate a model provider into the project-level auth file
- * (`<agentDir>/.secrets/auth.json`) by default, or `FASTAGENT_AUTH_PATH`.
+ * (`<agentDir>/.secrets/auth.json`) by default, or `FASTAGENT_AUTH_PATH`. `--deployment` runs the same login on this
+ * workspace's deployed box instead (box-login.ts); `--stdio` is the box's half of that.
  */
-import { homedir } from "node:os";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { enterAgentEnv } from "../../env.js";
-import { resolveAuthPath } from "../../engines/pi/config.js";
-import { GLOBAL_AUTH_PATH } from "../../engines/pi/auth.js";
-import { GLOBAL_HOME_DIR, findAgentDir, placementDeadEnd } from "../../paths.js";
+import { GLOBAL_AUTH_PATH, resolveAuthPath } from "../../engines/pi/auth.js";
+import { agentModels } from "../../engines/pi/agent-models.js";
+import { DEPLOY_HOSTS } from "../../deploy/hosts.js";
+import { findAgentDir, globalHome, placementDeadEnd, resolvePlacement } from "../../paths.js";
 import { LoginCancelled, loginFlow } from "../../engines/pi/login.js";
-import { failStartup, placementOrExit } from "../fail.js";
+import { environmentAuthSource } from "../../engines/pi/models.js";
+import { loginOnBox } from "../box-login.js";
+import { failStartup, failUsage, placementOrExit } from "../fail.js";
+import { stdioLoginIO } from "../login-relay.js";
 import { isInteractive, terminalLoginIO } from "../shared.js";
+import { HOSTS } from "./deploy.js";
 export async function runLogin(provider, opts) {
+    if (opts.stdio)
+        return runStdioLogin(provider, opts);
+    if (opts.deployment !== undefined)
+        return runDeploymentLogin(provider, opts);
     const cwd = process.cwd();
     const agentDir = findAgentDir(cwd);
     // "Outside an agent" must mean exactly that.
@@ -19,9 +29,12 @@ export async function runLogin(provider, opts) {
         placementOrExit(cwd);
     // Outside any agent the target is the user-global machinery home — handed over explicitly, so the path resolvers
     // need no "is this $HOME?" special case to infer it.
-    const loginDir = agentDir ?? join(homedir(), GLOBAL_HOME_DIR);
+    const loginDir = agentDir ?? globalHome();
     // FASTAGENT_AUTH_PATH and a proxy may both be configured in the project .env, and the OAuth token exchange must go
     // through that proxy (region-locked providers).
+    // Before the agent's `.env` joins it: the shadowing check below is about what EVERY agent sees, and that is the
+    // environment the shell hands down, not one agent's value file.
+    const shellEnv = { ...process.env };
     enterAgentEnv(loginDir);
     // `-g` names the global file outright. Otherwise: FASTAGENT_AUTH_PATH > default — the one owner. The
     // store built here is deliberately UNLAYERED: reading falls back to the global file, but writing must land
@@ -32,9 +45,9 @@ export async function runLogin(provider, opts) {
     // lands somewhere no agent will read.
     if (!agentDir && !opts.global && !process.env.FASTAGENT_AUTH_PATH) {
         console.error(`[fastagent] no agent here (no fastagent.config.ts, here or one level inside) — ` +
-            `logging in GLOBALLY (${authPath}). Every agent on this machine reads this file for providers its own ` +
-            `.secrets/auth.json does not have, so this is usually what you want; \`cd\` into an agent to give that ` +
-            `one its own account instead.`);
+            `logging in GLOBALLY (${authPath}). An agent on this machine uses this file for a provider it has no ` +
+            `credential of its own for (no entry in its .secrets/auth.json, no apiKey in its models.json, no env ` +
+            `variable), so this is usually what you want; \`cd\` into an agent to give that one its own account instead.`);
     }
     // login is inherently interactive — loginFlow renders provider/method menus and opens a browser (or prompts for a
     // key).
@@ -57,5 +70,105 @@ export async function runLogin(provider, opts) {
         failStartup(error);
     });
     console.error(`[fastagent] logged in to ${result.provider} (${result.method}) — saved to ${authPath}`);
+    // The environment outranks the global file for every agent, so a global login it shadows would sit unused while
+    // agents run on, say, an API key billed per request, with only a startup line to show it.
+    const shadowedBy = authPath === GLOBAL_AUTH_PATH ? await environmentAuthSource(result.provider, shellEnv) : undefined;
+    if (shadowedBy !== undefined) {
+        console.error(`[fastagent] warning: ${result.provider} is also authenticated by ${shadowedBy} in your shell environment, which ` +
+            `agents use before the global file, so this login is not used while it is set. Unset it to use this login.`);
+    }
     process.exit(0); // the undici proxy agent's keep-alive sockets would otherwise hold the event loop open
 }
+/**
+ * `--deployment [host]`: the host is named, or the one whose generated artifact is in the agent dir. Several is a
+ * question only the operator can answer, so it is asked back rather than guessed.
+ */
+async function runDeploymentLogin(provider, opts) {
+    if (opts.global)
+        failUsage("--deployment logs the deployment in; -g names this machine's global file — pick one");
+    const placement = placementOrExit(process.cwd());
+    // The host's CLI must reach the account/region/proxy the deploy used, and those may be definition-local.
+    enterAgentEnv(placement.agentDir);
+    let host;
+    if (typeof opts.deployment === "string") {
+        if (!DEPLOY_HOSTS.includes(opts.deployment)) {
+            failUsage(`--deployment takes a host (${DEPLOY_HOSTS.join(", ")}), not "${opts.deployment}" — to name a provider too: ` +
+                `fastagent login <provider> --deployment <host>`);
+        }
+        host = opts.deployment;
+    }
+    else {
+        const found = DEPLOY_HOSTS.filter((h) => existsSync(join(placement.agentDir, HOSTS[h].artifact)));
+        if (found.length !== 1) {
+            failUsage(found.length === 0
+                ? `no deployment artifacts in ${placement.agentDir} — name the host: --deployment <${DEPLOY_HOSTS.join("|")}>`
+                : `this agent deploys to ${found.join(" and ")} — name one: --deployment <${found.join("|")}>`);
+        }
+        host = found[0];
+    }
+    const input = opts.input !== false && isInteractive();
+    if (!input) {
+        failStartup(new Error(`login is interactive (it shows a menu and opens a browser) — run it in a terminal`));
+    }
+    const failed = await loginOnBox({
+        host,
+        shell: await HOSTS[host].shell(placement).catch(failStartup),
+        placement,
+        ...(provider ? { provider } : {}),
+        input,
+    });
+    if (failed)
+        failStartup(new Error(failed));
+    process.exit(0);
+}
+/**
+ * `--stdio`: the box's half of `--deployment`. Runs where the server runs; everything it would show or ask travels as
+ * the relay wire, and it ends with exactly one result line. Never started by hand: the credential path is the one the
+ * caller exported (container.ts `boxLoginCommand`).
+ */
+async function runStdioLogin(provider, opts) {
+    const wire = stdioLoginIO(process.stdin, process.stdout);
+    const result = await stdioLogin(wire.io, provider, opts).catch((error) => error instanceof LoginCancelled
+        ? { ok: false, reason: "cancelled", message: "cancelled" }
+        : { ok: false, reason: "failed", message: error.message });
+    wire.result(result);
+    process.exitCode = result.ok ? 0 : 1;
+    // Exit once the result line is flushed: an undici keep-alive socket would otherwise hold the process open.
+    process.stdout.write("", () => process.exit());
+}
+async function stdioLogin(io, provider, opts) {
+    // `boxLoginCommand` starts this in the deployed agent directory; anywhere else there is no box to log in.
+    const agentDir = findAgentDir(process.cwd());
+    if (!agentDir)
+        throw new Error(`login --stdio: ${process.cwd()} is not an agent directory`);
+    // A deployed box has no value file to read: its variables reach this process only as the host's shell hands them
+    // down (the container's for `docker compose exec`, the platform's over fly/railway ssh), and this installs the egress
+    // proxy they name. AgentCore's command shell hands down none of the runtime's, so a proxy carried there in
+    // FASTAGENT_ENV does not reach the login (docs/deploy.md).
+    enterAgentEnv(agentDir);
+    // The model environment the serving runtime reads (createPiAgentFromDir), so "logged in" means what the server will
+    // use.
+    const models = agentModels(agentDir, {}, { cwd: resolvePlacement(agentDir).workspace });
+    const { auth } = models;
+    if (opts.ifMissing && provider) {
+        // The server's own answer (`authStatus`), the one its startup report prints. Known ceiling: nothing is asked of
+        // the provider beyond a due refresh, so a revoked grant whose access token has not expired yet, or a revoked API
+        // key, reads as held and the first turn fails with the provider's error. Asking would spend a real model call on
+        // every redeploy, which the readiness checks deliberately never do.
+        const held = await models.authStatus(provider);
+        if (held.source !== undefined)
+            return { ok: true, provider, kept: held.source };
+        if (opts.input === false) {
+            const what = held.stored
+                ? `the stored ${provider} ${held.stored} credential is expired or unusable`
+                : `no ${provider} credential`;
+            const because = held.error === undefined ? "" : ` (${held.error})`;
+            return { ok: false, reason: "missing", message: `${what}${because} in ${held.path ?? auth.path}` };
+        }
+    }
+    if (opts.input === false) {
+        return { ok: false, reason: "missing", message: `no ${provider ?? "model"} credential in ${auth.path}` };
+    }
+    const result = await loginFlow(io, { authPath: auth.path, ...(provider ? { provider } : {}), agentDir });
+    return { ok: true, provider: result.provider, method: result.method, path: auth.path };
+}

package/dist/cli/commands/logs.js

@@ -2,7 +2,7 @@
 import { basename, resolve } from "node:path";
 import { agentcoreName } from "../../deploy/agentcore/plan.js";
 import { tailAgentcoreLogs } from "../../deploy/agentcore/logs.js";
-import { spawnRunner } from "../../deploy/runner.js";
+import { awsRunner } from "../../deploy/runner.js";
 import { enterAgentEnv } from "../../env.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runLogs(host, dirArg, opts) {
@@ -20,7 +20,7 @@ export async function runLogs(host, dirArg, opts) {
         source: source,
         since: opts.since,
         follow: opts.follow === true,
-    }, spawnRunner("aws", placement.workspace), (message) => console.error(`[fastagent] logs: ${message}`));
+    }, awsRunner(placement.workspace), (message) => console.error(`[fastagent] logs: ${message}`));
     if (!outcome.ok)
         failStartup(new Error(`logs stopped: ${outcome.gate}`));
 }

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

@@ -1 +1,4 @@
-export declare function runModels(search: string | undefined): void;
+export declare function runModels(search: string | undefined, opts?: {
+    refresh?: boolean;
+    global?: boolean;
+}): Promise<void>;

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 } from "../../engines/pi/models.js";
+import { refreshMachineModelCatalog, 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 refreshMachineModelCatalog().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/invoke-stream.js

@@ -10,6 +10,9 @@ export async function runInvokeStream(events, out, err) {
                 toolName.set(event.id, event.name);
                 err(`[tool] ${event.name}`);
                 break;
+            case "tool_progress":
+                err(`[tool] ${toolName.get(event.id) ?? event.id} › ${clipStatus(event.text)}`);
+                break;
             case "tool_ended":
                 if (event.isError)
                     err(`[tool] ${toolName.get(event.id) ?? event.id} failed`);
@@ -28,3 +31,14 @@ export async function runInvokeStream(events, out, err) {
     }
     return exitCode;
 }
+/** How much of a status line a terminal gets, in code points. */
+const STATUS_MAX = 120;
+/**
+ * A `tool_progress` line clipped to {@link STATUS_MAX} code points. The event is untruncated by contract, and a shell
+ * printing one long line (`curl -s` of a JSON body) re-sends that growing line every 100 ms.
+ */
+function clipStatus(text) {
+    // Only the first STATUS_MAX + 1 code points decide the result, and they fit in twice as many UTF-16 units.
+    const head = [...text.slice(0, (STATUS_MAX + 1) * 2)];
+    return head.length > STATUS_MAX ? `${head.slice(0, STATUS_MAX).join("")}…` : head.join("");
+}

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,9 @@
-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 IndirectTool } from "../engines/pi/create.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,13 +14,13 @@ export interface ReportableAssembly {
     agentDir: string;
     workspace: string;
     modelSpec: string;
-    auth: AuthLayers;
+    models: AgentModels;
     config: {
         thinkingLevel?: string;
     };
     definition: LoadedDefinition;
     toolNames: string[];
-    deferredToolNames: string[];
+    indirectTools: IndirectTool[];
     toolCollisions: ToolCollision[];
 }
 /** What `dev` and `start` say about the directory they just opened, in the order they say it. */
@@ -39,6 +40,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;