@fastagent-sh/fastagent 0.22.0 → 0.23.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 { 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";
-/** 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);
-}
 /** 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) {
@@ -95,7 +89,7 @@ async function modelsFileFor(agentDir) {
         return { path: definition };
     const content = JSON.stringify({ providers: { ...layers.machine, ...layers.own } }, null, 2);
     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);
@@ -120,25 +114,190 @@ 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. */
+async function readCatalog(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    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
+ * 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) {
+    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 ids = new Set(entry.models.map((model) => model.id));
+            merged.set(provider, held
+                ? {
+                    models: [...held.models.filter((model) => !ids.has(model.id)), ...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;
+}
+/**
+ * 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.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
-        : options.machineLayer === false
-            ? { path: join(agentDir, AGENT_MODELS_FILE) }
-            : await modelsFileFor(agentDir);
+        : machine
+            ? await modelsFileFor(agentDir)
+            : { path: join(agentDir, AGENT_MODELS_FILE) };
+    const catalogs = !agentDir
+        ? []
+        : [...(machine ? [globalCatalogPath()] : []), join(agentDir, AGENT_MODEL_CATALOG_FILE)];
+    return {
+        models,
+        create: {
+            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) }
+                    : {}),
+            // 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(),
+        ...(options.catalogFile
+            ? { modelsStorePath: options.catalogFile }
+            : { modelsStore: await layeredCatalog([globalCatalogPath()]) }),
         allowModelNetwork: false,
+        ...(options.catalogBaseUrl ? { catalogBaseUrl: options.catalogBaseUrl } : {}),
+    });
+    const error = runtime.getError();
+    if (error)
+        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).
+ */
+export async function refreshCatalog(runtime, 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");
+    // 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));
+    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 });
+    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;
+}
+/**
+ * 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 });
     // A malformed models.json does NOT throw upstream — `create` resolves with the built-ins and parks the reason in
     // getError().
     const error = runtime.getError();
@@ -152,17 +311,6 @@ export async function createPiModelRuntime(options = {}) {
         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 +326,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 +355,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 +383,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 +405,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 +417,7 @@ 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;
+    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 FastagentConfig } from "./config.ts";
 import type { AgentCommand, SessionControl } from "../../session.ts";
+import { 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,8 +70,8 @@ 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 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/, search_tools applied). */
     tools: MountedTool[];
     toolNames: string[];
@@ -77,8 +82,19 @@ export interface AgentAssembly {
 }
 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
@@ -88,9 +104,24 @@ export declare function resolveAgentAssembly(dir: string, options?: {
  * `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<string[]>;
+/**
+ * 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>;
 /**
  * "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 +141,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}. */

package/dist/engines/pi/open.js

@@ -3,9 +3,10 @@
  * drive.
  */
 import { mkdir } from "node:fs/promises";
-import { loadConfig, resolveAuthLayers, resolveModelSpec, } from "./config.js";
-import { resolveSessionsDir, resolveStateRoot, resolvePlacement } from "../../paths.js";
-import { agentOf, assemblePiFromDefinition, definitionModelRuntime, resolveAgentTools } from "./create.js";
+import { join } from "node:path";
+import { loadConfig, resolveModelSpec } from "./config.js";
+import { AGENT_MODEL_CATALOG_FILE, resolveSessionsDir, resolveStateRoot, resolvePlacement } from "../../paths.js";
+import { agentOf, assemblePiFromDefinition, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
 import { refuseBrokenDeclarations } from "../../loader.js";
@@ -13,6 +14,8 @@ import { loadAgentSkills } from "./definition.js";
 import { servedExtensionCommands } from "./agent-session-factory.js";
 import { reportFindingsIfChanged } from "./report.js";
 import { readMachine, withMachine } from "./machine.js";
+import { createPiModelRuntime, refreshCatalog } from "./models.js";
+import { agentModels } from "./agent-models.js";
 import { piSessionRecordStore } from "./session-store.js";
 import { gateSecrets } from "../../secrets-gate.js";
 /**
@@ -83,8 +86,6 @@ export async function resolveAgentAssembly(dir, options = {}) {
     // The state root: sessions/channel state/schedule state derive from it (FASTAGENT_STATE_DIR moves it in one knob —
     // a container points it at its volume).
     const stateRoot = resolveStateRoot(agentDir);
-    // The credentials file: project-level by default (under `<agentDir>/.secrets`).
-    const auth = resolveAuthLayers(agentDir, options.authPath);
     return {
         config,
         configPath,
@@ -92,7 +93,8 @@ export async function resolveAgentAssembly(dir, options = {}) {
         agentDir,
         workspace,
         stateRoot,
-        auth,
+        // Project-level by default (under `<agentDir>/.secrets`), with the global file behind it per provider.
+        models: agentModels(agentDir, options),
         tools,
         toolNames,
         deferredToolNames,
@@ -100,6 +102,21 @@ export async function resolveAgentAssembly(dir, options = {}) {
         toolSecrets,
     };
 }
+/**
+ * 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 function assembleFront(front, extra = {}) {
+    return assemblePiFromDefinition(front.agentDir, {
+        model: front.modelSpec,
+        thinkingLevel: front.config.thinkingLevel,
+        cwd: front.workspace,
+        tools: extra.tools ?? front.tools,
+        models: front.models,
+        ...(extra.sessions ? { sessions: extra.sessions } : {}),
+    });
+}
 /**
  * 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
@@ -111,18 +128,40 @@ export async function resolveAgentAssembly(dir, options = {}) {
  */
 export async function availableModelsFromDir(dir, options = {}) {
     const { agentDir } = resolvePlacement(dir);
-    const models = await definitionModelRuntime(agentDir, {
-        auth: resolveAuthLayers(agentDir, options.authPath),
-        ...(options.warn ? { warn: options.warn } : {}),
-    });
+    const models = await agentModels(agentDir, options).runtime();
     return (await models.getAvailable()).map((model) => `${model.provider}/${model.id}`).sort();
 }
+/**
+ * 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 function refreshModelCatalog(dir, options = {}) {
+    return refreshModelCatalogOver(dir, options);
+}
+/** {@link refreshModelCatalog} against another catalog server. Not public: a test seam. */
+export async function refreshModelCatalogOver(dir, options, catalogBaseUrl) {
+    const { agentDir } = resolvePlacement(dir);
+    const { credentials } = agentModels(agentDir, options);
+    await refreshCatalog((catalogFile) => createPiModelRuntime({
+        agentDir,
+        credentials,
+        ...(catalogFile ? { catalogFile: join(agentDir, AGENT_MODEL_CATALOG_FILE) } : {}),
+        ...(catalogBaseUrl ? { catalogBaseUrl } : {}),
+    }), options.signal ? { signal: options.signal } : {});
+}
 /**
  * "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.
  */
 export async function createPiAgentFromDir(dir, options = {}) {
-    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, auth, tools, toolNames, deferredToolNames, toolCollisions, } = await resolveAgentAssembly(dir, options);
+    const front = await resolveAgentAssembly(dir, options);
+    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, models, tools, toolNames, deferredToolNames, toolCollisions, } = front;
     // Every serve mounts the built-in `wake` tool: the agent's own follow-up work is a default capability, and a serve
     // is where the poller that honors it runs. A one-shot `invoke` has no poller, so nothing there would fire it.
     const mountedTools = withWakeTool(tools, stateRoot, !!options.serving);
@@ -131,15 +170,8 @@ export async function createPiAgentFromDir(dir, options = {}) {
     const sessionsDir = options.sessionsDir ?? resolveSessionsDir(agentDir);
     await mkdir(sessionsDir, { recursive: true });
     const sessions = piSessionRecordStore({ dir: sessionsDir, cwd: workspace });
-    const { assembly, definition } = await assemblePiFromDefinition(agentDir, {
-        model: modelSpec,
-        thinkingLevel: config.thinkingLevel,
-        cwd: workspace,
-        tools: mountedTools,
-        auth,
-        // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
-        sessions,
-    });
+    // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
+    const { assembly, definition } = await assembleFront(front, { tools: mountedTools, sessions });
     // The hub is wired HERE because the store is created here (an external `createPiSessionControl` cannot exist before
     // the store does).
     const caller = options.observer;
@@ -199,7 +231,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
         modelSpec,
         stateRoot,
         sessionsDir,
-        auth,
+        models,
         toolNames,
         deferredToolNames,
         toolCollisions,

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

@@ -1,8 +1,8 @@
 /** `createAgentService` — the product as one call, with pi supplying the engine. */
 import { type AgentService, type MountAgentServiceOptions } from "../../service.ts";
-export interface CreateAgentServiceOptions extends MountAgentServiceOptions {
+import type { CredentialSourceOptions } from "./auth.ts";
+export interface CreateAgentServiceOptions extends MountAgentServiceOptions, CredentialSourceOptions {
     model?: string;
-    authPath?: string;
     sessionsDir?: string;
 }
 /** Open an agent directory as a live service: one handler, mounted wherever you serve. */

package/dist/engines/pi/service.js

@@ -6,6 +6,7 @@ export async function createAgentService(dir, options = {}) {
     const opened = await createPiAgentFromDir(dir, {
         ...(options.model !== undefined ? { model: options.model } : {}),
         ...(options.authPath !== undefined ? { authPath: options.authPath } : {}),
+        ...(options.credentialStore !== undefined ? { credentialStore: options.credentialStore } : {}),
         ...(options.sessionsDir !== undefined ? { sessionsDir: options.sessionsDir } : {}),
         serving: true, // a mounted service is long-running: the scheduler poller runs
     });

package/dist/engines/pi/session-builder.d.ts

@@ -6,7 +6,8 @@ export interface BuildSessionRuntimeOptions {
     authPath?: string;
 }
 /**
- * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools, skills, and auth
- * resolved exactly as the serving opener does).
+ * Build pi's interactive runtime over the SAME assembly `dev`/`start` serve ({@link assembleFront}): model
+ * registry, prompt, tools, skills, reasoning effort and credentials all come from it, so what differs is only the
+ * session's shape (one resident runtime rather than one session per invoke).
  */
 export declare function buildAgentSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, sessionManager?: SessionManager): Promise<AgentSessionRuntime>;