@plumbus/core 0.6.19 → 0.7.0

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.d.ts

@@ -0,0 +1,5 @@
+import { type AIService, type RAGPipelineConfig, type RunToolLoopParams } from '@plumbus/core';
+export declare function legacyConsumer(ai: AIService, params: RunToolLoopParams): Promise<number>;
+export declare const legacyEmbeddingCallback: RAGPipelineConfig['onEmbeddingCost'];
+export declare const uncheckedEstimate: number;
+//# sourceMappingURL=legacy-cost-api.d.ts.map

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-cost-api.d.ts","sourceRoot":"","sources":["../../../src/ai/__typecheck-fixtures__/legacy-cost-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,wBAAsB,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9F;AAED,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CAAC,iBAAiB,CAGxE,CAAC;AAGF,eAAO,MAAM,iBAAiB,EAAE,MAAyC,CAAC"}

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.js

@@ -0,0 +1,15 @@
+import { calculateModelCost, estimateModelCost, runToolLoop, } from '@plumbus/core';
+export async function legacyConsumer(ai, params) {
+    const result = await ai.generateWithUsage({ prompt: 'p', input: {} });
+    const cost = result.cost;
+    const loop = await runToolLoop(ai, params);
+    const total = loop.aggregatedCost;
+    return cost + total + calculateModelCost(1, 1, 'local');
+}
+export const legacyEmbeddingCallback = (info) => {
+    const numericCost = info.cost;
+    void numericCost;
+};
+// @ts-expect-error Unknown-aware estimates cannot be treated as definitely priced.
+export const uncheckedEstimate = estimateModelCost(1, 1, 'local');
+//# sourceMappingURL=legacy-cost-api.js.map

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-cost-api.js","sourceRoot":"","sources":["../../../src/ai/__typecheck-fixtures__/legacy-cost-api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,GAIZ,MAAM,eAAe,CAAC;AAEvB,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EAAa,EAAE,MAAyB;IAC3E,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IACtE,MAAM,IAAI,GAAW,MAAM,CAAC,IAAI,CAAC;IACjC,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAW,IAAI,CAAC,cAAc,CAAC;IAC1C,OAAO,IAAI,GAAG,KAAK,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAyC,CAAC,IAAI,EAAE,EAAE;IACpF,MAAM,WAAW,GAAW,IAAI,CAAC,IAAI,CAAC;IACtC,KAAK,WAAW,CAAC;AACnB,CAAC,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC"}

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

@@ -27,7 +27,7 @@ export interface AICostRecord {
         connectionMinutes?: number;
         participantMinutes?: number;
     };
-    /** Actual cost from provider API, or null if API unavailable */
+    /** Provider-reported or catalog-estimated USD cost; null when unknown. */
     cost: number | null;
     latencyMs: number;
     tenantId?: string;
@@ -55,8 +55,9 @@ export interface BudgetConfig {
  * 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'> & {
+export type AICostRecordInput = Omit<AICostRecord, 'id' | 'timestamp' | 'status' | 'cost'> & {
     status?: AICostRecord['status'];
+    cost?: number | null;
 };
 export interface CostTracker {
     record(entry: AICostRecordInput): void;
@@ -71,7 +72,7 @@ export interface CostTracker {
     }): BudgetCheckResult;
     getDailyUsage(tenantId?: string): DailyUsage;
     getRecords(): AICostRecord[];
-    /** Fetch actual costs from provider usage APIs and update records */
+    /** Fetch provider totals for reconciliation; does not infer per-request prices from aggregates. */
     syncCosts?(): Promise<UsageSyncResult>;
 }
 export interface BudgetCheckResult {

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

@@ -14,6 +14,10 @@ export interface ModelRate {
     inputPerMTok: number;
     /** USD per 1M output tokens (0 for embedding / moderation / free models) */
     outputPerMTok: number;
+    /** Published cache-read USD per MTok; defaults to 0.1× input when omitted. */
+    cachedInputPerMTok?: number;
+    /** Above this inclusive input-token boundary, charge 2× input/cache and 1.5× output. */
+    longContextThreshold?: number;
     /**
      * Capability classification. Optional on the type for backward compat —
      * existing consumers that destructure only the rate fields keep working —
@@ -34,18 +38,23 @@ export declare function findModelRate(model: string): ModelRate | null;
  * catalog. Order is not guaranteed.
  */
 export declare function allKnownModels(): ReadonlyArray<readonly [string, ModelRate]>;
+/** Legacy numeric cost helper. Use estimateModelCost when unknown must differ from free. */
+export declare function calculateModelCost(inputTokens: number, outputTokens: number, model: string, options?: {
+    cachedInputTokens?: number;
+    cacheWriteTokens?: number;
+}): number;
 /**
  * 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).
+ * - **Cached input tokens**: published per-model rate, defaulting to 0.1× input.
  * - **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.
+ *   200K tokens, or GPT-5.6 Sol over 272K, charge 2× input/cache and 1.5× output.
  *
- * Returns 0 for unknown/unsupported models (Ollama, custom endpoints).
+ * Returns undefined for unknown/unsupported models; explicitly free adapters may report zero.
  */
-export declare function calculateModelCost(inputTokens: number, outputTokens: number, model: string, options?: {
+export declare function estimateModelCost(inputTokens: number, outputTokens: number, model: string, options?: {
     cachedInputTokens?: number;
     cacheWriteTokens?: number;
-}): number;
+}): number | undefined;

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

@@ -22,6 +22,8 @@ export interface UsageClientConfig {
     apiKey: string;
     baseUrl?: string;
     organizationId?: string;
+    /** Billing endpoint timeout in milliseconds (default 10000). */
+    timeoutMs?: number;
 }
 export declare function createUsageAPIClient(config: UsageClientConfig): UsageAPIClient;
 export declare class UsageAPIError extends Error {

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

@@ -0,0 +1,3 @@
+import type { TokenUsage } from './provider.js';
+export declare function validateTokenUsage(usage: TokenUsage): TokenUsage;
+export declare function normalizeCost(cost: unknown): number | null;

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":"AAMA,OAAO,KAAK,EACV,aAAa,EAIb,SAAS,EAIV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAoB,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC/F,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,EACL,KAAK,iBAAiB,EAUvB,MAAM,eAAe,CAAC;AACvB,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;QACE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,iBAAiB,CAAC;QAC9B,mCAAmC;QACnC,eAAe,CAAC,EAAE,eAAe,CAAC;KACnC,CACF,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;AAUD,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA2uClE"}
+{"version":3,"file":"ai-service.d.ts","sourceRoot":"","sources":["../../src/ai/ai-service.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,aAAa,EAIb,SAAS,EAIV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAoB,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,KAAK,EAAE,YAAY,EAAqB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAGnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,KAAK,iBAAiB,EAUvB,MAAM,eAAe,CAAC;AACvB,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;QACE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,iBAAiB,CAAC;QAC9B,mCAAmC;QACnC,eAAe,CAAC,EAAE,eAAe,CAAC;KACnC,CACF,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;AAUD,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA8zClE"}

package/dist/ai/ai-service.js

@@ -3,7 +3,8 @@
 // Integrates: provider adapter, prompt registry, validation, cost tracking, security, RAG, explainability
 import { z } from 'zod';
 import { AIBudgetExceededError, AISecurityBlockedError } from '../errors/data-errors.js';
-import { calculateModelCost } from './model-pricing.js';
+import { normalizeCost, validateTokenUsage } from './usage-validation.js';
+import { estimateModelCost as calculateModelCost, findModelRate } from './model-pricing.js';
 import { normalizeFinishReason, } from './provider.js';
 import { AIIncompleteOutputError, AIRefusalError } from './refusal.js';
 import { checkPromptSecurity } from './security.js';
@@ -32,7 +33,36 @@ export function createAIService(config) {
             const available = Object.keys(providers).join(', ');
             throw new Error(`AI provider "${name}" not configured. Available: ${available}`);
         }
-        return adapter;
+        // Every provider attempt, including validation retries, checks the budget.
+        const checkRequest = (request) => {
+            const input = JSON.stringify({
+                system: request.system,
+                prompt: request.prompt,
+                messages: request.messages,
+                tools: request.tools,
+                responseSchema: request.responseSchema,
+            });
+            checkBudget(Math.ceil(Buffer.byteLength(input, 'utf8') / 4) + (request.maxTokens ?? 0));
+        };
+        return {
+            ...adapter,
+            name: adapter.name,
+            embed: (request) => adapter.embed(request),
+            async complete(request) {
+                checkRequest(request);
+                const response = await adapter.complete(request);
+                validateTokenUsage(response.usage);
+                return { ...response, cost: normalizeCost(response.cost) ?? undefined };
+            },
+            async *stream(request) {
+                checkRequest(request);
+                for await (const event of adapter.stream(request)) {
+                    if (event.usage)
+                        validateTokenUsage(event.usage);
+                    yield { ...event, cost: normalizeCost(event.cost) ?? undefined };
+                }
+            },
+        };
     }
     function getSingleTextFieldName(schema) {
         const shape = schema instanceof z.ZodObject ? schema.shape : undefined;
@@ -94,12 +124,25 @@ export function createAIService(config) {
      * so the hook gets a fully-formed `AICostRecord`.
      */
     async function recordProviderCost(entry, costContext) {
+        entry = {
+            ...entry,
+            tenantId: config.budget ? config.budget.tenantId : entry.tenantId,
+            actor: config.budget ? config.budget.actor : entry.actor,
+            cost: (entry.cost == null ? undefined : normalizeCost(entry.cost)) ??
+                (entry.cost == null && entry.usage.totalTokens > 0 && findModelRate(entry.model)
+                    ? calculateModelCost(entry.usage.inputTokens, entry.usage.outputTokens, entry.model, {
+                        cachedInputTokens: entry.usage.cachedInputTokens,
+                        cacheWriteTokens: entry.usage.cacheWriteTokens,
+                    })
+                    : null),
+        };
         if (costTracker) {
             costTracker.record(entry);
         }
         if (onAICostRecorded) {
             const finalEntry = {
                 ...entry,
+                cost: normalizeCost(entry.cost),
                 status: entry.status ?? 'success',
                 id: crypto.randomUUID(),
                 timestamp: new Date(),
@@ -147,15 +190,12 @@ export function createAIService(config) {
         // Simple template resolution: replace top-level {{key}} placeholders.
         const substitutedKeys = new Set();
         const renderTemplate = (template) => {
-            let text = template;
-            for (const [key, value] of Object.entries(input)) {
-                const placeholder = `{{${key}}}`;
-                if (text.includes(placeholder)) {
-                    substitutedKeys.add(key);
-                    text = text.replaceAll(placeholder, String(value));
-                }
-            }
-            return text;
+            return template.replace(/\{\{([^{}]+)\}\}/g, (placeholder, key) => {
+                if (!Object.hasOwn(input, key))
+                    return placeholder;
+                substitutedKeys.add(key);
+                return String(input[key]);
+            });
         };
         const system = def.system ? renderTemplate(def.system) : undefined;
         const text = renderTemplate(def.description ?? promptName);
@@ -356,6 +396,11 @@ export function createAIService(config) {
             throw err;
         }
         const latencyMs = performance.now() - start;
+        const cost = providerCost ??
+            calculateModelCost(totalUsage.inputTokens, totalUsage.outputTokens, resolvedModel, {
+                cachedInputTokens: totalUsage.cachedInputTokens,
+                cacheWriteTokens: totalUsage.cacheWriteTokens,
+            });
         // Track cost (success path)
         await recordProviderCost({
             model: resolvedModel,
@@ -363,7 +408,7 @@ export function createAIService(config) {
             promptName: hasPromptDef ? params.prompt : undefined,
             operation: 'generate',
             usage: totalUsage,
-            cost: null,
+            cost: cost ?? null,
             latencyMs,
             tenantId: config.budget?.tenantId,
             actor: config.budget?.actor,
@@ -376,7 +421,7 @@ export function createAIService(config) {
                 promptName: hasPromptDef ? params.prompt : undefined,
                 model: promptInfo.model ?? config.defaultModel,
                 provider: activeProvider.name,
-                input: params.input,
+                input: inputForAI,
                 output: result,
                 usage: totalUsage,
                 validation: {
@@ -389,11 +434,6 @@ export function createAIService(config) {
                 latencyMs,
             });
         }
-        const cost = providerCost ??
-            calculateModelCost(totalUsage.inputTokens, totalUsage.outputTokens, resolvedModel, {
-                cachedInputTokens: totalUsage.cachedInputTokens,
-                cacheWriteTokens: totalUsage.cacheWriteTokens,
-            });
         if (toolsEnabled &&
             toolFinishNormalized === 'tool_calls' &&
             toolCallsResult &&
@@ -405,7 +445,8 @@ export function createAIService(config) {
                 usage: totalUsage,
                 model: resolvedModel,
                 provider: activeProvider.name,
-                cost,
+                cost: cost ?? 0,
+                costAvailable: cost != null,
             };
         }
         let resolvedFinishReason = finalFinishReason;
@@ -418,13 +459,17 @@ export function createAIService(config) {
             usage: totalUsage,
             model: resolvedModel,
             provider: activeProvider.name,
-            cost,
+            cost: cost ?? 0,
+            costAvailable: cost != null,
         };
     }
     function generateWithUsage(config) {
         return _generateCore(config);
     }
     return {
+        withContext(identity) {
+            return createAIService({ ...config, budget: { ...identity } });
+        },
         features: { perCallProviderModelReasoning: true },
         recordProviderCost,
         checkProviderCostBudget(config = {}) {
@@ -604,17 +649,18 @@ export function createAIService(config) {
             }
             // Compute cost and model info for the done event
             const streamCost = streamProviderCost ??
-                (streamUsage
+                (streamUsage && findModelRate(resolvedModel)
                     ? calculateModelCost(streamUsage.inputTokens, streamUsage.outputTokens, resolvedModel, {
                         cachedInputTokens: streamUsage.cachedInputTokens,
                         cacheWriteTokens: streamUsage.cacheWriteTokens,
                     })
-                    : 0);
+                    : undefined);
             const doneBase = {
                 usage: streamUsage,
                 model: resolvedModel,
                 provider: activeProvider.name,
                 cost: streamCost,
+                costAvailable: streamCost != null,
                 finishReason: providerFinishReason,
             };
             if (request.responseSchema &&
@@ -626,7 +672,7 @@ export function createAIService(config) {
                     promptName: hasPromptDef ? params.prompt : undefined,
                     operation: 'generate',
                     usage: failureUsage,
-                    cost: null,
+                    cost: streamCost ?? null,
                     latencyMs: 0,
                     tenantId: config.budget?.tenantId,
                     actor: config.budget?.actor,
@@ -650,7 +696,7 @@ export function createAIService(config) {
                     promptName: hasPromptDef ? params.prompt : undefined,
                     operation: 'generate',
                     usage: streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
-                    cost: null,
+                    cost: streamCost ?? null,
                     latencyMs: performance.now() - streamStart,
                     tenantId: config.budget?.tenantId,
                     actor: config.budget?.actor,
@@ -662,7 +708,7 @@ export function createAIService(config) {
                         promptName: hasPromptDef ? params.prompt : undefined,
                         model: resolvedModel,
                         provider: activeProvider.name,
-                        input: params.input,
+                        input: inputForAI,
                         output: singleTextField
                             ? { [singleTextField]: fullText.trim() }
                             : { text: fullText.trim() },
@@ -686,6 +732,7 @@ export function createAIService(config) {
                 let validatedData;
                 let validationFellBackToNonStreaming = false;
                 let fallbackUsage;
+                let fallbackCost;
                 try {
                     const parsed = JSON.parse(fullText);
                     validatedData = promptDef.output.parse(parsed);
@@ -731,6 +778,9 @@ export function createAIService(config) {
                         const validated = await generateWithValidation(activeProvider, { ...request, responseFormat: 'json' }, promptDef.output, { ...config.validation, model: resolvedModel, provider: activeProvider.name });
                         validatedData = validated.data;
                         fallbackUsage = validated.usage;
+                        fallbackCost =
+                            validated.cost ??
+                                calculateModelCost(validated.usage.inputTokens, validated.usage.outputTokens, resolvedModel, validated.usage);
                     }
                     catch (fallbackErr) {
                         // Bill the caller for the combined streamUsage + whatever the
@@ -769,6 +819,11 @@ export function createAIService(config) {
                 const successUsage = validationFellBackToNonStreaming
                     ? sumUsage(streamUsage, fallbackUsage)
                     : (streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 });
+                const successCost = validationFellBackToNonStreaming
+                    ? streamCost != null && fallbackCost != null
+                        ? streamCost + fallbackCost
+                        : undefined
+                    : streamCost;
                 await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
@@ -776,7 +831,7 @@ export function createAIService(config) {
                     operation: 'generate',
                     fallbackUsed: validationFellBackToNonStreaming || undefined,
                     usage: successUsage,
-                    cost: null,
+                    cost: successCost ?? null,
                     latencyMs: 0,
                     tenantId: config.budget?.tenantId,
                     actor: config.budget?.actor,
@@ -786,6 +841,9 @@ export function createAIService(config) {
                     type: 'done',
                     data: validatedData,
                     ...doneBase,
+                    usage: successUsage,
+                    cost: successCost,
+                    costAvailable: successCost != null,
                     validationFallbackFired: validationFellBackToNonStreaming,
                 };
             }
@@ -796,7 +854,7 @@ export function createAIService(config) {
                     promptName: hasPromptDef ? params.prompt : undefined,
                     operation: 'generate',
                     usage: streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
-                    cost: null,
+                    cost: streamCost ?? null,
                     latencyMs: 0,
                     tenantId: config.budget?.tenantId,
                     actor: config.budget?.actor,
@@ -807,6 +865,8 @@ export function createAIService(config) {
         },
         async extract(params) {
             const start = performance.now();
+            const { inputForAI, securityResult } = applyPromptSecurity({ text: params.text });
+            const textForAI = String(inputForAI.text);
             checkBudget();
             // extract uses default provider (no prompt-level routing)
             const activeProvider = resolveProvider();
@@ -814,7 +874,7 @@ export function createAIService(config) {
             const systemPrompt = 'Extract structured data from the following text. Return valid JSON matching the required schema.';
             const request = {
                 system: systemPrompt,
-                prompt: params.text,
+                prompt: textForAI,
                 model: config.defaultModel,
                 responseFormat: 'json',
                 responseSchema: config.enableStrictStructuredOutputs
@@ -855,7 +915,9 @@ export function createAIService(config) {
                 provider: activeProvider.name,
                 operation: 'extract',
                 usage: validated.usage,
-                cost: null,
+                cost: validated.cost ??
+                    calculateModelCost(validated.usage.inputTokens, validated.usage.outputTokens, resolvedModel, validated.usage) ??
+                    null,
                 latencyMs,
                 tenantId: config.budget?.tenantId,
                 actor: config.budget?.actor,
@@ -866,7 +928,8 @@ export function createAIService(config) {
                     operation: 'extract',
                     model: config.defaultModel,
                     provider: activeProvider.name,
-                    input: { text: params.text },
+                    input: inputForAI,
+                    securityWarnings: securityResult?.warnings.map((warning) => warning.message),
                     output: validated.data,
                     usage: validated.usage,
                     validation: { passed: validated.attempts === 1, attempts: validated.attempts },
@@ -879,6 +942,8 @@ export function createAIService(config) {
         },
         async classify(params) {
             const start = performance.now();
+            const { inputForAI, securityResult } = applyPromptSecurity({ text: params.text });
+            const textForAI = String(inputForAI.text);
             checkBudget();
             // classify uses default provider (no prompt-level routing)
             const activeProvider = resolveProvider();
@@ -886,7 +951,7 @@ export function createAIService(config) {
             const systemPrompt = 'Classify the following text into one or more of the provided labels. Return a JSON array of matching label strings.';
             const request = {
                 system: systemPrompt,
-                prompt: `Labels: ${JSON.stringify(params.labels)}\n\nText: ${params.text}`,
+                prompt: `Labels: ${JSON.stringify(params.labels)}\n\nText: ${textForAI}`,
                 model: config.defaultModel,
                 responseFormat: 'json',
                 responseSchema: config.enableStrictStructuredOutputs
@@ -930,7 +995,9 @@ export function createAIService(config) {
                 provider: activeProvider.name,
                 operation: 'classify',
                 usage: validated.usage,
-                cost: null,
+                cost: validated.cost ??
+                    calculateModelCost(validated.usage.inputTokens, validated.usage.outputTokens, resolvedModel, validated.usage) ??
+                    null,
                 latencyMs,
                 tenantId: config.budget?.tenantId,
                 actor: config.budget?.actor,
@@ -941,7 +1008,8 @@ export function createAIService(config) {
                     operation: 'classify',
                     model: config.defaultModel,
                     provider: activeProvider.name,
-                    input: { labels: params.labels, text: params.text },
+                    input: { labels: params.labels, ...inputForAI },
+                    securityWarnings: securityResult?.warnings.map((warning) => warning.message),
                     output: result,
                     usage: validated.usage,
                     validation: { passed: validated.attempts === 1, attempts: validated.attempts },