@exvio/os-backend-core 0.4.0

package/src/ai/providers/sse.ts

@@ -0,0 +1,163 @@
+/**
+ * A deliberately small SSE decoder for OpenAI-compatible streaming APIs.
+ *
+ * It implements the pieces of the event-stream format those APIs rely on:
+ * CRLF/LF/CR line endings, comments, multi-line `data` fields and a final
+ * unterminated event. The decoder never includes provider data in thrown
+ * errors because a response can contain user input or other sensitive data.
+ */
+
+export interface SseJsonOptions {
+  signal?: AbortSignal
+  /** Refuse an individual event larger than this many decoded characters. */
+  maxEventSize?: number
+}
+
+export type SseJsonEvent<T> =
+  | { type: 'data'; data: T }
+  | { type: 'done' }
+
+export class SseDecodeError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'SseDecodeError'
+  }
+}
+
+/**
+ * Decode JSON `data:` events from a fetch response body.
+ *
+ * The iterator yields a `done` event only for an explicit `[DONE]` marker.
+ * Consumers should still treat normal EOF as completion because a number of
+ * OpenAI-compatible servers omit that marker.
+ */
+export async function* parseSseJson<T>(
+  body: ReadableStream<Uint8Array>,
+  options: SseJsonOptions = {},
+): AsyncGenerator<SseJsonEvent<T>, void, undefined> {
+  const { signal, maxEventSize = 1_048_576 } = options
+  if (!Number.isSafeInteger(maxEventSize) || maxEventSize <= 0) {
+    throw new TypeError('maxEventSize must be a positive safe integer')
+  }
+  throwIfAborted(signal)
+
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  let sawExplicitDone = false
+  let finishedReading = false
+
+  const onAbort = () => {
+    // Cancelling unblocks a pending read. Ignore the returned promise here;
+    // the generator's finally block performs the awaited cleanup.
+    void reader.cancel(abortReason(signal))
+  }
+  signal?.addEventListener('abort', onAbort, { once: true })
+
+  try {
+    while (!sawExplicitDone) {
+      throwIfAborted(signal)
+      const result = await reader.read()
+      throwIfAborted(signal)
+
+      if (result.done) {
+        finishedReading = true
+        buffer += decoder.decode()
+        break
+      }
+
+      buffer += decoder.decode(result.value, { stream: true })
+      if (buffer.length > maxEventSize && findFrameBoundary(buffer) === undefined) {
+        throw new SseDecodeError('SSE event exceeded the configured size limit')
+      }
+
+      while (true) {
+        const boundary = findFrameBoundary(buffer)
+        if (!boundary) break
+
+        const frame = buffer.slice(0, boundary.index)
+        buffer = buffer.slice(boundary.index + boundary.length)
+        const event = decodeFrame<T>(frame, maxEventSize)
+        if (!event) continue
+
+        yield event
+        if (event.type === 'done') {
+          sawExplicitDone = true
+          break
+        }
+      }
+    }
+
+    // A valid server may close after its last `data:` line without sending a
+    // blank separator or [DONE]. Decode that final frame before returning.
+    if (!sawExplicitDone && finishedReading && buffer.length > 0) {
+      const event = decodeFrame<T>(buffer, maxEventSize)
+      if (event) yield event
+    }
+  } catch (error) {
+    if (signal?.aborted) throw abortReason(signal)
+    throw error
+  } finally {
+    signal?.removeEventListener('abort', onAbort)
+    // If the consumer stopped early, cancel the transport so its socket can
+    // be returned to the pool. Calling cancel after EOF is harmless in the
+    // web-stream implementations used by Bun and Node.
+    if (!finishedReading) {
+      try {
+        await reader.cancel()
+      } catch {
+        // Preserve the original iteration result/error.
+      }
+    }
+    reader.releaseLock()
+  }
+}
+
+function decodeFrame<T>(frame: string, maxEventSize: number): SseJsonEvent<T> | undefined {
+  if (frame.length > maxEventSize) {
+    throw new SseDecodeError('SSE event exceeded the configured size limit')
+  }
+
+  // A boundary can consist of mixed newline styles; splitting this way also
+  // accepts the final unterminated line at EOF.
+  const lines = frame.split(/\r\n|\n|\r/)
+  const dataLines: string[] = []
+
+  for (const line of lines) {
+    if (line.length === 0 || line.startsWith(':')) continue
+
+    const colon = line.indexOf(':')
+    const field = colon === -1 ? line : line.slice(0, colon)
+    if (field !== 'data') continue
+
+    let value = colon === -1 ? '' : line.slice(colon + 1)
+    if (value.startsWith(' ')) value = value.slice(1)
+    dataLines.push(value)
+  }
+
+  if (dataLines.length === 0) return undefined
+  const payload = dataLines.join('\n')
+  if (payload.trim() === '[DONE]') return { type: 'done' }
+
+  try {
+    return { type: 'data', data: JSON.parse(payload) as T }
+  } catch (cause) {
+    throw new SseDecodeError('Provider returned malformed JSON in an SSE event', { cause })
+  }
+}
+
+function findFrameBoundary(input: string): { index: number; length: number } | undefined {
+  // A blank line is two line endings. Each ending may independently be CRLF,
+  // LF, or CR, so this expression also handles mixed proxy-normalised input.
+  const match = /(?:\r\n|\n|\r)(?:\r\n|\n|\r)/.exec(input)
+  return match?.index === undefined ? undefined : { index: match.index, length: match[0].length }
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw abortReason(signal)
+}
+
+function abortReason(signal: AbortSignal | undefined): unknown {
+  if (signal?.reason !== undefined) return signal.reason
+  return new DOMException('The operation was aborted', 'AbortError')
+}

package/src/ai/registry.ts

@@ -0,0 +1,65 @@
+import { AIError } from './errors.ts'
+import type { AIProviderFactory, AIProviderName } from './types.ts'
+
+export type AIProviderRegistry = ReadonlyMap<AIProviderName, AIProviderFactory>
+
+/**
+ * Create a request-independent registry snapshot. There is deliberately no
+ * package-global registry: each application owns exactly which providers are
+ * available, and tests cannot leak registrations into one another.
+ */
+export function createAIProviderRegistry(
+  entries: Iterable<readonly [AIProviderName, AIProviderFactory]> = [],
+): AIProviderRegistry {
+  const registry = new Map<AIProviderName, AIProviderFactory>()
+  for (const [name, factory] of entries) {
+    assertProviderRegistration(name, factory)
+    if (registry.has(name)) {
+      throw new AIError({
+        code: 'invalid_config',
+        message: 'AI provider registry contains a duplicate name',
+      })
+    }
+    registry.set(name, factory)
+  }
+  return registry
+}
+
+/** Return a new snapshot with one provider added; the input map is untouched. */
+export function withAIProvider(
+  registry: AIProviderRegistry,
+  name: AIProviderName,
+  factory: AIProviderFactory,
+): AIProviderRegistry {
+  assertProviderRegistration(name, factory)
+  if (registry.has(name)) {
+    throw new AIError({
+      code: 'invalid_config',
+      message: 'AI provider is already registered',
+      provider: name,
+    })
+  }
+  const next = new Map(registry)
+  next.set(name, factory)
+  return next
+}
+
+function assertProviderRegistration(name: string, factory: AIProviderFactory): void {
+  if (!isNonEmptyString(name) || name.length > 128 || /\s/.test(name)) {
+    throw new AIError({
+      code: 'invalid_config',
+      message: 'AI provider registry name is invalid',
+    })
+  }
+  if (typeof factory !== 'function') {
+    throw new AIError({
+      code: 'invalid_config',
+      message: 'AI provider registry factory is invalid',
+      provider: name,
+    })
+  }
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}

package/src/ai/schema.ts

@@ -0,0 +1,382 @@
+import { AIError } from './errors.ts'
+import { assertActiveAIModelId } from './model-policy.ts'
+import type {
+  AIConfig,
+  AIModelRef,
+  AIObjectSchema,
+  AIProviderConfig,
+} from './types.ts'
+
+/** Validate and copy application-owned config without retaining unknown fields. */
+export function parseAIConfig(value: unknown): AIConfig {
+  if (!isRecord(value)) invalidConfig()
+
+  const rawProviders = value.providers
+  const rawLanes = value.lanes
+  if (!isRecord(rawProviders) || !isRecord(rawLanes)) invalidConfig()
+
+  const providers: Record<string, AIProviderConfig> = Object.create(null) as Record<string, AIProviderConfig>
+  for (const [name, rawProvider] of Object.entries(rawProviders)) {
+    if (!validName(name) || !isRecord(rawProvider)) invalidConfig()
+
+    const apiKey = optionalString(rawProvider.apiKey ?? rawProvider.api_key)
+    const endpoint = optionalString(rawProvider.endpoint)
+    const baseUrl = optionalString(rawProvider.baseUrl ?? rawProvider.base_url)
+    const settings = rawProvider.settings
+    if (settings !== undefined && !isRecord(settings)) invalidConfig()
+
+    providers[name] = Object.freeze({
+      ...(apiKey === undefined ? {} : { apiKey }),
+      ...(endpoint === undefined ? {} : { endpoint }),
+      ...(baseUrl === undefined ? {} : { baseUrl }),
+      ...(settings === undefined ? {} : { settings: Object.freeze({ ...settings }) }),
+    })
+  }
+
+  const lanes: Record<string, AIModelRef> = Object.create(null) as Record<string, AIModelRef>
+  for (const [name, rawLane] of Object.entries(rawLanes)) {
+    if (!validName(name) || !isRecord(rawLane)) invalidConfig()
+    const provider = requiredString(rawLane.provider)
+    const model = requiredString(rawLane.model ?? rawLane.default_model)
+    assertActiveAIModelId(model)
+    lanes[name] = Object.freeze({ provider, model })
+  }
+
+  return Object.freeze({
+    providers: Object.freeze(providers),
+    lanes: Object.freeze(lanes),
+  })
+}
+
+/** Parse an exact JSON value, allowing only a single surrounding markdown fence. */
+export function parseAIJSON(text: string): unknown {
+  if (typeof text !== 'string') invalidResponse()
+  const trimmed = text.trim()
+  if (!trimmed) invalidResponse()
+
+  const fenced = /^```(?:json)?\s*\r?\n?([\s\S]*?)\r?\n?```$/i.exec(trimmed)
+  const source = (fenced?.[1] ?? trimmed).trim()
+  try {
+    return JSON.parse(source) as unknown
+  } catch {
+    invalidResponse()
+  }
+}
+
+export function validateAIObject<T>(value: unknown, schema: AIObjectSchema<T>): T {
+  assertAIObjectSchema(schema)
+  try {
+    return schema.validate(value)
+  } catch {
+    invalidResponse()
+  }
+}
+
+export function parseAIObject<T>(text: string, schema: AIObjectSchema<T>): T {
+  return validateAIObject(parseAIJSON(text), schema)
+}
+
+export function createAIObjectPrompt<T>(prompt: string, schema: AIObjectSchema<T>): string {
+  if (typeof prompt !== 'string' || prompt.length === 0) {
+    throw new AIError({
+      code: 'invalid_request',
+      message: 'AI object prompt must not be empty',
+      operation: 'object',
+    })
+  }
+  assertAIObjectSchema(schema)
+  return `${prompt}\n\nReturn only JSON matching this schema:\n${JSON.stringify(schema.jsonSchema)}`
+}
+
+/** Validate before any billable provider request is started. */
+export function assertAIObjectSchema<T>(schema: AIObjectSchema<T>): void {
+  if (
+    !schema
+    || typeof schema.validate !== 'function'
+    || !isRecord(schema.jsonSchema)
+    || !isAIJSONValue(schema.jsonSchema)
+    || !isSupportedAIJSONSchema(schema.jsonSchema)
+  ) {
+    throw new AIError({
+      code: 'invalid_request',
+      message: 'AI object schema is invalid',
+      operation: 'object',
+    })
+  }
+}
+
+/** JSON-Schema subset validator used for untrusted provider tool arguments. */
+export function matchesAIJSONSchema(
+  value: unknown,
+  schema: unknown,
+  root: unknown = schema,
+  depth = 0,
+): boolean {
+  if (depth > 64) return false
+  if (typeof schema === 'boolean') return schema
+  if (!isRecord(schema)) return false
+
+  if (typeof schema.$ref === 'string') {
+    const resolved = resolveLocalRef(root, schema.$ref)
+    return resolved !== undefined && matchesAIJSONSchema(value, resolved, root, depth + 1)
+  }
+  if (schema.nullable === true && value === null) return true
+  if (Array.isArray(schema.allOf) && !schema.allOf.every(item => matchesAIJSONSchema(value, item, root, depth + 1))) return false
+  if (Array.isArray(schema.anyOf) && !schema.anyOf.some(item => matchesAIJSONSchema(value, item, root, depth + 1))) return false
+  if (Array.isArray(schema.oneOf)) {
+    if (schema.oneOf.filter(item => matchesAIJSONSchema(value, item, root, depth + 1)).length !== 1) return false
+  }
+  if (schema.not !== undefined && matchesAIJSONSchema(value, schema.not, root, depth + 1)) return false
+  if (schema.const !== undefined && !jsonEquals(value, schema.const)) return false
+  if (Array.isArray(schema.enum) && !schema.enum.some(item => jsonEquals(value, item))) return false
+
+  const types = typeof schema.type === 'string'
+    ? [schema.type]
+    : Array.isArray(schema.type) && schema.type.every(item => typeof item === 'string')
+      ? schema.type as string[]
+      : []
+  if (types.length > 0 && !types.some(type => matchesJSONType(value, type))) return false
+
+  if (isRecord(value)) {
+    const properties = isRecord(schema.properties) ? schema.properties : {}
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (typeof key !== 'string' || !Object.hasOwn(value, key)) return false
+      }
+    }
+    for (const [key, child] of Object.entries(value)) {
+      if (Object.hasOwn(properties, key)) {
+        if (!matchesAIJSONSchema(child, properties[key], root, depth + 1)) return false
+      } else if (schema.additionalProperties === false) {
+        return false
+      } else if (isRecord(schema.additionalProperties) || typeof schema.additionalProperties === 'boolean') {
+        if (!matchesAIJSONSchema(child, schema.additionalProperties, root, depth + 1)) return false
+      }
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) return false
+    if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) return false
+    if (schema.items !== undefined && !value.every(item => matchesAIJSONSchema(item, schema.items, root, depth + 1))) return false
+  }
+
+  if (typeof value === 'string') {
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) return false
+    if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) return false
+    if (typeof schema.pattern === 'string') {
+      try {
+        if (!new RegExp(schema.pattern, 'u').test(value)) return false
+      } catch {
+        return false
+      }
+    }
+  }
+
+  if (typeof value === 'number') {
+    if (typeof schema.minimum === 'number' && value < schema.minimum) return false
+    if (typeof schema.maximum === 'number' && value > schema.maximum) return false
+    if (typeof schema.exclusiveMinimum === 'number' && value <= schema.exclusiveMinimum) return false
+    if (typeof schema.exclusiveMaximum === 'number' && value >= schema.exclusiveMaximum) return false
+    if (typeof schema.multipleOf === 'number' && (
+      schema.multipleOf <= 0
+      || Math.abs(value / schema.multipleOf - Math.round(value / schema.multipleOf)) > Number.EPSILON * 16
+    )) return false
+  }
+  return true
+}
+
+export function isAIJSONValue(value: unknown, seen = new WeakSet<object>()): boolean {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true
+  if (typeof value === 'number') return Number.isFinite(value)
+  if (typeof value !== 'object') return false
+  if (seen.has(value)) return false
+  seen.add(value)
+  const valid = Array.isArray(value)
+    ? value.every(item => isAIJSONValue(item, seen))
+    : isRecord(value) && Object.values(value).every(item => isAIJSONValue(item, seen))
+  seen.delete(value)
+  return valid
+}
+
+const SUPPORTED_SCHEMA_KEYS = new Set([
+  '$ref', '$defs', 'definitions',
+  'title', 'description', 'default', 'examples',
+  'type', 'nullable', 'enum', 'const',
+  'allOf', 'anyOf', 'oneOf', 'not',
+  'properties', 'required', 'additionalProperties',
+  'items', 'minItems', 'maxItems',
+  'minLength', 'maxLength', 'pattern',
+  'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
+])
+
+/**
+ * Core intentionally supports a strict JSON-Schema subset. Unknown validation
+ * keywords fail before a provider call rather than being silently ignored.
+ */
+export function isSupportedAIJSONSchema(schema: unknown): boolean {
+  return isSupportedSchema(schema, schema, 0)
+}
+
+function isSupportedSchema(schema: unknown, root: unknown, depth: number): boolean {
+  if (depth > 64) return false
+  if (typeof schema === 'boolean') return true
+  if (!isRecord(schema)) return false
+  if (Object.keys(schema).some(key => !SUPPORTED_SCHEMA_KEYS.has(key))) return false
+
+  if (schema.$ref !== undefined) {
+    if (
+      typeof schema.$ref !== 'string'
+      || (schema.$ref !== '#' && !schema.$ref.startsWith('#/'))
+      || Object.keys(schema).some(key => !['$ref', 'title', 'description'].includes(key))
+    ) return false
+    const resolved = resolveLocalRef(root, schema.$ref)
+    return resolved !== undefined && isSupportedSchema(resolved, root, depth + 1)
+  }
+
+  for (const definitionsKey of ['$defs', 'definitions'] as const) {
+    const definitions = schema[definitionsKey]
+    if (definitions !== undefined) {
+      if (!isRecord(definitions)) return false
+      if (Object.values(definitions).some(child => !isSupportedSchema(child, root, depth + 1))) return false
+    }
+  }
+
+  const allowedTypes = new Set(['null', 'object', 'array', 'string', 'number', 'integer', 'boolean'])
+  if (schema.type !== undefined) {
+    const types = typeof schema.type === 'string' ? [schema.type] : schema.type
+    if (!Array.isArray(types) || types.length === 0 || types.some(type => typeof type !== 'string' || !allowedTypes.has(type))) {
+      return false
+    }
+  }
+  if (schema.nullable !== undefined && typeof schema.nullable !== 'boolean') return false
+
+  const properties = schema.properties
+  if (properties !== undefined) {
+    if (!isRecord(properties)) return false
+    if (Object.values(properties).some(child => !isSupportedSchema(child, root, depth + 1))) return false
+  }
+  if (schema.required !== undefined && (
+    !Array.isArray(schema.required)
+    || schema.required.some(key => typeof key !== 'string')
+    || new Set(schema.required).size !== schema.required.length
+  )) return false
+  if (
+    schema.additionalProperties !== undefined
+    && typeof schema.additionalProperties !== 'boolean'
+    && !isSupportedSchema(schema.additionalProperties, root, depth + 1)
+  ) return false
+  if (schema.items !== undefined && !isSupportedSchema(schema.items, root, depth + 1)) return false
+
+  for (const combinator of ['allOf', 'anyOf', 'oneOf'] as const) {
+    const entries = schema[combinator]
+    if (entries !== undefined && (
+      !Array.isArray(entries)
+      || entries.length === 0
+      || entries.some(child => !isSupportedSchema(child, root, depth + 1))
+    )) return false
+  }
+  if (schema.not !== undefined && !isSupportedSchema(schema.not, root, depth + 1)) return false
+
+  if (schema.enum !== undefined && (
+    !Array.isArray(schema.enum) || schema.enum.length === 0 || !isAIJSONValue(schema.enum)
+  )) return false
+  if (schema.const !== undefined && !isAIJSONValue(schema.const)) return false
+  for (const annotation of ['default', 'examples'] as const) {
+    if (schema[annotation] !== undefined && !isAIJSONValue(schema[annotation])) return false
+  }
+
+  for (const integerKeyword of ['minItems', 'maxItems', 'minLength', 'maxLength'] as const) {
+    const value = schema[integerKeyword]
+    if (value !== undefined && (!Number.isSafeInteger(value) || (value as number) < 0)) return false
+  }
+  for (const numberKeyword of [
+    'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
+  ] as const) {
+    const value = schema[numberKeyword]
+    if (value !== undefined && (!Number.isFinite(value) || (numberKeyword === 'multipleOf' && (value as number) <= 0))) {
+      return false
+    }
+  }
+  if (schema.pattern !== undefined) {
+    if (typeof schema.pattern !== 'string') return false
+    try { new RegExp(schema.pattern, 'u') } catch { return false }
+  }
+  return true
+}
+
+function matchesJSONType(value: unknown, type: string): boolean {
+  switch (type) {
+    case 'null': return value === null
+    case 'object': return isRecord(value)
+    case 'array': return Array.isArray(value)
+    case 'string': return typeof value === 'string'
+    case 'number': return typeof value === 'number' && Number.isFinite(value)
+    case 'integer': return typeof value === 'number' && Number.isSafeInteger(value)
+    case 'boolean': return typeof value === 'boolean'
+    default: return false
+  }
+}
+
+function resolveLocalRef(root: unknown, ref: string): unknown {
+  if (ref === '#') return root
+  if (!ref.startsWith('#/')) return undefined
+  let current: unknown = root
+  for (const segment of ref.slice(2).split('/')) {
+    if (!isRecord(current)) return undefined
+    const key = segment.replaceAll('~1', '/').replaceAll('~0', '~')
+    if (!Object.hasOwn(current, key)) return undefined
+    current = current[key]
+  }
+  return current
+}
+
+function jsonEquals(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((value, index) => jsonEquals(value, right[index]))
+  }
+  if (isRecord(left) && isRecord(right)) {
+    const leftKeys = Object.keys(left)
+    const rightKeys = Object.keys(right)
+    return leftKeys.length === rightKeys.length
+      && leftKeys.every(key => Object.hasOwn(right, key) && jsonEquals(left[key], right[key]))
+  }
+  return false
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value === 'string' && value.trim().length === 0) return undefined
+  return requiredString(value)
+}
+
+function requiredString(value: unknown): string {
+  if (typeof value !== 'string' || value.trim().length === 0) invalidConfig()
+  return value.trim()
+}
+
+function validName(value: string): boolean {
+  return value.length > 0 && value.length <= 128 && !/\s/.test(value)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function invalidConfig(): never {
+  throw new AIError({
+    code: 'invalid_config',
+    message: 'AI configuration is invalid',
+  })
+}
+
+function invalidResponse(): never {
+  throw new AIError({
+    code: 'invalid_response',
+    message: 'AI provider returned an invalid structured response',
+    operation: 'object',
+  })
+}