@plumbus/core 0.5.0 → 0.6.0

package/dist/ai/ai/cost-tracker.d.ts

@@ -0,0 +1,93 @@
+import type { TokenUsage } from './provider.js';
+import type { UsageAPIClient } from './usage-client.js';
+export interface AICostRecord {
+    id: string;
+    timestamp: Date;
+    model: string;
+    provider: string;
+    promptName?: string;
+    operation: 'generate' | 'extract' | 'classify' | 'embed' | 'transcribe' | 'synthesize' | 'transport';
+    /**
+     * True when the call originally streamed but fell back to a non-streaming
+     * retry after the streamed text failed JSON/schema validation. Both the
+     * original streamed attempt and the fallback attempt are billed, so this
+     * flag is the signal consumers use to detect duplicate billing for a
+     * single logical generation.
+     */
+    fallbackUsed?: boolean;
+    usage: TokenUsage;
+    /**
+     * Optional provider-native media billing units for non-token workloads such
+     * as speech-to-text, text-to-speech, or realtime transport.
+     */
+    mediaUsage?: {
+        audioInputSeconds?: number;
+        audioOutputSeconds?: number;
+        characters?: number;
+        connectionMinutes?: number;
+        participantMinutes?: number;
+    };
+    /** Actual cost from provider API, or null if API unavailable */
+    cost: number | null;
+    latencyMs: number;
+    tenantId?: string;
+    actor?: string;
+    /**
+     * Whether the underlying provider call completed successfully. Failed rows
+     * still represent real provider-side spend and count toward budget caps.
+     * Defaults to 'success' inside `createCostTracker` when the caller does
+     * not set it, preserving pre-0.3.0 behavior for existing consumers.
+     */
+    status: 'success' | 'failed' | 'refused' | 'incomplete';
+    /** Short description of the failure when `status !== 'success'`. */
+    errorMessage?: string;
+}
+export interface BudgetConfig {
+    /** Max tokens per single request */
+    maxTokensPerRequest?: number;
+    /** Daily cost limit in USD */
+    dailyCostLimit?: number;
+    /** Per-tenant daily cost limit in USD */
+    perTenantDailyLimit?: number;
+}
+/**
+ * Input type for {@link CostTracker.record}. `status` and `errorMessage` are
+ * optional so pre-0.3.0 call sites keep compiling; the tracker defaults
+ * `status` to `'success'` internally.
+ */
+export type AICostRecordInput = Omit<AICostRecord, 'id' | 'timestamp' | 'status'> & {
+    status?: AICostRecord['status'];
+};
+export interface CostTracker {
+    record(entry: AICostRecordInput): void;
+    checkBudget(config: {
+        tenantId?: string;
+        estimatedTokens?: number;
+        /**
+         * Optional normalized USD estimate for non-token workloads. Voice/media
+         * layers can compute this ahead of time and pre-check shared daily caps.
+         */
+        estimatedCostUsd?: number;
+    }): BudgetCheckResult;
+    getDailyUsage(tenantId?: string): DailyUsage;
+    getRecords(): AICostRecord[];
+    /** Fetch actual costs from provider usage APIs and update records */
+    syncCosts?(): Promise<UsageSyncResult>;
+}
+export interface BudgetCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+export interface DailyUsage {
+    totalTokens: number;
+    totalCost: number;
+    /** Whether cost data is available from provider APIs */
+    costAvailable: boolean;
+    requestCount: number;
+}
+export interface UsageSyncResult {
+    synced: boolean;
+    totalCost?: number;
+    error?: string;
+}
+export declare function createCostTracker(budget?: BudgetConfig, usageClients?: UsageAPIClient[]): CostTracker;

package/dist/ai/ai/derive-ledger-usage.d.ts

@@ -0,0 +1,10 @@
+import type { AICostRecord } from './cost-tracker.js';
+export type LedgerUsageKind = 'llm_tokens' | 'audio_seconds' | 'audio_output_seconds' | 'characters' | 'participant_minutes' | 'connection_minutes';
+export interface DerivedLedgerUsage {
+    usageKind: LedgerUsageKind;
+    usageQuantity: number;
+    usageQuantitySecondary?: number;
+}
+type DeriveLedgerUsageInput = Pick<AICostRecord, 'usage' | 'mediaUsage' | 'operation'>;
+export declare function deriveLedgerUsage(record: DeriveLedgerUsageInput): DerivedLedgerUsage;
+export {};

package/dist/ai/ai/model-pricing.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Capability classification for a model. Drives the filter on
+ * `AIProviderAdapter.listModels({ kind })`.
+ *
+ * - `text`:       chat / completion / reasoning (called via `complete` / `stream`)
+ * - `embedding`:  text-embedding models (called via `embed`)
+ * - `moderation`: content-moderation classifiers
+ * - `image`:      image generation
+ * - `audio`:      speech-to-text / text-to-speech / realtime audio
+ */
+export type Kind = 'text' | 'embedding' | 'moderation' | 'image' | 'audio';
+export interface ModelRate {
+    /** USD per 1M input tokens */
+    inputPerMTok: number;
+    /** USD per 1M output tokens (0 for embedding / moderation / free models) */
+    outputPerMTok: number;
+    /**
+     * Capability classification. Optional on the type for backward compat —
+     * existing consumers that destructure only the rate fields keep working —
+     * but every entry in `MODEL_PRICING` populates it.
+     */
+    kind?: Kind;
+}
+/**
+ * Finds the per-token rate for a model.
+ * Tries exact match first, then strips trailing date suffixes
+ * (e.g. "claude-sonnet-4-20250514" → "claude-sonnet-4").
+ * Returns null for unknown/unsupported models (Ollama, custom).
+ */
+export declare function findModelRate(model: string): ModelRate | null;
+/**
+ * Return all known model rates as an array of `[id, rate]` tuples. Used by
+ * `AIProviderAdapter.listModels()` to join live model ids against the pricing
+ * catalog. Order is not guaranteed.
+ */
+export declare function allKnownModels(): ReadonlyArray<readonly [string, ModelRate]>;
+/**
+ * Calculate the USD cost for a single AI request based on published per-token rates.
+ *
+ * Pricing adjustments applied:
+ * - **Cached input tokens**: charged at 0.1× the base input rate (both providers).
+ * - **Cache write tokens**: charged at 1.25× the base input rate (Anthropic 5-min cache).
+ * - **Long context premium**: for Claude Sonnet 4 / 4.5, when total input exceeds
+ *   200K tokens the entire request is charged at 2× input / 1.5× output.
+ *
+ * Returns 0 for unknown/unsupported models (Ollama, custom endpoints).
+ */
+export declare function calculateModelCost(inputTokens: number, outputTokens: number, model: string, options?: {
+    cachedInputTokens?: number;
+    cacheWriteTokens?: number;
+}): number;

package/dist/ai/ai/provider.d.ts

@@ -0,0 +1,214 @@
+import type { AIProviderConfig } from '../types/config.js';
+import { type Kind } from './model-pricing.js';
+/**
+ * A single chat-history turn. Used for native multi-turn requests where the
+ * model should see real conversation flow (assistant + user alternation).
+ * Optional — when omitted, providers fall back to single-user-message mode
+ * built from `ProviderRequest.prompt`.
+ */
+export interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface ProviderRequest {
+    /** System prompt / instructions */
+    system?: string;
+    /**
+     * User prompt content. Used as the SOLE user message when `messages` is
+     * absent. When `messages` is provided, this field is IGNORED — the messages
+     * array is the conversation. Callers passing `messages` may still set
+     * `prompt: ''` for type-compat.
+     */
+    prompt: string;
+    /**
+     * Optional native multi-turn conversation history. When present, providers
+     * send `[system?, ...messages]` to the API instead of `[system?, {role:'user', content: prompt}]`.
+     * The LAST entry should be a `user` message (the latest turn). Order is
+     * preserved exactly as supplied. Empty array is treated as "no messages"
+     * (falls back to single-user mode using `prompt`).
+     */
+    messages?: ChatMessage[];
+    /** Model name override */
+    model?: string;
+    /** Temperature (0-2) */
+    temperature?: number;
+    /** Max tokens for response */
+    maxTokens?: number;
+    /** Response format hint */
+    responseFormat?: 'text' | 'json';
+    /** Provider-compatible JSON Schema for strict structured outputs. */
+    responseSchema?: Record<string, unknown>;
+    /** Transport used for provider-side structured outputs. Defaults to response_format. */
+    structuredOutputTransport?: 'response_format' | 'tool';
+    /** Request timeout in milliseconds (default: 120_000) */
+    timeout?: number;
+    /**
+     * External AbortSignal (e.g. `ctx.signal`). When fired, the in-flight
+     * fetch(es) for this request abort immediately. Combined with the internal
+     * timeout signal via `AbortSignal.any([...])`, so whichever triggers first
+     * wins.
+     */
+    signal?: AbortSignal;
+    /**
+     * Deterministic sampling seed. OpenAI-compatible providers (including xAI
+     * Grok) honor this parameter: identical `{seed, temperature, model, prompt}`
+     * tuples produce the same tokens. Combined with `temperature: 0`, lets
+     * callers pin reproducible output for structural-planning prompts. Ignored
+     * by providers that do not support it.
+     */
+    seed?: number;
+}
+/** Compose a request's optional user signal with a timeout, returning a single AbortSignal. */
+export declare function combineRequestSignals(userSignal: AbortSignal | undefined, timeoutMs: number): AbortSignal;
+export interface ProviderResponse {
+    content: string;
+    model: string;
+    usage: TokenUsage;
+    finishReason: string;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** Tokens served from provider cache (charged at reduced rate). */
+    cachedInputTokens?: number;
+    /** Tokens written to provider cache (charged at elevated rate — Anthropic only). */
+    cacheWriteTokens?: number;
+}
+export interface ProviderStreamEvent {
+    type: 'content_delta' | 'usage' | 'done' | 'error';
+    /** Incremental text chunk (for content_delta) */
+    delta?: string;
+    /** Token usage (for usage / done events) */
+    usage?: TokenUsage;
+    /** Finish reason (for done events) */
+    finishReason?: string;
+    /** Error message (for error events) */
+    error?: string;
+}
+export interface EmbeddingRequest {
+    texts: string[];
+    model?: string;
+}
+export interface EmbeddingResponse {
+    embeddings: number[][];
+    model: string;
+    usage: {
+        totalTokens: number;
+    };
+    /**
+     * USD cost computed from the pricing catalog using `usage.totalTokens` against
+     * the model's input rate (embeddings are input-only). `0` for unknown models
+     * — same convention as completion-side cost. Optional so that external
+     * `AIProviderAdapter` implementations written before this field existed still
+     * satisfy the interface; consumers reading `cost` should treat `undefined` as
+     * "unknown" (typically by coalescing to `0`).
+     */
+    cost?: number;
+}
+/**
+ * A single model entry returned by `AIProviderAdapter.listModels()`.
+ * The id is whatever the provider's `/v1/models` returns; pricing and `kind`
+ * are joined from the framework's pricing catalog. Models not in the catalog
+ * surface as `kind: 'unknown'` with `null` prices.
+ */
+export interface ProviderModel {
+    /** API identifier (the value to pass as `model` in requests). */
+    id: string;
+    /** Adapter name (e.g. "openai", "anthropic", or a custom adapter's name). */
+    provider: string;
+    /** Capability classification, from the pricing catalog. `'unknown'` if not in the catalog. */
+    kind: Kind | 'unknown';
+    /** USD per 1M input tokens, or `null` if the model is not in the catalog. */
+    inputPerMTok: number | null;
+    /** USD per 1M output tokens, or `null` if the model is not in the catalog. */
+    outputPerMTok: number | null;
+    /** Provider-supplied human-readable label (Anthropic exposes this; OpenAI doesn't). */
+    displayName?: string;
+    /** ISO-8601 creation timestamp when the provider exposes one. */
+    createdAt?: string;
+    /** Owner/team (OpenAI exposes this; Anthropic doesn't). */
+    ownedBy?: string;
+}
+/**
+ * Optional filter passed to `AIProviderAdapter.listModels()`. `kind` accepts a
+ * single Kind or an array. When unset, all models are returned (including
+ * unknown ones). When set against an official endpoint, unknown-kind models
+ * are excluded; against a custom endpoint they are included alongside the
+ * filtered matches (see adapter docs).
+ */
+export interface ListModelsFilter {
+    kind?: Kind | Kind[];
+}
+export interface AIProviderAdapter {
+    readonly name: string;
+    /** Send a completion request */
+    complete(request: ProviderRequest): Promise<ProviderResponse>;
+    /** Stream a completion request, yielding incremental events */
+    stream(request: ProviderRequest): AsyncIterable<ProviderStreamEvent>;
+    /** Generate embeddings for texts */
+    embed(request: EmbeddingRequest): Promise<EmbeddingResponse>;
+    /**
+     * List models the provider exposes for this account, joined against the
+     * framework's pricing catalog. Optional — custom adapters that don't
+     * implement it still satisfy the interface.
+     *
+     * Filtering rule (see docs for full details):
+     * - No filter → all models, including unknown-kind entries.
+     * - Filter + official endpoint → only matching kinds; unknowns excluded.
+     * - Filter + custom endpoint → matching kinds **plus** all unknowns.
+     *
+     * On network error / 404 / unsupported endpoint, returns `[]` and emits
+     * one `console.warn`; does not throw.
+     */
+    listModels?(filter?: ListModelsFilter): Promise<ProviderModel[]>;
+}
+/**
+ * Shared logic used by adapter `listModels` implementations: join a list of
+ * provider-supplied model entries against the pricing catalog, then apply
+ * the kind filter respecting the official-endpoint rule.
+ */
+export declare function joinAndFilterModels(args: {
+    provider: string;
+    entries: Array<{
+        id: string;
+        displayName?: string;
+        createdAt?: string;
+        ownedBy?: string;
+    }>;
+    filter: ListModelsFilter | undefined;
+    isOfficial: boolean;
+}): ProviderModel[];
+export declare class ProviderAPIError extends Error {
+    readonly providerName: string;
+    readonly statusCode?: number;
+    readonly retryable: boolean;
+    readonly attempts: number;
+    constructor(args: {
+        providerName: string;
+        message: string;
+        retryable: boolean;
+        attempts: number;
+        statusCode?: number;
+    });
+}
+export declare function isProviderAPIError(value: unknown): value is ProviderAPIError;
+export interface OpenAIAdapterConfig {
+    apiKey: string;
+    model?: string;
+    embeddingModel?: string;
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 120_000) */
+    requestTimeout?: number;
+}
+export declare function createOpenAIAdapter(config: OpenAIAdapterConfig): AIProviderAdapter;
+export interface AnthropicAdapterConfig {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 120_000) */
+    requestTimeout?: number;
+}
+export declare function createAnthropicAdapter(config: AnthropicAdapterConfig): AIProviderAdapter;
+/** Create a provider adapter by name from a provider config entry */
+export declare function createProviderAdapter(name: string, providerConfig: AIProviderConfig): AIProviderAdapter;

package/dist/ai/ai/refusal.d.ts

@@ -0,0 +1,27 @@
+import type { TokenUsage } from './provider.js';
+export declare class AIRefusalError extends Error {
+    readonly provider: string;
+    readonly model: string;
+    readonly refusalText: string;
+    readonly usage: TokenUsage;
+    constructor(args: {
+        provider: string;
+        model: string;
+        refusalText: string;
+        usage?: TokenUsage;
+    });
+}
+export declare class AIIncompleteOutputError extends Error {
+    readonly provider: string;
+    readonly model: string;
+    readonly partialText: string;
+    readonly usage: TokenUsage;
+    readonly finishReason: string;
+    constructor(args: {
+        provider: string;
+        model: string;
+        partialText: string;
+        usage?: TokenUsage;
+        finishReason: string;
+    });
+}

package/dist/ai/ai/usage-client.d.ts

@@ -0,0 +1,30 @@
+export interface UsageEntry {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    requestCount: number;
+}
+export interface UsageData {
+    totalCost: number;
+    currency: string;
+    entries: UsageEntry[];
+}
+export interface UsageAPIClient {
+    provider: string;
+    fetchUsage(params: {
+        startDate: Date;
+        endDate: Date;
+    }): Promise<UsageData>;
+}
+export interface UsageClientConfig {
+    provider: 'openai' | 'anthropic';
+    apiKey: string;
+    baseUrl?: string;
+    organizationId?: string;
+}
+export declare function createUsageAPIClient(config: UsageClientConfig): UsageAPIClient;
+export declare class UsageAPIError extends Error {
+    readonly provider: string;
+    constructor(provider: string, message: string);
+}

package/dist/ai/ai-service.d.ts

@@ -11,7 +11,7 @@ export type { AICostContext };
  * Framework-level hook fired after every AI call completes (success or
  * failure) and the in-memory cost tracker has been updated. Consumers wire
  * this in through `ServerConfig.onAICostRecorded` to persist per-call spend
- * to their own ledger (see MemoirAi's `project_cost_ledger`).
+ * to their own ledger (e.g. an app-owned per-project cost ledger).
  */
 export type OnAICostRecorded = (record: AICostRecord, costContext?: AICostContext) => Promise<void> | void;
 export interface AIServiceConfig {

package/dist/ai/ai-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-service.d.ts","sourceRoot":"","sources":["../../src/ai/ai-service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EAGb,SAAS,EAEV,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,YAAY,EAAqB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAA4C,MAAM,eAAe,CAAC;AACjG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAIzB,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,MAAM,EAAE,YAAY,EACpB,WAAW,CAAC,EAAE,aAAa,KACxB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAG1B,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7C,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,cAAc,CAAC,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC,0DAA0D,CAAC;IACjF,gFAAgF;IAChF,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CACtB,MAAM,EACN;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAChF,CAAC,kCAAkC,CAAC;IACrC,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,iBAAiB,CAAC,GAC5D,eAAe,CAMjB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAijClE"}
+{"version":3,"file":"ai-service.d.ts","sourceRoot":"","sources":["../../src/ai/ai-service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EAGb,SAAS,EAEV,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,YAAY,EAAqB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAA4C,MAAM,eAAe,CAAC;AACjG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAIzB,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,MAAM,EAAE,YAAY,EACpB,WAAW,CAAC,EAAE,aAAa,KACxB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAG1B,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7C,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,cAAc,CAAC,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC,0DAA0D,CAAC;IACjF,gFAAgF;IAChF,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CACtB,MAAM,EACN;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAChF,CAAC,kCAAkC,CAAC;IACrC,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,iBAAiB,CAAC,GAC5D,eAAe,CAMjB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAwjClE"}

package/dist/ai/ai-service.js

@@ -86,7 +86,7 @@ export function createAIService(config) {
      * id/timestamp generation mirror what `createCostTracker` does internally
      * so the hook gets a fully-formed `AICostRecord`.
      */
-    async function recordCost(entry, costContext) {
+    async function recordProviderCost(entry, costContext) {
         if (costTracker) {
             costTracker.record(entry);
         }
@@ -117,12 +117,13 @@ export function createAIService(config) {
             cacheWriteTokens: (left.cacheWriteTokens ?? 0) + (right.cacheWriteTokens ?? 0),
         };
     }
-    function checkBudget(estimatedTokens) {
+    function checkBudget(estimatedTokens, estimatedCostUsd) {
         if (!costTracker)
             return;
         const result = costTracker.checkBudget({
             tenantId: config.budget?.tenantId,
             estimatedTokens,
+            estimatedCostUsd,
         });
         if (!result.allowed) {
             throw new Error(`AI budget exceeded: ${result.reason}`);
@@ -267,7 +268,7 @@ export function createAIService(config) {
                     cacheWriteTokens: failureUsage.cacheWriteTokens,
                 })
                 : null;
-            await recordCost({
+            await recordProviderCost({
                 model: resolvedModel,
                 provider: activeProvider.name,
                 promptName: hasPromptDef ? params.prompt : undefined,
@@ -284,7 +285,7 @@ export function createAIService(config) {
         }
         const latencyMs = performance.now() - start;
         // Track cost (success path)
-        await recordCost({
+        await recordProviderCost({
             model: resolvedModel,
             provider: activeProvider.name,
             promptName: hasPromptDef ? params.prompt : undefined,
@@ -329,6 +330,10 @@ export function createAIService(config) {
         };
     }
     return {
+        recordProviderCost,
+        checkProviderCostBudget(config = {}) {
+            checkBudget(config.estimatedTokens, config.estimatedCostUsd);
+        },
         async generate(params) {
             const { data } = await _generateCore(params);
             return data;
@@ -432,7 +437,7 @@ export function createAIService(config) {
                                 cacheWriteTokens: streamUsage.cacheWriteTokens,
                             })
                             : null;
-                        await recordCost({
+                        await recordProviderCost({
                             model: resolvedModel,
                             provider: activeProvider.name,
                             promptName: hasPromptDef ? params.prompt : undefined,
@@ -460,7 +465,7 @@ export function createAIService(config) {
                         cacheWriteTokens: errUsage.cacheWriteTokens,
                     })
                     : null;
-                await recordCost({
+                await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
                     promptName: hasPromptDef ? params.prompt : undefined,
@@ -492,7 +497,7 @@ export function createAIService(config) {
             if (request.responseSchema &&
                 (providerFinishReason === 'length' || providerFinishReason === 'max_tokens')) {
                 const failureUsage = streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-                await recordCost({
+                await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
                     promptName: hasPromptDef ? params.prompt : undefined,
@@ -516,7 +521,7 @@ export function createAIService(config) {
             // Build the final validated result
             if (singleTextField) {
                 // Plain text mode — wrap the accumulated text in the schema field
-                await recordCost({
+                await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
                     promptName: hasPromptDef ? params.prompt : undefined,
@@ -554,7 +559,7 @@ export function createAIService(config) {
                                 cacheWriteTokens: failureUsage.cacheWriteTokens,
                             })
                             : null;
-                        await recordCost({
+                        await recordProviderCost({
                             model: resolvedModel,
                             provider: activeProvider.name,
                             promptName: hasPromptDef ? params.prompt : undefined,
@@ -598,7 +603,7 @@ export function createAIService(config) {
                                 cacheWriteTokens: combinedUsage.cacheWriteTokens,
                             })
                             : null;
-                        await recordCost({
+                        await recordProviderCost({
                             model: resolvedModel,
                             provider: activeProvider.name,
                             promptName: hasPromptDef ? params.prompt : undefined,
@@ -617,7 +622,7 @@ export function createAIService(config) {
                 const successUsage = validationFellBackToNonStreaming
                     ? sumUsage(streamUsage, fallbackUsage)
                     : (streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 });
-                await recordCost({
+                await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
                     promptName: hasPromptDef ? params.prompt : undefined,
@@ -638,7 +643,7 @@ export function createAIService(config) {
                 };
             }
             else {
-                await recordCost({
+                await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
                     promptName: hasPromptDef ? params.prompt : undefined,
@@ -683,7 +688,7 @@ export function createAIService(config) {
                 const failureUsage = err instanceof AIValidationError
                     ? err.usage
                     : (getTypedAIErrorUsage(err) ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 });
-                await recordCost({
+                await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
                     operation: 'extract',
@@ -698,7 +703,7 @@ export function createAIService(config) {
                 throw err;
             }
             const latencyMs = performance.now() - start;
-            await recordCost({
+            await recordProviderCost({
                 model: resolvedModel,
                 provider: activeProvider.name,
                 operation: 'extract',
@@ -756,7 +761,7 @@ export function createAIService(config) {
                 const failureUsage = err instanceof AIValidationError
                     ? err.usage
                     : (getTypedAIErrorUsage(err) ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 });
-                await recordCost({
+                await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
                     operation: 'classify',
@@ -773,7 +778,7 @@ export function createAIService(config) {
             const latencyMs = performance.now() - start;
             // Filter to only valid labels
             const result = validated.data.filter((l) => params.labels.includes(l));
-            await recordCost({
+            await recordProviderCost({
                 model: resolvedModel,
                 provider: activeProvider.name,
                 operation: 'classify',