@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/accounts/accounts.d.ts

@@ -0,0 +1,165 @@
+import type { ModelRuntime } from '@earendil-works/pi-coding-agent';
+import { type Bus } from "../core/bus.js";
+import type { RunEvent, RunRecord } from "../sessions/contracts.js";
+import * as choices from "./choices.js";
+import * as env from "./env.js";
+import { type SecretStore } from "./secrets.js";
+import type { Account, AccountsOverview } from "./store.js";
+export type IssueCategory = 'auth_expired' | 'rate_limited' | 'quota' | 'network' | 'unknown';
+/** Best-effort classification of a provider error message. */
+export declare function classifyMessage(message: string): IssueCategory | null;
+export interface ModelOption {
+    id: string;
+    name: string;
+    provider: string;
+    supportsImages: boolean;
+    reasoning: boolean;
+}
+type Credential = Record<string, unknown> & {
+    type: 'api_key' | 'oauth';
+};
+export interface AccountLoginSnapshot {
+    accountId: string;
+    loginId: string;
+    provider: string;
+    method: string;
+    revision: number;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    events: Record<string, unknown>[];
+    prompt: Record<string, unknown> | null;
+    success: boolean | null;
+    error: string | null;
+}
+export interface AccountsOptions {
+    /** `<state dir>/accounts`. */
+    dir: string;
+    secrets: SecretStore;
+    bus: Bus;
+}
+export declare class Accounts {
+    readonly dir: string;
+    private readonly secrets;
+    private readonly bus;
+    private readonly runtimes;
+    private readonly logins;
+    private readonly latestLogins;
+    /** How many of this process's terminals use each account's auth.json. */
+    private readonly terminals;
+    /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
+    private readonly terminalSnapshots;
+    private installationDeviceIdPromise;
+    constructor(options: AccountsOptions);
+    private changed;
+    overview(): AccountsOverview;
+    find(accountId: string): Account;
+    /** The model and effort each mode last used on this account. */
+    choices(accountId: string): Record<string, choices.ModeChoice>;
+    /** Records a mode's model or effort on this account. Every selection counts, session-only ones too. */
+    choose(accountId: string, mode: string, patch: choices.ChoicePatch): Record<string, choices.ModeChoice>;
+    /** The account a new session uses; a session that already has one passes it and keeps it. */
+    resolve(accountId?: string | null, poolId?: string | null): Account;
+    context(account: Account): env.AccountContext;
+    readCredential(accountId: string, provider: string): Promise<Credential | null>;
+    /** Stores a provider's credential, or removes it when `credential` is `null`. */
+    writeCredential(accountId: string, provider: string, credential: Credential | null): Promise<void>;
+    listCredentials(accountId: string): Promise<{
+        providerId: string;
+        type: 'api_key' | 'oauth';
+    }[]>;
+    /** Pi's `CredentialStore` for one account. Writes are serialized, so a refresh never races another. */
+    private credentialStore;
+    /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
+    installationDeviceId(): Promise<string>;
+    private loadInstallationDeviceId;
+    /** The lazily loaded Pi runtime of one account: its models and its credentials. Pi's own `~/.pi` is never used. */
+    runtime(account: env.AccountContext | Account): Promise<ModelRuntime>;
+    /** Drops a cached runtime after its credentials changed outside it (sign-in, key edits, terminal sessions). */
+    invalidate(accountId: string): void;
+    models(accountId?: string | null): Promise<ModelOption[]>;
+    /** Offline inspection never refreshes OAuth tokens, contacts a provider, or changes credentials. */
+    inspect(accountId: string, signal?: AbortSignal): Promise<{
+        credentials: number;
+        models: ModelOption[];
+    }>;
+    /** Whether sessions can run, and why not. */
+    status(accountId?: string | null): Promise<{
+        available: boolean;
+        reason: string | null;
+        models: number;
+    }>;
+    /** Providers Pi can sign in to (OAuth) or take a key for, independent of any account. */
+    providers(): Promise<{
+        id: string;
+        name: string;
+        oauth: boolean;
+        oauthLabel: string | null;
+        subscription: boolean;
+        apiKey: boolean;
+    }[]>;
+    private probe;
+    /** Checks one account and records what Pi reports. */
+    refreshOne(account: Account): Promise<void>;
+    refresh(accountId?: string | null): Promise<AccountsOverview>;
+    create(label: string, authKind: string): AccountsOverview;
+    rename(accountId: string, label: string): AccountsOverview;
+    setDefault(accountId: string): AccountsOverview;
+    private forgetCredentials;
+    /** Deletes the account: removes its stored credentials and its runtime folder. Sessions pinned to it ask for another account next time they start. */
+    remove(accountId: string): Promise<AccountsOverview>;
+    savePool(pool: {
+        id?: string;
+        label: string;
+        accountIds: string[];
+    }): AccountsOverview;
+    removePool(poolId: string): AccountsOverview;
+    setApiKey(accountId: string, rawKey: string, provider: string): Promise<AccountsOverview>;
+    removeProvider(accountId: string, provider: string): Promise<AccountsOverview>;
+    signOut(accountId: string): Promise<AccountsOverview>;
+    private finishLogin;
+    /**
+     * Starts a provider's own sign-in for this account. Progress, links to open, and prompts
+     * arrive as `accounts.loginEvent` notices; the outcome as `accounts.login`.
+     */
+    loginStart(accountId: string, provider: string, method?: string | null): Promise<{
+        loginId: string;
+    }>;
+    /** Current in-memory sign-in progress for one account; codes and prompts are never written to disk. */
+    loginStatus(accountId: string): AccountLoginSnapshot | null;
+    loginRespond(loginId: string, promptId: string, value: string | null): void;
+    loginCancel(accountId: string, loginId?: string | null): void;
+    /**
+     * The `pi` command reads `auth.json` from its agent folder. For a terminal session the
+     * account's stored credentials are written there (mode 0600) while the terminal runs, then
+     * read back and removed.
+     */
+    /** How many terminal sessions are running on this account right now. */
+    terminalCount(accountId: string): number;
+    /**
+     * Starts a terminal's use of the account's auth.json. The file is written from the store when the
+     * first terminal of the account begins. While another process's terminal still uses it, the tokens
+     * already in the file stay, because that terminal may have refreshed them; only a provider the file
+     * lacks is added from the store, so a key saved after the other terminal began still reaches this one.
+     */
+    terminalBegin(account: Account): Promise<void>;
+    /**
+     * Ends a terminal's use of the auth.json. Each terminal saves what its Pi changed since it began (a
+     * refreshed or new sign-in, or a provider it signed out of), even while another process still uses the
+     * file, so no refresh is lost when the other terminal ends first. A credential saved to the store after
+     * the terminal began is in neither the file nor the snapshot, so it stays. The last terminal of the
+     * account to end, in every process, removes the file.
+     */
+    terminalEnd(account: Account): Promise<void>;
+    /** The account's stored credentials, with `existing` kept as it is for every provider it already has. */
+    private storedCredentials;
+    /**
+     * Whether another live process has a terminal on this account. Lease files of processes that have
+     * ended are removed, so a crash never leaves the account looking busy.
+     */
+    private otherTerminalProcesses;
+    private claimLease;
+    private releaseLease;
+    /** Tracks account health and limits from run events. `run` is the event's run record, when it is known. */
+    onRunEvent(event: RunEvent, run: RunRecord | null): void;
+    private applyStatus;
+}
+export {};