@omnicross/daemon 0.3.0 → 0.3.1

package/dist/index.d.cts

@@ -5,8 +5,8 @@ import { AllowanceSchedulingConfig, AccountProbeConfig, OutboundKeyDb as Outboun
 import { RouteLeaseManager, ProviderProxy } from '@omnicross/core/provider-proxy';
 import { UsageRecorder, PricingEngine } from '@omnicross/core/usage';
 import { SubscriptionCredentialStore, FetchLike, CodexImageCapabilityEvidenceSource, CodexImageCapabilityEvidenceRequest, CodexImageCapabilityEvidence, CodexImageCapabilityObservation, ImageExecutionScheduler, ImageExecutionAccountKey, ImageExecutionSchedulerRequest, ImageExecutionSchedulerGrant, SubscriptionAccountService, SubscriptionProviderRegistry } from '@omnicross/subscriptions';
-import { AccountAllowanceSnapshot } from '@omnicross/contracts/account-allowance-types';
-import { ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, AccountTokensConfig, ProxyConfig, SubscriptionAccountSanitized, AccountClientIdentity, SubscriptionAccountEntry } from '@omnicross/contracts/account-tokens-types';
+import { AccountAllowanceSnapshot, AllowanceWindow } from '@omnicross/contracts/account-allowance-types';
+import { ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, KimiTokenConfig, AccountTokensConfig, ProxyConfig, SubscriptionAccountSanitized, AccountClientIdentity, SubscriptionAccountEntry } from '@omnicross/contracts/account-tokens-types';
 import * as _omnicross_contracts_subscription_types from '@omnicross/contracts/subscription-types';
 import { OpenCodeGoTokenConfig, SubscriptionProviderId } from '@omnicross/contracts/subscription-types';
 import { AccountAllowanceStore } from '@omnicross/core/pipeline/AccountAllowanceStore';
@@ -626,6 +626,32 @@ declare function loadConfig(path: string): DaemonConfig;
  *  `enc:` untouched) before serializing. */
 declare function saveConfig(path: string, cfg: DaemonConfig): void;
 
+/**
+ * atomicFile — the daemon's shared ATOMIC file-replace for credential-bearing
+ * state files (`keys.json`, `tokens.json`, …).
+ *
+ * A bare `writeFileSync(target, …)` is truncate-then-write: a crash, ENOSPC,
+ * or power loss mid-write leaves the target HALF-WRITTEN and the prior content
+ * is gone. For `tokens.json` that is account data — the 2026-09-06 incident
+ * lost every stored OAuth account exactly this way (a truncated file that the
+ * reader then silently treated as "no accounts"). Same-directory temp-write +
+ * fsync + rename means a FAILED write only ever discards the temp file; the
+ * prior target survives byte-equal.
+ *
+ * The temp name embeds pid + random bytes (never collides with a live temp of
+ * another process) and lives in the target's own directory so the final
+ * `renameSync` never crosses a volume (POSIX and win32 both make the replace
+ * atomic there; Node maps rename-over-existing to MoveFileEx with
+ * REPLACE_EXISTING on Windows).
+ *
+ * Extracted verbatim from `JsonOutboundKeyDb` (its original + only user) so
+ * every file-backed port shares ONE implementation instead of re-deriving it.
+ *
+ * @module @omnicross/daemon/ports/atomicFile
+ */
+/** Injectable seam (tests pass a throwing/stubbed replace to prove the prior file survives). */
+type AtomicFileReplace = (targetPath: string, contents: string) => void;
+
 /**
  * account-multi — daemon-side pure helpers for the subscription multi-account
  * layout.
@@ -640,7 +666,7 @@ declare function saveConfig(path: string, cfg: DaemonConfig): void;
  */
 
 /** Provider id → owned contract field names. */
-type DaemonProvider = 'claude' | 'codex' | 'gemini' | 'opencodego';
+type DaemonProvider = 'claude' | 'codex' | 'gemini' | 'opencodego' | 'kimi';
 interface AccountMetadataPatch {
     label?: string;
     enabled?: boolean;
@@ -710,9 +736,14 @@ type ExternalCliReader = (provider: ExternalCliProvider) => ExternalCliCredentia
  * over a sibling `tokens.json` holding an `AccountTokensConfig`-shaped object
  * (`{ claude?, codex?, gemini?, opencodego?, updatedAt }`). Modeled on
  * `JsonOutboundKeyDb`: the constructor takes the path; reads are
- * `existsSync` `readFileSync` `JSON.parse`, tolerating a missing/corrupt
- * file by returning a minimal `{ updatedAt }` config (the strategies already
- * guard `?.accessToken`, so a partial/empty config never crashes dispatch).
+ * `existsSync` `readFileSync` `JSON.parse`. A MISSING file returns a minimal
+ * `{ updatedAt }` config (first boot; the strategies already guard
+ * `?.accessToken`, so a partial/empty config never crashes dispatch). A file
+ * that EXISTS but will not parse as a JSON object is first QUARANTINED to a
+ * sibling `tokens.json.corrupt-<stamp>` backup (see `quarantineCorrupt`) and
+ * only then treated as empty — a corrupt file is DATA, not "no accounts"
+ * (2026-09-06 incident: a truncated write read as empty, then the re-login
+ * persist overwrote the only copy of every stored account).
  *
  * The PORT surface is read-only by design: the codex / gemini strategies pull
  * their access token via `getFullConfig().<provider>.accessToken`; only claude /
@@ -736,6 +767,12 @@ type ExternalCliReader = (provider: ExternalCliProvider) => ExternalCliCredentia
  * at-rest with NO extra work (the store API guarantees it). The "re-read on every
  * call, no cache" semantics are unchanged.
  *
+ * DURABILITY: `persist` writes through the shared same-directory temp + fsync +
+ * rename (`atomicReplaceUtf8`) — a crashed/failed/interrupted write discards
+ * only the temp file and the prior `tokens.json` survives byte-equal. This is
+ * the other half of the 2026-09-06 fix: the store previously used a bare
+ * truncate-then-write `writeFileSync`, which could leave a half-written file.
+ *
  * REAL TOKEN REFRESH (oauth design D4): `refresh{Claude,Codex,Gemini}Token` mint
  * a new access token via the shared host-clean OAuth refresh functions
  * (`@omnicross/subscriptions/oauth`, injected `FetchLike` default global
@@ -758,13 +795,15 @@ type ExternalCliReader = (provider: ExternalCliProvider) => ExternalCliCredentia
  * shapes), keyed by `SubscriptionProviderId` the daemon admin layer validates
  * the wire body to one of these before calling the writer.
  */
-type SubscriptionTokenBlock = ClaudeTokenConfig | CodexTokenConfig | GeminiTokenConfig | OpenCodeGoTokenConfig;
+type SubscriptionTokenBlock = ClaudeTokenConfig | CodexTokenConfig | GeminiTokenConfig | OpenCodeGoTokenConfig | KimiTokenConfig;
 declare class JsonSubscriptionCredentialStore implements SubscriptionCredentialStore {
     private readonly tokensPath;
     private readonly box;
     private readonly fetchImpl;
     /** Injectable, strictly read-only external CLI native-store reader. */
     private readonly externalCliReader;
+    /** Injectable atomic-replace seam (tests prove a failed write keeps the prior file). */
+    private readonly atomicReplace;
     /**
      * @param tokensPath  on-disk `tokens.json` location.
      * @param box         at-rest `SecretBox` (encrypt-on-write / decrypt-on-read).
@@ -779,7 +818,9 @@ declare class JsonSubscriptionCredentialStore implements SubscriptionCredentialS
      */
     constructor(tokensPath: string, box: SecretBox, fetchImpl?: FetchLike | undefined, 
     /** Injectable, strictly read-only external CLI native-store reader. */
-    externalCliReader?: ExternalCliReader);
+    externalCliReader?: ExternalCliReader, 
+    /** Injectable atomic-replace seam (tests prove a failed write keeps the prior file). */
+    atomicReplace?: AtomicFileReplace);
     /**
      * The proxy-aware `FetchLike` for one refresh round-trip (upstream-proxy M1). A
      * TEST-injected `fetchImpl` is returned verbatim; otherwise the refresh routes
@@ -858,13 +899,21 @@ declare class JsonSubscriptionCredentialStore implements SubscriptionCredentialS
      * destroy the ability to refresh again). HONEST `false` when no refresh_token.
      */
     refreshGeminiToken(): Promise<boolean>;
+    /**
+     * Refresh the Kimi Code (Moonshot) OAuth access token (device-flow grant).
+     * Kimi ROTATES the refresh token, so the response's pair is written back
+     * whole; the account's stable `deviceId` (fingerprint header input) is
+     * preserved. The refresh call carries the CLI fingerprint headers. HONEST
+     * `false` when no refresh_token.
+     */
+    refreshKimiToken(): Promise<boolean>;
     /**
      * Refresh a SPECIFIC managed account by id (background scheduler sweep and
      * account-pool resolution). It uses only that account's stored refresh
      * token. Coalesced per `provider:id`; on failure flags ONLY that account
      * `expired`.
      */
-    refreshAccountById(provider: 'claude' | 'codex' | 'gemini', id: string): Promise<boolean>;
+    refreshAccountById(provider: 'claude' | 'codex' | 'gemini' | 'kimi', id: string): Promise<boolean>;
     /**
      * Resolve a SPECIFIC account's access token by id (design D6). Mirrors each
      * provider's ACTIVE-getter policy, keyed by id: claude returns the stored token
@@ -1030,22 +1079,49 @@ declare class JsonSubscriptionCredentialStore implements SubscriptionCredentialS
     /** Write the merged config to disk as pretty JSON (mkdir parent if needed).
      *  Encrypt-on-write: the token-material fields are encrypted (legacy plaintext
      *  `enc:v1:`; already-`enc:`/`$ENV` untouched) before serializing, so any
-     *  write incl. child 4's future refresh writes lands encrypted. */
+     *  write incl. child 4's future refresh writes lands encrypted.
+     *  ATOMIC: temp + fsync + rename (`atomicReplaceUtf8`) — a failed or
+     *  interrupted write discards only the temp file; the prior `tokens.json`
+     *  survives byte-equal (bare `writeFileSync` truncate-writes lost every
+     *  account on a mid-write failure, 2026-09-06). */
     private persist;
     /**
-     * Read + parse `tokens.json`, tolerating a missing/corrupt file, then DECRYPT
-     * the token-material fields so every getter returns plaintext (the
-     * subscription bearer path is byte-identical).
+     * Read + parse `tokens.json`, then DECRYPT the token-material fields so every
+     * getter returns plaintext (the subscription bearer path is byte-identical).
+     *
+     * A MISSING file is a legitimate first-boot state → minimal `{ updatedAt: '' }`.
+     * A file that EXISTS but cannot be parsed as a JSON object is CORRUPT →
+     * `quarantineCorrupt` moves it aside (once) before the empty config is
+     * returned, so the unreadable accounts survive for manual recovery.
      *
-     * The fs-read + JSON-parse tolerance is INSIDE the try (a missing or corrupt
-     * file empty `{ updatedAt: '' }`). The DECRYPT runs OUTSIDE the try, so a
-     * wrong/missing master key or a tampered `enc:` envelope FAILS FAST with the
-     * box's clear, secret-free error (secrets spec "/ UX":
-     * SHALL fail-fast, SHALL NOT a swallowed decrypt would report "no
-     * tokens" and silently send the WRONG bearer upstream 401). Mirrors
-     * `config.ts loadConfig`, which decrypts outside its parse try.
+     * The DECRYPT runs OUTSIDE any try, so a wrong/missing master key or a
+     * tampered `enc:` envelope FAILS FAST with the box's clear, secret-free
+     * error (secrets spec "/ UX": SHALL fail-fast, SHALL NOT a swallowed
+     * decrypt would report "no tokens" and silently send the WRONG bearer
+     * upstream 401). Mirrors `config.ts loadConfig`, which decrypts outside
+     * its parse try.
      */
     private readConfig;
+    /** One-shot latch: a corrupt file is quarantined (or found unmovable) at
+     *  most once per process, so the hot read path never re-attempts or re-logs. */
+    private corruptQuarantined;
+    /**
+     * Quarantine a present-but-corrupt `tokens.json`, then treat it as empty.
+     *
+     * Renames the file to a sibling `tokens.json.corrupt-<stamp>` backup and
+     * logs loudly (the daemon's stderr log; secret-free — reason + paths only).
+     * The daemon KEEPS SERVING (API-key routing is unaffected; subscription
+     * routing reports no credential, same as an absent file) while the corrupt
+     * bytes survive for manual recovery — and, critically, the NEXT persist
+     * (e.g. the user re-logging in) can no longer overwrite the only copy of
+     * the old accounts, which is exactly how the 2026-09-06 incident turned a
+     * recoverable truncated file into permanent account loss.
+     *
+     * Best-effort: if the rename fails (file locked, permissions), the corrupt
+     * file is left in place and every later read still tolerates it as empty;
+     * the latch still trips so the attempt + log happen exactly once.
+     */
+    private quarantineCorrupt;
 }
 
 /**
@@ -1349,9 +1425,140 @@ declare class ClaudeAllowanceCollector {
     private unsupportedSnapshot;
 }
 
+/**
+ * Codex (ChatGPT) OAuth usage collector.
+ *
+ * Actively polls `GET https://chatgpt.com/backend-api/wham/usage` per codex
+ * account (Bearer + `ChatGPT-Account-Id` decoded from the OAuth id_token),
+ * mirroring the Claude collector's cache/coalescing contract: 5-minute cache,
+ * per-account in-flight merging, one 401→refresh→retry. The passive
+ * `x-codex-*` response-header tap (`upstreamFetch`) remains the complement —
+ * it keeps windows fresh mid-flight; this collector makes the quota visible
+ * with ZERO traffic (previously codex reported not-observed until a real
+ * model response, and its refresh button had to spend a probe request).
+ *
+ * `reset_at` (absolute epoch seconds) is preferred over `reset_after_seconds`
+ * so deadlines do not accumulate observation-clock skew. Tokens and raw
+ * upstream payloads never leave this module.
+ */
+
+interface CodexAllowanceCredentialReader {
+    getAccessTokenForAccount(providerId: 'codex', accountId: string): Promise<string | null>;
+    refreshAccountToken(providerId: 'codex', accountId: string): Promise<boolean>;
+}
+type CodexAllowanceFetch = (url: string, init: RequestInit, accountId: string) => Promise<Response>;
+interface CodexAllowanceCollectOptions {
+    force?: boolean;
+    /** Treat an otherwise valid cache entry as due when it expires within this window. */
+    refreshAheadMs?: number;
+}
+declare class CodexAllowanceCollector {
+    private readonly credentials;
+    private readonly store;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly inFlight;
+    constructor(credentials: CodexAllowanceCredentialReader, store?: AccountAllowanceStore, fetchImpl?: CodexAllowanceFetch, now?: () => number);
+    collectMany(accounts: readonly SubscriptionAccountEntry<CodexTokenConfig>[], options?: CodexAllowanceCollectOptions): Promise<AccountAllowanceSnapshot[]>;
+    collect(account: SubscriptionAccountEntry<CodexTokenConfig>, options?: CodexAllowanceCollectOptions): Promise<AccountAllowanceSnapshot>;
+    /**
+     * A response-header snapshot stays a valid cache hit only while fresh; an
+     * active oauth-usage snapshot is honored on the same 5-minute cadence as
+     * Claude's (the poll is cheap and quota is the scheduling input).
+     */
+    private isCacheValid;
+    private fetchAccount;
+    private request;
+    private failureSnapshot;
+    private unsupportedSnapshot;
+}
+
+/**
+ * Kimi Code OAuth usage collector.
+ *
+ * Polls `GET https://api.kimi.com/coding/v1/usages` per kimi account (Bearer +
+ * the CLI fingerprint headers), mirroring the Claude/Codex collectors' cache
+ * contract: 5-minute cache, per-account in-flight merging, one 401→refresh→
+ * retry. The payload's `usage` aggregate is a weekly row; `limits[]` carries
+ * the per-window rows — the 300-minute burst window normalizes to `five-hour`
+ * and whole-day spans to `seven-day` (the same canonical ids the Claude view
+ * and the UI's window labels use).
+ */
+
+interface KimiAllowanceCredentialReader {
+    getAccessTokenForAccount(providerId: 'kimi', accountId: string): Promise<string | null>;
+    refreshAccountToken(providerId: 'kimi', accountId: string): Promise<boolean>;
+}
+type KimiAllowanceFetch = (url: string, init: RequestInit, accountId: string) => Promise<Response>;
+interface KimiAllowanceCollectOptions {
+    force?: boolean;
+    refreshAheadMs?: number;
+}
+declare class KimiAllowanceCollector {
+    private readonly credentials;
+    private readonly store;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly inFlight;
+    constructor(credentials: KimiAllowanceCredentialReader, store?: AccountAllowanceStore, fetchImpl?: KimiAllowanceFetch, now?: () => number);
+    collectMany(accounts: readonly SubscriptionAccountEntry<KimiTokenConfig>[], options?: KimiAllowanceCollectOptions): Promise<AccountAllowanceSnapshot[]>;
+    collect(account: SubscriptionAccountEntry<KimiTokenConfig>, options?: KimiAllowanceCollectOptions): Promise<AccountAllowanceSnapshot>;
+    private isCacheValid;
+    private fetchAccount;
+    private request;
+    private failureSnapshot;
+    private unsupportedSnapshot;
+}
+
+/**
+ * OpenCodeGo usage collector.
+ *
+ * Polls `GET {go-base}/v1/usage` per OpenCodeGo account with the account's
+ * static bearer key, mirroring the other collectors' cache contract (5-minute
+ * cache, per-account in-flight merging). The payload reports three percent
+ * windows; only rolling(≈5h) + weekly are surfaced — the MONTHLY window is
+ * deliberately dropped: the console's "Use balance" fallback keeps a
+ * monthly-exhausted key SERVING, and the scheduling policy pauses on the worst
+ * reported window, so reporting monthly would strand usable keys (oh-my-pi
+ * reached the same conclusion for its ranking scopes).
+ *
+ * `status: "rate-limited"` is authoritative over the percent (→ 100%).
+ */
+
+interface OpenCodeGoAllowanceCredentialReader {
+    getAccessTokenForAccount(providerId: 'opencodego', accountId: string): Promise<string | null>;
+}
+type OpenCodeGoAllowanceFetch = (url: string, init: RequestInit, accountId: string) => Promise<Response>;
+declare class OpenCodeGoAllowanceCollector {
+    private readonly credentials;
+    private readonly store;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly inFlight;
+    constructor(credentials: OpenCodeGoAllowanceCredentialReader, store?: AccountAllowanceStore, fetchImpl?: OpenCodeGoAllowanceFetch, now?: () => number);
+    collectMany(accounts: readonly SubscriptionAccountEntry<OpenCodeGoTokenConfig>[], options?: {
+        force?: boolean;
+        refreshAheadMs?: number;
+    }): Promise<AccountAllowanceSnapshot[]>;
+    collect(account: SubscriptionAccountEntry<OpenCodeGoTokenConfig>, options?: {
+        force?: boolean;
+        refreshAheadMs?: number;
+    }): Promise<AccountAllowanceSnapshot>;
+    private fetchAccount;
+    private failureSnapshot;
+}
+
 /** Secret-free account allowance query/refresh facade used by the admin API. */
 
-interface AccountAllowanceCredentialReader extends ClaudeAllowanceCredentialReader {
+/**
+ * The credential surface the collectors share. Declared explicitly (not via
+ * interface extension) because the collectors narrow
+ * `getAccessTokenForAccount`/`refreshAccountToken` to different provider
+ * literals — extending them all would make the overloads conflict.
+ */
+interface AccountAllowanceCredentialReader {
+    getAccessTokenForAccount(providerId: 'claude' | 'codex' | 'kimi' | 'opencodego', accountId: string): Promise<string | null>;
+    refreshAccountToken(providerId: 'claude' | 'codex' | 'kimi', accountId: string): Promise<boolean>;
     getFullConfig(): Promise<AccountTokensConfig>;
 }
 interface AccountAllowanceFilter {
@@ -1367,18 +1574,35 @@ declare class AccountAllowanceService {
     private readonly store;
     private readonly now;
     readonly claudeCollector: ClaudeAllowanceCollector;
-    constructor(credentials: AccountAllowanceCredentialReader, store?: AccountAllowanceStore, collector?: ClaudeAllowanceCollector, now?: () => number);
+    readonly codexCollector: CodexAllowanceCollector;
+    readonly kimiCollector: KimiAllowanceCollector;
+    readonly opencodegoCollector: OpenCodeGoAllowanceCollector;
+    constructor(credentials: AccountAllowanceCredentialReader, store?: AccountAllowanceStore, collector?: ClaudeAllowanceCollector, codexCollector?: CodexAllowanceCollector, kimiCollector?: KimiAllowanceCollector, opencodegoCollector?: OpenCodeGoAllowanceCollector, now?: () => number);
     /**
-     * Read all/filtered snapshots. Claude's five-minute cache is refreshed lazily;
-     * Codex remains passive and reports not-observed until a real model response.
+     * Read all/filtered snapshots. Claude's and Codex's five-minute caches are
+     * refreshed lazily on read (Codex polls `/backend-api/wham/usage`; the
+     * passive `x-codex-*` header tap still feeds mid-flight updates).
      */
     list(filter?: AccountAllowanceFilter): Promise<AccountAllowanceSnapshot[]>;
+    private knownAccounts;
     /** Force-refresh Claude usage for one account or every stored Claude account. */
     refreshClaude(accountId?: string): Promise<AccountAllowanceSnapshot[]>;
     /**
-     * Keep Claude snapshots warm for allowance-aware routing. This deliberately
-     * excludes Codex (whose quota is learned from real response headers) and
-     * preserves the collector's cache + per-account in-flight coalescing.
+     * Force-refresh Codex usage (`/backend-api/wham/usage`) for one account or
+     * every stored Codex account. Replaces the old probe-request workaround —
+     * no quota is spent reading the usage endpoint.
+     */
+    refreshCodex(accountId?: string): Promise<AccountAllowanceSnapshot[]>;
+    /** Force-refresh OpenCodeGo usage (`{go}/v1/usage`) for one/all accounts. */
+    refreshOpenCodeGo(accountId?: string): Promise<AccountAllowanceSnapshot[]>;
+    /** Force-refresh Kimi usage (`/coding/v1/usages`) for one/all accounts. */
+    refreshKimi(accountId?: string): Promise<AccountAllowanceSnapshot[]>;
+    /**
+     * Keep Claude + Codex + Kimi snapshots warm for allowance-aware routing. All
+     * collectors preserve their cache + per-account in-flight coalescing; a tick
+     * normally performs no network I/O. (Codex joined the warm path when it
+     * gained an active `/wham/usage` collector — the passive `x-codex-*` header
+     * tap alone could not keep the policy fed while idle.)
      */
     maintainClaudeCache(refreshAheadMs: number): Promise<void>;
     /** Remove a cache row as soon as an account is deleted by the admin path. */
@@ -1743,6 +1967,62 @@ type AuditCompactor = () => {
 /** The read surface the AdminServer consumes (bootstrap binds it to the ledger dir). */
 type BillingStatusReader = () => BillingDeliveryStatus;
 
+/**
+ * ProviderKeyQuota — BYO provider-row key quota parsing (pure functions).
+ *
+ * Subscription accounts have the daemon's allowance collectors; BYO rows (API
+ * keys pasted from a provider console) had NO quota surface at all. Several CN
+ * coding-plan providers expose a same-key usage endpoint:
+ *
+ *  - Z.AI / Zhipu bigmodel (GLM Coding Plan):
+ *      GET {origin}/api/monitor/usage/quota/limit
+ *      Raw `Authorization: <key>` (NO Bearer prefix). Envelope
+ *      `{success, data: {limits[], level}}`; each limit carries
+ *      `{type, usage(limit), currentValue(used), percentage, remaining,
+ *        nextResetTime, unit(3=h/4=d/5=mo/6=w), number, usageDetails[]}`.
+ *      A coding-plan key reports 5h + weekly credit windows; a PAYG key's shape
+ *      is unknown → defensive parse, unavailable on surprise.
+ *  - MiniMax Token Plan:
+ *      GET {origin}/v1/token_plan/remains
+ *      `Authorization: Bearer <key>`. HTTP is ALWAYS 200 — `base_resp
+ *      .status_code === 0` is the real success gate. `model_remains[]` buckets
+ *      each carry a rolling interval + weekly window as REMAINING percent
+ *      (0-100); the `"general"` bucket is the plan-wide shared quota.
+ *
+ * Everything here is pure; the fetch/cache lifecycle lives in
+ * `ProviderKeyQuotaService`. Windows reuse the subscription `AllowanceWindow`
+ * DTO so the UI renders one shape.
+ */
+
+/** Which quota adapter applies to a provider row (by resolved endpoint). */
+type ProviderKeyQuotaAdapter = 'zai' | 'minimax-token-plan' | 'umans' | 'synthetic';
+
+/**
+ * ProviderKeyQuotaService — read-through quota cache for BYO provider-row keys.
+ *
+ * The UI polls `GET /admin/api/providers/:id/keys` every few seconds for pool
+ * health; this service backs the optional `quota` field on that DTO. A read is
+ * cache-first (5-minute TTL) with per-key in-flight coalescing, so the UI's poll
+ * cadence never translates into upstream request cadence. `force` (the refresh
+ * button) bypasses the cache. Failures degrade to a stale marker — quota
+ * telemetry must never break the keys view.
+ *
+ * The key plaintext is resolved from the live row (same synthesis as the pool
+ * loader: explicit `apiKeys[]` else the single-key fallback) and decrypted via
+ * the injected box; it is used ONLY for the upstream Authorization header and
+ * never appears in any returned DTO.
+ */
+
+/** Secret-free quota view for one pool key. */
+interface ProviderKeyQuota {
+    adapter: ProviderKeyQuotaAdapter;
+    observedAt: string;
+    expiresAt: string;
+    windows: AllowanceWindow[];
+    /** Stable display-safe diagnostic code on a failed probe. */
+    errorCode?: string;
+}
+
 type PreparedImageRuntimeGeneration = {
     readonly id: string;
     readonly enabled: true;
@@ -2511,6 +2791,12 @@ interface AccountAllowanceAdminReader {
         accountId?: string;
     }): Promise<AccountAllowanceSnapshot[]>;
     refreshClaude(accountId?: string): Promise<AccountAllowanceSnapshot[]>;
+    /** Optional: Codex active `/wham/usage` refresh (absent on older daemons). */
+    refreshCodex?(accountId?: string): Promise<AccountAllowanceSnapshot[]>;
+    /** Optional: Kimi `/coding/v1/usages` refresh (absent on older daemons). */
+    refreshKimi?(accountId?: string): Promise<AccountAllowanceSnapshot[]>;
+    /** Optional: OpenCodeGo `/v1/usage` refresh (absent on older daemons). */
+    refreshOpenCodeGo?(accountId?: string): Promise<AccountAllowanceSnapshot[]>;
     removeAccountSnapshot?(providerId: SubscriptionProviderId, accountId: string): void;
     removeProviderSnapshots?(providerId: SubscriptionProviderId): void;
     getSchedulingStatus?(): AccountAllowanceSchedulingStatus;
@@ -2535,6 +2821,16 @@ interface PoolKeyHealth {
 interface PoolHealthReader {
     getKeyHealth(providerId: string): Promise<Record<string, PoolKeyHealth>>;
 }
+/**
+ * The BYO provider-key quota surface the keys view needs — structurally
+ * satisfied by `ProviderKeyQuotaService`. Read-only; the DTO is secret-free by
+ * construction (normalized windows + diagnostic codes only).
+ */
+interface ProviderKeyQuotaReader {
+    quotaFor(row: DaemonProviderConfig, keyId: string, options?: {
+        force?: boolean;
+    }): Promise<ProviderKeyQuota | null>;
+}
 interface AdminImagesStatusReader {
     inspectCapability(apiKeyId: string): Promise<ImageRuntimeCapabilityInspection>;
     status(): ImageRuntimeManagerStatus;
@@ -2612,6 +2908,12 @@ interface AdminApiDeps {
     readonly apiKeyPool: PoolHealthReader;
     /** In-memory auto-disable store (design D5) — read-only for the health view. */
     readonly autoDisableStore: AutoDisableStore;
+    /**
+     * OPTIONAL BYO provider-key quota service — same-key usage/quota probes for
+     * provider rows with a known adapter (Z.AI coding plan, MiniMax Token Plan).
+     * Absent ⇒ the keys view carries no `quota` field (light embedders).
+     */
+    readonly providerKeyQuota?: ProviderKeyQuotaReader;
     /**
      * Pending interactive-OAuth sessions (app-parity child 4, design D1) — the
      * in-memory `{ codeVerifier, state }` map keyed by a minted `sessionId`,
@@ -2639,6 +2941,11 @@ interface AdminApiDeps {
      * flight (port 1455 is one resource). Wired in `bootstrap.ts`.
      */
     readonly codexSessions: CodexOAuthSessionStore;
+    /**
+     * Kimi interactive-OAuth flow store (device code). Same token-free polled
+     * shape as codex; one sign-in at a time. Wired in `bootstrap.ts`.
+     */
+    readonly kimiSessions: CodexOAuthSessionStore;
     /**
      * Codex loopback listener (app-parity-2 child 5) — defaults to `awaitLoopbackCode`
      * (binds 127.0.0.1:1455) in `bootstrap.ts`; tests inject a mock so no real port
@@ -3467,7 +3774,6 @@ declare function createImageRuntimeGeneration(options: ImageRuntimeGenerationFac
  * @module @omnicross/daemon/ports/JsonOutboundKeyDb
  */
 
-type AtomicFileReplace = (targetPath: string, contents: string) => void;
 declare class JsonOutboundKeyDb implements OutboundKeyDb {
     private readonly keysPath;
     private readonly secretBox?;