@yanlinglabs/winter-provider-runtime 0.0.2

package/dist/credentials/file.d.ts

@@ -0,0 +1,21 @@
+import type { CredentialStore } from "../types.js";
+export interface FileCredentialStoreOptions {
+    env: Record<string, string | undefined>;
+    /** The home directory the default `~/.aws/credentials` location resolves under. Injected so a test never reads the real one. */
+    home: string;
+    /** Reads a file as UTF-8, or rejects. Injectable for tests that want to simulate an IO failure without creating one. */
+    readFile?: (path: string) => Promise<string>;
+    /**
+     * Returns a file's size in bytes, or rejects. Defaults to `node:fs/promises` `stat`.
+     *
+     * Its job is to make the size cap bound what is PULLED INTO MEMORY rather than only what is kept:
+     * checking the length after reading means a multi-gigabyte file addressed by a `{ kind: "file" }`
+     * ref is fully buffered first and rejected second. A custom `readFile` with no matching `stat`
+     * skips the pre-check — the post-read cap still applies — because a test double's "file" has no
+     * size to ask about.
+     */
+    stat?: (path: string) => Promise<{
+        size: number;
+    }>;
+}
+export declare function createFileCredentialStore(opts: FileCredentialStoreOptions): CredentialStore;

package/dist/credentials/memory.d.ts

@@ -0,0 +1,8 @@
+import type { CredentialMaterial, CredentialRef, CredentialStore } from "../types.js";
+export interface MemoryCredentialStore extends CredentialStore {
+    /** Test/diagnostic seam: how many records are held. Never exposes material. */
+    size(): number;
+}
+export declare function createMemoryCredentialStore(seed?: Iterable<readonly [Extract<CredentialRef, {
+    kind: "keychain";
+}>, CredentialMaterial]>): MemoryCredentialStore;

package/dist/credentials/types.d.ts

@@ -0,0 +1,38 @@
+import type { CredentialMaterial, CredentialRef, CredentialStore } from "../types.js";
+export type CredentialResolutionCode = "unsupported" | "malformed" | "io";
+/**
+ * A typed credential failure. **Its message never contains credential material** — construct it from
+ * a locator (`redactRef`) and a reason, never from a file's contents or a parsed value. The stores
+ * in this directory are tested for exactly that (`credentials.test.ts` asserts a malformed-file
+ * error's message does not contain the file's secret).
+ */
+export declare class CredentialResolutionError extends Error {
+    readonly code: CredentialResolutionCode;
+    constructor(code: CredentialResolutionCode, message: string);
+}
+/**
+ * Renders material for a log line or an error message: the KIND, and `***` where the material was.
+ * The one sanctioned way to put a `CredentialMaterial` into a string anywhere in Winter.
+ */
+export declare function redactMaterial(material: CredentialMaterial): string;
+/**
+ * Renders a reference for a log line or an error message. A ref is a LOCATOR, so its addressing
+ * fields (variable name, keychain account/service, file path) are kept — they are what makes a
+ * "credential not found" message actionable. `inline` is the one arm that carries material, and its
+ * value is replaced.
+ */
+export declare function redactRef(ref: CredentialRef): string;
+/** Every store answers `none` identically: null, meaning "send no credential". Shared so no store can drift on it. */
+export declare function isNoCredential(ref: CredentialRef): boolean;
+export declare function unsupported(storeName: string, ref: CredentialRef): CredentialResolutionError;
+/** A store that cannot write: `set`/`delete` are Keychain-only, and only a Keychain-backed store implements them. */
+export declare function readOnlyWriteRefusal(storeName: string): CredentialResolutionError;
+/**
+ * Chains stores: the first one that HANDLES the ref kind answers, whether it found material or not.
+ *
+ * The subtlety worth stating (and tested): a handled-but-empty `null` STOPS the chain. Falling
+ * through on null would mean a configured-but-empty env var silently resolved out of some later
+ * store — a credential arriving from a source the host never named, which is exactly what R6-10's
+ * "ambient keys are NEVER scanned implicitly" forbids.
+ */
+export declare function createCompositeCredentialStore(stores: readonly CredentialStore[]): CredentialStore;

package/dist/discovery.d.ts

@@ -0,0 +1,15 @@
+import type { DiscoveryContext, ModelCatalogResult, ProviderAdapter } from "./types.js";
+export interface DiscoveryCache {
+    get(key: string): ModelCatalogResult | undefined;
+    set(key: string, value: ModelCatalogResult): void;
+}
+/** A plain in-memory cache. Process-lifetime, no expiry — the caller decides when a cache is stale by choosing whether to pass one. */
+export declare function createDiscoveryCache(): DiscoveryCache;
+/**
+ * Runs `adapter.listModels` under the context's own bounds, validates and dedupes what comes back,
+ * and falls back to a cached answer when the provider fails.
+ *
+ * A failure with NO cache entry PROPAGATES rather than returning an empty catalog: `{ models: [] }`
+ * reads as "this provider has no models", which a picker would render as fact.
+ */
+export declare function discoverModels(adapter: ProviderAdapter, ctx: DiscoveryContext, cache?: DiscoveryCache): Promise<ModelCatalogResult>;

package/dist/endpoint-policy.d.ts

@@ -0,0 +1,127 @@
+export type EndpointEvaluation = {
+    ok: true;
+    origin: string;
+    local: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface EndpointEvaluationOptions {
+    /** True for a descriptor's own immutable endpoint; false for a user-supplied `baseUrl`. */
+    generated: boolean;
+    /** The host's explicit declaration that this endpoint is a local installation. Only meaningful for a LITERAL local address. */
+    local?: boolean;
+}
+/**
+ * P7a (WS-13b §10, the M-1 partial): HOW a `ConnectionProfile.baseUrl` is evaluated.
+ *
+ * THE PROBLEM THIS CLOSES. Two populations arrive in the same field as byte-identical strings:
+ * the catalog's own reviewed endpoint, COPIED into the profile by the runtime because a
+ * multi-provider adapter has no single vendor default to fall back on; and a host- or user-entered
+ * URL. Unable to tell them apart, every `resolveEndpoint` in this package read a present `baseUrl`
+ * as `generated: false` — so 156 of the catalog's rows silently left the privileged-header path in
+ * production, while adapter fixtures (which pass a generated base URL directly, never through a
+ * profile) went on passing. `endpointOrigin` is the profile's own answer, and this function is the
+ * one place it is read.
+ *
+ * ABSENT IS `"user"`, and that is the whole safety argument: a profile with no marker is one nobody
+ * has vouched for, and the conservative reading of "unknown provenance" is the one that attaches no
+ * organisation, project or account header. A producer that forgets the marker under-privileges a
+ * request; a default of `"reviewed"` would put the operator's account topology on an unreviewed
+ * host. Only the runtime's own copy-from-the-catalog path may stamp `"reviewed"` — a HOST writing
+ * it is asserting a provenance it does not have, which is why the runtime stamps `"user"`
+ * unconditionally over whatever a profile arrived with (`connectionFrom`, session-provider.ts).
+ */
+export declare function connectionEndpointOptions(connection: {
+    local?: boolean;
+    endpointOrigin?: "reviewed" | "user";
+}): EndpointEvaluationOptions;
+/**
+ * Headers that carry (or can carry) a credential and must never survive an origin change, and must
+ * never be attached to a user endpoint that inherited them from a generated one.
+ *
+ * Lowercase; `Headers` matching is case-insensitive but a raw record's is not, so callers compare
+ * against these exact strings.
+ */
+export declare const CREDENTIAL_HEADER_NAMES: readonly string[];
+/** Returns a COPY with every credential-bearing header removed. Never mutates its argument — a caller that reuses the original for a same-origin hop must still have it intact. */
+export declare function stripCredentialHeaders(headers: Headers): Headers;
+/**
+ * RULING R6-L — the enforcement point for R6-11's "privileged headers only for generated endpoints".
+ *
+ * Identity when the policy's endpoint is GENERATED (a reviewed, immutable descriptor endpoint);
+ * `{}` otherwise. Adapters build their privileged header set and route it through here, so the rule
+ * is a call site rather than prose — before this existed, `EndpointPolicy.generated` was plumbed and
+ * read by nothing at all.
+ *
+ * WHICH headers belong here is documented on `EndpointPolicy` below and is the adapter's judgement,
+ * not this function's: it cannot see a header's meaning, only the endpoint's provenance. The rule of
+ * thumb is "would this value still be true, and still be the operator's business to disclose, at a
+ * URL the reviewed catalog never named?" — an organisation or project identifier fails that test; a
+ * `content-type` passes it.
+ *
+ * Auth is deliberately NOT governed here. It has its own, stricter rule (`stripCredentialHeaders` on
+ * an origin change), and a user endpoint legitimately needs a credential to be reachable at all —
+ * routing auth through this helper would break every custom endpoint rather than protect anything.
+ */
+export declare function applyPrivilegedHeaders(policy: EndpointPolicy, headers: Record<string, string>): Record<string, string>;
+/**
+ * Evaluates a STORED endpoint — a descriptor's `defaultEndpoints` entry or a
+ * `ConnectionProfile.baseUrl`.
+ *
+ * Everything `evaluateUrlShape` checks, PLUS a refusal of any query string or fragment. That extra
+ * pair is specific to stored endpoints: a persisted `?key=…` reaches every log line, error message
+ * and telemetry record verbatim, and a fragment is meaningless to a request. Live request URLs and
+ * redirect targets go through `EndpointPolicy.evaluateRedirect` instead, which deliberately does
+ * NOT apply it — see `evaluateUrlShape`'s own header.
+ */
+export declare function evaluateEndpoint(baseUrl: string, opts: EndpointEvaluationOptions): EndpointEvaluation;
+/**
+ * The policy object `boundedFetch` carries: the accepted origin plus the rule a redirect target must
+ * pass before the request follows it.
+ *
+ * PRIVILEGED HEADERS (R6-11, ruling R6-L). `generated` is not decoration — it is the input to
+ * `applyPrivilegedHeaders` below, which is how "privileged headers only for generated endpoints"
+ * stops being prose. The split, stated once so adapters classify consistently:
+ *
+ *   PRIVILEGED — headers a GENERATED descriptor implies and a user endpoint must never inherit:
+ *     organisation / project / account identifiers (`OpenAI-Organization`, `OpenAI-Project`,
+ *     `x-goog-user-project`, an AWS account or role identifier), the codex adapter's `originator`,
+ *     and any header whose value only means something at the reviewed endpoint it was minted for.
+ *     Sending these to a user-supplied base URL discloses the operator's account topology to a host
+ *     the reviewed catalog never named.
+ *
+ *   PROTOCOL — headers EVERY endpoint needs to be spoken to at all, and which carry no
+ *     cross-endpoint meaning: `content-type`, `accept`, `anthropic-version`, `anthropic-beta`,
+ *     `x-goog-api-key`, `authorization` / `x-api-key` / `api-key`. These are NOT routed through
+ *     `applyPrivilegedHeaders`; auth in particular is governed by the separate and stricter
+ *     origin-change rule (`stripCredentialHeaders`), not by this one.
+ */
+export interface EndpointPolicy {
+    readonly origin: string;
+    readonly local: boolean;
+    readonly generated: boolean;
+    /**
+     * Revalidates a redirect target against this policy.
+     *
+     * `sameOrigin: false` is an INSTRUCTION, not a note: the caller MUST strip credential headers
+     * before following it (R6-11 — "no credential forwarding across an origin change"). A redirect
+     * chain is the standard way a compliant client is talked into replaying its bearer token to a
+     * host the user never named.
+     */
+    evaluateRedirect(target: string): {
+        ok: true;
+        origin: string;
+        sameOrigin: boolean;
+    } | {
+        ok: false;
+        reason: string;
+    };
+}
+export declare function createEndpointPolicy(baseUrl: string, opts: EndpointEvaluationOptions): {
+    ok: true;
+    policy: EndpointPolicy;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/errors.d.ts

@@ -0,0 +1,68 @@
+import type { ProviderError, SdkAssistantMessageError } from "./types.js";
+/** A stream that produced no bytes for `providerStallTimeoutMs`. Thrown by `parseSse`; NOT retryable (bytes may already have been consumed — R6-6 forbids replaying an effectful turn). */
+export declare class ProviderStallError extends Error {
+    constructor(message: string);
+}
+/**
+ * Lifts the provider's STRUCTURED error code out of a raw HTTP error body, across the three
+ * dialects Winter speaks. Never throws and never guesses: a non-JSON body (an HTML 502 page), a
+ * body with no envelope, or a non-string value all yield `undefined`.
+ */
+export declare function parseProviderErrorCode(body: string): string | undefined;
+/**
+ * Parses a `Retry-After` header in either RFC 7231 form: delta-seconds, or an HTTP-date.
+ *
+ * Returns `undefined` — never `0` — for anything unusable, including a past date and a
+ * non-positive delta. That distinction matters downstream: `0` reads as "retry immediately", a
+ * different instruction from "the header told us nothing", which must fall through to the computed
+ * backoff.
+ */
+export declare function parseRetryAfterMs(value: string | null | undefined, now?: number): number | undefined;
+/**
+ * Removes EXACT occurrences of a request's OWN credential material from a provider error body.
+ *
+ * HOISTED HERE from the Bedrock adapter (T2 carry), because the gap it closes is not Bedrock's.
+ * `scrubbedSnippet` scrubs a body whose contents `scanForSecrets` RECOGNISES, and that scanner is
+ * pattern-based: it knows `sk-`, `AKIA…`, `AIza…`, a PEM block. What it cannot know is a credential
+ * with no recognisable shape — an AWS SECRET access key is forty base64-ish characters, and no
+ * pattern could match that without matching arbitrary prose of the same length. Such a value echoed
+ * back by an endpoint survives verbatim into `ProviderError.message`, one of the most
+ * reliably-logged strings in the system, and the next family's shapeless token will do the same.
+ *
+ * Exact matching against the material THIS request actually carried is the complement: precise (no
+ * false positives, unlike a "40 base64-ish characters" heuristic) and family-agnostic, because the
+ * caller names its own secrets rather than this file guessing their shape. Belt and braces — the
+ * pattern scan still runs, and either one alone leaves the other's blind spot reachable.
+ */
+export declare function redactCredentialMaterial(text: string, secrets: readonly string[]): string;
+/**
+ * @param secrets Credential material THIS request carried, redacted from the body by exact match
+ *   before the snippet is taken. Optional and empty by default: a family with nothing to declare
+ *   passes nothing and gets exactly the previous behaviour.
+ */
+export declare function normalizeHttpError(status: number, headers: Headers, body: string, secrets?: readonly string[]): ProviderError;
+/** True for anything already shaped as a normalized `ProviderError`. */
+export declare function isProviderError(value: unknown): value is ProviderError;
+/**
+ * Normalizes anything thrown by a transport into a `ProviderError`.
+ *
+ * The two NOT-retryable transport cases are the load-bearing ones: an abort is a deliberate
+ * cancellation (retrying it would resurrect a turn the caller stopped), and a stall means bytes
+ * already flowed — R6-6 forbids replaying an effectful turn once a response has begun.
+ */
+export declare function normalizeThrown(err: unknown): ProviderError;
+/**
+ * Maps a normalized Winter error onto the pin's CLOSED 11-member `SDKAssistantMessageError`
+ * (`sdk.d.ts:3159`) — the value `api_retry.error` and `SDKAssistantMessage.error` carry.
+ *
+ * Two members have NO WINTER PRODUCER and that is recorded rather than faked:
+ * `oauth_org_not_allowed` and `account_on_hold` describe first-party subscription states that a
+ * provider-API session cannot be in. Nothing here ever returns them; if a codex-oauth quota state
+ * ever needs one, it comes from that adapter's own quota manager, not from an HTTP status.
+ *
+ * Transport failures (`network`/`timeout`/`stall`/`aborted`/`capability`) collapse to `unknown`.
+ * The pinned union has no transport member — the pin represents that case with
+ * `api_retry.error_status: null` while `error` still has to be one of the eleven — so `unknown` is
+ * the honest bucket rather than a stretched `server_error`.
+ */
+export declare function toSdkAssistantMessageError(err: ProviderError): SdkAssistantMessageError;

package/dist/http.d.ts

@@ -0,0 +1,29 @@
+import type { ProviderError } from "./types.js";
+import { type EndpointPolicy } from "./endpoint-policy.js";
+/** Following more than this many hops is a loop, not a route. */
+export declare const DEFAULT_MAX_REDIRECTS = 5;
+/**
+ * A `ProviderError` that is also a real `Error` — so it carries a stack, and `normalizeThrown`
+ * passes it through untouched (it satisfies `isProviderError` structurally).
+ */
+export declare class ProviderRequestError extends Error implements ProviderError {
+    readonly code: ProviderError["code"];
+    readonly retryable: boolean;
+    readonly status?: number;
+    readonly providerCode?: string;
+    readonly retryAfterMs?: number;
+    constructor(fields: ProviderError);
+}
+/** Thrown while READING a response body that exceeded `maxBodyBytes`. Not retryable: the peer is oversized, and a retry gets the same oversized answer. */
+export declare class ProviderBodyLimitError extends ProviderRequestError {
+    constructor(maxBodyBytes: number);
+}
+export interface BoundedFetchInit extends Omit<RequestInit, "redirect" | "signal"> {
+    /** Milliseconds allowed for RESPONSE HEADERS to arrive. Cleared once they do. */
+    timeoutMs: number;
+    maxBodyBytes: number;
+    policy: EndpointPolicy;
+    signal?: AbortSignal;
+    maxRedirects?: number;
+}
+export declare function boundedFetch(url: string, init: BoundedFetchInit): Promise<Response>;

package/dist/identity.d.ts

@@ -0,0 +1,62 @@
+import type { WinterCatalog } from "@yanlinglabs/winter-provider-catalog";
+/** The identity tokens a running product puts on the wire. */
+export interface WinterIdentity {
+    /** The product token in `User-Agent` and in a row's `<product>` placeholder — `brand.packageName`. */
+    product: string;
+    /** The codex backend's `originator` — `brand.codexOriginator`, validated never to be first-party. */
+    codexOriginator: string;
+    /**
+     * P7a fix wave (item 7): WHERE TO REACH the running product — a row's `<contact>` placeholder,
+     * `brand.contactUrl`.
+     *
+     * A vendor identity field is a `<name>:<version>:<contact>` triple. `product` moved with the brand
+     * from the day the profile landed; the contact did not, so a rebranded product's honest-identity
+     * header still named Winter's repository — a false statement in the one field whose entire purpose
+     * is being true, and the only part of it a vendor would actually act on.
+     */
+    contactUrl: string;
+}
+/** What this process is currently presenting as. Winter's own values until a branded session sets it. */
+export declare function activeWinterIdentity(): Readonly<WinterIdentity>;
+/**
+ * Install a session's identity; the returned disposer withdraws THIS session's frame.
+ *
+ * The value in force is the innermost frame still installed, so overlapping sessions unwind
+ * correctly in ANY order (see `IDENTITY_FRAMES`). Idempotent: a second call on the same disposer
+ * does nothing, so a host that disposes twice cannot pop somebody else's frame.
+ */
+export declare function setWinterIdentity(next: WinterIdentity): () => void;
+/**
+ * `<product>/<version>` — the `User-Agent` every adapter family sends.
+ *
+ * Never an editor, a vendor CLI or a first-party product identity (WS-13 §5, D21). Where a vendor
+ * names a second identity field (aihorde's `Client-Agent`, the codex backend's `originator`), that
+ * field carries the running product's name too; it never carries somebody else's.
+ */
+export declare function winterUserAgent(): string;
+/** A row id -> the Winter-authored identity headers that row's vendor names. Built once per adapter registration. */
+export type IdentityHeaderLookup = (providerId: string) => Record<string, string> | undefined;
+/** What a row's identity-header value is rendered against: this build's version, and this run's product and contact. */
+export interface IdentityRenderContext {
+    version: string;
+    product: string;
+    contact: string;
+}
+/**
+ * Substitutes ALL THREE placeholders in one row's declared identity headers.
+ *
+ * The seam Lane A needs, extracted from `winterIdentityHeaders` so the brand can be threaded in one
+ * place: everything about WHICH headers a row declares stays in the lookup, and everything about
+ * WHAT the tokens resolve to arrives here as data. A caller with no brand still gets today's answer.
+ */
+export declare function renderIdentityHeaders(declared: Record<string, string>, ctx: IdentityRenderContext): Record<string, string>;
+/** Indexes a catalog's `identityHeaders` by provider id. Rows without any are simply absent. */
+export declare function identityHeaderLookup(catalog: WinterCatalog): IdentityHeaderLookup;
+/**
+ * The identity headers for one row, with `<product>`, `<version>` and `<contact>` substituted — or `{}`.
+ *
+ * `{}` for a row with none, for an adapter constructed without a lookup (every unit fixture), and
+ * for an unknown id. An absent second identity field is the normal case: only a vendor that NAMES
+ * one gets one.
+ */
+export declare function winterIdentityHeaders(lookup: IdentityHeaderLookup | undefined, providerId: string): Record<string, string>;