@viveka10/cap-ai-token-optimizer 0.0.0-stage → 0.1.1

package/lib/exporters/db.js

@@ -0,0 +1,169 @@
+'use strict'
+/**
+ * Database exporter (`db`, alias `hana`): writes one TokenUsageLog row per call through
+ * CAP's database service, so it works with SAP HANA, SQLite and PostgreSQL.
+ *
+ * - Rows are buffered and inserted in batches on the flush interval, when a batch is full,
+ *   and on shutdown. Each tenant's rows go to that tenant's container (cds.tx with the tenant).
+ * - The queue is capped; when full, the oldest rows are dropped and counted. Failed inserts
+ *   are kept for the next flush (up to the cap).
+ * - Rows older than `retentionDays` are deleted at most once a day per tenant (0 keeps all).
+ * - Only metrics are stored, never prompt or completion text (even with captureContent).
+ *
+ * Never throws into the caller.
+ */
+const log = require('../util/log')
+const { getCds } = require('../util/cds')
+
+const ENTITY = 'cap.ai.token_optimizer.TokenUsageLog'
+const DAY = 24 * 60 * 60 * 1000
+const DEFAULTS = { batchSize: 50, maxQueueSize: 10000, retentionDays: 30 }
+
+const int = (v) => (Number.isFinite(v) ? Math.round(v) : null)
+const str = (v, max) => (v == null ? null : String(v).slice(0, max))
+
+/** Map a call event to a TokenUsageLog row. */
+function toRow (e) {
+  return {
+    ID: e.id,
+    timestamp: e.timestamp,
+    tenant: str(e.tenant, 255),
+    userHash: e.user ?? null,
+    cdsService: str(e.cdsService, 255),
+    useCase: str(e.useCase, 255),
+    mode: e.mode,
+    model: str(e.model, 255),
+    deploymentId: str(e.deploymentId, 255),
+    resourceGroup: str(e.resourceGroup, 255),
+    sdk: e.sdk ?? null,
+    operation: e.operation ?? null,
+    requestId: str(e.requestId, 255),
+    finishReason: str(e.finishReason, 50),
+    promptEstimatedBefore: int(e.tokens?.promptEstimatedBefore),
+    promptEstimatedAfter: int(e.tokens?.promptEstimatedAfter),
+    promptTokens: int(e.tokens?.prompt),
+    completionTokens: int(e.tokens?.completion),
+    totalTokens: int(e.tokens?.total),
+    cachedTokens: int(e.tokens?.cached),
+    savedTokensEstimate: int(e.savings?.estimatedTokens),
+    savingsByStep: JSON.stringify(e.savings?.byStep ?? {}),
+    cacheHit: !!e.savings?.cacheHit,
+    promptPrefixChanged: !!e.advisory?.promptPrefixChanged,
+    costEstimate: e.costEstimate ?? null,
+    latencyMs: int(e.latencyMs),
+    retries: int(e.retries) ?? 0,
+    status: e.status,
+    errorCategory: e.error?.category ?? null,
+    errorHttpStatus: int(e.error?.httpStatus),
+    errorCode: str(e.error?.code, 100),
+    errorMessage: str(e.error?.message, 300),
+    promptHash: e.promptHash ?? null,
+    promptLength: int(e.promptLength)
+  }
+}
+
+/**
+ * @param {object} [cfg] metrics.db config
+ * @param {{ cds?: any, now?: () => number }} [deps]
+ * @returns {import('../../index').Exporter}
+ */
+function createDbExporter (cfg = {}, deps = {}) {
+  const opts = { ...DEFAULTS, ...cfg }
+  const now = deps.now ?? Date.now
+  const queue = []
+  const counters = { written: 0, dropped: 0, failedWrites: 0, deleted: 0 }
+  const lastCleanup = new Map()
+  let flushing = null
+  let db = null
+  let unavailable = false
+
+  const cds = () => deps.cds ?? getCds()
+
+  async function connect () {
+    if (db) return db
+    const c = cds()
+    if (!c) throw new Error('@sap/cds is not loaded')
+    db = await c.connect.to('db')
+    if (!db.model?.definitions?.[ENTITY] && !c.model?.definitions?.[ENTITY]) {
+      throw new Error(`entity ${ENTITY} is not in the model (is the @viveka10/cap-ai-token-optimizer plugin loaded?)`)
+    }
+    return db
+  }
+
+  function enqueue (rows, front = false) {
+    if (front) queue.unshift(...rows)
+    else queue.push(...rows)
+    const over = queue.length - opts.maxQueueSize
+    if (over > 0) {
+      queue.splice(0, over)
+      counters.dropped += over
+    }
+  }
+
+  async function writeTenant (service, tenant, rows) {
+    const c = cds()
+    const ctx = { tenant: tenant ?? undefined, user: new c.User.Privileged() }
+    await service.tx(ctx, async (tx) => {
+      await tx.run(c.ql.INSERT.into(ENTITY).entries(rows))
+      const key = tenant ?? ''
+      if (opts.retentionDays > 0 && !(now() - (lastCleanup.get(key) ?? 0) < DAY)) {
+        lastCleanup.set(key, now())
+        const cutoff = new Date(now() - opts.retentionDays * DAY).toISOString()
+        const n = await tx.run(c.ql.DELETE.from(ENTITY).where({ timestamp: { '<': cutoff } }))
+        counters.deleted += Number(n) || 0
+      }
+    })
+  }
+
+  async function drain () {
+    if (!queue.length || unavailable) return
+    let service
+    try {
+      service = await connect()
+    } catch (e) {
+      unavailable = true
+      counters.dropped += queue.length
+      queue.length = 0
+      log.warn('db exporter disabled:', e?.message)
+      return
+    }
+    const rows = queue.splice(0, queue.length)
+    const byTenant = new Map()
+    for (const r of rows) {
+      if (!byTenant.has(r.tenant)) byTenant.set(r.tenant, [])
+      byTenant.get(r.tenant).push(r)
+    }
+    for (const [tenant, tenantRows] of byTenant) {
+      try {
+        await writeTenant(service, tenant, tenantRows)
+        counters.written += tenantRows.length
+      } catch (e) {
+        counters.failedWrites++
+        enqueue(tenantRows, true)
+        log.warn(`db exporter: could not write ${tenantRows.length} row(s):`, e?.message)
+      }
+    }
+  }
+
+  function flush () {
+    flushing ??= drain().catch(e => log.warn('db exporter flush failed:', e?.message)).finally(() => { flushing = null })
+    return flushing
+  }
+
+  return {
+    name: 'db',
+    export (event) {
+      if (unavailable) { counters.dropped++; return }
+      enqueue([toRow(event)])
+      if (queue.length >= opts.batchSize) flush()
+    },
+    flush,
+    async shutdown () {
+      await flushing
+      await flush()
+    },
+    stats: () => ({ queued: queue.length, ...counters })
+  }
+}
+
+module.exports = { createDbExporter, toRow, ENTITY, DEFAULTS }

package/lib/exporters/http.js

@@ -0,0 +1,143 @@
+'use strict'
+/**
+ * HTTP exporter: POSTs batches of events as JSON `{ "events": [...] }` to a URL or a BTP destination.
+ *
+ * - Events are queued; the queue is capped (`maxQueueSize`). When full, the oldest events are
+ *   dropped and counted.
+ * - Flushes on the collector's interval, when a batch is full, and on shutdown.
+ * - Retries 429, 5xx and network errors with exponential backoff (honours Retry-After);
+ *   other 4xx responses drop the batch. A batch that still fails goes back to the front of the
+ *   queue, so a short outage loses nothing (up to the queue cap).
+ * - Destinations are resolved with @sap-cloud-sdk/connectivity (present with @sap-ai-sdk) and
+ *   cached for `destinationCacheMs`. Only Internet destinations are supported.
+ *
+ * Never throws into the caller.
+ */
+const log = require('../util/log')
+const { loadPeer } = require('../util/peer')
+const { parseRetryAfter } = require('../metrics/classifier')
+
+const DEFAULTS = {
+  url: '',
+  destination: '',
+  headers: {},
+  batchSize: 100,
+  maxQueueSize: 10000,
+  maxRetries: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 30000,
+  timeoutMs: 10000,
+  destinationCacheMs: 5 * 60 * 1000
+}
+
+/**
+ * @param {object} cfg metrics.http config
+ * @param {{ fetch?: typeof fetch, sleep?: (ms: number) => Promise<void>, connectivity?: object, now?: () => number }} [deps]
+ * @returns {import('../../index').Exporter}
+ */
+function createHttpExporter (cfg = {}, deps = {}) {
+  const opts = { ...DEFAULTS, ...cfg, headers: { ...cfg.headers } }
+  if (!opts.url && !opts.destination) throw new Error('metrics.http needs a "url" or a "destination"')
+  const doFetch = deps.fetch ?? globalThis.fetch
+  const sleep = deps.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)))
+  const now = deps.now ?? Date.now
+
+  const queue = []
+  const counters = { sent: 0, dropped: 0, failedAttempts: 0, rejectedBatches: 0 }
+  let flushing = null
+  let resolved = null // { url, headers, expires }
+  let closed = false
+
+  async function target () {
+    if (opts.url) return { url: opts.url, headers: {} }
+    if (resolved && resolved.expires > now()) return resolved
+    const connectivity = deps.connectivity ?? loadPeer('@sap-cloud-sdk/connectivity', 'the http exporter with a destination')
+    const destination = await connectivity.getDestination({ destinationName: opts.destination, useCache: true })
+    if (!destination?.url) throw new Error(`destination "${opts.destination}" not found or has no URL`)
+    const headers = await connectivity.buildHeadersForDestination(destination)
+    resolved = { url: destination.url, headers, expires: now() + opts.destinationCacheMs }
+    return resolved
+  }
+
+  /** POST one batch. Returns true when sent, false when it should be kept for later. */
+  async function send (batch) {
+    for (let attempt = 0; ; attempt++) {
+      let retryAfter = null
+      try {
+        const t = await target()
+        const res = await doFetch(t.url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', ...t.headers, ...opts.headers },
+          body: JSON.stringify({ events: batch }),
+          signal: AbortSignal.timeout(opts.timeoutMs)
+        })
+        if (res.ok) {
+          counters.sent += batch.length
+          return true
+        }
+        if (res.status === 401 || res.status === 403) resolved = null // token may have expired
+        if (res.status !== 429 && res.status < 500 && res.status !== 401) {
+          counters.rejectedBatches++
+          log.warn(`http exporter: batch of ${batch.length} rejected with HTTP ${res.status}, dropped`)
+          counters.dropped += batch.length
+          return true
+        }
+        retryAfter = parseRetryAfter(res.headers?.get?.('retry-after'), now())
+        counters.failedAttempts++
+        log.debug(`http exporter: HTTP ${res.status} (attempt ${attempt + 1})`)
+      } catch (e) {
+        counters.failedAttempts++
+        log.debug(`http exporter: ${e?.message} (attempt ${attempt + 1})`)
+        if (attempt >= opts.maxRetries) log.warn('http exporter: could not send events:', e?.message)
+      }
+      if (attempt >= opts.maxRetries) return false
+      const backoff = opts.baseDelayMs * 2 ** attempt
+      await sleep(Math.min(opts.maxDelayMs, retryAfter ?? Math.round(backoff / 2 + Math.random() * backoff / 2)))
+    }
+  }
+
+  function enqueue (events, front = false) {
+    if (front) queue.unshift(...events)
+    else queue.push(...events)
+    const over = queue.length - opts.maxQueueSize
+    if (over > 0) {
+      // drop the oldest
+      queue.splice(0, over)
+      counters.dropped += over
+    }
+  }
+
+  async function drain () {
+    while (queue.length) {
+      const batch = queue.splice(0, opts.batchSize)
+      const ok = await send(batch)
+      if (!ok) {
+        enqueue(batch, true)
+        return
+      }
+    }
+  }
+
+  function flush () {
+    flushing ??= drain().catch(e => log.warn('http exporter flush failed:', e?.message)).finally(() => { flushing = null })
+    return flushing
+  }
+
+  return {
+    name: 'http',
+    export (event) {
+      if (closed) return
+      enqueue([event])
+      if (queue.length >= opts.batchSize) flush()
+    },
+    flush,
+    async shutdown () {
+      await flushing
+      await flush()
+      closed = true
+    },
+    stats: () => ({ queued: queue.length, ...counters })
+  }
+}
+
+module.exports = { createHttpExporter, DEFAULTS }

package/lib/exporters/index.js

@@ -0,0 +1,42 @@
+'use strict'
+const log = require('../util/log')
+const { createConsoleExporter } = require('./console')
+const { createHttpExporter } = require('./http')
+const { createOtelExporter } = require('./otel')
+const { createDbExporter } = require('./db')
+
+/** Built-in exporter factories. */
+const FACTORIES = {
+  console: (cfg, deps) => createConsoleExporter(deps.console),
+  http: (cfg, deps) => createHttpExporter(cfg.metrics.http, deps.http),
+  otel: (cfg, deps) => createOtelExporter(cfg.metrics.otel, deps.otel),
+  db: (cfg, deps) => createDbExporter(cfg.metrics.db, deps.db)
+}
+// `hana` is the name used in the docs for the database exporter
+FACTORIES.hana = FACTORIES.db
+
+/**
+ * Create exporters listed in `cfg.metrics.exporters`. Entries may be names of built-ins
+ * or exporter objects. Unknown names are skipped with a warning.
+ * @param {object} cfg resolved config
+ * @param {object} [deps] injectable dependencies for tests
+ */
+function createExporters (cfg, deps = {}) {
+  const out = []
+  const entries = [...(cfg.metrics?.exporters ?? [])]
+  // `metrics.otel.enabled: true` is a shortcut for listing 'otel'
+  if (cfg.metrics?.otel?.enabled && !entries.includes('otel')) entries.push('otel')
+  for (const entry of entries) {
+    if (entry && typeof entry === 'object' && typeof entry.export === 'function') { out.push(entry); continue }
+    const factory = FACTORIES[entry]
+    if (!factory) { log.warn(`Unknown metrics exporter '${entry}' — skipped`); continue }
+    try {
+      out.push(factory(cfg, deps))
+    } catch (e) {
+      log.warn(`Could not create exporter '${entry}':`, e?.message)
+    }
+  }
+  return out
+}
+
+module.exports = { createExporters, FACTORIES }

package/lib/exporters/otel.js

@@ -0,0 +1,126 @@
+'use strict'
+/**
+ * OpenTelemetry exporter (SAP Cloud ALM, Dynatrace, any OTLP backend).
+ *
+ * Uses only @opentelemetry/api and the globally registered providers. It never creates an
+ * SDK or providers itself: install @cap-js/telemetry (or the SAP Cloud ALM agent) to set them
+ * up and choose where data goes. Without registered providers, everything is a no-op.
+ *
+ * Emits per call:
+ *  - metrics: gen_ai.client.token.usage and gen_ai.client.operation.duration (OpenTelemetry
+ *    GenAI semantic conventions), plus cap_ai_optimizer.calls / .errors / .tokens.saved /
+ *    .cache.hits / .cost
+ *  - one span `chat <model>` (kind CLIENT) with token, savings and error attributes, as a child
+ *    of the active span (e.g. the CAP request span). Prompt and completion text are never added.
+ *
+ * Instruments are created on the first event, not at startup: meters taken before
+ * @cap-js/telemetry registers its MeterProvider would stay no-ops.
+ */
+const log = require('../util/log')
+const { loadPeer } = require('../util/peer')
+
+const { name: SCOPE, version: VERSION } = require('../../package.json')
+const PROVIDER = 'sap.ai_core'
+
+/**
+ * @param {{ tenantAttribute?: boolean }} [cfg] metrics.otel config
+ * @param {{ api?: object }} [deps]
+ * @returns {import('../../index').Exporter}
+ */
+function createOtelExporter (cfg = {}, deps = {}) {
+  const api = deps.api ?? loadPeer('@opentelemetry/api', 'the otel exporter')
+  const tenantAttribute = cfg.tenantAttribute !== false
+  let instruments = null
+
+  function init () {
+    const meterProvider = api.metrics.getMeterProvider()
+    if (meterProvider?.constructor?.name === 'NoopMeterProvider') {
+      log.warn('otel exporter: no OpenTelemetry MeterProvider is registered, metrics are not exported. Install @cap-js/telemetry.')
+    }
+    const meter = api.metrics.getMeter(SCOPE, VERSION)
+    instruments = {
+      tracer: api.trace.getTracer(SCOPE, VERSION),
+      tokenUsage: meter.createHistogram('gen_ai.client.token.usage', { unit: '{token}', description: 'Tokens used per AI Core call' }),
+      duration: meter.createHistogram('gen_ai.client.operation.duration', { unit: 's', description: 'Duration of AI Core calls' }),
+      calls: meter.createCounter('cap_ai_optimizer.calls', { unit: '{call}', description: 'AI Core calls' }),
+      errors: meter.createCounter('cap_ai_optimizer.errors', { unit: '{call}', description: 'Failed AI Core calls by category' }),
+      saved: meter.createCounter('cap_ai_optimizer.tokens.saved', { unit: '{token}', description: 'Estimated tokens saved, by optimization step' }),
+      cacheHits: meter.createCounter('cap_ai_optimizer.cache.hits', { unit: '{call}', description: 'Calls answered from the response cache' }),
+      cost: meter.createCounter('cap_ai_optimizer.cost', { description: 'Estimated cost, in the currency of the configured prices' }),
+      prefixChanges: meter.createCounter('cap_ai_optimizer.prompt_cache.prefix_changes', { unit: '{call}', description: 'Calls whose system prompt or tools changed for the same use case and model (defeats provider prompt caching)' })
+    }
+    return instruments
+  }
+
+  function attributes (e) {
+    const a = {
+      'gen_ai.operation.name': e.operation ?? 'chat',
+      'gen_ai.provider.name': PROVIDER,
+      'cap_ai_optimizer.use_case': e.useCase,
+      'cap_ai_optimizer.mode': e.mode,
+      'cap_ai_optimizer.sdk': e.sdk ?? 'unknown'
+    }
+    if (e.model) a['gen_ai.request.model'] = e.model
+    if (tenantAttribute && e.tenant) a['sap.tenancy.tenant_id'] = e.tenant
+    if (e.status === 'error') a['error.type'] = e.error?.category ?? 'UNKNOWN'
+    return a
+  }
+
+  function recordMetrics (i, e, attrs) {
+    if (Number.isFinite(e.latencyMs)) i.duration.record(e.latencyMs / 1000, attrs)
+    if (Number.isFinite(e.tokens?.prompt)) i.tokenUsage.record(e.tokens.prompt, { ...attrs, 'gen_ai.token.type': 'input' })
+    if (Number.isFinite(e.tokens?.completion)) i.tokenUsage.record(e.tokens.completion, { ...attrs, 'gen_ai.token.type': 'output' })
+    i.calls.add(1, attrs)
+    if (e.status === 'error') i.errors.add(1, attrs)
+    if (e.savings?.cacheHit) i.cacheHits.add(1, attrs)
+    for (const [step, saved] of Object.entries(e.savings?.byStep ?? {})) {
+      if (saved > 0) i.saved.add(saved, { ...attrs, 'cap_ai_optimizer.step': step })
+    }
+    if (e.costEstimate > 0) i.cost.add(e.costEstimate, attrs)
+    if (e.advisory?.promptPrefixChanged) {
+      i.prefixChanges.add(1, { ...attrs, 'cap_ai_optimizer.prefix_part': e.advisory.changed.join(','), 'cap_ai_optimizer.caused_by_optimizer': !!e.advisory.causedByOptimizer })
+    }
+  }
+
+  function recordSpan (i, e, attrs) {
+    const end = Date.parse(e.timestamp)
+    const endTime = Number.isFinite(end) ? end : Date.now()
+    const startTime = endTime - (Number.isFinite(e.latencyMs) ? e.latencyMs : 0)
+    const spanAttrs = { ...attrs }
+    const set = (k, v) => { if (v !== null && v !== undefined) spanAttrs[k] = v }
+    set('gen_ai.usage.input_tokens', e.tokens?.prompt)
+    set('gen_ai.usage.output_tokens', e.tokens?.completion)
+    if (e.finishReason) spanAttrs['gen_ai.response.finish_reasons'] = [e.finishReason]
+    set('sap.ai_core.request_id', e.requestId)
+    set('sap.ai_core.deployment_id', e.deploymentId)
+    set('sap.ai_core.resource_group', e.resourceGroup)
+    set('cap_ai_optimizer.event_id', e.id)
+    set('cap_ai_optimizer.tokens.prompt_estimated_before', e.tokens?.promptEstimatedBefore)
+    set('cap_ai_optimizer.tokens.prompt_estimated_after', e.tokens?.promptEstimatedAfter)
+    set('cap_ai_optimizer.tokens.cached', e.tokens?.cached)
+    set('cap_ai_optimizer.savings.estimated_tokens', e.savings?.estimatedTokens)
+    set('cap_ai_optimizer.cache_hit', e.savings?.cacheHit)
+    set('cap_ai_optimizer.retries', e.retries)
+    set('cap_ai_optimizer.cost_estimate', e.costEstimate)
+    set('cap_ai_optimizer.prompt_prefix_changed', e.advisory?.promptPrefixChanged)
+    if (e.status === 'error') set('http.response.status_code', e.error?.httpStatus)
+
+    const span = i.tracer.startSpan(`${e.operation ?? 'chat'}${e.model ? ` ${e.model}` : ''}`, { kind: api.SpanKind.CLIENT, startTime, attributes: spanAttrs }, api.context.active())
+    if (e.status === 'error') span.setStatus({ code: api.SpanStatusCode.ERROR, message: e.error?.category })
+    span.end(endTime)
+  }
+
+  return {
+    name: 'otel',
+    export (event) {
+      const i = instruments ?? init()
+      const attrs = attributes(event)
+      recordMetrics(i, event, attrs)
+      recordSpan(i, event, attrs)
+    },
+    flush () {},
+    shutdown () {}
+  }
+}
+
+module.exports = { createOtelExporter }

package/lib/metrics/classifier.js

@@ -0,0 +1,175 @@
+'use strict'
+/**
+ * Failure classifier — pure function, no I/O.
+ *
+ * @sap-ai-sdk 2.x throws `ErrorWithCause("Request failed with status code N.")` whose `.cause`
+ * is an AxiosError carrying `status`, `code`, `response.headers` and `response.data`
+ * (orchestration: `{ error: { code, message, location } }`, Azure OpenAI: `{ error: { code, message, innererror } }`).
+ * Deployment-resolution and OAuth failures wrap further levels of `cause`. We therefore walk the
+ * whole cause chain (and AggregateError.errors) and collect every signal before deciding.
+ */
+
+const CATEGORIES = Object.freeze([
+  'RATE_LIMIT', 'CONTENT_FILTER', 'CONTEXT_LENGTH', 'TIMEOUT', 'AUTH',
+  'DEPLOYMENT_NOT_FOUND', 'SERVER', 'NETWORK', 'UNKNOWN'
+])
+
+const MAX_MESSAGE_LENGTH = 300
+const MAX_DEPTH = 8
+
+const RE_CONTENT_FILTER = /content[_ ]?filter|ResponsibleAIPolicyViolation|filtering module|filtered due to safety|content management policy|content_policy_violation/i
+const RE_CONTEXT_LENGTH = /context_length_exceeded|maximum context length|context window|prompt is too long|input is too long|too many tokens|exceeds? the (maximum|max) (number of )?tokens|string_above_max_length/i
+const RE_RATE_LIMIT = /rate[ _-]?limit|too many requests|quota exceeded/i
+const RE_TIMEOUT = /timeout of \d+ms exceeded|timed? ?out|deadline exceeded/i
+const RE_DEPLOYMENT = /no deployment matched|deployment not found|DeploymentNotFound|has no deployment url/i
+const RE_AUTH = /unauthori[sz]ed|forbidden|invalid[_ ]client|could not fetch client credentials token/i
+const RE_NETWORK = /socket hang up|network error|fetch failed|getaddrinfo|connect ECONN/i
+
+const TIMEOUT_CODES = new Set(['ECONNABORTED', 'ETIMEDOUT', 'ESOCKETTIMEDOUT', 'ERR_TIMEOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT'])
+const NETWORK_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'EPIPE', 'EHOSTUNREACH', 'ENETUNREACH', 'ENETDOWN', 'ERR_NETWORK', 'UND_ERR_SOCKET'])
+
+/**
+ * @typedef {object} ClassifiedError
+ * @property {string} category one of CATEGORIES
+ * @property {number|null} httpStatus
+ * @property {string|null} code provider or system error code
+ * @property {string} message truncated, never contains request content from us
+ * @property {number|null} retryAfterMs parsed Retry-After header, if present
+ */
+
+/**
+ * @param {unknown} err
+ * @param {{ now?: number }} [opts] `now` makes HTTP-date Retry-After parsing deterministic in tests
+ * @returns {ClassifiedError}
+ */
+function classifyError (err, { now = Date.now() } = {}) {
+  const s = collectSignals(err)
+  const status = s.statuses[0] ?? null
+  const hasStatus = (pred) => s.statuses.some(pred)
+  const text = s.texts.join(' | ')
+  const codesText = s.codes.join(' ')
+
+  let category = 'UNKNOWN'
+  // Content-related 400s first — they are the most specific signals.
+  if (RE_CONTENT_FILTER.test(codesText) || RE_CONTENT_FILTER.test(text) || s.locations.some(l => /filter/i.test(l))) {
+    category = 'CONTENT_FILTER'
+  } else if (RE_CONTEXT_LENGTH.test(codesText) || RE_CONTEXT_LENGTH.test(text) || hasStatus(x => x === 413)) {
+    category = 'CONTEXT_LENGTH'
+  } else if (hasStatus(x => x === 429) || RE_RATE_LIMIT.test(text)) {
+    category = 'RATE_LIMIT'
+  } else if (hasStatus(x => x === 401 || x === 403)) {
+    category = 'AUTH'
+  } else if (hasStatus(x => x === 404) || RE_DEPLOYMENT.test(text) || RE_DEPLOYMENT.test(codesText)) {
+    category = 'DEPLOYMENT_NOT_FOUND'
+  } else if (hasStatus(x => x === 408 || x === 504) || s.codes.some(c => TIMEOUT_CODES.has(c)) ||
+    s.names.some(n => n === 'TimeoutError') || RE_TIMEOUT.test(text)) {
+    category = 'TIMEOUT'
+  } else if (hasStatus(x => x >= 500 && x <= 599)) {
+    category = 'SERVER'
+  } else if (s.codes.some(c => NETWORK_CODES.has(c)) || RE_NETWORK.test(text)) {
+    category = 'NETWORK'
+  } else if (RE_AUTH.test(text)) {
+    category = 'AUTH'
+  }
+
+  return {
+    category,
+    httpStatus: status,
+    code: s.providerCodes[0] ?? s.codes[0] ?? null,
+    message: truncate(s.providerMessages[0] ?? s.texts.find(Boolean) ?? String(err ?? 'Unknown error')),
+    retryAfterMs: parseRetryAfter(s.retryAfter, now)
+  }
+}
+
+function collectSignals (root) {
+  const s = { statuses: [], codes: [], providerCodes: [], texts: [], providerMessages: [], locations: [], names: [], retryAfter: null }
+  const seen = new Set()
+  const queue = [{ e: root, depth: 0 }]
+  while (queue.length) {
+    const { e, depth } = queue.shift()
+    if (e == null || depth > MAX_DEPTH || seen.has(e)) continue
+    if (typeof e !== 'object' && typeof e !== 'function') { s.texts.push(String(e)); continue }
+    seen.add(e)
+
+    pushNum(s.statuses, e.status, e.statusCode, e.httpStatus, e.response?.status)
+    if (typeof e.code === 'string' && e.code) s.codes.push(e.code)
+    if (typeof e.name === 'string') s.names.push(e.name)
+    if (typeof e.message === 'string' && e.message) s.texts.push(e.message)
+    s.retryAfter ??= header(e.response?.headers, 'retry-after') ?? header(e.headers, 'retry-after')
+
+    const body = parseBody(e.response?.data ?? e.body)
+    const errors = providerErrors(body)
+    // a non-JSON body (e.g. a gateway's "Payload Too Large") is the most useful message we have
+    if (!errors.length && typeof body?.message === 'string' && body.message) {
+      s.providerMessages.push(body.message)
+      s.texts.push(body.message)
+    }
+    for (const pe of errors) {
+      if (pe.code != null) {
+        const code = String(pe.code)
+        s.providerCodes.push(code)
+        s.codes.push(code)
+        if (/^\d{3}$/.test(code)) pushNum(s.statuses, Number(code))
+      }
+      if (pe.innererror?.code) s.codes.push(String(pe.innererror.code))
+      if (typeof pe.message === 'string') { s.providerMessages.push(pe.message); s.texts.push(pe.message) }
+      if (typeof pe.location === 'string') s.locations.push(pe.location)
+    }
+    if (typeof body?.error_description === 'string') s.texts.push(body.error_description)
+
+    queue.push({ e: e.cause, depth: depth + 1 })
+    if (Array.isArray(e.errors)) for (const x of e.errors) queue.push({ e: x, depth: depth + 1 })
+  }
+  return s
+}
+
+function providerErrors (body) {
+  if (!body || typeof body !== 'object') return []
+  const err = body.error
+  if (Array.isArray(err)) return err.filter(x => x && typeof x === 'object')
+  if (err && typeof err === 'object') return [err]
+  if (typeof body.code !== 'undefined' && typeof body.message === 'string') return [body]
+  return []
+}
+
+function parseBody (data) {
+  if (typeof data === 'string') {
+    try { return JSON.parse(data) } catch { return { message: data } }
+  }
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(data)) return parseBody(data.toString('utf8'))
+  return data
+}
+
+function header (headers, name) {
+  if (!headers) return null
+  if (typeof headers.get === 'function') return headers.get(name) ?? null
+  const key = Object.keys(headers).find(k => k.toLowerCase() === name)
+  return key ? headers[key] : null
+}
+
+function pushNum (arr, ...values) {
+  for (const v of values) {
+    const n = typeof v === 'string' ? Number(v) : v
+    if (Number.isInteger(n) && n >= 100 && n <= 599 && !arr.includes(n)) arr.push(n)
+  }
+}
+
+/**
+ * @param {string|number|null} value seconds or HTTP-date
+ * @param {number} now
+ * @returns {number|null} milliseconds
+ */
+function parseRetryAfter (value, now) {
+  if (value == null || value === '') return null
+  const secs = Number(value)
+  if (Number.isFinite(secs)) return Math.max(0, Math.round(secs * 1000))
+  const at = Date.parse(String(value))
+  return Number.isFinite(at) ? Math.max(0, at - now) : null
+}
+
+function truncate (msg) {
+  const str = String(msg)
+  return str.length > MAX_MESSAGE_LENGTH ? `${str.slice(0, MAX_MESSAGE_LENGTH - 1)}…` : str
+}
+
+module.exports = { classifyError, parseRetryAfter, CATEGORIES }