@omnicross/core 0.1.10 → 0.2.0

package/dist/types-CVRge76p.d.ts

@@ -0,0 +1,1115 @@
+import http from 'node:http';
+import { ThinkLevel } from '@omnicross/contracts/completion-types';
+import { UsageCacheKeySource } from '@omnicross/contracts/usage-stats-types';
+import { SubscriptionProviderId, OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
+import { UsageEngineOrigin, UsageTokens } from '@omnicross/contracts/usage-types';
+import { ApiKeyPoolService } from './completion/ApiKeyPoolService.js';
+import { AuthSource } from './pipeline/AuthSource.js';
+import { BoundAccountFallbackPolicy } from './pipeline/BoundAccountSelectionError.js';
+import { SubscriptionAuthProfile } from './pipeline/SubscriptionAuthSource.js';
+import { AuthStrategy } from './pipeline/SubscriptionAuthStrategy.js';
+import { ProviderConfigSource } from './ports/provider-config-source.js';
+import { WebSearchBackend } from './ports/web-search-backend.js';
+import { ImageArtifactMetadata, SensitiveOpaqueImageReference, ImageReferenceMetadata, ImageReferenceId, ImageAction, ImageQuality, ImageBackground, ImageOutputFormat, ImageGenerationErrorCode, ImageUsage, ImageArtifactId, ImageCapabilities, NormalizedImageRequest, ImageProviderEvent, ImageSize, ImageGenerationPublicError } from '@omnicross/contracts/image-generation-types';
+import { ApiFormat } from '@omnicross/contracts/llm-config';
+
+/**
+ * Stable identities for the OpenAI-compatible HTTP operations Omnicross knows.
+ *
+ * Classification is deliberately closed and path-only. Adapters can vary how
+ * an extension-owned operation is implemented, but cannot claim new public
+ * paths at runtime.
+ *
+ * @module openai-operation/openAIOperation
+ */
+type OpenAIOperationId = 'chat.completions.create' | 'responses.create' | 'responses.compact' | 'images.generate' | 'images.edit';
+type OpenAIPolicyFamily = 'chat' | 'responses' | 'images';
+type OpenAIRouteFamily = OpenAIPolicyFamily;
+type OpenAIOperationOwner = 'builtin' | 'extension';
+type OpenAIOperationBodyKind = 'json' | 'multipart';
+type OpenAIRequestedModelSource = 'request' | 'configured';
+interface OpenAIOperation {
+    readonly id: OpenAIOperationId;
+    readonly policyFamily: OpenAIPolicyFamily;
+    readonly routeFamily: OpenAIRouteFamily;
+    readonly owner: OpenAIOperationOwner;
+    readonly bodyKind: OpenAIOperationBodyKind;
+    readonly requestedModelSource: OpenAIRequestedModelSource;
+}
+type ExtensionOpenAIOperationId = 'responses.compact' | 'images.generate' | 'images.edit';
+declare function getOpenAIOperation(id: OpenAIOperationId): OpenAIOperation;
+/** Classify a supported OpenAI operation under any base-path prefix. */
+declare function classifyOpenAIOperation(method: string | undefined, url: string | undefined): OpenAIOperation | null;
+
+/**
+ * Trusted in-process handler seam for extension-owned OpenAI operations.
+ *
+ * The registry owns uniqueness, request-lifetime cancellation, and the narrow
+ * local error envelope. Authentication and route selection remain outside this
+ * module and must complete before dispatch.
+ *
+ * @module openai-operation/openAIOperationRegistry
+ */
+
+interface OpenAIOperationHandlerContext {
+    readonly operation: OpenAIOperation;
+    readonly request: http.IncomingMessage;
+    readonly response: http.ServerResponse;
+    readonly route: RouteContext;
+    readonly deps: ProviderProxyDeps;
+    readonly signal: AbortSignal;
+}
+type OpenAIOperationHandler = (context: OpenAIOperationHandlerContext) => Promise<void>;
+type OpenAIOperationRegistrationErrorCode = 'builtin_operation' | 'duplicate_operation_handler';
+declare class OpenAIOperationRegistrationError extends Error {
+    readonly code: OpenAIOperationRegistrationErrorCode;
+    readonly name = "OpenAIOperationRegistrationError";
+    constructor(code: OpenAIOperationRegistrationErrorCode, message: string);
+}
+interface OpenAIOperationErrorInit {
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly retryable?: boolean;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+declare class OpenAIOperationError extends Error {
+    readonly name = "OpenAIOperationError";
+    readonly status: number;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly headers: Readonly<Record<string, string>>;
+    constructor(init: OpenAIOperationErrorInit);
+}
+/** Write a typed, locally-generated OpenAI-compatible error before streaming starts. */
+declare function writeOpenAIOperationError(res: http.ServerResponse, error: OpenAIOperationError): boolean;
+declare function unsupportedOpenAIOperation(operation: OpenAIOperation): OpenAIOperationError;
+interface OpenAIOperationDispatchContext {
+    readonly operation: OpenAIOperation;
+    readonly request: http.IncomingMessage;
+    readonly response: http.ServerResponse;
+    readonly route: RouteContext;
+    readonly deps: ProviderProxyDeps;
+}
+declare class OpenAIOperationRegistry {
+    private readonly handlers;
+    register(operationId: ExtensionOpenAIOperationId, handler: OpenAIOperationHandler): () => void;
+    has(operationId: OpenAIOperationId): boolean;
+    dispatch(context: OpenAIOperationDispatchContext): Promise<boolean>;
+}
+
+interface ImageAsset extends ImageArtifactMetadata {
+    /** Every call returns a new bounded, independently readable byte stream. */
+    open(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ReadableStream<Uint8Array>>;
+}
+declare class InMemoryImageAsset implements ImageAsset {
+    #private;
+    readonly artifactId: ImageArtifactId;
+    readonly mimeType: `image/${string}`;
+    readonly byteLength: number;
+    readonly width: number;
+    readonly height: number;
+    readonly hasAlpha?: boolean;
+    readonly sha256?: string;
+    readonly independentlyDecodable: true;
+    constructor(bytes: Uint8Array, metadata: Omit<ImageArtifactMetadata, 'artifactId' | 'byteLength' | 'independentlyDecodable'> & {
+        readonly artifactId?: ImageArtifactId;
+    });
+    open(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ReadableStream<Uint8Array>>;
+    /** Best-effort zeroization for short-lived verified/probe artifacts. */
+    dispose(): void;
+}
+declare function readImageAssetBytes(asset: ImageAsset, maxBytes: number, signal?: AbortSignal): Promise<Uint8Array>;
+interface ImageReferenceValue {
+    readonly artifact?: ImageAsset;
+    readonly providerReference?: SensitiveOpaqueImageReference;
+}
+interface ImageReferenceSaveInput extends ImageReferenceValue {
+    readonly tenantId: string;
+    readonly ttlMs: number;
+    readonly metadata: Omit<ImageReferenceMetadata, 'referenceId' | 'createdAt' | 'expiresAt'>;
+}
+interface ImageReferenceLease {
+    readonly metadata: ImageReferenceMetadata;
+    readonly value: ImageReferenceValue;
+    release(): Promise<void>;
+}
+type ImageReferenceResolution = {
+    readonly status: 'found';
+    readonly lease: ImageReferenceLease;
+} | {
+    readonly status: 'expired';
+} | {
+    readonly status: 'not_found';
+};
+interface ImageReferenceStore {
+    save(input: ImageReferenceSaveInput): Promise<ImageReferenceMetadata>;
+    resolve(tenantId: string, referenceId: ImageReferenceId): Promise<ImageReferenceResolution>;
+    delete(tenantId: string, referenceId: ImageReferenceId): Promise<boolean>;
+    cleanup(now?: number): Promise<number>;
+}
+/** Deterministic-clock test double; production wiring supplies a bounded persistent store. */
+declare class InMemoryImageReferenceStore implements ImageReferenceStore {
+    #private;
+    constructor(now?: () => number);
+    save(input: ImageReferenceSaveInput): Promise<ImageReferenceMetadata>;
+    resolve(tenantId: string, referenceId: ImageReferenceId): Promise<ImageReferenceResolution>;
+    delete(tenantId: string, referenceId: ImageReferenceId): Promise<boolean>;
+    cleanup(now?: number): Promise<number>;
+}
+interface ImageTelemetryOutputMetadata {
+    readonly mimeType: `image/${string}`;
+    readonly byteLength: number;
+    readonly width: number;
+    readonly height: number;
+    readonly hasAlpha?: boolean;
+}
+/** No content-bearing, credential, tenant, account, URL, or raw-reference field exists here. */
+interface ImageTelemetryRecord {
+    readonly requestId: string;
+    readonly providerId: string;
+    readonly model: string;
+    readonly action: ImageAction;
+    readonly quality: ImageQuality;
+    readonly background: ImageBackground;
+    readonly outputFormat: ImageOutputFormat;
+    readonly streaming: boolean;
+    readonly inputCount: number;
+    readonly inputBytes: number;
+    readonly requestedOutputCount: number;
+    readonly outputs: readonly ImageTelemetryOutputMetadata[];
+    readonly startedAt: number;
+    readonly acceptedAt?: number;
+    readonly firstPartialAt?: number;
+    readonly generationStartedAt?: number;
+    readonly finishedAt: number;
+    readonly terminal: 'completed' | 'failed' | 'cancelled';
+    readonly errorCode?: ImageGenerationErrorCode;
+    readonly usage?: ImageUsage;
+    readonly usageUnavailable: boolean;
+    /** Present only when the provider can report exact attempt counts. */
+    readonly retryCount?: number;
+    /** Present only when the provider can report exact successful refresh counts. */
+    readonly authRefreshCount?: number;
+    /** Present only when selected-account scheduling measured its own wait. */
+    readonly queueWaitMs?: number;
+    /** Present when retention was enabled; contains a count, never reference IDs. */
+    readonly referenceSaveCount?: number;
+    /** Count-only cleanup signal; never contains tenant or reference identifiers. */
+    readonly retentionRollbackFailures?: number;
+}
+interface ImageTelemetrySink {
+    record(record: ImageTelemetryRecord): void | Promise<void>;
+}
+declare function emitImageTelemetry(sink: ImageTelemetrySink | undefined, record: ImageTelemetryRecord): Promise<void>;
+
+type ImageProviderRequest = NormalizedImageRequest<ImageAsset>;
+interface ImageProviderContext {
+    readonly requestId: string;
+    readonly tenantId: string;
+    readonly signal: AbortSignal;
+    readonly sessionKey?: string;
+    readonly preferredAccountId?: string;
+    readonly preferredAccountGroup?: string;
+    readonly boundAccountFallbackPolicy?: 'strict' | 'pool';
+}
+/** Optional numeric-only job observations exposed to the orchestrator. */
+interface ImageJobObservabilitySnapshot {
+    readonly queueWaitMs?: number;
+    readonly generationStartedAt?: number;
+    readonly retryCount?: number;
+    readonly authRefreshCount?: number;
+}
+interface ImageJobObservability {
+    snapshot(): ImageJobObservabilitySnapshot;
+}
+interface ImageJob {
+    readonly events: AsyncIterable<ImageProviderEvent<ImageAsset>>;
+    readonly observability?: ImageJobObservability;
+    cancel(reason?: string): Promise<void>;
+}
+interface ImageProviderLease {
+    readonly providerId: string;
+    readonly capabilities: ImageCapabilities;
+    start(request: ImageProviderRequest): Promise<ImageJob> | ImageJob;
+    release(): Promise<void>;
+}
+interface ImageProvider {
+    readonly id: string;
+    acquire(context: ImageProviderContext): Promise<ImageProviderLease>;
+}
+
+declare class ImageProviderRegistry {
+    #private;
+    constructor(providers?: readonly ImageProvider[]);
+    register(provider: ImageProvider): void;
+    resolve(id: string): ImageProvider | undefined;
+    require(id: string): ImageProvider;
+    list(): readonly ImageProvider[];
+}
+
+interface ImageRetentionPolicy {
+    readonly enabled: boolean;
+    readonly ttlMs: number;
+}
+interface ImageOrchestratorRunOptions {
+    readonly providerId: string;
+    readonly retention?: ImageRetentionPolicy;
+    /** Hosted Responses execution must be affirmed by the same acquired capability snapshot. */
+    readonly requireResponsesTool?: boolean;
+}
+interface ImageOrchestratorOptions {
+    readonly registry: ImageProviderRegistry;
+    readonly referenceStore?: ImageReferenceStore;
+    readonly telemetrySink?: ImageTelemetrySink;
+    readonly now?: () => number;
+}
+declare class ImageOrchestrator {
+    #private;
+    constructor(options: ImageOrchestratorOptions);
+    getCapabilities(providerId: string, context: ImageProviderContext): Promise<ImageCapabilities>;
+    run(request: ImageProviderRequest, context: ImageProviderContext, options: ImageOrchestratorRunOptions): AsyncIterable<ImageProviderEvent<ImageAsset>>;
+}
+
+interface ResponsesImageCallStateLease {
+    readonly binding: ResponsesImageCallBinding;
+    release(): Promise<void>;
+}
+interface ResponsesImageResponseStateLease {
+    readonly responseId: string;
+    readonly callIds: readonly ResponsesImageCallId[];
+    readonly expiresAt: number;
+    release(): Promise<void>;
+}
+type ResponsesImageCallResolution = {
+    readonly status: 'found';
+    readonly lease: ResponsesImageCallStateLease;
+} | {
+    readonly status: 'expired';
+} | {
+    readonly status: 'not_found';
+};
+type ResponsesImageResponseResolution = {
+    readonly status: 'found';
+    readonly lease: ResponsesImageResponseStateLease;
+} | {
+    readonly status: 'expired';
+} | {
+    readonly status: 'not_found';
+};
+interface ResponsesImageStateCommitInput {
+    readonly tenantId: string;
+    readonly responseId: string;
+    /** Empty is an explicit known-empty response marker, never a no-op. */
+    readonly bindings: readonly ResponsesImageCallBinding[];
+    readonly responseExpiresAt: number;
+}
+interface ResponsesImageStateStore {
+    commit(input: ResponsesImageStateCommitInput): Promise<readonly ResponsesImageCallBinding[]>;
+    resolveCall(tenantId: string, callId: ResponsesImageCallId): Promise<ResponsesImageCallResolution>;
+    resolveResponse(tenantId: string, responseId: string): Promise<ResponsesImageResponseResolution>;
+    deleteCall(tenantId: string, callId: ResponsesImageCallId): Promise<ResponsesImageCallBinding | undefined>;
+    deleteResponse(tenantId: string, responseId: string): Promise<boolean>;
+    cleanup(now?: number): Promise<readonly ResponsesImageCallBinding[]>;
+}
+interface InMemoryResponsesImageStateStoreOptions {
+    readonly maxCalls?: number;
+    readonly maxResponses?: number;
+    readonly maxTombstones?: number;
+    readonly tombstoneTtlMs?: number;
+    readonly now?: () => number;
+}
+/** Bounded deterministic test/default implementation; production wiring may inject persistence. */
+declare class InMemoryResponsesImageStateStore implements ResponsesImageStateStore {
+    #private;
+    constructor(options?: InMemoryResponsesImageStateStoreOptions);
+    commit(input: ResponsesImageStateCommitInput): Promise<readonly ResponsesImageCallBinding[]>;
+    resolveCall(tenantId: string, callId: ResponsesImageCallId): Promise<ResponsesImageCallResolution>;
+    resolveResponse(tenantId: string, responseId: string): Promise<ResponsesImageResponseResolution>;
+    deleteCall(tenantId: string, callId: ResponsesImageCallId): Promise<ResponsesImageCallBinding | undefined>;
+    deleteResponse(tenantId: string, responseId: string): Promise<boolean>;
+    cleanup(now?: number): Promise<readonly ResponsesImageCallBinding[]>;
+}
+
+type ResponsesImageAction = 'auto' | 'generate' | 'edit';
+type ResponsesImageCallId = `ig_${string}`;
+interface ResponsesImageInspectionInput {
+    readonly tools?: unknown;
+    readonly tool_choice?: unknown;
+    readonly stream?: unknown;
+    readonly previous_response_id?: unknown;
+    readonly input?: unknown;
+}
+interface ResponsesImageNormalizedOptions {
+    readonly action: ResponsesImageAction;
+    readonly quality: ImageQuality;
+    readonly size: ImageSize;
+    readonly background: ImageBackground;
+    readonly outputFormat: ImageOutputFormat;
+    readonly outputCompression?: number;
+    readonly partialImages: number;
+}
+type ResponsesImageSelectionPolicy = {
+    readonly kind: 'auto';
+} | {
+    readonly kind: 'required';
+} | {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'forced_image';
+} | {
+    readonly kind: 'forced_other';
+    readonly toolType: string;
+    readonly toolName?: string;
+};
+/**
+ * Closed identity for one non-image declaration. The declaration index is the
+ * trust anchor: selected plans cannot invent a type/name. Multiple bounded
+ * calls may reuse one declaration while their wire item/call IDs stay unique.
+ */
+interface ResponsesHostedToolIdentity {
+    readonly declarationIndex: number;
+    readonly type: string;
+    readonly name?: string;
+}
+interface ResponsesImageAdmission {
+    readonly declared: boolean;
+    readonly imageToolIndex?: number;
+    readonly otherToolCount: number;
+    readonly otherTools: readonly ResponsesHostedToolIdentity[];
+    readonly stream: boolean;
+    readonly previousResponseId?: string;
+    readonly explicitCallIds: readonly ResponsesImageCallId[];
+    readonly selectionPolicy: ResponsesImageSelectionPolicy;
+    readonly options?: ResponsesImageNormalizedOptions;
+}
+interface ResponsesSelectedImageCall {
+    readonly prompt: string;
+}
+interface ResponsesHostedToolSelection {
+    readonly imageCalls: readonly ResponsesSelectedImageCall[];
+    readonly otherToolCount: number;
+    readonly otherTools: readonly ResponsesHostedToolIdentity[];
+}
+interface ResponsesImageEventAllocator {
+    reserveOutputIndex(): number;
+    nextSequenceNumber(): number;
+}
+interface ResponsesImageCallBinding {
+    readonly callId: ResponsesImageCallId;
+    readonly referenceId: ImageReferenceId;
+    readonly expiresAt: number;
+}
+interface ResponsesImageGenerationCallItem {
+    readonly id: ResponsesImageCallId;
+    readonly type: 'image_generation_call';
+    readonly status: 'completed';
+    readonly result: string;
+    readonly revised_prompt?: string;
+}
+interface ResponsesImageGenerationCallStartedItem {
+    readonly id: ResponsesImageCallId;
+    readonly type: 'image_generation_call';
+    readonly status: 'in_progress';
+}
+interface ResponsesImagePartialEvent {
+    readonly type: 'response.image_generation_call.partial_image';
+    readonly output_index: number;
+    readonly item_id: ResponsesImageCallId;
+    readonly sequence_number: number;
+    readonly partial_image_index: number;
+    readonly partial_image_b64: string;
+}
+/** Internal start record; the integrator owns official item-added SSE events. */
+interface ResponsesImageStartedRecord {
+    readonly kind: 'started';
+    readonly outputIndex: number;
+    readonly item: ResponsesImageGenerationCallStartedItem;
+}
+/** Internal terminal record; the integrator owns official terminal SSE events. */
+interface ResponsesImageCompletedRecord {
+    readonly kind: 'completed';
+    readonly outputIndex: number;
+    readonly item: ResponsesImageGenerationCallItem;
+}
+/** Internal failure record for the integrator's normal Responses error path. */
+interface ResponsesImageFailedRecord {
+    readonly kind: 'failed';
+    readonly outputIndex?: number;
+    readonly callId?: ResponsesImageCallId;
+    readonly error: ImageGenerationPublicError;
+}
+type ResponsesImageExecutionEvent = ResponsesImageStartedRecord | ResponsesImagePartialEvent | ResponsesImageCompletedRecord | ResponsesImageFailedRecord;
+interface ResponsesImageTrustedRuntime {
+    readonly tenantId: string;
+    readonly requestId: string;
+    readonly providerId: string;
+    readonly imageModel: string;
+    readonly referenceTtlMs: number;
+    readonly maxOutputBytes: number;
+    readonly maxTotalOutputBytes: number;
+    readonly signal: AbortSignal;
+    readonly sessionKey?: string;
+    readonly preferredAccountId?: string;
+    readonly preferredAccountGroup?: string;
+    readonly boundAccountFallbackPolicy?: 'strict' | 'pool';
+}
+interface ResponsesImageRequestScopeInput {
+    readonly admission: ResponsesImageAdmission;
+    readonly runtime: ResponsesImageTrustedRuntime;
+    /** Must already be authorized by the existing Responses affinity boundary. */
+    readonly authorizedPreviousResponseId?: string;
+    /** True only when that authorized affinity record explicitly has no image context. */
+    readonly authorizedPreviousResponseKnownEmpty?: boolean;
+}
+interface ResponsesImageRequestScope {
+    executeSelectedCall(call: ResponsesSelectedImageCall, allocator: ResponsesImageEventAllocator): AsyncIterable<ResponsesImageExecutionEvent>;
+    commit(responseId: string): Promise<void>;
+    dispose(): Promise<void>;
+    waitForIdle(): Promise<void>;
+}
+interface ResponsesImageGenerationContributionDeps {
+    readonly orchestrator: ImageOrchestrator;
+    readonly stateStore: ResponsesImageStateStore;
+    /** Must be the same store injected into the orchestrator. */
+    readonly referenceStore: ImageReferenceStore;
+    readonly createCallId?: () => ResponsesImageCallId;
+    readonly now?: () => number;
+}
+interface ResponsesImageGenerationContribution {
+    readonly toolType: 'image_generation';
+    inspectRequest(input: ResponsesImageInspectionInput): ResponsesImageAdmission;
+    validateSelection(admission: ResponsesImageAdmission, selection: ResponsesHostedToolSelection): void;
+    createRequestScope(input: ResponsesImageRequestScopeInput): Promise<ResponsesImageRequestScope>;
+}
+
+type ResponsesCredentialIdentity = {
+    readonly kind: 'subscription-account';
+    readonly id: string;
+} | {
+    readonly kind: 'byo-key';
+    readonly id: string;
+} | {
+    readonly kind: 'provider-key';
+    readonly id: string;
+};
+interface ResponsesAffinityScope {
+    readonly providerId: string;
+    readonly clientScope: string;
+    readonly sessionKey: string;
+}
+interface ResponsesAffinityPendingImageReceipt {
+    readonly upstreamCallId: string;
+    readonly publicImageCallId: string;
+}
+interface ResponsesAffinityHostedImageState {
+    readonly hasImageContext: boolean;
+    readonly pendingReceipts: readonly ResponsesAffinityPendingImageReceipt[];
+}
+interface ResponsesAffinityRecord extends ResponsesAffinityScope {
+    readonly responseId: string;
+    readonly credential: ResponsesCredentialIdentity;
+    readonly hostedImage?: ResponsesAffinityHostedImageState;
+}
+interface ResponsesAffinityEntry extends ResponsesAffinityRecord {
+    readonly expiresAt: number;
+}
+interface ResponsesAffinityStoreOptions {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+}
+declare function previousResponseNotFound(): OpenAIOperationError;
+/** Bounded process-local response identity index with sliding expiry and LRU eviction. */
+declare class ResponsesAffinityStore {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options?: ResponsesAffinityStoreOptions);
+    get size(): number;
+    record(record: ResponsesAffinityRecord): void;
+    /** Lookup never discloses whether an id exists in another provider/client/session scope. */
+    lookup(responseId: string, scope: ResponsesAffinityScope): ResponsesAffinityEntry;
+    clear(): void;
+    private pruneExpired;
+}
+/** Resolve one affinity store per app-session dependency container. */
+declare function getResponsesAffinityStore(owner: object): ResponsesAffinityStore;
+
+type ResponsesProfile = 'native' | 'reduced';
+interface ResponsesProfileDeclaration {
+    readonly authMode: 'byo' | 'subscription';
+    readonly providerApiFormat?: ApiFormat;
+    readonly subscriptionProviderId?: string;
+    readonly subscriptionTransformerNames?: readonly string[];
+    readonly upstreamUrl?: string;
+}
+/**
+ * Resolve the protocol contract from explicit provider metadata. Transformer
+ * instance identity and transformer-array equality are deliberately irrelevant.
+ */
+declare function classifyResponsesProfile(declaration: ResponsesProfileDeclaration): ResponsesProfile;
+
+interface ResponsesHostedImageOpenRequestInput {
+    readonly admission: ResponsesImageAdmission;
+    readonly tenantId: string;
+    readonly requestId: string;
+    readonly sessionKey: string;
+    readonly signal: AbortSignal;
+    readonly authorizedPreviousResponseId?: string;
+    /** Derived only from the authorized affinity record, never from request input. */
+    readonly authorizedPreviousResponseKnownEmpty?: boolean;
+    readonly mainProviderId: string;
+    readonly selectedMainAccountId?: string;
+}
+/** Structural app-session port implemented by the daemon's pinned image generation. */
+interface ResponsesHostedImageRuntimeLease {
+    readonly generationId: string;
+    inspectRequest(input: ResponsesImageInspectionInput): ResponsesImageAdmission;
+    validateSelection(admission: ResponsesImageAdmission, selection: ResponsesHostedToolSelection): void;
+    openRequest(input: ResponsesHostedImageOpenRequestInput): Promise<ResponsesImageRequestScope>;
+    release(): Promise<void>;
+}
+/** Dormant until an admitted Responses request explicitly acquires it. */
+interface ResponsesHostedImageRuntimeFactory {
+    acquire(): Promise<ResponsesHostedImageRuntimeLease>;
+}
+interface ResponsesHostedImagePrepareInput {
+    readonly body: Readonly<Record<string, unknown>>;
+    readonly profile: ResponsesProfile;
+    readonly operation: 'create' | 'compact';
+    readonly hostedImageGenerationAllowed: boolean;
+    readonly tenantId?: string;
+    readonly sessionKey: string;
+    readonly authorizedPreviousResponseId?: string;
+    readonly previousHostedImageState?: ResponsesAffinityHostedImageState;
+    readonly mainProviderId: string;
+    readonly signal: AbortSignal;
+}
+interface ResponsesHostedImageWrapInput {
+    readonly response: Response;
+    readonly rawStatus: number | null;
+    readonly selectedMainAccountId?: string;
+    readonly onTerminalSuccess: (responseId: string, state: ResponsesAffinityHostedImageState) => void | Promise<void>;
+}
+interface ResponsesHostedImageRequestLease {
+    readonly upstreamBody: Record<string, unknown>;
+    wrapUpstreamResponse(input: ResponsesHostedImageWrapInput): Promise<Response>;
+    dispose(): Promise<void>;
+}
+/** Deep Native Responses mediator; ingress owns only prepare/wrap/dispose composition. */
+interface ResponsesHostedImageIngress {
+    prepare(input: ResponsesHostedImagePrepareInput): Promise<ResponsesHostedImageRequestLease | null>;
+}
+
+/**
+ * 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
+ */
+
+/** Callback for retry events (client toast). */
+type RetryCallback = (info: {
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    statusCode: number;
+    error?: string;
+}) => void;
+/** Callback for real-time SSE streaming events (content_block_delta, content_block_start, etc.) */
+type StreamEventCallback = (event: Record<string, unknown>) => void;
+/**
+ * Routing attribution carried alongside usage records — `messageId` is per-request
+ * and unknown at this layer, so only the persistent `sessionId` + `apiKeyId` flow
+ * through.
+ */
+interface ProxyAttribution {
+    sessionId?: string | null;
+    apiKeyId?: string | null;
+    /** Token-free Route Lease attribution; never contains the bearer token. */
+    routeLease?: RouteLeaseUsageAttribution | null;
+}
+interface RouteLeaseUsageAttribution {
+    readonly leaseId: string;
+    readonly consumer: string;
+    readonly runId?: string;
+    readonly stageId?: string;
+}
+/**
+ * 1M-context opt-in for outbound Anthropic requests. Populated by
+ * the host's Claude-SDK engine from the active session's `cliBackend` /
+ * `useExtendedContext` schema fields. When `enabled` is true and `model`
+ * is in the 1M-capable allowlist, `injectExtendedContextBeta` adds
+ * `'context-1m-2025-08-07'` to the request's `anthropic-beta` header
+ * before transport.
+ */
+interface ExtendedContextHint {
+    enabled: boolean;
+    model: string;
+}
+/** 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;
+}
+/** The single-entry handler the Anthropic ingress drives per request. */
+interface AnthropicIngressHandler {
+    handle(req: http.IncomingMessage, res: http.ServerResponse): Promise<void>;
+}
+/**
+ * Per-run inputs the resident proxy threads into the ingress handler factory.
+ * Structural mirror of the host's `RouteHandlerParams` — kept here so the
+ * ingress + `ProviderProxyDeps` do not import upward. The host's
+ * `RouteHandlerParams` re-exports / aligns to this shape (so its
+ * request-handler factory is assignable to the factory type below).
+ */
+interface AnthropicRouteHandlerParams {
+    readonly llmConfig: ProviderConfigSource;
+    readonly providerId: string;
+    readonly model: string;
+    readonly apiKey: string;
+    readonly backgroundTaskModel?: string;
+    readonly isOfficialProvider: boolean;
+    readonly thinkingLevel?: ThinkLevel;
+    readonly extendedContext?: ExtendedContextHint | null;
+    readonly passThrough: boolean;
+    /** Upstream Bearer for the pass-through path (resident-proxy route token swap). */
+    readonly passThroughAuthToken?: string | null;
+    /** Lazy per-request resolver for the pass-through Bearer (takes precedence over the static one). */
+    readonly resolvePassThroughAuthToken?: (() => Promise<string | null>) | null;
+    readonly subscriptionProfile?: SubscriptionDispatchProfile | null;
+    /** Bound subscription account forwarded to the host's Anthropic handler. */
+    readonly preferredAccountId?: string;
+    readonly preferredAccountGroup?: string;
+    /** Strict by default; pool fallback is an explicit endpoint opt-in. */
+    readonly boundAccountFallbackPolicy?: BoundAccountFallbackPolicy;
+    /** Preferred provider-pool key selected by a resource-level binding. */
+    readonly preferredKeyId?: string;
+    /** Strict by default; pool fallback is an explicit binding opt-in. */
+    readonly boundKeyFallbackPolicy?: BoundAccountFallbackPolicy;
+    readonly maxConcurrency?: number;
+    /** Instance-level web-search backend; falls back to the proxy-global one. */
+    readonly webSearchService?: WebSearchBackend | null;
+    readonly onRetry?: RetryCallback;
+    readonly onStreamEvent?: StreamEventCallback;
+    readonly usageRecorder?: UsageRecorderImport | null;
+    readonly attribution?: ProxyAttribution | null;
+}
+/** Factory that builds a per-request Anthropic ingress handler. */
+type AnthropicIngressHandlerFactory = (params: AnthropicRouteHandlerParams) => AnthropicIngressHandler;
+/**
+ * Wire format the proxy ingests for a given route. Phase 1 landed the two
+ * already-sound parsers (`anthropic-messages`, `openai-responses`);
+ * `provider-proxy-transformer-matrix` adds `openai-chat` (qwen / copilot /
+ * opencode) and `gemini-generatecontent` (gemini-CLI api-key/relay) — completing
+ * the resident proxy's 4-ingress-parser matrix.
+ */
+type IngressFormat = 'anthropic-messages' | 'openai-responses' | 'openai-chat' | 'gemini-generatecontent';
+/**
+ * The target Provider's wire format. The proxy's internal pass-through-vs-
+ * transform decision is keyed on `(ingressFormat, targetProviderFormat)`:
+ * when they MATCH the request is passed through + re-authed; otherwise it is
+ * transformed through the Unified chain (design D3).
+ *
+ * NOTE: `'anthropic'` here is the FORMAT family, not a provider id. An official
+ * or third-party Anthropic Messages provider is `'anthropic'`; an
+ * OpenAI-compatible / Responses provider is `'openai-responses'`.
+ */
+type TargetProviderFormat = 'anthropic' | 'openai-responses' | 'transform';
+/**
+ * How the proxy re-authenticates a route upstream. `'byo'` resolves the key
+ * from an LLM-config provider row (with optional `ApiKeyPool` failover);
+ * `'subscription'` re-auths via a subscription `AuthStrategy` (OAuth bearer +
+ * 401 refresh). The forwarded route-token sentinel is ALWAYS discarded — the
+ * proxy never trusts the CLI/SDK-carried key.
+ */
+type RouteAuthMode = 'byo' | 'subscription';
+/**
+ * The Anthropic SDK-hint bundle carried on a `RouteContext` for routes whose
+ * ingress is `'anthropic-messages'`. The Anthropic path is NOT re-implemented
+ * inside the resident proxy — it is DELEGATED wholesale to the host's existing
+ * per-request proxy handler (engine-provider-decouple task 2.10, "delegate for
+ * parity"). That handler keeps owning its own upstream fetch + all the SDK
+ * quirks (probe-mock, local web-search interception, thinkingLevel / 1M-context
+ * beta injection, subscription dispatch, and the 5h/7d window header taps) — so
+ * everything the host proxy used to receive per session is threaded here per
+ * run and fed straight into the per-request handler factory.
+ *
+ * D7 conversion-SSOT is ALREADY MET: the delegated host handler runs
+ * its Anthropic⇄Unified⇄provider conversion through the SAME shared pipeline
+ * SSOT (`executeProviderCall` + `AnthropicTransformer`) that the Responses /
+ * OpenAI-Chat / Gemini ingresses use — there is no second conversion stack. The
+ * SDK quirks listed above (probe / web-search / thinking / window-tap) are
+ * INGRESS concerns and deliberately stay at the ingress under the design's
+ * ingress-vs-core split; they are NOT folded into the shared core.
+ */
+interface AnthropicSdkHints {
+    /** Real provider key (resolved at run start) for `getProviderHeaders`. */
+    readonly apiKey: string;
+    /** Official-Anthropic provider → skip probe caching + transformer pipeline. */
+    readonly isOfficialProvider: boolean;
+    /** claude-code OAuth pass-through (forward to api.anthropic.com verbatim). */
+    readonly passThrough: boolean;
+    /**
+     * Host-managed OAuth Bearer token for the pass-through path. With the
+     * resident proxy the SDK forwards the route TOKEN as its `Authorization`
+     * header (used only for route lookup, then discarded), so the real upstream
+     * Bearer can no longer ride the SDK header — it is carried here and
+     * re-applied by the pass-through forwarder. `null`/absent → fall back to the
+     * SDK's own forwarded credential (system `~/.claude/.credentials.json`).
+     */
+    readonly passThroughAuthToken?: string | null;
+    /**
+     * OPTIONAL lazy resolver for the pass-through upstream Bearer, evaluated at
+     * REQUEST time rather than route-build time. When present it takes precedence
+     * over the static `passThroughAuthToken`, so a long-lived route always forwards
+     * a freshly auto-refreshed token (the host re-reads its OAuth store / system
+     * credentials per request) instead of the one captured when the route was
+     * built — that capture is what makes a session outlive its token and 401
+     * mid-run. Returns `null` (or throws) to fall back to the static token.
+     */
+    readonly resolvePassThroughAuthToken?: (() => Promise<string | null>) | null;
+    /** User thinking-budget preference (Anthropic-direct + reasoning chain). */
+    readonly thinkingLevel?: ThinkLevel;
+    /** 1M-context opt-in (injects `context-1m-2025-08-07` into anthropic_beta). */
+    readonly extendedContext?: ExtendedContextHint | null;
+    /** Subscription dispatch profile (Codex/Gemini/OpenCodeGo over the SDK wire). */
+    readonly subscriptionProfile?: SubscriptionDispatchProfile | null;
+    /** Bound subscription account for the delegated Anthropic path. */
+    readonly preferredAccountId?: string;
+    readonly preferredAccountGroup?: string;
+    /** Strict by default; pool fallback is an explicit endpoint opt-in. */
+    readonly boundAccountFallbackPolicy?: BoundAccountFallbackPolicy;
+    /** Preferred provider-pool key for a delegated BYO Anthropic route. */
+    readonly preferredKeyId?: string;
+    /** Strict by default; pool fallback is an explicit binding opt-in. */
+    readonly boundKeyFallbackPolicy?: BoundAccountFallbackPolicy;
+    /** Per-request max-concurrency cap for the error-handler semaphore. */
+    readonly maxConcurrency?: number;
+    /** Instance-level web-search backend (falls back to the proxy-global one). */
+    readonly webSearchService?: WebSearchBackend | null;
+    /** Retry-event callback (client toast). */
+    readonly onRetry?: RetryCallback;
+    /** Real-time SSE event callback (client live-display). */
+    readonly onStreamEvent?: StreamEventCallback;
+    /** Usage attribution (sessionId + apiKeyId) for recorded usage rows. */
+    readonly attribution?: ProxyAttribution | null;
+    /**
+     * The usage recorder (`UsageRecorderImport` port) for the delegated
+     * stream-manager taps (stream + non-stream + 5h/7d window). Per-run
+     * because `buildProviderEnvWithProxy` resolves it from the explicit arg ??
+     * the module-level recorder, exactly as the host proxy received it. The
+     * host injects its concrete usage-recorder service, which satisfies the port.
+     */
+    readonly usageRecorder?: UsageRecorderImport | null;
+}
+/**
+ * Per-run routing context, looked up by the crypto route token carried in the
+ * forwarded `Authorization` sentinel. Shaped to exactly what the pipeline call
+ * (`executeProviderCall` + the `endpointTransformer` seam) needs to re-auth and
+ * route a single run's traffic. There is NO fallback: a token miss or an
+ * expired entry is rejected (design D9).
+ */
+interface RouteContext {
+    /** Owning chat session id — usage attribution + ApiKeyPool affinity. */
+    readonly sessionId: string | null;
+    /**
+     * Target Provider's wire format. Drives the internal pass-through-vs-transform
+     * decision against the route's `ingressFormat`.
+     */
+    readonly targetProviderFormat: TargetProviderFormat;
+    /** Resolved provider model the upstream request targets. */
+    readonly model: string;
+    /**
+     * The client's ORIGINAL requested model id, for RESPONSE `model` passthrough
+     * on the kind-mapped outbound endpoints (`messages`/`responses`). Stamped ONLY
+     * by the outbound `resolveRoute` for those endpoints; the resident-proxy route
+     * minting path leaves it `undefined`, so internal completions are never
+     * rewritten (the two kind-mapped ingresses pass it as `relayResponse`'s
+     * `rewriteModel` — undefined ⇒ byte-identical passthrough).
+     */
+    readonly requestedModel?: string;
+    /**
+     * The outbound named-key id (`verified.id`) this request authenticated with,
+     * for usage attribution (the ByApiKey view). Stamped ONLY by the outbound
+     * `resolveRoute`; the resident-proxy route-minting path leaves it `undefined`,
+     * so internal completions record `apiKeyId: null` (the taps read
+     * `route.apiKeyId ?? null`), exactly as before.
+     */
+    readonly apiKeyId?: string;
+    /** Explicit hosted-image authority projected from the verified `images` permission. */
+    readonly hostedImageGenerationAllowed?: boolean;
+    /**
+     * Per-request, one-way audit seam supplied by the outbound router. Hosted
+     * image admission invokes it before any mediated response bytes are relayed.
+     */
+    readonly suppressAuditBodies?: () => void;
+    /** Safe process-local lease attribution. The route token is intentionally absent. */
+    readonly routeLease?: RouteLeaseUsageAttribution;
+    /** Wire format this route's ingress decodes. */
+    readonly ingressFormat: IngressFormat;
+    /** Re-auth mode (BYO key vs subscription OAuth). */
+    readonly authMode: RouteAuthMode;
+    /**
+     * LLM-config provider row id whose key/headers authenticate a BYO call.
+     * Required for `authMode === 'byo'`; ignored for subscription routes.
+     */
+    readonly providerId?: string;
+    /**
+     * Background-task model (the SDK's haiku probes map to this). Optional —
+     * falls back to `model` when omitted. Anthropic ingress quirk only.
+     */
+    readonly backgroundTaskModel?: string;
+    /**
+     * Pre-built `AuthSource` for this route, when the caller resolved it at run
+     * start (subscription routes supply this). When omitted for BYO routes the
+     * proxy builds an `LlmConfigProviderAuth` from `providerId` at request time.
+     */
+    readonly auth?: AuthSource;
+    /**
+     * Subscription profile (structural `SubscriptionAuthProfile` subset — the
+     * registry's full `SubscriptionDispatchProfile` satisfies it). REQUIRED when
+     * `authMode === 'subscription'`. The route resolver populates it for BOTH the
+     * OpenAI-Responses ingress and the built-in (factory-absent) Anthropic
+     * `/v1/messages` ingress (RT2.1). The Responses ingress consumes only
+     * `authStrategy` / `resolveUpstreamUrl` / `providerTransformerNames`; the
+     * built-in messages subscription path additionally reads the OPTIONAL `mode`
+     * + `modelMapper` fields (present on the registry profile passed here). The
+     * factory-present Anthropic delegation carries its OWN profile inside
+     * `anthropicSdkHints.subscriptionProfile` and ignores this field.
+     */
+    readonly subscriptionProfile?: SubscriptionAuthProfile | null;
+    /**
+     * Per-request preferred subscription account id (provider/subscription
+     * duality). Stamped by the outbound `resolveRoute` from
+     * `EndpointRoutingConfig.boundAccountId`; strict bindings fail when this
+     * account cannot serve. The pool is used only when the route carries the
+     * explicit `'pool'` fallback policy. Undefined ⇒ pool auto-schedule.
+     */
+    readonly preferredAccountId?: string;
+    /** Account-group binding projected by the outbound gateway. */
+    readonly preferredAccountGroup?: string;
+    /** Bound-account behavior; `'pool'` is the explicit fallback opt-in. */
+    readonly boundAccountFallbackPolicy?: BoundAccountFallbackPolicy;
+    /** Optional provider key selected by a resource-level gateway binding. */
+    readonly preferredKeyId?: string;
+    /** Strict by default; `'pool'` permits normal provider key selection. */
+    readonly boundKeyFallbackPolicy?: BoundAccountFallbackPolicy;
+    /**
+     * OPAQUE per-account subscription config (opencodego-only). Populated by the
+     * route resolver from the subscription registry's `getOpenCodeGoConfig()`
+     * getter; passed BACK INTO the profile closures (`modelMapper` /
+     * `nextFallback` / `resolveUpstreamUrl`) by the built-in (factory-absent)
+     * `/v1/messages` plan builder so user `baseUrl` / `modelMap` / `fallbacks`
+     * overrides apply on that path.
+     *
+     * Typed `unknown` ON PURPOSE: core MUST NOT name the concrete
+     * `OpenCodeGoTokenConfig` type from `@omnicross/subscriptions` (cross-layer
+     * litmus = 0). The plan builder narrows it to the contract type
+     * (`@omnicross/contracts`) at the single profile-call boundary.
+     *
+     * INERT when an Anthropic ingress factory is injected (the built-in plan
+     * builder is then unreachable) and for non-opencodego routes (claude /
+     * codex / gemini leave it `undefined`).
+     */
+    readonly subscriptionConfig?: unknown;
+    /**
+     * The Anthropic SDK-hint bundle. REQUIRED when
+     * `ingressFormat === 'anthropic-messages'` (the resident proxy delegates that
+     * ingress to the host's existing per-request handler, which needs the full bundle).
+     * Ignored for the OpenAI Responses ingress.
+     */
+    readonly anthropicSdkHints?: AnthropicSdkHints | null;
+    /**
+     * count_tokens strategy for `/v1/messages/count_tokens` requests
+     * (claude-api-routing-errors, widened in claude-api-protocol-fidelity).
+     * Absent ⇒ `'auto'`: Anthropic-wire upstream → passthrough, translation
+     * upstream → estimate. Stamped onto the minted route by the outbound router
+     * for count_tokens requests only; resident direct traffic stays `'auto'`.
+     */
+    readonly anthropicCountTokensMode?: 'auto' | 'passthrough' | 'estimate' | 'reject';
+    /**
+     * Wall-clock budget (ms) for the local count_tokens estimate walk
+     * (`anthropic.countTokens.estimateBudgetMs`, §10). Absent ⇒ the estimator's
+     * 2000ms default.
+     */
+    readonly anthropicCountTokensEstimateBudgetMs?: number;
+    /**
+     * Budget (ms) for the translate-path PDF text extraction
+     * (`anthropic.pdfTextExtraction.budgetMs`, claude-api-transform-fidelity).
+     * Absent ⇒ the extractor's 2000ms default. Applies to GENERATION translate
+     * routes (documents in message content), stamped by the outbound router for
+     * Anthropic-protocol requests; resident direct traffic uses the default.
+     */
+    readonly anthropicPdfTextExtractionBudgetMs?: number;
+}
+/**
+ * App-session-scoped dependencies the resident proxy needs to service ALL
+ * routes. Unlike the per-run proxies these are wired ONCE at startup; per-run
+ * state lives in the route map.
+ */
+interface ProviderProxyDeps {
+    readonly llmConfig: ProviderConfigSource;
+    /**
+     * Trusted handlers for OpenAI resource operations not owned by the built-in
+     * create ingresses. Optional so existing embedders stay source-compatible.
+     */
+    readonly openAIOperationRegistry?: OpenAIOperationRegistry | null;
+    /** Optional Native Responses hosted-image mediator composed by the daemon. */
+    readonly responsesHostedImageIngress?: ResponsesHostedImageIngress | null;
+    /**
+     * Session-affine key selection + 429/529/401/403 failover. Centralized here
+     * (task 2.8) so the next-batch cutover removes the per-proxy taps. Optional —
+     * BYO single-key routes work without it.
+     */
+    readonly apiKeyPool?: ApiKeyPoolService | null;
+    /**
+     * The single usage tap (task 2.8). When set, both ingress relays
+     * record their non-stream usage through it. Optional.
+     */
+    readonly usageRecorder?: UsageRecorderImport | null;
+    /**
+     * Factory for the per-request Anthropic `/v1/messages` ingress handler
+     * (E1 de-inversion). The ingress builds its delegated request handler
+     * through THIS injected factory instead of importing the host's factory
+     * directly. Bootstrap supplies the host implementation.
+     *
+     * Optional so unit-test constructors that never drive the Anthropic ingress
+     * (env-wiring smoke, pool failover, etc.) compile unchanged; when a route
+     * with `ingressFormat: 'anthropic-messages'` IS served without it wired, the
+     * ingress responds 502 (the factory is a hard dependency of THAT path only).
+     */
+    readonly anthropicIngressHandlerFactory?: AnthropicIngressHandlerFactory | null;
+}
+/**
+ * Structural port for the usage recorder — only the `record` method.
+ *
+ * Kept structural so the serving core does not depend on the host's concrete
+ * usage-recorder class. The host injects that concrete service at
+ * bootstrap; it satisfies this port. Both the proxy taps (narrow literal-null
+ * payloads) and the CompletionService / TransformerHandler completion path
+ * (rich payloads with `messageId` / `apiKeyId` / `'completion'` origin) call
+ * through this single `record()`, so the accepted input is the full structural
+ * mirror of the host's `UsageRecordInput`.
+ */
+interface UsageRecorderImport {
+    record(input: UsageRecordImportInput): void;
+}
+/**
+ * The usage payload accepted by the recorder port — structural mirror of the
+ * host's `UsageRecordInput` (type-only; no host import). Covers both the proxy
+ * taps and the completion path.
+ */
+interface UsageRecordImportInput {
+    messageId?: string | null;
+    parentMessageId?: string | null;
+    sessionId?: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId?: string | null;
+    engineOrigin: UsageEngineOrigin;
+    usage: UsageTokens;
+    rawUsage?: unknown;
+    runId?: string | null;
+    /** Token-free managed-route attribution. */
+    routeLeaseId?: string | null;
+    routeLeaseConsumer?: string | null;
+    routeLeaseStageId?: string | null;
+    eventId?: string | null;
+    /** Safe prompt-cache-key provenance; raw key material is never recorded. */
+    cacheKeySource?: UsageCacheKeySource;
+    /** Whether the gateway, rather than the client, attached the cache key. */
+    cacheKeyInjected?: boolean;
+    /**
+     * OPTIONAL per-request audit correlation key (request-audit-log) — the outbound
+     * relay taps set this to the request's `http.ServerResponse` so the recorder can
+     * stash this request's tokens/cost for the audit capture. Opaque; unset ⇒ no-op.
+     */
+    auditResponse?: object;
+}
+
+export { ResponsesAffinityStore as $, type AnthropicIngressHandler as A, InMemoryResponsesImageStateStore as B, type InMemoryResponsesImageStateStoreOptions as C, type IngressFormat as D, type ExtendedContextHint as E, type OpenAIOperationBodyKind as F, type OpenAIOperationDispatchContext as G, OpenAIOperationError as H, type ImageAsset as I, type OpenAIOperationErrorInit as J, type OpenAIOperationHandler as K, type OpenAIOperationHandlerContext as L, type OpenAIOperationId as M, type OpenAIOperationOwner as N, type OpenAIOperation as O, OpenAIOperationRegistrationError as P, type OpenAIOperationRegistrationErrorCode as Q, OpenAIOperationRegistry as R, type OpenAIPolicyFamily as S, type OpenAIRequestedModelSource as T, type UsageRecorderImport as U, type OpenAIRouteFamily as V, type ProviderProxyDeps as W, type ProxyAttribution as X, type ResponsesAffinityEntry as Y, type ResponsesAffinityRecord as Z, type ResponsesAffinityScope as _, type AnthropicIngressHandlerFactory as a, type ResponsesAffinityStoreOptions as a0, type ResponsesCredentialIdentity as a1, type ResponsesHostedImageIngress as a2, type ResponsesHostedImageRequestLease as a3, type ResponsesHostedImageRuntimeFactory as a4, type ResponsesHostedImageRuntimeLease as a5, type ResponsesHostedToolIdentity as a6, type ResponsesHostedToolSelection as a7, type ResponsesImageAction as a8, type ResponsesImageAdmission as a9, type ResponsesSelectedImageCall as aA, type RetryCallback as aB, type RouteAuthMode as aC, type RouteContext as aD, type RouteLeaseUsageAttribution as aE, type StreamEventCallback as aF, type SubscriptionDispatchProfile as aG, type SubscriptionRequestSummary as aH, type TargetProviderFormat as aI, classifyOpenAIOperation as aJ, classifyResponsesProfile as aK, emitImageTelemetry as aL, getOpenAIOperation as aM, getResponsesAffinityStore as aN, previousResponseNotFound as aO, readImageAssetBytes as aP, unsupportedOpenAIOperation as aQ, writeOpenAIOperationError as aR, type UsageRecordImportInput as aS, type ResponsesImageCallBinding as aa, type ResponsesImageCallId as ab, type ResponsesImageCallResolution as ac, type ResponsesImageCallStateLease as ad, type ResponsesImageCompletedRecord as ae, type ResponsesImageEventAllocator as af, type ResponsesImageExecutionEvent as ag, type ResponsesImageFailedRecord as ah, type ResponsesImageGenerationCallItem as ai, type ResponsesImageGenerationCallStartedItem as aj, type ResponsesImageGenerationContribution as ak, type ResponsesImageGenerationContributionDeps as al, type ResponsesImageInspectionInput as am, type ResponsesImageNormalizedOptions as an, type ResponsesImagePartialEvent as ao, type ResponsesImageRequestScope as ap, type ResponsesImageRequestScopeInput as aq, type ResponsesImageResponseResolution as ar, type ResponsesImageResponseStateLease as as, type ResponsesImageSelectionPolicy as at, type ResponsesImageStartedRecord as au, type ResponsesImageStateCommitInput as av, type ResponsesImageStateStore as aw, type ResponsesImageTrustedRuntime as ax, type ResponsesProfile as ay, type ResponsesProfileDeclaration as az, type AnthropicRouteHandlerParams as b, type AnthropicSdkHints as c, type ExtensionOpenAIOperationId as d, type ImageJob as e, type ImageJobObservability as f, type ImageJobObservabilitySnapshot as g, ImageOrchestrator as h, type ImageOrchestratorOptions as i, type ImageOrchestratorRunOptions as j, type ImageProvider as k, type ImageProviderContext as l, type ImageProviderLease as m, ImageProviderRegistry as n, type ImageProviderRequest as o, type ImageReferenceLease as p, type ImageReferenceResolution as q, type ImageReferenceSaveInput as r, type ImageReferenceStore as s, type ImageReferenceValue as t, type ImageRetentionPolicy as u, type ImageTelemetryOutputMetadata as v, type ImageTelemetryRecord as w, type ImageTelemetrySink as x, InMemoryImageAsset as y, InMemoryImageReferenceStore as z };