@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/engines/pi/invoke.js

@@ -1,5 +1,6 @@
 import { DEFAULT_COMPACTION_SETTINGS, calculateContextTokens, shouldCompact } from "@earendil-works/pi-agent-core";
-import { SESSION_BUSY_CODE } from "../../agent.js";
+import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
+import { abortFirstIterator } from "../../collect.js";
 import { log } from "../../log.js";
 import { TOOL_ACTIVATION_ENTRY, harnessSession } from "./harness.js";
 import { additiveActivation, turnContext } from "./tool-context.js";
@@ -95,21 +96,109 @@ function messageSignal(message) {
     }
     return {};
 }
-/** In-stream event mapping. Non text/tool_* pi events (turn_start, message_start, …) are dropped. */
-function toAgentEvent(pe) {
+/**
+ * In-stream event mapping — pi events are translated ONCE into the rich `SessionEvent` vocabulary;
+ * the SPEC `AgentEvent` stream is a narrow {@link projectAgentEvent} of it (design §6: one
+ * translation plus one projection, never two parallel translations). pi events with no session
+ * vocabulary yet (turn_start, agent_start, …) are dropped.
+ */
+export function toSessionEvent(pe, runId) {
+    const at = Date.now();
     switch (pe.type) {
+        case "queue_update":
+            return {
+                type: "queue_changed",
+                timestamp: at,
+                runId,
+                data: { steering: pe.steer.length, followUp: pe.followUp.length },
+            };
+        case "message_start":
+            // Assistant streaming only — a user/toolResult message is not a live message boundary.
+            if (pe.message.role !== "assistant")
+                return null;
+            return { type: "message_started", timestamp: at, runId, data: {} };
         case "message_update": {
             const ev = pe.assistantMessageEvent;
-            if (ev.type === "text_delta")
-                return { type: "text", delta: ev.delta };
-            if (ev.type === "thinking_delta")
-                return { type: "thinking", delta: ev.delta };
+            if (ev.type === "text_delta") {
+                return { type: "message_delta", timestamp: at, runId, data: { channel: "text", delta: ev.delta } };
+            }
+            if (ev.type === "thinking_delta") {
+                return { type: "message_delta", timestamp: at, runId, data: { channel: "thinking", delta: ev.delta } };
+            }
             return null;
         }
+        case "message_end":
+            if (pe.message.role !== "assistant")
+                return null;
+            return { type: "message_finished", timestamp: at, runId, data: {} };
         case "tool_execution_start":
-            return { type: "tool_started", id: pe.toolCallId, name: pe.toolName, args: pe.args };
+            return {
+                type: "tool_started",
+                timestamp: at,
+                runId,
+                data: { id: pe.toolCallId, name: pe.toolName, args: pe.args },
+            };
+        case "tool_execution_update":
+            return {
+                type: "tool_progress",
+                timestamp: at,
+                runId,
+                data: { id: pe.toolCallId, name: pe.toolName, partialResult: pe.partialResult },
+            };
         case "tool_execution_end":
-            return { type: "tool_ended", id: pe.toolCallId, isError: pe.isError, content: pe.result };
+            return {
+                type: "tool_finished",
+                timestamp: at,
+                runId,
+                data: { id: pe.toolCallId, isError: pe.isError, content: pe.result },
+            };
+        case "retry_scheduled": {
+            // Summarization retry backoff (auto-compaction / branch summary, pi ≥0.81.1) — without it,
+            // up to ~14s of backoff at the turn's tail reads as a hang. `retry_attempt_start`/
+            // `retry_finished` stay dropped: they carry no outcome, and the next event is the closure.
+            // Typed against the vocabulary (as is the second construction site, session-control's
+            // manual-compact callback) so a payload change breaks both at compile time.
+            const event = {
+                type: "retry_scheduled",
+                timestamp: at,
+                runId,
+                data: {
+                    operation: pe.operation,
+                    attempt: pe.attempt,
+                    maxAttempts: pe.maxAttempts,
+                    delayMs: pe.delayMs,
+                    error: pe.errorMessage,
+                },
+            };
+            return event;
+        }
+        default:
+            return null;
+    }
+}
+/** The SPEC projection of the rich stream. Events with no `AgentEvent` counterpart (progress,
+ *  message boundaries, run boundaries) project to null — the invoke terminal is produced from the
+ *  resolved message ({@link toTerminal}), not from `run_settled`. */
+export function projectAgentEvent(se) {
+    switch (se.type) {
+        case "message_delta": {
+            const d = se.data;
+            return d.channel === "text" ? { type: "text", delta: d.delta } : { type: "thinking", delta: d.delta };
+        }
+        case "tool_started": {
+            const d = se.data;
+            return { type: "tool_started", id: d.id, name: d.name, args: d.args };
+        }
+        case "tool_finished": {
+            const d = se.data;
+            return { type: "tool_ended", id: d.id, isError: d.isError, content: d.content };
+        }
+        case "retry_scheduled": {
+            // `operation` (compaction | branch_summary) stays session-plane vocabulary — a turn renderer
+            // only needs "transient failure, retrying"; the engine detail lives in the control plane.
+            const d = se.data;
+            return { type: "retrying", attempt: d.attempt, maxAttempts: d.maxAttempts, delayMs: d.delayMs, reason: d.error };
+        }
         default:
             return null;
     }
@@ -120,7 +209,13 @@ function toAgentEvent(pe) {
  * entire failure class (violating SPEC MUST 1).
  */
 export function toTerminal(message) {
-    if (message.stopReason === "error" || message.stopReason === "aborted") {
+    if (message.stopReason === "aborted") {
+        // A deliberate stop (control-plane abort / harness abort), not an error — see {@link ABORTED_CODE}
+        // for the consumer contract (design §6).
+        const details = message.errorMessage ?? "run aborted";
+        return { type: "failed", details, retryable: false, code: ABORTED_CODE };
+    }
+    if (message.stopReason === "error") {
         const details = message.errorMessage ?? `model stopped: ${message.stopReason}`;
         return { type: "failed", details, retryable: classifyRetryable(details, messageSignal(message)) };
     }
@@ -130,6 +225,20 @@ export function errorToTerminal(error) {
     const details = error instanceof Error ? error.message : String(error);
     return { type: "failed", details, retryable: classifyRetryable(details, errorSignal(error)) };
 }
+/** Bind the concrete pi-agent-core Session behind FastAgent's tool-runtime manager port. */
+function toolSessionManager(sessionId, harness) {
+    const session = harnessSession(harness);
+    if (!session)
+        return undefined;
+    return {
+        getSessionId: () => sessionId,
+        async getHeader() {
+            const metadata = await session.getMetadata();
+            return { id: sessionId, timestamp: metadata.createdAt };
+        },
+        getBranch: () => session.getBranch(),
+    };
+}
 /**
  * The turn's {@link ToolActivation} over the live harness. `activate` is additive and filters to the
  * registered names first — pi's `setActiveTools` THROWS on unknown names, and a loader must get a
@@ -243,10 +352,39 @@ class EventQueue {
 }
 /** "From a harness factory": engine wired by the caller; adds only the concurrency/stream shell. */
 export function createPiAgentFromHarness(options) {
-    const { harnessFactory, lease = inProcessLease() } = options;
-    async function* invoke(scope, prompt) {
+    const { harnessFactory, lease = inProcessLease(), observer } = options;
+    function invoke(scope, prompt) {
+        // The cancellation DOOR (SPEC MUST 3), via the shared abort-first protocol (see
+        // abortFirstIterator): cancel aborts the engine work, which settles the run and releases a
+        // generator suspended on a quiet stream (a tool mid-execution). The local for-await pattern
+        // never hit the underlying deadlock (it breaks at a yield boundary); pull-driven consumers
+        // (the SSE handler's eager reads) do.
+        // The cancel intent is LATCHED: a consumer may cancel while the generator is still inside
+        // the harness build (the door not yet armed) — abortFirstIterator knocks exactly once, and a
+        // knock before prompt() starts would be a no-op on an idle harness (the LATER run would
+        // ignore it). So turn consults the latch right after arming and, when the consumer already
+        // walked away, never starts the model call at all.
+        let externalCancel;
+        let cancelled = false;
+        const gen = turn(scope, prompt, (cancel) => {
+            externalCancel = cancel;
+        }, () => cancelled);
+        const iterator = abortFirstIterator(gen, () => {
+            cancelled = true;
+            externalCancel?.();
+        });
+        return {
+            [Symbol.asyncIterator]() {
+                return iterator;
+            },
+        };
+    }
+    async function* turn(scope, prompt, onCancelReady, 
+    /** The consumer's cancel latch (see invoke's wrapper) — checked once at arming. */
+    wasCancelled) {
         const release = lease.tryAcquire(scope.session);
         if (!release) {
+            // Rejected BEFORE acceptance: no run exists, so the observer sees nothing (replay-safe).
             yield {
                 type: "failed",
                 details: "session busy: a turn is already in flight for this session",
@@ -255,6 +393,90 @@ export function createPiAgentFromHarness(options) {
             };
             return;
         }
+        // The run exists from here: one run_started, exactly one run_settled. Terminal points only
+        // RECORD the outcome; the settlement event is emitted in the outer finally, right before
+        // release() — so the observation plane's "running" window equals the lease window (state()
+        // must never say idle while a new invoke would still be rejected session_busy), and the
+        // post-terminal auto-compaction is naturally inside the run. A run with no recorded outcome
+        // was cancelled by the caller (SPEC: cancellation has no terminal event) → aborted.
+        const runId = crypto.randomUUID();
+        let outcome;
+        const observe = (event, run) => {
+            if (!event || !observer)
+                return;
+            try {
+                observer(scope.session, event, run);
+            }
+            catch (error) {
+                // The observation plane must never break the data plane; a broken hub is its own problem.
+                log.warn(`[fastagent] session observer threw (event ${event.type}): ${String(error)}`);
+            }
+        };
+        // run_started must be observed before the (awaited) harness build so no early event outruns
+        // registration — so the controls AWAIT the build instead of erroring on the assembling window:
+        // a dispatch that races the build simply queues on the freshly built harness. A setup failure
+        // rejects the gate (and the run settles failed); the guard keeps an undispatched rejection from
+        // becoming an unhandled-rejection crash.
+        let harnessReady;
+        let harnessFailed;
+        const harnessGate = new Promise((resolve, reject) => {
+            harnessReady = resolve;
+            harnessFailed = reject;
+        });
+        harnessGate.catch(() => { }); // observed via controls only when a dispatch actually happens
+        // Aborted classification has two attribution sources, either suffices: pi's own
+        // stopReason:"aborted" (toTerminal), and control-plane INTENT — needed because providers do
+        // not uniformly attribute an aborted stream (verified empirically: the faux path surfaces a
+        // plain error). Intent = "an abort() succeeded, OR one was still in flight when the terminal
+        // arrived" (the harness error often lands before abort() resolves). A rejected abort that
+        // RETURNED before the terminal counts as nothing — no rollback dance, no interleaving hazard.
+        // GUARANTEE BOUNDARY: an abort still in flight that ultimately rejects can classify a
+        // concurrent real error as aborted — narrow, and non-lossy: the settlement carries
+        // `error.message` either way.
+        let abortsInFlight = 0;
+        let abortSucceeded = false;
+        // Stale-controls guard: after settlement pi's steer()/followUp()/abort() would still resolve
+        // (they queue / no-op on the to-be-discarded harness) — a silent acceptance of a command that
+        // can never take effect. The flag flips at THREE points, earliest wins: (1) the moment the
+        // run's terminal is determined (the main window — before the consumer-paced `yield terminal`
+        // and auto-compaction), (2) the setup-failure path, (3) the outer finally as the backstop for
+        // caller cancellation. A post-settle call throws and the dispatcher maps it to
+        // `run_command_failed`.
+        let runSettled = false;
+        const settledError = () => new Error("run already settled; the command cannot take effect");
+        // The settled check and the harness call MUST share one synchronous block (no await between):
+        // pi enqueues/aborts synchronously at method entry, so check-then-call in the same tick truly
+        // closes the race — a check behind its own await boundary would only shrink it.
+        const controls = {
+            async steer(p) {
+                const opts = await toPiPromptOptions(p);
+                const harness = await harnessGate;
+                if (runSettled)
+                    throw settledError();
+                await harness.steer(p.text, opts);
+            },
+            async followUp(p) {
+                const opts = await toPiPromptOptions(p);
+                const harness = await harnessGate;
+                if (runSettled)
+                    throw settledError();
+                await harness.followUp(p.text, opts);
+            },
+            async abort() {
+                const harness = await harnessGate;
+                if (runSettled)
+                    throw settledError();
+                abortsInFlight++;
+                try {
+                    await harness.abort();
+                    abortSucceeded = true;
+                }
+                finally {
+                    abortsInFlight--;
+                }
+            },
+        };
+        observe({ type: "run_started", timestamp: Date.now(), runId, data: {} }, controls);
         try {
             let harness;
             try {
@@ -262,22 +484,58 @@ export function createPiAgentFromHarness(options) {
             }
             catch (error) {
                 // Setup failures (session open / auth / …) MUST surface as a failed event, never a throw.
-                yield errorToTerminal(error);
-                return;
+                harnessFailed(error); // a pending dispatch learns the run cannot take commands
+                const terminal = errorToTerminal(error);
+                outcome = { status: "failed", error: { message: terminal.details, retryable: terminal.retryable } };
+                runSettled = true; // commands can no longer take effect — reject stale controls from here on
+                yield terminal;
+                return; // → outer finally emits the settlement
+            }
+            harnessReady(harness);
+            // Arm the cancellation door (see invoke's wrapper): aborting the harness settles the run,
+            // releasing any await the generator is parked on so a queued return() can reach the finally.
+            onCancelReady(() => {
+                void harness.abort().catch(() => { });
+            });
+            // The consumer cancelled DURING the build (latched — the door above came too late to be
+            // knocked): never start the model call; settle as aborted and let the queued return()
+            // finish the generator. Same synchronous tick as the arming — a cancel from here on
+            // reaches the armed door instead.
+            if (wasCancelled()) {
+                outcome = { status: "aborted" };
+                runSettled = true;
+                try {
+                    await harness.abort(); // teardown — fresh-harness discipline
+                }
+                catch (error) {
+                    log.warn(`[fastagent] harness abort failed during cleanup: ${String(error)}`);
+                }
+                return; // → outer finally emits the settlement
             }
             const queue = new EventQueue();
             const unsub = harness.subscribe((pe) => {
-                const event = toAgentEvent(pe);
+                // Summarization retries also warn to server logs: the session `retry_scheduled` event only
+                // reaches attached observers, and an operator tailing logs must see the backoff too.
+                if (pe.type === "retry_scheduled") {
+                    log.warn(`[fastagent] ${pe.operation} retry ${pe.attempt}/${pe.maxAttempts} in ${pe.delayMs}ms (session ${scope.session}): ${pe.errorMessage}`);
+                }
+                const rich = toSessionEvent(pe, runId);
+                if (!rich)
+                    return;
+                observe(rich);
+                const event = projectAgentEvent(rich);
                 if (event)
                     queue.push(event);
             });
             let completed; // the assistant message of a cleanly completed turn
             try {
-                // Run the turn inside the session context so a tool's `execute` can read which session it is in
-                // (turnContext / ToolContext.session). prompt() starts the async work synchronously here, so the
-                // store propagates to the tool calls awaited within it.
+                // Bind current cwd/session/activation capabilities for every FastAgent-defined tool.
                 const opts = await toPiPromptOptions(prompt);
-                const run = turnContext.run({ session: scope.session, tools: toolActivation(harness) }, () => harness.prompt(prompt.text, opts));
+                const run = turnContext.run({
+                    cwd: options.cwd ?? process.cwd(),
+                    sessionManager: toolSessionManager(scope.session, harness),
+                    tools: toolActivation(harness),
+                }, () => harness.prompt(prompt.text, opts));
                 yield* queue.drainUntil(run);
                 let terminal;
                 try {
@@ -289,6 +547,28 @@ export function createPiAgentFromHarness(options) {
                 catch (error) {
                     terminal = errorToTerminal(error);
                 }
+                if ((abortSucceeded || abortsInFlight > 0) && terminal.type === "failed") {
+                    terminal = { type: "failed", details: terminal.details, retryable: false, code: ABORTED_CODE };
+                }
+                if (terminal.type === "completed")
+                    outcome = { status: "completed" };
+                else if (terminal.type === "failed") {
+                    outcome =
+                        terminal.code === ABORTED_CODE
+                            ? // Carry the detail: an independent real error that raced an accepted abort must stay
+                                // diagnosable in the settlement (audit consumers read run_settled, not the invoke
+                                // stream) — aborted classifies the run, the message preserves what actually stopped it.
+                                { status: "aborted", error: { message: terminal.details, retryable: false } }
+                            : {
+                                status: "failed",
+                                error: { code: terminal.code, message: terminal.details, retryable: terminal.retryable },
+                            };
+                }
+                // Commands become ineffective the moment the run resolved — NOT at the outer finally, which
+                // sits behind `yield terminal` (a consumer-paced suspension) and auto-compaction. Flipping
+                // here closes the silent-drop window for steer/follow_up dispatched in that gap; the
+                // outer-finally flip remains as the backstop for caller cancellation.
+                runSettled = true;
                 yield terminal;
             }
             finally {
@@ -326,6 +606,11 @@ export function createPiAgentFromHarness(options) {
             }
         }
         finally {
+            // Exactly-one settlement, after ALL run work (incl. auto-compaction) and immediately before
+            // the lease releases — see the outcome note above. The stale-controls flag flips FIRST so a
+            // dispatch racing this settlement is rejected instead of silently accepted.
+            runSettled = true;
+            observe({ type: "run_settled", timestamp: Date.now(), runId, data: outcome ?? { status: "aborted" } });
             release(); // after cleanup, so the next invoke for this session can enter
         }
     }

package/dist/engines/pi/login.d.ts

@@ -1,6 +1,6 @@
 /**
  * `fastagent login`: authenticate a MODEL PROVIDER into the resolved auth file (project-level
- * `<dir>/.fastagent/auth.json` by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`) via the same
+ * `<root>/.secrets/auth.json` by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`) via the same
  * {@link fastagentCredentialStore} the runtime uses (one writer, one lock/corruption semantics).
  *
  * Flow (pi-ai's unified `ProviderAuth` API): pick a method (OAuth or API key), then a provider that
@@ -33,6 +33,17 @@ export interface LoginIO {
     openUrl(url: string): void;
 }
 export type LoginMethod = "oauth" | "api_key";
+/** The user backed out of a prompt/menu — a decision, not a failure. Callers (the first-run picker,
+ *  the login command) match on this to report neutrally instead of as a login "failure". */
+export declare class LoginCancelled extends Error {
+}
+/** What `loginFlow` can offer a provider interactively: an OAuth flow, an API-key ENTRY prompt, or
+ *  nothing ("none" — the key must come from the provider's env var). */
+export type InteractiveLoginKind = LoginMethod | "none";
+/** The provider's {@link InteractiveLoginKind}. OAuth wins when both exist (methodForProvider still
+ *  asks at login time); the first-run picker annotates with this so the hint predicts what picking
+ *  actually does — a browser login ("oauth"), a key prompt ("api_key"), or neither. */
+export declare function interactiveLoginKind(p: Provider): InteractiveLoginKind;
 export interface LoginResult {
     provider: string;
     method: LoginMethod;

package/dist/engines/pi/login.js

@@ -1,5 +1,17 @@
 import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
 import { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./auth.js";
+/** The user backed out of a prompt/menu — a decision, not a failure. Callers (the first-run picker,
+ *  the login command) match on this to report neutrally instead of as a login "failure". */
+export class LoginCancelled extends Error {
+}
+/** The provider's {@link InteractiveLoginKind}. OAuth wins when both exist (methodForProvider still
+ *  asks at login time); the first-run picker annotates with this so the hint predicts what picking
+ *  actually does — a browser login ("oauth"), a key prompt ("api_key"), or neither. */
+export function interactiveLoginKind(p) {
+    if (p.auth.oauth)
+        return "oauth";
+    return p.auth.apiKey?.login ? "api_key" : "none";
+}
 /** Combine present abort signals into one (no-op when none/one). */
 function anySignal(...signals) {
     const present = signals.filter((s) => s !== undefined);
@@ -17,13 +29,13 @@ function authCallbacks(io, userSignal, doneSignal) {
             if (p.type === "select") {
                 const v = await io.select(p.message, p.options.map((o) => ({ value: o.id, label: o.label, hint: o.description })));
                 if (v === undefined)
-                    throw new Error("cancelled");
+                    throw new LoginCancelled("cancelled");
                 return v;
             }
             const signal = anySignal(p.signal, userSignal, doneSignal);
             const v = await io.prompt(p.message, { hidden: p.type === "secret", signal });
             if (v === undefined)
-                throw new Error("cancelled");
+                throw new LoginCancelled("cancelled");
             return v;
         },
         notify: (e) => {
@@ -53,7 +65,7 @@ async function selectMethod(io) {
         { value: "api_key", label: "Use an API key" },
     ]);
     if (v !== "oauth" && v !== "api_key")
-        throw new Error("no authentication method selected");
+        throw new LoginCancelled("no authentication method selected");
     return v;
 }
 /** Given a provider arg, pick the method it supports (asking only when it offers both). */
@@ -80,7 +92,7 @@ async function selectProvider(io, providers, method, store) {
     }));
     const id = await io.select("Select a provider", options);
     if (!id)
-        throw new Error("no provider selected");
+        throw new LoginCancelled("no provider selected");
     return id;
 }
 /**

package/dist/engines/pi/models.d.ts

@@ -4,11 +4,13 @@
  * it into the harness alongside the selected `model`; the two must come from the same collection so
  * the model's provider auth is in scope.
  */
-import { type Models, type Provider } from "@earendil-works/pi-ai";
+import { type Api, type Model, type Models, type Provider } from "@earendil-works/pi-ai";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { type FastagentAuthOptions } from "./auth.ts";
+import { type InteractiveLoginKind } from "./login.ts";
 export interface CreatePiModelsOptions extends FastagentAuthOptions {
-    /** Credentials file path. Defaults to the global `~/.fastagent/auth.json`; the directory opener passes
-     *  the project-level `<dir>/.fastagent/auth.json`. */
+    /** Credentials file path. Defaults to the global `~/.fastagent/.secrets/auth.json`; the directory opener passes
+     *  the project-level `<root>/.secrets/auth.json`. */
     authPath?: string;
     /** Extra providers registered on top of the built-ins (same id overrides a built-in). */
     providers?: Provider[];
@@ -16,22 +18,47 @@ export interface CreatePiModelsOptions extends FastagentAuthOptions {
 /**
  * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
  * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
- * `~/.fastagent/auth.json` unless the opener passes a project-level path), then ambient env vars. A
+ * `~/.fastagent/.secrets/auth.json` unless the opener passes a project-level path), then ambient env vars. A
  * stored credential owns the provider; env is consulted only when nothing is stored (resolution order
  * is upstream-owned).
  */
 export declare function createPiModels(options?: CreatePiModelsOptions): Models;
 /**
- * The "provider/modelId" specs whose provider currently has USABLE credentials (a stored login or an
- * env key) — the menu for the first-run model picker (`fastagent dev`/`start`/`invoke` with no model
- * set). Auth is provider-scoped, so probe once per provider (any of its models) rather than per model.
- * A provider that resolves no auth (unconfigured) or rejects it (configured-but-expired) is omitted:
- * the picker offers only models that would actually run now; `fastagent login` fixes the rest. Sorted.
- *
- * pi deliberately has no "best/tier" ranking on Model, so this does not auto-pick — it narrows the menu
- * to what the user can use and lets them choose (mirroring pi-coding-agent's select-then-persist).
+ * The `ModelRuntime`-shaped sibling of {@link createPiModels} — the SAME hub semantics (built-in
+ * providers + fastagent's credential store at `authPath`) in the type pi's session services require
+ * (`createAgentSessionServices({ modelRuntime })`). Builtins only (`modelsPath: null` — pi's
+ * machine-global models.json is definition-foreign) and no availability network, so the model
+ * surface equals serving's. No `providers` option: `ModelRuntime` registers providers by config
+ * record, not `Provider` instance — accepting the option and dropping it would be a silent no-op;
+ * add the mapping when a consumer actually needs it.
  */
-export declare function configuredModelSpecs(models: Models): Promise<string[]>;
+export declare function createPiModelRuntime(options?: FastagentAuthOptions & {
+    authPath?: string;
+}): Promise<ModelRuntime>;
+/** Per-provider auth status for the first-run model picker: usable now (with the source label), not
+ *  configured, or configured-but-broken (expired token, refresh failure, corrupt store — kept as DATA
+ *  so the picker can show it instead of silently dropping the provider). Non-ready states carry the
+ *  provider's {@link InteractiveLoginKind}, so the picker's hint predicts what picking does — an
+ *  OAuth login, an API-key prompt, or (env-key-only providers) neither. */
+export type ProviderAuthStatus = {
+    state: "ready";
+    source?: string;
+} | {
+    state: "unconfigured";
+    login: InteractiveLoginKind;
+} | {
+    state: "broken";
+    message: string;
+    login: InteractiveLoginKind;
+};
+/**
+ * Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe)
+ * — the status map behind the first-run model picker (`fastagent dev`/`start`/`invoke` with no model
+ * set). The picker shows the FULL catalog annotated with these statuses, so "what fastagent supports"
+ * and "what is authenticated on this machine" stay distinguishable; a needs-login choice triggers an
+ * inline `loginFlow`. Providers with no models are omitted (nothing to pick).
+ */
+export declare function providerAuthStatuses(models: Models): Promise<Map<string, ProviderAuthStatus>>;
 /**
  * Which source currently satisfies auth for `spec` — a startup diagnostic. Returns the upstream
  * `AuthResult.source` label: `"OAuth"` for a stored OAuth credential (e.g. a logged-in openai-codex),
@@ -39,3 +66,22 @@ export declare function configuredModelSpecs(models: Models): Promise<string[]>;
  * undefined when unconfigured. Reporting-only; never throws.
  */
 export declare function probeAuthSource(models: Models, spec: string): Promise<string | undefined>;
+/** Verdict of {@link probeApiKey}: `rejected` is DEFINITIVE (the provider answered HTTP 401 — the key
+ *  is wrong); everything else non-ok is `unknown` — a 403 can be a VALID key without model permission,
+ *  a 429/5xx/network failure says nothing about the key — so callers must only destroy state on
+ *  `rejected`. */
+export type KeyProbe = {
+    state: "ok";
+} | {
+    state: "rejected" | "unknown";
+    message: string;
+};
+/**
+ * Quick-fail probe for a just-stored API key: one minimal real request through the standard auth
+ * resolution path (the same path invokes take), so a mistyped key surfaces at login time, not at the
+ * first turn. `complete` reports provider errors as `stopReason: "error"` rather than throwing; the
+ * HTTP status arrives via `onResponse` — when a provider path never calls it (SDK transports), fall
+ * back to a conservative "401" match in the error text. Short timeout, no retries: feedback speed
+ * over transient-failure tolerance (a transient lands on `unknown`, which keeps the key).
+ */
+export declare function probeApiKey(models: Models, model: Model<Api>): Promise<KeyProbe>;