@yanlinglabs/winter-provider-runtime 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yanlingLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,41 @@
+NOTICE
+======
+
+Third-party attributions for the Winter agent SDK.
+
+This file records material that Winter DERIVED FROM third-party artifacts. Winter copies no source
+code from any of them; what it takes is protocol facts — endpoint URLs, form-field names, client
+identifiers and scope strings — which it needs in order to speak to a vendor's service at all. Each
+entry names the exact commit the values were read at, so the derivation is re-checkable.
+
+
+-------------------------------------------------------------------------------
+xai-org/grok-build
+-------------------------------------------------------------------------------
+
+    Repository:  https://github.com/xai-org/grok-build
+    Commit:      72a61251fcffb464bcc687aeb5a998e5a98ec0c9
+    License:     Apache License, Version 2.0
+                 https://www.apache.org/licenses/LICENSE-2.0
+    Copyright:   Copyright 2023-2026 SpaceXAI
+
+Winter's `xai-oauth` provider derives the following constants and request shapes from this
+repository's authentication module, in order to perform its own OAuth 2.0 device authorization
+grant (RFC 8628) against xAI's public, secret-less OAuth client:
+
+  - the public OAuth client identifier
+  - the OAuth issuer, device-authorization endpoint and token endpoint
+  - the requested scope set
+  - the name of the form field the flow carries a client identity in
+  - the shape (field names) of the device-authorization and token requests
+
+No source code from this repository is copied into Winter, and no part of Winter is a derivative
+work of it. The derivation is recorded, with per-value line citations, in:
+
+    packages/conformance/compat/xai/grok-build/derived-shapes-p6b-xai.md
+
+Winter identifies ITSELF in that flow. It sends its own `User-Agent` (`winter-agent-sdk/<version>`)
+and its own name in the flow's identity field, and it does not send xAI's product-identity or
+telemetry headers. Winter is not affiliated with or endorsed by SpaceXAI, and "Grok" and "Grok Build"
+are the marks of their owner; they appear here and in the capture solely to identify the artifact
+these values were derived from.

package/README.md

@@ -0,0 +1,109 @@
+# `@yanlinglabs/winter-provider-runtime`
+
+Winter's provider layer: the adapter registry, the shipped provider adapters (OpenAI Responses and
+Chat Completions, Anthropic Messages, Google generateContent, Bedrock Converse, the OAuth-backed
+codex/xAI/Console flows), the credential-ref surface, endpoint policy, retry/stall handling and the
+honest-identity headers every request carries.
+
+This package is published to GitHub Packages under restricted access (`@yanlinglabs` scope). The
+registry is chosen by the release workflow, not by a committed pin — see [RELEASING.md](https://github.com/yanlingLabs/winter-agent-sdk/blob/main/RELEASING.md).
+
+## What it ships
+
+| Import | What it is |
+| --- | --- |
+| `@yanlinglabs/winter-provider-runtime` | The full barrel: the registry, the adapters, credential refs and stores, endpoint policy, the error taxonomy, and the identity surface. |
+| `@yanlinglabs/winter-provider-runtime/testing` | Test-support helpers a consumer's own adapter tests need: descriptor/context builders, the SigV4 and event-stream primitives, the loopback OAuth/chat fakes, and the fixture catalog. |
+
+## Install
+
+Published to **both** registries — but not because a consumer of the wrapper needs it. The wrapper
+`@yanlinglabs/winter-agent-sdk` SPAWNS the compiled `winter` runtime rather than importing this
+package, so `npm install @yanlinglabs/winter-agent-sdk` does not pull it in. It is on public npm
+because `@yanlinglabs/winter-provider-conformance` — a harness the out-of-repo router package uses as
+a dev dependency — imports it, and a published manifest pins its dependencies at an exact version: a
+harness on npm whose own dependency is not there is an install that 404s.
+
+### From public npm (anyone)
+
+```sh
+npm install @yanlinglabs/winter-provider-runtime
+```
+
+Nothing else is needed: the `@yanlinglabs` scope is public on npm.
+
+### From GitHub Packages (the `yanlingLabs` org)
+
+GitHub Packages needs the scope pointed at it and an authenticated read, even for a public package.
+In your project's `.npmrc`:
+
+```
+@yanlinglabs:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+…with `GITHUB_TOKEN` in the environment — a personal access token carrying `read:packages`, never a
+literal in the file. Then `npm install @yanlinglabs/winter-provider-runtime` as usual.
+
+**The published packages contain COMPILED OUTPUT ONLY.** Each tarball ships `dist/` — the bundled
+JavaScript a consumer imports and the `.d.ts` declarations their type-checker reads — plus its data
+files, `README.md` and `LICENSE`. It does **not** ship `src/`: the TypeScript sources live at
+<https://github.com/yanlingLabs/winter-agent-sdk>, which is where to read them, file an issue, or send
+a patch.
+
+## Bun-only surface
+
+This package declares `engines.node` and every entry point **imports** cleanly under Node 18+ (the
+compiled emit under `dist/` is what a non-Bun runtime resolves, via each export's `default`
+condition; Bun resolves the `bun` condition and gets the TypeScript source unchanged). Importable is
+not the same as runnable on every path — these exports need the Bun runtime:
+
+| Function | Import | Needs | Why |
+| --- | --- | --- | --- |
+| `startCodexLogin()` | `@yanlinglabs/winter-provider-runtime` | `Bun.serve` | The authorization-code flow receives the vendor's redirect on `127.0.0.1`, which needs a real HTTP listener. |
+| `startAnthropicConsoleLogin()` | `@yanlinglabs/winter-provider-runtime` | `Bun.serve` | Same flow, same listener. |
+| `startXaiOauthFake()` | `@yanlinglabs/winter-provider-runtime/testing` | `Bun.serve` | Binds a loopback server on `127.0.0.1:0` to stand in for the vendor. |
+| `startXaiChatFake()` | `@yanlinglabs/winter-provider-runtime/testing` | `Bun.serve` | Same. |
+
+(Internally all four go through one `runLoginFlow`/`Bun.serve` seam, which is not on either barrel
+and which a consumer cannot call.)
+
+Each throws `BunRequiredError` (exported from both barrels) as its FIRST action — before any network
+call, file write or credential read — naming the function, the Bun API and what to do instead. Catch
+it by identity:
+
+```ts
+import { startCodexLogin, BunRequiredError } from "@yanlinglabs/winter-provider-runtime";
+
+try {
+  await startCodexLogin(store, options);
+} catch (err) {
+  if (err instanceof BunRequiredError) {
+    // Complete the login in a Bun process, then pass the resulting credential ref to this session.
+  }
+  throw err;
+}
+```
+
+### `BunRequiredError` is THIS package's own class
+
+`@yanlinglabs/winter-conformance` exports a class with the same name and shape, and the two are
+deliberately **not** the same type — the packages share no dependency, so there is no module either
+could import it from. **Catch the one you imported.** Within this package it is one type across every
+subpath: an error thrown by `./testing`'s fakes satisfies `instanceof BunRequiredError` imported from
+the main barrel, and vice versa, under Node as well as Bun (the compiled emit gives each export entry
+its own bundle, so the class carries a package-scoped `Symbol.for` brand to make that hold).
+
+**`startXaiLogin()` is NOT on this list**, deliberately: xAI's login is RFC 8628 device-code, which is
+`fetch` and polling only — no listener, no spawn — so it runs under Node like the rest of the package.
+
+Everything else — the registry, every adapter's `streamTurn`, discovery, the credential stores, the
+endpoint policy and the identity helpers — is plain Node-compatible code over `fetch` and `node:*`.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE), which ships in the published tarball.
+
+This package's xAI OAuth provider derives its client id, endpoints, scope set and request field names
+from the Apache-2.0 licensed `xai-org/grok-build`; that attribution is in [`NOTICE`](./NOTICE), which
+ships in the tarball beside this file.

package/dist/adapters/anthropic/console-oauth.d.ts

@@ -0,0 +1,101 @@
+import type { CredentialRef, CredentialStore } from "../../types.js";
+/**
+ * The Console OAuth constants, derived from `@anthropic-ai/claude-agent-sdk@0.3.250`.
+ *
+ * Pinned field-by-field against `compat/anthropic/0.3.250/derived-p6b.ts`. Note what is NOT here:
+ * the consumer authorize host, the consumer origin, the two `claude_cli`-scoped endpoints, and the
+ * vendor's own product beta. A constant that exists is a constant something can come to use, so the
+ * excluded ones live only in the capture document, as a record of the exclusion.
+ */
+export declare const CONSOLE_OAUTH: {
+    /** A PUBLIC PKCE client id from a public npm artifact — there is no client secret, and none is sent. */
+    readonly clientId: "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+    readonly authorizeUrl: "https://platform.claude.com/oauth/authorize";
+    readonly tokenUrl: "https://platform.claude.com/v1/oauth/token";
+    /** The account id is NOT in the token response; it is read from here, as `account.uuid`. */
+    readonly profileUrl: "https://api.anthropic.com/api/oauth/profile";
+    readonly scope: "user:inference user:profile";
+    /**
+     * `0` — an ephemeral port, and the DERIVED value rather than a test convenience. This client's
+     * registration accepts a loopback URI on any port; codex's fixed 1455/1457 pair is the opposite
+     * case, and copying that shape here would bind a port for no reason and fight a concurrent login.
+     */
+    readonly callbackPort: 0;
+    readonly callbackPath: "/callback";
+    /** The `anthropic-beta` value that accompanies an OAuth bearer on every request. */
+    readonly betaHeader: "oauth-2025-04-20";
+    /**
+     * The profile-response field that names the credential record, as a dotted path.
+     *
+     * Present so that EVERY field of the capture's derived table has a counterpart here and the
+     * constants test gates all nine — a derived value with no shipped twin is a value nothing stops
+     * from drifting. `fetchAccountId` reads exactly this path; it is stated rather than walked because
+     * one fixed shape does not need a path interpreter.
+     */
+    readonly accountIdPath: "account.uuid";
+};
+/** How long before expiry a token is renewed rather than used. One minute of slack over a turn that may take seconds to start. */
+export declare const OAUTH_REFRESH_WINDOW_MS = 60000;
+/**
+ * The ONE provider id whose `oauth` credential is an Anthropic Console one.
+ *
+ * NOT A FORMALITY, and the reason it is a named constant rather than a string literal in a
+ * condition: R6b-5 makes this adapter MULTI-PROVIDER — a third party that speaks the Anthropic
+ * Messages dialect ships as its own `<id>-anthropic` row on this same `adapterId`, with its own
+ * `defaultEndpoints.api`. Nothing upstream of the adapter checks that a stored credential's KIND
+ * matches its row's `authKinds`, so without this gate an `oauth` credential stored against a sibling
+ * row would have its REFRESH TOKEN posted to `platform.claude.com` — a third party's credential sent
+ * to Anthropic — and would stamp Anthropic's beta on that third party's request. Both are the same
+ * mistake the `bearer` arm already refuses to make, with a considerably worse failure.
+ */
+export declare const ANTHROPIC_CONSOLE_PROVIDER_ID = "anthropic";
+/**
+ * The ONE spelling of an Anthropic OAuth record's name (R6-10).
+ *
+ * Exported and used by both the login and the adapter, because a host that assembles
+ * `anthropic:<id>` by hand will eventually assemble it differently from whatever reads it — a
+ * credential written to a key nothing looks up, failing as "no credential configured" with the
+ * record sitting right there.
+ */
+export declare function anthropicCredentialRef(accountId: string, service?: string): Extract<CredentialRef, {
+    kind: "keychain";
+}>;
+export interface AnthropicConsoleLoginOptions {
+    /** Opens the browser. HOST-supplied: the SDK never shells out to one itself. */
+    openUrl: (url: string) => Promise<void>;
+    /** Overridden by a fixture; production uses `CONSOLE_OAUTH`'s own values. */
+    authorizeUrl?: string;
+    tokenUrl?: string;
+    profileUrl?: string;
+    callbackPort?: 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 AnthropicConsoleLoginResult {
+    ref: Extract<CredentialRef, {
+        kind: "keychain";
+    }>;
+    accountId: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+/**
+ * The host-invoked Console login. Runs the PKCE loopback flow, asks who signed in, and PERSISTS the
+ * result through the credential store — returning the ref a session should then be configured with.
+ *
+ * WHY THERE IS A SECOND REQUEST. The token response carries no account of any kind (the capture's
+ * §2.3), so unlike codex — where the id token's own claim names the record — the account id has to
+ * be fetched. `GET /api/oauth/profile` under the new bearer is what the pinned artifact itself does,
+ * and `user:profile` is in the scope precisely to authorise it.
+ *
+ * A LOGIN THAT CANNOT NAME ITS RECORD IS A REFUSAL, not a fallback to some default slot: R6-10 is
+ * explicit that a credential occupies one record per provider/account, and `anthropic:undefined`
+ * would be a shared global slot wearing a per-account name.
+ */
+export declare function startAnthropicConsoleLogin(store: CredentialStore, options: AnthropicConsoleLoginOptions): Promise<AnthropicConsoleLoginResult>;

package/dist/adapters/anthropic/index.d.ts

@@ -0,0 +1,4 @@
+export { ANTHROPIC_ADAPTER_ID, ANTHROPIC_API_VERSION, ANTHROPIC_DEFAULT_BASE_URL, ANTHROPIC_DEFAULT_MAX_TOKENS, createAnthropicMessagesAdapter, findDescriptor, mapAnthropicEffort, toWireMessages, } from "./messages.js";
+export type { AnthropicAdapterOptions, EffortMapping } from "./messages.js";
+export { CONSOLE_OAUTH, OAUTH_REFRESH_WINDOW_MS, anthropicCredentialRef, startAnthropicConsoleLogin } from "./console-oauth.js";
+export type { AnthropicConsoleLoginOptions, AnthropicConsoleLoginResult } from "./console-oauth.js";

package/dist/adapters/anthropic/messages.d.ts

@@ -0,0 +1,76 @@
+import type { WinterCatalog, WinterModelDescriptor } from "@yanlinglabs/winter-provider-catalog";
+import { type RetryPolicyOptions } from "../../retry.js";
+import type { ProviderAdapter, ProviderMessageLike, TurnRequest } from "../../types.js";
+/** The provider id this adapter is registered for, and the catalog's own `adapterId` for it. */
+export declare const ANTHROPIC_ADAPTER_ID = "winter.anthropic-messages";
+/** The GENERATED endpoint. Immutable (R6-11); a user override rides `ConnectionProfile.baseUrl`. Pinned to the catalog row by a test. */
+export declare const ANTHROPIC_DEFAULT_BASE_URL = "https://api.anthropic.com";
+/** The `anthropic-version` header every request carries. A protocol header, never a privileged one (R6-L). */
+export declare const ANTHROPIC_API_VERSION = "2023-06-01";
+/**
+ * The wire `max_tokens` when neither the request nor the descriptor names one.
+ *
+ * DISCLOSED GAP-FILL: `max_tokens` is mandatory on this endpoint, `streamTurn` receives no
+ * descriptor guarantee, and the seed catalog carries no `maxOutputTokens` evidence for either
+ * Anthropic row. Capture (F) observed the pinned runtime sending 64000 for `claude-sonnet-5`, but
+ * that is one model's ceiling and inventing it for every model would be a capability claim with no
+ * evidence behind it. 4096 is the value the family's own documentation has used as the conservative
+ * default for as long as the endpoint has existed; a host that wants more sets
+ * `TurnRequest.maxOutputTokens` or the descriptor carries `maxOutputTokens` evidence.
+ */
+export declare const ANTHROPIC_DEFAULT_MAX_TOKENS = 4096;
+export interface AnthropicAdapterOptions {
+    /** The catalog the descriptor is looked up in. Defaults to the compiled one; injected in tests so a fixture owns its own rows. */
+    catalog?: WinterCatalog;
+    /** Milliseconds allowed for RESPONSE HEADERS. Not a bound on the generation -- mid-stream silence is `ctx.stallTimeoutMs`'s job. */
+    requestTimeoutMs?: number;
+    maxBodyBytes?: number;
+    /** Injected for deterministic retry fixtures (no real sleeping, no real jitter). */
+    retry?: RetryPolicyOptions;
+    /** `anthropic-beta` values, joined with commas. A PROTOCOL header (R6-L): every endpoint needs it to be spoken to, and it names no account. */
+    betas?: string[];
+    defaultMaxOutputTokens?: number;
+    /**
+     * The OAuth token endpoint a near-expiry `oauth` credential is renewed through (D20).
+     *
+     * Injectable for a fixture exactly as codex's is; production uses `CONSOLE_OAUTH.tokenUrl`. It has
+     * no effect on an `api-key` credential, which is every other row this adapter serves.
+     */
+    tokenUrl?: string;
+}
+export declare function toWireMessages(messages: ProviderMessageLike[]): Array<{
+    role: "user" | "assistant";
+    content: Record<string, unknown>[];
+}>;
+/** Looks a descriptor up by provider + the id/alias/key the request named. `undefined` for an `allowUnlisted` passthrough, which is a FACT the checks below fail closed on. */
+export declare function findDescriptor(catalog: WinterCatalog, providerId: string, model: string): WinterModelDescriptor | undefined;
+export type EffortMapping = {
+    ok: true;
+    value: {
+        type: "enabled";
+        budget_tokens: number;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Effort -> the model's VERIFIED vocabulary, or a refusal (WS-13 §8.2).
+ *
+ * A NUMBER is mapped to the nearest declared tier by treating it as a 0-100 intensity across the
+ * model's own `reasoning.efforts` list. The pin admits a numeric effort on exactly one surface
+ * (`AgentDefinition.effort`, `sdk.d.ts:87`) and states no unit, range or mapping for it -- so this
+ * is gap-filling, disclosed, and it can only ever select a tier the model already declares.
+ */
+export declare function mapAnthropicEffort(effort: TurnRequest["effort"], descriptor: WinterModelDescriptor | undefined): EffortMapping;
+/**
+ * At which event this family's COMPLETE in-dialect block is captured, from the descriptor's own
+ * `completionEvent` evidence (Minor 7).
+ *
+ * Matched LENIENTLY by mention, for the same reason as the Google resolver: the field is a prose-ish
+ * `CapabilityEvidence<string>`. An unrecognised value falls back to `block-stop`, this family's real
+ * per-block terminator -- the conservative answer, since it is the earliest point at which a block is
+ * genuinely complete and holding longer can only ever delay a capture, never take a partial one.
+ */
+export declare function anthropicCaptureEvent(descriptor: WinterModelDescriptor | undefined): "block-stop" | "message-stop";
+export declare function createAnthropicMessagesAdapter(opts?: AnthropicAdapterOptions): ProviderAdapter;

package/dist/adapters/bedrock/converse.d.ts

@@ -0,0 +1,143 @@
+import type { WinterModelDescriptor } from "@yanlinglabs/winter-provider-catalog";
+import type { DiscoveryContext, ProviderAdapter, ProviderError, ProviderMessageLike, TurnRequest } from "../../types.js";
+import { type RetryPolicyOptions } from "../../retry.js";
+import { type IdentityHeaderLookup } from "../../identity.js";
+export declare const BEDROCK_ADAPTER_ID = "winter.bedrock-converse";
+export declare const BEDROCK_ADAPTER_VERSION = "1";
+/** Resolves a provider-local model id to its catalog row, or `undefined` for an id the catalog does not list. */
+export type DescriptorLookup = (modelId: string) => WinterModelDescriptor | undefined;
+export interface BedrockAdapterOptions {
+    /**
+     * The descriptor for a provider-local model id. **REQUIRED** (controller ruling, matching Lane A).
+     *
+     * It is not optional precisely BECAUSE nothing fails to compile without it: the frozen
+     * `ProviderAdapter` hands a descriptor to `mapEffort` and `capabilities` but NOT to `streamTurn`,
+     * while WS-13 §8.2 requires the effort, thinking, tool and limit refusals to happen BEFORE a
+     * request is sent. An adapter built without a lookup is a WEAKER adapter, not a broken one — the
+     * tools-on-a-non-tool-calling-model and output-token-limit refusals simply vanish, silently — so
+     * the type makes the decision explicit instead. A caller with no catalog passes
+     * `descriptors: () => undefined` and has SAID so.
+     */
+    descriptors: DescriptorLookup;
+    /**
+     * Whether a model's answer is streamed. Default: always.
+     *
+     * `GetFoundationModel`/`ListFoundationModels` report `responseStreamingSupported`, and a model
+     * without it must be driven through `Converse` — whose completed JSON this adapter maps into the
+     * IDENTICAL `ProviderEvent` sequence, so a consumer cannot tell which operation answered.
+     */
+    streaming?: (modelId: string) => boolean;
+    /** R6-L PRIVILEGED: cross-account confused-deputy identifiers. They name the operator's account topology and must never reach a user endpoint. */
+    sourceAccount?: string;
+    sourceArn?: string;
+    /**
+     * The ADAPTER'S OWN endpoint, carrying GENERATED provenance. Defaults to the region-derived
+     * `https://bedrock-runtime.<region>.amazonaws.com` / `https://bedrock.<region>.amazonaws.com` pair.
+     *
+     * **A HOST MUST NOT SET THIS.** A host endpoint is `connection.baseUrl`, which is deliberately a
+     * USER endpoint and therefore loses privileged headers — that difference is the whole of R6-L, and
+     * setting this instead would silently restore them for an endpoint the reviewed catalog never
+     * named. It exists because the gate's POSITIVE branch is otherwise untestable: a generated
+     * endpoint is by definition a real AWS hostname, so without this seam "the privileged header rides
+     * a generated endpoint" could only be asserted about intent, never about a live request.
+     *
+     * `connection.baseUrl`, when present, still WINS over this — a host's explicit redirection is
+     * never overridden by an adapter's own default.
+     */
+    vendorBaseUrl?: string;
+    maxBodyBytes?: number;
+    timeoutMs?: number;
+    retry?: RetryPolicyOptions;
+    /** Injected so a fixture can pin a signature against a known-answer vector. */
+    now?: () => Date;
+    /**
+     * WS-13b §7/§8.4 (fix-wave R-FW-2): the per-ROW second identity field, looked up by
+     * `ctx.connection.providerId`.
+     *
+     * A CONSTRUCTION OPTION here rather than a catalog derivation (the shape the Anthropic and Google
+     * families use), because this adapter takes a `descriptors` lookup and never a catalog.
+     * `createShippedAdapters` supplies it; a fixture that omits it gets `{}`, which is what every
+     * Bedrock row carries today.
+     */
+    identityHeaders?: IdentityHeaderLookup;
+}
+/**
+ * Bedrock's structured error code, which `normalizeHttpError` cannot find on its own.
+ *
+ * The frozen normalizer reads `error.code` / `error.type` / `error.status` — the three JSON dialects
+ * of the P6 cohort. Bedrock is a fourth: its REST-JSON error body is a bare `{"message": "..."}` and
+ * the machine-readable value rides the `x-amzn-errortype` HEADER (or, on some paths, a `__type`
+ * field). Both spellings carry a trailing namespace (`ThrottlingException:http://internal…`,
+ * `com.amazon.coral#ValidationException`) that is stripped here so the code is the bare exception
+ * name — which is what a consumer matches on and what the corpus asserts is preserved verbatim.
+ *
+ * Read off the FULL body, before any truncation, for the same reason `errors.ts` states: a cap
+ * applied first slices away exactly the field a consumer wants.
+ */
+export declare function bedrockErrorCode(headers: Headers, body: string): string | undefined;
+/**
+ * Re-exported from `errors.ts`, where this now lives (T2 carry).
+ *
+ * It was written here because the gap it closes was found here — `scanForSecrets` is pattern-based,
+ * and while it does know `AKIA…`/`ASIA…` access key IDS, no pattern can match a SECRET access key
+ * (forty base64-ish characters) without matching arbitrary prose, so one echoed back by an endpoint
+ * survived verbatim into `ProviderError.message`. But nothing about "the pattern scanner cannot have
+ * a pattern for MY family's shapeless credential" is Bedrock-specific, and the next family to notice
+ * would have written a second copy. The shared normalizer takes a per-request `secrets` list now; this name stays so the
+ * lane's own fixtures and any external caller keep working.
+ */
+export { redactCredentialMaterial } from "../../errors.js";
+/** The five-way taxonomy from the HTTP status (the frozen normalizer's job), with Bedrock's own code layered on. */
+export declare function normalizeBedrockError(status: number, headers: Headers, body: string, secrets?: readonly string[]): ProviderError;
+type BedrockBlock = Record<string, unknown>;
+/**
+ * Winter's message list -> Bedrock's `messages`.
+ *
+ * TWO SHAPE RULES BEDROCK ENFORCES AND WINTER'S UNION DOES NOT: roles are only `user` and
+ * `assistant` (a `tool` message becomes a `user` message carrying `toolResult` blocks, which is
+ * Bedrock's own convention), and the two must strictly ALTERNATE. Consecutive same-role messages are
+ * merged by concatenating their content, which is lossless — the alternative, sending them as-is, is
+ * a `ValidationException` naming nothing the caller can act on.
+ */
+export declare function toBedrockMessages(messages: readonly ProviderMessageLike[]): Array<{
+    role: "user" | "assistant";
+    content: BedrockBlock[];
+}>;
+export interface BedrockRequestBody {
+    messages: Array<{
+        role: string;
+        content: BedrockBlock[];
+    }>;
+    system?: Array<{
+        text: string;
+    }>;
+    inferenceConfig?: BedrockBlock;
+    toolConfig?: BedrockBlock;
+    additionalModelRequestFields?: BedrockBlock;
+}
+/** Builds the shared Converse/ConverseStream body. Every refusal this can raise happens before a socket is opened. */
+export declare function buildConverseBody(req: TurnRequest, descriptor: WinterModelDescriptor | undefined, mappedEffort: string | undefined): BedrockRequestBody;
+/**
+ * WS-13 §8.2: map onto the model's VERIFIED vocabulary, or refuse BEFORE a request is sent.
+ *
+ * Standalone rather than a method so `streamTurn`'s pre-request check and the frozen
+ * `ProviderAdapter.mapEffort` seam are provably the SAME rule — a second copy is exactly how an
+ * adapter comes to refuse a selection at one door and send it at another.
+ */
+export declare function mapBedrockEffort(effort: TurnRequest["effort"], model: WinterModelDescriptor): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface BedrockAdapter extends ProviderAdapter {
+    /** The raw `ListFoundationModels` rows, including `responseStreamingSupported` — the input a host needs to build `BedrockAdapterOptions.streaming`. */
+    listFoundationModels(ctx: DiscoveryContext): Promise<Array<{
+        modelId: string;
+        modelName?: string;
+        inputModalities?: string[];
+        responseStreamingSupported?: boolean;
+    }>>;
+}
+export declare function createBedrockConverseAdapter(options: BedrockAdapterOptions): BedrockAdapter;

package/dist/adapters/bedrock/crc32.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The CRC-32 of `bytes`, as an unsigned 32-bit number.
+ *
+ * `seed` carries a running CRC so a message can be checksummed across the buffers it arrived in
+ * without concatenating them first — which matters here because an event-stream frame's message CRC
+ * covers everything before it, and that span is routinely megabytes for an image-bearing turn.
+ * Passing a previous result back in continues the same computation exactly.
+ */
+export declare function crc32(bytes: Uint8Array, seed?: number): number;

package/dist/adapters/bedrock/credentials.d.ts

@@ -0,0 +1,32 @@
+import type { ProviderContext } from "../../types.js";
+import type { AwsSigningCredentials } from "./sigv4.js";
+/**
+ * The marker that distinguishes "no credential is configured or present" from "a credential was
+ * rejected".
+ *
+ * Both are `code: "auth"` — they are the same taxonomy branch — but they are DIFFERENT ANSWERS to
+ * `validateCredential`, and telling a user their key is invalid when they never configured one sends
+ * them to debug the wrong thing entirely. It rides `providerCode` because that field is exactly "a
+ * finer, machine-readable code beneath the coarse taxonomy", and it is Winter-namespaced so it can
+ * never collide with a code AWS returns.
+ */
+export declare const WINTER_CREDENTIAL_MISSING = "WinterCredentialMissing";
+/**
+ * Resolves the context's credential ref into AWS signing material.
+ *
+ * EVERY FAILURE MESSAGE IS BUILT FROM A LOCATOR, never from a value: `redactRef` renders the ref
+ * (which is addressing information and is what makes the message actionable) and `redactMaterial`
+ * renders a wrong-kind material as `***(kind)`. A credential error message is one of the most
+ * reliably-logged strings in any system.
+ */
+export declare function resolveAwsCredentials(ctx: ProviderContext): Promise<AwsSigningCredentials>;
+/**
+ * The region this connection signs for.
+ *
+ * A HARD REQUIREMENT with no default, and that is a security property rather than pedantry: the
+ * region is part of the credential SCOPE, so a wrong one is not a routing mistake but a signature
+ * that will not verify — and a silent `us-east-1` default would send a European operator's requests,
+ * and their data, to a jurisdiction they never chose. R6-16 puts the region in the connection
+ * profile; absent, the session refuses to start rather than guessing.
+ */
+export declare function requireRegion(ctx: ProviderContext): string;

package/dist/adapters/bedrock/eventstream.d.ts

@@ -0,0 +1,65 @@
+/**
+ * AWS's own documented ceilings: 16 MiB per message, 128 KiB of headers. Enforced rather than
+ * assumed — `total length` is attacker-controlled in the only sense that matters (it is four bytes
+ * off a socket), and a decoder that honoured a 4 GiB length would buffer until the process died.
+ * `boundedFetch`'s `maxBodyBytes` bounds the WHOLE response; this bounds one frame.
+ */
+export declare const MAX_EVENT_STREAM_MESSAGE_BYTES: number;
+export declare const MAX_EVENT_STREAM_HEADER_BYTES: number;
+export type EventStreamDecodeErrorCode = "prelude-crc" | "message-crc" | "length" | "header" | "limit";
+/** A malformed frame. Carries a CODE rather than only a message so the adapter can normalize it without matching on prose. */
+export declare class EventStreamDecodeError extends Error {
+    readonly code: EventStreamDecodeErrorCode;
+    constructor(code: EventStreamDecodeErrorCode, message: string);
+}
+/**
+ * A decoded header value.
+ *
+ * Every AWS header type is decoded, not just the string type Bedrock uses in practice, and that is a
+ * robustness decision rather than completeness for its own sake: header parsing is POSITIONAL, so an
+ * unrecognised value type has no length and the parser cannot skip past it — one unexpected type
+ * byte would desynchronise the rest of the header block and every frame after it. Decoding all ten
+ * means an unexpected type is carried, not fatal.
+ */
+export type EventStreamHeaderValue = boolean | number | bigint | string | Uint8Array;
+export interface EventStreamMessage {
+    /** Header names are used verbatim (`:message-type`, `:event-type`, `:content-type`) — AWS's are case-sensitive and colon-prefixed. */
+    headers: Record<string, EventStreamHeaderValue>;
+    payload: Uint8Array;
+}
+export interface EventStreamDecoder {
+    /** Feeds bytes in; returns every message those bytes COMPLETED, in order. Throws `EventStreamDecodeError` on a malformed frame. */
+    push(chunk: Uint8Array): EventStreamMessage[];
+    /** Bytes held back as a partial frame. `> 0` at end-of-stream means the response was truncated. */
+    pending(): number;
+}
+/**
+ * An incremental event-stream decoder.
+ *
+ * BUFFERS BY CONCATENATION, deliberately, rather than keeping a chunk list and a cursor. A frame is
+ * bounded at 16 MiB and the common one is a few hundred bytes, so the copy is not where a streaming
+ * turn spends its time — and the alternative (a rope with cross-chunk reads) is exactly the kind of
+ * index arithmetic that produces a decoder which works until a frame lands on a chunk boundary in
+ * the one place nobody tested. `eventstream.test.ts` feeds a frame BYTE BY BYTE for that reason.
+ */
+export declare function createEventStreamDecoder(): EventStreamDecoder;
+/** The `:message-type` values AWS defines. `event` is a stream item; the other two are terminal failures. */
+export type EventStreamMessageType = "event" | "exception" | "error";
+/** A header read as a string, or `undefined` when absent or of another type. The accessor every caller should use — a header's TYPE is wire data, not an assumption. */
+export declare function stringHeader(message: EventStreamMessage, name: string): string | undefined;
+/**
+ * The frame's `:message-type`, defaulting to `event`.
+ *
+ * The default is the documented behaviour rather than leniency: AWS's own decoders treat an absent
+ * `:message-type` as an event, and Bedrock's happy path is entirely events.
+ */
+export declare function messageType(message: EventStreamMessage): EventStreamMessageType;
+/**
+ * The frame's payload as parsed JSON, or `undefined` when it is not JSON at all.
+ *
+ * `undefined` rather than a throw, because the two cases have different meanings to the adapter: a
+ * frame whose payload is unparseable is a `bad_request`-class provider failure (corpus case
+ * `error-malformed`), while an EMPTY payload is legitimate — `contentBlockStop` and the exception
+ * frames carry nothing.
+ */
+export declare function jsonPayload(message: EventStreamMessage): Record<string, unknown> | undefined;

package/dist/adapters/bedrock/index.d.ts

@@ -0,0 +1,8 @@
+export { BEDROCK_ADAPTER_ID, BEDROCK_ADAPTER_VERSION, bedrockErrorCode, buildConverseBody, createBedrockConverseAdapter, mapBedrockEffort, normalizeBedrockError, toBedrockMessages, } from "./converse.js";
+export type { BedrockAdapter, BedrockAdapterOptions, BedrockRequestBody } from "./converse.js";
+export { requireRegion, resolveAwsCredentials } from "./credentials.js";
+export { EventStreamDecodeError, MAX_EVENT_STREAM_HEADER_BYTES, MAX_EVENT_STREAM_MESSAGE_BYTES, createEventStreamDecoder, jsonPayload, messageType, stringHeader, } from "./eventstream.js";
+export type { EventStreamDecodeErrorCode, EventStreamDecoder, EventStreamHeaderValue, EventStreamMessage, EventStreamMessageType } from "./eventstream.js";
+export { crc32 } from "./crc32.js";
+export { BEDROCK_SERVICE, SIGV4_ALGORITHM, awsUriEncode, buildCanonicalRequest, buildStringToSign, canonicalQuery, canonicalUri, computeSignature, amzDate, parseAuthorization, sha256Hex, signRequest, signingKey, } from "./sigv4.js";
+export type { AwsSigningCredentials, CanonicalRequestInput, ParsedAuthorization, SignRequestInput, SignedRequest } from "./sigv4.js";