@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/security/platform-secure-store-node.js

@@ -0,0 +1,311 @@
+import { execFile, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ELIZA_AGENT_VAULT_SERVICE, keychainAccountForSecretKind, } from "./agent-vault-id";
+const execFileAsync = promisify(execFile);
+function isDarwin() {
+    return process.platform === "darwin";
+}
+function isLinux() {
+    return process.platform === "linux";
+}
+/**
+ * Write a password to the macOS Keychain via stdin to avoid argv exposure.
+ * The `security add-generic-password` command reads from stdin when `-w`
+ * is the last argument with no value. It prompts twice (password + retype),
+ * so we write the value twice separated by a newline.
+ */
+function keychainSetViaStdin(args, password) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("security", args, {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stderr = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(Object.assign(new Error(stderr.trim() || `security exited ${code}`), {
+                stderr,
+                code,
+            }));
+        });
+        // Swallow EPIPE if security exits before reading stdin (e.g. arg error).
+        // Without this, Node emits an unhandled error and may crash the process.
+        child.stdin.on("error", () => { });
+        // Write password twice (password + retype) then close stdin
+        child.stdin.write(`${password}\n${password}\n`, () => {
+            child.stdin.end();
+        });
+    });
+}
+function secretToolStoreWithStdin(args, secretLine) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("secret-tool", args, {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stderr = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(Object.assign(new Error(stderr.trim() || `secret-tool exited ${code}`), {
+                stderr,
+                code,
+            }));
+        });
+        const line = secretLine.endsWith("\n") ? secretLine : `${secretLine}\n`;
+        child.stdin.write(line, "utf8");
+        child.stdin.end();
+    });
+}
+/**
+ * Check if `secret-tool` is available on PATH without spawning a shell.
+ * Iterates PATH entries directly and checks for the executable.
+ */
+function secretToolOnPathSync() {
+    if (process.platform === "win32")
+        return false;
+    const pathEnv = process.env.PATH ?? "";
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, "secret-tool");
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            // not in this dir
+        }
+    }
+    return false;
+}
+async function secretToolOnPath() {
+    return secretToolOnPathSync();
+}
+function macErrReason(stderr, code) {
+    const s = stderr.toLowerCase();
+    if (s.includes("could not be found") ||
+        s.includes("the specified item could not be found")) {
+        return { ok: false, reason: "not_found" };
+    }
+    if (s.includes("user canceled") || s.includes("user cancelled")) {
+        return { ok: false, reason: "denied" };
+    }
+    return {
+        ok: false,
+        reason: code === 44 || code === 45 ? "denied" : "error",
+        message: stderr.trim().slice(0, 300),
+    };
+}
+class MacOSKeychainPlatformSecureStore {
+    backend = "macos_keychain";
+    async isAvailable() {
+        try {
+            await execFileAsync("security", ["-h"], { encoding: "utf8" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async get(vaultId, kind) {
+        const account = keychainAccountForSecretKind(vaultId, kind);
+        try {
+            const { stdout, stderr: _stderr } = await execFileAsync("security", [
+                "find-generic-password",
+                "-s",
+                ELIZA_AGENT_VAULT_SERVICE,
+                "-a",
+                account,
+                "-w",
+            ], { encoding: "utf8" });
+            const value = stdout.trim();
+            if (!value) {
+                return { ok: false, reason: "not_found" };
+            }
+            return { ok: true, value };
+        }
+        catch (err) {
+            const e = err;
+            return macErrReason(String(e.stderr ?? err), e.code ?? null);
+        }
+    }
+    async set(vaultId, kind, value) {
+        const account = keychainAccountForSecretKind(vaultId, kind);
+        try {
+            // Pass password via stdin instead of argv to avoid exposure via `ps`.
+            // The `-w` flag (last, with no value) triggers stdin read mode.
+            await keychainSetViaStdin([
+                "add-generic-password",
+                "-s",
+                ELIZA_AGENT_VAULT_SERVICE,
+                "-a",
+                account,
+                "-U",
+                "-w",
+            ], value);
+            return { ok: true };
+        }
+        catch (err) {
+            const stderr = String(err.stderr ?? err);
+            return {
+                ok: false,
+                reason: "error",
+                message: stderr.trim().slice(0, 300),
+            };
+        }
+    }
+    async delete(vaultId, kind) {
+        const account = keychainAccountForSecretKind(vaultId, kind);
+        try {
+            await execFileAsync("security", [
+                "delete-generic-password",
+                "-s",
+                ELIZA_AGENT_VAULT_SERVICE,
+                "-a",
+                account,
+            ]);
+        }
+        catch {
+            // ignore — item may not exist
+        }
+    }
+}
+/** Linux: `secret-tool` from libsecret (GNOME Keyring / KWallet Secret Service). */
+class LinuxSecretToolPlatformSecureStore {
+    backend = "linux_secret_service";
+    async isAvailable() {
+        return secretToolOnPath();
+    }
+    account(vaultId, kind) {
+        return keychainAccountForSecretKind(vaultId, kind);
+    }
+    async get(vaultId, kind) {
+        const account = this.account(vaultId, kind);
+        try {
+            const { stdout } = await execFileAsync("secret-tool", ["lookup", "service", ELIZA_AGENT_VAULT_SERVICE, "account", account], { encoding: "utf8" });
+            const value = stdout.trim();
+            if (!value)
+                return { ok: false, reason: "not_found" };
+            return { ok: true, value };
+        }
+        catch (err) {
+            const e = err;
+            const stderr = String(e.stderr ?? "");
+            if (e.code === 1 || stderr.includes("not found")) {
+                return { ok: false, reason: "not_found" };
+            }
+            return {
+                ok: false,
+                reason: "error",
+                message: stderr.trim().slice(0, 300),
+            };
+        }
+    }
+    async set(vaultId, kind, value) {
+        const account = this.account(vaultId, kind);
+        try {
+            await secretToolStoreWithStdin([
+                "store",
+                "--label=Eliza agent wallet",
+                "service",
+                ELIZA_AGENT_VAULT_SERVICE,
+                "account",
+                account,
+            ], value);
+            return { ok: true };
+        }
+        catch (err) {
+            const e = err;
+            return {
+                ok: false,
+                reason: "error",
+                message: String(e.stderr ?? err)
+                    .trim()
+                    .slice(0, 300),
+            };
+        }
+    }
+    async delete(vaultId, kind) {
+        const account = this.account(vaultId, kind);
+        try {
+            await execFileAsync("secret-tool", [
+                "clear",
+                "service",
+                ELIZA_AGENT_VAULT_SERVICE,
+                "account",
+                account,
+            ]);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+class NonePlatformSecureStore {
+    backend;
+    constructor(backend = "none") {
+        this.backend = backend;
+    }
+    async isAvailable() {
+        return false;
+    }
+    async get() {
+        return { ok: false, reason: "unavailable" };
+    }
+    async set() {
+        return { ok: false, reason: "unavailable" };
+    }
+    async delete() { }
+}
+/**
+ * Node-side factory: macOS Keychain, Linux `secret-tool`, or unavailable placeholder.
+ * Windows Credential Manager is not wired yet (`none`).
+ */
+export function createNodePlatformSecureStore() {
+    if (isDarwin()) {
+        return new MacOSKeychainPlatformSecureStore();
+    }
+    if (isLinux()) {
+        return new LinuxSecretToolPlatformSecureStore();
+    }
+    return new NonePlatformSecureStore();
+}
+const WALLET_OS_STORE_TRUE_VALUES = new Set(["1", "true", "on", "yes"]);
+const WALLET_OS_STORE_FALSE_VALUES = new Set(["0", "false", "off", "no"]);
+export function isNodePlatformSecureStoreDefaultAvailable() {
+    if (isDarwin())
+        return true;
+    if (isLinux())
+        return secretToolOnPathSync();
+    return false;
+}
+/**
+ * Explicit override: `ELIZA_WALLET_OS_STORE=0|false|off|no` disables this path.
+ * When unset, default on for supported local secure stores.
+ */
+export function isWalletOsStoreReadEnabled() {
+    const raw = process.env.ELIZA_WALLET_OS_STORE?.trim().toLowerCase();
+    if (raw) {
+        if (WALLET_OS_STORE_TRUE_VALUES.has(raw))
+            return true;
+        if (WALLET_OS_STORE_FALSE_VALUES.has(raw))
+            return false;
+    }
+    return isNodePlatformSecureStoreDefaultAvailable();
+}

package/security/platform-secure-store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Cross-platform OS secret store — **contract only** (no native bindings here).
+ *
+ * **Spec:** [Platform secure store (design)](../../../../docs/guides/platform-secure-store.md)
+ *
+ * Implementations live per runtime (e.g. Electrobun main process, Node CLI with
+ * native addons). Wallet and other callers depend on this interface + shared
+ * `vaultId` / `secretKind` conventions.
+ */
+/** Logical secret slot within a vault (one state profile). */
+export type SecureStoreSecretKind = "wallet.evm_private_key" | "wallet.solana_private_key" | "steward.api_url" | "steward.agent_id" | "steward.agent_token";
+export type SecureStoreUnavailableReason = "not_found" | "denied" | "unavailable" | "error";
+export type SecureStoreGetResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: SecureStoreUnavailableReason;
+    message?: string;
+};
+export type SecureStoreSetResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: SecureStoreUnavailableReason;
+    message?: string;
+};
+/**
+ * Which native API backs this implementation (for diagnostics and support).
+ */
+export type PlatformSecureStoreBackend = "macos_keychain" | "windows_credential_manager" | "linux_secret_service"
+/** Encrypted file or DPAPI-like blob under state dir — only after explicit consent. */
+ | "file_encrypted_fallback"
+/** Legacy / tests: no OS integration. */
+ | "none";
+/**
+ * Platform-provided secret storage scoped by `vaultId` (see design doc for derivation).
+ */
+export interface PlatformSecureStore {
+    readonly backend: PlatformSecureStoreBackend;
+    get(vaultId: string, kind: SecureStoreSecretKind): Promise<SecureStoreGetResult>;
+    set(vaultId: string, kind: SecureStoreSecretKind, value: string): Promise<SecureStoreSetResult>;
+    delete(vaultId: string, kind: SecureStoreSecretKind): Promise<void>;
+    /** True if the backend can run on this host right now (e.g. Secret Service up). */
+    isAvailable(): Promise<boolean>;
+}
+//# sourceMappingURL=platform-secure-store.d.ts.map

package/security/platform-secure-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-secure-store.d.ts","sourceRoot":"","sources":["../../../../../src/security/platform-secure-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,qBAAqB,GAC7B,wBAAwB,GACxB,2BAA2B,GAC3B,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,CAAC;AAE1B,MAAM,MAAM,4BAA4B,GACpC,WAAW,GACX,QAAQ,GACR,aAAa,GACb,OAAO,CAAC;AAEZ,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3B;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,4BAA4B,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEN,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,4BAA4B,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,gBAAgB,GAChB,4BAA4B,GAC5B,sBAAsB;AACxB,uFAAuF;GACrF,yBAAyB;AAC3B,yCAAyC;GACvC,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAE7C,GAAG,CACD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC,GAAG,CACD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,qBAAqB,EAC3B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE,mFAAmF;IACnF,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC"}

package/security/platform-secure-store.js

@@ -0,0 +1,10 @@
+/**
+ * Cross-platform OS secret store — **contract only** (no native bindings here).
+ *
+ * **Spec:** [Platform secure store (design)](../../../../docs/guides/platform-secure-store.md)
+ *
+ * Implementations live per runtime (e.g. Electrobun main process, Node CLI with
+ * native addons). Wallet and other callers depend on this interface + shared
+ * `vaultId` / `secretKind` conventions.
+ */
+export {};

package/security/wallet-os-store-actions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Wallet-key migration helpers for `EVM_PRIVATE_KEY` / `SOLANA_PRIVATE_KEY`.
+ *
+ * Storage layout (post-unification):
+ *   - The shared vault is the source of truth. Keys are written at the
+ *     bare `EVM_PRIVATE_KEY` / `SOLANA_PRIVATE_KEY` slots so the existing
+ *     inventory categorizer (`categorizeKey`) surfaces them under
+ *     Settings → Vault → Secrets in the "Wallet" group automatically.
+ *   - The OS keystore (Keychain / libsecret) remains a one-shot read
+ *     source for migrating off the legacy split-storage layout. We never
+ *     write back into it from this module.
+ *
+ * Hydration (see `hydrate-wallet-keys-from-platform-store.ts`) reads the
+ * vault first and copies the OS-keystore value across on the next boot
+ * when the OS-keystore read path is enabled (default on supported desktops,
+ * or explicitly via `ELIZA_WALLET_OS_STORE=1`).
+ */
+import { setEntryMeta } from "@elizaos/vault";
+/**
+ * Remove main wallet keys from BOTH the vault and the OS keystore.
+ * Used by `POST /api/agent/reset` and the equivalent CLI flow.
+ */
+export declare function deleteWalletSecretsFromOsStore(): Promise<void>;
+export type MigrateWalletPrivateKeysToOsStoreResult = {
+    migrated: string[];
+    failed: string[];
+    /** Reserved for compat — vault writes are always available. Always undefined now. */
+    unavailable?: boolean;
+};
+/**
+ * Copies wallet keys from `process.env` and/or persisted `config.env` into
+ * the shared vault, strips them from saved config, and ensures
+ * `process.env` holds the values for the running process.
+ *
+ * Idempotent: if the vault already holds a key, the env value (if any)
+ * is left in place but not re-written to the vault.
+ */
+export declare function migrateWalletPrivateKeysToOsStore(): Promise<MigrateWalletPrivateKeysToOsStoreResult>;
+/**
+ * Re-export for callers that want to write the wallet metadata explicitly
+ * (currently unused by external code; the inventory categorizer already
+ * recognizes `EVM_PRIVATE_KEY` / `SOLANA_PRIVATE_KEY` via heuristic).
+ */
+export { setEntryMeta };
+//# sourceMappingURL=wallet-os-store-actions.d.ts.map

package/security/wallet-os-store-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-os-store-actions.d.ts","sourceRoot":"","sources":["../../../../../src/security/wallet-os-store-actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAc9C;;;GAGG;AACH,wBAAsB,8BAA8B,IAAI,OAAO,CAAC,IAAI,CAAC,CAqBpE;AAED,MAAM,MAAM,uCAAuC,GAAG;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qFAAqF;IACrF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,iCAAiC,IAAI,OAAO,CAAC,uCAAuC,CAAC,CAoE1G;AAED;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/security/wallet-os-store-actions.js

@@ -0,0 +1,125 @@
+/**
+ * Wallet-key migration helpers for `EVM_PRIVATE_KEY` / `SOLANA_PRIVATE_KEY`.
+ *
+ * Storage layout (post-unification):
+ *   - The shared vault is the source of truth. Keys are written at the
+ *     bare `EVM_PRIVATE_KEY` / `SOLANA_PRIVATE_KEY` slots so the existing
+ *     inventory categorizer (`categorizeKey`) surfaces them under
+ *     Settings → Vault → Secrets in the "Wallet" group automatically.
+ *   - The OS keystore (Keychain / libsecret) remains a one-shot read
+ *     source for migrating off the legacy split-storage layout. We never
+ *     write back into it from this module.
+ *
+ * Hydration (see `hydrate-wallet-keys-from-platform-store.ts`) reads the
+ * vault first and copies the OS-keystore value across on the next boot
+ * when the OS-keystore read path is enabled (default on supported desktops,
+ * or explicitly via `ELIZA_WALLET_OS_STORE=1`).
+ */
+import { loadElizaConfig, saveElizaConfig } from "@elizaos/agent";
+import { setEntryMeta } from "@elizaos/vault";
+import { sharedVault } from "../services/vault-mirror";
+import { deriveAgentVaultId } from "./agent-vault-id";
+import { createNodePlatformSecureStore, isWalletOsStoreReadEnabled, } from "./platform-secure-store-node";
+const WALLET_PAIRS = [
+    ["EVM_PRIVATE_KEY", "wallet.evm_private_key"],
+    ["SOLANA_PRIVATE_KEY", "wallet.solana_private_key"],
+];
+/**
+ * Remove main wallet keys from BOTH the vault and the OS keystore.
+ * Used by `POST /api/agent/reset` and the equivalent CLI flow.
+ */
+export async function deleteWalletSecretsFromOsStore() {
+    const vault = sharedVault();
+    for (const [envKey] of WALLET_PAIRS) {
+        if (await vault.has(envKey)) {
+            await vault.remove(envKey);
+        }
+    }
+    // Best-effort cleanup of the legacy OS keystore copy. We only attempt
+    // this when the user previously opted into the OS-keystore read path —
+    // otherwise the keystore was never written from this module.
+    if (!isWalletOsStoreReadEnabled()) {
+        return;
+    }
+    const store = createNodePlatformSecureStore();
+    if (!(await store.isAvailable())) {
+        return;
+    }
+    const vaultId = deriveAgentVaultId();
+    await store.delete(vaultId, "wallet.evm_private_key");
+    await store.delete(vaultId, "wallet.solana_private_key");
+}
+/**
+ * Copies wallet keys from `process.env` and/or persisted `config.env` into
+ * the shared vault, strips them from saved config, and ensures
+ * `process.env` holds the values for the running process.
+ *
+ * Idempotent: if the vault already holds a key, the env value (if any)
+ * is left in place but not re-written to the vault.
+ */
+export async function migrateWalletPrivateKeysToOsStore() {
+    const vault = sharedVault();
+    const migrated = [];
+    const failed = [];
+    const config = loadElizaConfig();
+    const persisted = config.env && typeof config.env === "object" && !Array.isArray(config.env)
+        ? config.env
+        : {};
+    for (const [envKey] of WALLET_PAIRS) {
+        const fromProcess = typeof process.env[envKey] === "string"
+            ? process.env[envKey]?.trim()
+            : "";
+        const fromConfig = typeof persisted[envKey] === "string"
+            ? String(persisted[envKey]).trim()
+            : "";
+        const value = fromProcess || fromConfig;
+        if (!value) {
+            continue;
+        }
+        if (await vault.has(envKey)) {
+            // Already migrated — don't overwrite a vault entry that may have
+            // been rotated since.
+            continue;
+        }
+        try {
+            await vault.set(envKey, value, {
+                sensitive: true,
+                caller: "wallet-migrate",
+            });
+            migrated.push(envKey);
+        }
+        catch (err) {
+            failed.push(envKey);
+            throw err instanceof Error
+                ? err
+                : new Error(`vault write failed for ${envKey}: ${String(err)}`);
+        }
+        if (!fromProcess) {
+            process.env[envKey] = value;
+        }
+    }
+    let dirty = false;
+    const nextEnv = { ...persisted };
+    for (const [envKey] of WALLET_PAIRS) {
+        if (typeof nextEnv[envKey] === "string") {
+            delete nextEnv[envKey];
+            dirty = true;
+        }
+    }
+    if (dirty) {
+        if (Object.keys(nextEnv).length === 0) {
+            delete config.env;
+        }
+        else {
+            config.env = nextEnv;
+        }
+        saveElizaConfig(config);
+    }
+    return { migrated, failed };
+}
+/**
+ * Re-export for callers that want to write the wallet metadata explicitly
+ * (currently unused by external code; the inventory categorizer already
+ * recognizes `EVM_PRIVATE_KEY` / `SOLANA_PRIVATE_KEY` via heuristic).
+ */
+export { setEntryMeta };

package/services/account-pool.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Multi-account selection brain.
+ *
+ * Owns the runtime decision "which `LinkedAccountConfig` should serve this
+ * request?" given a strategy (priority / round-robin / least-used /
+ * quota-aware), session affinity, and per-account health state.
+ *
+ * The pool never reads OAuth credentials directly — callers resolve them
+ * via `getAccessToken(providerId, accountId)` from `@elizaos/agent` once
+ * the pool returns an account. Health, priority, and usage live in this
+ * layer; the OAuth blob lives under `~/.eliza/auth/` (see WS1's
+ * `account-storage.ts`).
+ *
+ * Persistence: the pool layers rich metadata (priority, enabled, health,
+ * usage) on top of WS1's credential records. The metadata is written to
+ * `<ELIZA_HOME>/auth/_pool-metadata.json` atomically so it survives
+ * process restarts and is independent of WS3's eventual `eliza.json`
+ * field — when WS3 lands its CRUD API on top of `LinkedAccountsConfig`
+ * we can swap `createDefaultAccountPool()`'s deps without touching the
+ * pool itself.
+ */
+import type { LinkedAccountConfig, LinkedAccountProviderId, LinkedAccountsConfig } from "@elizaos/shared";
+export type Strategy = "priority" | "round-robin" | "least-used" | "quota-aware";
+export type PoolProviderId = LinkedAccountProviderId;
+export interface AccountPoolDeps {
+    /** Read the current `LinkedAccountsConfig` (live). */
+    readAccounts: () => Record<string, LinkedAccountConfig>;
+    /** Persist a single account's mutated fields. */
+    writeAccount: (account: LinkedAccountConfig) => Promise<void>;
+    /** Remove the metadata overlay for an account. */
+    deleteAccount?: (providerId: PoolProviderId, accountId: string) => Promise<void>;
+}
+export interface SelectInput {
+    providerId: PoolProviderId;
+    /** Stable session key for affinity (e.g. agent id + run id). */
+    sessionKey?: string;
+    /** Defaults to `"priority"`. */
+    strategy?: Strategy;
+    /** Explicit pool; defaults to all enabled accounts for `providerId`. */
+    accountIds?: string[];
+    /** Account IDs to skip (e.g. just-failed accounts). */
+    exclude?: string[];
+}
+interface AccountPoolSelectionRoute {
+    backend?: string;
+    accountId?: string;
+    accountIds?: string[];
+    strategy?: string;
+}
+interface AccountPoolSelectionConfig {
+    accountStrategies?: Partial<Record<PoolProviderId, unknown>>;
+    serviceRouting?: {
+        llmText?: AccountPoolSelectionRoute;
+    } | null;
+}
+export declare class AccountPool {
+    private readonly deps;
+    private readonly affinity;
+    private readonly roundRobinCursor;
+    constructor(deps: AccountPoolDeps);
+    select(input: SelectInput): Promise<LinkedAccountConfig | null>;
+    private filterEligible;
+    private applyStrategy;
+    list(providerId?: PoolProviderId): LinkedAccountConfig[];
+    get(accountId: string, providerId?: PoolProviderId): LinkedAccountConfig | null;
+    upsert(account: LinkedAccountConfig): Promise<void>;
+    deleteMetadata(providerId: PoolProviderId, accountId: string): Promise<void>;
+    recordCall(accountId: string, result: {
+        tokens?: number;
+        latencyMs?: number;
+        ok: boolean;
+        errorCode?: string;
+        model?: string;
+    }, opts?: {
+        providerId?: PoolProviderId;
+    }): Promise<void>;
+    refreshUsage(accountId: string, accessToken: string, opts?: {
+        codexAccountId?: string;
+        fetch?: typeof fetch;
+        providerId?: PoolProviderId;
+    }): Promise<void>;
+    markRateLimited(accountId: string, untilMs: number, detail?: string, opts?: {
+        providerId?: PoolProviderId;
+    }): Promise<void>;
+    markNeedsReauth(accountId: string, detail?: string, opts?: {
+        providerId?: PoolProviderId;
+    }): Promise<void>;
+    markInvalid(accountId: string, detail?: string, opts?: {
+        providerId?: PoolProviderId;
+    }): Promise<void>;
+    markHealthy(accountId: string, opts?: {
+        providerId?: PoolProviderId;
+    }): Promise<void>;
+    /**
+     * Re-probe accounts whose `health` is non-OK and whose `healthDetail.until`
+     * has passed (or is absent). Used by background sweepers to recover
+     * temporarily flagged accounts. We don't load access tokens here — the
+     * caller probes via `refreshUsage` separately.
+     */
+    reprobeFlagged(): Promise<string[]>;
+}
+export declare function __getDefaultAccountPoolSelectionForTests(providerId: PoolProviderId): {
+    strategy?: Strategy;
+    accountIds?: string[];
+};
+export declare function configureDefaultAccountPoolSelection(config?: AccountPoolSelectionConfig): void;
+/**
+ * Module-level singleton for the default pool wired against WS1's
+ * `account-storage` and the pool-owned metadata file. Plugins / runtime
+ * resolvers should import `getDefaultAccountPool()` rather than building
+ * a new pool. WS3 may later swap the default deps to read/write the
+ * `LinkedAccountsConfig` field directly out of `eliza.json`; consumers
+ * keep the same accessor.
+ */
+export declare function getDefaultAccountPool(): AccountPool;
+export declare function applyAccountPoolApiCredentials(opts?: {
+    activeBackend?: string | null;
+    accountStrategies?: AccountPoolSelectionConfig["accountStrategies"];
+    serviceRouting?: AccountPoolSelectionConfig["serviceRouting"];
+}): Promise<void>;
+export interface AccountPoolKeepAliveResult {
+    checked: number;
+    refreshed: number;
+    failed: number;
+}
+export declare function sweepAccountPoolKeepAlive(): Promise<AccountPoolKeepAliveResult>;
+export declare function startAccountPoolKeepAlive(intervalMs?: number): void;
+export declare function stopAccountPoolKeepAliveForTests(): void;
+/**
+ * Resets the cached singleton. Test-only.
+ */
+export declare function __resetDefaultAccountPoolForTests(): void;
+export type { LinkedAccountsConfig };
+//# sourceMappingURL=account-pool.d.ts.map