@fastagent-sh/fastagent 0.24.3 → 0.25.0

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

@@ -2,20 +2,34 @@
  * 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 { InMemoryCredentialStore, } from "@earendil-works/pi-ai";
-import { dirname } from "node:path";
-import { SettingsManager } from "@earendil-works/pi-coding-agent";
-import { fastagentCredentialStore } from "./auth.js";
-import { createPiModelRuntime, interactiveAuth, loginProviders, piModelsOver, probeApiKey } from "./models.js";
-import { agentModels } from "./agent-models.js";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { assertOneCredentialSource, fastagentCredentialStore } from "./credentials.js";
+import { UNNAMED_AUTH_SOURCE, interactiveAuth, loginProviders, modelsOver, probeApiKey } from "./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 {
 }
+/** A sign-in that cannot start as asked: an unknown provider, or a choice a caller without menus did not make. */
+export class LoginRefused extends Error {
+    /** The sign-ins it could be instead, for a caller to choose from. */
+    choices;
+    constructor(message, choices) {
+        super(message);
+        this.choices = choices;
+    }
+}
+const ACCOUNT_LABEL = "Sign in with an account";
+const API_KEY_LABEL = "Sign in with an API key";
 /**
- * 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 function loginOptions(credentials) {
     return loginOptionsOver(credentials);
@@ -27,23 +41,64 @@ 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 storeOf(credentials).list()).map((info) => [info.providerId, info.type]));
+    // The environment alone, over no store: what authenticates a provider nothing is stored for.
+    const environment = modelsOver(new InMemoryCredentialStore(), providers);
     const offered = [];
     for (const provider of loginProviders(providers)) {
-        const methods = ["oauth", "api_key"].filter((method) => interactiveAuth(provider, method));
+        const methods = ["oauth", "api_key"].filter((method) => provider.auth[method === "oauth" ? "oauth" : "apiKey"]);
         if (methods.length === 0)
             continue;
         const stored = held.get(provider.id);
+        let status;
+        let problem;
+        if (stored !== undefined) {
+            status = { type: stored, source: stored === "oauth" ? "OAuth" : "stored credential" };
+        }
+        else {
+            try {
+                const found = await environment.checkAuth(provider.id);
+                if (found !== undefined)
+                    status = { type: found.type, source: found.source ?? UNNAMED_AUTH_SOURCE };
+            }
+            catch (error) {
+                problem = error.message;
+            }
+        }
         for (const method of methods) {
             offered.push({
                 provider: provider.id,
+                name: provider.name,
                 method,
-                label: interactiveAuth(provider, method)?.name ?? provider.name,
+                label: method === "oauth" ? (provider.auth.oauth?.loginLabel ?? ACCOUNT_LABEL) : API_KEY_LABEL,
                 subscription: method === "oauth" && provider.auth.oauth?.isSubscription === true,
-                ...(stored ? { stored } : {}),
+                external: interactiveAuth(provider, method) === undefined,
+                ...(status ? { status } : {}),
+                ...(problem ? { problem } : {}),
             });
         }
     }
-    return offered;
+    return offered.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** What a credential of `type` is called beside a provider's sign-in, as pi's picker calls it. */
+function credentialKind(type, subscription) {
+    if (type === "api_key")
+        return "API key";
+    return subscription ? "subscription" : "account";
+}
+/** An option's status as pi's picker writes it after the provider's name. */
+export function loginStatusText(option) {
+    if (option.problem !== undefined)
+        return `auth check failed: ${option.problem}`;
+    const { status } = option;
+    if (status === undefined)
+        return "not configured";
+    if (status.type !== option.method)
+        return `${credentialKind(status.type, option.subscription)} configured`;
+    if (status.source === "OAuth" || status.source === "stored credential")
+        return "✓ configured";
+    return /^[A-Z][A-Z0-9_]*(?:, [A-Z][A-Z0-9_]*)*$/.test(status.source)
+        ? `✓ env: ${status.source}`
+        : `✓ ${status.source}`;
 }
 /** Combine present abort signals into one (no-op when none/one). */
 function anySignal(...signals) {
@@ -60,7 +115,6 @@ function anySignal(...signals) {
  * 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
@@ -71,8 +125,9 @@ export function login(request) {
 }
 /** {@link login}, plus {@link LoginInternals}. */
 export async function loginOver(request, internals = {}) {
-    const { providers, verifyWith, agentDir } = internals;
+    const { providers, verifyWith } = internals;
     const { method, interaction } = request;
+    assertOneCredentialSource(request);
     if (request.credentialStore === undefined && typeof request.authPath !== "string") {
         throw new Error("login needs authPath or credentialStore: where the sign-in is written");
     }
@@ -85,32 +140,15 @@ export async function loginOver(request, internals = {}) {
     const flow = auth.login.bind(auth);
     // The key under test lives here, not in the file, until it passes.
     const trial = new InMemoryCredentialStore();
-    // Only a key needs the registry, and building an agent's fails on a broken models.json: an OAuth sign-in must not.
-    // For a key it is built BEFORE the flow, so that failure comes before the person types anything.
-    const models = method !== "api_key"
-        ? undefined
-        : agentDir
-            ? await createPiModelRuntime({
-                agentDir,
-                credentials: trial,
-                ...(providers ? { providers: [...providers] } : {}),
-            })
-            : piModelsOver(trial, providers);
-    const store = agentModels(undefined, request).credentials;
+    // Only a key needs the registry: it is checked with one request before it is kept.
+    const models = method === "api_key" ? modelsOver(trial, providers) : undefined;
+    const store = request.credentialStore ?? fastagentCredentialStore(request.authPath);
     await store.modify(provider.id, async () => undefined);
     const signal = interaction.signal ?? new AbortController().signal;
     const notify = (event) => interaction.notify(event);
     let getDeviceId = request.getDeviceId;
     if (method === "oauth" && !getDeviceId && request.authPath !== undefined) {
-        // Only the settings file beside the credentials: no project's `.pi/settings.json` has a say in this write.
-        const settings = SettingsManager.create(dirname(request.authPath), dirname(request.authPath), {
-            projectTrusted: false,
-        });
-        const deviceId = settings.getOrCreateDeviceId();
-        await settings.flush();
-        const errors = settings.drainErrors();
-        if (errors.length)
-            throw new Error(`could not persist login device ID: ${errors.map(({ error }) => error.message).join("; ")}`);
+        const deviceId = await deviceIdBeside(request.authPath);
         getDeviceId = () => deviceId;
     }
     for (;;) {
@@ -129,6 +167,39 @@ export async function loginOver(request, internals = {}) {
         return { provider: provider.id, method, verified };
     }
 }
+/**
+ * The installation's identity, kept beside the credentials file it signs in to: created once, then read. Settled before
+ * the flow runs, so a sign-in never completes with an identity that was not kept.
+ */
+async function deviceIdBeside(authPath) {
+    const path = join(dirname(authPath), "device.json");
+    try {
+        return await readOrCreateDeviceId(path);
+    }
+    catch (error) {
+        throw new Error(`could not persist login device ID in ${path}: ${error.message}`, { cause: error });
+    }
+}
+async function readOrCreateDeviceId(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (text !== undefined) {
+        const stored = JSON.parse(text).deviceId;
+        if (typeof stored !== "string" || stored === "")
+            throw new Error("it holds no deviceId");
+        return stored;
+    }
+    const deviceId = randomUUID();
+    await mkdir(dirname(path), { recursive: true });
+    writeFileAtomic(path, `${JSON.stringify({ deviceId })}\n`);
+    return deviceId;
+}
 async function runFlow(flow, interaction, signal) {
     if (signal.aborted)
         throw new LoginCancelled("cancelled");
@@ -165,10 +236,10 @@ export const PI_DEFAULT_MODELS = {
     "ant-ling": "Ring-2.6-1T",
     anthropic: "claude-opus-4-8",
     openai: "gpt-5.5",
-    "azure-openai-responses": "gpt-5.4",
+    azure: "gpt-5.4",
     "openai-codex": "gpt-6.1-sol",
     radius: "balanced",
-    nvidia: "nvidia/nemotron-3-super-120b-a12b",
+    nvidia: "nvidia/nemotron-3-ultra-550b-a55b",
     deepseek: "deepseek-v4-pro",
     google: "gemini-3.1-pro-preview",
     "google-vertex": "gemini-3.1-pro-preview",
@@ -255,7 +326,11 @@ function terminalInteraction(io, signal) {
                     label: o.label,
                     ...(o.description ? { hint: o.description } : {}),
                 })))
-                : await io.prompt(p.message, { hidden: p.type === "secret", ...(p.signal ? { signal: p.signal } : {}) });
+                : await io.prompt(p.message, {
+                    hidden: p.type === "secret",
+                    redirect: p.type === "manual_code",
+                    ...(p.signal ? { signal: p.signal } : {}),
+                });
             if (v === undefined)
                 throw new LoginCancelled("cancelled");
             return v;
@@ -269,7 +344,7 @@ function terminalInteraction(io, signal) {
             }
             else if (e.type === "device_code") {
                 io.note(`Go to ${e.verificationUri} and enter the code:  ${e.userCode}`);
-                io.openUrl(e.verificationUri);
+                io.openUrl(e.verificationUri, e.userCode);
             }
             else {
                 io.note(e.message);
@@ -277,55 +352,88 @@ function terminalInteraction(io, signal) {
         },
     };
 }
-async function selectMethod(io) {
-    const v = await io.select("Authentication method", [
-        { value: "oauth", label: "Use a subscription (OAuth)" },
-        { value: "api_key", label: "Use an API key" },
-    ]);
-    if (v !== "oauth" && v !== "api_key")
-        throw new LoginCancelled("no authentication method selected");
-    return v;
-}
 /**
- * `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 async function loginFlow(io, options) {
-    const offered = await loginOptionsOver(options.authPath, options.providers);
-    let provider = options.provider;
-    let method = options.method;
-    if (provider) {
-        const methods = offered.filter((o) => o.provider === provider).map((o) => o.method);
-        if (methods.length === 0) {
-            const known = loginProviders(options.providers).some((p) => p.id === provider);
-            throw new Error(known
-                ? `provider "${provider}" has no interactive login — set its API key via the provider's env var`
-                : `unknown provider "${provider}"`);
-        }
-        method ??= methods.length > 1 ? await selectMethod(io) : methods[0];
-    }
-    else {
-        const chosenMethod = method ?? (await selectMethod(io));
-        method = chosenMethod;
-        const candidates = offered.filter((o) => o.method === chosenMethod);
-        if (candidates.length === 0)
-            throw new Error(`no provider supports ${chosenMethod} login`);
-        provider = await io.select("Select a provider", candidates.map((o) => ({
-            value: o.provider,
-            label: o.label,
-            ...(o.stored ? { hint: `configured (${o.stored})` } : {}),
-        })));
-        if (!candidates.some((o) => o.provider === provider))
-            throw new LoginCancelled("no provider selected");
+    const offered = await loginOptionsOver(options.statusFrom ?? options.authPath, options.providers);
+    const choice = await chooseLogin(offered, options, io);
+    if (choice.external) {
+        throw new LoginRefused(`${choice.name} is configured outside fastagent: set its key in the environment`, []);
     }
     return loginOver({
-        provider: provider,
-        method: method,
+        provider: choice.provider,
+        method: choice.method,
         authPath: options.authPath,
         interaction: terminalInteraction(io, options.signal),
     }, {
         ...(options.providers ? { providers: options.providers } : {}),
         ...(options.verifyWith ? { verifyWith: options.verifyWith } : {}),
-        ...(options.agentDir ? { agentDir: options.agentDir } : {}),
     });
 }
+/** The flag that gives a method, as a refusal names it. */
+const METHOD_FLAGS = "--method account or --method api-key";
+/**
+ * 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 async function chooseLogin(offered, given, menus) {
+    const picked = async (message, options, from, by) => {
+        const value = await menus.select(message, options);
+        const option = from.find((o) => by(o) === value);
+        if (option === undefined)
+            throw new LoginCancelled("nothing selected");
+        return option;
+    };
+    if (given.provider !== undefined) {
+        const named = given.provider.trim().toLowerCase();
+        const ofProvider = offered.filter((o) => o.provider.toLowerCase() === named || o.name.toLowerCase() === named);
+        if (ofProvider.length === 0) {
+            throw new LoginRefused(`unknown provider "${given.provider}": ${providerIds(offered)}`, offered);
+        }
+        const name = ofProvider[0].name;
+        const ofMethod = given.method === undefined ? ofProvider : ofProvider.filter((o) => o.method === given.method);
+        if (ofMethod.length === 0) {
+            const only = ofProvider[0].method === "oauth" ? "an account" : "an API key";
+            throw new LoginRefused(`${name} signs in only with ${only}`, ofProvider);
+        }
+        if (ofMethod.length === 1)
+            return ofMethod[0];
+        if (menus === undefined)
+            throw new LoginRefused(`${name} signs in with an account or an API key: pass ${METHOD_FLAGS}`, ofMethod);
+        return picked(`Select authentication method for ${name}:`, ofMethod.map((o) => ({ value: o.method, label: o.label })), ofMethod, (o) => o.method);
+    }
+    if (menus === undefined) {
+        throw new LoginRefused(`name the provider to sign in to (${providerIds(offered)}), and ${METHOD_FLAGS} for one that offers both`, given.method === undefined ? offered : offered.filter((o) => o.method === given.method));
+    }
+    let method = given.method;
+    if (method === undefined) {
+        // pi offers its own gateway beside the two ways of signing in.
+        const radius = offered.find((o) => o.provider === "radius" && o.method === "oauth");
+        const ways = [
+            ...(offered.some((o) => o.method === "oauth") ? [{ value: "oauth", label: ACCOUNT_LABEL }] : []),
+            ...(offered.some((o) => o.method === "api_key") ? [{ value: "api_key", label: API_KEY_LABEL }] : []),
+            ...(radius ? [{ value: "radius", label: `Sign in with ${radius.name}${statusSuffix(radius)}` }] : []),
+        ];
+        const way = await menus.select("Select authentication method:", ways);
+        if (way === "radius" && radius)
+            return radius;
+        if (way !== "oauth" && way !== "api_key")
+            throw new LoginCancelled("no authentication method selected");
+        method = way;
+    }
+    const candidates = offered.filter((o) => o.method === method);
+    if (candidates.length === 0)
+        throw new LoginRefused(`no provider signs in with ${method === "oauth" ? "an account" : "an API key"}`, []);
+    return picked("Select provider to configure:", candidates.map((o) => ({ value: o.provider, label: `${o.name}${statusSuffix(o)}` })), candidates, (o) => o.provider);
+}
+/** An option's status after its name on every row, as pi's picker writes it: ` ✓ configured`, ` • not configured`. */
+function statusSuffix(option) {
+    const text = loginStatusText(option);
+    return text.startsWith("✓") ? ` ${text}` : ` • ${text}`;
+}
+/** Every provider id a sign-in can name, for a refusal that must say which. */
+function providerIds(offered) {
+    return `one of ${[...new Set(offered.map((o) => o.provider))].sort().join(", ")}`;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * 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. 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): 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,158 @@
+/**
+ * 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();
+}
+/**
+ * The built-ins plus `providers` (a same id replaces a built-in), over any credential store. 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) {
+    const models = createModels({
+        credentials,
+        authContext: defaultProviderAuthContext(),
+        ...(catalogs ? { modelsStore: catalogs.fetched } : {}),
+    });
+    for (const builtIn of builtinProviders())
+        models.setProvider(catalogs ? catalogs.over(builtIn) : builtIn);
+    for (const provider of providers)
+        models.setProvider(provider);
+    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: {
+            // pi's own reading of a variable (a blank one is unset), over the given environment.
+            env: async (name) => (env[name]?.trim() ? env[name] : undefined),
+            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>;