@omnicross/core 0.1.0 → 0.1.1

package/dist/outbound-api.d.cts

@@ -1,17 +1,21 @@
-import { E as EndpointRoutingConfig, a as OutboundApiDeps, e as OutboundApiServerStatus, g as OutboundFormatUrls, d as OutboundApiServerConfig, O as OutboundKeyDb, b as OutboundApiKeyCreated, R as RequestRole, f as OutboundEndpoint } from './types-CGGrKqC_.cjs';
-export { c as OutboundApiKeyInfo, h as OutboundKeyDbRow } from './types-CGGrKqC_.cjs';
-import { I as IngressFormat, P as ProviderConfigSource, g as RouteContext } from './types-DZIQbgp0.cjs';
-import { SubscriptionProviderId } from '@omnicross/contracts/subscription-types';
-import './ProviderProxy-f_8ziIhW.cjs';
+import { EndpointRoutingConfig, OutboundApiDeps, OutboundApiServerStatus, OutboundFormatUrls, OutboundApiServerConfig, OutboundKeyDb, OutboundApiKeyCreated, RequestRole } from './outbound-api/types.cjs';
+export { OutboundApiKeyInfo, OutboundEndpoint, OutboundKeyDbRow } from './outbound-api/types.cjs';
+import { IngressFormat } from './provider-proxy/types.cjs';
+export { S as SUBSCRIPTION_PROVIDER_IDS, e as endpointSupportsSubscription, i as isSubscriptionProviderId, r as resolveRoute } from './routeResolver-BrbK6ja9.cjs';
+import './ports/provider-config-source.cjs';
+import '@omnicross/contracts/llm-config';
+import './transformer/types.cjs';
+import './transformer/TransformerService.cjs';
+import './ProviderProxy-CnMQYN59.cjs';
 import 'node:http';
 import '@omnicross/contracts/completion-types';
+import '@omnicross/contracts/subscription-types';
 import '@omnicross/contracts/usage-types';
 import './ApiKeyPoolService-BmMkau07.cjs';
-import '@omnicross/contracts/llm-config';
-import './SubscriptionAuthSource-Cr4fVEYY.cjs';
+import './pipeline/AuthSource.cjs';
+import './pipeline/SubscriptionAuthSource.cjs';
 import './pipeline/SubscriptionAuthStrategy.cjs';
-import './transformer/types.cjs';
-import './transformer/TransformerService.cjs';
+import './ports/web-search-backend.cjs';
 import '@omnicross/contracts/websearch-types';
 
 /**
@@ -218,83 +222,6 @@ declare function detectRequestRole(ingressFormat: IngressFormat, body: Record<st
 /** Map a settings endpoint id to the provider-proxy ingress format. */
 declare function endpointToIngressFormat(endpoint: 'chat' | 'responses' | 'messages' | 'gemini'): IngressFormat;
 
-/**
- * subscriptionSupport — single source of truth for (a) which provider ids are
- * subscription-backed and (b) which outbound endpoints can soundly serve a
- * subscription route (`outbound-api-server`, design D2 + review M1/m1).
- *
- * The subscription-id catalog mirrors `SubscriptionProviderRegistry`'s ids; the
- * static fast-path is backstopped at runtime by a live registry lookup (see
- * `isSubscriptionProviderId`) so it degrades gracefully if it drifts. Both
- * `routeResolver` and `apiServerHandlers` import from here — no duplicated set.
- *
- * @module outbound-api/subscriptionSupport
- */
-
-/**
- * The registry-aligned subscription provider ids — the outbound layer's SSOT
- * fast-path. NOTE: `SubscriptionProviderId` is currently a `z.string()` alias,
- * so this `readonly SubscriptionProviderId[]` typing does NOT compile-enforce
- * alignment with the registry; drift is instead tolerated at runtime by
- * `isSubscriptionProviderId`'s live `registry.getProfile` fallback.
- */
-declare const SUBSCRIPTION_PROVIDER_IDS: readonly SubscriptionProviderId[];
-/**
- * True when a provider id refers to a subscription-backed provider. Checks the
- * registry-aligned static catalog first, then falls back to a live registry
- * lookup (so a registry addition is honored even before this list is updated).
- *
- * NOTE (review m2): this classifies by id string. The resolver MUST confirm the
- * id does not resolve to a real BYO provider row before treating it as
- * subscription-backed — see `routeResolver` (BYO rows win).
- */
-declare function isSubscriptionProviderId(providerId: string): boolean;
-/** True when the endpoint's ingress can soundly serve a subscription route. */
-declare function endpointSupportsSubscription(endpoint: OutboundEndpoint): boolean;
-
-/**
- * routeResolver — turn an endpoint's `EndpointRoutingConfig` + the detected
- * request role into a `RouteContext` for the shared `provider-proxy` dispatch
- * (`outbound-api-server`, design D2).
- *
- * Steps:
- *  1. Pick the model for the role (vision → default fallback when `visionModel`
- *     is unset; vision is optional).
- *  2. Parse the chosen `"providerId,modelId"` ref.
- *  3. Gate by `useSubscription`: OFF → only BYO-key providers are eligible
- *     (subscription-backed providers excluded); ON → subscription-backed
- *     providers are eligible.
- *  4. Resolve the provider (BYO via the `ProviderConfigSource`; subscription via the
- *     subscription registry) and build the `RouteContext` exactly as the
- *     internal callers do.
- *  5. Return a clear `503`-style error when the role's required model is unset,
- *     the provider is unavailable, or the subscription gate excludes it.
- *
- * @module outbound-api/routeResolver
- */
-
-/** A 503-style resolution failure. */
-interface RouteResolveError {
-    status: number;
-    message: string;
-}
-type RouteResolveResult = {
-    ok: true;
-    route: RouteContext;
-    usedRole: RequestRole;
-} | {
-    ok: false;
-    error: RouteResolveError;
-};
-/** Resolve a route for one authenticated outbound request. */
-declare function resolveRoute(args: {
-    config: EndpointRoutingConfig;
-    role: RequestRole;
-    ingressFormat: IngressFormat;
-    llmConfig: ProviderConfigSource;
-    sessionId?: string | null;
-}): Promise<RouteResolveResult>;
-
 /**
  * Outbound API server module — barrel + singleton accessor.
  *
@@ -317,4 +244,4 @@ declare function getOutboundApiServer(deps?: OutboundApiDeps, onPortChange?: (po
 /** Reset the singleton (tests / teardown only). */
 declare function __resetOutboundApiServerForTests(): void;
 
-export { type ApiServerSettingsStore, type ApplyConfigInput, DEFAULT_OUTBOUND_PORT, EndpointRoutingConfig, OUTBOUND_API_SERVER_CONFIG_KEY, OutboundApiDeps, OutboundApiKeyCreated, OutboundApiServer, OutboundApiServerConfig, OutboundApiServerStatus, OutboundEndpoint, OutboundFormatUrls, OutboundKeyDb, OutboundRateLimiter, RequestRole, SUBSCRIPTION_PROVIDER_IDS, __resetOutboundApiServerForTests, createNamedKey, defaultServerConfig, detectRequestRole, endpointSupportsSubscription, endpointToIngressFormat, formatUrls, getOutboundApiServer, hashKey, isSubscriptionProviderId, loadServerConfig, mergeServerConfig, normalizeServerConfig, resolveRoute, saveServerConfig, verifyPresentedKey };
+export { type ApiServerSettingsStore, type ApplyConfigInput, DEFAULT_OUTBOUND_PORT, EndpointRoutingConfig, OUTBOUND_API_SERVER_CONFIG_KEY, OutboundApiDeps, OutboundApiKeyCreated, OutboundApiServer, OutboundApiServerConfig, OutboundApiServerStatus, OutboundFormatUrls, OutboundKeyDb, OutboundRateLimiter, RequestRole, __resetOutboundApiServerForTests, createNamedKey, defaultServerConfig, detectRequestRole, endpointToIngressFormat, formatUrls, getOutboundApiServer, hashKey, loadServerConfig, mergeServerConfig, normalizeServerConfig, saveServerConfig, verifyPresentedKey };

package/dist/outbound-api.d.ts

@@ -1,17 +1,21 @@
-import { E as EndpointRoutingConfig, a as OutboundApiDeps, e as OutboundApiServerStatus, g as OutboundFormatUrls, d as OutboundApiServerConfig, O as OutboundKeyDb, b as OutboundApiKeyCreated, R as RequestRole, f as OutboundEndpoint } from './types-CbCN2NQP.js';
-export { c as OutboundApiKeyInfo, h as OutboundKeyDbRow } from './types-CbCN2NQP.js';
-import { I as IngressFormat, P as ProviderConfigSource, g as RouteContext } from './types-DCzHkhJt.js';
-import { SubscriptionProviderId } from '@omnicross/contracts/subscription-types';
-import './ProviderProxy-vjt8sQQk.js';
+import { EndpointRoutingConfig, OutboundApiDeps, OutboundApiServerStatus, OutboundFormatUrls, OutboundApiServerConfig, OutboundKeyDb, OutboundApiKeyCreated, RequestRole } from './outbound-api/types.js';
+export { OutboundApiKeyInfo, OutboundEndpoint, OutboundKeyDbRow } from './outbound-api/types.js';
+import { IngressFormat } from './provider-proxy/types.js';
+export { S as SUBSCRIPTION_PROVIDER_IDS, e as endpointSupportsSubscription, i as isSubscriptionProviderId, r as resolveRoute } from './routeResolver-HE-ZO0fO.js';
+import './ports/provider-config-source.js';
+import '@omnicross/contracts/llm-config';
+import './transformer/types.js';
+import './transformer/TransformerService.js';
+import './ProviderProxy-C-xqrkKi.js';
 import 'node:http';
 import '@omnicross/contracts/completion-types';
+import '@omnicross/contracts/subscription-types';
 import '@omnicross/contracts/usage-types';
 import './ApiKeyPoolService-BmMkau07.js';
-import '@omnicross/contracts/llm-config';
-import './SubscriptionAuthSource-D89zmiSS.js';
+import './pipeline/AuthSource.js';
+import './pipeline/SubscriptionAuthSource.js';
 import './pipeline/SubscriptionAuthStrategy.js';
-import './transformer/types.js';
-import './transformer/TransformerService.js';
+import './ports/web-search-backend.js';
 import '@omnicross/contracts/websearch-types';
 
 /**
@@ -218,83 +222,6 @@ declare function detectRequestRole(ingressFormat: IngressFormat, body: Record<st
 /** Map a settings endpoint id to the provider-proxy ingress format. */
 declare function endpointToIngressFormat(endpoint: 'chat' | 'responses' | 'messages' | 'gemini'): IngressFormat;
 
-/**
- * subscriptionSupport — single source of truth for (a) which provider ids are
- * subscription-backed and (b) which outbound endpoints can soundly serve a
- * subscription route (`outbound-api-server`, design D2 + review M1/m1).
- *
- * The subscription-id catalog mirrors `SubscriptionProviderRegistry`'s ids; the
- * static fast-path is backstopped at runtime by a live registry lookup (see
- * `isSubscriptionProviderId`) so it degrades gracefully if it drifts. Both
- * `routeResolver` and `apiServerHandlers` import from here — no duplicated set.
- *
- * @module outbound-api/subscriptionSupport
- */
-
-/**
- * The registry-aligned subscription provider ids — the outbound layer's SSOT
- * fast-path. NOTE: `SubscriptionProviderId` is currently a `z.string()` alias,
- * so this `readonly SubscriptionProviderId[]` typing does NOT compile-enforce
- * alignment with the registry; drift is instead tolerated at runtime by
- * `isSubscriptionProviderId`'s live `registry.getProfile` fallback.
- */
-declare const SUBSCRIPTION_PROVIDER_IDS: readonly SubscriptionProviderId[];
-/**
- * True when a provider id refers to a subscription-backed provider. Checks the
- * registry-aligned static catalog first, then falls back to a live registry
- * lookup (so a registry addition is honored even before this list is updated).
- *
- * NOTE (review m2): this classifies by id string. The resolver MUST confirm the
- * id does not resolve to a real BYO provider row before treating it as
- * subscription-backed — see `routeResolver` (BYO rows win).
- */
-declare function isSubscriptionProviderId(providerId: string): boolean;
-/** True when the endpoint's ingress can soundly serve a subscription route. */
-declare function endpointSupportsSubscription(endpoint: OutboundEndpoint): boolean;
-
-/**
- * routeResolver — turn an endpoint's `EndpointRoutingConfig` + the detected
- * request role into a `RouteContext` for the shared `provider-proxy` dispatch
- * (`outbound-api-server`, design D2).
- *
- * Steps:
- *  1. Pick the model for the role (vision → default fallback when `visionModel`
- *     is unset; vision is optional).
- *  2. Parse the chosen `"providerId,modelId"` ref.
- *  3. Gate by `useSubscription`: OFF → only BYO-key providers are eligible
- *     (subscription-backed providers excluded); ON → subscription-backed
- *     providers are eligible.
- *  4. Resolve the provider (BYO via the `ProviderConfigSource`; subscription via the
- *     subscription registry) and build the `RouteContext` exactly as the
- *     internal callers do.
- *  5. Return a clear `503`-style error when the role's required model is unset,
- *     the provider is unavailable, or the subscription gate excludes it.
- *
- * @module outbound-api/routeResolver
- */
-
-/** A 503-style resolution failure. */
-interface RouteResolveError {
-    status: number;
-    message: string;
-}
-type RouteResolveResult = {
-    ok: true;
-    route: RouteContext;
-    usedRole: RequestRole;
-} | {
-    ok: false;
-    error: RouteResolveError;
-};
-/** Resolve a route for one authenticated outbound request. */
-declare function resolveRoute(args: {
-    config: EndpointRoutingConfig;
-    role: RequestRole;
-    ingressFormat: IngressFormat;
-    llmConfig: ProviderConfigSource;
-    sessionId?: string | null;
-}): Promise<RouteResolveResult>;
-
 /**
  * Outbound API server module — barrel + singleton accessor.
  *
@@ -317,4 +244,4 @@ declare function getOutboundApiServer(deps?: OutboundApiDeps, onPortChange?: (po
 /** Reset the singleton (tests / teardown only). */
 declare function __resetOutboundApiServerForTests(): void;
 
-export { type ApiServerSettingsStore, type ApplyConfigInput, DEFAULT_OUTBOUND_PORT, EndpointRoutingConfig, OUTBOUND_API_SERVER_CONFIG_KEY, OutboundApiDeps, OutboundApiKeyCreated, OutboundApiServer, OutboundApiServerConfig, OutboundApiServerStatus, OutboundEndpoint, OutboundFormatUrls, OutboundKeyDb, OutboundRateLimiter, RequestRole, SUBSCRIPTION_PROVIDER_IDS, __resetOutboundApiServerForTests, createNamedKey, defaultServerConfig, detectRequestRole, endpointSupportsSubscription, endpointToIngressFormat, formatUrls, getOutboundApiServer, hashKey, isSubscriptionProviderId, loadServerConfig, mergeServerConfig, normalizeServerConfig, resolveRoute, saveServerConfig, verifyPresentedKey };
+export { type ApiServerSettingsStore, type ApplyConfigInput, DEFAULT_OUTBOUND_PORT, EndpointRoutingConfig, OUTBOUND_API_SERVER_CONFIG_KEY, OutboundApiDeps, OutboundApiKeyCreated, OutboundApiServer, OutboundApiServerConfig, OutboundApiServerStatus, OutboundFormatUrls, OutboundKeyDb, OutboundRateLimiter, RequestRole, __resetOutboundApiServerForTests, createNamedKey, defaultServerConfig, detectRequestRole, endpointToIngressFormat, formatUrls, getOutboundApiServer, hashKey, loadServerConfig, mergeServerConfig, normalizeServerConfig, saveServerConfig, verifyPresentedKey };

package/dist/outbound-api.js

@@ -3791,6 +3791,7 @@ async function handleAnthropicMessagesRequest(req, res, route, deps) {
     extendedContext: hints.extendedContext ?? null,
     passThrough: hints.passThrough,
     passThroughAuthToken: hints.passThroughAuthToken ?? null,
+    resolvePassThroughAuthToken: hints.resolvePassThroughAuthToken ?? null,
     subscriptionProfile: hints.subscriptionProfile ?? null,
     maxConcurrency: hints.maxConcurrency,
     webSearchService: hints.webSearchService ?? null,

package/dist/pipeline/AuthSource.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/pipeline/AuthSource.ts
+var AuthSource_exports = {};
+module.exports = __toCommonJS(AuthSource_exports);

package/dist/pipeline/AuthSource.d.cts

@@ -0,0 +1,101 @@
+/**
+ * AuthSource — unified outbound-authentication strategy for the provider
+ * request pipeline.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3).
+ *
+ * The three consumer paths (the wire-format proxy handler, the host engine
+ * adapter, TransformerHandler) each authenticate differently:
+ *
+ *   - provider-key (+ ApiKeyPool failover)  — LLM-config provider rows
+ *   - subscription `AuthStrategy` (+ 401 refresh + fallback) — code-cli OAuth
+ *   - OAuth pass-through                     — SDK forwards its own Bearer
+ *
+ * `AuthSource` is the single contract that unifies these. THIS PHASE ONLY
+ * DEFINES the interface and provides three behavior-preserving WRAPPERS
+ * (`LlmConfigProviderAuth`, `SubscriptionAuthSource`, `OAuthPassThroughAuth`)
+ * around the existing logic. NO caller is routed through it yet — the core
+ * (`executeProviderCall`) is NOT changed to consume `ctx.auth`, and
+ * the host handler's branch structure is UNCHANGED. Wiring (and
+ * the `onResult` pool-rotation integration) is Phase 3.
+ *
+ * @module pipeline/AuthSource
+ */
+/**
+ * Hints an `AuthSource` may need to vary header formatting per request.
+ *
+ * Mirrors the subscription-side `AuthApplyHints` (which uses optional
+ * `upstreamUrl` / `resolvedModel`) but with REQUIRED fields, since the
+ * pipeline always knows both at the point it applies headers. Adapters that
+ * wrap the looser subscription shape map these across at the boundary.
+ */
+interface AuthApplyHints {
+    /** Resolved upstream URL the request will be sent to. */
+    upstreamUrl: string;
+    /** Resolved model id for the request. */
+    model: string;
+}
+/**
+ * Result of {@link AuthSource.onResult}.
+ *
+ * `rebound` is `true` when the auth source rotated to a different credential
+ * (e.g. ApiKeyPool re-bound the session to a new key after a 429). `newKey`
+ * carries the freshly-resolved key string when a rotation produced one, so a
+ * caller MAY retry the same call once with it. Mirrors the
+ * `{ newKey | null }` contract of `ApiKeyPoolService.reportError` lifted into
+ * a structured shape.
+ */
+interface AuthResultOutcome {
+    /** Whether the credential was rotated/re-bound as a result of this status. */
+    rebound: boolean;
+    /** The new resolved key when a rotation produced one; omitted otherwise. */
+    newKey?: string;
+}
+/**
+ * A pluggable outbound-authentication source for one provider request.
+ *
+ * Implementations OWN exactly the auth concern: which headers carry the
+ * credential, how to recover from a 401, where the request should be sent
+ * (when the credential dictates the endpoint), and how to react to a final
+ * HTTP status (pool rotation / refresh). The pipeline core composes the rest.
+ */
+interface AuthSource {
+    /**
+     * Inject the authentication headers for this request, mutating `headers`
+     * in place. Implementations MAY refresh expiring tokens here.
+     *
+     * NOTE (Phase 2 boundary, see report): exactly WHAT this owns vs what the
+     * ingress assembles (content-type, OpenRouter app headers, proxy auth
+     * stripping) is intentionally left to the caller this phase. The wrappers
+     * preserve their source's CURRENT header behavior verbatim.
+     */
+    applyHeaders(headers: Record<string, string>, hints: AuthApplyHints): Promise<void> | void;
+    /**
+     * Called when the upstream returns 401. Return `true` to ask the caller to
+     * retry once with freshly-applied headers; `false` to surface the 401.
+     * Optional — sources without a refresh notion omit it.
+     */
+    onUnauthorized?(): Promise<boolean>;
+    /**
+     * Resolve the upstream URL the request should target, when the credential
+     * dictates it (e.g. a subscription profile's per-model endpoint). Returns
+     * `undefined` when the source does not override the URL (the ingress keeps
+     * its own URL logic). Optional.
+     */
+    resolveUpstreamUrl?(model: string): string | undefined;
+    /**
+     * React to a final HTTP status (pool participation seam — design D5).
+     *
+     * For the provider-key source this reports the status to the
+     * `ApiKeyPoolService` (cooldown / disable / re-bind) and returns whether it
+     * rotated plus any new key. THIS PHASE ONLY: `onResult` is implemented and
+     * unit-tested in isolation; NO caller invokes it yet. Phase 3 wires it into
+     * `fetchWithRetry`. Optional.
+     *
+     * @param status The final HTTP status, or `null` for non-HTTP failures
+     *   (e.g. network errors). Non-reportable statuses no-op.
+     */
+    onResult?(status: number | null): Promise<AuthResultOutcome>;
+}
+
+export type { AuthApplyHints, AuthResultOutcome, AuthSource };

package/dist/pipeline/AuthSource.d.ts

@@ -0,0 +1,101 @@
+/**
+ * AuthSource — unified outbound-authentication strategy for the provider
+ * request pipeline.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3).
+ *
+ * The three consumer paths (the wire-format proxy handler, the host engine
+ * adapter, TransformerHandler) each authenticate differently:
+ *
+ *   - provider-key (+ ApiKeyPool failover)  — LLM-config provider rows
+ *   - subscription `AuthStrategy` (+ 401 refresh + fallback) — code-cli OAuth
+ *   - OAuth pass-through                     — SDK forwards its own Bearer
+ *
+ * `AuthSource` is the single contract that unifies these. THIS PHASE ONLY
+ * DEFINES the interface and provides three behavior-preserving WRAPPERS
+ * (`LlmConfigProviderAuth`, `SubscriptionAuthSource`, `OAuthPassThroughAuth`)
+ * around the existing logic. NO caller is routed through it yet — the core
+ * (`executeProviderCall`) is NOT changed to consume `ctx.auth`, and
+ * the host handler's branch structure is UNCHANGED. Wiring (and
+ * the `onResult` pool-rotation integration) is Phase 3.
+ *
+ * @module pipeline/AuthSource
+ */
+/**
+ * Hints an `AuthSource` may need to vary header formatting per request.
+ *
+ * Mirrors the subscription-side `AuthApplyHints` (which uses optional
+ * `upstreamUrl` / `resolvedModel`) but with REQUIRED fields, since the
+ * pipeline always knows both at the point it applies headers. Adapters that
+ * wrap the looser subscription shape map these across at the boundary.
+ */
+interface AuthApplyHints {
+    /** Resolved upstream URL the request will be sent to. */
+    upstreamUrl: string;
+    /** Resolved model id for the request. */
+    model: string;
+}
+/**
+ * Result of {@link AuthSource.onResult}.
+ *
+ * `rebound` is `true` when the auth source rotated to a different credential
+ * (e.g. ApiKeyPool re-bound the session to a new key after a 429). `newKey`
+ * carries the freshly-resolved key string when a rotation produced one, so a
+ * caller MAY retry the same call once with it. Mirrors the
+ * `{ newKey | null }` contract of `ApiKeyPoolService.reportError` lifted into
+ * a structured shape.
+ */
+interface AuthResultOutcome {
+    /** Whether the credential was rotated/re-bound as a result of this status. */
+    rebound: boolean;
+    /** The new resolved key when a rotation produced one; omitted otherwise. */
+    newKey?: string;
+}
+/**
+ * A pluggable outbound-authentication source for one provider request.
+ *
+ * Implementations OWN exactly the auth concern: which headers carry the
+ * credential, how to recover from a 401, where the request should be sent
+ * (when the credential dictates the endpoint), and how to react to a final
+ * HTTP status (pool rotation / refresh). The pipeline core composes the rest.
+ */
+interface AuthSource {
+    /**
+     * Inject the authentication headers for this request, mutating `headers`
+     * in place. Implementations MAY refresh expiring tokens here.
+     *
+     * NOTE (Phase 2 boundary, see report): exactly WHAT this owns vs what the
+     * ingress assembles (content-type, OpenRouter app headers, proxy auth
+     * stripping) is intentionally left to the caller this phase. The wrappers
+     * preserve their source's CURRENT header behavior verbatim.
+     */
+    applyHeaders(headers: Record<string, string>, hints: AuthApplyHints): Promise<void> | void;
+    /**
+     * Called when the upstream returns 401. Return `true` to ask the caller to
+     * retry once with freshly-applied headers; `false` to surface the 401.
+     * Optional — sources without a refresh notion omit it.
+     */
+    onUnauthorized?(): Promise<boolean>;
+    /**
+     * Resolve the upstream URL the request should target, when the credential
+     * dictates it (e.g. a subscription profile's per-model endpoint). Returns
+     * `undefined` when the source does not override the URL (the ingress keeps
+     * its own URL logic). Optional.
+     */
+    resolveUpstreamUrl?(model: string): string | undefined;
+    /**
+     * React to a final HTTP status (pool participation seam — design D5).
+     *
+     * For the provider-key source this reports the status to the
+     * `ApiKeyPoolService` (cooldown / disable / re-bind) and returns whether it
+     * rotated plus any new key. THIS PHASE ONLY: `onResult` is implemented and
+     * unit-tested in isolation; NO caller invokes it yet. Phase 3 wires it into
+     * `fetchWithRetry`. Optional.
+     *
+     * @param status The final HTTP status, or `null` for non-HTTP failures
+     *   (e.g. network errors). Non-reportable statuses no-op.
+     */
+    onResult?(status: number | null): Promise<AuthResultOutcome>;
+}
+
+export type { AuthApplyHints, AuthResultOutcome, AuthSource };

package/dist/pipeline/LlmConfigProviderAuth.cjs

@@ -0,0 +1,169 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/pipeline/LlmConfigProviderAuth.ts
+var LlmConfigProviderAuth_exports = {};
+__export(LlmConfigProviderAuth_exports, {
+  LlmConfigProviderAuth: () => LlmConfigProviderAuth
+});
+module.exports = __toCommonJS(LlmConfigProviderAuth_exports);
+
+// src/openrouter.ts
+function isOpenRouterProvider(provider) {
+  const baseUrl = (provider.api_base_url || "").toLowerCase();
+  return baseUrl.includes("openrouter.ai");
+}
+var OPENROUTER_APP_HEADERS = {
+  "HTTP-Referer": "https://omnicross.dev",
+  "X-Title": "omnicross"
+};
+
+// src/completion/url-builder.ts
+var import_endpoint_resolver = require("@omnicross/contracts/endpoint-resolver");
+function resolveApiFormat(provider) {
+  if (provider.apiFormat) {
+    return provider.apiFormat;
+  }
+  if (provider.chatApiFormat) {
+    return provider.chatApiFormat;
+  }
+  if (provider.apiType === "claudecode" || provider.apiType === "anthropic") {
+    return "anthropic";
+  }
+  if (provider.apiType === "google") {
+    return "google";
+  }
+  return "openai";
+}
+
+// src/completion/header-builder.ts
+function getProviderHeaders(provider, apiKey) {
+  const format = resolveApiFormat(provider);
+  let headers;
+  switch (format) {
+    case "anthropic":
+      headers = {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2025-01-10"
+        // Required for extended thinking feature
+      };
+      break;
+    case "google":
+      headers = {
+        "Content-Type": "application/json",
+        "x-goog-api-key": apiKey
+      };
+      break;
+    case "azure-openai":
+      headers = {
+        "Content-Type": "application/json",
+        "api-key": apiKey
+      };
+      break;
+    case "openai":
+    case "openai-response":
+    default:
+      headers = {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${apiKey}`
+      };
+      break;
+  }
+  if (isOpenRouterProvider(provider)) {
+    return { ...headers, ...OPENROUTER_APP_HEADERS };
+  }
+  return headers;
+}
+
+// src/pipeline/LlmConfigProviderAuth.ts
+function isReportableStatus(status) {
+  return status === 429 || status === 529 || status === 401 || status === 403;
+}
+var LlmConfigProviderAuth = class {
+  provider;
+  apiKeyPool;
+  providerId;
+  sessionId;
+  /**
+   * The current resolved key. Mutable so a Phase-3 caller can read the
+   * rotated key after `onResult`; this phase it is only set at construction
+   * and updated inside `onResult` (mirroring the inline re-point in
+   * `callWithPoolReporting`).
+   */
+  apiKey;
+  constructor(opts) {
+    this.provider = opts.provider;
+    this.apiKey = opts.apiKey;
+    this.apiKeyPool = opts.apiKeyPool ?? null;
+    this.providerId = opts.providerId;
+    this.sessionId = opts.sessionId;
+  }
+  /**
+   * Merge the provider auth headers (and content-type / OpenRouter app
+   * headers) into `headers`, exactly as a direct `getProviderHeaders` call
+   * would produce them. `hints` are accepted for contract symmetry but the
+   * provider-key path does not vary headers by URL/model.
+   */
+  applyHeaders(headers, _hints) {
+    const authHeaders = getProviderHeaders(this.provider, this.apiKey);
+    for (const [k, v] of Object.entries(authHeaders)) {
+      headers[k] = v;
+    }
+  }
+  /**
+   * React to the final HTTP status — the pool-rotation seam (design D5).
+   *
+   * Reproduces `callWithPoolReporting`'s reportable + success branches:
+   *  - reportable status (429/529/401/403) on a pool-backed request →
+   *    `reportError(providerId, sessionId, status)`; when it hands back a
+   *    `newKey` the session was re-bound, so we adopt it (`this.apiKey`) and
+   *    return `{ rebound: true, newKey }`. When no key is available it returns
+   *    `{ rebound: false }` (the session is still cooled/disabled by the report).
+   *  - success / any 2xx → `reportSuccess(sessionId)`; `{ rebound: false }`.
+   *  - non-reportable, non-success, or non-pool request → no-op
+   *    `{ rebound: false }`.
+   *
+   * NOTE: no caller invokes this in Phase 2; it is unit-tested in isolation.
+   */
+  async onResult(status) {
+    const pool = this.apiKeyPool;
+    const providerId = this.providerId;
+    const sessionId = this.sessionId;
+    if (!pool || !providerId || !sessionId) {
+      return { rebound: false };
+    }
+    if (isReportableStatus(status)) {
+      const newKey = await pool.reportError(providerId, sessionId, status);
+      if (newKey) {
+        this.apiKey = newKey;
+        return { rebound: true, newKey };
+      }
+      return { rebound: false };
+    }
+    if (status !== null && status >= 200 && status < 300) {
+      pool.reportSuccess(sessionId);
+    }
+    return { rebound: false };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LlmConfigProviderAuth
+});