@fastagent-sh/fastagent 0.22.0 → 0.23.0

package/dist/engines/pi/agent-models.js

@@ -0,0 +1,93 @@
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { GLOBAL_AUTH_PATH, assertOneCredentialSource, fastagentCredentialStore, resolveAuthLayers, } from "./auth.js";
+import { createPiModelRuntime, environmentAuthSource, modelRuntimeFiles, piModelsOver, probeAuthSource, } from "./models.js";
+export function agentModels(agentDir, source = {}, options = {}) {
+    assertOneCredentialSource(source);
+    const { providers, machineLayer } = options;
+    const files = source.credentialStore
+        ? undefined
+        : agentDir
+            ? resolveAuthLayers(agentDir, source.authPath)
+            : { path: source.authPath ?? GLOBAL_AUTH_PATH };
+    const store = files
+        ? agentCredentialStore(files, { agentDir, providers, machineLayer, warn: source.warn })
+        : undefined;
+    const credentials = source.credentialStore ?? store;
+    let registry;
+    const runtime = () => {
+        registry ??= createPiModelRuntime({
+            credentials,
+            ...(agentDir ? { agentDir } : {}),
+            ...(providers ? { providers } : {}),
+            ...(machineLayer !== undefined ? { machineLayer } : {}),
+        });
+        return registry;
+    };
+    return {
+        ...(files ? { auth: files } : {}),
+        credentials,
+        runtime,
+        async authStatus(provider, modelId) {
+            const models = await runtime();
+            const id = modelId ?? models.getProvider(provider)?.getModels()[0]?.id;
+            let resolved = {};
+            if (id !== undefined) {
+                try {
+                    const found = await probeAuthSource(models, `${provider}/${id}`);
+                    if (found !== undefined)
+                        resolved = { source: found };
+                }
+                catch (error) {
+                    // The first line: pi folds the request's stack into the message of a failed refresh.
+                    resolved = { error: String(error.message).split("\n")[0] };
+                }
+            }
+            // `read` never refreshes: this is the kind on file, whatever became of it.
+            const stored = (await credentials.read(provider))?.type;
+            const fromEnvironment = stored === undefined ? undefined : await environmentAuthSource(provider, process.env);
+            const shadowed = resolved.source !== undefined && fromEnvironment !== resolved.source ? fromEnvironment : undefined;
+            return {
+                ...(store ? { path: await store.layerOf(provider) } : {}),
+                ...resolved,
+                ...(stored !== undefined ? { stored } : {}),
+                ...(shadowed !== undefined ? { shadowed } : {}),
+            };
+        },
+    };
+}
+/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
+export function createPiModels(options = {}) {
+    return piModelsOver(agentModels(undefined, options).credentials, options.providers);
+}
+/**
+ * The credential store an agent reads through: its own file, then the user-global one for a provider the PROJECT
+ * authenticates no other way (its own auth file, a models.json key, or the environment). "No other way" is answered
+ * by pi's own resolution over a registry that has no global layer, built the first time a provider is looked up
+ * there. A deployment never has the global file, so a global login that outranked, say, an `ANTHROPIC_API_KEY` in
+ * `.secrets/.env` would run one credential here and a different one deployed.
+ */
+function agentCredentialStore(auth, options) {
+    const { warn, providers = [] } = options;
+    const fallback = auth.fallback;
+    if (fallback === undefined)
+        return fastagentCredentialStore(auth.path, { warn });
+    let project;
+    const projectRuntime = () => {
+        project ??= (async () => {
+            const runtime = await ModelRuntime.create({
+                credentials: fastagentCredentialStore(auth.path, { warn }),
+                ...(await modelRuntimeFiles(options)).create,
+                refreshOnCreate: false,
+            });
+            for (const provider of providers)
+                runtime.registerNativeProvider(provider);
+            return runtime;
+        })();
+        return project;
+    };
+    return fastagentCredentialStore(auth.path, {
+        warn,
+        fallbackPath: fallback,
+        projectAuthenticates: async (providerId) => (await (await projectRuntime()).checkAuth(providerId)) !== undefined,
+    });
+}

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

@@ -8,15 +8,68 @@ export interface FastagentAuthOptions {
     /** Sink for non-fatal auth anomalies (unreadable/corrupt file). */
     warn?: (message: string) => void;
 }
+/**
+ * Where a caller's model credentials live: fastagent's JSON file (`authPath`, or the default layers when neither is
+ * given), or a {@link CredentialStore} the caller owns (an OS keychain, Electron `safeStorage`). A supplied store
+ * replaces the FILES: none is read or written, and no global layer applies. Env variables and `models.json` keys still
+ * apply, below a stored credential, exactly as with `authPath`. The store owns what the file store does
+ * for its file: `modify` for one provider must run one at a time, because an OAuth refresh happens inside it and a
+ * rotated refresh token must never be used twice; and a store it cannot parse must not be answered as empty, or the
+ * next write replaces every provider's credential.
+ */
+export interface CredentialSourceOptions {
+    /** fastagent's credentials file. Mutually exclusive with {@link credentialStore}. */
+    authPath?: string;
+    /** The caller's own store, read and written instead of any file. Mutually exclusive with {@link authPath}. */
+    credentialStore?: CredentialStore;
+}
+/** The one refusal for a caller that names both sources: silently preferring one would hide the other's mistake. */
+export declare function assertOneCredentialSource(options: CredentialSourceOptions): void;
+/** A credential store over fastagent's files, which can also say which file a provider belongs to. */
+export type FastagentCredentialStore = CredentialStore & {
+    /**
+     * The file this store reads a provider from and writes its refresh to: where it already is, else the primary. The
+     * one answer to "which file do I edit", so a report naming a file cannot disagree with the store that reads it.
+     */
+    layerOf(providerId: string): Promise<string>;
+};
 /**
  * A read-write `CredentialStore` over the given credentials file (default {@link GLOBAL_AUTH_PATH}; the directory
- * opener passes the project-level `<root>/.secrets/auth.json`), optionally falling back to a second file.
+ * opener passes the project-level `<root>/.secrets/auth.json`), optionally falling back to a second file. A path is
+ * read like `FASTAGENT_AUTH_PATH` (`~` is the home directory, a relative one resolves against the cwd), so every
+ * caller that names a file names the same one.
  *
  * The fallback is PER PROVIDER, not per file: logging one provider into a project must not hide the others a person
  * already has globally. And the layer a credential was READ from is the layer its refresh is written back to —
  * anything else would conjure a second holder of the same OAuth grant, which is the failure this whole area exists
  * to avoid. A provider present in neither layer is new, and new credentials belong to the primary.
+ *
+ * The fallback also yields to `projectAuthenticates`: a provider the project authenticates some other way (an env key,
+ * its own models.json) never reaches it — for reading, listing or writing back.
  */
-export declare function fastagentCredentialStore(authPath?: string, options?: FastagentAuthOptions & {
+export declare function fastagentCredentialStore(path?: string, options?: FastagentAuthOptions & {
     fallbackPath?: string;
-}): CredentialStore;
+    /** Whether the project authenticates this provider without the fallback; then the fallback is not read for it. */
+    projectAuthenticates?: (providerId: string) => Promise<boolean>;
+}): FastagentCredentialStore;
+/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
+export declare function resolveAuthPath(dir: string, flag?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Which credentials files an agent reads: `path` first, then, per provider, `fallback`. One value because it is one
+ * decision, read through `agentModels` (agent-models.ts) by everything that reads an agent's credentials.
+ */
+export interface AuthLayers {
+    path: string;
+    fallback?: string;
+}
+/**
+ * The {@link AuthLayers} an agent directory reads: `authPath` option > `FASTAGENT_AUTH_PATH` > its own file, and
+ * behind it the user-global store, because a login is a PERSON on a machine and not a project — one `login -g` then
+ * serves every agent here.
+ *
+ * No fallback when a path was named: "use this file" is an instruction, not a preference. BOTH knobs
+ * {@link resolveAuthPath} reads count as that instruction, `FASTAGENT_SECRETS_DIR` included — it is what the
+ * Fly/Railway/AgentCore artifacts set, and a deployed container must read its mounted credentials and nothing else
+ * (the artifact is the truth).
+ */
+export declare function resolveAuthLayers(agentDir: string, authPath?: string, env?: NodeJS.ProcessEnv): AuthLayers;

package/dist/engines/pi/auth.js

@@ -1,12 +1,11 @@
 /**
  * Auth for the pi engine: a read-WRITE {@link CredentialStore} over a fastagent credentials file, consumed by the
- * `Models` collection (models.ts). The write path refuses to overwrite a corrupt file, so a torn read never clobbers
- * the other providers' credentials.
+ * `Models` collection (models.ts), and which of those files an agent reads. The write path refuses to overwrite a
+ * corrupt file, so a torn read never clobbers the other providers' credentials.
  */
 import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { GLOBAL_HOME_DIR, SECRETS_DIRNAME, SECRET_FILE_MODE } from "../../paths.js";
+import { globalHome, SECRETS_DIRNAME, SECRET_FILE_MODE, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 import { writeFileAtomic } from "../../atomic-write.js";
 import { log } from "../../log.js";
 import lockfile from "proper-lockfile";
@@ -14,7 +13,13 @@ import lockfile from "proper-lockfile";
  * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery home
  * `~/.fastagent/`.
  */
-export const GLOBAL_AUTH_PATH = join(homedir(), GLOBAL_HOME_DIR, SECRETS_DIRNAME, "auth.json");
+export const GLOBAL_AUTH_PATH = join(globalHome(), SECRETS_DIRNAME, "auth.json");
+/** The one refusal for a caller that names both sources: silently preferring one would hide the other's mistake. */
+export function assertOneCredentialSource(options) {
+    if (options.authPath !== undefined && options.credentialStore !== undefined) {
+        throw new Error("pass authPath or credentialStore, not both: a supplied store replaces the credentials file");
+    }
+}
 /** A valid stored credential, or undefined — a foreign/old entry reads as not-configured, not a crash. */
 function pick(creds, providerId) {
     const cred = creds[providerId];
@@ -153,16 +158,25 @@ function parseForWrite(raw, where) {
 }
 /**
  * A read-write `CredentialStore` over the given credentials file (default {@link GLOBAL_AUTH_PATH}; the directory
- * opener passes the project-level `<root>/.secrets/auth.json`), optionally falling back to a second file.
+ * opener passes the project-level `<root>/.secrets/auth.json`), optionally falling back to a second file. A path is
+ * read like `FASTAGENT_AUTH_PATH` (`~` is the home directory, a relative one resolves against the cwd), so every
+ * caller that names a file names the same one.
  *
  * The fallback is PER PROVIDER, not per file: logging one provider into a project must not hide the others a person
  * already has globally. And the layer a credential was READ from is the layer its refresh is written back to —
  * anything else would conjure a second holder of the same OAuth grant, which is the failure this whole area exists
  * to avoid. A provider present in neither layer is new, and new credentials belong to the primary.
+ *
+ * The fallback also yields to `projectAuthenticates`: a provider the project authenticates some other way (an env key,
+ * its own models.json) never reaches it — for reading, listing or writing back.
  */
-export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options = {}) {
+export function fastagentCredentialStore(path, options = {}) {
     const warn = options.warn ?? ((message) => log.warn(message));
-    const fallback = options.fallbackPath !== undefined && options.fallbackPath !== authPath ? options.fallbackPath : undefined;
+    const authPath = resolveOverridePath(path) ?? GLOBAL_AUTH_PATH;
+    const fallbackPath = resolveOverridePath(options.fallbackPath);
+    const fallback = fallbackPath !== undefined && fallbackPath !== authPath ? fallbackPath : undefined;
+    /** The fallback, when it may serve this provider at all. */
+    const fallbackFor = async (providerId) => fallback === undefined || (await options.projectAuthenticates?.(providerId)) ? undefined : fallback;
     /**
      * The file that owns this provider: where it already is, else the primary.
      *
@@ -171,18 +185,21 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
      * "one grant, one copy" rule can be lost. Re-checking under the lock means locking both files in a fixed order;
      * worth it only if concurrent logins stop being a rounding error.
      */
-    const owner = (providerId) => {
-        if (fallback === undefined)
+    const owner = async (providerId) => {
+        const second = await fallbackFor(providerId);
+        if (second === undefined)
             return authPath;
         const primary = readCreds(authPath, warn);
         if (primary && pick(primary, providerId))
             return authPath;
-        const secondary = readCreds(fallback, warn);
-        return secondary && pick(secondary, providerId) ? fallback : authPath;
+        const secondary = readCreds(second, warn);
+        return secondary && pick(secondary, providerId) ? second : authPath;
     };
     return {
+        layerOf: owner,
         async read(providerId) {
-            for (const path of fallback === undefined ? [authPath] : [authPath, fallback]) {
+            const second = await fallbackFor(providerId);
+            for (const path of second === undefined ? [authPath] : [authPath, second]) {
                 const creds = readCreds(path, warn);
                 const found = creds && pick(creds, providerId);
                 if (found)
@@ -196,14 +213,16 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
             const infos = new Map();
             for (const path of fallback === undefined ? [authPath] : [fallback, authPath]) {
                 for (const [providerId, cred] of Object.entries(readCreds(path, warn) ?? {})) {
+                    if (path === fallback && (await fallbackFor(providerId)) === undefined)
+                        continue;
                     if (cred && (cred.type === "oauth" || cred.type === "api_key"))
                         infos.set(providerId, { providerId, type: cred.type });
                 }
             }
             return [...infos.values()];
         },
-        modify(providerId, fn) {
-            const path = owner(providerId);
+        async modify(providerId, fn) {
+            const path = await owner(providerId);
             return withLockedAuthFile(path, async (current) => {
                 const creds = parseForWrite(current, path); // corrupt → throw → no clobber
                 const next = await fn(pick(creds, providerId));
@@ -214,7 +233,7 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
             });
         },
         async delete(providerId) {
-            const path = owner(providerId);
+            const path = await owner(providerId);
             // No-op when nothing is stored: do NOT take the lock (which would create the file) on a machine that never
             // stored this provider.
             if (!existsSync(path))
@@ -229,3 +248,31 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
         },
     };
 }
+// ── Which files an agent reads ───────────────────────────────────────────────
+/**
+ * The auth-file override: the SDK's `authPath` option > `FASTAGENT_AUTH_PATH` env > undefined (then
+ * `<secrets dir>/auth.json`). The CLI has no flag for it: a second spelling of one environment variable buys nothing,
+ * and the variable is what a deployed container reads anyway.
+ */
+function resolveAuthPathOverride(flag, env) {
+    return resolveOverridePath(flag ?? env.FASTAGENT_AUTH_PATH);
+}
+/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
+export function resolveAuthPath(dir, flag, env = process.env) {
+    return resolveAuthPathOverride(flag, env) ?? join(resolveSecretsDir(dir, env), "auth.json");
+}
+/**
+ * The {@link AuthLayers} an agent directory reads: `authPath` option > `FASTAGENT_AUTH_PATH` > its own file, and
+ * behind it the user-global store, because a login is a PERSON on a machine and not a project — one `login -g` then
+ * serves every agent here.
+ *
+ * No fallback when a path was named: "use this file" is an instruction, not a preference. BOTH knobs
+ * {@link resolveAuthPath} reads count as that instruction, `FASTAGENT_SECRETS_DIR` included — it is what the
+ * Fly/Railway/AgentCore artifacts set, and a deployed container must read its mounted credentials and nothing else
+ * (the artifact is the truth).
+ */
+export function resolveAuthLayers(agentDir, authPath, env = process.env) {
+    const path = resolveAuthPath(agentDir, authPath, env);
+    const named = resolveAuthPathOverride(authPath, env) ?? resolveOverridePath(env.FASTAGENT_SECRETS_DIR);
+    return named === undefined ? { path, fallback: GLOBAL_AUTH_PATH } : { path };
+}

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

@@ -63,28 +63,3 @@ export declare function rewriteConfigModel(src: string, spec: string): string |
  * would refuse to start an agent whose config names a model.
  */
 export declare function resolveModelSpec(flag: string | undefined, config: FastagentConfig, env?: NodeJS.ProcessEnv): string | undefined;
-/** The default credentials file under a resolved secrets dir ({@link resolveSecretsDir}). */
-export declare function defaultAuthPath(secretsDir: string): string;
-/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
-export declare function resolveAuthPath(dir: string, flag?: string, env?: NodeJS.ProcessEnv): string;
-/**
- * Which credentials files an agent reads: `path` first, then, per provider, `fallback` — present only when nothing
- * named the path ({@link resolveAuthFallback}). One value because it is one decision: the opener, the model list, the
- * startup report and the first-run picker all read through it.
- */
-export interface AuthLayers {
-    path: string;
-    fallback?: string;
-}
-/** The {@link AuthLayers} an agent directory reads: `authPath` option > `FASTAGENT_AUTH_PATH` > its own file. */
-export declare function resolveAuthLayers(agentDir: string, authPath?: string, env?: NodeJS.ProcessEnv): AuthLayers;
-/**
- * Where a credential the project does not have is read from instead: the user-global store, because a login is a
- * PERSON on a machine and not a project — one `login -g` then serves every agent here. Undefined when an explicit
- * path was named: "use this file" is an instruction, not a preference, so it gets no second layer.
- *
- * BOTH knobs {@link resolveAuthPath} reads count as that instruction, `FASTAGENT_SECRETS_DIR` included — it is what
- * the Fly/Railway/AgentCore artifacts set, and a deployed container must read its mounted credentials and nothing
- * else (the artifact is the truth).
- */
-export declare function resolveAuthFallback(flag?: string, env?: NodeJS.ProcessEnv): string | undefined;

package/dist/engines/pi/config.js

@@ -14,11 +14,10 @@ import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { THINKING_LEVELS } from "./session-settings.js";
-import { GLOBAL_AUTH_PATH } from "./auth.js";
 import { readSecretDeclaration } from "../../declared-secrets.js";
 import { assertCorsOrigins } from "../../channels/serve.js";
 import { moduleLoadHint } from "../../loader.js";
-import { AGENT_CONFIG_FILE, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
+import { AGENT_CONFIG_FILE } from "../../paths.js";
 /** Identity function for typing and IDE completion (vite/next-style). */
 export function defineConfig(config) {
     return config;
@@ -152,7 +151,8 @@ export function resolveModel(models, spec) {
     const modelId = spec.slice(slash + 1);
     const model = models.getModel(provider, modelId);
     if (!model) {
-        throw new Error(`unknown model "${spec}" (provider "${provider}" / id "${modelId}" not in registry); run \`fastagent models\` to list available specs`);
+        throw new Error(`unknown model "${spec}" (provider "${provider}" / id "${modelId}" not in registry); run \`fastagent models\` to list ` +
+            "available specs, or `fastagent models --refresh` in the agent to fetch models newer than the installed pi");
     }
     return model;
 }
@@ -189,37 +189,3 @@ export function rewriteConfigModel(src, spec) {
 export function resolveModelSpec(flag, config, env = process.env) {
     return flag ?? (env.FASTAGENT_MODEL || config.model);
 }
-/**
- * The auth-file override: the SDK's `authPath` option > `FASTAGENT_AUTH_PATH` env > undefined (the opener then falls
- * back to {@link defaultAuthPath} under the {@link resolveSecretsDir} dir). The CLI has no flag for it: a second
- * spelling of one environment variable buys nothing, and the variable is what a deployed container reads anyway.
- */
-function resolveAuthPathOverride(flag, env = process.env) {
-    return resolveOverridePath(flag ?? env.FASTAGENT_AUTH_PATH);
-}
-/** The default credentials file under a resolved secrets dir ({@link resolveSecretsDir}). */
-export function defaultAuthPath(secretsDir) {
-    return join(secretsDir, "auth.json");
-}
-/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
-export function resolveAuthPath(dir, flag, env = process.env) {
-    return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveSecretsDir(dir, env));
-}
-/** The {@link AuthLayers} an agent directory reads: `authPath` option > `FASTAGENT_AUTH_PATH` > its own file. */
-export function resolveAuthLayers(agentDir, authPath, env = process.env) {
-    const fallback = resolveAuthFallback(authPath, env);
-    return { path: resolveAuthPath(agentDir, authPath, env), ...(fallback !== undefined ? { fallback } : {}) };
-}
-/**
- * Where a credential the project does not have is read from instead: the user-global store, because a login is a
- * PERSON on a machine and not a project — one `login -g` then serves every agent here. Undefined when an explicit
- * path was named: "use this file" is an instruction, not a preference, so it gets no second layer.
- *
- * BOTH knobs {@link resolveAuthPath} reads count as that instruction, `FASTAGENT_SECRETS_DIR` included — it is what
- * the Fly/Railway/AgentCore artifacts set, and a deployed container must read its mounted credentials and nothing
- * else (the artifact is the truth).
- */
-export function resolveAuthFallback(flag, env = process.env) {
-    const explicit = resolveAuthPathOverride(flag, env) ?? resolveOverridePath(env.FASTAGENT_SECRETS_DIR);
-    return explicit === undefined ? GLOBAL_AUTH_PATH : undefined;
-}

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

@@ -1,15 +1,16 @@
 import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type ModelRuntime } from "@earendil-works/pi-coding-agent";
-import type { Provider } from "@earendil-works/pi-ai";
+import type { CredentialStore, Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
-import { type AuthLayers, type FastagentConfig } from "./config.ts";
-import type { FastagentAuthOptions } from "./auth.ts";
+import { type FastagentConfig } from "./config.ts";
 import { type LoadedDefinition } from "./definition.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
 import { type DeclaredSecret } from "../../declared-secrets.ts";
 import { type PiAgentSessionFactory } from "./invoke-session.ts";
+import { type PiAgentSessionFactoryOptions } from "./agent-session-factory.ts";
 import { type AnyModel } from "./models.ts";
+import { type AgentModels } from "./agent-models.ts";
 import { type PiSessionRecordStore } from "./session-store.ts";
 import { type Lease, type SessionObserver } from "./turn-kit.ts";
 /**
@@ -65,6 +66,11 @@ export declare function assembleSystemPrompt(options: AssembleSystemPromptOption
 export interface PiAssembly {
     lease: Lease;
     sessionFactory: PiAgentSessionFactory;
+    /**
+     * The registry alone, with injected providers registered. `chat` resolves its model against it only after its
+     * extensions have loaded, because there an extension may register the provider (serving refuses that).
+     */
+    modelRuntime: () => Promise<ModelRuntime>;
     /** The registry and configured model, resolved on first use (a credential read is async). */
     engine: () => Promise<{
         modelRuntime: ModelRuntime;
@@ -72,6 +78,10 @@ export interface PiAssembly {
     }>;
     /** The configured reasoning effort — the other half of the pair a session without overrides runs on. */
     thinkingLevel: ThinkingLevel;
+    /** The tools every session mounts. */
+    tools: MountedTool[];
+    /** The prompt and skills a session runs on, read when a session is bound. */
+    readDefinition: PiAgentSessionFactoryOptions["readDefinition"];
     /** The extension entry points every session loads, discovered once with the assembly. */
     extensionPaths: readonly string[];
 }
@@ -98,6 +108,8 @@ export interface CreatePiAgentOptions {
     providers?: Provider[];
     /** Credentials file for stored OAuth/API-key auth (default `GLOBAL_AUTH_PATH`). */
     authPath?: string;
+    /** The caller's own credential store, in place of any file ({@link CredentialSourceOptions}). */
+    credentialStore?: CredentialStore;
     sessions?: PiSessionRecordStore;
     /** Supplies the working directory at L1 (default: process.cwd()), which loads no definition. */
     env?: ExecutionEnv;
@@ -129,6 +141,8 @@ export interface CreatePiAgentFromDefinitionOptions {
      * gets no second layer.
      */
     authPath?: string;
+    /** The caller's own credential store, in place of any file ({@link CredentialSourceOptions}). */
+    credentialStore?: CredentialStore;
     sessions?: PiSessionRecordStore;
     /** Filesystem/process environment; see {@link CreatePiAgentOptions.env}. */
     env?: ExecutionEnv;
@@ -137,20 +151,12 @@ export interface CreatePiAgentFromDefinitionOptions {
     observer?: SessionObserver;
 }
 /**
- * THE model registry an agent directory runs on: pi's built-ins, the directory's own `models.json` (custom endpoints
- * are definition data and travel with the artifact) layered over the machine's `~/.fastagent/models.json` (environment,
- * which does not travel), and any injected Provider instance, over the given credentials.
- * The directory rung assembles from it and `availableModelsFromDir` lists from it, so a layer added here reaches both.
+ * L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. `models` is the directory's
+ * model environment when the caller already built it (the opener, whose report must describe what runs); otherwise it
+ * is built here from the credential options.
  */
-export declare function definitionModelRuntime(dir: string, options: FastagentAuthOptions & {
-    auth: AuthLayers;
-    providers?: Provider[];
-}): Promise<ModelRuntime>;
-/** L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. */
-export declare function assemblePiFromDefinition(dir: string, 
-/** `auth` is the opener's already-resolved layers, which take the place of `authPath`. */
-options: Omit<CreatePiAgentFromDefinitionOptions, "observer"> & {
-    auth?: AuthLayers;
+export declare function assemblePiFromDefinition(dir: string, options: Omit<CreatePiAgentFromDefinitionOptions, "observer"> & {
+    models?: AgentModels;
 }): Promise<{
     assembly: PiAssembly;
     definition: LoadedDefinition;

package/dist/engines/pi/create.js

@@ -5,7 +5,7 @@
 import { toUSVString } from "node:util";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { createCodingTools, createPowerShellTool, createReadOnlyTools, } from "@earendil-works/pi-coding-agent";
-import { resolveAuthLayers, resolveModel } from "./config.js";
+import { resolveModel } from "./config.js";
 import { isAgentcoreRuntime, isDeployedWorkspace } from "../../paths.js";
 import { loadAgentDefinition, loadExtensionPaths } from "./definition.js";
 import { reportFindingsIfChanged } from "./report.js";
@@ -14,7 +14,8 @@ import { readSecretDeclaration } from "../../declared-secrets.js";
 import { withSearchTool } from "./search-tools.js";
 import { createPiAgentFromSession } from "./invoke-session.js";
 import { piAgentSessionFactory } from "./agent-session-factory.js";
-import { DEFAULT_THINKING_LEVEL, createPiModelRuntime } from "./models.js";
+import { DEFAULT_THINKING_LEVEL } from "./models.js";
+import { agentModels } from "./agent-models.js";
 import { piInMemorySessionRecordStore } from "./session-store.js";
 import { inProcessLease } from "./turn-kit.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
@@ -188,18 +189,20 @@ function assemblePi(opts) {
     const lease = opts.lease ?? inProcessLease();
     const sessions = opts.sessions ?? piInMemorySessionRecordStore({ cwd });
     // The model and its runtime resolve on FIRST USE.
-    let engine;
-    const resolveEngine = () => {
-        engine ??= (async () => {
-            // The caller's registry when there is one — the directory rung builds it from the agent's own models.json, so a
-            // custom endpoint declared there is the one a turn resolves against.
-            const modelRuntime = opts.models ?? (await createPiModelRuntime({ auth: opts.auth }));
+    let registry;
+    const modelRuntime = () => {
+        registry ??= opts.models().then((runtime) => {
             // ModelRuntime registers providers by config record, so an injected Provider INSTANCE (a gateway, a self-hosted
             // endpoint, a test fake) goes in through its native seam.
             for (const provider of opts.providers ?? [])
-                modelRuntime.registerNativeProvider(provider);
-            return { modelRuntime, model: resolveModel(modelRuntime, opts.model) };
-        })();
+                runtime.registerNativeProvider(provider);
+            return runtime;
+        });
+        return registry;
+    };
+    let engine;
+    const resolveEngine = () => {
+        engine ??= modelRuntime().then((runtime) => ({ modelRuntime: runtime, model: resolveModel(runtime, opts.model) }));
         return engine;
     };
     const sessionFactory = piAgentSessionFactory({
@@ -217,8 +220,11 @@ function assemblePi(opts) {
     return {
         lease,
         sessionFactory,
+        modelRuntime,
         engine: resolveEngine,
         thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+        tools: opts.tools ?? [],
+        readDefinition: opts.readDefinition,
         extensionPaths: opts.extensionPaths ?? [],
     };
 }
@@ -233,7 +239,7 @@ export function createPiAgent(options) {
         model: options.model,
         thinkingLevel: options.thinkingLevel,
         providers: options.providers,
-        ...(options.authPath !== undefined ? { auth: { path: options.authPath } } : {}),
+        models: agentModels(undefined, options).runtime,
         readDefinition: () => ({
             systemPrompt: typeof instructions === "function" ? instructions() : instructions,
             skills,
@@ -246,18 +252,11 @@ export function createPiAgent(options) {
     }), options.observer);
 }
 /**
- * THE model registry an agent directory runs on: pi's built-ins, the directory's own `models.json` (custom endpoints
- * are definition data and travel with the artifact) layered over the machine's `~/.fastagent/models.json` (environment,
- * which does not travel), and any injected Provider instance, over the given credentials.
- * The directory rung assembles from it and `availableModelsFromDir` lists from it, so a layer added here reaches both.
+ * L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. `models` is the directory's
+ * model environment when the caller already built it (the opener, whose report must describe what runs); otherwise it
+ * is built here from the credential options.
  */
-export function definitionModelRuntime(dir, options) {
-    return createPiModelRuntime({ agentDir: dir, ...options });
-}
-/** L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. */
-export async function assemblePiFromDefinition(dir, 
-/** `auth` is the opener's already-resolved layers, which take the place of `authPath`. */
-options) {
+export async function assemblePiFromDefinition(dir, options) {
     // `dir` = the agent-definition dir (persona.md/skills/); `cwd` (default = dir) is the run root where tools operate
     // and whose ancestors are walked for ② context.
     const cwd = options.cwd ?? dir;
@@ -271,14 +270,15 @@ options) {
     // Boot findings go through the SAME memoized reporter every later reader uses (report.ts, keyed by the resolved
     // dir).
     reportFindingsIfChanged(definition.dir, definition);
-    const auth = options.auth ?? (options.authPath === undefined ? resolveAuthLayers(dir) : { path: options.authPath });
+    const { providers } = options;
+    const models = options.models ?? agentModels(dir, options, providers ? { providers } : {});
+    // Built at boot, so a malformed models.json fails the assembly rather than its first turn. The directory's own
+    // models.json is what a turn resolves against, layered over the machine's (models.ts).
+    await models.runtime();
     const assembly = assemblePi({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
-        models: await definitionModelRuntime(dir, {
-            auth,
-            ...(options.providers ? { providers: options.providers } : {}),
-        }),
+        models: models.runtime,
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills edits (the
         // author's, or the agent's own self-modification) take effect on the next turn with no process restart — restarts
         // are reserved for code (tools/channels/config, module cache).

package/dist/engines/pi/entry-images.d.ts

@@ -0,0 +1,14 @@
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { ImageRef } from "../../agent.ts";
+import type { EntryImage } from "../../session.ts";
+type Message = {
+    role: string;
+    content?: unknown;
+};
+/** `data.images` of the entry `entryId` holding `message`, absent when it has none. */
+export declare function entryImages(entryId: string, message: Message): {
+    images?: EntryImage[];
+};
+/** The image `ref` names in `record`, or undefined when it names none there. The inverse of `entryImages`. */
+export declare function imageAt(record: SessionManager, ref: string): ImageRef | undefined;
+export {};

package/dist/engines/pi/entry-images.js

@@ -0,0 +1,23 @@
+/** A user prompt's and a tool result's images; no other message publishes any, so no ref can reach them. */
+function publishedImages(message) {
+    if (message.role !== "user" && message.role !== "toolResult")
+        return [];
+    const content = message.content;
+    return Array.isArray(content) ? content.filter((b) => b.type === "image") : [];
+}
+/** `data.images` of the entry `entryId` holding `message`, absent when it has none. */
+export function entryImages(entryId, message) {
+    const images = publishedImages(message).map((b, i) => ({ ref: `${entryId}:${i}`, mimeType: b.mimeType }));
+    return images.length > 0 ? { images } : {};
+}
+/** The image `ref` names in `record`, or undefined when it names none there. The inverse of `entryImages`. */
+export function imageAt(record, ref) {
+    const at = ref.lastIndexOf(":");
+    const index = ref.slice(at + 1);
+    // Canonical digits only, so one image has one ref (`:00` is not `:0`).
+    if (at <= 0 || !/^(0|[1-9]\d*)$/.test(index))
+        return undefined;
+    const entry = record.getEntry(ref.slice(0, at));
+    const image = entry?.type === "message" ? publishedImages(entry.message)[Number(index)] : undefined;
+    return image ? { data: image.data, mimeType: image.mimeType } : undefined;
+}