@fastagent-sh/fastagent 0.24.4 → 0.26.0

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

@@ -0,0 +1,84 @@
+/**
+ * pi-ai's model collection as FastAgent composes it: the built-in providers over a credential store, kept current by
+ * the catalogs (catalog.ts), and the definition's own providers; and the reads a report, a login or a picker make of
+ * it. A custom model is a provider in code (`defineAgent({ providers })`), never a models file or a per-account list
+ * (architecture.md §3).
+ */
+import { type Api, type CredentialStore, type Model, type Models, type Provider } from "@earendil-works/pi-ai";
+import type { Catalogs } from "./catalog.ts";
+/** The provider of a `"provider/modelId"` spec. */
+export declare function providerOf(spec: string): string;
+/** Every chat model `models` offers, as `"provider/modelId"`, sorted. */
+export declare function listModels(models: Models): string[];
+/**
+ * The built-ins plus `providers` (a same id replaces a built-in), over any credential store, in `environment`: what
+ * the agent's environment adds to this process's, read before it by a provider's auth and by each request. With
+ * `catalogs`, the lists its refresh brings up to date; without, the ones this pi-ai was built with.
+ */
+export declare function modelsOver(credentials: CredentialStore, providers?: readonly Provider[], catalogs?: Catalogs, environment?: Readonly<Record<string, string>>): Models;
+/**
+ * Whether `env` alone satisfies a provider, by pi's own check, and with what when the provider says (its API-key
+ * variable, or an ambient source such as an AWS profile); undefined when it does not. A provider in code may
+ * authenticate without naming a source. 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 (environment.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 environmentAuth(providerId: string, env: NodeJS.ProcessEnv, fileExists?: (path: string) => Promise<boolean>, providers?: readonly Provider[]): Promise<{
+    source?: string;
+} | undefined>;
+/**
+ * The environment variables a provider reads its key from, in the order it reads them: what a person sets for it to
+ * authenticate with no sign-in. pi-ai keeps the names inside each provider's auth, so they are learnt by asking the
+ * provider to authenticate over an environment that records every name asked for and holds none. Its side-effect-free
+ * `check` when it has one, since its `resolve` may then run commands.
+ */
+export declare function keyVariables(provider: Provider): Promise<string[]>;
+/**
+ * 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 modelsOver} 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>>;
+/** The source of a provider that authenticates without naming one: a definition's provider resolving its own key. */
+export declare const UNNAMED_AUTH_SOURCE = "the provider's own auth";
+/**
+ * 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>;

package/dist/harnesses/models/models.js

@@ -0,0 +1,197 @@
+/**
+ * pi-ai's model collection as FastAgent composes it: the built-in providers over a credential store, kept current by
+ * the catalogs (catalog.ts), and the definition's own providers; and the reads a report, a login or a picker make of
+ * it. A custom model is a provider in code (`defineAgent({ providers })`), never a models file or a per-account list
+ * (architecture.md §3).
+ */
+import { InMemoryCredentialStore, createModels, defaultProviderAuthContext, } from "@earendil-works/pi-ai";
+import { builtinModels, builtinProviders } from "@earendil-works/pi-ai/providers/all";
+/** The provider of a `"provider/modelId"` spec. */
+export function providerOf(spec) {
+    const slash = spec.indexOf("/");
+    return slash > 0 ? spec.slice(0, slash) : spec;
+}
+/** Every chat model `models` offers, as `"provider/modelId"`, sorted. */
+export function listModels(models) {
+    const specs = [];
+    for (const provider of models.getProviders()) {
+        for (const model of provider.getModels())
+            specs.push(`${provider.id}/${model.id}`);
+    }
+    return specs.sort();
+}
+/**
+ * pi's own reading of an environment (a blank variable is unset) through `read` instead of this process's: an agent's
+ * environment is its own when the process runs several. Files a source points at are this machine's unless
+ * `fileExists` says otherwise.
+ */
+function authContextIn(read, fileExists = defaultProviderAuthContext().fileExists) {
+    return {
+        env: async (name) => {
+            const value = read(name);
+            return value?.trim() ? value : undefined;
+        },
+        fileExists,
+    };
+}
+/**
+ * `provider` with `environment` given to each request, as its auth reads it: pi resolves a provider's key from the
+ * auth context, but a request reads its region, endpoint or ambient key (Bedrock, Azure, Vertex) from the request's
+ * own `env`, which it otherwise takes from this process.
+ */
+function inEnvironment(provider, environment) {
+    const withEnv = (options) => ({ ...options, env: { ...environment, ...options?.env } });
+    const { fetchDeferred, cancelDeferred, generateImages, classify } = provider;
+    return {
+        ...provider,
+        stream: (model, context, options) => provider.stream(model, context, withEnv(options)),
+        streamSimple: (model, context, options) => provider.streamSimple(model, context, withEnv(options)),
+        ...(fetchDeferred && {
+            fetchDeferred: (model, handle, options) => fetchDeferred.call(provider, model, handle, withEnv(options)),
+        }),
+        ...(cancelDeferred && {
+            cancelDeferred: (model, handle, options) => cancelDeferred.call(provider, model, handle, withEnv(options)),
+        }),
+        ...(generateImages && {
+            generateImages: (model, context, options) => generateImages.call(provider, model, context, withEnv(options)),
+        }),
+        ...(classify && {
+            classify: (model, context, options) => classify.call(provider, model, context, withEnv(options)),
+        }),
+    };
+}
+/**
+ * The built-ins plus `providers` (a same id replaces a built-in), over any credential store, in `environment`: what
+ * the agent's environment adds to this process's, read before it by a provider's auth and by each request. With
+ * `catalogs`, the lists its refresh brings up to date; without, the ones this pi-ai was built with.
+ */
+export function modelsOver(credentials, providers = [], catalogs, environment = {}) {
+    const models = createModels({
+        credentials,
+        // As a request reads it (pi's getProviderEnvValue): the request's env first, then this process's.
+        authContext: authContextIn((name) => environment[name] || process.env[name]),
+        ...(catalogs ? { modelsStore: catalogs.fetched } : {}),
+    });
+    for (const builtIn of builtinProviders()) {
+        models.setProvider(inEnvironment(catalogs ? catalogs.over(builtIn) : builtIn, environment));
+    }
+    for (const provider of providers)
+        models.setProvider(inEnvironment(provider, environment));
+    return models;
+}
+/**
+ * Whether `env` alone satisfies a provider, by pi's own check, and with what when the provider says (its API-key
+ * variable, or an ambient source such as an AWS profile); undefined when it does not. A provider in code may
+ * authenticate without naming a source. 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 (environment.ts), so a
+ * global login for such a provider is not used.
+ *
+ * `fileExists` answers for the files a source points at (an AWS profile, Google ADC): this machine's by default, which
+ * is right wherever the answer is about THIS machine. A deployment passes one that finds nothing, because no file of
+ * the builder's travels with it.
+ */
+export async function environmentAuth(providerId, env, fileExists = defaultProviderAuthContext().fileExists, providers = []) {
+    const models = builtinModels({
+        credentials: new InMemoryCredentialStore(),
+        authContext: authContextIn((name) => env[name], fileExists),
+    });
+    for (const provider of providers)
+        models.setProvider(provider);
+    return models.checkAuth(providerId);
+}
+/**
+ * The environment variables a provider reads its key from, in the order it reads them: what a person sets for it to
+ * authenticate with no sign-in. pi-ai keeps the names inside each provider's auth, so they are learnt by asking the
+ * provider to authenticate over an environment that records every name asked for and holds none. Its side-effect-free
+ * `check` when it has one, since its `resolve` may then run commands.
+ */
+export async function keyVariables(provider) {
+    const apiKey = provider.auth.apiKey;
+    if (apiKey === undefined)
+        return [];
+    const asked = new Set();
+    const ctx = {
+        env: async (name) => void asked.add(name),
+        fileExists: async () => false,
+    };
+    const signal = new AbortController().signal;
+    await (apiKey.check ? apiKey.check({ ctx, signal }) : apiKey.resolve({ ctx, signal }));
+    return [...asked];
+}
+export function interactiveLoginKind(p) {
+    if (interactiveAuth(p, "oauth"))
+        return "oauth";
+    return interactiveAuth(p, "api_key") ? "api_key" : "none";
+}
+/** THE rule for "can this method be signed in to interactively": the auth to run for it, or undefined. */
+export function interactiveAuth(provider, method) {
+    return method === "oauth" ? provider.auth.oauth : provider.auth.apiKey?.login ? provider.auth.apiKey : undefined;
+}
+/** The providers a sign-in can target: pi's built-ins plus `extra`, composed exactly as {@link modelsOver} does. */
+export function loginProviders(extra) {
+    return modelsOver(new InMemoryCredentialStore(), extra).getProviders();
+}
+/** Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe). */
+export async function providerAuthStatuses(models) {
+    const statuses = new Map();
+    for (const provider of models.getProviders()) {
+        const [probe] = provider.getModels();
+        if (!probe)
+            continue;
+        const login = interactiveLoginKind(provider);
+        try {
+            const auth = await models.getAuth(probe);
+            statuses.set(provider.id, auth ? { state: "ready", source: auth.source } : { state: "unconfigured", login });
+        }
+        catch (error) {
+            statuses.set(provider.id, { state: "broken", message: error.message, login });
+        }
+    }
+    return statuses;
+}
+/** The source of a provider that authenticates without naming one: a definition's provider resolving its own key. */
+export const UNNAMED_AUTH_SOURCE = "the provider's own auth";
+/**
+ * Which source currently satisfies auth for `spec`, or undefined when none does (or the spec is not in `models`).
+ * Rejects when resolving fails — a corrupt entry, a refresh the provider refused — which is a different answer from
+ * "nothing configured" and must reach whoever reports it.
+ */
+export async function probeAuthSource(models, spec) {
+    const slash = spec.indexOf("/");
+    if (slash < 1)
+        return undefined;
+    const model = models.getModel(spec.slice(0, slash), spec.slice(slash + 1));
+    if (!model)
+        return undefined;
+    // A virtual selection authenticates the physical model after routing, not its catalog entry.
+    if (model.api === "pi-virtual")
+        return "virtual";
+    const auth = await models.getAuth(model);
+    return auth === undefined ? undefined : (auth.source ?? UNNAMED_AUTH_SOURCE);
+}
+/** Quick-fail probe for a just-stored API key. */
+export async function probeApiKey(models, model, signal) {
+    let status;
+    let reply;
+    try {
+        reply = await models.complete(model, { messages: [{ role: "user", content: "ping", timestamp: Date.now() }] }, {
+            maxTokens: 16,
+            timeoutMs: 15_000,
+            maxRetries: 0,
+            ...(signal ? { signal } : {}),
+            onResponse: (r) => {
+                status = r.status;
+            },
+        });
+    }
+    catch (error) {
+        // Thrown = before/around the request (auth resolution, transport setup) — not a provider verdict.
+        return { state: "unknown", message: error.message };
+    }
+    if (reply.stopReason !== "error" && reply.stopReason !== "aborted")
+        return { state: "ok" };
+    const message = reply.errorMessage ?? `stopReason "${reply.stopReason}"`;
+    const unauthorized = status === 401 || (status === undefined && /(^|\D)401(\D|$)/.test(message));
+    return { state: unauthorized ? "rejected" : "unknown", message };
+}

package/dist/harnesses/pi-durable/agent.d.ts

@@ -0,0 +1,42 @@
+import type { Models, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { type Conversation, Harness, type HarnessOptions, type HarnessSettings, type ModelRef, type RegistryReader, type Storage } from "@earendil-works/pi-durable";
+import { type Agent } from "../../agent-api.ts";
+/** What a Caller may offer as `/<name>`: a prompt template or a skill, expanded for the model (SPEC.md §5.1). */
+export interface AgentCommand {
+    name: string;
+    description?: string;
+    expand(args: string): string;
+}
+export interface DurableAgentOptions {
+    storage: Storage;
+    models: Models;
+    registry: RegistryReader;
+    settings?: HarnessSettings;
+    env?: HarnessOptions["env"];
+    name: string;
+    description?: string;
+    /** Read for every `info()` and send, so a command the definition gains is offered without a restart. */
+    commands?: () => readonly AgentCommand[];
+    /** What a conversation answers with when its own settings name none (defaults.ts). */
+    model?: ModelRef;
+    thinkingLevel?: ModelThinkingLevel;
+    inFlightPerProcess?: number;
+    /** What becomes of the messages an earlier process accepted and did not end ({@link Unfinished}). */
+    unfinished?: Unfinished;
+}
+/**
+ * What a process does with the messages an earlier one accepted and did not end (it was stopped, or killed). `"resume"`
+ * (the default, a serve's): they run on in this one, as its own work. `"abort"`: they end aborted before anything runs,
+ * for a Caller whose messages do not outlive it (`fastagent invoke`), where running one again would run what its user
+ * stopped. `"refuse"`: the open fails naming them, for a process that runs one thing and would cut the rest off
+ * (`fastagent schedules run`).
+ */
+export type Unfinished = "resume" | "abort" | "refuse";
+export interface DurableAgent extends Agent {
+    /** pi-durable's own API, for operating the agent. */
+    readonly harness: Harness;
+    /** The conversation a session id names, to operate it through `harness`. */
+    conversation(sessionId: string): Promise<Conversation | undefined>;
+    close(): Promise<void>;
+}
+export declare function openDurableAgent(options: DurableAgentOptions): Promise<DurableAgent>;