@omnicross/core 0.1.0 → 0.1.1

package/dist/pipeline/LlmConfigProviderAuth.d.cts

@@ -0,0 +1,86 @@
+import { LLMProvider } from '@omnicross/contracts/llm-config';
+import { A as ApiKeyPoolService } from '../ApiKeyPoolService-BmMkau07.cjs';
+import { AuthSource, AuthApplyHints, AuthResultOutcome } from './AuthSource.cjs';
+
+/**
+ * LlmConfigProviderAuth — `AuthSource` for LLM-config provider rows.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3, task 4.2).
+ *
+ * Wraps the two pieces that authenticate a normal (non-subscription) provider
+ * request today:
+ *
+ *   - `getProviderHeaders(provider, apiKey)` — the format-specific auth
+ *     headers (x-api-key / Authorization Bearer / x-goog-api-key / api-key)
+ *     plus content-type and the OpenRouter app-attribution headers. `applyHeaders`
+ *     merges these into the caller's header object VERBATIM (same output as a
+ *     direct `getProviderHeaders` call).
+ *   - `ApiKeyPoolService` — session-affine key selection + 429/529/401/403
+ *     rotation. `onResult` reproduces the reportable-status branch of
+ *     the host engine adapter's `callWithPoolReporting` (report → re-bind →
+ *     return the new key) and the success branch (`reportSuccess`).
+ *
+ * IMPORTANT (Phase 2 scope): this class is DEFINED + unit-tested in isolation
+ * only. NO caller routes through it yet — `executeProviderCall` is unchanged
+ * and the rotation INTEGRATION is Phase 3 (D5). Do not wire `onResult` into a
+ * fetch loop in this phase.
+ *
+ * @module pipeline/LlmConfigProviderAuth
+ */
+
+interface LlmConfigProviderAuthOptions {
+    /** Provider row whose auth format + key drives header assembly. */
+    provider: LLMProvider;
+    /** Resolved API key string to authenticate with (post env-ref resolution). */
+    apiKey: string;
+    /**
+     * Pool service for rotation, when this request is pool-backed. Omit (or pass
+     * `null`) for legacy single-key requests — `onResult` then never touches the
+     * pool (matching `fromPool === false`).
+     */
+    apiKeyPool?: ApiKeyPoolService | null;
+    /** Provider id the pool should report/select against (the ACTUAL provider
+     *  whose key was resolved, post-routing). Required for pool participation. */
+    providerId?: string;
+    /** Session id for pool affinity + rebind. Required for pool participation. */
+    sessionId?: string | null;
+}
+declare class LlmConfigProviderAuth implements AuthSource {
+    private readonly provider;
+    private readonly apiKeyPool;
+    private readonly providerId;
+    private readonly 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: string;
+    constructor(opts: LlmConfigProviderAuthOptions);
+    /**
+     * 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: Record<string, string>, _hints: AuthApplyHints): void;
+    /**
+     * 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.
+     */
+    onResult(status: number | null): Promise<AuthResultOutcome>;
+}
+
+export { LlmConfigProviderAuth, type LlmConfigProviderAuthOptions };

package/dist/pipeline/LlmConfigProviderAuth.d.ts

@@ -0,0 +1,86 @@
+import { LLMProvider } from '@omnicross/contracts/llm-config';
+import { A as ApiKeyPoolService } from '../ApiKeyPoolService-BmMkau07.js';
+import { AuthSource, AuthApplyHints, AuthResultOutcome } from './AuthSource.js';
+
+/**
+ * LlmConfigProviderAuth — `AuthSource` for LLM-config provider rows.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3, task 4.2).
+ *
+ * Wraps the two pieces that authenticate a normal (non-subscription) provider
+ * request today:
+ *
+ *   - `getProviderHeaders(provider, apiKey)` — the format-specific auth
+ *     headers (x-api-key / Authorization Bearer / x-goog-api-key / api-key)
+ *     plus content-type and the OpenRouter app-attribution headers. `applyHeaders`
+ *     merges these into the caller's header object VERBATIM (same output as a
+ *     direct `getProviderHeaders` call).
+ *   - `ApiKeyPoolService` — session-affine key selection + 429/529/401/403
+ *     rotation. `onResult` reproduces the reportable-status branch of
+ *     the host engine adapter's `callWithPoolReporting` (report → re-bind →
+ *     return the new key) and the success branch (`reportSuccess`).
+ *
+ * IMPORTANT (Phase 2 scope): this class is DEFINED + unit-tested in isolation
+ * only. NO caller routes through it yet — `executeProviderCall` is unchanged
+ * and the rotation INTEGRATION is Phase 3 (D5). Do not wire `onResult` into a
+ * fetch loop in this phase.
+ *
+ * @module pipeline/LlmConfigProviderAuth
+ */
+
+interface LlmConfigProviderAuthOptions {
+    /** Provider row whose auth format + key drives header assembly. */
+    provider: LLMProvider;
+    /** Resolved API key string to authenticate with (post env-ref resolution). */
+    apiKey: string;
+    /**
+     * Pool service for rotation, when this request is pool-backed. Omit (or pass
+     * `null`) for legacy single-key requests — `onResult` then never touches the
+     * pool (matching `fromPool === false`).
+     */
+    apiKeyPool?: ApiKeyPoolService | null;
+    /** Provider id the pool should report/select against (the ACTUAL provider
+     *  whose key was resolved, post-routing). Required for pool participation. */
+    providerId?: string;
+    /** Session id for pool affinity + rebind. Required for pool participation. */
+    sessionId?: string | null;
+}
+declare class LlmConfigProviderAuth implements AuthSource {
+    private readonly provider;
+    private readonly apiKeyPool;
+    private readonly providerId;
+    private readonly 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: string;
+    constructor(opts: LlmConfigProviderAuthOptions);
+    /**
+     * 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: Record<string, string>, _hints: AuthApplyHints): void;
+    /**
+     * 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.
+     */
+    onResult(status: number | null): Promise<AuthResultOutcome>;
+}
+
+export { LlmConfigProviderAuth, type LlmConfigProviderAuthOptions };

package/dist/pipeline/LlmConfigProviderAuth.js

@@ -0,0 +1,142 @@
+// 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
+import { resolveProviderEndpoint as resolveProviderEndpointShared } from "@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 };
+  }
+};
+export {
+  LlmConfigProviderAuth
+};

package/dist/pipeline/SubscriptionAuthSource.d.cts

@@ -1,3 +1,165 @@
-import '@omnicross/contracts/subscription-types';
-export { S as SubscriptionAuthProfile, a as SubscriptionAuthSource, b as SubscriptionRequestSummary, s as stripAuthHeaders } from '../SubscriptionAuthSource-Cr4fVEYY.cjs';
-import './SubscriptionAuthStrategy.cjs';
+import { OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
+import { AuthSource, AuthApplyHints } from './AuthSource.cjs';
+import { AuthStrategy } from './SubscriptionAuthStrategy.cjs';
+
+/**
+ * SubscriptionAuthSource — `AuthSource` wrapping a subscription `AuthStrategy`.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3, task 4.3).
+ *
+ * Re-expresses the subscription auth used by `SubscriptionDispatcher` behind
+ * the unified `AuthSource` contract, delegating to the existing
+ * `AuthStrategy` so the OAuth refresh / token formatting logic is NOT
+ * rewritten:
+ *
+ *   - `applyHeaders` → `stripAuthHeaders(headers)` then
+ *     `authStrategy.applyHeaders(headers, { upstreamUrl, resolvedModel })`,
+ *     wrapped in the same best-effort try/catch as
+ *     `SubscriptionDispatcher.applyHeadersWithRetry` (a thrown
+ *     `applyHeaders` is logged + swallowed, NOT propagated — preserved
+ *     verbatim).
+ *   - `onUnauthorized` → `authStrategy.onUnauthorized()`.
+ *   - `resolveUpstreamUrl` → `profile.resolveUpstreamUrl?.(model)`.
+ *
+ * IMPORTANT (Phase 2 scope): this WRAPS the strategy + strip behavior but does
+ * NOT re-route `SubscriptionDispatcher` through it. The dispatcher's fragile
+ * 401-refresh + fallback loop is left UNCHANGED (task 4.5 deferred). This
+ * class is unit-tested in isolation only.
+ *
+ * @module pipeline/SubscriptionAuthSource
+ */
+
+/**
+ * Lightweight summary derived from the inbound request body — consumed by a
+ * profile's `modelMapper` (scenario routing). Structural mirror of
+ * `provider-proxy/types.ts`'s `SubscriptionRequestSummary`, declared here so
+ * `SubscriptionAuthProfile.modelMapper` is type-identical WITHOUT a circular
+ * import back into `provider-proxy/types` (which imports THIS module).
+ */
+interface SubscriptionRequestSummary {
+    messageCount: number;
+    estimatedInputTokens: number;
+    /**
+     * OPTIONAL bounded per-message match-text slice — kept structurally identical
+     * to the canonical declaration in `provider-proxy/types.ts` (the two are
+     * deliberate mirrors, not one shared import). Consumed only by the OpenCodeGo
+     * keyword matcher in `@omnicross/subscriptions`; core writes, never reads it.
+     */
+    matchText?: string[];
+}
+/**
+ * The subset of a `SubscriptionDispatchProfile` the subscription paths need.
+ * Kept structural (not the full profile type) so the wrapper does not pull in
+ * the whole registry surface. The full `SubscriptionDispatchProfile` (which IS
+ * what gets passed here) satisfies this shape; the optional `mode` + `modelMapper`
+ * are read by the built-in `/v1/messages` subscription path (RT2.1) to decide the
+ * verbatim-vs-transformer shape and to apply opencodego scenario routing.
+ */
+interface SubscriptionAuthProfile {
+    readonly authStrategy: AuthStrategy;
+    /** Per-model upstream URL resolver (transformer profiles). Optional for
+     *  pass-through profiles that hard-code their endpoint upstream. The OPTIONAL
+     *  2nd `config` arg (opencodego `baseUrl` override, D1) is additive — existing
+     *  one-arg callers compile unchanged; mirrors the full
+     *  `SubscriptionDispatchProfile.resolveUpstreamUrl` so the registry profile
+     *  stays assignable. */
+    readonly resolveUpstreamUrl?: (resolvedModel: string, config?: OpenCodeGoTokenConfig) => string;
+    /**
+     * Names of provider-level transformers (registered in `TransformerService`)
+     * to run on the subscription chain — re-encode Unified → the upstream's wire.
+     * The full `SubscriptionDispatchProfile` (which IS what gets passed here)
+     * carries these; exposing them on the narrow structural type lets the
+     * Responses ingress build the profile's REAL chain (cross-vendor route-to,
+     * task #29) instead of hard-coding `['openai-response']`. Absent/empty →
+     * the ingress falls back to its endpoint transformer (codex byte-identity).
+     */
+    readonly providerTransformerNames?: readonly string[];
+    /** Names of model-specific transformers — usually empty. See above. */
+    readonly modelTransformerNames?: readonly string[];
+    /**
+     * OPTIONAL shape-aware provider transformer-name resolver (opencodego zen).
+     * Type-identical to `SubscriptionDispatchProfile.resolveProviderTransformerNames`
+     * so the registry profile stays assignable. The built-in `/v1/messages`
+     * subscription path (Phase 3) consults it via
+     * `profile.resolveProviderTransformerNames?.(model, route.subscriptionConfig)`
+     * to pick the right zen chain per resolved shape. `config` is `unknown` (core
+     * opaque-config discipline — no `@omnicross/subscriptions` import). When ABSENT
+     * the path reads the static `providerTransformerNames` exactly as today (codex
+     * byte-identity).
+     */
+    readonly resolveProviderTransformerNames?: (model: string, config?: unknown) => readonly string[];
+    /**
+     * Pass-through (claude) vs transformer (codex / opencodego / gemini). The
+     * built-in `/v1/messages` subscription path (RT2.1) reads this for its
+     * core-local same-format signal (pass-through ⇒ always verbatim relay).
+     * Optional on the narrow type — partial profiles built by other route-minting
+     * sites may omit it.
+     */
+    readonly mode?: 'pass-through' | 'transformer';
+    /**
+     * Optional model placeholder rewriter — only set for OpenCodeGo. Type-identical
+     * to `SubscriptionDispatchProfile.modelMapper` so the registry profile stays
+     * assignable. Applied by the built-in `/v1/messages` subscription path BEFORE
+     * resolving the upstream URL (so scenario-based shape routing picks the right
+     * Anthropic-shape vs OpenAI-shape upstream).
+     */
+    readonly modelMapper?: (sdkModel: string, summary: SubscriptionRequestSummary, config: OpenCodeGoTokenConfig | undefined) => {
+        resolvedModel: string;
+        scenario: OpenCodeGoScenario;
+    };
+    /**
+     * Optional fallback resolver — only set for OpenCodeGo. Type-identical to
+     * `SubscriptionDispatchProfile.nextFallback` so the registry profile stays
+     * assignable. Read by the built-in `/v1/messages` fallback loop (D6b) to pick
+     * the next model after an unrecoverable upstream failure; returns `null` when
+     * exhausted (claude / codex / gemini omit it → no fallback attempted).
+     */
+    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). Type-identical to `SubscriptionDispatchProfile.allowModel`.
+     * Only OpenCodeGo sets it; the core `/v1/messages` loop consults it for the
+     * primary before its first attempt and jumps to the first admitting
+     * `nextFallback` candidate when the primary's circuit is open. Absent ⇒ the
+     * primary is always admitted (claude / codex / gemini — no breaker).
+     */
+    readonly allowModel?: (modelId: string) => boolean;
+    /**
+     * Optional record-outcome callback (D5 record seam). Type-identical to
+     * `SubscriptionDispatchProfile.recordModelOutcome`. The core `/v1/messages`
+     * loop calls `profile.recordModelOutcome?.(model, ok)` THROUGH this optional
+     * field after each attempt, so `@omnicross/core` gains NO import of
+     * `@omnicross/subscriptions` (the cross-layer litmus stays 0 — exactly the
+     * `nextFallback` precedent). `ok: true` on `2xx`; `ok: false` on
+     * thrown/`5xx`/`429`; a non-429 `4xx` is NEUTRAL (the loop does NOT call it).
+     * Absent for claude / codex / gemini ⇒ no-op.
+     */
+    readonly recordModelOutcome?: (modelId: string, ok: boolean) => void;
+}
+/**
+ * Drop auth headers the transformer chain may have set so the `AuthStrategy`
+ * is the single source of truth for outbound authentication. Byte-identical
+ * to `SubscriptionDispatcher.stripAuthHeaders`.
+ */
+declare function stripAuthHeaders(headers: Record<string, string>): void;
+declare class SubscriptionAuthSource implements AuthSource {
+    private readonly profile;
+    constructor(profile: SubscriptionAuthProfile);
+    /**
+     * Strip any transformer-set auth headers, then delegate to the bound
+     * strategy. Mirrors `SubscriptionDispatcher`'s
+     * `stripAuthHeaders(...)` + `applyHeadersWithRetry(...)` sequence, including
+     * the best-effort swallow-and-warn around a throwing `applyHeaders`.
+     *
+     * The strategy's looser `AuthApplyHints` (optional `upstreamUrl` /
+     * `resolvedModel`) is fed from the pipeline's required `{ upstreamUrl,
+     * model }` at the boundary.
+     */
+    applyHeaders(headers: Record<string, string>, hints: AuthApplyHints): Promise<void>;
+    /** Delegate the 401-refresh decision to the bound strategy. */
+    onUnauthorized(): Promise<boolean>;
+    /** Resolve the upstream URL from the profile, when it provides one. */
+    resolveUpstreamUrl(model: string): string | undefined;
+}
+
+export { type SubscriptionAuthProfile, SubscriptionAuthSource, type SubscriptionRequestSummary, stripAuthHeaders };

package/dist/pipeline/SubscriptionAuthSource.d.ts

@@ -1,3 +1,165 @@
-import '@omnicross/contracts/subscription-types';
-export { S as SubscriptionAuthProfile, a as SubscriptionAuthSource, b as SubscriptionRequestSummary, s as stripAuthHeaders } from '../SubscriptionAuthSource-D89zmiSS.js';
-import './SubscriptionAuthStrategy.js';
+import { OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
+import { AuthSource, AuthApplyHints } from './AuthSource.js';
+import { AuthStrategy } from './SubscriptionAuthStrategy.js';
+
+/**
+ * SubscriptionAuthSource — `AuthSource` wrapping a subscription `AuthStrategy`.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3, task 4.3).
+ *
+ * Re-expresses the subscription auth used by `SubscriptionDispatcher` behind
+ * the unified `AuthSource` contract, delegating to the existing
+ * `AuthStrategy` so the OAuth refresh / token formatting logic is NOT
+ * rewritten:
+ *
+ *   - `applyHeaders` → `stripAuthHeaders(headers)` then
+ *     `authStrategy.applyHeaders(headers, { upstreamUrl, resolvedModel })`,
+ *     wrapped in the same best-effort try/catch as
+ *     `SubscriptionDispatcher.applyHeadersWithRetry` (a thrown
+ *     `applyHeaders` is logged + swallowed, NOT propagated — preserved
+ *     verbatim).
+ *   - `onUnauthorized` → `authStrategy.onUnauthorized()`.
+ *   - `resolveUpstreamUrl` → `profile.resolveUpstreamUrl?.(model)`.
+ *
+ * IMPORTANT (Phase 2 scope): this WRAPS the strategy + strip behavior but does
+ * NOT re-route `SubscriptionDispatcher` through it. The dispatcher's fragile
+ * 401-refresh + fallback loop is left UNCHANGED (task 4.5 deferred). This
+ * class is unit-tested in isolation only.
+ *
+ * @module pipeline/SubscriptionAuthSource
+ */
+
+/**
+ * Lightweight summary derived from the inbound request body — consumed by a
+ * profile's `modelMapper` (scenario routing). Structural mirror of
+ * `provider-proxy/types.ts`'s `SubscriptionRequestSummary`, declared here so
+ * `SubscriptionAuthProfile.modelMapper` is type-identical WITHOUT a circular
+ * import back into `provider-proxy/types` (which imports THIS module).
+ */
+interface SubscriptionRequestSummary {
+    messageCount: number;
+    estimatedInputTokens: number;
+    /**
+     * OPTIONAL bounded per-message match-text slice — kept structurally identical
+     * to the canonical declaration in `provider-proxy/types.ts` (the two are
+     * deliberate mirrors, not one shared import). Consumed only by the OpenCodeGo
+     * keyword matcher in `@omnicross/subscriptions`; core writes, never reads it.
+     */
+    matchText?: string[];
+}
+/**
+ * The subset of a `SubscriptionDispatchProfile` the subscription paths need.
+ * Kept structural (not the full profile type) so the wrapper does not pull in
+ * the whole registry surface. The full `SubscriptionDispatchProfile` (which IS
+ * what gets passed here) satisfies this shape; the optional `mode` + `modelMapper`
+ * are read by the built-in `/v1/messages` subscription path (RT2.1) to decide the
+ * verbatim-vs-transformer shape and to apply opencodego scenario routing.
+ */
+interface SubscriptionAuthProfile {
+    readonly authStrategy: AuthStrategy;
+    /** Per-model upstream URL resolver (transformer profiles). Optional for
+     *  pass-through profiles that hard-code their endpoint upstream. The OPTIONAL
+     *  2nd `config` arg (opencodego `baseUrl` override, D1) is additive — existing
+     *  one-arg callers compile unchanged; mirrors the full
+     *  `SubscriptionDispatchProfile.resolveUpstreamUrl` so the registry profile
+     *  stays assignable. */
+    readonly resolveUpstreamUrl?: (resolvedModel: string, config?: OpenCodeGoTokenConfig) => string;
+    /**
+     * Names of provider-level transformers (registered in `TransformerService`)
+     * to run on the subscription chain — re-encode Unified → the upstream's wire.
+     * The full `SubscriptionDispatchProfile` (which IS what gets passed here)
+     * carries these; exposing them on the narrow structural type lets the
+     * Responses ingress build the profile's REAL chain (cross-vendor route-to,
+     * task #29) instead of hard-coding `['openai-response']`. Absent/empty →
+     * the ingress falls back to its endpoint transformer (codex byte-identity).
+     */
+    readonly providerTransformerNames?: readonly string[];
+    /** Names of model-specific transformers — usually empty. See above. */
+    readonly modelTransformerNames?: readonly string[];
+    /**
+     * OPTIONAL shape-aware provider transformer-name resolver (opencodego zen).
+     * Type-identical to `SubscriptionDispatchProfile.resolveProviderTransformerNames`
+     * so the registry profile stays assignable. The built-in `/v1/messages`
+     * subscription path (Phase 3) consults it via
+     * `profile.resolveProviderTransformerNames?.(model, route.subscriptionConfig)`
+     * to pick the right zen chain per resolved shape. `config` is `unknown` (core
+     * opaque-config discipline — no `@omnicross/subscriptions` import). When ABSENT
+     * the path reads the static `providerTransformerNames` exactly as today (codex
+     * byte-identity).
+     */
+    readonly resolveProviderTransformerNames?: (model: string, config?: unknown) => readonly string[];
+    /**
+     * Pass-through (claude) vs transformer (codex / opencodego / gemini). The
+     * built-in `/v1/messages` subscription path (RT2.1) reads this for its
+     * core-local same-format signal (pass-through ⇒ always verbatim relay).
+     * Optional on the narrow type — partial profiles built by other route-minting
+     * sites may omit it.
+     */
+    readonly mode?: 'pass-through' | 'transformer';
+    /**
+     * Optional model placeholder rewriter — only set for OpenCodeGo. Type-identical
+     * to `SubscriptionDispatchProfile.modelMapper` so the registry profile stays
+     * assignable. Applied by the built-in `/v1/messages` subscription path BEFORE
+     * resolving the upstream URL (so scenario-based shape routing picks the right
+     * Anthropic-shape vs OpenAI-shape upstream).
+     */
+    readonly modelMapper?: (sdkModel: string, summary: SubscriptionRequestSummary, config: OpenCodeGoTokenConfig | undefined) => {
+        resolvedModel: string;
+        scenario: OpenCodeGoScenario;
+    };
+    /**
+     * Optional fallback resolver — only set for OpenCodeGo. Type-identical to
+     * `SubscriptionDispatchProfile.nextFallback` so the registry profile stays
+     * assignable. Read by the built-in `/v1/messages` fallback loop (D6b) to pick
+     * the next model after an unrecoverable upstream failure; returns `null` when
+     * exhausted (claude / codex / gemini omit it → no fallback attempted).
+     */
+    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). Type-identical to `SubscriptionDispatchProfile.allowModel`.
+     * Only OpenCodeGo sets it; the core `/v1/messages` loop consults it for the
+     * primary before its first attempt and jumps to the first admitting
+     * `nextFallback` candidate when the primary's circuit is open. Absent ⇒ the
+     * primary is always admitted (claude / codex / gemini — no breaker).
+     */
+    readonly allowModel?: (modelId: string) => boolean;
+    /**
+     * Optional record-outcome callback (D5 record seam). Type-identical to
+     * `SubscriptionDispatchProfile.recordModelOutcome`. The core `/v1/messages`
+     * loop calls `profile.recordModelOutcome?.(model, ok)` THROUGH this optional
+     * field after each attempt, so `@omnicross/core` gains NO import of
+     * `@omnicross/subscriptions` (the cross-layer litmus stays 0 — exactly the
+     * `nextFallback` precedent). `ok: true` on `2xx`; `ok: false` on
+     * thrown/`5xx`/`429`; a non-429 `4xx` is NEUTRAL (the loop does NOT call it).
+     * Absent for claude / codex / gemini ⇒ no-op.
+     */
+    readonly recordModelOutcome?: (modelId: string, ok: boolean) => void;
+}
+/**
+ * Drop auth headers the transformer chain may have set so the `AuthStrategy`
+ * is the single source of truth for outbound authentication. Byte-identical
+ * to `SubscriptionDispatcher.stripAuthHeaders`.
+ */
+declare function stripAuthHeaders(headers: Record<string, string>): void;
+declare class SubscriptionAuthSource implements AuthSource {
+    private readonly profile;
+    constructor(profile: SubscriptionAuthProfile);
+    /**
+     * Strip any transformer-set auth headers, then delegate to the bound
+     * strategy. Mirrors `SubscriptionDispatcher`'s
+     * `stripAuthHeaders(...)` + `applyHeadersWithRetry(...)` sequence, including
+     * the best-effort swallow-and-warn around a throwing `applyHeaders`.
+     *
+     * The strategy's looser `AuthApplyHints` (optional `upstreamUrl` /
+     * `resolvedModel`) is fed from the pipeline's required `{ upstreamUrl,
+     * model }` at the boundary.
+     */
+    applyHeaders(headers: Record<string, string>, hints: AuthApplyHints): Promise<void>;
+    /** Delegate the 401-refresh decision to the bound strategy. */
+    onUnauthorized(): Promise<boolean>;
+    /** Resolve the upstream URL from the profile, when it provides one. */
+    resolveUpstreamUrl(model: string): string | undefined;
+}
+
+export { type SubscriptionAuthProfile, SubscriptionAuthSource, type SubscriptionRequestSummary, stripAuthHeaders };