dsh-endpoint 0.0.0-stage → 1.0.0

package/src/openai/errors.js

@@ -0,0 +1,68 @@
+/** OpenAI-shaped errors, mapped from DSH's stable failure codes. */
+export class ApiError extends Error {
+  /**
+   * @param {number} status
+   * @param {string} type
+   * @param {string} message
+   * @param {{ code?: string, param?: string }} [extra]
+   */
+  constructor(status, type, message, extra = {}) {
+    super(message)
+    this.status = status
+    this.type = type
+    this.code = extra.code
+    this.param = extra.param
+  }
+}
+
+export function badRequest(message, param) {
+  return new ApiError(400, 'invalid_request_error', message, { param })
+}
+
+export function notFound(message) {
+  return new ApiError(404, 'model_not_found', message, { code: 'model_not_found' })
+}
+
+const CODE_MAP = {
+  AUTH: [401, 'authentication_error', 'authentication_error'],
+  INVALID_CREDENTIAL: [401, 'authentication_error', 'invalid_api_key'],
+  MISSING_CREDENTIAL: [503, 'api_error', 'missing_credential'],
+  RATE_LIMIT: [429, 'rate_limit_error', 'rate_limit_exceeded'],
+  QUOTA: [429, 'insufficient_quota', 'insufficient_quota'],
+  ACCOUNT_QUOTA: [429, 'insufficient_quota', 'insufficient_quota'],
+  CONTEXT_WINDOW_EXCEEDED: [400, 'invalid_request_error', 'context_length_exceeded'],
+  NO_ADAPTER: [404, 'model_not_found', 'model_not_found'],
+  UNKNOWN_MODEL: [404, 'model_not_found', 'model_not_found'],
+  INVALID_MODEL_INFO: [404, 'model_not_found', 'model_not_found'],
+  INVALID_MODEL_CONTEXT: [404, 'model_not_found', 'model_not_found'],
+  INVALID_MODEL_MAX_TOKENS: [404, 'model_not_found', 'model_not_found'],
+  UNSUPPORTED_OPTION: [400, 'invalid_request_error', 'unsupported_parameter'],
+  IMAGE_OFFLOAD_REQUIRED: [400, 'invalid_request_error', 'image_too_large'],
+}
+
+/**
+ * Map a DSH failure (`{ code, message }`) to an OpenAI error.
+ * @param {{ code?: string, message?: string }} failure
+ */
+export function fromLlmFailure(failure) {
+  const code = typeof failure?.code === 'string' ? failure.code : undefined
+  const message = typeof failure?.message === 'string' ? failure.message : 'model call failed'
+  const mapped = code === undefined ? undefined : CODE_MAP[code]
+  if (mapped === undefined) {
+    return new ApiError(500, 'api_error', message, { code: code ?? 'internal_error' })
+  }
+  const [status, type, openaiCode] = mapped
+  return new ApiError(status, type, message, { code: openaiCode })
+}
+
+export function toOpenAiBody(error, requestId) {
+  return {
+    error: {
+      message: error.message,
+      type: error.type,
+      param: error.param ?? null,
+      code: error.code ?? null,
+    },
+    ...(requestId === undefined ? {} : { request_id: requestId }),
+  }
+}

package/src/openai/media.js

@@ -0,0 +1,120 @@
+import { badRequest } from './errors.js'
+
+const IMAGE_TYPES = new Map([
+  ['image/png', 'image/png'],
+  ['image/jpeg', 'image/jpeg'],
+  ['image/jpg', 'image/jpeg'],
+  ['image/webp', 'image/webp'],
+  ['image/gif', 'image/gif'],
+])
+
+const TEXT_TYPES = [
+  'application/json',
+  'application/xml',
+  'application/x-yaml',
+  'application/yaml',
+  'application/javascript',
+  'application/typescript',
+  'application/sql',
+]
+
+const TEXT_MAX_BYTES = 512 * 1024
+
+/**
+ * Parse one `data:` URL. Remote URLs are rejected on purpose: the endpoint
+ * must not fetch arbitrary hosts on behalf of a client (SSRF), and every
+ * supported client can inline base64.
+ *
+ * @param {string} url
+ * @param {string} param
+ * @returns {{ mediaType: string, data: Buffer }}
+ */
+export function parseDataUrl(url, param) {
+  if (typeof url !== 'string' || url.length === 0) throw badRequest(`${param} must be a string`, param)
+  if (/^https?:/i.test(url)) {
+    throw badRequest(
+      'remote file URLs are not supported; send a data: URL with base64 content instead',
+      param,
+    )
+  }
+  const match = /^data:([^;,]+)((?:;[^,]*)*?),(.*)$/s.exec(url)
+  if (match === null) throw badRequest(`${param} must be a data: URL`, param)
+  const mediaType = match[1].trim().toLowerCase()
+  const parameters = match[2] ?? ''
+  const payload = match[3] ?? ''
+  let data
+  if (/;base64/i.test(parameters)) {
+    // Guard before decoding: base64 expands by ~4/3.
+    if (payload.length > 64 * 1024 * 1024) throw badRequest(`${param} is too large`, param)
+    data = Buffer.from(payload, 'base64')
+  } else {
+    data = Buffer.from(decodeURIComponent(payload), 'utf8')
+  }
+  if (data.length === 0) throw badRequest(`${param} is empty`, param)
+  return { mediaType, data }
+}
+
+/** Normalise an image media type, or `undefined` when it is not a raster image. */
+export function imageMediaType(mediaType) {
+  return IMAGE_TYPES.get(mediaType)
+}
+
+/** Whether a media type should be inlined as UTF-8 text. */
+export function isTextMediaType(mediaType) {
+  return mediaType.startsWith('text/') || TEXT_TYPES.includes(mediaType)
+}
+
+/**
+ * Decode one inline file (image or text) into a DSH content block.
+ *
+ * @param {object} input
+ * @param {string} input.url - data URL
+ * @param {string} [input.name] - original filename
+ * @param {string} input.param - request path for error messages
+ * @param {object} options
+ * @param {(inputs: Array<{ data: Uint8Array, mediaType: string, name?: string }>) => Promise<Array<object>>} [options.saveImages]
+ * @param {boolean} [options.allowText]
+ * @returns {Promise<object>} text or image block
+ */
+export async function decodeInlineFile({ url, name, param }, options = {}) {
+  const { mediaType, data } = parseDataUrl(url, param)
+  const image = imageMediaType(mediaType)
+  if (image !== undefined) {
+    if (typeof options.saveImages !== 'function') {
+      throw badRequest('image input is not available in this profile', param)
+    }
+    const [ref] = await options.saveImages([{ data: new Uint8Array(data), mediaType: image, ...(name ? { name } : {}) }])
+    if (ref === undefined) throw badRequest('could not store the image attachment', param)
+    return { type: 'image', attachment: ref }
+  }
+  if (isTextMediaType(mediaType) && options.allowText === true) {
+    const truncated = data.length > TEXT_MAX_BYTES
+    const text = data.subarray(0, TEXT_MAX_BYTES).toString('utf8')
+    const header = `[file${name ? `: ${name}` : ''}${truncated ? ', truncated' : ''}]\n`
+    return { type: 'text', text: header + text }
+  }
+  throw badRequest(
+    `unsupported inline media type "${mediaType}"; images and text files are supported, other documents must be sent as text`,
+    param,
+  )
+}
+
+/**
+ * OpenAI `file` content part: `{ type: 'file', file: { filename, file_data } }`.
+ * `file_id` refers to the Files API, which this endpoint does not implement.
+ */
+export async function decodeFilePart(part, param, options = {}) {
+  const file = part?.file
+  if (file === null || typeof file !== 'object') throw badRequest(`${param}.file is required`, param)
+  if (typeof file.file_id === 'string') {
+    throw badRequest('file_id is not supported; inline the bytes as file_data', `${param}.file.file_id`)
+  }
+  const fileData = file.file_data ?? file.data
+  if (typeof fileData !== 'string') {
+    throw badRequest(`${param}.file.file_data is required`, `${param}.file.file_data`)
+  }
+  return decodeInlineFile(
+    { url: fileData, name: typeof file.filename === 'string' ? file.filename : undefined, param },
+    { ...options, allowText: true },
+  )
+}

package/src/openai/stream.js

@@ -0,0 +1,294 @@
+import { randomUUID } from 'node:crypto'
+
+export function newCompletionId() {
+  return `chatcmpl-${randomUUID().replaceAll('-', '')}`
+}
+
+/** Map a DSH `usage` chunk to an OpenAI usage object. */
+export function toOpenAiUsage(usage) {
+  if (usage === null || typeof usage !== 'object') return undefined
+  const input = number(usage.inputTokens)
+  const output = number(usage.outputTokens)
+  const cacheRead = number(usage.cacheReadTokens)
+  const cacheWrite = number(usage.cacheWriteTokens)
+  const reasoning = number(usage.reasoningTokens)
+  return {
+    prompt_tokens: input + cacheRead + cacheWrite,
+    completion_tokens: output,
+    total_tokens: input + cacheRead + cacheWrite + output,
+    prompt_tokens_details: { cached_tokens: cacheRead },
+    completion_tokens_details: { reasoning_tokens: reasoning },
+  }
+}
+
+function number(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0
+}
+
+/** Map a DSH finish reason to an OpenAI `finish_reason`. */
+export function toFinishReason(reason) {
+  switch (reason?.kind) {
+    case 'stop':
+      return 'stop'
+    case 'tool-calls':
+      return 'tool_calls'
+    case 'max-tokens':
+      return 'length'
+    case 'aborted':
+      return 'stop'
+    case 'error':
+      return 'stop'
+    default:
+      return 'stop'
+  }
+}
+
+/**
+ * Assembles raw DSH chunks into the assistant content blocks the session log
+ * expects, while feeding the SSE writer.
+ */
+export class CompletionCollector {
+  constructor() {
+    this.chunks = []
+    this.partials = new Map()
+    this.text = ''
+    this.reasoning = ''
+    this.usage = undefined
+    this.finishReason = undefined
+    this.failure = undefined
+  }
+
+  push(chunk) {
+    this.chunks.push(chunk)
+    switch (chunk?.type) {
+      case 'block-start': {
+        this.#ensure(chunk.index, chunk.blockType)
+        return
+      }
+      case 'text-delta': {
+        const partial = this.#ensure(chunk.index, 'text')
+        partial.text += chunk.text
+        this.text += chunk.text
+        return
+      }
+      case 'reasoning-delta': {
+        const partial = this.#ensure(chunk.index, 'reasoning')
+        partial.text += chunk.text
+        this.reasoning += chunk.text
+        return
+      }
+      case 'tool-call-delta': {
+        const partial = this.#ensure(chunk.index, 'tool-call')
+        if (typeof chunk.id === 'string' && chunk.id.length > 0) partial.id = chunk.id
+        if (typeof chunk.name === 'string' && chunk.name.length > 0) partial.name = chunk.name
+        partial.arguments += chunk.argumentsDelta ?? ''
+        return
+      }
+      case 'block-end': {
+        const partial = this.#ensure(chunk.index, chunk.block?.type ?? 'text')
+        partial.closed = chunk.block
+        return
+      }
+      case 'usage': {
+        this.usage = chunk.usage
+        return
+      }
+      case 'finish': {
+        this.finishReason = chunk.reason
+        if (chunk.reason?.kind === 'error') this.failure = chunk.reason.failure
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  get blocks() {
+    const blocks = []
+    for (const [, partial] of [...this.partials].sort((a, b) => a[0] - b[0])) {
+      if (partial.closed !== undefined) {
+        blocks.push(partial.closed)
+        continue
+      }
+      if (partial.type === 'text' && partial.text.length > 0) blocks.push({ type: 'text', text: partial.text })
+      else if (partial.type === 'reasoning' && partial.text.length > 0) {
+        blocks.push({ type: 'reasoning', text: partial.text })
+      } else if (partial.type === 'tool-call') {
+        blocks.push({
+          type: 'tool-call',
+          id: partial.id ?? randomUUID(),
+          name: partial.name ?? '',
+          arguments: partial.arguments,
+        })
+      }
+    }
+    return blocks
+  }
+
+  get toolCalls() {
+    return this.blocks.filter((block) => block.type === 'tool-call')
+  }
+
+  #ensure(index, type) {
+    let partial = this.partials.get(index)
+    if (partial === undefined) {
+      partial = { type, text: '', arguments: '', id: undefined, name: undefined, closed: undefined }
+      this.partials.set(index, partial)
+    }
+    return partial
+  }
+}
+
+/**
+ * Incremental OpenAI SSE writer for one completion.
+ *
+ * DSH block indexes are not OpenAI tool indexes (text and reasoning blocks are
+ * interleaved), so tool calls get their own 0-based counter.
+ */
+export class SseWriter {
+  constructor({ res, id, created, model }) {
+    this.res = res
+    this.id = id
+    this.created = created
+    this.model = model
+    this.toolIndex = new Map()
+    this.nextToolIndex = 0
+    this.done = false
+  }
+
+  #write(payload) {
+    if (this.done) return
+    this.res.write(`data: ${JSON.stringify(payload)}\n\n`)
+  }
+
+  #frame(delta, finishReason = null) {
+    return {
+      id: this.id,
+      object: 'chat.completion.chunk',
+      created: this.created,
+      model: this.model,
+      choices: [{ index: 0, delta, finish_reason: finishReason }],
+    }
+  }
+
+  start() {
+    this.#write(this.#frame({ role: 'assistant', content: '' }))
+  }
+
+  /** @param {object} chunk */
+  chunk(chunk) {
+    switch (chunk?.type) {
+      case 'text-delta':
+        if (chunk.text.length > 0) this.#write(this.#frame({ content: chunk.text }))
+        return
+      case 'reasoning-delta':
+        if (chunk.text.length > 0) this.#write(this.#frame({ reasoning_content: chunk.text }))
+        return
+      case 'tool-call-delta': {
+        let index = this.toolIndex.get(chunk.index)
+        const first = index === undefined
+        if (first) {
+          index = this.nextToolIndex
+          this.nextToolIndex += 1
+          this.toolIndex.set(chunk.index, index)
+        }
+        this.#write(
+          this.#frame({
+            tool_calls: [
+              {
+                index,
+                ...(first ? { id: chunk.id, type: 'function' } : {}),
+                function: {
+                  ...(first && typeof chunk.name === 'string' ? { name: chunk.name } : {}),
+                  arguments: chunk.argumentsDelta ?? '',
+                },
+              },
+            ],
+          }),
+        )
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  finish(reason) {
+    this.#write(this.#frame({}, toFinishReason(reason)))
+  }
+
+  /** Emit an error frame on an already-started stream. */
+  writeError(body) {
+    this.#write(body)
+  }
+
+  usage(usage) {
+    const mapped = toOpenAiUsage(usage)
+    if (mapped === undefined) return
+    this.#write({
+      id: this.id,
+      object: 'chat.completion.chunk',
+      created: this.created,
+      model: this.model,
+      choices: [],
+      usage: mapped,
+    })
+  }
+
+  end() {
+    if (this.done) return
+    this.done = true
+    this.res.write('data: [DONE]\n\n')
+    this.res.end()
+  }
+}
+
+/**
+ * Tracks OpenAI `stop` sequences across delta boundaries and reports where the
+ * visible text must be cut. DSH adapters do not all accept `stop`, so the
+ * endpoint honours it itself.
+ */
+export class StopMatcher {
+  /** @param {string[]} sequences */
+  constructor(sequences) {
+    this.sequences = sequences.filter((value) => typeof value === 'string' && value.length > 0)
+    this.seen = ''
+    this.hit = false
+  }
+
+  get active() {
+    return this.sequences.length > 0
+  }
+
+  /**
+   * @param {string} delta
+   * @returns {{ text: string, hit: boolean }}
+   */
+  push(delta) {
+    if (!this.active || this.hit) return { text: '', hit: this.hit }
+    this.seen += delta
+    let cut = this.seen.length
+    for (const sequence of this.sequences) {
+      const index = this.seen.indexOf(sequence)
+      if (index >= 0 && index < cut) cut = index
+    }
+    if (cut < this.seen.length) {
+      this.hit = true
+      const text = this.seen.slice(0, cut)
+      return { text, hit: true }
+    }
+    // Emit everything that can no longer be part of a stop sequence.
+    const held = this.sequences.reduce((max, sequence) => Math.max(max, sequence.length), 1) - 1
+    if (this.seen.length <= held) return { text: '', hit: false }
+    const text = this.seen.slice(0, this.seen.length - held)
+    this.seen = this.seen.slice(this.seen.length - held)
+    return { text, hit: false }
+  }
+
+  /** Remaining text when the stream ends without a stop hit. */
+  flush() {
+    const text = this.seen
+    this.seen = ''
+    return text
+  }
+}