network-ai 5.12.7 → 5.13.0

package/dist/lib/model-budget.d.ts

@@ -0,0 +1,144 @@
+/**
+ * ModelBudget — cross-model cost accounting with fallback-credit repricing.
+ *
+ * Where {@link ../lib/federated-budget!FederatedBudget} tracks raw token counts
+ * against a shared ceiling, `ModelBudget` tracks **money**. It prices each
+ * attempt with a per-model rate card, distinguishes cache-read from cache-write
+ * input tokens, and — critically for a refusal → fallback flow — reprices a
+ * redeemed fallback credit so the retry is billed as a cache read (≈10% of the
+ * base input rate) instead of a cache write (1.25×–2×).
+ *
+ * It satisfies the `BudgetSink` contract consumed by
+ * {@link ../lib/model-gateway!GovernedModelGateway}, and can optionally forward
+ * token totals into a `FederatedBudget` for unified swarm-wide ceilings.
+ *
+ * @module ModelBudget
+ * @version 1.0.0
+ * @license MIT
+ */
+/** Per-model rate card. Multipliers are applied to the input rate. */
+export interface ModelPricing {
+    /** USD per million input tokens. */
+    inputPerMTok: number;
+    /** USD per million output tokens. */
+    outputPerMTok: number;
+    /** Multiplier on the input rate for cache-read tokens. Default `0.1`. */
+    cacheReadMultiplier?: number;
+    /** Multiplier on the input rate for cache-creation (write) tokens. Default `1.25`. */
+    cacheWriteMultiplier?: number;
+}
+/** Token usage for a single attempt. Matches the gateway's `ModelUsage`. */
+export interface UsageLike {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+}
+/** Minimal token-budget contract (a `FederatedBudget` satisfies this). */
+export interface TokenBudgetLike {
+    spend(agentId: string, tokens: number): {
+        allowed: boolean;
+    };
+}
+/** Construction options for {@link ModelBudget}. */
+export interface ModelBudgetOptions {
+    /** Total USD ceiling across all models. Must be positive and finite. */
+    ceilingUsd: number;
+    /** Per-model rate cards keyed by model id. */
+    pricing: Record<string, ModelPricing>;
+    /** Rate card used for models absent from `pricing`. */
+    defaultPricing?: ModelPricing;
+    /** Optional token budget to also debit (e.g. a `FederatedBudget`). */
+    tokenBudget?: TokenBudgetLike;
+}
+/** One raw per-attempt usage record (mirrors a `usage.iterations[]` entry). */
+export interface UsageIteration {
+    /** `'fallback_message'` is the served attempt; `'message'` is a declined hop. */
+    type: 'message' | 'fallback_message' | string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+}
+/**
+ * Compute the USD cost of one attempt.
+ *
+ * `inputTokens` is treated as *uncached* input; `cacheReadInputTokens` and
+ * `cacheCreationInputTokens` are billed separately via their multipliers. When
+ * `creditRedeemed` is set, cache-creation tokens are repriced at the cache-read
+ * multiplier — the fallback-credit refund.
+ *
+ * @param usage    Token usage for the attempt.
+ * @param pricing  The model's rate card.
+ * @param opts     `creditRedeemed` reprices cache-write as cache-read.
+ * @returns        Cost in USD.
+ */
+export declare function costOfUsage(usage: UsageLike, pricing: ModelPricing, opts?: {
+    creditRedeemed?: boolean;
+}): number;
+/**
+ * USD budget tracker priced per model, with fallback-credit awareness.
+ *
+ * @example
+ * ```typescript
+ * const budget = new ModelBudget({
+ *   ceilingUsd: 5,
+ *   pricing: {
+ *     'claude-fable-5': { inputPerMTok: 10, outputPerMTok: 50 },
+ *     'claude-opus-4-8': { inputPerMTok: 5, outputPerMTok: 25 },
+ *   },
+ * });
+ *
+ * budget.recordAttempt('claude-opus-4-8', { inputTokens: 1000, outputTokens: 500 });
+ * budget.remainingUsd();
+ * ```
+ */
+export declare class ModelBudget {
+    private readonly _ceilingUsd;
+    private readonly _pricing;
+    private readonly _defaultPricing;
+    private readonly _tokenBudget;
+    private _spentUsd;
+    private readonly _perModelUsd;
+    constructor(options: ModelBudgetOptions);
+    /**
+     * Record one attempt's usage and return its cost plus remaining budget.
+     *
+     * @param model  The model that ran the attempt.
+     * @param usage  Token usage for the attempt.
+     * @param opts   `creditRedeemed` reprices cache-write as cache-read; `agentId`
+     *               attributes the spend on the optional token budget.
+     * @returns      `{ costUsd, remainingUsd, allowed }`. `allowed` is `false`
+     *               once the ceiling is breached, signalling callers to stop.
+     */
+    recordAttempt(model: string, usage: UsageLike, opts?: {
+        creditRedeemed?: boolean;
+        agentId?: string;
+    }): {
+        costUsd: number;
+        remainingUsd: number;
+        allowed: boolean;
+    };
+    /**
+     * Account an entire `usage.iterations` array from a server-side fallback
+     * response. The `fallback_message` hop is repriced as a cache read, matching
+     * the API's automatic billing change.
+     *
+     * @param iterations  The per-attempt usage records.
+     * @param agentId     Optional attribution for the token budget.
+     * @returns           Total USD across all iterations.
+     */
+    accountIterations(iterations: UsageIteration[], agentId?: string): number;
+    /** Remaining USD in the pool (never negative). */
+    remainingUsd(): number;
+    /** Total USD spent across all models. */
+    getTotalUsd(): number;
+    /** Per-model USD totals as a plain object. */
+    getPerModelUsd(): Record<string, number>;
+    /** The configured USD ceiling. */
+    getCeilingUsd(): number;
+    /** Reset all spend counters. */
+    reset(): void;
+}
+//# sourceMappingURL=model-budget.d.ts.map

package/dist/lib/model-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-budget.d.ts","sourceRoot":"","sources":["../../lib/model-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sFAAsF;IACtF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9D;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACtC,uDAAuD;IACvD,cAAc,CAAC,EAAE,YAAY,CAAC;IAC9B,sEAAsE;IACtE,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,IAAI,EAAE,SAAS,GAAG,kBAAkB,GAAG,MAAM,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,EACrB,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,GAClC,MAAM,CAgBR;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8B;IAC3D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;gBAEnD,OAAO,EAAE,kBAAkB;IAavC;;;;;;;;;OASG;IACH,aAAa,CACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACpD;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE;IAqB9D;;;;;;;;OAQG;IACH,iBAAiB,CAAC,UAAU,EAAE,cAAc,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;IAmBzE,kDAAkD;IAClD,YAAY,IAAI,MAAM;IAItB,yCAAyC;IACzC,WAAW,IAAI,MAAM;IAIrB,8CAA8C;IAC9C,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMxC,kCAAkC;IAClC,aAAa,IAAI,MAAM;IAIvB,gCAAgC;IAChC,KAAK,IAAI,IAAI;CAId"}

package/dist/lib/model-budget.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * ModelBudget — cross-model cost accounting with fallback-credit repricing.
+ *
+ * Where {@link ../lib/federated-budget!FederatedBudget} tracks raw token counts
+ * against a shared ceiling, `ModelBudget` tracks **money**. It prices each
+ * attempt with a per-model rate card, distinguishes cache-read from cache-write
+ * input tokens, and — critically for a refusal → fallback flow — reprices a
+ * redeemed fallback credit so the retry is billed as a cache read (≈10% of the
+ * base input rate) instead of a cache write (1.25×–2×).
+ *
+ * It satisfies the `BudgetSink` contract consumed by
+ * {@link ../lib/model-gateway!GovernedModelGateway}, and can optionally forward
+ * token totals into a `FederatedBudget` for unified swarm-wide ceilings.
+ *
+ * @module ModelBudget
+ * @version 1.0.0
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelBudget = void 0;
+exports.costOfUsage = costOfUsage;
+// ============================================================================
+// PURE COST FUNCTION
+// ============================================================================
+/**
+ * Compute the USD cost of one attempt.
+ *
+ * `inputTokens` is treated as *uncached* input; `cacheReadInputTokens` and
+ * `cacheCreationInputTokens` are billed separately via their multipliers. When
+ * `creditRedeemed` is set, cache-creation tokens are repriced at the cache-read
+ * multiplier — the fallback-credit refund.
+ *
+ * @param usage    Token usage for the attempt.
+ * @param pricing  The model's rate card.
+ * @param opts     `creditRedeemed` reprices cache-write as cache-read.
+ * @returns        Cost in USD.
+ */
+function costOfUsage(usage, pricing, opts) {
+    const inRate = pricing.inputPerMTok / 1_000_000;
+    const outRate = pricing.outputPerMTok / 1_000_000;
+    const readMult = pricing.cacheReadMultiplier ?? 0.1;
+    const writeMult = pricing.cacheWriteMultiplier ?? 1.25;
+    const cacheRead = usage.cacheReadInputTokens ?? 0;
+    const cacheWrite = usage.cacheCreationInputTokens ?? 0;
+    const writeEffectiveMult = opts?.creditRedeemed ? readMult : writeMult;
+    return (usage.inputTokens * inRate +
+        cacheRead * inRate * readMult +
+        cacheWrite * inRate * writeEffectiveMult +
+        usage.outputTokens * outRate);
+}
+// ============================================================================
+// MODEL BUDGET
+// ============================================================================
+/**
+ * USD budget tracker priced per model, with fallback-credit awareness.
+ *
+ * @example
+ * ```typescript
+ * const budget = new ModelBudget({
+ *   ceilingUsd: 5,
+ *   pricing: {
+ *     'claude-fable-5': { inputPerMTok: 10, outputPerMTok: 50 },
+ *     'claude-opus-4-8': { inputPerMTok: 5, outputPerMTok: 25 },
+ *   },
+ * });
+ *
+ * budget.recordAttempt('claude-opus-4-8', { inputTokens: 1000, outputTokens: 500 });
+ * budget.remainingUsd();
+ * ```
+ */
+class ModelBudget {
+    _ceilingUsd;
+    _pricing;
+    _defaultPricing;
+    _tokenBudget;
+    _spentUsd = 0;
+    _perModelUsd = new Map();
+    constructor(options) {
+        if (typeof options.ceilingUsd !== 'number' || options.ceilingUsd <= 0 || !Number.isFinite(options.ceilingUsd)) {
+            throw new RangeError('ModelBudget: ceilingUsd must be a positive finite number');
+        }
+        if (!options.pricing || typeof options.pricing !== 'object') {
+            throw new TypeError('ModelBudget: pricing must be an object of model → rate card');
+        }
+        this._ceilingUsd = options.ceilingUsd;
+        this._pricing = options.pricing;
+        this._defaultPricing = options.defaultPricing;
+        this._tokenBudget = options.tokenBudget;
+    }
+    /**
+     * Record one attempt's usage and return its cost plus remaining budget.
+     *
+     * @param model  The model that ran the attempt.
+     * @param usage  Token usage for the attempt.
+     * @param opts   `creditRedeemed` reprices cache-write as cache-read; `agentId`
+     *               attributes the spend on the optional token budget.
+     * @returns      `{ costUsd, remainingUsd, allowed }`. `allowed` is `false`
+     *               once the ceiling is breached, signalling callers to stop.
+     */
+    recordAttempt(model, usage, opts) {
+        const pricing = this._pricing[model] ?? this._defaultPricing;
+        const costUsd = pricing ? costOfUsage(usage, pricing, opts) : 0;
+        this._spentUsd += costUsd;
+        this._perModelUsd.set(model, (this._perModelUsd.get(model) ?? 0) + costUsd);
+        if (this._tokenBudget) {
+            const tokens = Math.max(0, Math.round(usage.inputTokens + usage.outputTokens));
+            if (tokens > 0) {
+                this._tokenBudget.spend(opts?.agentId ?? model, tokens);
+            }
+        }
+        return {
+            costUsd,
+            remainingUsd: this.remainingUsd(),
+            allowed: this._spentUsd <= this._ceilingUsd,
+        };
+    }
+    /**
+     * Account an entire `usage.iterations` array from a server-side fallback
+     * response. The `fallback_message` hop is repriced as a cache read, matching
+     * the API's automatic billing change.
+     *
+     * @param iterations  The per-attempt usage records.
+     * @param agentId     Optional attribution for the token budget.
+     * @returns           Total USD across all iterations.
+     */
+    accountIterations(iterations, agentId) {
+        let total = 0;
+        for (const it of iterations) {
+            const creditRedeemed = it.type === 'fallback_message';
+            const { costUsd } = this.recordAttempt(it.model, {
+                inputTokens: it.inputTokens,
+                outputTokens: it.outputTokens,
+                cacheReadInputTokens: it.cacheReadInputTokens,
+                cacheCreationInputTokens: it.cacheCreationInputTokens,
+            }, { creditRedeemed, agentId });
+            total += costUsd;
+        }
+        return total;
+    }
+    /** Remaining USD in the pool (never negative). */
+    remainingUsd() {
+        return Math.max(0, this._ceilingUsd - this._spentUsd);
+    }
+    /** Total USD spent across all models. */
+    getTotalUsd() {
+        return this._spentUsd;
+    }
+    /** Per-model USD totals as a plain object. */
+    getPerModelUsd() {
+        const out = {};
+        for (const [model, usd] of this._perModelUsd)
+            out[model] = usd;
+        return out;
+    }
+    /** The configured USD ceiling. */
+    getCeilingUsd() {
+        return this._ceilingUsd;
+    }
+    /** Reset all spend counters. */
+    reset() {
+        this._spentUsd = 0;
+        this._perModelUsd.clear();
+    }
+}
+exports.ModelBudget = ModelBudget;
+//# sourceMappingURL=model-budget.js.map

package/dist/lib/model-budget.js.map

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

package/dist/lib/model-gateway.d.ts

@@ -0,0 +1,252 @@
+/**
+ * GovernedModelGateway — model-interaction lifecycle governance.
+ *
+ * Absorbs a frontier model's refusal → fallback → billing complexity and
+ * presents one governed, budgeted, audited interface. When the primary model
+ * declines a request with a classifier refusal (`stop_reason: "refusal"`), the
+ * gateway:
+ *
+ *   1. records the refusal (which classifier `category` fired) to the audit sink,
+ *   2. emits a refusal signal to telemetry (a refusal is an HTTP 200, *not* an
+ *      error — it is invisible to error-rate monitoring),
+ *   3. retries on the next model in the fallback chain, redeeming the one-time
+ *      fallback-credit token so the retry is repriced as a cache read,
+ *   4. strips model-specific thinking blocks when it switches models (unless a
+ *      credit is being redeemed, which requires an exact body match),
+ *   5. accounts each attempt's cost against the cross-model budget.
+ *
+ * This layer is **provider-agnostic**. It operates on a normalized
+ * {@link ModelCaller}; the concrete provider binding (e.g. the Anthropic
+ * Messages adapter) maps the native API to these shapes. Unlike
+ * `AdapterRegistry.fallbackChain` — which fails over on adapter *health*
+ * (`CircuitOpenError`) — this gateway falls over on a *classifier refusal*.
+ *
+ * @module GovernedModelGateway
+ * @version 1.0.0
+ * @license MIT
+ */
+/** Effort levels, lowest to highest cost/depth. Mirrors `output_config.effort`. */
+export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * Classifier categories a refusal can carry. `null` when the refusal does not
+ * map to a named category (a normal, permanent value — not a placeholder).
+ */
+export type RefusalCategory = 'cyber' | 'bio' | 'frontier_llm' | 'reasoning_extraction' | null;
+/** A single conversation message in normalized form. */
+export interface ModelMessage {
+    role: string;
+    content: unknown;
+}
+/** A normalized content block. `thinking`/`signature` appear on thinking blocks. */
+export interface ModelContentBlock {
+    type: string;
+    text?: string;
+    thinking?: string;
+    signature?: string;
+    [key: string]: unknown;
+}
+/** Per-attempt token usage, normalized across providers. */
+export interface ModelUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+}
+/**
+ * Refusal metadata extracted from a declined response. Present only when
+ * `stopReason === 'refusal'`.
+ */
+export interface RefusalDetails {
+    /** Policy area that triggered the classifier, or `null` if unnamed. */
+    category: RefusalCategory;
+    /** Human-readable description. Display it; do not parse it (text is unstable). */
+    explanation?: string;
+    /** One-time credit token that reprices the fallback retry. ~5-minute TTL. */
+    fallbackCreditToken?: string | null;
+    /** Whether the retry may continue the refused model's partial output. */
+    fallbackHasPrefillClaim?: boolean | null;
+    /** Model to retry directly when a configured fallback could not run. */
+    recommendedModel?: string | null;
+}
+/** A normalized request to a single model. */
+export interface ModelRequest {
+    model: string;
+    messages: ModelMessage[];
+    system?: string;
+    maxTokens?: number;
+    tools?: unknown[];
+    /** Soft cost/depth signal; the primary lever on per-token spend. */
+    effort?: EffortLevel;
+    /** When set, the caller should redeem this credit on the retry. */
+    fallbackCreditToken?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A normalized response from a single model. */
+export interface ModelResponse {
+    id?: string;
+    /** The model that actually produced this response. */
+    model: string;
+    content: ModelContentBlock[];
+    stopReason: string | null;
+    /** Refusal metadata when `stopReason === 'refusal'`, else `null`/absent. */
+    refusal?: RefusalDetails | null;
+    usage: ModelUsage;
+}
+/**
+ * Provider-agnostic model invocation. A concrete adapter (Anthropic, etc.)
+ * implements this by mapping the native API to {@link ModelRequest} /
+ * {@link ModelResponse}.
+ */
+export type ModelCaller = (request: ModelRequest) => Promise<ModelResponse>;
+/** Records one attempt's cost. {@link ../lib/model-budget!ModelBudget} satisfies this. */
+export interface BudgetSink {
+    recordAttempt(model: string, usage: ModelUsage, opts?: {
+        creditRedeemed?: boolean;
+        agentId?: string;
+    }): {
+        costUsd: number;
+        remainingUsd: number;
+        allowed: boolean;
+    };
+}
+/** Append-only audit destination. */
+export interface AuditSink {
+    log(event: Record<string, unknown>): void | Promise<void>;
+}
+/** Thinking-block lifecycle hook. {@link ThinkingBlockManager} satisfies this. */
+export interface ThinkingSink {
+    /** Strip thinking blocks from prior turns before a cross-model retry. */
+    stripForModelSwitch(messages: ModelMessage[]): ModelMessage[];
+}
+/** Effort governance hook. {@link EffortPolicy} satisfies this. */
+export interface EffortSink {
+    resolve(requested: EffortLevel | undefined, ctx: {
+        agentId?: string;
+    }): EffortLevel | undefined;
+}
+/** Refusal observability hook. {@link RefusalTelemetry} satisfies this. */
+export interface RefusalTelemetrySink {
+    recordRefusal(info: {
+        model: string;
+        category: RefusalCategory;
+        agentId?: string;
+    }): void;
+    recordFallbackServed(info: {
+        requestedModel: string;
+        servedModel: string;
+        agentId?: string;
+    }): void;
+}
+/** Construction options for {@link GovernedModelGateway}. */
+export interface GovernedModelGatewayConfig {
+    /** Normalized model invocation. Required. */
+    caller: ModelCaller;
+    /** Model tried first. Required, non-empty. */
+    primaryModel: string;
+    /** Ordered fallback models, tried after a refusal. */
+    fallbackModels?: string[];
+    /** Default effort applied when a request omits one. */
+    defaultEffort?: EffortLevel;
+    /** Maximum number of fallback attempts (default: `fallbackModels.length`). */
+    maxFallbacks?: number;
+    /** Permitted fallback targets per model (mirrors `allowed_fallback_models`). */
+    allowedFallbacks?: Record<string, string[]>;
+    /** Cross-model cost accounting. */
+    budget?: BudgetSink;
+    /** Audit destination for every attempt and refusal. */
+    audit?: AuditSink;
+    /** Refusal / fallback observability. */
+    telemetry?: RefusalTelemetrySink;
+    /** Thinking-block lifecycle manager. */
+    thinking?: ThinkingSink;
+    /** Effort governance policy. */
+    effort?: EffortSink;
+}
+/** A single attempt in the fallback chain — the source of truth for billing. */
+export interface GatewayAttempt {
+    model: string;
+    stopReason: string | null;
+    refusalCategory: RefusalCategory;
+    usage: ModelUsage;
+    costUsd?: number;
+    servedByFallback: boolean;
+    creditRedeemed: boolean;
+}
+/** A request to the gateway. The gateway, not the caller, picks the model. */
+export interface GovernedSendRequest {
+    messages: ModelMessage[];
+    system?: string;
+    maxTokens?: number;
+    tools?: unknown[];
+    effort?: EffortLevel;
+    /** Used for audit/telemetry/budget attribution. */
+    agentId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** The governed outcome of a {@link GovernedModelGateway.send} call. */
+export interface GovernedModelResult {
+    /** The response that served the turn, or the final refusal if all declined. */
+    response: ModelResponse;
+    /** Model that ultimately served (or was last attempted). */
+    servedModel: string;
+    /** `true` when every model in the chain refused. */
+    refused: boolean;
+    /** `true` when a fallback (not the primary) served the response. */
+    servedByFallback: boolean;
+    /** Per-attempt record. Use this for billing and serving-model analytics. */
+    attempts: GatewayAttempt[];
+    /** Distinct refusal categories encountered across attempts. */
+    refusalCategories: RefusalCategory[];
+    /** Sum of attempt costs when a budget is configured. */
+    totalCostUsd?: number;
+}
+/** Whether a response is a classifier refusal. Branch on this, not on content. */
+export declare function isRefusal(response: ModelResponse): boolean;
+/**
+ * Governs the full model-interaction lifecycle: refusal detection, cross-model
+ * fallback, fallback-credit redemption, thinking-block handoff, and per-attempt
+ * cost accounting — behind one {@link GovernedModelGateway.send} call.
+ *
+ * @example
+ * ```typescript
+ * const gateway = new GovernedModelGateway({
+ *   caller,                       // provider binding (e.g. Anthropic adapter)
+ *   primaryModel: 'claude-fable-5',
+ *   fallbackModels: ['claude-opus-4-8'],
+ *   budget, audit, telemetry, thinking, effort,
+ * });
+ *
+ * const r = await gateway.send({ messages: [{ role: 'user', content: 'hi' }] });
+ * console.log(r.servedModel, r.servedByFallback, r.totalCostUsd);
+ * ```
+ */
+export declare class GovernedModelGateway {
+    private readonly caller;
+    private readonly primaryModel;
+    private readonly fallbackModels;
+    private readonly defaultEffort;
+    private readonly maxFallbacks;
+    private readonly allowedFallbacks;
+    private readonly budget;
+    private readonly audit;
+    private readonly telemetry;
+    private readonly thinking;
+    private readonly effortPolicy;
+    constructor(config: GovernedModelGatewayConfig);
+    /**
+     * Send a request through the governed lifecycle.
+     *
+     * Tries the primary model, then walks the fallback chain on each refusal,
+     * redeeming fallback credit and stripping cross-model thinking blocks as it
+     * goes. Returns once a model serves the turn or the chain is exhausted.
+     *
+     * @param request  The request. The gateway selects the model(s).
+     * @returns        A {@link GovernedModelResult} describing every attempt.
+     */
+    send(request: GovernedSendRequest): Promise<GovernedModelResult>;
+    /** The ordered model chain: primary followed by permitted fallbacks. */
+    private buildChain;
+    private resolveEffort;
+    private auditAttempt;
+}
+//# sourceMappingURL=model-gateway.d.ts.map

package/dist/lib/model-gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-gateway.d.ts","sourceRoot":"","sources":["../../lib/model-gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAEtE;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,KAAK,GAAG,cAAc,GAAG,sBAAsB,GAAG,IAAI,CAAC;AAE/F,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,EAAE,eAAe,CAAC;IAC1B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,yEAAyE;IACzE,uBAAuB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAM5E,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,aAAa,CACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,EACjB,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACpD;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAChE;AAED,qCAAqC;AACrC,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,mBAAmB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAAC;CAC/D;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,SAAS,EAAE,WAAW,GAAG,SAAS,EAAE,GAAG,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW,GAAG,SAAS,CAAC;CACjG;AAED,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1F,oBAAoB,CAAC,IAAI,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACrG;AAMD,6DAA6D;AAC7D,MAAM,WAAW,0BAA0B;IACzC,6CAA6C;IAC7C,MAAM,EAAE,WAAW,CAAC;IACpB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uDAAuD;IACvD,aAAa,CAAC,EAAE,WAAW,CAAC;IAC5B,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5C,mCAAmC;IACnC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uDAAuD;IACvD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,wCAAwC;IACxC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,wCAAwC;IACxC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,gCAAgC;IAChC,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,eAAe,CAAC;IACjC,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,QAAQ,EAAE,aAAa,CAAC;IACxB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,+DAA+D;IAC/D,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAE1D;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;gBAE1C,MAAM,EAAE,0BAA0B;IAoB9C;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAoHtE,wEAAwE;IACxE,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,aAAa;YAOP,YAAY;CA2B3B"}