dsh-endpoint 0.0.0-stage → 1.0.0

package/src/config.js

@@ -0,0 +1,89 @@
+import z from '@deepseek-ai/schemastery'
+
+/**
+ * Plugin configuration. The Settings -> Plugins form is generated from this
+ * schema, so every field here is also the management surface.
+ */
+export const Config = z.object({
+  host: z
+    .string()
+    .default('127.0.0.1')
+    .description('Bind address. 127.0.0.1 keeps the endpoint on this machine; 0.0.0.0 exposes every interface.'),
+  port: z
+    .natural()
+    .max(65535)
+    .default(43130)
+    .description('Listening port. The GUI owns 43129, so the endpoint defaults to the next one.'),
+  defaultModel: z
+    .string()
+    .default('')
+    .description('Model used when a request omits `model`, as `provider/model`.'),
+  modelAliases: z
+    .dict(z.string())
+    .default({})
+    .description('Extra request names mapped to `provider/model`, e.g. `gpt-4o: opencode-go/deepseek-v4.1-flash`.'),
+  session: z
+    .object({
+      header: z
+        .string()
+        .default('x-dsh-session-id')
+        .description('Request/response header carrying the DSH session id.'),
+      mirror: z
+        .boolean()
+        .default(true)
+        .description('Mirror each conversation into a real DSH session so it appears in the sidebar.'),
+      deriveFrom: z
+        .array(z.string())
+        .default(['model', 'first-user'])
+        .description('Fingerprint inputs used when a request carries no session id: model, system, first-user.'),
+      mappingTtlDays: z
+        .natural()
+        .default(3)
+        .description('Days an external conversation id keeps its DSH session after its last use.'),
+      archiveOnExpire: z
+        .boolean()
+        .default(true)
+        .description('Archive the mirrored session when its mapping expires.'),
+      workspacePath: z
+        .string()
+        .default('')
+        .description('Directory whose workspace groups mirrored sessions. Empty means $DSH_HOME/dsh-endpoint/conversations.'),
+      maxOpenSessions: z
+        .natural()
+        .default(64)
+        .description('Upper bound on sessions whose write handle stays open (each one also blocks GUI takeover).'),
+    })
+    .default({}),
+  limits: z
+    .object({
+      maxBodyBytes: z
+        .natural()
+        .default(8 * 1024 * 1024)
+        .description('Reject request bodies larger than this.'),
+      maxOutputTokens: z
+        .natural()
+        .default(32768)
+        .description('Upper bound applied to max_tokens when a request does not set one.'),
+      firstTokenTimeoutMs: z
+        .natural()
+        .default(120000)
+        .description('Abort a model call that produces no first token within this window.'),
+      idleTimeoutMs: z
+        .natural()
+        .default(120000)
+        .description('Abort a model call whose stream stalls for this long.'),
+    })
+    .default({}),
+  log: z
+    .object({
+      accessFile: z
+        .string()
+        .default('')
+        .description('JSONL access log path. Empty disables it.'),
+      includePayload: z
+        .boolean()
+        .default(false)
+        .description('Record request/response bodies in the access log (may contain user text).'),
+    })
+    .default({}),
+})

package/src/dsh/catalog.js

@@ -0,0 +1,97 @@
+import { notFound, badRequest } from '../openai/errors.js'
+
+const CACHE_TTL_MS = 60_000
+
+/**
+ * Reads the live provider/model directory from `ctx.llm` and resolves the
+ * `model` string of an OpenAI request to a concrete `provider/model` route.
+ */
+export class ModelCatalog {
+  /**
+   * @param {{ listProviders: Function, listModels: Function }} llm
+   * @param {{ aliases?: Record<string,string>, defaultModel?: string, log?: Function }} [options]
+   */
+  constructor(llm, options = {}) {
+    this.llm = llm
+    this.aliases = options.aliases ?? {}
+    this.defaultModel = options.defaultModel ?? ''
+    this.log = options.log ?? (() => {})
+    this.cache = new Map()
+    this.created = Math.floor(Date.now() / 1000)
+  }
+
+  /** @returns {Array<{id:string}>} */
+  providers() {
+    try {
+      const listed = this.llm.listProviders()
+      return Array.isArray(listed) ? listed.filter((entry) => typeof entry?.id === 'string') : []
+    } catch (error) {
+      this.log('warn', `listProviders failed: ${String(error)}`)
+      return []
+    }
+  }
+
+  async modelsOf(provider) {
+    const cached = this.cache.get(provider)
+    const now = Date.now()
+    if (cached !== undefined && now - cached.at < CACHE_TTL_MS) return cached.models
+    try {
+      const models = await this.llm.listModels(provider)
+      const safe = Array.isArray(models) ? models : []
+      this.cache.set(provider, { at: now, models: safe })
+      return safe
+    } catch (error) {
+      this.log('warn', `listModels(${provider}) failed: ${String(error)}`)
+      this.cache.set(provider, { at: now, models: cached?.models ?? [] })
+      return cached?.models ?? []
+    }
+  }
+
+  /** OpenAI `/v1/models` payload. */
+  async list() {
+    const data = []
+    const seen = new Set()
+    for (const provider of this.providers()) {
+      const models = await this.modelsOf(provider.id)
+      for (const model of models) {
+        const id = `${provider.id}/${model.id}`
+        if (seen.has(id)) continue
+        seen.add(id)
+        data.push({
+          id,
+          object: 'model',
+          created: this.created,
+          owned_by: provider.id,
+          ...(typeof model.name === 'string' ? { name: model.name } : {}),
+        })
+      }
+    }
+    for (const [alias, target] of Object.entries(this.aliases)) {
+      if (seen.has(alias)) continue
+      data.push({ id: alias, object: 'model', created: this.created, owned_by: target.split('/')[0] ?? 'dsh-endpoint' })
+    }
+    return data
+  }
+
+  /**
+   * Resolve a requested model name to a concrete route.
+   * @param {unknown} requested
+   * @returns {{ provider: string, model: string, id: string }}
+   */
+  resolve(requested) {
+    const name = typeof requested === 'string' && requested.length > 0 ? requested : this.defaultModel
+    if (typeof name !== 'string' || name.length === 0) {
+      throw badRequest('`model` is required (use `provider/model` or a configured alias)', 'model')
+    }
+    const aliased = this.aliases[name] ?? name
+    const slash = aliased.indexOf('/')
+    if (slash <= 0 || slash === aliased.length - 1) {
+      throw notFound(`model "${name}" is not a provider/model route; configure modelAliases or use provider/model`)
+    }
+    const provider = aliased.slice(0, slash)
+    const model = aliased.slice(slash + 1)
+    const known = this.providers().some((entry) => entry.id === provider)
+    if (!known) throw notFound(`provider "${provider}" is not configured in this DSH instance`)
+    return { provider, model, id: aliased }
+  }
+}

package/src/index.js

@@ -0,0 +1,28 @@
+import { Config } from './config.js'
+import { startEndpoint } from './server.js'
+
+export const name = 'dsh-endpoint'
+
+/** `ctx.llm` is the only hard dependency: every provider call goes through it. */
+export const inject = ['llm']
+
+export { Config }
+
+/**
+ * @param {object} ctx - Cordis host context
+ * @param {object} [config]
+ */
+export function apply(ctx, config) {
+  const resolved = config ?? Config({})
+  const log = (level, message) => {
+    const logger = ctx.logger
+    if (typeof logger?.[level] === 'function') logger[level](`[dsh-endpoint] ${message}`)
+    else if (level === 'warn') console.warn(`[dsh-endpoint] ${message}`)
+    else console.log(`[dsh-endpoint] ${message}`)
+  }
+
+  ctx.effect(async () => {
+    const handle = await startEndpoint(ctx, resolved, { log })
+    return handle.dispose
+  })
+}

package/src/mirror.js

@@ -0,0 +1,286 @@
+import { mkdir } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+
+/**
+ * Mirrors endpoint conversations into real DSH sessions.
+ *
+ * A mirrored session is created through the public session store, given a
+ * persistence write handle, and attached to a dedicated workspace, so it shows
+ * up in the sidebar and can be read — but not continued — from the GUI. The
+ * open write handle is also the single-writer lock that refuses `resume`.
+ */
+export class SessionMirror {
+  /**
+   * @param {object} ctx - Cordis host context
+   * @param {object} options
+   * @param {string} options.workspacePath - directory grouping mirrored sessions
+   * @param {(level: string, message: string) => void} [options.log]
+   */
+  constructor(ctx, options) {
+    this.ctx = ctx
+    this.workspacePath = options.workspacePath
+    this.log = options.log ?? (() => {})
+    this.states = new Map()
+    this.workspace = undefined
+    this.workspacePromise = undefined
+    this.closed = false
+  }
+
+  get available() {
+    return (
+      typeof this.ctx.get('sessions')?.create === 'function' &&
+      typeof this.ctx.get('sessionPersistence')?.create === 'function'
+    )
+  }
+
+  /**
+   * Return the live mirror state for a stored mapping, restoring the session
+   * from its log when the process no longer holds it.
+   *
+   * @param {{ dshSessionId: string, turns?: number }} entry
+   */
+  async ensure(entry) {
+    const existing = this.states.get(entry.dshSessionId)
+    if (existing !== undefined) return existing
+
+    const { session, handle } = await this.#adopt(entry.dshSessionId)
+    const state = {
+      session,
+      handle,
+      turn: Number.isFinite(entry.turns) ? entry.turns : 0,
+      step: 0,
+      lastError: undefined,
+    }
+    this.states.set(entry.dshSessionId, state)
+    await this.#attachWorkspace(entry.dshSessionId)
+    return state
+  }
+
+  /**
+   * Create a brand-new mirrored session owned by this plugin fiber.
+   * @returns {Promise<{ dshSessionId: string, state: object }>}
+   */
+  async create() {
+    const sessions = this.ctx.get('sessions')
+    const persistence = this.ctx.get('sessionPersistence')
+    // Mint the id ourselves: the store's counter restarts with the process, so
+    // `sessions.create()` would hand out `session-1` again after a restart and
+    // collide with an already persisted mirror.
+    const session = sessions.create(`session-${randomUUID()}`, { meta: { cwd: this.workspacePath } })
+    let handle
+    try {
+      handle = await persistence.create(session.header)
+      // `sessions.create` publishes a few bookkeeping events (permission,
+      // sandbox, approval) while announcing the session, before a write handle
+      // exists — the live router only forwards what happens after `create`.
+      // Persist that prefix explicitly so the routed batch starts at the right
+      // cursor instead of failing contiguity.
+      if (session.seq > 0) {
+        const prefix = []
+        for (let seq = 0; seq < session.seq; seq += 1) {
+          const event = session.eventAt(seq)
+          if (event !== undefined) prefix.push(event)
+        }
+        await handle.append(prefix)
+      }
+      // Materialize the header so `attachSession` can read the stored cwd.
+      await handle.flush()
+    } catch (error) {
+      this.log('warn', `could not persist mirrored session ${session.id}: ${String(error)}`)
+      throw error
+    }
+    const state = { session, handle, turn: 0, step: 0 }
+    this.states.set(session.id, state)
+    await this.#attachWorkspace(session.id)
+    return { dshSessionId: session.id, state }
+  }
+
+  /**
+   * Append the client-side part of one turn and open the turn for completion.
+   *
+   * @param {object} state - mirror state from `ensure`/`create`
+   * @param {Array<object>} events - DSH surface events to append
+   * @returns {{ turn: number, step: number }}
+   */
+  beginTurn(state, events) {
+    state.turn += 1
+    state.step = 1
+    state.lastError = undefined
+    const session = state.session
+    session.append('turn/start', { turn: state.turn })
+    session.append('step/start', { turn: state.turn, step: state.step })
+    for (const event of events) {
+      if (event.type === 'user/message') session.append('user/message', event.data, { surfaceOp: 'append' })
+      else if (event.type === 'tool/result') {
+        // `tool/result` is not the message itself: the event carries turn/step
+        // and nests the ToolResultMessage under `message`.
+        session.append(
+          'tool/result',
+          { turn: state.turn, step: state.step, message: event.message },
+          { surfaceOp: 'append' },
+        )
+      } else throw new Error(`unsupported mirrored event ${event.type}`)
+    }
+    return { turn: state.turn, step: state.step }
+  }
+
+  /**
+   * Close the open turn with a successful assistant message.
+   *
+   * @param {object} state
+   * @param {object} result
+   * @param {Array<object>} result.blocks - assembled assistant content blocks
+   * @param {Array<object>} result.chunks - raw stream chunks, in order
+   * @param {object} [result.usage]
+   * @param {string} result.provider
+   * @param {string} result.model
+   */
+  completeTurn(state, { blocks, chunks, usage, provider, model }) {
+    const session = state.session
+    const message = {
+      id: randomUUID(),
+      role: 'assistant',
+      content: blocks,
+      source: { kind: 'model', provider, model },
+    }
+    session.append(
+      'assistant/message',
+      {
+        turn: state.turn,
+        step: state.step,
+        message,
+        stream: chunks.map((chunk) => ({ type: 'chunk', time: Date.now(), chunk: sanitize(chunk) })),
+        ...(usage === undefined ? {} : { usage: sanitize(usage) }),
+      },
+      { surfaceOp: 'append' },
+    )
+    session.append('step/end', { turn: state.turn, step: state.step })
+    session.append('turn/end', { turn: state.turn, reason: { kind: 'completed' } })
+  }
+
+  /**
+   * Close the open turn without an assistant message.
+   *
+   * @param {object} state
+   * @param {{ message: string, code: string }} failure
+   */
+  failTurn(state, failure) {
+    const session = state.session
+    state.lastError = failure
+    session.append('step/end', { turn: state.turn, step: state.step })
+    session.append('turn/end', {
+      turn: state.turn,
+      reason: { kind: 'error', error: { message: failure.message, code: failure.code } },
+    })
+  }
+
+  /** Best-effort durability barrier for one mirrored session. */
+  async flush(state) {
+    try {
+      await this.ctx.get('sessions').flush(state.session)
+    } catch (error) {
+      this.log('warn', `flush failed for ${state.session.id}: ${String(error)}`)
+    }
+  }
+
+  async close() {
+    if (this.closed) return
+    this.closed = true
+    for (const state of this.states.values()) {
+      await this.flush(state)
+      await state.handle?.close?.().catch((error) => this.log('warn', `handle close failed: ${String(error)}`))
+    }
+    this.states.clear()
+  }
+
+  async #adopt(id) {
+    const sessions = this.ctx.get('sessions')
+    const live = sessions.get(id)
+    if (live !== undefined) {
+      // Same-process reload: the session is still live, only the handle is ours.
+      const handle = await this.ctx.get('sessionPersistence').open(id, 'write')
+      return { session: live, handle }
+    }
+    const persistence = this.ctx.get('sessionPersistence')
+    const handle = await persistence.open(id, 'write')
+    try {
+      const read = await handle.read(0)
+      const session = sessions.prepare(id, {
+        seed: read.events,
+        meta: handle.header,
+        inheritedEventCount: handle.inheritedEventCount,
+        eventState: read.eventState,
+      })
+      sessions.enter(session)
+      sessions.announce(session)
+      return { session, handle }
+    } catch (error) {
+      await handle.close().catch(() => {})
+      throw error
+    }
+  }
+
+  async #attachWorkspace(sessionId) {
+    const registry = this.ctx.get('workspaceRegistry')
+    if (registry === undefined) return
+    try {
+      this.workspacePromise ??= (async () => {
+        await mkdir(this.workspacePath, { recursive: true })
+        return registry.create(this.workspacePath)
+      })()
+      this.workspace = await this.workspacePromise
+      await this.workspace?.attachSession(sessionId)
+    } catch (error) {
+      this.workspacePromise = undefined
+      this.workspace = undefined
+      this.log('warn', `could not attach ${sessionId} to workspace ${this.workspacePath}: ${String(error)}`)
+    }
+  }
+}
+
+/** Strip undefined/function values that the session log refuses to snapshot. */
+function sanitize(value) {
+  return JSON.parse(JSON.stringify(value ?? null))
+}
+
+/**
+ * Build a DSH `user/message` surface event payload.
+ * @param {string} text
+ */
+export function userMessageEvent(textOrBlocks) {
+  const content =
+    typeof textOrBlocks === 'string'
+      ? textOrBlocks.length > 0
+        ? [{ type: 'text', text: textOrBlocks }]
+        : [{ type: 'text', text: '[empty]' }]
+      : Array.isArray(textOrBlocks) && textOrBlocks.length > 0
+        ? textOrBlocks
+        : [{ type: 'text', text: '[empty]' }]
+  return {
+    type: 'user/message',
+    data: {
+      id: randomUUID(),
+      role: 'user',
+      content,
+      source: { kind: 'user' },
+    },
+  }
+}
+
+/**
+ * Build a DSH `tool/result` surface event payload.
+ * @param {object} input
+ */
+export function toolResultEvent({ callId, text, isError = false }) {
+  return {
+    type: 'tool/result',
+    message: {
+      id: randomUUID(),
+      role: 'tool',
+      toolCallId: callId,
+      content: [{ type: 'text', text }],
+      source: { kind: 'tool', callId },
+      ...(isError ? { isError: true } : {}),
+    },
+  }
+}

package/src/openai/convert.js

@@ -0,0 +1,197 @@
+import { randomUUID } from 'node:crypto'
+import { badRequest } from './errors.js'
+import { decodeFilePart, decodeInlineFile } from './media.js'
+
+/**
+ * Convert OpenAI chat messages into DSH request messages.
+ *
+ * DSH accepts request-only user input, but assistant and tool turns need a
+ * full `Message` (identity + source), so every message gets a fresh id. The
+ * ids exist only for this request; the durable record is the mirrored session.
+ *
+ * Inline `image_url` data URLs and `file` parts are materialised through the
+ * host attachment service; remote URLs are refused (see `media.js`).
+ *
+ * @param {Array<object>} messages
+ * @param {{ provider: string, model: string }} route
+ * @param {{ saveImages?: Function }} [options]
+ */
+export async function toDshMessages(messages, route, options = {}) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw badRequest('`messages` must be a non-empty array', 'messages')
+  }
+  const converted = []
+  for (const [index, message] of messages.entries()) {
+    converted.push(await toDshMessage(message, index, route, options))
+  }
+  return converted
+}
+
+async function toDshMessage(message, index, route, options) {
+  const param = `messages[${index}]`
+  if (message === null || typeof message !== 'object') throw badRequest(`${param} must be an object`, param)
+  const role = message.role
+  if (typeof role !== 'string') throw badRequest(`${param}.role is required`, `${param}.role`)
+
+  if (role === 'system' || role === 'developer') {
+    const text = coerceText(message.content, `${param}.content`)
+    return {
+      id: randomUUID(),
+      role: 'system',
+      content: text.length === 0 ? [] : [{ type: 'text', text }],
+      source: { kind: 'system-prompt' },
+    }
+  }
+
+  if (role === 'user') {
+    return {
+      id: randomUUID(),
+      role: 'user',
+      content: await toContentBlocks(message.content, `${param}.content`, options),
+      source: { kind: 'user' },
+    }
+  }
+
+  if (role === 'assistant') {
+    const content = await toContentBlocks(message.content ?? [], `${param}.content`, {
+      ...options,
+      allowEmpty: true,
+      allowMedia: false,
+    })
+    for (const call of message.tool_calls ?? []) {
+      const fn = call?.function
+      if (typeof fn?.name !== 'string' || fn.name.length === 0) {
+        throw badRequest(`${param}.tool_calls[].function.name is required`, `${param}.tool_calls`)
+      }
+      content.push({
+        type: 'tool-call',
+        id: typeof call.id === 'string' && call.id.length > 0 ? call.id : randomUUID(),
+        name: fn.name,
+        arguments: typeof fn.arguments === 'string' ? fn.arguments : JSON.stringify(fn.arguments ?? {}),
+      })
+    }
+    return {
+      id: randomUUID(),
+      role: 'assistant',
+      content,
+      source: { kind: 'model', provider: route.provider, model: route.model },
+    }
+  }
+
+  if (role === 'tool') {
+    const callId = message.tool_call_id
+    if (typeof callId !== 'string' || callId.length === 0) {
+      throw badRequest(`${param}.tool_call_id is required for tool messages`, `${param}.tool_call_id`)
+    }
+    return {
+      id: randomUUID(),
+      role: 'tool',
+      toolCallId: callId,
+      content: await toContentBlocks(message.content, `${param}.content`, {
+        ...options,
+        allowEmpty: true,
+        allowMedia: false,
+      }),
+      source: { kind: 'tool', callId },
+      ...(message.is_error === true ? { isError: true } : {}),
+    }
+  }
+
+  throw badRequest(`${param}.role "${role}" is not supported`, `${param}.role`)
+}
+
+async function toContentBlocks(content, param, options = {}) {
+  if (typeof content === 'string') return content.length === 0 ? [] : [{ type: 'text', text: content }]
+  if (content === null || content === undefined) {
+    if (options.allowEmpty === true) return []
+    throw badRequest(`${param} is required`, param)
+  }
+  if (!Array.isArray(content)) throw badRequest(`${param} must be a string or an array of parts`, param)
+
+  const blocks = []
+  for (const [index, part] of content.entries()) {
+    const partParam = `${param}[${index}]`
+    if (part === null || typeof part !== 'object') throw badRequest(`${partParam} must be an object`, partParam)
+
+    if (part.type === 'text') {
+      if (typeof part.text !== 'string') throw badRequest(`${partParam}.text must be a string`, partParam)
+      if (part.text.length > 0) blocks.push({ type: 'text', text: part.text })
+      continue
+    }
+
+    if (part.type === 'image_url') {
+      if (options.allowMedia === false) throw badRequest(`${partParam} is not allowed here`, partParam)
+      const url = typeof part.image_url === 'string' ? part.image_url : part.image_url?.url
+      if (typeof url !== 'string') throw badRequest(`${partParam}.image_url.url is required`, partParam)
+      blocks.push(await safeDecode(partParam, () => decodeInlineFile({ url, param: partParam }, options)))
+      continue
+    }
+
+    if (part.type === 'file') {
+      if (options.allowMedia === false) throw badRequest(`${partParam} is not allowed here`, partParam)
+      blocks.push(await safeDecode(partParam, () => decodeFilePart(part, partParam, options)))
+      continue
+    }
+
+    throw badRequest(`${partParam}.type "${String(part.type)}" is not supported`, `${partParam}.type`)
+  }
+  if (blocks.length === 0 && options.allowEmpty !== true) throw badRequest(`${param} is empty`, param)
+  return blocks
+}
+
+async function safeDecode(param, run) {
+  try {
+    return await run()
+  } catch (error) {
+    if (error?.status !== undefined) throw error
+    throw badRequest(`attachment rejected: ${error?.message ?? error}`, param)
+  }
+}
+
+function coerceText(content, param) {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content
+      .filter((part) => part?.type === 'text' && typeof part.text === 'string')
+      .map((part) => part.text)
+      .join('')
+  }
+  if (content === null || content === undefined) return ''
+  throw badRequest(`${param} must be a string or an array of text parts`, param)
+}
+
+/** Concatenated system/developer text, used by the fingerprint fallback. */
+export function systemText(messages) {
+  return messages
+    .filter((message) => message?.role === 'system' || message?.role === 'developer')
+    .map((message) => coerceText(message.content, 'messages'))
+    .join('\n')
+}
+
+/** Text of the first user message, used by the fingerprint fallback. */
+export function firstUserText(messages) {
+  const first = messages.find((message) => message?.role === 'user')
+  return first === undefined ? '' : coerceText(first.content, 'messages')
+}
+
+/** Convert OpenAI tool declarations into DSH tool schemas. */
+export function toDshTools(tools) {
+  if (tools === undefined || tools === null) return undefined
+  if (!Array.isArray(tools)) throw badRequest('`tools` must be an array', 'tools')
+  const declarations = []
+  for (const [index, tool] of tools.entries()) {
+    const fn = tool?.type === 'function' ? tool.function : undefined
+    if (fn === undefined || typeof fn.name !== 'string' || fn.name.length === 0) {
+      throw badRequest(`tools[${index}] must be a function declaration with a name`, `tools[${index}]`)
+    }
+    declarations.push({
+      name: fn.name,
+      description: typeof fn.description === 'string' ? fn.description : '',
+      parameters:
+        fn.parameters !== null && typeof fn.parameters === 'object'
+          ? fn.parameters
+          : { type: 'object', properties: {} },
+    })
+  }
+  return declarations.length === 0 ? undefined : declarations
+}