@fastagent-sh/fastagent 0.25.0 → 0.26.0

package/dist/environment/mise.js

@@ -15,7 +15,7 @@ import { loadEnvironment } from "../content/file.js";
 import { log } from "../log.js";
 import { detectRuntime, listsFastagent, readPackageJson } from "../runtime.js";
 import { aptAdvice, missingAptPackages } from "./apt.js";
-import { missingPythonRuntime, resolvedBackendRefusal, writtenBackend, } from "./declare.js";
+import { missingPythonRuntime, resolvedBackendRefusal, writtenBackend } from "./declare.js";
 /** mise's npm package for each platform it publishes one for, by Node's `${platform}-${arch}`. */
 const MISE_PACKAGES = {
     "darwin-arm64": "@jdxcode/mise-darwin-arm64",
@@ -77,14 +77,15 @@ function specOf(name, packages) {
     return `${name}@${packages[name]}`;
 }
 /**
- * Run the agent's mise with `args` in `cwd`. Its errors go to this process's stderr unless `quiet` keeps them for
- * the error, which then says what mise said; `capture` returns its stdout instead of passing it through.
+ * Run the agent's mise with `args` in `cwd`, in `env` (this process's by default). Its errors go to this process's
+ * stderr unless `quiet` keeps them for the error, which then says what mise said; `capture` returns its stdout instead
+ * of passing it through.
  */
 function runMise(cwd, bin, args, options = {}) {
     return new Promise((done, fail) => {
         const child = spawn(bin, args, {
             cwd,
-            env: { ...process.env, ...MISE_ENVIRONMENT },
+            env: { ...(options.env ?? process.env), ...MISE_ENVIRONMENT },
             stdio: ["inherit", options.capture ? "pipe" : process.stderr, options.quiet ? "pipe" : "inherit"],
         });
         let stdout = "";
@@ -175,14 +176,14 @@ export async function checkPackages(agentDir, bin, packages) {
  * so a start whose packages are installed needs no network and keeps the versions it has. An install that matches may
  * be another project's: mise's data directory is the machine's.
  */
-export async function installPackages(agentDir, bin, packages, newest = []) {
+export async function installPackages(agentDir, bin, packages, newest = [], env = process.env) {
     const names = Object.keys(packages);
     const asked = names.filter((name) => newest === "all" || newest.includes(name));
     const others = names.filter((name) => !asked.includes(name));
     const installed = await Promise.all(
     // A failed `where` is what mise says of a package with no install here; the install that follows reports any other
     // reason it cannot be had.
-    others.map((name) => runMise(agentDir, bin, ["where", specOf(name, packages)], { capture: true, quiet: true }).then(() => true, () => false)));
+    others.map((name) => runMise(agentDir, bin, ["where", specOf(name, packages)], { capture: true, quiet: true, env }).then(() => true, () => false)));
     const present = new Set(others.filter((_, i) => installed[i]));
     const wanted = names.filter((name) => !present.has(name)).map((name) => specOf(name, packages));
     if (wanted.length === 0)
@@ -190,11 +191,14 @@ export async function installPackages(agentDir, bin, packages, newest = []) {
     const installedSpecs = [...present].map((name) => specOf(name, packages));
     // A package installs with the ones it needs (a PyPI one runs uv), which mise finds in the packages it is given or on
     // the PATH. The installed ones go on the PATH: given as packages, mise would install a newer release of them.
-    await runInstall(agentDir, bin, wanted, installedSpecs.length > 0 ? await packagesEnvironment(agentDir, bin, installedSpecs) : {});
+    await runInstall(agentDir, bin, wanted, {
+        ...env,
+        ...(installedSpecs.length > 0 ? await packagesEnvironment(agentDir, bin, installedSpecs, env) : {}),
+    });
 }
 /** What `mise env` puts in a process's environment for `specs`: the PATH their commands are on. */
-async function packagesEnvironment(agentDir, bin, specs) {
-    return JSON.parse(await runMise(agentDir, bin, ["env", "--json", ...specs], { capture: true }));
+async function packagesEnvironment(agentDir, bin, specs, env) {
+    return JSON.parse(await runMise(agentDir, bin, ["env", "--json", ...specs], { capture: true, env }));
 }
 /**
  * The notice mise prints after installing a package no configuration file names, with the `mise use` it suggests: not
@@ -202,7 +206,7 @@ async function packagesEnvironment(agentDir, bin, specs) {
  */
 const NOT_ACTIVATED = /installed but not activated|^To install and activate, run:|^\s+mise use /;
 /**
- * `mise install` of `specs`, with `env` added to its environment. Its progress is passed on to this process's stderr as
+ * `mise install` of `specs`, in `env`. Its progress is passed on to this process's stderr as
  * it comes, so a runtime that takes minutes is seen to; a failure carries what mise said, every line of it, since
  * mise names the packages on its first line and the reason (a 404, a proxy, a rate limit) on the lines after.
  */
@@ -211,7 +215,7 @@ function runInstall(agentDir, bin, specs, env) {
     return new Promise((done, fail) => {
         const child = spawn(bin, ["install", ...specs], {
             cwd: agentDir,
-            env: { ...process.env, ...env, ...MISE_ENVIRONMENT },
+            env: { ...env, ...MISE_ENVIRONMENT },
             stdio: ["inherit", process.stderr, "pipe"],
         });
         const said = [];
@@ -246,23 +250,23 @@ function missingMise(agentDir) {
     return new Error(`context.json declares packages, and the agent has no mise installed — run \`fastagent env install\` in ${agentDir}`);
 }
 /**
- * Enter the agent's environment, for a process that runs it: install the declared packages that have no install here
- * yet, and put them first on this process's PATH, which every command the agent runs inherits. mise itself is not put
- * on the PATH. An agent without packages borrows the machine's commands. Apt packages are the image's to install; one
- * missing here is said, with how.
+ * The agent's declared environment, for a process that runs it: install the declared packages that have no install
+ * here yet, and answer the variables that put them first on the PATH of the commands the agent runs. mise runs in
+ * `env`, the agent's environment so far, and nothing is written into this process's: a process may run several agents.
+ * mise itself is not put on the PATH. An agent without packages borrows the machine's commands (no variables). Apt
+ * packages are the image's to install; one missing here is said, with how.
  */
-export async function enterEnvironment(agentDir) {
+export async function prepareEnvironment(agentDir, env) {
     const declared = loadEnvironment(agentDir);
     const missingApt = missingAptPackages(declared?.aptPackages ?? []);
     if (missingApt && missingApt.length > 0)
         log.warn(`[fastagent] ${aptAdvice(missingApt)}`);
     const packages = declared?.packages ?? {};
     if (Object.keys(packages).length === 0)
-        return declared;
+        return {};
     const bin = miseBinary(agentDir);
     if (!bin)
         throw missingMise(agentDir);
-    await installPackages(agentDir, bin, packages);
-    Object.assign(process.env, await packagesEnvironment(agentDir, bin, packageSpecs(packages)));
-    return declared;
+    await installPackages(agentDir, bin, packages, [], env);
+    return packagesEnvironment(agentDir, bin, packageSpecs(packages), env);
 }

package/dist/git.d.ts

@@ -1,8 +1,8 @@
 /** git is not on the PATH. Its message names what needed it: `git is not installed: <why>`. */
 export declare class GitNotInstalled extends Error {
 }
-/** git for one purpose, `why`: what a missing git is reported as needed for. */
-export declare function gitFor(why: string): {
+/** git for one purpose, `why`: what a missing git is reported as needed for. It runs in `env`. */
+export declare function gitFor(why: string, env?: NodeJS.ProcessEnv): {
     /**
      * git's answer in `cwd` (which must exist), or undefined when it answers with a non-zero exit. A git that cannot
      * run is an error.

package/dist/git.js

@@ -12,10 +12,10 @@ export class GitNotInstalled extends Error {
  * Never wait on a terminal prompt for a credential: a serving process has nobody to answer it, so git fails and says
  * why instead. Not covered by a test: it takes a remote that asks for a credential.
  */
-const gitEnv = () => ({ ...process.env, GIT_TERMINAL_PROMPT: "0" });
+const gitEnv = (env) => ({ ...env, GIT_TERMINAL_PROMPT: "0" });
 const execGit = promisify(execFile);
-/** git for one purpose, `why`: what a missing git is reported as needed for. */
-export function gitFor(why) {
+/** git for one purpose, `why`: what a missing git is reported as needed for. It runs in `env`. */
+export function gitFor(why, env = process.env) {
     const missing = () => new GitNotInstalled(`git is not installed: ${why}`);
     return {
         /**
@@ -26,7 +26,7 @@ export function gitFor(why) {
             try {
                 return execFileSync("git", args, {
                     cwd,
-                    env: gitEnv(),
+                    env: gitEnv(env),
                     encoding: "utf8",
                     stdio: ["ignore", "pipe", "pipe"],
                 }).trim();
@@ -42,7 +42,7 @@ export function gitFor(why) {
         /** Run git in `cwd`: its output, or its stderr as the error. */
         async run(args, cwd) {
             try {
-                return (await execGit("git", args, { cwd, env: gitEnv() })).stdout;
+                return (await execGit("git", args, { cwd, env: gitEnv(env) })).stdout;
             }
             catch (error) {
                 if (error.code === "ENOENT")

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

@@ -34,10 +34,15 @@ export interface ModelEnvironment {
 /**
  * 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.
+ * ({@link resolveAuthLayers}), or the named file, or the global one. `providers` are the definition's. `environment` is
+ * what the agent's environment adds to this process's: its keys, the requests' settings, and where its files are
+ * (`FASTAGENT_AUTH_PATH`, `FASTAGENT_STATE_DIR`) are all read there first. The model lists are refreshed before it
+ * resolves, kept in the instance's state root (`stateRoot`, else the directory's); `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;
+    stateRoot?: string;
+    environment?: Readonly<Record<string, string>>;
 }): Promise<ModelEnvironment>;
 export {};

package/dist/harnesses/models/environment.js

@@ -14,21 +14,27 @@ 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.
+ * ({@link resolveAuthLayers}), or the named file, or the global one. `providers` are the definition's. `environment` is
+ * what the agent's environment adds to this process's: its keys, the requests' settings, and where its files are
+ * (`FASTAGENT_AUTH_PATH`, `FASTAGENT_STATE_DIR`) are all read there first. The model lists are refreshed before it
+ * resolves, kept in the instance's state root (`stateRoot`, else the directory's); `force` asks the network even when
+ * they are fresh.
  */
 export async function modelEnvironment(agentDir, source = {}, providers = [], options = {}) {
+    const environment = options.environment ?? {};
+    const env = { ...process.env, ...environment };
     assertOneCredentialSource(source);
     const files = source.credentialStore
         ? undefined
         : agentDir
-            ? resolveAuthLayers(agentDir, source.authPath)
+            ? resolveAuthLayers(agentDir, source.authPath, env)
             : { path: source.authPath ?? GLOBAL_AUTH_PATH };
-    const store = files === undefined ? undefined : layeredStore(files, providers, source.warn);
+    const store = files === undefined ? undefined : layeredStore(files, providers, source.warn, environment);
     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);
+    const stateRoot = options.stateRoot ?? (agentDir === undefined ? undefined : resolveStateRoot(agentDir, env));
+    const catalogs = catalogsIn(stateRoot === undefined ? undefined : join(stateRoot, "models"));
+    const models = modelsOver(credentials, providers, catalogs, environment);
+    const catalogProblem = await catalogs.refresh(models, { force: options.force === true });
     if (catalogProblem !== undefined)
         log.warn(`[fastagent] ${catalogProblem}`);
     return {
@@ -52,7 +58,7 @@ export async function modelEnvironment(agentDir, source = {}, providers = [], op
             }
             // `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 fromEnvironment = stored === undefined ? undefined : (await environmentAuth(provider, env, undefined, providers))?.source;
             const shadowed = resolved.source !== undefined && fromEnvironment !== resolved.source ? fromEnvironment : undefined;
             return {
                 ...(store ? { path: await store.layerOf(provider) } : {}),
@@ -69,11 +75,11 @@ export async function modelEnvironment(agentDir, source = {}, providers = [], op
  * 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) {
+function layeredStore(auth, providers, warn, environment) {
     const own = () => fastagentCredentialStore(auth.path, { ...(warn ? { warn } : {}) });
     if (auth.fallback === undefined)
         return own();
-    const project = modelsOver(own(), providers);
+    const project = modelsOver(own(), providers, undefined, environment);
     return fastagentCredentialStore(auth.path, {
         ...(warn ? { warn } : {}),
         fallbackPath: auth.fallback,

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

@@ -0,0 +1,30 @@
+/**
+ * What an embedding host calls for model credentials (sign-in-api.ts has the types): a store kept where the host
+ * chooses, a sign-in in its own UI, and what authenticates a provider. Thin over what `fastagent login`, `logout` and
+ * `auth check` run, so each rule keeps one implementation. The one translation between FastAgent's types and pi-ai's
+ * is here, written without casts and with every function checked as a function, so it stops compiling when the two
+ * drift apart.
+ */
+import type { CredentialStore as PiCredentialStore } from "@earendil-works/pi-ai";
+import type { CredentialStore, ProviderAuth, SignInOption, SignInRequest, SignInResult } from "../../sign-in-api.ts";
+/**
+ * FastAgent's locked JSON credentials file at `path` (`~` is the home directory, a relative one resolves against the
+ * working directory now). A corrupt or unreadable file rejects every call.
+ */
+export declare function credentialFile(path: string): CredentialStore;
+/** A host's store as pi-ai reads it. */
+export declare function piCredentials(store: CredentialStore): PiCredentialStore;
+/** Every sign-in of the built-in providers, by name, with what authenticates each one now. */
+export declare function signInOptions(credentials: CredentialStore): Promise<SignInOption[]>;
+/**
+ * Sign in to a built-in provider and store the credential. The store is written to first, so a sign-in never runs
+ * toward a store that refuses it; an API key is checked with one request before it is stored, and one the provider
+ * rejects is asked for again. Aborting the interaction's signal rejects with `SignInCancelled` and stores nothing.
+ */
+export declare function signIn(request: SignInRequest): Promise<SignInResult>;
+/**
+ * What a request to a built-in provider authenticates with, resolved as a message resolves it: a stored credential
+ * (refreshing an OAuth token that is due, through the store's `modify`), else the environment. Undefined when nothing
+ * does; rejects when resolving fails, such as a refresh the provider refused.
+ */
+export declare function providerAuth(credentials: CredentialStore, provider: string): Promise<ProviderAuth | undefined>;

package/dist/harnesses/models/host.js

@@ -0,0 +1,97 @@
+import { resolveOverridePath } from "../../paths.js";
+import { fastagentCredentialStore } from "./credentials.js";
+import { loginOptionsOver, loginOver } from "./login.js";
+import { modelsOver } from "./models.js";
+/** The file behind each store {@link credentialFile} made: a sign-in keeps the installation's id beside it. */
+const files = new WeakMap();
+/**
+ * FastAgent's locked JSON credentials file at `path` (`~` is the home directory, a relative one resolves against the
+ * working directory now). A corrupt or unreadable file rejects every call.
+ */
+export function credentialFile(path) {
+    // Resolved once, so the credentials and the installation's id beside them stay in one directory.
+    const resolved = resolveOverridePath(path);
+    if (resolved === undefined)
+        throw new Error("credentialFile needs the path of a credentials file");
+    const file = fastagentCredentialStore(resolved, {
+        warn: (message) => {
+            throw new Error(message);
+        },
+    });
+    const store = {
+        read: (provider) => file.read(provider),
+        list: async () => (await file.list()).map(({ providerId, type }) => ({ provider: providerId, type })),
+        modify: (provider, change) => file.modify(provider, change),
+        delete: (provider) => file.delete(provider),
+    };
+    files.set(store, resolved);
+    return store;
+}
+/** A host's store as pi-ai reads it. */
+export function piCredentials(store) {
+    return {
+        read: (provider) => store.read(provider),
+        list: async () => (await store.list()).map(({ provider, type }) => ({ providerId: provider, type })),
+        modify: (provider, change) => store.modify(provider, change),
+        delete: (provider) => store.delete(provider),
+    };
+}
+/**
+ * A host's interaction as pi-ai drives it. Arrow functions, not the object as it is: both declare `prompt` and
+ * `notify` as methods, whose parameters TypeScript checks in either direction, so a kind of prompt or event pi-ai adds
+ * would pass unseen; a call checks it.
+ */
+function piInteraction(interaction) {
+    return {
+        ...(interaction.signal === undefined ? {} : { signal: interaction.signal }),
+        prompt: (prompt) => interaction.prompt(prompt),
+        notify: (event) => interaction.notify(event),
+    };
+}
+/** Every sign-in of the built-in providers, by name, with what authenticates each one now. */
+export function signInOptions(credentials) {
+    return loginOptionsOver(piCredentials(credentials));
+}
+/**
+ * Sign in to a built-in provider and store the credential. The store is written to first, so a sign-in never runs
+ * toward a store that refuses it; an API key is checked with one request before it is stored, and one the provider
+ * rejects is asked for again. Aborting the interaction's signal rejects with `SignInCancelled` and stores nothing.
+ */
+export function signIn(request) {
+    const { credentials, provider, method, interaction, deviceId } = request;
+    const file = files.get(credentials);
+    return loginOver({
+        provider,
+        method,
+        interaction: piInteraction(interaction),
+        ...(file === undefined ? { credentialStore: piCredentials(credentials) } : { authPath: file }),
+        ...(deviceId === undefined ? {} : { getDeviceId: () => deviceId }),
+    });
+}
+/**
+ * What a request to a built-in provider authenticates with, resolved as a message resolves it: a stored credential
+ * (refreshing an OAuth token that is due, through the store's `modify`), else the environment. Undefined when nothing
+ * does; rejects when resolving fails, such as a refresh the provider refused.
+ */
+export async function providerAuth(credentials, provider) {
+    const models = modelsOver(piCredentials(credentials));
+    if (models.getProvider(provider) === undefined)
+        throw new Error(`unknown provider "${provider}"`);
+    const checked = await models.checkAuth(provider);
+    if (checked === undefined)
+        return undefined;
+    const resolved = await models.getAuth(provider);
+    if (resolved === undefined)
+        return undefined;
+    const source = resolved.source ?? checked.source;
+    const { apiKey, baseUrl } = resolved.auth;
+    // pi's null header is one a request leaves out, which is what a header not given does.
+    const headers = Object.entries(resolved.auth.headers ?? {}).flatMap(([name, value]) => value === null ? [] : [[name, value]]);
+    return {
+        type: checked.type,
+        ...(source === undefined ? {} : { source }),
+        ...(apiKey === undefined ? {} : { apiKey }),
+        ...(headers.length === 0 ? {} : { headers: Object.fromEntries(headers) }),
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+    };
+}

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

@@ -1,55 +1,27 @@
 /**
- * Signing in to a MODEL PROVIDER, for any front end: {@link login} runs one provider's flow over pi-ai's own
+ * Signing in to a MODEL PROVIDER, for any front end: {@link loginOver} 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}); `login --deployment` drives the same flow on a
- * deployed box over a relay (cli/login-relay.ts).
+ * (one writer, one lock/corruption semantics); {@link loginOptionsOver} is the list a picker offers. An embedding host
+ * reaches both through host.ts (`signIn`, `signInOptions`); `fastagent login` is a front end of its own
+ * ({@link loginFlow}: terminal menus, then {@link loginOver}); `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 {
-}
+import { type SignInMethod, type SignInOption, type SignInResult } from "../../sign-in-api.ts";
 /** 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;
-    /** 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 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.
-     */
-    status?: {
-        type: LoginMethod;
-        source: string;
-    };
-    /** Why checking what authenticates it failed, when it did. */
-    problem?: string;
+    readonly choices: readonly SignInOption[];
+    constructor(message: string, choices: readonly SignInOption[]);
 }
 /**
- * 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.
+ * Every sign-in of pi's built-in providers plus `providers` (a same id replaces one), sorted by name as pi's `/login`
+ * lists them, with what authenticates each one here: a credential `credentials` (a credentials file, or a 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[]>;
+export declare function loginOptionsOver(credentials: string | CredentialStore, providers?: readonly Provider[]): Promise<SignInOption[]>;
 /** An option's status as pi's picker writes it after the provider's name. */
-export declare function loginStatusText(option: LoginOption): string;
+export declare function loginStatusText(option: SignInOption): string;
 export type LoginRequest = {
     /**
      * Stable installation identity (Sign in with ChatGPT requires one). With `authPath` it defaults to `device.json`
@@ -58,7 +30,7 @@ export type LoginRequest = {
      */
     getDeviceId?: () => string;
     provider: string;
-    method: LoginMethod;
+    method: SignInMethod;
     /** pi-ai's own interaction: prompts (`text`, `secret`, `select`, `manual_code`) and events (`auth_url`, …). */
     interaction: AuthInteraction;
 } & ({
@@ -70,29 +42,7 @@ export type LoginRequest = {
     credentialStore: CredentialStore;
     authPath?: never;
 });
-export interface LoginResult {
-    provider: string;
-    method: LoginMethod;
-    /** An API key checked with one minimal request: accepted, or not decidable (kept). OAuth needs no check. */
-    verified: "ok" | "unknown" | "n/a";
-}
-/**
- * Sign in to one of pi's built-in providers and persist the credential to `authPath`, or to the caller's
- * `credentialStore`.
- *
- * 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
- * again (the provider and method were not the mistake). Progress and outcome go out through `interaction.notify`.
- *
- * 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
- * beating a `manual_code` prompt), and when the flow settles with a prompt still pending.
- */
-export declare function login(request: LoginRequest): Promise<LoginResult>;
-/** Not public: what the CLI and the tests add to {@link login}. */
+/** What the CLI adds to a sign-in. */
 export interface LoginInternals {
     /**
      * The definition's providers, added to pi's built-ins (a same id replaces one): a key is verified against the
@@ -106,8 +56,23 @@ export interface LoginInternals {
      */
     verifyWith?: string;
 }
-/** {@link login}, plus {@link LoginInternals}. */
-export declare function loginOver(request: LoginRequest, internals?: LoginInternals): Promise<LoginResult>;
+/**
+ * Sign in to one of pi's built-in providers (plus the definition's) and persist the credential to `authPath`, or to
+ * the caller's `credentialStore`.
+ *
+ * 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
+ * again (the provider and method were not the mistake). Progress and outcome go out through `interaction.notify`.
+ *
+ * Aborting `interaction.signal` at any point, the verification included, rejects with {@link SignInCancelled} 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 beating a `manual_code` prompt), and when the
+ * flow settles with a prompt still pending.
+ */
+export declare function loginOver(request: LoginRequest, internals?: LoginInternals): Promise<SignInResult>;
 /**
  * pi's default model per provider (`defaultModelPerProvider` in pi-coding-agent's model-resolver): the general-purpose
  * model pi itself starts on, so the likeliest to answer a minimal request. COPIED, because pi does not export it;
@@ -140,12 +105,12 @@ export interface LoginIO {
 }
 /**
  * `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}.
+ * provider; a provider named by its id or its name, then how, when it offers both), then {@link loginOver}.
  */
 export declare function loginFlow(io: LoginIO, options: {
     authPath: string;
     provider?: string;
-    method?: LoginMethod;
+    method?: SignInMethod;
     providers?: readonly Provider[];
     signal?: AbortSignal;
     /**
@@ -155,12 +120,12 @@ export declare function loginFlow(io: LoginIO, options: {
     statusFrom?: CredentialStore;
     /** {@link LoginInternals.verifyWith}. */
     verifyWith?: string;
-}): Promise<LoginResult>;
+}): Promise<SignInResult>;
 /**
  * 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: {
+export declare function chooseLogin(offered: readonly SignInOption[], given: {
     provider?: string;
-    method?: LoginMethod;
-}, menus: LoginIO | undefined): Promise<LoginOption>;
+    method?: SignInMethod;
+}, menus: LoginIO | undefined): Promise<SignInOption>;