mohdel 0.118.0 → 0.119.0

package/README.md

@@ -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.
 

package/js/client/call.js

@@ -9,6 +9,7 @@
  */
 
 import { requestUnix } from './transport.js'
+import { readAll, parseErrorBody } from './response.js'
 import { parseNDJSON } from './ndjson.js'
 import { isEvent, MohdelError } from '#core'
 
@@ -44,33 +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}`,
-    severity: 'error',
-    retryable: status >= 500
-  }
-}

package/js/client/call_image.js

@@ -8,6 +8,7 @@
  */
 
 import { requestUnix } from './transport.js'
+import { readAll, parseErrorBody } from './response.js'
 import { MohdelError } from '#core'
 
 /**
@@ -51,33 +52,3 @@ export async function callImage (envelope, { socketPath, signal, path = '/v1/ima
   }
   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}`,
-    severity: 'error',
-    retryable: status >= 500
-  }
-}

package/js/client/call_transcription.js

@@ -11,6 +11,7 @@
  */
 
 import { requestUnix } from './transport.js'
+import { readAll, parseErrorBody } from './response.js'
 import { MohdelError } from '#core'
 
 /**
@@ -54,33 +55,3 @@ export async function callTranscription (envelope, { socketPath, signal, path =
   }
   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}`,
-    severity: 'error',
-    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

@@ -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

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/factory/bridge.js

@@ -281,7 +281,7 @@ function newCallId () {
  */
 const ALLOWED_CONFIG_KEYS = new Set(['apiKey', 'baseURL'])
 
-function configToAuth (configuration) {
+export function configToAuth (configuration) {
   if (!configuration) return { key: '' }
   const unsupported = Object.keys(configuration).filter(k => !ALLOWED_CONFIG_KEYS.has(k))
   if (unsupported.length > 0) {

package/js/session/_idle_heartbeat.js

@@ -11,20 +11,30 @@
  * own. Consumers decide whether to log, bump a watchdog, or trigger
  * an external AbortSignal.
  *
- * The in-flight `iterator.next()` is reused across timer firings so
- * no real event is dropped: when the timer wins the race, the
- * underlying promise stays pending and the next loop iteration
- * attaches a fresh race to the same promise.
+ * `idleMs` is caller-supplied and raised to `MIN_IDLE_HEARTBEAT_MS`.
+ * Without a floor one request can ask for a millisecond cadence and
+ * turn adapter silence into thousands of serialized events per second
+ * through the gate.
+ *
+ * The in-flight `iterator.next()` is reused across timer firings so no
+ * real event is dropped. Its continuation is attached exactly once, at
+ * creation, and parks its result in `settled`; each idle tick races a
+ * fresh timer against that flag rather than re-subscribing. Attaching
+ * per tick instead would retain two reaction records per firing on a
+ * promise that by definition has not settled.
  *
  * @module session/_idle_heartbeat
  */
 
+export const MIN_IDLE_HEARTBEAT_MS = 250
+
 /**
  * @template T
  * @param {AsyncIterable<T>} source
  * @param {number | undefined | null} idleMs
  *   When falsy or non-positive, the source is yielded through
- *   unchanged (no timer is set up).
+ *   unchanged (no timer is set up). Positive values below
+ *   `MIN_IDLE_HEARTBEAT_MS` are raised to it.
  * @returns {AsyncGenerator<T | import('#core/events.js').IdleEvent>}
  */
 export async function * withIdleHeartbeat (source, idleMs) {
@@ -33,28 +43,45 @@ export async function * withIdleHeartbeat (source, idleMs) {
     return
   }
 
+  const tickMs = Math.max(idleMs, MIN_IDLE_HEARTBEAT_MS)
   const iter = source[Symbol.asyncIterator]()
   let lastAt = Date.now()
-  /** @type {Promise<IteratorResult<T>> | null} */
-  let pending = null
+
+  /** @type {{real: IteratorResult<T>} | {err: unknown} | null} */
+  let settled = null
+  /** @type {(() => void) | null} */
+  let wake = null
+  let inFlight = false
+
+  const park = (result) => {
+    settled = result
+    const w = wake
+    wake = null
+    w?.()
+  }
 
   try {
     while (true) {
-      if (!pending) pending = iter.next()
-
-      /** @type {NodeJS.Timeout | undefined} */
-      let timer
-      /** @type {{idle: true} | {real: IteratorResult<T>} | {err: unknown}} */
-      const winner = await new Promise(resolve => {
-        timer = setTimeout(() => resolve({ idle: true }), idleMs)
-        pending.then(
-          r => resolve({ real: r }),
-          e => resolve({ err: e })
+      if (!inFlight) {
+        inFlight = true
+        iter.next().then(
+          r => park({ real: r }),
+          e => park({ err: e })
         )
-      })
-      clearTimeout(timer)
+      }
+
+      if (!settled) {
+        /** @type {NodeJS.Timeout | undefined} */
+        let timer
+        await new Promise(resolve => {
+          wake = resolve
+          timer = setTimeout(resolve, tickMs)
+        })
+        clearTimeout(timer)
+        wake = null
+      }
 
-      if ('idle' in winner) {
+      if (!settled) {
         yield /** @type {import('#core/events.js').IdleEvent} */ ({
           type: 'idle',
           sinceMs: Date.now() - lastAt
@@ -62,11 +89,13 @@ export async function * withIdleHeartbeat (source, idleMs) {
         continue
       }
 
-      pending = null
-      if ('err' in winner) throw winner.err
-      if (winner.real.done) return
+      const done = settled
+      settled = null
+      inFlight = false
+      if ('err' in done) throw done.err
+      if (done.real.done) return
       lastAt = Date.now()
-      yield winner.real.value
+      yield done.real.value
     }
   } finally {
     // Best-effort cleanup if the consumer abandons us mid-stream.

package/js/session/adapters/_errors.js

@@ -417,3 +417,38 @@ export function classifyProviderError (e, key, opts = {}) {
     detail
   }
 }
+
+/**
+ * Wrap a `TypedError` payload in a throwable `Error`. Adapters that
+ * fetch directly (rather than through a provider SDK) throw these; the
+ * run loop lifts `.typed` onto the terminal error event.
+ *
+ * @param {string} message
+ * @param {string} type
+ * @param {boolean} retryable
+ * @param {string} [detail]
+ * @returns {Error & {typed: import('#core/errors.js').TypedError}}
+ */
+export function typedError (message, type, retryable, detail) {
+  const err = new Error(message)
+  /** @type {import('#core/errors.js').TypedError} */
+  const typed = { message, severity: retryable ? 'warn' : 'error', retryable, type }
+  if (detail) typed.detail = detail
+  return Object.assign(err, { typed })
+}
+
+/**
+ * Classify an HTTP status, keeping the classifier's stable message and
+ * routing the caller's context plus any response-body snippet into
+ * `detail` — provider response bodies must never reach
+ * `TypedError.message`.
+ *
+ * @param {number} status
+ * @param {string} message
+ * @param {string} [detail]
+ * @returns {Error & {typed: import('#core/errors.js').TypedError}}
+ */
+export function fromHttpStatus (status, message, detail) {
+  const typed = classifyProviderError({ status })
+  return typedError(typed.message, typed.type, typed.retryable, detail ? `${message}: ${detail}` : message)
+}

package/js/session/adapters/_lazy_json_cache.js

@@ -14,9 +14,12 @@
  *     hook for deployments that source config from elsewhere).
  *   - `get(key)` — read-through; loads synchronously on first miss.
  *
- * A malformed / missing / non-object file resolves to the supplied
- * `defaultValue` (default `{}`) so callers never have to handle
- * file-absence explicitly.
+ * A missing file resolves to the supplied `defaultValue` (default
+ * `{}`) so callers never have to handle file-absence explicitly. A
+ * file that exists but does not parse throws: absent config is a
+ * runtime state, corrupt config is a bug, and collapsing the two
+ * turns a typo in `curated.json` into `Unknown model` on every call
+ * with nothing naming the real cause.
  *
  * @module session/adapters/_lazy_json_cache
  */
@@ -40,24 +43,42 @@ export function createLazyJsonFileCache (pathFn, { defaultValue = /** @type {any
     return /** @type {V} */(parsed)
   }
 
+  /** @param {string} file */
+  function parseOrThrow (text, file) {
+    try {
+      return normalize(JSON.parse(text))
+    } catch (e) {
+      throw new Error(`[mohdel] ${file} is not valid JSON: ${e.message}`, { cause: e })
+    }
+  }
+
   /** @param {string} [p] */
   function loadSync (p) {
     const file = p ?? pathFn()
+    let text
     try {
-      return normalize(JSON.parse(fs.readFileSync(file, 'utf8')))
-    } catch {
-      return defaultValue
+      text = fs.readFileSync(file, 'utf8')
+    } catch (e) {
+      if (e.code === 'ENOENT') return defaultValue
+      throw e
     }
+    return parseOrThrow(text, file)
   }
 
   async function initAsync () {
     if (active !== null) return
+    const file = pathFn()
+    let text
     try {
-      const text = await fs.promises.readFile(pathFn(), 'utf8')
-      active = normalize(JSON.parse(text))
-    } catch {
-      active = defaultValue
+      text = await fs.promises.readFile(file, 'utf8')
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        active = defaultValue
+        return
+      }
+      throw e
     }
+    active = parseOrThrow(text, file)
   }
 
   /** @param {V} table */

package/js/session/adapters/_media.js

@@ -10,8 +10,10 @@
  */
 
 import { readFile as fsReadFile, realpath as fsRealpath, stat as fsStat } from 'node:fs/promises'
-import { fileURLToPath } from 'node:url'
 import { delimiter, isAbsolute, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { typedError } from './_errors.js'
 
 export const MEDIA_MAX_BYTES = 64 * 1024 * 1024
 
@@ -58,11 +60,7 @@ export function mediaScheme (uri) {
  * @returns {Error & {typed: import('#core/errors.js').TypedError}}
  */
 export function mediaError (message, type, detail) {
-  const err = new Error(message)
-  /** @type {import('#core/errors.js').TypedError} */
-  const typed = { message, severity: 'error', retryable: false, type }
-  if (detail) typed.detail = detail
-  return Object.assign(err, { typed })
+  return typedError(message, type, false, detail)
 }
 
 /**

package/js/session/adapters/_videos.js

@@ -77,11 +77,39 @@ async function hashFile (filePath) {
   return h.digest('hex')
 }
 
+/**
+ * Provider file handles expire server-side — Gemini's Files API keeps
+ * an upload about 48h — while a cache entry would live forever. An
+ * entry outliving its handle is worse than a cache miss: the upload is
+ * skipped and the provider rejects a URI it no longer knows.
+ */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000
+
+/** Bound on retained entries; the file is rewritten whole on each save. */
+const CACHE_MAX_ENTRIES = 500
+
+/**
+ * @param {Record<string, UploadedFileRecord>} cache
+ * @returns {Record<string, UploadedFileRecord>}
+ */
+function prune (cache) {
+  const cutoff = Date.now() - CACHE_TTL_MS
+  const live = Object.entries(cache).filter(([, e]) => {
+    const at = Date.parse(e?.cachedAt ?? '')
+    return Number.isFinite(at) && at >= cutoff
+  })
+  if (live.length <= CACHE_MAX_ENTRIES) return Object.fromEntries(live)
+  live.sort((a, b) => Date.parse(b[1].cachedAt) - Date.parse(a[1].cachedAt))
+  return Object.fromEntries(live.slice(0, CACHE_MAX_ENTRIES))
+}
+
 async function loadCache () {
   try {
     if (!existsSync(CACHE_PATH)) return {}
     const text = await fs.readFile(CACHE_PATH, 'utf8')
-    return JSON.parse(text)
+    const parsed = JSON.parse(text)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+    return prune(parsed)
   } catch {
     return {}
   }
@@ -90,7 +118,7 @@ async function loadCache () {
 async function saveCache (cache) {
   try {
     await ensureCacheDir()
-    await fs.writeFile(CACHE_PATH, JSON.stringify(cache, null, 2))
+    await fs.writeFile(CACHE_PATH, JSON.stringify(prune(cache), null, 2))
   } catch {
     // cache write failures shouldn't bring down a call
   }

package/js/session/adapters/image/novita.js

@@ -11,7 +11,7 @@
  */
 
 import { getSpec } from '../_catalog.js'
-import { classifyProviderError } from '../_errors.js'
+import { classifyProviderError, fromHttpStatus, typedError } from '../_errors.js'
 import { catalogKey } from '#core/model-id.js'
 
 const BASE_URL = 'https://api.novita.ai'
@@ -118,19 +118,3 @@ async function pollTaskResult (fetchFn, sleep, now, taskId, apiKey) {
 
   throw typedError('novita image generation timed out', 'PROVIDER_UNAVAILABLE', true)
 }
-
-function fromHttpStatus (status, message, detail) {
-  const typed = classifyProviderError({ status })
-  // Keep the classifier's message (stable/machine-readable); put the
-  // caller's context + any response-body snippet into `detail`. Never
-  // echo provider response bodies into `TypedError.message`.
-  return typedError(typed.message, typed.type, typed.retryable, detail ? `${message}: ${detail}` : message)
-}
-
-function typedError (message, type, retryable, detail) {
-  const err = new Error(message)
-  const typed = { message, severity: retryable ? 'warn' : 'error', retryable, type }
-  if (detail) typed.detail = detail
-  err.typed = typed
-  return err
-}

package/js/session/adapters/transcription/openai_compatible.js

@@ -21,7 +21,7 @@
 import { basename } from 'node:path'
 
 import { getSpec } from '../_catalog.js'
-import { classifyProviderError } from '../_errors.js'
+import { classifyProviderError, fromHttpStatus, typedError } from '../_errors.js'
 import { dataUriPayload, isTrustedMedia, mediaScheme, readLocalMedia } from '../_media.js'
 import { computeTranscriptionCost } from '../_pricing.js'
 import { catalogKey, bareOf } from '#core/model-id.js'
@@ -150,18 +150,3 @@ export async function loadAudio (audio, opts = {}) {
     false
   )
 }
-
-function fromHttpStatus (status, message, detail) {
-  const typed = classifyProviderError({ status })
-  // Keep the classifier's message (stable/machine-readable); response
-  // body snippets go to `detail` only.
-  return typedError(typed.message, typed.type, typed.retryable, detail ? `${message}: ${detail}` : message)
-}
-
-function typedError (message, type, retryable, detail) {
-  const err = new Error(message)
-  const typed = { message, severity: retryable ? 'warn' : 'error', retryable, type }
-  if (detail) typed.detail = detail
-  err.typed = typed
-  return err
-}

package/js/session/driver.js

@@ -12,6 +12,9 @@
  * @module session/driver
  */
 
+import { once } from 'node:events'
+
+import { MAX_LINE_BYTES, exceedsLineBytes } from '#core/framing.js'
 import { run } from './run.js'
 import { runImage } from './run_image.js'
 import { runTranscription } from './run_transcription.js'
@@ -48,6 +51,34 @@ export async function drive (stdin, stdout) {
     precancelled.add(callId)
   }
 
+  /**
+   * Write one NDJSON frame, pausing on a full pipe. A fast adapter
+   * feeding a slow gate reader would otherwise grow Node's internal
+   * write buffer without bound, since `for await` keeps pulling events
+   * regardless of whether the previous one reached the socket.
+   *
+   * @param {unknown} payload
+   */
+  async function writeLine (payload) {
+    if (!stdout.write(JSON.stringify(payload) + '\n')) {
+      await once(stdout, 'drain')
+    }
+  }
+
+  function stdinMalformed (detail) {
+    process.stderr.write(`session: ${detail}; exiting\n`)
+    const error = {
+      message: 'unusable stdin line',
+      detail,
+      severity: 'error',
+      retryable: false,
+      type: 'SESSION_STDIN_MALFORMED'
+    }
+    stdout.write(JSON.stringify({ type: 'error', error }) + '\n')
+    framingError = Object.assign(new Error('SESSION_STDIN_MALFORMED'), { detail })
+    if (queueNotify) { queueNotify(); queueNotify = null }
+  }
+
   const onLine = (line) => {
     if (framingError) return
     const trimmed = line.trim()
@@ -57,17 +88,7 @@ export async function drive (stdin, stdout) {
     try {
       obj = JSON.parse(trimmed)
     } catch (e) {
-      process.stderr.write(`session: malformed stdin line, exiting: ${e.message}\n`)
-      const error = {
-        message: 'SESSION_STDIN_MALFORMED',
-        detail: `stdin line is not valid JSON: ${e.message}`,
-        severity: 'error',
-        retryable: false,
-        type: 'SESSION_STDIN_MALFORMED'
-      }
-      stdout.write(JSON.stringify({ type: 'error', error }) + '\n')
-      framingError = Object.assign(new Error(error.message), { detail: error.detail })
-      if (queueNotify) { queueNotify(); queueNotify = null }
+      stdinMalformed(`stdin line is not valid JSON: ${e.message}`)
       return
     }
 
@@ -82,18 +103,6 @@ export async function drive (stdin, stdout) {
       return
     }
 
-    // Readiness heartbeat from supervisor: the pool sends `ping`
-    // before marking a fresh session "pool-ready". Reply immediately
-    // with `pong` on stdout — emitted as a standalone control frame,
-    // outside any in-flight call's event stream.
-    //
-    // Current protocol pings only between calls. If a supervisor
-    // violates that invariant and pings a busy session, emitting
-    // `{op:"pong"}` mid-stream would land in the gate's
-    // `pool_stream_next` read buffer, fail Event parse, and get
-    // classified as `SESSION_INVALID_EVENT` — killing the session.
-    // Drop mid-call pings; the supervisor can re-ping after the
-    // call terminates.
     // Catalog injection from the supervisor. Supersedes whatever was
     // loaded from disk at startup. Lets a supervisor (e.g. a
     // thin-gate session pool) run sessions in contexts without
@@ -108,6 +117,18 @@ export async function drive (stdin, stdout) {
       return
     }
 
+    // Readiness heartbeat from supervisor: the pool sends `ping`
+    // before marking a fresh session "pool-ready". Reply immediately
+    // with `pong` on stdout — emitted as a standalone control frame,
+    // outside any in-flight call's event stream.
+    //
+    // Current protocol pings only between calls. If a supervisor
+    // violates that invariant and pings a busy session, emitting
+    // `{op:"pong"}` mid-stream would land in the gate's
+    // `pool_stream_next` read buffer, fail Event parse, and get
+    // classified as `SESSION_INVALID_EVENT` — killing the session.
+    // Drop mid-call pings; the supervisor can re-ping after the
+    // call terminates.
     if (obj && typeof obj === 'object' && obj.op === 'ping') {
       if (currentCall) {
         process.stderr.write(
@@ -119,6 +140,19 @@ export async function drive (stdin, stdout) {
       return
     }
 
+    // Parseable JSON is not yet a usable envelope: `null`, an array or
+    // a bare scalar would reach the dispatch loop and throw on
+    // `envelope.callId`, killing the process with no terminal event.
+    // PROTOCOL.md §3 requires a terminal `error` for unusable stdin.
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+      stdinMalformed(`stdin line is not an envelope object (got ${obj === null ? 'null' : Array.isArray(obj) ? 'array' : typeof obj})`)
+      return
+    }
+    if (typeof obj.callId !== 'string' || !obj.callId) {
+      stdinMalformed('envelope is missing a string `callId`')
+      return
+    }
+
     envelopeQueue.push(obj)
     if (queueNotify) { queueNotify(); queueNotify = null }
   }
@@ -133,6 +167,13 @@ export async function drive (stdin, stdout) {
       stdinBuf = stdinBuf.slice(nl + 1)
       onLine(line)
     }
+    // The gate caps what it reads *from* a session; nothing capped what
+    // a session accepts, so a supervisor streaming a newline-less line
+    // grew this buffer without bound.
+    if (!framingError && exceedsLineBytes(stdinBuf)) {
+      stdinBuf = ''
+      stdinMalformed(`stdin line exceeds ${MAX_LINE_BYTES} bytes without newline`)
+    }
   })
   stdin.on('end', () => {
     if (stdinBuf) onLine(stdinBuf)
@@ -166,9 +207,9 @@ export async function drive (stdin, stdout) {
         const { op: _op, ...imgEnv } = envelope
         const out = await runImage(imgEnv)
         if (out.ok) {
-          stdout.write(JSON.stringify({ type: 'image_done', result: out.result }) + '\n')
+          await writeLine({ type: 'image_done', result: out.result })
         } else {
-          stdout.write(JSON.stringify({ type: 'error', error: out.error }) + '\n')
+          await writeLine({ type: 'error', error: out.error })
         }
       } else if (envelope.op === 'transcription') {
         // Same one-shot contract as the image path; shape matches
@@ -176,13 +217,13 @@ export async function drive (stdin, stdout) {
         const { op: _op, ...trEnv } = envelope
         const out = await runTranscription(trEnv)
         if (out.ok) {
-          stdout.write(JSON.stringify({ type: 'transcription_done', result: out.result }) + '\n')
+          await writeLine({ type: 'transcription_done', result: out.result })
         } else {
-          stdout.write(JSON.stringify({ type: 'error', error: out.error }) + '\n')
+          await writeLine({ type: 'error', error: out.error })
         }
       } else {
         for await (const ev of run(envelope, { signal: controller.signal })) {
-          stdout.write(JSON.stringify(ev) + '\n')
+          await writeLine(ev)
         }
       }
     } finally {

package/js/session/run.js

@@ -29,7 +29,7 @@ import { getProviderLimits } from './adapters/_providers.js'
 import { providerOf, catalogKey, effortOf } from '#core/model-id.js'
 import * as defaultCooldown from './_cooldown.js'
 import * as defaultLimiter from './_rate_limiter.js'
-import { withIdleHeartbeat } from './_idle_heartbeat.js'
+import { withIdleHeartbeat, MIN_IDLE_HEARTBEAT_MS } from './_idle_heartbeat.js'
 import { logger as defaultLogger } from './_logger.js'
 import {
   startSpan,
@@ -176,6 +176,12 @@ export async function * run (envelope, {
   let lastFrameAt = startedAt
   let maxInterFrameMs = 0
   try {
+    if (envelope.idleHeartbeatMs > 0 && envelope.idleHeartbeatMs < MIN_IDLE_HEARTBEAT_MS) {
+      log.warn(
+        { requested: envelope.idleHeartbeatMs, applied: MIN_IDLE_HEARTBEAT_MS },
+        '[mohdel:answer] idleHeartbeatMs raised to the floor'
+      )
+    }
     const adapterStream = adapter(envelope, { signal, log, span })
     const heartbeated = withIdleHeartbeat(adapterStream, envelope.idleHeartbeatMs)
     for await (const ev of heartbeated) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mohdel",
-  "version": "0.118.0",
+  "version": "0.119.0",
   "license": "MIT",
   "author": {
     "name": "Christophe Le Bars",
@@ -8,6 +8,27 @@
   },
   "description": "Self-hosted LLM gateway and SDK for Node — a LiteLLM-style unified API for 11 providers (Anthropic, OpenAI, Gemini, Mistral, Groq, xAI, DeepSeek, OpenRouter, …) with per-call USD cost tracking, streaming, tool calls, vision, speech-to-text, and built-in OpenTelemetry. Run in-process, or behind the process-isolated thin-gate for fault containment.",
   "type": "module",
+  "keywords": [
+    "llm",
+    "llm-gateway",
+    "ai-gateway",
+    "ai-sdk",
+    "openai",
+    "anthropic",
+    "claude",
+    "gemini",
+    "mistral",
+    "groq",
+    "deepseek",
+    "openrouter",
+    "streaming",
+    "tool-calling",
+    "token-cost",
+    "rate-limiting",
+    "opentelemetry",
+    "self-hosted",
+    "cli"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/clbrge/mohdel.git"
@@ -86,26 +107,26 @@
     "@clack/prompts": "^1.7.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.221.0",
     "@opentelemetry/sdk-node": "^0.221.0",
-    "chalk": "^5.4.0",
-    "mohdel-thin-gate-linux-x64-gnu": "0.118.0"
+    "chalk": "^6.0.0",
+    "mohdel-thin-gate-linux-x64-gnu": "0.119.0"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.115.0",
     "@cerebras/cerebras_cloud_sdk": "^1.91.0",
-    "@google/genai": "^2.13.0",
+    "@google/genai": "^2.16.0",
     "@opentelemetry/api": "^1.9.1",
     "env-paths": "^4.0.0",
-    "groq-sdk": "^1.4.0",
-    "openai": "^6.49.0",
-    "undici": "^7.24.5"
+    "groq-sdk": "^1.5.0",
+    "openai": "^7.4.0",
+    "undici": "^7.29.0"
   },
   "lint-staged": {
     "*.{js,cjs}": "standard"
   },
   "devDependencies": {
     "gpt-tokenizer": "^3.4.0",
-    "lint-staged": "^17.2.0",
-    "release-it": "^20.2.1",
+    "lint-staged": "^17.3.0",
+    "release-it": "^21.0.1",
     "standard": "^17.1.2",
     "vitest": "^4.1.10"
   }

package/src/cli/_chalk.js

@@ -0,0 +1,41 @@
+/**
+ * Chalk, or an uncoloured stand-in when it is absent.
+ *
+ * `chalk` is an `optionalDependency`, so npm skips it on an engine
+ * mismatch or `--no-optional` without failing the install. A static
+ * import would then take the whole CLI down at load time instead of
+ * dropping colour, which is the only thing actually lost. Dynamic
+ * import is the exception the style rule allows: an optional package
+ * cannot be resolved statically.
+ *
+ * The stand-in has to be callable *and* chainable, because call sites
+ * use both `dim('x')` and `bold.red('x')`.
+ *
+ * @module cli/_chalk
+ */
+
+const identity = (s) => String(s)
+
+/** @type {any} */
+const plain = new Proxy(identity, {
+  get (target, prop, receiver) {
+    // Symbols and function internals must resolve on the function
+    // itself; returning the chain proxy for `Symbol.toPrimitive` or
+    // `util.inspect.custom` breaks string coercion and console output.
+    if (typeof prop === 'symbol' || prop in Function.prototype) {
+      return Reflect.get(target, prop, receiver)
+    }
+    return plain
+  }
+})
+
+/** @type {any} */
+let chalk
+try {
+  chalk = (await import('chalk')).default
+} catch {
+  chalk = plain
+}
+
+export const isColorAvailable = chalk !== plain
+export default chalk

package/src/cli/colored-logger.js

@@ -10,7 +10,7 @@
  * @module cli/colored-logger
  */
 
-import chalk from 'chalk'
+import chalk from './_chalk.js'
 
 const noop = () => {}
 

package/src/cli/colors.js

@@ -1,5 +1,5 @@
 // Semantic color roles for CLI output.
-import chalk from 'chalk'
+import chalk from './_chalk.js'
 
 export const id = chalk.cyan // model IDs, provider names
 export const label = chalk.bold // display names, titles

package/src/cli/onboard.js

@@ -107,6 +107,8 @@ function getConfiguredProviders () {
   return { configured, unconfigured }
 }
 
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
 async function appendToEnvFile (key, value) {
   const dir = dirname(ENV_PATH)
   if (!existsSync(dir)) await mkdir(dir, { recursive: true })
@@ -114,10 +116,13 @@ async function appendToEnvFile (key, value) {
   let content = ''
   if (existsSync(ENV_PATH)) {
     content = await readFile(ENV_PATH, 'utf8')
-    // Replace existing line if present
-    const re = new RegExp(`^${key}=.*$`, 'm')
+    // Replace existing line if present. The replacement is a function
+    // because `$&`, `` $` ``, `$'` and `$1` are expanded inside a
+    // replacement *string* — a pasted key containing any of them would
+    // be silently rewritten before it hit disk.
+    const re = new RegExp(`^${escapeRegExp(key)}=.*$`, 'm')
     if (re.test(content)) {
-      content = content.replace(re, `${key}=${value}`)
+      content = content.replace(re, () => `${key}=${value}`)
       await writeFile(ENV_PATH, content, { mode: 0o600 })
       chmodSync(ENV_PATH, 0o600)
       return

package/src/lib/cache.js

@@ -1,76 +1,3 @@
-import { createHash } from 'crypto'
-import { join } from 'path'
-import { readFile, writeFile, mkdir, stat } from 'fs/promises'
-import { existsSync } from 'fs'
 import envPaths from 'env-paths'
-import { silent } from './logger.js'
 
 export const CACHE_DIR = envPaths('mohdel', { suffix: null }).cache
-export const FILE_CACHE_PATH = join(CACHE_DIR, 'uploaded-files.json')
-
-const ensureCacheDir = async () => {
-  if (!existsSync(CACHE_DIR)) {
-    await mkdir(CACHE_DIR, { recursive: true })
-  }
-}
-
-const createFileHash = async (filePath) => {
-  const data = await readFile(filePath)
-  const stats = await stat(filePath)
-  const hash = createHash('sha256')
-  hash.update(data)
-  hash.update(filePath)
-  hash.update(stats.mtime.toISOString())
-  return hash.digest('hex')
-}
-
-export const loadFileCache = async (logger = silent) => {
-  try {
-    await ensureCacheDir()
-    if (!existsSync(FILE_CACHE_PATH)) {
-      return {}
-    }
-    const content = await readFile(FILE_CACHE_PATH, 'utf8')
-    return JSON.parse(content)
-  } catch (err) {
-    logger.warn({ err }, '[mohdel:cache] failed to load file cache')
-    return {}
-  }
-}
-
-export const saveFileCache = async (cache, logger = silent) => {
-  try {
-    await ensureCacheDir()
-    await writeFile(FILE_CACHE_PATH, JSON.stringify(cache, null, 2))
-  } catch (err) {
-    logger.error({ err }, '[mohdel:cache] failed to save file cache')
-  }
-}
-
-export const getCachedFileData = async (filePath, provider = 'gemini', logger = silent) => {
-  try {
-    const hash = await createFileHash(filePath)
-    const cache = await loadFileCache(logger)
-    return cache[`${provider}:${hash}`]
-  } catch (err) {
-    logger.warn({ err }, '[mohdel:cache] failed to get cached file ID')
-    return null
-  }
-}
-
-export const setCachedFileData = async (filePath, data, provider = 'gemini', logger = silent) => {
-  try {
-    const hash = await createFileHash(filePath)
-    const cache = await loadFileCache(logger)
-    cache[`${provider}:${hash}`] = {
-      hash,
-      data,
-      filePath,
-      provider,
-      cachedAt: new Date().toISOString()
-    }
-    await saveFileCache(cache, logger)
-  } catch (err) {
-    logger.error({ err }, '[mohdel:cache] failed to set cached file data')
-  }
-}

package/src/lib/catalog/gemini.js

@@ -5,10 +5,11 @@ const fetchModels = async ({ apiKey }) => {
   let pageToken = null
   while (true) {
     const url = new URL(`${BASE_URL}/models`)
-    url.searchParams.set('key', apiKey)
     url.searchParams.set('pageSize', '1000')
     if (pageToken) url.searchParams.set('pageToken', pageToken)
-    const res = await fetch(url)
+    // Header, not `?key=`: query strings are recorded verbatim by
+    // proxies, CDNs and server access logs.
+    const res = await fetch(url, { headers: { 'x-goog-api-key': apiKey } })
     if (!res.ok) throw new Error(`${res.status} ${res.statusText} fetching ${url.pathname}`)
     const body = await res.json()
     const page = Array.isArray(body?.models) ? body.models : []

package/src/lib/common.js

@@ -101,6 +101,13 @@ const rotateBackup = async (filePath) => {
 
 export const BACKUP_SLOTS = ['prev', 'daily', 'weekly']
 
+export class ConfigParseError extends Error {
+  constructor (message, options) {
+    super(message, options)
+    this.name = 'ConfigParseError'
+  }
+}
+
 const createFileOperation = (filePath, defaultValue = {}, operationType) => {
   const loadHandler = async () => {
     let loadedData
@@ -118,7 +125,14 @@ const createFileOperation = (filePath, defaultValue = {}, operationType) => {
         }
       } else {
         const fileContent = await readFile(filePath, 'utf8')
-        loadedData = JSON.parse(fileContent)
+        try {
+          loadedData = JSON.parse(fileContent)
+        } catch (e) {
+          throw new ConfigParseError(
+            `[mohdel:common] ${filePath} is not valid JSON: ${e.message}`,
+            { cause: e }
+          )
+        }
       }
 
       if (typeof loadedData === 'object' && loadedData !== null && !Array.isArray(loadedData)) {
@@ -158,6 +172,11 @@ const createFileOperation = (filePath, defaultValue = {}, operationType) => {
 
       return loadedData
     } catch (err) {
+      // A file that exists but does not parse is corrupt state, not an
+      // absent-config runtime branch. Falling back would make it read
+      // as empty and surface later as `Unknown model`, and this warn
+      // goes to `silent` unless the embedder wired a logger.
+      if (err instanceof ConfigParseError) throw err
       moduleLogger.warn(`[mohdel:common] failed to load ${operationType}: ${err.message}`)
       return JSON.parse(JSON.stringify(defaultValue || {}))
     }

package/src/lib/providers.js

@@ -74,18 +74,7 @@ const providers = {
   openrouter: {
     sdk: 'openrouter',
     apiKeyEnv: 'OPENROUTER_API_SK',
-    createConfiguration: apiKey => {
-      // Optional OpenRouter attribution headers — only sent when the
-      // embedder opts in via env. No defaults.
-      const defaultHeaders = {}
-      if (process.env.OPENROUTER_REFERER) defaultHeaders['HTTP-Referer'] = process.env.OPENROUTER_REFERER
-      if (process.env.OPENROUTER_TITLE) defaultHeaders['X-Title'] = process.env.OPENROUTER_TITLE
-      return {
-        baseURL: 'https://openrouter.ai/api/v1',
-        apiKey,
-        defaultHeaders
-      }
-    },
+    createConfiguration: apiKey => ({ baseURL: 'https://openrouter.ai/api/v1', apiKey }),
     creators: []
   },
   qwen: {