@omnicross/daemon 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1375 @@
+import { ApiKeyPoolService } from '@omnicross/core/completion/ApiKeyPoolService';
+import { OutboundKeyDb, OutboundApiServer } from '@omnicross/core/outbound-api';
+import { ProviderProxy } from '@omnicross/core/provider-proxy';
+import { SubscriptionCredentialStore, FetchLike, SubscriptionProviderRegistry, SubscriptionAccountService } from '@omnicross/subscriptions';
+import { OutboundApiServerConfig, ProviderConfigSource, TransformerService, Transformer, ResolvedTransformerChain, ApiServerSettingsStore, Logger, OutboundKeyDb as OutboundKeyDb$1, OutboundKeyDbRow } from '@omnicross/core';
+import http from 'node:http';
+import { LLMProvider, AgentDefaultModels, GlobalModelParameters } from '@omnicross/contracts/llm-config';
+import { OpenCodeGoTokenConfig, SubscriptionProviderId } from '@omnicross/contracts/subscription-types';
+import { ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, AccountTokensConfig, SubscriptionAccountSanitized } from '@omnicross/contracts/account-tokens-types';
+
+/**
+ * SecretBox.ts — a 32-byte master key wrapped with the tri-state secret rules
+ * (secrets design D2/D7).
+ *
+ * `SecretBox` holds the resolved master key (never exposed) and applies the
+ * tri-state discrimination on top of the pure `envelope.ts` codec:
+ *
+ *   `$`-prefix   → ENV indirection: ALWAYS plaintext, never encrypted (resolved
+ *                  later by the pool's `resolveEnvKey`). Passthrough both ways.
+ *   `enc:`       → ciphertext: decrypted on read, left as-is on write.
+ *   else         → legacy plaintext: passed through on read, encrypted on write.
+ *
+ * `decryptMaybe` / `encryptMaybe` are the idempotent seam every read/write
+ * accessor calls — applying either repeatedly never changes a correctly-typed
+ * value (no `enc:enc:` nesting, no double-decrypt). `decrypt` wraps a GCM
+ * auth-tag failure (wrong key / tampered envelope) into an actionable,
+ * secret-free error — it NEVER echoes the key or the ciphertext.
+ *
+ * LAZY KEY (secrets design D3 — "首次需要时自动生成"): the constructor accepts
+ * either a resolved 32-byte Buffer OR a `() => Buffer` resolver. The key is only
+ * resolved on the FIRST `encrypt`/`decrypt` (then cached). The tri-state
+ * passthroughs (`$ENV` / empty / non-envelope-on-read) return BEFORE the key is
+ * touched — so a pure legacy-plaintext load that only passes values through
+ * NEVER triggers key resolution, and therefore never auto-generates a keyfile.
+ * A keyfile is materialized only when an `enc:` value must be decrypted or a
+ * write must encrypt (the resolver does the lazy auto-gen).
+ *
+ * @module @omnicross/daemon/secrets/SecretBox
+ */
+/** A resolved master key, or a lazy resolver that produces one on first use. */
+type MasterKeyInput = Buffer | (() => Buffer);
+declare class SecretBox {
+    /** The raw 32-byte master key (resolved lazily). Held privately; never logged. */
+    private key;
+    /** The lazy resolver (used once, then nulled after caching the key). */
+    private resolver;
+    constructor(key: MasterKeyInput);
+    /** Resolve (and cache) the master key on first crypto use. Validates length. */
+    private getKey;
+    /** Encrypt a plaintext value into a fresh `enc:v1:...` envelope (unconditional). */
+    encrypt(plain: string): string;
+    /**
+     * Decrypt an `enc:v1:...` envelope to plaintext. Wraps a GCM verification
+     * failure (wrong master key or a tampered envelope) into a clear, actionable
+     * error — the original crypto error (which carries no secret material) is
+     * intentionally NOT re-surfaced verbatim and the ciphertext/key are never
+     * placed in the message.
+     */
+    decrypt(envelope: string): string;
+    /**
+     * READ-direction tri-state: decrypt an `enc:` envelope; pass a `$ENV`
+     * reference or legacy plaintext through unchanged. Idempotent on any
+     * non-envelope value.
+     */
+    decryptMaybe(value: string): string;
+    /**
+     * WRITE-direction tri-state: encrypt legacy plaintext; pass a `$ENV` reference
+     * (never encrypt indirection) or an already-`enc:` envelope (no `enc:enc:`
+     * nesting) through unchanged. Idempotent — re-applying never re-encrypts.
+     */
+    encryptMaybe(value: string): string;
+}
+
+/**
+ * config.ts — the daemon's `config.json` schema + load/save (design D9).
+ *
+ * The daemon is BYO-key and factory-less: its `config.json` provider rows ARE
+ * the provider catalog the `ConfigFileProviderConfigSource` serves. The `server`
+ * field is the same `OutboundApiServerConfig` shape `loadServerConfig`
+ * normalizes (persisted via `JsonApiServerSettingsStore` under the single
+ * `'outboundApiServer.config'` key).
+ *
+ * `loadConfig(path)` reads + shape-guards; `saveConfig(path, cfg)` writes pretty
+ * JSON. The loader is defensive (best-effort, never throws on a partial file) so
+ * the CLI surfaces a clear error rather than a stack trace.
+ *
+ * AT-REST ENCRYPTION (secrets design D5/D7): a MODULE-LEVEL `SecretBox` is
+ * injected via `setSecretBox` (by bootstrap + each offline CLI command). When
+ * set, `loadConfig` decrypts the secret fields (`apiKey`/`apiKeys[].apiKey`/
+ * `admin.token`) AFTER the shape-guard (envelopes are strings → shape-guard
+ * passes), and `saveConfig` encrypts them before writing. When NOT set (box =
+ * null), both are a no-op passthrough — so the existing pure tests that call
+ * `loadConfig`/`saveConfig`/`validateConfig` without a box are byte-unchanged.
+ * `$ENV` references are never encrypted (the box's tri-state passthrough).
+ *
+ * @module @omnicross/daemon/config
+ */
+
+/** The wire formats the daemon's BYO providers can speak. */
+type DaemonApiFormat = 'openai' | 'anthropic' | 'gemini';
+/**
+ * One pool key on a provider row (design D1). Structurally compatible with
+ * core's `ApiKeyEntry` (`@omnicross/contracts/llm-config`) — a hand-authored SUBSET: only
+ * `id` + `apiKey` are required, the rest carry sensible defaults applied at
+ * load time (`pool/loadPoolKeys.ts` normalizes a `DaemonApiKeyEntry` up to the
+ * full `ApiKeyEntry` core consumes, filling `providerId`/`label`/`weight`/
+ * `enabled`/`sortOrder`). config.json should not have to hand-write core's
+ * DB/UI fields (`providerId`/`sortOrder`/`hasKey`/`disabledReason`/…).
+ */
+interface DaemonApiKeyEntry {
+    /** Stable id — the pool's selection / cooldown / auto-disable key. */
+    id: string;
+    /** The BYO key (literal, or a `$ENV_VAR` reference resolved at call time). */
+    apiKey: string;
+    /** Display name (defaults to `id`). */
+    label?: string;
+    /** Whether this key is selectable (defaults to `true`). */
+    enabled?: boolean;
+    /** Weighted round-robin weight (defaults to `1`). */
+    weight?: number;
+}
+/**
+ * Per-model metadata subset (app-parity child 2). A hand-authored SUBSET of the
+ * app's `ModelConfig` (`app/src/shared-types/llm-config.ts`), carrying ONLY the
+ * named-five fields the daemon stores + round-trips, keyed by the model `id`:
+ * `name` (display name), `enabled`, `group`, `vision`, `reasoning`. The wider
+ * `ModelConfig` fields the discovery flow may send (`category`/`contextLength`/
+ * `maxTokens`/`functionCall`/`webSearch`/`completionSettings`/`openRouterProvider`/
+ * `thinkingLevels`/…) are NOT in this allowlist — they are DROPPED by
+ * deny-by-default (`validateModelConfigs`/`parseModelConfigsInput`).
+ *
+ * ENFORCEMENT (app-parity-2 child 2): `enabled` is now a DISCOVERY/advertisement
+ * gate — `toLLMProvider` drops a `enabled: false` model from the routed provider's
+ * `models[]`, so the served catalog no longer lists it. HONEST SCOPE: this gates
+ * advertisement, NOT a hard per-request block (core does not validate a requested
+ * model against `models[]`, so a hardcoded disabled model id still reaches the
+ * upstream, which rejects it). The admin management view (`toProviderView`) still
+ * lists ALL models. The other fields (`name`/`group`/`vision`/`reasoning`) remain
+ * display-only metadata (no core per-model capability binding on the BYO path).
+ */
+interface DaemonModelConfig {
+    /** Model id — the metadata key (parallels an entry in the flat `models[]`). */
+    id: string;
+    /** Display name (display/management only; not consumed by routing). */
+    name?: string;
+    /** Enable flag — DISCOVERY GATE (parity-2 child 2): `false` drops the model from
+     *  the routed/advertised catalog; not a hard per-request block. */
+    enabled?: boolean;
+    /** Display group label (app derives groups from this — no separate daemon array). */
+    group?: string;
+    /** Vision-capable hint (display only; not consumed by routing). */
+    vision?: boolean;
+    /** Reasoning-capable hint (display only; not consumed by routing). */
+    reasoning?: boolean;
+}
+/**
+ * One transformer chain entry (app-parity child 5). Mirrors the app's
+ * `TransformerEntry`: either a bare transform-rule NAME (`string`), or a
+ * `[name, options]` tuple carrying that rule's options. NON-SECRET (rule names +
+ * options — no key material).
+ */
+type DaemonTransformerEntry = string | [string, Record<string, unknown>];
+/**
+ * Provider transformer config subset (app-parity child 5). Mirrors the app's
+ * `TransformerConfig` PROVIDER-LEVEL portion: `use[]` is the provider-level
+ * transform chain. The index signature preserves any per-model transformer keys
+ * (`[modelName]`) VERBATIM as an opaque value so a round-trip is non-lossy — the
+ * minimal editor only edits `use[]`, but stored per-model keys are not dropped.
+ *
+ * ENFORCED (app-parity-2 child 2): the daemon APPLIES this `use[]` chain in the
+ * request pipeline. `ConfigFileProviderConfigSource.resolveTransformerChain`
+ * resolves the custom `use[]` into the provider chain, composed FORMAT-FIRST — the
+ * format transformer (anthropic/gemini, supplied by `getMainTransformer` and
+ * prepended by core's `resolveProviderChain`) runs before the custom transformers,
+ * preserving the load-bearing wire-format conversion. An unknown transformer name
+ * is warned + skipped (lenient). Additive + back-compat: absent (or empty `use[]`)
+ * reads as undefined and resolves to the format transformer alone — byte-identical
+ * to before. NON-SECRET — round-trips verbatim on GET (no masking).
+ */
+interface DaemonTransformerConfig {
+    /** Provider-level transform chain (the UI count + the minimal editor surface). */
+    use?: DaemonTransformerEntry[];
+    /** Per-model transformer keys preserved verbatim (opaque — not edited here). */
+    [modelName: string]: unknown;
+}
+/**
+ * Coding-plan endpoint config (app-parity-2 child 3). The provider's "coding-plan"
+ * subscription endpoint (e.g. domestic providers' 编程套餐 — Zhipu GLM Coding Plan,
+ * DashScope, DeepSeek, Kimi …): an OPTIONAL alternate endpoint with its OWN
+ * `baseUrl` + `apiKey`, distinct from the pay-as-you-go API key. Structurally
+ * identical to the contracts `CodingPlanConfig` (`@omnicross/contracts/provider-presets`)
+ * so a daemon row's `codingPlan` assigns straight onto `LLMProvider.codingPlan`.
+ *
+ * SECRET-BEARING: `apiKey` is encrypted at rest (registered in
+ * `secretFields.transformProvider`) and NEVER serialized back out — the masked GET
+ * view returns only a `hasApiKey` boolean.
+ *
+ * ENFORCED BY CORE, NOT THE DAEMON: the daemon does NOT contain its own endpoint
+ * resolver. It only POPULATES `LLMProvider.codingPlan` in `toLLMProvider`; the
+ * shared `resolveProviderEndpoint` (`@omnicross/contracts/endpoint-resolver`, layer
+ * 2: `apiModes > codingPlan > plain`) — already wired into core's `buildProviderApiUrl`
+ * (URL) and the BYO proxy key path — does the actual routing (when `enabled` AND a
+ * `baseUrl` is set, the request uses this `baseUrl` + `apiKey`, key falling back to
+ * the provider's main key when empty). Additive + back-compat: absent → undefined.
+ */
+interface DaemonCodingPlanConfig {
+    /** Whether the coding-plan endpoint is active (core routes via baseUrl/apiKey below). */
+    enabled: boolean;
+    /** Dedicated base URL — when set AND enabled, core overrides the provider's baseUrl. */
+    baseUrl?: string;
+    /** Dedicated key (SECRET; literal or `$ENV`). Empty → core falls back to the main key. */
+    apiKey?: string;
+    /** Free-text plan note (display/management only). */
+    note?: string;
+}
+/**
+ * One API mode (app-parity-2 child 4). The provider's selectable endpoint "mode"
+ * (e.g. `standard` / `coding-plan` / `token-plan` for domestic providers): each
+ * carries its own `baseUrl` + an OPTIONAL `apiKey`. Structurally identical to the
+ * contracts `ApiMode` so a daemon row's `apiModes` assigns straight onto
+ * `LLMProvider.apiModes`. SECRET-BEARING: `apiKey` is encrypted at rest
+ * (`secretFields`) + masked on GET (`hasApiKey` only) — never serialized out.
+ * ENFORCED BY CORE: `toLLMProvider` populates `apiModes`/`selectedApiModeId`; the
+ * shared `resolveProviderEndpoint` (layer 1) reports `source:'api-mode'` and uses
+ * `api_base_url || mode.baseUrl`. The row's `baseUrl`/`apiKey` hold the EFFECTIVE
+ * endpoint (synced on switch — baseUrl app-side, the secret key server-side).
+ */
+interface DaemonApiMode {
+    /** Stable mode id within the provider. */
+    id: string;
+    /** i18n key or display label. */
+    label: string;
+    /** This mode's endpoint base URL. */
+    baseUrl: string;
+    /** This mode's OPTIONAL key (SECRET; literal or `$ENV`). */
+    apiKey?: string;
+    /** Optional API-key prefix hint (e.g. `sk-tp-`). Non-secret. */
+    apiKeyPrefix?: string;
+    /** Optional note (i18n key). Non-secret. */
+    note?: string;
+}
+/** One BYO provider row — the unit the `ProviderConfigSource` serves. */
+interface DaemonProviderConfig {
+    /** Stable id referenced by the per-endpoint `"<id>,<model>"` model refs. */
+    id: string;
+    /**
+     * OPTIONAL mutable display name (app-parity-2 child 1), SEPARATE from the
+     * immutable `id`. The `id` stays the identity key (model refs, pool, accounts);
+     * `name` is a free-text label the rename UI edits. Additive + back-compat:
+     * absent reads as undefined and the app falls back to displaying the `id`.
+     * NON-SECRET — round-trips verbatim on GET (no masking).
+     */
+    name?: string;
+    /** The provider's wire format (drives the transformer chain). */
+    apiFormat: DaemonApiFormat;
+    /** The upstream base URL (e.g. `https://api.openai.com/v1`). */
+    baseUrl: string;
+    /** The BYO API key (literal, or a `$ENV_VAR` reference resolved at call time). */
+    apiKey: string;
+    /** Optional advertised model list (informational; routing uses the model ref). */
+    models?: string[];
+    /**
+     * OPTIONAL per-model metadata (app-parity child 2), keyed by model id, PARALLEL
+     * to the flat `models[]`. Additive + back-compat: a row with only `models[]`
+     * (no `modelConfigs`) loads unchanged and reads as undefined metadata; the flat
+     * `models[]` stays AUTHORITATIVE for the model catalog. ENFORCEMENT (parity-2
+     * child 2): `enabled` is a DISCOVERY GATE — `toLLMProvider` drops a
+     * `enabled: false` model from the routed `models[]` (advertisement-scoped, not a
+     * hard per-request block; the admin view still lists all). `name`/`group`/
+     * `vision`/`reasoning` stay display-only. Group lives here as `modelConfigs[].group`
+     * (no separate daemon `modelGroups[]`). None of the fields are secrets — verbatim on GET.
+     */
+    modelConfigs?: DaemonModelConfig[];
+    /**
+     * OPTIONAL multi-key pool (design D1, key-pool change). When present, the
+     * `ApiKeyPoolService` loads these for observable health + (future) failover.
+     * **Absent `apiKeys` = single-key behavior byte-identical to before** — the
+     * pool synthesizes a 1-key pool from `apiKey` and the outbound take-key path
+     * is unchanged. The single `apiKey` field is RETAINED as the fallback.
+     */
+    apiKeys?: DaemonApiKeyEntry[];
+    /**
+     * OPTIONAL enable flag (app-foundation D8). When absent, the provider reads as
+     * ENABLED (back-compat: existing `config.json` rows with no `enabled` field are
+     * treated as enabled). Surfaced on the admin GET DTO (`enabled: row.enabled !==
+     * false`) and accepted by the provider write path (PUT). Purely a management-UI
+     * concern — the routing/outbound paths do not consume it yet.
+     */
+    enabled?: boolean;
+    /**
+     * OPTIONAL "official provider" management flag (app-parity child 1). Additive +
+     * back-compat: absent reads as the prior default (undefined). NON-SECRET —
+     * round-trips verbatim on GET (no masking). Management-UI only; the
+     * routing/outbound paths do not consume it.
+     */
+    isOfficial?: boolean;
+    /**
+     * OPTIONAL API version (e.g. an Azure `api-version`) (app-parity child 1).
+     * Additive + back-compat: absent reads as the prior default (undefined).
+     * NON-SECRET — round-trips verbatim on GET. Management-UI only (not yet consumed
+     * by the outbound path).
+     */
+    apiVersion?: string;
+    /**
+     * OPTIONAL max-concurrency hint (app-parity child 1). Additive + back-compat:
+     * absent reads as the prior default (undefined). NON-SECRET — round-trips
+     * verbatim on GET. Management-UI only (not yet enforced by the routing path).
+     */
+    maxConcurrency?: number;
+    /**
+     * OPTIONAL custom models endpoint URL (app-parity child 1). Additive +
+     * back-compat: absent reads as the prior default (undefined). NON-SECRET —
+     * round-trips verbatim on GET. Management-UI only.
+     */
+    modelsEndpoint?: string;
+    /**
+     * OPTIONAL provider transformer config (app-parity child 5). Additive +
+     * back-compat: absent reads as the prior default (undefined). NON-SECRET —
+     * round-trips verbatim on GET (no masking). ENFORCED (parity-2 child 2): the
+     * daemon APPLIES the custom `use[]` chain in the request pipeline, FORMAT-FIRST
+     * (see `DaemonTransformerConfig`); absent/empty resolves to the format
+     * transformer alone (byte-identical to before).
+     */
+    transformer?: DaemonTransformerConfig;
+    /**
+     * OPTIONAL coding-plan endpoint (app-parity-2 child 3). SECRET-BEARING (its
+     * `apiKey` is encrypted at rest + masked on GET). Populated onto
+     * `LLMProvider.codingPlan` by `toLLMProvider`; ENFORCED by core's shared
+     * `resolveProviderEndpoint` (the daemon does not resolve endpoints itself).
+     * Additive + back-compat: absent reads as undefined.
+     */
+    codingPlan?: DaemonCodingPlanConfig;
+    /**
+     * OPTIONAL API modes (app-parity-2 child 4) — selectable endpoint modes. Each
+     * mode's `apiKey` is SECRET (encrypted at rest, masked on GET). Populated onto
+     * `LLMProvider.apiModes` by `toLLMProvider`; the SELECTED mode drives core's
+     * `resolveProviderEndpoint` (layer 1). Additive + back-compat: absent → undefined.
+     */
+    apiModes?: DaemonApiMode[];
+    /** OPTIONAL id of the active API mode (app-parity-2 child 4). */
+    selectedApiModeId?: string;
+}
+/**
+ * The admin-dashboard config block (RT3 design D8). All fields optional;
+ * defaults are applied at read time by `resolveAdminConfig`.
+ *
+ * SECURITY: `token` is a SEPARATE secret (NOT a named outbound key). It is never
+ * serialized back out by any management-API GET — the masking spine treats it
+ * like every other secret (in, never out).
+ */
+interface DaemonAdminConfig {
+    /** Dashboard on by default; `false` opts out (same as `--no-dashboard`). */
+    enabled?: boolean;
+    /** Admin server port (default 8766; distinct from the 8765 outbound server). */
+    port?: number;
+    /** Bind `0.0.0.0` (LAN) instead of `127.0.0.1`. Requires `token` (fail-closed). */
+    networkBinding?: boolean;
+    /** Optional bearer secret; when set every `/admin/*` request must carry it. */
+    token?: string;
+}
+/** Resolved admin config with defaults applied (read-time view). */
+interface ResolvedAdminConfig {
+    enabled: boolean;
+    port: number;
+    networkBinding: boolean;
+    token: string | undefined;
+}
+/** The default admin port (distinct from the 8765 outbound server). */
+declare const DEFAULT_ADMIN_PORT = 8766;
+/** The full daemon config. */
+interface DaemonConfig {
+    providers: DaemonProviderConfig[];
+    /** Persisted outbound-API server config (same shape `loadServerConfig` normalizes). */
+    server?: OutboundApiServerConfig;
+    /** Optional admin-dashboard config (RT3). */
+    admin?: DaemonAdminConfig;
+}
+/** Apply defaults to a (possibly absent) admin block: enabled, port 8766,
+ *  loopback, no token. NOTE: an EXPLICIT `port: 0` is honored as "bind an
+ *  ephemeral port" (it is NOT coerced to the default); only an absent/undefined
+ *  port falls back to `DEFAULT_ADMIN_PORT`. */
+declare function resolveAdminConfig(admin: DaemonAdminConfig | undefined): ResolvedAdminConfig;
+/** Validate a parsed config object into a typed `DaemonConfig`. */
+declare function validateConfig(raw: unknown): DaemonConfig;
+/** Read + validate the config.json at `path`. When a `SecretBox` is set, the
+ *  secret fields are decrypted AFTER shape-guarding (envelopes are strings, so
+ *  the guard passes); the returned config carries DECRYPTED values. */
+declare function loadConfig(path: string): DaemonConfig;
+/** Write `cfg` to `path` as pretty JSON. When a `SecretBox` is set, the secret
+ *  fields are encrypted-on-write (legacy plaintext → `enc:v1:`; `$ENV`/already-
+ *  `enc:` untouched) before serializing. */
+declare function saveConfig(path: string, cfg: DaemonConfig): void;
+
+/**
+ * JsonSubscriptionCredentialStore — the daemon's file-backed
+ * `SubscriptionCredentialStore` port impl (design D1).
+ *
+ * Implements `@omnicross/subscriptions`' narrow six-method credential surface
+ * 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).
+ *
+ * The PORT surface is read-only by design: the codex / gemini strategies pull
+ * their access token via `getFullConfig().<provider>.accessToken`; only claude /
+ * opencodego have dedicated getters. No OAuth login flow is initiated here
+ * (strategies only consume + refresh, never log in).
+ *
+ * DAEMON-ONLY WRITE PATH (token-paste, design D1): `writeProviderTokens` /
+ * `clearProvider` are CONCRETE-CLASS methods — NOT part of the
+ * `SubscriptionCredentialStore` port. The registry / auth strategies / account
+ * service never see them (they hold the port type), so a mutation can never leak
+ * into the subscription block. Only the daemon admin API (which holds the
+ * concrete instance via `Daemon.credentialStore`) calls them. They read-merge a
+ * single provider block into `tokens.json` and re-persist; since `readConfig`
+ * re-reads on every call (NO cache), the next read immediately sees the write.
+ *
+ * AT-REST ENCRYPTION (secrets design D6/D7): the constructor takes a `SecretBox`.
+ * `readConfig` decrypts the token-material fields on read (so every getter +
+ * `getFullConfig` returns PLAINTEXT tokens — the subscription bearer path is
+ * byte-identical), and `persist` encrypts them before writing. Because EVERY
+ * write funnels through `persist`, the OAuth-refresh writes below are encrypted
+ * at-rest with NO extra work (the store API guarantees it). The "re-read on every
+ * call, no cache" semantics are unchanged.
+ *
+ * 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
+ * `fetch`), then read-merge the refreshed fields into the provider block and
+ * write back through `persist` (→ encrypted). Field-writes:
+ * claude/codex write access+refresh(+codex idToken)
+ * +expiresAt+status:authorized+lastRefreshedAt; gemini writes ONLY access+
+ * expiresAt (its refresh response omits refresh_token → the OLD value is reused,
+ * never overwritten). On any failure the block is marked `status:'expired'` +
+ * errorMessage and `false` is returned. When the block has NO refresh_token
+ * (claude setup-token, manual token), it is an HONEST `false` BEFORE any upstream
+ * call — the block is not touched and no refresh_token is invented.
+ *
+ * @module @omnicross/daemon/ports/JsonSubscriptionCredentialStore
+ */
+
+/**
+ * The per-provider token block accepted by `writeProviderTokens`. Mirrors the
+ * `AccountTokensConfig` per-provider field types (one of the four contract token
+ * 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;
+declare class JsonSubscriptionCredentialStore implements SubscriptionCredentialStore {
+    private readonly tokensPath;
+    private readonly box;
+    private readonly fetchImpl;
+    /**
+     * @param tokensPath  on-disk `tokens.json` location.
+     * @param box         at-rest `SecretBox` (encrypt-on-write / decrypt-on-read).
+     * @param fetchImpl   injectable HTTP port for the OAuth refresh round-trips
+     *                    (oauth design D4). Defaults to the global `fetch` so boot
+     *                    is unchanged; tests inject a mock fetch. NOT used by any
+     *                    read/write path — only by `refresh*Token`.
+     */
+    constructor(tokensPath: string, box: SecretBox, fetchImpl?: FetchLike);
+    /** Full parsed account-tokens config (or a minimal `{ updatedAt }` when the
+     *  file is absent/corrupt). This is the hot read — the codex / gemini auth
+     *  strategies pull `accessToken` / `expiresAt` / `status` from it. */
+    getFullConfig(): Promise<AccountTokensConfig>;
+    /** Current Claude OAuth access token, or `null` when none is stored. No inline
+     *  refresh here — the lead-window / 401-retry refresh is driven by the
+     *  subscription auth strategy, which calls `refreshClaudeToken` (now real). */
+    getValidClaudeAccessToken(): Promise<string | null>;
+    /** Current OpenCodeGo static API key, or `null` when none is stored. */
+    getValidOpenCodeGoApiKey(): Promise<string | null>;
+    /**
+     * DAEMON-ONLY sanitized accounts list (design D8, NOT on the port). Projects
+     * each provider's accounts to the secret-free `SubscriptionAccountSanitized`
+     * shape (id/label/status/expiresAt/hasAccessToken/isActive) — NEVER a token.
+     * Used by the admin accounts GET (secret-IN-never-OUT).
+     */
+    listSanitizedAccounts(): Promise<Record<string, SubscriptionAccountSanitized[]>>;
+    /**
+     * Refresh the Claude OAuth access token (oauth design D4). HONEST `false` when
+     * the block has no refresh_token (setup-token / manual) — no upstream call, the
+     * block is untouched. Otherwise mint via the shared claude refresh flow and
+     * write back access+refresh+expiresAt+status:authorized+lastRefreshedAt.
+     * On failure → status:expired +
+     * errorMessage → `false`.
+     */
+    refreshClaudeToken(): Promise<boolean>;
+    /**
+     * Refresh the Codex (ChatGPT) OAuth access token. Same shape
+     * as claude, additionally writing back the refreshed `idToken`.
+     * HONEST `false` when no refresh_token.
+     */
+    refreshCodexToken(): Promise<boolean>;
+    /**
+     * Refresh the Gemini (Google) OAuth access token. The Google
+     * refresh response does NOT return a refresh_token, so this writes ONLY
+     * access+expiresAt (+status/lastRefreshedAt) and DELIBERATELY leaves the
+     * existing `refreshToken` untouched (overwriting it with `undefined` would
+     * destroy the ability to refresh again). HONEST `false` when no refresh_token.
+     */
+    refreshGeminiToken(): Promise<boolean>;
+    /**
+     * Materialize a lazily-synthesized account id to disk (design D3). On a legacy
+     * single-slot file, `readConfig` synthesizes a NON-deterministic account id
+     * per read; without persisting it, the later write-back (which re-reads) would
+     * synthesize a DIFFERENT id and miss the captured account. Persisting the
+     * migrated config here makes the id durable so the write-back keys correctly.
+     * Idempotent: a config whose ids are already on disk re-persists byte-equal.
+     */
+    private materializeMigration;
+    /**
+     * Write refreshed tokens back to the captured account by id (oauth design D4),
+     * re-derive the mirror from the CURRENT active id, re-stamp + persist. A switch
+     * mid-refresh leaves the refreshed tokens in the captured (now non-active)
+     * account and keeps the CURRENT active account's tokens in the mirror.
+     */
+    private writeBackById;
+    /**
+     * Mark the captured account `status:'expired'` + errorMessage on a refresh
+     * failure, keyed by id, then re-derive the mirror.
+     */
+    private markExpiredById;
+    /**
+     * DAEMON-ONLY WRITE (design D1, NOT on the port). Read-merge the given
+     * provider's token block into the current `AccountTokensConfig`, stamp a fresh
+     * `updatedAt`, and re-persist `tokens.json` as pretty JSON. Preserves every
+     * OTHER provider's existing block (read-merge-write, not overwrite). Reuses the
+     * tolerate-on-read base (`{ updatedAt: '' }` when the file is absent/corrupt),
+     * so a first-ever write still produces a valid config. No cache → the next read
+     * sees this write.
+     */
+    writeProviderTokens(providerId: SubscriptionProviderId, config: SubscriptionTokenBlock): Promise<void>;
+    /**
+     * DAEMON-ONLY login append (design D5, NOT on the port). Append a NEW account
+     * (optional label) and set it active, then re-derive the mirror — used by
+     * `omnicross login <provider> --label` to add an account instead of overwriting.
+     */
+    appendProviderAccount(providerId: SubscriptionProviderId, config: SubscriptionTokenBlock, label?: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * DAEMON-ONLY active switch (design D5, NOT on the port). Switch the active
+     * account for a provider; rejects an unknown id. Re-derives the mirror.
+     */
+    setActiveAccount(providerId: SubscriptionProviderId, id: string): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * DAEMON-ONLY per-account remove (design D5, NOT on the port). Remove one
+     * account; promote the most-recent remaining on active-removal (or clear the
+     * mirror when none remain). Re-derives the mirror.
+     */
+    removeAccount(providerId: SubscriptionProviderId, id: string): Promise<{
+        removed: boolean;
+    }>;
+    /**
+     * DAEMON-ONLY CLEAR (design D1/D3, NOT on the port). Remove a single provider's
+     * block from `tokens.json` and re-persist (the strategies already tolerate an
+     * absent block). Stamps a fresh `updatedAt`. A no-op-shaped write when the
+     * provider was already absent (still re-stamps + persists).
+     */
+    clearProvider(providerId: SubscriptionProviderId): Promise<void>;
+    /** 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. */
+    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).
+     *
+     * 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.
+     */
+    private readConfig;
+}
+
+/**
+ * accountsWrite — the daemon admin API's subscription-token WRITE path
+ * (`PUT|POST|DELETE /admin/api/accounts/:providerId`, design D1/D3/D4/D5).
+ *
+ * Extracted from `adminApi.ts` (file-size discipline, design D6) so the write
+ * handler + the per-provider body validators live in one focused module.
+ *
+ * SECRET SPINE (the load-bearing invariant): the token flows IN via the POST/PUT
+ * body and NEVER OUT. The write/clear response is STATUS-ONLY — the token-free
+ * `SubscriptionListEntry` for that provider (or a `{ ok: true }` ack). The handler
+ * NEVER serializes the request body (or any token field) back. The least-authority
+ * `SubscriptionTokenWriter` dep exposes ONLY `writeProviderTokens` / `clearProvider`,
+ * so this layer is structurally unable to read a stored token.
+ *
+ * @module @omnicross/daemon/admin/accountsWrite
+ */
+
+/**
+ * Least-authority writer handle (design D4): the admin write path sees ONLY the
+ * mutation methods of the credential store, never a token-returning read. Wired
+ * in `bootstrap.ts` from the concrete `daemon.credentialStore`.
+ */
+interface SubscriptionTokenWriter {
+    writeProviderTokens(providerId: SubscriptionProviderId, config: SubscriptionTokenBlock): Promise<void>;
+    clearProvider(providerId: SubscriptionProviderId): Promise<void>;
+    setActiveAccount(providerId: SubscriptionProviderId, id: string): Promise<{
+        ok: boolean;
+    }>;
+    removeAccount(providerId: SubscriptionProviderId, id: string): Promise<{
+        removed: boolean;
+    }>;
+    listSanitizedAccounts(): Promise<Record<string, SubscriptionAccountSanitized[]>>;
+}
+
+/**
+ * oauthSessions — the in-memory pending-OAuth-session store for the admin HTTP
+ * two-phase login (`POST /accounts/:providerId/oauth/{start,complete}`,
+ * app-parity child 4, design D1).
+ *
+ * `start` mints a crypto-random `sessionId` and stashes the per-session PKCE
+ * `{ providerId, codeVerifier, state }` here; `complete` does a SINGLE-USE
+ * `take(sessionId)` (returns + deletes) and exchanges the code. The map is
+ * NEVER serialized to the client — only the opaque `sessionId` + the public
+ * `authUrl` cross the wire. Sessions are short-lived (OQ3 = 10-min TTL); a sweep
+ * reaps abandoned sessions, and `take` re-checks the TTL so an expired-but-not-
+ * yet-swept session is still rejected. A daemon restart simply drops in-flight
+ * logins (correct fail-safe — no partial token is ever written).
+ *
+ * SECRET SPINE: the `codeVerifier` is a PKCE secret-ish value (useless without
+ * the matching `code`); it never leaves this module. No token is ever stored
+ * here — the exchanged token lands ONLY through the encrypted credential store.
+ *
+ * @module @omnicross/daemon/admin/oauthSessions
+ */
+
+/** One pending OAuth session (NEVER serialized to the client). */
+interface PendingOAuthSession {
+    readonly providerId: SubscriptionProviderId;
+    /** PKCE verifier — secret-ish; stays daemon-side, never echoed. */
+    readonly codeVerifier: string;
+    /** CSRF state minted with the auth params (validated on complete). */
+    readonly state: string;
+    /** Epoch ms the session was created (for the TTL sweep + take re-check). */
+    readonly createdAt: number;
+}
+/**
+ * Module-scoped store for pending OAuth sessions. A single instance is created
+ * per daemon (in `bootstrap.ts`) and wired through `AdminApiDeps`. The TTL sweep
+ * runs lazily on each `put`/`take` (no background timer to leak across tests).
+ */
+declare class OAuthSessionStore {
+    private readonly ttlMs;
+    private readonly sessions;
+    constructor(ttlMs?: number);
+    /**
+     * Mint a fresh opaque `sessionId`, stash the pending session, and return the
+     * id. Sweeps expired entries first so the map never grows unbounded.
+     */
+    put(session: Omit<PendingOAuthSession, 'createdAt'>): string;
+    /**
+     * SINGLE-USE consume: return + delete the session for `sessionId`, or `null`
+     * when it is unknown, already used, or past its TTL (in which case it is
+     * dropped). A `null` return means the completer must reject (no exchange, no
+     * write).
+     */
+    take(sessionId: string): PendingOAuthSession | null;
+    /** Drop every session past its TTL. Called on each put/take. */
+    private sweep;
+}
+
+/**
+ * accountsOAuth — the daemon admin API's INTERACTIVE OAuth login path
+ * (`POST /admin/api/accounts/:providerId/oauth/{start,complete}`, app-parity
+ * child 4, design D1/D2/D4).
+ *
+ * EXPOSES the existing `@omnicross/subscriptions/oauth` flow over admin HTTP as a
+ * two-phase pair — it does NOT rebuild PKCE / token-exchange. `start` builds the
+ * provider's authorize params and stashes the per-session `{ codeVerifier, state }`
+ * in the `OAuthSessionStore` keyed by a minted opaque `sessionId`, returning ONLY
+ * `{ authUrl, sessionId }` (the `authUrl` carries client_id + PKCE challenge +
+ * state — all public). `complete` does a SINGLE-USE `take(sessionId)`, validates
+ * state (claude's `code#state`), `exchangeCodeForTokens(...)`, persists the minted
+ * token through the encrypted credential store (`appendProviderAccount`) + marks
+ * it active, and responds ONLY the sanitized `SubscriptionListEntry`.
+ *
+ * SECRET SPINE (the load-bearing invariant): the minted access/refresh token
+ * NEVER appears in any response body or log; the `codeVerifier` / session map is
+ * never serialized; error messages reference the session/provider, never a token.
+ * At-rest encryption is inherited (the store's `SecretBox` → `enc:` envelope).
+ *
+ * OAuth-capable here = `claude` / `gemini` (code-paste). `codex` (loopback) is
+ * DEFERRED (OQ1) and `opencodego` is manual-only — both are rejected by `start`
+ * as oauth-unsupported (defensive; their app Sign-in stays `<Unbacked>`).
+ *
+ * @module @omnicross/daemon/admin/accountsOAuth
+ */
+
+/**
+ * NARROW append handle (design D2-a): the OAuth complete handler legitimately
+ * needs `appendProviderAccount` (multi-account append + activate) — a method NOT
+ * on the least-authority `SubscriptionTokenWriter`. Rather than widen that
+ * deliberate security boundary, `AdminApiDeps` carries this minimal interface
+ * (NOT the full read-capable store, so no token-returning read is reachable).
+ * Structurally satisfied by the concrete `JsonSubscriptionCredentialStore`.
+ */
+interface SubscriptionAccountAppender {
+    appendProviderAccount(providerId: SubscriptionProviderId, config: SubscriptionTokenBlock, label?: string): Promise<{
+        id: string;
+    }>;
+}
+
+/**
+ * accountsCodexOAuth — the daemon admin API's CODEX interactive OAuth path
+ * (`POST /accounts/codex/oauth/start` + `GET /accounts/codex/oauth/:sessionId/status`,
+ * app-parity-2 child 5).
+ *
+ * Codex differs from claude/gemini (which are CODE-PASTE, handled by
+ * `accountsOAuth.ts`): its redirect is a LOOPBACK to `http://localhost:1455/auth/callback`,
+ * so there is no code to paste — the browser hits the daemon's loopback listener
+ * directly. This makes the flow ASYNC + POLLED rather than two-phase paste:
+ *   - `start` builds the codex authorize params, ARMS the one-shot loopback
+ *     listener (`awaitLoopbackCode`, injected for tests), kicks the
+ *     capture→exchange→persist off ASYNC (fire-and-forget), and returns ONLY
+ *     `{ authUrl, sessionId }` (public — client_id + PKCE challenge + state).
+ *   - the app opens `authUrl`; the browser redirects to the loopback; the daemon
+ *     captures the `code`, validates `state`, `exchangeCodeForTokens`, and persists
+ *     the minted token through the encrypted credential store (`appendProviderAccount`).
+ *   - the app POLLS `status` until `done` / `error`, then refreshes `/accounts`.
+ *
+ * SECRET SPINE (the load-bearing invariant): the minted access/refresh/id token
+ * NEVER crosses to the client — it lands ONLY in the encrypted store. The poll
+ * `status` body is TOKEN-FREE (`{ state, message? }`); error messages reference the
+ * loopback/exchange failure, never a token. The PKCE `codeVerifier` stays in this
+ * module's closure (never serialized). Port 1455 is a single resource → only ONE
+ * codex sign-in may be in flight at a time (a second `start` → 409).
+ *
+ * REUSES the existing `@omnicross/subscriptions` codex flow + the CLI's
+ * `awaitLoopbackCode` listener — it does NOT rebuild PKCE / token-exchange / the
+ * loopback server.
+ *
+ * @module @omnicross/daemon/admin/accountsCodexOAuth
+ */
+
+/** The loopback-listener fn (injected so tests need not bind a real port). */
+type CodexLoopbackFn = (state: string, timeoutMs?: number) => Promise<string>;
+/** One codex sign-in flow's polled status (NEVER carries a token). */
+interface CodexFlowState {
+    status: 'pending' | 'done' | 'error';
+    /** Loopback/exchange failure reason (NEVER a token). Present only on 'error'. */
+    error?: string;
+    createdAt: number;
+}
+/**
+ * In-memory store for the async codex sign-in flows. A single instance per daemon
+ * (wired in `bootstrap.ts`). Tracks per-session status for the poll + a single
+ * `activeSessionId` (port 1455 is one resource → one in-flight login at a time).
+ * Never serialized; a daemon restart drops in-flight logins (fail-safe).
+ */
+declare class CodexOAuthSessionStore {
+    private readonly ttlMs;
+    private readonly sessions;
+    private activeSessionId;
+    constructor(ttlMs?: number);
+    /** Whether a codex sign-in is currently in flight (port 1455 held). */
+    isBusy(): boolean;
+    /** Mint a fresh sessionId, mark it pending + active, return the id. */
+    begin(): string;
+    /** Settle a flow (done/error) + free the active slot. */
+    settle(sessionId: string, status: 'done' | 'error', error?: string): void;
+    /** Read a flow's status (token-free), or null when unknown/expired. */
+    get(sessionId: string): CodexFlowState | null;
+    /** Drop expired flows; free the active slot if the active flow expired. */
+    private sweep;
+}
+
+/**
+ * autoDisableStore.ts — the daemon's PROCESS-IN-MEMORY auto-disable store.
+ *
+ * A DB-backed embedder can persist 401/403 auto-disable durably so a UI can
+ * render per-key health. The daemon has no DB, and its only
+ * durable layer is `config.json` — but writing auto-disable back there in v1
+ * would (1) cause write amplification under a 401 storm and (2) collide with
+ * the at-rest encryption schema that owns the `apiKeys[]` on-disk
+ * format. So v1 records auto-disable IN MEMORY only:
+ *  - `markAutoDisabled(keyId, status, at)` records `{ status, at, reason }`,
+ *  - `isDisabled(keyId)` / `get(keyId)` read it back,
+ *  - `loadPoolKeys` reads this store and flips a flagged key's `enabled` to
+ *    `false`, so `getAvailableKeys` skips it within this process lifetime.
+ *
+ * Restart resets the store (the honest v1 boundary — see spec). Persistence
+ * (encrypted write-back) is a child-3 follow-up.
+ *
+ * @module @omnicross/daemon/pool/autoDisableStore
+ */
+/** One in-memory auto-disable record for a pool key. */
+interface AutoDisableRecord {
+    /** The HTTP status that triggered the disable (401/403). */
+    status: number;
+    /** Epoch-ms when the disable was recorded. */
+    at: number;
+    /** Always `'auth_failure'` in v1 (the only auto-disable trigger). */
+    reason: 'auth_failure';
+}
+/**
+ * A process-lifetime in-memory store of auto-disabled pool keys, keyed by the
+ * pool key id. Constructed once in `buildDaemon` and injected as the pool's
+ * `disableKey` / `markAutoDisabled` sinks AND read by `loadPoolKeys`.
+ */
+declare class AutoDisableStore {
+    private readonly records;
+    /** Record (or overwrite) an auth-failure auto-disable for `keyId`. */
+    markAutoDisabled(keyId: string, status: number, at: number): void;
+    /** Whether `keyId` is currently auto-disabled in this process. */
+    isDisabled(keyId: string): boolean;
+    /** Read the auto-disable record for `keyId`, or `undefined` when healthy. */
+    get(keyId: string): AutoDisableRecord | undefined;
+    /** Clear all records (tests / teardown). */
+    clear(): void;
+}
+
+/**
+ * ConfigFileProviderConfigSource — the daemon's file-backed `ProviderConfigSource`
+ * port impl: an embedder of `@omnicross/core`'s provider catalog port.
+ *
+ * The daemon's `config.json` provider rows ARE the catalog. Of the port's ten
+ * methods, FOUR are real (the ones the BYO proxy/outbound path actually hits):
+ *  - `getProvider(id)` — map a `DaemonProviderConfig` row to an `LLMProvider`.
+ *  - `getTransformerService()` — a single `TransformerService` seeded by
+ *    `registerBuiltinTransformers` in the ctor.
+ *  - `getMainTransformer(id)` — the transformer for the provider's target wire
+ *    format (anthropic → AnthropicTransformer, gemini → GeminiTransformer,
+ *    openai → null/identity), mirroring the host `AgentModelsManager` switch.
+ *    `resolveProviderChain` unshifts this FORMAT-FIRST into the provider chain.
+ *  - `resolveTransformerChain(id, model)` — the provider's CUSTOM
+ *    `transformer.use[]` chain (app-parity-2 child 2: ENFORCED). The format
+ *    transformer is NOT included here (getMainTransformer supplies it,
+ *    format-first); no `transformer.use[]` → empty chain.
+ *
+ * The remaining SIX are minimal sensible stubs (never hit on the BYO single-key
+ * path — the boot smoke test is the proof).
+ *
+ * @module @omnicross/daemon/ports/ConfigFileProviderConfigSource
+ */
+
+declare class ConfigFileProviderConfigSource implements ProviderConfigSource {
+    private readonly providers;
+    private readonly transformerService;
+    /**
+     * Optional reload-hook (key-pool change, design D4). A no-type-coupling
+     * callback invoked at the END of `reload(...)`. `buildDaemon` injects
+     * `() => pool.invalidateCache()` so the `ApiKeyPoolService.keyCache` is
+     * flushed after a hot-reload swaps the catalog — WITHOUT this port ever
+     * importing/depending on `ApiKeyPoolService`. Absent = no-op (single-key
+     * boots that never construct a pool stay byte-identical).
+     */
+    private reloadHook;
+    constructor(config: DaemonConfig);
+    /**
+     * Register a callback fired after every `reload(...)`. Used by `buildDaemon`
+     * to invalidate the pool's keyCache on a hot-reload. The port stays ignorant
+     * of what the callback does (no pool type dependency).
+     */
+    setReloadHook(fn: () => void): void;
+    /**
+     * Read the live (post-reload) provider row for `providerId`, or `undefined`.
+     * Exposed so the pool's `loadKeys` reads the SAME live catalog Map this port
+     * serves (so a hot-reload is observed on the next load after `invalidateCache`).
+     */
+    getProviderRow(providerId: string): DaemonProviderConfig | undefined;
+    /** Await the built-in transformer registration (tests await this before dispatch). */
+    ready(): Promise<void>;
+    /**
+     * Replace the live provider catalog in place (additive — does NOT touch the
+     * ten port methods, the seeded `TransformerService`, or `ready()`). Called by
+     * the admin API after a provider POST/PUT/DELETE persists `config.json`, so the
+     * next outbound request sees the new catalog WITHOUT a daemon restart. The Map
+     * swap is synchronous; an in-flight request keeps its already-resolved
+     * provider (no locking needed for a single-operator local daemon).
+     */
+    reload(config: DaemonConfig): void;
+    /** Clear + repopulate the private providers Map from a fresh provider list. */
+    setProviders(providers: readonly DaemonProviderConfig[]): void;
+    getProvider(id: string): Promise<LLMProvider | null>;
+    getTransformerService(): TransformerService | undefined;
+    getMainTransformer(providerId: string): Promise<Transformer | null>;
+    resolveTransformerChain(providerId: string, _model?: string): Promise<ResolvedTransformerChain>;
+    resolveRoutedModel(): Promise<null>;
+    resolveEffectiveModels(): Promise<{
+        background?: string;
+        vision?: string;
+    }>;
+    getAgentDefaultModels(): Promise<AgentDefaultModels>;
+    hasVisionCapability(): Promise<boolean>;
+    getGlobalModelParameters(): Promise<GlobalModelParameters>;
+    getDiscoveredModelMaxTokens(): Promise<number | undefined>;
+}
+
+/**
+ * JsonApiServerSettingsStore — the daemon's file-backed `ApiServerSettingsStore`
+ * port impl.
+ *
+ * The serving core persists the outbound-API server config (`{ enabled,
+ * networkBinding, endpoints, port }`) under a SINGLE settings key
+ * (`OUTBOUND_API_SERVER_CONFIG_KEY === 'outboundApiServer.config'`). Here that
+ * store is the daemon's `config.json` `server`
+ * field. `loadServerConfig(store)` / `saveServerConfig(store, cfg)` (core)
+ * normalize + persist through this 2-method surface.
+ *
+ * Only the one outbound-API key is ever read/written — any other key is a no-op
+ * miss (returns `undefined`) so the surface stays honest about what it backs.
+ *
+ * @module @omnicross/daemon/ports/JsonApiServerSettingsStore
+ */
+
+declare class JsonApiServerSettingsStore implements ApiServerSettingsStore {
+    private readonly configPath;
+    constructor(configPath: string);
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    /** Read the config.json, tolerating a missing/corrupt file (→ empty shape). */
+    private readFile;
+}
+
+/**
+ * migration.ts — the export gather + import apply logic for the passphrase pack
+ * (app-parity child 6, design D2/D3/D5).
+ *
+ * EXPORT (`gatherExport`): read the FULL local state DECRYPTED in-memory — every
+ * provider row (scalars / modelConfigs / single apiKey / pool apiKeys /
+ * transformer) via `loadConfig` (the at-rest box decrypts on read) AND the
+ * subscription tokens via `credentialStore.getFullConfig()` (also decrypted) —
+ * serialize to ONE bundle JSON, and `sealPack` it under the passphrase-derived
+ * key. The caller returns ONLY the opaque pack; the decrypted bundle + the
+ * passphrase live only in local variables and are never logged.
+ *
+ * IMPORT (`applyImport`): `openPack` decrypts + authenticates (a wrong passphrase
+ * or a tampered pack fails the GCM auth-tag BEFORE any write — atomic). Every
+ * provider is re-validated through `parseProviderInput` and every token block
+ * through `validateTokenBody` (deny-by-default — a malicious blob cannot inject
+ * unknown fields or escape the allowlist). Validation collects ALL rows BEFORE
+ * applying, so a structurally invalid pack does not leave a half-applied state.
+ * Apply merges by provider id (additive default): a new id is added; a colliding
+ * id is skipped (or overwritten with `mode:'overwrite'`). Writes go through the
+ * EXISTING paths (`saveConfig` re-encrypts at-rest under the LOCAL box +
+ * `writeProviderTokens`/`appendProviderAccount`), so imported secrets land
+ * `enc:`-encrypted under the TARGET machine's key — the passphrase key is used
+ * ONLY for transport.
+ *
+ * SECRET SPINE: the export RESPONSE is the opaque pack ONLY; the import RESPONSE
+ * is status-only counts. No decrypted secret + no passphrase ever reaches a
+ * response body or a log here.
+ *
+ * @module @omnicross/daemon/migration/migration
+ */
+
+/**
+ * The credential-store surface the migration paths need: the full DECRYPTED read
+ * (export) + the multi-account append (import re-encrypts at-rest). One shape so
+ * `ExportDeps` + `ImportDeps` can be unified into `MigrationDeps` without a
+ * `credentialStore` type conflict.
+ */
+interface MigrationCredentialStore extends SubscriptionAccountAppender {
+    getFullConfig(): Promise<AccountTokensConfig>;
+}
+
+/**
+ * adminApi — the daemon admin dashboard's management API router (`/admin/api/*`,
+ * JSON) (RT3, design D3/D4/D5).
+ *
+ * A small method+path router over the LIVE daemon handles + exported core fns.
+ * Resources: providers (CRUD + hot-reload), keys (CRUD + one-time plaintext),
+ * server config (live apply), accounts (read-only status), status, playground
+ * (same-origin proxy to `/v1/*`).
+ *
+ * SECRET SPINE (design D4 — the load-bearing invariant): secrets flow IN
+ * (POST/PUT) and NEVER OUT (GET). The provider mask (`maskProviderApiKey`) and
+ * the key DTO map (`toKeyInfo`) are the single places the masking is applied so
+ * the invariant lives in one spot.
+ *
+ * @module @omnicross/daemon/admin/adminApi
+ */
+
+/** Token-free subscription account list entry (passthrough from core's service). */
+interface AdminAccountsLister {
+    listAll(): Promise<unknown[]>;
+}
+/** One key's live cooldown health (mirrors core `KeyHealthEntry`; read-only). */
+interface PoolKeyHealth {
+    until: number;
+    errors: number;
+    lastStatus: number | null;
+}
+/**
+ * The READ-ONLY pool-health surface the admin view needs (key-pool design D7).
+ * Structurally satisfied by core's `ApiKeyPoolService.getKeyHealth`; typed as a
+ * minimal reader so `adminApi` carries no class coupling and can never reach a
+ * key value through it (cooldown health only).
+ */
+interface PoolHealthReader {
+    getKeyHealth(providerId: string): Promise<Record<string, PoolKeyHealth>>;
+}
+/** The live daemon handles the management API operates over. */
+interface AdminApiDeps {
+    /** Path to the daemon's `config.json` (provider catalog + `server` field). */
+    readonly configPath: string;
+    /** Live provider catalog (hot-reload target). */
+    readonly llmConfig: ConfigFileProviderConfigSource;
+    /** Named outbound-key store. */
+    readonly keyDb: OutboundKeyDb;
+    /** Outbound server settings store (server config persistence). */
+    readonly settingsStore: JsonApiServerSettingsStore;
+    /** The running outbound server (status + live applyConfig). */
+    readonly outboundApiServer: OutboundApiServer;
+    /** Subscription accounts (token-free `listAll`). */
+    readonly subscriptionAccounts: AdminAccountsLister;
+    /**
+     * Least-authority subscription-token WRITER (design D4) — ONLY the mutation
+     * methods (`writeProviderTokens` / `clearProvider`), never a token-returning
+     * read. The token-free `subscriptionAccounts` lister stays separate so a GET
+     * handler can never reach a token through this dep.
+     */
+    readonly subscriptionTokenWriter: SubscriptionTokenWriter;
+    /**
+     * Read-only pool-health reader (key-pool design D7) — cooldown health only,
+     * never a key value. Drives `GET /admin/api/providers/:id/keys`.
+     */
+    readonly apiKeyPool: PoolHealthReader;
+    /** In-memory auto-disable store (design D5) — read-only for the health view. */
+    readonly autoDisableStore: AutoDisableStore;
+    /**
+     * Pending interactive-OAuth sessions (app-parity child 4, design D1) — the
+     * in-memory `{ codeVerifier, state }` map keyed by a minted `sessionId`,
+     * NEVER serialized to the client.
+     */
+    readonly oauthSessions: OAuthSessionStore;
+    /**
+     * Injected token-exchange `FetchLike` (oauth design D2-a) — defaults to global
+     * `fetch` in `bootstrap.ts`; tests inject a mock so no real token endpoint is
+     * hit. Mirrors how `login.ts` injects its exchange fetch.
+     */
+    readonly oauthExchangeFetch: FetchLike;
+    /**
+     * NARROW append handle (oauth design D2-a) — the OAuth complete handler needs
+     * `appendProviderAccount` (NOT on the least-authority `SubscriptionTokenWriter`).
+     * A minimal interface, NOT the full read-capable store, so no token-returning
+     * read is reachable. Wired from the concrete `credentialStore` in `bootstrap.ts`.
+     */
+    readonly subscriptionAccountAppender: SubscriptionAccountAppender;
+    /**
+     * Codex interactive-OAuth flow store (app-parity-2 child 5). Tracks the async
+     * loopback sign-in's polled status (token-free); only ONE codex login may be in
+     * flight (port 1455 is one resource). Wired in `bootstrap.ts`.
+     */
+    readonly codexSessions: 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
+     * is bound. The captured code crosses to the daemon ONLY (never the client).
+     */
+    readonly codexAwaitLoopback: CodexLoopbackFn;
+    /**
+     * Migration credential-store handle (app-parity child 6, design D2/D3). The
+     * export gather needs `getFullConfig()` (full DECRYPTED tokens, in-memory only —
+     * the pack is the only thing that leaves) and import needs `appendProviderAccount`
+     * (multi-account append + re-encrypt at-rest). Confined to the migration
+     * handlers (which seal/validate everything); never reached by a GET handler.
+     * Wired from the concrete `credentialStore` in `bootstrap.ts`.
+     */
+    readonly migrationCredentialStore: MigrationCredentialStore;
+}
+/**
+ * Dispatch one `/admin/api/*` request. `path` is the already-extracted pathname
+ * (no query). The auth gate has already run in `AdminServer`.
+ */
+declare function handleAdminApi(req: http.IncomingMessage, res: http.ServerResponse, path: string, deps: AdminApiDeps): Promise<void>;
+
+/**
+ * AdminServer — the daemon's localhost admin/dashboard HTTP listener (RT3,
+ * design D1/D2).
+ *
+ * A SEPARATE `node:http` listener distinct from core's outbound `/v1/*` server
+ * (port 8765, untouched). Mirrors `OutboundApiServer`'s proven shape:
+ *  - `http.createServer`, default bind `127.0.0.1` (or `0.0.0.0` when
+ *    `networkBinding`), `listen` with `EADDRINUSE`→ephemeral(port 0) fallback,
+ *  - `getStatus()` (running / bound port / dashboard URL), `start` / `stop`.
+ * Default admin port 8766.
+ *
+ * Auth (design D2):
+ *  - Baseline = localhost bind, no token → reachable only from the machine.
+ *  - Optional `admin.token` → every `/admin/*` request (incl. `GET /`) must
+ *    carry `Authorization: Bearer <token>` or `X-Admin-Token: <token>`; compared
+ *    server-side with a constant-time equality → `401` on a miss.
+ *  - HARD SAFETY GATE: `networkBinding` (LAN/`0.0.0.0`) without a non-empty
+ *    `admin.token` → `start` REFUSES to bind (logs + stays down, fail closed).
+ *
+ * Routing: `GET /` (and `GET /admin`) → `DASHBOARD_HTML`; `* /admin/api/*` → the
+ * management API (`handleAdminApi`); everything else → `404`.
+ *
+ * @module @omnicross/daemon/admin/AdminServer
+ */
+
+/** The dependencies the admin server + its API need (live daemon handles). */
+interface AdminServerDeps extends AdminApiDeps {
+    /** Read the resolved admin config (enabled/port/networkBinding/token). */
+    getAdminConfig: () => ResolvedAdminConfig;
+}
+/** A live status snapshot for the admin listener. */
+interface AdminServerStatus {
+    running: boolean;
+    /** Actual bound port (0 when not running). */
+    port: number;
+    /** The dashboard URL (loopback or LAN base), or null when not running. */
+    url: string | null;
+}
+declare class AdminServer {
+    private readonly deps;
+    private server;
+    private boundPort;
+    private boundAddr;
+    constructor(deps: AdminServerDeps);
+    /**
+     * Start the admin listener honoring the resolved admin config. Returns the
+     * actual bound port, or `0` when it refuses/declines to bind (disabled or the
+     * LAN fail-closed gate). Idempotent: a second call returns the bound port.
+     */
+    start(): Promise<number>;
+    /** Bind once; on EADDRINUSE retry with an ephemeral port (port 0). */
+    private listen;
+    /** Per-request handler: auth gate (when a token is set) → routing. */
+    private onRequest;
+    private dispatch;
+    /** Constant-time bearer/header check against the configured token. */
+    private isAuthorized;
+    /** Stop the listener and release the port. */
+    stop(): Promise<void>;
+    /** A live status snapshot. */
+    getStatus(): AdminServerStatus;
+}
+
+/**
+ * ConsoleLogger — the daemon's file-less default `Logger` port impl (design D5).
+ *
+ * A thin `console.*` wrapper. The serving core depends on the `Logger` port
+ * (never a host class), so this trivial implementation is the only logger the
+ * standalone daemon needs. `error` uses the WIDEST `(message, error?, meta?)`
+ * signature so every core call site stays assignable.
+ *
+ * @module @omnicross/daemon/ports/ConsoleLogger
+ */
+
+declare class ConsoleLogger implements Logger {
+    info(message: string, meta?: Record<string, unknown> | Error | object): void;
+    warn(message: string, meta?: Record<string, unknown> | Error | object): void;
+    error(message: string, error?: unknown, meta?: Record<string, unknown> | object): void;
+    debug(message: string, meta?: Record<string, unknown> | Error | object): void;
+}
+
+/**
+ * JsonOutboundKeyDb — the daemon's file-backed `OutboundKeyDb` port impl
+ * (design D3).
+ *
+ * Durable storage for named outbound API keys, backed by a json file (a sibling
+ * of `config.json`, e.g. `keys.json`) holding an `OutboundKeyDbRow[]`. This port
+ * provides ONLY storage — it never generates secrets nor hashes. Core's
+ * `createNamedKey(db, name)` calls `outboundApiKeysCreate` with the sha256
+ * `keyHash` + display `keyPrefix` and returns the one-time plaintext; the hot
+ * auth path uses core's `hashKey(presented)` + `outboundApiKeysGetByHash`.
+ *
+ * @module @omnicross/daemon/ports/JsonOutboundKeyDb
+ */
+
+declare class JsonOutboundKeyDb implements OutboundKeyDb$1 {
+    private readonly keysPath;
+    constructor(keysPath: string);
+    outboundApiKeysList(): Promise<OutboundKeyDbRow[]>;
+    outboundApiKeysGetByHash(hash: string): Promise<OutboundKeyDbRow | null>;
+    outboundApiKeysCreate(input: {
+        id: string;
+        name: string;
+        keyHash: string;
+        keyPrefix: string;
+        createdAt?: number;
+    }): Promise<OutboundKeyDbRow>;
+    outboundApiKeysRevoke(id: string): Promise<boolean>;
+    outboundApiKeysTouchLastUsed(id: string): Promise<boolean>;
+    outboundApiKeysSetEnabled(id: string, enabled: boolean): Promise<boolean>;
+    /** Apply `fn` to the row with `id`, persisting when it returns true. */
+    private mutateRow;
+    /** Read the key rows, tolerating a missing/corrupt file (→ empty list). */
+    private readRows;
+    private writeRows;
+}
+
+/**
+ * bootstrap.ts — `buildDaemon` wires `@omnicross/core`'s `ProviderProxy` +
+ * `OutboundApiServer` STANDALONE (design D6).
+ *
+ * A DB-backed embedder wires the same `@omnicross/core` surface differently;
+ * this standalone wiring makes three SUBSTITUTIONS (file-backed ports replace
+ * DB-backed ones) and three SUBTRACTIONS:
+ *  - no `CompletionService` (the BYO proxy path doesn't need it),
+ *  - no `apiKeyPool` / `usageRecorder` (optional `ProviderProxyDeps`),
+ *  - no `anthropicIngressHandlerFactory` (→ `/v1/messages` returns 502 by core's
+ *    existing contract — no daemon code needed).
+ *
+ * `getProviderProxy` / `getOutboundApiServer` are module singletons, so the boot
+ * smoke test calls `__resetProviderProxyForTests` / `__resetOutboundApiServerForTests`
+ * (re-exported here) in `beforeEach`.
+ *
+ * @module @omnicross/daemon/bootstrap
+ */
+
+/** On-disk locations the file-backed ports persist to. */
+interface DaemonPaths {
+    /** The config.json path (provider catalog + persisted `server` field). */
+    configPath: string;
+    /** The named-key json store path (sibling of config.json by convention). */
+    keysPath: string;
+    /** The subscription `tokens.json` store path (sibling of config.json by convention). */
+    tokensPath: string;
+    /**
+     * OPTIONAL `--master-key-file` override for the at-rest master key (secrets
+     * design D3). Absent → the default `~/.omnicross/master.key`. The
+     * `OMNICROSS_MASTER_KEY` env still beats this when set.
+     */
+    masterKeyFilePath?: string;
+    /**
+     * TEST SEAM (optional, app-parity-2 child 5): override the codex loopback listener
+     * so tests need not bind `127.0.0.1:1455`. Absent → the real `awaitLoopbackCode`.
+     */
+    codexAwaitLoopback?: CodexLoopbackFn;
+    /**
+     * TEST SEAM (optional): override the OAuth token-exchange fetch so tests need not
+     * hit a real token endpoint. Absent → the global `fetch`.
+     */
+    oauthExchangeFetch?: FetchLike;
+}
+/** The constructed daemon handles the CLI commands operate on. */
+interface Daemon {
+    readonly logger: ConsoleLogger;
+    readonly llmConfig: ConfigFileProviderConfigSource;
+    readonly keyDb: JsonOutboundKeyDb;
+    readonly settingsStore: JsonApiServerSettingsStore;
+    readonly providerProxy: ProviderProxy;
+    readonly outboundApiServer: OutboundApiServer;
+    /**
+     * Multi-key load balancer. Wired into the proxy deps slot
+     * AND exposed here so the admin read-only key-health view can
+     * read `getKeyHealth`. NOTE: outbound failover does NOT fire on
+     * the daemon's null-session outbound path — v1 is cold-standby + observable.
+     */
+    readonly apiKeyPool: ApiKeyPoolService;
+    /** In-memory 401/403 auto-disable store (design D5; read by the admin view). */
+    readonly autoDisableStore: AutoDisableStore;
+    /** File-backed subscription credential store (reads `tokens.json`). */
+    readonly credentialStore: JsonSubscriptionCredentialStore;
+    /** Subscription dispatch-profile registry (mirrored into core's outbound slot). */
+    readonly subscriptionRegistry: SubscriptionProviderRegistry;
+    /** Subscription account service (token-free `listAll`) — now exposed for the
+     *  admin dashboard's read-only accounts panel (RT3). */
+    readonly subscriptionAccounts: SubscriptionAccountService;
+    /** The localhost admin/dashboard HTTP listener (RT3). Started by `start.ts`. */
+    readonly adminServer: AdminServer;
+}
+/**
+ * Construct the standalone daemon from a loaded config + on-disk paths. Does NOT
+ * start the listeners — the `start` command awaits `providerProxy.start()` then
+ * `outboundApiServer.applyConfig(...)`.
+ */
+declare function buildDaemon(config: DaemonConfig, paths: DaemonPaths): Daemon;
+/** Reset the core singletons (tests / teardown only). Re-exported for the suite.
+ *
+ * Also clears BOTH subscription singletons (design D4). This is mandatory: the
+ * `setSubscriptionProviderRegistry` setter mirrors into core's outbound slot, so
+ * without it a prior test's registry would leak into a BYO-only boot and
+ * mis-route. We clear the core outbound slot directly via
+ * `setSubscriptionRegistryForOutbound(null)` (which accepts `null`), and null
+ * the `@omnicross/subscriptions` module singletons through their setters (the
+ * setters assign verbatim — passing `null` is a no-throw runtime clear; the
+ * `as never` keeps the call within the package's non-nullable type without
+ * modifying its behavior). It also nulls the core Gemini Code-Assist resolver
+ * slot so a wired resolver does not leak across boots.
+ *
+ * NOTE: the `AdminServer` is INSTANCE-scoped on the returned `Daemon` (not a
+ * module singleton), so it needs no reset here — the test stops it in `afterEach`
+ * via `daemon.adminServer.stop()`. */
+declare function resetDaemonSingletonsForTests(): void;
+
+/**
+ * html.ts — the embedded vanilla-JS admin dashboard (RT3, design D7).
+ *
+ * A SINGLE `text/html` template literal served by `AdminServer` on `GET /`. No
+ * framework, no bundler, no new dependency — vanilla `fetch` + DOM. Panels:
+ * providers (table + add/edit form), keys (table + create modal showing the
+ * one-time plaintext with a copy button + a "shown once" warning, never
+ * persisted), server config, read-only accounts status, and a playground
+ * (endpoint select + key + request textarea + Send + response area).
+ *
+ * SECURITY: the create-key plaintext is held only in a local variable inside the
+ * modal flow and cleared on dismiss — never written to a field, list, or storage.
+ *
+ * @module @omnicross/daemon/admin/html
+ */
+/** The full dashboard document (style + body + the vanilla client script). */
+declare const DASHBOARD_HTML: string;
+
+/**
+ * ccr-import.ts — translate a `claude-code-router` (CCR) `config.json` into an
+ * omnicross daemon config (design D9). Pure + testable: `parseCcrConfig(raw)` +
+ * `mapCcrToOmnicross(ccr) → { config, notes }`.
+ *
+ * Provider mapping: CCR `Providers[{name, api_base_url, api_key, models}]` →
+ * omnicross provider rows. `apiFormat` is inferred heuristically (default
+ * `openai`), with a `notes[]` entry whenever the inference is ambiguous.
+ *
+ * Router-role mapping (per doc 03 §4.1 / 04 §4.1, user decision 2026-06-03):
+ *   default      → default
+ *   background   → background
+ *   think        → default      (omnicross has no think slot)
+ *   longContext  → default      (no longContext slot; `longContextThreshold` dropped)
+ *   image        → vision       (CCR's `forceUseImageAgent` dropped)
+ *   webSearch    → DROPPED      (philosophically different; recorded as a note)
+ *
+ * @module @omnicross/daemon/ccr-import
+ */
+
+/** A CCR provider entry (defensive — all fields optional). */
+interface CcrProvider {
+    name?: string;
+    api_base_url?: string;
+    api_key?: string;
+    models?: string[];
+    transformer?: unknown;
+}
+/** The CCR `Router` block (a subset; unknown roles are ignored). */
+interface CcrRouter {
+    default?: string;
+    background?: string;
+    think?: string;
+    longContext?: string;
+    longContextThreshold?: number;
+    image?: string;
+    webSearch?: string;
+    forceUseImageAgent?: boolean;
+}
+/** A parsed CCR config. */
+interface CcrConfig {
+    Providers?: CcrProvider[];
+    Router?: CcrRouter;
+}
+/** Parse + shape-guard a raw CCR config object. */
+declare function parseCcrConfig(raw: unknown): CcrConfig;
+/**
+ * Infer the wire format for a CCR provider from its base URL / name. Returns the
+ * inferred format and whether it was an ambiguous (heuristic) guess.
+ */
+declare function inferApiFormat(provider: CcrProvider): {
+    format: DaemonApiFormat;
+    ambiguous: boolean;
+};
+/**
+ * Translate a parsed CCR config into a `DaemonConfig` + the list of human-readable
+ * notes describing every folded/dropped field. Pure — directly unit-tested.
+ */
+declare function mapCcrToOmnicross(ccr: CcrConfig): {
+    config: DaemonConfig;
+    notes: string[];
+};
+
+export { type AdminApiDeps, AdminServer, type AdminServerDeps, type AdminServerStatus, type CcrConfig, type CcrProvider, type CcrRouter, ConfigFileProviderConfigSource, ConsoleLogger, DASHBOARD_HTML, DEFAULT_ADMIN_PORT, type Daemon, type DaemonAdminConfig, type DaemonApiFormat, type DaemonConfig, type DaemonPaths, type DaemonProviderConfig, JsonApiServerSettingsStore, JsonOutboundKeyDb, JsonSubscriptionCredentialStore, type ResolvedAdminConfig, buildDaemon, handleAdminApi, inferApiFormat, loadConfig, mapCcrToOmnicross, parseCcrConfig, resetDaemonSingletonsForTests, resolveAdminConfig, saveConfig, validateConfig };