mohdel 0.90.0

package/js/factory/bridge.js

@@ -0,0 +1,372 @@
+/**
+ * Factory bridge — in-process path from the `mohdel()` factory API
+ * to the `/session` runtime.
+ *
+ * The factory surface is `mohdel().use(model).answer(prompt, options)`
+ * returning a `Promise<AnswerResult>`. This module takes those
+ * call arguments, builds a `CallEnvelope` (the wire shape
+ * documented in `PROTOCOL.md`), drives `run()` / `runImage()`
+ * in `js/session/`, and collapses the event stream back into a
+ * single result object.
+ *
+ * The bridge is what the `mo` CLI, library consumers doing
+ * `import mohdel from 'mohdel'`, and test harnesses all sit on top
+ * of. It's **in-process only** — `thin-gate` is not spawned. For
+ * the subprocess path use `mohdel/client` directly.
+ *
+ * Adapter error events are rethrown as `MohdelError` so caller
+ * catch blocks see a thrown exception rather than an event.
+ *
+ * @module factory/bridge
+ */
+
+import { run } from '../session/run.js'
+import { runImage } from '../session/run_image.js'
+import { MohdelError, Severity } from '../../src/lib/errors.js'
+import { createRealtimeDeltaBuffer } from '../../src/lib/utils.js'
+
+/**
+ * @typedef {object} BridgeDeps
+ * @property {object} [cooldown]  Cooldown tracker injected into run().
+ * @property {object} [limiter]   Rate limiter injected into run().
+ * @property {(provider: string) => any} [resolveProviderLimits]
+ *   Hook that returns `{rpmLimit, tpmLimit}` for a given provider —
+ *   lets the factory keep its own `providersConfig` as source of
+ *   truth instead of the module-level `providers.json` loader.
+ * @property {AbortSignal} [signal]
+ */
+
+/**
+ * Run `answer()` through the /session runtime.
+ *
+ * ## Option mapping
+ *
+ * Every factory `answer()` option is either mapped onto the envelope
+ * or intentionally ignored. Ignored options are listed explicitly —
+ * audit any "missing option" report against this table first.
+ *
+ * | factory option                                    | envelope destination                                 |
+ * |---------------------------------------------------|------------------------------------------------------|
+ * | `outputBudget`/`outputType`/`outputStyle`/`outputEffort` | flat fields on envelope                       |
+ * | `images` / `videos` / `cache`                     | flat fields on envelope                              |
+ * | `tools` / `toolChoice` / `parallelToolCalls`      | flat fields on envelope                              |
+ * | `identifier`                                      | envelope.identifier (adapter maps to provider field) |
+ * | `realtimeHandler` / `bufferOpts`                  | drained via createRealtimeDeltaBuffer                |
+ * | `providerOrder` / `providerAllow` / `providerDeny`| envelope.providerOptions.openrouter                  |
+ * | `traceparent` / `baggage`                         | envelope transport metadata                          |
+ * | `callId` / `authId`                               | envelope transport metadata                          |
+ * | `configuration.apiKey`                            | envelope.auth.key                                    |
+ * | **`parentSpan`**                                  | **dropped** — use `traceparent` instead              |
+ * | **`maybeThrowHandler`**                           | **dropped** — no factory-side validation hook        |
+ * | **`configuration.baseURL` / `defaultHeaders` / …**| **rejected** — adapters own baseURL (F24)            |
+ *
+ * @param {object} args
+ * @param {string} args.provider      Resolved provider name (e.g. 'openai').
+ * @param {string} args.model         Provider-native model id (no provider prefix).
+ * @param {string} args.modelKey      Catalog key `<provider>/<model>` — for spec/pricing.
+ * @param {any} args.configuration    Provider config. Only `apiKey` is threaded; other fields are rejected (F24).
+ * @param {string | any[] | {system?: any, messages: any[]}} args.prompt
+ * @param {any} [args.options]        Factory `answer()` options.
+ * @param {BridgeDeps} [deps]
+ * @returns {Promise<any>}            AnswerResult (matches the factory's return shape).
+ */
+export async function runAnswer ({ provider, model, modelKey, configuration, prompt, options = {} }, deps = {}) {
+  const envelope = toEnvelope({ provider, model, configuration, prompt, options })
+
+  // If the caller passed a `realtimeHandler`, feed every `delta`
+  // event into a buffer that invokes the handler on batches matching
+  // `bufferOpts` cadence. Without this, streaming callbacks silently
+  // never fire — `mo ask --stream` and any integration that relies
+  // on streaming callbacks stops working.
+  //
+  // F54: skip the buffer allocation entirely when no handler was
+  // supplied — the common case.
+  const deltaBuffer = options.realtimeHandler
+    ? createRealtimeDeltaBuffer(options.realtimeHandler, options.bufferOpts)
+    : null
+
+  let terminal
+  try {
+    for await (const ev of run(envelope, deps)) {
+      if (ev.type === 'delta' && ev.delta) {
+        if (deltaBuffer) deltaBuffer.push(ev.delta.type, ev.delta.delta)
+      } else if (ev.type === 'done' || ev.type === 'error') {
+        terminal = ev
+        break
+      }
+    }
+  } finally {
+    // Flush any pending buffered content regardless of terminal
+    // path (success, error, or exception) so the handler sees the
+    // tail of the stream.
+    deltaBuffer?.flush()
+  }
+
+  if (!terminal) {
+    throw new MohdelError('SESSION_NO_TERMINAL', {
+      severity: Severity.ERROR,
+      detail: 'session run produced no terminal event',
+      retryable: false
+    })
+  }
+
+  if (terminal.type === 'error') {
+    throw fromTypedError(terminal.error, { provider, model, modelKey })
+  }
+
+  return terminal.result
+}
+
+/**
+ * Run an `image()` call through the /session runtime.
+ *
+ * @param {object} args
+ * @param {string} args.provider
+ * @param {string} args.model
+ * @param {any} args.configuration
+ * @param {string} args.prompt
+ * @param {any} [args.options]
+ * @param {any} [args.spec]       modelSpec passthrough so the image
+ *                                adapter picks up `imageEndpoint`,
+ *                                `imageDefaultSize`, etc. without
+ *                                re-reading the catalog.
+ * @returns {Promise<any>}
+ */
+export async function runAnswerImage ({ provider, model, configuration, prompt, options = {}, spec }) {
+  const envelope = {
+    callId: options.callId || newCallId(),
+    authId: options.authId || 'local',
+    auth: configToAuth(configuration),
+    provider,
+    model,
+    prompt
+  }
+  if (options.size) envelope.size = options.size
+  if (options.seed != null) envelope.seed = options.seed
+
+  const out = await runImage(envelope, spec ? { spec } : {})
+  if (!out.ok) throw fromTypedError(out.error, { provider, model })
+  return out.result
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.provider
+ * @param {string} args.model
+ * @param {any} args.configuration
+ * @param {string | any[] | {system?: any, messages: any[]}} args.prompt
+ * @param {any} args.options
+ * @returns {import('#core/envelope.js').CallEnvelope}
+ */
+function toEnvelope ({ provider, model, configuration, prompt, options }) {
+  /** @type {import('#core/envelope.js').CallEnvelope} */
+  const envelope = {
+    callId: options.callId || newCallId(),
+    authId: options.authId || 'local',
+    auth: configToAuth(configuration),
+    provider,
+    model,
+    prompt: toEnvelopePrompt(prompt)
+  }
+
+  if (options.traceparent) envelope.traceparent = options.traceparent
+  if (options.baggage) envelope.baggage = options.baggage
+  if (options.outputBudget !== undefined) envelope.outputBudget = options.outputBudget
+  if (options.outputType) envelope.outputType = options.outputType
+  if (options.outputStyle) envelope.outputStyle = options.outputStyle
+  if (options.outputEffort) envelope.outputEffort = options.outputEffort
+  if (options.images?.length) envelope.images = options.images
+  if (options.videos?.length) envelope.videos = options.videos
+  if (options.cache !== undefined) envelope.cache = options.cache
+  if (options.tools?.length) envelope.tools = options.tools
+  if (options.toolChoice) envelope.toolChoice = options.toolChoice
+  if (options.parallelToolCalls === false) envelope.parallelToolCalls = false
+  if (options.identifier) envelope.identifier = options.identifier
+
+  // OpenRouter routing prefs ride in their own bag to keep the flat
+  // envelope clean. The openrouter adapter reads this via
+  // `config.mutateArgs`.
+  if (options.providerOrder || options.providerAllow || options.providerDeny) {
+    envelope.providerOptions = {
+      openrouter: {
+        order: options.providerOrder,
+        allow: options.providerAllow,
+        deny: options.providerDeny
+      }
+    }
+  }
+
+  return envelope
+}
+
+/**
+ * Re-throw a TypedError as a MohdelError so factory-API caller catch
+ * blocks — which duck-type on `.detail` / `.retryable` — keep
+ * working without knowing about the session event-stream shape.
+ *
+ * @param {import('#core/errors.js').TypedError} err
+ * @param {{provider: string, model: string, modelKey?: string}} ctx
+ * @returns {MohdelError}
+ */
+function fromTypedError (err, ctx) {
+  // TypedError `message` is the machine-key label (e.g. "provider error
+  // 400"); `detail` carries the provider's own rejection text when it
+  // was safe to surface. Prefer the detail so callers see what to fix.
+  return new MohdelError(err.type || 'PROVIDER_ERROR', {
+    severity: toSeveritySymbol(err.severity),
+    detail: err.detail || err.message,
+    retryable: !!err.retryable,
+    context: { provider: ctx.provider, model: ctx.model }
+  })
+}
+
+/** @param {string | undefined} s */
+function toSeveritySymbol (s) {
+  switch (s) {
+    case 'trace': return Severity.TRACE
+    case 'debug': return Severity.DEBUG
+    case 'info': return Severity.INFO
+    case 'warn': return Severity.WARN
+    case 'error': return Severity.ERROR
+    case 'fatal': return Severity.FATAL
+    default: return Severity.ERROR
+  }
+}
+
+function newCallId () {
+  return `m86_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * Turn the factory's `configuration` bag into an envelope `auth` object.
+ * Accepts `apiKey` + `baseURL`; anything else is rejected with
+ * `CONFIGURATION_UNSUPPORTED` rather than silently dropped — otherwise
+ * a caller could believe their proxy / org header / timeout is in
+ * effect when it isn't, which in the worst case leaks auth keys and
+ * prompts to a provider they never intended to reach.
+ *
+ * @param {any} configuration
+ * @returns {import('#core/envelope.js').Auth}
+ */
+const ALLOWED_CONFIG_KEYS = new Set(['apiKey', 'baseURL'])
+
+function configToAuth (configuration) {
+  if (!configuration) return { key: '' }
+  const unsupported = Object.keys(configuration).filter(k => !ALLOWED_CONFIG_KEYS.has(k))
+  if (unsupported.length > 0) {
+    throw new MohdelError('CONFIGURATION_UNSUPPORTED', {
+      severity: Severity.ERROR,
+      detail:
+        'per-call SDK configuration is limited to `apiKey` and `baseURL`. ' +
+        `Unsupported keys: ${unsupported.join(', ')}. ` +
+        'Move other fields to environment variables or pin them at factory construction.',
+      retryable: false
+    })
+  }
+  const auth = { key: configuration.apiKey || '' }
+  if (configuration.baseURL) auth.baseURL = configuration.baseURL
+  return auth
+}
+
+/**
+ * Translate the factory's structured-input shape
+ * (`{ system?, messages: [{role, content, toolCalls?, toolCallId?, toolName?}] }`)
+ * into the envelope `Message[]` expected by session adapters. Plain
+ * strings and pre-shaped arrays pass through untouched.
+ *
+ * Role mapping:
+ *   - factory `tool_result` → envelope `tool` (carrying `toolCallId`,
+ *     `content`, and optional `name` from `toolName`).
+ *   - `assistant.toolCalls` carries through as-is onto the envelope
+ *     Message so adapters can emit the provider-native tool_use.
+ *
+ * @param {unknown} prompt
+ * @returns {string | import('#core/envelope.js').Message[]}
+ */
+function toEnvelopePrompt (prompt) {
+  if (typeof prompt === 'string') return prompt
+  if (Array.isArray(prompt)) return /** @type {any} */(prompt)
+
+  if (prompt && typeof prompt === 'object' && Array.isArray(prompt.messages)) {
+    const out = []
+    if (prompt.system != null) {
+      out.push({
+        role: 'system',
+        content: flattenSystem(prompt.system)
+      })
+    }
+    for (const m of prompt.messages) {
+      if (m.role === 'tool_result') {
+        const msg = {
+          role: 'tool',
+          content: m.content ?? ''
+        }
+        if (m.toolCallId) msg.toolCallId = m.toolCallId
+        if (m.toolName) msg.toolName = m.toolName
+        out.push(msg)
+      } else if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length) {
+        const msg = {
+          role: 'assistant',
+          content: m.content ?? '',
+          toolCalls: m.toolCalls.map(tc => {
+            const out = {
+              id: tc.id,
+              name: tc.name,
+              arguments: tc.arguments ?? {}
+            }
+            // Preserve provider-specific bits so a subsequent replay
+            // reaches the adapter intact. Gemini rejects a tool-call
+            // replay whose original `thoughtSignature` has been stripped.
+            if (tc.thoughtSignature) out.thoughtSignature = tc.thoughtSignature
+            return out
+          })
+        }
+        out.push(msg)
+      } else {
+        out.push({ role: m.role, content: m.content ?? '' })
+      }
+    }
+    return out
+  }
+
+  // Unknown shape — reject early with a clear error. Letting this
+  // fall through would land a raw non-iterable in the envelope and
+  // produce a confusing `prompt.map is not a function` deep inside
+  // the adapter.
+  throw new MohdelError('SESSION_INVALID_PROMPT', {
+    severity: Severity.ERROR,
+    retryable: false,
+    detail:
+      'prompt must be a string, a Message[] array, ' +
+      'or { system?, messages: [...] }; received ' +
+      describePromptShape(prompt)
+  })
+}
+
+/** @param {unknown} v */
+function describePromptShape (v) {
+  if (v === null) return 'null'
+  if (v === undefined) return 'undefined'
+  if (typeof v !== 'object') return typeof v
+  if ('messages' in v && !Array.isArray(/** @type {any} */(v).messages)) {
+    return 'object with non-array messages'
+  }
+  return 'object without messages'
+}
+
+/**
+ * The factory accepts `system` as either a plain string or an array
+ * of `{text, cache?}` blocks (for Anthropic prompt caching). The
+ * envelope's `Message.content` is string-or-MessagePart[]; flatten
+ * blocks to a single string here. Callers who need Anthropic
+ * cache-control blocks preserved need a separate path.
+ *
+ * @param {string | Array<{text?: string}>} system
+ */
+function flattenSystem (system) {
+  if (typeof system === 'string') return system
+  if (Array.isArray(system)) {
+    return system.map(b => b?.text ?? '').filter(Boolean).join('\n')
+  }
+  return String(system ?? '')
+}

package/js/session/_cooldown.js

@@ -0,0 +1,114 @@
+/**
+ * Consecutive-failure cooldown tracker.
+ *
+ *   - Auth failures (401/403) trigger immediate cooldown (1 failure).
+ *   - Other retryable failures require `threshold` consecutive
+ *     failures before cooldown triggers.
+ *   - Success resets the failure counter.
+ *   - `check`/`throwIfCoolingDown` expires the entry when the
+ *     cooldown window passes.
+ *
+ * Configuration comes from env vars (session-level, global):
+ *   - MOHDEL_COOLDOWN_THRESHOLD (default 3)
+ *   - MOHDEL_COOLDOWN_DURATION_MS (default 60_000)
+ *
+ * State is session-process-local.
+ *
+ * @module session/cooldown
+ */
+
+const DEFAULT_THRESHOLD = 3
+const DEFAULT_DURATION_MS = 60_000
+
+function envInt (name, fallback) {
+  const v = process.env[name]
+  if (!v) return fallback
+  const n = Number.parseInt(v, 10)
+  return Number.isFinite(n) && n > 0 ? n : fallback
+}
+
+export function createCooldownTracker (
+  threshold = envInt('MOHDEL_COOLDOWN_THRESHOLD', DEFAULT_THRESHOLD),
+  durationMs = envInt('MOHDEL_COOLDOWN_DURATION_MS', DEFAULT_DURATION_MS)
+) {
+  /** @type {Map<string, {failCount: number, until: number | null, reason: string | null}>} */
+  const entries = new Map()
+
+  /** @param {string} key */
+  const check = (key) => {
+    const entry = entries.get(key)
+    if (!entry || !entry.until) return null
+    if (Date.now() >= entry.until) {
+      entries.delete(key)
+      return null
+    }
+    return entry
+  }
+
+  /**
+   * Records a failure. Returns `true` only if this call caused a
+   * **fresh** cooldown activation — no active window existed (or the
+   * previous one had expired). Late failures during an active window
+   * increment `failCount` (diagnostics) but do NOT push `until`
+   * forward; the cooldown is set-once, waited-out, reset on success.
+   * Without this freeze, concurrent failures racing past the
+   * pre-dispatch check would keep sliding the deadline and the user
+   * would effectively never recover.
+   *
+   * @param {string} key
+   * @param {{immediate?: boolean}} [options]
+   * @returns {boolean} true if this call freshly activated the cooldown
+   */
+  const recordFailure = (key, { immediate = false } = {}) => {
+    const entry = entries.get(key) || { failCount: 0, until: null, reason: null }
+    entry.failCount++
+    const shouldCooldown = immediate || entry.failCount >= threshold
+    if (shouldCooldown) {
+      const now = Date.now()
+      if (entry.until == null || now >= entry.until) {
+        entry.until = now + durationMs
+        entry.reason = immediate ? 'auth' : 'consecutive_failures'
+        entries.set(key, entry)
+        return true
+      }
+    }
+    entries.set(key, entry)
+    return false
+  }
+
+  /** @param {string} key */
+  const reset = (key) => {
+    entries.delete(key)
+  }
+
+  /**
+   * Returns a TypedError shape if the bucket is cooling down, else
+   * undefined. Caller yields it as a `call.error` event.
+   *
+   * @param {string} key
+   * @returns {import('#core/errors.js').TypedError | undefined}
+   */
+  const coolingDownError = (key) => {
+    const entry = check(key)
+    if (!entry) return undefined
+    const secsLeft = Math.ceil((entry.until - Date.now()) / 1000)
+    return {
+      message: 'provider in cooldown',
+      detail: `${key} is in cooldown for ${secsLeft}s after ${entry.failCount} consecutive failures (${entry.reason})`,
+      severity: 'warn',
+      retryable: true,
+      type: 'PROVIDER_COOLDOWN'
+    }
+  }
+
+  return { check, recordFailure, reset, coolingDownError, threshold, durationMs }
+}
+
+// Single session-local tracker. Re-exported as named members so
+// callers can `import * as cooldown from './_cooldown.js'` and use
+// `cooldown.reset(key)` / `cooldown.coolingDownError(key)`.
+const defaultTracker = createCooldownTracker()
+export const check = defaultTracker.check
+export const recordFailure = defaultTracker.recordFailure
+export const reset = defaultTracker.reset
+export const coolingDownError = defaultTracker.coolingDownError

package/js/session/_logger.js

@@ -0,0 +1,138 @@
+/**
+ * Session-process logger.
+ *
+ * Minimal pino-shape writer with no pino dependency. Writes one
+ * newline-delimited JSON object per call to **stderr** — stdout is
+ * reserved for the NDJSON event stream. Every line carries the
+ * log level, subsystem message, and any structured fields the caller
+ * included (including `traceId` / `spanId` for SigNoz / Jaeger /
+ * Honeycomb correlation).
+ *
+ * Verbosity tier (`MOHDEL_VERBOSITY`, 0/1/2) matches the LOGGING.md
+ * spec. Level gate (`MOHDEL_LOG_LEVEL`, one of trace/debug/info/warn/
+ * error/fatal/silent) is the standard severity filter applied on top
+ * of the tier.
+ *
+ * @module session/logger
+ */
+
+const LEVELS = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+  silent: 100
+}
+
+// Real sessions want "warn" (anomalies visible) but tests would
+// otherwise flood stderr with the lines we deliberately induce.
+// Under vitest, default to silent unless MOHDEL_LOG_LEVEL is set
+// explicitly.
+const DEFAULT_LEVEL = process.env.VITEST ? 'silent' : 'warn'
+const DEFAULT_VERBOSITY = 1
+
+function envInt (name, fallback) {
+  const v = process.env[name]
+  if (!v) return fallback
+  const n = Number.parseInt(v, 10)
+  return Number.isFinite(n) ? n : fallback
+}
+
+function envLevel (name, fallback) {
+  const v = process.env[name]
+  if (!v) return fallback
+  const k = String(v).toLowerCase()
+  return Object.prototype.hasOwnProperty.call(LEVELS, k) ? k : fallback
+}
+
+/**
+ * @param {{level?: string, verbosity?: number, stream?: NodeJS.WritableStream, context?: object}} [opts]
+ */
+export function createLogger (opts = {}) {
+  const level = opts.level ?? envLevel('MOHDEL_LOG_LEVEL', DEFAULT_LEVEL)
+  const verbosity = opts.verbosity ?? envInt('MOHDEL_VERBOSITY', DEFAULT_VERBOSITY)
+  const stream = opts.stream ?? process.stderr
+  const baseContext = { ...(opts.context ?? {}) }
+  const threshold = LEVELS[level] ?? LEVELS[DEFAULT_LEVEL]
+
+  const emit = (lvl, firstArg, msg) => {
+    if (LEVELS[lvl] < threshold) return
+    const line = { level: lvl, time: Date.now(), ...baseContext }
+    if (typeof firstArg === 'string') {
+      line.msg = firstArg
+    } else if (firstArg && typeof firstArg === 'object') {
+      // Stack traces can harbor sensitive data from some SDKs (tokens,
+      // request bodies passed into Error constructors). Keep them only
+      // at the verbose levels (trace/debug), which are off by default
+      // in production.
+      mergeFields(line, firstArg, LEVELS[lvl] <= LEVELS.debug)
+      if (msg !== undefined) line.msg = msg
+    }
+    try {
+      stream.write(JSON.stringify(line) + '\n')
+    } catch {
+      // swallow: stderr write failures must not take down the session
+    }
+  }
+
+  const trace = (fields, msg) => emit('trace', fields, msg)
+  const debug = (fields, msg) => emit('debug', fields, msg)
+  const info = (fields, msg) => emit('info', fields, msg)
+  const warn = (fields, msg) => emit('warn', fields, msg)
+  const error = (fields, msg) => emit('error', fields, msg)
+  const fatal = (fields, msg) => emit('fatal', fields, msg)
+
+  /**
+   * @param {object} extra
+   */
+  const withContext = (extra) => createLogger({
+    level,
+    verbosity,
+    stream,
+    context: { ...baseContext, ...extra }
+  })
+
+  return Object.freeze({
+    level,
+    verbosity,
+    trace,
+    debug,
+    info,
+    warn,
+    error,
+    fatal,
+    withContext
+  })
+}
+
+/**
+ * Merge structured log fields. Errors are flattened to a stable shape
+ * so `JSON.stringify` doesn't drop the message.
+ *
+ * @param {object} target
+ * @param {object} source
+ * @param {boolean} includeStack
+ */
+function mergeFields (target, source, includeStack) {
+  for (const [k, v] of Object.entries(source)) {
+    if (v instanceof Error) {
+      target[k] = {
+        message: v.message,
+        name: v.name,
+        ...(includeStack && v.stack ? { stack: v.stack } : {}),
+        ...(v.code ? { code: v.code } : {}),
+        ...(v.status ? { status: v.status } : {})
+      }
+    } else {
+      target[k] = v
+    }
+  }
+}
+
+// Module-level default — used when a caller doesn't pass their own.
+// Keeping the stream open lets adapters import the singleton
+// directly; `withContext` spawns scoped children per call without
+// allocating a new writer.
+export const logger = createLogger()

package/js/session/_rate_limiter.js

@@ -0,0 +1,77 @@
+/**
+ * Minute-bucket rate limiter (per-key: provider or provider/model).
+ *
+ * Tracks RPM and TPM. Returns ms to wait if over limit — throttles
+ * rather than rejecting, so the caller can absorb small bursts
+ * without a 429 round-trip.
+ *
+ * State is session-process-local. In a pool, each session has its
+ * own counters — total throughput ~= pool_size × limit. For strict
+ * cross-process enforcement, configure it at thin-gate level via
+ * the `QuotaPolicy` hook.
+ *
+ * @module session/rate-limiter
+ */
+
+export function createRateLimiter () {
+  /** @type {Map<string, {count: number, tokens: number, minute: number}>} */
+  const buckets = new Map()
+
+  const currentMinute = () => Math.floor(Date.now() / 60000)
+
+  /** @param {string} key */
+  const getBucket = (key) => {
+    const minute = currentMinute()
+    const b = buckets.get(key)
+    if (b && b.minute === minute) return b
+    const fresh = { count: 0, tokens: 0, minute }
+    buckets.set(key, fresh)
+    return fresh
+  }
+
+  /** @param {number} minute */
+  const msUntilNextMinute = (minute) => Math.max(0, (minute + 1) * 60000 - Date.now())
+
+  /**
+   * Returns ms to wait before sending. 0 means go ahead.
+   *
+   * Semantics:
+   *   - `undefined` / `null` on a dimension → no limit configured,
+   *     skipped.
+   *   - `0` → **deny all** (killswitch). `msUntilNextMinute` is
+   *     returned regardless of the current bucket.
+   *   - positive number → throttle at that value.
+   *
+   * @param {string} key
+   * @param {{rpmLimit?: number, tpmLimit?: number}} limits
+   * @returns {number}
+   */
+  const check = (key, { rpmLimit, tpmLimit } = {}) => {
+    if (rpmLimit == null && tpmLimit == null) return 0
+    const b = getBucket(key)
+    if (rpmLimit != null && b.count >= rpmLimit) return msUntilNextMinute(b.minute)
+    if (tpmLimit != null && b.tokens >= tpmLimit) return msUntilNextMinute(b.minute)
+    return 0
+  }
+
+  /** @param {string} key */
+  const recordRequest = (key) => {
+    getBucket(key).count++
+  }
+
+  /**
+   * @param {string} key
+   * @param {number} tokens
+   */
+  const recordTokens = (key, tokens) => {
+    getBucket(key).tokens += tokens
+  }
+
+  return { check, recordRequest, recordTokens }
+}
+
+// Single session-local instance.
+const defaultLimiter = createRateLimiter()
+export const check = defaultLimiter.check
+export const recordRequest = defaultLimiter.recordRequest
+export const recordTokens = defaultLimiter.recordTokens