@fastagent-sh/fastagent 0.24.4 → 0.26.0

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;

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

@@ -1,5 +1,5 @@
 /**
- * Auth for the pi engine: a read-WRITE {@link CredentialStore} over a fastagent credentials file, consumed by the
+ * Auth for the pi harness: a read-WRITE {@link CredentialStore} over a fastagent credentials file, consumed by the
  * `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.
  */
@@ -7,7 +7,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { globalHome, SECRETS_DIRNAME, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 import { log } from "../../log.js";
-import { withLockedFile } from "./locked-file.js";
+import { withLockedFile } from "../../locked-file.js";
 /**
  * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery home
  * `~/.fastagent/`.
@@ -80,7 +80,7 @@ function parseForWrite(raw, where) {
  * 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 function fastagentCredentialStore(path, options = {}) {
     const warn = options.warn ?? ((message) => log.warn(message));

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

@@ -0,0 +1,48 @@
+import type { Credential, CredentialStore, Models, Provider } from "@earendil-works/pi-ai";
+import { type AuthLayers, type CredentialSourceOptions, type FastagentAuthOptions } from "./credentials.ts";
+/** What authenticates one provider for an agent ({@link ModelEnvironment.authStatus}). */
+interface AuthStatus {
+    /** What satisfies it now (`OAuth`, `stored credential`, an env variable's name), after a due refresh. */
+    source?: string;
+    /** Why resolving it failed (a corrupt entry, a refresh the provider refused), when it did. */
+    error?: string;
+    /** The file that holds the stored credential, or the one a login would write; absent over a caller's store. */
+    path?: string;
+    /** The kind of credential the store holds for it, usable or not. */
+    stored?: Credential["type"];
+    /**
+     * An env variable that also authenticates it but goes unused, because a stored credential owns its provider: a key
+     * added to a deployment's value file after the box was logged in, typically.
+     */
+    shadowed?: string;
+}
+export interface ModelEnvironment {
+    /** The credentials files behind {@link credentials}; absent when the caller supplied its own store. */
+    auth?: AuthLayers;
+    credentials: CredentialStore;
+    /** pi's built-ins and the definition's providers, over {@link credentials}. */
+    models: Models;
+    /** Why a model list is not current, when one is not (logged already): each lists what it last had. */
+    catalogProblem?: string;
+    /**
+     * What authenticates `provider` here, resolved exactly as a message resolves it: the one answer the startup report
+     * and a deployed box's `login --if-missing` both give. `modelId` picks the model to probe with; the provider's first
+     * one otherwise (auth is provider-scoped).
+     */
+    authStatus(provider: string, modelId?: string): Promise<AuthStatus>;
+}
+/**
+ * The model environment of the agent in `agentDir` (or, without one, of a caller with no directory: the named or global
+ * credentials file). A supplied `credentialStore` is used as given; otherwise the files: the directory's own layers
+ * ({@link resolveAuthLayers}), or the named file, or the global one. `providers` are the definition's. `environment` is
+ * what the agent's environment adds to this process's: its keys, the requests' settings, and where its files are
+ * (`FASTAGENT_AUTH_PATH`, `FASTAGENT_STATE_DIR`) are all read there first. The model lists are refreshed before it
+ * resolves, kept in the instance's state root (`stateRoot`, else the directory's); `force` asks the network even when
+ * they are fresh.
+ */
+export declare function modelEnvironment(agentDir: string | undefined, source?: CredentialSourceOptions & FastagentAuthOptions, providers?: readonly Provider[], options?: {
+    force?: boolean;
+    stateRoot?: string;
+    environment?: Readonly<Record<string, string>>;
+}): Promise<ModelEnvironment>;
+export {};

package/dist/harnesses/models/environment.js

@@ -0,0 +1,88 @@
+/**
+ * An agent's MODEL ENVIRONMENT as one value: the credential store its messages authenticate through, the models they
+ * resolve against (models.ts) with their lists refreshed (catalog.ts), and what authenticates a provider there. Every
+ * reader builds it here (the serve, the startup report, a deployed box's `login --if-missing`, `info`, `login`, the
+ * model list, `deploy`'s pre-flight), so none can read other credential layers, another registry, or older lists than
+ * the Agent does.
+ */
+import { join } from "node:path";
+import { log } from "../../log.js";
+import { resolveStateRoot } from "../../paths.js";
+import { catalogsIn } from "./catalog.js";
+import { GLOBAL_AUTH_PATH, assertOneCredentialSource, fastagentCredentialStore, resolveAuthLayers, } from "./credentials.js";
+import { environmentAuth, modelsOver, probeAuthSource } from "./models.js";
+/**
+ * The model environment of the agent in `agentDir` (or, without one, of a caller with no directory: the named or global
+ * credentials file). A supplied `credentialStore` is used as given; otherwise the files: the directory's own layers
+ * ({@link resolveAuthLayers}), or the named file, or the global one. `providers` are the definition's. `environment` is
+ * what the agent's environment adds to this process's: its keys, the requests' settings, and where its files are
+ * (`FASTAGENT_AUTH_PATH`, `FASTAGENT_STATE_DIR`) are all read there first. The model lists are refreshed before it
+ * resolves, kept in the instance's state root (`stateRoot`, else the directory's); `force` asks the network even when
+ * they are fresh.
+ */
+export async function modelEnvironment(agentDir, source = {}, providers = [], options = {}) {
+    const environment = options.environment ?? {};
+    const env = { ...process.env, ...environment };
+    assertOneCredentialSource(source);
+    const files = source.credentialStore
+        ? undefined
+        : agentDir
+            ? resolveAuthLayers(agentDir, source.authPath, env)
+            : { path: source.authPath ?? GLOBAL_AUTH_PATH };
+    const store = files === undefined ? undefined : layeredStore(files, providers, source.warn, environment);
+    const credentials = source.credentialStore ?? store;
+    const stateRoot = options.stateRoot ?? (agentDir === undefined ? undefined : resolveStateRoot(agentDir, env));
+    const catalogs = catalogsIn(stateRoot === undefined ? undefined : join(stateRoot, "models"));
+    const models = modelsOver(credentials, providers, catalogs, environment);
+    const catalogProblem = await catalogs.refresh(models, { force: options.force === true });
+    if (catalogProblem !== undefined)
+        log.warn(`[fastagent] ${catalogProblem}`);
+    return {
+        ...(files ? { auth: files } : {}),
+        credentials,
+        models,
+        ...(catalogProblem === undefined ? {} : { catalogProblem }),
+        async authStatus(provider, modelId) {
+            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 environmentAuth(provider, env, undefined, providers))?.source;
+            const shadowed = resolved.source !== undefined && fromEnvironment !== resolved.source ? fromEnvironment : undefined;
+            return {
+                ...(store ? { path: await store.layerOf(provider) } : {}),
+                ...resolved,
+                ...(stored !== undefined ? { stored } : {}),
+                ...(shadowed !== undefined ? { shadowed } : {}),
+            };
+        },
+    };
+}
+/**
+ * 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 file, a provider in code that needs no key, or the environment). 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 layeredStore(auth, providers, warn, environment) {
+    const own = () => fastagentCredentialStore(auth.path, { ...(warn ? { warn } : {}) });
+    if (auth.fallback === undefined)
+        return own();
+    const project = modelsOver(own(), providers, undefined, environment);
+    return fastagentCredentialStore(auth.path, {
+        ...(warn ? { warn } : {}),
+        fallbackPath: auth.fallback,
+        projectAuthenticates: async (providerId) => (await project.checkAuth(providerId)) !== undefined,
+    });
+}

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

@@ -0,0 +1,30 @@
+/**
+ * What an embedding host calls for model credentials (sign-in-api.ts has the types): a store kept where the host
+ * chooses, a sign-in in its own UI, and what authenticates a provider. Thin over what `fastagent login`, `logout` and
+ * `auth check` run, so each rule keeps one implementation. The one translation between FastAgent's types and pi-ai's
+ * is here, written without casts and with every function checked as a function, so it stops compiling when the two
+ * drift apart.
+ */
+import type { CredentialStore as PiCredentialStore } from "@earendil-works/pi-ai";
+import type { CredentialStore, ProviderAuth, SignInOption, SignInRequest, SignInResult } from "../../sign-in-api.ts";
+/**
+ * FastAgent's locked JSON credentials file at `path` (`~` is the home directory, a relative one resolves against the
+ * working directory now). A corrupt or unreadable file rejects every call.
+ */
+export declare function credentialFile(path: string): CredentialStore;
+/** A host's store as pi-ai reads it. */
+export declare function piCredentials(store: CredentialStore): PiCredentialStore;
+/** Every sign-in of the built-in providers, by name, with what authenticates each one now. */
+export declare function signInOptions(credentials: CredentialStore): Promise<SignInOption[]>;
+/**
+ * Sign in to a built-in provider and store the credential. The store is written to first, so a sign-in never runs
+ * toward a store that refuses it; an API key is checked with one request before it is stored, and one the provider
+ * rejects is asked for again. Aborting the interaction's signal rejects with `SignInCancelled` and stores nothing.
+ */
+export declare function signIn(request: SignInRequest): Promise<SignInResult>;
+/**
+ * What a request to a built-in provider authenticates with, resolved as a message resolves it: a stored credential
+ * (refreshing an OAuth token that is due, through the store's `modify`), else the environment. Undefined when nothing
+ * does; rejects when resolving fails, such as a refresh the provider refused.
+ */
+export declare function providerAuth(credentials: CredentialStore, provider: string): Promise<ProviderAuth | undefined>;

package/dist/harnesses/models/host.js

@@ -0,0 +1,97 @@
+import { resolveOverridePath } from "../../paths.js";
+import { fastagentCredentialStore } from "./credentials.js";
+import { loginOptionsOver, loginOver } from "./login.js";
+import { modelsOver } from "./models.js";
+/** The file behind each store {@link credentialFile} made: a sign-in keeps the installation's id beside it. */
+const files = new WeakMap();
+/**
+ * FastAgent's locked JSON credentials file at `path` (`~` is the home directory, a relative one resolves against the
+ * working directory now). A corrupt or unreadable file rejects every call.
+ */
+export function credentialFile(path) {
+    // Resolved once, so the credentials and the installation's id beside them stay in one directory.
+    const resolved = resolveOverridePath(path);
+    if (resolved === undefined)
+        throw new Error("credentialFile needs the path of a credentials file");
+    const file = fastagentCredentialStore(resolved, {
+        warn: (message) => {
+            throw new Error(message);
+        },
+    });
+    const store = {
+        read: (provider) => file.read(provider),
+        list: async () => (await file.list()).map(({ providerId, type }) => ({ provider: providerId, type })),
+        modify: (provider, change) => file.modify(provider, change),
+        delete: (provider) => file.delete(provider),
+    };
+    files.set(store, resolved);
+    return store;
+}
+/** A host's store as pi-ai reads it. */
+export function piCredentials(store) {
+    return {
+        read: (provider) => store.read(provider),
+        list: async () => (await store.list()).map(({ provider, type }) => ({ providerId: provider, type })),
+        modify: (provider, change) => store.modify(provider, change),
+        delete: (provider) => store.delete(provider),
+    };
+}
+/**
+ * A host's interaction as pi-ai drives it. Arrow functions, not the object as it is: both declare `prompt` and
+ * `notify` as methods, whose parameters TypeScript checks in either direction, so a kind of prompt or event pi-ai adds
+ * would pass unseen; a call checks it.
+ */
+function piInteraction(interaction) {
+    return {
+        ...(interaction.signal === undefined ? {} : { signal: interaction.signal }),
+        prompt: (prompt) => interaction.prompt(prompt),
+        notify: (event) => interaction.notify(event),
+    };
+}
+/** Every sign-in of the built-in providers, by name, with what authenticates each one now. */
+export function signInOptions(credentials) {
+    return loginOptionsOver(piCredentials(credentials));
+}
+/**
+ * Sign in to a built-in provider and store the credential. The store is written to first, so a sign-in never runs
+ * toward a store that refuses it; an API key is checked with one request before it is stored, and one the provider
+ * rejects is asked for again. Aborting the interaction's signal rejects with `SignInCancelled` and stores nothing.
+ */
+export function signIn(request) {
+    const { credentials, provider, method, interaction, deviceId } = request;
+    const file = files.get(credentials);
+    return loginOver({
+        provider,
+        method,
+        interaction: piInteraction(interaction),
+        ...(file === undefined ? { credentialStore: piCredentials(credentials) } : { authPath: file }),
+        ...(deviceId === undefined ? {} : { getDeviceId: () => deviceId }),
+    });
+}
+/**
+ * What a request to a built-in provider authenticates with, resolved as a message resolves it: a stored credential
+ * (refreshing an OAuth token that is due, through the store's `modify`), else the environment. Undefined when nothing
+ * does; rejects when resolving fails, such as a refresh the provider refused.
+ */
+export async function providerAuth(credentials, provider) {
+    const models = modelsOver(piCredentials(credentials));
+    if (models.getProvider(provider) === undefined)
+        throw new Error(`unknown provider "${provider}"`);
+    const checked = await models.checkAuth(provider);
+    if (checked === undefined)
+        return undefined;
+    const resolved = await models.getAuth(provider);
+    if (resolved === undefined)
+        return undefined;
+    const source = resolved.source ?? checked.source;
+    const { apiKey, baseUrl } = resolved.auth;
+    // pi's null header is one a request leaves out, which is what a header not given does.
+    const headers = Object.entries(resolved.auth.headers ?? {}).flatMap(([name, value]) => value === null ? [] : [[name, value]]);
+    return {
+        type: checked.type,
+        ...(source === undefined ? {} : { source }),
+        ...(apiKey === undefined ? {} : { apiKey }),
+        ...(headers.length === 0 ? {} : { headers: Object.fromEntries(headers) }),
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+    };
+}