@wardby/cli 0.1.0

package/dist/providers/llm/claude-messages.js

@@ -0,0 +1,157 @@
+/**
+ * Client-agnostic Claude Messages protocol. Pure functions, no SDK import,
+ * so a future Bedrock-Claude adapter reuses them unchanged — Bedrock and the
+ * direct API differ only in client/auth, model IDs, and pricing.
+ */
+import { encode as encodeO200kBase } from "gpt-tokenizer/encoding/o200k_base";
+function parseArgs(argsJson) {
+    try {
+        return JSON.parse(argsJson || "{}");
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Same shape sent to the API in `toClaudeRequest` — kept as one function so
+ * a pre-flight token estimate (AnthropicLlmProvider.countTokens) can never
+ * drift from what's actually serialized into the request. Mirrors the
+ * OpenAI adapter's `toOpenAiTools`, which guards against the same failure
+ * class: a duplicated tool-schema mapping once desynced the pre-flight
+ * estimate from the real request and broke the budget guardrail's turn-1
+ * refuse guarantee (measured 44-52% under-count).
+ */
+export function toClaudeTools(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.parameters,
+    }));
+}
+const TOKENS_PER_MESSAGE = 3;
+/**
+ * Raw (pre-inflation) offline token estimate shared by every Claude-protocol
+ * adapter. Each caller applies its own inflation constant on top.
+ */
+export function estimateClaudeTokens(messages, tools) {
+    let raw = 0;
+    for (const m of messages) {
+        raw += TOKENS_PER_MESSAGE + encodeO200kBase(m.content).length + encodeO200kBase(m.role).length;
+    }
+    if (tools && tools.length > 0) {
+        raw += encodeO200kBase(JSON.stringify(toClaudeTools(tools))).length;
+    }
+    return raw;
+}
+export function toClaudeRequest(req, defaultMaxTokens) {
+    const system = [];
+    const messages = [];
+    for (const m of req.messages) {
+        if (m.role === "system") {
+            system.push({ type: "text", text: m.content });
+            continue;
+        }
+        if (m.role === "tool") {
+            messages.push({
+                role: "user",
+                content: [{ type: "tool_result", tool_use_id: m.toolCallId ?? "", content: m.content }],
+            });
+            continue;
+        }
+        if (m.role === "assistant") {
+            const content = [];
+            if (m.content)
+                content.push({ type: "text", text: m.content });
+            for (const tc of m.toolCalls ?? []) {
+                content.push({ type: "tool_use", id: tc.id, name: tc.name, input: parseArgs(tc.argsJson) });
+            }
+            messages.push({ role: "assistant", content });
+            continue;
+        }
+        // user
+        messages.push({ role: "user", content: [{ type: "text", text: m.content }] });
+    }
+    const tools = req.tools ? toClaudeTools(req.tools) : undefined;
+    return {
+        ...(system.length > 0 ? { system } : {}),
+        messages,
+        ...(tools && tools.length > 0 ? { tools } : {}),
+        max_tokens: req.maxTokens ?? defaultMaxTokens,
+    };
+}
+const EPHEMERAL = { type: "ephemeral" };
+/**
+ * Two-breakpoint canonical caching. Anthropic's cache order is
+ * tools -> system -> messages, so a breakpoint on the last system block
+ * caches tools+system (static across the run). A rolling breakpoint on the
+ * last message's final block grows the conversation cache each turn.
+ * Sub-minimum prefixes (1024/2048 tokens) are silently un-cached by Anthropic.
+ */
+export function withCacheBreakpoints(req) {
+    const system = req.system?.map((b, i, arr) => (i === arr.length - 1 ? { ...b, cache_control: EPHEMERAL } : b));
+    const messages = req.messages.map((m, mi, marr) => {
+        if (mi !== marr.length - 1)
+            return m;
+        const content = m.content.map((b, bi, barr) => (bi === barr.length - 1 ? { ...b, cache_control: EPHEMERAL } : b));
+        return { ...m, content };
+    });
+    return { ...req, ...(system ? { system } : {}), messages };
+}
+export async function* mapClaudeStream(events, priceUsd) {
+    const toolBuffers = new Map();
+    let start = {};
+    let outputTokens = 0;
+    let stopReason = "stop";
+    for await (const ev of events) {
+        switch (ev.type) {
+            case "message_start":
+                start = ev.message.usage ?? {};
+                outputTokens = ev.message.usage?.output_tokens ?? 0;
+                break;
+            case "content_block_start":
+                if (ev.content_block.type === "tool_use") {
+                    toolBuffers.set(ev.index, { id: ev.content_block.id ?? "", name: ev.content_block.name ?? "", argsJson: "" });
+                }
+                break;
+            case "content_block_delta":
+                if (ev.delta.type === "text_delta") {
+                    yield { type: "text", delta: ev.delta.text };
+                }
+                else {
+                    const buf = toolBuffers.get(ev.index);
+                    if (buf)
+                        buf.argsJson += ev.delta.partial_json;
+                }
+                break;
+            case "content_block_stop": {
+                const buf = toolBuffers.get(ev.index);
+                if (buf) {
+                    yield { type: "tool_call", id: buf.id, name: buf.name, argsJson: buf.argsJson };
+                    toolBuffers.delete(ev.index);
+                }
+                break;
+            }
+            case "message_delta":
+                if (ev.delta.stop_reason)
+                    stopReason = ev.delta.stop_reason;
+                if (ev.usage?.output_tokens != null)
+                    outputTokens = ev.usage.output_tokens;
+                break;
+            case "message_stop": {
+                const cachedInputTokens = start.cache_read_input_tokens ?? 0;
+                const cacheWriteTokens = start.cache_creation_input_tokens ?? 0;
+                const inputTokens = (start.input_tokens ?? 0) + cachedInputTokens;
+                const usage = {
+                    inputTokens,
+                    outputTokens,
+                    cachedInputTokens,
+                    cacheWriteTokens,
+                    costUsd: 0,
+                };
+                usage.costUsd = priceUsd(usage);
+                yield { type: "done", stopReason, usage };
+                break;
+            }
+        }
+    }
+}

package/dist/providers/llm/claude-provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LlmProvider implementation shared by every Claude-protocol adapter (direct
+ * Anthropic API, Bedrock-Claude, and any future Claude-protocol client).
+ * Imports no SDK — the client and pricing module are injected, so this file
+ * stays exactly what each concrete adapter (anthropic.ts, bedrock.ts) has in
+ * common, and nothing more.
+ */
+import type { LlmMessage, LlmProvider, LlmRequest, LlmStreamEvent, LlmToolDef } from "./types.js";
+import type { ModelPricing, UsageTokens } from "./pricing-core.js";
+/**
+ * Structural shape every Claude-protocol SDK client satisfies. Loose on
+ * purpose — params/return are untyped here, mirroring the cast anthropic.ts
+ * already needed before this extraction (its own SDK's stream() params/
+ * return never lined up 1:1 with this codebase's own request/event shapes).
+ */
+export interface ClaudeMessagesClient {
+    messages: {
+        stream(params: unknown, options?: {
+            signal?: AbortSignal;
+        }): unknown;
+    };
+}
+export interface ClaudePricingModule {
+    /** Must throw on an unknown model — fail-closed, never price at zero. */
+    getPricing(model: string): ModelPricing;
+    priceUsd(model: string, usage: UsageTokens): number;
+}
+export declare class ClaudeLlmProvider implements LlmProvider {
+    private readonly client;
+    private readonly pricing;
+    constructor(client: ClaudeMessagesClient, pricing: ClaudePricingModule);
+    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    countTokens(model: string, messages: LlmMessage[], tools?: LlmToolDef[]): Promise<number>;
+    priceUsd(model: string, usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cachedInputTokens?: number;
+        cacheWriteTokens?: number;
+    }): number;
+}

package/dist/providers/llm/claude-provider.js

@@ -0,0 +1,31 @@
+import { toClaudeRequest, withCacheBreakpoints, mapClaudeStream, estimateClaudeTokens, } from "./claude-messages.js";
+// Anthropic's own guidance: don't lowball max_tokens — hitting the cap
+// truncates output mid-thought with no error, silently handing engine-native.ts
+// (which never sets LlmRequest.maxTokens, and never checks stopReason) a
+// clipped "final" answer it treats as complete. This adapter streams, so a
+// generous ceiling costs nothing in latency; the budget guardrail is driven
+// by actual token counts (core/budget.ts), not by this cap.
+const DEFAULT_MAX_TOKENS = 16000;
+// Claude has no offline tokenizer; o200k_base is a proxy. Bias high so the
+// pre-flight refuse never admits an over-budget run on an under-count.
+const CLAUDE_TOKEN_INFLATION = 1.2;
+export class ClaudeLlmProvider {
+    client;
+    pricing;
+    constructor(client, pricing) {
+        this.client = client;
+        this.pricing = pricing;
+    }
+    async *stream(req, signal) {
+        const claudeReq = withCacheBreakpoints(toClaudeRequest(req, DEFAULT_MAX_TOKENS));
+        const raw = this.client.messages.stream({ model: req.model, ...claudeReq }, { signal });
+        yield* mapClaudeStream(raw, (usage) => this.priceUsd(req.model, usage));
+    }
+    async countTokens(model, messages, tools) {
+        this.pricing.getPricing(model); // fail-closed on unknown model
+        return Math.ceil(estimateClaudeTokens(messages, tools) * CLAUDE_TOKEN_INFLATION);
+    }
+    priceUsd(model, usage) {
+        return this.pricing.priceUsd(model, usage);
+    }
+}

package/dist/providers/llm/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./pricing.js";
+export * from "./openai.js";
+export { AnthropicLlmProvider, anthropicCredentialsPresent, anthropicSupportedModels } from "./anthropic.js";
+export { BedrockClaudeLlmProvider, bedrockCredentialsPresent, bedrockClaudeSupportedModels } from "./bedrock.js";
+export { ClaudeLlmProvider, type ClaudeMessagesClient, type ClaudePricingModule } from "./claude-provider.js";
+export { openaiCredentialsPresent } from "./openai.js";
+export { supportedModels as openaiSupportedModels } from "./pricing.js";
+export { RoutingLlmProvider, type LlmRegistration } from "./routing.js";
+export { resolveLlmRegistrations, type LlmRegistrationResult } from "./registration.js";

package/dist/providers/llm/index.js

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./pricing.js";
+export * from "./openai.js";
+export { AnthropicLlmProvider, anthropicCredentialsPresent, anthropicSupportedModels } from "./anthropic.js";
+export { BedrockClaudeLlmProvider, bedrockCredentialsPresent, bedrockClaudeSupportedModels } from "./bedrock.js";
+export { ClaudeLlmProvider } from "./claude-provider.js";
+export { openaiCredentialsPresent } from "./openai.js";
+export { supportedModels as openaiSupportedModels } from "./pricing.js";
+export { RoutingLlmProvider } from "./routing.js";
+export { resolveLlmRegistrations } from "./registration.js";

package/dist/providers/llm/openai.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OpenAI adapter for the `LlmProvider` seam — Phase 1's only concrete LLM
+ * adapter. The `openai` npm package is used only inside this file; core
+ * never imports it.
+ */
+import OpenAI from "openai";
+import type { LlmMessage, LlmProvider, LlmRequest, LlmStreamEvent, LlmToolDef } from "./types.js";
+/** Whether the OpenAI adapter has credentials to run (used by the router's enable-by-credential wiring). */
+export declare function openaiCredentialsPresent(env?: NodeJS.ProcessEnv): boolean;
+export declare function estimateTokens(model: string, messages: LlmMessage[], tools?: LlmToolDef[]): number;
+export declare class OpenAiLlmProvider implements LlmProvider {
+    private readonly client;
+    /** `client` is an injection point for tests — a real adapter never passes it. */
+    constructor(apiKey?: string, client?: OpenAI);
+    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    countTokens(model: string, messages: LlmMessage[], tools?: LlmToolDef[]): Promise<number>;
+    priceUsd(model: string, usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cachedInputTokens?: number;
+        cacheWriteTokens?: number;
+    }): number;
+}

package/dist/providers/llm/openai.js

@@ -0,0 +1,156 @@
+/**
+ * OpenAI adapter for the `LlmProvider` seam — Phase 1's only concrete LLM
+ * adapter. The `openai` npm package is used only inside this file; core
+ * never imports it.
+ */
+import OpenAI from "openai";
+import { encode as encodeCl100kBase } from "gpt-tokenizer/encoding/cl100k_base";
+import { encode as encodeO200kBase } from "gpt-tokenizer/encoding/o200k_base";
+import { getModelPricing, priceUsd as priceUsdFromTable } from "./pricing.js";
+/** Whether the OpenAI adapter has credentials to run (used by the router's enable-by-credential wiring). */
+export function openaiCredentialsPresent(env = process.env) {
+    return Boolean(env.OPENAI_API_KEY);
+}
+// Per-message token overhead from OpenAI's public chat-format guidance
+// (role framing + a name field costs a few tokens beyond the raw content).
+// This is a pre-flight *estimate* for the budget guardrail, not an exact
+// match to server-side billing — the real count comes back in `usage` on
+// the `done` event.
+const TOKENS_PER_MESSAGE = 3;
+const TOKENS_PER_NAME = 1;
+const TOKENS_PRIMING_REPLY = 3;
+// gpt-tokenizer's package default is cl100k_base, but every gpt-4o-and-later
+// model (all of Phase 1's roster) actually uses o200k_base — using the
+// wrong table skews the pre-flight token count, which is the budget
+// guardrail's input. The encoding lives on the pricing table (pricing.ts)
+// so a model can't be run without also declaring which tokenizer counts it.
+function encodeForModel(model, text) {
+    const { encoding } = getModelPricing(model);
+    return encoding === "o200k_base" ? encodeO200kBase(text) : encodeCl100kBase(text);
+}
+/** Same shape sent to the API in `stream()` — kept as one function so the estimate can never drift from what's actually serialized. */
+function toOpenAiTools(tools) {
+    return tools.map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+    }));
+}
+// Fixed: this used to count message tokens only. When a request carries
+// `tools`, OpenAI also tokenizes the serialized tool JSON schemas into the
+// prompt — measured live at a 44-52% under-count for a small tool roster,
+// which is what let a turn-1 pre-flight refuse (budget.ts, cumulative
+// spend still zero) admit a run whose real input cost already exceeded
+// budget. Counting `JSON.stringify` of the same payload `stream()` sends
+// is still an *approximation* (not OpenAI's undocumented exact tool-schema
+// tokenization), not a byte-for-byte match — calibration logging
+// (budget.ts's checkTokenCalibration) is what surfaces any remaining drift.
+export function estimateTokens(model, messages, tools) {
+    let total = TOKENS_PRIMING_REPLY;
+    for (const message of messages) {
+        total += TOKENS_PER_MESSAGE;
+        total += encodeForModel(model, message.content).length;
+        total += encodeForModel(model, message.role).length;
+        if (message.name) {
+            total += encodeForModel(model, message.name).length + TOKENS_PER_NAME;
+        }
+    }
+    if (tools && tools.length > 0) {
+        total += encodeForModel(model, JSON.stringify(toOpenAiTools(tools))).length;
+    }
+    return total;
+}
+export class OpenAiLlmProvider {
+    client;
+    /** `client` is an injection point for tests — a real adapter never passes it. */
+    constructor(apiKey = process.env.OPENAI_API_KEY ?? "", client) {
+        if (client) {
+            this.client = client;
+            return;
+        }
+        if (!apiKey) {
+            throw new Error("OPENAI_API_KEY is not set — required by the OpenAI LlmProvider adapter.");
+        }
+        this.client = new OpenAI({ apiKey });
+    }
+    async *stream(req, signal) {
+        const stream = await this.client.chat.completions.create({
+            model: req.model,
+            messages: req.messages.map((m) => ({
+                role: m.role,
+                content: m.content,
+                ...(m.name ? { name: m.name } : {}),
+                ...(m.toolCallId ? { tool_call_id: m.toolCallId } : {}),
+                ...(m.toolCalls && m.toolCalls.length > 0
+                    ? {
+                        tool_calls: m.toolCalls.map((tc) => ({
+                            id: tc.id,
+                            type: "function",
+                            function: { name: tc.name, arguments: tc.argsJson },
+                        })),
+                    }
+                    : {}),
+            })),
+            tools: req.tools ? toOpenAiTools(req.tools) : undefined,
+            max_tokens: req.maxTokens,
+            temperature: req.temperature,
+            stop: req.stopSequences,
+            stream: true,
+            stream_options: { include_usage: true },
+        }, { signal });
+        let stopReason = "stop";
+        // OpenAI streams tool-call arguments fragmented across chunks, keyed by
+        // index — buffer per index until the turn's finish_reason confirms the
+        // call is complete, then emit one `tool_call` event per call.
+        const toolCallBuffers = new Map();
+        for await (const chunk of stream) {
+            const choice = chunk.choices[0];
+            if (choice?.delta?.content) {
+                yield { type: "text", delta: choice.delta.content };
+            }
+            if (choice?.delta?.tool_calls) {
+                for (const fragment of choice.delta.tool_calls) {
+                    const buffered = toolCallBuffers.get(fragment.index) ?? { id: "", name: "", argsJson: "" };
+                    if (fragment.id)
+                        buffered.id = fragment.id;
+                    if (fragment.function?.name)
+                        buffered.name += fragment.function.name;
+                    if (fragment.function?.arguments)
+                        buffered.argsJson += fragment.function.arguments;
+                    toolCallBuffers.set(fragment.index, buffered);
+                }
+            }
+            if (choice?.finish_reason) {
+                stopReason = choice.finish_reason;
+                if (stopReason === "tool_calls") {
+                    for (const toolCall of toolCallBuffers.values()) {
+                        yield { type: "tool_call", id: toolCall.id, name: toolCall.name, argsJson: toolCall.argsJson };
+                    }
+                    toolCallBuffers.clear();
+                }
+            }
+            if (chunk.usage) {
+                // OpenAI's prompt caching is automatic and read-only — no billed
+                // "cache write" step, so cacheWriteTokens stays unset here. Other
+                // future adapters (e.g. Bedrock/Claude) may report and bill one.
+                const cachedInputTokens = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+                const usage = {
+                    inputTokens: chunk.usage.prompt_tokens,
+                    outputTokens: chunk.usage.completion_tokens,
+                    cachedInputTokens,
+                    costUsd: this.priceUsd(req.model, {
+                        inputTokens: chunk.usage.prompt_tokens,
+                        outputTokens: chunk.usage.completion_tokens,
+                        cachedInputTokens,
+                    }),
+                };
+                yield { type: "done", stopReason, usage };
+            }
+        }
+    }
+    async countTokens(model, messages, tools) {
+        return estimateTokens(model, messages, tools);
+    }
+    priceUsd(model, usage) {
+        return priceUsdFromTable(model, usage);
+    }
+}

package/dist/providers/llm/pricing-anthropic.d.ts

@@ -0,0 +1,4 @@
+import { type ModelPricing, type UsageTokens } from "./pricing-core.js";
+export declare function getAnthropicPricing(model: string): ModelPricing;
+export declare function anthropicSupportedModels(): string[];
+export declare function anthropicPriceUsd(model: string, usage: UsageTokens): number;

package/dist/providers/llm/pricing-anthropic.js

@@ -0,0 +1,30 @@
+import { computeCost } from "./pricing-core.js";
+const CACHE_READ_MULT = 0.1;
+const CACHE_WRITE_MULT = 1.25;
+function claude(inputPerMTok, outputPerMTok) {
+    return {
+        encoding: "o200k_base",
+        inputPerMTok,
+        outputPerMTok,
+        cachedInputPerMTok: inputPerMTok * CACHE_READ_MULT,
+        cacheWritePerMTok: inputPerMTok * CACHE_WRITE_MULT,
+    };
+}
+const PRICING = {
+    "claude-opus-5": claude(5, 25),
+    "claude-sonnet-5": claude(2, 10),
+    "claude-fable-5": claude(10, 50),
+    "claude-haiku-4-5": claude(1, 5),
+};
+export function getAnthropicPricing(model) {
+    const p = PRICING[model];
+    if (!p)
+        throw new Error(`No pricing entry for model "${model}" — refusing to price at zero. Add it to src/providers/llm/pricing-anthropic.ts.`);
+    return p;
+}
+export function anthropicSupportedModels() {
+    return Object.keys(PRICING);
+}
+export function anthropicPriceUsd(model, usage) {
+    return computeCost(getAnthropicPricing(model), usage);
+}

package/dist/providers/llm/pricing-bedrock-claude.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bedrock-Claude pricing table. Every entry is a fully literal, hardcoded
+ * ModelPricing — every field, including cache read/write, is the provider's
+ * own published rate for that exact model, never derived from another
+ * field via a ratio (see CLAUDE.md "LLM pricing tables — STRICT": a
+ * multiplier that happens to be correct today silently goes stale the
+ * moment one model's real cache pricing diverges from the pattern).
+ */
+import { type ModelPricing, type UsageTokens } from "./pricing-core.js";
+export declare function getBedrockClaudePricing(model: string): ModelPricing;
+export declare function bedrockClaudeSupportedModels(): string[];
+export declare function bedrockClaudePriceUsd(model: string, usage: UsageTokens): number;

package/dist/providers/llm/pricing-bedrock-claude.js

@@ -0,0 +1,37 @@
+/**
+ * Bedrock-Claude pricing table. Every entry is a fully literal, hardcoded
+ * ModelPricing — every field, including cache read/write, is the provider's
+ * own published rate for that exact model, never derived from another
+ * field via a ratio (see CLAUDE.md "LLM pricing tables — STRICT": a
+ * multiplier that happens to be correct today silently goes stale the
+ * moment one model's real cache pricing diverges from the pattern).
+ */
+import { computeCost } from "./pricing-core.js";
+function claude(inputPerMTok, outputPerMTok, cachedInputPerMTok, cacheWritePerMTok) {
+    return { encoding: "o200k_base", inputPerMTok, outputPerMTok, cachedInputPerMTok, cacheWritePerMTok };
+}
+// These are `us.` cross-region inference profiles (region us-east-1) — routability
+// is keyed by model ID only; region is a separate adapter concern
+// (BEDROCK_REGION/AWS_REGION). Rates below are the exact published 5-minute
+// cache-TTL numbers (platform.claude.com/docs/en/about-claude/pricing,
+// confirmed 2026-09-08) — this adapter only ever emits the default 5-minute
+// cache_control breakpoint (see claude-messages.ts's withCacheBreakpoints),
+// so the 1-hour-TTL rates are out of scope and not stored here.
+const PRICING = {
+    "us.anthropic.claude-sonnet-4-6": claude(3, 15, 0.3, 3.75),
+    "us.anthropic.claude-opus-4-6-v1": claude(5, 25, 0.5, 6.25),
+    "us.anthropic.claude-opus-4-8": claude(5, 25, 0.5, 6.25),
+    "us.anthropic.claude-haiku-4-5-20251001-v1:0": claude(1, 5, 0.1, 1.25),
+};
+export function getBedrockClaudePricing(model) {
+    const p = PRICING[model];
+    if (!p)
+        throw new Error(`No pricing entry for model "${model}" — refusing to price at zero. Add it to src/providers/llm/pricing-bedrock-claude.ts.`);
+    return p;
+}
+export function bedrockClaudeSupportedModels() {
+    return Object.keys(PRICING);
+}
+export function bedrockClaudePriceUsd(model, usage) {
+    return computeCost(getBedrockClaudePricing(model), usage);
+}

package/dist/providers/llm/pricing-core.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared pricing types + cost math, provider-agnostic. Each LLM adapter
+ * owns its own model table but prices through this one `computeCost`, so the
+ * cache-read/cache-write accounting can never diverge between providers.
+ */
+export type TokenizerEncoding = "cl100k_base" | "o200k_base";
+export interface ModelPricing {
+    encoding: TokenizerEncoding;
+    inputPerMTok: number;
+    outputPerMTok: number;
+    cachedInputPerMTok?: number;
+    cacheWritePerMTok?: number;
+}
+export interface UsageTokens {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    cacheWriteTokens?: number;
+}
+/**
+ * A model missing `cachedInputPerMTok` / `cacheWritePerMTok` falls back to the
+ * full input rate — fail-toward-overestimate, never underestimate.
+ * `inputTokens` is the total billed at the *fresh* rate PLUS cache-read;
+ * cache-write tokens are billed separately and are NOT part of `inputTokens`.
+ */
+export declare function computeCost(pricing: ModelPricing, usage: UsageTokens): number;

package/dist/providers/llm/pricing-core.js

@@ -0,0 +1,17 @@
+/**
+ * A model missing `cachedInputPerMTok` / `cacheWritePerMTok` falls back to the
+ * full input rate — fail-toward-overestimate, never underestimate.
+ * `inputTokens` is the total billed at the *fresh* rate PLUS cache-read;
+ * cache-write tokens are billed separately and are NOT part of `inputTokens`.
+ */
+export function computeCost(pricing, usage) {
+    const cachedInputTokens = usage.cachedInputTokens ?? 0;
+    const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
+    const freshInputTokens = usage.inputTokens - cachedInputTokens;
+    const cachedRate = pricing.cachedInputPerMTok ?? pricing.inputPerMTok;
+    const cacheWriteRate = pricing.cacheWritePerMTok ?? pricing.inputPerMTok;
+    return ((freshInputTokens / 1_000_000) * pricing.inputPerMTok +
+        (cachedInputTokens / 1_000_000) * cachedRate +
+        (cacheWriteTokens / 1_000_000) * cacheWriteRate +
+        (usage.outputTokens / 1_000_000) * pricing.outputPerMTok);
+}

package/dist/providers/llm/pricing.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Static price + tokenizer table for the budget guardrail.
+ *
+ * Sourced from OpenAI's public pricing page at write time. Deliberately
+ * static (no pricing API call) so `priceUsd` stays synchronous and
+ * network-free — the budget math must work offline and in tests. An unknown
+ * model throws rather than silently pricing at zero, so a misconfigured
+ * agent can never bypass the budget guardrail by accident.
+ *
+ * `encoding` is here too (not just price) because it drives which
+ * `gpt-tokenizer` BPE table `countTokens` uses — every gpt-4o-and-later
+ * model uses `o200k_base`, not the older `cl100k_base` gpt-tokenizer
+ * defaults to. Keeping both in one table means a model can't be priced
+ * without also being told which tokenizer estimates its input cost.
+ *
+ * `cachedInputPerMTok` / `cacheWritePerMTok` are optional: not every model's
+ * entry carries verified cache rates. When a model has cached or
+ * cache-write tokens but no rate for them, `priceUsd` falls back to the
+ * full (non-cached) input rate — the same fail-toward-overestimate
+ * direction as the unknown-model error, never fail-toward-underestimate.
+ */
+import { type ModelPricing, type UsageTokens } from "./pricing-core.js";
+export { computeCost } from "./pricing-core.js";
+export type { ModelPricing, TokenizerEncoding, UsageTokens } from "./pricing-core.js";
+/** Bump whenever a rate changes so durable reservations retain their original terms. */
+export declare const PRICING_VERSION = "2026-09-06";
+/** Looks up a model's pricing/tokenizer entry, or throws (fail closed). */
+export declare function getModelPricing(model: string): ModelPricing;
+export declare function supportedModels(): string[];
+export declare function priceUsd(model: string, usage: UsageTokens): number;