@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/cli/serve.js

@@ -0,0 +1,248 @@
+/**
+ * The serving spine shared by `dev` (its worker) and `start`: channel assembly, Node HTTP binding,
+ * long-connection lifecycle, scheduler lifecycle, and the optional Cloudflare quick tunnel.
+ */
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { controlRoutes } from "../channels/control.js";
+import { INVOKE_EXAMPLE_BODY, createInvokeHandler } from "../channels/http.js";
+import { text } from "../channels/respond.js";
+import { loadChannels } from "../engines/pi/channel.js";
+import { reportModuleLoadFailures } from "../engines/pi/report.js";
+import { parseRouteKey, router, serveNode } from "../host/node.js";
+import { log } from "../log.js";
+import { openExternalUrl } from "../open-url.js";
+import { loadSchedules } from "../schedule/discover.js";
+import { createScheduler } from "../schedule/scheduler.js";
+import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
+import { failStartup } from "./fail.js";
+/**
+ * The surface this deployment serves: default `GET /health` plus discovered channels, or the default
+ * POST `/invoke` only when neither a route nor a long-connection channel was declared.
+ */
+export async function routesFor(workspaceDir, agent, stateRoot, control) {
+    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(workspaceDir, {
+        agent,
+        stateRoot,
+        control,
+    });
+    for (const c of collisions) {
+        console.error(`[fastagent] warn: channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
+    }
+    reportModuleLoadFailures(failures);
+    if (failures.length > 0 || collisions.length > 0) {
+        throw new Error(`channel setup is invalid (${failures.length} load failure(s), ${collisions.length} route collision(s)) — ` +
+            `fix it, or rename an intentionally disabled file to *.disabled`);
+    }
+    const builtinInvoke = Object.keys(routes).length === 0 && longConnections.length === 0;
+    const channels = builtinInvoke ? { "POST /invoke": createInvokeHandler(agent) } : routes;
+    const healthCovered = Object.keys(channels).some((key) => {
+        const entry = parseRouteKey(key);
+        return entry.path === "/health" && (entry.method === undefined || entry.method === "GET");
+    });
+    let ready = longConnections.length === 0;
+    const health = () => (ready ? text("ok\n", 200) : text("starting\n", 503));
+    return {
+        routes: healthCovered ? channels : { "GET /health": health, ...channels },
+        longConnections,
+        routeChannels,
+        builtinInvoke,
+        markReady() {
+            ready = true;
+        },
+    };
+}
+/**
+ * Mount the session control plane (`/control/*`) when the workspace enabled it
+ * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
+ * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
+ * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
+ * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
+ * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
+ * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
+ * and silently shadowing either side would serve a surface the author didn't write.
+ */
+export function mountSessionControl(routes, control, stateRoot, options = {}) {
+    if (!control)
+        return { routes, announce: () => { } };
+    const token = crypto.randomUUID();
+    const mounted = controlRoutes(control, { token, agent: options.agent });
+    // PATH-level collision, matching the router's semantics (an any-method "/control/dispatch"
+    // channel key would dodge an exact-key check yet still shadow the method-qualified control
+    // route at match time — the router matches by path first).
+    const mountedPaths = new Set(Object.keys(mounted).map((key) => parseRouteKey(key).path));
+    const collisions = Object.keys(routes).filter((key) => mountedPaths.has(parseRouteKey(key).path));
+    if (collisions.length > 0) {
+        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the session control plane — ` +
+            `rename the channel route or disable sessionControl in fastagent.config`);
+    }
+    return {
+        routes: { ...routes, ...mounted },
+        announce: (boundPort) => {
+            // The state root normally exists (the opener mkdirs the sessions dir under it), but an
+            // external --sessions-dir leaves it uncreated — and announce runs inside serve's listening
+            // callback, where a throw is an unhandled rejection, not a one-line startup diagnostic.
+            mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+            const path = join(stateRoot, "control.json");
+            // Atomic (tmp+rename, the state.ts pattern): attach re-reads this file exactly during the
+            // restart window — a torn read would be misdiagnosed as "serve gone".
+            const tmp = `${path}.tmp`;
+            writeFileSync(tmp, `${JSON.stringify({ url: `http://127.0.0.1:${boundPort}`, token })}\n`, { mode: 0o600 });
+            chmodSync(tmp, 0o600); // an existing file keeps its old mode on rewrite — pin it
+            renameSync(tmp, path);
+            log.info(`[fastagent] session control on /control/* (token in ${path})`);
+            // The serve binds ALL interfaces (containers require it), so /control/* is LAN-reachable
+            // with the bearer token as the only protection — the tunnel and deploy paths warn loudly,
+            // and the LAN path must not be the silent third way past the local trust story.
+            log.warn("[fastagent] the port binds all interfaces: /control/* is reachable on your LAN, protected only by " +
+                "the bearer token — firewall the port or wrap it for real exposure (docs: design §14)");
+            if (options.tunnel) {
+                // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC
+                // (beyond even the LAN reach the mount already warned about). The operator asked for the tunnel (webhooks), but must not DISCOVER the control
+                // plane went public with it — say it loudly.
+                log.warn("[fastagent] --tunnel exposes /control/* (steer/abort/set_model) at the public tunnel URL, " +
+                    "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs: design §14)");
+            }
+            // Best-effort lifecycle end: a clean exit removes the discovery file so a later `attach`
+            // fails with "cannot read" (accurate) instead of a stale token's misleading 401/ECONNREFUSED.
+            const unlink = () => {
+                try {
+                    rmSync(path, { force: true });
+                }
+                catch {
+                    /* the file is advisory — exit must not fail on it */
+                }
+            };
+            // Signal handlers MUST NOT absorb termination: registering any listener disables Node's
+            // default kill, so clean up and RE-RAISE. The mechanism: `process.kill` delivery is ASYNC —
+            // it lands after the current emit completes, so every listener of this same emit (scheduler
+            // stop, tunnel close — regardless of registration order) runs first, and the re-raised
+            // signal then hits the default action because each `once` handler is already consumed. When
+            // some listener exits the process itself (the tunnel path calls process.exit(0)), the
+            // re-raise is harmless redundancy. Without this, the first Ctrl+C would leave the serve
+            // alive minus its control.json, and dev's watch restart (SIGTERM → wait for exit → respawn)
+            // would hang on a worker that never exits.
+            const unlinkAndReraise = (signal) => () => {
+                unlink();
+                process.kill(process.pid, signal);
+            };
+            process.once("SIGINT", unlinkAndReraise("SIGINT"));
+            process.once("SIGTERM", unlinkAndReraise("SIGTERM"));
+            process.once("exit", unlink);
+        },
+    };
+}
+/**
+ * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
+ * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
+ * the sole clean-shutdown command.
+ */
+export function serve(surface, port, onListening) {
+    const hosted = serveNode(router(surface.routes), { port });
+    const abort = new AbortController();
+    let stopping = false;
+    const stop = (exitCode) => {
+        if (stopping)
+            return;
+        stopping = true;
+        abort.abort();
+        const deadline = setTimeout(() => process.exit(exitCode), 1_000);
+        void hosted
+            .close()
+            .catch(() => { })
+            .finally(() => {
+            clearTimeout(deadline);
+            process.exit(exitCode);
+        });
+        // Preserve the existing no-drain shutdown contract: stop accepting first, then cut active streams.
+        hosted.closeAllConnections();
+    };
+    process.once("SIGINT", () => stop(0));
+    process.once("SIGTERM", () => stop(0));
+    hosted.listening.then(async (boundPort) => {
+        try {
+            const runs = surface.longConnections.map((connection) => {
+                const run = connection.connect(abort.signal);
+                if (run === null ||
+                    typeof run !== "object" ||
+                    typeof run.ready?.then !== "function" ||
+                    typeof run.closed?.then !== "function") {
+                    throw new Error(`${connection.name} connect(signal) must return { ready: Promise, closed: Promise }`);
+                }
+                void run.closed.then(() => {
+                    if (!abort.signal.aborted)
+                        failStartup(new Error(`${connection.name} closed unexpectedly`));
+                }, (error) => {
+                    if (!abort.signal.aborted)
+                        failStartup(new Error(`${connection.name} failed: ${String(error)}`));
+                });
+                return { connection, run };
+            });
+            await Promise.all(runs.map(async ({ connection, run }) => {
+                await run.ready;
+                if (!abort.signal.aborted)
+                    log.info(`[fastagent] long connection ready: ${connection.name}`);
+            }));
+            // Shutdown raced startup: a pre-ready abort settles `ready` as cancellation, not readiness —
+            // stop() already owns the exit; don't mark ready or report a surface being torn down.
+            if (abort.signal.aborted)
+                return;
+            surface.markReady();
+            process.send?.({
+                type: "ready",
+                port: boundPort,
+                routeChannels: surface.routeChannels,
+            });
+            log.info(`[fastagent] http host on :${boundPort}`);
+            log.info(`[fastagent] routes: ${Object.keys(surface.routes).join(", ") || "(none)"}`);
+            if (surface.longConnections.length > 0) {
+                log.info(`[fastagent] long connections: ${surface.longConnections.map((connection) => connection.name).join(", ")}`);
+            }
+            if (surface.builtinInvoke) {
+                log.info(`[fastagent] try it: curl -s localhost:${boundPort}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`);
+            }
+            onListening?.(boundPort);
+        }
+        catch (error) {
+            abort.abort();
+            const closing = hosted.close().catch(() => { });
+            hosted.closeAllConnections();
+            await closing;
+            failStartup(error);
+        }
+    }, (error) => {
+        if (error.code === "EADDRINUSE")
+            failStartup(new Error(`port ${port} is already in use; choose another with --port`));
+        failStartup(new Error(`cannot bind http channel on :${port}: ${error.message}`));
+    });
+}
+/** Start a Cloudflare tunnel for route channels only. */
+export function maybeTunnel(workspaceDir, routeChannels, boundPort, tunnel, stateRoot) {
+    if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
+        return;
+    void startCloudflareTunnel(boundPort).then((instance) => {
+        if (!instance)
+            return;
+        void announceWebhooks(workspaceDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
+        const cleanup = () => instance.close();
+        process.once("SIGINT", cleanup);
+        process.once("SIGTERM", cleanup);
+    });
+}
+/**
+ * Load and start the workspace's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
+ * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals.
+ */
+export async function startSchedules(workspaceDir, agent, stateRoot, selfSchedule) {
+    const { schedules, failures } = await loadSchedules(workspaceDir).catch(failStartup);
+    reportModuleLoadFailures(failures);
+    if (schedules.length === 0 && !selfSchedule)
+        return;
+    const scheduler = createScheduler({ agent, stateRoot, schedules });
+    scheduler.start();
+    if (schedules.length > 0)
+        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}`);
+    const stop = () => scheduler.stop();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+}

package/dist/cli/shared.d.ts

@@ -0,0 +1,44 @@
+import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/login.ts";
+/** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
+export declare function isInteractive(): boolean;
+/**
+ * Parse + range-check a port string (CLI flag or env). Empty/whitespace is "not set" → undefined, so
+ * the `??` chain falls through instead of binding port 0 (`Number("")` is 0). The exit code follows
+ * RESPONSIBILITY, not the layer that discovers the problem: a bad `--port` is a usage error (2), a
+ * bad `PORT` env is broken runtime configuration (1).
+ */
+export declare function parsePort(value: string | undefined, source: string, from: "flag" | "env"): number | undefined;
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
+export declare function reportAuth(modelSpec: string, authPath: string): Promise<void>;
+/**
+ * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE
+ * funnel, no dead ends. When no model is set (flag/env/config) and we're on a TTY, show the FULL
+ * catalog annotated per provider — ready (with the credential source, so which account pays is
+ * visible at the decision point) or login-required — and, when the choice needs auth, run the login
+ * flow INLINE instead of exiting with "run `fastagent login` and come back". A no-op when a model is
+ * already set; on a non-TTY (CI, a piped stdin), with `--no-input`, on cancel, or on a failed login
+ * it stays quiet and lets the caller raise its own clear error (`missing model`, or deploy's
+ * model-travel gate). The pick is exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it,
+ * and best-effort written back to the config so the next run is quiet.
+ */
+export declare function resolveFirstRunModel(workspaceDir: string, options?: {
+    model?: string;
+    authPath?: string;
+    input?: boolean;
+}): Promise<void>;
+/**
+ * Interactive login with the api_key quick-fail probe closed into a LOOP: a definitively rejected key
+ * (HTTP 401) deletes the bad credential and RE-PROMPTS immediately — the user's hands are on the
+ * keyboard NOW; parking the failure for a later `fastagent login` would waste that. The loop exits on
+ * a verified/unverifiable key (kept), an OAuth login (completing the flow already proved the
+ * credential), or cancel (LoginCancelled propagates to the caller's cancel policy). Used by both the
+ * `login` command and the first-run picker's inline login.
+ */
+export declare function loginWithKeyCheck(provider: string | undefined, authPath: string, spec?: string, seams?: {
+    flow?: (io: LoginIO, options: {
+        provider?: string;
+        authPath?: string;
+        method?: LoginMethod;
+    }) => Promise<LoginResult>;
+    verify?: (provider: string, authPath: string, spec?: string) => Promise<"ok" | "rejected" | "unknown">;
+}): Promise<LoginResult>;

package/dist/cli/shared.js

@@ -0,0 +1,246 @@
+/**
+ * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report,
+ * first-run model resolution, and the login terminal IO. Bodies moved verbatim from cli.ts; the
+ * module-scoped flag access (`values.*`) became parameters.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { relative } 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, resolveAuthPath, resolveModel, resolveModelSpec, resolveStateRoot, rewriteConfigModel, } from "../engines/pi/config.js";
+import { ensureStateRootSelfIgnored, isUnderDir } from "../engines/pi/definition.js";
+import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
+import { createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses } from "../engines/pi/models.js";
+import { formatAuthReport } from "./auth-view.js";
+import { log } from "../log.js";
+import { openExternalUrl } from "../open-url.js";
+import { failStartup, failUsage } from "./fail.js";
+/** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+ * Parse + range-check a port string (CLI flag or env). Empty/whitespace is "not set" → undefined, so
+ * the `??` chain falls through instead of binding port 0 (`Number("")` is 0). The exit code follows
+ * RESPONSIBILITY, not the layer that discovers the problem: a bad `--port` is a usage error (2), a
+ * bad `PORT` env is broken runtime configuration (1).
+ */
+export function parsePort(value, source, from) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    if (!/^\d+$/.test(trimmed) || !isValidPort(Number(trimmed))) {
+        const message = `invalid ${source} "${value}": must be an integer 0-65535`;
+        if (from === "flag")
+            failUsage(message);
+        failStartup(new Error(message));
+    }
+    return Number(trimmed);
+}
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
+export async function reportAuth(modelSpec, authPath) {
+    const provider = providerOf(modelSpec);
+    const source = await probeAuthSource(createPiModels({ authPath }), modelSpec);
+    // Only when nothing satisfies auth do we read the store (refresh-FREE) to tell "nothing stored" from
+    // "stored but unusable" — see formatAuthReport for why. store.read warns on a corrupt file itself.
+    const stored = source === undefined
+        ? await fastagentCredentialStore(authPath)
+            .read(provider)
+            .catch(() => undefined)
+        : undefined;
+    const report = formatAuthReport(provider, authPath, source, stored);
+    log.info(`[fastagent] ${report.line}`);
+    if (report.warn)
+        log.warn(`[fastagent] ${report.warn}`);
+}
+/**
+ * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE
+ * funnel, no dead ends. When no model is set (flag/env/config) and we're on a TTY, show the FULL
+ * catalog annotated per provider — ready (with the credential source, so which account pays is
+ * visible at the decision point) or login-required — and, when the choice needs auth, run the login
+ * flow INLINE instead of exiting with "run `fastagent login` and come back". A no-op when a model is
+ * already set; on a non-TTY (CI, a piped stdin), with `--no-input`, on cancel, or on a failed login
+ * it stays quiet and lets the caller raise its own clear error (`missing model`, or deploy's
+ * model-travel gate). The pick is exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it,
+ * and best-effort written back to the config so the next run is quiet.
+ */
+export async function resolveFirstRunModel(workspaceDir, options = {}) {
+    const { config, path: configPath } = await loadConfig(workspaceDir).catch(failStartup);
+    if (resolveModelSpec(options.model, config))
+        return; // already set (flag > FASTAGENT_MODEL > config)
+    if (options.input === false)
+        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 authPath = resolveAuthPath(workspaceDir, options.authPath);
+    const models = createPiModels({ authPath });
+    const chosen = await pickWithCredentials(workspaceDir, models, authPath);
+    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
+    await persistModelChoice(workspaceDir, configPath, chosen);
+}
+/**
+ * The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy —
+ * remedy warnings for providers no login flow can fix (the choice is KEPT: model validity is
+ * independent of credentials), or the inline login for the rest. Returns the chosen spec, or
+ * undefined when the pick should be discarded (picker cancel, login cancel, a failed auth probe).
+ */
+async function pickWithCredentials(workspaceDir, models, authPath) {
+    let statuses;
+    try {
+        statuses = await providerAuthStatuses(models);
+    }
+    catch (error) {
+        // Per-provider auth throws are captured as `broken` INSIDE providerAuthStatuses; reaching here
+        // means the enumeration itself failed (getProviders / a provider with no probe-able surface) — a
+        // system fault. Surface it; the opener then still raises the clear missing-model error.
+        log.warn(`[fastagent] could not probe provider auth: ${error.message}`);
+        return undefined;
+    }
+    const r = await autocomplete({
+        message: "Choose a model for this agent",
+        options: buildModelPickerOptions(listModels(models), statuses),
+    });
+    if (isCancel(r))
+        return undefined; // cancelled: the caller raises its clear missing-model error
+    const chosen = r;
+    const provider = providerOf(chosen);
+    const status = statuses.get(provider);
+    if (status?.state === "ready")
+        return chosen; // usable now — nothing to fix
+    if (status && status.login === "none") {
+        // No login flow exists for this provider — KEEP the choice and name the remedy. The remedy depends
+        // on WHY it is not ready: a BROKEN stored credential still owns the provider (env is consulted
+        // only when nothing is stored — createPiModels), so "set the env var" would not help there.
+        if (status.state === "broken") {
+            log.warn(`[fastagent] stored auth for "${provider}" is unusable: ${status.message} — fix or remove it in ${authPath}; invokes fail until then`);
+        }
+        else {
+            log.warn(`[fastagent] "${provider}" has no interactive login — set its API key env var; invokes fail until then`);
+        }
+        return chosen;
+    }
+    // Inline login. Same leak guard as `login`: self-ignore the state root BEFORE a credential
+    // can land in-tree, so the secret is never untracked-but-committable.
+    const stateRoot = resolveStateRoot(workspaceDir);
+    if (isUnderDir(authPath, stateRoot))
+        await ensureStateRootSelfIgnored(workspaceDir, stateRoot);
+    try {
+        // Verified against the CHOSEN model — the exact request the agent is about to make; a rejected
+        // key re-prompts inside the loop, so reaching here means a usable (or at worst unverifiable) key.
+        await loginWithKeyCheck(provider, authPath, chosen);
+        console.error(`[fastagent] logged in to ${provider} — saved to ${authPath}`);
+    }
+    catch (error) {
+        if (error instanceof LoginCancelled)
+            return undefined; // user backed out — discard the choice, like a picker cancel
+        // A FAILED login keeps the choice: the pick persists, the startup auth report names the remedy,
+        // and a later `fastagent login` fixes auth without re-picking the model.
+        log.warn(`[fastagent] login for "${provider}" failed: ${error.message} — model saved; run \`fastagent login\` to fix auth`);
+    }
+    return chosen;
+}
+/**
+ * Interactive login with the api_key quick-fail probe closed into a LOOP: a definitively rejected key
+ * (HTTP 401) deletes the bad credential and RE-PROMPTS immediately — the user's hands are on the
+ * keyboard NOW; parking the failure for a later `fastagent login` would waste that. The loop exits on
+ * a verified/unverifiable key (kept), an OAuth login (completing the flow already proved the
+ * credential), or cancel (LoginCancelled propagates to the caller's cancel policy). Used by both the
+ * `login` command and the first-run picker's inline login.
+ */
+export async function loginWithKeyCheck(provider, authPath, spec, 
+// Test seams: this loop DESTROYS credential state on `rejected`, so its policy (rejected → delete →
+// re-ask ONLY the key) is pinned by a test through fake flow/verify; production callers omit both.
+seams = {}) {
+    const flow = seams.flow ?? loginFlow;
+    const verify = seams.verify ?? verifyApiKeyLogin;
+    const io = terminalLoginIO();
+    let method;
+    for (;;) {
+        const result = await flow(io, { provider, authPath, method });
+        if (result.method !== "api_key")
+            return result;
+        const verdict = await verify(result.provider, authPath, spec);
+        if (verdict !== "rejected")
+            return result;
+        // Retry re-asks ONLY the key: the provider/method choices weren't the mistake, the keystrokes were.
+        provider = result.provider;
+        method = "api_key";
+    }
+}
+/**
+ * Quick-fail check after an api_key login (OAuth needs none — completing the flow already proved the
+ * credential): probe the stored key with one minimal request against `spec`, or the provider's first
+ * model. Policy over {@link probeApiKey}'s verdict: `rejected` (definitive HTTP 401) DELETES the
+ * just-stored credential — a mistyped key must not persist as plausible state — and the caller
+ * ({@link loginWithKeyCheck}) re-prompts; `unknown` (network, quota, permissions) keeps it and prints
+ * the provider's message: the key may still be right, and wrongly destroying a good credential costs
+ * more than keeping a doubtful one.
+ */
+async function verifyApiKeyLogin(provider, authPath, spec) {
+    const models = createPiModels({ authPath });
+    const model = spec ? resolveModel(models, spec) : models.getProvider(provider)?.getModels()[0];
+    if (!model) {
+        console.error(`[fastagent] cannot verify the key: provider "${provider}" lists no models — kept as stored`);
+        return "unknown";
+    }
+    const label = `${model.provider}/${model.id}`;
+    console.error(`[fastagent] verifying the key with ${label}…`);
+    const probe = await probeApiKey(models, model);
+    if (probe.state === "ok") {
+        console.error(`[fastagent] key verified — ${label} responded`);
+    }
+    else if (probe.state === "rejected") {
+        await fastagentCredentialStore(authPath).delete(provider);
+        console.error(`[fastagent] ${provider} rejected the API key (HTTP 401): ${probe.message} — enter it again (or cancel)`);
+    }
+    else {
+        console.error(`[fastagent] could not verify the key with ${label}: ${probe.message} — kept; invokes surface the provider's error`);
+    }
+    return probe.state;
+}
+/** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. Shared
+ *  by the `login` command and the first-run picker's inline login. */
+function terminalLoginIO() {
+    return {
+        async select(message, options) {
+            const r = await (options.length > 7 ? autocomplete : select)({ message, options });
+            return isCancel(r) ? undefined : r;
+        },
+        async prompt(message, opts) {
+            const r = opts?.hidden
+                ? await password({ message, signal: opts.signal })
+                : await clackText({ message, signal: opts?.signal });
+            return isCancel(r) ? undefined : r;
+        },
+        note: (message) => clackLog.info(message),
+        openUrl: openExternalUrl,
+    };
+}
+/**
+ * Best-effort persist the picked model so the next run does not prompt. Rewrites the commented
+ * `model:` placeholder the scaffold writes / an existing `model:` line, or re-inserts the line into a
+ * scaffold-shaped config (the hand-deleted-to-reset case); anything else (zero-config, a hand-shaped
+ * config) is left untouched with a printed hint. Never throws — persistence is a convenience.
+ */
+async function persistModelChoice(workspaceDir, configPath, spec) {
+    const hint = () => console.error(
+    // No "using it for this run" promise: deploy's model-travel gate rightly ignores the un-persisted pick.
+    `[fastagent] picked ${spec} — set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
+    if (!configPath)
+        return hint();
+    try {
+        const replaced = rewriteConfigModel(await readFile(configPath, "utf8"), spec);
+        if (!replaced)
+            return hint();
+        await writeFile(configPath, replaced);
+        console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(workspaceDir, configPath)}`);
+    }
+    catch {
+        hint();
+    }
+}