mohdel 0.117.3 → 0.118.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.
 
@@ -240,7 +240,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

@@ -10,7 +10,7 @@
 
 import { requestUnix } from './transport.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 +31,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 }
       )
@@ -70,6 +70,7 @@ function parseErrorBody (body, status) {
   return {
     type: 'PROTOCOL_HTTP_ERROR',
     message: `thin-gate returned HTTP ${status}`,
+    severity: 'error',
     retryable: status >= 500
   }
 }

package/js/client/call_image.js

@@ -8,7 +8,7 @@
  */
 
 import { requestUnix } from './transport.js'
-import { MohdelTypedError } from '#core'
+import { MohdelError } from '#core'
 
 /**
  * @param {import('#core/image.js').ImageEnvelope} envelope
@@ -30,21 +30,21 @@ 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 }
     )
@@ -77,6 +77,7 @@ function parseErrorBody (body, status) {
   return {
     type: 'PROTOCOL_HTTP_ERROR',
     message: `thin-gate returned HTTP ${status}`,
+    severity: 'error',
     retryable: status >= 500
   }
 }

package/js/client/call_transcription.js

@@ -11,7 +11,7 @@
  */
 
 import { requestUnix } from './transport.js'
-import { MohdelTypedError } from '#core'
+import { MohdelError } from '#core'
 
 /**
  * @param {import('#core/transcription.js').TranscriptionEnvelope} envelope
@@ -33,21 +33,21 @@ 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 }
     )
@@ -80,6 +80,7 @@ function parseErrorBody (body, status) {
   return {
     type: 'PROTOCOL_HTTP_ERROR',
     message: `thin-gate returned HTTP ${status}`,
+    severity: 'error',
     retryable: status >= 500
   }
 }

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
@@ -155,3 +155,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/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

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
+    })
   }
 }
 
@@ -291,8 +285,8 @@ 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/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,7 +410,7 @@ 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',