mohdel 0.117.3 → 0.119.0

package/js/factory/bridge.js

@@ -23,7 +23,8 @@
 import { run } from '../session/run.js'
 import { runImage } from '../session/run_image.js'
 import { runTranscription } from '../session/run_transcription.js'
-import { MohdelError, Severity } from '../../src/lib/errors.js'
+import { markTrustedMedia } from '../session/adapters/_media.js'
+import { MohdelError, validateIds } from '#core'
 import { createRealtimeDeltaBuffer } from '../../src/lib/utils.js'
 
 /**
@@ -60,20 +61,20 @@ import { createRealtimeDeltaBuffer } from '../../src/lib/utils.js'
  * | `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)            |
+ * | **`configuration.baseURL` / `defaultHeaders` / …**| **rejected** — adapters own baseURL                  |
  *
  * @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 {any} args.configuration    Provider config. Only `apiKey` is threaded; other fields are rejected.
  * @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({ modelKey, configuration, prompt, options })
+  const envelope = markTrustedMedia(toEnvelope({ modelKey, configuration, prompt, options }))
 
   // If the caller passed a `realtimeHandler`, feed every `delta`
   // event into a buffer that invokes the handler on batches matching
@@ -81,7 +82,7 @@ export async function runAnswer ({ provider, model, modelKey, configuration, pro
   // 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
+  // Skip the buffer allocation entirely when no handler was
   // supplied — the common case.
   const deltaBuffer = options.realtimeHandler
     ? createRealtimeDeltaBuffer(options.realtimeHandler, options.bufferOpts)
@@ -105,15 +106,14 @@ export async function runAnswer ({ provider, model, modelKey, configuration, pro
   }
 
   if (!terminal) {
-    throw new MohdelError('SESSION_NO_TERMINAL', {
-      severity: Severity.ERROR,
-      detail: 'session run produced no terminal event',
+    throw new MohdelError('session run produced no terminal event', {
+      type: 'SESSION_NO_TERMINAL',
       retryable: false
     })
   }
 
   if (terminal.type === 'error') {
-    throw fromTypedError(terminal.error, { provider, model, modelKey })
+    throw MohdelError.fromJSON(terminal.error, { provider, model, modelKey })
   }
 
   return terminal.result
@@ -135,9 +135,13 @@ export async function runAnswer ({ provider, model, modelKey, configuration, pro
  * @returns {Promise<any>}
  */
 export async function runAnswerImage ({ provider, model, configuration, prompt, options = {}, spec }) {
+  const callId = options.callId || newCallId()
+  const authId = options.authId || 'local'
+  assertValidIds(callId, authId, `${provider}/${model}`)
+
   const envelope = {
-    callId: options.callId || newCallId(),
-    authId: options.authId || 'local',
+    callId,
+    authId,
     auth: configToAuth(configuration),
     model: `${provider}/${model}`,
     prompt
@@ -145,8 +149,8 @@ export async function runAnswerImage ({ provider, model, configuration, 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 })
+  const out = await runImage(markTrustedMedia(envelope), spec ? { spec } : {})
+  if (!out.ok) throw MohdelError.fromJSON(out.error, { provider, model })
   return out.result
 }
 
@@ -168,9 +172,13 @@ export async function runAnswerImage ({ provider, model, configuration, prompt,
  * @returns {Promise<any>}
  */
 export async function runAnswerTranscription ({ provider, model, configuration, audio, options = {}, spec }) {
+  const callId = options.callId || newCallId()
+  const authId = options.authId || 'local'
+  assertValidIds(callId, authId, `${provider}/${model}`)
+
   const envelope = {
-    callId: options.callId || newCallId(),
-    authId: options.authId || 'local',
+    callId,
+    authId,
     auth: configToAuth(configuration),
     model: `${provider}/${model}`,
     audio
@@ -178,8 +186,8 @@ export async function runAnswerTranscription ({ provider, model, configuration,
   if (options.language) envelope.language = options.language
   if (options.prompt) envelope.prompt = options.prompt
 
-  const out = await runTranscription(envelope, spec ? { spec } : {})
-  if (!out.ok) throw fromTypedError(out.error, { provider, model })
+  const out = await runTranscription(markTrustedMedia(envelope), spec ? { spec } : {})
+  if (!out.ok) throw MohdelError.fromJSON(out.error, { provider, model })
   return out.result
 }
 
@@ -196,12 +204,16 @@ export async function runAnswerTranscription ({ provider, model, configuration,
  * @returns {import('#core/envelope.js').CallEnvelope}
  */
 function toEnvelope ({ modelKey, configuration, prompt, options }) {
+  const callId = options.callId || newCallId()
+  const authId = options.authId || 'local'
+  assertValidIds(callId, authId, modelKey)
+
   /** @type {import('#core/envelope.js').CallEnvelope} */
   const envelope = {
-    callId: options.callId || newCallId(),
-    authId: options.authId || 'local',
+    callId,
+    authId,
     auth: configToAuth(configuration),
-    model: /** @type {import('#core/model-id.js').ModelId} */ (modelKey),
+    model: modelKey,
     prompt: toEnvelopePrompt(prompt)
   }
 
@@ -237,36 +249,18 @@ function toEnvelope ({ modelKey, configuration, prompt, options }) {
 }
 
 /**
- * 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}
+ * @param {string} callId
+ * @param {string} authId
+ * @param {string} model
  */
-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 assertValidIds (callId, authId, model) {
+  const reason = validateIds(callId, authId, model)
+  if (reason) {
+    throw new MohdelError('invalid envelope', {
+      type: 'PROTOCOL_INVALID_ENVELOPE',
+      detail: reason,
+      retryable: false
+    })
   }
 }
 
@@ -287,12 +281,12 @@ 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) {
-    throw new MohdelError('CONFIGURATION_UNSUPPORTED', {
-      severity: Severity.ERROR,
+    throw new MohdelError('unsupported per-call configuration', {
+      type: 'CONFIGURATION_UNSUPPORTED',
       detail:
         'per-call SDK configuration is limited to `apiKey` and `baseURL`. ' +
         `Unsupported keys: ${unsupported.join(', ')}. ` +
@@ -372,8 +366,8 @@ function toEnvelopePrompt (prompt) {
   // 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,
+  throw new MohdelError('invalid prompt shape', {
+    type: 'SESSION_INVALID_PROMPT',
     retryable: false,
     detail:
       'prompt must be a string, a Message[] array, ' +

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/_cancelled.js

@@ -3,7 +3,7 @@
  * a terminal `done` event on `signal.aborted` mid-stream.
  *
  * Three adapters (openai, anthropic, gemini) had byte-identical
- * copies of this before F58; consolidated here. `_chat_completions.js`
+ * copies of this; consolidated here. `_chat_completions.js`
  * and `run.js` have their own cancel paths — don't migrate them
  * here unless you're certain the shape matches (thinkingTokens,
  * cost, tool_calls semantics can all differ).

package/js/session/adapters/_chat_completions.js

@@ -142,7 +142,7 @@ async function * runStreaming (envelope, client, args, config, start, deps) {
   args.stream = true
   args.stream_options = { include_usage: true }
 
-  // F53: accumulate via array + join to avoid per-delta V8 cons-string
+  // Accumulate via array + join to avoid per-delta V8 cons-string
   // churn on long streams.
   const contentParts = []
   const reasoningParts = []

package/js/session/adapters/_errors.js

@@ -32,13 +32,6 @@
 
 const DETAIL_CAP = 500
 
-/**
- * Extract a short human-readable detail from an SDK error. Trimmed
- * to `DETAIL_CAP` chars so a verbose provider body doesn't blow up
- * log pipelines.
- * @param {any} err
- * @returns {string | undefined}
- */
 /**
  * Replace verbatim occurrences of `key` in `detail` with a masked
  * form. Long keys (≥ 16 chars) become `<first4>…<last4>` so a caller
@@ -60,6 +53,13 @@ function scrubKey (detail, key) {
   return detail.split(key).join(mask)
 }
 
+/**
+ * Extract a short human-readable detail from an SDK error. Trimmed
+ * to `DETAIL_CAP` chars so a verbose provider body doesn't blow up
+ * log pipelines.
+ * @param {any} err
+ * @returns {string | undefined}
+ */
 function extractDetail (err) {
   if (!err) return undefined
   const nested = err.error?.message || err.response?.data?.error?.message
@@ -410,10 +410,45 @@ export function classifyProviderError (e, key, opts = {}) {
     }
   }
   return {
-    message: message ? String(message).slice(0, 200) : 'network error',
+    message: message ? scrubKey(String(message), key).slice(0, 200) : 'network error',
     severity: 'warn',
     retryable: true,
     type: 'NET_ERROR',
     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/_images.js

@@ -11,10 +11,16 @@
  * provider. Errors are surfaced — file IO failures bubble up so the
  * adapter can emit a typed error rather than silently skipping.
  *
+ * Local paths are resolved through `_media.js`, which owns symlink
+ * resolution, the `MOHDEL_MEDIA_ROOTS` confinement check and the read
+ * cap.
+ *
  * @module session/adapters/_images
  */
 
-import { readFile } from 'node:fs/promises'
+import { dataUriPayload, mediaError, mediaScheme, readLocalMedia } from './_media.js'
+
+const IMAGE_ERROR = 'SESSION_INVALID_IMAGE'
 
 /**
  * @typedef {object} LoadedImage
@@ -25,36 +31,39 @@ import { readFile } from 'node:fs/promises'
 
 /**
  * @param {Array<{fileUri: string, mimeType: string}>} images
+ * @param {{trusted?: boolean}} [opts]
  * @returns {Promise<LoadedImage[]>}
  */
-export async function loadImages (images) {
+export async function loadImages (images, opts = {}) {
   if (!images || !Array.isArray(images)) return []
   const out = []
   for (const img of images) {
     if (!img?.fileUri || !img?.mimeType) continue
-    out.push(await loadImage(img))
+    out.push(await loadImage(img, opts))
   }
   return out
 }
 
 /**
  * @param {{fileUri: string, mimeType: string}} image
+ * @param {{trusted?: boolean}} [opts]
  * @returns {Promise<LoadedImage>}
  */
-export async function loadImage (image) {
+export async function loadImage (image, opts = {}) {
   const { fileUri, mimeType } = image
-  if (fileUri.startsWith('file://')) {
-    const path = fileUri.replace(/^file:\/\//, '')
-    const buf = await readFile(path)
-    return { mimeType, base64: buf.toString('base64') }
-  }
-  if (fileUri.startsWith('data:')) {
-    const parts = fileUri.split(',')
-    if (parts.length > 1) return { mimeType, base64: parts[1] }
-    throw new Error(`malformed data URI: ${fileUri.slice(0, 32)}…`)
-  }
-  if (fileUri.startsWith('https://') || fileUri.startsWith('http://')) {
-    return { mimeType, url: fileUri }
+  switch (mediaScheme(fileUri)) {
+    case 'file': {
+      const { bytes } = await readLocalMedia(fileUri, { type: IMAGE_ERROR, trusted: opts.trusted })
+      return { mimeType, base64: bytes.toString('base64') }
+    }
+    case 'data':
+      return { mimeType, base64: dataUriPayload(fileUri, IMAGE_ERROR) }
+    case 'remote':
+      return { mimeType, url: fileUri }
+    default:
+      throw mediaError(
+        `unsupported image URI scheme: ${fileUri.slice(0, 32)}…`,
+        IMAGE_ERROR
+      )
   }
-  throw new Error(`unsupported image URI scheme: ${fileUri.slice(0, 32)}…`)
 }

package/js/session/adapters/_lazy_json_cache.js

@@ -1,8 +1,7 @@
 /**
  * Shared lazy-load-once JSON cache for config files under
  * `~/.config/mohdel/`. `_catalog.js` and `_providers.js` both had
- * byte-similar implementations before F62; this helper owns the
- * pattern.
+ * byte-similar implementations; this helper owns the pattern.
  *
  * Contract:
  *   - `loadSync(path?)` — synchronous read; used as the lazy
@@ -15,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
  */
@@ -41,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 */