@omnicross/subscriptions 0.1.0 → 0.1.3

package/dist/index.d.cts

@@ -1,7 +1,15 @@
 import { AccountTokensConfig } from '@omnicross/contracts/account-tokens-types';
-import { SubscriptionProviderId, SubscriptionStatusEntry, SubscriptionListEntry, OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
+import { SubscriptionProviderId, SubscriptionStatusEntry, SubscriptionListEntry, OpenCodeGoTokenConfig } from '@omnicross/contracts/subscription-types';
+import { AuthStrategy } from '@omnicross/core/pipeline/SubscriptionAuthStrategy';
+export { AuthApplyHints, AuthStrategy } from '@omnicross/core/pipeline/SubscriptionAuthStrategy';
+import { SubscriptionDispatchProfile } from '@omnicross/core/provider-proxy/types';
+export { SubscriptionDispatchProfile, SubscriptionRequestSummary } from '@omnicross/core/provider-proxy/types';
 import http from 'node:http';
-export { FetchLike, claudeOAuth, codexOAuth, geminiOAuth } from './oauth.cjs';
+import { TransformerChainExecutor } from '@omnicross/core/transformer/TransformerChainExecutor';
+import { TransformerService } from '@omnicross/core/transformer/TransformerService';
+import { Transformer } from '@omnicross/core/transformer/types';
+export { FetchLike } from '@omnicross/core/auth/GeminiCodeAssistProjectResolver';
+export { claudeOAuth, codexOAuth, geminiOAuth } from './oauth.cjs';
 
 /**
  * SubscriptionCredentialStore — the credential port the subscription block
@@ -19,7 +27,15 @@ export { FetchLike, claudeOAuth, codexOAuth, geminiOAuth } from './oauth.cjs';
  * subscriptions layer).
  */
 
-/** The six methods the subscription block consumes from the host credential store. */
+/**
+ * The credential surface the subscription block consumes from the host store.
+ *
+ * The six ORIGINAL methods (active-account getters + refreshers) are REQUIRED;
+ * the three by-id methods (subscription-account-scheduling, design D6) are
+ * OPTIONAL and feature-detected so every existing lightweight test double that
+ * implements only the six keeps compiling and the single-account active path is
+ * untouched.
+ */
 interface SubscriptionCredentialStore {
     /** Full decrypted account-tokens config (all subscription providers). */
     getFullConfig(): Promise<AccountTokensConfig>;
@@ -33,64 +49,124 @@ interface SubscriptionCredentialStore {
     refreshGeminiToken(): Promise<boolean>;
     /** Current valid OpenCodeGo static API key; `null` if none. */
     getValidOpenCodeGoApiKey(): Promise<string | null>;
+    /**
+     * Resolve a SPECIFIC account's access token by id (refreshing a near-expiry
+     * OAuth token for that account, mirroring the active getter's per-provider
+     * refresh policy). `null` when the account is unknown/expired/tokenless.
+     */
+    getAccessTokenForAccount?(providerId: SubscriptionProviderId, accountId: string): Promise<string | null>;
+    /**
+     * Force a refresh of a SPECIFIC account's OAuth token by id; `true` on success.
+     * Static-key providers (opencodego) return `false` — they don't refresh.
+     */
+    refreshAccountToken?(providerId: SubscriptionProviderId, accountId: string): Promise<boolean>;
+    /**
+     * Best-effort record of a selection's time onto the account's `lastUsedAt`
+     * (throttled by the selector so the hot path does not rewrite the store every
+     * request). Durability only — never affects which credential is valid.
+     */
+    touchAccountLastUsed?(providerId: SubscriptionProviderId, accountId: string, iso: string): Promise<void>;
 }
 
 /**
- * SubscriptionAuthStrategy — the pluggable subscription-auth contract, defined
- * in the serving core (`pipeline/`).
+ * SubscriptionAccountSelector — the pure, in-memory account scheduler
+ * (subscription-account-scheduling, design D3).
+ *
+ * Given a provider's account list (+ an optional session key) it decides WHICH
+ * account of the pool serves the outbound request:
  *
- * Each subscription provider in the `SubscriptionProviderRegistry` (the
- * subscriptions package) carries an `AuthStrategy` instance. The proxy calls
- * `applyHeaders` before issuing the upstream request and `onUnauthorized`
- * after a 401 to ask whether to retry.
+ *   filter `schedulable !== false`
+ *     → session-affinity short-circuit (sticky `sessionKey → accountId`, TTL 1h)
+ *     → sort by `priority` asc → effective `lastUsedAt` asc (LRU) → `createdAt` asc
+ *     → `[0]`.
  *
- * It is a PURE contract (no upstream semantics), defined down here so
- * `pipeline/SubscriptionAuthSource.ts` consumes it WITHOUT importing upward
- * (correct dependency direction). The subscriptions package's
- * `auth/AuthStrategy.ts` RE-EXPORTS this type, and its three concrete
- * strategies implement THIS interface — so they remain assignable and no
- * downstream consumer's import path changes.
+ * A faithful port of CRS `sortAccountsByPriority` + `unifiedClaudeScheduler`
+ * session mapping. The class holds process-lived state — the affinity map and an
+ * in-memory `lastUsedAt` overlay (the authoritative live tie-break value, seeded
+ * from the persisted field and advanced to `now` on each selection so repeated
+ * selections round-robin fairly even before any durable persist). ONE instance is
+ * constructed at bootstrap and SHARED by all three auth strategies (each scopes
+ * its calls by `providerId`), mirroring the single long-lived CRS scheduler.
  *
- * NOTE: this `AuthApplyHints` (OPTIONAL fields) is the SUBSCRIPTION-side hint
- * shape and is intentionally distinct from `pipeline/AuthSource.ts`'s
- * `AuthApplyHints` (REQUIRED fields). They are not interchangeable; the
- * `SubscriptionAuthSource` adapter maps between them at the boundary.
+ * ZERO-REGRESSION CARRIER: `select()` returns `null` when the schedulable account
+ * count is ≤ 1. Callers treat `null` (and an `isActive` result) as "use the
+ * existing active-mirror path", so a single-account provider exercises NO new
+ * code and its token read is byte-identical to before this change.
  *
- * @module pipeline/SubscriptionAuthStrategy
+ * @module scheduler/SubscriptionAccountSelector
  */
 
-/** Hints the strategy may need to vary header formatting per request. */
-interface AuthApplyHints {
-    /** Resolved upstream URL — used by some strategies (e.g. OpenCodeGo) to
-     *  choose between Anthropic-shape and OpenAI-shape headers. */
-    upstreamUrl?: string;
-    /** Resolved model id — same purpose as `upstreamUrl`. */
-    resolvedModel?: string;
-}
-interface AuthStrategy {
-    /** Discriminator — also surfaced through `subscription:list` to renderers. */
-    readonly kind: 'pass-through' | 'oauth-bearer' | 'static-bearer';
-    /** Stable id of the bound subscription provider. */
-    readonly providerId: SubscriptionProviderId;
-    /**
-     * Inject any required authentication headers into the outbound request.
-     * Implementations MAY refresh expiring tokens here (transparent refresh).
-     *
-     * Pass-through implementations are a no-op; the proxy's pass-through
-     * code path preserves the SDK's own Authorization header instead.
-     */
-    applyHeaders(headers: Record<string, string>, hints?: AuthApplyHints): Promise<void>;
-    /**
-     * Called when the upstream returns 401. Return `true` to ask the proxy to
-     * retry the request once with freshly-applied headers; return `false` to
-     * surface the 401 immediately.
-     *
-     * Implementations SHOULD use a shared `RefreshMutex` to dedupe concurrent
-     * refreshes so N parallel 401s collapse into one upstream refresh call.
-     */
-    onUnauthorized(): Promise<boolean>;
-    /** Diagnostic surface for the `subscription:status` IPC. */
-    describeStatus(): Promise<SubscriptionStatusEntry>;
+/** Sticky session→account affinity TTL (CRS parity: 1 hour). */
+declare const SESSION_AFFINITY_TTL_MS = 3600000;
+/** Min gap between best-effort `lastUsedAt` durable persists, per account. */
+declare const LAST_USED_PERSIST_THROTTLE_MS = 60000;
+/** Precedence assumed for an account with no `priority` (CRS `|| 50`). */
+declare const DEFAULT_ACCOUNT_PRIORITY = 50;
+/** One schedulable candidate — the scheduling projection of an account entry. */
+interface SchedulableAccount {
+    id: string;
+    /** Default `50` (lower = higher precedence). */
+    priority?: number;
+    /** ISO — LRU tie-break; absent ⇒ treated as least-recently-used (`0`). */
+    lastUsedAt?: string;
+    /** ISO — final tie-break; absent ⇒ oldest (`0`). */
+    createdAt?: string;
+    /** Default `true`; child #2 (account health) sets `false` for an unhealthy
+     *  account and the selector skips it. */
+    schedulable?: boolean;
+}
+interface SelectInput {
+    providerId: SubscriptionProviderId;
+    accounts: readonly SchedulableAccount[];
+    /** The persistent active-account pointer (for the `isActive` discriminant). */
+    activeAccountId?: string;
+    /** Stable per-conversation key for session affinity; absent ⇒ pure priority/LRU. */
+    sessionKey?: string;
+    /** Injectable clock for tests (default `Date.now()`). */
+    now?: number;
+}
+interface SelectResult {
+    accountId: string;
+    /** `true` when the chosen account is the active one — the caller then runs the
+     *  existing active-mirror getter verbatim (no by-id read). */
+    isActive: boolean;
+}
+declare class SubscriptionAccountSelector {
+    /** `providerId\0accountId → live lastUsedAt ms` (authoritative tie-break). */
+    private readonly lastUsedOverlay;
+    /** `providerId\0sessionKey → { accountId, expiresAt }`. */
+    private readonly affinity;
+    /** `providerId\0accountId → last durable-persist ms` (throttle state). */
+    private readonly lastPersist;
+    /**
+     * Choose the account to serve this request, or `null` when there are ≤ 1
+     * schedulable accounts (the zero-regression signal — caller uses the active
+     * account). Updates the live `lastUsedAt` overlay for the chosen account and,
+     * when a `sessionKey` is given, records/extends the affinity mapping.
+     */
+    select(input: SelectInput): SelectResult | null;
+    /**
+     * Drop every session-affinity mapping bound to this account (subscription-account-
+     * health, task 4.1). Called when a selected account's by-id token turns out
+     * null/invalid or an affinity-bound account becomes unhealthy, so the next
+     * selection for those sessions picks a fresh account instead of re-sticking to
+     * the bad one. O(affinity entries) — the map is tiny (one entry per live
+     * conversation).
+     */
+    evictAffinity(providerId: SubscriptionProviderId, accountId: string): void;
+    /**
+     * Whether a best-effort `lastUsedAt` durable persist is DUE for this account
+     * (≥ `LAST_USED_PERSIST_THROTTLE_MS` since the last one). Records the persist
+     * time when it returns `true`, so the strategy calls `touchAccountLastUsed`
+     * sparingly and the request hot path does not rewrite the store every request.
+     */
+    duePersist(providerId: SubscriptionProviderId, accountId: string, now?: number): boolean;
+    /** Sort by `priority` asc → effective `lastUsedAt` asc → `createdAt` asc → `[0]`. */
+    private pickOrdered;
+    /** The live tie-break value: the in-memory overlay when set, else the persisted
+     *  `lastUsedAt` (0 when absent). */
+    private effectiveLastUsed;
+    private markUsed;
 }
 
 /**
@@ -107,6 +183,9 @@ interface AuthStrategy {
 
 declare class SubscriptionAccountService {
     private readonly mutex;
+    /** ONE account-pool scheduler (subscription-account-scheduling) shared by all
+     *  four strategies so they share the affinity map + the `lastUsedAt` overlay. */
+    private readonly selector;
     private readonly strategies;
     constructor(tokens: SubscriptionCredentialStore);
     /** Returns the strategy bound to a subscription provider, or `null` for unknown ids. */
@@ -122,622 +201,6 @@ declare function setSubscriptionAccountService(svc: SubscriptionAccountService):
  *  may run before main wiring on early-boot diagnostics). */
 declare function getSubscriptionAccountService(): SubscriptionAccountService | null;
 
-/**
- * TransformerService Types
- *
- * Type definitions for the Transformer system, providing unified
- * request/response formats and transformer chain configuration.
- *
- * @module transformer/types
- */
-/**
- * Thinking effort level for reasoning models
- */
-type ThinkLevel = 'none' | 'low' | 'medium' | 'high';
-/**
- * Thinking content with optional signature for extended context
- */
-interface ThinkingContent {
-    content: string;
-    signature?: string;
-}
-/**
- * Reasoning configuration for request
- */
-interface ReasoningConfig {
-    /** OpenAI-style effort level */
-    effort?: ThinkLevel;
-    /** Anthropic-style max tokens for thinking */
-    max_tokens?: number;
-    /** Whether reasoning is enabled */
-    enabled?: boolean;
-}
-/**
- * Text content block
- */
-interface TextContent {
-    type: 'text';
-    text: string;
-    cache_control?: {
-        type?: string;
-    };
-}
-/**
- * Image content block
- */
-interface ImageContent {
-    type: 'image_url';
-    image_url: {
-        url: string;
-    };
-    media_type?: string;
-}
-/**
- * Union of all content types
- */
-type MessageContent = TextContent | ImageContent;
-/**
- * Tool call definition
- */
-interface ToolCall {
-    id: string;
-    type: 'function';
-    function: {
-        name: string;
-        arguments: string;
-    };
-}
-/**
- * Unified message format that works across all providers
- */
-interface UnifiedMessage {
-    role: 'user' | 'assistant' | 'system' | 'tool';
-    content: string | null | MessageContent[];
-    tool_calls?: ToolCall[];
-    tool_call_id?: string;
-    cache_control?: {
-        type?: string;
-    };
-    thinking?: ThinkingContent;
-}
-/**
- * Tool parameter schema
- */
-interface ToolParameterSchema {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-    additionalProperties?: boolean;
-    $schema?: string;
-}
-/**
- * Unified tool definition
- */
-interface UnifiedTool {
-    type: 'function';
-    function: {
-        name: string;
-        description: string;
-        parameters: ToolParameterSchema;
-    };
-}
-/**
- * Tool choice configuration
- */
-type ToolChoice = 'auto' | 'none' | 'required' | string | {
-    type: 'function';
-    function: {
-        name: string;
-    };
-};
-/**
- * Unified chat request format
- */
-interface UnifiedChatRequest {
-    messages: UnifiedMessage[];
-    model: string;
-    max_tokens?: number;
-    temperature?: number;
-    stream?: boolean;
-    tools?: UnifiedTool[];
-    tool_choice?: ToolChoice;
-    reasoning?: ReasoningConfig;
-    /**
-     * Internal-only routing metadata. Populated by callers (CompletionService /
-     * the host's engine adapters and proxy servers) so the usage-capture hook can attribute
-     * the recorded event to a chat message, session, engine origin, and api key.
-     *
-     * **Must not be serialised into the outbound HTTP body.** The transformer chain
-     * passes this object alongside the request internally; transformers that build
-     * provider request payloads must drop `meta` from their output.
-     */
-    meta?: UnifiedChatRequestMeta;
-}
-/**
- * Routing metadata threaded through the transformer chain so the usage-capture
- * hook can identify which chat message / session / api key produced the call.
- * See `UnifiedChatRequest.meta`.
- */
-interface UnifiedChatRequestMeta {
-    /** Host message id of the assistant message being produced, when known. */
-    messageId?: string | null;
-    /** Parent assistant message id (for subagent dispatches that have a parent). */
-    parentMessageId?: string | null;
-    /** Host session id, when applicable. */
-    sessionId?: string | null;
-    /** Which engine path is making the call. See `UsageEngineOrigin`. */
-    engineOrigin?: 'completion' | 'claude-sdk' | 'claude-sdk-direct' | 'codex-ingress' | (string & {});
-    /** The api-key-pool entry id selected for this request. */
-    apiKeyId?: string | null;
-}
-/**
- * LLM Provider configuration (runtime format)
- */
-interface LLMProvider {
-    name: string;
-    baseUrl: string;
-    apiKey: string;
-    models: string[];
-    transformer?: TransformerChainConfig;
-    /**
-     * Resolved Google **Code Assist** project id, threaded onto the transformer
-     * provider object by the subscription dispatch seam (SubscriptionDispatcher /
-     * openaiResponsesIngress) so `GeminiCodeAssistTransformer.transformRequestIn`
-     * can embed it in the top-level envelope. `undefined` is the valid fresh
-     * free-tier value (sending a project on free/legacy-tier → Precondition
-     * Failed). Only ever set for the gemini subscription profile; inert otherwise.
-     */
-    geminiProject?: string;
-}
-/**
- * Transformer options passed during instantiation
- */
-interface TransformerOptions {
-    [key: string]: unknown;
-}
-/**
- * Context passed through transformer chain
- */
-interface TransformerContext {
-    /** Original request object */
-    req?: unknown;
-    /** Logger instance */
-    logger?: TransformerLogger;
-    /** Provider name */
-    providerName?: string;
-    /** Additional context data */
-    [key: string]: unknown;
-}
-/**
- * Logger interface for transformers
- */
-interface TransformerLogger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-}
-/**
- * Transformer interface - defines the contract for all transformers
- */
-interface Transformer {
-    /** Unique name for the transformer */
-    name?: string;
-    /** API endpoint path (e.g., '/v1/chat/completions') */
-    endPoint?: string;
-    /** Logger instance */
-    logger?: TransformerLogger;
-    /**
-     * Transform incoming request (provider-specific → unified format)
-     * Called when request enters the transformer chain
-     */
-    transformRequestIn?: (request: UnifiedChatRequest, provider: LLMProvider, context: TransformerContext) => Promise<Record<string, unknown>>;
-    /**
-     * Transform outgoing request (unified → provider-specific format)
-     * Called before sending to LLM provider
-     */
-    transformRequestOut?: (request: unknown, context: TransformerContext) => Promise<UnifiedChatRequest>;
-    /**
-     * Transform incoming response (provider-specific → unified format)
-     * Called after receiving response from provider
-     */
-    transformResponseIn?: (response: Response, context?: TransformerContext) => Promise<Response>;
-    /**
-     * Transform outgoing response (unified → client format)
-     * Called before returning response to client
-     */
-    transformResponseOut?: (response: Response, context: TransformerContext) => Promise<Response>;
-    /**
-     * Handle authentication for the request
-     */
-    auth?: (request: unknown, provider: LLMProvider, context: TransformerContext) => Promise<unknown>;
-}
-/**
- * Transformer constructor interface
- */
-interface TransformerConstructor {
-    new (options?: TransformerOptions): Transformer;
-    TransformerName?: string;
-}
-/**
- * Individual transformer reference in chain
- * Can be a string name or [name, options] tuple
- */
-type TransformerReference = string | [string, TransformerOptions];
-/**
- * Model-specific transformer configuration
- */
-interface ModelTransformerConfig {
-    use?: TransformerReference[];
-}
-/**
- * Transformer chain configuration for a provider
- */
-interface TransformerChainConfig {
-    /** Provider-level transformers applied to all models */
-    use?: TransformerReference[];
-    /** Model-specific transformer overrides */
-    [modelName: string]: ModelTransformerConfig | TransformerReference[] | undefined;
-}
-/**
- * Resolved transformer chain (instances ready to execute)
- */
-interface ResolvedTransformerChain {
-    /** Provider-level transformer instances */
-    providerTransformers: Transformer[];
-    /** Model-specific transformer instances */
-    modelTransformers: Transformer[];
-}
-/**
- * Result of request transformation
- */
-interface TransformRequestResult {
-    /** Transformed request body */
-    requestBody: unknown;
-    /** Additional request configuration */
-    config: RequestConfig;
-    /** Whether to bypass further transformations */
-    bypass: boolean;
-}
-/**
- * Request configuration for HTTP call
- */
-interface RequestConfig {
-    /** Request URL */
-    url?: URL | string;
-    /** Request headers */
-    headers?: Record<string, string>;
-    /** Additional fetch options */
-    [key: string]: unknown;
-}
-
-/**
- * TransformerChainExecutor - Executes transformer chains for requests and responses
- *
- * Implements the transformer pipeline:
- * Request: transformRequestOut 鈫?Provider transformers 鈫?Model transformers 鈫?HTTP
- * Response: Model transformers (reverse) 鈫?Provider transformers (reverse) 鈫?transformResponseIn
- *
- * @module transformer/TransformerChainExecutor
- */
-
-/**
- * Options for chain execution
- */
-interface ChainExecutionOptions {
-    /** The primary/endpoint transformer */
-    endpointTransformer?: Transformer;
-    /** Request headers */
-    headers?: Record<string, string> | Headers;
-    /** Logger instance */
-    logger?: TransformerLogger;
-    /**
-     * 1M-context opt-in. When `enabled` is true and the post-chain request body
-     * looks Anthropic-shaped (has a `messages` array), the executor injects
-     * `'context-1m-2025-08-07'` into `body.anthropic_beta`. Capability gating
-     * (model id allowlist) lives inside `injectExtendedContextBeta` itself.
-     */
-    extendedContext?: {
-        enabled: boolean;
-        model: string;
-    };
-}
-/**
- * TransformerChainExecutor handles the execution of transformer chains.
- *
- * The execution flow follows the llms project pattern:
- *
- * Request Phase:
- * 1. transformRequestOut (endpoint transformer) - Convert to unified format
- * 2. Provider transformers [].transformRequestIn (forward order)
- * 3. Model transformers [].transformRequestIn (forward order)
- *
- * Response Phase:
- * 4. Model transformers [].transformResponseOut (reverse order)
- * 5. Provider transformers [].transformResponseOut (reverse order)
- * 6. transformResponseIn (endpoint transformer) - Convert to client format
- */
-declare class TransformerChainExecutor {
-    private logger;
-    constructor(logger?: TransformerLogger);
-    /**
-     * Execute the request transformation chain
-     *
-     * @param request - Original request body
-     * @param provider - LLM provider configuration
-     * @param chain - Resolved transformer chain
-     * @param options - Execution options
-     * @returns Transformed request result
-     */
-    executeRequestChain(request: unknown, provider: LLMProvider, chain: ResolvedTransformerChain, options?: ChainExecutionOptions): Promise<TransformRequestResult>;
-    /**
-     * Execute the response transformation chain
-     *
-     * @param request - Original request (for context)
-     * @param response - Response from provider
-     * @param provider - LLM provider configuration
-     * @param chain - Resolved transformer chain
-     * @param options - Execution options
-     * @returns Transformed response
-     */
-    executeResponseChain(request: UnifiedChatRequest, response: Response, provider: LLMProvider, chain: ResolvedTransformerChain, options?: ChainExecutionOptions): Promise<Response>;
-    /**
-     * Execute authentication handler if available
-     *
-     * @param request - Request body
-     * @param provider - LLM provider
-     * @param endpointTransformer - Endpoint transformer with auth handler
-     * @param context - Transformer context
-     * @returns Auth result with potentially modified request and config
-     */
-    executeAuth(request: unknown, provider: LLMProvider, endpointTransformer: Transformer | undefined, context: TransformerContext): Promise<{
-        requestBody: unknown;
-        config: RequestConfig;
-    }>;
-    /**
-     * Check if transformers should be bypassed (optimization)
-     *
-     * Bypass is enabled when:
-     * - Provider has only one transformer that matches the endpoint transformer
-     * - Model has no specific transformers or only the same endpoint transformer
-     */
-    private shouldBypassTransformers;
-    /**
-     * Clean headers for pass-through
-     */
-    private cleanHeaders;
-    /**
-     * Get error message from unknown error
-     */
-    private getErrorMessage;
-}
-
-/**
- * TransformerService - Core service for managing transformer lifecycle
- *
- * Handles transformer registration, retrieval, and initialization.
- *
- * Adapted from the `musistudio/llms` project (MIT, © 2025 musistudio) — the
- * transformer IR upstream — for the Electron environment. See the package
- * `NOTICE` for full third-party attribution.
- *
- * @module transformer/TransformerService
- */
-
-/**
- * TransformerService manages the lifecycle of all transformers.
- *
- * Features:
- * - Register transformers by name
- * - Get transformer by name
- * - Initialize default transformers
- * - Resolve transformer chains from configuration
- */
-declare class TransformerService {
-    private transformers;
-    private logger;
-    private instanceCache;
-    private endpointTransformersCache;
-    private noEndpointTransformersCache;
-    constructor(logger?: TransformerLogger);
-    /**
-     * Clear instance caches
-     */
-    clearInstanceCache(): void;
-    /**
-     * Get cache statistics for diagnostics
-     */
-    getCacheStats(): {
-        instanceCacheSize: number;
-        hasEndpointCache: boolean;
-    };
-    /**
-     * Register a transformer by name
-     * @param name - Unique transformer name
-     * @param transformer - Transformer instance or constructor
-     */
-    registerTransformer(name: string, transformer: Transformer | TransformerConstructor): void;
-    /**
-     * Get a transformer by name
-     * @param name - Transformer name
-     * @returns Transformer instance/constructor or undefined
-     */
-    getTransformer(name: string): Transformer | TransformerConstructor | undefined;
-    /**
-     * Get all registered transformers
-     * @returns Map of all transformers
-     */
-    getAllTransformers(): Map<string, Transformer | TransformerConstructor>;
-    /**
-     * Get transformers that have an endpoint defined
-     * Uses cache to avoid redundant traversal
-     * @returns Array of transformers with endpoints
-     */
-    getTransformersWithEndpoint(): {
-        name: string;
-        transformer: Transformer;
-    }[];
-    /**
-     * Get transformers without endpoints
-     * Uses cache to avoid redundant traversal
-     * @returns Array of transformers without endpoints
-     */
-    getTransformersWithoutEndpoint(): {
-        name: string;
-        transformer: Transformer;
-    }[];
-    /**
-     * Remove a transformer by name
-     * @param name - Transformer name
-     * @returns true if removed, false if not found
-     */
-    removeTransformer(name: string): boolean;
-    /**
-     * Check if a transformer is registered
-     * @param name - Transformer name
-     * @returns true if registered
-     */
-    hasTransformer(name: string): boolean;
-    /**
-     * Initialize the service with default transformers
-     * @param defaultTransformers - Map or object of default transformers
-     */
-    initialize(defaultTransformers?: Record<string, Transformer | TransformerConstructor>): Promise<void>;
-    /**
-     * Register default transformers from a map
-     * @param transformers - Map of transformer name to transformer
-     */
-    private registerDefaultTransformers;
-    /**
-     * Resolve a transformer chain configuration to actual transformer instances
-     * @param chainConfig - Transformer chain configuration
-     * @param modelName - Model name for model-specific transformers
-     * @returns Resolved transformer chain with instances
-     */
-    resolveTransformerChain(chainConfig: TransformerChainConfig | undefined, modelName?: string): ResolvedTransformerChain;
-    /**
-     * Resolve an array of transformer references to instances
-     * @param refs - Array of transformer references
-     * @returns Array of transformer instances
-     */
-    resolveTransformerReferences(refs: TransformerReference[]): Transformer[];
-    /**
-     * Instantiate a transformer if it's a constructor
-     * Uses instance cache to avoid redundant instantiation
-     *
-     * @param transformer - Transformer instance or constructor
-     * @param options - Options to pass to constructor
-     * @returns Transformer instance
-     */
-    private instantiateIfNeeded;
-    /**
-     * Check if a value is a transformer constructor
-     * @param value - Value to check
-     * @returns true if it's a constructor
-     */
-    private isTransformerConstructor;
-    /**
-     * Get list of all registered transformer names
-     * @returns Array of transformer names
-     */
-    getTransformerNames(): string[];
-    /**
-     * Clear all registered transformers
-     */
-    clear(): void;
-}
-
-/**
- * Shared contract types for the resident `ProviderProxy`.
- *
- * The `ProviderProxy` (OpenSpec `engine-provider-decouple`, design D0/D3/D7/D9)
- * is the single resident `127.0.0.1` listener that subsumes both of the
- * host's per-session proxies (Anthropic Messages ingress and OpenAI Responses
- * ingress). Per-run state lives in a `Map<token, RouteContext>`
- * minted at run start and reaped at run end / on idle TTL.
- *
- * These types are kept in their own module so the server, route map, router,
- * and the two ingress parsers can share shapes without importing one another
- * for type-only purposes.
- *
- * @module provider-proxy/types
- */
-
-/** Lightweight summary derived from the inbound Anthropic request body —
- *  consumed by `modelMapper` (scenario routing) without full body access. */
-interface SubscriptionRequestSummary {
-    messageCount: number;
-    /** cl100k_base-estimated token count of system + messages (no tools). */
-    estimatedInputTokens: number;
-    /**
-     * OPTIONAL bounded per-message text slice (system prompt + the most recent
-     * user/system messages, each per-message-capped) consumed ONLY by the
-     * OpenCodeGo keyword matcher in `@omnicross/subscriptions`
-     * (`resolveOpenCodeGoScenario`). Core only WRITES this `string[]`; it never
-     * reads it and never names the matcher — keeping the cross-layer litmus at 0
-     * (no `@omnicross/core` → `@omnicross/subscriptions` edge). Optional so callers
-     * that omit it (legacy/tests) compile and degrade to the token-threshold +
-     * `default` routing.
-     */
-    matchText?: string[];
-}
-interface SubscriptionDispatchProfile {
-    readonly providerId: SubscriptionProviderId;
-    readonly displayName: string;
-    readonly authStrategy: AuthStrategy;
-    /** Pass-through providers (Claude) skip the transformer chain entirely.
-     *  Transformer providers use the chain below + the proxy's existing
-     *  `AnthropicTransformer` endpoint reverse-decoder. */
-    readonly mode: 'pass-through' | 'transformer';
-    /** Resolve the upstream URL for a given resolved model id. Required for
-     *  `mode === 'transformer'`; unused for pass-through (proxy hard-codes
-     *  `api.anthropic.com`). The OPTIONAL 2nd `config` arg lets the opencodego
-     *  profile honor a per-account `baseUrl` override (D1) — additive, so existing
-     *  one-arg callers compile unchanged. */
-    readonly resolveUpstreamUrl?: (resolvedModel: string, config?: OpenCodeGoTokenConfig) => string;
-    /** Names of transformers (registered in `TransformerService`) to run on the
-     *  provider chain. The proxy adds `AnthropicTransformer` as the endpoint
-     *  reverse-decoder. */
-    readonly providerTransformerNames?: readonly string[];
-    readonly modelTransformerNames?: readonly string[];
-    /**
-     * OPTIONAL shape-aware provider transformer-name resolver (opencodego zen).
-     * Parallel to `resolveUpstreamUrl(model, config)`: lets a profile vary its
-     * provider chain by the RESOLVED model's wire shape (e.g. zen `responses` ⇒
-     * `['openai-response']`, `gemini` ⇒ `['gemini']`). `config` is `unknown` on the
-     * core side (opaque-config discipline — core never names
-     * `OpenCodeGoTokenConfig` from `@omnicross/subscriptions`); the subscriptions
-     * implementation narrows it. When ABSENT, both ingress paths fall back to the
-     * static `providerTransformerNames` — BYTE-IDENTICAL for claude / codex / gemini
-     * (which leave this unset). Purely additive (optional).
-     */
-    readonly resolveProviderTransformerNames?: (model: string, config?: unknown) => readonly string[];
-    /** Optional model placeholder rewriter — only set for OpenCodeGo. */
-    readonly modelMapper?: (sdkModel: string, summary: SubscriptionRequestSummary, config: OpenCodeGoTokenConfig | undefined) => {
-        resolvedModel: string;
-        scenario: OpenCodeGoScenario;
-    };
-    /** Optional fallback resolver — for OpenCodeGo, picks the next model after
-     *  an unrecoverable error. Returns `null` when exhausted. Cap = 3. The
-     *  opencodego implementation ALSO consults the circuit breaker (D5): it skips
-     *  models whose circuit is open. */
-    readonly nextFallback?: (scenario: OpenCodeGoScenario, attempted: readonly string[], config: OpenCodeGoTokenConfig | undefined) => OpenCodeGoModelEntry | null;
-    /** Optional circuit-breaker admission gate for the PRIMARY (mapped) model
-     *  (D5 primary-gating). Only set for OpenCodeGo. Returns whether `modelId`'s
-     *  circuit currently admits a request (side-effecting: flips an `open` model
-     *  to `half-open` once its window elapses, exactly like `nextFallback`'s
-     *  internal consult). `nextFallback` covers the FALLBACKS; this covers the
-     *  primary the loop already holds. Absent/undefined ⇒ the loop treats the
-     *  primary as always admitted (claude / codex / gemini have no breaker). */
-    readonly allowModel?: (modelId: string) => boolean;
-    /** Optional record-outcome callback (D5 record seam). Only set for OpenCodeGo.
-     *  Both fallback loops invoke it after each attempt: `ok: true` on a `2xx`,
-     *  `ok: false` on a thrown/network error / `5xx` / `429`; a non-429 `4xx` is
-     *  NEUTRAL and the loops MUST NOT call it. Drives the per-model breaker.
-     *  Absent/undefined for claude / codex / gemini ⇒ a no-op (no breaker). */
-    readonly recordModelOutcome?: (modelId: string, ok: boolean) => void;
-}
-
 /**
  * SubscriptionProviderRegistry — fixed catalog of subscription dispatch profiles.
  *
@@ -802,7 +265,17 @@ interface DispatcherHooks {
     readonly executor: TransformerChainExecutor;
     /** Shared transformer service registry — looks up transformer-by-name. */
     readonly transformerService: TransformerService;
-    /** Fetch + retry helper from the proxy (semaphore, 429/5xx loop). */
+    /**
+     * Fetch + retry helper from the proxy (semaphore, 429/5xx loop). On a non-ok
+     * upstream it throws a `ProviderApiError`-shaped error carrying `.status`.
+     *
+     * ACCOUNT-HEALTH CONTRACT (subscription-account-health): for the daemon-path
+     * 429-reset cooldown + 403-ban sniff to function, the thrown error SHOULD also
+     * carry the upstream response `headers` (a `Headers` or a plain record) and, on
+     * a 403, a bounded `bodyText`/`body` string. The dispatcher reads them
+     * STRUCTURALLY (`errHeaders`/`errBodyText`) — absent ⇒ the account-health mark
+     * gracefully degrades to a bare-429 (unmarked, lazy re-probe), never an error.
+     */
     fetchWithRetry(url: string, headers: Record<string, string>, body: unknown, model: string): Promise<Response>;
     /** Forward the upstream response to the SDK + tap usage. */
     writeProxyResponse(res: http.ServerResponse, providerResponse: Response, isStream: boolean, reqId?: number): Promise<void>;
@@ -851,6 +324,17 @@ declare class SubscriptionDispatcher {
      */
     private maybeRetryAfterError;
     private applyHeadersWithRetry;
+    /**
+     * Mark the served account's health against ONE attempt's outcome
+     * (subscription-account-health, task 3.4). No-op when no account was reported
+     * (non-pooled / single-account) or on a session-cancel (status 0). On a caught
+     * error `err` is passed so the 429-reset / 403-ban drivers are read STRUCTURALLY
+     * from the error's upstream `headers` + `bodyText` (the `fetchWithRetry`
+     * contract) — so daemon-path 429 cooldown + ban blocking function for
+     * multi-account codex/gemini/opencodego pools; absent headers ⇒ a bare-429
+     * (unmarked, lazy re-probe). Success (2xx) clears; 401/5xx/thrown → transient.
+     */
+    private markHealth;
     /**
      * Resolve the Code Assist project for the gemini subscription profile. Pulls
      * the Bearer the bound `AuthStrategy` would inject (so the strategy stays the
@@ -865,4 +349,4 @@ declare class SubscriptionDispatcher {
     private buildRequestSummary;
 }
 
-export { type AuthApplyHints, type AuthStrategy, type DispatchRequest, type DispatcherHooks, SubscriptionAccountService, type SubscriptionCredentialStore, type SubscriptionDispatchProfile, SubscriptionDispatcher, SubscriptionProviderRegistry, type SubscriptionRequestSummary, getSubscriptionAccountService, getSubscriptionProviderRegistry, setSubscriptionAccountService, setSubscriptionProviderRegistry };
+export { DEFAULT_ACCOUNT_PRIORITY, type DispatchRequest, type DispatcherHooks, LAST_USED_PERSIST_THROTTLE_MS, SESSION_AFFINITY_TTL_MS, type SchedulableAccount, type SelectInput, type SelectResult, SubscriptionAccountSelector, SubscriptionAccountService, type SubscriptionCredentialStore, SubscriptionDispatcher, SubscriptionProviderRegistry, getSubscriptionAccountService, getSubscriptionProviderRegistry, setSubscriptionAccountService, setSubscriptionProviderRegistry };