@xingular/harness 0.1.6 → 1.0.0

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

@@ -0,0 +1,23 @@
+import { type Effort } from "../core/effort.js";
+export interface ModeChoice {
+    /** `provider/id` of the model. */
+    model?: string;
+    effort?: Effort;
+    updatedAt: string;
+}
+export interface ChoicePatch {
+    model?: string;
+    effort?: Effort;
+}
+/** Every saved mode of the account. A missing or unreadable file, and any invalid entry, reads as nothing. */
+export declare function readChoices(dir: string, accountId: string): Record<string, ModeChoice>;
+/** Records one or both fields for a mode, keeping the field the patch does not name. */
+export declare function saveChoice(dir: string, accountId: string, mode: string, patch: ChoicePatch): Record<string, ModeChoice>;
+/**
+ * The model and effort a mode starts from: its own saved field, else the fallback mode's. The
+ * fallback itself has no further fallback.
+ */
+export declare function resolveChoice(modes: Record<string, ModeChoice>, mode: string, fallback?: string): {
+    model?: string;
+    effort?: Effort;
+};

package/dist/sdk/accounts/choices.js

@@ -0,0 +1,62 @@
+// The model and effort each mode last used on an account. One file per account, in the account's
+// own folder, so removing the account removes its choices. It never holds credentials.
+import { join } from 'node:path';
+import { EFFORTS } from "../core/effort.js";
+import { invalid } from "../core/errors.js";
+import { now, readJsonOr, safeId, writeJson } from "../core/fs.js";
+const MODE = /^[a-z][a-z0-9_-]{0,31}$/;
+const MODEL = /^[^\s/]+\/\S+$/;
+const MAX_MODEL = 200;
+const choicesPath = (dir, accountId) => join(dir, safeId(accountId), 'choices.json');
+const validModel = (model) => model.length <= MAX_MODEL && MODEL.test(model);
+const validEffort = (effort) => typeof effort === 'string' && EFFORTS.includes(effort);
+function validChoice(entry) {
+    const model = typeof entry.model === 'string' && validModel(entry.model) ? entry.model : undefined;
+    const effort = validEffort(entry.effort) ? entry.effort : undefined;
+    if (!model && !effort)
+        return null;
+    return { ...(model ? { model } : {}), ...(effort ? { effort } : {}), updatedAt: typeof entry.updatedAt === 'string' ? entry.updatedAt : now() };
+}
+/** Every saved mode of the account. A missing or unreadable file, and any invalid entry, reads as nothing. */
+export function readChoices(dir, accountId) {
+    const stored = readJsonOr(choicesPath(dir, accountId), null);
+    const modes = {};
+    for (const [mode, entry] of Object.entries(stored?.modes ?? {})) {
+        if (!MODE.test(mode) || !entry || typeof entry !== 'object')
+            continue;
+        const choice = validChoice(entry);
+        if (choice)
+            modes[mode] = choice;
+    }
+    return modes;
+}
+/** Records one or both fields for a mode, keeping the field the patch does not name. */
+export function saveChoice(dir, accountId, mode, patch) {
+    if (!MODE.test(mode))
+        throw invalid('A mode is lowercase letters, digits, - or _, starting with a letter.');
+    if (patch.model !== undefined && (typeof patch.model !== 'string' || !validModel(patch.model)))
+        throw invalid('A model is provider/id.');
+    if (patch.effort !== undefined && !validEffort(patch.effort))
+        throw invalid(`An effort is one of ${EFFORTS.join(', ')}.`);
+    const modes = readChoices(dir, accountId);
+    const current = modes[mode] ?? {};
+    const next = validChoice({
+        ...(patch.model !== undefined ? { model: patch.model } : { model: current.model }),
+        ...(patch.effort !== undefined ? { effort: patch.effort } : { effort: current.effort }),
+        updatedAt: now()
+    });
+    if (!next)
+        throw invalid('Choose a model or an effort.');
+    modes[mode] = next;
+    writeJson(choicesPath(dir, accountId), { modes });
+    return modes;
+}
+/**
+ * The model and effort a mode starts from: its own saved field, else the fallback mode's. The
+ * fallback itself has no further fallback.
+ */
+export function resolveChoice(modes, mode, fallback = 'normal') {
+    const own = modes[mode] ?? {};
+    const base = mode === fallback ? {} : modes[fallback] ?? {};
+    return { model: own.model ?? base.model, effort: own.effort ?? base.effort };
+}

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

@@ -0,0 +1,78 @@
+import type { Account } from "./store.js";
+/** Inherited variables that carry credentials; they would bypass the account's own sign-in. */
+export declare function isCredentialVar(name: string): boolean;
+/** Names of inherited variables to remove from a session's process. */
+export declare function inheritedCredentialVars(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Makes this process safe to run Pi sessions in: credentials come only from an account's own
+ * store, so inherited credential variables are dropped, and Pi's fallback agent folder is an
+ * empty one under the state directory rather than `~/.pi`.
+ */
+export declare function isolateProcess(accountsDir: string, env?: NodeJS.ProcessEnv): void;
+export declare const homeDir: (accountsDir: string, accountId: string) => string;
+/** Pi's agent folder for this account. */
+export declare const configDir: (accountsDir: string, account: Pick<Account, "id">) => string;
+/** The agent-folder entries every account shares. */
+export declare const sharedDir: (accountsDir: string) => string;
+export interface NativeConfig {
+    provider: string;
+    path: string;
+    entries: {
+        name: string;
+        directory: boolean;
+        present: boolean;
+    }[];
+}
+/** What the accounts share, and which of it exists yet. Reads only; nothing is created. */
+export declare function nativeConfig(accountsDir: string): NativeConfig;
+/** The shared folder, created private if no account has linked it yet. */
+export declare function ensureSharedDir(accountsDir: string): string;
+/**
+ * How one shared entry is linked into an account folder. Windows refuses a symbolic link to a
+ * user without the symlink privilege, so each kind has a fallback that needs none.
+ */
+export interface EntryLinker {
+    /** A symbolic link to a file, or a junction to a folder (junctions need no privilege on Windows). */
+    symlink(target: string, path: string, isDir: boolean): void;
+    /** A hard link to a file on the same volume. */
+    hardLink(target: string, path: string): void;
+}
+/** What happened to one shared entry: linked to the shared copy, or left as the account's own. */
+export interface SharedEntry {
+    name: string;
+    state: 'linked' | 'unshared';
+    /** Why the link was refused, when it was. */
+    reason?: string;
+}
+/**
+ * Creates the account's runtime folder and links the shared entries into it. Never throws for a
+ * refused link: each entry is reported, and the account falls back to its own copy.
+ */
+export declare function linkSharedEntries(accountsDir: string, account: Pick<Account, 'id'>, linker?: EntryLinker): {
+    dir: string;
+    entries: SharedEntry[];
+};
+/** Creates the account's runtime folder and links the shared entries into it. */
+export declare function ensureHome(accountsDir: string, account: Pick<Account, 'id'>): string;
+/**
+ * Refuses an agent folder that is (or is inside) a default tool folder, or that is not inside
+ * the harness's own accounts folder.
+ */
+export declare function assertIsolated(accountsDir: string, dir: string): void;
+/** Variables to set, or remove (`null`), when launching a session for this account. */
+export declare function launchEnv(accountsDir: string, account: Pick<Account, 'id'>, inherited?: NodeJS.ProcessEnv): Record<string, string | null>;
+/** What a session needs to run for an account. */
+export interface AccountContext {
+    id: string;
+    provider: 'pi';
+    label: string;
+    /** Variables to set; `null` removes an inherited one. */
+    env: Record<string, string | null>;
+    /** The account's own agent folder. */
+    configDir: string;
+    /** Which shared entries are linked, and which the account keeps as its own. */
+    sharing: SharedEntry[];
+}
+export declare function accountContext(accountsDir: string, account: Account): AccountContext;
+/** The process environment for a `pi` process launched on behalf of this account. */
+export declare function processEnv(account: AccountContext, inherited?: NodeJS.ProcessEnv): Record<string, string>;

package/dist/sdk/accounts/env.js

@@ -0,0 +1,294 @@
+// Isolated launch environments. Every Pi session the harness starts gets its account's own
+// agent folder (`PI_CODING_AGENT_DIR`) under the state directory, and inherited credential
+// variables are removed. A launch that would fall back to `~/.pi` is refused.
+//
+// Settings, skills, prompts, and instructions are shared by every account: the account's agent
+// folder links those entries to `_shared/pi/`. Where the system refuses a link (Windows without
+// the symlink privilege), the entry stays the account's own, and a shared file is copied in so
+// its settings still load. Credentials, sessions, and history stay in the account's own folder.
+import { chmodSync, copyFileSync, linkSync, lstatSync, mkdirSync, readlinkSync, renameSync, rmdirSync, statSync, symlinkSync, unlinkSync, utimesSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { HarnessError } from "../core/errors.js";
+// Config-directory variables the harness always sets itself, including those of other tools so
+// a session can never inherit them.
+const DIR_VARS = ['CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'PI_CODING_AGENT_DIR'];
+/** Inherited variables that carry credentials; they would bypass the account's own sign-in. */
+export function isCredentialVar(name) {
+    const upper = name.toUpperCase();
+    return DIR_VARS.includes(upper) || ['_API_KEY', '_AUTH_TOKEN', '_OAUTH_TOKEN', '_ACCESS_TOKEN'].some((suffix) => upper.endsWith(suffix));
+}
+/** Names of inherited variables to remove from a session's process. */
+export function inheritedCredentialVars(env = process.env) {
+    const names = Object.keys(env).filter(isCredentialVar);
+    for (const name of DIR_VARS)
+        if (!names.includes(name))
+            names.push(name);
+    return names;
+}
+/**
+ * Makes this process safe to run Pi sessions in: credentials come only from an account's own
+ * store, so inherited credential variables are dropped, and Pi's fallback agent folder is an
+ * empty one under the state directory rather than `~/.pi`.
+ */
+export function isolateProcess(accountsDir, env = process.env) {
+    for (const name of inheritedCredentialVars(env))
+        delete env[name];
+    const fallback = join(accountsDir, '.sidecar', 'pi');
+    mkdirSync(fallback, { recursive: true });
+    env.PI_CODING_AGENT_DIR = fallback;
+}
+export const homeDir = (accountsDir, accountId) => join(accountsDir, accountId, 'home');
+/** Pi's agent folder for this account. */
+export const configDir = (accountsDir, account) => join(homeDir(accountsDir, account.id), 'pi');
+/** The agent-folder entries every account shares. */
+export const sharedDir = (accountsDir) => join(accountsDir, '_shared', 'pi');
+function makePrivate(path) {
+    mkdirSync(path, { recursive: true });
+    chmodSync(path, 0o700);
+}
+// Entries every account shares, and whether each is a folder. Credentials (`auth.json`),
+// sessions, and history are never listed.
+const SHARED_ENTRIES = [
+    ['settings.json', false],
+    ['models.json', false],
+    ['AGENTS.md', false],
+    ['SYSTEM.md', false],
+    ['skills', true],
+    ['prompts', true],
+    ['extensions', true],
+    ['themes', true],
+    // Where Pi keeps installed packages: one install serves every account.
+    ['npm', true],
+    ['git', true]
+];
+const present = (path) => {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** What the accounts share, and which of it exists yet. Reads only; nothing is created. */
+export function nativeConfig(accountsDir) {
+    const shared = sharedDir(accountsDir);
+    return { provider: 'pi', path: shared, entries: SHARED_ENTRIES.map(([name, directory]) => ({ name, directory, present: present(join(shared, name)) })) };
+}
+/** The shared folder, created private if no account has linked it yet. */
+export function ensureSharedDir(accountsDir) {
+    const shared = sharedDir(accountsDir);
+    makePrivate(shared);
+    return shared;
+}
+const modified = (path) => {
+    try {
+        return lstatSync(path).mtimeMs;
+    }
+    catch {
+        return -1;
+    }
+};
+/** Moves a real file or folder aside so the shared link can take its place; returns where it went. */
+function backUp(path) {
+    const backup = join(dirname(path), `${basename(path)}.xagent-backup-${Math.floor(Date.now() / 1000)}`);
+    renameSync(path, backup);
+    return backup;
+}
+const nodeLinker = {
+    symlink: (target, path, isDir) => symlinkSync(resolve(target), path, isDir ? 'junction' : 'file'),
+    hardLink: (target, path) => linkSync(target, path)
+};
+const codeOf = (error) => error.code ?? String(error);
+const PRIVILEGE_CODES = ['EPERM', 'EACCES'];
+function createLink(target, path, isDir, linker) {
+    try {
+        linker.symlink(target, path, isDir);
+    }
+    catch (error) {
+        // A file can still be hard-linked without the privilege; a folder has no such fallback.
+        if (isDir || !PRIVILEGE_CODES.includes(codeOf(error)))
+            throw error;
+        linker.hardLink(target, path);
+    }
+}
+const isLink = (path) => {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+// Windows reports some link targets with the `\\?\` prefix.
+const LONG_PREFIX = /^\\\\\?\\/;
+function samePath(a, b) {
+    const normal = (path) => {
+        const full = resolve(path.replace(LONG_PREFIX, ''));
+        return process.platform === 'win32' ? full.toLowerCase() : full;
+    };
+    return normal(a) === normal(b);
+}
+/** A hard link is the same file on disk as its target, so it has the same device and inode. */
+function sameFile(a, b) {
+    try {
+        const left = lstatSync(a);
+        const right = lstatSync(b);
+        return left.ino !== 0 && left.dev === right.dev && left.ino === right.ino;
+    }
+    catch {
+        return false;
+    }
+}
+function isLinkTo(path, target, isDir) {
+    try {
+        const meta = lstatSync(path);
+        if (meta.isSymbolicLink())
+            return samePath(readlinkSync(path), target);
+        return !isDir && meta.isFile() && sameFile(path, target);
+    }
+    catch {
+        return false;
+    }
+}
+/** Removes a link without touching what it points to. A Windows junction needs `rmdir`. */
+function removeLink(path, isDir) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (!isDir)
+            throw error;
+        rmdirSync(path);
+    }
+}
+/**
+ * A file the account does not have, for an entry whose link was refused: a copy of the shared one
+ * (with its time kept, so the newest-wins rule does not move it), so the account's settings load.
+ */
+function keepCopy(target, path, isDir) {
+    if (isDir || present(path) || !present(target))
+        return;
+    try {
+        copyFileSync(target, path);
+        const { atime, mtime } = statSync(target);
+        utimesSync(path, atime, mtime);
+    }
+    catch {
+        // The account simply keeps no copy; its sign-in and its own files are not affected.
+    }
+}
+/**
+ * Links one entry to its shared copy. A real entry found in the account folder (from before
+ * sharing, or a tool that replaced the link while saving) becomes the shared copy when there is
+ * none or it is newer; otherwise it is kept as a backup. If the link is then refused, every move
+ * is undone, so the account keeps what it had.
+ */
+function linkOne(name, target, path, isDir, linker) {
+    if (isLinkTo(path, target, isDir)) {
+        if (isDir)
+            mkdirSync(target, { recursive: true });
+        return { name, state: 'linked' };
+    }
+    const undo = [];
+    try {
+        if (isLink(path)) {
+            const previous = readlinkSync(path);
+            removeLink(path, isDir);
+            undo.push(() => nodeLinker.symlink(previous, path, isDir));
+        }
+        else if (present(path)) {
+            if (!present(target)) {
+                renameSync(path, target);
+                undo.push(() => renameSync(target, path));
+            }
+            else if (!isDir && modified(path) > modified(target)) {
+                const backup = backUp(target);
+                undo.push(() => renameSync(backup, target));
+                renameSync(path, target);
+                undo.push(() => renameSync(target, path));
+            }
+            else {
+                const backup = backUp(path);
+                undo.push(() => renameSync(backup, path));
+            }
+        }
+        if (isDir)
+            mkdirSync(target, { recursive: true });
+        createLink(target, path, isDir, linker);
+        return { name, state: 'linked' };
+    }
+    catch (error) {
+        for (const step of undo.reverse()) {
+            try {
+                step();
+            }
+            catch {
+                // The entry stays where that step left it; nothing further can be restored safely.
+            }
+        }
+        keepCopy(target, path, isDir);
+        return { name, state: 'unshared', reason: codeOf(error) };
+    }
+}
+/**
+ * Creates the account's runtime folder and links the shared entries into it. Never throws for a
+ * refused link: each entry is reported, and the account falls back to its own copy.
+ */
+export function linkSharedEntries(accountsDir, account, linker = nodeLinker) {
+    makePrivate(join(accountsDir, account.id));
+    makePrivate(homeDir(accountsDir, account.id));
+    const dir = configDir(accountsDir, account);
+    makePrivate(dir);
+    const shared = ensureSharedDir(accountsDir);
+    const entries = SHARED_ENTRIES.map(([name, isDir]) => linkOne(name, join(shared, name), join(dir, name), isDir, linker));
+    return { dir, entries };
+}
+/** Creates the account's runtime folder and links the shared entries into it. */
+export function ensureHome(accountsDir, account) {
+    return linkSharedEntries(accountsDir, account).dir;
+}
+const inside = (path, parent) => path === parent || path.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`);
+/**
+ * Refuses an agent folder that is (or is inside) a default tool folder, or that is not inside
+ * the harness's own accounts folder.
+ */
+export function assertIsolated(accountsDir, dir) {
+    const defaults = ['.codex', '.claude', '.pi'].map((name) => join(homedir() || '/', name));
+    if (defaults.some((folder) => inside(dir, folder)) || !inside(dir, accountsDir)) {
+        throw new HarnessError('account_required', 'A session cannot start outside its isolated account folder.');
+    }
+}
+function sessionEnv(dir, inherited) {
+    const env = {};
+    for (const name of inheritedCredentialVars(inherited))
+        env[name] = null;
+    env.PI_CODING_AGENT_DIR = dir;
+    return env;
+}
+/** Variables to set, or remove (`null`), when launching a session for this account. */
+export function launchEnv(accountsDir, account, inherited = process.env) {
+    const dir = ensureHome(accountsDir, account);
+    assertIsolated(accountsDir, dir);
+    return sessionEnv(dir, inherited);
+}
+export function accountContext(accountsDir, account) {
+    const { dir, entries } = linkSharedEntries(accountsDir, account);
+    assertIsolated(accountsDir, dir);
+    return { id: account.id, provider: 'pi', label: account.label, env: sessionEnv(dir, process.env), configDir: dir, sharing: entries };
+}
+/** The process environment for a `pi` process launched on behalf of this account. */
+export function processEnv(account, inherited = process.env) {
+    const env = {};
+    for (const [name, value] of Object.entries(inherited))
+        if (value !== undefined)
+            env[name] = value;
+    for (const [name, value] of Object.entries(account.env)) {
+        if (value === null)
+            delete env[name];
+        else
+            env[name] = value;
+    }
+    return env;
+}

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

@@ -0,0 +1,16 @@
+export interface SecretStore {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** `<account id>/<secret name>`: the key an account's secret is stored under. */
+export declare const secretKey: (accountId: string, name: string) => string;
+/** Secrets held only for the life of the process. For tests and throwaway runs. */
+export declare function memorySecretStore(initial?: Record<string, string>): SecretStore & {
+    values: Map<string, string>;
+};
+/**
+ * Secrets in one owner-only JSON file. For a host with no Keychain to offer; anything that can
+ * read the file can read every secret in it.
+ */
+export declare function fileSecretStore(path: string): SecretStore;

package/dist/sdk/accounts/secrets.js

@@ -0,0 +1,40 @@
+// Where credentials live. The harness never writes a secret to its own files: it asks the
+// store the embedding application provides (a Keychain, an encrypted vault), by key.
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { atomicWrite, readJsonOr } from "../core/fs.js";
+/** `<account id>/<secret name>`: the key an account's secret is stored under. */
+export const secretKey = (accountId, name) => `${accountId}/${name}`;
+/** Secrets held only for the life of the process. For tests and throwaway runs. */
+export function memorySecretStore(initial = {}) {
+    const values = new Map(Object.entries(initial));
+    return {
+        values,
+        get: async (key) => values.get(key) ?? null,
+        set: async (key, value) => void values.set(key, value),
+        delete: async (key) => void values.delete(key)
+    };
+}
+/**
+ * Secrets in one owner-only JSON file. For a host with no Keychain to offer; anything that can
+ * read the file can read every secret in it.
+ */
+export function fileSecretStore(path) {
+    const read = () => readJsonOr(path, {});
+    const write = (values) => {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        atomicWrite(path, `${JSON.stringify(values, null, 2)}\n`);
+        chmodSync(path, 0o600);
+    };
+    return {
+        get: async (key) => read()[key] ?? null,
+        set: async (key, value) => write({ ...read(), [key]: value }),
+        delete: async (key) => {
+            const values = read();
+            if (key in values) {
+                delete values[key];
+                write(values);
+            }
+        }
+    };
+}

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

@@ -0,0 +1,114 @@
+/** The only provider the harness runs. Records of other providers are kept in the file and ignored. */
+export declare const PROVIDER = "pi";
+export interface Account {
+    id: string;
+    provider: string;
+    label: string;
+    /** `subscription` (a provider's own sign-in) or `apiKey`. */
+    authKind: string;
+    credentialStore?: string;
+    createdAt: string;
+}
+export interface Pool {
+    id: string;
+    provider: string;
+    label: string;
+    accountIds: string[];
+}
+interface Registry {
+    accounts: Account[];
+    defaults: Record<string, string>;
+    pools: Pool[];
+    migratedProviderKeys: boolean;
+}
+export interface Limit {
+    id: string;
+    label: string;
+    usedPercent?: number | null;
+    resetsAt?: string | null;
+    windowMinutes?: number | null;
+    /** `allowed`, `warning`, or `rejected` when the provider reports it. */
+    status?: string | null;
+}
+export interface Issue {
+    /** `auth_expired`, `rate_limited`, `quota`, `network`, or `unknown`. */
+    category: string;
+    message: string;
+    at: string;
+    resetsAt: string | null;
+}
+export interface AccountState {
+    /** `ok`, `limited`, `auth_expired`, `signed_out`, `error`, or `unknown`. */
+    health: string;
+    signedIn: boolean | null;
+    authMethod: string | null;
+    plan: string | null;
+    identity: string | null;
+    limits: Limit[];
+    lastError: Issue | null;
+    lastCheckedAt: string | null;
+    cliVersion: string | null;
+    /** Features detected for this account, e.g. `models:12`, `provider:anthropic`. */
+    capabilities: string[];
+    /** Providers with a stored credential (names only). */
+    piProviders: string[];
+}
+export declare const emptyState: () => AccountState;
+export type AccountView = Account & {
+    isDefault: boolean;
+    state: AccountState;
+};
+export interface AccountsOverview {
+    accounts: AccountView[];
+    pools: Pool[];
+    defaults: Record<string, string>;
+}
+export interface AuditEntry {
+    at: string;
+    accountId: string | null;
+    action: string;
+    detail: string;
+}
+export declare function loadRegistry(dir: string): Registry;
+export declare function saveRegistry(dir: string, registry: Registry): void;
+export declare function loadState(dir: string, accountId: string): AccountState;
+/** Replaces anything that looks like a token so audit lines and stored errors never hold secrets. */
+export declare function scrub(text: string): string;
+export declare function audit(dir: string, accountId: string | null, action: string, detail: string): void;
+/** The newest audit entries first, optionally for one account. */
+export declare function readAudit(dir: string, accountId?: string | null, limit?: number): AuditEntry[];
+export declare const isLimitCategory: (category: string) => boolean;
+/**
+ * Whether a `rate_limited` or `quota` error still counts. With a reset time it counts until
+ * then; without one it counts for a short while after it was recorded.
+ */
+export declare function limitErrorActive(issue: Issue): boolean;
+export declare function deriveHealth(state: AccountState): string;
+/** Read-modify-write on one account's state. Returns the previous health and the new state. */
+export declare function updateState(dir: string, accountId: string, change: (state: AccountState) => void): {
+    previous: string;
+    state: AccountState;
+};
+export declare function find(dir: string, accountId: string): Account;
+/**
+ * Chooses the account for a new session: the explicit account, else the pool's first usable
+ * account, else the default, else the first account. It never skips to another one silently.
+ */
+export declare function resolve(dir: string, accountId?: string | null, poolId?: string | null): Account;
+/** The default account, if any exists. */
+export declare function defaultAccount(dir: string): Account | null;
+export declare function summaryAuthentication(dir: string): 'authenticated' | 'unauthenticated' | 'unknown';
+export declare function overview(dir: string): AccountsOverview;
+export declare function cleanLabel(label: string): string;
+export declare function addAccount(dir: string, label: string, authKind: string): Account;
+export declare function renameAccount(dir: string, accountId: string, label: string): void;
+export declare function setDefault(dir: string, accountId: string): Account;
+/** Drops the account from the registry, its pools, and the default. Its folder and secrets are the caller's to remove. */
+export declare function forgetAccount(dir: string, account: Account): void;
+export declare function savePool(dir: string, pool: {
+    id?: string;
+    label: string;
+    accountIds: string[];
+}): Pool;
+export declare function removePool(dir: string, poolId: string): void;
+export {};