@alvin0/ai-agent-sdk-provider-http 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,641 @@
+import { GenerateOptions, ModelAdapter, ModelError, ModelInfo, ModelInvocationContext, ModelModality, ModelReasoningInfo, NativeToolName, PreparedAdapterCall, ProviderInfo, ProviderRequestId, ResolvedModelInfo, ResolvedRetryPolicy, RetryPolicyConfig, StreamChunk, UsageCounters } from "@alvin0/ai-agent-sdk-core";
+import { CredentialInput, GenerateOptions as GenerateOptions$1, ModelInvocationContext as ModelInvocationContext$1, ResolvedModelInfo as ResolvedModelInfo$1, RetryPolicyConfig as RetryPolicyConfig$1, StreamChunk as StreamChunk$1, UsageCounters as UsageCounters$1 } from "@alvin0/ai-agent-sdk-core/provider";
+//#region src/stream/sse.d.ts
+/**
+ * Decode an SSE byte stream into events.
+ *
+ * All the genuinely hard framing work  Echunk reassembly, UTF-8 sequences split
+ * across reads, CRLF and BOM handling, comment and unknown-field skipping,
+ * joining multiple `data:` lines of one event  Ebelongs to `eventsource-parser`.
+ *
+ * Note what is deliberately NOT decided here. OpenAI terminates with a literal
+ * `data: [DONE]` sentinel; Anthropic terminates with a named `message_stop` event
+ * and sends no sentinel at all. Baking in either rule would make the parser lie
+ * about the other, so termination is the adapter's call and this generator simply
+ * runs to the end of the body.
+ *
+ * The callback-based parser is used rather than `EventSourceParserStream` so the
+ * SDK does not require `TextDecoderStream` to exist  Eit is absent on some
+ * runtimes this package should still work on.
+ *
+ * @module @alvin0/ai-agent-sdk-provider-http/sse
+ */
+/**
+ * Ceiling on characters the parser may buffer across reads.
+ *
+ * A stream that never sends an event terminator would otherwise buffer without
+ * bound. 1 MiB is far above any legitimate single SSE event from either provider
+ * and far below a memory problem.
+ */
+/** One decoded server-sent event. */
+interface SseEvent {
+  /**
+   * The event name, or `undefined` when the server declared none.
+   *
+   * NOT defaulted to `'message'` the way a browser `EventSource` would. Absence is
+   * reported faithfully, which is what lets an adapter tell Anthropic's named
+   * events apart from OpenAI's anonymous data-only frames.
+   */
+  event: string | undefined;
+  /** The event's data payload. */
+  data: string;
+}
+/**
+ * Parse an SSE byte stream into events, in arrival order.
+ *
+ * Framing is spec-strict: an event dispatches only on its blank-line terminator,
+ * so an unterminated tail at EOF is truncation rather than a flushable payload.
+ * @param stream - raw SSE bytes, as `Response.body` provides them. Reads may split
+ *   anywhere, including mid-codepoint; the streaming decoder handles that.
+ * @param onActivity - called on every frame INCLUDING comments. Providers send
+ *   comment-only keepalives during long pauses, so a liveness watchdog has to
+ *   count them as activity even though they carry no data.
+ * @returns each event in arrival order; returns normally at end of body.
+ */
+declare function parseSse(stream: ReadableStream<Uint8Array>, onActivity?: () => void, teardownTimeoutMs?: number): AsyncGenerator<SseEvent>;
+//#endregion
+//#region src/stream/types.d.ts
+/** Protocol output before untrusted usage crosses the transport validator. */
+type ProviderProtocolChunk = Exclude<StreamChunk, {
+  readonly type: 'usage';
+}> | {
+  readonly type: 'usage';
+  readonly usage: UsageCounters;
+};
+//#endregion
+//#region src/base/transport.d.ts
+declare function redactHeaders(headers: Readonly<Record<string, string>>, sensitiveHeaderNames?: readonly string[]): Record<string, string>;
+//#endregion
+//#region src/base/http-adapter.d.ts
+/** Default idle bound: five minutes without a single byte is a hung stream. */
+declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/** Default end-to-end bound once provider request construction begins. */
+declare const DEFAULT_REQUEST_TIMEOUT_MS: number;
+/** Default serialized request ceiling. */
+declare const DEFAULT_MAX_REQUEST_BYTES: number;
+/** Default cumulative successful response-body ceiling. */
+declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/** Default number of raw response chunks accepted from one request. */
+declare const DEFAULT_MAX_RESPONSE_CHUNKS = 100000;
+/** Default error body retained for classification and diagnostics. */
+declare const DEFAULT_MAX_ERROR_BODY_BYTES: number;
+/** Default diagnostic observer deadline; logging must never gate dispatch indefinitely. */
+declare const DEFAULT_REQUEST_LOGGER_TIMEOUT_MS = 5000;
+/** One model a provider's configuration advertises. */
+interface ProviderCatalogModel {
+  /** Wire model id, passed to the provider verbatim. */
+  id: string;
+  /** Selector label; defaults to {@link id}. */
+  name?: string;
+  /** Optional detail distinguishing similar variants. */
+  description?: string;
+  /** Combined request/response capacity, when known. */
+  contextWindow?: number;
+  /** Per-request output cap for this model. */
+  maxTokens?: number;
+  /** Accepted request modalities; omission is treated as text-only. */
+  inputModalities?: readonly ModelModality[];
+  /** Modalities this model route may return. */
+  outputModalities?: readonly ModelModality[];
+  /** Provider-native tools explicitly supported; omission means unknown. */
+  nativeTools?: readonly NativeToolName[];
+  /** Reasoning levels this model offers, when any. */
+  reasoning?: ModelReasoningInfo;
+}
+/**
+ * Everything needed to issue ONE request, captured as a single snapshot.
+ *
+ * The snapshot exists to close a specific gap: if the endpoint and the credential
+ * were read separately, a configuration change between the two reads would send
+ * one generation's secret to another generation's URL. Reading them together, once
+ * per call, makes that impossible.
+ */
+interface HttpConnection {
+  /** Endpoint base; the provider's {@link HttpModelAdapter.endpointPath} is appended. */
+  readonly baseUrl: string;
+  /**
+   * Every header for the request, INCLUDING authorization.
+   *
+   * Resolved in `connect()` so the credential travels with the endpoint it will
+   * be sent to. The base pipeline adds attribution and `accept` on top.
+   */
+  readonly headers: Readonly<Record<string, string>>;
+  /** Auth-produced names that must be redacted regardless of spelling. */
+  readonly sensitiveHeaderNames?: readonly string[];
+  /** Maximum idle interval while a read is outstanding. */
+  readonly streamIdleTimeoutMs: number;
+  /** End-to-end request/stream timeout. */
+  readonly requestTimeoutMs?: number;
+  /** Maximum serialized outbound request bytes. */
+  readonly maxRequestBytes?: number;
+  /** Maximum cumulative successful response bytes. */
+  readonly maxResponseBytes?: number;
+  /** Maximum raw chunks accepted from a successful response. */
+  readonly maxResponseChunks?: number;
+  /** Maximum decoded SSE events accepted from one response. */
+  readonly maxSseEvents?: number;
+  /** Maximum characters accepted in one decoded SSE event. */
+  readonly maxSseEventChars?: number;
+  /** Maximum bytes read from a non-success response. */
+  readonly maxErrorBodyBytes?: number;
+  /** Maximum time granted to the optional request logger. */
+  readonly requestLoggerTimeoutMs?: number;
+  /** Permit cleartext HTTP explicitly, for trusted local development endpoints only. */
+  readonly allowInsecureHttp?: boolean;
+  /** Captured fetch implementation; omission uses the platform global. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Retry policy this route owns. */
+  readonly retryPolicy: ResolvedRetryPolicy;
+  /** Advisory catalog; requests are never restricted to it. */
+  readonly models: readonly ProviderCatalogModel[];
+  /** Output cap applied when neither the caller nor the model entry names one. */
+  readonly defaultMaxTokens: number;
+  /** Context capacity used when the selected model has no exact value. */
+  readonly defaultContextWindow: number;
+}
+/** What {@link HttpModelAdapter.buildBody} and `translate` receive. */
+interface ProviderRequest {
+  /** The normalized request, with registry-resolved defaults already applied. */
+  readonly options: GenerateOptions;
+  /** Exact model metadata for this call. */
+  readonly model: ResolvedModelInfo;
+  /** The connection snapshot this call is bound to. */
+  readonly connection: HttpConnection;
+  /** Output cap to send; always resolved to a number, which some APIs require. */
+  readonly maxTokens: number;
+}
+/**
+ * One exact wire request observed immediately before the shared pipeline calls `fetch`.
+ * @deprecated High-risk compatibility diagnostics; prefer structured observation.
+ */
+interface ProviderRequestLogRecord {
+  /** Version of this durable/debug record shape. */
+  readonly schemaVersion: 1;
+  readonly type: 'provider-request';
+  /** Locally generated correlation id; providers may assign a different id later. */
+  readonly id: string;
+  readonly timestamp: string;
+  readonly provider: string;
+  readonly model: string;
+  readonly method: 'POST';
+  readonly url: string;
+  /** Request headers with credentials and cookies replaced by `[REDACTED]`. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** Exact protocol-serialized JSON body. This may contain prompts and tool output. */
+  readonly body: unknown;
+  readonly bodyBytes: number;
+}
+/**
+ * Optional observer for exact provider-wire requests.
+ * @deprecated High-risk compatibility diagnostics; prefer structured observation.
+ */
+type ProviderRequestLogger = (record: ProviderRequestLogRecord) => Promise<void> | void;
+/** Base for every HTTP provider adapter in this package. */
+declare abstract class HttpModelAdapter extends ModelAdapter {
+  /** Human-readable provider name reported by {@link providerInfo}. */
+  protected abstract readonly displayName: string;
+  /**
+   * Capture the connection facts for one operation.
+   *
+   * Called once per operation and never re-read mid-request. Resolve the
+   * credential here, together with the endpoint.
+   * @param provider - the route being served.
+   * @param signal - cancellation for any I/O this resolution performs.
+   */
+  protected abstract connect(provider: string, signal?: AbortSignal, context?: ModelInvocationContext): Promise<HttpConnection>;
+  /** Path appended to {@link HttpConnection.baseUrl}, e.g. `/v1/messages`. */
+  protected abstract endpointPath(request: ProviderRequest): string;
+  /** Convert the normalized request into this provider's wire JSON. */
+  protected abstract buildBody(request: ProviderRequest): Promise<unknown> | unknown;
+  /**
+   * Convert this provider's SSE events into the SDK's chunk protocol.
+   *
+   * Owns termination: this generator decides what ends the stream (a `[DONE]`
+   * sentinel, a named terminal event, or end of body) and must raise
+   * `STREAM_CLOSED` when the body ends before the provider said it was finished.
+   */
+  protected abstract translate(events: AsyncIterable<SseEvent>, request: ProviderRequest): AsyncGenerator<ProviderProtocolChunk>;
+  /**
+   * Extra headers merged in by the base pipeline. Override to change `accept`.
+   * @returns headers applied beneath {@link HttpConnection.headers}.
+   */
+  protected baseHeaders(): Record<string, string>;
+  /**
+   * Observe an exact, credential-redacted wire request before dispatch.
+   *
+   * The default is a no-op so library users do not silently persist prompts.
+   * Implementations should treat this as diagnostics, not a dispatch veto.
+   * @deprecated High-risk compatibility diagnostics; prefer structured observation.
+   */
+  protected observeRequest(_record: ProviderRequestLogRecord): Promise<void> | void;
+  /**
+   * Map a non-2xx response to a stable code. Override only to add codes this
+   * provider reports that the shared mapping cannot infer from the status.
+   */
+  protected providerErrorCode(status: number, detail: string): string;
+  providerInfo(provider: string): ProviderInfo;
+  listModels(provider: string, signal?: AbortSignal): Promise<readonly ModelInfo[]>;
+  resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<ResolvedModelInfo>;
+  prepareCall(provider: string, model: string, signal?: AbortSignal, context?: ModelInvocationContext): Promise<PreparedAdapterCall>;
+  /**
+   * Stream one model call.
+   *
+   * Intentionally NOT an extension point — see the module note. Providers
+   * customize behaviour through the abstract members instead.
+   */
+  stream(options: GenerateOptions, context?: ModelInvocationContext): AsyncIterable<StreamChunk>;
+  /** Resolve a connection first, for the un-prepared entry point. */
+  private runResolving;
+  /** Resolve exact-model metadata from the catalog, falling back to config defaults. */
+  protected modelInfoFor(connection: HttpConnection, provider: string, model: string): ResolvedModelInfo;
+  /** Decorate resolved metadata without reopening the captured connection generation. */
+  protected decorateModel(info: ResolvedModelInfo, _connection: HttpConnection): ResolvedModelInfo;
+  /** Capture legacy subclass transport/auth layers once; configured adapters already return all five. */
+  private captureConnection;
+  /**
+   * The shared pipeline: guard, build, send, classify, decode, bound, translate.
+   */
+  private run;
+  private prepareWireBody;
+  /** Turn a non-2xx response into a fully populated {@link ModelError}. */
+  private httpFailure;
+}
+//#endregion
+//#region src/base/http-errors.d.ts
+/**
+ * Map an HTTP status plus whatever the provider said into a stable code.
+ *
+ * `detail` should be the provider's error `code`, `type`, and `message` joined
+ * into one string — the wording classifiers need all three because providers
+ * disagree about which field carries the useful part.
+ * @param status - status of a non-2xx response.
+ * @param detail - provider error text, joined; empty string when the body was unparseable.
+ * @returns the normalized code.
+ */
+declare function httpErrorCode(status: number, detail?: string): string;
+/**
+ * Parse a `retry-after` header into milliseconds.
+ *
+ * The header comes in two forms — delta-seconds and an HTTP date — and both are
+ * used in practice. A date already in the past yields `undefined` rather than a
+ * negative delay.
+ * @param value - the raw header value, or `null` when absent.
+ * @returns a positive finite delay, or `undefined` when absent or unusable.
+ */
+declare function retryAfterMs(value: string | null): number | undefined;
+/**
+ * Extract a provider request id for diagnostics.
+ *
+ * Worth capturing even though nothing programmatic reads it: when a provider is
+ * misbehaving, this id is what their support needs to find the request.
+ * @param headers - the response headers.
+ * @returns the first non-empty id found, or `undefined`.
+ */
+declare function requestIdFrom(headers: Headers): ProviderRequestId | undefined;
+/** A provider error body reduced to the two things this SDK needs. */
+interface ParsedErrorBody {
+  /** Best human-readable message found, or `undefined` to fall back to the status. */
+  message: string | undefined;
+  /** Provider `code`/`type`/`message` joined, for the wording classifiers. */
+  detail: string;
+}
+/**
+ * Reduce a provider error body to a message and a classifier detail string.
+ *
+ * Handles the two shapes both providers use — `{error: {...}}` and a bare
+ * `{type, message}` — and tolerates a body that is not JSON at all, which is what
+ * a gateway or load balancer in front of the provider will return.
+ * @param raw - the response body as text.
+ * @returns the message and joined detail.
+ */
+declare function parseErrorBody(raw: string): ParsedErrorBody;
+//#endregion
+//#region src/common/config.d.ts
+/** Runtime wire-protocol contract version supported by this package. */
+declare const HTTP_PROTOCOL_API_VERSION: 1;
+/** Stable support-safe errors owned by the runtime HTTP extension path. */
+declare const HTTP_PROVIDER_ERROR_CODES: Readonly<{
+  readonly PROTOCOL_API_UNSUPPORTED: 'HTTP_PROTOCOL_API_UNSUPPORTED';
+  readonly HEADER_INVALID: 'HTTP_HEADER_INVALID';
+  readonly HEADER_RESERVED: 'HTTP_HEADER_RESERVED';
+  readonly HEADER_COLLISION: 'HTTP_HEADER_COLLISION';
+  readonly WIRE_BODY_INVALID: 'HTTP_WIRE_BODY_INVALID';
+  readonly WIRE_BODY_TOO_LARGE: 'HTTP_WIRE_BODY_TOO_LARGE';
+  readonly STREAM_MEDIA_TYPE_INVALID: 'HTTP_STREAM_MEDIA_TYPE_INVALID';
+  readonly SSE_LIMIT_EXCEEDED: 'HTTP_SSE_LIMIT_EXCEEDED';
+  readonly REDIRECT_REJECTED: 'HTTP_REDIRECT_REJECTED';
+}>;
+//#endregion
+//#region src/protocol/runtime-types.d.ts
+interface ProtocolSseEvent {
+  readonly event: string | undefined;
+  readonly data: string;
+}
+type ProtocolStreamChunk = Exclude<StreamChunk$1, {
+  readonly type: 'usage';
+}> | {
+  readonly type: 'usage';
+  readonly usage: UsageCounters$1;
+};
+interface ProtocolRequest {
+  readonly options: GenerateOptions$1;
+  readonly model: ResolvedModelInfo$1;
+  readonly connection: HttpConnection;
+  readonly maxTokens: number;
+}
+/** Versioned executable protocol accepted by the runtime HTTP adapter. */
+interface RuntimeWireProtocol<Dialect extends object> {
+  readonly kind: 'http-wire-protocol';
+  readonly apiVersion: typeof HTTP_PROTOCOL_API_VERSION;
+  readonly id: string;
+  readonly defaultDialect: Dialect;
+  readonly endpointPath: (request: ProtocolRequest, dialect: Dialect) => string;
+  readonly protocolHeaders?: (dialect: Dialect) => Readonly<Record<string, string>>;
+  readonly serialize: (request: ProtocolRequest, dialect: Dialect) => Readonly<Record<string, unknown>>;
+  readonly translate: (events: AsyncIterable<ProtocolSseEvent>, request: ProtocolRequest, displayName: string) => AsyncGenerator<ProtocolStreamChunk>;
+}
+type WireProtocolDefinition<Dialect extends object> = Omit<RuntimeWireProtocol<Dialect>, 'kind' | 'apiVersion'>;
+interface HttpAuthResolveOptions {
+  readonly provider: string;
+  readonly baseUrl: URL;
+  readonly signal: AbortSignal;
+  readonly context?: ModelInvocationContext$1;
+}
+//#endregion
+//#region src/protocol/definition.d.ts
+/**
+ * Stamp a protocol definition without allocating transport state or performing I/O.
+ * All executable properties are captured once and retain the author's receiver.
+ */
+declare function defineWireProtocol<Dialect extends object>(definition: WireProtocolDefinition<Dialect>): RuntimeWireProtocol<Dialect>;
+//#endregion
+//#region src/protocol/protocol.d.ts
+/** A protocol may report partial/untrusted usage before transport validation. */
+type WireProtocolChunk = ProviderProtocolChunk;
+/**
+ * One wire protocol.
+ *
+ * `Dialect` is the protocol's own knob record — the per-endpoint variations that
+ * change which optional fields are sent without changing any behaviour. Keeping it
+ * a type parameter means an endpoint can override exactly the knobs its protocol
+ * defines and nothing else.
+ */
+interface WireProtocol<Dialect> {
+  /** Stable identifier, used in diagnostics and to name the protocol in config. */
+  readonly id: string;
+  /**
+   * Knob defaults.
+   *
+   * An endpoint supplies a partial override, so a new knob can be added to a
+   * protocol without touching any endpoint that does not care about it.
+   */
+  readonly defaultDialect: Dialect;
+  /** Path appended to the endpoint's base URL. */
+  endpointPath(request: ProviderRequest, dialect: Dialect): string;
+  /**
+   * Headers the PROTOCOL requires, as opposed to the ones authentication supplies.
+   *
+   * `anthropic-version` is the motivating case: it is mandatory on every request
+   * to that API regardless of which endpoint or credential is used, so it belongs
+   * to the protocol rather than being copied into each endpoint's config.
+   */
+  protocolHeaders?(dialect: Dialect): Record<string, string>;
+  /** Normalized request to this protocol's wire JSON. */
+  serialize(request: ProviderRequest, dialect: Dialect): unknown | Promise<unknown>;
+  /**
+   * This protocol's SSE events to the SDK's chunk protocol.
+   *
+   * Owns termination: it decides what ends the stream and must raise
+   * `STREAM_CLOSED` when the body ends before the provider said it was finished.
+   */
+  translate(events: AsyncIterable<SseEvent>, request: ProviderRequest, displayName: string): AsyncGenerator<WireProtocolChunk>;
+}
+/** Any protocol, when the dialect type does not matter to the holder. */
+type AnyWireProtocol = WireProtocol<never>;
+/**
+ * Merge an endpoint's partial dialect over a protocol's defaults.
+ *
+ * `undefined` entries are dropped rather than applied, so an override object built
+ * with optional fields cannot accidentally erase a default.
+ * @param protocol - the protocol supplying defaults.
+ * @param overrides - the endpoint's partial override.
+ * @returns the effective, frozen dialect.
+ */
+declare function resolveDialect<Dialect extends object>(protocol: WireProtocol<Dialect>, overrides: Partial<Dialect> | undefined): Dialect;
+//#endregion
+//#region src/configurable/http-provider.d.ts
+/** A credential, either literal or resolved per operation. */
+type CredentialSource = string | ((signal?: AbortSignal, context?: ModelInvocationContext) => string | Promise<string>);
+/**
+ * How requests are authenticated.
+ *
+ * `dynamic` is the escape hatch that keeps OAuth out of subclass territory: it is
+ * called once per operation, so it can refresh a token, read a rotating secret, or
+ * add account-scoping headers.
+ */
+type AuthScheme =
+/** Unauthenticated — a local server, or an endpoint behind a network boundary. */
+{
+  kind: 'none';
+} |
+/** `authorization: Bearer <token>`. */
+{
+  kind: 'bearer';
+  token: CredentialSource;
+  label?: string;
+} |
+/** A named header, e.g. `x-api-key`. */
+{
+  kind: 'header';
+  name: string;
+  value: CredentialSource;
+  label?: string;
+} |
+/** Arbitrary headers resolved per operation. */
+{
+  kind: 'dynamic';
+  resolve: (signal?: AbortSignal, context?: ModelInvocationContext, provider?: string) => Record<string, string> | Promise<Record<string, string>>;
+};
+/** What a model-discovery hook receives. */
+interface ModelDiscoveryContext {
+  /** The endpoint base, with no trailing slash. */
+  readonly baseUrl: string;
+  /** Every header the request would carry, including authentication. */
+  readonly headers: Readonly<Record<string, string>>;
+  readonly signal?: AbortSignal;
+  /** Additive runtime context; legacy discovery hooks may ignore it. */
+  readonly provider?: string;
+  /** Additive invocation context; legacy discovery hooks may ignore it. */
+  readonly context?: ModelInvocationContext;
+}
+/** Configuration for {@link createHttpProvider}. */
+interface HttpProviderOptions<Dialect extends object> {
+  /** Human-readable name used in every diagnostic. */
+  displayName: string;
+  /** The wire protocol this endpoint speaks. */
+  protocol: WireProtocol<Dialect>;
+  /** Endpoint base; the protocol's path is appended. */
+  baseUrl: string;
+  /** Permit cleartext HTTP explicitly, for trusted local development only. */
+  allowInsecureHttp?: boolean;
+  /** Captured fetch implementation for tests, custom runtimes, and transport policy. */
+  fetch?: typeof globalThis.fetch;
+  /** How to authenticate. */
+  auth: AuthScheme;
+  /**
+   * Per-endpoint protocol knobs, merged over the protocol's defaults.
+   *
+   * Partial, so a protocol can gain a knob without any endpoint needing an edit.
+   */
+  dialect?: Partial<Dialect>;
+  /** Extra static headers, or a resolver for them. */
+  headers?: Record<string, string> | (() => Record<string, string>);
+  /**
+   * Advisory model catalog.
+   *
+   * Requests are never restricted to it. Supply entries to declare capabilities
+   * the SDK cannot infer — most importantly image support, since an uncatalogued
+   * model is treated as text-only and its images are projected to text.
+   */
+  models?: readonly ProviderCatalogModel[];
+  /**
+   * Fetch the catalog from the endpoint instead of declaring it.
+   *
+   * Result is memoized for {@link catalogTtlMs}. A failure here is NOT fatal:
+   * refusing the actual model call because a metadata request failed would be the
+   * wrong trade.
+   */
+  discoverModels?: (context: ModelDiscoveryContext) => Promise<readonly ProviderCatalogModel[]>;
+  /** How long a discovered catalog is reused. Defaults to five minutes. */
+  catalogTtlMs?: number;
+  /** Additional opt-in lifetime for the last valid catalog after refresh failure. */
+  catalogStaleTtlMs?: number;
+  /** Backoff after discovery failure before another refresh is attempted. */
+  catalogFailureBackoffMs?: number;
+  /** Maximum catalog entries retained from static config or discovery. Defaults to 2,048. */
+  maxCatalogModels?: number;
+  /** Maximum serialized catalog bytes retained. Defaults to 4 MiB. */
+  maxCatalogBytes?: number;
+  /**
+   * Decorate resolved model metadata.
+   *
+   * The hook for capabilities that come from the endpoint's configuration rather
+   * than its catalog — Anthropic uses it to advertise thinking budgets as
+   * selectable reasoning efforts.
+   */
+  describeModel?: (info: ResolvedModelInfo, dialect: Dialect) => ResolvedModelInfo;
+  /** Output cap when neither caller nor catalog names one. */
+  defaultMaxTokens?: number;
+  /** Context capacity assumed for an uncatalogued model. */
+  defaultContextWindow?: number;
+  /** Idle bound while a stream read is outstanding. */
+  streamIdleTimeoutMs?: number;
+  /** End-to-end request/stream timeout. Defaults to ten minutes. */
+  requestTimeoutMs?: number;
+  /** Maximum serialized outbound request bytes. Defaults to 32 MiB. */
+  maxRequestBytes?: number;
+  /** Maximum cumulative successful response bytes. Defaults to 32 MiB. */
+  maxResponseBytes?: number;
+  /** Maximum raw response chunks. Defaults to 100,000. */
+  maxResponseChunks?: number;
+  /** Maximum decoded SSE events accepted from one response. */
+  maxSseEvents?: number;
+  /** Maximum characters accepted in one decoded SSE event. */
+  maxSseEventChars?: number;
+  /** Maximum non-success response bytes retained. Defaults to 1 MiB. */
+  maxErrorBodyBytes?: number;
+  /** Maximum time granted to the optional request logger. Defaults to 5 seconds. */
+  requestLoggerTimeoutMs?: number;
+  /** Retry policy this route owns. */
+  retryPolicy?: RetryPolicyConfig;
+  /**
+   * Classify a status this endpoint reports specially.
+   *
+   * Return `undefined` to fall through to the shared mapping, so an override only
+   * has to describe what is genuinely different.
+   */
+  errorCode?: (status: number, detail: string) => string | undefined;
+  /** Override the `accept` / `content-type` the pipeline sends. */
+  baseHeaders?: Record<string, string>;
+  /**
+   * Observe exact protocol-serialized requests immediately before `fetch`.
+   * Credentials are redacted, but bodies still contain prompts and tool output.
+   * @deprecated High-risk compatibility bridge. Prefer structured observation.
+   */
+  requestLogger?: ProviderRequestLogger;
+}
+/**
+ * Create a provider adapter from configuration.
+ * @param options - protocol, endpoint, credential, and optional capability hooks.
+ * @returns an adapter ready for `registry.registerAdapter`.
+ */
+declare function createHttpProvider<Dialect extends object>(options: HttpProviderOptions<Dialect>): HttpModelAdapter;
+//#endregion
+//#region src/configurable/runtime-types.d.ts
+type RuntimeCredentialSource = CredentialInput;
+type RuntimeAuthScheme = {
+  readonly kind: 'none';
+} | {
+  readonly kind: 'bearer';
+  readonly token: RuntimeCredentialSource;
+  readonly label?: string;
+} | {
+  readonly kind: 'header';
+  readonly name: string;
+  readonly value: RuntimeCredentialSource;
+  readonly label?: string;
+} | {
+  readonly kind: 'dynamic';
+  readonly resolve: (options: HttpAuthResolveOptions) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+};
+interface RuntimeModelDiscoveryContext {
+  readonly provider: string;
+  readonly baseUrl: URL;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly signal: AbortSignal;
+  readonly context?: ModelInvocationContext$1;
+}
+interface RuntimeHttpProviderOptions<Dialect extends object> {
+  readonly displayName: string;
+  readonly protocol: RuntimeWireProtocol<Dialect>;
+  readonly baseUrl: string | URL;
+  readonly allowInsecureHttp?: boolean;
+  readonly auth: RuntimeAuthScheme;
+  readonly models?: readonly ProviderCatalogModel[];
+  readonly dialect?: Partial<Dialect>;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly headers?: Readonly<Record<string, string>> | (() => Readonly<Record<string, string>>);
+  readonly discoverModels?: (context: RuntimeModelDiscoveryContext) => Promise<readonly ProviderCatalogModel[]>;
+  readonly catalogTtlMs?: number;
+  readonly catalogStaleTtlMs?: number;
+  readonly catalogFailureBackoffMs?: number;
+  readonly maxCatalogModels?: number;
+  readonly maxCatalogBytes?: number;
+  readonly describeModel?: (info: ResolvedModelInfo$1, dialect: Dialect) => ResolvedModelInfo$1;
+  readonly defaultMaxTokens?: number;
+  readonly defaultContextWindow?: number;
+  readonly streamIdleTimeoutMs?: number;
+  readonly requestTimeoutMs?: number;
+  readonly maxRequestBytes?: number;
+  readonly maxResponseBytes?: number;
+  readonly maxResponseChunks?: number;
+  readonly maxSseEvents?: number;
+  readonly maxSseEventChars?: number;
+  readonly maxErrorBodyBytes?: number;
+  readonly requestLoggerTimeoutMs?: number;
+  readonly retryPolicy?: RetryPolicyConfig$1;
+  readonly errorCode?: (status: number, detail: string) => string | undefined;
+  readonly baseHeaders?: Readonly<Record<string, string>>;
+  readonly requestLogger?: ProviderRequestLogger;
+}
+//#endregion
+//#region src/configurable/runtime-provider.d.ts
+/** Create the versioned HTTP extension adapter without performing credential or network I/O. */
+declare function createRuntimeHttpProvider<Dialect extends object>(options: RuntimeHttpProviderOptions<Dialect>): HttpModelAdapter;
+//#endregion
+//#region src/observation/operations.d.ts
+declare function observeCredentialOperation<T>(context: ModelInvocationContext | undefined, provider: string, operation: 'resolve' | 'refresh' | 'login', task: () => Promise<T>): Promise<T>;
+declare function observeModelCatalogOperation<T>(context: ModelInvocationContext | undefined, provider: string, origin: string, task: () => Promise<T>): Promise<T>;
+//#endregion
+export { AnyWireProtocol, AuthScheme, CredentialSource, DEFAULT_MAX_ERROR_BODY_BYTES, DEFAULT_MAX_REQUEST_BYTES, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_MAX_RESPONSE_CHUNKS, DEFAULT_REQUEST_LOGGER_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, HTTP_PROTOCOL_API_VERSION, HTTP_PROVIDER_ERROR_CODES, type HttpAuthResolveOptions, type HttpConnection, HttpModelAdapter, HttpProviderOptions, ModelDiscoveryContext, type ParsedErrorBody, type ProtocolRequest, type ProtocolSseEvent, type ProtocolStreamChunk, type ProviderCatalogModel, type ProviderRequest, type ProviderRequestLogRecord, type ProviderRequestLogger, type RuntimeAuthScheme, type RuntimeCredentialSource, type RuntimeHttpProviderOptions, type RuntimeModelDiscoveryContext, type RuntimeWireProtocol, SseEvent, WireProtocol, WireProtocolChunk, type WireProtocolDefinition, createHttpProvider, createRuntimeHttpProvider, defineWireProtocol, httpErrorCode, observeCredentialOperation, observeModelCatalogOperation, parseErrorBody, parseSse, redactHeaders, requestIdFrom, resolveDialect, retryAfterMs };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/stream/sse.ts","../src/stream/types.ts","../src/base/transport.ts","../src/base/http-adapter.ts","../src/base/http-errors.ts","../src/common/config.ts","../src/protocol/runtime-types.ts","../src/protocol/definition.ts","../src/protocol/protocol.ts","../src/configurable/http-provider.ts","../src/configurable/runtime-types.ts","../src/configurable/runtime-provider.ts","../src/observation/operations.ts"],"mappings":"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"}