@exvio/os-backend-core 0.4.0

package/src/ai/client.ts

@@ -0,0 +1,1059 @@
+import { getCurrentTenant } from '../db/tenant-context.ts'
+import {
+  AIError,
+  isRetryableAIError,
+  toAIError,
+  unsupportedAIProviderOperation,
+} from './errors.ts'
+import { createAIProviderRegistry, type AIProviderRegistry } from './registry.ts'
+import {
+  assertAIObjectSchema,
+  createAIObjectPrompt,
+  isAIJSONValue,
+  isSupportedAIJSONSchema,
+  matchesAIJSONSchema,
+  parseAIConfig,
+  parseAIJSON,
+  validateAIObject,
+} from './schema.ts'
+import { assertActiveAIModelId } from './model-policy.ts'
+import type {
+  AIChatOutput,
+  AIChatRequestOptions,
+  AIClient,
+  AIClientOptions,
+  AIConfig,
+  AIContentPart,
+  AIEmbedRequestOptions,
+  AIEmbeddingOutput,
+  AIMessage,
+  AIModelRef,
+  AIObjectSchema,
+  AIOperation,
+  AIProvider,
+  AIProviderChatRequest,
+  AIProviderConfig,
+  AIProviderContentRequest,
+  AIProviderEmbedRequest,
+  AIProviderFactory,
+  AIProviderRequestBase,
+  AIProviderTextRequest,
+  AIRequestOptions,
+  AIResult,
+  AIRetryOptions,
+  AIStreamEvent,
+  AITelemetryEvent,
+  AIToolCall,
+  AIToolChoice,
+  AIToolDefinition,
+} from './types.ts'
+
+const DEFAULT_TIMEOUT_MS = 60_000
+const MAX_TIMEOUT_MS = 10 * 60_000
+const MAX_ATTEMPTS = 4
+const DEFAULT_RETRY = Object.freeze({ maxAttempts: 2, baseDelayMs: 100, maxDelayMs: 2_000 })
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls', 'content_filter', 'error', 'other'])
+const SENSITIVE_METADATA_KEY = /(?:api.?key|secret|token|authorization|password|credential|prompt|content)/i
+
+interface NormalizedRetry {
+  readonly maxAttempts: number
+  readonly baseDelayMs: number
+  readonly maxDelayMs: number
+}
+
+interface DeadlineScope {
+  readonly signal: AbortSignal
+  readonly timeoutMs: number
+  readonly startedAt: number
+  readonly deadlineAt: number
+  readonly externalSignal?: AbortSignal
+  readonly timedOut: () => boolean
+  readonly cleanup: () => void
+}
+
+interface ResolvedInvocation {
+  readonly tenantId: number
+  readonly selection: AIModelRef
+  readonly provider: AIProvider
+  readonly timeout: DeadlineScope
+  readonly retry: NormalizedRetry
+  readonly metadata?: Readonly<Record<string, string | number | boolean>>
+}
+
+export function createAIClient(options: AIClientOptions): AIClient {
+  if (!options || (typeof options !== 'object' && typeof options !== 'function')) {
+    throw invalidConfig('AI client options are invalid')
+  }
+
+  const registry = createAIProviderRegistry(options.providers)
+  const loadConfig = configLoader(options)
+  const resolveTenantFromContext = options.tenantResolver ?? (() => {
+    const store = getCurrentTenant()
+    return store && !store.bypass ? store.tenantId : undefined
+  })
+  const missingTenantPolicy = options.missingTenantPolicy ?? 'throw'
+  const defaultTenantId = options.defaultTenantId
+  const defaultTimeoutMs = normalizeTimeout(options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS, 'invalid_config')
+  const defaultRetry = normalizeRetry(options.retry ?? DEFAULT_RETRY, 'invalid_config')
+  const fetchImpl = options.fetch ?? globalThis.fetch
+  const now = options.now ?? Date.now
+  const random = options.random ?? Math.random
+
+  if (typeof fetchImpl !== 'function') throw invalidConfig('AI client requires a fetch implementation')
+  if (typeof now !== 'function' || typeof random !== 'function') throw invalidConfig('AI client clock is invalid')
+  if (missingTenantPolicy !== 'throw' && missingTenantPolicy !== 'use-default') {
+    throw invalidConfig('AI missing tenant policy is invalid')
+  }
+  if (missingTenantPolicy === 'use-default' && !isTenantId(defaultTenantId)) {
+    throw invalidConfig('AI default tenant must be a positive safe integer')
+  }
+
+  const resolveTenant = (explicit: number | undefined): number => {
+    let contextual: number | null | undefined
+    try {
+      contextual = resolveTenantFromContext()
+    } catch {
+      throw new AIError({ code: 'missing_tenant', message: 'AI tenant context is unavailable' })
+    }
+    if (contextual !== null && contextual !== undefined) {
+      if (!isTenantId(contextual)) {
+        throw new AIError({ code: 'missing_tenant', message: 'AI tenant context is invalid' })
+      }
+    }
+
+    if (explicit !== undefined) {
+      if (!isTenantId(explicit)) throw invalidRequest('AI tenantId must be a positive safe integer')
+      if (isTenantId(contextual) && explicit !== contextual) {
+        throw invalidRequest('AI tenantId does not match the active tenant context')
+      }
+      return explicit
+    }
+    if (isTenantId(contextual)) return contextual
+    if (missingTenantPolicy === 'use-default') return defaultTenantId!
+    throw new AIError({ code: 'missing_tenant', message: 'AI tenant context is required' })
+  }
+
+  const resolveInvocation = async (
+    operation: AIOperation,
+    requestOptions: AIRequestOptions | AIEmbedRequestOptions,
+    timeout: DeadlineScope,
+  ): Promise<ResolvedInvocation> => {
+    const tenantId = resolveTenant(requestOptions.tenantId)
+    const retry = normalizeRetry(requestOptions.retry ?? defaultRetry, 'invalid_request')
+    // Reject invalid/retired explicit overrides before loading tenant credentials.
+    // Configured lane models are validated centrally by parseAIConfig below.
+    if (requestOptions.model !== undefined) validateModelRef(requestOptions.model)
+    const raw = await raceWithDeadline(loadConfigSafely(loadConfig, tenantId), timeout)
+    const config = parseAIConfig(raw)
+    const selection = resolveModel(config, operation, requestOptions)
+    const factory = registry.get(selection.provider)
+    if (!factory) {
+      throw new AIError({
+        code: 'unknown_provider',
+        message: 'AI provider is not registered',
+        provider: selection.provider,
+        model: selection.model,
+        operation,
+      })
+    }
+    const configured = config.providers[selection.provider]
+    if (!configured?.apiKey?.trim()) {
+      throw new AIError({
+        code: 'not_configured',
+        message: 'AI provider is not configured for this tenant',
+        provider: selection.provider,
+        model: selection.model,
+        operation,
+      })
+    }
+    const providerConfig = await raceWithDeadline(
+      approveEndpoint(options, factory, configured, tenantId, selection),
+      timeout,
+    )
+    let provider: AIProvider
+    try {
+      provider = await raceWithDeadline(
+        Promise.resolve(factory({ name: selection.provider, config: providerConfig, fetch: fetchImpl })),
+        timeout,
+      )
+    } catch (error) {
+      throw normalizeError(error, timeout, selection, operation)
+    }
+    if (!provider || provider.name !== selection.provider) {
+      throw new AIError({
+        code: 'invalid_config',
+        message: 'AI provider factory returned an invalid provider',
+        provider: selection.provider,
+        model: selection.model,
+        operation,
+      })
+    }
+    return {
+      tenantId,
+      selection,
+      provider,
+      timeout,
+      retry,
+      ...('metadata' in requestOptions && requestOptions.metadata
+        ? { metadata: sanitizeMetadata(requestOptions.metadata) }
+        : {}),
+    }
+  }
+
+  const execute = async <TRaw, T>(
+    operation: Exclude<AIOperation, 'stream'>,
+    requestOptions: AIRequestOptions | AIEmbedRequestOptions,
+    invoke: (invocation: ResolvedInvocation, remainingMs: number) => Promise<AIResult<TRaw>>,
+    validateOutput: (output: unknown) => T,
+  ): Promise<AIResult<T>> => {
+    const timeout = createDeadline(
+      normalizeTimeout(requestOptions.timeoutMs ?? defaultTimeoutMs, 'invalid_request'),
+      requestOptions.signal,
+      now,
+    )
+    let invocation: ResolvedInvocation | undefined
+    let attempts = 0
+    try {
+      invocation = await resolveInvocation(operation, requestOptions, timeout)
+      for (;;) {
+        attempts += 1
+        try {
+          const result = await raceWithDeadline(
+            invoke(invocation, remainingMs(timeout, now)),
+            timeout,
+          )
+          const normalized = normalizeResult(result, invocation.selection, operation, validateOutput)
+          emitTelemetry(options, telemetryEvent(invocation, operation, attempts, now, {
+            success: true,
+            usage: normalized.usage,
+            finishReason: normalized.finishReason,
+          }, normalized))
+          return normalized
+        } catch (error) {
+          const normalized = normalizeError(error, timeout, invocation.selection, operation)
+          if (!mayRetry(normalized, attempts, invocation.retry, timeout)) throw normalized
+          await waitBeforeRetry(invocation.retry, attempts, timeout, now, random)
+        }
+      }
+    } catch (error) {
+      const normalized = normalizeError(error, timeout, invocation?.selection, operation)
+      if (invocation) {
+        emitTelemetry(options, telemetryEvent(invocation, operation, attempts, now, {
+          success: false,
+          usage: null,
+          errorCode: normalized.code,
+        }))
+      }
+      throw normalized
+    } finally {
+      timeout.cleanup()
+    }
+  }
+
+  const generateText = (prompt: string, requestOptions: AIRequestOptions = {}) => {
+    assertNonEmptyText(prompt, 'AI text prompt must not be empty')
+    return execute('text', requestOptions, async (invocation, timeoutMs) => {
+      assertCapability(invocation.provider, 'text', invocation.selection)
+      const request: AIProviderTextRequest = {
+        ...generationRequestBase(requestOptions, invocation, timeoutMs),
+        prompt,
+      }
+      return invocation.provider.generateText(request)
+    }, stringOutput)
+  }
+
+  const generateContent = (content: readonly AIContentPart[], requestOptions: AIRequestOptions = {}) => {
+    if (!Array.isArray(content) || content.length === 0) {
+      throw invalidRequest('AI content must contain at least one part')
+    }
+    return execute('content', requestOptions, async (invocation, timeoutMs) => {
+      assertCapability(invocation.provider, 'content', invocation.selection)
+      const request: AIProviderContentRequest = {
+        ...generationRequestBase(requestOptions, invocation, timeoutMs),
+        content,
+      }
+      return invocation.provider.generateContent(request)
+    }, stringOutput)
+  }
+
+  const generateChat = (messages: readonly AIMessage[], requestOptions: AIChatRequestOptions = {}) => {
+    assertMessages(messages)
+    assertToolConfiguration(requestOptions)
+    return execute('chat', requestOptions, async (invocation, timeoutMs) => {
+      assertCapability(invocation.provider, 'chat', invocation.selection)
+      if (requestOptions.tools?.length) assertCapability(invocation.provider, 'tools', invocation.selection)
+      return invocation.provider.generateChat(chatRequest(messages, requestOptions, invocation, timeoutMs))
+    }, (output) => chatOutput(output, requestOptions.tools, requestOptions.toolChoice))
+  }
+
+  const generateObject = <T>(
+    prompt: string,
+    schema: AIObjectSchema<T>,
+    requestOptions: AIRequestOptions = {},
+  ): Promise<AIResult<T>> => {
+    assertNonEmptyText(prompt, 'AI object prompt must not be empty')
+    assertAIObjectSchema(schema)
+    return execute<unknown, T>('object', requestOptions, async (invocation, timeoutMs) => {
+      const base = generationRequestBase(
+        { ...requestOptions, responseFormat: 'json' },
+        invocation,
+        timeoutMs,
+      )
+      if (invocation.provider.capabilities.object && invocation.provider.generateObject) {
+        return invocation.provider.generateObject({ ...base, prompt, schema })
+      }
+      assertCapability(invocation.provider, 'text', invocation.selection)
+      const result = await invocation.provider.generateText({
+        ...base,
+        prompt: createAIObjectPrompt(prompt, schema),
+      })
+      return { ...result, output: parseAIJSON(result.output) }
+    }, (output) => validateAIObject(output, schema))
+  }
+
+  const embed = (
+    input: string | readonly string[],
+    requestOptions: AIEmbedRequestOptions = {},
+  ): Promise<AIResult<AIEmbeddingOutput>> => {
+    const values = typeof input === 'string' ? [input] : [...input]
+    if (values.length === 0 || values.some(value => typeof value !== 'string' || value.length === 0)) {
+      throw invalidRequest('AI embedding input must not be empty')
+    }
+    if (
+      requestOptions.dimensions !== undefined
+      && (!Number.isSafeInteger(requestOptions.dimensions) || requestOptions.dimensions <= 0)
+    ) {
+      throw invalidRequest('AI embedding dimensions must be a positive safe integer')
+    }
+    return execute('embed', requestOptions, async (invocation, timeoutMs) => {
+      assertCapability(invocation.provider, 'embedding', invocation.selection)
+      if (!invocation.provider.embed) {
+        throw unsupportedAIProviderOperation(invocation.provider.name, 'embed', invocation.selection.model)
+      }
+      const request: AIProviderEmbedRequest = {
+        model: invocation.selection.model,
+        signal: invocation.timeout.signal,
+        timeoutMs,
+        input: values,
+        ...(requestOptions.dimensions === undefined ? {} : { dimensions: requestOptions.dimensions }),
+      }
+      return invocation.provider.embed(request)
+    }, output => embeddingOutput(output, values.length, requestOptions.dimensions))
+  }
+
+  const streamChat = async function* (
+    messages: readonly AIMessage[],
+    requestOptions: AIChatRequestOptions = {},
+  ): AsyncGenerator<AIStreamEvent> {
+    assertMessages(messages)
+    assertToolConfiguration(requestOptions)
+    const timeout = createDeadline(
+      normalizeTimeout(requestOptions.timeoutMs ?? defaultTimeoutMs, 'invalid_request'),
+      requestOptions.signal,
+      now,
+    )
+    let invocation: ResolvedInvocation | undefined
+    let attempts = 0
+    let emitted = false
+    let successTelemetrySent = false
+    try {
+      invocation = await resolveInvocation('stream', requestOptions, timeout)
+      assertCapability(invocation.provider, 'streaming', invocation.selection)
+      assertCapability(invocation.provider, 'chat', invocation.selection)
+      if (requestOptions.tools?.length) assertCapability(invocation.provider, 'tools', invocation.selection)
+
+      for (;;) {
+        attempts += 1
+        let finished = false
+        const streamedToolCallIds = new Set<string>()
+        try {
+          const stream = invocation.provider.streamChat(
+            chatRequest(messages, requestOptions, invocation, remainingMs(timeout, now)),
+          )
+          const iterator = stream[Symbol.asyncIterator]()
+          try {
+            while (true) {
+              const next = await raceWithDeadline(Promise.resolve(iterator.next()), timeout)
+              if (next.done) break
+              const event = next.value
+            if (timeout.signal.aborted) throw deadlineError(timeout, invocation.selection, 'stream')
+            if (finished) {
+              throw new AIError({
+                code: 'invalid_response',
+                message: 'AI provider emitted data after stream completion',
+                ...invocation.selection,
+                operation: 'stream',
+              })
+            }
+            const normalized = normalizeStreamEvent(
+              event,
+              invocation.selection,
+              requestOptions.tools,
+              requestOptions.toolChoice,
+            )
+            if (normalized.type === 'tool-call') {
+              if (streamedToolCallIds.has(normalized.toolCall.id)) {
+                throw new AIError({
+                  code: 'invalid_response',
+                  message: 'AI provider returned duplicate tool-call ids',
+                  ...invocation.selection,
+                  operation: 'stream',
+                })
+              }
+              streamedToolCallIds.add(normalized.toolCall.id)
+            }
+            emitted = true
+            if (normalized.type === 'finish') {
+              finished = true
+              emitTelemetry(options, telemetryEvent(invocation, 'stream', attempts, now, {
+                success: true,
+                usage: normalized.result.usage,
+                finishReason: normalized.result.finishReason,
+              }, normalized.result))
+              successTelemetrySent = true
+            }
+            yield normalized
+            }
+          } finally {
+            // Do not await a provider that ignores cancellation; the total
+            // deadline must remain enforceable even for a broken iterator.
+            if (typeof iterator.return === 'function') {
+              try {
+                void Promise.resolve(iterator.return()).catch(() => undefined)
+              } catch {
+                // Preserve the request outcome/deadline.
+              }
+            }
+          }
+          if (!finished) {
+            throw new AIError({
+              code: 'invalid_response',
+              message: 'AI provider stream ended without a finish event',
+              provider: invocation.selection.provider,
+              model: invocation.selection.model,
+              operation: 'stream',
+            })
+          }
+          if (!successTelemetrySent) {
+            throw new AIError({
+              code: 'invalid_response',
+              message: 'AI provider stream completed without telemetry metadata',
+              provider: invocation.selection.provider,
+              model: invocation.selection.model,
+              operation: 'stream',
+            })
+          }
+          return
+        } catch (error) {
+          const normalized = normalizeError(error, timeout, invocation.selection, 'stream')
+          if (emitted || !mayRetry(normalized, attempts, invocation.retry, timeout)) throw normalized
+          await waitBeforeRetry(invocation.retry, attempts, timeout, now, random)
+        }
+      }
+    } catch (error) {
+      const normalized = normalizeError(error, timeout, invocation?.selection, 'stream')
+      if (invocation) {
+        emitTelemetry(options, telemetryEvent(invocation, 'stream', attempts, now, {
+          success: false,
+          usage: null,
+          errorCode: normalized.code,
+        }))
+      }
+      throw normalized
+    } finally {
+      timeout.cleanup()
+    }
+  }
+
+  return Object.freeze({ generateText, generateContent, generateChat, streamChat, generateObject, embed })
+}
+
+function configLoader(options: AIClientOptions): (tenantId: number) => unknown | Promise<unknown> {
+  if (typeof options.configSource === 'function') return options.configSource
+  if (options.configSource && typeof options.configSource.loadConfig === 'function') {
+    return options.configSource.loadConfig.bind(options.configSource)
+  }
+  throw invalidConfig('AI config source is invalid')
+}
+
+async function loadConfigSafely(
+  loadConfig: (tenantId: number) => unknown | Promise<unknown>,
+  tenantId: number,
+): Promise<unknown> {
+  try {
+    return await loadConfig(tenantId)
+  } catch (error) {
+    if (error instanceof AIError) throw error
+    throw new AIError({ code: 'invalid_config', message: 'AI configuration could not be loaded' })
+  }
+}
+
+function resolveModel(
+  config: AIConfig,
+  operation: AIOperation,
+  options: AIRequestOptions | AIEmbedRequestOptions,
+): AIModelRef {
+  const explicit = options.model
+  if (explicit !== undefined) return validateModelRef(explicit)
+  const lane = options.lane ?? defaultLane(operation)
+  const selected = config.lanes[lane]
+  if (!selected) {
+    throw new AIError({
+      code: 'not_configured',
+      message: 'AI lane is not configured for this tenant',
+      operation,
+    })
+  }
+  return validateModelRef(selected)
+}
+
+function validateModelRef(value: AIModelRef): AIModelRef {
+  if (!value || !nonEmpty(value.provider) || !nonEmpty(value.model)) {
+    throw invalidRequest('AI model must explicitly include provider and model')
+  }
+  const model = value.model.trim()
+  assertActiveAIModelId(model)
+  return { provider: value.provider.trim(), model }
+}
+
+function defaultLane(operation: AIOperation): string {
+  switch (operation) {
+    case 'text':
+    case 'object': return 'text'
+    case 'content': return 'vision'
+    case 'chat':
+    case 'stream': return 'chat'
+    case 'embed': return 'embedding'
+  }
+}
+
+async function approveEndpoint(
+  clientOptions: AIClientOptions,
+  factory: AIProviderFactory,
+  config: AIProviderConfig,
+  tenantId: number,
+  selection: AIModelRef,
+): Promise<AIProviderConfig> {
+  if (config.endpoint && config.baseUrl && config.endpoint !== config.baseUrl) {
+    throw endpointError(selection)
+  }
+  const configuredValue = config.endpoint ?? config.baseUrl
+  const configured = configuredValue === undefined ? undefined : safeEndpoint(configuredValue, selection)
+  const official = factory.defaultEndpoint === undefined
+    ? undefined
+    : safeEndpoint(factory.defaultEndpoint, selection, 'invalid_config')
+
+  if (configured && configured.href !== official?.href) {
+    let allowed = false
+    try {
+      allowed = await clientOptions.validateEndpoint?.({
+        tenantId,
+        provider: selection.provider,
+        endpoint: configured,
+        ...(official ? { defaultEndpoint: official } : {}),
+      }) === true
+    } catch {
+      allowed = false
+    }
+    if (!allowed) throw endpointError(selection)
+  }
+
+  if (!configured) return config
+  return Object.freeze({ ...config, endpoint: configured.href, baseUrl: configured.href })
+}
+
+function safeEndpoint(
+  value: string,
+  selection: AIModelRef,
+  code: 'invalid_config' | 'endpoint_not_allowed' = 'endpoint_not_allowed',
+): URL {
+  let endpoint: URL
+  try {
+    endpoint = new URL(value)
+  } catch {
+    throw new AIError({
+      code,
+      message: code === 'invalid_config' ? 'AI provider default endpoint is invalid' : 'AI provider endpoint is not allowed',
+      ...selection,
+    })
+  }
+  if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password) {
+    throw new AIError({
+      code,
+      message: code === 'invalid_config' ? 'AI provider default endpoint is invalid' : 'AI provider endpoint is not allowed',
+      ...selection,
+    })
+  }
+  return endpoint
+}
+
+function endpointError(selection: AIModelRef): AIError {
+  return new AIError({
+    code: 'endpoint_not_allowed',
+    message: 'AI provider endpoint is not allowed',
+    ...selection,
+  })
+}
+
+function generationRequestBase(
+  options: AIRequestOptions,
+  invocation: ResolvedInvocation,
+  timeoutMs: number,
+): AIProviderRequestBase {
+  return {
+    model: invocation.selection.model,
+    signal: invocation.timeout.signal,
+    timeoutMs,
+    ...(options.systemInstruction === undefined ? {} : { systemInstruction: options.systemInstruction }),
+    ...(options.maxOutputTokens === undefined ? {} : { maxOutputTokens: options.maxOutputTokens }),
+    ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
+    ...(options.topP === undefined ? {} : { topP: options.topP }),
+    ...(options.stopSequences === undefined ? {} : { stopSequences: options.stopSequences }),
+    ...(options.responseFormat === undefined ? {} : { responseFormat: options.responseFormat }),
+    ...(options.disableThinking === undefined ? {} : { disableThinking: options.disableThinking }),
+  }
+}
+
+function chatRequest(
+  messages: readonly AIMessage[],
+  options: AIChatRequestOptions,
+  invocation: ResolvedInvocation,
+  timeoutMs: number,
+): AIProviderChatRequest {
+  return {
+    ...generationRequestBase(options, invocation, timeoutMs),
+    messages,
+    ...(options.tools === undefined ? {} : { tools: options.tools }),
+    ...(options.toolChoice === undefined ? {} : { toolChoice: options.toolChoice }),
+  }
+}
+
+function assertCapability(
+  provider: AIProvider,
+  capability: keyof AIProvider['capabilities'],
+  selection: AIModelRef,
+): void {
+  if (!provider.capabilities[capability]) {
+    const operation: AIOperation = capability === 'embedding'
+      ? 'embed'
+      : capability === 'streaming'
+        ? 'stream'
+        : capability === 'tools'
+          ? 'chat'
+          : capability
+    throw unsupportedAIProviderOperation(provider.name, operation, selection.model)
+  }
+}
+
+function normalizeResult<T>(
+  result: AIResult<unknown>,
+  selected: AIModelRef,
+  operation: AIOperation,
+  validateOutput: (output: unknown) => T,
+): AIResult<T> {
+  if (!result || typeof result !== 'object' || result.provider !== selected.provider || !nonEmpty(result.model)) {
+    throw invalidProviderResponse(selected, operation)
+  }
+  if (!FINISH_REASONS.has(result.finishReason)) throw invalidProviderResponse(selected, operation)
+  if (result.finishReason === 'content_filter') {
+    throw new AIError({
+      code: 'content_filtered',
+      message: 'AI provider blocked the response for safety reasons',
+      provider: result.provider,
+      model: result.model,
+      operation,
+    })
+  }
+  const usage = normalizeUsage(result.usage, selected, operation)
+  return {
+    ...result,
+    output: validateOutput(result.output),
+    provider: result.provider,
+    model: result.model,
+    usage,
+  }
+}
+
+function normalizeUsage(
+  usage: AIResult<unknown>['usage'],
+  selected: AIModelRef,
+  operation: AIOperation,
+): AIResult<unknown>['usage'] {
+  if (usage === null) return null
+  const values = [usage.inputTokens, usage.outputTokens, usage.totalTokens]
+  if (values.some(value => !Number.isSafeInteger(value) || value < 0)) {
+    throw invalidProviderResponse(selected, operation)
+  }
+  for (const optional of [usage.cachedInputTokens, usage.cacheMissInputTokens, usage.reasoningTokens]) {
+    if (optional !== undefined && (!Number.isSafeInteger(optional) || optional < 0)) {
+      throw invalidProviderResponse(selected, operation)
+    }
+  }
+  const cached = usage.cachedInputTokens ?? 0
+  const missed = usage.cacheMissInputTokens ?? 0
+  if (
+    usage.totalTokens < usage.inputTokens + usage.outputTokens
+    || cached > usage.inputTokens
+    || missed > usage.inputTokens
+    || cached + missed > usage.inputTokens
+  ) {
+    throw invalidProviderResponse(selected, operation)
+  }
+  return usage
+}
+
+function normalizeStreamEvent(
+  event: AIStreamEvent,
+  selection: AIModelRef,
+  tools?: readonly AIToolDefinition[],
+  toolChoice?: AIToolChoice,
+): AIStreamEvent {
+  if (!event || typeof event !== 'object') throw invalidProviderResponse(selection, 'stream')
+  switch (event.type) {
+    case 'text-delta':
+      if (typeof event.delta !== 'string') throw invalidProviderResponse(selection, 'stream')
+      return event
+    case 'tool-call':
+      if (!event.toolCall || !nonEmpty(event.toolCall.id) || !nonEmpty(event.toolCall.name)) {
+        throw invalidProviderResponse(selection, 'stream')
+      }
+      assertReturnedToolCall(event.toolCall, tools, toolChoice)
+      return event
+    case 'finish':
+      return {
+        type: 'finish',
+        result: normalizeResult(
+          event.result,
+          selection,
+          'stream',
+          output => chatOutput(output, tools, toolChoice),
+        ),
+      }
+  }
+}
+
+function stringOutput(value: unknown): string {
+  if (typeof value !== 'string') throw new AIError({ code: 'invalid_response', message: 'AI provider returned invalid text' })
+  return value
+}
+
+function chatOutput(
+  value: unknown,
+  tools?: readonly AIToolDefinition[],
+  toolChoice?: AIToolChoice,
+): AIChatOutput {
+  if (!value || typeof value !== 'object') {
+    throw new AIError({ code: 'invalid_response', message: 'AI provider returned invalid chat output' })
+  }
+  const output = value as Partial<AIChatOutput>
+  if (typeof output.text !== 'string' || !Array.isArray(output.toolCalls)) {
+    throw new AIError({ code: 'invalid_response', message: 'AI provider returned invalid chat output' })
+  }
+  const ids = new Set<string>()
+  for (const call of output.toolCalls) {
+    assertReturnedToolCall(call, tools, toolChoice)
+    if (ids.has(call.id)) {
+      throw new AIError({
+        code: 'invalid_response',
+        message: 'AI provider returned duplicate tool-call ids',
+        operation: 'chat',
+      })
+    }
+    ids.add(call.id)
+  }
+  if ((toolChoice === 'required' || typeof toolChoice === 'object') && output.toolCalls.length === 0) {
+    throw new AIError({
+      code: 'invalid_response',
+      message: 'AI provider did not return the required tool call',
+      operation: 'chat',
+    })
+  }
+  return output as AIChatOutput
+}
+
+function assertToolConfiguration(options: AIChatRequestOptions): void {
+  const tools = options.tools ?? []
+  const names = new Set<string>()
+  for (const tool of tools) {
+    if (
+      !tool
+      || !nonEmpty(tool.name)
+      || names.has(tool.name)
+      || !tool.parameters
+      || typeof tool.parameters !== 'object'
+      || Array.isArray(tool.parameters)
+      || !isAIJSONValue(tool.parameters)
+      || !isSupportedAIJSONSchema(tool.parameters)
+    ) {
+      throw invalidRequest('AI tool declaration is invalid')
+    }
+    names.add(tool.name)
+  }
+  if ((options.toolChoice === 'required' || typeof options.toolChoice === 'object') && tools.length === 0) {
+    throw invalidRequest('AI tool choice requires declared tools')
+  }
+  if (typeof options.toolChoice === 'object' && !names.has(options.toolChoice.name)) {
+    throw invalidRequest('AI named tool choice is not declared')
+  }
+}
+
+function assertReturnedToolCall(
+  call: unknown,
+  tools?: readonly AIToolDefinition[],
+  toolChoice?: AIToolChoice,
+): void {
+  if (!call || typeof call !== 'object') throw new AIError({
+    code: 'invalid_response', message: 'AI provider returned invalid tool arguments', operation: 'chat',
+  })
+  const candidate = call as Partial<AIToolCall>
+  const declaration = tools?.find(tool => tool.name === candidate.name)
+  if (
+    !nonEmpty(candidate.id)
+    || !nonEmpty(candidate.name)
+    || toolChoice === 'none'
+    || (typeof toolChoice === 'object' && candidate.name !== toolChoice.name)
+    || !declaration
+    || !candidate.arguments
+    || typeof candidate.arguments !== 'object'
+    || Array.isArray(candidate.arguments)
+    || !isAIJSONValue(candidate.arguments)
+    || !matchesAIJSONSchema(candidate.arguments, declaration.parameters)
+  ) {
+    throw new AIError({
+      code: 'invalid_response',
+      message: 'AI provider returned invalid tool arguments',
+      operation: 'chat',
+    })
+  }
+}
+
+function embeddingOutput(
+  value: unknown,
+  expectedRows: number,
+  expectedDimensions: number | undefined,
+): AIEmbeddingOutput {
+  if (!value || typeof value !== 'object') {
+    throw new AIError({ code: 'invalid_response', message: 'AI provider returned invalid embeddings' })
+  }
+  const embeddings = (value as Partial<AIEmbeddingOutput>).embeddings
+  const firstDimensions = Array.isArray(embeddings?.[0]) ? embeddings[0].length : 0
+  if (
+    !Array.isArray(embeddings)
+    || embeddings.length !== expectedRows
+    || firstDimensions <= 0
+    || (expectedDimensions !== undefined && firstDimensions !== expectedDimensions)
+    || embeddings.some(row => (
+      !Array.isArray(row)
+      || row.length !== firstDimensions
+      || row.some(item => typeof item !== 'number' || !Number.isFinite(item))
+    ))
+  ) {
+    throw new AIError({ code: 'invalid_response', message: 'AI provider returned invalid embeddings' })
+  }
+  return { embeddings }
+}
+
+function invalidProviderResponse(selection: AIModelRef, operation: AIOperation): AIError {
+  return new AIError({
+    code: 'invalid_response',
+    message: 'AI provider returned an invalid response',
+    ...selection,
+    operation,
+  })
+}
+
+function normalizeError(
+  error: unknown,
+  deadline: DeadlineScope,
+  selection: AIModelRef | undefined,
+  operation: AIOperation,
+): AIError {
+  if (deadline.signal.aborted) return deadlineError(deadline, selection, operation)
+  if (error instanceof TypeError) {
+    return new AIError({
+      code: 'network',
+      message: 'AI provider network request failed',
+      ...(selection ?? {}),
+      operation,
+      retryable: true,
+      cause: error,
+    })
+  }
+  return toAIError(error, { ...(selection ?? {}), operation })
+}
+
+function createDeadline(timeoutMs: number, externalSignal: AbortSignal | undefined, now: () => number): DeadlineScope {
+  const startedAt = now()
+  const controller = new AbortController()
+  let expired = false
+  const timeoutHandle = setTimeout(() => {
+    expired = true
+    controller.abort()
+  }, timeoutMs)
+  const abortFromExternal = () => controller.abort()
+  if (externalSignal?.aborted) controller.abort()
+  else externalSignal?.addEventListener('abort', abortFromExternal, { once: true })
+
+  return {
+    signal: controller.signal,
+    timeoutMs,
+    startedAt,
+    deadlineAt: startedAt + timeoutMs,
+    ...(externalSignal ? { externalSignal } : {}),
+    timedOut: () => expired,
+    cleanup: () => {
+      clearTimeout(timeoutHandle)
+      externalSignal?.removeEventListener('abort', abortFromExternal)
+    },
+  }
+}
+
+function deadlineError(
+  deadline: DeadlineScope,
+  selection: AIModelRef | undefined,
+  operation: AIOperation,
+): AIError {
+  return new AIError({
+    code: deadline.timedOut() ? 'timeout' : 'aborted',
+    message: deadline.timedOut() ? 'AI request timed out' : 'AI request was aborted',
+    ...(selection ?? {}),
+    operation,
+  })
+}
+
+async function raceWithDeadline<T>(work: Promise<T>, deadline: DeadlineScope): Promise<T> {
+  if (deadline.signal.aborted) throw deadlineError(deadline, undefined, 'text')
+  return await new Promise<T>((resolve, reject) => {
+    const abort = () => reject(deadlineError(deadline, undefined, 'text'))
+    deadline.signal.addEventListener('abort', abort, { once: true })
+    work.then(resolve, reject).finally(() => deadline.signal.removeEventListener('abort', abort))
+  })
+}
+
+function remainingMs(deadline: DeadlineScope, now: () => number): number {
+  return Math.max(1, Math.ceil(deadline.deadlineAt - now()))
+}
+
+function mayRetry(
+  error: AIError,
+  attempts: number,
+  retry: NormalizedRetry,
+  deadline: DeadlineScope,
+): boolean {
+  return !deadline.signal.aborted && attempts < retry.maxAttempts && isRetryableAIError(error)
+}
+
+async function waitBeforeRetry(
+  retry: NormalizedRetry,
+  attempts: number,
+  deadline: DeadlineScope,
+  now: () => number,
+  random: () => number,
+): Promise<void> {
+  const exponential = Math.min(retry.maxDelayMs, retry.baseDelayMs * (2 ** Math.max(0, attempts - 1)))
+  const boundedRandom = Math.min(1, Math.max(0, random()))
+  const delayMs = Math.min(retry.maxDelayMs, Math.round(exponential * (0.5 + boundedRandom)))
+  if (delayMs <= 0) return
+  await new Promise<void>((resolve, reject) => {
+    const complete = () => {
+      deadline.signal.removeEventListener('abort', abort)
+      resolve()
+    }
+    const handle = setTimeout(complete, delayMs)
+    const abort = () => {
+      clearTimeout(handle)
+      deadline.signal.removeEventListener('abort', abort)
+      reject(deadlineError(deadline, undefined, 'text'))
+    }
+    if (deadline.signal.aborted) abort()
+    else deadline.signal.addEventListener('abort', abort, { once: true })
+  })
+  if (remainingMs(deadline, now) <= 0) throw deadlineError(deadline, undefined, 'text')
+}
+
+function normalizeRetry(value: AIRetryOptions, code: 'invalid_config' | 'invalid_request'): NormalizedRetry {
+  const attempts = value.maxAttempts ?? DEFAULT_RETRY.maxAttempts
+  const base = value.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs
+  const max = value.maxDelayMs ?? DEFAULT_RETRY.maxDelayMs
+  if (!Number.isFinite(attempts) || !Number.isFinite(base) || !Number.isFinite(max) || base < 0 || max < 0) {
+    throw new AIError({ code, message: 'AI retry options are invalid' })
+  }
+  return {
+    maxAttempts: Math.max(1, Math.min(MAX_ATTEMPTS, Math.floor(attempts))),
+    baseDelayMs: Math.min(30_000, Math.floor(base)),
+    maxDelayMs: Math.min(30_000, Math.max(Math.floor(base), Math.floor(max))),
+  }
+}
+
+function normalizeTimeout(value: number, code: 'invalid_config' | 'invalid_request'): number {
+  if (!Number.isFinite(value) || value <= 0) throw new AIError({ code, message: 'AI timeout is invalid' })
+  return Math.min(MAX_TIMEOUT_MS, Math.floor(value))
+}
+
+function telemetryEvent(
+  invocation: ResolvedInvocation,
+  operation: AIOperation,
+  attempts: number,
+  now: () => number,
+  outcome: Pick<AITelemetryEvent, 'success' | 'usage'> &
+    Partial<Pick<AITelemetryEvent, 'finishReason' | 'errorCode'>>,
+  actual?: Pick<AIResult<unknown>, 'provider' | 'model'>,
+): AITelemetryEvent {
+  return {
+    operation,
+    tenantId: invocation.tenantId,
+    provider: actual?.provider ?? invocation.selection.provider,
+    model: actual?.model ?? invocation.selection.model,
+    durationMs: Math.max(0, now() - invocation.timeout.startedAt),
+    attempts,
+    ...outcome,
+    ...(invocation.metadata && Object.keys(invocation.metadata).length > 0
+      ? { metadata: invocation.metadata }
+      : {}),
+  }
+}
+
+function emitTelemetry(options: AIClientOptions, event: AITelemetryEvent): void {
+  if (!options.telemetry) return
+  try {
+    void Promise.resolve(options.telemetry(event)).catch(() => undefined)
+  } catch {
+    // Observability must never change the application-visible AI result.
+  }
+}
+
+function sanitizeMetadata(
+  metadata: Readonly<Record<string, string | number | boolean>>,
+): Readonly<Record<string, string | number | boolean>> {
+  const safe: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(metadata)) {
+    if (!SENSITIVE_METADATA_KEY.test(key)) safe[key] = value
+  }
+  return Object.freeze(safe)
+}
+
+function assertMessages(messages: readonly AIMessage[]): void {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw invalidRequest('AI chat requires at least one message')
+  }
+}
+
+function assertNonEmptyText(value: unknown, message: string): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0) throw invalidRequest(message)
+}
+
+function isTenantId(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) > 0
+}
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function invalidConfig(message: string): AIError {
+  return new AIError({ code: 'invalid_config', message })
+}
+
+function invalidRequest(message: string): AIError {
+  return new AIError({ code: 'invalid_request', message })
+}