@omnicross/subscriptions 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,868 @@
+import { AccountTokensConfig } from '@omnicross/contracts/account-tokens-types';
+import { SubscriptionProviderId, SubscriptionStatusEntry, SubscriptionListEntry, OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
+import http from 'node:http';
+export { FetchLike, claudeOAuth, codexOAuth, geminiOAuth } from './oauth.js';
+
+/**
+ * SubscriptionCredentialStore — the credential port the subscription block
+ * depends on instead of the host's concrete token store.
+ *
+ * The subscription auth strategies + account service + provider registry only
+ * ever consume a narrow six-method surface of the host's encrypted OAuth/static
+ * credential store. Declaring it here (in `@omnicross/subscriptions`) keeps the
+ * package host-clean: the host injects its concrete token store (which
+ * structurally satisfies this interface) at bootstrap.
+ *
+ * The serving core (`@omnicross/core`) does NOT consume credentials — it sees
+ * the subscription registry only through the `subscriptionRegistryPort` slot —
+ * so this port lives in THIS package, not in core (Phase-0b port pattern at the
+ * subscriptions layer).
+ */
+
+/** The six methods the subscription block consumes from the host credential store. */
+interface SubscriptionCredentialStore {
+    /** Full decrypted account-tokens config (all subscription providers). */
+    getFullConfig(): Promise<AccountTokensConfig>;
+    /** Current valid Claude OAuth access token, refreshing if near expiry; `null` if none. */
+    getValidClaudeAccessToken(): Promise<string | null>;
+    /** Force a Claude OAuth token refresh; `true` on success. */
+    refreshClaudeToken(): Promise<boolean>;
+    /** Force a Codex (ChatGPT) OAuth token refresh; `true` on success. */
+    refreshCodexToken(): Promise<boolean>;
+    /** Force a Gemini (Google) OAuth token refresh; `true` on success. */
+    refreshGeminiToken(): Promise<boolean>;
+    /** Current valid OpenCodeGo static API key; `null` if none. */
+    getValidOpenCodeGoApiKey(): Promise<string | null>;
+}
+
+/**
+ * SubscriptionAuthStrategy — the pluggable subscription-auth contract, defined
+ * in the serving core (`pipeline/`).
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @module pipeline/SubscriptionAuthStrategy
+ */
+
+/** 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>;
+}
+
+/**
+ * SubscriptionAccountService — the single resolver between the credential store and
+ * the dispatch proxy for subscription-mode dispatch.
+ *
+ * Responsibilities:
+ *   - Hold long-lived `AuthStrategy` instances for each subscription provider.
+ *   - Share a single `RefreshMutex` across all strategies so concurrent 401s
+ *     for the same provider collapse into one upstream refresh call.
+ *   - Expose `listAll()` / `getStatus()` for the `subscription:status` and
+ *     `subscription:list` IPC channels.
+ */
+
+declare class SubscriptionAccountService {
+    private readonly mutex;
+    private readonly strategies;
+    constructor(tokens: SubscriptionCredentialStore);
+    /** Returns the strategy bound to a subscription provider, or `null` for unknown ids. */
+    getStrategy(providerId: SubscriptionProviderId): AuthStrategy | null;
+    /** Diagnostic for the `subscription:status` IPC. */
+    getStatus(providerId: SubscriptionProviderId): Promise<SubscriptionStatusEntry>;
+    /** Catalog entry list for the `subscription:list` IPC. */
+    listAll(): Promise<SubscriptionListEntry[]>;
+}
+/** Set once at host bootstrap; consumed by the host's router + engine wiring. */
+declare function setSubscriptionAccountService(svc: SubscriptionAccountService): void;
+/** Returns the singleton if it has been set, else `null` (don't throw — callers
+ *  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.
+ *
+ * Each entry maps a `SubscriptionProviderId` to a `SubscriptionDispatchProfile`
+ * that tells the dispatch proxy:
+ *   - how to authenticate (via the bound `AuthStrategy`),
+ *   - which transformer chain to run (resolved by name from `TransformerService`),
+ *   - which upstream URL to hit (static OR computed per model id),
+ *   - how to map the SDK-supplied model placeholder to a provider model
+ *     (OpenCodeGo scenario routing),
+ *   - which fallback model entries to try when the primary fails.
+ *
+ * The registry is intentionally a static in-memory map — subscription
+ * providers are a built-in catalog, NOT user-configurable LLM provider rows.
+ */
+
+declare class SubscriptionProviderRegistry {
+    private readonly accounts;
+    private readonly tokens;
+    private readonly profiles;
+    /**
+     * Per-model circuit breaker for opencodego routing (D5). ONE registry-owned
+     * process singleton, built here and captured by the opencodego profile's
+     * `nextFallback` (consult) + `recordModelOutcome` (record) closures. Because
+     * the `SubscriptionProviderRegistry` is itself a process singleton (via
+     * `setSubscriptionProviderRegistry`), breaker state persists across requests —
+     * exactly the reference's long-lived `FallbackHandler`. Constructed with the
+     * default reference thresholds (3 / 30s / 3) and the default `Date.now` clock.
+     */
+    private readonly breaker;
+    constructor(accounts: SubscriptionAccountService, tokens: SubscriptionCredentialStore);
+    /** Returns the dispatch profile for a known subscription provider, or
+     *  `null` for unknown ids (callers must treat null as "fall back to the
+     *  legacy LLM provider DB lookup"). */
+    getProfile(providerId: string): SubscriptionDispatchProfile | null;
+    /** Read the currently-stored OpenCodeGo config so the proxy can pick up
+     *  user overrides (modelMap / fallbacks / baseUrl). Wraps the injected
+     *  `SubscriptionCredentialStore` so the proxy doesn't need to know about
+     *  that surface. */
+    getOpenCodeGoConfig(): Promise<OpenCodeGoTokenConfig | undefined>;
+}
+declare function setSubscriptionProviderRegistry(svc: SubscriptionProviderRegistry): void;
+declare function getSubscriptionProviderRegistry(): SubscriptionProviderRegistry | null;
+
+/**
+ * SubscriptionDispatcher — handles the dispatch proxy's subscription-mode flow.
+ *
+ * Extracted from the host proxy server to keep that file focused on the legacy
+ * LLM-provider pipeline. The dispatcher mirrors the proxy's inner
+ * transformer-pipeline shape but sources upstream URL,
+ * transformer chain, auth, and model mapping from a
+ * `SubscriptionDispatchProfile` instead of the host's config service.
+ *
+ * The proxy delegates here from `handleRequest` whenever a profile is bound.
+ */
+
+/** Hooks the dispatcher needs from the host proxy server's private surface. */
+interface DispatcherHooks {
+    /** Anthropic endpoint transformer instance, reused across requests. */
+    readonly endpointTransformer: Transformer;
+    /** Shared transformer chain executor. */
+    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). */
+    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>;
+}
+interface DispatchRequest {
+    reqId: number;
+    res: http.ServerResponse;
+    rawBody: string;
+    anthropicBody: Record<string, unknown>;
+    isStream: boolean;
+    sdkModel: string;
+    fallbackModel: string;
+}
+declare class SubscriptionDispatcher {
+    private readonly profile;
+    private readonly hooks;
+    private readonly getOpenCodeGoConfig;
+    constructor(profile: SubscriptionDispatchProfile, hooks: DispatcherHooks, getOpenCodeGoConfig: () => Promise<OpenCodeGoTokenConfig | undefined>);
+    /**
+     * Entry point — called by the host proxy's request handler after model
+     * resolution and probe-detection.
+     */
+    dispatch(req: DispatchRequest): Promise<void>;
+    /** Bypass path for OpenCodeGo MiniMax models — forwards Anthropic body verbatim. */
+    private dispatchAnthropicShapeBypass;
+    /** Standard subscription transformer chain — Codex/Gemini/OpenCodeGo OpenAI-shape. */
+    private dispatchTransformerChain;
+    /**
+     * D2 PRIMARY-GATING (opencodego, D5): pick the first-attempt model for a
+     * fallback loop. Consults the breaker for the mapped primary; when the primary's
+     * circuit is open, advance to the first admitting `nextFallback` candidate
+     * WITHOUT an upstream round-trip on the open primary. When EVERY candidate is
+     * open (all-open) the breaker FAILS OPEN — it attempts the original primary
+     * anyway. Returns the resolved first-attempt model plus the `attempted` list
+     * seeded for the loop (the SKIPPED primary is recorded at chain index 0 so the
+     * loop's `nextFallback` excludes it; on fail-open the list is left empty so the
+     * primary is the first real attempt). When the profile has no `allowModel`
+     * (claude / codex / gemini, or breaker unset) this is byte-identical to the
+     * prior behavior: the primary is the first attempt, `attempted` empty.
+     */
+    private gatePrimaryModel;
+    /**
+     * On a 401 error from the upstream, ask the AuthStrategy whether to retry.
+     * Returns `{ retryOnce: true, headers }` when the strategy refreshed
+     * successfully (caller should retry once); otherwise re-throws.
+     */
+    private maybeRetryAfterError;
+    private applyHeadersWithRetry;
+    /**
+     * Resolve the Code Assist project for the gemini subscription profile. Pulls
+     * the Bearer the bound `AuthStrategy` would inject (so the strategy stays the
+     * single source of the token), then runs the cached handshake. Returns
+     * `undefined` for a fresh free-tier account (valid — the envelope omits the
+     * project). A handshake hard failure (403/429) propagates to the dispatch
+     * error handler.
+     */
+    private resolveGeminiProject;
+    private resolveTransformers;
+    /** Build a lightweight request summary for OpenCodeGo scenario routing. */
+    private buildRequestSummary;
+}
+
+export { type AuthApplyHints, type AuthStrategy, type DispatchRequest, type DispatcherHooks, SubscriptionAccountService, type SubscriptionCredentialStore, type SubscriptionDispatchProfile, SubscriptionDispatcher, SubscriptionProviderRegistry, type SubscriptionRequestSummary, getSubscriptionAccountService, getSubscriptionProviderRegistry, setSubscriptionAccountService, setSubscriptionProviderRegistry };