mohdel 0.119.0 → 0.121.0

package/js/core/model-id.js

@@ -2,10 +2,10 @@
  * Model-id helpers.
  *
  * A mohdel model id is a single string of shape
- * `"<provider>/<bare>[:<effort>]"` — same on the wire and in-process.
- * See PROTOCOL §3. Nothing in mohdel ever holds the id in a split
- * object form; when the provider or bare part is needed, these
- * helpers return it as a substring.
+ * `"<provider>/<bare>[:<effort>][@<speed>]"` — same on the wire and
+ * in-process. See PROTOCOL §3. Nothing in mohdel ever holds the id in
+ * a split object form; when a part is needed, these helpers return it
+ * as a substring.
  *
  * Ids are validated at ingress by the gate
  * (`rust/thin-gate/src/protocol.rs::validate_ids`); these accessors
@@ -47,12 +47,8 @@ export function bareOf (model) {
  * @returns {string}
  */
 export function catalogKey (model) {
-  const colon = model.lastIndexOf(':')
-  const slash = model.indexOf('/')
-  // Only treat `:` as an effort separator when it appears after the
-  // provider slash (otherwise a model id without `/` that happens to
-  // contain `:` would get the wrong thing stripped).
-  return colon > slash ? model.slice(0, colon) : model
+  const base = beforeSuffix(model, SPEED_SIGIL)
+  return beforeSuffix(base, EFFORT_SIGIL)
 }
 
 /**
@@ -62,8 +58,46 @@ export function catalogKey (model) {
  * @returns {string | undefined}
  */
 export function effortOf (model) {
-  const colon = model.lastIndexOf(':')
+  return afterSuffix(beforeSuffix(model, SPEED_SIGIL), EFFORT_SIGIL)
+}
+
+/**
+ * Speed-lane suffix, without the `@`, or `undefined` if absent.
+ *
+ * @param {string} model
+ * @returns {string | undefined}
+ */
+export function speedOf (model) {
+  return afterSuffix(model, SPEED_SIGIL)
+}
+
+const EFFORT_SIGIL = ':'
+const SPEED_SIGIL = '@'
+
+/**
+ * Index of `sigil` when it separates a suffix, or `-1`. A sigil only
+ * separates when it falls after the provider slash, so a bare id that
+ * itself contains one is left whole.
+ *
+ * @param {string} model
+ * @param {string} sigil
+ * @returns {number}
+ */
+function suffixIndex (model, sigil) {
   const slash = model.indexOf('/')
-  if (colon <= slash) return undefined
-  return model.slice(colon + 1)
+  if (slash < 0) return -1
+  const at = model.lastIndexOf(sigil)
+  return at > slash ? at : -1
+}
+
+/** @returns {string} */
+function beforeSuffix (model, sigil) {
+  const at = suffixIndex(model, sigil)
+  return at < 0 ? model : model.slice(0, at)
+}
+
+/** @returns {string | undefined} */
+function afterSuffix (model, sigil) {
+  const at = suffixIndex(model, sigil)
+  return at < 0 ? undefined : model.slice(at + 1)
 }

package/js/factory/bridge.js

@@ -223,6 +223,7 @@ function toEnvelope ({ modelKey, configuration, prompt, options }) {
   if (options.outputType) envelope.outputType = options.outputType
   if (options.outputStyle) envelope.outputStyle = options.outputStyle
   if (options.outputEffort) envelope.outputEffort = options.outputEffort
+  if (options.speed) envelope.speed = options.speed
   if (options.images?.length) envelope.images = options.images
   if (options.videos?.length) envelope.videos = options.videos
   if (options.cache !== undefined) envelope.cache = options.cache

package/js/session/adapters/_cancelled.js

@@ -13,7 +13,6 @@
 
 import { STATUS_INCOMPLETE, WARNING_CANCELLED } from '#core/status.js'
 import { costFor } from './_pricing.js'
-import { catalogKey } from '#core/model-id.js'
 
 /**
  * @param {string} start       hrtime-bigint-as-string at call entry
@@ -43,7 +42,7 @@ export function cancelledDone (start, first, envelope, output, inputTokens, outp
       ...(cacheWriteInputTokens > 0 && { cacheWriteInputTokens }),
       ...(cacheReadInputTokens > 0 && { cacheReadInputTokens }),
       cost: costFor(
-        catalogKey(envelope.model),
+        envelope,
         { inputTokens, outputTokens, thinkingTokens: 0, cacheWriteInputTokens, cacheReadInputTokens }
       ),
       timestamps: { start, first: first ?? end, end },

package/js/session/adapters/_catalog.js

@@ -12,7 +12,10 @@
 
 import envPaths from 'env-paths'
 
+import { catalogKey } from '#core/model-id.js'
+
 import { createLazyJsonFileCache } from './_lazy_json_cache.js'
+import { mergeSpeed } from './_speed.js'
 
 // `{ suffix: null }` mirrors `src/lib/common.js::CONFIG_DIR` so the
 // session subprocess reads the same `~/.config/mohdel/curated.json`
@@ -56,3 +59,16 @@ export function setCatalog (table) {
 export function getSpec (model) {
   return cache.get(model)
 }
+
+/**
+ * Effective spec for a call: the catalog entry with any speed-lane
+ * overlay applied. Adapters resolve spec through this rather than
+ * `getSpec` so lane prices and quotas reach pricing and throttling
+ * without each adapter merging for itself.
+ *
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @returns {any | undefined}
+ */
+export function specFor (envelope) {
+  return mergeSpeed(getSpec(catalogKey(envelope.model)), envelope.speed)
+}

package/js/session/adapters/_chat_completions.js

@@ -287,7 +287,7 @@ function finalize ({ envelope, content, toolCalls, usage, finishReason, start, f
       thinkingTokens,
       ...(cachedInputTokens > 0 && { cacheReadInputTokens: cachedInputTokens }),
       cost: costFor(
-        catalogKey(envelope.model),
+        envelope,
         {
           inputTokens,
           outputTokens: visibleOutputTokens,

package/js/session/adapters/_errors.js

@@ -53,6 +53,29 @@ function scrubKey (detail, key) {
   return detail.split(key).join(mask)
 }
 
+const UNWRAP_DEPTH = 2
+
+/**
+ * `@google/genai` sets `ApiError.message` to `JSON.stringify({error:
+ * {message, code, status}})`, and Gemini's own body inside it is
+ * itself JSON — so the sentence sits two envelopes deep.
+ * @param {string} str
+ * @returns {string}
+ */
+function unwrapJsonMessage (str) {
+  let current = str
+  for (let i = 0; i < UNWRAP_DEPTH; i++) {
+    const trimmed = current.trim()
+    if (!trimmed.startsWith('{')) return current
+    let parsed
+    try { parsed = JSON.parse(trimmed) } catch { return current }
+    const inner = parsed?.error?.message ?? parsed?.message
+    if (typeof inner !== 'string' || !inner) return current
+    current = inner
+  }
+  return current
+}
+
 /**
  * Extract a short human-readable detail from an SDK error. Trimmed
  * to `DETAIL_CAP` chars so a verbose provider body doesn't blow up
@@ -65,7 +88,7 @@ function extractDetail (err) {
   const nested = err.error?.message || err.response?.data?.error?.message
   const raw = nested || err.message
   if (!raw) return undefined
-  const str = typeof raw === 'string' ? raw : JSON.stringify(raw)
+  const str = unwrapJsonMessage(typeof raw === 'string' ? raw : JSON.stringify(raw))
   return str.length > DETAIL_CAP ? str.slice(0, DETAIL_CAP) + '…' : str
 }
 

package/js/session/adapters/_pricing.js

@@ -9,7 +9,7 @@
  * @module session/adapters/_pricing
  */
 
-import { getSpec, setCatalog } from './_catalog.js'
+import { setCatalog, specFor } from './_catalog.js'
 
 /**
  * Pure cost computation from spec + usage.
@@ -104,12 +104,15 @@ function resolveTier (price, tokens) {
 }
 
 /**
- * @param {string} model  Fully-qualified `<provider>/<model>`.
+ * Cost of a call, priced against the envelope's effective spec so an
+ * active speed lane bills at the lane's rates.
+ *
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
  * @param {{inputTokens?: number, outputTokens?: number, thinkingTokens?: number}} usage
  * @returns {number}
  */
-export function costFor (model, usage) {
-  return computeCost(getSpec(model), usage)
+export function costFor (envelope, usage) {
+  return computeCost(specFor(envelope), usage)
 }
 
 /**

package/js/session/adapters/_speed.js

@@ -0,0 +1,87 @@
+/**
+ * Service-speed lanes — catalog side.
+ *
+ * A lane is a named service speed a model sells, declared per catalog
+ * entry under `speeds` with the price and rate-limit fields that
+ * differ from the base entry. This module owns only what is common to
+ * every provider: what the entry declares, and what that means for
+ * pricing and throttling.
+ *
+ * How a lane reaches the wire, and how the served lane is read back,
+ * is provider protocol and lives in the adapter. An adapter that
+ * handles lanes advertises the names it accepts on `speedLanes`;
+ * absence of that property is the declaration that it handles none,
+ * and is what `run.js` checks before dispatch.
+ *
+ * @module session/adapters/_speed
+ */
+
+/** Spec fields a lane overlay may restate. */
+export const SPEED_OVERRIDABLE = Object.freeze([
+  'inputPrice',
+  'outputPrice',
+  'thinkingPrice',
+  'cacheWritePrice',
+  'cacheWrite1hPrice',
+  'cacheReadPrice',
+  'rpmLimit',
+  'tpmLimit'
+])
+
+/**
+ * Whether `spec` declares `speed`. Uses `hasOwn` rather than
+ * truthiness so a lane sold at base prices still counts.
+ *
+ * @param {any} spec
+ * @param {string} speed
+ * @returns {boolean}
+ */
+export function hasSpeed (spec, speed) {
+  return !!spec?.speeds && Object.hasOwn(spec.speeds, speed)
+}
+
+/**
+ * @param {any} spec
+ * @returns {string[]}
+ */
+export function speedNames (spec) {
+  return spec?.speeds ? Object.keys(spec.speeds) : []
+}
+
+/**
+ * Whether the lane declares a quota of its own, which is what earns it
+ * a private rate-limit bucket. Lanes that don't (OpenAI's service_tier
+ * shares the model's TPM/RPM pool) count against the base bucket —
+ * giving them their own would silently double the allowance.
+ *
+ * @param {any} spec
+ * @param {string} [speed]
+ * @returns {boolean}
+ */
+export function speedHasOwnQuota (spec, speed) {
+  if (!speed || !hasSpeed(spec, speed)) return false
+  const overlay = spec.speeds[speed]
+  return overlay.rpmLimit != null || overlay.tpmLimit != null
+}
+
+/**
+ * Spec with `speed`'s overlay applied. Unnamed fields fall through to
+ * the base entry.
+ *
+ * @param {any} spec
+ * @param {string} [speed]
+ * @returns {any}
+ * @throws when `speed` is set and `spec` does not declare it
+ */
+export function mergeSpeed (spec, speed) {
+  if (!speed) return spec
+  if (!hasSpeed(spec, speed)) {
+    throw new Error(`model does not declare speed lane '${speed}'`)
+  }
+  const overlay = spec.speeds[speed]
+  const merged = { ...spec }
+  for (const field of SPEED_OVERRIDABLE) {
+    if (Object.hasOwn(overlay, field)) merged[field] = overlay[field]
+  }
+  return merged
+}

package/js/session/adapters/anthropic.js

@@ -261,7 +261,7 @@ export async function * anthropic (envelope, deps = {}) {
       ...(cacheWrite1hTokens > 0 && { cacheWrite1hInputTokens: cacheWrite1hTokens }),
       ...(cacheReadTokens > 0 && { cacheReadInputTokens: cacheReadTokens }),
       cost: costFor(
-        catalogKey(envelope.model),
+        envelope,
         {
           inputTokens,
           outputTokens: messageOutputTokens,

package/js/session/adapters/gemini.js

@@ -208,7 +208,7 @@ export async function * gemini (envelope, deps = {}) {
       thinkingTokens,
       ...(cacheReadTokens > 0 && { cacheReadInputTokens: cacheReadTokens }),
       cost: costFor(
-        catalogKey(envelope.model),
+        envelope,
         { inputTokens: regularInputTokens, outputTokens, thinkingTokens, cacheReadInputTokens: cacheReadTokens }
       ),
       timestamps: { start, first: first ?? end, end }

package/js/session/adapters/openai.js

@@ -83,6 +83,8 @@ export async function * openai (envelope, deps = {}) {
   let status = STATUS_COMPLETED
   /** @type {string | undefined} */
   let warning
+  /** @type {string | null | undefined} */
+  let servedTier
 
   // Tool-call accumulation: itemId → {call_id, name, arguments}
   /** @type {Map<string, {call_id: string, name: string, arguments: string}>} */
@@ -130,6 +132,7 @@ export async function * openai (envelope, deps = {}) {
           break
 
         case 'response.completed':
+          servedTier = event.response?.service_tier ?? servedTier
           if (event.response?.usage) {
             inputTokens = event.response.usage.input_tokens ?? 0
             outputTokens = event.response.usage.output_tokens ?? 0
@@ -143,6 +146,7 @@ export async function * openai (envelope, deps = {}) {
           break
 
         case 'response.incomplete':
+          servedTier = event.response?.service_tier ?? servedTier
           status = STATUS_INCOMPLETE
           if (event.response?.incomplete_details?.reason === 'max_output_tokens') {
             warning = WARNING_INSUFFICIENT_OUTPUT_BUDGET
@@ -189,6 +193,8 @@ export async function * openai (envelope, deps = {}) {
   // simpler with the additive shape.
   const regularInputTokens = Math.max(0, inputTokens - cachedInputTokens - cacheWriteTokens)
 
+  const billed = billedEnvelope(envelope, servedTier, log)
+
   /** @type {import('#core/events.js').DoneEvent} */
   const done = {
     type: 'done',
@@ -200,8 +206,9 @@ export async function * openai (envelope, deps = {}) {
       thinkingTokens,
       ...(cacheWriteTokens > 0 && { cacheWriteInputTokens: cacheWriteTokens }),
       ...(cachedInputTokens > 0 && { cacheReadInputTokens: cachedInputTokens }),
+      ...(envelope.speed && { servedSpeed: billed.served }),
       cost: costFor(
-        catalogKey(envelope.model),
+        billed.envelope,
         {
           inputTokens: regularInputTokens,
           outputTokens: messageOutputTokens,
@@ -220,6 +227,66 @@ export async function * openai (envelope, deps = {}) {
   yield done
 }
 
+/**
+ * Lane names the OpenAI adapter can put on `service_tier`. `run.js`
+ * reads this before dispatch; a lane outside it never reaches here.
+ */
+openai.speedLanes = new Set(['fast', 'priority', 'flex', 'scale'])
+
+/**
+ * Lane the response says was served, given the one requested.
+ *
+ * OpenAI answers `service_tier: 'priority'` to a granted request for
+ * either premium lane, so the echo alone cannot name which was asked
+ * for — the request is the other half of the answer. Any other value
+ * is the tier that actually ran, `null` when nothing was reported.
+ *
+ * @param {string} requested
+ * @param {string | null | undefined} servedTier
+ * @returns {string | null | undefined}
+ */
+function servedLane (requested, servedTier) {
+  if (servedTier == null) return undefined
+  if (servedTier === 'priority') {
+    return (requested === 'fast' || requested === 'priority') ? requested : 'priority'
+  }
+  return openai.speedLanes.has(servedTier) ? servedTier : null
+}
+
+/**
+ * Envelope to price the call against. OpenAI serves Standard instead
+ * when a premium lane is unavailable — documented behaviour above the
+ * ramp rate limit — so billing the requested lane would charge premium
+ * rates for standard service.
+ *
+ * When a lane was requested and nothing was reported back, the request
+ * is the only evidence available: bill it and say so.
+ *
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {string | null | undefined} servedTier
+ * @param {any} [log]
+ * @returns {{envelope: import('#core/envelope.js').CallEnvelope, served: string | null}}
+ */
+function billedEnvelope (envelope, servedTier, log) {
+  if (!envelope.speed) return { envelope, served: null }
+
+  const served = servedLane(envelope.speed, servedTier)
+  if (served === undefined) {
+    log?.warn(
+      { model: envelope.model, speed: envelope.speed },
+      '[mohdel:openai] no service_tier reported; billing the requested lane'
+    )
+    return { envelope, served: envelope.speed }
+  }
+  if (served === envelope.speed) return { envelope, served }
+
+  log?.warn(
+    { model: envelope.model, requested: envelope.speed, servedTier, served },
+    '[mohdel:openai] provider served a different speed lane; billing what was served'
+  )
+  return { envelope: { ...envelope, speed: served ?? undefined }, served }
+}
+
 /**
  * @param {import('#core/envelope.js').CallEnvelope} envelope
  * @param {Array<any>} input
@@ -287,6 +354,8 @@ function buildRequest (envelope, input, instructions) {
     }
   }
 
+  if (envelope.speed) request.service_tier = envelope.speed
+
   return request
 }