@yanlinglabs/winter-provider-runtime 0.0.2

package/dist/adapters/openai/shared.d.ts

@@ -0,0 +1,359 @@
+import type { WinterModelDescriptor } from "@yanlinglabs/winter-provider-catalog";
+import { type IdentityHeaderLookup } from "../../identity.js";
+import { type EndpointPolicy } from "../../endpoint-policy.js";
+import { ProviderRequestError } from "../../http.js";
+import { type RetryPolicy, type RetryPolicyOptions } from "../../retry.js";
+import type { ContentBlockLike, CredentialMaterial, CredentialRef, CredentialStatus, DiscoveryContext, ModelCatalogResult, ProviderContext, ProviderEvent, ProviderMessageLike, TurnRequest } from "../../types.js";
+/** How this surface carries a key: OpenAI-style `Authorization: Bearer`, or Azure's own `api-key` header. */
+export type AuthStyle = "bearer" | "azure-api-key";
+/** Looks a provider-local model id up in the catalog. See decision 2 in this file's header. */
+export type DescriptorLookup = (providerLocalModelId: string) => WinterModelDescriptor | undefined;
+export interface OpenAiAdapterOptions {
+    /**
+     * The adapter's OWN reviewed endpoint — the one `applyPrivilegedHeaders` will speak to. Defaults
+     * to the family's vendor URL; overridable at CONSTRUCTION only, which is what lets a fixture point
+     * a generated endpoint at a loopback fake without turning `ConnectionProfile.baseUrl` (untrusted)
+     * into a privileged one.
+     */
+    generatedBaseUrl?: string;
+    /**
+     * REQUIRED — omitting it is a compile error, and that is the fail-closed mechanism (ruling on
+     * finding I3).
+     *
+     * Nothing in this file's logic changes when a lookup is absent; what changes is that EVERY WS-13
+     * §8.2 refusal quietly stops happening: an unmapped effort passes through, an over-limit request
+     * is sent, a thinking config on a model with no reasoning evidence is honoured, and — worst,
+     * because it is silent and remote — a DeepSeek profile stops capturing `reasoning_content` and
+     * 400s on the second leg of every tool loop. None of that fails to compile, and none of it fails
+     * a test that did not think to look. Requiring the field is the only guard that cannot be
+     * forgotten.
+     *
+     * The gateway/unlisted shape is an EXPLICIT `() => undefined`: a caller saying "this model has no
+     * catalog evidence" out loud, rather than a caller who forgot.
+     */
+    descriptors: DescriptorLookup;
+    /** Injected in tests so a retry fixture never sleeps a real backoff. */
+    retry?: RetryPolicyOptions;
+    /** R6-L PRIVILEGED: an organisation identifier only means something at the reviewed endpoint it was minted for. */
+    organization?: string;
+    /** R6-L PRIVILEGED, same reasoning as `organization`. */
+    project?: string;
+    /** The cap on a STREAM's total bytes. Generous by design: a long generation is legitimately large. */
+    maxBodyBytes?: number;
+    /** Milliseconds allowed for response HEADERS. Cleared once they arrive — never a bound on the generation. */
+    headerTimeoutMs?: number;
+    /** How this surface carries a key. Azure's deployment path wants `api-key`; every other surface is a bearer. */
+    authStyle?: AuthStyle;
+    /**
+     * WS-13b §7/§8.4 (fix-wave R-FW-2): the per-ROW second identity field, looked up by
+     * `ctx.connection.providerId`.
+     *
+     * A LOOKUP rather than a value, because this family's adapters are multi-provider: one
+     * `winter.openai-chat-completions` instance serves a hundred and thirty-six rows, so "the identity
+     * headers" is a property of the row a turn is for, not of the adapter. Optional, and absent means
+     * `{}` — only a vendor that NAMES a second identity field gets one.
+     */
+    identityHeaders?: IdentityHeaderLookup;
+}
+export declare const DEFAULT_STREAM_BODY_BYTES: number;
+export declare const DEFAULT_HEADER_TIMEOUT_MS = 60000;
+/** A `/v1/models` page count that is a loop rather than a catalog. Discovery is additionally item- and time-bounded by `discoverModels`. */
+export declare const MAX_DISCOVERY_PAGES = 20;
+/** A refusal raised BEFORE any request is sent (WS-13 §8.2). `capability` is the Winter code for "this selection cannot be represented on this wire". */
+export declare function capabilityRefusal(reason: string): ProviderRequestError;
+/** A refusal about the request's own shape, raised before it is sent. */
+export declare function badRequestRefusal(reason: string): ProviderRequestError;
+/**
+ * This family's twin of `THINKING_ENABLED_NEEDS_BUDGET` (`adapters/refusals.ts`): the same caller
+ * mistake — "reasoning on, but at what?" — asked in this family's own vocabulary, because the way
+ * out is an EFFORT here and a budget there. Same sentence shape, so a caller moving a session
+ * between families recognises the situation without re-reading it.
+ */
+export declare function THINKING_ENABLED_NEEDS_EFFORT(model: string): string;
+export interface ResolvedEndpoint {
+    /** The origin+path prefix every request URL is built from. No trailing slash. */
+    baseUrl: string;
+    policy: EndpointPolicy;
+    /** True when the base came from the ADAPTER (reviewed) rather than from `ConnectionProfile.baseUrl`. */
+    generated: boolean;
+}
+/**
+ * Chooses between the adapter's generated endpoint and the profile's base URL, and builds the
+ * policy `boundedFetch` enforces.
+ *
+ * A profile `baseUrl` is evaluated by its ORIGIN, not by its mere presence (P7a): a reviewed
+ * endpoint the runtime COPIED in (`endpointOrigin: "reviewed"` — every row on an adapter that
+ * serves several providers) stays generated, and only a host- or user-supplied one is a USER
+ * endpoint. `connectionEndpointOptions` is the single reading of that field, and it carries the
+ * profile's own `local` declaration through — which is what lets a loopback Ollama be reached over
+ * plain http while an undeclared private address is still refused (`evaluateEndpoint`'s own rule,
+ * not a second copy of it here).
+ */
+export declare function resolveEndpoint(ctx: ProviderContext, options: OpenAiAdapterOptions, fallbackGeneratedBaseUrl?: string): ResolvedEndpoint;
+export interface ResolvedAuth {
+    headers: Record<string, string>;
+    material: CredentialMaterial | null;
+}
+/**
+ * Resolves `ctx.authRef` into request headers.
+ *
+ * A `null` material (a `none` ref, or a keychain slot with nothing in it) is NOT an error here: a
+ * local server with `authKind: "local-none"` is a first-class configuration, and the surfaces that
+ * genuinely require a credential say so themselves by refusing an empty header set.
+ */
+export declare function resolveAuth(ctx: ProviderContext, style: AuthStyle): Promise<ResolvedAuth>;
+export interface HeaderPlan {
+    policy: EndpointPolicy;
+    /** Everything an endpoint needs to be spoken to at all: content-type, accept, `OpenAI-Beta`, and auth. NOT routed through `applyPrivilegedHeaders`. */
+    protocol: Record<string, string>;
+    /** Identifiers that only mean something at the reviewed endpoint they were minted for (R6-L). */
+    privileged?: Record<string, string>;
+    /**
+     * WINTER'S OWN second identity field for this row (`Client-Agent`), already `<version>`-substituted.
+     *
+     * Spread with the `user-agent`, BEFORE the host's map and NOT through `applyPrivilegedHeaders` —
+     * it is Winter's name, not the operator's account topology, and gating it on a generated endpoint
+     * would drop it for every multi-provider row (whose reviewed endpoint is copied into the profile
+     * and evaluated as a user endpoint). `identityFor` builds it.
+     */
+    identity?: Record<string, string>;
+    /** `ConnectionProfile.headers` — the host's own additions (OpenRouter's attribution pair, a proxy token's sibling header). */
+    userSupplied?: Record<string, string> | undefined;
+}
+/**
+ * Assembles a request's headers.
+ *
+ * ORDER IS THE POINT: user-supplied first, privileged next, protocol last, so an adapter-owned
+ * header can never be displaced by a profile. And a user-supplied set is stripped of every
+ * credential-bearing NAME first — a `ConnectionProfile` is non-secret connection metadata by
+ * contract (WS-13 §6), so a credential appearing there is a misconfiguration to drop, not a second
+ * auth channel to honour.
+ */
+export declare function buildHeaders(plan: HeaderPlan): Record<string, string>;
+/** This row's Winter-authored identity headers, for a `HeaderPlan`. One call shape for every site in the family. */
+export declare function identityFor(options: Pick<OpenAiAdapterOptions, "identityHeaders">, ctx: ProviderContext): Record<string, string>;
+/** The pinned five-tier ladder (`sdk.d.ts:586`), in order. The rank is what a NUMERIC effort is snapped onto. */
+export declare const EFFORT_LADDER: readonly ["low", "medium", "high", "xhigh", "max"];
+export type LadderEffort = (typeof EFFORT_LADDER)[number];
+/**
+ * A numeric effort -> the nearest tier the MODEL verifies.
+ *
+ * The pin states no unit, no range and no mapping for the numeric form (derived-shapes-p6.md item
+ * (c): "the answer is a documented absence", OQ-P6-2), so this is gap-filling and is disclosed. The
+ * rule chosen, stated so it is auditable: the integer is a POSITION ON THE PINNED FIVE-TIER LADDER,
+ * clamped to [1, 5] — so `3` means "high" on every model — and is then snapped to the nearest tier
+ * this model's own `reasoning.efforts` actually lists. That keeps the number's meaning stable across
+ * models (an index-into-the-model's-list reading would make `2` mean different things on a 3-tier
+ * and a 5-tier model) while still never sending a value the model has not verified.
+ */
+export declare function snapNumericEffort(value: number, verified: readonly string[]): string | undefined;
+/**
+ * WS-13 §8.2's rule as a function: map onto the model's VERIFIED vocabulary, or reject BEFORE the
+ * request. A silent downgrade to the provider's default is prohibited, which is why every failure
+ * arm returns `{ ok: false }` rather than `undefined`.
+ *
+ * The descriptor-less arm (a gateway model passed through by `allowUnlisted`) is deliberately
+ * different rather than lax: a NAMED effort is passed through verbatim (the caller named a tier the
+ * pin defines and Winter has no evidence to contradict it), while a NUMERIC one is refused, because
+ * snapping a number needs a vocabulary and there is none.
+ */
+export declare function mapEffortAgainst(effort: TurnRequest["effort"], descriptor: WinterModelDescriptor | undefined): {
+    ok: true;
+    value: string | undefined;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ReasoningPlan {
+    /** The `reasoning.effort` value, when one applies. */
+    effort?: string;
+    /** The `reasoning.summary` value, when the descriptor's `summaryRequest` evidence says how to ask. */
+    summary?: string;
+    /** True when the request should carry `include: ["reasoning.encrypted_content"]` (Responses only). */
+    wantsEncryptedContent: boolean;
+    /** False when `thinking: {type:"disabled"}` — no reasoning object at all. */
+    enabled: boolean;
+}
+/**
+ * Resolves `effort` + `thinking` into what the wire will carry, or throws a typed refusal.
+ *
+ * THE FAMILY'S RULE IN ONE LINE (WS-13 §8.2, fix-wave ruling F-2): this family has NO budget field,
+ * so `thinking: { type: "enabled" }` means reasoning ON at the row's own `defaultEffort` — the only
+ * effort the catalog verified for that model, never an invented one.
+ *
+ * The three refusals worth stating, because each has a tempting silent alternative:
+ *
+ *   `thinking: {type:"enabled", budgetTokens: N}` is REFUSED. The OpenAI surfaces have no
+ *     token-budget knob for reasoning — the verified vocabulary is effort tiers — so honouring the
+ *     config would mean dropping the budget and sending an effort the caller never asked for. That
+ *     is precisely the silent downgrade WS-13 §8.2 prohibits.
+ *
+ *   `thinking: {type:"enabled"|"adaptive"}` on a model with NO reasoning evidence is REFUSED rather
+ *     than ignored, for the same reason: "we quietly did not think" is not an outcome a caller can
+ *     see.
+ *
+ *   `thinking: {type:"enabled"|"adaptive"}` with NO effort given and NO `defaultEffort` on the row
+ *     is REFUSED — and this one was the whole-branch review's M-9. It used to resolve to `effort:
+ *     undefined`, which `buildResponsesBody` renders as `include: ["reasoning.encrypted_content"]`
+ *     with NO `reasoning` object at all: a request that asks to keep reasoning state for reasoning
+ *     it never asked the model to do. The turn succeeds, the caller is told nothing, and the answer
+ *     is the no-think one. Same class as the two above, so it gets the same treatment.
+ */
+export declare function resolveReasoning(req: TurnRequest, descriptor: WinterModelDescriptor | undefined): ReasoningPlan;
+/**
+ * WS-13 §8.2's other half: a request over the model's DECLARED limits, or naming a parameter the
+ * model rejects, fails here — before a byte goes out — rather than upstream.
+ */
+export declare function assertWithinLimits(req: TurnRequest, descriptor: WinterModelDescriptor | undefined, parametersInPlay: readonly string[]): void;
+/** The three-state tool capability plus the reasoning facts the bridge reads off an adapter. */
+export declare function capabilitiesFrom(descriptor: WinterModelDescriptor): {
+    toolCalling: "native" | "emulated" | "none";
+    continuationDomain?: string;
+    readableState: "none" | "summary" | "full-exposed";
+};
+/**
+ * A tool the adapter cannot represent is an ERROR, never a silently dropped tool (WS-13 §9's own
+ * hard negative). "Cannot represent" is narrow and structural: a tool with no name, or a schema that
+ * is not a JSON-Schema object, is one the provider would reject or — worse — accept while quietly
+ * losing the constraint.
+ */
+export declare function assertRepresentableTools(tools: TurnRequest["tools"]): void;
+/** Normalizes `string | ContentBlockLike[]` to blocks, so a mapper has one shape to walk. */
+export declare function asBlocks(content: ProviderMessageLike["content"]): ContentBlockLike[];
+/** Flattens a `tool_result.content` (which R6-3 widened to `string | ContentBlockLike[]`) into the plain text every OpenAI surface carries. */
+export declare function toolResultText(content: string | ContentBlockLike[]): string;
+/**
+ * A Winter-authored annotation -> the text that actually rides the wire (minor 11).
+ *
+ * BOTH DOORS RENDER AS PLAIN TEXT on this family, and that is a decision rather than a shortcut.
+ * `thinking-channel` names an in-dialect reasoning slot; no OpenAI-family surface has one a caller
+ * may write into, and the nearest thing (`reasoning_content`) is the MODEL's own output channel —
+ * putting Winter's prose there would present an annotation as something the model reasoned, which is
+ * the impersonation R6-8 exists to forbid. So the annotation is carried plainly, on both doors.
+ *
+ * VERBATIM — this layer adds NOTHING, not even a label. The text arrives from Lane C already
+ * finished and already delimited (the `<recovered_reasoning_summary>` tag WS-13 §8.2 names for the
+ * tag door, the bracketed label for the thinking-channel door), and Lane C's §9.6 budget is counted
+ * on exactly these bytes. A wrapper of this layer's own would double-label the second door, would
+ * add a delimiter `neutralizeDelimiters` does not neutralise (so a foreign summary containing the
+ * added closing delimiter would break straight out of it), and would make this family the only one
+ * that alters the string — the whole-branch review's I-3, escalated from Lane B's identical
+ * `<winter-note>` wrapper. The other three families render it byte-for-byte; so does this one.
+ *
+ * Without this door at all, Lane C's decorations were built, persisted and then silently dropped at
+ * the wire: a cross-family handoff note that never reaches the model is worse than none, because the
+ * switch's `continuity_warning` has already reported the context as carried.
+ *
+ * WHERE it goes depends on what the message carries. On an ordinary message it LEADS the content.
+ * On a message carrying TOOL RESULTS it PREFIXES the first result's own text (see
+ * `prefixToolResult`) — never a message of its own, because a message between an assistant's
+ * `tool_calls` and its `tool` reply is rejected outright ("messages with role 'tool' must be a
+ * response to a preceeding message with 'tool_calls'"). Round 3's finding: an annotation that
+ * breaks the turn is worse than one that is dropped.
+ */
+export declare function decorationText(message: ProviderMessageLike): string | undefined;
+/**
+ * A decoration prefixed onto a tool result's own text.
+ *
+ * Adjacency between a tool call and its result is a WIRE INVARIANT on every surface in this family,
+ * so the annotation rides INSIDE the result it annotates rather than beside it. Same verbatim text,
+ * same position relative to what it describes, and no extra item on the wire at all.
+ */
+export declare function prefixToolResult(decoration: string | undefined, output: string): string;
+/** An `image` block -> the data URL every OpenAI surface accepts. */
+export declare function imageDataUrl(block: Extract<ContentBlockLike, {
+    type: "image";
+}>): string;
+/**
+ * A one-slot async queue for events produced by a SYNCHRONOUS callback while the generator that
+ * must yield them is suspended. See decision 3 in this file's header.
+ */
+export declare class EventQueue {
+    private items;
+    private waker;
+    push(event: ProviderEvent): void;
+    wake(): void;
+    drain(): ProviderEvent[];
+    wait(): Promise<void>;
+}
+/**
+ * Runs `work` while yielding whatever lands on `queue`, and returns `work`'s value.
+ *
+ * The ordering this buys is the whole point: `withRetry` announces a retry BEFORE it sleeps, so the
+ * event is queued, the pump wakes on the next microtask, and the consumer sees it before the retried
+ * request reaches the wire. A post-hoc flush would report every retry after the attempt that
+ * finally succeeded.
+ */
+export declare function pumpEvents<T>(queue: EventQueue, work: Promise<T>): AsyncGenerator<ProviderEvent, T>;
+export interface StreamingRequestPlan {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+    policy: EndpointPolicy;
+    ctx: ProviderContext;
+    options: OpenAiAdapterOptions;
+    signal?: AbortSignal | undefined;
+    /** Called once per attempt, BEFORE the request goes out. The codex quota manager's hook. */
+    beforeAttempt?: (attempt: number) => Promise<void>;
+    /** Given a non-2xx response, decides whether the adapter can recover in-band (codex's one-shot token refresh). Returning a new header set retries immediately, outside the retry budget. */
+    recover?: (status: number, attempt: number) => Promise<Record<string, string> | undefined>;
+    /**
+     * Observes the REFUSED response before its body is read, so an adapter can take a fact off the
+     * headers that the normalized error does not carry onward.
+     *
+     * The one caller is codex's quota manager, and the reason it needs this door rather than the
+     * `retry` event is finding I1: `retry.retryDelayMs` is `Retry-After` only when the backend sent
+     * one, and is Winter's own jittered backoff otherwise — so reading the window off the event
+     * fabricated a subscription reset time out of local jitter. This hands over the header itself,
+     * present or absent.
+     */
+    onRefused?: (response: Response) => void;
+}
+/**
+ * Opens a streaming POST under the retry policy, and returns the response whose body the caller will
+ * consume.
+ *
+ * `policy.commit()` is called by the CALLER, the moment it consumes the first byte — not here.
+ * Committing at header time would forbid retrying a 503 that arrived with headers and no body, and
+ * committing never would allow replaying a turn whose tool call the caller already executed. The
+ * first byte is the line WS-13 §13 actually draws.
+ */
+export declare function openStream(plan: StreamingRequestPlan, policy: RetryPolicy, onEvent: (event: ProviderEvent) => void): Promise<Response>;
+/** Reads an error response's body (bounded by `boundedFetch` already) and normalizes it. Never logs the body. */
+export declare function httpErrorFrom(response: Response): Promise<ProviderRequestError>;
+/** Turns anything thrown during a turn into the `error` event the fold converts to a `ProviderTurnError`. */
+export declare function errorEvent(err: unknown): Extract<ProviderEvent, {
+    type: "error";
+}>;
+export declare function makeRetryPolicy(options: OpenAiAdapterOptions): RetryPolicy;
+/**
+ * `GET {base}/models`, paged.
+ *
+ * BOUNDED THREE WAYS and none of them is advisory: `boundedFetch` caps the bytes of each page at
+ * `ctx.limits.maxBytes`, `MAX_DISCOVERY_PAGES` caps the hops, and `ctx.limits.maxItems` caps the
+ * rows. `partial: true` whenever a bound stopped the walk — the caller must never read a truncated
+ * list as "these are all the models that exist" (which, for an authoritative provider, would read
+ * the absent ones as removed).
+ *
+ * Sanitisation, dedup and malformed-row rejection are `discoverModels`'s, deliberately: this
+ * function's job is to fetch honestly, and having two places decide what a valid model id is, is how
+ * they drift.
+ */
+export declare function fetchOpenAiModels(ctx: DiscoveryContext, endpoint: ResolvedEndpoint, headers: Record<string, string>, options: OpenAiAdapterOptions, 
+/** Query parameters every discovery page must carry (Azure's mandatory `api-version`). */
+extraQuery?: Record<string, string>): Promise<ModelCatalogResult>;
+/** One `/v1/models` row -> the catalog-result shape. Untrusted: nothing here is interpolated anywhere, and `discoverModels` does the validation. */
+export declare function rowToModel(row: unknown): ModelCatalogResult["models"][number];
+/**
+ * The family's shared `validateCredential`: a bounded `GET /models` with the credential attached.
+ *
+ * `unsupported` means the adapter cannot CHECK this ref kind — never that the credential is bad. A
+ * `none` ref against a non-local endpoint is `missing`, which is the actionable answer.
+ */
+export declare function validateViaModels(ref: CredentialRef, ctx: ProviderContext, endpoint: ResolvedEndpoint, headers: Record<string, string>, options: OpenAiAdapterOptions, hasCredential: boolean, 
+/** Query parameters the probe must carry. Azure rejects EVERY call without `api-version`, so omitting it made a valid key report as unreachable. */
+extraQuery?: Record<string, string>): Promise<CredentialStatus>;
+/** `[DONE]` is an OpenAI-family convention rather than an SSE one, so `parseSse` passes it through and the adapter recognises it here. */
+export declare function isStreamTerminator(data: string): boolean;
+/** Parses one SSE `data:` payload. A junk frame is tolerated (returns `undefined`) — forward compatibility, and providers do emit them. */
+export declare function parseSseJson(data: string): Record<string, unknown> | undefined;

package/dist/adapters/openai/testing.d.ts

@@ -0,0 +1,59 @@
+import type { CapabilityEvidence, WinterModelDescriptor } from "@yanlinglabs/winter-provider-catalog";
+import type { CredentialRef, DiscoveryContext, ProviderContext, ProviderEvent } from "../../types.js";
+export declare const TEST_API_KEY = "test-key-openai-0000";
+export declare function evidence<T>(value: T, confidence?: CapabilityEvidence<T>["confidence"]): CapabilityEvidence<T>;
+export interface DescriptorOverrides {
+    key?: string;
+    providerId?: string;
+    upstreamId?: string;
+    efforts?: string[];
+    defaultEffort?: string;
+    readableState?: "none" | "summary" | "full-exposed";
+    summaryValues?: string[];
+    maxOutputTokens?: number;
+    unsupportedParameters?: string[];
+    toolCalling?: "native" | "emulated" | "none";
+    continuationDomain?: string[];
+    continuation?: "none" | "plaintext" | "opaque-provider-state" | "server-response-handle";
+    noReasoning?: boolean;
+    inputModalities?: string[];
+    parallelTools?: boolean;
+}
+/** A descriptor shaped like the seed catalog's rows, with only the fields a fixture cares about varied. */
+export declare function descriptor(overrides?: DescriptorOverrides): WinterModelDescriptor;
+export interface TestContextOptions {
+    providerId?: string;
+    baseUrl?: string;
+    local?: boolean;
+    headers?: Record<string, string>;
+    deployment?: string;
+    apiVersion?: string;
+    authRef?: CredentialRef;
+    apiKey?: string | null;
+    stallTimeoutMs?: number;
+    logs?: Array<{
+        kind: string;
+        providerId: string;
+        model?: string;
+        bytes?: number;
+    }>;
+}
+export declare function testContext(opts?: TestContextOptions): ProviderContext;
+export declare function testDiscoveryContext(opts?: TestContextOptions & {
+    maxItems?: number;
+    maxBytes?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): DiscoveryContext;
+/** A retry policy that never actually waits — one tick is enough for the observation pump to run, and a real backoff would eat a test budget. */
+export declare const FAST_RETRY: {
+    maxRetries: number;
+    random: () => number;
+    sleep: (_ms: number) => Promise<void>;
+};
+/** Drains an adapter stream. The events, in order, exactly as a consumer would see them. */
+export declare function collect(stream: AsyncIterable<ProviderEvent>): Promise<ProviderEvent[]>;
+/** The single `error` event a refused turn produces, or a failure naming what came instead. */
+export declare function soleError(events: ProviderEvent[]): Extract<ProviderEvent, {
+    type: "error";
+}>;

package/dist/adapters/openai/xai-derived-shapes.d.ts

@@ -0,0 +1,67 @@
+/** `github.com/xai-org/grok-build`, Apache-2.0, at the commit the capture pinned. Recorded in the repository-root `NOTICE`. */
+export declare const DERIVED_XAI_COMMIT = "72a61251fcffb464bcc687aeb5a998e5a98ec0c9";
+/**
+ * The xAI OAuth constants as the vendor's own public client states them.
+ *
+ * Cross-checked, where possible, against a SECOND independent artifact: the authorization server's
+ * own discovery document at `https://auth.x.ai/.well-known/openid-configuration`, which names the
+ * same device-authorization and token endpoints and lists `none` among its supported token-endpoint
+ * auth methods — i.e. confirms the client is public and secret-less.
+ */
+export declare const DERIVED_XAI: {
+    /** capture §2 — `auth/config.rs:250`. Published in Apache-2.0 source; `obfstr!`-wrapped in the shipped binary, which is binary hardening, not a secret. */
+    readonly clientId: "b1a00492-073a-47ea-816f-4c329264a828";
+    /** capture §2 — `auth/config.rs:122`. */
+    readonly issuer: "https://auth.x.ai";
+    /** capture §2 — `auth/config.rs:14-27`, frozen by the vendor client's own contract test at `config.rs:426-446`. All ten, unchanged: see capture §5.3 for why Winter does not narrow them. */
+    readonly scope: "openid profile email offline_access grok-cli:access api:access conversations:read conversations:write workspaces:read workspaces:write";
+    /** capture §2/§3.1 — `auth/config.rs:118-120,150` and `auth/device_code.rs:145`. The form field the flow carries a client identity in. */
+    readonly identityField: "referrer";
+    /** capture §2 — the value the VENDOR's client sends in that field. Winter sends its own name instead (capture §5.2); this is here so a reader can see the difference the codex shape turns on. */
+    readonly vendorIdentityValue: "grok-build";
+    /** capture §2/§3.1 — `auth/device_code.rs:132`, confirmed by the discovery document's `device_authorization_endpoint`. */
+    readonly deviceCodeUrl: "https://auth.x.ai/oauth2/device/code";
+    /** capture §2/§3.2 — `auth/device_code.rs:199`, confirmed by the discovery document's `token_endpoint`. */
+    readonly tokenUrl: "https://auth.x.ai/oauth2/token";
+    /**
+     * capture §4 — where an OAuth/subscription bearer is actually spent.
+     *
+     * NOT `https://api.x.ai/v1`, which the task brief and WS-13b §2 both name: that is the METERED,
+     * api-key surface (lane X2's separate `xai` row). This one is the proxy the vendor's own
+     * installers default to and the host whose 401s report `auth_kind=bearer`. Pointing a
+     * subscription token at the metered endpoint either fails to authenticate or bills a user for
+     * traffic their subscription already covers.
+     */
+    readonly apiBaseUrl: "https://cli-chat-proxy.grok.com/v1";
+    /**
+     * capture §3.4 — the vendor client's OWN identity and telemetry headers, ALL SIX.
+     *
+     * Recorded so they can be asserted ABSENT, on the login path and the generation path alike.
+     * WS-13 §5: client-identity headers are never imported; Winter adapters author their own. This
+     * list is a DENYLIST for Winter's requests, never a template for them.
+     *
+     * The last two are the ones that matter most, and they are not telemetry: the vendor's client
+     * injects `X-XAI-Token-Auth: xai-grok-cli` and `x-authenticateresponse` **only when the base URL
+     * is the cli-chat-proxy** — i.e. exactly the endpoint this row uses — and `xai-grok-cli` is a
+     * first-party product identity Winter may not send. If the proxy REQUIRES it, this row's
+     * inference path is closed to an honest client. See capture §3.4 and the inference-path reversion
+     * condition in §7.
+     */
+    readonly vendorOnlyHeaders: readonly ["x-grok-client-version", "x-grok-client-surface", "x-grok-client-identifier", "x-grok-client-mode", "x-xai-token-auth", "x-authenticateresponse"];
+};
+/**
+ * The models the vendor's subscription client offers, from its own catalogue
+ * (`xai-grok-models/default_models.json`) — capture §6.
+ *
+ * Deliberately unpriced: this row is subscription-priced, and a per-token price on it would
+ * misreport cost for traffic that is not metered.
+ */
+export declare const DERIVED_XAI_MODELS: readonly [{
+    readonly id: "grok-4.6";
+    readonly contextWindow: 500000;
+    readonly isDefault: true;
+}, {
+    readonly id: "grok-4.5";
+    readonly contextWindow: 500000;
+    readonly isDefault: false;
+}];

package/dist/adapters/openai/xai-oauth.d.ts

@@ -0,0 +1,102 @@
+import type { CredentialRef, CredentialStore, ProviderAdapter } from "../../types.js";
+import { type ChatTurnOptions } from "./chat-completions.js";
+/** The registered adapter id. One provider, so it is a constant rather than an option. */
+export declare const XAI_OAUTH_ADAPTER_ID = "winter.xai-oauth";
+/**
+ * The flow's constants, as SHIPPED.
+ *
+ * Stated as independent literals rather than read out of `DERIVED_XAI`, so that the constants test
+ * compares two things instead of one thing with itself. If you change a value here, re-run the
+ * capture and change `xai-derived-shapes.ts` too — the test is there to make that unavoidable.
+ */
+export declare const XAI_OAUTH: {
+    /** xAI's public client. Secret-less: the authorization server advertises `none` among its token-endpoint auth methods. */
+    readonly clientId: "b1a00492-073a-47ea-816f-4c329264a828";
+    /** The vendor client's own frozen ten-scope set, unchanged (capture §5.3 records why it is not narrowed, and what the live gate should try). */
+    readonly scope: "openid profile email offline_access grok-cli:access api:access conversations:read conversations:write workspaces:read workspaces:write";
+    /** The form field this flow carries a client identity in. */
+    readonly identityField: "referrer";
+    /**
+     * DOCUMENTATION ONLY as of P7a (fix r1, Minor-3): the DEFAULT profile's token, kept so this row
+     * still SHOWS what it sends. Nothing reads it — all three wire sites below read
+     * `activeWinterIdentity().product`, which is the running brand's own name.
+     *
+     * What it documents is the whole of what makes this row admissible rather than impersonation: the
+     * bare product name (not `winterUserAgent()`'s versioned token) in an originator field a vendor's
+     * analytics buckets, the same shape as codex's own `originator`. It is never the vendor's value,
+     * and it is never omitted — see the reversion condition below for what it means if that turns out
+     * not to be allowed. A future edit here changes NOTHING on the wire; change the brand profile.
+     */
+    readonly identityValue: string;
+    readonly deviceCodeUrl: "https://auth.x.ai/oauth2/device/code";
+    readonly tokenUrl: "https://auth.x.ai/oauth2/token";
+    /**
+     * Where a subscription bearer is actually spent.
+     *
+     * NOT `https://api.x.ai/v1`. That is xAI's METERED, api-key surface and it belongs to the separate
+     * token-priced `xai` row. This one is the proxy the vendor's own installers default to, the host
+     * its 401s report `auth_kind=bearer` from, and the one the `grok-cli:access` scope is described as
+     * authorizing. Pointing a subscription token at the metered endpoint either fails to authenticate
+     * or bills the user for traffic their subscription already covers.
+     */
+    readonly apiBaseUrl: "https://cli-chat-proxy.grok.com/v1";
+};
+/**
+ * What a host must tell the user on the connect screen, before the browser opens.
+ *
+ * Audit §2.5's disclosure note. Because the flow rides xAI's shared public client, the consent page
+ * may name the vendor's own product rather than Winter. That is structurally identical to Codex
+ * OAuth and is not impersonation by Winter — Winter names itself in the flow and on every request —
+ * but it IS a user-facing misattribution, and a user who is not told will reasonably read it as one.
+ * Exported rather than hard-coded into a UI so every host says the same thing.
+ */
+export declare const XAI_CONSENT_DISCLOSURE: string;
+/** How an xAI credential is stored: one `oauth` material under `xai-oauth:<accountId>` (R6-10, one record per provider/account). */
+export declare function xaiCredentialRef(accountId: string, service?: string): Extract<CredentialRef, {
+    kind: "keychain";
+}>;
+export interface XaiLoginOptions {
+    /** Overridden by a fixture; production uses `XAI_OAUTH`'s own values. */
+    deviceCodeUrl?: string;
+    tokenUrl?: string;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    /** The Keychain service the record lands in — `config.keychainService` from the host. */
+    service?: string;
+    onAuthStatus?: (status: {
+        isAuthenticating: boolean;
+        output?: string[];
+        error?: string;
+    }) => void;
+}
+export interface XaiLoginResult {
+    ref: Extract<CredentialRef, {
+        kind: "keychain";
+    }>;
+    accountId: string;
+    expiresAt: number;
+}
+/**
+ * The host-invoked login. Runs the device authorization grant and PERSISTS the result through the
+ * credential store, returning the ref a session should be configured with.
+ *
+ * The identity field rides the device request and every poll (the shared helper's rule, and a
+ * deliberate superset of what the vendor's own client does — capture §5.1). There is no code path
+ * here that retries without it.
+ */
+export declare function startXaiLogin(store: CredentialStore, options?: XaiLoginOptions): Promise<XaiLoginResult>;
+export interface XaiAdapterOptions extends Omit<ChatTurnOptions, "generatedBaseUrl" | "organization" | "project"> {
+    generatedBaseUrl?: string;
+    /** Overridden by a fixture; production uses `XAI_OAUTH.tokenUrl`. */
+    tokenUrl?: string;
+}
+/**
+ * `winter.xai-oauth` — the chat adapter, at xAI's subscription proxy, on an oauth bearer.
+ *
+ * A composition rather than a copy, and deliberately so: everything about the TURN is
+ * `openai-chat-completions@1`'s, and `resolveAuth` already turns `oauth` material into
+ * `Authorization: Bearer <accessToken>`. What differs is the endpoint, the id the registry resolves
+ * it by, and the refresh above — so only those are restated. Copying the turn would have given this
+ * row its own drifting version of streaming, tool-call mapping and error classification for no gain.
+ */
+export declare function createXaiOauthAdapter(options: XaiAdapterOptions): ProviderAdapter;

package/dist/adapters/openai/xai-oauth.testing.d.ts

@@ -0,0 +1,62 @@
+/** Only what an assertion needs. Header names are lowercased; an `authorization` value would be redacted, though these two endpoints carry none. */
+export interface XaiRecordedRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    /** Raw form body. Bodies are not redacted: the body is exactly what the identity assertions are about. */
+    body: string;
+}
+export interface XaiOauthFake {
+    deviceCodeUrl: string;
+    tokenUrl: string;
+    requests: XaiRecordedRequest[];
+    close(): Promise<void>;
+}
+export interface XaiChatFake {
+    /** The base URL a `generatedBaseUrl` points at. */
+    url: string;
+    requests: XaiRecordedRequest[];
+    /**
+     * Whether the bearer this fake actually received was the REFRESHED one.
+     *
+     * Observed here rather than asserted from the recorded header, because `requests` redacts an
+     * `authorization` value to `Bearer ***` — which makes "the turn carried the new token" untestable
+     * from the outside. Comparing inside the fake and exposing one boolean keeps the token out of the
+     * transcript while still making the claim falsifiable.
+     */
+    sawFreshBearer: boolean;
+    close(): Promise<void>;
+}
+export interface XaiOauthFakeOptions {
+    /**
+     * When the identity field arrives carrying THIS value, the token endpoint answers `access_denied`
+     * — the vendor refusing an agent it does not recognise.
+     *
+     * It answers at the TOKEN endpoint, not the device endpoint, and that is deliberate rather than
+     * convenient: RFC 8628 §3.5 is where `access_denied` lives, the device-authorization response
+     * (§3.2) carries the RFC 6749 §5.2 set instead, and a real authorization server decides a consent
+     * question when the authorization is finalized rather than when a code is minted. The device
+     * endpoint still validates the field — it refuses a request that OMITS it (see below).
+     */
+    rejectIdentity?: string;
+    /** How many polls answer `authorization_pending` before the token arrives. Default 0. */
+    pendingPolls?: number;
+    /** An ordinary terminal failure from the token endpoint (`expired_token`, …) — the negative that keeps `rejectIdentity` meaningful. */
+    tokenError?: string;
+    /** Omit the id token from the successful response, so the caller has no account id to name a record with (R6-10). */
+    omitIdToken?: boolean;
+}
+/** What the token endpoint answers a `refresh_token` grant with. Named so the chat fake and the tests agree on it without re-spelling the literal. */
+export declare const REFRESHED_ACCESS_TOKEN = "test-token-xai-access-refreshed";
+/**
+ * A minimal `/chat/completions` double, so a REFRESH test can prove the turn that followed carried
+ * the new token.
+ *
+ * Deliberately tiny rather than a second copy of the conformance chat fake: the only questions asked
+ * of it are "did a turn happen" and "what did it carry", and the full corpus fake lives on the other
+ * side of a dependency direction this package cannot import across.
+ */
+export declare function startXaiChatFake(opts?: {
+    freshBearer?: string;
+}): Promise<XaiChatFake>;
+export declare function startXaiOauthFake(opts?: XaiOauthFakeOptions): Promise<XaiOauthFake>;