mohdel 0.90.0

package/js/client/index.js

@@ -0,0 +1,16 @@
+/**
+ * mohdel client — thin caller for thin-gate's data-plane unix socket.
+ *
+ * Public surface (0.90):
+ *   - call(envelope, { socketPath, signal }): AsyncGenerator<Event>
+ *   - callImage(envelope, { socketPath, signal }): Promise<ImageResult>
+ *
+ * No provider SDKs are imported transitively. This module can be
+ * consumed by callers that must not pull openai-node, anthropic-sdk,
+ * etc. into their bundle.
+ *
+ * @module client
+ */
+
+export { call } from './call.js'
+export { callImage } from './call_image.js'

package/js/client/ndjson.js

@@ -0,0 +1,29 @@
+/**
+ * NDJSON line parser. Yields parsed objects from a byte/string stream.
+ *
+ * @module client/ndjson
+ */
+
+const MAX_LINE_BYTES = 16 * 1024 * 1024
+
+/**
+ * @param {AsyncIterable<Buffer|string>} stream
+ * @returns {AsyncGenerator<unknown>}
+ */
+export async function * parseNDJSON (stream) {
+  let buf = ''
+  for await (const chunk of stream) {
+    buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8')
+    if (buf.length > MAX_LINE_BYTES) {
+      throw new Error(`NDJSON line exceeds ${MAX_LINE_BYTES} bytes without newline`)
+    }
+    let nl
+    while ((nl = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, nl).trim()
+      buf = buf.slice(nl + 1)
+      if (line) yield JSON.parse(line)
+    }
+  }
+  const tail = buf.trim()
+  if (tail) yield JSON.parse(tail)
+}

package/js/client/transport.js

@@ -0,0 +1,48 @@
+/**
+ * Low-level unix-socket HTTP transport for mohdel client.
+ *
+ * Stateless — each request opens and closes its own socket. Pooling/
+ * keep-alive can be added later if measurement shows a bottleneck;
+ * unix-socket overhead is typically negligible.
+ *
+ * @module client/transport
+ */
+
+import http from 'node:http'
+
+/**
+ * @typedef {object} RequestOptions
+ * @property {string} socketPath
+ * @property {string} path
+ * @property {string} method
+ * @property {object} [body]
+ * @property {AbortSignal} [signal]
+ * @property {Record<string,string>} [headers]
+ */
+
+/**
+ * @param {RequestOptions} options
+ * @returns {Promise<http.IncomingMessage>}
+ */
+export function requestUnix ({ socketPath, path, method, body, signal, headers }) {
+  return new Promise((resolve, reject) => {
+    /** @type {Record<string,string>} */
+    const h = { ...(headers || {}) }
+    if (body !== undefined) h['content-type'] = 'application/json'
+
+    const req = http.request({ socketPath, path, method, headers: h }, resolve)
+    req.on('error', reject)
+
+    if (signal) {
+      if (signal.aborted) {
+        req.destroy(new Error('aborted'))
+        reject(new Error('aborted'))
+        return
+      }
+      signal.addEventListener('abort', () => req.destroy(new Error('aborted')), { once: true })
+    }
+
+    if (body !== undefined) req.end(JSON.stringify(body))
+    else req.end()
+  })
+}

package/js/core/envelope.js

@@ -0,0 +1,141 @@
+/**
+ * Canonical call envelope — the frozen wire shape for a single
+ * inference call. Flat `answer(prompt, options)` surface plus the
+ * minimum transport metadata needed to cross a process boundary
+ * (callId, authId, auth.key, traceparent).
+ *
+ * camelCase on the wire. JSON on NDJSON frames. Rust mirror:
+ * `rust/thin-gate/src/protocol.rs`.
+ *
+ * @module core/envelope
+ */
+
+/**
+ * @typedef {object} CallEnvelope
+ *
+ * @property {string} callId
+ *   Unique per call.
+ * @property {string} authId
+ *   Quota-scoping identity (rate-limit/cooldown bucket). Distinct
+ *   from `identifier`, which is the provider-side safety/tracking
+ *   ID that gets forwarded to the provider API.
+ * @property {Auth} auth
+ * @property {string} [traceparent]  W3C tracecontext header.
+ * @property {string} [baggage]      W3C baggage header.
+ *
+ * @property {string} provider       Adapter discriminator.
+ * @property {string} model          Provider-native model id.
+ *
+ * @property {(string|Message[])} prompt
+ *   Either a plain string or a structured array of messages.
+ *
+ * --- Answer options (flat) ---
+ *
+ * @property {number} [outputBudget]
+ *   Max output tokens (clamped to model's outputTokenLimit).
+ * @property {('text'|'json')} [outputType]
+ *   Default 'text'.
+ * @property {('chat'|'coding'|'analysis'|'translation'|'creative')} [outputStyle]
+ * @property {string} [outputEffort]
+ *   Thinking effort level. Valid keys are per-model — validated at
+ *   runtime against the curated entry's `thinkingEffortLevels`.
+ *   Default is the model's `defaultThinkingEffort`.
+ *
+ * @property {MediaRef[]} [images]
+ * @property {MediaRef[]} [videos]
+ * @property {boolean} [cache]
+ *   Cache uploaded files (Gemini videos).
+ *
+ * @property {ToolSpec[]} [tools]
+ * @property {('auto'|'required'|'none'|string)} [toolChoice]
+ * @property {boolean} [parallelToolCalls]
+ *
+ * @property {string} [identifier]
+ *   Opaque per-user ID passed to the provider for tracking / abuse
+ *   monitoring.
+ *
+ * @property {Object<string, object>} [providerOptions]
+ *   Namespaced bag of provider-specific knobs that don't fit the
+ *   shared envelope. Keys are provider names; values are arbitrary
+ *   JSON objects the matching adapter consumes. Today only
+ *   `providerOptions.openrouter = {order?, allow?, deny?}` is
+ *   recognized (OpenRouter routing preferences). Unknown keys are
+ *   accepted on the wire and silently ignored by adapters that
+ *   don't read them — upgrade to a typed sub-struct per provider if
+ *   strict validation becomes necessary.
+ */
+
+/**
+ * @typedef {object} Auth
+ * @property {string} key  Provider API key. Redact in logs; never persist.
+ * @property {string} [baseURL]
+ *   Optional override of the adapter's default provider endpoint.
+ *   Lets callers point at a self-hosted deployment, regional endpoint,
+ *   proxy, or test server. Adapters treat it as `baseURL ?? ADAPTER_DEFAULT`.
+ */
+
+/**
+ * @typedef {object} Message
+ * @property {('system'|'user'|'assistant'|'tool')} role
+ * @property {(string|MessagePart[])} content
+ * @property {string} [toolCallId]
+ *   Set on `tool` messages — identifies which assistant tool call
+ *   this is a response to.
+ * @property {string} [name]
+ *   Optional function name for `tool` messages (providers that
+ *   require naming the tool alongside the response).
+ * @property {ToolCall[]} [toolCalls]
+ *   Set on `assistant` messages when the model called tools in this
+ *   turn. Preserves multi-turn histories where the assistant both
+ *   spoke text AND invoked tools; adapters emit the provider-native
+ *   tool_use / function_call / tool_calls representation.
+ */
+
+/**
+ * @typedef {object} ToolCall
+ * @property {string} id
+ * @property {string} name
+ * @property {object} arguments  Parsed object, not a JSON string.
+ */
+
+/**
+ * @typedef {object} MessagePart
+ * @property {('text'|'reasoning')} type
+ * @property {string} text
+ */
+
+/**
+ * @typedef {object} MediaRef
+ * @property {string} fileUri
+ * @property {string} mimeType
+ */
+
+/**
+ * @typedef {object} ToolSpec
+ * @property {string} name
+ * @property {string} [description]
+ * @property {object} parameters  JSON Schema
+ */
+
+export const ENVELOPE_FIELDS = Object.freeze([
+  'callId',
+  'authId',
+  'auth',
+  'traceparent',
+  'baggage',
+  'provider',
+  'model',
+  'prompt',
+  'outputBudget',
+  'outputType',
+  'outputStyle',
+  'outputEffort',
+  'images',
+  'videos',
+  'cache',
+  'tools',
+  'toolChoice',
+  'parallelToolCalls',
+  'identifier',
+  'providerOptions'
+])

package/js/core/errors.js

@@ -0,0 +1,75 @@
+/**
+ * `TypedError` — wire-format error. Carries `message` (machine key),
+ * optional `detail` (user-facing context), `severity` (lowercase
+ * string), `retryable`, and optional `type` (canonical tag).
+ *
+ * Rust mirror: `rust/thin-gate/src/protocol.rs::TypedError`.
+ *
+ * @module core/errors
+ */
+
+/**
+ * @typedef {('trace'|'debug'|'info'|'warn'|'error'|'fatal')} SeverityTag
+ */
+
+/**
+ * @typedef {object} TypedError
+ * @property {string} message
+ *   Top-level message. Never echo provider response bodies.
+ * @property {string} [detail]
+ *   User-facing error detail (mirrors `MohdelError.detail`).
+ * @property {SeverityTag} severity
+ * @property {boolean} retryable
+ * @property {string} [type]
+ *   Optional canonical tag (e.g. `'PROVIDER_COOLDOWN'`, `'AUTH_INVALID'`).
+ */
+
+export const SEVERITY_TAGS = Object.freeze([
+  'trace', 'debug', 'info', 'warn', 'error', 'fatal'
+])
+
+export class MohdelTypedError extends Error {
+  /**
+   * @param {string} message
+   * @param {{
+   *   severity?: SeverityTag,
+   *   retryable?: boolean,
+   *   detail?: string,
+   *   type?: string
+   * }} [options]
+   */
+  constructor (message, { severity = 'error', retryable = false, detail, type } = {}) {
+    super(message)
+    this.name = 'MohdelTypedError'
+    this.severity = severity
+    this.retryable = retryable
+    if (detail) this.detail = detail
+    if (type) this.type = type
+  }
+
+  /** @returns {TypedError} */
+  toJSON () {
+    /** @type {TypedError} */
+    const out = {
+      message: this.message,
+      severity: this.severity,
+      retryable: this.retryable
+    }
+    if (this.detail) out.detail = this.detail
+    if (this.type) out.type = this.type
+    return out
+  }
+
+  /**
+   * @param {TypedError} data
+   * @returns {MohdelTypedError}
+   */
+  static fromJSON (data) {
+    return new MohdelTypedError(data.message, {
+      severity: data.severity,
+      retryable: data.retryable,
+      detail: data.detail,
+      type: data.type
+    })
+  }
+}

package/js/core/events.js

@@ -0,0 +1,96 @@
+/**
+ * Event union for the session → thin-gate → client stream.
+ *
+ * Three events:
+ *   - `delta`  — streaming chunk (message text or function-call args).
+ *   - `done`   — terminal with the full `AnswerResult`.
+ *   - `error`  — wire-format error (serializable `TypedError`).
+ *
+ * Rust mirror: `rust/thin-gate/src/protocol.rs::Event`.
+ *
+ * @module core/events
+ */
+
+/**
+ * @typedef {(DeltaEvent | DoneEvent | ErrorEvent)} Event
+ */
+
+/**
+ * Streaming chunk: `{ type: 'message' | 'function_call', delta: string }`.
+ *
+ * @typedef {object} DeltaEvent
+ * @property {'delta'} type
+ * @property {DeltaChunk} delta
+ */
+
+/**
+ * @typedef {object} DeltaChunk
+ * @property {('message'|'function_call')} type
+ * @property {string} delta
+ */
+
+/**
+ * Terminal event on success.
+ *
+ * @typedef {object} DoneEvent
+ * @property {'done'} type
+ * @property {AnswerResult} result
+ */
+
+/**
+ * Terminal event on failure.
+ *
+ * @typedef {object} ErrorEvent
+ * @property {'error'} type
+ * @property {import('./errors.js').TypedError} error
+ */
+
+/**
+ * Inference result — the shape returned by the factory `answer()` and
+ * carried in `DoneEvent.result`.
+ *
+ * @typedef {object} AnswerResult
+ * @property {import('./status.js').Status} status
+ *   `'completed' | 'tool_use' | 'incomplete'`.
+ * @property {(string|null)} output
+ *   Final text (null when `status === 'tool_use'` with no text).
+ * @property {number} inputTokens
+ * @property {number} outputTokens
+ * @property {number} thinkingTokens
+ * @property {number} cost
+ *   USD, computed from curated pricing. Single number (not a breakdown).
+ * @property {Timestamps} timestamps
+ * @property {string} [warning]
+ *   `'insufficientOutputBudget' | 'cancelled' | ...` additive union.
+ * @property {ToolCall[]} [toolCalls]
+ *   Present when `status === 'tool_use'`.
+ */
+
+/**
+ * `process.hrtime.bigint()` values as strings (nanoseconds).
+ *
+ * @typedef {object} Timestamps
+ * @property {string} start  Adapter invocation start.
+ * @property {string} first  Time of first delta.
+ * @property {string} end    Completion time.
+ */
+
+/**
+ * Tool call as emitted on `AnswerResult.toolCalls`. `arguments` is a
+ * **parsed object**, not a JSON string.
+ *
+ * @typedef {object} ToolCall
+ * @property {string} id
+ * @property {string} name
+ * @property {object} arguments
+ */
+
+export const EVENT_TYPES = Object.freeze(['delta', 'done', 'error'])
+
+/**
+ * @param {unknown} x
+ * @returns {x is Event}
+ */
+export function isEvent (x) {
+  return x !== null && typeof x === 'object' && EVENT_TYPES.includes(/** @type {any} */(x).type)
+}

package/js/core/image.js

@@ -0,0 +1,58 @@
+/**
+ * Image-generation envelope and result.
+ *
+ * Separate call path from `CallEnvelope` / `AnswerResult`: image
+ * generation is a single synchronous request/response (no streaming).
+ * Result shape: `{ status, images, seed, timestamps }`.
+ *
+ * @module core/image
+ */
+
+/**
+ * @typedef {object} ImageEnvelope
+ *
+ * @property {string} callId
+ * @property {string} authId
+ * @property {import('./envelope.js').Auth} auth
+ * @property {string} [traceparent]
+ * @property {string} [baggage]
+ *
+ * @property {string} provider
+ * @property {string} model
+ * @property {string} prompt
+ *
+ * @property {string} [size]       e.g. "1024x1024". Provider-specific.
+ * @property {number} [seed]       Deterministic generation seed (provider support varies).
+ */
+
+/**
+ * @typedef {object} ImageData
+ * @property {string} mimeType
+ * @property {string} [url]        Remote URL (transient — providers may expire).
+ * @property {string} [base64]     Inline base64-encoded image bytes.
+ */
+
+/**
+ * @typedef {object} ImageResult
+ *
+ * @property {'completed'} status
+ *   Images are one-shot — no `incomplete` state.
+ * @property {ImageData[]} images
+ * @property {number | null} seed
+ *   Echo of provider seed when available; null otherwise.
+ * @property {{start: string, first: string, end: string}} timestamps
+ *   hrtime-bigint-as-string. `first` = `end` for image (no streaming).
+ */
+
+export const IMAGE_ENVELOPE_FIELDS = Object.freeze([
+  'callId',
+  'authId',
+  'auth',
+  'traceparent',
+  'baggage',
+  'provider',
+  'model',
+  'prompt',
+  'size',
+  'seed'
+])

package/js/core/index.js

@@ -0,0 +1,10 @@
+/**
+ * Internal barrel for mohdel 0.90 core types.
+ *
+ * @module core
+ */
+
+export * from './envelope.js'
+export * from './events.js'
+export * from './status.js'
+export * from './errors.js'

package/js/core/status.js

@@ -0,0 +1,48 @@
+/**
+ * Answer-result status contract.
+ *
+ * Three states:
+ *   - `completed`  — the call finished normally.
+ *   - `tool_use`   — the model emitted tool calls; the caller is
+ *                    expected to round-trip results back.
+ *   - `incomplete` — the call was cut short (budget, cancel, policy).
+ *
+ * Rust mirror: `rust/thin-gate/src/protocol.rs::Status`.
+ *
+ * @module core/status
+ */
+
+/** @typedef {('completed'|'tool_use'|'incomplete')} Status */
+
+/**
+ * Warning values emitted on `AnswerResult.warning` when status is
+ * `incomplete`:
+ *   - `insufficientOutputBudget` — the model hit `max_tokens`.
+ *   - `cancelled` — the call was aborted via a cancel control
+ *     message or `AbortSignal`.
+ *
+ * Additive: future releases may add new warning strings; consumers
+ * should treat unknown warnings as pass-through metadata.
+ *
+ * @typedef {('insufficientOutputBudget'|'cancelled'|string)} Warning
+ */
+
+export const STATUS_COMPLETED = 'completed'
+export const STATUS_TOOL_USE = 'tool_use'
+export const STATUS_INCOMPLETE = 'incomplete'
+export const STATUSES = Object.freeze([
+  STATUS_COMPLETED,
+  STATUS_TOOL_USE,
+  STATUS_INCOMPLETE
+])
+
+export const WARNING_INSUFFICIENT_OUTPUT_BUDGET = 'insufficientOutputBudget'
+export const WARNING_CANCELLED = 'cancelled'
+
+/**
+ * @param {unknown} x
+ * @returns {x is Status}
+ */
+export function isStatus (x) {
+  return typeof x === 'string' && STATUSES.includes(/** @type {Status} */(x))
+}