@fastagent-sh/fastagent 0.23.0 → 0.24.0

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,5 +1,5 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { type Api, type CredentialStore, InMemoryModelsStore, 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";
 /** 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;
@@ -10,6 +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 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.
@@ -48,36 +59,34 @@ export interface PiModelRuntimeOptions {
  * 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 models.json a runtime for these options loads, and which model catalog it reads. */
-export declare function modelRuntimeFiles(options: Omit<PiModelRuntimeOptions, "credentials">): Promise<{
-    models: {
-        path: string;
-        merged?: {
-            machine: string;
-            definition: string;
-        };
-    } | undefined;
-    create: {
-        modelsPath: string | null;
-        modelsStorePath: string;
-        allowModelNetwork: boolean;
-        catalogBaseUrl?: string | undefined;
-    } | {
-        modelsPath: string | null;
-        modelsStore: InMemoryModelsStore;
-        allowModelNetwork: boolean;
-        catalogBaseUrl?: string | undefined;
-    } | {
+/**
+ * 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;
-        allowModelNetwork: boolean;
-        catalogBaseUrl?: string | undefined;
-    };
-}>;
+        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).
@@ -88,23 +97,15 @@ export declare function machineModelRuntime(options?: {
     catalogBaseUrl?: string;
 }): Promise<ModelRuntime>;
 /**
- * Refresh the machine's catalog ({@link globalCatalogPath}) with the machine's credentials: the global credentials
- * file and the environment. See {@link refreshCatalog} for what it asks and when it rejects.
+ * 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 refreshGlobalModelCatalog(options?: {
-    signal?: AbortSignal;
-    catalogBaseUrl?: string;
-}): Promise<void>;
-/**
- * Fetch the model catalog of every provider the runtime can authenticate into its catalog file: the refresh
- * `pi update --models` runs. `runtime(true)` is built over that file, `runtime(false)` over the read-only layers; the
- * file-backed one is built only once the refresh is known to run, because pi's file store creates the file on read and
- * a refused refresh must leave nothing behind. 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, and when no provider has a
- * usable credential (the refresh would ask for nothing).
- */
-export declare function refreshCatalog(runtime: (catalogFile: boolean) => Promise<ModelRuntime>, options?: {
+export declare function refreshCatalog(catalogFile: string, build: (catalogFile: string) => Promise<ModelRuntime>, options?: {
     signal?: AbortSignal;
 }): Promise<void>;
 /**
@@ -119,12 +120,16 @@ export declare function refreshCatalog(runtime: (catalogFile: boolean) => Promis
  * 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): Promise<ModelRuntime>;
+export declare function createPiModelRuntime(options: PiModelRuntimeOptions & {
+    files?: ModelFiles;
+}): Promise<ModelRuntime>;
 /**
  * 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.

package/dist/engines/pi/models.js

@@ -10,9 +10,9 @@ import { join } from "node:path";
 import { InMemoryCredentialStore, InMemoryModelsStore, defaultProviderAuthContext, } from "@earendil-works/pi-ai";
 import { builtinModels, builtinProviders, getBuiltinModelDataGeneratedAt } from "@earendil-works/pi-ai/providers/all";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
-import { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./auth.js";
 import { AGENT_MODEL_CATALOG_FILE, AGENT_MODELS_FILE, globalHome, resolveOverridePath } from "../../paths.js";
 import { writeFileAtomic } from "../../atomic-write.js";
+import { withLockedFile } from "./locked-file.js";
 /** The built-ins plus `providers` (a same id replaces a built-in), over any credential store. */
 export function piModelsOver(credentials, providers = []) {
     const models = builtinModels({ credentials, authContext: defaultProviderAuthContext() });
@@ -70,30 +70,45 @@ async function modelLayers(agentDir) {
     return { machinePath, machine, own: (await readProviders(join(agentDir, AGENT_MODELS_FILE))) ?? {} };
 }
 /**
- * The models.json pi loads for an agent: its own file, layered over the machine's. The agent's file wins a provider id
- * outright, as a definition's skill wins a name: an agent that pins an endpoint keeps it.
+ * The models.json pi loads for an agent: its own file, layered over the machine's when `machine` is on. The agent's
+ * file wins a provider id outright, as a definition's skill wins a name: an agent that pins an endpoint keeps it.
  *
- * The merge is a SNAPSHOT named by its content, in fastagent's own home: not in the agent (so `info` writes nothing
- * there), and not in a shared temp dir, which the OS clears while a long-running process still re-reads it (pi
- * reloads `modelsPath` on every refresh). Content addressing is what lets every process share the directory: a
- * snapshot is never rewritten, so no process can change what another's refresh reads. The price is that a running
- * process keeps the snapshot it started with; an edit to either file takes effect on the next start.
+ * Always a SNAPSHOT named by its content, in fastagent's own home: pi reloads `modelsPath` on every refresh, and every
+ * session builds its own runtime, so a live file would let turns run on an edit the control plane never read. Not in
+ * the agent (so `info` writes nothing there), and not in a shared temp dir, which the OS clears while a long-running
+ * process still re-reads it. Content addressing is what lets every process share the directory: a snapshot is never
+ * rewritten, so no process can change what another reads. A running process keeps the content it started with; an
+ * edit to either file takes effect on the next start.
  *
  * ponytail: snapshots are never pruned (one per distinct content, a few KB each) because a running process may still
  * read an old one; delete the directory while no fastagent process runs if it ever matters.
  */
-async function modelsFileFor(agentDir) {
+async function modelsFileFor(agentDir, machine) {
     const definition = join(agentDir, AGENT_MODELS_FILE);
-    const layers = await modelLayers(agentDir);
-    if (!layers)
-        return { path: definition };
-    const content = JSON.stringify({ providers: { ...layers.machine, ...layers.own } }, null, 2);
+    const layers = machine ? await modelLayers(agentDir) : undefined;
+    if (layers) {
+        const content = JSON.stringify({ providers: { ...layers.machine, ...layers.own } }, null, 2);
+        return { path: snapshotFile(content), merged: { machine: layers.machinePath, definition } };
+    }
+    let own;
+    try {
+        own = await readFile(definition, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { path: null };
+        throw new Error(`could not read ${definition}: ${error.message}`);
+    }
+    // Verbatim, so pi parses it exactly as it would the file itself.
+    return { path: snapshotFile(own), snapshotOf: definition };
+}
+function snapshotFile(content) {
     const hash = createHash("sha256").update(content).digest("hex").slice(0, 32);
     const path = join(globalHome(), ".cache", "models", `${hash}.json`);
     // 0600: it may carry literal keys. Several processes may create the same snapshot at once.
     if (!existsSync(path))
         writeFileAtomic(path, content, 0o600, true);
-    return { path, merged: { machine: layers.machinePath, definition } };
+    return path;
 }
 /**
  * Where an agent's custom endpoints come from, for a report: the machine file, the providers the agent inherits from
@@ -122,19 +137,63 @@ export function isBuiltinProvider(providerId) {
 export function globalCatalogPath() {
     return join(globalHome(), AGENT_MODEL_CATALOG_FILE);
 }
-/** A catalog file as pi writes it (entries by provider), or `{}` when there is none. */
+/** A catalog file as pi writes it (entries by provider), or `{}` when there is none. Read without a lock: its one
+ *  writer ({@link catalogFileStore}) replaces the file whole, so a read sees the old catalog or the new one. */
 async function readCatalog(path) {
     if (!existsSync(path))
         return {};
+    return parseCatalog(await readFile(path, "utf8"), path);
+}
+/**
+ * The one reading of a catalog file's content, for reads and writes alike. Empty is an empty catalog, as pi reads it:
+ * the writer creates the file exclusively an instant before its first content, and pi's own store, which wrote these
+ * files before, left one behind whenever a refresh it began wrote no entry. That is safe only because nothing writes
+ * these files in place any more: a rewrite in place is read mostly as empty while it runs. Anything else that does not
+ * parse is a corrupt file, and a WRITE refuses it too: serializing over it would drop every other provider's entries.
+ */
+function parseCatalog(content, path) {
+    if (content === "")
+        return {};
     try {
-        return JSON.parse(await readFile(path, "utf8"));
+        return JSON.parse(content);
     }
     catch (error) {
         throw new Error(`model catalog ${path} is not valid JSON (${error.message}): refresh or delete it`);
     }
 }
 /**
- * The catalog files layered into one read-only store, later files winning a model id. An entry pi would ignore (no
+ * 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 function catalogFileStore(path) {
+    const change = (update, signal) => withLockedFile(path, async (current) => {
+        const catalog = parseCatalog(current ?? "", path);
+        update(catalog);
+        return { result: undefined, next: JSON.stringify(catalog, null, 2) };
+    }, signal ? { signal } : {});
+    return {
+        async read(providerId, options) {
+            options?.signal?.throwIfAborted();
+            return (await readCatalog(path))[providerId];
+        },
+        async write(providerId, entry, options) {
+            options?.signal?.throwIfAborted();
+            await change((catalog) => {
+                catalog[providerId] = structuredClone(entry);
+            }, options?.signal);
+        },
+        async delete(providerId, options) {
+            options?.signal?.throwIfAborted();
+            await change((catalog) => {
+                delete catalog[providerId];
+            }, options?.signal);
+        },
+    };
+}
+/**
+ * The catalog files layered into one read-only store, later files winning a (type, model id) pair. An entry pi would ignore (no
  * newer than the catalog bundled with it) is dropped before the merge, so a stale layer cannot ride a newer one's
  * date past pi's rule.
  *
@@ -142,6 +201,16 @@ async function readCatalog(path) {
  * on read, which would drop an empty catalog into every agent dir that was never refreshed.
  */
 async function layeredCatalog(paths) {
+    return catalogStore(await readLayeredCatalog(paths));
+}
+/** A fresh store over a catalog read once: pi may write into the store it is given, so runtimes never share one. */
+async function catalogStore(entries) {
+    const store = new InMemoryModelsStore();
+    for (const [provider, entry] of entries)
+        await store.write(provider, structuredClone(entry));
+    return store;
+}
+async function readLayeredCatalog(paths) {
     const bundledAt = getBuiltinModelDataGeneratedAt();
     const merged = new Map();
     for (const path of paths) {
@@ -149,19 +218,17 @@ async function layeredCatalog(paths) {
             if (bundledAt !== undefined && (entry.lastModified === undefined || entry.lastModified <= bundledAt))
                 continue;
             const held = merged.get(provider);
-            const ids = new Set(entry.models.map((model) => model.id));
+            const key = (model) => `${model.type ?? "chat"}\u0000${model.id}`;
+            const ids = new Set(entry.models.map(key));
             merged.set(provider, held
                 ? {
-                    models: [...held.models.filter((model) => !ids.has(model.id)), ...entry.models],
+                    models: [...held.models.filter((model) => !ids.has(key(model))), ...entry.models],
                     lastModified: Math.max(held.lastModified ?? 0, entry.lastModified ?? 0),
                 }
                 : entry);
         }
     }
-    const store = new InMemoryModelsStore();
-    for (const [provider, entry] of merged)
-        await store.write(provider, entry);
-    return store;
+    return merged;
 }
 /**
  * Whether the machine's model catalog supplies this model, by the same rule every registry reads it with
@@ -169,35 +236,32 @@ async function layeredCatalog(paths) {
  */
 export async function inGlobalCatalog(provider, id) {
     const entry = await (await layeredCatalog([globalCatalogPath()])).read(provider);
-    return entry?.models.some((model) => model.id === id) ?? false;
+    return entry?.models.some((model) => (model.type ?? "chat") === "chat" && model.id === id) ?? false;
 }
 /** The models.json a runtime for these options loads, and which model catalog it reads. */
 export async function modelRuntimeFiles(options) {
     const { agentDir } = options;
     const machine = options.machineLayer !== false;
-    const models = !agentDir
-        ? undefined
-        : machine
-            ? await modelsFileFor(agentDir)
-            : { path: join(agentDir, AGENT_MODELS_FILE) };
+    const models = agentDir ? await modelsFileFor(agentDir, machine) : undefined;
     const catalogs = !agentDir
         ? []
         : [...(machine ? [globalCatalogPath()] : []), join(agentDir, AGENT_MODEL_CATALOG_FILE)];
+    const catalog = !options.catalogFile && agentDir ? await readLayeredCatalog(catalogs) : undefined;
     return {
-        models,
-        create: {
+        ...(models ? { models } : {}),
+        create: async () => ({
             modelsPath: models?.path ?? null,
             // Always a store of our own whenever modelsPath is set: pi's default is a file at
             // `<dirname(modelsPath)>/models-store.json`. Without a directory, pi keeps an empty one in memory.
             ...(options.catalogFile
-                ? { modelsStorePath: options.catalogFile }
-                : agentDir
-                    ? { modelsStore: await layeredCatalog(catalogs) }
+                ? { modelsStore: catalogFileStore(options.catalogFile) }
+                : catalog
+                    ? { modelsStore: await catalogStore(catalog) }
                     : {}),
             // Never fetched while a runtime is built: serving stays offline and reproducible. A refresh is asked for.
             allowModelNetwork: false,
             ...(options.catalogBaseUrl ? { catalogBaseUrl: options.catalogBaseUrl } : {}),
-        },
+        }),
     };
 }
 /**
@@ -208,9 +272,9 @@ export async function machineModelRuntime(options = {}) {
     const runtime = await ModelRuntime.create({
         credentials: options.credentials ?? new InMemoryCredentialStore(),
         modelsPath: machineModelsPath(),
-        ...(options.catalogFile
-            ? { modelsStorePath: options.catalogFile }
-            : { modelsStore: await layeredCatalog([globalCatalogPath()]) }),
+        modelsStore: options.catalogFile
+            ? catalogFileStore(options.catalogFile)
+            : await layeredCatalog([globalCatalogPath()]),
         allowModelNetwork: false,
         ...(options.catalogBaseUrl ? { catalogBaseUrl: options.catalogBaseUrl } : {}),
     });
@@ -219,45 +283,36 @@ export async function machineModelRuntime(options = {}) {
         throw new Error(error);
     return runtime;
 }
-/**
- * Refresh the machine's catalog ({@link globalCatalogPath}) with the machine's credentials: the global credentials
- * file and the environment. See {@link refreshCatalog} for what it asks and when it rejects.
- */
-export async function refreshGlobalModelCatalog(options = {}) {
-    const credentials = fastagentCredentialStore(GLOBAL_AUTH_PATH);
-    await refreshCatalog((catalogFile) => machineModelRuntime({
-        credentials,
-        ...(catalogFile ? { catalogFile: globalCatalogPath() } : {}),
-        ...(options.catalogBaseUrl ? { catalogBaseUrl: options.catalogBaseUrl } : {}),
-    }), options.signal ? { signal: options.signal } : {});
-}
 /** How long a catalog refresh may take, as `pi update --models` allows. */
 const CATALOG_REFRESH_TIMEOUT_MS = 15_000;
 /**
- * Fetch the model catalog of every provider the runtime can authenticate into its catalog file: the refresh
- * `pi update --models` runs. `runtime(true)` is built over that file, `runtime(false)` over the read-only layers; the
- * file-backed one is built only once the refresh is known to run, because pi's file store creates the file on read and
- * a refused refresh must leave nothing behind. 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, and when no provider has a
- * usable credential (the refresh would ask for nothing).
+ * 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 async function refreshCatalog(runtime, options = {}) {
+export async function refreshCatalog(catalogFile, build, options = {}) {
     // pi skips its own background refresh under PI_OFFLINE, but an explicit `allowNetwork: true` overrides that.
     if (process.env.PI_OFFLINE !== undefined)
         throw new Error("PI_OFFLINE is set, so the model catalog is not refreshed");
+    // A corrupt file fails here, once, by its own message: past this point every provider's refresh reads the store and
+    // would repeat it, worded as that provider's failure.
+    await readCatalog(catalogFile);
+    const runtime = await build(catalogFile);
     // pi skips a provider it cannot authenticate without recording anything, so with no usable credential at all the
     // refresh would "succeed" having asked for nothing.
-    const probe = await runtime(false);
-    const refreshable = probe.getProviders().filter((provider) => provider.refreshModels !== undefined);
-    const usable = await Promise.all(refreshable.map(async (provider) => (await probe.checkAuth(provider.id)) !== undefined));
+    const refreshable = runtime.getProviders().filter((provider) => provider.refreshModels !== undefined);
+    const usable = await Promise.all(refreshable.map(async (provider) => (await runtime.checkAuth(provider.id)) !== undefined));
     if (!usable.includes(true)) {
         throw new Error("no provider has a usable credential here, so there is no model catalog to fetch — log in " +
             "(`fastagent login`) or set a provider's API key first");
     }
     const timeout = AbortSignal.timeout(CATALOG_REFRESH_TIMEOUT_MS);
     const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
-    const result = await (await runtime(true)).refresh({ allowNetwork: true, force: true, signal });
+    const result = await runtime.refresh({ allowNetwork: true, force: true, signal });
     if (result.aborted) {
         throw new Error(options.signal?.aborted
             ? "model catalog refresh cancelled"
@@ -290,25 +345,47 @@ export async function environmentAuthSource(providerId, env, fileExists = defaul
     });
     return (await models.checkAuth(providerId))?.source;
 }
+/** Pi registration starts background refreshes; wait for all of them before publishing this fresh runtime. */
+export async function withModelRegistration(runtime, register) {
+    const refresh = runtime.refresh;
+    const refreshes = [];
+    runtime.refresh = (...args) => {
+        const pending = refresh.apply(runtime, args);
+        refreshes.push(pending);
+        return pending;
+    };
+    try {
+        const result = await register();
+        await Promise.all(refreshes);
+        return result;
+    }
+    finally {
+        runtime.refresh = refresh;
+    }
+}
 /**
  * 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 async function createPiModelRuntime(options) {
-    const { models, create } = await modelRuntimeFiles(options);
-    const runtime = await ModelRuntime.create({ credentials: options.credentials, ...create });
+    const { models, create } = options.files ?? (await modelRuntimeFiles(options));
+    const runtime = await ModelRuntime.create({ credentials: options.credentials, ...(await create()) });
     // A malformed models.json does NOT throw upstream — `create` resolves with the built-ins and parks the reason in
     // getError().
     const error = runtime.getError();
     if (error) {
         const origin = models?.merged
             ? `\n\nThat file merges ${models.merged.machine} with ${models.merged.definition} (the agent's own wins a provider id).`
-            : "";
+            : models?.snapshotOf
+                ? `\n\nThat file is ${models.snapshotOf} as read at startup.`
+                : "";
         throw new Error(`${error}${origin}`);
     }
-    for (const provider of options.providers ?? [])
-        runtime.registerNativeProvider(provider);
+    await withModelRegistration(runtime, async () => {
+        for (const provider of options.providers ?? [])
+            runtime.registerNativeProvider(provider);
+    });
     return runtime;
 }
 /**
@@ -417,6 +494,9 @@ export async function probeAuthSource(models, spec) {
     const model = models.getModel(spec.slice(0, slash), spec.slice(slash + 1));
     if (!model)
         return undefined;
+    // A virtual selection authenticates the physical model after routing, not its catalog entry.
+    if (model.api === "pi-virtual")
+        return "virtual";
     return (await models.getAuth(model))?.source;
 }
 /** Quick-fail probe for a just-stored API key. */