@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/cli/commands/schedule.js

@@ -5,20 +5,20 @@
  */
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { loadConfig, resolveAgentDir, resolveStateRoot } from "../../engines/pi/config.js";
+import { resolveStateRoot } from "../../paths.js";
 import { reportModuleLoadFailures } from "../../engines/pi/report.js";
 import { readRuns } from "../../schedule/audit.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { listWakeups, removeWakeup } from "../../schedule/wakeups.js";
-import { failStartup } from "../fail.js";
+import { failStartup, placementOrExit } from "../fail.js";
 /**
  * `fastagent schedule history <name> [dir]`: print the run audit for one schedule (or "wake") — fired
  * time, outcome, duration, reply/error. Read-only (reads `<stateRoot>/schedule/runs.jsonl`); the answer
  * to "did last night's run silently fail?". Text mode previews the reply/error; --json is the full record.
  */
 export function runScheduleHistory(name, dirArg, json) {
-    const target = resolve(dirArg);
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
     loadDotEnv(target); // FASTAGENT_STATE_DIR may live in .env — read the SAME state root the scheduler wrote
     const runs = readRuns(resolveStateRoot(target), name);
     if (json) {
@@ -45,11 +45,9 @@ export function runScheduleHistory(name, dirArg, json) {
 /** `fastagent schedule list [dir]`: everything that will fire — BOTH producers: the static `schedules/`
  *  files (with their next instant) and the agent's pending self-scheduled wake-ups. Read-only. */
 export async function runScheduleList(dirArg, json) {
-    const target = resolve(dirArg);
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
     loadDotEnv(target);
-    const { config } = await loadConfig(target).catch(failStartup);
-    const agentDir = resolveAgentDir(target, config);
-    const { schedules, failures } = await loadSchedules(agentDir).catch(failStartup);
+    const { schedules, failures } = await loadSchedules(target).catch(failStartup);
     reportModuleLoadFailures(failures);
     const wakeups = listWakeups(resolveStateRoot(target));
     if (json) {
@@ -75,7 +73,7 @@ export async function runScheduleList(dirArg, json) {
 /** `fastagent schedule cancel <id> [dir]`: remove a pending wake-up — the operator's kill switch (the
  *  agent's own is the `unwake` tool). Unlike unwake it is NOT session-scoped: the operator owns the box. */
 export function runScheduleCancel(id, dirArg) {
-    const target = resolve(dirArg);
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
     loadDotEnv(target);
     if (removeWakeup(resolveStateRoot(target), id)) {
         // ponytail: the store's load→save is lock-free — a serving scheduler's claim-advance can race this

package/dist/cli/commands/start.js

@@ -4,84 +4,147 @@
  */
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { authSeedBytes } from "../../deploy/fly/run.js";
+import { authSeedBytes, collectAuthSeed } from "../../deploy/fly/run.js";
 import { loadDotEnv } from "../../env.js";
-import { defaultAuthPath, resolveAuthPathOverride, resolveSessionsDirOverride, resolveStateRoot, } from "../../engines/pi/config.js";
+import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
+import { resolveSecretsDir, workspaceHint } from "../../paths.js";
 import { isUnderDir } from "../../engines/pi/definition.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
-import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
+import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { log, setLogLevel } from "../../log.js";
+import { createWakeAlarmSink, reconcileWakeAlarms } from "../../schedule/wake-alarm.js";
+import { setWakeupsSink } from "../../schedule/wakeups.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
-import { exists } from "../../scaffold/init.js";
-import { failStartup } from "../fail.js";
-import { maybeTunnel, routesFor, serve, startSchedules } from "../serve.js";
-import { parsePort, reportAuth, resolveFirstRunModel } from "../shared.js";
+import { exists } from "../../paths.js";
+import { failStartup, placementOrExit } from "../fail.js";
+import { maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
+import { parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const dir = resolve(dirArg);
-    setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
+    // Flag validation first: a bad --port is a USAGE error (exit 2), and reporting it must not depend on
+    // the directory being an agent (which is a runtime/environment failure, exit 1).
     const portFlag = parsePort(opts.port, "--port", "flag");
-    loadDotEnv(dir);
+    const placement = placementOrExit(dir);
+    setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
+    loadDotEnv(placement.agentDir);
     installProxyFetch();
-    await resolveFirstRunModel(dir, opts);
+    await resolveFirstRunModel(placement.agentDir, opts);
     // A `deploy --run` may carry the operator's local credential as FASTAGENT_AUTH_SEED —
-    // materialize it onto the writable state root BEFORE the opener resolves auth (once, absent-only).
-    const authPathOverride = resolveAuthPathOverride(opts.authPath);
-    await maybeSeedAuth(authPathOverride ?? defaultAuthPath(resolveStateRoot(dir)));
+    // materialize it into the writable secrets dir BEFORE the opener resolves auth (once, absent-only).
+    // Same resolveAuthPath the opener uses — ONE owner of the flag > env > default chain.
+    await maybeSeedAuth(resolveAuthPath(placement.agentDir, opts.authPath));
     // The same opener dev uses (single assembly source), just no watch.
     const sessionsDirOverride = resolveSessionsDirOverride(opts.sessionsDir);
-    const { agent, definition, agentDir, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await createPiAgentFromWorkspace(dir, {
+    const { agent, definition, agentDir, workspace, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, sessionControl, } = await createPiAgentFromDir(dir, {
         model: opts.model,
         sessionsDir: sessionsDirOverride,
-        authPath: authPathOverride,
+        authPath: opts.authPath,
         serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
     }).catch(failStartup);
-    log.info(`[fastagent] start:  ${dir}`);
-    if (agentDir !== dir)
-        log.info(`[fastagent] agent:  ${agentDir}`);
-    log.info(`[fastagent] model:  ${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
+    reportLine("agent", agentDir);
+    reportLine("workspace", workspace);
+    reportWorkspaceHint(workspaceHint({ agentDir, workspace }));
+    reportLine("model", `${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
     await reportAuth(modelSpec, authPath);
-    log.info(`[fastagent] context: ${definition.contextFiles.map((f) => f.path).join(", ") || "(none)"}`);
+    reportLine("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
     if (definition.persona)
-        log.info(`[fastagent] persona: persona.md`);
-    log.info(`[fastagent] skills: ${definition.skills.map((s) => s.name).join(", ") || "(none)"}`);
+        reportLine("persona", "persona.md");
+    reportLine("skills", definition.skills.map((s) => s.name).join(", ") || "(none)");
     if (toolNames.length > 0)
-        log.info(`[fastagent] tools:  ${toolNames.join(", ")}`);
+        reportLine("tools", toolNames.join(", "));
     if (deferredToolNames.length > 0) {
-        log.info(`[fastagent] deferred: ${deferredToolNames.join(", ")} (activated via search_tools)`);
+        reportLine("deferred", `${deferredToolNames.join(", ")} (activated via search_tools)`);
     }
     reportToolCollisions(toolCollisions);
     reportModuleLoadFailures(toolFailures);
-    log.info(`[fastagent] state:  ${stateRoot}`);
-    log.info(`[fastagent] sessions: ${sessionsDir}`);
-    // State defaults under the definition dir, which a redeploy may replace wholesale. Gate on where the
-    // root ACTUALLY resolved (in-tree?), not on the raw env var: an empty `FASTAGENT_STATE_DIR=""` reads
-    // as unset (resolveStateRoot) and still lands in-tree, so a raw `=== undefined` check would wrongly
-    // silence the warning. A sessions/auth override to a volume does not help — channel state (the
-    // telegram turn/context files replay depends on) is still in-tree.
-    if (isUnderDir(stateRoot, dir)) {
-        log.info(`[fastagent] note: state (auth, sessions, channel state) lives under the definition dir; point ` +
+    reportLine("state", stateRoot);
+    reportLine("sessions", sessionsDir);
+    // State defaults under the agent dir, which a redeploy may replace wholesale. Gate on where the
+    // state root ACTUALLY resolved (inside the agent dir?), not on the raw env var: an empty
+    // `FASTAGENT_STATE_DIR=""` reads as unset (resolveStateRoot) and still lands in-agent, so a raw
+    // `=== undefined` check would wrongly silence the warning. A sessions override to a volume does not
+    // help — channel state (the telegram turn/context files replay depends on) is still in-agent.
+    // (auth.json is NOT under the state root — it lives in the secrets dir, resolveSecretsDir.)
+    if (isUnderDir(stateRoot, agentDir)) {
+        log.info(`[fastagent] note: state (sessions, channel state) lives under the definition dir; point ` +
             `FASTAGENT_STATE_DIR at a persistent volume so a redeploy that replaces the dir does not wipe it.`);
     }
+    // The secrets dir is the SAME trap on a different lifecycle: auth.json is MACHINE-WRITTEN (OAuth
+    // rotation), so the copy under the definition dir is the only valid one — a redeploy that replaces
+    // the dir loses a credential no re-seed can restore. An independent check on purpose: moving ONE
+    // of the two to a volume must not silence the note about the other.
+    if (isUnderDir(resolveSecretsDir(agentDir), agentDir)) {
+        log.info(`[fastagent] note: secrets (.env, rotated auth.json) live under the definition dir; point ` +
+            `FASTAGENT_SECRETS_DIR at a persistent volume so a redeploy that replaces the dir does not wipe them.`);
+    }
     reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+    // AgentCore Runtime posture (FASTAGENT_AGENTCORE=1, set by the generated deploy artifacts): the
+    // adapter (POST /invocations + GET /ping) is the container's only reachable surface, and cron
+    // slots arrive from the external clock through it — so no resident cron timers. In particular,
+    // do NOT mount the ordinary unauthenticated POST /invoke fallback: a selfSchedule-only topology
+    // needs a public Function URL for wake callbacks, and its forwarder can relay arbitrary paths.
+    const agentcore = process.env.FASTAGENT_AGENTCORE === "1";
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
-    const routes = await routesFor(agentDir, traced, stateRoot).catch(failStartup);
-    await startSchedules(agentDir, traced, stateRoot, config.selfSchedule ?? false);
-    serve(routes, portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, (p) => maybeTunnel(agentDir, p, opts.tunnel ?? false));
+    const routed = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: !agentcore }).catch(failStartup);
+    const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
+        tunnel: opts.tunnel ?? false,
+        agent: traced,
+    });
+    // AgentCore + selfSchedule: register the wake-ALARM sink BEFORE the scheduler starts — the boot
+    // wake pump may advance a recurring entry (a store save) and that save must already re-arm its
+    // alarm. The secret arrives via the stack (FASTAGENT_WAKE_SECRET); without it the deployment
+    // degrades to awake-only wakes — warned, never silent.
+    let onStateReady;
+    if (agentcore && config.selfSchedule) {
+        const wakeSecret = process.env.FASTAGENT_WAKE_SECRET;
+        if (wakeSecret) {
+            const sink = createWakeAlarmSink({ secret: wakeSecret });
+            setWakeupsSink(sink);
+            // NOT here: at boot the state mount is whatever the platform just provisioned — after a runtime
+            // version update that is EMPTY, so a reconcile now would see no pending wake-ups and conclude
+            // there is nothing to re-arm. It runs once the snapshot has been restored (mountAgentcore).
+            onStateReady = () => reconcileWakeAlarms(stateRoot, sink);
+            log.info(`[fastagent] wake alarms: EventBridge-backed via the forwarder`);
+        }
+        else {
+            log.warn(`[fastagent] FASTAGENT_WAKE_SECRET is not set — wake-ups fire only while a session is awake ` +
+                `(redeploy with the current template to fix)`);
+        }
+    }
+    const schedules = await startSchedules(agentDir, traced, stateRoot, config.selfSchedule ?? false, {
+        externalClock: agentcore,
+    });
+    let routes = withControl.routes;
+    if (agentcore) {
+        try {
+            routes = mountAgentcore(routes, { agent: traced, stateRoot, schedules, onStateReady });
+        }
+        catch (e) {
+            failStartup(e);
+        }
+        log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
+    }
+    serve({ ...routed, routes }, portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, (p) => {
+        withControl.announce(p);
+        maybeTunnel(agentDir, routed.routeChannels, p, opts.tunnel ?? false, stateRoot);
+    });
     // No graceful drain: webhook turns run fire-and-forget; SIGTERM just exits mid-turn. Whether an
     // in-flight turn is LOST depends on the channel: the Telegram channel persists turn intent pre-ACK
     // and replays it next start (turn-store.ts, L1 durable execution, at-least-once); HTTP and other
     // channels have no such layer, so their in-flight turns are still lost (the asker re-invokes).
 }
 /**
- * Materialize `FASTAGENT_AUTH_SEED` (base64 of an auth.json, set by `deploy --run`) onto the
- * writable state root ONCE — only when the seed is set AND the auth file is absent, so a refreshed
+ * Materialize `FASTAGENT_AUTH_SEED` (base64 of an auth.json, set by `deploy --run`) into the
+ * writable secrets dir ONCE — only when the seed is set AND the auth file is absent, so a refreshed
  * volume copy is never clobbered by the stale seed. Lets a deploy carry the operator's local
  * OAuth/API credential so the box runs on the SAME subscription. No-op locally (the seed is unset).
  */
 async function maybeSeedAuth(authPath) {
-    const bytes = authSeedBytes(process.env.FASTAGENT_AUTH_SEED, await exists(authPath));
+    // collectAuthSeed: the seed may arrive CHUNKED (FASTAGENT_AUTH_SEED + _2…) on hosts with a small
+    // env-value max length (AgentCore); single-var hosts are unchanged.
+    const bytes = authSeedBytes(collectAuthSeed(process.env), await exists(authPath));
     if (!bytes)
         return;
     await mkdir(dirname(authPath), { recursive: true });

package/dist/cli/commands/tool.js

@@ -1,19 +1,22 @@
 /** `fastagent tool <name> '<json>' [dir]`: run one tool's body directly with JSON args — no model. */
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
-import { resolveWorkspaceTools } from "../../engines/pi/create.js";
+import { loadConfig } from "../../engines/pi/config.js";
+import { resolveAgentTools } from "../../engines/pi/create.js";
 import { reportModuleLoadFailures } from "../../engines/pi/report.js";
-import { failStartup, failUsage } from "../fail.js";
+import { turnContext } from "../../engines/pi/tool-context.js";
+import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runTool(name, argsJson, dirArg) {
-    const toolDir = resolve(dirArg);
-    loadDotEnv(toolDir); // a tool may read a key from .env
-    const { config } = await loadConfig(toolDir).catch(failStartup);
+    // Argument shape first: malformed JSON is a USAGE error (exit 2), independent of whether the
+    // directory is an agent (a runtime failure, exit 1).
+    const args = parseToolArgs(argsJson);
+    const { agentDir, workspace } = placementOrExit(resolve(dirArg));
+    loadDotEnv(agentDir); // a tool may read a key from .env
+    const { config } = await loadConfig(agentDir).catch(failStartup);
     // The same tool set dev/start mount (defaults + config.tools + discovered, deduped), so the runner
-    // exercises exactly what gets served — a shadowed tool is surfaced, not silently run. Resolve agentDir
-    // like the openers so `fastagent tool` finds the SAME tools/ as dev/start when config.agentDir is set.
-    const agentDir = resolveAgentDir(toolDir, config);
-    const { tools, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, toolDir).catch(failStartup);
+    // exercises exactly what gets served — a shadowed tool is surfaced, not silently run. Resolve the
+    // placement like the openers, so `fastagent tool` finds the SAME tools/ as dev/start.
+    const { tools, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir, workspace).catch(failStartup);
     for (const c of toolCollisions) {
         console.error(`[fastagent] warn: tool "${c.name}" (${c.source}) is shadowed by a default/config tool — not mounted`);
     }
@@ -22,16 +25,18 @@ export async function runTool(name, argsJson, dirArg) {
     if (!tool) {
         failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
     }
-    let args;
-    try {
-        args = JSON.parse(argsJson);
-    }
-    catch {
-        failUsage(`invalid JSON args: ${argsJson}`); // malformed input syntax = usage error, exit 2
-    }
-    const result = await tool.execute(`cli-${name}`, args).catch(failStartup);
+    const result = await turnContext.run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args)).catch(failStartup);
     const out = result?.details !== undefined
         ? result.details
         : (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");
     console.log(typeof out === "string" ? out : JSON.stringify(out, null, 2));
 }
+/** Parse the CLI's JSON args blob; malformed input syntax is a usage error (exit 2). */
+function parseToolArgs(argsJson) {
+    try {
+        return JSON.parse(argsJson);
+    }
+    catch {
+        failUsage(`invalid JSON args: ${argsJson}`);
+    }
+}

package/dist/cli/fail.d.ts

@@ -1,5 +1,4 @@
-/** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
-export declare function stderrHasColors(): boolean;
+import { type ResolvedPlacement } from "../paths.ts";
 /**
  * The ONE error prefix every error message carries — bold red when stderr renders color, plain
  * otherwise. Errors are the only place the CLI uses color at all.
@@ -11,6 +10,22 @@ export declare function errorPrefix(colors?: boolean): string;
  * Shared by the kernel and the command modules; exit 1 (runtime failure).
  */
 export declare function failStartup(error: unknown): never;
+/**
+ * THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. Every
+ * command that needs an agent goes through this — the try/catch was hand-repeated at sixteen call
+ * sites, which is sixteen chances to forget it (`dev`'s supervisor did, and surfaced a raw stack).
+ *
+ * The catch is what makes it a function at all: placement resolves SYNCHRONOUSLY, before any promise
+ * exists, so it cannot ride the `.catch(failStartup)` every async startup chain carries — and its
+ * refusals ("not a fastagent agent", plus the two dead ends with their own exits) are user-fixable,
+ * which means a one-line `Error:` and exit 1, never a stack.
+ *
+ * Not every command calls it — and the exceptions are the useful part of this note. `init` CREATES the
+ * agent (it must run where there is none). `models` is directory-independent. `login` needs one only for
+ * the project-level credential and falls back to the global one, and `attach --url/--token` reads
+ * nothing local. Everything else needs an agent, so it comes through here.
+ */
+export declare function placementOrExit(dir: string): ResolvedPlacement;
 /**
  * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination
  * discovered in a command body): print the message and exit 2 — the same class as a parse error.

package/dist/cli/fail.js

@@ -1,5 +1,6 @@
+import { resolvePlacement } from "../paths.js";
 /** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
-export function stderrHasColors() {
+function stderrHasColors() {
     return process.stderr.isTTY === true && (process.stderr.hasColors?.() ?? false);
 }
 /**
@@ -21,6 +22,29 @@ export function failStartup(error) {
         console.error(errorPrefix(), error);
     process.exit(1);
 }
+/**
+ * THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. Every
+ * command that needs an agent goes through this — the try/catch was hand-repeated at sixteen call
+ * sites, which is sixteen chances to forget it (`dev`'s supervisor did, and surfaced a raw stack).
+ *
+ * The catch is what makes it a function at all: placement resolves SYNCHRONOUSLY, before any promise
+ * exists, so it cannot ride the `.catch(failStartup)` every async startup chain carries — and its
+ * refusals ("not a fastagent agent", plus the two dead ends with their own exits) are user-fixable,
+ * which means a one-line `Error:` and exit 1, never a stack.
+ *
+ * Not every command calls it — and the exceptions are the useful part of this note. `init` CREATES the
+ * agent (it must run where there is none). `models` is directory-independent. `login` needs one only for
+ * the project-level credential and falls back to the global one, and `attach --url/--token` reads
+ * nothing local. Everything else needs an agent, so it comes through here.
+ */
+export function placementOrExit(dir) {
+    try {
+        return resolvePlacement(dir);
+    }
+    catch (error) {
+        failStartup(error);
+    }
+}
 /**
  * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination
  * discovered in a command body): print the message and exit 2 — the same class as a parse error.

package/dist/{invoke-stream.d.ts → cli/invoke-stream.d.ts}

@@ -6,5 +6,5 @@
  * An errored tool inside an otherwise-completed turn still surfaces (the diagnostic the operator
  * needs); tool_ended carries no name, so it is remembered from the matching tool_started.
  */
-import type { AgentEvent } from "./agent.ts";
+import type { AgentEvent } from "../agent.ts";
 export declare function runInvokeStream(events: AsyncIterable<AgentEvent>, out: (text: string) => void, err: (line: string) => void): Promise<number>;

package/dist/{invoke-stream.js → cli/invoke-stream.js}

@@ -14,6 +14,10 @@ export async function runInvokeStream(events, out, err) {
                 if (event.isError)
                     err(`[tool] ${toolName.get(event.id) ?? event.id} failed`);
                 break;
+            case "retrying":
+                // Operator-facing: include the reason (channels show a neutral customer line instead).
+                err(`[fastagent] transient failure — retrying (${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms): ${event.reason}`);
+                break;
             case "failed":
                 err(`[fastagent] failed: ${event.details}${event.retryable ? " (retryable)" : ""}`);
                 exitCode = 1;

package/dist/cli/kernel.d.ts

@@ -13,7 +13,7 @@
  */
 import { Command } from "commander";
 /** One positional argument, in commander syntax: `<name>` required, `[dir]` optional. */
-export interface ArgSpec {
+interface ArgSpec {
     name: string;
     description: string;
     default?: string;
@@ -29,7 +29,7 @@ export interface FlagSpec {
     /** Mutually exclusive with these {@link optionKey} values — validated at build time. */
     conflicts?: string[];
 }
-export interface ExampleSpec {
+interface ExampleSpec {
     cmd: string;
     note?: string;
 }
@@ -87,3 +87,4 @@ export interface ProgramOptions {
 export declare function optionKey(flags: string): string;
 /** Build the commander program for `specs`. The CLI entry parses with it; tests inject the IO seams. */
 export declare function buildProgram(specs: readonly CommandSpec[], options?: ProgramOptions): Command;
+export {};

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

@@ -0,0 +1,21 @@
+import type { ProviderAuthStatus } from "../engines/pi/models.ts";
+/** One first-run picker entry (@clack/prompts option shape). */
+export interface ModelPickerOption {
+    value: string;
+    label: string;
+    hint: string;
+}
+/**
+ * The first-run picker menu: the FULL model catalog, each spec annotated with its provider's auth
+ * status — ready first (usable now, with the credential source so "which account pays" is visible at
+ * the decision point), then the rest with their remedy. Order within each group preserves `specs`
+ * (sorted by the caller). A broken provider (expired/corrupt credential) is annotated, not dropped —
+ * fail visibly.
+ */
+export declare function buildModelPickerOptions(specs: string[], statuses: Map<string, ProviderAuthStatus>): ModelPickerOption[];
+/** The output of `fastagent models [search]`: the spec `lines` to print to stdout (a case-insensitive
+ *  substring filter; no search → all), and an stderr `error` diagnostic when a search matches nothing. */
+export declare function formatModelsCommand(specs: string[], search?: string): {
+    lines: string[];
+    error?: string;
+};

package/dist/cli/models-view.js

@@ -0,0 +1,66 @@
+/**
+ * CLI presenter for the model-facing commands: `fastagent models [search]` output and the first-run
+ * picker's option list. Output DECISIONS live here, out of the engine config layer (config.ts owns
+ * model resolution / listModels), so this process-boundary behavior is unit-testable without
+ * spawning the CLI.
+ */
+import { providerOf } from "../engines/pi/config.js";
+/** The remedy hint for a non-ready provider, by what picking it actually does: an OAuth flow →
+ *  "login required"; an interactive key prompt → "API key required"; no flow at all → the env var. */
+function remedy(login) {
+    if (login === "oauth")
+        return "login required";
+    return login === "api_key" ? "API key required" : "API key required — set the provider's env var";
+}
+/**
+ * The first-run picker menu: the FULL model catalog, each spec annotated with its provider's auth
+ * status — ready first (usable now, with the credential source so "which account pays" is visible at
+ * the decision point), then the rest with their remedy. Order within each group preserves `specs`
+ * (sorted by the caller). A broken provider (expired/corrupt credential) is annotated, not dropped —
+ * fail visibly.
+ */
+export function buildModelPickerOptions(specs, statuses) {
+    const ready = [];
+    const rest = [];
+    for (const spec of specs) {
+        const status = statuses.get(providerOf(spec));
+        if (status?.state === "ready") {
+            ready.push({ value: spec, label: spec, hint: status.source ? `ready — ${status.source}` : "ready" });
+        }
+        else if (status?.state === "broken") {
+            // A broken stored credential OWNS the provider (env is consulted only when nothing is stored),
+            // so with no login flow the remedy is fixing the store — not the env var (which can't win here).
+            rest.push({
+                value: spec,
+                label: spec,
+                hint: status.login === "none"
+                    ? `stored auth unusable: ${status.message} — fix or remove the stored credential`
+                    : `${remedy(status.login)} — stored auth unusable: ${status.message}`,
+            });
+        }
+        else if (status) {
+            rest.push({ value: spec, label: spec, hint: remedy(status.login) });
+        }
+        else {
+            // Unreachable when `specs` and `statuses` come from the same Models (every listed provider is
+            // probed); if a caller ever mixes sources, promise nothing — neutral wording, no login claim.
+            rest.push({ value: spec, label: spec, hint: "auth required" });
+        }
+    }
+    return [...ready, ...rest];
+}
+/** The output of `fastagent models [search]`: the spec `lines` to print to stdout (a case-insensitive
+ *  substring filter; no search → all), and an stderr `error` diagnostic when a search matches nothing. */
+export function formatModelsCommand(specs, search) {
+    if (!search)
+        return { lines: specs };
+    const q = search.toLowerCase();
+    const matches = specs.filter((spec) => spec.toLowerCase().includes(q));
+    if (matches.length === 0)
+        return { lines: matches, error: `no model matches "${search}"` };
+    // Rank a PROVIDER-name match (query in the part before "/") above an incidental model-id match, so
+    // `models anthropic` leads with anthropic/* rather than burying it under amazon-bedrock/anthropic.*
+    // and google-vertex/…-anthropic-… (which only match in the model id). Order within each group is kept.
+    const providerMatch = (spec) => providerOf(spec).toLowerCase().includes(q);
+    return { lines: [...matches.filter(providerMatch), ...matches.filter((s) => !providerMatch(s))] };
+}