@fastagent-sh/fastagent 0.22.1 → 0.23.0

package/dist/engines/pi/invoke-session.js

@@ -4,6 +4,7 @@ import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Queue from "effect/Queue";
 import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
+import { entryImages } from "./entry-images.js";
 import { cancellableStream } from "../../collect.js";
 import { log } from "../../log.js";
 import { toRetryScheduledEvent } from "./retry-event.js";
@@ -105,9 +106,10 @@ function reportUserMessages(session, report) {
     return Effect.acquireRelease(Effect.sync(() => {
         record.appendMessage = (message) => {
             const entryId = append.call(record, message);
-            // The same text `entries()` publishes for this entry (session-control.ts toSessionEntry).
-            if (message.role === "user")
-                report(entryId, contentText(message.content, ""));
+            // The same text and images `entries()` publishes for this entry (session-control.ts toSessionEntry).
+            if (message.role === "user") {
+                report({ entryId, text: contentText(message.content, ""), ...entryImages(entryId, message) });
+            }
             return entryId;
         };
     }), () => Effect.sync(() => {
@@ -240,7 +242,7 @@ export function createPiAgentFromSession(options) {
                 if (OWED_BY_THE_RUN.has(error.event))
                     extensionFailure ??= `${error.event} failed (${error.extensionPath}): ${error.error}`;
             })), (unsubscribe) => Effect.sync(unsubscribe));
-            yield* reportUserMessages(session, (entryId, text) => observe({ type: "user_message", timestamp: Date.now(), runId, data: { entryId, text } }));
+            yield* reportUserMessages(session, (data) => observe({ type: "user_message", timestamp: Date.now(), runId, data }));
             const extensionTurns = trackExtensionTurns(session);
             // Completing the gate can run waiting controls synchronously; their queue events must be observed.
             yield* Deferred.succeed(bound, session);

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

@@ -4,7 +4,7 @@
  * (one writer, one lock/corruption semantics); {@link loginOptions} is the list a picker offers. `fastagent login` is
  * one front end ({@link loginFlow}: terminal menus, then {@link login}); a GUI client is another.
  */
-import { type AuthInteraction, type Provider } from "@earendil-works/pi-ai";
+import { type AuthInteraction, type CredentialStore, type Provider } from "@earendil-works/pi-ai";
 export type LoginMethod = "oauth" | "api_key";
 /** The user backed out of a prompt/menu, or the flow was aborted — a decision, not a failure. */
 export declare class LoginCancelled extends Error {
@@ -18,26 +18,32 @@ export interface LoginOption {
     /** An OAuth login backed by a provider subscription. */
     subscription: boolean;
     /**
-     * What the file holds for this provider now. It keeps ONE credential per provider, so signing in with the other
+     * What the store holds for this provider now. It keeps ONE credential per provider, so signing in with the other
      * method replaces it — worth a warning in a client.
      */
     stored?: LoginMethod;
 }
 /**
- * Every interactive sign-in of pi's built-in providers, with what `authPath` already holds for each. A provider whose
- * key can only come from its env var offers none and is left out.
+ * Every interactive sign-in of pi's built-in providers, with what `credentials` (a credentials file, or the caller's
+ * own store) already holds for each. A provider whose key can only come from its env var offers none and is left out.
  */
-export declare function loginOptions(authPath: string): Promise<LoginOption[]>;
+export declare function loginOptions(credentials: string | CredentialStore): Promise<LoginOption[]>;
 /** {@link loginOptions} over pi's built-ins plus `providers` (a same id replaces one). Not public: a test seam. */
-export declare function loginOptionsOver(authPath: string, providers?: readonly Provider[]): Promise<LoginOption[]>;
-export interface LoginRequest {
+export declare function loginOptionsOver(credentials: string | CredentialStore, providers?: readonly Provider[]): Promise<LoginOption[]>;
+export type LoginRequest = {
     provider: string;
     method: LoginMethod;
-    /** The credentials file the sign-in is written to. */
-    authPath: string;
     /** pi-ai's own interaction: prompts (`text`, `secret`, `select`, `manual_code`) and events (`auth_url`, …). */
     interaction: AuthInteraction;
-}
+} & ({
+    /** The credentials file the sign-in is written to. */
+    authPath: string;
+    credentialStore?: never;
+} | {
+    /** The caller's own store the sign-in is written to, in place of any file. */
+    credentialStore: CredentialStore;
+    authPath?: never;
+});
 export interface LoginResult {
     provider: string;
     method: LoginMethod;
@@ -45,10 +51,11 @@ export interface LoginResult {
     verified: "ok" | "unknown" | "n/a";
 }
 /**
- * Sign in to one of pi's built-in providers and persist the credential to `authPath`.
+ * Sign in to one of pi's built-in providers and persist the credential to `authPath`, or to the caller's
+ * `credentialStore`.
  *
- * The file is checked FIRST (a no-op write runs the refuse-corrupt and writability checks), so a flow never runs
- * toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
+ * The store is checked FIRST (a no-op write runs the file store's refuse-corrupt and writability checks, or whatever
+ * the caller's store does on a write), so a flow never runs toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
  * default model for the provider (its first model when pi names none), at pi's built-in endpoint, BEFORE it is
  * written. Credentials are provider-scoped, so any of the provider's models answers the question the check asks (does
  * the provider refuse the key, HTTP 401); a key the provider rejects is never stored, and the provider's key flow runs

package/dist/engines/pi/login.js

@@ -7,21 +7,24 @@
 import { InMemoryCredentialStore, } from "@earendil-works/pi-ai";
 import { fastagentCredentialStore } from "./auth.js";
 import { createPiModelRuntime, interactiveAuth, loginProviders, piModelsOver, probeApiKey } from "./models.js";
+import { agentModels } from "./agent-models.js";
 /** The user backed out of a prompt/menu, or the flow was aborted — a decision, not a failure. */
 export class LoginCancelled extends Error {
 }
 /**
- * Every interactive sign-in of pi's built-in providers, with what `authPath` already holds for each. A provider whose
- * key can only come from its env var offers none and is left out.
+ * Every interactive sign-in of pi's built-in providers, with what `credentials` (a credentials file, or the caller's
+ * own store) already holds for each. A provider whose key can only come from its env var offers none and is left out.
  */
-export function loginOptions(authPath) {
-    return loginOptionsOver(authPath);
+export function loginOptions(credentials) {
+    return loginOptionsOver(credentials);
 }
+/** A credentials file path names fastagent's store over it; a store is used as given. */
+const storeOf = (credentials) => typeof credentials === "string" ? fastagentCredentialStore(credentials) : credentials;
 /** {@link loginOptions} over pi's built-ins plus `providers` (a same id replaces one). Not public: a test seam. */
-export async function loginOptionsOver(authPath, providers) {
-    // ONE read of the file: `list` is metadata only, and reading per provider would repeat a corrupt file's warning for
+export async function loginOptionsOver(credentials, providers) {
+    // ONE read of the store: `list` is metadata only, and reading per provider would repeat a corrupt file's warning for
     // every provider.
-    const held = new Map((await fastagentCredentialStore(authPath).list()).map((info) => [info.providerId, info.type]));
+    const held = new Map((await storeOf(credentials).list()).map((info) => [info.providerId, info.type]));
     const offered = [];
     for (const provider of loginProviders(providers)) {
         const methods = ["oauth", "api_key"].filter((method) => interactiveAuth(provider, method));
@@ -46,10 +49,11 @@ function anySignal(...signals) {
     return present.length === 0 ? undefined : present.length === 1 ? present[0] : AbortSignal.any(present);
 }
 /**
- * Sign in to one of pi's built-in providers and persist the credential to `authPath`.
+ * Sign in to one of pi's built-in providers and persist the credential to `authPath`, or to the caller's
+ * `credentialStore`.
  *
- * The file is checked FIRST (a no-op write runs the refuse-corrupt and writability checks), so a flow never runs
- * toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
+ * The store is checked FIRST (a no-op write runs the file store's refuse-corrupt and writability checks, or whatever
+ * the caller's store does on a write), so a flow never runs toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
  * default model for the provider (its first model when pi names none), at pi's built-in endpoint, BEFORE it is
  * written. Credentials are provider-scoped, so any of the provider's models answers the question the check asks (does
  * the provider refuse the key, HTTP 401); a key the provider rejects is never stored, and the provider's key flow runs
@@ -66,7 +70,10 @@ export function login(request) {
 /** {@link login}, plus {@link LoginInternals}. */
 export async function loginOver(request, internals = {}) {
     const { providers, verifyWith, agentDir } = internals;
-    const { method, authPath, interaction } = request;
+    const { method, interaction } = request;
+    if (request.credentialStore === undefined && typeof request.authPath !== "string") {
+        throw new Error("login needs authPath or credentialStore: where the sign-in is written");
+    }
     const provider = loginProviders(providers).find((p) => p.id === request.provider);
     if (!provider)
         throw new Error(`unknown provider "${request.provider}"`);
@@ -86,7 +93,7 @@ export async function loginOver(request, internals = {}) {
                 ...(providers ? { providers: [...providers] } : {}),
             })
             : piModelsOver(trial, providers);
-    const store = fastagentCredentialStore(authPath);
+    const store = agentModels(undefined, request).credentials;
     await store.modify(provider.id, async () => undefined);
     const signal = interaction.signal ?? new AbortController().signal;
     const notify = (event) => interaction.notify(event);

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

@@ -1,17 +1,6 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { type Api, type CredentialStore, type Model, type Models, type Provider } from "@earendil-works/pi-ai";
+import { type Api, type CredentialStore, InMemoryModelsStore, type Model, type Models, type Provider } from "@earendil-works/pi-ai";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
-import { type FastagentAuthOptions } from "./auth.ts";
-import { type AuthLayers } from "./config.ts";
-/** The DEFINITION-LOCAL custom-endpoint file, in pi's own models.json schema (see pi's docs/models.md). */
-export interface CreatePiModelsOptions extends FastagentAuthOptions {
-    /** Credentials file (default `GLOBAL_AUTH_PATH`). A named file is an instruction: no second layer. */
-    authPath?: string;
-    /** Extra providers registered on top of the built-ins (same id overrides a built-in). */
-    providers?: Provider[];
-}
-/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
-export declare function createPiModels(options?: CreatePiModelsOptions): Models;
 /** 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;
 /**
@@ -21,12 +10,6 @@ export declare function piModelsOver(credentials: CredentialStore, providers?: r
 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 MACHINE's custom-endpoint file, in the same schema as an agent's own: endpoints a person set up for this machine
- * (a local Ollama, a company gateway), which every agent here inherits the way it inherits the machine's skills.
- * `FASTAGENT_MODELS_PATH` moves it. It never ships: a deployed agent has only its definition's file.
- */
-export declare function machineModelsPath(env?: NodeJS.ProcessEnv): 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.
@@ -38,29 +21,110 @@ export declare function machineModels(agentDir: string): Promise<{
 } | 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;
-/** The `ModelRuntime`-shaped sibling of {@link createPiModels}. */
-export declare function createPiModelRuntime(options?: FastagentAuthOptions & {
-    /** The credentials files to read (default: the global file alone). */
-    auth?: AuthLayers;
-    /** The agent dir, whose {@link AGENT_MODELS_FILE} declares custom endpoints. */
+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's models.json under the agent's (default). Off for the registry a DEPLOYED agent has, which
-     * `deploy` must judge by: the machine's file does not ship.
+     * 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;
-    /** Where the dynamic model-catalog cache goes; defaults to the agent's resolved state root. */
-    stateRoot?: string;
     /** Extra providers for the ids the built-ins do not cover. */
-    providers?: Provider[];
-    /** A credential store to use instead of the files (login verifies an entered key from memory). */
+    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;
+/**
+ * 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 models.json a runtime for these options loads, and which model catalog it reads. */
+export declare function modelRuntimeFiles(options: Omit<PiModelRuntimeOptions, "credentials">): Promise<{
+    models: {
+        path: string;
+        merged?: {
+            machine: string;
+            definition: string;
+        };
+    } | undefined;
+    create: {
+        modelsPath: string | null;
+        modelsStorePath: string;
+        allowModelNetwork: boolean;
+        catalogBaseUrl?: string | undefined;
+    } | {
+        modelsPath: string | null;
+        modelsStore: InMemoryModelsStore;
+        allowModelNetwork: boolean;
+        catalogBaseUrl?: string | undefined;
+    } | {
+        modelsPath: string | null;
+        allowModelNetwork: boolean;
+        catalogBaseUrl?: string | undefined;
+    };
+}>;
+/**
+ * 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>;
-/** How a model's credential will REACH a deployed agent. */
-export declare function modelCredentialCarry(runtime: ModelRuntime, spec: string): {
-    envVar?: string;
-    inDefinition: boolean;
-};
+/**
+ * Refresh the machine's catalog ({@link globalCatalogPath}) with the machine's credentials: the global credentials
+ * file and the environment. See {@link refreshCatalog} for what it asks and when it rejects.
+ */
+export declare function refreshGlobalModelCatalog(options?: {
+    signal?: AbortSignal;
+    catalogBaseUrl?: string;
+}): Promise<void>;
+/**
+ * Fetch the model catalog of every provider the runtime can authenticate into its catalog file: the refresh
+ * `pi update --models` runs. `runtime(true)` is built over that file, `runtime(false)` over the read-only layers; the
+ * file-backed one is built only once the refresh is known to run, because pi's file store creates the file on read and
+ * a refused refresh must leave nothing behind. 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, and when no provider has a
+ * usable credential (the refresh would ask for nothing).
+ */
+export declare function refreshCatalog(runtime: (catalogFile: boolean) => 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>;
+/**
+ * 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): 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.
@@ -76,6 +140,17 @@ export declare function modelCredentialCarry(runtime: ModelRuntime, spec: string
  * 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).
@@ -84,7 +159,7 @@ 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 createPiModels} does. */
+/** 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 = {
@@ -100,7 +175,11 @@ export type ProviderAuthStatus = {
 };
 /** 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` — a startup diagnostic. */
+/**
+ * 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);