@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/environment/mise.js

@@ -0,0 +1,268 @@
+/**
+ * RUNNING an agent's environment with mise. The agent carries its own mise, as optional npm dependencies, one package
+ * per platform of which npm installs only this machine's: the author installs nothing, and the image's `npm ci`
+ * installs the same mise. mise is given the packages as arguments (`gh@2`), and never reads a configuration file: not
+ * the machine's, not an author's own `mise.toml`, not a parent directory's.
+ *
+ * Nothing is locked. Each place installs the newest release a declared version allows when it first needs a package,
+ * and keeps it: a process that runs the agent installs only what has no install matching it yet (the image installs
+ * every package when it is built), and `fastagent env install` installs the newest again.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { loadEnvironment } from "../content/file.js";
+import { log } from "../log.js";
+import { detectRuntime, listsFastagent, readPackageJson } from "../runtime.js";
+import { aptAdvice, missingAptPackages } from "./apt.js";
+import { missingPythonRuntime, resolvedBackendRefusal, writtenBackend, } from "./declare.js";
+/** mise's npm package for each platform it publishes one for, by Node's `${platform}-${arch}`. */
+const MISE_PACKAGES = {
+    "darwin-arm64": "@jdxcode/mise-darwin-arm64",
+    "darwin-x64": "@jdxcode/mise-darwin-x64",
+    "linux-arm64": "@jdxcode/mise-linux-arm64",
+    "linux-x64": "@jdxcode/mise-linux-x64",
+};
+/** Every platform's package: an agent lists them all, so its lockfile has the image's too. */
+export const MISE_PACKAGE_NAMES = Object.values(MISE_PACKAGES);
+/** A path no file can be at, for the mise configuration files an agent's environment must not read. */
+const NO_FILE = "/dev/null/none.toml";
+/** This machine's mise package; a platform mise publishes none for cannot run an environment. */
+function platformPackage() {
+    const key = `${process.platform}-${process.arch}`;
+    const name = MISE_PACKAGES[key];
+    if (!name)
+        throw new Error(`an agent's environment does not run on ${key} yet: mise has no npm package for it`);
+    return name;
+}
+/**
+ * The agent's mise on this machine, or undefined when the agent has none installed. Found by its package, not by
+ * `node_modules/.bin/mise`: the platform packages all name that bin, and npm drops the link while it skips the
+ * other platforms' packages.
+ */
+export function miseBinary(agentDir) {
+    const require = createRequire(join(resolve(agentDir), "package.json"));
+    try {
+        return join(dirname(require.resolve(`${platformPackage()}/package.json`)), "bin", "mise");
+    }
+    catch (error) {
+        if (error.code === "MODULE_NOT_FOUND")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * What every run of the agent's mise is given, here and in the image: no configuration file is read, so the packages
+ * are the arguments alone, and a runtime is installed from a prebuilt release or not at all (mise compiles python by
+ * default, and `all_compile`, already false, does not stop it). Given to these runs alone, never exported to the
+ * agent's processes: a mise the agent runs is the machine's.
+ */
+export const MISE_ENVIRONMENT = {
+    MISE_GLOBAL_CONFIG_FILE: NO_FILE,
+    MISE_SYSTEM_CONFIG_FILE: NO_FILE,
+    // A path, not a name: mise looks for a file of the name given here in every directory up to the root.
+    MISE_OVERRIDE_CONFIG_FILENAMES: NO_FILE,
+    MISE_OVERRIDE_TOOL_VERSIONS_FILENAMES: NO_FILE,
+    MISE_PYTHON_COMPILE: "false",
+    MISE_NODE_COMPILE: "false",
+    MISE_RUBY_COMPILE: "false",
+    MISE_ERLANG_COMPILE: "false",
+};
+/** What mise is given for `packages`: each as `name@version`, here and in the image (container.ts). */
+export function packageSpecs(packages) {
+    return Object.keys(packages).map((name) => specOf(name, packages));
+}
+/** How mise is given the package `name` of `packages`. */
+function specOf(name, packages) {
+    return `${name}@${packages[name]}`;
+}
+/**
+ * Run the agent's mise with `args` in `cwd`. Its errors go to this process's stderr unless `quiet` keeps them for
+ * the error, which then says what mise said; `capture` returns its stdout instead of passing it through.
+ */
+function runMise(cwd, bin, args, options = {}) {
+    return new Promise((done, fail) => {
+        const child = spawn(bin, args, {
+            cwd,
+            env: { ...process.env, ...MISE_ENVIRONMENT },
+            stdio: ["inherit", options.capture ? "pipe" : process.stderr, options.quiet ? "pipe" : "inherit"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8").on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.setEncoding("utf8").on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", fail);
+        child.on("close", (code, signal) => {
+            if (code === 0)
+                return done(stdout);
+            const said = stderr.match(/ERROR\s+(.+)/)?.[1];
+            fail(new Error(`mise ${args.join(" ")} failed (${signal ?? `exit ${code}`})${said ? `: ${said}` : ""}`));
+        });
+    });
+}
+/**
+ * The command that puts mise into the agent: every platform's package, at the newest version, pinned. When
+ * `package.json` already lists it (a fresh clone), the dependencies are installed as they are, never upgraded.
+ */
+async function addMiseCommand(agentDir) {
+    const pkg = await readPackageJson(agentDir);
+    const { runtime } = detectRuntime(agentDir, pkg);
+    if (platformPackage() in (pkg.optionalDependencies ?? {})) {
+        return runtime === "bun" ? ["bun", ["install"]] : ["npm", ["install", "--no-audit", "--no-fund"]];
+    }
+    const packages = MISE_PACKAGE_NAMES.map((name) => `${name}@latest`);
+    return runtime === "bun"
+        ? ["bun", ["add", "--optional", "--exact", ...packages]]
+        : ["npm", ["install", "--save-optional", "--save-exact", "--no-audit", "--no-fund", ...packages]];
+}
+/**
+ * The agent's mise, added to its `package.json` first when it has none: for the commands an author runs to change the
+ * environment (`fastagent env`), never for one that runs the agent. A manifest that does not list FastAgent is
+ * refused: the mise would make it a code agent, whose image runs the FastAgent its `package.json` lists.
+ */
+export async function ensureMise(agentDir) {
+    const found = miseBinary(agentDir);
+    if (found)
+        return found;
+    if (!listsFastagent(await readPackageJson(agentDir))) {
+        throw new Error(`${join(agentDir, "package.json")} does not list @fastagent-sh/fastagent — the agent's mise is one of its ` +
+            `dependencies, and an agent with dependencies runs the FastAgent they list. Add it first: ` +
+            `\`npm install @fastagent-sh/fastagent\` in ${agentDir}`);
+    }
+    const [command, args] = await addMiseCommand(agentDir);
+    log.info(`[fastagent] installing the agent's mise: ${command} ${args.join(" ")}`);
+    await new Promise((done, fail) => {
+        const child = spawn(command, args, { cwd: agentDir, stdio: ["inherit", process.stderr, "inherit"] });
+        child.on("error", fail);
+        child.on("close", (code) => (code === 0 ? done() : fail(new Error(`${command} ${args[0]} failed (exit ${code})`))));
+    });
+    const added = miseBinary(agentDir);
+    if (!added)
+        throw new Error(`${command} ${args[0]} added mise to ${agentDir}, and it is still not installed`);
+    return added;
+}
+/**
+ * Check `packages` against the backend each resolves to: a written one says it (`npm:prettier`), and mise resolves a
+ * registry name (`tokei` is `cargo:tokei`). A name mise does not know fails the check with what mise said.
+ */
+export async function checkPackages(agentDir, bin, packages) {
+    const kinds = new Map();
+    const refusals = [];
+    await Promise.all(Object.keys(packages).map(async (name) => {
+        const written = writtenBackend(name);
+        if (written)
+            return void kinds.set(name, written);
+        const out = await runMise(agentDir, bin, ["tool", name, "--json"], { capture: true, quiet: true });
+        const backend = JSON.parse(out).backend;
+        if (typeof backend !== "string")
+            throw new Error(`mise tool ${name} --json reported no backend`);
+        kinds.set(name, backend.split(":")[0] ?? backend);
+        const refusal = resolvedBackendRefusal(name, backend);
+        if (refusal)
+            refusals.push(refusal);
+    }));
+    const runtime = missingPythonRuntime(packages, kinds);
+    return { refusals: refusals.sort(), ...(runtime ? { runtime } : {}) };
+}
+/**
+ * Install `packages` here, each at the newest release its declared version allows. Those `newest` names (every one
+ * when it is `"all"`: `fastagent env install`) are given to mise whatever is installed, which installs a newer release
+ * where one is out; the rest only when nothing installed matches them, which `mise where` answers without the network,
+ * so a start whose packages are installed needs no network and keeps the versions it has. An install that matches may
+ * be another project's: mise's data directory is the machine's.
+ */
+export async function installPackages(agentDir, bin, packages, newest = []) {
+    const names = Object.keys(packages);
+    const asked = names.filter((name) => newest === "all" || newest.includes(name));
+    const others = names.filter((name) => !asked.includes(name));
+    const installed = await Promise.all(
+    // A failed `where` is what mise says of a package with no install here; the install that follows reports any other
+    // reason it cannot be had.
+    others.map((name) => runMise(agentDir, bin, ["where", specOf(name, packages)], { capture: true, quiet: true }).then(() => true, () => false)));
+    const present = new Set(others.filter((_, i) => installed[i]));
+    const wanted = names.filter((name) => !present.has(name)).map((name) => specOf(name, packages));
+    if (wanted.length === 0)
+        return;
+    const installedSpecs = [...present].map((name) => specOf(name, packages));
+    // A package installs with the ones it needs (a PyPI one runs uv), which mise finds in the packages it is given or on
+    // the PATH. The installed ones go on the PATH: given as packages, mise would install a newer release of them.
+    await runInstall(agentDir, bin, wanted, installedSpecs.length > 0 ? await packagesEnvironment(agentDir, bin, installedSpecs) : {});
+}
+/** What `mise env` puts in a process's environment for `specs`: the PATH their commands are on. */
+async function packagesEnvironment(agentDir, bin, specs) {
+    return JSON.parse(await runMise(agentDir, bin, ["env", "--json", ...specs], { capture: true }));
+}
+/**
+ * The notice mise prints after installing a package no configuration file names, with the `mise use` it suggests: not
+ * the agent's way to a package, so it is not passed on.
+ */
+const NOT_ACTIVATED = /installed but not activated|^To install and activate, run:|^\s+mise use /;
+/**
+ * `mise install` of `specs`, with `env` added to its environment. Its progress is passed on to this process's stderr as
+ * it comes, so a runtime that takes minutes is seen to; a failure carries what mise said, every line of it, since
+ * mise names the packages on its first line and the reason (a 404, a proxy, a rate limit) on the lines after.
+ */
+function runInstall(agentDir, bin, specs, env) {
+    log.info(`[fastagent] installing the agent's packages: ${specs.join(", ")}`);
+    return new Promise((done, fail) => {
+        const child = spawn(bin, ["install", ...specs], {
+            cwd: agentDir,
+            env: { ...process.env, ...env, ...MISE_ENVIRONMENT },
+            stdio: ["inherit", process.stderr, "pipe"],
+        });
+        const said = [];
+        let partial = "";
+        child.stderr?.setEncoding("utf8").on("data", (chunk) => {
+            const lines = (partial + chunk).split("\n");
+            partial = lines.pop() ?? "";
+            for (const line of lines) {
+                if (NOT_ACTIVATED.test(line))
+                    continue;
+                process.stderr.write(`${line}\n`);
+                said.push(line);
+            }
+        });
+        child.on("error", fail);
+        child.on("close", (code, signal) => {
+            if (partial !== "")
+                said.push(partial);
+            if (code === 0)
+                return done();
+            const reason = said
+                .slice(Math.max(0, said.findIndex((line) => /\bERROR\b/.test(line))))
+                .filter((line) => !/ERROR\s+(Version:|Run with --verbose)/.test(line))
+                .map((line) => line.replace(/^mise\s+ERROR\s+/, "").trim())
+                .filter((line) => line !== "");
+            fail(new Error(`mise install ${specs.join(" ")} failed (${signal ?? `exit ${code}`})${reason.length > 0 ? `: ${reason.join("; ")}` : ""}`));
+        });
+    });
+}
+/** What a process that runs the agent says when its environment has no mise to install it with. */
+function missingMise(agentDir) {
+    return new Error(`context.json declares packages, and the agent has no mise installed — run \`fastagent env install\` in ${agentDir}`);
+}
+/**
+ * Enter the agent's environment, for a process that runs it: install the declared packages that have no install here
+ * yet, and put them first on this process's PATH, which every command the agent runs inherits. mise itself is not put
+ * on the PATH. An agent without packages borrows the machine's commands. Apt packages are the image's to install; one
+ * missing here is said, with how.
+ */
+export async function enterEnvironment(agentDir) {
+    const declared = loadEnvironment(agentDir);
+    const missingApt = missingAptPackages(declared?.aptPackages ?? []);
+    if (missingApt && missingApt.length > 0)
+        log.warn(`[fastagent] ${aptAdvice(missingApt)}`);
+    const packages = declared?.packages ?? {};
+    if (Object.keys(packages).length === 0)
+        return declared;
+    const bin = miseBinary(agentDir);
+    if (!bin)
+        throw missingMise(agentDir);
+    await installPackages(agentDir, bin, packages);
+    Object.assign(process.env, await packagesEnvironment(agentDir, bin, packageSpecs(packages)));
+    return declared;
+}

package/dist/feishu.d.ts

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
-export { feishuChannel, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuWebSocketChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";
-export { feishuTransport, type FeishuTransport } from "./channels/feishu/shared-api.ts";
+export { feishuChannel, feishuIngress, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuWebSocketChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";
+export { feishuThreads, feishuTransport, type FeishuTransport } from "./channels/feishu/shared-api.ts";

package/dist/feishu.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
-export { feishuChannel, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";
-export { feishuTransport } from "./channels/feishu/shared-api.js";
+export { feishuChannel, feishuIngress, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";
+export { feishuThreads, feishuTransport } from "./channels/feishu/shared-api.js";

package/dist/git.d.ts

@@ -0,0 +1,13 @@
+/** git is not on the PATH. Its message names what needed it: `git is not installed: <why>`. */
+export declare class GitNotInstalled extends Error {
+}
+/** git for one purpose, `why`: what a missing git is reported as needed for. */
+export declare function gitFor(why: string): {
+    /**
+     * git's answer in `cwd` (which must exist), or undefined when it answers with a non-zero exit. A git that cannot
+     * run is an error.
+     */
+    answer(args: string[], cwd: string): string | undefined;
+    /** Run git in `cwd`: its output, or its stderr as the error. */
+    run(args: string[], cwd: string): Promise<string>;
+};

package/dist/git.js

@@ -0,0 +1,55 @@
+/**
+ * Running git, and what ONE result means: an answer, a "no" (a non-zero exit: not a checkout, no such ref, not
+ * ignored), or a git that cannot run at all. Every caller reads git through here, so a new kind of result is decided
+ * once; each caller says only why it needed git, which is what a missing git is reported with.
+ */
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+/** git is not on the PATH. Its message names what needed it: `git is not installed: <why>`. */
+export class GitNotInstalled extends Error {
+}
+/**
+ * Never wait on a terminal prompt for a credential: a serving process has nobody to answer it, so git fails and says
+ * why instead. Not covered by a test: it takes a remote that asks for a credential.
+ */
+const gitEnv = () => ({ ...process.env, GIT_TERMINAL_PROMPT: "0" });
+const execGit = promisify(execFile);
+/** git for one purpose, `why`: what a missing git is reported as needed for. */
+export function gitFor(why) {
+    const missing = () => new GitNotInstalled(`git is not installed: ${why}`);
+    return {
+        /**
+         * git's answer in `cwd` (which must exist), or undefined when it answers with a non-zero exit. A git that cannot
+         * run is an error.
+         */
+        answer(args, cwd) {
+            try {
+                return execFileSync("git", args, {
+                    cwd,
+                    env: gitEnv(),
+                    encoding: "utf8",
+                    stdio: ["ignore", "pipe", "pipe"],
+                }).trim();
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    throw missing();
+                if (typeof error.status === "number")
+                    return undefined;
+                throw error;
+            }
+        },
+        /** Run git in `cwd`: its output, or its stderr as the error. */
+        async run(args, cwd) {
+            try {
+                return (await execGit("git", args, { cwd, env: gitEnv() })).stdout;
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    throw missing();
+                const stderr = String(error.stderr ?? "").trim();
+                throw new Error(stderr || error.message);
+            }
+        },
+    };
+}

package/dist/harnesses/models/catalog.d.ts

@@ -0,0 +1,20 @@
+import { type Models, type ModelsStore, type Provider } from "@earendil-works/pi-ai";
+export interface Catalogs {
+    /** A built-in provider, listing what the published catalog adds to it; one that fetches its own list, as it is. */
+    over(provider: Provider): Provider;
+    /** Where pi-ai keeps the list of a provider that fetches its own. */
+    fetched: ModelsStore;
+    /**
+     * Bring the lists of `models` (built over {@link over} and {@link fetched}) up to date: the kept ones, then, unless
+     * {@link OFFLINE_VARIABLE} is set, what the network has newer. Never rejects: resolves with why a list is not
+     * current, when one is not.
+     */
+    refresh(models: Models, options?: {
+        force?: boolean;
+    }): Promise<string | undefined>;
+}
+/** The catalogs kept in `dir`, or, without one, for this process alone. `url` and `timeoutMs` are for tests. */
+export declare function catalogsIn(dir: string | undefined, options?: {
+    url?: string;
+    timeoutMs?: number;
+}): Catalogs;

package/dist/harnesses/models/catalog.js

@@ -0,0 +1,254 @@
+/**
+ * The model lists a pi-ai release does not carry yet. pi publishes the catalog of every built-in provider at pi.dev;
+ * when it is newer than the data this pi-ai was built with, each built-in provider lists its models too, so a model a
+ * provider releases can be named without a FastAgent release. A provider that fetches its own list (radius, a provider
+ * in code with `fetchModels`) is refreshed by pi-ai, with the credential that needs. Both are kept in the instance's
+ * state, so a start without the network, or whose refresh fails, has the lists it last had.
+ *
+ * Adapted from pi-coding-agent's `remote-catalog-provider` (MIT). Two differences: one request answers for every
+ * provider, and the published catalog is fetched whatever this machine authenticates (pi-ai's refresh asks the network
+ * only for a provider holding a credential), because a deployed box opens its agent, default model checked, before
+ * anyone logs in on it.
+ */
+import { readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { InMemoryModelsStore, getModelType, isModelType, } from "@earendil-works/pi-ai";
+import { getBuiltinModelDataGeneratedAt } from "@earendil-works/pi-ai/providers/all";
+import { writeFileAtomic } from "../../atomic-write.js";
+const PUBLISHED_URL = "https://pi.dev/api/models";
+/** The model types this pi-ai takes; asked for, since pi.dev answers a client that names none with chat models only. */
+const MODEL_TYPES = ["chat", "image", "classifier"];
+/** How long a fetched catalog counts as current, so a start inside it asks the network nothing. pi's own. */
+const FRESH_MS = 4 * 60 * 60 * 1000;
+const TIMEOUT_MS = 5_000;
+/** `1`: no model list is fetched, and each is the one last kept. */
+const OFFLINE_VARIABLE = "FASTAGENT_OFFLINE";
+/** The catalogs kept in `dir`, or, without one, for this process alone. `url` and `timeoutMs` are for tests. */
+export function catalogsIn(dir, options = {}) {
+    const builtAt = getBuiltinModelDataGeneratedAt();
+    const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+    const fetched = dir === undefined ? new InMemoryModelsStore() : providerFiles(join(dir, "providers"));
+    const publishedPath = dir === undefined ? undefined : join(dir, "published.json");
+    let inMemory;
+    let listed = {};
+    const show = (kept) => {
+        listed = kept && (builtAt === undefined || kept.lastModified > builtAt) ? kept.models : {};
+    };
+    const keep = (published) => {
+        if (publishedPath === undefined)
+            inMemory = published;
+        // Shared writers: a serve and an `invoke` may refresh at once, and either whole catalog is a good one.
+        else
+            writeFileAtomic(publishedPath, JSON.stringify(published), undefined, true);
+    };
+    async function refreshPublished(network, force, signal) {
+        const piAi = piAiVersion();
+        const found = publishedPath === undefined ? inMemory : readJson(publishedPath);
+        const kept = found?.piAi === piAi ? found : undefined;
+        show(kept);
+        if (!network || (!force && kept && Date.now() - kept.checkedAt < FRESH_MS))
+            return;
+        try {
+            await askPublished(piAi, kept, signal);
+        }
+        catch (error) {
+            // A failed ask counts as one: the catalog kept stays, and is not asked for again for FRESH_MS. With none kept,
+            // the next open asks, since a default model may need it.
+            if (kept)
+                keep({ ...kept, checkedAt: Date.now() });
+            throw error;
+        }
+    }
+    async function askPublished(piAi, kept, signal) {
+        const url = new URL(options.url ?? PUBLISHED_URL);
+        url.searchParams.set("types", MODEL_TYPES.join(","));
+        url.searchParams.set("pi-version", piAi);
+        const validator = kept?.etag;
+        const response = await fetch(url, {
+            headers: { accept: "application/json", ...(validator === undefined ? {} : { "if-none-match": validator }) },
+            signal,
+        });
+        if (response.status === 304 && kept) {
+            keep({ ...kept, checkedAt: Date.now() });
+            return;
+        }
+        if (response.status === 404 || response.status === 501) {
+            // pi.dev publishes no catalog for this pi-ai, so its own lists are the current ones.
+            const none = { piAi, models: {}, lastModified: 0, checkedAt: Date.now() };
+            keep(none);
+            show(none);
+            return;
+        }
+        if (!response.ok)
+            throw new Error(`${url.origin} answered ${response.status}`);
+        const needs = response.headers.get("x-pi-model-catalog-minimum-version");
+        if (needs !== null && olderThan(piAi, needs)) {
+            throw new Error(`${url.origin} answered a catalog for pi-ai ${needs} or later, and this is ${piAi}`);
+        }
+        const lastModified = Date.parse(response.headers.get("last-modified") ?? "");
+        const etag = response.headers.get("etag");
+        const published = {
+            piAi,
+            models: parseCatalog(await response.json()),
+            lastModified: Number.isNaN(lastModified) ? 0 : lastModified,
+            ...(etag === null ? {} : { etag }),
+            checkedAt: Date.now(),
+        };
+        keep(published);
+        show(published);
+    }
+    return {
+        over(provider) {
+            if (provider.refreshModels !== undefined)
+                return provider;
+            const added = () => listed[provider.id] ?? [];
+            return {
+                ...provider,
+                getModels: () => merged(provider.getModels(), added().filter((model) => isModelType(model, "chat"))),
+                getAllModels: () => merged(provider.getAllModels?.() ?? provider.getModels(), added()),
+            };
+        },
+        fetched,
+        async refresh(models, { force = false } = {}) {
+            const offline = process.env[OFFLINE_VARIABLE] === "1";
+            const signal = AbortSignal.timeout(timeoutMs);
+            const why = (error) => signal.aborted ? `no answer within ${timeoutMs / 1000}s` : messageOf(error);
+            const [published, own] = await Promise.all([
+                refreshPublished(!offline, force, signal).then(() => undefined, (error) => `pi's published catalog: ${why(error)}`),
+                refreshOwn(models, !offline, force, signal),
+            ]);
+            const problems = [
+                ...(offline && force ? [`${OFFLINE_VARIABLE}=1 is set`] : []),
+                ...(published === undefined ? [] : [published]),
+                ...[...own.errors].map(([provider, error]) => `${provider}: ${messageOf(error)}`),
+                ...(own.aborted ? [`the providers that fetch their own: ${why(undefined)}`] : []),
+            ];
+            if (problems.length === 0)
+                return undefined;
+            const skip = offline ? "" : `; ${OFFLINE_VARIABLE}=1 skips the refresh`;
+            return `model lists not refreshed (${problems.join("; ")}): each lists what it last had${skip}`;
+        },
+    };
+    /**
+     * The providers that fetch their own list, each asked only once what it last fetched is {@link FRESH_MS} old: pi-ai
+     * asks every one of them each refresh it allows the network, and keeps when it last did beside the list.
+     */
+    async function refreshOwn(models, network, force, signal) {
+        // An entry it cannot read counts as none: pi-ai's refresh reads it again, and reports why it could not.
+        const keptOf = (id) => fetched.read(id).then((entry) => entry, () => undefined);
+        const own = models.getProviders().filter((provider) => provider.refreshModels !== undefined);
+        const stale = new Map();
+        const fresh = [];
+        for (const { id } of own) {
+            const kept = await keptOf(id);
+            const checkedAt = kept?.checkedAt;
+            if (force || checkedAt === undefined || Date.now() - checkedAt >= FRESH_MS)
+                stale.set(id, kept);
+            else
+                fresh.push(id);
+        }
+        const [restored, asked] = await Promise.all([
+            models.refresh({ allowNetwork: false, providers: fresh, signal }),
+            models.refresh({ allowNetwork: network, providers: [...stale.keys()], force, signal }),
+        ]);
+        // A failed ask counts as one, as for the published catalog: pi-ai replaces an entry only when it fetched a list, so
+        // one it left as it was is a list asked for and kept, not asked for again for FRESH_MS.
+        const unwritten = new Map();
+        for (const [id, kept] of network ? stale : []) {
+            if (kept === undefined || (await keptOf(id))?.checkedAt !== kept.checkedAt)
+                continue;
+            await fetched
+                .write(id, { ...kept, checkedAt: Date.now() })
+                .catch((error) => void unwritten.set(id, error));
+        }
+        return {
+            aborted: restored.aborted || asked.aborted,
+            errors: new Map([...restored.errors, ...asked.errors, ...unwritten]),
+        };
+    }
+}
+/** The pi-ai this process runs, from its own package.json, which its exports do not reach. */
+function piAiVersion() {
+    let dir = dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-ai")));
+    for (;;) {
+        const pkg = readJson(join(dir, "package.json"));
+        if (pkg?.name === "@earendil-works/pi-ai" && typeof pkg.version === "string")
+            return pkg.version;
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error("no package.json of @earendil-works/pi-ai above its entry");
+        dir = parent;
+    }
+}
+/** Whether release `version` is older than `than`, by `major.minor.patch`. */
+function olderThan(version, than) {
+    const parts = (release) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)/.exec(release);
+        if (match === null)
+            throw new Error(`"${release}" is not a version`);
+        return match.slice(1).map(Number);
+    };
+    const [ours, theirs] = [parts(version), parts(than)];
+    for (const [index, part] of ours.entries()) {
+        const other = theirs[index];
+        if (part !== other)
+            return part < other;
+    }
+    return false;
+}
+/** Published models override built-in ones of the same type and id, as in pi. */
+function merged(builtIn, published) {
+    const byKey = new Map();
+    for (const model of [...builtIn, ...published])
+        byKey.set(`${getModelType(model)}\0${model.id}`, model);
+    return [...byKey.values()];
+}
+/** pi.dev's answer: each provider's models, as a list (with `types`) or keyed by id (without). */
+function parseCatalog(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("the answer is not a model catalog");
+    }
+    const catalog = {};
+    for (const [provider, models] of Object.entries(value)) {
+        const entries = Array.isArray(models) ? models : typeof models === "object" ? Object.values(models) : [];
+        catalog[provider] = entries
+            .filter((entry) => typeof entry === "object" &&
+            entry !== null &&
+            typeof entry.id === "string" &&
+            [undefined, ...MODEL_TYPES].includes(entry.type))
+            .map((model) => ({ ...model, provider }));
+    }
+    return catalog;
+}
+/** One file per provider: each is written by its own refresh, so none waits on another's lock. */
+function providerFiles(dir) {
+    const path = (providerId) => join(dir, `${encodeURIComponent(providerId)}.json`);
+    return {
+        read: async (providerId) => readJson(path(providerId)),
+        write: async (providerId, entry) => writeFileAtomic(path(providerId), JSON.stringify(entry), undefined, true),
+        delete: async (providerId) => rmSync(path(providerId), { force: true }),
+    };
+}
+function readJson(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${path} is not JSON: delete it, and the next refresh fetches it again`);
+    }
+}
+/** pi-ai and `fetch` put the reason in the cause ("fetch failed", "Model refresh failed for radius"). */
+function messageOf(error) {
+    const cause = error.cause instanceof Error ? `: ${error.cause.message}` : "";
+    return `${error.message}${cause}`;
+}

package/dist/{engines/pi/auth.d.ts → harnesses/models/credentials.d.ts}

@@ -11,8 +11,8 @@ export interface FastagentAuthOptions {
 /**
  * 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
+ * replaces the FILES: none is read or written, and no global layer applies. Env variables and a provider's own auth
+ * 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.
@@ -45,7 +45,7 @@ export type FastagentCredentialStore = CredentialStore & {
  * 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.
+ * a provider in its config that authenticates itself) never reaches it — for reading, listing or writing back.
  */
 export declare function fastagentCredentialStore(path?: string, options?: FastagentAuthOptions & {
     fallbackPath?: string;