dsh-plugin-show-me-data 0.1.0

package/src/host/ai/dsh-llm-gateway.js

@@ -0,0 +1,333 @@
+/**
+ * The 'ctx.llm' AI gateway (docs/06 §1, docs/07 T9.3).
+ *
+ * It maps 'GenerateOptions'/'StreamChunk' onto this plugin's 'AiGateway'
+ * contract, and it is the only place that talks to a model. Everything it does
+ * is optional: if the service is missing, the request fails, or the provider is
+ * unset, the caller falls back to the deterministic gateway.
+ *
+ * @module host/ai/dsh-llm-gateway
+ */
+import { fingerprint } from '../../core/insight/rank.js'
+import { SYSTEM_PROMPT } from '../../core/ai/prompts.js'
+
+/** Gateway mode label. */
+export const MODE = 'llm'
+
+/** Request timeout (docs/05 §5: 30s, partial output preserved). */
+export const LLM_TIMEOUT_MS = 30_000
+
+/**
+ * Output budget for one answer.
+ *
+ * Reasoning models spend tokens on `reasoning-delta` before emitting any
+ * `text-delta`, so a budget sized for the answer alone is entirely consumed by
+ * thinking and the response arrives with no text at all (observed live with
+ * deepseek-v4-flash at 600 tokens). The budget therefore has to cover thinking
+ * plus a {@link MAX_CHARS}-ish answer.
+ */
+export const DEFAULT_MAX_TOKENS = 4000
+
+/**
+ * Build the message object the 'llm' service expects.
+ *
+ * The service wants 'Message[]' (with 'id' and 'source'), and its constructors
+ * live in packages this plugin deliberately does not import, so a minimal valid
+ * message is built here.
+ *
+ * @param {string} text - user content.
+ * @param {{ idSeed: string }} options - identity seed for deterministic ids.
+ * @returns {object} message.
+ */
+export function buildUserMessage(text, { idSeed }) {
+  return {
+    id: `smd-${fingerprint(`${idSeed}|${text.length}|${text.slice(0, 64)}`)}`,
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: { kind: 'plugin', plugin: 'show-me-data' },
+  }
+}
+
+/**
+ * Create the LLM gateway.
+ *
+ * @param {object} deps - dependencies.
+ * @param {object} deps.llm - 'ctx.llm' service.
+ * @param {object} [deps.defaultModel] - 'ctx.agentDefaultModel' service.
+ * @param {number} [deps.maxChars] - output budget passed to the model.
+ * @param {number} [deps.timeoutMs] - request timeout.
+ * @param {(msg: string, meta?: object) => void} [deps.log] - logger.
+ * @returns {object} 'AiGateway'.
+ */
+export function createDshLlmGateway({ llm, defaultModel, maxChars = 1200, timeoutMs = LLM_TIMEOUT_MS, log = () => {} }) {
+  if (llm === undefined || typeof llm.stream !== 'function') {
+    throw new Error('createDshLlmGateway: an `llm` service with `stream()` is required')
+  }
+
+  /**
+   * Resolve the provider/model to call.
+   *
+   * @param {object} [override] - per-request override.
+   * @returns {{ provider: string, model: string, reasoningEffort?: string }} selection.
+   */
+  function selection(override) {
+    if (override?.provider !== undefined && override?.model !== undefined) return override
+    const current = defaultModel?.currentSelection?.()
+    if (current?.provider !== undefined && current?.model !== undefined) return current
+    const providers = typeof llm.listProviders === 'function' ? llm.listProviders() : []
+    const first = providers[0]
+    if (first !== undefined) {
+      const model = first.models?.[0]?.id ?? first.defaultModel ?? first.models?.[0]
+      if (model !== undefined) return { provider: first.provider ?? first.id, model: String(model) }
+    }
+    throw new Error('no LLM provider/model is configured (agentDefaultModel.currentSelection() is empty)')
+  }
+
+  /**
+   * Run one completion, collecting streamed text.
+   *
+   * @param {object} input - invocation.
+   * @param {string} input.system - system prompt.
+   * @param {string} input.user - user prompt.
+   * @param {string} input.idSeed - identity seed for the message id.
+   * @param {number} [input.maxTokens] - output budget.
+   * @returns {Promise<{ text: string, usage?: object, interrupted: boolean }>} completion.
+   */
+  async function complete({ system, user, idSeed, maxTokens }) {
+    const target = selection()
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(new Error('llm timeout')), timeoutMs)
+    let text = ''
+    // Reasoning text is kept separately: a reasoning model that runs out of
+    // budget mid-thought emits no `text` block at all, and showing the user the
+    // model's own thinking beats showing them nothing.
+    let reasoning = ''
+    let usage
+    let interrupted = false
+    /** Chunk-type census, so an empty answer can explain itself. */
+    const census = {}
+    let finishReason
+    let failure
+    try {
+      const stream = llm.stream({
+        provider: target.provider,
+        model: target.model,
+        ...(target.reasoningEffort === undefined ? {} : { reasoningEffort: target.reasoningEffort }),
+        system,
+        messages: [buildUserMessage(user, { idSeed })],
+        ...(maxTokens === undefined ? {} : { maxTokens }),
+        signal: controller.signal,
+      })
+      for await (const chunk of stream) {
+        if (chunk?.type !== undefined) census[chunk.type] = (census[chunk.type] ?? 0) + 1
+        if (chunk?.type === 'text-delta') text += chunk.text
+        else if (chunk?.type === 'reasoning-delta') reasoning += chunk.text
+        else if (chunk?.type === 'usage') usage = chunk.usage
+        else if (chunk?.type === 'finish') {
+          finishReason = chunk.reason?.kind
+          if (chunk.reason?.kind === 'aborted' || chunk.reason?.kind === 'error') {
+            interrupted = true
+            failure = chunk.reason.failure
+          }
+        }
+      }
+    } catch (error) {
+      if (text.length === 0) throw error
+      // Keep what we already received: a partial answer beats no answer.
+      interrupted = true
+      failure = { message: error?.message ?? String(error), code: error?.code }
+      log('llm stream interrupted, keeping partial output', { message: error?.message ?? String(error) })
+    } finally {
+      clearTimeout(timer)
+    }
+    const textOut = text
+    const reasoningOnly = textOut.trim() === '' && reasoning.trim() !== ''
+    if (reasoningOnly) {
+      // Budget exhausted during thinking. Reasoning is NOT an answer: handing it
+      // back as `markdown` let a model's private deliberation ("用户要求重写，且
+      // 上次因未引用数据点未通过") reach the panel as if it were the analysis, and
+      // it once passed the validator because it restated digest numbers. The
+      // answer stays empty — the caller then retries and degrades to the
+      // deterministic summary — while the reasoning is kept for diagnostics.
+      log('llm produced reasoning but no text (budget likely exhausted during thinking)', {
+        provider: target.provider,
+        model: target.model,
+        finishReason,
+        maxTokens,
+        reasoningChars: reasoning.length,
+      })
+    }
+    if (textOut.trim() === '') {
+      // An empty completion is a provider-level failure, and the caller must be
+      // able to say WHY instead of showing a generic "no model configured".
+      log('llm returned no text', { provider: target.provider, model: target.model, census, finishReason, failure })
+    }
+    return {
+      text: textOut,
+      // The raw reasoning is diagnostics, never an answer.
+      reasoning: reasoningOnly ? reasoning.trim() : undefined,
+      usage,
+      interrupted,
+      reasoningOnly,
+      census,
+      finishReason,
+      failure,
+      provider: target.provider,
+      model: target.model,
+    }
+  }
+
+  /**
+   * Build an 'AiResult' from a completion.
+   *
+   * @param {object} input - invocation.
+   * @param {string} input.text - completion text.
+   * @param {object} input.usage - token usage.
+   * @param {boolean} input.interrupted - whether the stream was cut short.
+   * @param {string} input.idSeed - fingerprint seed.
+   * @returns {object} 'AiResult'.
+   */
+  function resultOf({ text, usage, interrupted, idSeed, census, finishReason, failure, provider, model, reasoningOnly, reasoning }) {
+    const described = describe()
+    return {
+      markdown: text,
+      // Citations are produced by the validator from the text; an empty list here
+      // means the caller must validate before showing anything.
+      usedPoints: [],
+      mode: MODE,
+      interrupted: interrupted === true,
+      reasoningOnly: reasoningOnly === true,
+      usage,
+      provider: described.provider ?? provider,
+      model: described.model ?? model,
+      // Diagnostic facts travel with the result so the panel can explain an
+      // empty answer instead of pretending no model is configured.
+      emptyReason:
+        text === ''
+          ? {
+              kind: failure !== undefined ? 'provider-error' : reasoningOnly ? 'reasoning-only' : 'no-text',
+              detail: failure?.message ??
+                (reasoningOnly
+                  ? `模型把全部输出预算用在了思考上（${reasoning?.length ?? 0} 字），没有产出回答`
+                  : `模型只返回了 ${Object.keys(census ?? {}).join('/') || '无'} 类型的内容，没有文本`),
+              code: failure?.code,
+              finishReason,
+              census,
+            }
+          : undefined,
+      fingerprint: fingerprint(`${idSeed}|${text.length}`),
+    }
+  }
+
+  /**
+   * @param {object} request - request with 'system'/'user' prompts already built.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function explain(request) {
+    const completion = await complete({
+      system: request.system ?? SYSTEM_PROMPT,
+      user: request.user ?? '',
+      idSeed: `explain|${request.indicatorId ?? ''}`,
+      maxTokens: DEFAULT_MAX_TOKENS,
+    })
+    return resultOf({ ...completion, idSeed: `explain|${request.indicatorId ?? ''}` })
+  }
+
+  /**
+   * @param {object} request - request.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function summarize(request) {
+    const completion = await complete({
+      system: request.system ?? SYSTEM_PROMPT,
+      user: request.user ?? '',
+      idSeed: `summary|${request.range?.from ?? ''}`,
+      maxTokens: DEFAULT_MAX_TOKENS,
+    })
+    return resultOf({ ...completion, idSeed: `summary|${request.range?.from ?? ''}` })
+  }
+
+  /**
+   * @param {object} request - request.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function answer(request) {
+    const completion = await complete({
+      system: request.system ?? SYSTEM_PROMPT,
+      user: request.user ?? '',
+      idSeed: `answer|${request.question ?? ''}`,
+      maxTokens: DEFAULT_MAX_TOKENS,
+    })
+    return resultOf({ ...completion, idSeed: `answer|${request.question ?? ''}` })
+  }
+
+  /**
+   * Ask the model for structured JSON candidates.
+   *
+   * @param {object} request - request with 'system'/'user'.
+   * @returns {Promise<{ candidates: object[], unsupported: object[], mode: string, raw: string }>} proposal.
+   */
+  async function propose(request) {
+    const completion = await complete({
+      system: request.system ?? SYSTEM_PROMPT,
+      user: request.user ?? '',
+      idSeed: `propose|${request.request ?? ''}`,
+      maxTokens: 1500,
+    })
+    try {
+      const parsed = JSON.parse(extractJson(completion.text))
+      return {
+        candidates: Array.isArray(parsed?.candidates) ? parsed.candidates : [],
+        unsupported: Array.isArray(parsed?.unsupported) ? parsed.unsupported : [],
+        mode: MODE,
+        raw: completion.text,
+      }
+    } catch (error) {
+      // Unparseable model output is not a candidate list: say so rather than
+      // inventing one.
+      return {
+        candidates: [],
+        unsupported: [
+          {
+            request: request.request ?? '',
+            reason: `模型返回的不是合法 JSON（${error?.message ?? error}），未做任何猜测。`,
+            alternatives: ['换一种说法重试', '在指标目录中手动检索'],
+          },
+        ],
+        mode: MODE,
+        raw: completion.text,
+      }
+    }
+  }
+
+  /**
+   * @returns {{ mode: string, provider?: string, model?: string }} description.
+   */
+  function describe() {
+    try {
+      const target = selection()
+      return { mode: MODE, provider: target.provider, model: target.model }
+    } catch {
+      return { mode: MODE }
+    }
+  }
+
+  return { explain, summarize, answer, propose, describe }
+}
+
+/**
+ * Pull the first JSON object out of model text (models like to wrap JSON in
+ * prose or fences).
+ *
+ * @param {string} text - model output.
+ * @returns {string} JSON candidate.
+ */
+export function extractJson(text) {
+  const source = String(text ?? '')
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(source)
+  if (fenced !== null) return fenced[1].trim()
+  const start = source.indexOf('{')
+  const end = source.lastIndexOf('}')
+  if (start !== -1 && end > start) return source.slice(start, end + 1)
+  return source.trim()
+}

package/src/host/config.js

@@ -0,0 +1,194 @@
+/**
+ * Plugin configuration: defaults, validation and the Standard Schema export
+ * (docs/09 §5).
+ *
+ * **Why this file exists.** Cordis validates a loader row's 'config' *before*
+ * 'apply' runs, through 'plugin.Config["~standard"].validate(config)'. A plugin
+ * that exports a plain defaults object as 'Config' therefore crashes the whole
+ * profile at boot ('Cannot read properties of undefined (reading 'validate')'),
+ * not just its own row. The exported schema below is a real Standard Schema:
+ * valid configuration passes through normalized, invalid configuration becomes
+ * 'issues' that the loader reports as a readable boot error.
+ *
+ * @module host/config
+ */
+
+/** The row defaults. Kept as data so {@link ConfigSchema} and the docs agree. */
+export const DEFAULT_CONFIG = {
+  refreshMinutes: 30,
+  cacheTtl: { daily: 15, weekly: 180, monthly: 360, quarterly: 1440 },
+  groups: ['US', 'CN', 'GLOBAL', 'CUSTOM'],
+  noteworthyLimit: 5,
+  storageDir: undefined,
+  /** Print AI diagnostics to stderr as well; for troubleshooting a silent model. */
+  debug: false,
+  ai: { enabled: true, mode: 'auto', maxChars: 1200, cacheMinutes: 60 },
+  sources: {
+    fred: true,
+    'eastmoney-quote': true,
+    'eastmoney-macro': true,
+    'us-treasury': true,
+    worldbank: true,
+    ecb: true,
+  },
+}
+
+/** The AI modes a row may select. */
+export const AI_MODES = ['auto', 'llm', 'deterministic', 'relay']
+
+/**
+ * Validate and normalize one raw row config.
+ *
+ * @param {unknown} raw - configuration from the loader row.
+ * @returns {{ value: object, issues: Array<{ message: string, path?: string[] }> }} normalized config and issues.
+ */
+export function resolveConfig(raw) {
+  const issues = []
+  const config = raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw) ? {} : raw
+  if (raw !== undefined && (raw === null || typeof raw !== 'object' || Array.isArray(raw))) {
+    issues.push({ message: 'config must be an object', path: [] })
+  }
+
+  const takeNumber = (key, { min, max, integer = true }) => {
+    const value = config[key]
+    if (value === undefined) return DEFAULT_CONFIG[key]
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      issues.push({ message: `${key} must be a finite number`, path: [key] })
+      return DEFAULT_CONFIG[key]
+    }
+    if (integer && !Number.isInteger(value)) {
+      issues.push({ message: `${key} must be an integer`, path: [key] })
+      return Math.trunc(value)
+    }
+    if (value < min || value > max) {
+      issues.push({ message: `${key} must be between ${min} and ${max}`, path: [key] })
+      return Math.min(Math.max(value, min), max)
+    }
+    return value
+  }
+
+  const refreshMinutes = takeNumber('refreshMinutes', { min: 0, max: 24 * 60 })
+  const noteworthyLimit = takeNumber('noteworthyLimit', { min: 1, max: 20 })
+
+  let groups = DEFAULT_CONFIG.groups
+  if (config.groups !== undefined) {
+    if (!Array.isArray(config.groups) || config.groups.length === 0 || config.groups.some((entry) => typeof entry !== 'string')) {
+      issues.push({ message: 'groups must be a non-empty array of strings', path: ['groups'] })
+    } else {
+      groups = [...config.groups]
+    }
+  }
+
+  let storageDir
+  if (config.storageDir !== undefined) {
+    if (typeof config.storageDir !== 'string' || config.storageDir === '') {
+      issues.push({ message: 'storageDir must be a non-empty string when set', path: ['storageDir'] })
+    } else {
+      storageDir = config.storageDir
+    }
+  }
+
+  const cacheTtl = { ...DEFAULT_CONFIG.cacheTtl }
+  if (config.cacheTtl !== undefined) {
+    if (config.cacheTtl === null || typeof config.cacheTtl !== 'object' || Array.isArray(config.cacheTtl)) {
+      issues.push({ message: 'cacheTtl must be an object of minutes per frequency', path: ['cacheTtl'] })
+    } else {
+      for (const [key, value] of Object.entries(config.cacheTtl)) {
+        if (!(key in DEFAULT_CONFIG.cacheTtl)) {
+          issues.push({ message: `cacheTtl.${key} is not a known frequency`, path: ['cacheTtl', key] })
+          continue
+        }
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+          issues.push({ message: `cacheTtl.${key} must be a non-negative number`, path: ['cacheTtl', key] })
+          continue
+        }
+        cacheTtl[key] = value
+      }
+    }
+  }
+
+  const ai = { ...DEFAULT_CONFIG.ai }
+  if (config.ai !== undefined) {
+    if (config.ai === null || typeof config.ai !== 'object' || Array.isArray(config.ai)) {
+      issues.push({ message: 'ai must be an object', path: ['ai'] })
+    } else {
+      if (config.ai.enabled !== undefined) {
+        if (typeof config.ai.enabled !== 'boolean') issues.push({ message: 'ai.enabled must be a boolean', path: ['ai', 'enabled'] })
+        else ai.enabled = config.ai.enabled
+      }
+      if (config.ai.mode !== undefined) {
+        if (!AI_MODES.includes(config.ai.mode)) {
+          issues.push({ message: `ai.mode must be one of ${AI_MODES.join('|')}`, path: ['ai', 'mode'] })
+        } else {
+          ai.mode = config.ai.mode
+        }
+      }
+      if (config.ai.maxChars !== undefined) {
+        if (!Number.isInteger(config.ai.maxChars) || config.ai.maxChars < 200 || config.ai.maxChars > 8000) {
+          issues.push({ message: 'ai.maxChars must be an integer between 200 and 8000', path: ['ai', 'maxChars'] })
+        } else {
+          ai.maxChars = config.ai.maxChars
+        }
+      }
+      if (config.ai.cacheMinutes !== undefined) {
+        if (!Number.isInteger(config.ai.cacheMinutes) || config.ai.cacheMinutes < 0) {
+          issues.push({ message: 'ai.cacheMinutes must be a non-negative integer', path: ['ai', 'cacheMinutes'] })
+        } else {
+          ai.cacheMinutes = config.ai.cacheMinutes
+        }
+      }
+    }
+  }
+
+  const sources = { ...DEFAULT_CONFIG.sources }
+  if (config.sources !== undefined) {
+    if (config.sources === null || typeof config.sources !== 'object' || Array.isArray(config.sources)) {
+      issues.push({ message: 'sources must be an object of booleans', path: ['sources'] })
+    } else {
+      for (const [key, value] of Object.entries(config.sources)) {
+        if (typeof value !== 'boolean') {
+          issues.push({ message: `sources.${key} must be a boolean`, path: ['sources', key] })
+          continue
+        }
+        sources[key] = value
+      }
+    }
+  }
+
+  let debug = DEFAULT_CONFIG.debug
+  if (config.debug !== undefined) {
+    if (typeof config.debug !== 'boolean') issues.push({ message: 'debug must be a boolean', path: ['debug'] })
+    else debug = config.debug
+  }
+
+  return {
+    value: { refreshMinutes, cacheTtl, groups, noteworthyLimit, storageDir, debug, ai, sources },
+    issues,
+  }
+}
+
+/**
+ * The Standard Schema Cordis reads from 'plugin.Config'.
+ *
+ * 'validate' never throws: an unexpected failure becomes an 'issues' entry so a
+ * configuration mistake surfaces as a readable boot message instead of a
+ * process-level TypeError.
+ */
+export const ConfigSchema = {
+  '~standard': {
+    version: 1,
+    vendor: 'dsh-plugin-show-me-data',
+    /**
+     * @param {unknown} value - raw row config.
+     * @returns {{ value: object, issues?: Array<{ message: string, path?: string[] }> }} validation result.
+     */
+    validate(value) {
+      try {
+        const { value: normalized, issues } = resolveConfig(value)
+        return issues.length === 0 ? { value: normalized } : { value: normalized, issues }
+      } catch (error) {
+        return { value: DEFAULT_CONFIG, issues: [{ message: `config validation failed: ${error?.message ?? error}` }] }
+      }
+    },
+  },
+}

package/src/host/http/respond.js

@@ -0,0 +1,165 @@
+/**
+ * HTTP plumbing for the browser half's data channel (docs/07 T7.2).
+ *
+ * The route table is registered with 'kind: 'prefix'' for the whole
+ * '/api/show-me-data' subtree, and every handler is a thin adapter: parse the
+ * request, call a use case, serialise. Errors are structured and never leak a
+ * stack (docs/05 §3).
+ *
+ * @module host/http/respond
+ */
+
+/** The prefix every route lives under. */
+export const API_PREFIX = '/api/show-me-data'
+
+/**
+ * Read a request body, with a hard size cap.
+ *
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {number} [maxBytes] - cap.
+ * @returns {Promise<any>} parsed JSON body ('{}' when empty).
+ */
+export async function readJsonBody(req, maxBytes = 256 * 1024) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > maxBytes) {
+      const error = new Error(`request body exceeds ${maxBytes} bytes`)
+      error.code = 'BODY_TOO_LARGE'
+      throw error
+    }
+    chunks.push(chunk)
+  }
+  if (size === 0) return {}
+  const text = Buffer.concat(chunks).toString('utf8')
+  try {
+    const parsed = JSON.parse(text)
+    return parsed === null || typeof parsed !== 'object' ? {} : parsed
+  } catch {
+    const error = new Error('request body is not valid JSON')
+    error.code = 'BAD_JSON'
+    throw error
+  }
+}
+
+/**
+ * Send a JSON response.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {number} status - status code.
+ * @param {any} payload - JSON payload.
+ * @returns {void}
+ */
+export function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(body),
+    'cache-control': 'no-store',
+  })
+  res.end(body)
+}
+
+/**
+ * Send a structured error. Stacks stay in the log, never on the wire.
+ *
+ * `payload` merges top-level fields beside `error`. A failure that still produced
+ * something the caller needs — a discussion whose session exists even though its
+ * first turn failed — has to hand that id over, or the reader is told to open a
+ * session whose id they never receive.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {number} status - status code.
+ * @param {string} kind - machine-readable kind.
+ * @param {string} detail - human-readable detail.
+ * @param {{ retryable?: boolean }} [extra] - extra fields.
+ * @param {object} [payload] - top-level fields to merge beside `error`.
+ * @returns {void}
+ */
+export function sendError(res, status, kind, detail, extra = {}, payload = {}) {
+  sendJson(res, status, { ...payload, error: { kind, detail, retryable: extra.retryable === true } })
+}
+
+/**
+ * Start a 'text/event-stream' response.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {Record<string, string>} [headers] - extra headers.
+ * @returns {(event: string, data: any) => void} event writer.
+ */
+export function startSse(res, headers = {}) {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-store',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+    ...headers,
+  })
+  if (typeof res.flushHeaders === 'function') res.flushHeaders()
+  let closed = false
+  res.on('close', () => {
+    closed = true
+  })
+  return (event, data) => {
+    if (closed || res.writableEnded) return
+    res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+  }
+}
+
+/**
+ * Parse a URL into its pathname and query.
+ *
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {string} prefix - route prefix.
+ * @returns {{ route: string, query: URLSearchParams }} route name and query.
+ */
+export function parseRoute(req, prefix = API_PREFIX) {
+  const url = new URL(req.url ?? '/', 'http://localhost')
+  const path = url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) : url.pathname
+  return { route: path.replace(/^\/+|\/+$/g, ''), query: url.searchParams }
+}
+
+/**
+ * Read a positive integer query parameter.
+ *
+ * @param {URLSearchParams} query - query.
+ * @param {string} key - parameter name.
+ * @param {number} fallback - default.
+ * @param {{ min?: number, max?: number }} [bounds] - bounds.
+ * @returns {number} value.
+ */
+export function intParam(query, key, fallback, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  const raw = query.get(key)
+  if (raw === null) return fallback
+  const value = Number(raw)
+  if (!Number.isFinite(value)) return fallback
+  return Math.min(Math.max(Math.trunc(value), min), max)
+}
+
+/**
+ * Read a comma-separated list parameter.
+ *
+ * @param {URLSearchParams} query - query.
+ * @param {string} key - parameter name.
+ * @returns {string[]|undefined} values.
+ */
+export function listParam(query, key) {
+  const raw = query.get(key)
+  if (raw === null || raw.trim() === '') return undefined
+  return raw.split(',').map((entry) => entry.trim()).filter((entry) => entry !== '')
+}
+
+/**
+ * Normalise any thrown value into a structured error payload.
+ *
+ * @param {unknown} error - thrown value.
+ * @returns {{ status: number, kind: string, detail: string, retryable: boolean }} payload.
+ */
+export function errorPayload(error) {
+  if (error?.code === 'BODY_TOO_LARGE') return { status: 413, kind: 'payload-too-large', detail: error.message, retryable: false }
+  if (error?.code === 'BAD_JSON') return { status: 400, kind: 'bad-request', detail: error.message, retryable: false }
+  if (error instanceof RangeError) return { status: 400, kind: 'bad-request', detail: error.message, retryable: false }
+  if (error?.name === 'ToolArgsError') return { status: 400, kind: 'bad-request', detail: error.message, retryable: false }
+  return { status: 500, kind: 'internal', detail: 'plugin error (details in the host log)', retryable: true }
+}