mohdel 0.119.0 → 0.120.0

package/README.md

@@ -101,6 +101,9 @@ mo ask anthropic/claude-sonnet-4-6 --stream "write a haiku about recursion"
 # With thinking effort
 mo ask anthropic/claude-opus-4-6 --effort high "prove P != NP"
 
+# On a faster service lane, when the model sells one
+mo ask anthropic/claude-opus-4-6@fast "triage this alert"
+
 # Speech → text from an audio file
 mo transcribe groq/whisper-large-v3-turbo meeting.mp3
 mo transcribe mistral/voxtral-mini-transcribe interview.wav --language fr
@@ -315,6 +318,8 @@ What each provider supports through mohdel's unified interface:
 
 Adapter capability ≠ model capability — whether a given model accepts images, tools, or thinking effort depends on the model spec in `curated.json`. The adapter passes through what the envelope supplies; the provider rejects unsupported combos.
 
+**Service speeds** are the exception to that pass-through rule. Where a provider sells the same weights at several speeds (Anthropic's fast mode, and equivalents elsewhere), the lanes a model sells are declared in its `curated.json` entry under `speeds`, with their own prices and rate limits. Select one with `speed` or the `@lane` id suffix. There is no default lane and no fallback: an undeclared lane fails the call before it is sent, because a model that silently ignores an unsupported lane would otherwise be billed at the lane's rates for standard service. See [docs/CATALOG.md](docs/CATALOG.md#service-speeds).
+
 ## Local Development
 
 ```bash

package/config/curated.schema.json

@@ -88,6 +88,7 @@
           "description": "USD per 1M thinking/reasoning tokens (when the provider bills these separately)."
         },
         "cacheWritePrice": { "type": "number", "minimum": 0, "description": "USD per 1M tokens written to provider-side prompt cache." },
+        "cacheWrite1hPrice": { "type": "number", "minimum": 0, "description": "USD per 1M tokens written with a 1h TTL, when the provider prices that above the default write rate. Falls back to cacheWritePrice." },
         "cacheReadPrice": { "type": "number", "minimum": 0, "description": "USD per 1M tokens served from provider-side prompt cache." },
 
         "contextTokenLimit": { "type": "integer", "minimum": 1, "description": "Maximum total tokens (input + output)." },
@@ -107,6 +108,43 @@
         },
         "defaultThinkingEffort": { "type": "string", "description": "Effort level used when the envelope omits 'outputEffort'." },
 
+        "speeds": {
+          "type": "object",
+          "description": "Service speed lanes this model sells, keyed by lane name. A lane is a provider request parameter buying a different speed/price point for the same weights. There is no default lane: omitting 'speed' on the envelope sends no parameter. Only lanes declared here may be requested.",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["wire"],
+            "additionalProperties": false,
+            "description": "Lane overlay. Fields named here override the base entry; unnamed fields fall through. Only prices and rate limits are overridable — anything that would change what the model is belongs in its own entry.",
+            "properties": {
+              "wire": { "type": "string", "description": "Provider-native value for the lane parameter (e.g. 'fast')." },
+              "inputPrice": {
+                "oneOf": [
+                  { "type": "number", "minimum": 0 },
+                  { "type": "object", "required": ["default"], "additionalProperties": { "type": "number" }, "properties": { "default": { "type": "number" } } }
+                ]
+              },
+              "outputPrice": {
+                "oneOf": [
+                  { "type": "number", "minimum": 0 },
+                  { "type": "object", "required": ["default"], "additionalProperties": { "type": "number" }, "properties": { "default": { "type": "number" } } }
+                ]
+              },
+              "thinkingPrice": {
+                "oneOf": [
+                  { "type": "number", "minimum": 0 },
+                  { "type": "object", "required": ["default"], "additionalProperties": { "type": "number" }, "properties": { "default": { "type": "number" } } }
+                ]
+              },
+              "cacheWritePrice": { "type": "number", "minimum": 0 },
+              "cacheWrite1hPrice": { "type": "number", "minimum": 0 },
+              "cacheReadPrice": { "type": "number", "minimum": 0 },
+              "rpmLimit": { "type": "integer", "minimum": 1 },
+              "tpmLimit": { "type": "integer", "minimum": 1 }
+            }
+          }
+        },
+
         "tags": {
           "type": "array",
           "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9._-]{0,31}$" },

package/js/core/envelope.js

@@ -43,6 +43,13 @@
  *   Thinking effort level. Valid keys are per-model — validated at
  *   runtime against the curated entry's `thinkingEffortLevels`.
  *   Default is the model's `defaultThinkingEffort`.
+ * @property {string} [speed]
+ *   Service speed lane. Valid keys are per-model — validated at
+ *   runtime against the curated entry's `speeds`. There is no
+ *   default and no fallback: omitting the field sends no speed
+ *   parameter, while naming a lane the entry does not declare
+ *   (`SESSION_INVALID_SPEED`) or the provider's adapter cannot emit
+ *   (`SESSION_SPEED_NOT_IMPLEMENTED`) fails the call before dispatch.
  *
  * @property {MediaRef[]} [images]
  * @property {MediaRef[]} [videos]
@@ -146,6 +153,7 @@ export const ENVELOPE_FIELDS = Object.freeze([
   'outputType',
   'outputStyle',
   'outputEffort',
+  'speed',
   'images',
   'videos',
   'cache',

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

@@ -19,6 +19,7 @@
 import { getSpec } from './_catalog.js'
 import { classifyProviderError } from './_errors.js'
 import { costFor } from './_pricing.js'
+import { applySpeed } from './_speed.js'
 import { catalogKey, bareOf } from '#core/model-id.js'
 import {
   STATUS_COMPLETED,
@@ -287,7 +288,7 @@ function finalize ({ envelope, content, toolCalls, usage, finishReason, start, f
       thinkingTokens,
       ...(cachedInputTokens > 0 && { cacheReadInputTokens: cachedInputTokens }),
       cost: costFor(
-        catalogKey(envelope.model),
+        envelope,
         {
           inputTokens,
           outputTokens: visibleOutputTokens,
@@ -370,6 +371,8 @@ function buildRequest (envelope, spec, config) {
     args[config.identifierField || 'user'] = envelope.identifier
   }
 
+  applySpeed(args, envelope, spec)
+
   return args
 }
 

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,119 @@
+/**
+ * Service-speed lanes.
+ *
+ * A lane is a provider request parameter that buys a different
+ * speed/price point for the same weights (Anthropic `speed: "fast"`).
+ * Lanes are declared per catalog entry under `speeds`, keyed by lane
+ * name, each carrying the wire value plus any price and rate-limit
+ * fields that differ from the base entry.
+ *
+ * Two declarations must agree for a lane to be usable: the entry
+ * declares it (`spec.speeds`) and the provider's adapter can emit it
+ * (`SPEED_PARAMS`). `run.js` checks both before dispatch.
+ *
+ * @module session/adapters/_speed
+ */
+
+import { providerOf } from '#core/model-id.js'
+
+/**
+ * Providers whose adapter emits a lane parameter, mapped to the
+ * native parameter name. Absence from this table is the declaration
+ * that a provider has no lanes.
+ */
+export const SPEED_PARAMS = Object.freeze({
+  anthropic: 'speed'
+})
+
+/** Spec fields a lane overlay may restate. */
+export const SPEED_OVERRIDABLE = Object.freeze([
+  'inputPrice',
+  'outputPrice',
+  'thinkingPrice',
+  'cacheWritePrice',
+  'cacheWrite1hPrice',
+  'cacheReadPrice',
+  'rpmLimit',
+  'tpmLimit'
+])
+
+/**
+ * @param {string} provider
+ * @returns {boolean}
+ */
+export function providerSupportsSpeed (provider) {
+  return Object.hasOwn(SPEED_PARAMS, provider)
+}
+
+/**
+ * @param {string} provider
+ * @returns {string | undefined}
+ */
+export function speedParamFor (provider) {
+  return SPEED_PARAMS[provider]
+}
+
+/**
+ * Whether `spec` declares `speed`. Uses `hasOwn` rather than
+ * truthiness so an overlay that only carries `wire` 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) : []
+}
+
+/**
+ * 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
+}
+
+/**
+ * Set the provider-native lane parameter on an outbound request.
+ * No-op when the envelope carries no lane.
+ *
+ * @param {Record<string, any>} request
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {any} spec
+ * @throws when the envelope carries a lane the provider cannot emit
+ *   or the spec does not declare
+ */
+export function applySpeed (request, envelope, spec) {
+  if (!envelope.speed) return
+  const provider = providerOf(envelope.model)
+  const param = speedParamFor(provider)
+  if (!param) {
+    throw new Error(`provider '${provider}' does not implement speed lanes`)
+  }
+  if (!hasSpeed(spec, envelope.speed)) {
+    throw new Error(`model does not declare speed lane '${envelope.speed}'`)
+  }
+  request[param] = spec.speeds[envelope.speed].wire
+}

package/js/session/adapters/anthropic.js

@@ -29,6 +29,7 @@ import { classifyProviderError } from './_errors.js'
 import { loadImages } from './_images.js'
 import { isTrustedMedia } from './_media.js'
 import { costFor } from './_pricing.js'
+import { applySpeed } from './_speed.js'
 import { catalogKey, bareOf } from '#core/model-id.js'
 import {
   toAnthropicTools,
@@ -261,7 +262,7 @@ export async function * anthropic (envelope, deps = {}) {
       ...(cacheWrite1hTokens > 0 && { cacheWrite1hInputTokens: cacheWrite1hTokens }),
       ...(cacheReadTokens > 0 && { cacheReadInputTokens: cacheReadTokens }),
       cost: costFor(
-        catalogKey(envelope.model),
+        envelope,
         {
           inputTokens,
           outputTokens: messageOutputTokens,
@@ -352,6 +353,7 @@ function buildRequest (envelope, conversation, system, conversationCacheTtl = nu
     }
   }
 
+  applySpeed(request, envelope, spec)
   applyCacheBreakpoints(request, conversationCacheTtl)
 
   return request

package/js/session/adapters/gemini.js

@@ -31,6 +31,7 @@ import { loadImages } from './_images.js'
 import { isTrustedMedia } from './_media.js'
 import { loadVideos } from './_videos.js'
 import { costFor } from './_pricing.js'
+import { applySpeed } from './_speed.js'
 import { catalogKey, bareOf } from '#core/model-id.js'
 import {
   toGeminiTools,
@@ -208,7 +209,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 }
@@ -271,6 +272,7 @@ function buildRequest (envelope, contents, systemInstruction) {
     contents
   }
   if (Object.keys(config).length > 0) request.config = config
+  applySpeed(request, envelope, spec)
   return request
 }
 

package/js/session/adapters/openai.js

@@ -30,6 +30,7 @@ import { classifyProviderError } from './_errors.js'
 import { loadImages } from './_images.js'
 import { isTrustedMedia } from './_media.js'
 import { costFor } from './_pricing.js'
+import { applySpeed } from './_speed.js'
 import { catalogKey, providerOf, bareOf } from '#core/model-id.js'
 import {
   toOpenAITools,
@@ -201,7 +202,7 @@ export async function * openai (envelope, deps = {}) {
       ...(cacheWriteTokens > 0 && { cacheWriteInputTokens: cacheWriteTokens }),
       ...(cachedInputTokens > 0 && { cacheReadInputTokens: cachedInputTokens }),
       cost: costFor(
-        catalogKey(envelope.model),
+        envelope,
         {
           inputTokens: regularInputTokens,
           outputTokens: messageOutputTokens,
@@ -287,6 +288,8 @@ function buildRequest (envelope, input, instructions) {
     }
   }
 
+  applySpeed(request, envelope, spec)
+
   return request
 }
 

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, providerSupportsSpeed, 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)
+    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,14 @@ 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
+  // An active lane is its own capacity pool, so it gets its own bucket
+  // whatever `rateLimitScope` says — sharing one would let standard
+  // traffic throttle the lane being paid for.
+  const bucketKey = envelope.speed
+    ? `${key}@${envelope.speed}`
+    : (spec?.rateLimitScope === 'model' ? key : provider)
 
   // `0` is a killswitch ("deny all"), not "unset"; `undefined`/`null`
   // means no limit configured for that dimension. Gate on nullability
@@ -220,8 +233,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 +284,108 @@ 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
+ * @returns {import('#core/events.js').ErrorEvent | undefined}
+ */
+function speedError (key, speed, spec, provider) {
+  if (!hasSpeed(spec, speed)) {
+    const available = speedNames(spec)
+    const detail = available.length
+      ? `Available: ${available.join(', ')}`
+      : 'It declares no speed lanes.'
+    const hint = speed.includes(':')
+      ? " Suffix order is ':effort' then '@speed'."
+      : ''
+    return errorEvent(
+      `Model '${key}' does not support speed lane '${speed}'. ${detail}${hint}`,
+      'SESSION_INVALID_SPEED'
+    )
+  }
+  if (!providerSupportsSpeed(provider)) {
+    return errorEvent(
+      `Provider '${provider}' does not implement speed lanes, but '${key}' declares '${speed}'.`,
+      'SESSION_SPEED_NOT_IMPLEMENTED'
+    )
   }
+  return undefined
 }
 
 /**
@@ -332,6 +404,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)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mohdel",
-  "version": "0.119.0",
+  "version": "0.120.0",
   "license": "MIT",
   "author": {
     "name": "Christophe Le Bars",
@@ -108,7 +108,7 @@
     "@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.120.0"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.115.0",

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 { providerSupportsSpeed } from '../../js/session/adapters/_speed.js'
 import { getCuratedModels, loadDefaultEnv, catalogEntries, catalogValues } from '../lib/common.js'
 
 // --- Local validation ---
@@ -50,6 +51,22 @@ const checkLocal = (curated) => {
       warnings.push(`${key}: has thinkingEffortLevels but no defaultThinkingEffort`)
     }
 
+    if (spec.speeds && !providerSupportsSpeed(keyProvider)) {
+      errors.push(`${key}: declares speeds but provider '${keyProvider}' has no adapter support — calls on those lanes would fail at dispatch`)
+    }
+    for (const [lane, overlay] of Object.entries(spec.speeds || {})) {
+      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

@@ -268,8 +268,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 +354,14 @@ 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}`)
+          }
+
           // Validate outputEffort alias against model capabilities
           if (aliasOutputEffort) {
             if (!modelSpec.thinkingEffortLevels) {
@@ -337,7 +372,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 +418,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 +480,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,23 @@
+import { SPEED_OVERRIDABLE } from '../../js/session/adapters/_speed.js'
+
+const validateSpeeds = (speeds) => {
+  const allowed = new Set(['wire', ...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`
+    }
+    if (typeof overlay.wire !== 'string' || !overlay.wire) {
+      return `lane '${lane}' must set a string 'wire' value`
+    }
+    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' },
@@ -15,6 +35,7 @@ const fieldDefs = {
   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: [] },