@genee/omp-opsx-addon 0.1.0

package/lib/unified-config.ts

@@ -0,0 +1,463 @@
+/**
+ * Unified opsx config schema.
+ *
+ * `opsx.yml` (per project at `<cwd>/.omp/opsx.yml`, layered on top of
+ * `~/.omp/agent/opsx.yml`) declares how each role is dispatched. Since
+ * `acpx` was removed, every role is local — values describe the *model*
+ * the role should run on, not an external agent to spawn.
+ *
+ * Accepted values for each role:
+ *   - `'auto'` — let the model-selector pick based on tier + usage.
+ *   - An OMP role alias: `default`, `smol`, `slow`, `vision`, `plan`,
+ *     `designer`, `commit`, `tiny`, `task`, `advisor` — expanded by the
+ *     OMP `modelRoles` setting (not by this plugin) to a concrete model.
+ *   - A concrete model id: `gpt-5`, `claude-opus-4-6`.
+ *   - A provider-scoped selector: `anthropic/claude-opus-4-6`,
+ *     `openai-codex/gpt-5-codex`.
+ *
+ * Top-level fields:
+ *   - `model_allowlist`: list of `provider/model` glob patterns — restricts
+ *     which models the auto-selector may pick from.
+ *   - `tiers`: list of `{ pattern, tier }` overrides for tier scoring.
+ *   - `role_tiers`: `role → tier_name` map overriding the default expected
+ *     tier (DEFAULT_ROLE_TIER in model-tiers).
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { YAML } from 'bun';
+import { TIER_NAMES, type TierName, type TierOverride } from './model-tiers.js';
+
+/** OMP-documented role aliases. Plugins MAY pass these to `task(..., model: '@alias')`. */
+export const OMP_ROLE_ALIASES = new Set<string>([
+    'default',
+    'smol',
+    'slow',
+    'vision',
+    'plan',
+    'designer',
+    'commit',
+    'tiny',
+    'task',
+    'advisor',
+]);
+
+/** Special "let the plugin decide" marker. */
+export const AUTO_TOKEN = 'auto';
+
+/** Roles the plugin manages. */
+export const OPSX_ROLES = ['coder', 'reviewer', 'planner', 'proposal-reviewer'] as const;
+export type OpsxRole = (typeof OPSX_ROLES)[number];
+
+/** Raw YAML shape — every key is optional. */
+export interface OpsxYamlShape {
+    coder?: string;
+    reviewer?: string;
+    planner?: string;
+    'proposal-reviewer'?: string;
+    primary?: string;
+    model_allowlist?: string[];
+    tiers?: TierOverride[];
+    role_tiers?: Partial<Record<OpsxRole, TierName>>;
+    plan_providers?: string[];
+    probe_enabled?: boolean;
+    probe_timeout_ms?: number;
+    probe_http_enabled?: boolean;
+    probe_ttl_ms?: number;
+    excluded_providers?: string[];
+    redis_enabled?: boolean;
+    redis_host?: string;
+    redis_port?: number;
+    redis_connect_timeout_ms?: number;
+    redis_command_timeout_ms?: number;
+    redis_reconcile_interval_ms?: number;
+    redis_probe_interval_ms?: number;
+    redis_unhealthy_retry_ms?: number;
+    redis_ttl_ms?: number;
+}
+
+/** A role value as parsed. */
+export type RoleValue =
+    | { kind: 'auto' }
+    | { kind: 'omp-alias'; alias: string }
+    | { kind: 'model'; modelId: string }
+    | { kind: 'provider-model'; provider: string; modelId: string };
+
+export interface ResolvedOpsxConfig {
+    roles: Record<OpsxRole, RoleValue>;
+    modelAllowlist: string[];
+    tierOverrides: TierOverride[];
+    roleTiers: Partial<Record<OpsxRole, TierName>>;
+    /** Provider ids that have monthly plan subscriptions. */
+    planProviders: string[];
+    warnings: string[];
+    /** 是否开启可达性探测，默认 true */
+    probe_enabled: boolean;
+    /** 单端点 TLS 探测超时 ms，默认 3000 */
+    probe_timeout_ms: number;
+    /** 是否开启 HTTP 探测（第二层），默认 false */
+    probe_http_enabled: boolean;
+    /** 探测结果 TTL ms，默认 600000（10 分钟） */
+    probe_ttl_ms: number;
+    /** 静态排除的 provider 列表（零探测成本） */
+    excluded_providers: string[];
+    /** 是否启用本地 Redis 实时中转（默认 true；false 时纯文件路径）。 */
+    redis_enabled: boolean;
+    /** Redis host（默认 127.0.0.1）。 */
+    redis_host: string;
+    /** Redis port（默认 6379）。 */
+    redis_port: number;
+    /** TCP 连接超时 ms（默认 300）。 */
+    redis_connect_timeout_ms: number;
+    /** 单命令往返超时 ms（默认 500）。 */
+    redis_command_timeout_ms: number;
+    /** reconcile 周期 ms（默认 30000）。 */
+    redis_reconcile_interval_ms: number;
+    /** healthy 心跳 PING 周期 ms（默认 30000）。 */
+    redis_probe_interval_ms: number;
+    /** unhealthy 退避重试周期 ms（默认 5000）。 */
+    redis_unhealthy_retry_ms: number;
+    /** Redis key TTL ms（默认 180000）。 */
+    redis_ttl_ms: number;
+}
+
+/** Default values applied when no config is provided. */
+export const DEFAULT_OPSX: Record<OpsxRole, string> = {
+    coder: 'auto',
+    reviewer: 'auto',
+    planner: 'auto',
+    'proposal-reviewer': 'auto',
+};
+
+function splitProviderModel(raw: string): { provider?: string; modelId: string } {
+    const slash = raw.indexOf('/');
+    if (slash === -1) return { modelId: raw.trim() };
+    const provider = raw.slice(0, slash).trim();
+    const modelId = raw.slice(slash + 1).trim();
+    return { provider: provider || undefined, modelId };
+}
+
+/** Parse a single role value string into a RoleValue. */
+export function parseRoleValue(raw: string | undefined, _warn: (msg: string) => void): RoleValue {
+    if (raw === undefined || raw === null) {
+        return { kind: 'auto' };
+    }
+    const trimmed = String(raw).trim();
+    if (!trimmed || trimmed === AUTO_TOKEN) {
+        return { kind: 'auto' };
+    }
+    // Legacy compat: strip `pi:` / `local:` prefix (old acpx-era config).
+    const legacyStripped = trimmed.replace(/^(pi|local):/i, '').trim();
+    if (legacyStripped !== trimmed) {
+        _warn(`[omp-opsx-addon] legacy "${trimmed}" → "${legacyStripped}" (pi:/local: prefix no longer needed)`);
+        return parseRoleValue(legacyStripped, _warn);
+    }
+    if (OMP_ROLE_ALIASES.has(trimmed.toLowerCase())) {
+        return { kind: 'omp-alias', alias: trimmed.toLowerCase() };
+    }
+    const { provider, modelId } = splitProviderModel(trimmed);
+    if (provider) {
+        return { kind: 'provider-model', provider, modelId };
+    }
+    return { kind: 'model', modelId: trimmed };
+}
+/** Validate tier override entries. Invalid entries are dropped with a warning. */
+export function parseTierOverrides(
+    raw: unknown,
+    warn: (msg: string) => void,
+): TierOverride[] {
+    if (!Array.isArray(raw)) return [];
+    const out: TierOverride[] = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== 'object') {
+            warn(`[omp-opsx-addon] tiers: skipping non-object entry ${JSON.stringify(entry)}`);
+            continue;
+        }
+        const obj = entry as Record<string, unknown>;
+        if (
+            typeof obj.pattern !== 'string' ||
+            (typeof obj.tier !== 'string' && typeof obj.tier !== 'number')
+        ) {
+            warn(`[omp-opsx-addon] tiers: skipping entry missing pattern/tier ${JSON.stringify(entry)}`);
+            continue;
+        }
+        if (typeof obj.tier === 'string' && !TIER_NAMES.includes(obj.tier as TierName)) {
+            warn(`[omp-opsx-addon] tiers: unknown tier name "${obj.tier}" (use one of ${TIER_NAMES.join('/')})`);
+            continue;
+        }
+        out.push({ pattern: obj.pattern, tier: obj.tier as TierName | number });
+    }
+    return out;
+}
+
+/** Validate role_tiers entries. */
+export function parseRoleTiers(
+    raw: unknown,
+    warn: (msg: string) => void,
+): Partial<Record<OpsxRole, TierName>> {
+    if (!raw || typeof raw !== 'object') return {};
+    const out: Partial<Record<OpsxRole, TierName>> = {};
+    for (const role of OPSX_ROLES) {
+        const v = (raw as Record<string, unknown>)[role];
+        if (v === undefined || v === null) continue;
+        if (typeof v !== 'string') {
+            warn(`[omp-opsx-addon] role_tiers.${role}: expected tier name, got ${typeof v}`);
+            continue;
+        }
+        if (!TIER_NAMES.includes(v as TierName)) {
+            warn(`[omp-opsx-addon] role_tiers.${role}: unknown tier "${v}" (use one of ${TIER_NAMES.join('/')})`);
+            continue;
+        }
+        out[role] = v as TierName;
+    }
+    return out;
+}
+
+/** Validate the model_allowlist (array of glob strings). */
+export function parseModelAllowlist(
+    raw: unknown,
+    warn: (msg: string) => void,
+): string[] {
+    if (raw === undefined || raw === null) return [];
+    if (!Array.isArray(raw)) {
+        warn('[omp-opsx-addon] model_allowlist: expected array of glob strings');
+        return [];
+    }
+    const out: string[] = [];
+    for (const entry of raw) {
+        if (typeof entry !== 'string') {
+            warn(`[omp-opsx-addon] model_allowlist: skipping non-string entry ${JSON.stringify(entry)}`);
+            continue;
+        }
+        out.push(entry);
+    }
+    return out;
+}
+/** 解析布尔值：合法 boolean 返回，否则返回 defaultValue 并 warn。 */
+export function parseProbeBool(raw: unknown, key: string, defaultValue: boolean, warn: (msg: string) => void): boolean {
+    if (raw === undefined || raw === null) return defaultValue;
+    if (typeof raw === 'boolean') return raw;
+    warn(`[omp-opsx-addon] ${key}: expected boolean, got ${JSON.stringify(raw)}`);
+    return defaultValue;
+}
+
+/** 解析正整数值：合法正整数返回，否则返回 defaultValue 并 warn。 */
+export function parsePositiveInt(raw: unknown, key: string, defaultValue: number, warn: (msg: string) => void): number {
+    if (raw === undefined || raw === null) return defaultValue;
+    if (typeof raw === 'number' && Number.isFinite(raw) && raw > 0 && Number.isInteger(raw)) return raw;
+    warn(`[omp-opsx-addon] ${key}: expected positive integer, got ${JSON.stringify(raw)}`);
+    return defaultValue;
+}
+
+/** 解析字符串数组：合法则返回，否则返回 [] 并 warn。 */
+export function parseStringArray(raw: unknown, key: string, warn: (msg: string) => void): string[] {
+    if (raw === undefined || raw === null) return [];
+    if (!Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] ${key}: expected array, got ${JSON.stringify(raw)}`);
+        return [];
+    }
+    const out: string[] = [];
+    for (const entry of raw) {
+        if (typeof entry === 'string') out.push(entry);
+        else warn(`[omp-opsx-addon] ${key}: skipping non-string entry ${JSON.stringify(entry)}`);
+    }
+    return out;
+}
+
+/** Parse the full raw opsx config. */
+export function parseOpsxConfig(
+    raw: unknown,
+    warn: (msg: string) => void = () => {},
+): ResolvedOpsxConfig {
+    const obj = (raw ?? {}) as OpsxYamlShape;
+    const warnings: string[] = [];
+    const localWarn = (m: string) => {
+        warnings.push(m);
+        warn(m);
+    };
+
+    function sanitizePlanProviders(raw: unknown): string[] {
+        if (raw === undefined || raw === null) return [];
+        if (!Array.isArray(raw)) return [];
+        return raw.filter((v): v is string => typeof v === 'string');
+    }
+
+    const roles: Record<OpsxRole, RoleValue> = {} as Record<OpsxRole, RoleValue>;
+    for (const role of OPSX_ROLES) {
+        const raw = (obj as Record<string, unknown>)[role];
+        roles[role] = parseRoleValue(raw as string | undefined, localWarn);
+    }
+    let redisHost = '127.0.0.1';
+    if (obj.redis_host !== undefined) {
+        if (typeof obj.redis_host === 'string' && obj.redis_host.trim() !== '') {
+            redisHost = obj.redis_host;
+        } else {
+            localWarn(`[omp-opsx-addon] redis_host: expected non-empty string, got ${JSON.stringify(obj.redis_host)}`);
+        }
+    }
+
+    return {
+        roles,
+        modelAllowlist: parseModelAllowlist(obj.model_allowlist, localWarn),
+        tierOverrides: parseTierOverrides(obj.tiers, localWarn),
+        roleTiers: parseRoleTiers(obj.role_tiers, localWarn),
+        planProviders: sanitizePlanProviders(obj.plan_providers),
+        warnings,
+        probe_enabled: parseProbeBool(obj.probe_enabled, 'probe_enabled', true, localWarn),
+        probe_timeout_ms: parsePositiveInt(obj.probe_timeout_ms, 'probe_timeout_ms', 3000, localWarn),
+        probe_http_enabled: parseProbeBool(obj.probe_http_enabled, 'probe_http_enabled', false, localWarn),
+        probe_ttl_ms: parsePositiveInt(obj.probe_ttl_ms, 'probe_ttl_ms', 600_000, localWarn),
+        excluded_providers: parseStringArray(obj.excluded_providers, 'excluded_providers', localWarn),
+        redis_enabled: parseProbeBool(obj.redis_enabled, 'redis_enabled', true, localWarn),
+        redis_host: redisHost,
+        redis_port: parsePositiveInt(obj.redis_port, 'redis_port', 6379, localWarn),
+        redis_connect_timeout_ms: parsePositiveInt(obj.redis_connect_timeout_ms, 'redis_connect_timeout_ms', 300, localWarn),
+        redis_command_timeout_ms: parsePositiveInt(obj.redis_command_timeout_ms, 'redis_command_timeout_ms', 500, localWarn),
+        redis_reconcile_interval_ms: parsePositiveInt(obj.redis_reconcile_interval_ms, 'redis_reconcile_interval_ms', 30_000, localWarn),
+        redis_probe_interval_ms: parsePositiveInt(obj.redis_probe_interval_ms, 'redis_probe_interval_ms', 30_000, localWarn),
+        redis_unhealthy_retry_ms: parsePositiveInt(obj.redis_unhealthy_retry_ms, 'redis_unhealthy_retry_ms', 5_000, localWarn),
+        redis_ttl_ms: parsePositiveInt(obj.redis_ttl_ms, 'redis_ttl_ms', 180_000, localWarn),
+    };
+}
+
+/** Parse YAML text into an OpsxYamlShape. */
+export function parseOpsxYaml(content: string): OpsxYamlShape {
+    const trimmed = content.trim();
+    if (!trimmed) return {};
+    const parsed = YAML.parse(trimmed);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed as OpsxYamlShape;
+}
+
+function readOpsxYamlFile(path: string): OpsxYamlShape {
+    try {
+        if (!existsSync(path)) return {};
+        return parseOpsxYaml(readFileSync(path, 'utf-8'));
+    } catch {
+        return {};
+    }
+}
+function pickRoleKeys(raw: OpsxYamlShape): Partial<Record<OpsxRole, string>> {
+    const out: Partial<Record<OpsxRole, string>> = {};
+    for (const role of OPSX_ROLES) {
+        const v = raw[role];
+        if (v === undefined || v === null) continue;
+        out[role] = String(v);
+    }
+    return out;
+}
+
+function pickTopLevelKeys(raw: OpsxYamlShape): OpsxYamlShape {
+    return {
+        model_allowlist: raw.model_allowlist,
+        tiers: raw.tiers,
+        role_tiers: raw.role_tiers,
+        plan_providers: raw.plan_providers,
+        probe_enabled: raw.probe_enabled,
+        probe_timeout_ms: raw.probe_timeout_ms,
+        probe_http_enabled: raw.probe_http_enabled,
+        probe_ttl_ms: raw.probe_ttl_ms,
+        excluded_providers: raw.excluded_providers,
+        redis_enabled: raw.redis_enabled,
+        redis_host: raw.redis_host,
+        redis_port: raw.redis_port,
+        redis_connect_timeout_ms: raw.redis_connect_timeout_ms,
+        redis_command_timeout_ms: raw.redis_command_timeout_ms,
+        redis_reconcile_interval_ms: raw.redis_reconcile_interval_ms,
+        redis_probe_interval_ms: raw.redis_probe_interval_ms,
+        redis_unhealthy_retry_ms: raw.redis_unhealthy_retry_ms,
+        redis_ttl_ms: raw.redis_ttl_ms,
+    };
+}
+
+function warnLegacySettingsJson(
+    directory: string,
+    homeDir: string,
+    warn: (msg: string) => void,
+): void {
+    const paths = [
+        join(homeDir, '.omp', 'agent', 'settings.json'),
+        join(directory, '.omp', 'settings.json'),
+    ];
+    for (const p of paths) {
+        try {
+            if (!existsSync(p)) continue;
+            const raw = JSON.parse(readFileSync(p, 'utf-8'));
+            if (raw?.opsx && typeof raw.opsx === 'object') {
+                warn(
+                    `[omp-opsx-addon] Found legacy opsx in ${p}; migrate to opsx.yml (~/.omp/agent/opsx.yml or <cwd>/.omp/opsx.yml). The 'opsx' settings key is no longer read.`,
+                );
+                return;
+            }
+        } catch {
+            // ignore unreadable / invalid JSON
+        }
+    }
+}
+
+/**
+ * Read opsx config from two-layer opsx.yml:
+ *   - global: `<homeDir>/.omp/agent/opsx.yml`
+ *   - project: `<cwd>/.omp/opsx.yml` (per-key override on roles; full overlay on
+ *     `model_allowlist` / `tiers` / `role_tiers`)
+ *
+ * `homeDir` is overridable for tests; defaults to `os.homedir()`.
+ */
+export function readOpsxSettings(
+    directory: string,
+    warn: (msg: string) => void = () => {},
+    homeDir: string = homedir(),
+): ResolvedOpsxConfig {
+    const globalPath = join(homeDir, '.omp', 'agent', 'opsx.yml');
+    const projectPath = join(directory, '.omp', 'opsx.yml');
+    return readOpsxSettingsFromPaths(globalPath, projectPath, warn);
+}
+
+/** Lower-level: read from explicit paths. Test seam. */
+export function readOpsxSettingsFromPaths(
+    globalPath: string,
+    projectPath: string,
+    warn: (msg: string) => void,
+): ResolvedOpsxConfig {
+    const globalYaml = readOpsxYamlFile(globalPath);
+    const projectYaml = readOpsxYamlFile(projectPath);
+
+    const homeFromGlobal = globalPath.replace(/\.omp\/agent\/opsx\.yml$/, '');
+    const projectFromPath = projectPath.replace(/\.omp\/opsx\.yml$/, '');
+    warnLegacySettingsJson(projectFromPath, homeFromGlobal, warn);
+
+    const globalRoles = pickRoleKeys(globalYaml);
+    const projectRoles = pickRoleKeys(projectYaml);
+
+    // Per-role: project overrides global, fall back to DEFAULT_OPSX.
+    const merged: OpsxYamlShape = { ...globalYaml };
+    for (const role of OPSX_ROLES) {
+        const v = projectRoles[role] ?? globalRoles[role] ?? DEFAULT_OPSX[role];
+        (merged as Record<string, unknown>)[role] = v;
+    }
+
+    // Top-level: project fully replaces global when present.
+    const projectTop = pickTopLevelKeys(projectYaml);
+    const globalTop = pickTopLevelKeys(globalYaml);
+    merged.model_allowlist = projectTop.model_allowlist ?? globalTop.model_allowlist;
+    merged.tiers = projectTop.tiers ?? globalTop.tiers;
+    merged.role_tiers = projectTop.role_tiers ?? globalTop.role_tiers;
+    merged.plan_providers = projectTop.plan_providers ?? globalTop.plan_providers;
+    merged.probe_enabled = projectTop.probe_enabled ?? globalTop.probe_enabled;
+    merged.probe_timeout_ms = projectTop.probe_timeout_ms ?? globalTop.probe_timeout_ms;
+    merged.probe_http_enabled = projectTop.probe_http_enabled ?? globalTop.probe_http_enabled;
+    merged.probe_ttl_ms = projectTop.probe_ttl_ms ?? globalTop.probe_ttl_ms;
+    merged.excluded_providers = projectTop.excluded_providers ?? globalTop.excluded_providers;
+    merged.redis_enabled = projectTop.redis_enabled ?? globalTop.redis_enabled;
+    merged.redis_host = projectTop.redis_host ?? globalTop.redis_host;
+    merged.redis_port = projectTop.redis_port ?? globalTop.redis_port;
+    merged.redis_connect_timeout_ms = projectTop.redis_connect_timeout_ms ?? globalTop.redis_connect_timeout_ms;
+    merged.redis_command_timeout_ms = projectTop.redis_command_timeout_ms ?? globalTop.redis_command_timeout_ms;
+    merged.redis_reconcile_interval_ms = projectTop.redis_reconcile_interval_ms ?? globalTop.redis_reconcile_interval_ms;
+    merged.redis_probe_interval_ms = projectTop.redis_probe_interval_ms ?? globalTop.redis_probe_interval_ms;
+    merged.redis_unhealthy_retry_ms = projectTop.redis_unhealthy_retry_ms ?? globalTop.redis_unhealthy_retry_ms;
+    merged.redis_ttl_ms = projectTop.redis_ttl_ms ?? globalTop.redis_ttl_ms;
+
+    return parseOpsxConfig(merged, warn);
+}

package/lib/usage-estimator.ts

@@ -0,0 +1,154 @@
+/**
+ * Second-level usage estimation: blend the low-frequency provider snapshot
+ * (stock: balance / window fractions) with the high-frequency sessionUsage
+ * consumption flow to produce a per-second estimate of remaining quota, then
+ * re-align to the exact snapshot on every actual fetch.
+ *
+ * Pure functions only — the host wires snapshot baselines and deltas.
+ */
+
+/** Fixed USD→CNY conversion for balance-denominated (CNY) estimates. */
+export const USD_CNY_FX = 7.2;
+
+/** Bucketed token usage (cacheRead is billed as input, folded in upstream). */
+export interface UsageBucket {
+    total: number;
+    input: number;
+    output: number;
+}
+
+/** Per-1M-token price in USD for one provider (averaged over its models). */
+export interface ProviderPrice {
+    input: number;
+    output: number;
+}
+
+/** Snapshot shapes the estimator understands (subset of UsageLimit.amount). */
+export interface LimitSnapshot {
+    /** Balance-style (CNY) remaining, when the provider is pay-as-you-go. */
+    remaining?: number;
+    /** Currency of `remaining` — estimate only computed for CNY balances. */
+    unit?: string;
+    /** Window-style remaining fraction (0..1), tokens or percent windows. */
+    remainingFraction?: number;
+    /** Window-style used fraction (0..1), an alternative to remainingFraction. */
+    usedFraction?: number;
+}
+
+/** Normalize any stored per-provider sessionUsage value (legacy number → bucket). */
+export function normalizeBucket(value: unknown): UsageBucket {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        const total = value;
+        return { total, input: total / 2, output: total / 2 };
+    }
+    const o = value as Partial<UsageBucket> | null | undefined;
+    const total = typeof o?.total === 'number' && Number.isFinite(o.total) ? o.total : 0;
+    const input = typeof o?.input === 'number' && Number.isFinite(o.input) ? o.input : total / 2;
+    const output = typeof o?.output === 'number' && Number.isFinite(o.output) ? o.output : total - input;
+    return { total, input, output };
+}
+
+/** Sum a list of buckets into one. */
+export function sumBuckets(buckets: Iterable<UsageBucket>): UsageBucket {
+    const acc = { total: 0, input: 0, output: 0 };
+    for (const b of buckets) {
+        acc.total += b.total;
+        acc.input += b.input;
+        acc.output += b.output;
+    }
+    return acc;
+}
+
+/** Average per-1M price over a provider's models (input/output buckets). */
+export function providerPrice(
+    models: readonly { provider: string; cost?: { input: number; output: number } }[],
+    provider: string,
+): ProviderPrice | undefined {
+    let input = 0;
+    let output = 0;
+    let n = 0;
+    for (const m of models) {
+        if (m.provider !== provider || !m.cost) continue;
+        input += m.cost.input;
+        output += m.cost.output;
+        n++;
+    }
+    if (n === 0) return undefined;
+    return { input: input / n, output: output / n };
+}
+
+/** USD price of a delta bucket (tokens → USD; per-1M prices). */
+export function spendUSD(delta: UsageBucket, price: ProviderPrice): number {
+    return (delta.input * price.input + delta.output * price.output) / 1_000_000;
+}
+
+/**
+ * Estimate the remaining amount/fraction after `delta` is spent since the
+ * snapshot. Returns undefined when the limit type cannot be estimated.
+ */
+export function estimateRemaining(
+    limit: LimitSnapshot,
+    delta: UsageBucket,
+    price: ProviderPrice,
+): number | undefined {
+    // Balance-style (CNY): exact subtraction via price × FX.
+    if (typeof limit.remaining === 'number' && limit.unit === 'CNY') {
+        const spent = spendUSD(delta, price) * USD_CNY_FX;
+        return Math.max(0, limit.remaining - spent);
+    }
+    // Window-style: absolute token remaining + fraction → total = remaining/fraction;
+    // subtract spent tokens and re-derive the fraction.
+    if (
+        typeof limit.remaining === 'number' &&
+        typeof limit.remainingFraction === 'number' &&
+        limit.remainingFraction > 0
+    ) {
+        const total = limit.remaining / limit.remainingFraction;
+        return Math.max(0, Math.min(1, (limit.remaining - delta.total) / total));
+    }
+    return undefined;
+}
+
+/** Format a balance estimate with the estimate marker. */
+export function formatBalanceEstimate(estimated: number): string {
+    return `~¥${estimated.toFixed(2)}`;
+}
+
+/** Format a fraction estimate as a percent with the estimate marker. */
+export function formatFractionEstimate(estimated: number): string {
+    return `~${Math.round(estimated * 100)}%`;
+}
+
+/**
+ * Build per-provider balance estimates (CNY) from the latest snapshot, the
+ * aggregated sessionUsage flow, and a baseline captured at the last fetch.
+ * Returns provider → replacement usage-line text; providers without a
+ * balance-style limit or without drift since the baseline are omitted.
+ */
+export function buildBalanceEstimates(
+    reports: readonly { provider: string; limits: readonly { amount?: { remaining?: number; unit?: string } }[] }[],
+    totals: Record<string, UsageBucket>,
+    models: readonly { provider: string; cost?: { input: number; output: number } }[],
+    baseline: Record<string, UsageBucket>,
+): Map<string, string> {
+    const out = new Map<string, string>();
+    for (const r of reports) {
+        const limit = r.limits[0];
+        const amount = limit?.amount;
+        if (!amount || amount.unit !== 'CNY' || typeof amount.remaining !== 'number') continue;
+        const price = providerPrice(models, r.provider);
+        if (!price) continue;
+        const cur = totals[r.provider] ?? { total: 0, input: 0, output: 0 };
+        const base = baseline[r.provider] ?? cur;
+        const delta = {
+            total: cur.total - base.total,
+            input: cur.input - base.input,
+            output: cur.output - base.output,
+        };
+        if (delta.total <= 0) continue;
+        const estimated = estimateRemaining(amount, delta, price);
+        if (estimated === undefined || estimated === amount.remaining) continue;
+        out.set(r.provider, `余额 ${formatBalanceEstimate(estimated)}`);
+    }
+    return out;
+}