@omnicross/core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE +57 -0
  3. package/README.md +15 -0
  4. package/dist/ApiKeyPoolService-BmMkau07.d.cts +170 -0
  5. package/dist/ApiKeyPoolService-BmMkau07.d.ts +170 -0
  6. package/dist/ProviderProxy-f_8ziIhW.d.cts +120 -0
  7. package/dist/ProviderProxy-vjt8sQQk.d.ts +120 -0
  8. package/dist/SubscriptionAuthSource-Cr4fVEYY.d.cts +264 -0
  9. package/dist/SubscriptionAuthSource-D89zmiSS.d.ts +264 -0
  10. package/dist/auth/GeminiCodeAssistProjectResolver.cjs +218 -0
  11. package/dist/auth/GeminiCodeAssistProjectResolver.d.cts +68 -0
  12. package/dist/auth/GeminiCodeAssistProjectResolver.d.ts +68 -0
  13. package/dist/auth/GeminiCodeAssistProjectResolver.js +189 -0
  14. package/dist/completion/ApiKeyPoolService.cjs +331 -0
  15. package/dist/completion/ApiKeyPoolService.d.cts +2 -0
  16. package/dist/completion/ApiKeyPoolService.d.ts +2 -0
  17. package/dist/completion/ApiKeyPoolService.js +306 -0
  18. package/dist/completion.cjs +4027 -0
  19. package/dist/completion.d.cts +17 -0
  20. package/dist/completion.d.ts +17 -0
  21. package/dist/completion.js +3983 -0
  22. package/dist/index-BTSmc9Sm.d.ts +645 -0
  23. package/dist/index-DXazdTzZ.d.cts +645 -0
  24. package/dist/index.cjs +10428 -0
  25. package/dist/index.d.cts +128 -0
  26. package/dist/index.d.ts +128 -0
  27. package/dist/index.js +10339 -0
  28. package/dist/outbound-api/subscriptionRegistryPort.cjs +38 -0
  29. package/dist/outbound-api/subscriptionRegistryPort.d.cts +73 -0
  30. package/dist/outbound-api/subscriptionRegistryPort.d.ts +73 -0
  31. package/dist/outbound-api/subscriptionRegistryPort.js +12 -0
  32. package/dist/outbound-api.cjs +5264 -0
  33. package/dist/outbound-api.d.cts +320 -0
  34. package/dist/outbound-api.d.ts +320 -0
  35. package/dist/outbound-api.js +5218 -0
  36. package/dist/pipeline/SubscriptionAuthSource.cjs +131 -0
  37. package/dist/pipeline/SubscriptionAuthSource.d.cts +3 -0
  38. package/dist/pipeline/SubscriptionAuthSource.d.ts +3 -0
  39. package/dist/pipeline/SubscriptionAuthSource.js +103 -0
  40. package/dist/pipeline/SubscriptionAuthStrategy.cjs +18 -0
  41. package/dist/pipeline/SubscriptionAuthStrategy.d.cts +61 -0
  42. package/dist/pipeline/SubscriptionAuthStrategy.d.ts +61 -0
  43. package/dist/pipeline/SubscriptionAuthStrategy.js +0 -0
  44. package/dist/ports/gemini-code-assist-resolver.cjs +38 -0
  45. package/dist/ports/gemini-code-assist-resolver.d.cts +26 -0
  46. package/dist/ports/gemini-code-assist-resolver.d.ts +26 -0
  47. package/dist/ports/gemini-code-assist-resolver.js +12 -0
  48. package/dist/ports.cjs +18 -0
  49. package/dist/ports.d.cts +15 -0
  50. package/dist/ports.d.ts +15 -0
  51. package/dist/ports.js +0 -0
  52. package/dist/provider-proxy/ingress/providerProxyShared.cjs +2958 -0
  53. package/dist/provider-proxy/ingress/providerProxyShared.d.cts +77 -0
  54. package/dist/provider-proxy/ingress/providerProxyShared.d.ts +77 -0
  55. package/dist/provider-proxy/ingress/providerProxyShared.js +2925 -0
  56. package/dist/provider-proxy/matchText.cjs +73 -0
  57. package/dist/provider-proxy/matchText.d.cts +47 -0
  58. package/dist/provider-proxy/matchText.d.ts +47 -0
  59. package/dist/provider-proxy/matchText.js +45 -0
  60. package/dist/provider-proxy/types.cjs +18 -0
  61. package/dist/provider-proxy/types.d.cts +12 -0
  62. package/dist/provider-proxy/types.d.ts +12 -0
  63. package/dist/provider-proxy/types.js +0 -0
  64. package/dist/provider-proxy.cjs +4667 -0
  65. package/dist/provider-proxy.d.cts +69 -0
  66. package/dist/provider-proxy.d.ts +69 -0
  67. package/dist/provider-proxy.js +4636 -0
  68. package/dist/serializeError.cjs +82 -0
  69. package/dist/serializeError.d.cts +24 -0
  70. package/dist/serializeError.d.ts +24 -0
  71. package/dist/serializeError.js +57 -0
  72. package/dist/sse-parser.cjs +456 -0
  73. package/dist/sse-parser.d.cts +143 -0
  74. package/dist/sse-parser.d.ts +143 -0
  75. package/dist/sse-parser.js +430 -0
  76. package/dist/transformer/TransformerChainExecutor.cjs +321 -0
  77. package/dist/transformer/TransformerChainExecutor.d.cts +104 -0
  78. package/dist/transformer/TransformerChainExecutor.d.ts +104 -0
  79. package/dist/transformer/TransformerChainExecutor.js +294 -0
  80. package/dist/transformer/TransformerService.cjs +290 -0
  81. package/dist/transformer/TransformerService.d.cts +138 -0
  82. package/dist/transformer/TransformerService.d.ts +138 -0
  83. package/dist/transformer/TransformerService.js +265 -0
  84. package/dist/transformer/transformers/GeminiCodeAssistTransformer.cjs +1115 -0
  85. package/dist/transformer/transformers/GeminiCodeAssistTransformer.d.cts +102 -0
  86. package/dist/transformer/transformers/GeminiCodeAssistTransformer.d.ts +102 -0
  87. package/dist/transformer/transformers/GeminiCodeAssistTransformer.js +1085 -0
  88. package/dist/transformer/transformers/GeminiTransformer.cjs +1013 -0
  89. package/dist/transformer/transformers/GeminiTransformer.d.cts +70 -0
  90. package/dist/transformer/transformers/GeminiTransformer.d.ts +70 -0
  91. package/dist/transformer/transformers/GeminiTransformer.js +986 -0
  92. package/dist/transformer/transformers/OpenAIResponseTransformer.cjs +538 -0
  93. package/dist/transformer/transformers/OpenAIResponseTransformer.d.cts +53 -0
  94. package/dist/transformer/transformers/OpenAIResponseTransformer.d.ts +53 -0
  95. package/dist/transformer/transformers/OpenAIResponseTransformer.js +513 -0
  96. package/dist/transformer/transformers/OpenCodeGoTransformer.cjs +73 -0
  97. package/dist/transformer/transformers/OpenCodeGoTransformer.d.cts +51 -0
  98. package/dist/transformer/transformers/OpenCodeGoTransformer.d.ts +51 -0
  99. package/dist/transformer/transformers/OpenCodeGoTransformer.js +48 -0
  100. package/dist/transformer/types.cjs +18 -0
  101. package/dist/transformer/types.d.cts +405 -0
  102. package/dist/transformer/types.d.ts +405 -0
  103. package/dist/transformer/types.js +0 -0
  104. package/dist/transformer.cjs +3736 -0
  105. package/dist/transformer.d.cts +33 -0
  106. package/dist/transformer.d.ts +33 -0
  107. package/dist/transformer.js +3712 -0
  108. package/dist/types-CGGrKqC_.d.cts +142 -0
  109. package/dist/types-CbCN2NQP.d.ts +142 -0
  110. package/dist/types-DCzHkhJt.d.ts +467 -0
  111. package/dist/types-DZIQbgp0.d.cts +467 -0
  112. package/dist/usage-event-sink-BX7FE1NL.d.cts +59 -0
  113. package/dist/usage-event-sink-BX7FE1NL.d.ts +59 -0
  114. package/package.json +62 -0
@@ -0,0 +1,467 @@
1
+ import http from 'node:http';
2
+ import { ThinkLevel } from '@omnicross/contracts/completion-types';
3
+ import { SubscriptionProviderId, OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
4
+ import { UsageEngineOrigin, UsageTokens } from '@omnicross/contracts/usage-types';
5
+ import { A as ApiKeyPoolService } from './ApiKeyPoolService-BmMkau07.js';
6
+ import { A as AuthSource, S as SubscriptionAuthProfile } from './SubscriptionAuthSource-D89zmiSS.js';
7
+ import { AuthStrategy } from './pipeline/SubscriptionAuthStrategy.js';
8
+ import { LLMProvider, AgentDefaultModels, GlobalModelParameters } from '@omnicross/contracts/llm-config';
9
+ import { ResolvedTransformerChain, Transformer } from './transformer/types.js';
10
+ import { TransformerService } from './transformer/TransformerService.js';
11
+ import { WebSearchProviderId, WebSearchOptions, WebSearchResponse, JinaReaderResponse } from '@omnicross/contracts/websearch-types';
12
+
13
+ /**
14
+ * `ProviderConfigSource` — core-owned port for the provider catalog + routing +
15
+ * transformer-chain reads the serving core needs from its host config service.
16
+ *
17
+ * The serving core (`pipeline` / `transformer` / `provider-proxy` /
18
+ * `completion` / `outbound-api`) MUST depend on THIS interface, never on the
19
+ * host's concrete config-service class as a type. The host supplies the impl
20
+ * at bootstrap (its config service implementing `ProviderConfigSource` is the
21
+ * compile-time assignability guard).
22
+ *
23
+ * The surface is sized to EXACTLY the ten methods the core invokes today —
24
+ * signatures copied verbatim from the host's config service so the host stays
25
+ * structurally assignable with zero behavior change.
26
+ *
27
+ * NOTE (Phase-1 narrowing, omnicross): `getTransformerService()` is a
28
+ * transformer-registry accessor that returns a CORE class (`TransformerService`,
29
+ * not a host class), so exposing it through this port is sound for 0b. It is a
30
+ * separate concern from provider-catalog reads, however; splitting it into its
31
+ * own narrower port is deferred to Phase 1 (see design Q1). Do NOT split now.
32
+ *
33
+ * @module ports/provider-config-source
34
+ */
35
+
36
+ interface ProviderConfigSource {
37
+ getProvider(id: string): Promise<LLMProvider | null>;
38
+ /** @deprecated mirror of the host method — router-based routing is a no-op today. */
39
+ resolveRoutedModel(providerId: string, modelId: string): Promise<{
40
+ isRouted: boolean;
41
+ actualProviderId: string;
42
+ actualModelId: string;
43
+ routerId?: string;
44
+ routerName?: string;
45
+ } | null>;
46
+ resolveEffectiveModels(): Promise<{
47
+ background?: string;
48
+ vision?: string;
49
+ }>;
50
+ getAgentDefaultModels(): Promise<AgentDefaultModels>;
51
+ hasVisionCapability(providerId: string, modelId: string): Promise<boolean>;
52
+ getGlobalModelParameters(): Promise<GlobalModelParameters>;
53
+ getDiscoveredModelMaxTokens(providerId: string, modelId: string): Promise<number | undefined>;
54
+ resolveTransformerChain(providerId: string, model?: string): Promise<ResolvedTransformerChain>;
55
+ getMainTransformer(providerId: string): Promise<Transformer | null>;
56
+ getTransformerService(): TransformerService | undefined;
57
+ }
58
+
59
+ /**
60
+ * `WebSearchBackend` — core-owned port for the web-search service the serving
61
+ * core's built-in `web_search` tool executor and the Anthropic proxy hints use.
62
+ *
63
+ * The serving core MUST depend on THIS interface, never on the concrete host
64
+ * `WebSearchService` class as a type. The host already exposes a superset of
65
+ * this surface, so it is passed directly with NO adapter.
66
+ *
67
+ * The surface is EXACTLY the three methods the core invokes
68
+ * (`search`/`isProviderEnabled`/`readUrl`), signatures matching
69
+ * `WebSearchService`. The argument/return types are `@omnicross/contracts`
70
+ * contract types (not host classes), so they cross into a Phase-1 package cleanly.
71
+ *
72
+ * @module ports/web-search-backend
73
+ */
74
+
75
+ interface WebSearchBackend {
76
+ search(query: string, providerId: WebSearchProviderId, options?: WebSearchOptions): Promise<WebSearchResponse>;
77
+ isProviderEnabled(id: WebSearchProviderId): boolean;
78
+ readUrl(url: string, options?: {
79
+ timeout?: number;
80
+ signal?: AbortSignal;
81
+ apiKey?: string;
82
+ }): Promise<JinaReaderResponse>;
83
+ }
84
+
85
+ /**
86
+ * Shared contract types for the resident `ProviderProxy`.
87
+ *
88
+ * The `ProviderProxy` (OpenSpec `engine-provider-decouple`, design D0/D3/D7/D9)
89
+ * is the single resident `127.0.0.1` listener that subsumes both of the
90
+ * host's per-session proxies (Anthropic Messages ingress and OpenAI Responses
91
+ * ingress). Per-run state lives in a `Map<token, RouteContext>`
92
+ * minted at run start and reaped at run end / on idle TTL.
93
+ *
94
+ * These types are kept in their own module so the server, route map, router,
95
+ * and the two ingress parsers can share shapes without importing one another
96
+ * for type-only purposes.
97
+ *
98
+ * @module provider-proxy/types
99
+ */
100
+
101
+ /** Callback for retry events (client toast). */
102
+ type RetryCallback = (info: {
103
+ attempt: number;
104
+ maxAttempts: number;
105
+ delayMs: number;
106
+ statusCode: number;
107
+ error?: string;
108
+ }) => void;
109
+ /** Callback for real-time SSE streaming events (content_block_delta, content_block_start, etc.) */
110
+ type StreamEventCallback = (event: Record<string, unknown>) => void;
111
+ /**
112
+ * Routing attribution carried alongside usage records — `messageId` is per-request
113
+ * and unknown at this layer, so only the persistent `sessionId` + `apiKeyId` flow
114
+ * through.
115
+ */
116
+ interface ProxyAttribution {
117
+ sessionId?: string | null;
118
+ apiKeyId?: string | null;
119
+ }
120
+ /**
121
+ * 1M-context opt-in for outbound Anthropic requests. Populated by
122
+ * the host's Claude-SDK engine from the active session's `cliBackend` /
123
+ * `useExtendedContext` schema fields. When `enabled` is true and `model`
124
+ * is in the 1M-capable allowlist, `injectExtendedContextBeta` adds
125
+ * `'context-1m-2025-08-07'` to the request's `anthropic-beta` header
126
+ * before transport.
127
+ */
128
+ interface ExtendedContextHint {
129
+ enabled: boolean;
130
+ model: string;
131
+ }
132
+ /** Lightweight summary derived from the inbound Anthropic request body —
133
+ * consumed by `modelMapper` (scenario routing) without full body access. */
134
+ interface SubscriptionRequestSummary {
135
+ messageCount: number;
136
+ /** cl100k_base-estimated token count of system + messages (no tools). */
137
+ estimatedInputTokens: number;
138
+ /**
139
+ * OPTIONAL bounded per-message text slice (system prompt + the most recent
140
+ * user/system messages, each per-message-capped) consumed ONLY by the
141
+ * OpenCodeGo keyword matcher in `@omnicross/subscriptions`
142
+ * (`resolveOpenCodeGoScenario`). Core only WRITES this `string[]`; it never
143
+ * reads it and never names the matcher — keeping the cross-layer litmus at 0
144
+ * (no `@omnicross/core` → `@omnicross/subscriptions` edge). Optional so callers
145
+ * that omit it (legacy/tests) compile and degrade to the token-threshold +
146
+ * `default` routing.
147
+ */
148
+ matchText?: string[];
149
+ }
150
+ interface SubscriptionDispatchProfile {
151
+ readonly providerId: SubscriptionProviderId;
152
+ readonly displayName: string;
153
+ readonly authStrategy: AuthStrategy;
154
+ /** Pass-through providers (Claude) skip the transformer chain entirely.
155
+ * Transformer providers use the chain below + the proxy's existing
156
+ * `AnthropicTransformer` endpoint reverse-decoder. */
157
+ readonly mode: 'pass-through' | 'transformer';
158
+ /** Resolve the upstream URL for a given resolved model id. Required for
159
+ * `mode === 'transformer'`; unused for pass-through (proxy hard-codes
160
+ * `api.anthropic.com`). The OPTIONAL 2nd `config` arg lets the opencodego
161
+ * profile honor a per-account `baseUrl` override (D1) — additive, so existing
162
+ * one-arg callers compile unchanged. */
163
+ readonly resolveUpstreamUrl?: (resolvedModel: string, config?: OpenCodeGoTokenConfig) => string;
164
+ /** Names of transformers (registered in `TransformerService`) to run on the
165
+ * provider chain. The proxy adds `AnthropicTransformer` as the endpoint
166
+ * reverse-decoder. */
167
+ readonly providerTransformerNames?: readonly string[];
168
+ readonly modelTransformerNames?: readonly string[];
169
+ /**
170
+ * OPTIONAL shape-aware provider transformer-name resolver (opencodego zen).
171
+ * Parallel to `resolveUpstreamUrl(model, config)`: lets a profile vary its
172
+ * provider chain by the RESOLVED model's wire shape (e.g. zen `responses` ⇒
173
+ * `['openai-response']`, `gemini` ⇒ `['gemini']`). `config` is `unknown` on the
174
+ * core side (opaque-config discipline — core never names
175
+ * `OpenCodeGoTokenConfig` from `@omnicross/subscriptions`); the subscriptions
176
+ * implementation narrows it. When ABSENT, both ingress paths fall back to the
177
+ * static `providerTransformerNames` — BYTE-IDENTICAL for claude / codex / gemini
178
+ * (which leave this unset). Purely additive (optional).
179
+ */
180
+ readonly resolveProviderTransformerNames?: (model: string, config?: unknown) => readonly string[];
181
+ /** Optional model placeholder rewriter — only set for OpenCodeGo. */
182
+ readonly modelMapper?: (sdkModel: string, summary: SubscriptionRequestSummary, config: OpenCodeGoTokenConfig | undefined) => {
183
+ resolvedModel: string;
184
+ scenario: OpenCodeGoScenario;
185
+ };
186
+ /** Optional fallback resolver — for OpenCodeGo, picks the next model after
187
+ * an unrecoverable error. Returns `null` when exhausted. Cap = 3. The
188
+ * opencodego implementation ALSO consults the circuit breaker (D5): it skips
189
+ * models whose circuit is open. */
190
+ readonly nextFallback?: (scenario: OpenCodeGoScenario, attempted: readonly string[], config: OpenCodeGoTokenConfig | undefined) => OpenCodeGoModelEntry | null;
191
+ /** Optional circuit-breaker admission gate for the PRIMARY (mapped) model
192
+ * (D5 primary-gating). Only set for OpenCodeGo. Returns whether `modelId`'s
193
+ * circuit currently admits a request (side-effecting: flips an `open` model
194
+ * to `half-open` once its window elapses, exactly like `nextFallback`'s
195
+ * internal consult). `nextFallback` covers the FALLBACKS; this covers the
196
+ * primary the loop already holds. Absent/undefined ⇒ the loop treats the
197
+ * primary as always admitted (claude / codex / gemini have no breaker). */
198
+ readonly allowModel?: (modelId: string) => boolean;
199
+ /** Optional record-outcome callback (D5 record seam). Only set for OpenCodeGo.
200
+ * Both fallback loops invoke it after each attempt: `ok: true` on a `2xx`,
201
+ * `ok: false` on a thrown/network error / `5xx` / `429`; a non-429 `4xx` is
202
+ * NEUTRAL and the loops MUST NOT call it. Drives the per-model breaker.
203
+ * Absent/undefined for claude / codex / gemini ⇒ a no-op (no breaker). */
204
+ readonly recordModelOutcome?: (modelId: string, ok: boolean) => void;
205
+ }
206
+ /** The single-entry handler the Anthropic ingress drives per request. */
207
+ interface AnthropicIngressHandler {
208
+ handle(req: http.IncomingMessage, res: http.ServerResponse): Promise<void>;
209
+ }
210
+ /**
211
+ * Per-run inputs the resident proxy threads into the ingress handler factory.
212
+ * Structural mirror of the host's `RouteHandlerParams` — kept here so the
213
+ * ingress + `ProviderProxyDeps` do not import upward. The host's
214
+ * `RouteHandlerParams` re-exports / aligns to this shape (so its
215
+ * request-handler factory is assignable to the factory type below).
216
+ */
217
+ interface AnthropicRouteHandlerParams {
218
+ readonly llmConfig: ProviderConfigSource;
219
+ readonly providerId: string;
220
+ readonly model: string;
221
+ readonly apiKey: string;
222
+ readonly backgroundTaskModel?: string;
223
+ readonly isOfficialProvider: boolean;
224
+ readonly thinkingLevel?: ThinkLevel;
225
+ readonly extendedContext?: ExtendedContextHint | null;
226
+ readonly passThrough: boolean;
227
+ /** Upstream Bearer for the pass-through path (resident-proxy route token swap). */
228
+ readonly passThroughAuthToken?: string | null;
229
+ readonly subscriptionProfile?: SubscriptionDispatchProfile | null;
230
+ readonly maxConcurrency?: number;
231
+ /** Instance-level web-search backend; falls back to the proxy-global one. */
232
+ readonly webSearchService?: WebSearchBackend | null;
233
+ readonly onRetry?: RetryCallback;
234
+ readonly onStreamEvent?: StreamEventCallback;
235
+ readonly usageRecorder?: UsageRecorderImport | null;
236
+ readonly attribution?: ProxyAttribution | null;
237
+ }
238
+ /** Factory that builds a per-request Anthropic ingress handler. */
239
+ type AnthropicIngressHandlerFactory = (params: AnthropicRouteHandlerParams) => AnthropicIngressHandler;
240
+ /**
241
+ * Wire format the proxy ingests for a given route. Phase 1 landed the two
242
+ * already-sound parsers (`anthropic-messages`, `openai-responses`);
243
+ * `provider-proxy-transformer-matrix` adds `openai-chat` (qwen / copilot /
244
+ * opencode) and `gemini-generatecontent` (gemini-CLI api-key/relay) — completing
245
+ * the resident proxy's 4-ingress-parser matrix.
246
+ */
247
+ type IngressFormat = 'anthropic-messages' | 'openai-responses' | 'openai-chat' | 'gemini-generatecontent';
248
+ /**
249
+ * The target Provider's wire format. The proxy's internal pass-through-vs-
250
+ * transform decision is keyed on `(ingressFormat, targetProviderFormat)`:
251
+ * when they MATCH the request is passed through + re-authed; otherwise it is
252
+ * transformed through the Unified chain (design D3).
253
+ *
254
+ * NOTE: `'anthropic'` here is the FORMAT family, not a provider id. An official
255
+ * or third-party Anthropic Messages provider is `'anthropic'`; an
256
+ * OpenAI-compatible / Responses provider is `'openai-responses'`.
257
+ */
258
+ type TargetProviderFormat = 'anthropic' | 'openai-responses' | 'transform';
259
+ /**
260
+ * How the proxy re-authenticates a route upstream. `'byo'` resolves the key
261
+ * from an LLM-config provider row (with optional `ApiKeyPool` failover);
262
+ * `'subscription'` re-auths via a subscription `AuthStrategy` (OAuth bearer +
263
+ * 401 refresh). The forwarded route-token sentinel is ALWAYS discarded — the
264
+ * proxy never trusts the CLI/SDK-carried key.
265
+ */
266
+ type RouteAuthMode = 'byo' | 'subscription';
267
+ /**
268
+ * The Anthropic SDK-hint bundle carried on a `RouteContext` for routes whose
269
+ * ingress is `'anthropic-messages'`. The Anthropic path is NOT re-implemented
270
+ * inside the resident proxy — it is DELEGATED wholesale to the host's existing
271
+ * per-request proxy handler (engine-provider-decouple task 2.10, "delegate for
272
+ * parity"). That handler keeps owning its own upstream fetch + all the SDK
273
+ * quirks (probe-mock, local web-search interception, thinkingLevel / 1M-context
274
+ * beta injection, subscription dispatch, and the 5h/7d window header taps) — so
275
+ * everything the host proxy used to receive per session is threaded here per
276
+ * run and fed straight into the per-request handler factory.
277
+ *
278
+ * D7 conversion-SSOT is ALREADY MET: the delegated host handler runs
279
+ * its Anthropic⇄Unified⇄provider conversion through the SAME shared pipeline
280
+ * SSOT (`executeProviderCall` + `AnthropicTransformer`) that the Responses /
281
+ * OpenAI-Chat / Gemini ingresses use — there is no second conversion stack. The
282
+ * SDK quirks listed above (probe / web-search / thinking / window-tap) are
283
+ * INGRESS concerns and deliberately stay at the ingress under the design's
284
+ * ingress-vs-core split; they are NOT folded into the shared core.
285
+ */
286
+ interface AnthropicSdkHints {
287
+ /** Real provider key (resolved at run start) for `getProviderHeaders`. */
288
+ readonly apiKey: string;
289
+ /** Official-Anthropic provider → skip probe caching + transformer pipeline. */
290
+ readonly isOfficialProvider: boolean;
291
+ /** claude-code OAuth pass-through (forward to api.anthropic.com verbatim). */
292
+ readonly passThrough: boolean;
293
+ /**
294
+ * Host-managed OAuth Bearer token for the pass-through path. With the
295
+ * resident proxy the SDK forwards the route TOKEN as its `Authorization`
296
+ * header (used only for route lookup, then discarded), so the real upstream
297
+ * Bearer can no longer ride the SDK header — it is carried here and
298
+ * re-applied by the pass-through forwarder. `null`/absent → fall back to the
299
+ * SDK's own forwarded credential (system `~/.claude/.credentials.json`).
300
+ */
301
+ readonly passThroughAuthToken?: string | null;
302
+ /** User thinking-budget preference (Anthropic-direct + reasoning chain). */
303
+ readonly thinkingLevel?: ThinkLevel;
304
+ /** 1M-context opt-in (injects `context-1m-2025-08-07` into anthropic_beta). */
305
+ readonly extendedContext?: ExtendedContextHint | null;
306
+ /** Subscription dispatch profile (Codex/Gemini/OpenCodeGo over the SDK wire). */
307
+ readonly subscriptionProfile?: SubscriptionDispatchProfile | null;
308
+ /** Per-request max-concurrency cap for the error-handler semaphore. */
309
+ readonly maxConcurrency?: number;
310
+ /** Instance-level web-search backend (falls back to the proxy-global one). */
311
+ readonly webSearchService?: WebSearchBackend | null;
312
+ /** Retry-event callback (client toast). */
313
+ readonly onRetry?: RetryCallback;
314
+ /** Real-time SSE event callback (client live-display). */
315
+ readonly onStreamEvent?: StreamEventCallback;
316
+ /** Usage attribution (sessionId + apiKeyId) for recorded usage rows. */
317
+ readonly attribution?: ProxyAttribution | null;
318
+ /**
319
+ * The usage recorder (`UsageRecorderImport` port) for the delegated
320
+ * stream-manager taps (stream + non-stream + 5h/7d window). Per-run
321
+ * because `buildProviderEnvWithProxy` resolves it from the explicit arg ??
322
+ * the module-level recorder, exactly as the host proxy received it. The
323
+ * host injects its concrete usage-recorder service, which satisfies the port.
324
+ */
325
+ readonly usageRecorder?: UsageRecorderImport | null;
326
+ }
327
+ /**
328
+ * Per-run routing context, looked up by the crypto route token carried in the
329
+ * forwarded `Authorization` sentinel. Shaped to exactly what the pipeline call
330
+ * (`executeProviderCall` + the `endpointTransformer` seam) needs to re-auth and
331
+ * route a single run's traffic. There is NO fallback: a token miss or an
332
+ * expired entry is rejected (design D9).
333
+ */
334
+ interface RouteContext {
335
+ /** Owning chat session id — usage attribution + ApiKeyPool affinity. */
336
+ readonly sessionId: string | null;
337
+ /**
338
+ * Target Provider's wire format. Drives the internal pass-through-vs-transform
339
+ * decision against the route's `ingressFormat`.
340
+ */
341
+ readonly targetProviderFormat: TargetProviderFormat;
342
+ /** Resolved provider model the upstream request targets. */
343
+ readonly model: string;
344
+ /** Wire format this route's ingress decodes. */
345
+ readonly ingressFormat: IngressFormat;
346
+ /** Re-auth mode (BYO key vs subscription OAuth). */
347
+ readonly authMode: RouteAuthMode;
348
+ /**
349
+ * LLM-config provider row id whose key/headers authenticate a BYO call.
350
+ * Required for `authMode === 'byo'`; ignored for subscription routes.
351
+ */
352
+ readonly providerId?: string;
353
+ /**
354
+ * Background-task model (the SDK's haiku probes map to this). Optional —
355
+ * falls back to `model` when omitted. Anthropic ingress quirk only.
356
+ */
357
+ readonly backgroundTaskModel?: string;
358
+ /**
359
+ * Pre-built `AuthSource` for this route, when the caller resolved it at run
360
+ * start (subscription routes supply this). When omitted for BYO routes the
361
+ * proxy builds an `LlmConfigProviderAuth` from `providerId` at request time.
362
+ */
363
+ readonly auth?: AuthSource;
364
+ /**
365
+ * Subscription profile (structural `SubscriptionAuthProfile` subset — the
366
+ * registry's full `SubscriptionDispatchProfile` satisfies it). REQUIRED when
367
+ * `authMode === 'subscription'`. The route resolver populates it for BOTH the
368
+ * OpenAI-Responses ingress and the built-in (factory-absent) Anthropic
369
+ * `/v1/messages` ingress (RT2.1). The Responses ingress consumes only
370
+ * `authStrategy` / `resolveUpstreamUrl` / `providerTransformerNames`; the
371
+ * built-in messages subscription path additionally reads the OPTIONAL `mode`
372
+ * + `modelMapper` fields (present on the registry profile passed here). The
373
+ * factory-present Anthropic delegation carries its OWN profile inside
374
+ * `anthropicSdkHints.subscriptionProfile` and ignores this field.
375
+ */
376
+ readonly subscriptionProfile?: SubscriptionAuthProfile | null;
377
+ /**
378
+ * OPAQUE per-account subscription config (opencodego-only). Populated by the
379
+ * route resolver from the subscription registry's `getOpenCodeGoConfig()`
380
+ * getter; passed BACK INTO the profile closures (`modelMapper` /
381
+ * `nextFallback` / `resolveUpstreamUrl`) by the built-in (factory-absent)
382
+ * `/v1/messages` plan builder so user `baseUrl` / `modelMap` / `fallbacks`
383
+ * overrides apply on that path.
384
+ *
385
+ * Typed `unknown` ON PURPOSE: core MUST NOT name the concrete
386
+ * `OpenCodeGoTokenConfig` type from `@omnicross/subscriptions` (cross-layer
387
+ * litmus = 0). The plan builder narrows it to the contract type
388
+ * (`@omnicross/contracts`) at the single profile-call boundary.
389
+ *
390
+ * INERT when an Anthropic ingress factory is injected (the built-in plan
391
+ * builder is then unreachable) and for non-opencodego routes (claude /
392
+ * codex / gemini leave it `undefined`).
393
+ */
394
+ readonly subscriptionConfig?: unknown;
395
+ /**
396
+ * The Anthropic SDK-hint bundle. REQUIRED when
397
+ * `ingressFormat === 'anthropic-messages'` (the resident proxy delegates that
398
+ * ingress to the host's existing per-request handler, which needs the full bundle).
399
+ * Ignored for the OpenAI Responses ingress.
400
+ */
401
+ readonly anthropicSdkHints?: AnthropicSdkHints | null;
402
+ }
403
+ /**
404
+ * App-session-scoped dependencies the resident proxy needs to service ALL
405
+ * routes. Unlike the per-run proxies these are wired ONCE at startup; per-run
406
+ * state lives in the route map.
407
+ */
408
+ interface ProviderProxyDeps {
409
+ readonly llmConfig: ProviderConfigSource;
410
+ /**
411
+ * Session-affine key selection + 429/529/401/403 failover. Centralized here
412
+ * (task 2.8) so the next-batch cutover removes the per-proxy taps. Optional —
413
+ * BYO single-key routes work without it.
414
+ */
415
+ readonly apiKeyPool?: ApiKeyPoolService | null;
416
+ /**
417
+ * The single usage tap (task 2.8). When set, both ingress relays
418
+ * record their non-stream usage through it. Optional.
419
+ */
420
+ readonly usageRecorder?: UsageRecorderImport | null;
421
+ /**
422
+ * Factory for the per-request Anthropic `/v1/messages` ingress handler
423
+ * (E1 de-inversion). The ingress builds its delegated request handler
424
+ * through THIS injected factory instead of importing the host's factory
425
+ * directly. Bootstrap supplies the host implementation.
426
+ *
427
+ * Optional so unit-test constructors that never drive the Anthropic ingress
428
+ * (env-wiring smoke, pool failover, etc.) compile unchanged; when a route
429
+ * with `ingressFormat: 'anthropic-messages'` IS served without it wired, the
430
+ * ingress responds 502 (the factory is a hard dependency of THAT path only).
431
+ */
432
+ readonly anthropicIngressHandlerFactory?: AnthropicIngressHandlerFactory | null;
433
+ }
434
+ /**
435
+ * Structural port for the usage recorder — only the `record` method.
436
+ *
437
+ * Kept structural so the serving core does not depend on the host's concrete
438
+ * usage-recorder class. The host injects that concrete service at
439
+ * bootstrap; it satisfies this port. Both the proxy taps (narrow literal-null
440
+ * payloads) and the CompletionService / TransformerHandler completion path
441
+ * (rich payloads with `messageId` / `apiKeyId` / `'completion'` origin) call
442
+ * through this single `record()`, so the accepted input is the full structural
443
+ * mirror of the host's `UsageRecordInput`.
444
+ */
445
+ interface UsageRecorderImport {
446
+ record(input: UsageRecordImportInput): void;
447
+ }
448
+ /**
449
+ * The usage payload accepted by the recorder port — structural mirror of the
450
+ * host's `UsageRecordInput` (type-only; no host import). Covers both the proxy
451
+ * taps and the completion path.
452
+ */
453
+ interface UsageRecordImportInput {
454
+ messageId?: string | null;
455
+ parentMessageId?: string | null;
456
+ sessionId?: string | null;
457
+ providerId: string;
458
+ model: string;
459
+ apiKeyId?: string | null;
460
+ engineOrigin: UsageEngineOrigin;
461
+ usage: UsageTokens;
462
+ rawUsage?: unknown;
463
+ runId?: string | null;
464
+ eventId?: string | null;
465
+ }
466
+
467
+ export type { AnthropicIngressHandler as A, ExtendedContextHint as E, IngressFormat as I, ProviderConfigSource as P, RetryCallback as R, SubscriptionDispatchProfile as S, TargetProviderFormat as T, UsageRecorderImport as U, WebSearchBackend as W, ProviderProxyDeps as a, AnthropicIngressHandlerFactory as b, AnthropicRouteHandlerParams as c, AnthropicSdkHints as d, ProxyAttribution as e, RouteAuthMode as f, RouteContext as g, StreamEventCallback as h, SubscriptionRequestSummary as i, UsageRecordImportInput as j };