@juno-ai/bind 1.0.0 → 3.0.0

package/contracts/index.d.ts

@@ -1 +1 @@
-export { emptyRunStats, accumulateTurn, accumulateToolCall, type TranscriptMessage, type AssistantTurnMessage, type WireToolDefinition, type WireToolCall, type TurnTimings, type TurnUsage, type ModelTurnResult, type TurnFn, type StopReason, type RunStats, } from "./turn";
+export { emptyRunStats, accumulateTurn, accumulateToolCall, type TranscriptMessage, type AssistantTurnMessage, type WireToolDefinition, type WireToolCall, type TurnTimings, type TurnUsage, type ModelTurnResult, type TurnFn, type StopReason, type RunStats, } from "./turn.js";

package/contracts/index.js

@@ -1 +1 @@
-export { emptyRunStats, accumulateTurn, accumulateToolCall, } from "./turn";
+export { emptyRunStats, accumulateTurn, accumulateToolCall, } from "./turn.js";

package/contracts/turn.d.ts

@@ -8,9 +8,9 @@ import type OpenAI from "openai";
  * declarations here; no runtime import). Hosts on other client stacks (e.g.
  * the Vercel AI SDK) adapt at the turn-function boundary.
  *
- * NOTE: `ToolPlugin` / tool-context contracts deliberately do NOT live here
- * yet — they are being reshaped by the single-agent consolidation work in
- * the host repo and move here once that lands.
+ * The tool/plugin vocabulary is a separate contract and lives in `plugins/`,
+ * not here: this module is about what a turn *is* on the wire, while that one
+ * is about what a host can register and how the harness discloses it.
  */
 export type TranscriptMessage = OpenAI.ChatCompletionMessageParam;
 export type AssistantTurnMessage = OpenAI.ChatCompletionMessage;
@@ -18,8 +18,8 @@ export type WireToolDefinition = OpenAI.ChatCompletionTool;
 export type WireToolCall = OpenAI.ChatCompletionMessageToolCall;
 /**
  * Per-turn latency/throughput measurements. Field shapes deliberately match
- * the metrics the AA/StirrupJS harness reports (`speedStats`) so numbers are
- * directly comparable with published benchmark methodology:
+ * the metrics the StirrupJS benchmark harness reports (`speedStats`), so
+ * numbers are directly comparable with published benchmark methodology:
  * time-to-first-token, generation wall time, and output tokens/second —
  * plus the model-time vs tool-time split that per-task wall-clock hides.
  */

package/index.d.ts

@@ -5,9 +5,17 @@
  * completion into tool effects into the next turn's context. This package is
  * the harness that runs that chain.
  *
- * Current surface: the deterministic LLM provider-routing core (see
- * `docs/bind.md` and the LLM Provider Routing PRD). The turn kernel and tool
- * contracts move here in later extraction phases.
+ * Current surface: the deterministic LLM provider-routing core, the turn
+ * vocabulary, the run mechanics (deadline, coalesced heartbeat, failure
+ * classification, tool-batch pooling), transcript validation/healing, provider
+ * tool-schema sanitization, and the plugin/tool vocabulary with its registry
+ * and progressive-disclosure activation (`src/plugins/`, generic over the
+ * host's invocation context). The turn kernel arrives in a later phase; see
+ * the README for what is deliberately not here yet.
  */
-export * from "./routing/index";
-export * from "./contracts/index";
+export * from "./routing/index.js";
+export * from "./contracts/index.js";
+export * from "./run/index.js";
+export * from "./transcript/index.js";
+export * from "./tools/index.js";
+export * from "./plugins/index.js";

package/index.js

@@ -5,9 +5,17 @@
  * completion into tool effects into the next turn's context. This package is
  * the harness that runs that chain.
  *
- * Current surface: the deterministic LLM provider-routing core (see
- * `docs/bind.md` and the LLM Provider Routing PRD). The turn kernel and tool
- * contracts move here in later extraction phases.
+ * Current surface: the deterministic LLM provider-routing core, the turn
+ * vocabulary, the run mechanics (deadline, coalesced heartbeat, failure
+ * classification, tool-batch pooling), transcript validation/healing, provider
+ * tool-schema sanitization, and the plugin/tool vocabulary with its registry
+ * and progressive-disclosure activation (`src/plugins/`, generic over the
+ * host's invocation context). The turn kernel arrives in a later phase; see
+ * the README for what is deliberately not here yet.
  */
-export * from "./routing/index";
-export * from "./contracts/index";
+export * from "./routing/index.js";
+export * from "./contracts/index.js";
+export * from "./run/index.js";
+export * from "./transcript/index.js";
+export * from "./tools/index.js";
+export * from "./plugins/index.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juno-ai/bind",
-  "version": "1.0.0",
-  "description": "Agent harness: deterministic LLM provider routing core and turn contracts (turn kernel arrives in later phases). MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
+  "version": "3.0.0",
+  "description": "Agent harness: deterministic LLM provider routing, run mechanics, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary (turn kernel arrives in a later phase). MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
@@ -18,6 +18,22 @@
     "./contracts": {
       "types": "./contracts/index.d.ts",
       "import": "./contracts/index.js"
+    },
+    "./run": {
+      "types": "./run/index.d.ts",
+      "import": "./run/index.js"
+    },
+    "./transcript": {
+      "types": "./transcript/index.d.ts",
+      "import": "./transcript/index.js"
+    },
+    "./tools": {
+      "types": "./tools/index.d.ts",
+      "import": "./tools/index.js"
+    },
+    "./plugins": {
+      "types": "./plugins/index.d.ts",
+      "import": "./plugins/index.js"
     }
   },
   "peerDependencies": {

package/plugins/activation.d.ts

@@ -0,0 +1,67 @@
+import type { PluginSummary } from "./registry.js";
+/**
+ * Progressive tool disclosure: which plugins are loaded right now, and how a
+ * persisted set is restored across a run boundary.
+ *
+ * Two-tier disclosure exists because tool-selection accuracy degrades once a
+ * model sees more than a few dozen tools, and because every tool's JSON Schema
+ * is resent on every turn. Core plugins load unconditionally; the rest are
+ * announced as a compact catalog and activated on demand.
+ *
+ * The governing rule for restoring a persisted set is that **it is a hint, not
+ * a fact**. Names are persisted; implementations are resolved at load time, and
+ * anything that no longer resolves is dropped rather than reported as active —
+ * a plugin can be renamed, gated off, or (for a dynamically connected one) fail
+ * to reconnect between runs.
+ */
+/** Why a persisted activation could not be restored. */
+export type ActivationDropReason = "unknown" | "unavailable" | "unreachable" | "error";
+export interface DroppedActivation {
+    /** The canonicalized name that was dropped. */
+    name: string;
+    reason: ActivationDropReason;
+}
+export interface RehydrateResult {
+    /** Canonicalized, de-duplicated names that resolved and stay active. */
+    active: string[];
+    /** Everything that did not survive, for the host to log. */
+    dropped: DroppedActivation[];
+}
+export interface RehydrateOptions {
+    /** Map a persisted (possibly legacy) name to its current canonical name. */
+    canonicalizeName: (name: string) => string;
+    /**
+     * Can this name be activated on THIS run? Async because restoring a
+     * dynamically connected plugin may require re-establishing a connection —
+     * the harness owns the policy, the host owns the transport.
+     *
+     * Return `true` to keep, or a drop reason to discard.
+     */
+    resolve: (name: string) => ActivationDropReason | true | Promise<ActivationDropReason | true>;
+    /**
+     * Observe a resolver rejection. The entry is dropped as `"error"` either way,
+     * and an observer that throws is swallowed — reporting a failure must not
+     * turn one bad name into a failed restore.
+     */
+    onResolveError?: (name: string, error: unknown) => void;
+}
+/**
+ * Restore a persisted activation set, re-validating every entry against
+ * current reality. Order is preserved; duplicates (including two legacy names
+ * that canonicalize to the same plugin) collapse to the first occurrence.
+ */
+export declare function rehydrateActivation(persisted: readonly string[], options: RehydrateOptions): Promise<RehydrateResult>;
+/** The activation set a fresh run starts from. */
+export declare function initialActivePlugins(corePlugins: readonly string[]): string[];
+export interface CatalogPartition {
+    active: PluginSummary[];
+    loadable: PluginSummary[];
+}
+/**
+ * Split the catalog into what is already active and what the model may load.
+ *
+ * This returns **data, not prose**: the wording of a catalog belongs to the
+ * host's system prompt, which is a product surface with its own voice and
+ * (in Monad's case) its own byte-for-byte prompt-cache concerns.
+ */
+export declare function partitionPluginCatalog(activePlugins: ReadonlySet<string>, allSummaries: readonly PluginSummary[]): CatalogPartition;

package/plugins/activation.js

@@ -0,0 +1,61 @@
+/**
+ * Restore a persisted activation set, re-validating every entry against
+ * current reality. Order is preserved; duplicates (including two legacy names
+ * that canonicalize to the same plugin) collapse to the first occurrence.
+ */
+export async function rehydrateActivation(persisted, options) {
+    const active = [];
+    const dropped = [];
+    const seen = new Set();
+    for (const rawName of persisted) {
+        const name = options.canonicalizeName(rawName);
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        // A throwing resolver drops its entry rather than failing the walk. The
+        // contract is best-effort restoration, and a host resolver that reaches a
+        // database or decrypts a credential can reject transiently — one bad name
+        // must not cost the caller every other restored plugin.
+        let verdict;
+        try {
+            verdict = await options.resolve(name);
+        }
+        catch (error) {
+            try {
+                options.onResolveError?.(name, error);
+            }
+            catch {
+                // An observer that throws (a logger choking on a circular error, a
+                // metrics client rejecting) would otherwise defeat the very guarantee
+                // this catch exists to provide.
+            }
+            // Not `unreachable`: that reason means a dynamic plugin failed to
+            // reconnect, and a resolver can just as well throw while checking a
+            // static plugin. Reporting the failure as its own kind keeps the host's
+            // drop logging honest about what it knows.
+            verdict = "error";
+        }
+        if (verdict === true)
+            active.push(name);
+        else
+            dropped.push({ name, reason: verdict });
+    }
+    return { active, dropped };
+}
+/** The activation set a fresh run starts from. */
+export function initialActivePlugins(corePlugins) {
+    return [...new Set(corePlugins)];
+}
+/**
+ * Split the catalog into what is already active and what the model may load.
+ *
+ * This returns **data, not prose**: the wording of a catalog belongs to the
+ * host's system prompt, which is a product surface with its own voice and
+ * (in Monad's case) its own byte-for-byte prompt-cache concerns.
+ */
+export function partitionPluginCatalog(activePlugins, allSummaries) {
+    return {
+        active: allSummaries.filter((summary) => activePlugins.has(summary.name)),
+        loadable: allSummaries.filter((summary) => !activePlugins.has(summary.name)),
+    };
+}

package/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export { hasContentParts, type ToolAnnotations, type ToolDef, type ToolFailureKind, type ToolPlugin, type ToolResult, type RegistrablePlugin, type SuspendDirective, } from "./tool.js";
+export { createToolRegistry, type PluginSummary, type ToolRegistry, type ToolRegistryOptions, } from "./registry.js";
+export { rehydrateActivation, initialActivePlugins, partitionPluginCatalog, type ActivationDropReason, type CatalogPartition, type DroppedActivation, type RehydrateOptions, type RehydrateResult, } from "./activation.js";

package/plugins/index.js

@@ -0,0 +1,3 @@
+export { hasContentParts, } from "./tool.js";
+export { createToolRegistry, } from "./registry.js";
+export { rehydrateActivation, initialActivePlugins, partitionPluginCatalog, } from "./activation.js";

package/plugins/registry.d.ts

@@ -0,0 +1,52 @@
+import type { RegistrablePlugin } from "./tool.js";
+/**
+ * A plugin registry, created as a **factory rather than a module singleton**.
+ *
+ * Monad's original registry was a module-level `Map` populated by
+ * self-registration at import time. That is workable in a long-lived Node
+ * process but wrong for a package targeting workerd isolates (module state is
+ * per-isolate and its lifetime is not the host's) and it makes tests share
+ * state implicitly. A host that wants the singleton ergonomics can still wrap
+ * one instance in a module — the choice moves to the host, which is where it
+ * belongs.
+ */
+export interface PluginSummary {
+    name: string;
+    description: string;
+    isCorePlugin: boolean;
+}
+export interface ToolRegistryOptions<TPlugin extends RegistrablePlugin> {
+    /**
+     * Always-active plugins, loaded on every run without explicit activation.
+     */
+    corePlugins: readonly string[];
+    /**
+     * Compatibility aliases for historical plugin names, mapping an old name to
+     * the current canonical one. Persisted activation state stores names, so an
+     * alias is how a rename avoids silently stripping capabilities from live
+     * sessions without a data migration. Entries are permanent.
+     */
+    aliases?: Readonly<Record<string, string>>;
+    /**
+     * Called after a plugin is registered. The seam for host-side side effects
+     * of registration (e.g. contributing a plugin's skills into a separate
+     * registry) without the harness knowing what those are.
+     */
+    onRegister?: (plugin: TPlugin) => void;
+}
+export interface ToolRegistry<TPlugin extends RegistrablePlugin> {
+    register(plugin: TPlugin): void;
+    /** Resolve by name (following aliases); `undefined` when absent or unavailable. */
+    get(name: string): TPlugin | undefined;
+    /** The canonical registered name for `name`, following any alias. */
+    canonicalizeName(name: string): string;
+    corePlugins(): string[];
+    isCoreName(name: string): boolean;
+    /** Every registered plugin, including currently-unavailable ones. */
+    all(): TPlugin[];
+    /** Summaries of available plugins only. */
+    summaries(): PluginSummary[];
+    /** Names of available plugins — the single source of truth for "what exists". */
+    availableNames(): string[];
+}
+export declare function createToolRegistry<TPlugin extends RegistrablePlugin>(options: ToolRegistryOptions<TPlugin>): ToolRegistry<TPlugin>;

package/plugins/registry.js

@@ -0,0 +1,54 @@
+export function createToolRegistry(options) {
+    const plugins = new Map();
+    const core = [...new Set(options.corePlugins)];
+    const coreSet = new Set(core);
+    const aliases = options.aliases ?? {};
+    // Own-property check, not `aliases[name] ?? name`: a bare index reads
+    // through Object.prototype, so a lookup of "constructor" or "toString"
+    // returns an inherited function instead of the name. Hosts supply arbitrary
+    // alias maps, and a plugin may legitimately be named either.
+    //
+    // The `typeof` check is not redundant with the declared type: a host may
+    // build its alias map from JSON or another untyped source, and this function
+    // is a hard invariant — every caller downstream treats the result as a
+    // string. Falling back to the input beats returning a lie.
+    const canonicalizeName = (name) => {
+        if (!Object.prototype.hasOwnProperty.call(aliases, name))
+            return name;
+        const alias = aliases[name];
+        return typeof alias === "string" ? alias : name;
+    };
+    const isAvailable = (plugin) => plugin.isAvailable?.() ?? true;
+    return {
+        register(plugin) {
+            plugins.set(plugin.name, plugin);
+            options.onRegister?.(plugin);
+        },
+        get(name) {
+            const plugin = plugins.get(name) ?? plugins.get(canonicalizeName(name));
+            return plugin && isAvailable(plugin) ? plugin : undefined;
+        },
+        canonicalizeName,
+        corePlugins() {
+            return [...core];
+        },
+        isCoreName(name) {
+            return coreSet.has(name);
+        },
+        all() {
+            return [...plugins.values()];
+        },
+        summaries() {
+            return [...plugins.values()].filter(isAvailable).map((plugin) => ({
+                name: plugin.name,
+                description: plugin.description,
+                isCorePlugin: coreSet.has(plugin.name),
+            }));
+        },
+        availableNames() {
+            return [...plugins.values()]
+                .filter(isAvailable)
+                .map((plugin) => plugin.name);
+        },
+    };
+}

package/plugins/tool.d.ts

@@ -0,0 +1,164 @@
+import type { z } from "zod";
+/**
+ * The plugin/tool vocabulary — the shape of a tool, a bundle of tools, and
+ * the result of running one.
+ *
+ * Two things are deliberately NOT fixed here, because they are where hosts
+ * genuinely diverge rather than incidentally differ:
+ *
+ *  - **The invocation context** (`TCtx`). A census of two production agent
+ *    runtimes' contexts found ~33 fields of which exactly one (`abortSignal`)
+ *    was shared; the rest are host identity (tenant, workspace, thread, role),
+ *    host authorization (principal, scope clamps), or host product
+ *    features. A common concrete context would be either a
+ *    lowest-common-denominator or a union of two products' identity models,
+ *    so the context is a type parameter and the host supplies it.
+ *
+ *  - **Multimodal content parts** (`TContentPart`). The wire shape is the
+ *    provider's, but building one from bytes needs host capabilities, so the
+ *    harness carries the parts through without interpreting them.
+ *
+ * Hosts extend `ToolPlugin` with their own fields via ordinary interface
+ * extension (Monad adds `configuration`, `skills`, `exposeViaMcp`).
+ */
+/**
+ * Behavioural hints that travel with a tool on `tools/list`. Mirrors
+ * the MCP `ToolAnnotations` shape — duplicated here so plugins can
+ * declare them without importing the SDK directly.
+ */
+export interface ToolAnnotations {
+    /** Human-readable title for the tool. */
+    title?: string;
+    /** True if the tool only reads data. */
+    readOnlyHint?: boolean;
+    /** True if the tool may make destructive changes. Meaningful only when readOnlyHint===false. */
+    destructiveHint?: boolean;
+    /** True if calling the tool with the same args yields the same result. */
+    idempotentHint?: boolean;
+    /** True if the tool may interact with external systems. */
+    openWorldHint?: boolean;
+}
+export interface ToolDef {
+    name: string;
+    description: string;
+    parameters: z.ZodType;
+    /**
+     * Pure post-parse canonicalization applied before run-scoped idempotency
+     * hashing and execution. Keep model-facing schemas JSON-Schema-compatible;
+     * semantic normalization such as sorting set-like arrays belongs here.
+     */
+    normalizeArgs?: (args: unknown) => unknown;
+    /**
+     * Pre-computed JSON Schema to pass to the LLM instead of converting via
+     * `z.toJSONSchema()`. Also the seam for a host whose tools are authored as
+     * raw JSON Schema rather than zod.
+     */
+    rawJsonSchema?: Record<string, unknown>;
+    /** Annotations forwarded on the MCP `tools/list` response. */
+    annotations?: ToolAnnotations;
+    /** If true, the dispatcher emits a periodic auto-heartbeat. */
+    supportsProgress?: boolean;
+    /**
+     * When `true`, the tool stays runnable (dispatch + `plugin.tools` lookup
+     * still resolve it) but is omitted from the model-facing catalog. Used to
+     * retire a tool from the prompt while keeping it callable for resumed
+     * sessions whose history still references it.
+     */
+    hidden?: boolean;
+    /**
+     * Optional human one-liner describing THIS call, derived from its args.
+     * MUST be pure + synchronous: `safeParse` the args with the tool's own
+     * schema, then read fields — no I/O, no context. Returns `null` to fall
+     * back to generic copy. Purity is load-bearing: it runs on the executor
+     * hot path inside a fire-and-forget emit.
+     */
+    summarizeActivity?: (args: unknown) => string | null;
+}
+/**
+ * Structured failure category for a failed `ToolResult`. Lets a host map a
+ * plugin failure onto its own error taxonomy — a protocol error code, an HTTP
+ * status, a retry decision — without matching on the error string, which is
+ * brittle and locale-dependent. Plugins should set it explicitly.
+ */
+export type ToolFailureKind = "authz" | "validation" | "not_found" | "conflict" | "external" | "system";
+/**
+ * Human-in-the-loop suspend directive. A first-party tool returns this on a
+ * successful result to **end the run** and record its open tool-call as
+ * awaiting resolution. Two resume kinds:
+ *  - `answer`: the run resumes by threading a human/external response back as
+ *    the matching `role:"tool"` result. The loop therefore WITHHOLDS this
+ *    call's tool message — the result is the future answer.
+ *  - `wake`: a time/event resume that re-enters via a prompt and keeps the
+ *    tool message.
+ * `request` is an opaque render/route payload, validated by the consumer and
+ * never inspected by the loop.
+ */
+export type SuspendDirective = {
+    reason: string;
+    resumeKind: "answer" | "wake";
+    request?: unknown;
+};
+export type ToolResult<TContentPart = unknown> = {
+    success: true;
+    data: unknown;
+    contentParts?: TContentPart[];
+    suspend?: SuspendDirective;
+} | {
+    success: false;
+    error: string;
+    kind?: ToolFailureKind;
+    /** Optional structured recovery context safe to expose to the model. */
+    data?: unknown;
+};
+/**
+ * Narrow helper: does this tool result ask the executor to relay multimodal
+ * content parts alongside the textual JSON result on the next turn?
+ */
+export declare function hasContentParts<TContentPart>(result: ToolResult<TContentPart>): result is {
+    success: true;
+    data: unknown;
+    contentParts: TContentPart[];
+    suspend?: SuspendDirective;
+};
+/**
+ * A self-contained bundle of related tools plus the metadata the catalog and
+ * the system prompt need. `execute` dispatches by tool name so a plugin can
+ * share setup across its tools.
+ */
+export interface ToolPlugin<TCtx, TContentPart = unknown> {
+    name: string;
+    description: string;
+    /**
+     * Optional short icon identifier a host UI may use to pick a glyph. Optional
+     * because a headless consumer has no glyph to pick; a host that renders tool
+     * activity can re-require it on its own extension of this interface.
+     */
+    icon?: string;
+    /**
+     * Global availability gate; unavailable plugins stay registered (so they can
+     * still be listed for configuration) but do not resolve for a run.
+     *
+     * **Must be constant for the lifetime of the process or isolate.** It is
+     * re-evaluated on every catalog render — which, for a host that re-renders
+     * its system prompt on each activation, is several times per run. A value
+     * that can flip mid-run (a TTL-cached feature flag, a health probe, a live
+     * credential check) rewrites the catalog and invalidates the provider
+     * prompt-cache prefix from that byte onward for every remaining turn, and
+     * nothing will fail a test. Gate on process-stable configuration; do the
+     * liveness check inside `execute`, where a failure is a tool error.
+     */
+    isAvailable?: () => boolean;
+    /** Instructions appended to the system prompt when this plugin is active. */
+    systemMessage?: string;
+    tools: ToolDef[];
+    execute(toolName: string, args: unknown, ctx: TCtx): Promise<ToolResult<TContentPart>>;
+}
+/**
+ * The structural minimum the registry and catalog need. Hosts pass their own
+ * richer plugin type; this is the constraint, not the contract.
+ */
+export interface RegistrablePlugin {
+    name: string;
+    description: string;
+    isAvailable?: () => boolean;
+}

package/plugins/tool.js

@@ -0,0 +1,9 @@
+/**
+ * Narrow helper: does this tool result ask the executor to relay multimodal
+ * content parts alongside the textual JSON result on the next turn?
+ */
+export function hasContentParts(result) {
+    return (result.success === true &&
+        Array.isArray(result.contentParts) &&
+        result.contentParts.length > 0);
+}

package/routing/billing-basis.d.ts

@@ -0,0 +1,48 @@
+import type { ProviderPricingBasis } from "./plan.js";
+/**
+ * Synchronous provider billing-basis cost —
+ * the configured-list-rate calculation used when a provider (Azure) reports
+ * usage but not dollars. OpenRouter's provider-reported cost keeps the
+ * existing path in `llm.ts` and never goes through this function.
+ *
+ * Results are USD cents at the inference log's numeric(10, 4) precision.
+ */
+export interface BillingBasisUsage {
+    readonly inputTokens: number;
+    /**
+     * Provider-reported cached (discounted) input tokens. Whether this is a
+     * subset of `inputTokens` or a disjoint count is DECLARED by the binding's
+     * `cachedTokenSemantics` — never inferred from the relative sizes.
+     */
+    readonly cachedInputTokens: number;
+    /**
+     * Provider completion-token total. Already includes reasoning tokens — do
+     * not add them a second time.
+     */
+    readonly outputTokens: number;
+}
+export type BillingBasisResult = Readonly<{
+    ok: true;
+    costCents: number;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Compute the list-rate cost in USD cents from usage and configured
+ * per-million-token rates. Rejects internally inconsistent usage rather than
+ * producing a zero-cost call: negative counts, non-integers,
+ * all-zero usage (a request always consumes prompt tokens — zeros mean the
+ * provider's accounting is broken, not that the call was free), and — under
+ * declared `"subset"` semantics — cached counts exceeding total input.
+ *
+ * The uncached-input calculation follows the binding's declared
+ * `cachedTokenSemantics`:
+ * - `"subset"`  — cached ⊆ input (OpenAI): uncached = input − cached.
+ * - `"disjoint"` — cached reported alongside input (Grok via Azure AI
+ *   Foundry, observed live: cached 192 vs prompt 88): uncached = input.
+ * Either way every token prices exactly once at its own rate.
+ */
+export declare function computeConfiguredRatesCostCents(pricing: Extract<ProviderPricingBasis, {
+    kind: "configured_token_rates";
+}>, usage: BillingBasisUsage): BillingBasisResult;

package/routing/billing-basis.js

@@ -0,0 +1,67 @@
+function isUsableCount(value) {
+    return Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+}
+function roundToScale4(value) {
+    return Math.round(value * 10_000) / 10_000;
+}
+/**
+ * Compute the list-rate cost in USD cents from usage and configured
+ * per-million-token rates. Rejects internally inconsistent usage rather than
+ * producing a zero-cost call: negative counts, non-integers,
+ * all-zero usage (a request always consumes prompt tokens — zeros mean the
+ * provider's accounting is broken, not that the call was free), and — under
+ * declared `"subset"` semantics — cached counts exceeding total input.
+ *
+ * The uncached-input calculation follows the binding's declared
+ * `cachedTokenSemantics`:
+ * - `"subset"`  — cached ⊆ input (OpenAI): uncached = input − cached.
+ * - `"disjoint"` — cached reported alongside input (Grok via Azure AI
+ *   Foundry, observed live: cached 192 vs prompt 88): uncached = input.
+ * Either way every token prices exactly once at its own rate.
+ */
+export function computeConfiguredRatesCostCents(pricing, usage) {
+    if (!isUsableCount(usage.inputTokens)) {
+        return { ok: false, reason: `invalid input token count: ${usage.inputTokens}` };
+    }
+    if (!isUsableCount(usage.cachedInputTokens)) {
+        return {
+            ok: false,
+            reason: `invalid cached input token count: ${usage.cachedInputTokens}`,
+        };
+    }
+    if (!isUsableCount(usage.outputTokens)) {
+        return { ok: false, reason: `invalid output token count: ${usage.outputTokens}` };
+    }
+    if (usage.inputTokens === 0 &&
+        usage.cachedInputTokens === 0 &&
+        usage.outputTokens === 0) {
+        return { ok: false, reason: "all-zero usage (provider reported no tokens)" };
+    }
+    let uncachedInputTokens;
+    switch (pricing.cachedTokenSemantics) {
+        case "subset":
+            if (usage.cachedInputTokens > usage.inputTokens) {
+                return {
+                    ok: false,
+                    reason: `cached input tokens (${usage.cachedInputTokens}) exceed input tokens ` +
+                        `(${usage.inputTokens}) under declared "subset" semantics — if this ` +
+                        `provider reports cached tokens alongside prompt tokens, declare ` +
+                        `cachedTokenSemantics: "disjoint" on its binding`,
+                };
+            }
+            uncachedInputTokens = usage.inputTokens - usage.cachedInputTokens;
+            break;
+        case "disjoint":
+            uncachedInputTokens = usage.inputTokens;
+            break;
+        default: {
+            const _exhaustive = pricing.cachedTokenSemantics;
+            throw new Error(`unknown cached-token semantics: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+    const usd = (uncachedInputTokens * pricing.inputUsdPerM +
+        usage.cachedInputTokens * pricing.cachedInputUsdPerM +
+        usage.outputTokens * pricing.outputUsdPerM) /
+        1_000_000;
+    return { ok: true, costCents: roundToScale4(usd * 100) };
+}