@fastagent-sh/fastagent 0.22.1 → 0.24.0

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

@@ -4,7 +4,7 @@
  * (one writer, one lock/corruption semantics); {@link loginOptions} is the list a picker offers. `fastagent login` is
  * one front end ({@link loginFlow}: terminal menus, then {@link login}); a GUI client is another.
  */
-import { type AuthInteraction, type Provider } from "@earendil-works/pi-ai";
+import { type AuthInteraction, type CredentialStore, type Provider } from "@earendil-works/pi-ai";
 export type LoginMethod = "oauth" | "api_key";
 /** The user backed out of a prompt/menu, or the flow was aborted — a decision, not a failure. */
 export declare class LoginCancelled extends Error {
@@ -18,26 +18,38 @@ export interface LoginOption {
     /** An OAuth login backed by a provider subscription. */
     subscription: boolean;
     /**
-     * What the file holds for this provider now. It keeps ONE credential per provider, so signing in with the other
+     * What the store holds for this provider now. It keeps ONE credential per provider, so signing in with the other
      * method replaces it — worth a warning in a client.
      */
     stored?: LoginMethod;
 }
 /**
- * Every interactive sign-in of pi's built-in providers, with what `authPath` already holds for each. A provider whose
- * key can only come from its env var offers none and is left out.
+ * Every interactive sign-in of pi's built-in providers, with what `credentials` (a credentials file, or the caller's
+ * own store) already holds for each. A provider whose key can only come from its env var offers none and is left out.
  */
-export declare function loginOptions(authPath: string): Promise<LoginOption[]>;
+export declare function loginOptions(credentials: string | CredentialStore): Promise<LoginOption[]>;
 /** {@link loginOptions} over pi's built-ins plus `providers` (a same id replaces one). Not public: a test seam. */
-export declare function loginOptionsOver(authPath: string, providers?: readonly Provider[]): Promise<LoginOption[]>;
-export interface LoginRequest {
+export declare function loginOptionsOver(credentials: string | CredentialStore, providers?: readonly Provider[]): Promise<LoginOption[]>;
+export type LoginRequest = {
+    /**
+     * Stable installation identity (Sign in with ChatGPT requires one). With `authPath` it defaults to Pi settings
+     * beside that file (`settings.json`, written before the flow runs); over a caller's `credentialStore` there is no
+     * file to keep it beside, so a flow that needs one fails unless this supplies it.
+     */
+    getDeviceId?: () => string;
     provider: string;
     method: LoginMethod;
-    /** The credentials file the sign-in is written to. */
-    authPath: string;
     /** pi-ai's own interaction: prompts (`text`, `secret`, `select`, `manual_code`) and events (`auth_url`, …). */
     interaction: AuthInteraction;
-}
+} & ({
+    /** The credentials file the sign-in is written to. */
+    authPath: string;
+    credentialStore?: never;
+} | {
+    /** The caller's own store the sign-in is written to, in place of any file. */
+    credentialStore: CredentialStore;
+    authPath?: never;
+});
 export interface LoginResult {
     provider: string;
     method: LoginMethod;
@@ -45,10 +57,11 @@ export interface LoginResult {
     verified: "ok" | "unknown" | "n/a";
 }
 /**
- * Sign in to one of pi's built-in providers and persist the credential to `authPath`.
+ * Sign in to one of pi's built-in providers and persist the credential to `authPath`, or to the caller's
+ * `credentialStore`.
  *
- * The file is checked FIRST (a no-op write runs the refuse-corrupt and writability checks), so a flow never runs
- * toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
+ * The store is checked FIRST (a no-op write runs the file store's refuse-corrupt and writability checks, or whatever
+ * the caller's store does on a write), so a flow never runs toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
  * default model for the provider (its first model when pi names none), at pi's built-in endpoint, BEFORE it is
  * written. Credentials are provider-scoped, so any of the provider's models answers the question the check asks (does
  * the provider refuse the key, HTTP 401); a key the provider rejects is never stored, and the provider's key flow runs
@@ -56,7 +69,7 @@ export interface LoginResult {
  * A provider an agent's models.json points elsewhere is not this call's: store that key with `fastagentCredentialStore`.
  *
  * Aborting `interaction.signal` at any point, the verification included, rejects with {@link LoginCancelled} and
- * writes nothing. Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
+ * writes no credential (an OAuth device ID, the installation's identity, is kept once created). Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
  * beating a `manual_code` prompt), and when the flow settles with a prompt still pending.
  */
 export declare function login(request: LoginRequest): Promise<LoginResult>;

package/dist/engines/pi/login.js

@@ -5,23 +5,28 @@
  * one front end ({@link loginFlow}: terminal menus, then {@link login}); a GUI client is another.
  */
 import { InMemoryCredentialStore, } from "@earendil-works/pi-ai";
+import { dirname } from "node:path";
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
 import { fastagentCredentialStore } from "./auth.js";
 import { createPiModelRuntime, interactiveAuth, loginProviders, piModelsOver, probeApiKey } from "./models.js";
+import { agentModels } from "./agent-models.js";
 /** The user backed out of a prompt/menu, or the flow was aborted — a decision, not a failure. */
 export class LoginCancelled extends Error {
 }
 /**
- * Every interactive sign-in of pi's built-in providers, with what `authPath` already holds for each. A provider whose
- * key can only come from its env var offers none and is left out.
+ * Every interactive sign-in of pi's built-in providers, with what `credentials` (a credentials file, or the caller's
+ * own store) already holds for each. A provider whose key can only come from its env var offers none and is left out.
  */
-export function loginOptions(authPath) {
-    return loginOptionsOver(authPath);
+export function loginOptions(credentials) {
+    return loginOptionsOver(credentials);
 }
+/** A credentials file path names fastagent's store over it; a store is used as given. */
+const storeOf = (credentials) => typeof credentials === "string" ? fastagentCredentialStore(credentials) : credentials;
 /** {@link loginOptions} over pi's built-ins plus `providers` (a same id replaces one). Not public: a test seam. */
-export async function loginOptionsOver(authPath, providers) {
-    // ONE read of the file: `list` is metadata only, and reading per provider would repeat a corrupt file's warning for
+export async function loginOptionsOver(credentials, providers) {
+    // ONE read of the store: `list` is metadata only, and reading per provider would repeat a corrupt file's warning for
     // every provider.
-    const held = new Map((await fastagentCredentialStore(authPath).list()).map((info) => [info.providerId, info.type]));
+    const held = new Map((await storeOf(credentials).list()).map((info) => [info.providerId, info.type]));
     const offered = [];
     for (const provider of loginProviders(providers)) {
         const methods = ["oauth", "api_key"].filter((method) => interactiveAuth(provider, method));
@@ -46,10 +51,11 @@ function anySignal(...signals) {
     return present.length === 0 ? undefined : present.length === 1 ? present[0] : AbortSignal.any(present);
 }
 /**
- * Sign in to one of pi's built-in providers and persist the credential to `authPath`.
+ * Sign in to one of pi's built-in providers and persist the credential to `authPath`, or to the caller's
+ * `credentialStore`.
  *
- * The file is checked FIRST (a no-op write runs the refuse-corrupt and writability checks), so a flow never runs
- * toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
+ * The store is checked FIRST (a no-op write runs the file store's refuse-corrupt and writability checks, or whatever
+ * the caller's store does on a write), so a flow never runs toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
  * default model for the provider (its first model when pi names none), at pi's built-in endpoint, BEFORE it is
  * written. Credentials are provider-scoped, so any of the provider's models answers the question the check asks (does
  * the provider refuse the key, HTTP 401); a key the provider rejects is never stored, and the provider's key flow runs
@@ -57,7 +63,7 @@ function anySignal(...signals) {
  * A provider an agent's models.json points elsewhere is not this call's: store that key with `fastagentCredentialStore`.
  *
  * Aborting `interaction.signal` at any point, the verification included, rejects with {@link LoginCancelled} and
- * writes nothing. Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
+ * writes no credential (an OAuth device ID, the installation's identity, is kept once created). Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
  * beating a `manual_code` prompt), and when the flow settles with a prompt still pending.
  */
 export function login(request) {
@@ -66,13 +72,17 @@ export function login(request) {
 /** {@link login}, plus {@link LoginInternals}. */
 export async function loginOver(request, internals = {}) {
     const { providers, verifyWith, agentDir } = internals;
-    const { method, authPath, interaction } = request;
+    const { method, interaction } = request;
+    if (request.credentialStore === undefined && typeof request.authPath !== "string") {
+        throw new Error("login needs authPath or credentialStore: where the sign-in is written");
+    }
     const provider = loginProviders(providers).find((p) => p.id === request.provider);
     if (!provider)
         throw new Error(`unknown provider "${request.provider}"`);
     const auth = interactiveAuth(provider, method);
     if (!auth?.login)
         throw new Error(`provider "${provider.id}" has no interactive ${method} login`);
+    const flow = auth.login.bind(auth);
     // The key under test lives here, not in the file, until it passes.
     const trial = new InMemoryCredentialStore();
     // Only a key needs the registry, and building an agent's fails on a broken models.json: an OAuth sign-in must not.
@@ -86,12 +96,25 @@ export async function loginOver(request, internals = {}) {
                 ...(providers ? { providers: [...providers] } : {}),
             })
             : piModelsOver(trial, providers);
-    const store = fastagentCredentialStore(authPath);
+    const store = agentModels(undefined, request).credentials;
     await store.modify(provider.id, async () => undefined);
     const signal = interaction.signal ?? new AbortController().signal;
     const notify = (event) => interaction.notify(event);
+    let getDeviceId = request.getDeviceId;
+    if (method === "oauth" && !getDeviceId && request.authPath !== undefined) {
+        // Only the settings file beside the credentials: no project's `.pi/settings.json` has a say in this write.
+        const settings = SettingsManager.create(dirname(request.authPath), dirname(request.authPath), {
+            projectTrusted: false,
+        });
+        const deviceId = settings.getOrCreateDeviceId();
+        await settings.flush();
+        const errors = settings.drainErrors();
+        if (errors.length)
+            throw new Error(`could not persist login device ID: ${errors.map(({ error }) => error.message).join("; ")}`);
+        getDeviceId = () => deviceId;
+    }
     for (;;) {
-        const credential = await runFlow(auth.login.bind(auth), interaction, signal);
+        const credential = await runFlow((io) => flow(io, { getDeviceId }), interaction, signal);
         let verified = "n/a";
         if (models) {
             await trial.modify(provider.id, async () => credential);
@@ -143,7 +166,7 @@ export const PI_DEFAULT_MODELS = {
     anthropic: "claude-opus-4-8",
     openai: "gpt-5.5",
     "azure-openai-responses": "gpt-5.4",
-    "openai-codex": "gpt-5.5",
+    "openai-codex": "gpt-6.1-sol",
     radius: "balanced",
     nvidia: "nvidia/nemotron-3-super-120b-a12b",
     deepseek: "deepseek-v4-pro",
@@ -163,11 +186,11 @@ export const PI_DEFAULT_MODELS = {
     moonshotai: "kimi-k2.6",
     "moonshotai-cn": "kimi-k2.6",
     huggingface: "moonshotai/Kimi-K2.6",
-    fireworks: "accounts/fireworks/models/kimi-k2p6",
-    together: "moonshotai/Kimi-K2.6",
+    fireworks: "accounts/fireworks/models/kimi-k3",
+    together: "moonshotai/Kimi-K3",
     baseten: "zai-org/GLM-5.2",
     opencode: "kimi-k2.6",
-    "opencode-go": "kimi-k2.6",
+    "opencode-go": "kimi-k3",
     "kimi-coding": "kimi-for-coding",
     meta: "muse-spark-1.3",
     "cloudflare-workers-ai": "@cf/moonshotai/kimi-k2.6",

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

@@ -13,10 +13,33 @@ import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-codin
 /** pi's own shapes, taken from its loader rather than re-declared. */
 export type MachineSkill = ReturnType<DefaultResourceLoader["getSkills"]>["skills"][number];
 type MachinePrompt = ReturnType<DefaultResourceLoader["getPrompts"]>["prompts"][number];
+/** The Pi built-in extensions a definition loads, each unless the machine's settings disable it. */
+export declare const BUILTIN_EXTENSIONS: readonly ["codemode", "tool-search"];
+/**
+ * The way in for an authored tool the model is not given up front, by its exposure: the built-in extension that
+ * provides it and the tool that extension registers. A `codemode` tool is called from codemode scripts, a `deferred`
+ * one is loaded by tool_search — the rule Pi's MCP extension applies to its own tools (`ensureDiscoveryActive`).
+ * Without that extension the tool has no way in at all.
+ */
+export declare const DISCOVERY: {
+    readonly codemode: {
+        readonly extension: "codemode";
+        readonly tool: "codemode";
+    };
+    readonly deferred: {
+        readonly extension: "tool-search";
+        readonly tool: "tool_search";
+    };
+};
 /** What this box lends an agent. */
 export interface Machine {
     skills: MachineSkill[];
     prompts: MachinePrompt[];
+    /**
+     * The {@link BUILTIN_EXTENSIONS} left enabled, by Pi's own rule: `"extensions": ["-builtin:codemode"]` in the user
+     * settings disables one, and the workspace's `.pi/settings.json` overrides that either way.
+     */
+    builtinExtensions: string[];
     /** pi's engine settings (retry, compaction, cache warming, …) as read at boot — a fresh manager per caller. */
     settingsManager(): SettingsManager;
 }

package/dist/engines/pi/machine.js

@@ -11,6 +11,20 @@
  */
 import { DefaultPackageManager, DefaultResourceLoader, SettingsManager, getAgentDir, } from "@earendil-works/pi-coding-agent";
 import { log } from "../../log.js";
+/** The Pi built-in extensions a definition loads, each unless the machine's settings disable it. */
+// Not `mcp`: its server connections live as long as a session, and a served session lives one turn, so every turn
+// would start every configured server.
+export const BUILTIN_EXTENSIONS = ["codemode", "tool-search"];
+/**
+ * The way in for an authored tool the model is not given up front, by its exposure: the built-in extension that
+ * provides it and the tool that extension registers. A `codemode` tool is called from codemode scripts, a `deferred`
+ * one is loaded by tool_search — the rule Pi's MCP extension applies to its own tools (`ensureDiscoveryActive`).
+ * Without that extension the tool has no way in at all.
+ */
+export const DISCOVERY = {
+    codemode: { extension: "codemode", tool: "codemode" },
+    deferred: { extension: "tool-search", tool: "tool_search" },
+};
 /** Keyed by the two places it reads: the workspace (project scope) and pi's own directory (user scope). */
 const reads = new Map();
 /** This process's one read of the machine, shared by the run plane and `commands()` so the two cannot disagree. */
@@ -37,7 +51,12 @@ async function read(workspace, agentDir) {
     // (`npm install`, `git clone`), throwing out of `reload()` when that fails — measured. So fastagent resolves them
     // here, telling pi to skip what is absent, and hands the loader a packageless copy of the settings so its own
     // resolve has nothing to do.
-    const manager = new DefaultPackageManager({ cwd: workspace, agentDir, settingsManager: files });
+    const manager = new DefaultPackageManager({
+        cwd: workspace,
+        agentDir,
+        settingsManager: files,
+        builtinExtensions: [...BUILTIN_EXTENSIONS],
+    });
     const packages = await manager.resolve(async () => "skip");
     // A package skipped is said, once: its skills would otherwise just not be there. Asked of the configured list, not
     // of `onMissing` — pi never calls that under `PI_OFFLINE`, so the warning would vanish exactly when offline.
@@ -72,7 +91,10 @@ async function read(workspace, agentDir) {
             log.warn(`[fastagent] ${kind} ${diagnostic.type}: ${diagnostic.message}${diagnostic.path ? ` (${diagnostic.path})` : ""}`);
         }
     }
-    return { skills, prompts, settingsManager: () => scopedSettings(settings) };
+    const builtinExtensions = packages.extensions
+        .filter((resource) => resource.enabled && resource.metadata.source === "builtin")
+        .map((resource) => resource.path.slice("builtin:".length));
+    return { skills, prompts, builtinExtensions, settingsManager: () => scopedSettings(settings) };
 }
 /** A package's enabled resources; the loader discovers the top-level ones itself. */
 function fromPackages(resources) {

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

@@ -1,17 +1,6 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { type Api, type CredentialStore, type Model, type Models, type Provider } from "@earendil-works/pi-ai";
+import { type Api, type CredentialStore, type Model, type Models, type ModelsStore, type Provider } from "@earendil-works/pi-ai";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
-import { type FastagentAuthOptions } from "./auth.ts";
-import { type AuthLayers } from "./config.ts";
-/** The DEFINITION-LOCAL custom-endpoint file, in pi's own models.json schema (see pi's docs/models.md). */
-export interface CreatePiModelsOptions extends FastagentAuthOptions {
-    /** Credentials file (default `GLOBAL_AUTH_PATH`). A named file is an instruction: no second layer. */
-    authPath?: string;
-    /** Extra providers registered on top of the built-ins (same id overrides a built-in). */
-    providers?: Provider[];
-}
-/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
-export declare function createPiModels(options?: CreatePiModelsOptions): Models;
 /** The built-ins plus `providers` (a same id replaces a built-in), over any credential store. */
 export declare function piModelsOver(credentials: CredentialStore, providers?: readonly Provider[]): Models;
 /**
@@ -21,12 +10,17 @@ export declare function piModelsOver(credentials: CredentialStore, providers?: r
 export type AnyModel = Model<any>;
 /** The serving default for reasoning effort, pinned to what pi's TUI defaults to (its own DEFAULT_THINKING_LEVEL). */
 export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
-/**
- * The MACHINE's custom-endpoint file, in the same schema as an agent's own: endpoints a person set up for this machine
- * (a local Ollama, a company gateway), which every agent here inherits the way it inherits the machine's skills.
- * `FASTAGENT_MODELS_PATH` moves it. It never ships: a deployed agent has only its definition's file.
- */
-export declare function machineModelsPath(env?: NodeJS.ProcessEnv): string;
+/** The models.json pi loads for an agent, and where its content came from (for a load error). */
+export interface ModelsFile {
+    /** A snapshot pi loads; null when the agent has no models.json. */
+    path: string | null;
+    /** The agent's own file, when the snapshot is a copy of it alone. */
+    snapshotOf?: string;
+    merged?: {
+        machine: string;
+        definition: string;
+    };
+}
 /**
  * Where an agent's custom endpoints come from, for a report: the machine file, the providers the agent inherits from
  * it, and the ones its own file overrides. Undefined when the machine has no file.
@@ -38,29 +32,104 @@ export declare function machineModels(agentDir: string): Promise<{
 } | undefined>;
 /** Whether pi ships this provider id itself, so an agent resolves it without any models.json entry. */
 export declare function isBuiltinProvider(providerId: string): boolean;
-/** The `ModelRuntime`-shaped sibling of {@link createPiModels}. */
-export declare function createPiModelRuntime(options?: FastagentAuthOptions & {
-    /** The credentials files to read (default: the global file alone). */
-    auth?: AuthLayers;
-    /** The agent dir, whose {@link AGENT_MODELS_FILE} declares custom endpoints. */
+export interface PiModelRuntimeOptions {
+    /** The store every credential is read from and refreshed into. */
+    credentials: CredentialStore;
+    /** The agent dir, whose {@link AGENT_MODELS_FILE} and {@link AGENT_MODEL_CATALOG_FILE} the registry reads. */
     agentDir?: string;
     /**
-     * Layer the machine's models.json under the agent's (default). Off for the registry a DEPLOYED agent has, which
-     * `deploy` must judge by: the machine's file does not ship.
+     * Layer the machine under the agent (default): its models.json and its model catalog ({@link globalCatalogPath}).
+     * Off for the registry a DEPLOYED agent has, which `deploy` must judge by: neither ships, so that registry is the
+     * agent's own two files over the catalog bundled with pi.
      */
     machineLayer?: boolean;
-    /** Where the dynamic model-catalog cache goes; defaults to the agent's resolved state root. */
-    stateRoot?: string;
     /** Extra providers for the ids the built-ins do not cover. */
-    providers?: Provider[];
-    /** A credential store to use instead of the files (login verifies an entered key from memory). */
+    providers?: readonly Provider[];
+    /**
+     * Read and write THIS catalog file instead of the layered, read-only snapshot: what a refresh runs on, since the
+     * refresh writes it.
+     */
+    catalogFile?: string;
+    /** Where a catalog refresh asks instead of pi.dev: a test seam. */
+    catalogBaseUrl?: string;
+}
+/**
+ * The MACHINE's model catalog: the models pi.dev lists that are newer than the catalog bundled with pi, fetched by
+ * `fastagent models --refresh -g`. Every agent here reads it under its own; like `~/.fastagent/models.json`, it
+ * never ships.
+ */
+export declare function globalCatalogPath(): string;
+/**
+ * The catalog file a refresh writes, as pi's store. It replaces pi's own file store, which rewrites the file in place
+ * under its lock: a reader that takes no lock (every catalog read here, and anything else reading the file) could open
+ * it cut short mid-write and blame a healthy file. Same lock as pi's, so concurrent refreshes still queue; reading
+ * creates nothing, so a refresh that is refused writes no file.
+ */
+export declare function catalogFileStore(path: string): ModelsStore;
+/**
+ * Whether the machine's model catalog supplies this model, by the same rule every registry reads it with
+ * ({@link layeredCatalog}): an entry pi would ignore supplies nothing. The one layer a deployed agent does not have.
+ */
+export declare function inGlobalCatalog(provider: string, id: string): Promise<boolean>;
+/**
+ * The model files a runtime reads, READ ONCE: `agentModels` keeps one of these per agent, so every session's runtime
+ * and the control plane's catalog see the same content however the files change while serving.
+ */
+export interface ModelFiles {
+    models?: ModelsFile;
+    /** `ModelRuntime.create` options over this read; a fresh catalog store each call. */
+    create(): Promise<{
+        modelsPath: string | null;
+        modelsStore?: ModelsStore;
+        allowModelNetwork: false;
+        catalogBaseUrl?: string;
+    }>;
+}
+/** The models.json a runtime for these options loads, and which model catalog it reads. */
+export declare function modelRuntimeFiles(options: Omit<PiModelRuntimeOptions, "credentials">): Promise<ModelFiles>;
+/**
+ * This machine's registry, without an agent: pi's built-ins, the machine's models.json and its model catalog. What
+ * `fastagent models` lists outside an agent; {@link catalogFile} is the refresh's (it writes the file).
+ */
+export declare function machineModelRuntime(options?: {
     credentials?: CredentialStore;
+    catalogFile?: string;
+    catalogBaseUrl?: string;
+}): Promise<ModelRuntime>;
+/**
+ * Fetch the model catalog of every provider the runtime can authenticate into `catalogFile` ({@link
+ * catalogFileStore}): the refresh `pi update --models` runs. `build` makes the runtime over that file, and runs only
+ * once the refresh is known to go ahead. A refusal writes nothing: the store creates the file only when pi writes an
+ * entry. pi asks pi.dev only for a provider with a usable credential, and may refresh an expired OAuth token of the
+ * runtime's store to get one. Rejects, naming each provider that failed, when any part fails, when it outlasts 15
+ * seconds, when `PI_OFFLINE` is set, when the catalog file is corrupt, and when no provider has a usable credential (the
+ * refresh would ask for nothing).
+ */
+export declare function refreshCatalog(catalogFile: string, build: (catalogFile: string) => Promise<ModelRuntime>, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * What satisfies a provider from `env` alone (its API-key variable, or an ambient source such as an AWS profile), by
+ * pi's own check, or undefined. Passed explicitly rather than read from `process.env`: only the environment a SHELL
+ * hands down is shared by every agent on the machine, and a process that has loaded an agent's `.secrets/.env` holds
+ * that agent's variables too. What the shell shares outranks the global credentials file (agent-models.ts),
+ * so a global login for such a provider is not used.
+ *
+ * `fileExists` answers for the files a source points at (an AWS profile, Google ADC): this machine's by default, which
+ * is right wherever the answer is about THIS machine. A deployment passes one that finds nothing, because no file of
+ * the builder's travels with it.
+ */
+export declare function environmentAuthSource(providerId: string, env: NodeJS.ProcessEnv, fileExists?: (path: string) => Promise<boolean>): Promise<string | undefined>;
+/** Pi registration starts background refreshes; wait for all of them before publishing this fresh runtime. */
+export declare function withModelRegistration<T>(runtime: ModelRuntime, register: () => Promise<T>): Promise<T>;
+/**
+ * A registry over the given credential store. What an agent runs on is built through `agentModels`
+ * (agent-models.ts); this is for a registry over some OTHER store: none at all (`models`, a deploy check of what
+ * ships), a trial key under test (login), or the catalog file a refresh writes.
+ */
+export declare function createPiModelRuntime(options: PiModelRuntimeOptions & {
+    files?: ModelFiles;
 }): Promise<ModelRuntime>;
-/** How a model's credential will REACH a deployed agent. */
-export declare function modelCredentialCarry(runtime: ModelRuntime, spec: string): {
-    envVar?: string;
-    inDefinition: boolean;
-};
 /**
  * EVERY provider whose `models.json` entry writes its key as a LITERAL rather than a `"$NAME"` reference or a
  * `"!cmd"`. The file ships inside the image, so a literal there is a credential in a readable layer.
@@ -76,6 +145,17 @@ export declare function modelCredentialCarry(runtime: ModelRuntime, spec: string
  * gates what IT causes; what the author wrote into their own committed file, it reports.
  */
 export declare function literalKeyProviders(agentDir: string): Promise<string[]>;
+/**
+ * How the agent's OWN models.json supplies `providerId`'s key, read from the file for the reason
+ * {@link literalKeyProviders} gives: `reference` is the variable a `"$NAME"` reads (the value file must hold it),
+ * `inFile` a key that travels with the definition itself (a literal, or a `"!command"` run on the box), and undefined
+ * no apiKey there at all.
+ */
+export declare function definitionKeyOf(agentDir: string, providerId: string): Promise<{
+    reference: string;
+} | {
+    inFile: true;
+} | undefined>;
 /**
  * What a provider can offer as an interactive login: an OAuth flow, an API-key ENTRY prompt, or nothing ("none" — the
  * key must come from the provider's env var).
@@ -84,7 +164,7 @@ export type InteractiveLoginKind = "oauth" | "api_key" | "none";
 export declare function interactiveLoginKind(p: Provider): InteractiveLoginKind;
 /** THE rule for "can this method be signed in to interactively": the auth to run for it, or undefined. */
 export declare function interactiveAuth(provider: Provider, method: Exclude<InteractiveLoginKind, "none">): import("@earendil-works/pi-ai").ApiKeyAuth | import("@earendil-works/pi-ai").OAuthAuth | undefined;
-/** The providers a sign-in can target: pi's built-ins plus `extra`, composed exactly as {@link createPiModels} does. */
+/** The providers a sign-in can target: pi's built-ins plus `extra`, composed exactly as {@link piModelsOver} does. */
 export declare function loginProviders(extra?: readonly Provider[]): readonly Provider[];
 /** Per-provider auth status for the first-run model picker. */
 export type ProviderAuthStatus = {
@@ -100,7 +180,11 @@ export type ProviderAuthStatus = {
 };
 /** Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe). */
 export declare function providerAuthStatuses(models: Models): Promise<Map<string, ProviderAuthStatus>>;
-/** Which source currently satisfies auth for `spec` — a startup diagnostic. */
+/**
+ * Which source currently satisfies auth for `spec`, or undefined when none does (or the spec is not in `models`).
+ * Rejects when resolving fails — a corrupt entry, a refresh the provider refused — which is a different answer from
+ * "nothing configured" and must reach whoever reports it.
+ */
 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);