@fastagent-sh/fastagent 0.24.4 → 0.25.0

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

@@ -1,200 +0,0 @@
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { type Api, type CredentialStore, type Model, type Models, type ModelsStore, type Provider } from "@earendil-works/pi-ai";
-import { ModelRuntime } from "@earendil-works/pi-coding-agent";
-/** The built-ins plus `providers` (a same id replaces a built-in), over any credential store. */
-export declare function piModelsOver(credentials: CredentialStore, providers?: readonly Provider[]): Models;
-/**
- * pi's Model with the API-shape generic erased — fastagent only passes models through to the engine, so the generic
- * carries no information.
- */
-export type AnyModel = Model<any>;
-/** The serving default for reasoning effort, pinned to what pi's TUI defaults to (its own DEFAULT_THINKING_LEVEL). */
-export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
-/** The models.json pi loads for an agent, and where its content came from (for a load error). */
-export interface ModelsFile {
-    /** A snapshot pi loads; null when the agent has no models.json. */
-    path: string | null;
-    /** The agent's own file, when the snapshot is a copy of it alone. */
-    snapshotOf?: string;
-    merged?: {
-        machine: string;
-        definition: string;
-    };
-}
-/**
- * Where an agent's custom endpoints come from, for a report: the machine file, the providers the agent inherits from
- * it, and the ones its own file overrides. Undefined when the machine has no file.
- */
-export declare function machineModels(agentDir: string): Promise<{
-    path: string;
-    inherited: string[];
-    overridden: string[];
-} | undefined>;
-/** Whether pi ships this provider id itself, so an agent resolves it without any models.json entry. */
-export declare function isBuiltinProvider(providerId: string): boolean;
-export interface PiModelRuntimeOptions {
-    /** The store every credential is read from and refreshed into. */
-    credentials: CredentialStore;
-    /** The agent dir, whose {@link AGENT_MODELS_FILE} and {@link AGENT_MODEL_CATALOG_FILE} the registry reads. */
-    agentDir?: string;
-    /**
-     * Layer the machine under the agent (default): its models.json and its model catalog ({@link globalCatalogPath}).
-     * Off for the registry a DEPLOYED agent has, which `deploy` must judge by: neither ships, so that registry is the
-     * agent's own two files over the catalog bundled with pi.
-     */
-    machineLayer?: boolean;
-    /** Extra providers for the ids the built-ins do not cover. */
-    providers?: readonly Provider[];
-    /**
-     * Read and write THIS catalog file instead of the layered, read-only snapshot: what a refresh runs on, since the
-     * refresh writes it.
-     */
-    catalogFile?: string;
-    /** Where a catalog refresh asks instead of pi.dev: a test seam. */
-    catalogBaseUrl?: string;
-}
-/**
- * The MACHINE's model catalog: the models pi.dev lists that are newer than the catalog bundled with pi, fetched by
- * `fastagent models --refresh -g`. Every agent here reads it under its own; like `~/.fastagent/models.json`, it
- * never ships.
- */
-export declare function globalCatalogPath(): string;
-/**
- * The catalog file a refresh writes, as pi's store. It replaces pi's own file store, which rewrites the file in place
- * under its lock: a reader that takes no lock (every catalog read here, and anything else reading the file) could open
- * it cut short mid-write and blame a healthy file. Same lock as pi's, so concurrent refreshes still queue; reading
- * creates nothing, so a refresh that is refused writes no file.
- */
-export declare function catalogFileStore(path: string): ModelsStore;
-/**
- * Whether the machine's model catalog supplies this model, by the same rule every registry reads it with
- * ({@link layeredCatalog}): an entry pi would ignore supplies nothing. The one layer a deployed agent does not have.
- */
-export declare function inGlobalCatalog(provider: string, id: string): Promise<boolean>;
-/**
- * The model files a runtime reads, READ ONCE: `agentModels` keeps one of these per agent, so every session's runtime
- * and the control plane's catalog see the same content however the files change while serving.
- */
-export interface ModelFiles {
-    models?: ModelsFile;
-    /** `ModelRuntime.create` options over this read; a fresh catalog store each call. */
-    create(): Promise<{
-        modelsPath: string | null;
-        modelsStore?: ModelsStore;
-        allowModelNetwork: false;
-        catalogBaseUrl?: string;
-    }>;
-}
-/** The models.json a runtime for these options loads, and which model catalog it reads. */
-export declare function modelRuntimeFiles(options: Omit<PiModelRuntimeOptions, "credentials">): Promise<ModelFiles>;
-/**
- * This machine's registry, without an agent: pi's built-ins, the machine's models.json and its model catalog. What
- * `fastagent models` lists outside an agent; {@link catalogFile} is the refresh's (it writes the file).
- */
-export declare function machineModelRuntime(options?: {
-    credentials?: CredentialStore;
-    catalogFile?: string;
-    catalogBaseUrl?: string;
-}): Promise<ModelRuntime>;
-/**
- * Fetch the model catalog of every provider the runtime can authenticate into `catalogFile` ({@link
- * catalogFileStore}): the refresh `pi update --models` runs. `build` makes the runtime over that file, and runs only
- * once the refresh is known to go ahead. A refusal writes nothing: the store creates the file only when pi writes an
- * entry. pi asks pi.dev only for a provider with a usable credential, and may refresh an expired OAuth token of the
- * runtime's store to get one. Rejects, naming each provider that failed, when any part fails, when it outlasts 15
- * seconds, when `PI_OFFLINE` is set, when the catalog file is corrupt, and when no provider has a usable credential (the
- * refresh would ask for nothing).
- */
-export declare function refreshCatalog(catalogFile: string, build: (catalogFile: string) => Promise<ModelRuntime>, options?: {
-    signal?: AbortSignal;
-}): Promise<void>;
-/**
- * What satisfies a provider from `env` alone (its API-key variable, or an ambient source such as an AWS profile), by
- * pi's own check, or undefined. Passed explicitly rather than read from `process.env`: only the environment a SHELL
- * hands down is shared by every agent on the machine, and a process that has loaded an agent's `.secrets/.env` holds
- * that agent's variables too. What the shell shares outranks the global credentials file (agent-models.ts),
- * so a global login for such a provider is not used.
- *
- * `fileExists` answers for the files a source points at (an AWS profile, Google ADC): this machine's by default, which
- * is right wherever the answer is about THIS machine. A deployment passes one that finds nothing, because no file of
- * the builder's travels with it.
- */
-export declare function environmentAuthSource(providerId: string, env: NodeJS.ProcessEnv, fileExists?: (path: string) => Promise<boolean>): Promise<string | undefined>;
-/** Pi registration starts background refreshes; wait for all of them before publishing this fresh runtime. */
-export declare function withModelRegistration<T>(runtime: ModelRuntime, register: () => Promise<T>): Promise<T>;
-/**
- * A registry over the given credential store. What an agent runs on is built through `agentModels`
- * (agent-models.ts); this is for a registry over some OTHER store: none at all (`models`, a deploy check of what
- * ships), a trial key under test (login), or the catalog file a refresh writes.
- */
-export declare function createPiModelRuntime(options: PiModelRuntimeOptions & {
-    files?: ModelFiles;
-}): Promise<ModelRuntime>;
-/**
- * EVERY provider whose `models.json` entry writes its key as a LITERAL rather than a `"$NAME"` reference or a
- * `"!cmd"`. The file ships inside the image, so a literal there is a credential in a readable layer.
- *
- * Read from the FILE, not from `getProviderAuthStatus`: that answers "what satisfies this provider right now" and
- * returns `stored` first, so a provider that has both an `auth.json` entry and a literal in the file would report
- * `stored` and the literal would go unreported. The question is what the definition DECLARES, and only the file
- * answers it. The three-way split mirrors pi's `configuredRequestAuthStatus`, which is not exported.
- *
- * The caller WARNS on this; it does not refuse. Whether a given string is a credential is the author's knowledge,
- * not the framework's — pi's own docs prescribe `"apiKey": "ollama"` for a keyless local server, and no static rule
- * separates that from a leaked key (an endpoint's reachability is not decidable from its URL either). FastAgent
- * gates what IT causes; what the author wrote into their own committed file, it reports.
- */
-export declare function literalKeyProviders(agentDir: string): Promise<string[]>;
-/**
- * How the agent's OWN models.json supplies `providerId`'s key, read from the file for the reason
- * {@link literalKeyProviders} gives: `reference` is the variable a `"$NAME"` reads (the value file must hold it),
- * `inFile` a key that travels with the definition itself (a literal, or a `"!command"` run on the box), and undefined
- * no apiKey there at all.
- */
-export declare function definitionKeyOf(agentDir: string, providerId: string): Promise<{
-    reference: string;
-} | {
-    inFile: true;
-} | undefined>;
-/**
- * What a provider can offer as an interactive login: an OAuth flow, an API-key ENTRY prompt, or nothing ("none" — the
- * key must come from the provider's env var).
- */
-export type InteractiveLoginKind = "oauth" | "api_key" | "none";
-export declare function interactiveLoginKind(p: Provider): InteractiveLoginKind;
-/** THE rule for "can this method be signed in to interactively": the auth to run for it, or undefined. */
-export declare function interactiveAuth(provider: Provider, method: Exclude<InteractiveLoginKind, "none">): import("@earendil-works/pi-ai").ApiKeyAuth | import("@earendil-works/pi-ai").OAuthAuth | undefined;
-/** The providers a sign-in can target: pi's built-ins plus `extra`, composed exactly as {@link piModelsOver} does. */
-export declare function loginProviders(extra?: readonly Provider[]): readonly Provider[];
-/** Per-provider auth status for the first-run model picker. */
-export type ProviderAuthStatus = {
-    state: "ready";
-    source?: string;
-} | {
-    state: "unconfigured";
-    login: InteractiveLoginKind;
-} | {
-    state: "broken";
-    message: string;
-    login: InteractiveLoginKind;
-};
-/** Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe). */
-export declare function providerAuthStatuses(models: Models): Promise<Map<string, ProviderAuthStatus>>;
-/**
- * Which source currently satisfies auth for `spec`, or undefined when none does (or the spec is not in `models`).
- * Rejects when resolving fails — a corrupt entry, a refresh the provider refused — which is a different answer from
- * "nothing configured" and must reach whoever reports it.
- */
-export declare function probeAuthSource(models: Models, spec: string): Promise<string | undefined>;
-/**
- * Verdict of {@link probeApiKey}: `rejected` is DEFINITIVE (the provider answered HTTP 401 — the key is wrong);
- * everything else non-ok is `unknown`.
- */
-export type KeyProbe = {
-    state: "ok";
-} | {
-    state: "rejected" | "unknown";
-    message: string;
-};
-/** Quick-fail probe for a just-stored API key. */
-export declare function probeApiKey(models: Models, model: Model<Api>, signal?: AbortSignal): Promise<KeyProbe>;