@providerkit/core 0.1.0

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,31 @@
+export interface RequestInit_ {
+    url: string;
+    headers?: Record<string, string>;
+    body: unknown;
+    /** Names the provider in the error envelope. */
+    provider: string;
+    signal?: AbortSignal;
+    /** Swapped in tests, or to route through a proxy. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/** Join a base URL and a path without doubling or dropping the slash. */
+export declare function apiUrl(baseUrl: string, path: string): string;
+/**
+ * How long the provider says to wait, read from the RESPONSE rather than from
+ * a thrown error. Headers are authoritative — `Retry-After` first, then the
+ * vendor reset headers that name a subscription window rather than a
+ * per-minute throttle, because "try again in a moment" is a lie for those.
+ */
+export declare function retryAfterFromHeaders(headers: Headers, now?: number): number | undefined;
+/** POST and parse one JSON response. For the endpoints that do not stream. */
+export declare function postJson<T = unknown>(opts: RequestInit_): Promise<T>;
+/**
+ * POST an SSE request and yield each `data:` payload, trimmed.
+ *
+ * Frames are split on the blank line the spec requires, so a payload
+ * containing a bare newline survives; `[DONE]` is swallowed here rather than in
+ * every adapter. CRLF is normalized — some gateways send it, and a `\r` left on
+ * the end of a JSON payload is a parse error nobody enjoys debugging.
+ */
+export declare function streamSse(opts: RequestInit_): AsyncGenerator<string>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CA6B5F;AAoCD,8EAA8E;AAC9E,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAI1E;AAED;;;;;;;GAOG;AACH,wBAAuB,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC,CAmD3E"}

package/dist/transport.js

@@ -0,0 +1,157 @@
+// The wire. One `fetch`, one SSE reader, one error envelope — no vendor SDK,
+// no Node built-ins, so the same build runs in Bun, Node, Workers, Deno and an
+// MV3 service worker.
+//
+// Adapters keep only their per-event mapping; everything about being an HTTP
+// client lives here once.
+import { classify, isTransportFailure, ProviderError } from "./errors.js";
+/** Join a base URL and a path without doubling or dropping the slash. */
+export function apiUrl(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+/**
+ * How long the provider says to wait, read from the RESPONSE rather than from
+ * a thrown error. Headers are authoritative — `Retry-After` first, then the
+ * vendor reset headers that name a subscription window rather than a
+ * per-minute throttle, because "try again in a moment" is a lie for those.
+ */
+export function retryAfterFromHeaders(headers, now = Date.now()) {
+    const retryAfter = headers.get("retry-after");
+    if (retryAfter) {
+        if (/^\d+$/.test(retryAfter))
+            return Number(retryAfter) * 1000;
+        const date = Date.parse(retryAfter);
+        if (!Number.isNaN(date))
+            return Math.max(0, date - now);
+    }
+    // Anthropic and several gateways publish an epoch-seconds reset instead.
+    for (const name of [
+        "anthropic-ratelimit-unified-reset",
+        "anthropic-ratelimit-requests-reset",
+        "anthropic-ratelimit-tokens-reset",
+        "x-ratelimit-reset-requests",
+        "x-ratelimit-reset-tokens",
+        "x-ratelimit-reset",
+    ]) {
+        const value = headers.get(name);
+        if (!value)
+            continue;
+        if (/^\d+$/.test(value)) {
+            const seconds = Number(value);
+            // Epoch seconds (a big number) or a relative count — tell them apart by
+            // magnitude rather than by trusting one vendor's convention.
+            const ms = seconds > 1_000_000_000 ? seconds * 1000 - now : seconds * 1000;
+            if (ms > 0)
+                return ms;
+        }
+        const date = Date.parse(value);
+        if (!Number.isNaN(date))
+            return Math.max(0, date - now);
+    }
+    return undefined;
+}
+/** Turn a non-2xx response into the classified error every caller branches on. */
+async function errorFor(provider, res) {
+    const text = await res.text().catch(() => "");
+    const kind = classify({ status: res.status, error: text }, res.status, text);
+    const message = text
+        ? `${provider} ${res.status}: ${text.slice(0, 500)}`
+        : `${provider} ${res.status} ${res.statusText}`;
+    return new ProviderError(provider, kind, message, {
+        status: res.status,
+        retryAfterMs: retryAfterFromHeaders(res.headers),
+        body: text.slice(0, 2_000) || undefined,
+    });
+}
+async function send(opts) {
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    try {
+        return await doFetch(opts.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...opts.headers },
+            body: typeof opts.body === "string" ? opts.body : JSON.stringify(opts.body),
+            signal: opts.signal,
+        });
+    }
+    catch (err) {
+        // A stopped run rejects here too, and that is not a failure — let it pass
+        // through untouched. Anything that is not a recognizable transport
+        // rejection is a bug of ours and keeps its own loud shape.
+        if (opts.signal?.aborted || !isTransportFailure(err))
+            throw err;
+        throw new ProviderError(opts.provider, "network", `no response from ${opts.url}`, {
+            cause: err,
+        });
+    }
+}
+/** POST and parse one JSON response. For the endpoints that do not stream. */
+export async function postJson(opts) {
+    const res = await send(opts);
+    if (!res.ok)
+        throw await errorFor(opts.provider, res);
+    return (await res.json());
+}
+/**
+ * POST an SSE request and yield each `data:` payload, trimmed.
+ *
+ * Frames are split on the blank line the spec requires, so a payload
+ * containing a bare newline survives; `[DONE]` is swallowed here rather than in
+ * every adapter. CRLF is normalized — some gateways send it, and a `\r` left on
+ * the end of a JSON payload is a parse error nobody enjoys debugging.
+ */
+export async function* streamSse(opts) {
+    const res = await send(opts);
+    if (!res.ok)
+        throw await errorFor(opts.provider, res);
+    // A 2xx with no body at all is an upstream anomaly, not a request we got
+    // wrong — worth the same retry a 5xx gets.
+    if (!res.body) {
+        throw new ProviderError(opts.provider, "overload", `${opts.provider}: empty response body`, {
+            status: res.status,
+        });
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    /** Pull the `data:` payload out of one SSE frame, joining continuation
+     *  lines the way the spec says to. Returns null for a comment or a frame
+     *  carrying only an `event:` name. */
+    function payloadOf(frame) {
+        const parts = [];
+        for (const line of frame.split("\n")) {
+            if (!line.startsWith("data:"))
+                continue;
+            parts.push(line.slice(5).replace(/^ /, ""));
+        }
+        if (parts.length === 0)
+            return null;
+        const payload = parts.join("\n").trim();
+        return payload.length > 0 ? payload : null;
+    }
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+            let boundary = buffer.indexOf("\n\n");
+            while (boundary !== -1) {
+                const frame = buffer.slice(0, boundary);
+                buffer = buffer.slice(boundary + 2);
+                const payload = payloadOf(frame);
+                if (payload !== null && payload !== "[DONE]")
+                    yield payload;
+                boundary = buffer.indexOf("\n\n");
+            }
+        }
+        // A stream that ends without its final blank line still has an event in
+        // hand — dropping it loses the last delta, or the usage record.
+        const tail = payloadOf(buffer);
+        if (tail !== null && tail !== "[DONE]")
+            yield tail;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * How hard the model thinks before answering. Absent = the provider's own
+ * default (never sent). Passed through verbatim on OpenAI-shape
+ * (`reasoning_effort`); mapped to thinking budgets on Anthropic-shape.
+ * Support varies per model — an unsupported level comes back as a clean 400.
+ *
+ * Ordered least → most; the type derives from the array so the runtime guard
+ * and the union can never drift apart.
+ */
+export declare const EFFORTS: readonly ["none", "low", "medium", "high", "max"];
+export type Effort = (typeof EFFORTS)[number];
+/** The one place the effort union meets raw input (pickers, CLI flags). */
+export declare function isEffort(value: string): value is Effort;
+export type ImageMimeType = "image/jpeg" | "image/png" | "image/webp" | "image/gif";
+export interface TextPart {
+    type: "text";
+    text: string;
+}
+/** An image the model looks at (vision) — bytes as base64, never a URL the
+ *  provider would have to fetch on our behalf. */
+export interface ImagePart {
+    type: "image";
+    mimeType: ImageMimeType;
+    data: string;
+}
+export type ContentPart = TextPart | ImagePart;
+/**
+ * A tool the model asked to run. `arguments` is the RAW JSON string, not a
+ * parsed object: it arrives in fragments and can be truncated mid-stream, so
+ * assembly and validation are the consumer's job (see tools/define).
+ */
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+    /** Gemini's opaque reasoning token. It must ride back on the next turn
+     *  verbatim or the model loses its own chain of thought. */
+    thoughtSignature?: string;
+}
+export type ChatMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | ContentPart[];
+} | {
+    role: "assistant";
+    content: string;
+    /**
+     * The model's chain-of-thought. Thinking-mode providers require it
+     * replayed on a turn that made a tool call (DeepSeek 400s without it).
+     * OpenAI-shape serializes it as `reasoning_content`; Anthropic-shape
+     * drops it, since its thinking blocks carry signatures we never capture.
+     *
+     * A turn that DISABLES thinking must not carry it — mixing the two is
+     * unsupported. `stripReasoning` below is that rule, once.
+     */
+    reasoning?: string;
+    toolCalls?: ToolCall[];
+} | {
+    role: "tool";
+    toolCallId: string;
+    name: string;
+    content: string;
+    /** Images a tool hands back (a screenshot, a rendered chart). */
+    images?: ImagePart[];
+};
+/** JSON Schema for an object — what every provider's tool contract wants. */
+export interface JsonObjectSchema {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JsonObjectSchema;
+}
+export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter";
+/** Incremental tool-call fragment, assembled by `index` by the consumer. */
+export interface ToolCallDelta {
+    index: number;
+    id?: string;
+    name?: string;
+    arguments?: string;
+    thoughtSignature?: string;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    /** Cache-HIT subset of `inputTokens` — providers auto-cache repeated
+     *  prefixes and bill the hit portion far cheaper, so it must be tracked
+     *  separately to cost a turn correctly. 0 when the provider reports none. */
+    cachedInputTokens: number;
+    /** Tokens WRITTEN to cache. Anthropic bills these above the input rate;
+     *  the OpenAI-shape auto-cachers bill them at it. 0 when not reported. */
+    cacheWriteTokens?: number;
+    outputTokens: number;
+}
+export declare const EMPTY_USAGE: TokenUsage;
+/** Normalized streaming chunk — every provider's shape collapses into this. */
+export interface ProviderChunk {
+    type: "delta" | "usage" | "finish";
+    content?: string;
+    reasoning?: string;
+    toolCalls?: ToolCallDelta[];
+    usage?: TokenUsage;
+    finishReason?: FinishReason;
+}
+/** Pin or deny tool use. `{ name }` forces one specific tool — how a run is
+ *  made to commit an answer at its step budget's edge. */
+export type ToolChoice = "auto" | "none" | "required" | {
+    name: string;
+};
+/**
+ * Ask for a JSON object matching `schema`. Providers that enforce schemas get
+ * it verbatim; the rest get JSON mode plus the schema in the prompt. Either
+ * way the CALLER validates — a provider's "guaranteed" JSON is not one.
+ */
+export interface JsonOutput {
+    name: string;
+    schema: JsonObjectSchema;
+}
+export interface StreamOptions {
+    /** Override the provider's bound model for this call. */
+    model?: string;
+    effort?: Effort;
+    /** Output ceiling. On most providers thinking and answer SHARE it, so a
+     *  task emitting a large artifact must raise it or the tool-call JSON is
+     *  silently truncated mid-argument. */
+    maxTokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+    toolChoice?: ToolChoice;
+    json?: JsonOutput;
+}
+export interface Provider {
+    readonly id: string;
+    readonly model: string;
+    createStream(messages: ChatMessage[], tools: ToolDefinition[], opts?: StreamOptions): AsyncIterable<ProviderChunk>;
+}
+export interface Completion {
+    text: string;
+    reasoning: string;
+    usage: TokenUsage;
+    finishReason: FinishReason | null;
+    model: string;
+}
+/** Drain a no-tools stream into a Completion. Usage chunks are cumulative on
+ *  some providers and final-only on others: the LAST one wins. */
+export declare function drainStream(stream: AsyncIterable<ProviderChunk>, model: string): Promise<Completion>;
+/**
+ * Prepare a history for a thinking-DISABLED turn: strip `reasoning` from every
+ * assistant message.
+ *
+ * The chain-of-thought belongs only to thinking turns. A provider that
+ * requires it replayed while thinking is ON (DeepSeek) rejects it when
+ * thinking is OFF — which is exactly the shape of a forced-submit salvage
+ * turn, where a run reasons through its whole investigation and then drops
+ * thinking to serialize what it already found.
+ *
+ * Returns a shallow-cleaned copy; the caller's array is left untouched.
+ */
+export declare function stripReasoning(messages: readonly ChatMessage[]): ChatMessage[];
+/** `data:` URI for an image part — what the OpenAI dialect wants inline. */
+export declare function toDataUri(part: ImagePart): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,75 @@
+// The seam — provider-neutral messages, tools and chunks. Every adapter
+// (OpenAI-compatible, Anthropic, Responses, Gemini) translates to and from
+// exactly these shapes, so a caller never sees a vendor's dialect.
+//
+// Deliberately NOT OpenAI's parameter types. Using one vendor's wire shape as
+// the lingua franca forces the other adapters to round-trip through a dialect
+// that isn't theirs, and every quirk of that dialect then leaks into callers
+// who never asked for it.
+/**
+ * How hard the model thinks before answering. Absent = the provider's own
+ * default (never sent). Passed through verbatim on OpenAI-shape
+ * (`reasoning_effort`); mapped to thinking budgets on Anthropic-shape.
+ * Support varies per model — an unsupported level comes back as a clean 400.
+ *
+ * Ordered least → most; the type derives from the array so the runtime guard
+ * and the union can never drift apart.
+ */
+export const EFFORTS = ["none", "low", "medium", "high", "max"];
+/** The one place the effort union meets raw input (pickers, CLI flags). */
+export function isEffort(value) {
+    return EFFORTS.some((effort) => effort === value);
+}
+export const EMPTY_USAGE = {
+    inputTokens: 0,
+    cachedInputTokens: 0,
+    outputTokens: 0,
+};
+/** Drain a no-tools stream into a Completion. Usage chunks are cumulative on
+ *  some providers and final-only on others: the LAST one wins. */
+export async function drainStream(stream, model) {
+    let text = "";
+    let reasoning = "";
+    let usage = EMPTY_USAGE;
+    let finishReason = null;
+    for await (const chunk of stream) {
+        if (chunk.type === "delta") {
+            if (chunk.content)
+                text += chunk.content;
+            if (chunk.reasoning)
+                reasoning += chunk.reasoning;
+        }
+        else if (chunk.type === "usage" && chunk.usage) {
+            usage = chunk.usage;
+        }
+        else if (chunk.type === "finish" && chunk.finishReason) {
+            finishReason = chunk.finishReason;
+        }
+    }
+    return { text, reasoning, usage, finishReason, model };
+}
+/**
+ * Prepare a history for a thinking-DISABLED turn: strip `reasoning` from every
+ * assistant message.
+ *
+ * The chain-of-thought belongs only to thinking turns. A provider that
+ * requires it replayed while thinking is ON (DeepSeek) rejects it when
+ * thinking is OFF — which is exactly the shape of a forced-submit salvage
+ * turn, where a run reasons through its whole investigation and then drops
+ * thinking to serialize what it already found.
+ *
+ * Returns a shallow-cleaned copy; the caller's array is left untouched.
+ */
+export function stripReasoning(messages) {
+    return messages.map((message) => {
+        if (message.role !== "assistant" || message.reasoning === undefined)
+            return message;
+        const { reasoning: _dropped, ...rest } = message;
+        return rest;
+    });
+}
+/** `data:` URI for an image part — what the OpenAI dialect wants inline. */
+export function toDataUri(part) {
+    return `data:${part.mimeType};base64,${part.data}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2EAA2E;AAC3E,mEAAmE;AACnE,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,0BAA0B;AAE1B;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AAGzE,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC;AACpD,CAAC;AAkGD,MAAM,CAAC,MAAM,WAAW,GAAe;IACrC,WAAW,EAAE,CAAC;IACd,iBAAiB,EAAE,CAAC;IACpB,YAAY,EAAE,CAAC;CAChB,CAAC;AA0DF;kEACkE;AAClE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAoC,EACpC,KAAa;IAEb,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,KAAK,GAAe,WAAW,CAAC;IACpC,IAAI,YAAY,GAAwB,IAAI,CAAC;IAC7C,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,OAAO;gBAAE,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC;YACzC,IAAI,KAAK,CAAC,SAAS;gBAAE,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC;QACpD,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YACjD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACtB,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACzD,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QACpC,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgC;IAC7D,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9B,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC;QACpF,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CAAC,IAAe;IACvC,OAAO,QAAQ,IAAI,CAAC,QAAQ,WAAW,IAAI,CAAC,IAAI,EAAE,CAAC;AACrD,CAAC"}

package/dist/usage.d.ts

@@ -0,0 +1,50 @@
+import type { TokenUsage } from "./types.ts";
+/** USD per MILLION tokens — how every vendor prints its price sheet, so a row
+ *  can be checked against one without arithmetic. */
+export interface ModelRate {
+    /** Cache-MISS input: fresh tokens the provider had to read. */
+    input: number;
+    output: number;
+    /** Cache-HIT input. Providers auto-cache repeated prefixes and bill the hit
+     *  portion far cheaper — 0.1× on Anthropic, ~0.1× on Gemini, 0.5× on some
+     *  OpenAI models. In an agent loop the re-sent context is overwhelmingly
+     *  hits, so billing it at the miss rate overcounts by up to 10×. */
+    cacheRead: number;
+    /** Input WRITTEN to cache. Anthropic bills this ABOVE the input rate
+     *  (1.25×); the OpenAI-shape auto-cachers bill it at the input rate.
+     *  Defaults to `input` when a vendor does not price it separately. */
+    cacheWrite?: number;
+}
+/** Add two usage records. */
+export declare function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+/**
+ * USD for one call.
+ *
+ * Cached tokens are a SUBSET of input, not an addition to it: the miss part
+ * bills at the full rate and the hit part at the cache rate. `cached` is
+ * clamped to `input` so an over-reporting provider can neither drive the miss
+ * count negative nor bill for more prompt than it was sent.
+ */
+export declare function costUsd(usage: TokenUsage, rate: ModelRate): number;
+/**
+ * Accumulates usage and cost across the calls of one run, pricing each with
+ * the rate in effect for the model that served it — so a run that switches to
+ * a backup model, or spans a time-of-day price boundary, still bills correctly.
+ */
+export declare class UsageTracker {
+    private usage;
+    private cost;
+    /** USD the cache hits saved, versus billing them all as misses.
+     *  Observability only — never billed. */
+    private saved;
+    add(usage: TokenUsage, rate?: ModelRate): void;
+    get totals(): TokenUsage;
+    get costUsd(): number;
+    get cacheSavingsUsd(): number;
+    /** A generous runaway guard, not a quality cap: the loop's step budget is
+     *  the real bound, and a run that trips this should finalize rather than
+     *  fail, so set it well above any legitimate run. */
+    isOverBudget(maxUsd: number): boolean;
+    reset(): void;
+}
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;qDACqD;AACrD,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;wEAGoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;0EAEsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6BAA6B;AAC7B,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAOjE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAalE;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAuD;IACpE,OAAO,CAAC,IAAI,CAAK;IACjB;6CACyC;IACzC,OAAO,CAAC,KAAK,CAAK;IAElB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAQ9C,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;yDAEqD;IACrD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIrC,KAAK,IAAI,IAAI;CAKd"}

package/dist/usage.js

@@ -0,0 +1,71 @@
+import { EMPTY_USAGE } from "./types.js";
+/** Add two usage records. */
+export function addUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        cachedInputTokens: a.cachedInputTokens + b.cachedInputTokens,
+        cacheWriteTokens: (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0),
+        outputTokens: a.outputTokens + b.outputTokens,
+    };
+}
+/**
+ * USD for one call.
+ *
+ * Cached tokens are a SUBSET of input, not an addition to it: the miss part
+ * bills at the full rate and the hit part at the cache rate. `cached` is
+ * clamped to `input` so an over-reporting provider can neither drive the miss
+ * count negative nor bill for more prompt than it was sent.
+ */
+export function costUsd(usage, rate) {
+    const input = Math.max(0, usage.inputTokens);
+    const cached = Math.min(Math.max(0, usage.cachedInputTokens), input);
+    const written = Math.max(0, usage.cacheWriteTokens ?? 0);
+    const miss = input - cached;
+    const writeRate = rate.cacheWrite ?? rate.input;
+    return ((miss * rate.input +
+        cached * rate.cacheRead +
+        written * writeRate +
+        Math.max(0, usage.outputTokens) * rate.output) /
+        1_000_000);
+}
+/**
+ * Accumulates usage and cost across the calls of one run, pricing each with
+ * the rate in effect for the model that served it — so a run that switches to
+ * a backup model, or spans a time-of-day price boundary, still bills correctly.
+ */
+export class UsageTracker {
+    usage = { ...EMPTY_USAGE, cacheWriteTokens: 0 };
+    cost = 0;
+    /** USD the cache hits saved, versus billing them all as misses.
+     *  Observability only — never billed. */
+    saved = 0;
+    add(usage, rate) {
+        this.usage = addUsage(this.usage, usage);
+        if (!rate)
+            return;
+        this.cost += costUsd(usage, rate);
+        const cached = Math.min(Math.max(0, usage.cachedInputTokens), Math.max(0, usage.inputTokens));
+        this.saved += (cached * (rate.input - rate.cacheRead)) / 1_000_000;
+    }
+    get totals() {
+        return { ...this.usage };
+    }
+    get costUsd() {
+        return this.cost;
+    }
+    get cacheSavingsUsd() {
+        return this.saved;
+    }
+    /** A generous runaway guard, not a quality cap: the loop's step budget is
+     *  the real bound, and a run that trips this should finalize rather than
+     *  fail, so set it well above any legitimate run. */
+    isOverBudget(maxUsd) {
+        return this.cost >= maxUsd;
+    }
+    reset() {
+        this.usage = { ...EMPTY_USAGE, cacheWriteTokens: 0 };
+        this.cost = 0;
+        this.saved = 0;
+    }
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}

package/dist/watchdog.d.ts

@@ -0,0 +1,34 @@
+/** No byte at all for this long and the stream is considered wedged. */
+export declare const STREAM_IDLE_MS = 60000;
+export interface StreamWatch {
+    /** Hand this to the provider in place of the caller's signal. */
+    readonly signal: AbortSignal;
+    /** A byte arrived: re-arm the deadline, and mark TTFT if it was the first. */
+    sawByte(): void;
+    /**
+     * Milliseconds from the call opening to its first byte of any kind — the
+     * wait a person actually experiences, and the number a prompt-cache pin
+     * exists to shrink. Null until something arrives.
+     */
+    firstChunkMs(): number | null;
+    /**
+     * Re-issue a provider failure as the idle timeout when — and only when — it
+     * was our deadline that aborted. A caller's Stop passes through untouched.
+     */
+    classify(err: unknown): unknown;
+    /** Clear the deadline timer. Safe to call more than once. */
+    dispose(): void;
+}
+export interface StreamWatchOptions {
+    provider?: string;
+    idleMs?: number;
+    signal?: AbortSignal;
+}
+export declare function streamWatch(opts?: StreamWatchOptions): StreamWatch;
+/**
+ * Wrap a stream so every chunk re-arms `watch`, and a failure is re-classified
+ * through it. Disposes on any exit — completion, throw, or the consumer
+ * breaking out of the loop.
+ */
+export declare function watchChunks<T>(watch: StreamWatch, chunks: AsyncIterable<T>): AsyncGenerator<T>;
+//# sourceMappingURL=watchdog.d.ts.map

package/dist/watchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchdog.d.ts","sourceRoot":"","sources":["../src/watchdog.ts"],"names":[],"mappings":"AAgBA,wEAAwE;AACxE,eAAO,MAAM,cAAc,QAAS,CAAC;AAErC,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,8EAA8E;IAC9E,OAAO,IAAI,IAAI,CAAC;IAChB;;;;OAIG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;IAChC,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,WAAW,CAoDtE;AAED;;;;GAIG;AACH,wBAAuB,WAAW,CAAC,CAAC,EAClC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GACvB,cAAc,CAAC,CAAC,CAAC,CAWnB"}