maestro-core 0.2.0 → 0.2.2

package/dist/cost.d.ts

@@ -0,0 +1,60 @@
+/**
+ * LLM pricing table + cost estimator.
+ *
+ * Per-million-token USD rates. Numbers track the Anthropic and OpenAI
+ * public pricing pages; update when the providers publish a new
+ * default alias.
+ *
+ * Hosts that need custom rates (private deployments, enterprise
+ * negotiated pricing, additional providers) pass an override map
+ * through the second argument of `estimateCost` — it merges over the
+ * built-in table without mutating it.
+ *
+ * IMPORTANT: model ids from OpenAI may include date suffixes at
+ * runtime (e.g. `gpt-4o-mini-2024-07-18`). `estimateCost` falls
+ * through to the blended rate for unknown ids — intentional, so an
+ * unrecognised model never crashes the cost call. Add the suffixed id
+ * to the table when the provider publishes one.
+ */
+export interface PricingRow {
+    /** Per-million input tokens, USD. */
+    input: number;
+    /** Per-million output tokens, USD. */
+    output: number;
+    /** Per-million cache-read tokens, USD. Anthropic: ~10% of input. OpenAI: 50%. */
+    cacheRead: number;
+    /** Per-million cache-write tokens, USD. Anthropic: ~1.25× input. OpenAI: no extra. */
+    cacheWrite: number;
+}
+/**
+ * Default model pricing snapshot. Sourced from:
+ * - Anthropic: https://www.anthropic.com/pricing (2026 baseline)
+ * - OpenAI:    https://openai.com/api/pricing
+ */
+export declare const MODEL_PRICING: Record<string, PricingRow>;
+/**
+ * Blended fallback used when the model id is unknown (date-suffixed
+ * OpenAI variants, custom deployments, missing telemetry). Skews
+ * Haiku-heavy because the default router lands on fast, but biases up
+ * slightly so dashboards never under-report cost.
+ *
+ * Hosts that surface this on a UI should label it as approximate.
+ */
+export declare const BLENDED_PRICING: PricingRow;
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/**
+ * Estimate USD cost for a token-usage block. When `modelId` matches
+ * a known model in `MODEL_PRICING` (or in the optional `customPricing`
+ * override map) the exact rate applies; otherwise `BLENDED_PRICING`
+ * is used.
+ *
+ * `customPricing` is shallow-merged on top of the default table — host
+ * entries override built-ins when the ids collide.
+ */
+export declare function estimateCost(usage: TokenUsage, modelId?: string | null, customPricing?: Record<string, PricingRow>): number;
+//# sourceMappingURL=cost.d.ts.map

package/dist/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,UAAU;IACvB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAA;IACjB,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CA4BpD,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,UAK7B,CAAA;AAED,MAAM,WAAW,UAAU;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CACxB,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,EACvB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAC3C,MAAM,CAYR"}

package/dist/cost.js

@@ -0,0 +1,68 @@
+/**
+ * Default model pricing snapshot. Sourced from:
+ * - Anthropic: https://www.anthropic.com/pricing (2026 baseline)
+ * - OpenAI:    https://openai.com/api/pricing
+ */
+export const MODEL_PRICING = {
+    // ── Anthropic ─────────────────────────────────────────────────
+    'claude-haiku-4-5-20251001': {
+        input: 1.0,
+        output: 5.0,
+        cacheRead: 0.1,
+        cacheWrite: 1.25,
+    },
+    'claude-sonnet-4-6': {
+        input: 3.0,
+        output: 15.0,
+        cacheRead: 0.3,
+        cacheWrite: 3.75,
+    },
+    // ── OpenAI (fallback provider) ────────────────────────────────
+    'gpt-4o-mini': {
+        input: 0.15,
+        output: 0.6,
+        cacheRead: 0.075, // 50% of input rate
+        cacheWrite: 0.15, // no extra charge; matches input
+    },
+    'gpt-4o': {
+        input: 2.5,
+        output: 10.0,
+        cacheRead: 1.25, // 50% of input
+        cacheWrite: 2.5, // matches input
+    },
+};
+/**
+ * Blended fallback used when the model id is unknown (date-suffixed
+ * OpenAI variants, custom deployments, missing telemetry). Skews
+ * Haiku-heavy because the default router lands on fast, but biases up
+ * slightly so dashboards never under-report cost.
+ *
+ * Hosts that surface this on a UI should label it as approximate.
+ */
+export const BLENDED_PRICING = {
+    input: 1.5,
+    output: 7.5,
+    cacheRead: 0.15,
+    cacheWrite: 1.875,
+};
+/**
+ * Estimate USD cost for a token-usage block. When `modelId` matches
+ * a known model in `MODEL_PRICING` (or in the optional `customPricing`
+ * override map) the exact rate applies; otherwise `BLENDED_PRICING`
+ * is used.
+ *
+ * `customPricing` is shallow-merged on top of the default table — host
+ * entries override built-ins when the ids collide.
+ */
+export function estimateCost(usage, modelId, customPricing) {
+    const merged = customPricing
+        ? { ...MODEL_PRICING, ...customPricing }
+        : MODEL_PRICING;
+    const price = (modelId && merged[modelId]) || BLENDED_PRICING;
+    return ((usage.input * price.input +
+        usage.output * price.output +
+        usage.cacheRead * price.cacheRead +
+        usage.cacheWrite * price.cacheWrite) /
+        1_000_000);
+}
+//# sourceMappingURL=cost.js.map

package/dist/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AA6BA;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAA+B;IACrD,iEAAiE;IACjE,2BAA2B,EAAE;QACzB,KAAK,EAAE,GAAG;QACV,MAAM,EAAE,GAAG;QACX,SAAS,EAAE,GAAG;QACd,UAAU,EAAE,IAAI;KACnB;IACD,mBAAmB,EAAE;QACjB,KAAK,EAAE,GAAG;QACV,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,GAAG;QACd,UAAU,EAAE,IAAI;KACnB;IAED,iEAAiE;IACjE,aAAa,EAAE;QACX,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,GAAG;QACX,SAAS,EAAE,KAAK,EAAE,oBAAoB;QACtC,UAAU,EAAE,IAAI,EAAE,iCAAiC;KACtD;IACD,QAAQ,EAAE;QACN,KAAK,EAAE,GAAG;QACV,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,IAAI,EAAE,eAAe;QAChC,UAAU,EAAE,GAAG,EAAE,gBAAgB;KACpC;CACJ,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAe;IACvC,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,GAAG;IACX,SAAS,EAAE,IAAI;IACf,UAAU,EAAE,KAAK;CACpB,CAAA;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CACxB,KAAiB,EACjB,OAAuB,EACvB,aAA0C;IAE1C,MAAM,MAAM,GAAG,aAAa;QACxB,CAAC,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,aAAa,EAAE;QACxC,CAAC,CAAC,aAAa,CAAA;IACnB,MAAM,KAAK,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,eAAe,CAAA;IAC7D,OAAO,CACH,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK;QACtB,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;QAC3B,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS;QACjC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACxC,SAAS,CACZ,CAAA;AACL,CAAC"}

package/dist/index.d.ts

@@ -2,6 +2,9 @@ export type { BaseToolContext } from './context.js';
 export { err, isOk, ok, type ToolEnvelope, type ToolMeta } from './envelope.js';
 export { type AgentToolDefinition, type AnyAgentToolDefinition, defineAgentTool, type ToolCostBand, type ToolKind, } from './tool.js';
 export { applyCacheBreakpoints, type CacheableBlock, type CachedMessages, } from './cache-control.js';
+export { BLENDED_PRICING, estimateCost, MODEL_PRICING, type PricingRow, type TokenUsage, } from './cost.js';
+export { DEFAULT_SMART_KEYWORDS, DEFAULT_SMART_LENGTH_THRESHOLD, DEFAULT_SMART_TURN_THRESHOLD, type ModelSelection, type ModelTier, selectChatModel, type SelectModelArgs, } from './models.js';
 export { captureToolException, type ToolExceptionHandler, type ToolExceptionTags, } from './safe-tool.js';
 export * from './ports/index.js';
+export { DAY_SECONDS, DAY_TTL_SECONDS, dailyCostWindow, dailyTokensWindow, dayKeyUtc, HOUR_SECONDS, HOUR_TTL_SECONDS, hourKeyUtc, hourlyToolCallsWindow, nextUtcHour, nextUtcMidnight, type WindowDescriptor, } from './windows.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC/E,OAAO,EACH,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,GAChB,MAAM,WAAW,CAAA;AAGlB,OAAO,EACH,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,GACtB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACzB,MAAM,gBAAgB,CAAA;AAGvB,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC/E,OAAO,EACH,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,GAChB,MAAM,WAAW,CAAA;AAGlB,OAAO,EACH,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,GACtB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,eAAe,EACf,YAAY,EACZ,aAAa,EACb,KAAK,UAAU,EACf,KAAK,UAAU,GAClB,MAAM,WAAW,CAAA;AAClB,OAAO,EACH,sBAAsB,EACtB,8BAA8B,EAC9B,4BAA4B,EAC5B,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,eAAe,EACf,KAAK,eAAe,GACvB,MAAM,aAAa,CAAA;AACpB,OAAO,EACH,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACzB,MAAM,gBAAgB,CAAA;AAGvB,cAAc,kBAAkB,CAAA;AAKhC,OAAO,EACH,WAAW,EACX,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,qBAAqB,EACrB,WAAW,EACX,eAAe,EACf,KAAK,gBAAgB,GACxB,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -2,7 +2,13 @@ export { err, isOk, ok } from './envelope.js';
 export { defineAgentTool, } from './tool.js';
 // Cross-cutting kernel utilities
 export { applyCacheBreakpoints, } from './cache-control.js';
+export { BLENDED_PRICING, estimateCost, MODEL_PRICING, } from './cost.js';
+export { DEFAULT_SMART_KEYWORDS, DEFAULT_SMART_LENGTH_THRESHOLD, DEFAULT_SMART_TURN_THRESHOLD, selectChatModel, } from './models.js';
 export { captureToolException, } from './safe-tool.js';
 // Ports re-exported at root for ergonomic single-import setups
 export * from './ports/index.js';
+// Window-math helpers — host `QuotaStore` impls import these to
+// compute consistent counter keys / TTLs / reset times. Not used
+// directly by `runChatTurn`; exposed for the host port boundary.
+export { DAY_SECONDS, DAY_TTL_SECONDS, dailyCostWindow, dailyTokensWindow, dayKeyUtc, HOUR_SECONDS, HOUR_TTL_SECONDS, hourKeyUtc, hourlyToolCallsWindow, nextUtcHour, nextUtcMidnight, } from './windows.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAoC,MAAM,eAAe,CAAA;AAC/E,OAAO,EAGH,eAAe,GAGlB,MAAM,WAAW,CAAA;AAElB,iCAAiC;AACjC,OAAO,EACH,qBAAqB,GAGxB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,oBAAoB,GAGvB,MAAM,gBAAgB,CAAA;AAEvB,+DAA+D;AAC/D,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAoC,MAAM,eAAe,CAAA;AAC/E,OAAO,EAGH,eAAe,GAGlB,MAAM,WAAW,CAAA;AAElB,iCAAiC;AACjC,OAAO,EACH,qBAAqB,GAGxB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,eAAe,EACf,YAAY,EACZ,aAAa,GAGhB,MAAM,WAAW,CAAA;AAClB,OAAO,EACH,sBAAsB,EACtB,8BAA8B,EAC9B,4BAA4B,EAG5B,eAAe,GAElB,MAAM,aAAa,CAAA;AACpB,OAAO,EACH,oBAAoB,GAGvB,MAAM,gBAAgB,CAAA;AAEvB,+DAA+D;AAC/D,cAAc,kBAAkB,CAAA;AAEhC,gEAAgE;AAChE,iEAAiE;AACjE,iEAAiE;AACjE,OAAO,EACH,WAAW,EACX,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,qBAAqB,EACrB,WAAW,EACX,eAAe,GAElB,MAAM,cAAc,CAAA"}

package/dist/models.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Two-tier model router for chat surfaces. Picks between a fast/cheap
+ * model and a smart/expensive one based on cheap heuristics on the
+ * user's last message.
+ *
+ * The kernel ships sensible defaults tuned for an owner-help persona
+ * (lookups → fast; mutations/long asks → smart). Hosts override the
+ * model ids by passing `models` and can extend or replace the keyword
+ * triggers via the optional `smartKeywords` / threshold args.
+ *
+ * The kernel does NOT read `process.env` — host products are responsible
+ * for pulling `MODEL_ID` overrides from their own env layer and passing
+ * them in. Keeps the kernel testable in isolation and avoids the
+ * surprise of NEXT_PUBLIC-style build-time inlining.
+ */
+export type ModelTier = 'fast' | 'smart';
+export interface ModelSelection {
+    tier: ModelTier;
+    modelId: string;
+    /** Short string describing why this tier was chosen. Useful for telemetry. */
+    reason: string;
+}
+/**
+ * Default trigger words mapped to mutation verbs or compositional asks
+ * that justify routing to the smart tier. Tuned for Portuguese /
+ * Spanish / English owner-help personas. Replace via `smartKeywords`
+ * when the persona shifts.
+ */
+export declare const DEFAULT_SMART_KEYWORDS: readonly string[];
+/** Default message-length threshold (chars) above which we route smart. */
+export declare const DEFAULT_SMART_LENGTH_THRESHOLD = 200;
+/** Default user-turn count above which we route smart (deeper chains benefit from reasoning). */
+export declare const DEFAULT_SMART_TURN_THRESHOLD = 4;
+export interface SelectModelArgs {
+    /** Most recent user message. */
+    userMessage: string;
+    /** 1-based user-turn count for the thread. */
+    turnIndex?: number;
+    /** Caller may force the tier (e.g. a known-complex nudge). */
+    forceTier?: ModelTier;
+    /**
+     * Model ids per tier. The kernel does not read env; the host
+     * resolves overrides from its env layer and passes them here.
+     *
+     * `force` short-circuits to that exact model id regardless of
+     * tier — useful for canary rollouts and eval pinning.
+     */
+    models: {
+        fast: string;
+        smart: string;
+        force?: string | null;
+    };
+    /** Override the default keyword trigger set. Pass `[]` to disable keyword routing entirely. */
+    smartKeywords?: readonly string[];
+    /** Override the default length threshold (chars). */
+    smartLengthThreshold?: number;
+    /** Override the default turn-depth threshold. */
+    smartTurnThreshold?: number;
+}
+/**
+ * Heuristic router. Smart tier wins when any of:
+ *   - `forceTier === 'smart'` (caller intent)
+ *   - message length ≥ length threshold
+ *   - turn index ≥ turn threshold
+ *   - message contains a keyword trigger
+ * Otherwise fast. `models.force` always wins when set.
+ */
+export declare function selectChatModel(args: SelectModelArgs): ModelSelection;
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;AAExC,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EA0CnD,CAAA;AAED,2EAA2E;AAC3E,eAAO,MAAM,8BAA8B,MAAM,CAAA;AAEjD,iGAAiG;AACjG,eAAO,MAAM,4BAA4B,IAAI,CAAA;AAE7C,MAAM,WAAW,eAAe;IAC5B,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB;;;;;;OAMG;IACH,MAAM,EAAE;QACJ,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KACxB,CAAA;IAED,+FAA+F;IAC/F,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,qDAAqD;IACrD,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc,CAwCrE"}

package/dist/models.js

@@ -0,0 +1,113 @@
+/**
+ * Two-tier model router for chat surfaces. Picks between a fast/cheap
+ * model and a smart/expensive one based on cheap heuristics on the
+ * user's last message.
+ *
+ * The kernel ships sensible defaults tuned for an owner-help persona
+ * (lookups → fast; mutations/long asks → smart). Hosts override the
+ * model ids by passing `models` and can extend or replace the keyword
+ * triggers via the optional `smartKeywords` / threshold args.
+ *
+ * The kernel does NOT read `process.env` — host products are responsible
+ * for pulling `MODEL_ID` overrides from their own env layer and passing
+ * them in. Keeps the kernel testable in isolation and avoids the
+ * surprise of NEXT_PUBLIC-style build-time inlining.
+ */
+/**
+ * Default trigger words mapped to mutation verbs or compositional asks
+ * that justify routing to the smart tier. Tuned for Portuguese /
+ * Spanish / English owner-help personas. Replace via `smartKeywords`
+ * when the persona shifts.
+ */
+export const DEFAULT_SMART_KEYWORDS = [
+    // PT
+    'agendar',
+    'agenda pra',
+    'marcar',
+    'cancelar',
+    'remarcar',
+    'registrar venda',
+    'registra venda',
+    'vendi',
+    'criar promoç',
+    'criar cupom',
+    'cadastrar cliente',
+    'mesclar',
+    'excluir',
+    'apagar',
+    'comparar',
+    'compare',
+    'resumo geral',
+    'me dá um resumo',
+    'agendamento em série',
+    'série de agendamentos',
+    // ES
+    'reservar',
+    'reagendar',
+    'registrar venta',
+    'crear promo',
+    'crear cupon',
+    'eliminar',
+    'resumen general',
+    // EN
+    'book ',
+    'schedule ',
+    'cancel',
+    'reschedule',
+    'log a sale',
+    'record sale',
+    'create coupon',
+    'create promotion',
+    'merge clients',
+    'delete',
+    'summary',
+];
+/** Default message-length threshold (chars) above which we route smart. */
+export const DEFAULT_SMART_LENGTH_THRESHOLD = 200;
+/** Default user-turn count above which we route smart (deeper chains benefit from reasoning). */
+export const DEFAULT_SMART_TURN_THRESHOLD = 4;
+/**
+ * Heuristic router. Smart tier wins when any of:
+ *   - `forceTier === 'smart'` (caller intent)
+ *   - message length ≥ length threshold
+ *   - turn index ≥ turn threshold
+ *   - message contains a keyword trigger
+ * Otherwise fast. `models.force` always wins when set.
+ */
+export function selectChatModel(args) {
+    const forceId = args.models.force ?? null;
+    if (forceId) {
+        return { tier: 'fast', modelId: forceId, reason: 'force-override' };
+    }
+    if (args.forceTier === 'smart') {
+        return { tier: 'smart', modelId: args.models.smart, reason: 'forced' };
+    }
+    if (args.forceTier === 'fast') {
+        return { tier: 'fast', modelId: args.models.fast, reason: 'forced' };
+    }
+    const text = (args.userMessage ?? '').trim().toLowerCase();
+    if (text.length === 0) {
+        return { tier: 'fast', modelId: args.models.fast, reason: 'empty' };
+    }
+    const lengthThreshold = args.smartLengthThreshold ?? DEFAULT_SMART_LENGTH_THRESHOLD;
+    if (text.length >= lengthThreshold) {
+        return { tier: 'smart', modelId: args.models.smart, reason: 'long-message' };
+    }
+    const turn = args.turnIndex ?? 1;
+    const turnThreshold = args.smartTurnThreshold ?? DEFAULT_SMART_TURN_THRESHOLD;
+    if (turn >= turnThreshold) {
+        return { tier: 'smart', modelId: args.models.smart, reason: 'deep-thread' };
+    }
+    const keywords = args.smartKeywords ?? DEFAULT_SMART_KEYWORDS;
+    for (const keyword of keywords) {
+        if (text.includes(keyword)) {
+            return {
+                tier: 'smart',
+                modelId: args.models.smart,
+                reason: `keyword:${keyword.trim()}`,
+            };
+        }
+    }
+    return { tier: 'fast', modelId: args.models.fast, reason: 'default-fast' };
+}
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

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

package/dist/ports/quota-store.d.ts

@@ -40,6 +40,8 @@ export interface QuotaUsage {
     tokensOut: number;
     cacheReadTokens: number;
     cacheWriteTokens: number;
+    /** Tool invocations attributed to this turn. Drives the `maxCallsPerWindow` ceiling. */
+    toolCalls?: number;
     /** USD cost in micro-dollars (integer). */
     costUsdMicro: number;
     modelId: string;

package/dist/ports/quota-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quota-store.d.ts","sourceRoot":"","sources":["../../src/ports/quota-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,QAAQ;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE;QACF,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,MAAM,CAAA;QACb,QAAQ,EAAE,MAAM,CAAA;KACnB,CAAA;IACD,WAAW,EAAE,IAAI,CAAA;IACjB,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,IAAI,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACvB,gEAAgE;IAChE,WAAW,CAAC,KAAK,EAAE;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,WAAW,CAAA;KACtB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAErB,mEAAmE;IACnE,KAAK,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAExE,sDAAsD;IACtD,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C"}
+{"version":3,"file":"quota-store.d.ts","sourceRoot":"","sources":["../../src/ports/quota-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,QAAQ;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE;QACF,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,MAAM,CAAA;QACb,QAAQ,EAAE,MAAM,CAAA;KACnB,CAAA;IACD,WAAW,EAAE,IAAI,CAAA;IACjB,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,IAAI,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACvB,gEAAgE;IAChE,WAAW,CAAC,KAAK,EAAE;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,WAAW,CAAA;KACtB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAErB,mEAAmE;IACnE,KAAK,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAExE,sDAAsD;IACtD,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C"}

package/dist/runtime/empty-recovery.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Empty-text recovery decision helper.
+ *
+ * The recoverable bug class: the model called a tool, got valid data
+ * back, then emitted zero user-visible text. The visitor sees an empty
+ * bubble below the tool card and reads it as failure. Symptom seen in
+ * prod across multiple deployments — `event.text === '' && event.toolCalls.length > 0`
+ * after streamText finishes.
+ *
+ * The kernel offers this as a PURE decision helper. Callers detect the
+ * empty-text condition themselves (cheapest check: `text.trim().length === 0`
+ * after a turn that invoked tools), supply the locale-appropriate
+ * fallback string, and act on the decision struct (inject text into
+ * the stream + persist the recovery error code on the turn row).
+ *
+ * Why a helper instead of in-kernel recovery: the act of injecting
+ * text mid-stream is host-specific (Next.js Server Components,
+ * Cloudflare Worker, raw Node HTTP all differ). The decision is
+ * portable; the execution is not.
+ */
+export type EmptyRecoveryMode = 'off' | 'log_only' | 'enforce';
+export interface EmptyRecoveryDecision {
+    /**
+     * Whether recovery engaged for this turn. `false` means the mode
+     * was `off`, the turn isn't a recoverable tool-loop-no-text case,
+     * or the turn produced visible text.
+     */
+    triggered: boolean;
+    mode: EmptyRecoveryMode;
+    /**
+     * Pre-localized fallback string the caller should inject. Only
+     * populated when `triggered === true && mode === 'enforce'`. `null`
+     * in `log_only` mode (caller logs but does NOT modify the stream
+     * or row).
+     */
+    fallbackText: string | null;
+    /**
+     * Suggested error code to persist on the turn row:
+     *   - `null` — recovery did not engage.
+     *   - `'tool_loop_no_text_logged'` — log_only mode signal.
+     *   - `'tool_loop_no_text_recovered_fallback'` — enforce signal.
+     */
+    persistedErrorCode: string | null;
+}
+export interface DecideEmptyRecoveryArgs {
+    mode: EmptyRecoveryMode;
+    /**
+     * Caller-detected signal: `true` when the model invoked a tool but
+     * produced no visible text on the turn. Other empty-answer shapes
+     * (token-limit cap, empty response) are handled by separate layers.
+     */
+    isToolLoopNoText: boolean;
+    /**
+     * Locale + surface-appropriate fallback. The kernel intentionally
+     * does NOT ship per-locale defaults — every host has its own
+     * translation namespace, and shipping a copy here would create two
+     * sources of truth.
+     */
+    fallbackText: string;
+}
+export declare function decideEmptyRecovery(args: DecideEmptyRecoveryArgs): EmptyRecoveryDecision;
+//# sourceMappingURL=empty-recovery.d.ts.map

package/dist/runtime/empty-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-recovery.d.ts","sourceRoot":"","sources":["../../src/runtime/empty-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,CAAA;AAE9D,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,EAAE,iBAAiB,CAAA;IACvB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,uBAAuB;IACpC,IAAI,EAAE,iBAAiB,CAAA;IACvB;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAA;IACzB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAA;CACvB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,qBAAqB,CAgCxF"}

package/dist/runtime/empty-recovery.js

@@ -0,0 +1,34 @@
+export function decideEmptyRecovery(args) {
+    if (args.mode === 'off') {
+        return {
+            triggered: false,
+            mode: 'off',
+            fallbackText: null,
+            persistedErrorCode: null,
+        };
+    }
+    if (!args.isToolLoopNoText) {
+        return {
+            triggered: false,
+            mode: args.mode,
+            fallbackText: null,
+            persistedErrorCode: null,
+        };
+    }
+    if (args.mode === 'log_only') {
+        return {
+            triggered: true,
+            mode: 'log_only',
+            fallbackText: null,
+            persistedErrorCode: 'tool_loop_no_text_logged',
+        };
+    }
+    // enforce
+    return {
+        triggered: true,
+        mode: 'enforce',
+        fallbackText: args.fallbackText,
+        persistedErrorCode: 'tool_loop_no_text_recovered_fallback',
+    };
+}
+//# sourceMappingURL=empty-recovery.js.map

package/dist/runtime/empty-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-recovery.js","sourceRoot":"","sources":["../../src/runtime/empty-recovery.ts"],"names":[],"mappings":"AA+DA,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC7D,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QACtB,OAAO;YACH,SAAS,EAAE,KAAK;YAChB,IAAI,EAAE,KAAK;YACX,YAAY,EAAE,IAAI;YAClB,kBAAkB,EAAE,IAAI;SAC3B,CAAA;IACL,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACzB,OAAO;YACH,SAAS,EAAE,KAAK;YAChB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,YAAY,EAAE,IAAI;YAClB,kBAAkB,EAAE,IAAI;SAC3B,CAAA;IACL,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC3B,OAAO;YACH,SAAS,EAAE,IAAI;YACf,IAAI,EAAE,UAAU;YAChB,YAAY,EAAE,IAAI;YAClB,kBAAkB,EAAE,0BAA0B;SACjD,CAAA;IACL,CAAC;IACD,UAAU;IACV,OAAO;QACH,SAAS,EAAE,IAAI;QACf,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,kBAAkB,EAAE,sCAAsC;KAC7D,CAAA;AACL,CAAC"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,6 @@
+export { decideEmptyRecovery, type DecideEmptyRecoveryArgs, type EmptyRecoveryDecision, type EmptyRecoveryMode, } from './empty-recovery.js';
+export { formatMemoryBlock, loadMemoryBlock } from './memory.js';
+export { mapModelIdToOpenAI, shouldFallback } from './providers.js';
+export { AiQuotaDeniedError, type AiQuotaDenyPayload, type AiQuotaDenyReason, checkAndEnforce, enforceQuotaOrThrow, } from './quota.js';
+export { runChatTurn, type RunChatTurnArgs, type RunChatTurnPorts, } from './run-chat-turn.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,GACzB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EACH,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,eAAe,EACf,mBAAmB,GACtB,MAAM,YAAY,CAAA;AACnB,OAAO,EACH,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACxB,MAAM,oBAAoB,CAAA"}

package/dist/runtime/index.js

@@ -0,0 +1,6 @@
+export { decideEmptyRecovery, } from './empty-recovery.js';
+export { formatMemoryBlock, loadMemoryBlock } from './memory.js';
+export { mapModelIdToOpenAI, shouldFallback } from './providers.js';
+export { AiQuotaDeniedError, checkAndEnforce, enforceQuotaOrThrow, } from './quota.js';
+export { runChatTurn, } from './run-chat-turn.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,mBAAmB,GAItB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EACH,kBAAkB,EAGlB,eAAe,EACf,mBAAmB,GACtB,MAAM,YAAY,CAAA;AACnB,OAAO,EACH,WAAW,GAGd,MAAM,oBAAoB,CAAA"}

package/dist/runtime/memory.d.ts

@@ -0,0 +1,32 @@
+import type { MemoryRecord, MemoryScope, MemoryStore } from '../ports/memory-store.js';
+/**
+ * Load + format memory facts for system-prompt injection.
+ *
+ * Pull semantics: the kernel asks the host's MemoryStore for ALL facts
+ * matching the scope, then formats them as a compact prose block. The
+ * host is responsible for any retrieval / semantic filtering — barbeiro's
+ * impl, for example, runs a relevance pass via embeddings before
+ * returning. The kernel does not do retrieval; it just consumes the
+ * already-selected list.
+ *
+ * Output goes in the DYNAMIC system segment (varies per principal,
+ * cannot be cached). Anthropic prompt cache would split per-user
+ * otherwise, killing cross-tenant cache reuse.
+ *
+ * Returns `''` (empty string) when there are no facts so callers can
+ * safely concatenate to existing dynamic content without conditional
+ * branching.
+ */
+export interface LoadMemoryBlockArgs {
+    memoryStore: MemoryStore;
+    scope: MemoryScope;
+    /** Optional header line. Defaults to a generic prefix. */
+    header?: string;
+}
+export declare function loadMemoryBlock(args: LoadMemoryBlockArgs): Promise<string>;
+/**
+ * Pure formatter — separated from the port call so tests can drive
+ * arbitrary record sets without standing up a fake store.
+ */
+export declare function formatMemoryBlock(records: readonly MemoryRecord[], header?: string): string;
+//# sourceMappingURL=memory.d.ts.map

package/dist/runtime/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/runtime/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,mBAAmB;IAChC,WAAW,EAAE,WAAW,CAAA;IACxB,KAAK,EAAE,WAAW,CAAA;IAClB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC7B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,MAAM,SAAqD,GAC5D,MAAM,CAIR"}

package/dist/runtime/memory.js

@@ -0,0 +1,15 @@
+export async function loadMemoryBlock(args) {
+    const records = await args.memoryStore.load(args.scope);
+    return formatMemoryBlock(records, args.header);
+}
+/**
+ * Pure formatter — separated from the port call so tests can drive
+ * arbitrary record sets without standing up a fake store.
+ */
+export function formatMemoryBlock(records, header = 'User context (memories you should keep in mind):') {
+    if (records.length === 0)
+        return '';
+    const lines = records.map((r) => `- ${r.fact}`);
+    return `${header}\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=memory.js.map

package/dist/runtime/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/runtime/memory.ts"],"names":[],"mappings":"AA2BA,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAyB;IAC3D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACvD,OAAO,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC7B,OAAgC,EAChC,MAAM,GAAG,kDAAkD;IAE3D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IAC/C,OAAO,GAAG,MAAM,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AAC3C,CAAC"}

package/dist/runtime/providers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Provider-fallback helpers. Used by hosts that want OpenAI as a
+ * resilience fallback when the primary Anthropic call hits a transient
+ * failure mode.
+ *
+ * 0.2.0 ships the helpers but does NOT wrap `runChatTurn` with the
+ * retry loop — mid-stream provider switching is invasive enough to
+ * deserve its own design pass. Hosts compose retry themselves using
+ * these primitives:
+ *
+ *   try {
+ *     return await runChatTurn({ ..., models: anthropicModels })
+ *   } catch (e) {
+ *     if (shouldFallback(e)) {
+ *       return runChatTurn({
+ *         ...,
+ *         models: {
+ *           fast: mapModelIdToOpenAI(anthropicModels.fast),
+ *           smart: mapModelIdToOpenAI(anthropicModels.smart),
+ *         },
+ *       })
+ *     }
+ *     throw e
+ *   }
+ *
+ * Built-in retry wrapper tracked for 0.2.1.
+ */
+/**
+ * Returns true when the error suggests a transient provider failure
+ * worth retrying against a different provider (rate limit, 5xx,
+ * network error, timeout). Returns false for caller-side errors
+ * (auth, content policy, abort, intentional quota deny) so a real
+ * problem doesn't get masked by a successful fallback.
+ *
+ * Unwraps a single layer of `RetryError` (the AI SDK wraps the
+ * underlying APICallError after exhausting its internal retries) so
+ * the status-code logic applies to the root cause.
+ */
+export declare function shouldFallback(err: unknown): boolean;
+/**
+ * Map an Anthropic model id to its OpenAI equivalent for the fallback
+ * path. Capability + cost parity:
+ *   - Haiku  → gpt-4o-mini  (fast, cheap)
+ *   - Sonnet → gpt-4o       (capable, mid-range)
+ *   - Opus   → gpt-4o       (closest available equivalent)
+ *   - Unknown → gpt-4o-mini (conservative default — cheaper)
+ *
+ * Anthropic model ids may include date suffixes
+ * (e.g. `claude-haiku-4-5-20251001`); the substring match handles all
+ * variants.
+ */
+export declare function mapModelIdToOpenAI(anthropicModelId: string | null | undefined): string;
+//# sourceMappingURL=providers.d.ts.map

package/dist/runtime/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/runtime/providers.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CA2DpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAKtF"}