@omnicross/core 0.1.0 → 0.1.1

package/dist/SubscriptionAuthSource-D89zmiSS.d.ts

@@ -1,264 +0,0 @@
-import { OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
-import { AuthStrategy } from './pipeline/SubscriptionAuthStrategy.js';
-
-/**
- * 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>;
-}
-
-/**
- * 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 AuthSource as A, type SubscriptionAuthProfile as S, SubscriptionAuthSource as a, type SubscriptionRequestSummary as b, stripAuthHeaders as s };