mohdel 0.119.0 → 0.121.0

package/js/session/run.js

@@ -26,7 +26,8 @@ import { getAdapter } from './adapters/index.js'
 import { isImageProvider } from './adapters/image/index.js'
 import { getSpec } from './adapters/_catalog.js'
 import { getProviderLimits } from './adapters/_providers.js'
-import { providerOf, catalogKey, effortOf } from '#core/model-id.js'
+import { hasSpeed, mergeSpeed, speedHasOwnQuota, speedNames } from './adapters/_speed.js'
+import { providerOf, catalogKey, effortOf, speedOf } from '#core/model-id.js'
 import * as defaultCooldown from './_cooldown.js'
 import * as defaultLimiter from './_rate_limiter.js'
 import { withIdleHeartbeat, MIN_IDLE_HEARTBEAT_MS } from './_idle_heartbeat.js'
@@ -66,15 +67,13 @@ export async function * run (envelope, {
   sleep = defaultSleep,
   signal
 } = {}) {
-  // Honor the `model:effort` shortcut on the wire (mirrors the
-  // factory-side `mohdel().use('model:effort')` convenience). If
-  // the envelope's `model` field ends in `:<effort>` and the base
-  // resolves to a known spec, split the suffix into
-  // `envelope.outputEffort`. Explicit `outputEffort` wins when both
-  // are set (suffix is a shortcut, not an override).
-  const effortNorm = normalizeModelEffort(envelope, resolveSpec)
-  if (effortNorm.error) { yield effortNorm.error; return }
-  envelope = effortNorm.envelope
+  // Honor the `model:effort@speed` shortcuts on the wire (mirrors the
+  // factory-side `mohdel().use('model:effort')` convenience). Explicit
+  // envelope fields win when both are set (a suffix is a shortcut, not
+  // an override).
+  const norm = normalizeModelId(envelope, resolveSpec)
+  if (norm.error) { yield norm.error; return }
+  envelope = norm.envelope
 
   const provider = providerOf(envelope.model)
   const span = openSpan(envelope)
@@ -85,6 +84,7 @@ export async function * run (envelope, {
     provider,
     model: envelope.model,
     effort: envelope.outputEffort ?? 'default',
+    speed: envelope.speed ?? null,
     outputBudget: envelope.outputBudget ?? null,
     tools: envelope.tools?.length || 0,
     images: envelope.images?.length || 0
@@ -116,11 +116,8 @@ export async function * run (envelope, {
   // Catalog is authoritative: every callable model must have a
   // spec. Without one we'd silently run the provider call with
   // defaults (no rate-limits, no budget clamps, cost=0), masking
-  // misconfiguration in the layer that pushed the catalog. Effort
-  // suffix is stripped for the lookup — catalog entries are keyed
-  // by the bare `<provider>/<bare>` id, not per-effort variants.
-  const key = catalogKey(envelope.model)
-  const spec = resolveSpec(key)
+  // misconfiguration in the layer that pushed the catalog.
+  const { key, spec } = norm
   if (!spec) {
     const detail = `Unknown model '${key}' — not in catalog`
     const err = errorEvent(detail, 'SESSION_UNKNOWN_MODEL')
@@ -130,6 +127,17 @@ export async function * run (envelope, {
     return
   }
 
+  if (envelope.speed) {
+    const speedErr = speedError(key, envelope.speed, spec, provider, adapter)
+    if (speedErr) {
+      log.warn({ provider, speed: envelope.speed }, '[mohdel:answer] unusable speed lane')
+      endSpanError(span, new Error(speedErr.error.message))
+      yield speedErr
+      return
+    }
+  }
+  const effective = mergeSpeed(spec, envelope.speed)
+
   const coolErr = cooldown.coolingDownError(provider)
   if (coolErr) {
     log.debug({ provider, detail: coolErr.detail }, '[mohdel:cooldown] fast-fail')
@@ -140,9 +148,12 @@ export async function * run (envelope, {
   }
 
   const providerCfg = resolveProviderLimits(provider) || {}
-  const rpmLimit = spec?.rpmLimit ?? providerCfg.rpmLimit
-  const tpmLimit = spec?.tpmLimit ?? providerCfg.tpmLimit
-  const bucketKey = (spec?.rateLimitScope === 'model') ? key : provider
+  const rpmLimit = effective?.rpmLimit ?? providerCfg.rpmLimit
+  const tpmLimit = effective?.tpmLimit ?? providerCfg.tpmLimit
+  const baseBucket = (spec?.rateLimitScope === 'model') ? key : provider
+  const bucketKey = speedHasOwnQuota(spec, envelope.speed)
+    ? `${key}@${envelope.speed}`
+    : baseBucket
 
   // `0` is a killswitch ("deny all"), not "unset"; `undefined`/`null`
   // means no limit configured for that dimension. Gate on nullability
@@ -220,8 +231,12 @@ export async function * run (envelope, {
         }
         // Surface on AnswerResult so hosts that pass the whole
         // result upstream pick it up without needing a separate
-        // wire field.
-        if (ev.result) ev.result.maxInterFrameMs = maxInterFrameMs
+        // wire field. `speed` rides along because lane prices differ,
+        // so cost is only meaningful attributed per (model, lane).
+        if (ev.result) {
+          ev.result.maxInterFrameMs = maxInterFrameMs
+          if (envelope.speed) ev.result.speed = envelope.speed
+        }
         finalizeSpanOk(span, ev.result, sawDelta, maxInterFrameMs)
         log.debug(summarizeDone(ev.result, startedAt), '[mohdel:answer] done')
       } else if (ev.type === 'error') {
@@ -267,53 +282,114 @@ export async function * run (envelope, {
 }
 
 /**
- * Split an optional `:effort` suffix from `envelope.model`. If the
- * base resolves to a known spec, rewrites `envelope.model` and sets
- * `envelope.outputEffort` (unless already set). Emits a typed error
- * when the suffix is present and the spec rejects it.
+ * Split the optional `:effort` and `@speed` suffixes from
+ * `envelope.model`. If the base resolves to a known spec, rewrites
+ * `envelope.model` and sets `envelope.outputEffort` / `envelope.speed`
+ * (unless already set). Emits a typed error when an effort suffix is
+ * present and the spec rejects it; lane validity is checked in `run`
+ * so that an explicitly-set `envelope.speed` goes through the same
+ * guard as the suffix form.
+ *
+ * Also carries out the catalog lookup, so the key the spec was found
+ * under is the one the rest of the call uses.
  *
  * @param {import('#core/envelope.js').CallEnvelope} envelope
  * @param {(key: string) => any} resolveSpec
  * @returns {{
  *   envelope: import('#core/envelope.js').CallEnvelope,
+ *   key: string,
+ *   spec?: any,
  *   error?: import('#core/events.js').ErrorEvent
  * }}
  */
-function normalizeModelEffort (envelope, resolveSpec) {
-  const candidate = effortOf(envelope.model)
-  if (!candidate) return { envelope }
+function normalizeModelId (envelope, resolveSpec) {
+  // A bare id that itself contains `:` or `@` is a catalog key in its
+  // own right; resolving the whole string first stops it being split
+  // into a base plus a suffix that was never meant as one.
+  const whole = resolveSpec(envelope.model)
+  if (whole) return { envelope, key: envelope.model, spec: whole }
 
+  const effort = effortOf(envelope.model)
+  const speed = speedOf(envelope.model)
   const base = catalogKey(envelope.model)
   const baseSpec = resolveSpec(base)
-  if (!baseSpec) return { envelope } // base not known — let full string fall through to not-found
+  const unresolved = { envelope, key: base, spec: baseSpec }
+  if (effort === undefined && speed === undefined) return unresolved
+  if (!baseSpec) return unresolved
 
-  // Explicit outputEffort wins; still strip the suffix so spans/logs see the canonical id.
-  if (envelope.outputEffort) {
-    return { envelope: { ...envelope, model: base } }
+  const next = { ...envelope, model: base }
+  if (speed !== undefined && !envelope.speed) next.speed = speed
+
+  if (effort === undefined || envelope.outputEffort) {
+    return { envelope: next, key: base, spec: baseSpec }
   }
 
   if (!baseSpec.thinkingEffortLevels) {
     return {
-      envelope,
+      ...unresolved,
       error: errorEvent(
-        `Model '${base}' does not support output effort (no thinkingEffortLevels). Cannot use ':${candidate}' suffix.`,
+        `Model '${base}' does not support output effort (no thinkingEffortLevels). Cannot use ':${effort}' suffix.`,
         'SESSION_INVALID_OUTPUT_EFFORT'
       )
     }
   }
-  if (candidate !== 'none' && !baseSpec.thinkingEffortLevels[candidate]) {
+  if (effort !== 'none' && !baseSpec.thinkingEffortLevels[effort]) {
     return {
-      envelope,
+      ...unresolved,
       error: errorEvent(
-        `Model '${base}' does not support output effort level '${candidate}'. Available: ${Object.keys(baseSpec.thinkingEffortLevels).join(', ')}`,
+        `Model '${base}' does not support output effort level '${effort}'. Available: ${Object.keys(baseSpec.thinkingEffortLevels).join(', ')}`,
         'SESSION_INVALID_OUTPUT_EFFORT'
       )
     }
   }
 
-  return {
-    envelope: { ...envelope, model: base, outputEffort: candidate }
+  next.outputEffort = effort
+  return { envelope: next, key: base, spec: baseSpec }
+}
+
+/**
+ * The two lane guards, in caller-then-internal order. Returns an
+ * error event, or `undefined` when the lane is usable.
+ *
+ * They are deliberately separate. A lane the entry does not declare is
+ * the caller asking for something this model does not sell. A lane the
+ * adapter cannot emit is the catalog and the adapter disagreeing —
+ * left to run, the call would silently take the standard lane and bill
+ * at the overlay's rates.
+ *
+ * @param {string} key
+ * @param {string} speed
+ * @param {any} spec
+ * @param {string} provider
+ * @param {any} adapter
+ * @returns {import('#core/events.js').ErrorEvent | undefined}
+ */
+function speedError (key, speed, spec, provider, adapter) {
+  if (!hasSpeed(spec, speed)) {
+    const available = speedNames(spec)
+    const detail = available.length
+      ? `Available: ${available.join(', ')}`
+      : 'It declares no speed lanes.'
+    const colon = speed.indexOf(':')
+    const hint = colon < 0
+      ? ''
+      : ` Suffix order is ':effort' then '@speed' — did you mean '${key}:${speed.slice(colon + 1)}@${speed.slice(0, colon)}'?`
+    return errorEvent(
+      `Model '${key}' does not support speed lane '${speed}'. ${detail}${hint}`,
+      'SESSION_INVALID_SPEED'
+    )
+  }
+  const lanes = adapter?.speedLanes
+  if (!lanes?.has(speed)) {
+    const detail = lanes
+      ? `It accepts: ${[...lanes].join(', ')}.`
+      : 'It implements no speed lanes.'
+    return errorEvent(
+      `Provider '${provider}' cannot serve speed lane '${speed}', but '${key}' declares it. ${detail}`,
+      'SESSION_SPEED_NOT_IMPLEMENTED'
+    )
   }
+  return undefined
 }
 
 /**
@@ -332,6 +408,7 @@ function openSpan (envelope) {
   }
   if (envelope.outputBudget) attrs['gen_ai.request.max_tokens'] = envelope.outputBudget
   if (envelope.outputEffort) attrs['mohdel.output_effort'] = envelope.outputEffort
+  if (envelope.speed) attrs['mohdel.speed'] = envelope.speed
   return startSpan('mohdel.session.answer', attrs, parent)
 }
 
@@ -383,6 +460,8 @@ function finalizeSpanOk (span, result, sawDelta = false, maxInterFrameMs = 0) {
   }
   if (result?.cacheWriteInputTokens) attrs['mohdel.cache_write_input_tokens'] = result.cacheWriteInputTokens
   if (result?.cacheReadInputTokens) attrs['mohdel.cache_read_input_tokens'] = result.cacheReadInputTokens
+  if (result?.speed) attrs['mohdel.speed'] = result.speed
+  if (result?.servedSpeed !== undefined) attrs['mohdel.served_speed'] = result.servedSpeed ?? 'standard'
   if (result?.cost != null) attrs['mohdel.cost'] = result.cost
   if (result?.warning) attrs['mohdel.warning'] = result.warning
   if (result?.timestamps?.start && result?.timestamps?.first) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mohdel",
-  "version": "0.119.0",
+  "version": "0.121.0",
   "license": "MIT",
   "author": {
     "name": "Christophe Le Bars",
@@ -108,12 +108,12 @@
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.221.0",
     "@opentelemetry/sdk-node": "^0.221.0",
     "chalk": "^6.0.0",
-    "mohdel-thin-gate-linux-x64-gnu": "0.119.0"
+    "mohdel-thin-gate-linux-x64-gnu": "0.121.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.115.0",
+    "@anthropic-ai/sdk": "^0.117.1",
     "@cerebras/cerebras_cloud_sdk": "^1.91.0",
-    "@google/genai": "^2.16.0",
+    "@google/genai": "^2.17.1",
     "@opentelemetry/api": "^1.9.1",
     "env-paths": "^4.0.0",
     "groq-sdk": "^1.5.0",
@@ -126,7 +126,7 @@
   "devDependencies": {
     "gpt-tokenizer": "^3.4.0",
     "lint-staged": "^17.3.0",
-    "release-it": "^21.0.1",
+    "release-it": "^21.0.2",
     "standard": "^17.1.2",
     "vitest": "^4.1.10"
   }

package/src/cli/ask.js

@@ -176,6 +176,12 @@ Examples:
     if (tokens.outputTokens) summary.push(`${tokens.outputTokens} out`)
     if (tokens.thinkingTokens) summary.push(`${tokens.thinkingTokens} think`)
     if (tokens.cost != null) summary.push(`$${tokens.cost.toFixed(4)}`)
+    if (tokens.speed) {
+      const served = tokens.servedSpeed
+      summary.push(served === tokens.speed
+        ? `${tokens.speed} lane`
+        : `${tokens.speed} lane → ${served ?? 'standard'}`)
+    }
     const ts = tokens.timestamps
     if (ts) {
       const toMs = (a, b) => {

package/src/cli/check.js

@@ -1,6 +1,7 @@
 import { label, err, warn, ok } from './colors.js'
 import providers from '../lib/providers.js'
 import { validate, isValidTag } from '../lib/schema.js'
+import { adapters } from '../../js/session/adapters/index.js'
 import { getCuratedModels, loadDefaultEnv, catalogEntries, catalogValues } from '../lib/common.js'
 
 // --- Local validation ---
@@ -50,6 +51,24 @@ const checkLocal = (curated) => {
       warnings.push(`${key}: has thinkingEffortLevels but no defaultThinkingEffort`)
     }
 
+    const lanes = adapters[keyProvider]?.speedLanes
+    for (const [lane, overlay] of Object.entries(spec.speeds || {})) {
+      if (!lanes?.has(lane)) {
+        const detail = lanes ? `accepts: ${[...lanes].join(', ')}` : 'implements no speed lanes'
+        errors.push(`${key}: speeds.${lane} — provider '${keyProvider}' ${detail}; calls on that lane would fail at dispatch`)
+      }
+      for (const priceField of ['inputPrice', 'outputPrice', 'thinkingPrice']) {
+        const val = overlay[priceField]
+        if (val != null && typeof val === 'object' && val.default == null) {
+          errors.push(`${key}: speeds.${lane}.${priceField} is tiered but missing 'default' key`)
+        }
+      }
+      const priced = ['inputPrice', 'outputPrice'].some(f => overlay[f] != null)
+      if (!priced) {
+        warnings.push(`${key}: speeds.${lane} restates no prices — the lane will bill at base rates`)
+      }
+    }
+
     if (Array.isArray(spec.tags)) {
       for (const t of spec.tags) {
         if (!isValidTag(t)) warnings.push(`${key}: invalid tag "${t}" — must match /^[a-zA-Z][a-zA-Z0-9._-]{0,31}$/`)

package/src/lib/index.js

@@ -75,6 +75,17 @@ const resolvePrice = (price, inputTokens) => {
 // @internal — exported for unit tests only.
 export { resolvePrice as _resolvePriceForTests }
 
+// A lane candidate containing `:` means the suffixes were written the
+// other way round, which is otherwise reported as an unknown lane
+// spelled `fast:none`.
+const reversedSuffixHint = (base, candidate) => {
+  const colon = candidate.indexOf(':')
+  if (colon < 0) return ''
+  const speed = candidate.slice(0, colon)
+  const effort = candidate.slice(colon + 1)
+  return ` Suffix order is ':effort' then '@speed' — did you mean '${base}:${effort}@${speed}'?`
+}
+
 const normalizeModelSpec = (resolvedModelId, modelSpec, providerConfig) => {
   const normalized = { ...modelSpec }
   if (!normalized.provider) {
@@ -268,8 +279,35 @@ const mohdel = async ({ logger, verbosity: verbosityOpt, onSuccess, onFailure, c
           // below. If `base` doesn't resolve, fall through — the full
           // `modelId` (with colon) gets the normal lookup + "not
           // found" error path.
+          // A curated id that itself contains `:` or `@` is a catalog
+          // key in its own right, so an exact hit wins over splitting.
+          // Fallback specs are excluded from that test on purpose:
+          // providers that synthesize them resolve any string, which
+          // would disable suffix parsing for them entirely.
+          const exactId = libraryMode ? modelId : expandModelAliasSync(modelId)
+          const isCuratedId = !!catalog[exactId]
+
+          // `@speed` is parsed off first so the two suffixes are read
+          // in canonical order (`base:effort@speed`).
+          let aliasSpeed
+          const atIdx = isCuratedId ? -1 : modelId.lastIndexOf('@')
+          if (atIdx > 0) {
+            const candidate = modelId.slice(atIdx + 1)
+            const base = modelId.slice(0, atIdx)
+            // The base may still carry `:effort`, which is stripped
+            // separately below — probe without it so `x:high@fast`
+            // resolves the same as `x@fast`.
+            const colon = base.lastIndexOf(':')
+            const probe = colon > 0 ? base.slice(0, colon) : base
+            const probeResolved = libraryMode ? probe : expandModelAliasSync(probe)
+            if (catalog[probeResolved] || createFallbackModelSpec(probeResolved)) {
+              aliasSpeed = candidate
+              modelId = base
+            }
+          }
+
           let aliasOutputEffort
-          const colonIdx = modelId.lastIndexOf(':')
+          const colonIdx = isCuratedId ? -1 : modelId.lastIndexOf(':')
           if (colonIdx > 0) {
             const candidate = modelId.slice(colonIdx + 1)
             const base = modelId.slice(0, colonIdx)
@@ -327,6 +365,17 @@ const mohdel = async ({ logger, verbosity: verbosityOpt, onSuccess, onFailure, c
           }
           modelSpec = normalizeModelSpec(resolvedModelId, modelSpec, providerConfig)
 
+          if (aliasSpeed && !Object.hasOwn(modelSpec.speeds || {}, aliasSpeed)) {
+            const available = Object.keys(modelSpec.speeds || {})
+            const detail = available.length
+              ? `Available: ${available.join(', ')}.`
+              : 'It declares no speed lanes.'
+            throw new Error(
+              `Model '${resolvedModelId}' does not support speed lane '${aliasSpeed}'. ${detail}` +
+              reversedSuffixHint(resolvedModelId, aliasSpeed)
+            )
+          }
+
           // Validate outputEffort alias against model capabilities
           if (aliasOutputEffort) {
             if (!modelSpec.thinkingEffortLevels) {
@@ -337,7 +386,7 @@ const mohdel = async ({ logger, verbosity: verbosityOpt, onSuccess, onFailure, c
             }
           }
 
-          return createModelProxy(resolvedModelId, modelSpec, handlers, aliasOutputEffort, sdkCache, rateLimiter, providersConfig, cooldown, configurations, resolveProviderLimits)
+          return createModelProxy(resolvedModelId, modelSpec, handlers, aliasOutputEffort, aliasSpeed, sdkCache, rateLimiter, providersConfig, cooldown, configurations, resolveProviderLimits)
         }
       }
 
@@ -383,7 +432,7 @@ const mohdel = async ({ logger, verbosity: verbosityOpt, onSuccess, onFailure, c
   })
 }
 
-const createModelProxy = (resolvedModelId, modelSpec, handlers, aliasOutputEffort, sdkCache, rateLimiter, providersConfig, cooldown, externalConfigurations, resolveProviderLimits) => {
+const createModelProxy = (resolvedModelId, modelSpec, handlers, aliasOutputEffort, aliasSpeed, sdkCache, rateLimiter, providersConfig, cooldown, externalConfigurations, resolveProviderLimits) => {
   // modelSpec is the full metadata object for resolvedModelId
   let runtimePromise = null
 
@@ -445,6 +494,9 @@ const createModelProxy = (resolvedModelId, modelSpec, handlers, aliasOutputEffor
           if (aliasOutputEffort && !options.outputEffort) {
             options.outputEffort = aliasOutputEffort
           }
+          if (aliasSpeed && !options.speed) {
+            options.speed = aliasSpeed
+          }
 
           // Verbosity tier — captured from handlers (set by the mohdel factory). Used
           // to gate per-call log lines. Read once per call so the closure doesn't have

package/src/lib/schema.js

@@ -1,3 +1,20 @@
+import { SPEED_OVERRIDABLE } from '../../js/session/adapters/_speed.js'
+
+const validateSpeeds = (speeds) => {
+  const allowed = new Set(SPEED_OVERRIDABLE)
+  for (const [lane, overlay] of Object.entries(speeds)) {
+    if (typeof overlay !== 'object' || overlay === null || Array.isArray(overlay)) {
+      return `lane '${lane}' must be an object`
+    }
+    for (const field of Object.keys(overlay)) {
+      if (!allowed.has(field)) {
+        return `lane '${lane}' may not override '${field}' (allowed: ${[...allowed].join(', ')})`
+      }
+    }
+  }
+  return null
+}
+
 const fieldDefs = {
   model: { type: 'string', required: true },
   provider: { type: 'string' },
@@ -10,11 +27,15 @@ const fieldDefs = {
   inputPrice: { type: 'number', altType: 'object' },
   outputPrice: { type: 'number', altType: 'object' },
   thinkingPrice: { type: 'number', altType: 'object' },
+  cacheReadPrice: { type: 'number', altType: 'object' },
+  cacheWritePrice: { type: 'number', altType: 'object' },
+  cacheWrite1hPrice: { type: 'number', altType: 'object' },
   contextTokenLimit: { type: 'number' },
   outputTokenLimit: { type: 'number' },
   thinkingTokenLimit: { type: 'number' },
   thinkingEffortLevels: { type: 'object', nullable: true, default: null },
   defaultThinkingEffort: { type: 'string' },
+  speeds: { type: 'object', validate: validateSpeeds },
   tags: { type: 'array', itemType: 'string', default: [] },
   aliases: { type: 'array', itemType: 'string', default: [] },
   replaces: { type: 'array', itemType: 'string', default: [] },