mohdel 0.117.3 → 0.119.0

package/README.md

@@ -179,7 +179,7 @@ Every call emits:
 
 - **OpenTelemetry span** (`mohdel.session.answer`) under the caller's `traceparent`, with GenAI semantic-convention attributes (`gen_ai.request.model`, `gen_ai.system`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`) plus mohdel's own (`mohdel.status`, `mohdel.cost`, `mohdel.thinking_tokens`, `mohdel.time_to_first_token_ms`, `mohdel.cooldown` on fast-fail).
 - **Trace-linked logs** — every stderr log line carries `{traceId, spanId, callId, authId, provider, model}`. Dump logs + traces into the same collector (SigNoz, Honeycomb, Jaeger + Loki) and they're correlated for free. No per-call instrumentation code.
-- **Gate-side OTLP metrics** (when running `thin-gate`): `mohdel.sessions.{alive,respawned,spawn_failures}`, `mohdel.calls{provider,status}`, `mohdel.call.duration_ms`, `mohdel.cooldown.rejections`, `mohdel.quota.rejections`, `mohdel.policy.errors`.
+- **Gate-side OTLP metrics** (when running `thin-gate`): `mohdel.sessions.{alive,respawned,spawn_failures}`, `mohdel.calls{provider,status}`, `mohdel.call.duration_ms`, `mohdel.cooldown.rejections`, `mohdel.quota.rejections`, `mohdel.policy.errors`, `mohdel.enforcer.keyspace_full{map}`. The `provider` attribute is folded to `other` for anything outside mohdel's provider set, so a caller can't mint metric series by varying the model prefix.
 
 One endpoint for everything: set `OTEL_EXPORTER_OTLP_ENDPOINT` and spans + metrics flow to it over gRPC. No-op when unset — zero overhead for callers who aren't wired. See [INTEGRATION.md §OpenTelemetry](INTEGRATION.md#opentelemetry) and [LOGGING.md](LOGGING.md) for details.
 
@@ -221,6 +221,8 @@ cargo run --bin mohdel-thin-gate /tmp/mohdel-data.sock /tmp/mohdel-admin.sock /p
 Positional args are optional (data socket, admin socket, session bin). Env overrides:
 - `MOHDEL_SESSION_BIN` — path to session entrypoint (defaults to none; if unset, data plane returns synthetic events)
 - `MOHDEL_SESSION_POOL_SIZE` — pre-warmed sessions (default 2)
+- `MOHDEL_POOL_ACQUIRE_TIMEOUT_MS` — wait for a free session before `503 SESSION_POOL_BUSY` (default 30000)
+- `MOHDEL_MAX_CONNECTIONS` — concurrently served data-plane connections (default 64)
 
 With no session-bin configured, thin-gate runs in demo mode: `POST /v1/call` returns a synthetic echo event sequence. Useful for health-checking the HTTP layer without a runtime dependency on Node.
 
@@ -240,7 +242,7 @@ Wire format is JSON over NDJSON frames, camelCase. Types are defined in `js/core
 - **`AnswerResult`** — `status`, `output`, `inputTokens`, `outputTokens`, `thinkingTokens`, `cost` (single number), `timestamps`, `warning?`, `toolCalls?`.
 - **`Status`** — `'completed' | 'tool_use' | 'incomplete'`.
 - **`Warning`** — additive string union: `'insufficientOutputBudget'`, `'cancelled'`, ...
-- **`TypedError`** — `{ message, detail?, severity, retryable, type }`. `message` is a stable machine key; `detail` is user-facing context; `severity` is `'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'`; `type` is an optional canonical tag (e.g. `'AUTH_INVALID'`, `'PROVIDER_COOLDOWN'`).
+- **`TypedError`** — `{ message, detail?, severity, retryable, type }`. `type` is the canonical tag callers branch on (e.g. `'AUTH_INVALID'`, `'PROVIDER_COOLDOWN'`), optional on the wire; `message` is a short human-readable label; `detail` is the provider's own rejection text; `severity` is `'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'`.
 
 A `cancel` control message `{ op: "cancel", callId }` on session stdin aborts the matching in-flight call.
 

package/js/client/call.js

@@ -9,8 +9,9 @@
  */
 
 import { requestUnix } from './transport.js'
+import { readAll, parseErrorBody } from './response.js'
 import { parseNDJSON } from './ndjson.js'
-import { isEvent, MohdelTypedError } from '#core'
+import { isEvent, MohdelError } from '#core'
 
 /**
  * @param {import('#core/envelope.js').CallEnvelope} envelope
@@ -31,12 +32,12 @@ export async function * call (envelope, { socketPath, signal, path = '/v1/call'
 
   if (res.statusCode !== 200) {
     const body = await readAll(res)
-    throw MohdelTypedError.fromJSON(parseErrorBody(body, res.statusCode ?? 0))
+    throw MohdelError.fromJSON(parseErrorBody(body, res.statusCode ?? 0))
   }
 
   for await (const obj of parseNDJSON(res)) {
     if (!isEvent(obj)) {
-      throw new MohdelTypedError(
+      throw new MohdelError(
         'received non-Event object from thin-gate',
         { type: 'PROTOCOL_INVALID_EVENT', retryable: false }
       )
@@ -44,32 +45,3 @@ export async function * call (envelope, { socketPath, signal, path = '/v1/call'
     yield /** @type {import('#core/events.js').Event} */(obj)
   }
 }
-
-/**
- * @param {AsyncIterable<Buffer|string>} stream
- * @returns {Promise<string>}
- */
-async function readAll (stream) {
-  let s = ''
-  for await (const c of stream) s += typeof c === 'string' ? c : c.toString('utf8')
-  return s
-}
-
-/**
- * @param {string} body
- * @param {number} status
- * @returns {import('#core/errors.js').TypedError}
- */
-function parseErrorBody (body, status) {
-  try {
-    const parsed = JSON.parse(body)
-    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
-      return parsed
-    }
-  } catch {}
-  return {
-    type: 'PROTOCOL_HTTP_ERROR',
-    message: `thin-gate returned HTTP ${status}`,
-    retryable: status >= 500
-  }
-}

package/js/client/call_image.js

@@ -8,7 +8,8 @@
  */
 
 import { requestUnix } from './transport.js'
-import { MohdelTypedError } from '#core'
+import { readAll, parseErrorBody } from './response.js'
+import { MohdelError } from '#core'
 
 /**
  * @param {import('#core/image.js').ImageEnvelope} envelope
@@ -30,53 +31,24 @@ export async function callImage (envelope, { socketPath, signal, path = '/v1/ima
   const body = await readAll(res)
 
   if (res.statusCode !== 200) {
-    throw MohdelTypedError.fromJSON(parseErrorBody(body, res.statusCode ?? 0))
+    throw MohdelError.fromJSON(parseErrorBody(body, res.statusCode ?? 0))
   }
 
   let parsed
   try {
     parsed = JSON.parse(body)
   } catch (e) {
-    throw new MohdelTypedError(
+    throw new MohdelError(
       'thin-gate returned non-JSON image response',
       { type: 'PROTOCOL_INVALID_EVENT', retryable: false }
     )
   }
 
   if (!parsed || typeof parsed !== 'object' || parsed.status !== 'completed' || !Array.isArray(parsed.images)) {
-    throw new MohdelTypedError(
+    throw new MohdelError(
       'thin-gate returned malformed ImageResult',
       { type: 'PROTOCOL_INVALID_EVENT', retryable: false }
     )
   }
   return parsed
 }
-
-/**
- * @param {AsyncIterable<Buffer|string>} stream
- * @returns {Promise<string>}
- */
-async function readAll (stream) {
-  let s = ''
-  for await (const c of stream) s += typeof c === 'string' ? c : c.toString('utf8')
-  return s
-}
-
-/**
- * @param {string} body
- * @param {number} status
- * @returns {import('#core/errors.js').TypedError}
- */
-function parseErrorBody (body, status) {
-  try {
-    const parsed = JSON.parse(body)
-    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
-      return parsed
-    }
-  } catch {}
-  return {
-    type: 'PROTOCOL_HTTP_ERROR',
-    message: `thin-gate returned HTTP ${status}`,
-    retryable: status >= 500
-  }
-}

package/js/client/call_transcription.js

@@ -11,7 +11,8 @@
  */
 
 import { requestUnix } from './transport.js'
-import { MohdelTypedError } from '#core'
+import { readAll, parseErrorBody } from './response.js'
+import { MohdelError } from '#core'
 
 /**
  * @param {import('#core/transcription.js').TranscriptionEnvelope} envelope
@@ -33,53 +34,24 @@ export async function callTranscription (envelope, { socketPath, signal, path =
   const body = await readAll(res)
 
   if (res.statusCode !== 200) {
-    throw MohdelTypedError.fromJSON(parseErrorBody(body, res.statusCode ?? 0))
+    throw MohdelError.fromJSON(parseErrorBody(body, res.statusCode ?? 0))
   }
 
   let parsed
   try {
     parsed = JSON.parse(body)
   } catch (e) {
-    throw new MohdelTypedError(
+    throw new MohdelError(
       'thin-gate returned non-JSON transcription response',
       { type: 'PROTOCOL_INVALID_EVENT', retryable: false }
     )
   }
 
   if (!parsed || typeof parsed !== 'object' || parsed.status !== 'completed' || typeof parsed.text !== 'string') {
-    throw new MohdelTypedError(
+    throw new MohdelError(
       'thin-gate returned malformed TranscriptionResult',
       { type: 'PROTOCOL_INVALID_EVENT', retryable: false }
     )
   }
   return parsed
 }
-
-/**
- * @param {AsyncIterable<Buffer|string>} stream
- * @returns {Promise<string>}
- */
-async function readAll (stream) {
-  let s = ''
-  for await (const c of stream) s += typeof c === 'string' ? c : c.toString('utf8')
-  return s
-}
-
-/**
- * @param {string} body
- * @param {number} status
- * @returns {import('#core/errors.js').TypedError}
- */
-function parseErrorBody (body, status) {
-  try {
-    const parsed = JSON.parse(body)
-    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
-      return parsed
-    }
-  } catch {}
-  return {
-    type: 'PROTOCOL_HTTP_ERROR',
-    message: `thin-gate returned HTTP ${status}`,
-    retryable: status >= 500
-  }
-}

package/js/client/ndjson.js

@@ -1,10 +1,14 @@
 /**
  * NDJSON line parser. Yields parsed objects from a byte/string stream.
  *
+ * The cap applies to a single unterminated line, not to the accumulated
+ * buffer: a buffer holding several complete frames is a legitimate
+ * burst, not a runaway line.
+ *
  * @module client/ndjson
  */
 
-const MAX_LINE_BYTES = 16 * 1024 * 1024
+import { MAX_LINE_BYTES, exceedsLineBytes } from '#core/framing.js'
 
 /**
  * @param {AsyncIterable<Buffer|string>} stream
@@ -14,15 +18,15 @@ export async function * parseNDJSON (stream) {
   let buf = ''
   for await (const chunk of stream) {
     buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8')
-    if (buf.length > MAX_LINE_BYTES) {
-      throw new Error(`NDJSON line exceeds ${MAX_LINE_BYTES} bytes without newline`)
-    }
     let nl
     while ((nl = buf.indexOf('\n')) !== -1) {
       const line = buf.slice(0, nl).trim()
       buf = buf.slice(nl + 1)
       if (line) yield JSON.parse(line)
     }
+    if (exceedsLineBytes(buf)) {
+      throw new Error(`NDJSON line exceeds ${MAX_LINE_BYTES} bytes without newline`)
+    }
   }
   const tail = buf.trim()
   if (tail) yield JSON.parse(tail)

package/js/client/response.js

@@ -0,0 +1,40 @@
+/**
+ * Shared response handling for the three gate call paths.
+ *
+ * `call.js`, `call_image.js` and `call_transcription.js` each read a
+ * non-200 body the same way and turn it into the same `TypedError`;
+ * keeping one copy means a fix to the error shape cannot land on some
+ * paths and miss others.
+ *
+ * @module client/response
+ */
+
+/**
+ * @param {AsyncIterable<Buffer|string>} stream
+ * @returns {Promise<string>}
+ */
+export async function readAll (stream) {
+  let s = ''
+  for await (const c of stream) s += typeof c === 'string' ? c : c.toString('utf8')
+  return s
+}
+
+/**
+ * @param {string} body
+ * @param {number} status
+ * @returns {import('#core/errors.js').TypedError}
+ */
+export function parseErrorBody (body, status) {
+  try {
+    const parsed = JSON.parse(body)
+    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
+      return parsed
+    }
+  } catch {}
+  return {
+    type: 'PROTOCOL_HTTP_ERROR',
+    message: `thin-gate returned HTTP ${status}`,
+    severity: 'error',
+    retryable: status >= 500
+  }
+}

package/js/client/transport.js

@@ -39,7 +39,12 @@ export function requestUnix ({ socketPath, path, method, body, signal, headers }
         reject(new Error('aborted'))
         return
       }
-      signal.addEventListener('abort', () => req.destroy(new Error('aborted')), { once: true })
+      const onAbort = () => req.destroy(new Error('aborted'))
+      signal.addEventListener('abort', onAbort, { once: true })
+      // Released on `close` rather than on resolve: the promise
+      // resolves at response headers, and cancellation has to stay
+      // live for the streaming body that follows.
+      req.on('close', () => signal.removeEventListener('abort', onAbort))
     }
 
     if (body !== undefined) req.end(JSON.stringify(body))

package/js/core/envelope.js

@@ -23,7 +23,7 @@
  * @property {string} [traceparent]  W3C tracecontext header.
  * @property {string} [baggage]      W3C baggage header.
  *
- * @property {import('./model-id.js').ModelId} model
+ * @property {string} model
  *   Full mohdel id — `"<provider>/<bare>[:<effort>]"`. Same shape
  *   on the wire and in-process. See PROTOCOL §3. No separate
  *   `provider` field exists at any layer; callers that need the
@@ -64,6 +64,7 @@
  *   the gap persists. The consumer decides whether to act (log,
  *   bump a watchdog, abort via its own AbortSignal). Mohdel never
  *   aborts on its own. Omitting the field disables the heartbeat.
+ *   Positive values are raised to `MIN_IDLE_HEARTBEAT_MS` (250).
  *
  * @property {Object<string, object>} [providerOptions]
  *   Namespaced bag of provider-specific knobs that don't fit the
@@ -155,3 +156,47 @@ export const ENVELOPE_FIELDS = Object.freeze([
   'idleHeartbeatMs',
   'providerOptions'
 ])
+
+export const MAX_ID_BYTES = 128
+export const MAX_MODEL_BYTES = 256
+export const MAX_PROVIDER_BYTES = 32
+
+const encoder = new TextEncoder()
+
+/**
+ * @param {string} s
+ * @returns {number}
+ */
+function byteLength (s) {
+  return encoder.encode(s).length
+}
+
+/**
+ * Bound the envelope fields that become long-lived map keys and
+ * telemetry attributes, and reject a model id with an empty half.
+ *
+ * Mirror of `rust/thin-gate/src/protocol.rs::validate_ids`, applied on
+ * the in-process factory path which does not cross the gate. Reason
+ * strings match the gate's byte for byte so both transports report a
+ * rejection identically.
+ *
+ * @param {string} callId
+ * @param {string} authId
+ * @param {string} model
+ * @returns {string | undefined}  Reason, or undefined when valid.
+ */
+export function validateIds (callId, authId, model) {
+  if (byteLength(callId) > MAX_ID_BYTES) return `callId exceeds ${MAX_ID_BYTES} bytes`
+  if (byteLength(authId) > MAX_ID_BYTES) return `authId exceeds ${MAX_ID_BYTES} bytes`
+  if (byteLength(model) > MAX_MODEL_BYTES) return `model exceeds ${MAX_MODEL_BYTES} bytes`
+
+  const slash = model.indexOf('/')
+  const provider = slash < 0 ? '' : model.slice(0, slash)
+  const bare = slash < 0 ? '' : model.slice(slash + 1)
+  if (slash < 0 || !provider || !bare) {
+    return `model must be '<provider>/<id>' (got: ${model})`
+  }
+  if (byteLength(provider) > MAX_PROVIDER_BYTES) {
+    return `model provider exceeds ${MAX_PROVIDER_BYTES} bytes`
+  }
+}

package/js/core/errors.js

@@ -1,7 +1,13 @@
 /**
- * `TypedError` — wire-format error. Carries `message` (machine key),
- * optional `detail` (user-facing context), `severity` (lowercase
- * string), `retryable`, and optional `type` (canonical tag).
+ * `MohdelError` — the one error kind. `TypedError` is its serialized
+ * form: `type` is the canonical machine tag callers branch on,
+ * `message` is a short human-readable label, `detail` carries the
+ * provider's own rejection text, plus `severity` (lowercase string)
+ * and `retryable`.
+ *
+ * Thrown in-process by the factory and serialized over the gate are
+ * two transports for the same error. `toJSON()` whitelists the wire
+ * fields, so in-process-only state (`context`) cannot reach the wire.
  *
  * Rust mirror: `rust/thin-gate/src/protocol.rs::TypedError`.
  *
@@ -15,36 +21,44 @@
 /**
  * @typedef {object} TypedError
  * @property {string} message
- *   Top-level message. Never echo provider response bodies.
+ *   Short human-readable label (e.g. `'provider error 400'`). Never
+ *   echo provider response bodies.
  * @property {string} [detail]
- *   User-facing error detail (mirrors `MohdelError.detail`).
+ *   Provider rejection text, capped and API-key-scrubbed by
+ *   `classifyProviderError`. Whether to surface, log, or redact it
+ *   further is the caller's policy.
  * @property {SeverityTag} severity
  * @property {boolean} retryable
  * @property {string} [type]
- *   Optional canonical tag (e.g. `'PROVIDER_COOLDOWN'`, `'AUTH_INVALID'`).
+ *   Canonical tag callers branch on (e.g. `'PROVIDER_COOLDOWN'`,
+ *   `'AUTH_INVALID'`). Optional on the wire; every
+ *   `classifyProviderError` result sets it.
  */
 
 export const SEVERITY_TAGS = Object.freeze([
   'trace', 'debug', 'info', 'warn', 'error', 'fatal'
 ])
 
-export class MohdelTypedError extends Error {
+export class MohdelError extends Error {
   /**
    * @param {string} message
    * @param {{
    *   severity?: SeverityTag,
    *   retryable?: boolean,
    *   detail?: string,
-   *   type?: string
+   *   type?: string,
+   *   context?: object
    * }} [options]
+   *   `context` is in-process only and never serialized.
    */
-  constructor (message, { severity = 'error', retryable = false, detail, type } = {}) {
+  constructor (message, { severity = 'error', retryable = false, detail, type, context } = {}) {
     super(message)
-    this.name = 'MohdelTypedError'
+    this.name = 'MohdelError'
     this.severity = severity
     this.retryable = retryable
     if (detail) this.detail = detail
     if (type) this.type = type
+    if (context) this.context = context
   }
 
   /** @returns {TypedError} */
@@ -62,14 +76,16 @@ export class MohdelTypedError extends Error {
 
   /**
    * @param {TypedError} data
-   * @returns {MohdelTypedError}
+   * @param {object} [context]  In-process only; not part of `data`.
+   * @returns {MohdelError}
    */
-  static fromJSON (data) {
-    return new MohdelTypedError(data.message, {
+  static fromJSON (data, context) {
+    return new MohdelError(data.message, {
       severity: data.severity,
       retryable: data.retryable,
       detail: data.detail,
-      type: data.type
+      type: data.type,
+      context
     })
   }
 }

package/js/core/framing.js

@@ -0,0 +1,29 @@
+/**
+ * NDJSON framing limits, shared by every JS reader of the protocol.
+ *
+ * The cap bounds a single unterminated line, not accumulated buffered
+ * frames, and is measured in UTF-8 bytes so it matches the gate's
+ * `read_capped_line` (`rust/thin-gate/src/server.rs`), which counts
+ * bytes off the socket. A reader that capped UTF-16 units instead
+ * would accept up to three times what the gate does.
+ *
+ * @module core/framing
+ */
+
+export const MAX_LINE_BYTES = 16 * 1024 * 1024
+
+/**
+ * Exact byte length is O(n) in the string, so it is only computed in
+ * the band where the answer is in doubt: UTF-8 encodes a UTF-16 unit
+ * as 1-3 bytes, which brackets the count between `length` and
+ * `3 * length`.
+ *
+ * @param {string} s
+ * @param {number} [cap]
+ * @returns {boolean}
+ */
+export function exceedsLineBytes (s, cap = MAX_LINE_BYTES) {
+  if (s.length > cap) return true
+  if (s.length * 3 <= cap) return false
+  return Buffer.byteLength(s, 'utf8') > cap
+}

package/js/core/image.js

@@ -17,7 +17,7 @@
  * @property {string} [traceparent]
  * @property {string} [baggage]
  *
- * @property {import('./model-id.js').ModelId} model
+ * @property {string} model
  *   Full mohdel id — `"<provider>/<bare>"`. Same shape as
  *   `CallEnvelope.model` (see `envelope.js`). No separate `provider`
  *   field.

package/js/core/model-id.js

@@ -7,39 +7,16 @@
  * object form; when the provider or bare part is needed, these
  * helpers return it as a substring.
  *
- * `parseModelId` validates + brands at the boundary (factory input,
- * wire deserialize, admin endpoints). After that every `ModelId` in
- * memory is known-valid; adapters and core code call the accessors
- * freely without re-validating.
+ * Ids are validated at ingress by the gate
+ * (`rust/thin-gate/src/protocol.rs::validate_ids`); these accessors
+ * assume a well-formed id and do not re-validate.
  *
  * @module core/model-id
  */
 
-/**
- * Branded string type. Only `parseModelId` produces one.
- * @typedef {string & { __brand: 'ModelId' }} ModelId
- */
-
-const MODEL_ID_RE = /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9._-]*(?::[a-z]+)?$/i
-
-/**
- * Validate and brand a raw string. Throws on malformed input so the
- * boundary layer fails loudly instead of letting a bad id flow
- * through.
- *
- * @param {string} raw
- * @returns {ModelId}
- */
-export function parseModelId (raw) {
-  if (typeof raw !== 'string' || !MODEL_ID_RE.test(raw)) {
-    throw new TypeError(`invalid model id: ${JSON.stringify(raw)} (expected "<provider>/<bare>[:<effort>]")`)
-  }
-  return /** @type {ModelId} */ (raw)
-}
-
 /**
  * Provider segment of a model id.
- * @param {ModelId | string} model
+ * @param {string} model
  * @returns {string}
  */
 export function providerOf (model) {
@@ -52,7 +29,7 @@ export function providerOf (model) {
  * `:effort` suffix. Callers that want effort stripped use
  * `catalogKey()` instead.
  *
- * @param {ModelId | string} model
+ * @param {string} model
  * @returns {string}
  */
 export function bareOf (model) {
@@ -66,7 +43,7 @@ export function bareOf (model) {
  * output limits etc. are stored — per-effort variants do not get
  * their own entry.
  *
- * @param {ModelId | string} model
+ * @param {string} model
  * @returns {string}
  */
 export function catalogKey (model) {
@@ -81,7 +58,7 @@ export function catalogKey (model) {
 /**
  * Effort suffix, without the `:`, or `undefined` if absent.
  *
- * @param {ModelId | string} model
+ * @param {string} model
  * @returns {string | undefined}
  */
 export function effortOf (model) {

package/js/core/status.js

@@ -38,11 +38,3 @@ export const STATUSES = Object.freeze([
 
 export const WARNING_INSUFFICIENT_OUTPUT_BUDGET = 'insufficientOutputBudget'
 export const WARNING_CANCELLED = 'cancelled'
-
-/**
- * @param {unknown} x
- * @returns {x is Status}
- */
-export function isStatus (x) {
-  return typeof x === 'string' && STATUSES.includes(/** @type {Status} */(x))
-}

package/js/core/transcription.js

@@ -27,7 +27,7 @@
  * @property {string} [traceparent]
  * @property {string} [baggage]
  *
- * @property {import('./model-id.js').ModelId} model
+ * @property {string} model
  *   Full mohdel id — `"<provider>/<bare>"`. Same shape as
  *   `CallEnvelope.model` (see `envelope.js`).
  * @property {AudioRef} audio