@elizaos/agent 2.0.0-alpha.441 → 2.0.0-alpha.501

package/packages/app-core/src/services/account-pool.js

@@ -0,0 +1,506 @@
+/**
+ * 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 `milady.json`
+ * field — when WS3 lands its CRUD API on top of `LinkedAccountsConfig`
+ * we can swap `createDefaultAccountPool()`'s deps without touching the
+ * pool itself.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getAccessToken as getSubscriptionAccessToken, listProviderAccounts, } from "@elizaos/agent";
+import { pollAnthropicUsage, pollCodexUsage, recordCall as recordUsageEntry, } from "./account-usage.js";
+const DEFAULT_RATE_LIMIT_BACKOFF_MS = 60_000;
+const QUOTA_AWARE_SKIP_PCT = 85;
+const SESSION_AFFINITY_MAX_ATTEMPTS = 3;
+export class AccountPool {
+    deps;
+    affinity = new Map();
+    roundRobinCursor = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // Selection.
+    async select(input) {
+        const all = this.deps.readAccounts();
+        const eligible = this.filterEligible(all, input);
+        if (eligible.length === 0)
+            return null;
+        if (input.sessionKey) {
+            const cached = this.affinity.get(input.sessionKey);
+            if (cached &&
+                cached.attempts < SESSION_AFFINITY_MAX_ATTEMPTS &&
+                eligible.some((a) => a.id === cached.accountId)) {
+                cached.attempts += 1;
+                const account = eligible.find((a) => a.id === cached.accountId);
+                if (account)
+                    return account;
+            }
+        }
+        const strategy = input.strategy ?? "priority";
+        const picked = this.applyStrategy(strategy, eligible, input.providerId);
+        if (!picked)
+            return null;
+        if (input.sessionKey) {
+            this.affinity.set(input.sessionKey, {
+                accountId: picked.id,
+                attempts: 1,
+            });
+        }
+        return picked;
+    }
+    filterEligible(all, input) {
+        const exclude = new Set(input.exclude ?? []);
+        const explicit = input.accountIds && input.accountIds.length > 0
+            ? new Set(input.accountIds)
+            : null;
+        const now = Date.now();
+        return Object.values(all).filter((account) => {
+            if (account.providerId !== input.providerId)
+                return false;
+            if (!account.enabled)
+                return false;
+            if (exclude.has(account.id))
+                return false;
+            if (explicit && !explicit.has(account.id))
+                return false;
+            if (account.health === "ok")
+                return true;
+            // Allow rate-limited accounts back in once their reset has passed.
+            if (account.health === "rate-limited" &&
+                typeof account.healthDetail?.until === "number" &&
+                account.healthDetail.until < now) {
+                return true;
+            }
+            return false;
+        });
+    }
+    applyStrategy(strategy, eligible, providerId) {
+        if (eligible.length === 0)
+            return null;
+        if (eligible.length === 1)
+            return eligible[0] ?? null;
+        switch (strategy) {
+            case "round-robin": {
+                const sorted = [...eligible].sort(byPriorityThenAge);
+                const cursor = (this.roundRobinCursor.get(providerId) ?? -1) + 1;
+                const index = cursor % sorted.length;
+                this.roundRobinCursor.set(providerId, index);
+                return sorted[index] ?? null;
+            }
+            case "least-used": {
+                return [...eligible].sort(byLeastUsedThenPriority)[0] ?? null;
+            }
+            case "quota-aware": {
+                const underQuota = eligible.filter((a) => (a.usage?.sessionPct ?? 0) < QUOTA_AWARE_SKIP_PCT);
+                const pool = underQuota.length > 0 ? underQuota : eligible;
+                return [...pool].sort(byPriorityThenAge)[0] ?? null;
+            }
+            default:
+                return [...eligible].sort(byPriorityThenAge)[0] ?? null;
+        }
+    }
+    // CRUD — used by accounts-routes.ts as the single source of truth for
+    // LinkedAccountConfig records. Both reads and writes go through here so
+    // changes from the HTTP API and from runtime mutations (markRateLimited,
+    // refreshUsage, recordCall) stay consistent.
+    list(providerId) {
+        const all = Object.values(this.deps.readAccounts());
+        if (!providerId)
+            return all;
+        return all.filter((a) => a.providerId === providerId);
+    }
+    get(accountId) {
+        return findAccountById(this.deps.readAccounts(), accountId);
+    }
+    async upsert(account) {
+        await this.deps.writeAccount(account);
+    }
+    async deleteMetadata(providerId, accountId) {
+        if (!this.deps.deleteAccount)
+            return;
+        await this.deps.deleteAccount(providerId, accountId);
+    }
+    // Mutations.
+    async recordCall(accountId, result) {
+        const account = findAccountById(this.deps.readAccounts(), accountId);
+        if (!account)
+            return;
+        recordUsageEntry(account.providerId, account.id, result);
+        const next = {
+            ...account,
+            lastUsedAt: Date.now(),
+        };
+        await this.deps.writeAccount(next);
+    }
+    async refreshUsage(accountId, accessToken, opts) {
+        const account = findAccountById(this.deps.readAccounts(), accountId);
+        if (!account)
+            return;
+        let usage;
+        if (account.providerId === "anthropic-subscription") {
+            usage = await pollAnthropicUsage(accessToken, opts?.fetch);
+        }
+        else if (account.providerId === "openai-codex") {
+            const codexAccountId = opts?.codexAccountId ?? account.organizationId;
+            if (!codexAccountId) {
+                throw new Error(`[AccountPool] Codex usage probe needs the OpenAI account_id (account ${accountId} has no organizationId).`);
+            }
+            usage = await pollCodexUsage(accessToken, codexAccountId, opts?.fetch);
+        }
+        else {
+            // No probe defined for direct API providers.
+            return;
+        }
+        await this.deps.writeAccount({
+            ...account,
+            health: "ok",
+            usage,
+        });
+    }
+    async markRateLimited(accountId, untilMs, detail) {
+        const account = findAccountById(this.deps.readAccounts(), accountId);
+        if (!account)
+            return;
+        const healthDetail = {
+            until: Number.isFinite(untilMs) && untilMs > Date.now()
+                ? untilMs
+                : Date.now() + DEFAULT_RATE_LIMIT_BACKOFF_MS,
+            lastChecked: Date.now(),
+            ...(detail ? { lastError: detail } : {}),
+        };
+        await this.deps.writeAccount({
+            ...account,
+            health: "rate-limited",
+            healthDetail,
+        });
+    }
+    async markNeedsReauth(accountId, detail) {
+        const account = findAccountById(this.deps.readAccounts(), accountId);
+        if (!account)
+            return;
+        await this.deps.writeAccount({
+            ...account,
+            health: "needs-reauth",
+            healthDetail: {
+                lastChecked: Date.now(),
+                ...(detail ? { lastError: detail } : {}),
+            },
+        });
+    }
+    async markInvalid(accountId, detail) {
+        const account = findAccountById(this.deps.readAccounts(), accountId);
+        if (!account)
+            return;
+        await this.deps.writeAccount({
+            ...account,
+            health: "invalid",
+            healthDetail: {
+                lastChecked: Date.now(),
+                ...(detail ? { lastError: detail } : {}),
+            },
+        });
+    }
+    async markHealthy(accountId) {
+        const account = findAccountById(this.deps.readAccounts(), accountId);
+        if (!account)
+            return;
+        if (account.health === "ok")
+            return;
+        await this.deps.writeAccount({
+            ...account,
+            health: "ok",
+            ...(account.healthDetail ? { healthDetail: undefined } : {}),
+        });
+    }
+    /**
+     * 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.
+     */
+    async reprobeFlagged() {
+        const all = this.deps.readAccounts();
+        const now = Date.now();
+        const ready = [];
+        for (const account of Object.values(all)) {
+            if (account.health === "ok")
+                continue;
+            if (account.health === "rate-limited") {
+                const until = account.healthDetail?.until;
+                if (typeof until === "number" && until > now)
+                    continue;
+            }
+            ready.push(account.id);
+        }
+        return ready;
+    }
+}
+function poolRecordKey(providerId, accountId) {
+    return `${providerId}:${accountId}`;
+}
+function findAccountById(all, accountId) {
+    const direct = all[accountId];
+    if (direct)
+        return direct;
+    return Object.values(all).find((account) => account.id === accountId) ?? null;
+}
+function byPriorityThenAge(a, b) {
+    if (a.priority !== b.priority)
+        return a.priority - b.priority;
+    const aLast = a.lastUsedAt ?? 0;
+    const bLast = b.lastUsedAt ?? 0;
+    return aLast - bLast; // older first
+}
+function byLeastUsedThenPriority(a, b) {
+    const aPct = a.usage?.sessionPct ?? 0;
+    const bPct = b.usage?.sessionPct ?? 0;
+    if (aPct !== bPct)
+        return aPct - bPct;
+    return byPriorityThenAge(a, b);
+}
+function authRoot() {
+    return path.join(process.env.ELIZA_HOME || path.join(os.homedir(), ".eliza"), "auth");
+}
+function metadataFile() {
+    return path.join(authRoot(), "_pool-metadata.json");
+}
+function isPoolProviderId(value) {
+    return (value === "anthropic-subscription" ||
+        value === "openai-codex" ||
+        value === "anthropic-api" ||
+        value === "openai-api");
+}
+function readMetaStore() {
+    const file = metadataFile();
+    if (!existsSync(file)) {
+        return {};
+    }
+    try {
+        const raw = readFileSync(file, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Corrupt file — fall through to empty store. Next write rewrites it.
+    }
+    return {};
+}
+function writeMetaStore(store) {
+    const file = metadataFile();
+    const dir = path.dirname(file);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify(store, null, 2), {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    renameSync(tmp, file);
+}
+function recordToLinked(record, meta, providerId, defaultPriority) {
+    return {
+        id: record.id,
+        providerId,
+        label: meta?.label ?? record.label,
+        source: record.source,
+        enabled: meta?.enabled ?? true,
+        priority: meta?.priority ?? defaultPriority,
+        createdAt: record.createdAt,
+        health: meta?.health ?? "ok",
+        ...(record.lastUsedAt !== undefined
+            ? { lastUsedAt: record.lastUsedAt }
+            : {}),
+        ...(meta?.healthDetail ? { healthDetail: meta.healthDetail } : {}),
+        ...(meta?.usage ? { usage: meta.usage } : {}),
+        ...(record.organizationId ? { organizationId: record.organizationId } : {}),
+        ...(record.userId ? { userId: record.userId } : {}),
+        ...(record.email ? { email: record.email } : {}),
+    };
+}
+function loadAllAccounts() {
+    const subscriptionProviders = [
+        "anthropic-subscription",
+        "openai-codex",
+    ];
+    const meta = readMetaStore();
+    const out = {};
+    for (const provider of subscriptionProviders) {
+        const records = listProviderAccounts(provider);
+        let priorityCounter = 0;
+        const sorted = [...records].sort((a, b) => a.createdAt - b.createdAt);
+        for (const record of sorted) {
+            const providerMeta = meta[provider]?.[record.id];
+            out[poolRecordKey(provider, record.id)] = recordToLinked(record, providerMeta, provider, priorityCounter);
+            priorityCounter += 1;
+        }
+    }
+    return out;
+}
+async function persistAccount(account) {
+    if (!isPoolProviderId(account.providerId))
+        return;
+    const store = readMetaStore();
+    if (!store[account.providerId]) {
+        store[account.providerId] = {};
+    }
+    store[account.providerId][account.id] = {
+        label: account.label,
+        enabled: account.enabled,
+        priority: account.priority,
+        health: account.health,
+        ...(account.healthDetail ? { healthDetail: account.healthDetail } : {}),
+        ...(account.usage ? { usage: account.usage } : {}),
+    };
+    writeMetaStore(store);
+}
+async function deleteAccountMeta(providerId, accountId) {
+    const store = readMetaStore();
+    const bucket = store[providerId];
+    if (!bucket)
+        return;
+    if (!(accountId in bucket))
+        return;
+    delete bucket[accountId];
+    writeMetaStore(store);
+}
+/**
+ * Symbol-keyed shim contract consumed by plugin-anthropic's
+ * `credential-store.ts`. Kept narrow so the plugin doesn't have to import
+ * the full pool surface (or the rest of `@elizaos/app-core`).
+ */
+const ANTHROPIC_POOL_SHIM_SYMBOL = Symbol.for("milady.account-pool.anthropic.v1");
+/**
+ * Shim used by plugin-agent-orchestrator. The orchestrator can't depend on
+ * `@elizaos/app-core`, so it discovers the pool via this symbol on
+ * `globalThis`. Returns the picked account + access token in one shot
+ * because the orchestrator only needs to inject the env vars and forget.
+ */
+const ORCHESTRATOR_POOL_SHIM_SYMBOL = Symbol.for("milady.account-pool.orchestrator.v1");
+/**
+ * Shim used by `applySubscriptionCredentials` in `@elizaos/agent` to pick
+ * the active Codex account when applying `OPENAI_API_KEY`. Lives behind
+ * a symbol so the agent package doesn't need to depend on app-core.
+ */
+const SUBSCRIPTION_SELECTOR_SHIM_SYMBOL = Symbol.for("milady.account-pool.subscription-selector.v1");
+let cachedDefaultPool = null;
+/**
+ * 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 `milady.json`; consumers
+ * keep the same accessor.
+ */
+export function getDefaultAccountPool() {
+    if (!cachedDefaultPool) {
+        cachedDefaultPool = new AccountPool({
+            readAccounts: () => loadAllAccounts(),
+            writeAccount: persistAccount,
+            deleteAccount: deleteAccountMeta,
+        });
+        installAnthropicShim(cachedDefaultPool);
+        installOrchestratorShim(cachedDefaultPool);
+        installSubscriptionSelectorShim(cachedDefaultPool);
+    }
+    return cachedDefaultPool;
+}
+/**
+ * Install the `globalThis`-keyed shim that plugin-anthropic's
+ * credential-store reads. Idempotent — repeated installs replace the
+ * previous shim.
+ */
+function installAnthropicShim(pool) {
+    if (typeof globalThis === "undefined")
+        return;
+    const shim = {
+        selectAnthropicSubscription: async (opts) => {
+            const account = await pool.select({
+                providerId: "anthropic-subscription",
+                sessionKey: opts?.sessionKey,
+                exclude: opts?.exclude,
+            });
+            if (!account)
+                return null;
+            // expiresAt is sourced from the underlying credential blob via
+            // `loadCredentials`; we cache it on the cached account record's
+            // lastUsedAt is independent. The plugin only uses expiresAt as a
+            // hint for cache TTL, so an Infinity fallback is acceptable.
+            return { id: account.id, expiresAt: Number.POSITIVE_INFINITY };
+        },
+        getAccessToken: (providerId, accountId) => getSubscriptionAccessToken(providerId, accountId),
+        markInvalid: (accountId, detail) => pool.markInvalid(accountId, detail),
+        markRateLimited: (accountId, untilMs, detail) => pool.markRateLimited(accountId, untilMs, detail),
+    };
+    globalThis[ANTHROPIC_POOL_SHIM_SYMBOL] = shim;
+}
+function installOrchestratorShim(pool) {
+    if (typeof globalThis === "undefined")
+        return;
+    const shim = {
+        pickAnthropicTokenForSpawn: async ({ sessionKey }) => {
+            const account = await pool.select({
+                providerId: "anthropic-subscription",
+                sessionKey,
+            });
+            if (!account)
+                return null;
+            const token = await getSubscriptionAccessToken("anthropic-subscription", account.id);
+            if (!token)
+                return null;
+            return { accessToken: token, accountId: account.id };
+        },
+        markRateLimited: (accountId, untilMs, detail) => {
+            void pool.markRateLimited(accountId, untilMs, detail);
+        },
+        markInvalid: (accountId, detail) => {
+            void pool.markInvalid(accountId, detail);
+        },
+        markNeedsReauth: (accountId, detail) => {
+            void pool.markNeedsReauth(accountId, detail);
+        },
+    };
+    globalThis[ORCHESTRATOR_POOL_SHIM_SYMBOL] = shim;
+}
+function installSubscriptionSelectorShim(pool) {
+    if (typeof globalThis === "undefined")
+        return;
+    const shim = {
+        pickAccountId: async (providerId) => {
+            const account = await pool.select({ providerId });
+            return account?.id ?? null;
+        },
+    };
+    globalThis[SUBSCRIPTION_SELECTOR_SHIM_SYMBOL] =
+        shim;
+}
+/**
+ * @deprecated kept for compatibility with the WS2 spec naming. Use
+ * {@link getDefaultAccountPool}.
+ */
+export function createDefaultAccountPool() {
+    return getDefaultAccountPool();
+}
+/**
+ * Resets the cached singleton. Test-only.
+ */
+export function __resetDefaultAccountPoolForTests() {
+    cachedDefaultPool = null;
+}

package/packages/app-core/src/services/account-usage.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Account usage probes + local JSONL counters.
+ *
+ * Two responsibilities:
+ *  1. Probe provider usage APIs (`pollAnthropicUsage`, `pollCodexUsage`)
+ *     to populate the `LinkedAccountUsage` snapshot on each account.
+ *  2. Maintain append-only JSONL counters per `(providerId, accountId, day)`
+ *     so we can answer "calls made today / tokens used / errors" without
+ *     re-reading every trajectory.
+ *
+ * The probes throw on HTTP error so the caller can decide whether to mark
+ * the account as `rate-limited` / `needs-reauth` / `invalid`. The counters
+ * are best-effort and synchronous — at our scale appendFileSync is fine.
+ */
+import type { LinkedAccountUsage } from "@elizaos/shared";
+/**
+ * Snapshot returned by the provider usage probes. Mirrors
+ * {@link LinkedAccountUsage} but without `refreshedAt` being optional —
+ * the probe is the thing that stamps it.
+ */
+export interface UsageSnapshot extends LinkedAccountUsage {
+    refreshedAt: number;
+}
+export interface UsageEntry {
+    ts: number;
+    tokens?: number;
+    latencyMs?: number;
+    ok: boolean;
+    model?: string;
+    errorCode?: string;
+}
+type FetchLike = typeof fetch;
+/**
+ * Probe Anthropic's OAuth usage endpoint.
+ *
+ * Endpoint: `GET https://api.anthropic.com/api/oauth/usage`
+ * Headers : `Authorization: Bearer <accessToken>`,
+ *           `anthropic-beta: oauth-2025-04-20`,
+ *           `Content-Type: application/json`
+ *
+ * Handles both legacy flat (`five_hour_utilization`) and new nested
+ * (`five_hour: { utilization }`) response shapes. Throws on any HTTP
+ * error with the status code included in the message.
+ */
+export declare function pollAnthropicUsage(accessToken: string, fetchImpl?: FetchLike): Promise<UsageSnapshot>;
+/**
+ * Probe Codex / ChatGPT's usage endpoint.
+ *
+ * Endpoint: `GET https://chatgpt.com/backend-api/wham/usage`
+ * Headers : `Authorization: Bearer <accessToken>`,
+ *           `ChatGPT-Account-Id: <openAIAccountId>`,
+ *           `User-Agent: codex-cli`
+ *
+ * `used_percent` is already on the 0..100 scale. `reset_at` is epoch
+ * seconds. Codex has no weekly equivalent, so `weeklyPct` stays undefined.
+ */
+export declare function pollCodexUsage(accessToken: string, accountId: string, fetchImpl?: FetchLike): Promise<UsageSnapshot>;
+/**
+ * Append a usage entry for the given `(providerId, accountId)` pair.
+ * One line per call, written synchronously with mode 0o600. The day
+ * directory is created on demand.
+ */
+export declare function recordCall(providerId: string, accountId: string, entry: Omit<UsageEntry, "ts">): void;
+export interface DailyCounters {
+    calls: number;
+    tokens: number;
+    errors: number;
+}
+/**
+ * Read today's JSONL and aggregate `(calls, tokens, errors)`. Lines that
+ * fail to parse are skipped silently (best-effort).
+ */
+export declare function readTodayCounters(providerId: string, accountId: string): DailyCounters;
+export {};
+//# sourceMappingURL=account-usage.d.ts.map

package/packages/app-core/src/services/account-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-usage.d.ts","sourceRoot":"","sources":["../../../../../../app-core/src/services/account-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACvD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,KAAK,SAAS,GAAG,OAAO,KAAK,CAAC;AAmC9B;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,SAAiB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAiCxB;AAaD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,SAAiB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA6BxB;AA8BD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAC5B,IAAI,CAYN;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,aAAa,CA0Bf"}