@plumbus/core 0.8.0-beta.1 → 0.8.0-beta.10

package/dist/ai/ai-service.js

@@ -2,16 +2,101 @@
 // Full ctx.ai implementation: generate, extract, classify, retrieve
 // Integrates: provider adapter, prompt registry, validation, cost tracking, security, RAG, explainability
 import { z } from 'zod';
+import { createErrorService } from '../errors/index.js';
 import { AIBudgetExceededError, AISecurityBlockedError } from '../errors/data-errors.js';
+import { PlumbusError } from '../errors/plumbus-error.js';
 import { fillPromptTemplate } from './fill-prompt-template.js';
 import { normalizeCost, validateTokenUsage } from './usage-validation.js';
 import { estimateModelCost as calculateModelCost, findModelRate } from './model-pricing.js';
+import { restoreOmittedOptionalProperties } from './openai-strict-schema.js';
+import { resolvePromptOverride } from './prompt-overrides.js';
 import { createPromptRegistry } from './prompt-registry.js';
-import { normalizeFinishReason, } from './provider.js';
+import { isCostFreeProviderFailure } from './provider-failure.js';
+import { assertRequestTimeout, normalizeFinishReason, } from './provider.js';
 import { AIIncompleteOutputError, AIRefusalError } from './refusal.js';
 import { checkPromptSecurity } from './security.js';
 import { AIValidationError, generateWithValidation, } from './validation.js';
 import { zodToProviderJsonSchema } from './zod-to-provider-schema.js';
+/**
+ * Output a request without `maxTokens` is assumed to have produced when its usage never came
+ * back. Matches the Anthropic adapter's default `max_tokens`.
+ */
+const UNMETERED_OUTPUT_TOKENS = 4096;
+function addUsage(left, right) {
+    // Reasoning tokens are part of outputTokens (and priced there); summed once either side has them.
+    const reasoning = left.reasoningTokens === undefined && right.reasoningTokens === undefined
+        ? undefined
+        : (left.reasoningTokens ?? 0) + (right.reasoningTokens ?? 0);
+    return {
+        inputTokens: left.inputTokens + right.inputTokens,
+        outputTokens: left.outputTokens + right.outputTokens,
+        totalTokens: left.totalTokens + right.totalTokens,
+        cachedInputTokens: (left.cachedInputTokens ?? 0) + (right.cachedInputTokens ?? 0),
+        cacheWriteTokens: (left.cacheWriteTokens ?? 0) + (right.cacheWriteTokens ?? 0),
+        ...(reasoning === undefined ? {} : { reasoningTokens: reasoning }),
+    };
+}
+/** Catalog price, or undefined for an unpriced model or usage the catalog rejects. */
+function catalogCost(usage, model) {
+    try {
+        return calculateModelCost(usage.inputTokens, usage.outputTokens, model, {
+            cachedInputTokens: usage.cachedInputTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function meterAnsweredAttempt(spend, attempt, usage, providerCost) {
+    spend.answered = addUsage(spend.answered, usage);
+    const cost = providerCost ?? catalogCost(usage, attempt.model) ?? null;
+    spend.answeredCost =
+        spend.answeredCost == null || cost == null ? null : spend.answeredCost + cost;
+}
+function meterUnansweredAttempt(spend, attempt, partial = {}) {
+    spend.unmetered += 1;
+    if (partial.usage)
+        spend.unmeteredUsage = addUsage(spend.unmeteredUsage, partial.usage);
+    // A model with no price adds only what the provider had reported: the rest cannot be
+    // estimated. The attempt has already failed; refusing later calls on its account would be a
+    // lockout for the rest of the day.
+    const estimate = catalogCost({
+        inputTokens: attempt.inputTokens,
+        outputTokens: attempt.outputTokens,
+        totalTokens: attempt.inputTokens + attempt.outputTokens,
+    }, attempt.model) ?? 0;
+    // Usage reported mid-stream (Anthropic's opening input count) leaves out the output.
+    const reportedSoFar = partial.cost ?? (partial.usage ? catalogCost(partial.usage, attempt.model) : undefined) ?? 0;
+    spend.unmeteredEstimate += Math.max(estimate, reportedSoFar);
+}
+/**
+ * Meter an attempt that threw or ended in a provider `error` event. Free when nothing came back
+ * and the request never reached the provider or was turned away; the reported usage when the
+ * provider answered (refusal, truncation) or had finished; an estimate otherwise.
+ */
+function meterFailedAttempt(spend, attempt, failure, dispatched, report) {
+    const errorUsage = getTypedAIErrorUsage(failure);
+    if (errorUsage && errorUsage.totalTokens > 0) {
+        meterAnsweredAttempt(spend, attempt, errorUsage, null);
+        return;
+    }
+    const reportedSpend = report.usage !== undefined || report.cost !== undefined;
+    if (!report.streamed && !reportedSpend && (!dispatched || isCostFreeProviderFailure(failure))) {
+        return;
+    }
+    if (report.finished && reportedSpend) {
+        meterAnsweredAttempt(spend, attempt, report.usage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, report.cost ?? null);
+        return;
+    }
+    meterUnansweredAttempt(spend, attempt, report);
+}
+function getTypedAIErrorUsage(err) {
+    if (err instanceof AIRefusalError || err instanceof AIIncompleteOutputError) {
+        return err.usage;
+    }
+    return undefined;
+}
 /** Convenience: create config from a single provider (backward compat) */
 export function singleProviderConfig(provider, rest) {
     return {
@@ -26,7 +111,7 @@ function resolveReasoningOverride(reasoning, inherited) {
     return inherited;
 }
 export function createAIService(config) {
-    const { providers, defaultProvider, promptRegistry: configuredPromptRegistry, prompts, costTracker, ragPipeline, explainability, security, onAICostRecorded, } = config;
+    const { providers, promptRegistry: configuredPromptRegistry, prompts, costTracker, ragPipeline, explainability, security, onAICostRecorded, } = config;
     const promptRegistry = prompts !== undefined
         ? (() => {
             const registry = configuredPromptRegistry ?? createPromptRegistry([]);
@@ -38,13 +123,108 @@ export function createAIService(config) {
         })()
         : configuredPromptRegistry;
     const responseSchemaCache = new WeakMap();
-    function resolveProvider(providerName) {
-        const name = providerName ?? defaultProvider;
+    // Keyed by the per-call wrapper `resolveProvider` returns, so each logical call has its own.
+    const providerCallSpend = new WeakMap();
+    const concurrencyState = config._providerConcurrencyState ?? {
+        active: new Map(),
+    };
+    // Dynamic-override wrappers retain the original config object; attach the runtime so every
+    // identity-bound service created from it competes for the same slots.
+    config._providerConcurrencyState = concurrencyState;
+    function callContext(provider, operation, costContext) {
+        return {
+            provider,
+            operation,
+            ...(config.budget?.tenantId ? { tenantId: config.budget.tenantId } : {}),
+            ...(config.budget?.actor ? { actor: config.budget.actor } : {}),
+            ...(config.budget?.correlationId ? { correlationId: config.budget.correlationId } : {}),
+            ...(costContext ? { costContext } : {}),
+        };
+    }
+    function acquireProviderSlot(context) {
+        const policy = config.providerConcurrency;
+        if (!policy)
+            return () => undefined;
+        if (!Number.isSafeInteger(policy.maxConcurrentCalls) || policy.maxConcurrentCalls < 1) {
+            throw new Error('AI provider concurrency maxConcurrentCalls must be a positive integer');
+        }
+        const scope = policy.resolveScope?.(context) ??
+            [
+                context.provider,
+                context.tenantId ?? 'platform',
+                context.costContext?.serviceArea ?? 'default',
+            ].join(':');
+        const active = concurrencyState.active.get(scope) ?? 0;
+        if (active >= policy.maxConcurrentCalls) {
+            throw new PlumbusError('conflict', 'AI provider concurrency is exhausted for this tenant and package', {
+                failureCode: 'ai-provider-concurrency-exhausted',
+                reason: 'ai-provider-concurrency-exhausted',
+                provider: context.provider,
+                limit: policy.maxConcurrentCalls,
+                retryAfterSeconds: 1,
+            });
+        }
+        concurrencyState.active.set(scope, active + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const remaining = (concurrencyState.active.get(scope) ?? 1) - 1;
+            if (remaining <= 0)
+                concurrencyState.active.delete(scope);
+            else
+                concurrencyState.active.set(scope, remaining);
+        };
+    }
+    async function trustedProviderHeaders(context) {
+        const headers = (await config.resolveProviderHeaders?.(context)) ?? {};
+        const projected = {};
+        for (const [name, value] of Object.entries(headers)) {
+            const lower = name.toLowerCase();
+            if (['authorization', 'proxy-authorization', 'x-api-key', 'api-key', 'content-type'].includes(lower)) {
+                throw new Error(`AI provider propagation header "${name}" is reserved`);
+            }
+            projected[lower] = String(value);
+        }
+        return projected;
+    }
+    async function reportProviderSpan(context, startedAt, durationMs, status, traceparent, error) {
+        if (!config.onProviderSpan)
+            return;
+        try {
+            await config.onProviderSpan({
+                ...context,
+                startedAt: startedAt.toISOString(),
+                durationMs,
+                status,
+                ...(traceparent ? { traceparent } : {}),
+                ...(status === 'error'
+                    ? { errorType: error instanceof Error ? error.name : 'UnknownError' }
+                    : {}),
+            });
+        }
+        catch {
+            // Observability must never turn a provider answer into an application failure.
+        }
+    }
+    function resolveProvider(providerName, operation, costContext) {
+        // Read at call time: `resolveAiOverrides` may replace the default provider between calls.
+        const name = providerName ?? config.defaultProvider;
         const adapter = providers[name];
         if (!adapter) {
             const available = Object.keys(providers).join(', ');
             throw new Error(`AI provider "${name}" not configured. Available: ${available}`);
         }
+        const context = callContext(adapter.name, operation, costContext);
+        const providerLabel = adapter.name;
+        const spend = {
+            answered: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+            answeredCost: 0,
+            unmetered: 0,
+            unmeteredUsage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+            unmeteredEstimate: 0,
+        };
         // Every provider attempt, including validation retries, checks the budget.
         const checkRequest = (request) => {
             const input = JSON.stringify({
@@ -54,27 +234,113 @@ export function createAIService(config) {
                 tools: request.tools,
                 responseSchema: request.responseSchema,
             });
-            checkBudget(Math.ceil(Buffer.byteLength(input, 'utf8') / 4) + (request.maxTokens ?? 0));
+            const inputTokens = Math.ceil(Buffer.byteLength(input, 'utf8') / 4);
+            // The same model the call's ledger rows carry, so unpriced spend is matched to it.
+            const model = request.model ?? providerLabel;
+            checkBudget(inputTokens + (request.maxTokens ?? 0), undefined, {
+                provider: providerLabel,
+                model,
+            });
+            const cap = request.maxTokens;
+            return {
+                model,
+                inputTokens,
+                outputTokens: cap !== undefined && Number.isSafeInteger(cap) && cap > 0 ? cap : UNMETERED_OUTPUT_TOKENS,
+            };
         };
-        return {
+        const wrapper = {
             ...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 };
+                const attempt = checkRequest(request);
+                const release = acquireProviderSlot(context);
+                const startedAt = new Date();
+                let traceparent;
+                // Refusals above (budget, concurrency) and header failures never reach the provider.
+                let dispatched = false;
+                try {
+                    const transportHeaders = await trustedProviderHeaders(context);
+                    traceparent = transportHeaders.traceparent;
+                    // An already-fired abort makes the adapter's fetch reject without opening a connection.
+                    dispatched = !request.signal?.aborted;
+                    const response = await adapter.complete({ ...request, transportHeaders });
+                    validateTokenUsage(response.usage);
+                    meterAnsweredAttempt(spend, attempt, response.usage, normalizeCost(response.cost));
+                    await reportProviderSpan(context, startedAt, Date.now() - startedAt.getTime(), 'ok', traceparent);
+                    return { ...response, cost: normalizeCost(response.cost) ?? undefined };
+                }
+                catch (error) {
+                    meterFailedAttempt(spend, attempt, error, dispatched, {
+                        streamed: false,
+                        finished: false,
+                    });
+                    await reportProviderSpan(context, startedAt, Date.now() - startedAt.getTime(), 'error', traceparent, error);
+                    throw error;
+                }
+                finally {
+                    release();
+                }
             },
             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 };
+                const attempt = checkRequest(request);
+                const release = acquireProviderSlot(context);
+                const startedAt = new Date();
+                let traceparent;
+                let dispatched = false;
+                let metered = false;
+                const reported = { streamed: false, finished: false };
+                try {
+                    const transportHeaders = await trustedProviderHeaders(context);
+                    traceparent = transportHeaders.traceparent;
+                    dispatched = !request.signal?.aborted;
+                    for await (const event of adapter.stream({ ...request, transportHeaders })) {
+                        if (event.usage)
+                            reported.usage = validateTokenUsage(event.usage);
+                        const cost = normalizeCost(event.cost) ?? undefined;
+                        if (cost !== undefined)
+                            reported.cost = cost;
+                        if (event.type === 'error') {
+                            // Built-in adapters report a failed fetch (never connected, 4xx) as an opening
+                            // error event carrying the caught error. Metered before the yield: the caller
+                            // stops at a provider error event, so this generator never resumes past it.
+                            if (!metered) {
+                                metered = true;
+                                meterFailedAttempt(spend, attempt, event.cause, dispatched, reported);
+                            }
+                        }
+                        else {
+                            reported.streamed = true;
+                            if (event.type === 'done')
+                                reported.finished = true;
+                        }
+                        yield { ...event, cost };
+                    }
+                    if (!metered) {
+                        metered = true;
+                        // A stream that ended normally without usage still cost something: estimate it.
+                        if (reported.usage === undefined && reported.cost === undefined) {
+                            meterUnansweredAttempt(spend, attempt);
+                        }
+                        else {
+                            meterAnsweredAttempt(spend, attempt, reported.usage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, reported.cost ?? null);
+                        }
+                    }
+                    await reportProviderSpan(context, startedAt, Date.now() - startedAt.getTime(), 'ok', traceparent);
+                }
+                catch (error) {
+                    if (!metered)
+                        meterFailedAttempt(spend, attempt, error, dispatched, reported);
+                    await reportProviderSpan(context, startedAt, Date.now() - startedAt.getTime(), 'error', traceparent, error);
+                    throw error;
+                }
+                finally {
+                    release();
                 }
             },
         };
+        providerCallSpend.set(wrapper, spend);
+        return wrapper;
     }
     function getSingleTextFieldName(schema) {
         const shape = schema instanceof z.ZodObject ? schema.shape : undefined;
@@ -122,12 +388,6 @@ export function createAIService(config) {
             return 'incomplete';
         return 'failed';
     }
-    function getTypedAIErrorUsage(err) {
-        if (err instanceof AIRefusalError || err instanceof AIIncompleteOutputError) {
-            return err.usage;
-        }
-        return undefined;
-    }
     /**
      * Centralized cost recorder: updates the in-memory tracker and fires the
      * optional `onAICostRecorded` hook. Hook errors are swallowed so a
@@ -135,32 +395,43 @@ export function createAIService(config) {
      * id/timestamp generation mirror what `createCostTracker` does internally
      * so the hook gets a fully-formed `AICostRecord`.
      */
-    async function recordProviderCost(entry, costContext) {
+    async function recordProviderCost(entry, costContext, inferCatalogCost = true) {
+        const { estimatedCost: rawEstimate, ...rest } = entry;
+        const estimatedCost = normalizeCost(rawEstimate);
         entry = {
-            ...entry,
+            ...rest,
             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)
+                // An estimate means part of the call's spend is unknown; pricing only the answered
+                // usage would present the call as fully priced.
+                (inferCatalogCost &&
+                    estimatedCost == null &&
+                    entry.operation !== 'decide' &&
+                    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);
-        }
+        const cost = normalizeCost(entry.cost);
+        const finalEntry = {
+            ...entry,
+            usage: { ...entry.usage },
+            ...(entry.mediaUsage ? { mediaUsage: { ...entry.mediaUsage } } : {}),
+            cost,
+            ...(cost == null && estimatedCost != null ? { estimatedCost } : {}),
+            status: entry.status ?? 'success',
+            id: crypto.randomUUID(),
+            timestamp: new Date(),
+        };
+        costTracker?.record(finalEntry);
         if (onAICostRecorded) {
-            const finalEntry = {
-                ...entry,
-                cost: normalizeCost(entry.cost),
-                status: entry.status ?? 'success',
-                id: crypto.randomUUID(),
-                timestamp: new Date(),
-            };
             try {
-                await onAICostRecorded(finalEntry, costContext);
+                await onAICostRecorded(structuredClone(finalEntry), costContext);
             }
             catch (hookErr) {
                 const msg = hookErr instanceof Error ? hookErr.message : String(hookErr);
@@ -169,23 +440,47 @@ export function createAIService(config) {
         }
     }
     function sumUsage(a, b) {
-        const left = a ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-        const right = b ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        return addUsage(a ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, b ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 });
+    }
+    /**
+     * Usage and cost for the ledger row of a logical call that failed, from the attempts its
+     * resolved provider metered: everything the provider answered (including validation attempts
+     * a later transport error would otherwise drop) and, while any attempt's usage never came
+     * back, an `estimatedCost` in place of a cost so dollar budgets stay enforced. A call whose
+     * attempts never reached the provider, or were turned away, costs zero.
+     */
+    function failedCallCost(provider, usage, model) {
+        const spend = providerCallSpend.get(provider);
+        if (!spend) {
+            return { usage, cost: usage.totalTokens > 0 ? (catalogCost(usage, model) ?? null) : null };
+        }
+        // The provider's view covers every attempt, including usage a cut-off stream had reported;
+        // the call site's own figure only shows on the row if it is larger.
+        const metered = addUsage(spend.answered, spend.unmeteredUsage);
+        const rowUsage = metered.totalTokens >= usage.totalTokens ? metered : usage;
+        if (spend.unmetered === 0) {
+            return {
+                usage: rowUsage,
+                cost: rowUsage === metered ? spend.answeredCost : (catalogCost(usage, model) ?? null),
+            };
+        }
+        // Usage of the cut-off attempts is already inside their estimate; do not price it twice.
         return {
-            inputTokens: left.inputTokens + right.inputTokens,
-            outputTokens: left.outputTokens + right.outputTokens,
-            totalTokens: left.totalTokens + right.totalTokens,
-            cachedInputTokens: (left.cachedInputTokens ?? 0) + (right.cachedInputTokens ?? 0),
-            cacheWriteTokens: (left.cacheWriteTokens ?? 0) + (right.cacheWriteTokens ?? 0),
+            usage: rowUsage,
+            cost: null,
+            ...(spend.answeredCost != null
+                ? { estimatedCost: spend.answeredCost + spend.unmeteredEstimate }
+                : {}),
         };
     }
-    function checkBudget(estimatedTokens, estimatedCostUsd) {
+    function checkBudget(estimatedTokens, estimatedCostUsd, scope) {
         if (!costTracker)
             return;
         const result = costTracker.checkBudget({
             tenantId: config.budget?.tenantId,
             estimatedTokens,
             estimatedCostUsd,
+            ...scope,
         });
         if (!result.allowed) {
             throw new AIBudgetExceededError(result.reason ?? 'budget exceeded');
@@ -209,10 +504,18 @@ export function createAIService(config) {
         ]);
         const system = systemFilled?.text;
         const text = textFilled.text;
-        // Resolution chain: config/env override → prompt-level → defaults
-        // Look up override by prompt name (dots replaced with underscores for env var matching)
-        const overrideKey = promptName.toLowerCase().replaceAll('.', '_');
-        const override = config.promptOverrides?.[overrideKey] ?? config.promptOverrides?.[promptName];
+        // Field by field: resolveAiOverrides → PROMPT_{NAME}_* env → prompt definition → defaults
+        // (per-call values are applied over this by the caller). Each layer is looked up by the
+        // prompt's own name and by its env-style key (`report.summarize` → `report_summarize`), the
+        // name winning when both set a field.
+        const override = resolvePromptOverride(promptName, [
+            config.promptOverrides,
+            config._dynamicPromptOverrides,
+        ]);
+        // `reasoning` and its deprecated shorthand `reasoningEffort` are one setting: an override
+        // that sets either replaces the definition's pair (adapters prefer `reasoning` when both are
+        // sent, so mixing them would let the definition's `reasoning` beat the override).
+        const reasoningSource = override?.reasoning != null || override?.reasoningEffort != null ? override : def.model;
         return {
             system,
             text,
@@ -220,8 +523,9 @@ export function createAIService(config) {
             provider: override?.provider ?? def.model?.provider,
             temperature: override?.temperature ?? def.model?.temperature,
             maxTokens: override?.maxTokens ?? def.model?.maxTokens,
-            reasoning: override?.reasoning ?? def.model?.reasoning,
-            reasoningEffort: override?.reasoningEffort ?? def.model?.reasoningEffort,
+            reasoning: reasoningSource?.reasoning,
+            reasoningEffort: reasoningSource?.reasoningEffort,
+            timeoutMs: override?.timeoutMs ?? def.model?.timeoutMs,
             appendUnsubstitutedInput: def.appendUnsubstitutedInput,
             substitutedKeys,
         };
@@ -266,15 +570,17 @@ export function createAIService(config) {
     async function _generateCore(params) {
         const start = performance.now();
         const { inputForAI, securityResult } = applyPromptSecurity(params.input);
-        // Budget pre-check
-        checkBudget();
         // Build prompt
         const hasPromptDef = promptRegistry?.has(params.prompt);
         const promptInfo = hasPromptDef
             ? buildPromptText(params.prompt, inputForAI)
             : { text: params.prompt, substitutedKeys: new Set() };
         // Resolve provider: per-call > prompt-level > default
-        const activeProvider = resolveProvider(params.provider ?? ('provider' in promptInfo ? promptInfo.provider : undefined));
+        const activeProvider = resolveProvider(params.provider ?? ('provider' in promptInfo ? promptInfo.provider : undefined), 'generate', params.costContext);
+        const resolvedModel = params.model ?? promptInfo.model ?? config.defaultModel ?? activeProvider.name;
+        // Budget pre-check, scoped to the model so unpriced spend elsewhere does not refuse it.
+        // A refusal here leaves no ledger row.
+        checkBudget(undefined, undefined, { provider: activeProvider.name, model: resolvedModel });
         // Check if we have a schema to validate against
         const promptDef = hasPromptDef ? promptRegistry?.get(params.prompt) : undefined;
         const singleTextField = promptDef ? getSingleTextFieldName(promptDef.output) : undefined;
@@ -286,7 +592,8 @@ export function createAIService(config) {
             : promptInfo.system;
         const toolsEnabled = params.tools !== undefined;
         const outputValidationNone = params.outputValidation === 'none';
-        const skipStructuredOutput = toolsEnabled || outputValidationNone;
+        const validateToolAnswer = toolsEnabled && params.outputValidation === 'prompt' && Boolean(promptDef);
+        const skipStructuredOutput = (toolsEnabled && !validateToolAnswer) || outputValidationNone;
         const structuredResponseFormat = promptDef && !singleTextField ? 'json' : undefined;
         const resolvedReasoning = resolveReasoningOverride(params.reasoning, 'reasoning' in promptInfo ? promptInfo.reasoning : undefined);
         const resolvedLegacyReasoningEffort = params.reasoning === null || params.reasoningEffort === null
@@ -309,7 +616,14 @@ export function createAIService(config) {
                 : promptDef?.structuredOutputTransport,
             signal: params.signal,
             seed: params.seed,
+            cache: params.cache ?? config.cache,
         };
+        // Per call → prompt override → prompt definition; unset keeps the adapter's requestTimeout.
+        const timeoutMs = params.timeoutMs ?? ('timeoutMs' in promptInfo ? promptInfo.timeoutMs : undefined);
+        if (timeoutMs !== undefined) {
+            assertRequestTimeout(timeoutMs);
+            request.timeout = timeoutMs;
+        }
         if (toolsEnabled) {
             request.tools = params.tools;
             if (params.toolChoice !== undefined)
@@ -317,7 +631,6 @@ export function createAIService(config) {
             if (params.toolExecution !== undefined)
                 request.toolExecution = params.toolExecution;
         }
-        const resolvedModel = params.model ?? promptInfo.model ?? config.defaultModel ?? activeProvider.name;
         let result;
         let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let providerCost;
@@ -329,10 +642,9 @@ export function createAIService(config) {
         let toolFinishNormalized;
         try {
             if (toolsEnabled) {
-                // Tool-enabled generation: forward tools verbatim, skip Zod output
-                // validation entirely (honors outputValidation:'none'), and surface
-                // the provider tool calls when finishReason normalizes to 'tool_calls'.
-                // A non-tool final answer returns { content } as data.
+                // Default tool rounds remain raw. Explicit prompt validation constrains
+                // and validates final answers in this call; tool calls bypass the answer
+                // schema and never cause a validation retry or repeated tool action.
                 const response = await activeProvider.complete(request);
                 result = { content: response.content };
                 totalUsage = response.usage;
@@ -340,6 +652,37 @@ export function createAIService(config) {
                 toolCallsResult = response.toolCalls;
                 toolProviderState = response.providerState;
                 toolFinishNormalized = normalizeFinishReason(response.finishReason);
+                if (validateToolAnswer && promptDef && toolFinishNormalized !== 'tool_calls') {
+                    try {
+                        if (toolFinishNormalized !== 'stop') {
+                            throw new AIIncompleteOutputError({
+                                partialText: response.content,
+                                finishReason: response.finishReason ?? 'other',
+                                usage: response.usage,
+                                model: resolvedModel,
+                                provider: activeProvider.name,
+                            });
+                        }
+                        const candidate = singleTextField
+                            ? { [singleTextField]: response.content }
+                            : JSON.parse(response.content);
+                        result = promptDef.output.parse(request.responseSchema
+                            ? restoreOmittedOptionalProperties(candidate, request.responseSchema)
+                            : candidate);
+                    }
+                    catch (error) {
+                        if (error instanceof AIIncompleteOutputError)
+                            throw error;
+                        throw new AIValidationError({
+                            attempts: 1,
+                            rawOutput: response.content,
+                            lastError: error instanceof Error ? error : null,
+                            usage: response.usage,
+                            model: resolvedModel,
+                            provider: activeProvider.name,
+                        });
+                    }
+                }
             }
             else if (outputValidationNone) {
                 // Explicit no-validation path (no tools): return raw content as data.
@@ -377,26 +720,19 @@ export function createAIService(config) {
         }
         catch (err) {
             // Failure-path cost recording: capture whatever usage we know about
-            // (from AIValidationError or zero for opaque fetch errors) so the
-            // sunk provider-side spend is still visible to budgets and ledgers.
+            // (from AIValidationError, or what the provider metered per attempt)
+            // so the sunk provider-side spend is still visible to budgets and ledgers.
             const latencyMs = performance.now() - start;
             const failureUsage = err instanceof AIValidationError
                 ? err.usage
                 : (getTypedAIErrorUsage(err) ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 });
             const errorMessage = err instanceof Error ? err.message : String(err);
-            const failureCost = failureUsage.totalTokens > 0
-                ? calculateModelCost(failureUsage.inputTokens, failureUsage.outputTokens, resolvedModel, {
-                    cachedInputTokens: failureUsage.cachedInputTokens,
-                    cacheWriteTokens: failureUsage.cacheWriteTokens,
-                })
-                : null;
             await recordProviderCost({
                 model: resolvedModel,
                 provider: activeProvider.name,
                 promptName: hasPromptDef ? params.prompt : undefined,
                 operation: 'generate',
-                usage: failureUsage,
-                cost: failureCost,
+                ...failedCallCost(activeProvider, failureUsage, resolvedModel),
                 latencyMs,
                 tenantId: config.budget?.tenantId,
                 actor: config.budget?.actor,
@@ -476,15 +812,65 @@ export function createAIService(config) {
     function generateWithUsage(config) {
         return _generateCore(config);
     }
+    async function executeDecision(params, operation, project = (result) => result.answers) {
+        const costContext = params.costContext ? { ...params.costContext } : undefined;
+        // Runtime loading keeps the shared package's core error/Zod imports out of initialization.
+        const packageName = '@plumbus/ai-decision';
+        const runtime = (await import(packageName));
+        let securedInput = {};
+        let warnings;
+        let decisionName;
+        const result = await runtime.runDecision(params, config.decisions, {
+            secure(input) {
+                const checked = applyPromptSecurity(input);
+                securedInput = checked.inputForAI;
+                warnings = checked.securityResult?.warnings.map((warning) => warning.message);
+                return securedInput;
+            },
+            checkBudget,
+            async record(record) {
+                decisionName = record.decisionName;
+                await recordProviderCost({
+                    ...record,
+                    operation,
+                    tenantId: config.budget?.tenantId,
+                    actor: config.budget?.actor,
+                }, costContext, 
+                // Native decision prices must not fall back to the text-model catalog.
+                false);
+            },
+        });
+        explainability?.record({
+            operation,
+            decisionName,
+            provider: result.provider,
+            model: result.model,
+            input: securedInput,
+            output: project(result),
+            usage: result.usage,
+            securityWarnings: warnings,
+            latencyMs: result.latencyMs,
+            tenantId: config.budget?.tenantId,
+            actor: config.budget?.actor,
+        });
+        return result;
+    }
     return {
         withContext(identity) {
-            return createAIService({ ...config, budget: { ...identity } });
+            return createAIService({
+                ...config,
+                budget: { ...identity },
+                _providerConcurrencyState: concurrencyState,
+            });
         },
-        features: { perCallProviderModelReasoning: true },
+        features: { perCallProviderModelReasoning: true, typedDecisions: true },
         recordProviderCost,
         checkProviderCostBudget(config = {}) {
             checkBudget(config.estimatedTokens, config.estimatedCostUsd);
         },
+        decide(params) {
+            return executeDecision(params, 'decide');
+        },
         async generate(params) {
             const result = await _generateCore(params);
             if (result.finishReason === 'tool_calls') {
@@ -497,15 +883,16 @@ export function createAIService(config) {
             const streamStart = performance.now();
             const { inputForAI, securityResult } = applyPromptSecurity(params.input);
             const streamSecurityWarnings = securityResult?.warnings.map((w) => w.message);
-            // Budget pre-check
-            checkBudget();
             // Build prompt
             const hasPromptDef = promptRegistry?.has(params.prompt);
             const promptInfo = hasPromptDef
                 ? buildPromptText(params.prompt, inputForAI)
                 : { text: params.prompt, substitutedKeys: new Set() };
             // Resolve provider
-            const activeProvider = resolveProvider(params.provider ?? ('provider' in promptInfo ? promptInfo.provider : undefined));
+            const activeProvider = resolveProvider(params.provider ?? ('provider' in promptInfo ? promptInfo.provider : undefined), 'stream', params.costContext);
+            const resolvedModel = params.model ?? promptInfo.model ?? config.defaultModel ?? activeProvider.name;
+            // Budget pre-check, scoped to the model; a refusal here leaves no ledger row.
+            checkBudget(undefined, undefined, { provider: activeProvider.name, model: resolvedModel });
             // Detect if the output schema is a simple single-string-field object
             // (e.g. z.object({ question: z.string() })). If so, stream plain text
             // so the user sees readable words instead of JSON tokens.
@@ -561,8 +948,15 @@ export function createAIService(config) {
                 structuredOutputTransport: promptDef?.structuredOutputTransport,
                 signal: params.signal,
                 seed: params.seed,
+                cache: params.cache ?? config.cache,
             };
-            const resolvedModel = params.model ?? promptInfo.model ?? config.defaultModel ?? activeProvider.name;
+            // Per call → prompt override → prompt definition; unset keeps the adapter's requestTimeout.
+            // The non-streaming validation fallback below reuses this request, timeout included.
+            const timeoutMs = params.timeoutMs ?? ('timeoutMs' in promptInfo ? promptInfo.timeoutMs : undefined);
+            if (timeoutMs !== undefined) {
+                assertRequestTimeout(timeoutMs);
+                request.timeout = timeoutMs;
+            }
             // Stream from provider, collecting full text and usage
             let fullText = '';
             let streamUsage;
@@ -581,6 +975,9 @@ export function createAIService(config) {
                             totalTokens: event.usage.totalTokens,
                             cachedInputTokens: event.usage.cachedInputTokens,
                             cacheWriteTokens: event.usage.cacheWriteTokens,
+                            ...(event.usage.reasoningTokens !== undefined
+                                ? { reasoningTokens: event.usage.reasoningTokens }
+                                : {}),
                         };
                         if (event.cost != null)
                             streamProviderCost = event.cost;
@@ -602,25 +999,21 @@ export function createAIService(config) {
                                 totalTokens: event.usage.totalTokens,
                                 cachedInputTokens: event.usage.cachedInputTokens,
                                 cacheWriteTokens: event.usage.cacheWriteTokens,
+                                ...(event.usage.reasoningTokens !== undefined
+                                    ? { reasoningTokens: event.usage.reasoningTokens }
+                                    : {}),
                             };
                         }
                     }
                     else if (event.type === 'error') {
                         // Provider-reported mid-stream error — record whatever usage we
                         // have so the sunk spend is visible, then yield error to caller.
-                        const errCost = streamUsage
-                            ? calculateModelCost(streamUsage.inputTokens, streamUsage.outputTokens, resolvedModel, {
-                                cachedInputTokens: streamUsage.cachedInputTokens,
-                                cacheWriteTokens: streamUsage.cacheWriteTokens,
-                            })
-                            : null;
                         await recordProviderCost({
                             model: resolvedModel,
                             provider: activeProvider.name,
                             promptName: hasPromptDef ? params.prompt : undefined,
                             operation: 'generate',
-                            usage: streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
-                            cost: errCost,
+                            ...failedCallCost(activeProvider, streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, resolvedModel),
                             latencyMs: 0,
                             tenantId: config.budget?.tenantId,
                             actor: config.budget?.actor,
@@ -636,19 +1029,12 @@ export function createAIService(config) {
                 // Transport-level failure mid-stream (fetch error, abort, etc.).
                 const errUsage = getTypedAIErrorUsage(err) ??
                     streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-                const errCost = errUsage.totalTokens > 0
-                    ? calculateModelCost(errUsage.inputTokens, errUsage.outputTokens, resolvedModel, {
-                        cachedInputTokens: errUsage.cachedInputTokens,
-                        cacheWriteTokens: errUsage.cacheWriteTokens,
-                    })
-                    : null;
                 await recordProviderCost({
                     model: resolvedModel,
                     provider: activeProvider.name,
                     promptName: hasPromptDef ? params.prompt : undefined,
                     operation: 'generate',
-                    usage: errUsage,
-                    cost: errCost,
+                    ...failedCallCost(activeProvider, errUsage, resolvedModel),
                     latencyMs: 0,
                     tenantId: config.budget?.tenantId,
                     actor: config.budget?.actor,
@@ -745,7 +1131,11 @@ export function createAIService(config) {
                 let fallbackCost;
                 try {
                     const parsed = JSON.parse(fullText);
-                    validatedData = promptDef.output.parse(parsed);
+                    // Same null-to-absent step as non-streaming validation: OpenAI strict mode streams an
+                    // omitted optional property as null.
+                    validatedData = promptDef.output.parse(request.responseSchema
+                        ? restoreOmittedOptionalProperties(parsed, request.responseSchema)
+                        : parsed);
                 }
                 catch (parseErr) {
                     // Streamed output failed local validation. The default behaviour
@@ -757,19 +1147,12 @@ export function createAIService(config) {
                         const errMsg = parseErr instanceof Error ? parseErr.message : String(parseErr);
                         console.error(`[stream:${params.prompt}] validation-fallback SKIPPED by prompt config — stream produced invalid JSON (${errMsg}); throwing. streamedChars=${fullText.length} finishReason=${providerFinishReason ?? 'unknown'}`);
                         const failureUsage = streamUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-                        const failureCost = failureUsage.totalTokens > 0
-                            ? calculateModelCost(failureUsage.inputTokens, failureUsage.outputTokens, resolvedModel, {
-                                cachedInputTokens: failureUsage.cachedInputTokens,
-                                cacheWriteTokens: failureUsage.cacheWriteTokens,
-                            })
-                            : null;
                         await recordProviderCost({
                             model: resolvedModel,
                             provider: activeProvider.name,
                             promptName: hasPromptDef ? params.prompt : undefined,
                             operation: 'generate',
-                            usage: failureUsage,
-                            cost: failureCost,
+                            ...failedCallCost(activeProvider, failureUsage, resolvedModel),
                             latencyMs: 0,
                             tenantId: config.budget?.tenantId,
                             actor: config.budget?.actor,
@@ -804,19 +1187,12 @@ export function createAIService(config) {
                                 totalTokens: 0,
                             });
                         const combinedUsage = sumUsage(streamUsage, fallbackErrorUsage);
-                        const combinedCost = combinedUsage.totalTokens > 0
-                            ? calculateModelCost(combinedUsage.inputTokens, combinedUsage.outputTokens, resolvedModel, {
-                                cachedInputTokens: combinedUsage.cachedInputTokens,
-                                cacheWriteTokens: combinedUsage.cacheWriteTokens,
-                            })
-                            : null;
                         await recordProviderCost({
                             model: resolvedModel,
                             provider: activeProvider.name,
                             promptName: hasPromptDef ? params.prompt : undefined,
                             operation: 'generate',
-                            usage: combinedUsage,
-                            cost: combinedCost,
+                            ...failedCallCost(activeProvider, combinedUsage, resolvedModel),
                             latencyMs: 0,
                             tenantId: config.budget?.tenantId,
                             actor: config.budget?.actor,
@@ -877,10 +1253,10 @@ export function createAIService(config) {
             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();
+            const activeProvider = resolveProvider(undefined, 'extract', params.costContext);
             const resolvedModel = config.defaultModel ?? activeProvider.name;
+            checkBudget(undefined, undefined, { provider: activeProvider.name, model: resolvedModel });
             const systemPrompt = 'Extract structured data from the following text. Return valid JSON matching the required schema.';
             const request = {
                 system: systemPrompt,
@@ -892,6 +1268,11 @@ export function createAIService(config) {
                     : undefined,
                 signal: params.signal,
             };
+            // Unset keeps the adapter's requestTimeout; each validation retry gets its own.
+            if (params.timeoutMs !== undefined) {
+                assertRequestTimeout(params.timeoutMs);
+                request.timeout = params.timeoutMs;
+            }
             let validated;
             try {
                 validated = (await generateWithValidation(activeProvider, request, params.schema, {
@@ -909,8 +1290,7 @@ export function createAIService(config) {
                     model: resolvedModel,
                     provider: activeProvider.name,
                     operation: 'extract',
-                    usage: failureUsage,
-                    cost: null,
+                    ...failedCallCost(activeProvider, failureUsage, resolvedModel),
                     latencyMs,
                     tenantId: config.budget?.tenantId,
                     actor: config.budget?.actor,
@@ -951,24 +1331,72 @@ export function createAIService(config) {
             return validated.data;
         },
         async classify(params) {
+            const options = z
+                .object({
+                provider: z.string().trim().min(1).optional(),
+                model: z.string().trim().min(1).optional(),
+                threshold: z.number().finite().min(0).max(1).optional(),
+            })
+                .safeParse(params);
+            if (!options.success)
+                throw createErrorService().validation('Invalid classification options');
+            const { provider, model, threshold } = options.data;
+            if (provider && config.decisions && Object.hasOwn(config.decisions.providers, provider)) {
+                if (Object.hasOwn(providers, provider))
+                    throw createErrorService().validation('Classification provider is registered in both registries; use distinct names');
+                const input = z
+                    .object({ labels: z.array(z.string().min(1)).min(1).max(256), text: z.string() })
+                    .safeParse(params);
+                if (!input.success)
+                    throw createErrorService().validation('Decision classification requires 1–256 nonempty labels and string text');
+                const { labels, text } = input.data;
+                const questions = Object.fromEntries(labels.map((label, index) => [
+                    `label_${index}`,
+                    {
+                        type: 'probability',
+                        instructions: { label, question: 'Does the label apply to the text?' },
+                    },
+                ]));
+                const select = (result) => labels.filter((_label, index) => (result.answers[`label_${index}`]?.probability ?? -1) >= (threshold ?? 0.5));
+                const result = await executeDecision({
+                    state: { text },
+                    questions,
+                    provider,
+                    model,
+                    signal: params.signal,
+                    timeoutMs: params.timeoutMs,
+                    costContext: params.costContext,
+                }, 'classify', select);
+                return select(result);
+            }
+            if (provider && !Object.hasOwn(providers, provider))
+                throw createErrorService().validation('Classification provider is not registered');
+            if (threshold !== undefined)
+                throw createErrorService().validation('Classification threshold requires a decision provider');
             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();
-            const resolvedModel = config.defaultModel ?? activeProvider.name;
+            // Text classification retains its existing path, with optional per-call routing.
+            const activeProvider = resolveProvider(provider, 'classify', params.costContext);
+            const requestedModel = model ?? config.defaultModel;
+            const resolvedModel = requestedModel ?? activeProvider.name;
+            checkBudget(undefined, undefined, { provider: activeProvider.name, model: resolvedModel });
             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: ${textForAI}`,
-                model: config.defaultModel,
+                model: requestedModel,
                 responseFormat: 'json',
                 responseSchema: config.enableStrictStructuredOutputs
                     ? zodToProviderJsonSchema(z.array(z.string()), { promptName: 'classify' }).schema
                     : undefined,
                 signal: params.signal,
             };
+            // Unset keeps the adapter's requestTimeout; each validation retry gets its own.
+            if (params.timeoutMs !== undefined) {
+                assertRequestTimeout(params.timeoutMs);
+                request.timeout = params.timeoutMs;
+            }
             const schema = z.array(z.string());
             let validated;
             try {
@@ -987,8 +1415,7 @@ export function createAIService(config) {
                     model: resolvedModel,
                     provider: activeProvider.name,
                     operation: 'classify',
-                    usage: failureUsage,
-                    cost: null,
+                    ...failedCallCost(activeProvider, failureUsage, resolvedModel),
                     latencyMs,
                     tenantId: config.budget?.tenantId,
                     actor: config.budget?.actor,
@@ -1016,7 +1443,7 @@ export function createAIService(config) {
             if (explainability) {
                 explainability.record({
                     operation: 'classify',
-                    model: config.defaultModel,
+                    model: requestedModel,
                     provider: activeProvider.name,
                     input: { labels: params.labels, ...inputForAI },
                     securityWarnings: securityResult?.warnings.map((warning) => warning.message),
@@ -1036,6 +1463,8 @@ export function createAIService(config) {
             }
             const start = performance.now();
             checkBudget();
+            if (params.timeoutMs !== undefined)
+                assertRequestTimeout(params.timeoutMs);
             const results = await ragPipeline.retrieve({
                 query: params.query,
                 tenantId: config.budget?.tenantId,
@@ -1043,6 +1472,8 @@ export function createAIService(config) {
                 filter: params.filter,
                 limit: params.limit,
                 minScore: params.minScore,
+                ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs } : {}),
+                ...(params.signal !== undefined ? { signal: params.signal } : {}),
             });
             const latencyMs = performance.now() - start;
             if (explainability) {