mohdel 0.90.0

package/js/session/adapters/index.js

@@ -0,0 +1,53 @@
+/**
+ * Adapter registry. Maps `envelope.provider` to an adapter function.
+ *
+ * Each adapter has the shape:
+ *   async function* adapter(envelope) => AsyncGenerator<Event>
+ *
+ * Adapters should yield events in order and return when the stream
+ * is complete. Exceptions thrown from an adapter are caught by
+ * `run()` and converted into `call.error` events.
+ *
+ * @module session/adapters
+ */
+
+import { anthropic } from './anthropic.js'
+import { cerebras } from './cerebras.js'
+import { deepseek } from './deepseek.js'
+import { echo } from './echo.js'
+import { fake } from './fake.js'
+import { fireworks } from './fireworks.js'
+import { gemini } from './gemini.js'
+import { groq } from './groq.js'
+import { mistral } from './mistral.js'
+import { novita } from './novita.js'
+import { openai } from './openai.js'
+import { openrouter } from './openrouter.js'
+import { xai } from './xai.js'
+
+export const adapters = Object.freeze({
+  anthropic,
+  cerebras,
+  deepseek,
+  echo,
+  fake,
+  fireworks,
+  gemini,
+  groq,
+  mistral,
+  novita,
+  openai,
+  openrouter,
+  xai
+})
+
+/**
+ * @param {string} provider
+ * @returns {(env: import('#core/envelope.js').CallEnvelope)
+ *   => AsyncGenerator<import('#core/events.js').Event>}
+ */
+export function getAdapter (provider) {
+  const a = adapters[provider]
+  if (!a) throw new Error(`unknown provider: ${provider}`)
+  return a
+}

package/js/session/adapters/mistral.js

@@ -0,0 +1,31 @@
+/**
+ * Mistral adapter — OpenAI-compatible chat completions against
+ * api.mistral.ai/v1. Mistral uses `tool_choice: "any"` for what
+ * other providers spell as `required`; the shared core re-routes via
+ * `toolChoiceFlavor: 'mistral'`.
+ *
+ * @module session/adapters/mistral
+ */
+
+import OpenAI from 'openai'
+
+import { runChatCompletions } from './_chat_completions.js'
+
+const BASE_URL = 'https://api.mistral.ai/v1'
+
+/**
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {{client?: any, signal?: AbortSignal, log?: any, span?: any}} [deps]
+ * @returns {AsyncGenerator<import('#core/events.js').Event>}
+ */
+export async function * mistral (envelope, deps = {}) {
+  const client = deps.client ?? new OpenAI({ apiKey: envelope.auth.key, baseURL: envelope.auth.baseURL || BASE_URL })
+  yield * runChatCompletions(envelope, client, {
+    provider: 'mistral',
+    toolChoiceFlavor: 'mistral'
+  }, {
+    signal: deps.signal,
+    log: deps.log,
+    span: deps.span
+  })
+}

package/js/session/adapters/novita.js

@@ -0,0 +1,29 @@
+/**
+ * Novita adapter — OpenAI-compatible chat completions against
+ * api.novita.ai. Image generation lives in `adapters/image/novita.js`;
+ * this file covers the text path only.
+ *
+ * @module session/adapters/novita
+ */
+
+import OpenAI from 'openai'
+
+import { runChatCompletions } from './_chat_completions.js'
+
+const BASE_URL = 'https://api.novita.ai/openai'
+
+/**
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {{client?: any, signal?: AbortSignal, log?: any, span?: any}} [deps]
+ * @returns {AsyncGenerator<import('#core/events.js').Event>}
+ */
+export async function * novita (envelope, deps = {}) {
+  const client = deps.client ?? new OpenAI({ apiKey: envelope.auth.key, baseURL: envelope.auth.baseURL || BASE_URL })
+  yield * runChatCompletions(envelope, client, {
+    provider: 'novita'
+  }, {
+    signal: deps.signal,
+    log: deps.log,
+    span: deps.span
+  })
+}

package/js/session/adapters/openai.js

@@ -0,0 +1,381 @@
+/**
+ * OpenAI Responses API adapter.
+ *
+ * Scope:
+ *   - Text in, text out, streaming
+ *   - Status contract (incomplete + warning on max_output_tokens)
+ *   - Tools: unified format → OpenAI function tool; streaming
+ *     function_call argument deltas; tool_use terminal state;
+ *     function_call_output input items on the way back in
+ *   - AbortSignal forwarded to SDK
+ *
+ * Deferred: vision, reasoning (outputEffort → reasoning.effort),
+ *           outputStyle (GPT-5 verbosity).
+ *
+ * @module session/adapters/openai
+ */
+
+import OpenAI from 'openai'
+
+import {
+  STATUS_COMPLETED,
+  STATUS_INCOMPLETE,
+  STATUS_TOOL_USE,
+  WARNING_INSUFFICIENT_OUTPUT_BUDGET
+} from '#core/status.js'
+
+import { cancelledDone } from './_cancelled.js'
+import { getSpec } from './_catalog.js'
+import { classifyProviderError } from './_errors.js'
+import { loadImages } from './_images.js'
+import { costFor } from './_pricing.js'
+import {
+  toOpenAITools,
+  fromOpenAIToolCalls,
+  toToolChoice
+} from './_tools.js'
+
+/**
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {{client?: OpenAI, signal?: AbortSignal, log?: any, span?: any}} [deps]
+ * @returns {AsyncGenerator<import('#core/events.js').Event>}
+ */
+export async function * openai (envelope, deps = {}) {
+  const client = deps.client ?? new OpenAI({
+    apiKey: envelope.auth.key,
+    ...(envelope.auth.baseURL ? { baseURL: envelope.auth.baseURL } : {})
+  })
+  const signal = deps.signal
+  const log = deps.log
+  const start = String(process.hrtime.bigint())
+  let first = null
+
+  const { instructions, input } = splitPrompt(envelope.prompt)
+
+  if (envelope.images?.length) {
+    try {
+      const loaded = await loadImages(envelope.images)
+      const parts = loaded.map(toOpenAIImagePart).filter(Boolean)
+      if (parts.length) injectImageParts(input, parts)
+    } catch (e) {
+      log?.warn({ err: e }, '[mohdel:openai] image load failed')
+      yield { type: 'error', error: classifyProviderError(e) }
+      return
+    }
+  }
+
+  const request = buildRequest(envelope, input, instructions)
+
+  // F53: accumulate via array + join to avoid per-delta V8 cons-string
+  // churn. Materialized at each exit point.
+  const outputParts = []
+  const currentOutput = () => outputParts.join('')
+  let inputTokens = 0
+  let outputTokens = 0
+  let thinkingTokens = 0
+  let status = STATUS_COMPLETED
+  /** @type {string | undefined} */
+  let warning
+
+  // Tool-call accumulation: itemId → {call_id, name, arguments}
+  /** @type {Map<string, {call_id: string, name: string, arguments: string}>} */
+  const toolItems = new Map()
+
+  try {
+    const stream = await client.responses.stream(request, { signal })
+
+    for await (const event of stream) {
+      if (signal?.aborted) {
+        yield cancelledDone(start, first, envelope, currentOutput(), inputTokens, outputTokens)
+        return
+      }
+      switch (event.type) {
+        case 'response.output_text.delta':
+          if (event.delta) {
+            if (first === null) first = String(process.hrtime.bigint())
+            outputParts.push(event.delta)
+            yield { type: 'delta', delta: { type: 'message', delta: event.delta } }
+          }
+          break
+
+        case 'response.output_item.added':
+          if (event.item?.type === 'function_call') {
+            toolItems.set(event.item.id, {
+              call_id: event.item.call_id ?? event.item.id,
+              name: event.item.name ?? '',
+              arguments: ''
+            })
+          }
+          break
+
+        case 'response.function_call_arguments.delta':
+          if (event.item_id && event.delta) {
+            const t = toolItems.get(event.item_id)
+            if (t) {
+              t.arguments += event.delta
+              if (first === null) first = String(process.hrtime.bigint())
+              yield {
+                type: 'delta',
+                delta: { type: 'function_call', delta: event.delta }
+              }
+            }
+          }
+          break
+
+        case 'response.completed':
+          if (event.response?.usage) {
+            inputTokens = event.response.usage.input_tokens ?? 0
+            outputTokens = event.response.usage.output_tokens ?? 0
+            thinkingTokens = event.response.usage.output_tokens_details?.reasoning_tokens ?? 0
+          }
+          if (toolItems.size > 0) {
+            status = STATUS_TOOL_USE
+          }
+          break
+
+        case 'response.incomplete':
+          status = STATUS_INCOMPLETE
+          if (event.response?.incomplete_details?.reason === 'max_output_tokens') {
+            warning = WARNING_INSUFFICIENT_OUTPUT_BUDGET
+          }
+          if (event.response?.usage) {
+            inputTokens = event.response.usage.input_tokens ?? 0
+            outputTokens = event.response.usage.output_tokens ?? 0
+            thinkingTokens = event.response.usage.output_tokens_details?.reasoning_tokens ?? 0
+          }
+          break
+
+        default:
+          break
+      }
+    }
+  } catch (e) {
+    if (signal?.aborted) {
+      yield cancelledDone(start, first, envelope, currentOutput(), inputTokens, outputTokens)
+      return
+    }
+    log?.warn({ err: e }, '[mohdel:openai] stream failed')
+    yield { type: 'error', error: classifyProviderError(e) }
+    return
+  }
+
+  if (signal?.aborted) {
+    yield cancelledDone(start, first, envelope, currentOutput(), inputTokens, outputTokens)
+    return
+  }
+
+  const end = String(process.hrtime.bigint())
+  // OpenAI Responses reports `output_tokens` INCLUDING reasoning
+  // tokens. The `AnswerResult` contract separates them into
+  // `outputTokens` (message-only) and `thinkingTokens`, so subtract
+  // one from the other for the message-only count.
+  const messageOutputTokens = Math.max(0, outputTokens - thinkingTokens)
+
+  /** @type {import('#core/events.js').DoneEvent} */
+  const done = {
+    type: 'done',
+    result: {
+      status,
+      output: currentOutput() || null,
+      inputTokens,
+      outputTokens: messageOutputTokens,
+      thinkingTokens,
+      cost: costFor(
+        `${envelope.provider}/${envelope.model}`,
+        { inputTokens, outputTokens: messageOutputTokens, thinkingTokens }
+      ),
+      timestamps: { start, first: first ?? end, end }
+    }
+  }
+  if (warning) done.result.warning = warning
+  if (toolItems.size > 0) {
+    done.result.toolCalls = fromOpenAIToolCalls(Array.from(toolItems.values()))
+  }
+  yield done
+}
+
+/**
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {Array<any>} input
+ * @param {string} instructions
+ */
+function buildRequest (envelope, input, instructions) {
+  const spec = getSpec(`${envelope.provider}/${envelope.model}`)
+
+  /** @type {Record<string, any>} */
+  const request = {
+    model: envelope.model,
+    input
+  }
+  if (instructions) request.instructions = instructions
+  if (envelope.outputBudget !== undefined) request.max_output_tokens = envelope.outputBudget
+  if (envelope.tools?.length) {
+    request.tools = toOpenAITools(envelope.tools)
+  }
+  if (envelope.toolChoice) {
+    request.tool_choice = toToolChoice('openai', envelope.toolChoice)
+  }
+  if (envelope.parallelToolCalls === false) {
+    request.parallel_tool_calls = false
+  }
+
+  // Thinking: when the spec has `thinkingEffortLevels`, set
+  // `reasoning.effort` and add the thinking-budget headroom on top
+  // of the user's `outputBudget`. `reasoning` is an OpenAI-only
+  // parameter — xAI reasoning is automatic, so add the headroom
+  // but skip the request field on xAI.
+  if (spec?.thinkingEffortLevels) {
+    const effort = envelope.outputEffort ?? spec.defaultThinkingEffort ?? 'low'
+    if (effort && effort !== 'none') {
+      const headroom = spec.thinkingEffortLevels[effort]
+      if (request.max_output_tokens && typeof headroom === 'number') {
+        request.max_output_tokens += headroom
+      }
+      if (envelope.provider === 'openai') {
+        request.reasoning = { effort }
+      }
+    }
+  }
+
+  // outputType: 'json' → text.format
+  if (envelope.outputType === 'json') {
+    request.text = { ...(request.text || {}), format: { type: 'json_object' } }
+  }
+
+  // outputStyle: 'chat' → GPT-5 verbosity hint (only on gpt-5 family)
+  if (envelope.outputStyle && /gpt-5/.test(envelope.model)) {
+    request.text = {
+      ...(request.text || {}),
+      verbosity: envelope.outputStyle === 'chat' ? 'high' : 'low'
+    }
+  }
+
+  // Per-user identifier — openai uses `safety_identifier`; other
+  // Responses-API providers (xai) use the legacy `user` field.
+  if (envelope.identifier) {
+    if (envelope.provider === 'openai') {
+      request.safety_identifier = envelope.identifier
+    } else {
+      request.user = envelope.identifier
+    }
+  }
+
+  return request
+}
+
+/** @param {string | import('#core/envelope.js').Message[]} prompt */
+function splitPrompt (prompt) {
+  if (typeof prompt === 'string') {
+    return { instructions: '', input: [{ role: 'user', content: prompt }] }
+  }
+  /** @type {string[]} */
+  const systemParts = []
+  /** @type {Array<any>} */
+  const input = []
+  for (const m of prompt) {
+    if (m.role === 'system') {
+      systemParts.push(flattenText(m.content))
+    } else if (m.role === 'tool') {
+      input.push({
+        type: 'function_call_output',
+        call_id: m.toolCallId ?? '',
+        output: flattenText(m.content)
+      })
+    } else if (m.role === 'assistant' && m.toolCalls?.length) {
+      // Responses API wants a message item (if any text) followed
+      // by one function_call item per tool invocation.
+      const text = flattenText(m.content)
+      if (text) {
+        input.push({
+          type: 'message',
+          role: 'assistant',
+          content: [{ type: 'output_text', text }]
+        })
+      }
+      for (const tc of m.toolCalls) {
+        input.push({
+          type: 'function_call',
+          name: tc.name,
+          call_id: tc.id,
+          arguments: stringifyToolArgs(tc.arguments)
+        })
+      }
+    } else {
+      input.push({
+        role: m.role,
+        content: toInputContent(m.role, m.content)
+      })
+    }
+  }
+  return { instructions: systemParts.filter(Boolean).join('\n\n'), input }
+}
+
+/** @param {string | import('#core/envelope.js').MessagePart[]} content */
+function flattenText (content) {
+  if (typeof content === 'string') return content
+  return content.filter(p => p.type === 'text' && p.text).map(p => p.text).join('\n')
+}
+
+/**
+ * OpenAI's `function_call` item demands a JSON string for arguments.
+ * The unified `ToolCall.arguments` is an object, so stringify here
+ * and fall back to `"{}"` on any JSON oddness rather than crashing
+ * mid-call.
+ * @param {unknown} args
+ */
+function stringifyToolArgs (args) {
+  if (typeof args === 'string' && args) return args
+  try {
+    return JSON.stringify(args ?? {})
+  } catch {
+    return '{}'
+  }
+}
+
+/**
+ * @param {string} role
+ * @param {string | import('#core/envelope.js').MessagePart[]} content
+ */
+function toInputContent (role, content) {
+  if (typeof content === 'string') return content
+  const partType = role === 'assistant' ? 'output_text' : 'input_text'
+  return content.map(p => {
+    if (p.type === 'text') return { type: partType, text: p.text ?? '' }
+    throw new Error(`unsupported content part type: ${p.type}`)
+  })
+}
+
+/** @param {import('./_images.js').LoadedImage} img */
+function toOpenAIImagePart (img) {
+  if (img.url) {
+    return { type: 'input_image', image_url: img.url }
+  }
+  if (img.base64) {
+    // Responses API takes a data URI for inline images.
+    return {
+      type: 'input_image',
+      image_url: `data:${img.mimeType};base64,${img.base64}`
+    }
+  }
+  return null
+}
+
+/**
+ * Inject image parts into the LAST user input item.
+ *
+ * @param {Array<any>} input
+ * @param {Array<any>} parts
+ */
+function injectImageParts (input, parts) {
+  for (let i = input.length - 1; i >= 0; i--) {
+    const item = input[i]
+    if (item.role !== 'user') continue
+    if (typeof item.content === 'string') {
+      item.content = [{ type: 'input_text', text: item.content }, ...parts]
+    } else if (Array.isArray(item.content)) {
+      item.content = [...item.content, ...parts]
+    }
+    return
+  }
+  input.push({ role: 'user', content: parts })
+}

package/js/session/adapters/openrouter.js

@@ -0,0 +1,66 @@
+/**
+ * OpenRouter adapter — meta-provider with streaming chat completions
+ * and optional `provider` routing preferences (order/allow/deny).
+ *
+ * Routing prefs ride on `envelope.providerOptions.openrouter` to keep
+ * the base envelope schema clean; the shape matches OpenRouter's
+ * `provider` request field: `{order?, allow?, deny?}`.
+ *
+ * @module session/adapters/openrouter
+ */
+
+import OpenAI from 'openai'
+
+import { runChatCompletions } from './_chat_completions.js'
+
+const BASE_URL = 'https://openrouter.ai/api/v1'
+
+/**
+ * Strip `\r` and `\n` from a header value. Node already rejects CRLF
+ * in header values at send time (throws), so this is defense-in-depth
+ * against a misconfigured `OPENROUTER_REFERER` / `OPENROUTER_TITLE`
+ * env var crashing the adapter instead of producing a valid header.
+ *
+ * @param {string} v
+ */
+export function sanitizeHeader (v) {
+  return String(v).replace(/[\r\n]/g, '')
+}
+
+/**
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {{client?: any, signal?: AbortSignal}} [deps]
+ * @returns {AsyncGenerator<import('#core/events.js').Event>}
+ */
+export async function * openrouter (envelope, deps = {}) {
+  // OpenRouter accepts optional `HTTP-Referer` + `X-Title` headers for
+  // attribution in their dashboard. Only send when the embedder sets
+  // the env vars — no defaults, so mohdel never identifies any
+  // upstream consumer unprompted.
+  const defaultHeaders = {}
+  if (process.env.OPENROUTER_REFERER) {
+    defaultHeaders['HTTP-Referer'] = sanitizeHeader(process.env.OPENROUTER_REFERER)
+  }
+  if (process.env.OPENROUTER_TITLE) {
+    defaultHeaders['X-Title'] = sanitizeHeader(process.env.OPENROUTER_TITLE)
+  }
+  const client = deps.client ?? new OpenAI({
+    apiKey: envelope.auth.key,
+    baseURL: envelope.auth.baseURL || BASE_URL,
+    defaultHeaders
+  })
+
+  yield * runChatCompletions(envelope, client, {
+    provider: 'openrouter',
+    stream: true,
+    mutateArgs: (env, args) => {
+      const routing = env.providerOptions?.openrouter
+      if (routing && (routing.order || routing.allow || routing.deny)) {
+        args.provider = {}
+        if (routing.order) args.provider.order = routing.order
+        if (routing.allow) args.provider.allow = routing.allow
+        if (routing.deny) args.provider.deny = routing.deny
+      }
+    }
+  }, { signal: deps.signal, log: deps.log, span: deps.span })
+}

package/js/session/adapters/xai.js

@@ -0,0 +1,27 @@
+/**
+ * xAI adapter — OpenAI Responses API over x.ai/v1. Delegates to the
+ * `openai` adapter with a baseURL-configured client; the openai
+ * adapter branches on `envelope.provider === 'openai'` for fields
+ * that differ between vendors (reasoning param, safety_identifier).
+ *
+ * @module session/adapters/xai
+ */
+
+import OpenAI from 'openai'
+
+import { openai } from './openai.js'
+
+const BASE_URL = 'https://api.x.ai/v1'
+
+/**
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {{client?: any, signal?: AbortSignal}} [deps]
+ * @returns {AsyncGenerator<import('#core/events.js').Event>}
+ */
+export async function * xai (envelope, deps = {}) {
+  const client = deps.client ?? new OpenAI({
+    apiKey: envelope.auth.key,
+    baseURL: envelope.auth.baseURL || BASE_URL
+  })
+  yield * openai(envelope, { ...deps, client })
+}

package/js/session/bin.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * Session process entrypoint. Invoked by thin-gate (or any supervisor)
+ * as `node <path-to-this-file>`. Reads one CallEnvelope from stdin
+ * and writes events to stdout; stderr is for structured logs.
+ *
+ * At startup:
+ *   - Lazy-initializes OTel SDK when `OTEL_EXPORTER_OTLP_ENDPOINT`
+ *     is set (exports spans to the configured collector).
+ *   - Constructs the default logger from `MOHDEL_LOG_LEVEL` /
+ *     `MOHDEL_VERBOSITY` (see LOGGING.md).
+ *
+ * `run.js` reads `logger` as a module-level import — `bin.js` does
+ * not need to thread it through.
+ *
+ * @module session/bin
+ */
+
+import { drive } from './driver.js'
+import { ensureOtelInitialized } from './_tracing.js'
+import { logger } from './_logger.js'
+import { initCatalogFromDefault } from './adapters/_catalog.js'
+import { initProvidersFromDefault } from './adapters/_providers.js'
+
+async function main () {
+  await ensureOtelInitialized()
+
+  // `MOHDEL_NO_CONFIG_DISK=1` tells the session that a supervisor is
+  // responsible for pushing config over stdin (`op: set_catalog`,
+  // future `op: set_providers`). Skip the eager disk init in that
+  // case — the catalog cache stays empty until the first injection
+  // lands. Standalone use (CLI, tests) leaves the variable unset and
+  // the cache warms from `~/.config/mohdel/` as before.
+  const noDisk = process.env.MOHDEL_NO_CONFIG_DISK === '1'
+  if (!noDisk) {
+    await Promise.all([initCatalogFromDefault(), initProvidersFromDefault()])
+  }
+
+  logger.info(
+    {
+      level: logger.level,
+      verbosity: logger.verbosity,
+      pid: process.pid,
+      configFrom: noDisk ? 'supervisor' : 'disk'
+    },
+    '[mohdel:session] starting'
+  )
+  await drive(process.stdin, process.stdout)
+}
+
+main().catch((e) => {
+  logger.fatal({ err: e }, '[mohdel:session] fatal')
+  process.exit(1)
+})