@fastagent-sh/fastagent 0.24.3 → 0.25.0

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,43 @@
+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. The model lists
+ * are refreshed before it resolves, kept in the agent's state root; `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;
+}): Promise<ModelEnvironment>;
+export {};

package/dist/harnesses/models/environment.js

@@ -0,0 +1,82 @@
+/**
+ * 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. The model lists
+ * are refreshed before it resolves, kept in the agent's state root; `force` asks the network even when they are fresh.
+ */
+export async function modelEnvironment(agentDir, source = {}, providers = [], options = {}) {
+    assertOneCredentialSource(source);
+    const files = source.credentialStore
+        ? undefined
+        : agentDir
+            ? resolveAuthLayers(agentDir, source.authPath)
+            : { path: source.authPath ?? GLOBAL_AUTH_PATH };
+    const store = files === undefined ? undefined : layeredStore(files, providers, source.warn);
+    const credentials = source.credentialStore ?? store;
+    const catalogs = catalogsIn(agentDir === undefined ? undefined : join(resolveStateRoot(agentDir), "models"));
+    const models = modelsOver(credentials, providers, catalogs);
+    const catalogProblem = await catalogs.refresh(models, options);
+    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, process.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) {
+    const own = () => fastagentCredentialStore(auth.path, { ...(warn ? { warn } : {}) });
+    if (auth.fallback === undefined)
+        return own();
+    const project = modelsOver(own(), providers);
+    return fastagentCredentialStore(auth.path, {
+        ...(warn ? { warn } : {}),
+        fallbackPath: auth.fallback,
+        projectAuthenticates: async (providerId) => (await project.checkAuth(providerId)) !== undefined,
+    });
+}

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

@@ -2,39 +2,59 @@
  * Signing in to a MODEL PROVIDER, for any front end: {@link login} runs one provider's flow over pi-ai's own
  * `AuthInteraction` and persists the credential through the same {@link fastagentCredentialStore} the runtime reads
  * (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.
+ * one front end ({@link loginFlow}: terminal menus, then {@link login}); `login --deployment` drives the same flow on a
+ * deployed box over a relay (cli/login-relay.ts).
  */
 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 {
 }
-/** One provider sign-in a picker can offer. */
+/** A sign-in that cannot start as asked: an unknown provider, or a choice a caller without menus did not make. */
+export declare class LoginRefused extends Error {
+    /** The sign-ins it could be instead, for a caller to choose from. */
+    readonly choices: readonly LoginOption[];
+    constructor(message: string, choices: readonly LoginOption[]);
+}
+/** One provider sign-in a picker can offer, as pi's `/login` offers it. */
 export interface LoginOption {
     provider: string;
+    /** The provider's name, as pi lists it: "OpenAI", "OpenAI Codex (legacy)". */
+    name: string;
     method: LoginMethod;
-    /** The method's own name, e.g. "Anthropic (Claude Pro/Max)" or "Anthropic API key". */
+    /** What signing in this way is called: the provider's own label ("Sign in with ChatGPT"), else pi's. */
     label: string;
     /** An OAuth login backed by a provider subscription. */
     subscription: boolean;
+    /** Its key comes from the environment, never from a sign-in: picking it says so. */
+    external: boolean;
     /**
-     * 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.
+     * What authenticates the provider now: the kind of credential, and `OAuth`, `stored credential` or an env variable
+     * such as `OPENAI_API_KEY`. The store keeps ONE credential per provider, so signing in with the other method
+     * replaces a stored one, which a picker shows.
      */
-    stored?: LoginMethod;
+    status?: {
+        type: LoginMethod;
+        source: string;
+    };
+    /** Why checking what authenticates it failed, when it did. */
+    problem?: string;
 }
 /**
- * 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.
+ * Every sign-in of pi's built-in providers, sorted by name as pi's `/login` lists them, with what authenticates each
+ * one here: a credential `credentials` (a credentials file, or the caller's own store) holds, else this process's
+ * environment, which a stored credential outranks.
  */
 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(credentials: string | CredentialStore, providers?: readonly Provider[]): Promise<LoginOption[]>;
+/** An option's status as pi's picker writes it after the provider's name. */
+export declare function loginStatusText(option: LoginOption): string;
 export type LoginRequest = {
     /**
-     * Stable installation identity (Sign in with ChatGPT requires one). With `authPath` it defaults to Pi settings
-     * beside that file (`settings.json`, written before the flow runs); over a caller's `credentialStore` there is no
-     * file to keep it beside, so a flow that needs one fails unless this supplies it.
+     * Stable installation identity (Sign in with ChatGPT requires one). With `authPath` it defaults to `device.json`
+     * beside that file, written before the flow runs; over a caller's `credentialStore` there is no file to keep it
+     * beside, so a flow that needs one fails unless this supplies it.
      */
     getDeviceId?: () => string;
     provider: string;
@@ -66,7 +86,6 @@ export interface LoginResult {
  * 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
  * again (the provider and method were not the mistake). Progress and outcome go out through `interaction.notify`.
- * A provider an agent's models.json points elsewhere is not this call's: store that key with `fastagentCredentialStore`.
  *
  * Aborting `interaction.signal` at any point, the verification included, rejects with {@link LoginCancelled} and
  * writes no credential (an OAuth device ID, the installation's identity, is kept once created). Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
@@ -75,14 +94,11 @@ export interface LoginResult {
 export declare function login(request: LoginRequest): Promise<LoginResult>;
 /** Not public: what the CLI and the tests add to {@link login}. */
 export interface LoginInternals {
-    /** Providers added to pi's built-ins (a same id replaces one): a test seam. */
-    providers?: readonly Provider[];
     /**
-     * The agent the key is for. Verification then runs on THAT agent's registry (its models.json and the machine's over
-     * the built-ins), so the check reaches the endpoint its turns will: a models.json can point a built-in provider at a
-     * gateway, where the provider's own endpoint would refuse the gateway's key and loop the person through re-entry.
+     * The definition's providers, added to pi's built-ins (a same id replaces one): a key is verified against the
+     * endpoint its turns will reach, which a provider in code can point at a gateway.
      */
-    agentDir?: string;
+    providers?: readonly Provider[];
     /**
      * A model spec to verify an entered key with, when the registry has it as one of this provider's models: the
      * first-run picker's choice, the request the agent is about to make. Otherwise pi's default model for the provider
@@ -108,28 +124,43 @@ export interface IoOption {
 export interface LoginIO {
     /** Single-choice picker. */
     select(message: string, options: IoOption[]): Promise<string | undefined>;
-    /** Free-text or hidden input. */
+    /**
+     * Free-text or hidden input. `redirect`: what is asked is the address the browser ended on after signing in, or the
+     * code its page showed (pi-ai's `manual_code`).
+     */
     prompt(message: string, opts?: {
         hidden?: boolean;
+        redirect?: boolean;
         signal?: AbortSignal;
     }): Promise<string | undefined>;
     /** Print an informational line (auth URL, device code, progress). */
     note(message: string): void;
-    /** Best-effort open a URL in the browser (printed regardless). */
-    openUrl(url: string): void;
+    /** Best-effort open a URL in the browser (printed regardless); `userCode` is what a device sign-in enters there. */
+    openUrl(url: string, userCode?: string): void;
 }
 /**
- * `fastagent login`: ask only what was not given (method, then provider, from {@link loginOptions} with each one's
- * stored credential), then {@link login}.
+ * `fastagent login` in a terminal: ask only what was not given, as pi's `/login` asks it (how to sign in, then the
+ * provider; a provider named by its id or its name, then how, when it offers both), then {@link login}.
  */
 export declare function loginFlow(io: LoginIO, options: {
     authPath: string;
     provider?: string;
     method?: LoginMethod;
-    providers?: Provider[];
+    providers?: readonly Provider[];
     signal?: AbortSignal;
+    /**
+     * Where the menus read what authenticates each provider now: the credentials the agent reads (its file over the
+     * global one), which can hold more than the file a sign-in writes. Default that file.
+     */
+    statusFrom?: CredentialStore;
     /** {@link LoginInternals.verifyWith}. */
     verifyWith?: string;
-    /** {@link LoginInternals.agentDir}. */
-    agentDir?: string;
 }): Promise<LoginResult>;
+/**
+ * The sign-in `given` names, or, with `menus`, the one a person picks; without them a choice not given refuses
+ * ({@link LoginRefused}) naming how to give it.
+ */
+export declare function chooseLogin(offered: readonly LoginOption[], given: {
+    provider?: string;
+    method?: LoginMethod;
+}, menus: LoginIO | undefined): Promise<LoginOption>;