@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/engines/pi/models.js

@@ -1,24 +1,18 @@
 /**
- * The pi `Models` collection — the single hub that owns BOTH model resolution (provider/modelId lookup) AND auth
- * (per-request credential resolution). fastagent builds one per opener and threads it into the engine alongside the
- * selected `model`; the two must come from the same collection so the model's provider auth is in scope.
+ * Building pi's model registry: the built-ins, an agent's `models.json` and model catalog layered over the machine's,
+ * the catalog refresh, and the reads of those files a report or a deploy check needs. Which credential store an agent
+ * runs it over is agent-models.ts's; registry and auth are one collection, so the model's provider auth is in scope.
  */
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
-import { InMemoryCredentialStore, defaultProviderAuthContext, } from "@earendil-works/pi-ai";
-import { builtinModels, builtinProviders } from "@earendil-works/pi-ai/providers/all";
+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 { fastagentCredentialStore } from "./auth.js";
-import { providerOf } from "./config.js";
-import { AGENT_MODELS_FILE, GLOBAL_HOME_DIR, resolveOverridePath, resolveStateRoot } from "../../paths.js";
+import { AGENT_MODEL_CATALOG_FILE, AGENT_MODELS_FILE, globalHome, resolveOverridePath } from "../../paths.js";
 import { writeFileAtomic } from "../../atomic-write.js";
-/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
-export function createPiModels(options = {}) {
-    return piModelsOver(fastagentCredentialStore(options.authPath, { warn: options.warn }), options.providers);
-}
+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() });
@@ -33,8 +27,8 @@ export const DEFAULT_THINKING_LEVEL = "medium";
  * (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 function machineModelsPath(env = process.env) {
-    return resolveOverridePath(env.FASTAGENT_MODELS_PATH) ?? join(homedir(), GLOBAL_HOME_DIR, AGENT_MODELS_FILE);
+function machineModelsPath(env = process.env) {
+    return resolveOverridePath(env.FASTAGENT_MODELS_PATH) ?? join(globalHome(), AGENT_MODELS_FILE);
 }
 /** A custom-endpoint file's providers by id, or undefined when there is no file. Strict JSON: see {@link modelLayers}. */
 async function readProviders(path) {
@@ -76,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(homedir(), GLOBAL_HOME_DIR, ".cache", "models", `${hash}.json`);
+    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
@@ -120,49 +129,265 @@ export async function machineModels(agentDir) {
 export function isBuiltinProvider(providerId) {
     return builtinProviders().some((provider) => provider.id === providerId);
 }
-/** The `ModelRuntime`-shaped sibling of {@link createPiModels}. */
-export async function createPiModelRuntime(options = {}) {
+/**
+ * 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 function globalCatalogPath() {
+    return join(globalHome(), AGENT_MODEL_CATALOG_FILE);
+}
+/** 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(content);
+    }
+    catch (error) {
+        throw new Error(`model catalog ${path} is not valid JSON (${error.message}): refresh or delete it`);
+    }
+}
+/**
+ * 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.
+ *
+ * Read here rather than handed to pi as a file: pi takes one store, and its file store creates the file (and a lock)
+ * 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) {
+        for (const [provider, entry] of Object.entries(await readCatalog(path))) {
+            if (bundledAt !== undefined && (entry.lastModified === undefined || entry.lastModified <= bundledAt))
+                continue;
+            const held = merged.get(provider);
+            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(key(model))), ...entry.models],
+                    lastModified: Math.max(held.lastModified ?? 0, entry.lastModified ?? 0),
+                }
+                : entry);
+        }
+    }
+    return merged;
+}
+/**
+ * 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 async function inGlobalCatalog(provider, id) {
+    const entry = await (await layeredCatalog([globalCatalogPath()])).read(provider);
+    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 models = !agentDir
-        ? undefined
-        : options.machineLayer === false
-            ? { path: join(agentDir, AGENT_MODELS_FILE) }
-            : await modelsFileFor(agentDir);
+    const machine = options.machineLayer !== false;
+    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 ? { 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
+                ? { 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 } : {}),
+        }),
+    };
+}
+/**
+ * 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 async function machineModelRuntime(options = {}) {
     const runtime = await ModelRuntime.create({
-        credentials: options.credentials ??
-            fastagentCredentialStore(options.auth?.path, { warn: options.warn, fallbackPath: options.auth?.fallback }),
-        modelsPath: models?.path ?? null,
-        // MUST be set whenever modelsPath is: pi defaults this to `<dirname(modelsPath)>/models-store.json`, which would
-        // write a generated cache INTO the author's agent dir.
-        ...(agentDir
-            ? { modelsStorePath: join(options.stateRoot ?? resolveStateRoot(agentDir), "models-store.json") }
-            : {}),
+        credentials: options.credentials ?? new InMemoryCredentialStore(),
+        modelsPath: machineModelsPath(),
+        modelsStore: options.catalogFile
+            ? catalogFileStore(options.catalogFile)
+            : await layeredCatalog([globalCatalogPath()]),
         allowModelNetwork: false,
+        ...(options.catalogBaseUrl ? { catalogBaseUrl: options.catalogBaseUrl } : {}),
     });
+    const error = runtime.getError();
+    if (error)
+        throw new Error(error);
+    return runtime;
+}
+/** 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 `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(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 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 runtime.refresh({ allowNetwork: true, force: true, signal });
+    if (result.aborted) {
+        throw new Error(options.signal?.aborted
+            ? "model catalog refresh cancelled"
+            : `model catalog refresh did not finish within ${CATALOG_REFRESH_TIMEOUT_MS / 1000}s`);
+    }
+    if (result.errors.size > 0) {
+        const details = [...result.errors].map(([provider, error]) => `${provider}: ${error.message}`).join("; ");
+        throw new Error(`could not refresh the model catalog: ${details}`);
+    }
+}
+/**
+ * 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 async function environmentAuthSource(providerId, env, fileExists = defaultProviderAuthContext().fileExists) {
+    const models = builtinModels({
+        credentials: new InMemoryCredentialStore(),
+        authContext: {
+            // pi's own reading of a variable (a blank one is unset), over the given environment.
+            env: async (name) => (env[name]?.trim() ? env[name] : undefined),
+            fileExists,
+        },
+    });
+    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 } = 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;
 }
-/** How a model's credential will REACH a deployed agent. */
-export function modelCredentialCarry(runtime, spec) {
-    const status = runtime.getProviderAuthStatus(providerOf(spec));
-    if (!status.configured)
-        return { inDefinition: false };
-    // An env-var name is only useful downstream if it IS one.
-    if (status.source === "environment" && status.label && /^[A-Z][A-Z0-9_]*$/.test(status.label)) {
-        return { envVar: status.label, inDefinition: false };
-    }
-    return { inDefinition: status.source !== "stored" };
-}
 /**
  * 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.
@@ -178,6 +403,27 @@ export function modelCredentialCarry(runtime, spec) {
  * gates what IT causes; what the author wrote into their own committed file, it reports.
  */
 export async function literalKeyProviders(agentDir) {
+    return Object.entries(await definitionApiKeys(agentDir))
+        .filter(([, apiKey]) => isLiteralKey(apiKey))
+        .map(([id]) => id);
+}
+/**
+ * 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 async function definitionKeyOf(agentDir, providerId) {
+    const apiKey = (await definitionApiKeys(agentDir))[providerId];
+    if (typeof apiKey !== "string" || apiKey === "")
+        return undefined;
+    if (apiKey.startsWith("!") || isLiteralKey(apiKey))
+        return { inFile: true };
+    // Not a literal, so isLiteralKey's own pattern matched: there is a name to read.
+    return { reference: apiKey.replaceAll("$$", "").match(/\$\{?([A-Za-z_][A-Za-z0-9_]*)/)?.[1] };
+}
+/** Each provider's `apiKey` as the agent's own models.json writes it. */
+async function definitionApiKeys(agentDir) {
     const file = join(agentDir, AGENT_MODELS_FILE);
     let raw;
     try {
@@ -186,15 +432,13 @@ export async function literalKeyProviders(agentDir) {
     catch (error) {
         // No custom endpoints is the normal case; anything else (unreadable, a directory) is the caller's problem.
         if (error.code === "ENOENT")
-            return [];
+            return {};
         throw error;
     }
     // Malformed JSON already threw out of createPiModelRuntime before this runs, so a parse failure here would be a
     // genuine surprise and must not be swallowed.
     const providers = JSON.parse(raw).providers ?? {};
-    return Object.entries(providers)
-        .filter(([, provider]) => isLiteralKey(provider?.apiKey))
-        .map(([id]) => id);
+    return Object.fromEntries(Object.entries(providers).map(([id, provider]) => [id, provider?.apiKey]));
 }
 /**
  * `!cmd` runs on the box; `$NAME` / `${NAME}` reads the environment; anything else is the key itself.
@@ -216,7 +460,7 @@ export function interactiveLoginKind(p) {
 export function interactiveAuth(provider, method) {
     return method === "oauth" ? provider.auth.oauth : provider.auth.apiKey?.login ? provider.auth.apiKey : 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 function loginProviders(extra) {
     return piModelsOver(new InMemoryCredentialStore(), extra).getProviders();
 }
@@ -238,7 +482,11 @@ export async function providerAuthStatuses(models) {
     }
     return statuses;
 }
-/** 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 async function probeAuthSource(models, spec) {
     const slash = spec.indexOf("/");
     if (slash < 1)
@@ -246,8 +494,10 @@ export async function probeAuthSource(models, spec) {
     const model = models.getModel(spec.slice(0, slash), spec.slice(slash + 1));
     if (!model)
         return undefined;
-    const auth = await models.getAuth(model).catch(() => undefined);
-    return auth?.source;
+    // 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. */
 export async function probeApiKey(models, model, signal) {

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

@@ -1,10 +1,13 @@
 import type { Agent } from "../../agent.ts";
-import { type AuthLayers, type FastagentConfig } from "./config.ts";
-import type { AgentCommand, SessionControl } from "../../session.ts";
+import { type FastagentConfig } from "./config.ts";
+import type { AgentCommand, ModelDescriptor, SessionControl } from "../../session.ts";
+import { type IndirectTool, type PiAssembly } from "./create.ts";
 import type { SessionObserver } from "./turn-kit.ts";
 import { type LoadedDefinition } from "./definition.ts";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
-import type { FastagentAuthOptions } from "./auth.ts";
+import type { CredentialStore } from "@earendil-works/pi-ai";
+import type { CredentialSourceOptions, FastagentAuthOptions } from "./auth.ts";
+import { type AgentModels } from "./agent-models.ts";
 import { type PiSessionRecordStore } from "./session-store.ts";
 import type { ToolCollision, MountedTool } from "./tool.ts";
 import type { DeclaredSecret } from "../../declared-secrets.ts";
@@ -36,6 +39,8 @@ export interface CreatePiAgentFromDirOptions {
     sessionsDir?: string;
     /** Credentials file override. */
     authPath?: string;
+    /** The caller's own credential store, in place of any file ({@link CredentialSourceOptions}). */
+    credentialStore?: CredentialStore;
     /**
      * This is a long-running SERVE (`dev`/`start`), where the scheduler poller runs — so a self-scheduled wake-up is
      * actually honored.
@@ -65,32 +70,72 @@ export interface AgentAssembly {
     workspace: string;
     /** Absolute state root (FASTAGENT_STATE_DIR > <agentDir>/.state). */
     stateRoot: string;
-    /** The credentials files it reads ({@link resolveAuthLayers}). */
-    auth: AuthLayers;
-    /** The full mounted tool surface (all coding tools + config.tools + discovered tools/, search_tools applied). */
+    /** The credential store and model registry every turn and every report reads ({@link agentModels}). */
+    models: AgentModels;
+    /** The full mounted tool surface (all coding tools + config.tools + discovered tools/). */
     tools: MountedTool[];
     toolNames: string[];
-    deferredToolNames: string[];
+    indirectTools: IndirectTool[];
     toolCollisions: ToolCollision[];
     /** Env vars the mounted tools declared, by tool name — already asserted present by this function. */
     toolSecrets: Map<string, DeclaredSecret[]>;
 }
 export declare function resolveAgentAssembly(dir: string, options?: {
     model?: string;
-    authPath?: string;
-}): Promise<AgentAssembly>;
+} & CredentialSourceOptions): Promise<AgentAssembly>;
+/**
+ * L2 over a resolved front half: the ONE mapping from what the directory resolved to what the assembly runs on, for
+ * both session shapes (the served agent and `chat`'s resident one). Two copies of it drifted once (#566, chat ran at
+ * the wrong reasoning effort). `models` is the front's own, so the assembly runs on what the report describes.
+ */
+export declare function assembleFront(front: AgentAssembly, extra?: {
+    tools?: MountedTool[];
+    sessions?: PiSessionRecordStore;
+}): Promise<{
+    assembly: PiAssembly;
+    definition: LoadedDefinition;
+}>;
 /**
- * The model specs `createPiAgentFromDir(dir, { authPath })` could run now: the agent's registry (pi's built-ins plus
- * its `models.json`) filtered to the providers whose credentials are configured, sorted. The directory needs no model
- * set, and the same placement and credential layers as the opener apply, so a listed spec authenticates there.
- * Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
+ * The models `createPiAgentFromDir(dir, { authPath })` could run now, as a picker shows them (spec, name, the thinking
+ * levels a session on it accepts, context window), sorted by spec: the agent's registry (pi's built-ins, its
+ * `models.json`, and what its `extensions/` declare) filtered to the providers whose credentials are configured. The
+ * directory needs no model set, and the same placement and credential layers as the opener apply, so a listed spec
+ * authenticates there. Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
  *
  * `warn` reaches the credential store. An unreadable or corrupt credentials file otherwise reads as "nothing
  * configured", so a client that must not show that as an empty list passes a sink that throws.
  */
-export declare function availableModelsFromDir(dir: string, options?: FastagentAuthOptions & {
-    authPath?: string;
-}): Promise<string[]>;
+export declare function availableModelsFromDir(dir: string, options?: FastagentAuthOptions & CredentialSourceOptions): Promise<ModelDescriptor[]>;
+/**
+ * Refresh the agent's model catalog (`<agent dir>/models-store.json`) with the credentials
+ * `createPiAgentFromDir(dir, { authPath })` would use, so a model released after the installed pi appears in
+ * {@link availableModelsFromDir} and runs. Only providers those credentials authenticate are fetched (pi asks pi.dev
+ * for no other). Nothing refreshes it on its own. The file is part of the definition: commit it, and it ships with a
+ * deploy, so the deployed agent knows the same models without a network call.
+ *
+ * Rejects, naming each provider that failed, when the refresh fails, outlasts 15 seconds or `PI_OFFLINE` is set, and
+ * when the credentials authenticate no provider at all.
+ */
+export declare function refreshModelCatalog(dir: string, options?: FastagentAuthOptions & CredentialSourceOptions & {
+    signal?: AbortSignal;
+}): Promise<void>;
+/** {@link refreshModelCatalog} against another catalog server. Not public: a test seam. */
+export declare function refreshModelCatalogOver(dir: string, options: FastagentAuthOptions & CredentialSourceOptions & {
+    signal?: AbortSignal;
+}, catalogBaseUrl?: string): Promise<void>;
+/**
+ * Refresh the MACHINE's model catalog (`~/.fastagent/models-store.json`), which every agent here reads under its own,
+ * so one refresh serves them all and no file is written into any agent. Credentials resolve as for
+ * {@link refreshModelCatalog} without a directory: `credentialStore`, else `authPath`, else the global credentials file;
+ * the environment applies either way. Rejects for the same reasons. The file never ships with a deploy.
+ */
+export declare function refreshMachineModelCatalog(options?: FastagentAuthOptions & CredentialSourceOptions & {
+    signal?: AbortSignal;
+}): Promise<void>;
+/** {@link refreshMachineModelCatalog} against another catalog server. Not public: a test seam. */
+export declare function refreshMachineModelCatalogOver(options: FastagentAuthOptions & CredentialSourceOptions & {
+    signal?: AbortSignal;
+}, catalogBaseUrl?: string): Promise<void>;
 /**
  * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or the agent dir
  * itself), load the config, resolve model and tools, then L2.
@@ -110,8 +155,8 @@ export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgen
     stateRoot: string;
     /** Absolute session store directory in use (for the startup report). */
     sessionsDir: string;
-    /** The credentials files in use — the startup report names whichever layer the credential came from. */
-    auth: AuthLayers;
+    /** The credential store and registry the agent runs on — what the startup report describes. */
+    models: AgentModels;
     sessions: PiSessionRecordStore;
     /** The observation plane over this agent's sessions; present on every serve (a channel's stop command reaches the
      *  live run through it). Its boundary is wired only when {@link publishControl}. */
@@ -122,7 +167,7 @@ export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgen
     http?: HttpSurface;
     /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. */
     toolNames: string[];
-    /** Tools registered but not initially active (deferred) — activated via search_tools. */
-    deferredToolNames: string[];
+    /** Mounted authored tools the model is not given up front, with how each is reached. */
+    indirectTools: IndirectTool[];
     toolCollisions: ToolCollision[];
 }>;