@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/accounts/accounts.js

@@ -0,0 +1,821 @@
+// The accounts service: everything that needs the secret store, the Pi runtime, or a notice.
+// Credentials go to the embedding application's secret store; nothing here writes one to the
+// harness's own files. A terminal's Pi reaches them through `accounts.credentials.*`.
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { log } from "../core/bus.js";
+import { HarnessError, invalid } from "../core/errors.js";
+import { atomicWrite, now, readJson, safeId } from "../core/fs.js";
+import { loadPi } from "../pi/runtime.js";
+import * as choices from "./choices.js";
+import * as env from "./env.js";
+import { secretKey, withCredentialLock } from "./secrets.js";
+import * as store from "./store.js";
+/** Best-effort classification of a provider error message. */
+export function classifyMessage(message) {
+    const text = message.toLowerCase();
+    if (/\b401\b|unauthori[sz]ed|invalid (api )?key|invalid x-api-key|authentication|not logged in|log ?in again|expired token|token (has )?expired|refresh token|oauth/.test(text))
+        return 'auth_expired';
+    if (/usage limit|quota|insufficient_quota|billing|credit balance|out of credits/.test(text))
+        return 'quota';
+    if (/\b429\b|rate.?limit|too many requests/.test(text))
+        return 'rate_limited';
+    if (/econnrefused|enotfound|etimedout|network|socket hang up|fetch failed/.test(text))
+        return 'network';
+    return null;
+}
+/** The lease files of an account: one per process that has a terminal on it. */
+const leaseFolder = (dir, accountId) => join(dir, accountId, 'terminal-leases');
+/** Whether a process with this id exists. One that exists but belongs to another user still counts. */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** The credentials in an auth.json, or null when there is no readable file. */
+function readAuth(path) {
+    try {
+        const parsed = readJson(path);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Compares two credentials by their fields, not their key order, which Pi may change when it rewrites the file. */
+function sameCredential(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return JSON.stringify(a, Object.keys(a).sort()) === JSON.stringify(b, Object.keys(b).sort());
+}
+/**
+ * Whether a credential found outside the store should replace the stored one. The store is the
+ * truth; an OAuth token wins only when it expires later, because OpenAI and others rotate the
+ * refresh token on every refresh and an older one is already spent.
+ */
+function preferCredential(candidate, stored) {
+    if (!stored)
+        return true;
+    if (sameCredential(candidate, stored))
+        return false;
+    if (candidate.type !== 'oauth' || stored.type !== 'oauth')
+        return false;
+    const expires = (credential) => typeof credential.expires === 'number' ? credential.expires : 0;
+    return expires(candidate) > expires(stored);
+}
+/** How long a terminal may hold a provider's credential lock; shorter than another waiter's lock timeout. */
+export const CREDENTIAL_LEASE_MS = 20_000;
+function validProvider(provider) {
+    if (provider && provider.length <= 64 && /^[A-Za-z0-9._-]+$/.test(provider))
+        return provider;
+    throw invalid('Invalid provider name.');
+}
+export class Accounts {
+    dir;
+    secrets;
+    bus;
+    credentialLockOptions;
+    runtimes = new Map();
+    logins = new Map();
+    latestLogins = new Map();
+    /** How many of this process's terminals run on each account. */
+    terminals = new Map();
+    /** Open credential leases: a terminal holds a provider's lock while its Pi refreshes or signs in. */
+    leases = new Map();
+    installationDeviceIdPromise = null;
+    /**
+     * Lets the limits service observe each account runtime's provider responses. The Harness sets
+     * it once; with none, a runtime behaves exactly as before.
+     */
+    observeModels = null;
+    constructor(options) {
+        this.dir = options.dir;
+        this.secrets = options.secrets;
+        this.bus = options.bus;
+        this.credentialLockOptions = options.credentialLock ?? {};
+    }
+    changed(payload = {}) {
+        this.bus.emit({ type: 'accounts.changed', ...payload });
+    }
+    overview() {
+        return store.overview(this.dir);
+    }
+    find(accountId) {
+        return store.find(this.dir, accountId);
+    }
+    /** The model and effort each mode last used on this account. */
+    choices(accountId) {
+        this.find(accountId);
+        return choices.readChoices(this.dir, accountId);
+    }
+    /** Records a mode's model or effort on this account. Every selection counts, session-only ones too. */
+    choose(accountId, mode, patch) {
+        this.find(accountId);
+        return choices.saveChoice(this.dir, accountId, mode, patch);
+    }
+    /** The account a new session uses; a session that already has one passes it and keeps it. */
+    resolve(accountId, poolId) {
+        return store.resolve(this.dir, accountId, poolId);
+    }
+    context(account) {
+        return env.accountContext(this.dir, account);
+    }
+    // ---- Stored credentials -----------------------------------------------------------------
+    async readCredential(accountId, provider) {
+        this.find(accountId);
+        const text = await this.secrets.get(secretKey(accountId, `pi-auth/${validProvider(provider)}`));
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    credentialLock(key, work) {
+        return withCredentialLock(join(this.dir, '.credential-locks'), key, work, this.credentialLockOptions);
+    }
+    /** Stores a provider's credential, or removes it when `credential` is `null`. */
+    async writeCredential(accountId, provider, credential) {
+        this.find(accountId);
+        const name = validProvider(provider);
+        await this.credentialLock(`provider/${accountId}/${name}`, () => this.persistCredential(accountId, name, credential));
+    }
+    /** The entire refresh read/modify/write is coordinated across services and processes. */
+    async modifyCredential(accountId, provider, change) {
+        this.find(accountId);
+        const name = validProvider(provider);
+        return this.credentialLock(`provider/${accountId}/${name}`, async () => {
+            const current = (await this.readCredential(accountId, name)) ?? undefined;
+            const updated = await change(current);
+            if (updated !== undefined)
+                await this.persistCredential(accountId, name, updated);
+            return updated ?? current;
+        });
+    }
+    async persistCredential(accountId, name, credential) {
+        // Different providers still share the account's provider index. Keep its short commit serialized.
+        await this.credentialLock(`account/${accountId}`, async () => {
+            this.find(accountId);
+            if (credential === null)
+                await this.secrets.delete(secretKey(accountId, `pi-auth/${name}`));
+            else
+                await this.secrets.set(secretKey(accountId, `pi-auth/${name}`), JSON.stringify(credential));
+            store.updateState(this.dir, accountId, (state) => {
+                state.piProviders = state.piProviders.filter((existing) => existing !== name);
+                if (credential !== null)
+                    state.piProviders = [...state.piProviders, name].sort();
+            });
+        });
+    }
+    async listCredentials(accountId) {
+        this.find(accountId);
+        const listed = [];
+        for (const provider of store.loadState(this.dir, accountId).piProviders) {
+            const credential = await this.readCredential(accountId, provider).catch(() => null);
+            if (credential && typeof credential.type === 'string')
+                listed.push({ providerId: provider, type: credential.type });
+        }
+        return listed;
+    }
+    /** Pi and explicit account edits share the same cross-process credential lock. */
+    credentialStore(accountId) {
+        return {
+            read: async (providerId) => (await this.readCredential(accountId, providerId)) ?? undefined,
+            list: () => this.listCredentials(accountId),
+            modify: (providerId, change) => this.modifyCredential(accountId, providerId, change),
+            delete: (providerId) => this.writeCredential(accountId, providerId, null)
+        };
+    }
+    /**
+     * Takes a provider's cross-process credential lock for a terminal whose Pi will refresh or sign in
+     * with the current credential, and holds it until `commitCredentialLease` or `CREDENTIAL_LEASE_MS`.
+     * A terminal reads and writes credentials only this way, so one refresh token has one lock: two
+     * copies refreshed under separate locks made the second refresh fail with `invalid_grant`.
+     */
+    async leaseCredential(accountId, provider, timeoutMs = CREDENTIAL_LEASE_MS) {
+        this.find(accountId);
+        const name = validProvider(provider);
+        const leaseId = randomUUID();
+        let grant;
+        const granted = new Promise((resolve) => { grant = resolve; });
+        let commit;
+        const committed = new Promise((resolve) => { commit = resolve; });
+        const done = this.modifyCredential(accountId, name, async (current) => {
+            grant(current);
+            // An abandoned lease changes nothing.
+            const timer = setTimeout(() => commit(undefined), timeoutMs);
+            timer.unref?.();
+            try {
+                return await committed;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }).finally(() => this.leases.delete(leaseId));
+        this.leases.set(leaseId, { accountId, commit, done });
+        // The lock can fail (a wait timeout) before it is granted; once granted, how it ends is the commit's concern.
+        const ended = done.then(() => { throw new Error('The credential lease ended before it was granted.'); });
+        ended.catch(() => undefined);
+        const current = await Promise.race([granted, ended]);
+        return { leaseId, current };
+    }
+    /** Ends a lease, storing `credential` when one is given. Resolves with the stored credential afterwards. */
+    async commitCredentialLease(accountId, leaseId, credential) {
+        const lease = this.leases.get(leaseId);
+        if (!lease || lease.accountId !== accountId)
+            throw new HarnessError('not_found', 'That credential lease has ended.');
+        if (credential !== undefined && (!credential || typeof credential !== 'object' || (credential.type !== 'oauth' && credential.type !== 'api_key'))) {
+            lease.commit(undefined);
+            throw invalid('Invalid credential.');
+        }
+        lease.commit(credential);
+        return lease.done;
+    }
+    /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
+    installationDeviceId() {
+        if (!this.installationDeviceIdPromise) {
+            this.installationDeviceIdPromise = this.loadInstallationDeviceId().catch((error) => {
+                this.installationDeviceIdPromise = null;
+                throw error;
+            });
+        }
+        return this.installationDeviceIdPromise;
+    }
+    async loadInstallationDeviceId() {
+        const { SettingsManager } = await loadPi();
+        const settings = SettingsManager.create(process.cwd(), env.ensureSharedDir(this.dir));
+        const deviceId = settings.getOrCreateDeviceId();
+        await settings.flush();
+        return deviceId;
+    }
+    // ---- The Pi runtime ---------------------------------------------------------------------
+    /** The lazily loaded Pi runtime of one account: its models and its credentials. Pi's own `~/.pi` is never used. */
+    runtime(account) {
+        const id = account.id;
+        let runtime = this.runtimes.get(id);
+        if (!runtime) {
+            const configDir = 'configDir' in account ? account.configDir : env.ensureHome(this.dir, account);
+            runtime = loadPi()
+                .then(({ ModelRuntime }) => ModelRuntime.create({ credentials: this.credentialStore(id), modelsPath: join(configDir, 'models.json') }))
+                .then((created) => {
+                // Reading provider responses never changes what a request does; a broken observer is ignored.
+                try {
+                    this.observeModels?.(created, id);
+                }
+                catch { /* observation is best effort */ }
+                return created;
+            })
+                .catch((error) => {
+                this.runtimes.delete(id);
+                throw error;
+            });
+            this.runtimes.set(id, runtime);
+        }
+        return runtime;
+    }
+    /** Drops a cached runtime after its credentials changed outside it (sign-in, key edits, terminal sessions). */
+    invalidate(accountId) {
+        this.runtimes.delete(accountId);
+    }
+    async models(accountId) {
+        const account = accountId ? this.find(accountId) : store.defaultAccount(this.dir);
+        if (!account)
+            return [];
+        const available = await (await this.runtime(account)).getAvailable();
+        return available.map((model) => ({ id: `${model.provider}/${model.id}`, name: model.name || model.id, provider: String(model.provider), supportsImages: model.input.includes('image'), reasoning: model.reasoning }));
+    }
+    /** Offline inspection never refreshes OAuth tokens, contacts a provider, or changes credentials. */
+    async inspect(accountId, signal) {
+        this.find(accountId);
+        const { ModelRuntime } = await loadPi();
+        const credentials = this.credentialStore(accountId);
+        const readOnly = { read: credentials.read, list: credentials.list, modify: async () => undefined, delete: async () => undefined };
+        const runtime = await ModelRuntime.create({ credentials: readOnly, modelsPath: join(env.configDir(this.dir, { id: accountId }), 'models.json'), refreshOnCreate: false, allowModelNetwork: false, signal });
+        const saved = await runtime.listCredentials({ signal });
+        const providers = new Set(saved.map(item => item.providerId));
+        return { credentials: saved.length, models: runtime.getModels().filter(model => providers.has(String(model.provider))).map(model => ({ id: `${model.provider}/${model.id}`, name: model.name || model.id, provider: String(model.provider), supportsImages: model.input.includes('image'), reasoning: model.reasoning })) };
+    }
+    /** Whether sessions can run, and why not. */
+    async status(accountId) {
+        const account = accountId ? this.find(accountId) : store.defaultAccount(this.dir);
+        if (!account)
+            return { available: false, reason: 'Add a Pi account in Accounts to use Chat.', models: 0 };
+        try {
+            const models = await this.models(account.id);
+            return models.length ? { available: true, reason: null, models: models.length } : { available: false, reason: `The Pi account "${account.label}" has no signed-in provider. Sign in or add a key in Accounts.`, models: 0 };
+        }
+        catch (error) {
+            log('Pi runtime failed to load', error instanceof Error ? error.message : String(error));
+            return { available: false, reason: 'The Pi SDK could not be loaded.', models: 0 };
+        }
+    }
+    /** Providers Pi can sign in to (OAuth) or take a key for, independent of any account. */
+    async providers() {
+        const { ModelRuntime } = await loadPi();
+        const none = { read: async () => undefined, list: async () => [], modify: async () => undefined, delete: async () => undefined };
+        const runtime = await ModelRuntime.create({ credentials: none, modelsPath: null, refreshOnCreate: false });
+        return runtime
+            .getProviders()
+            .map((provider) => ({ id: provider.id, name: provider.name, oauth: Boolean(provider.auth.oauth), oauthLabel: provider.auth.oauth?.loginLabel ?? provider.auth.oauth?.name ?? null, subscription: Boolean(provider.auth.oauth?.isSubscription), apiKey: Boolean(provider.auth.apiKey?.login) }))
+            .filter((provider) => provider.oauth || provider.apiKey)
+            .sort((left, right) => left.name.localeCompare(right.name));
+    }
+    // ---- Status checks ----------------------------------------------------------------------
+    async probe(account) {
+        const runtime = await this.runtime(account);
+        const credentials = await runtime.listCredentials();
+        const available = await runtime.getAvailable();
+        const subscription = credentials.filter((credential) => runtime.isUsingSubscription(credential.providerId)).map((credential) => credential.providerId);
+        return {
+            signedIn: credentials.length > 0 && available.length > 0,
+            authMethod: [...new Set(credentials.map((credential) => credential.type))].join(', ') || null,
+            plan: subscription.length ? `Subscription: ${subscription.join(', ')}` : null,
+            identity: credentials.map((credential) => credential.providerId).join(', ') || null,
+            capabilities: [`models:${available.length}`, ...credentials.map((credential) => `provider:${credential.providerId}`)]
+        };
+    }
+    /** Checks one account and records what Pi reports. */
+    async refreshOne(account) {
+        let probe = null;
+        let failure = null;
+        try {
+            probe = await this.probe(account);
+        }
+        catch (error) {
+            failure = error instanceof Error ? error.message : String(error);
+        }
+        const { previous, state } = store.updateState(this.dir, account.id, (current) => {
+            current.lastCheckedAt = now();
+            if (probe) {
+                current.signedIn = probe.signedIn;
+                current.authMethod = probe.authMethod;
+                current.plan = probe.plan ?? current.plan;
+                current.identity = probe.identity;
+                if (probe.limits)
+                    current.limits = probe.limits;
+                current.capabilities = probe.capabilities;
+                const keepLimitError = current.lastError !== null && store.isLimitCategory(current.lastError.category) && store.limitErrorActive(current.lastError);
+                if (probe.signedIn === true && !keepLimitError)
+                    current.lastError = null;
+            }
+            else {
+                current.lastError = { category: classifyMessage(failure ?? '') ?? 'unknown', message: store.scrub(failure ?? ''), at: now(), resetsAt: null };
+            }
+        });
+        if (previous !== state.health)
+            store.audit(this.dir, account.id, 'health.changed', `${previous} → ${state.health} (status check)`);
+        this.changed({ accountId: account.id });
+    }
+    async refresh(accountId) {
+        const accounts = accountId ? [this.find(accountId)] : store.loadRegistry(this.dir).accounts.filter((account) => account.provider === store.PROVIDER);
+        for (const account of accounts)
+            await this.refreshOne(account);
+        return this.overview();
+    }
+    // ---- Create, rename, remove -------------------------------------------------------------
+    create(label, authKind) {
+        const account = store.addAccount(this.dir, label, authKind);
+        env.ensureHome(this.dir, account);
+        store.audit(this.dir, account.id, 'account.created', `Pi account "${account.label}" (${account.authKind})`);
+        this.changed({ accountId: account.id });
+        return this.overview();
+    }
+    rename(accountId, label) {
+        store.renameAccount(this.dir, accountId, label);
+        store.audit(this.dir, accountId, 'account.renamed', store.cleanLabel(label));
+        this.changed({ accountId });
+        return this.overview();
+    }
+    setDefault(accountId) {
+        store.setDefault(this.dir, accountId);
+        store.audit(this.dir, accountId, 'default.changed', 'Default Pi account for new sessions.');
+        this.changed({ accountId });
+        return this.overview();
+    }
+    async forgetCredentials(account) {
+        for (const provider of store.loadState(this.dir, account.id).piProviders)
+            await this.writeCredential(account.id, provider, null);
+        this.invalidate(account.id);
+    }
+    /** Deletes the account: removes its stored credentials and its runtime folder. Sessions pinned to it ask for another account next time they start. */
+    async remove(accountId) {
+        const account = this.find(accountId);
+        for (const login of this.logins.values())
+            if (login.accountId === accountId)
+                login.cancel();
+        this.latestLogins.delete(accountId);
+        await this.forgetCredentials(account).catch(() => undefined);
+        await this.secrets.delete(secretKey(account.id, 'apiKey')).catch(() => undefined);
+        store.forgetAccount(this.dir, account);
+        rmSync(join(this.dir, safeId(account.id)), { recursive: true, force: true });
+        store.audit(this.dir, account.id, 'account.deleted', `"${account.label}" and its stored sign-in were removed.`);
+        this.changed({ accountId: account.id });
+        return this.overview();
+    }
+    savePool(pool) {
+        const saved = store.savePool(this.dir, pool);
+        store.audit(this.dir, null, 'pool.saved', `${saved.label}: ${saved.accountIds.length} account(s)`);
+        this.changed();
+        return this.overview();
+    }
+    removePool(poolId) {
+        store.removePool(this.dir, poolId);
+        store.audit(this.dir, null, 'pool.removed', poolId);
+        this.changed();
+        return this.overview();
+    }
+    // ---- Keys and sign-in -------------------------------------------------------------------
+    async setApiKey(accountId, rawKey, provider) {
+        const account = this.find(accountId);
+        const key = rawKey.trim();
+        if (!key || key.length > 4096 || /\s/.test(key))
+            throw invalid('Paste the key without spaces.');
+        if (!provider)
+            throw invalid('Choose which Pi provider the key is for.');
+        await this.writeCredential(account.id, provider, { type: 'api_key', key });
+        this.invalidate(account.id);
+        store.audit(this.dir, account.id, 'key.set', 'Provider key stored in the Keychain.');
+        await this.refreshOne(account);
+        return this.overview();
+    }
+    async removeProvider(accountId, provider) {
+        const account = this.find(accountId);
+        await this.writeCredential(account.id, provider, null);
+        this.invalidate(account.id);
+        store.audit(this.dir, account.id, 'key.removed', provider);
+        await this.refreshOne(account);
+        return this.overview();
+    }
+    async signOut(accountId) {
+        const account = this.find(accountId);
+        await this.forgetCredentials(account);
+        store.audit(this.dir, account.id, 'logout', 'Signed out; stored credentials removed.');
+        store.updateState(this.dir, account.id, (current) => {
+            current.signedIn = false;
+            current.identity = null;
+            current.lastError = null;
+        });
+        this.changed({ accountId: account.id });
+        return this.overview();
+    }
+    finishLogin(loginId, success, error, cancelled = false) {
+        const login = this.logins.get(loginId);
+        if (!login)
+            return;
+        this.logins.delete(loginId);
+        for (const prompt of login.prompts.values())
+            prompt.reject(new Error('Sign-in ended.'));
+        if (success)
+            this.invalidate(login.accountId);
+        store.audit(this.dir, login.accountId, success ? 'login.completed' : 'login.failed', error ?? '');
+        // A fresh sign-in starts clean; a limit that still applies is reported again by the next run.
+        if (success)
+            store.updateState(this.dir, login.accountId, (current) => void (current.lastError = null));
+        login.revision += 1;
+        const status = success ? 'completed' : cancelled ? 'cancelled' : 'failed';
+        if (this.latestLogins.get(login.accountId)?.loginId === loginId) {
+            this.latestLogins.set(login.accountId, {
+                accountId: login.accountId,
+                loginId,
+                provider: login.provider,
+                method: login.method,
+                revision: login.revision,
+                status,
+                // A terminal result is enough to reconcile the client. In particular, do not retain a
+                // device code after the attempt ends.
+                events: [],
+                prompt: null,
+                success,
+                error
+            });
+        }
+        this.bus.emit({ type: 'accounts.login', accountId: login.accountId, loginId, revision: login.revision, success, error });
+        try {
+            void this.refreshOne(this.find(login.accountId)).catch(() => undefined);
+        }
+        catch {
+            // The account was removed while its sign-in was running.
+        }
+    }
+    /**
+     * 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`.
+     */
+    async loginStart(accountId, provider, method) {
+        const account = this.find(accountId);
+        if (!provider)
+            throw invalid('Choose which Pi provider to sign in to.');
+        store.audit(this.dir, account.id, 'login.started', `${method ?? 'oauth'} · ${provider}`);
+        const loginId = randomUUID();
+        const controller = new AbortController();
+        const login = {
+            accountId: account.id,
+            provider,
+            method: method === 'api_key' ? 'api_key' : 'oauth',
+            prompts: new Map(),
+            cancel: () => controller.abort(),
+            revision: 0,
+            events: [],
+            prompt: null
+        };
+        this.logins.set(loginId, login);
+        this.latestLogins.set(account.id, {
+            accountId: account.id,
+            loginId,
+            provider: login.provider,
+            method: login.method,
+            revision: 0,
+            status: 'running',
+            events: [],
+            prompt: null,
+            success: null,
+            error: null
+        });
+        const event = (payload) => {
+            login.revision += 1;
+            if (payload.type === 'prompt')
+                login.prompt = payload;
+            else if (payload.type === 'promptClosed' && login.prompt?.promptId === payload.promptId)
+                login.prompt = null;
+            else {
+                login.events.push(payload);
+                if (login.events.length > 50)
+                    login.events.shift();
+            }
+            if (this.latestLogins.get(account.id)?.loginId === loginId) {
+                this.latestLogins.set(account.id, {
+                    accountId: account.id,
+                    loginId,
+                    provider: login.provider,
+                    method: login.method,
+                    revision: login.revision,
+                    status: 'running',
+                    events: login.events.map((step) => ({ ...step })),
+                    prompt: login.prompt ? { ...login.prompt } : null,
+                    success: null,
+                    error: null
+                });
+            }
+            this.bus.emit({ type: 'accounts.loginEvent', accountId: account.id, loginId, revision: login.revision, event: payload });
+        };
+        const interaction = {
+            signal: controller.signal,
+            notify: (notification) => event(notification),
+            prompt: (prompt) => new Promise((resolve, reject) => {
+                const promptId = randomUUID();
+                login.prompts.set(promptId, { resolve, reject });
+                prompt.signal?.addEventListener('abort', () => {
+                    login.prompts.delete(promptId);
+                    event({ type: 'promptClosed', promptId });
+                    reject(new Error('Prompt closed.'));
+                });
+                event({ type: 'prompt', promptId, prompt: { type: prompt.type, message: prompt.message, placeholder: prompt.placeholder ?? null, options: prompt.options ?? null } });
+            })
+        };
+        void this.runtime(account)
+            .then(async (runtime) => {
+            if (login.method !== 'oauth')
+                return runtime.login(provider, login.method, interaction);
+            const deviceId = await this.installationDeviceId();
+            return runtime.login(provider, login.method, interaction, { getDeviceId: () => deviceId });
+        })
+            .then(() => this.finishLogin(loginId, true, null))
+            .catch((error) => this.finishLogin(loginId, false, controller.signal.aborted ? 'Sign-in was cancelled.' : error instanceof Error ? error.message : String(error), controller.signal.aborted));
+        return { loginId };
+    }
+    /** Current in-memory sign-in progress for one account; codes and prompts are never written to disk. */
+    loginStatus(accountId) {
+        this.find(accountId);
+        const snapshot = this.latestLogins.get(accountId);
+        return snapshot ? structuredClone(snapshot) : null;
+    }
+    loginRespond(loginId, promptId, value) {
+        const login = this.logins.get(loginId);
+        const prompt = login?.prompts.get(promptId);
+        if (!login || !prompt)
+            throw new HarnessError('not_found', 'That sign-in step is no longer waiting.');
+        login.prompts.delete(promptId);
+        // The renderer's recoverable snapshot must stop presenting a prompt as soon as it is answered.
+        const current = this.latestLogins.get(login.accountId);
+        if (current?.loginId === loginId && current.prompt?.promptId === promptId) {
+            login.prompt = null;
+            current.revision += 1;
+            login.revision = current.revision;
+            current.prompt = null;
+            this.latestLogins.set(login.accountId, current);
+            this.bus.emit({ type: 'accounts.loginEvent', accountId: login.accountId, loginId, revision: current.revision, event: { type: 'promptClosed', promptId } });
+        }
+        if (value === null)
+            prompt.reject(new Error('Cancelled.'));
+        else
+            prompt.resolve(value);
+    }
+    loginCancel(accountId, loginId) {
+        if (loginId) {
+            const login = this.logins.get(loginId);
+            if (login?.accountId === accountId)
+                login.cancel();
+        }
+        else
+            for (const login of this.logins.values())
+                if (login.accountId === accountId)
+                    login.cancel();
+        store.audit(this.dir, accountId, 'login.cancelled', '');
+    }
+    // ---- Terminal sessions --------------------------------------------------------------------
+    /** How many terminal sessions are running on this account right now. */
+    terminalCount(accountId) {
+        return this.terminals.get(accountId) ?? 0;
+    }
+    /**
+     * Starts a terminal on the account. Its Pi reads and writes credentials through this store over
+     * the terminal's control socket (`accounts.credentials.*`), so nothing is written to `auth.json`.
+     * A file an older terminal left is folded into the store, newest token first.
+     */
+    async terminalBegin(account) {
+        const count = (this.terminals.get(account.id) ?? 0) + 1;
+        this.terminals.set(account.id, count);
+        if (count > 1)
+            return;
+        try {
+            this.claimLease(account.id);
+            await this.adoptAuthFile(account);
+        }
+        catch (error) {
+            this.terminals.delete(account.id);
+            this.releaseLease(account.id);
+            throw error;
+        }
+    }
+    /** Ends a terminal on the account; the last one in this process folds in any `auth.json` left behind. */
+    async terminalEnd(account) {
+        const remaining = Math.max(0, (this.terminals.get(account.id) ?? 1) - 1);
+        if (remaining > 0) {
+            this.terminals.set(account.id, remaining);
+            return;
+        }
+        this.terminals.delete(account.id);
+        this.releaseLease(account.id);
+        await this.adoptAuthFile(account);
+    }
+    /**
+     * Saves what an older terminal's `auth.json` holds that the store lacks or holds older, under each
+     * provider's lock, and never replaces a newer token. The file is removed once no other process has
+     * a terminal on the account, since an older one may still be reading it.
+     */
+    async adoptAuthFile(account) {
+        const path = join(env.configDir(this.dir, account), 'auth.json');
+        if (!existsSync(path))
+            return;
+        const data = readAuth(path);
+        if (!data)
+            throw new Error(`The terminal credential file ${path} is not readable.`);
+        let changed = false;
+        for (const [provider, candidate] of Object.entries(data)) {
+            if (!candidate || typeof candidate !== 'object' || (candidate.type !== 'oauth' && candidate.type !== 'api_key'))
+                continue;
+            try {
+                await this.modifyCredential(account.id, provider, async (stored) => {
+                    if (!preferCredential(candidate, stored))
+                        return undefined;
+                    changed = true;
+                    return candidate;
+                });
+            }
+            catch (error) {
+                log('terminal credentials', `${provider}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (changed) {
+            this.invalidate(account.id);
+            store.audit(this.dir, account.id, 'credentials.synced', 'A terminal sign-in from auth.json was saved to the Keychain.');
+        }
+        if (!this.otherTerminalProcesses(account.id))
+            rmSync(path, { force: true });
+    }
+    /**
+     * 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.
+     */
+    otherTerminalProcesses(accountId) {
+        const folder = leaseFolder(this.dir, accountId);
+        let names;
+        try {
+            names = readdirSync(folder);
+        }
+        catch {
+            return false;
+        }
+        let others = false;
+        for (const name of names) {
+            const pid = Number(name);
+            if (!/^\d+$/.test(name) || pid <= 0 || pid === process.pid)
+                continue;
+            if (processAlive(pid))
+                others = true;
+            else
+                rmSync(join(folder, name), { force: true });
+        }
+        return others;
+    }
+    claimLease(accountId) {
+        const folder = leaseFolder(this.dir, accountId);
+        mkdirSync(folder, { recursive: true, mode: 0o700 });
+        atomicWrite(join(folder, String(process.pid)), JSON.stringify({ pid: process.pid, startedAt: now() }));
+    }
+    releaseLease(accountId) {
+        rmSync(join(leaseFolder(this.dir, accountId), String(process.pid)), { force: true });
+    }
+    // ---- Health from runs ---------------------------------------------------------------------
+    /** Tracks account health and limits from run events. `run` is the event's run record, when it is known. */
+    onRunEvent(event, run) {
+        if (event.type === 'account.status')
+            this.applyStatus(event);
+        else if (event.type === 'completed' && run?.accountId) {
+            const accountId = run.accountId;
+            const { previous, state } = store.updateState(this.dir, accountId, (current) => {
+                // A finished run proves the sign-in works; limit windows and limit errors stay until they reset.
+                if (current.lastError && (!store.isLimitCategory(current.lastError.category) || !store.limitErrorActive(current.lastError)))
+                    current.lastError = null;
+                current.signedIn = true;
+            });
+            if (previous !== state.health)
+                this.changed({ accountId, health: state.health, previous });
+        }
+    }
+    /**
+     * Records what a provider reported about its limits. An endpoint reading replaces that provider's
+     * limits; a header reading merges by id. Windows whose reset has passed are dropped. No credential
+     * is stored here.
+     */
+    applyLimits(accountId, readouts) {
+        this.find(accountId);
+        const expired = (limit) => {
+            const time = limit.resetsAt ? Date.parse(limit.resetsAt) : Number.NaN;
+            return !Number.isNaN(time) && time <= Date.now();
+        };
+        store.updateState(this.dir, accountId, (state) => {
+            for (const readout of readouts) {
+                // An endpoint read is the provider's whole answer; a header read only adds what it saw.
+                const kept = new Map((readout.source === 'provider' ? [] : state.limits.filter((limit) => limit.provider === readout.provider && !expired(limit)))
+                    .map((limit) => [limit.id, limit]));
+                for (const limit of readout.limits)
+                    kept.set(limit.id, limit);
+                state.limits = [...state.limits.filter((limit) => limit.provider !== readout.provider), ...kept.values()];
+                const entry = { provider: readout.provider, source: readout.source, reason: readout.reason, observedAt: readout.observedAt };
+                state.providerLimits = [...state.providerLimits.filter((existing) => existing.provider !== readout.provider), entry];
+                if (readout.plan)
+                    state.plan = readout.plan;
+            }
+            state.limits.sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+        });
+        this.changed({ accountId });
+        return this.overview();
+    }
+    applyStatus(event) {
+        const payload = event.payload;
+        if (typeof payload.accountId !== 'string')
+            return;
+        const accountId = payload.accountId;
+        const text = (value) => (typeof value === 'string' ? value : null);
+        const category = text(payload.category);
+        const message = text(payload.message) === null ? null : store.scrub(payload.message);
+        const limits = Array.isArray(payload.limits) ? payload.limits : null;
+        let result;
+        try {
+            result = store.updateState(this.dir, accountId, (state) => {
+                if (limits) {
+                    for (const limit of limits)
+                        state.limits = [...state.limits.filter((existing) => existing.id !== limit.id), limit];
+                    state.limits.sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+                }
+                if (text(payload.plan) !== null)
+                    state.plan = text(payload.plan);
+                if (category) {
+                    state.lastError = { category, message: message ?? '', at: now(), resetsAt: text(payload.resetsAt) };
+                    if (category === 'auth_expired')
+                        state.signedIn = false;
+                }
+            });
+        }
+        catch {
+            return;
+        }
+        if (result.previous !== result.state.health) {
+            store.audit(this.dir, accountId, 'health.changed', `${result.previous} → ${result.state.health}${message ? `: ${message}` : ''}`);
+            this.changed({ accountId, health: result.state.health, previous: result.previous, message, resetsAt: text(payload.resetsAt) });
+        }
+        else {
+            this.changed({ accountId });
+        }
+    }
+}