@kukonce/dsh-loomy 0.0.0-stage → 0.3.2

package/src/llm/endings.js

@@ -0,0 +1,116 @@
+/**
+ * Classify how a stream ended, and turn the uninteresting cases into one stable answer.
+ *
+ * The harness acts on the terminal `finish` chunk: `stop` ends the step, `error` fails it
+ * (and the retry package may rerun it), `max-tokens` continues it. The gateway is not
+ * always explicit about which it meant, so this module applies the rules once:
+ *
+ *   - `finish_reason: stop|end_turn|stop_sequence` -> stop
+ *   - `finish_reason: length`                     -> max-tokens
+ *   - `finish_reason: content_filter`             -> error, INVALID_REQUEST (do not retry)
+ *   - `finish_reason: tool_calls`                 -> stop (the calls are the answer)
+ *   - no `[DONE]` and no `finish_reason`          -> error, TRANSPORT (retryable)
+ *   - `[DONE]` with no reason at all              -> stop
+ *
+ * The one judgement call is the third-from-last rule: a connection dropped mid-answer
+ * looks exactly like an empty answer otherwise, and silently accepting it would hand the
+ * user a truncated reply with no indication anything went wrong.
+ */
+
+/**
+ * @param {object} facts
+ * @param {boolean} facts.streamEnded    `[DONE]` was seen
+ * @param {string|undefined} facts.finishReason
+ * @param {boolean} facts.argsTruncated  a tool call's arguments were cut mid-JSON
+ * @param {number} facts.orphanCalls     fragments that never carried a tool name
+ * @param {number} facts.blockCount      how many blocks were delivered
+ * @param {boolean} facts.hasTools       at least one complete tool call was delivered
+ * @param {string} provider
+ * @returns {{ kind: 'stop'|'error'|'max-tokens', failure?: object, note?: string }}
+ */
+export function classifyEnding(facts, provider) {
+  const { streamEnded, finishReason, argsTruncated, orphanCalls, blockCount, hasTools } = facts
+
+  // The arguments of a tool call were cut mid-JSON: the call cannot be executed, so this
+  // step is really a budget truncation (the harness can continue it) rather than an answer.
+  if (argsTruncated) {
+    return {
+      kind: 'max-tokens',
+      note: 'args-budget',
+      failure: undefined
+    }
+  }
+
+  if (finishReason === 'length') {
+    return { kind: 'max-tokens', note: blockCount === 0 ? 'empty-budget' : 'budget' }
+  }
+
+  if (finishReason === 'content_filter') {
+    return {
+      kind: 'error',
+      note: 'filtered',
+      failure: { message: `${provider}: 上游以内容审核中断了本次回答（finish_reason=content_filter）`, code: 'INVALID_REQUEST' }
+    }
+  }
+
+  if (finishReason === 'tool_calls' || hasTools) return { kind: 'stop', note: 'tools' }
+
+  if (finishReason === 'stop' || finishReason === 'end_turn' || finishReason === 'stop_sequence') {
+    return { kind: 'stop', note: 'stop' }
+  }
+
+  // A call fragment whose name never arrived cannot be announced to the harness, so the
+  // step would read as "the model chose to stop" while a call was in flight. That is a
+  // transport problem, not an answer.
+  if (orphanCalls > 0) {
+    return {
+      kind: 'error',
+      note: 'orphan-tool',
+      failure: { message: `${provider}: 收到工具调用分片但没有工具名（finish_reason=${finishReason ?? '(无)'}），可重试`, code: 'TRANSPORT' }
+    }
+  }
+
+  if (streamEnded) {
+    return { kind: 'stop', note: 'done-without-reason' }
+  }
+
+  return {
+    kind: 'error',
+    note: 'cut',
+    failure: { message: `${provider}: 响应在 finish_reason/[DONE] 之前中断，可重试`, code: 'TRANSPORT' }
+  }
+}
+
+/**
+ * Whether a tool call's accumulated argument text is syntactically incomplete.
+ *
+ * Checked by parsing rather than by brace counting: the arguments are a JSON object and
+ * nothing else, so "parses" is exactly the right predicate.
+ */
+export function isTruncatedArguments(text) {
+  const trimmed = String(text ?? '').trim()
+  if (trimmed.length === 0) return false
+  try {
+    JSON.parse(trimmed)
+    return false
+  } catch {
+    return true
+  }
+}
+
+/**
+ * Normalize the argument string handed to the harness.
+ *
+ * The harness expects the raw JSON string; an empty or unparseable one becomes '{}' so
+ * the tool sees an empty argument object instead of a parse error.
+ */
+export function normalizeToolArguments(raw) {
+  const trimmed = String(raw ?? '').trim()
+  if (trimmed.length === 0) return '{}'
+  try {
+    const parsed = JSON.parse(trimmed)
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? JSON.stringify(parsed) : '{}'
+  } catch {
+    return '{}'
+  }
+}

package/src/llm/sse.js

@@ -0,0 +1,80 @@
+/**
+ * Server-sent-events reader for the Loomy gateway.
+ *
+ * The gateway answers with the ordinary OpenAI shape -- `data: {json}` lines, `data:
+ * [DONE]` to terminate -- with one wrinkle that matters: it also sends blank separator
+ * lines and, on a proxy error, an HTML page where the stream should be. Neither may be
+ * allowed to throw, because a throw from the middle of a generator loses whatever had
+ * already been yielded.
+ */
+
+export const SSE_DONE = Symbol('sse-done')
+
+/**
+ * Yield each `data:` payload as a string, and {SSE_DONE} once `[DONE]` arrives.
+ *
+ * `state` accumulates byte and timing facts the adapter uses to describe a stream that
+ * was cut before its terminator -- `receivedBytes`, `lastDataAt`. Passing the object in
+ * rather than returning them keeps the yield type a plain string.
+ */
+export async function* readSse(response, state = { receivedBytes: 0, lastDataAt: Date.now() }) {
+  if (response.body === null) return
+  const decoder = new TextDecoder('utf-8')
+  let buffer = ''
+  for await (const chunk of response.body) {
+    const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk)
+    state.receivedBytes += bytes.byteLength
+    state.lastDataAt = Date.now()
+    buffer += decoder.decode(bytes, { stream: true })
+    // Events are separated by a blank line; accept a bare newline too, because the
+    // gateway has emitted single-`\n` framing and a strict parser then never fires.
+    let boundary
+    while ((boundary = findEventBoundary(buffer)) !== -1) {
+      const event = buffer.slice(0, boundary.index)
+      buffer = buffer.slice(boundary.index + boundary.length)
+      const payload = eventPayload(event)
+      if (payload === undefined) continue
+      if (payload === '[DONE]') {
+        yield SSE_DONE
+        return
+      }
+      yield payload
+    }
+  }
+  // A stream that ends without its trailing blank line still has one final event.
+  const tail = buffer.trim()
+  if (tail.length > 0) {
+    const payload = eventPayload(tail)
+    if (payload === '[DONE]') yield SSE_DONE
+    else if (payload !== undefined) yield payload
+  }
+}
+
+/** Index just past the next event separator, or -1. */
+function findEventBoundary(buffer) {
+  const doubleNewline = buffer.indexOf('\n\n')
+  const doubleCarriage = buffer.indexOf('\r\n\r\n')
+  const candidates = []
+  if (doubleNewline !== -1) candidates.push({ index: doubleNewline, length: 2 })
+  if (doubleCarriage !== -1) candidates.push({ index: doubleCarriage, length: 4 })
+  if (candidates.length === 0) return -1
+  candidates.sort((left, right) => left.index - right.index)
+  return candidates[0]
+}
+
+/**
+ * The concatenated `data:` payload of one event block, or undefined when it has none.
+ *
+ * Multi-line `data:` fields are joined with a newline, per the event-stream spec; the
+ * gateway does not currently split a JSON object across lines, but a proxy might.
+ */
+function eventPayload(event) {
+  const dataLines = []
+  for (const rawLine of event.split('\n')) {
+    const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine
+    if (!line.startsWith('data:')) continue
+    dataLines.push(line.slice(5).replace(/^ /u, ''))
+  }
+  if (dataLines.length === 0) return undefined
+  return dataLines.join('\n')
+}

package/src/llm/wire.js

@@ -0,0 +1,272 @@
+/**
+ * Harness messages -> OpenAI-compatible wire messages for the Loomy gateway.
+ *
+ * Split out of the adapter so the conversion can be read and tested on its own: the
+ * bugs that live here are always the same two -- a tool result that arrives as its own
+ * message gets folded into a user turn (and the model loses which call it answers), or
+ * a tool call whose result never came back gets sent anyway (and the gateway rejects
+ * the whole request as malformed).
+ *
+ * The harness's vocabulary is richer than OpenAI's; everything here is a lossy
+ * projection, and the places where it loses information are commented.
+ */
+
+const TOOL_RESULT_IMAGE_TEXT = 'Attached image(s) from tool result:'
+
+/** Concatenated text of a content array, ignoring non-text blocks. */
+export function contentToText(content) {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter((block) => typeof block === 'object' && block !== null && block.type === 'text')
+    .map((block) => String(block.text ?? ''))
+    .join('')
+}
+
+/**
+ * Tool arguments must reach the gateway as a JSON **string** that parses to an object.
+ * A malformed one is sent as '{}' rather than as the raw text: the gateway rejects the
+ * turn otherwise, and a rejected turn is a worse outcome than a call with no arguments
+ * (which the tool itself then reports).
+ */
+export function normalizeToolArguments(raw) {
+  const trimmed = String(raw ?? '').trim()
+  if (trimmed.length === 0) return '{}'
+  try {
+    const parsed = JSON.parse(trimmed)
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? trimmed : '{}'
+  } catch {
+    return '{}'
+  }
+}
+
+export const hasUsableToolName = (name) => typeof name === 'string' && name.trim().length > 0
+
+/**
+ * The call id a result message answers.
+ *
+ * The harness answers a call with a message of its own: role 'tool' plus
+ * source.callId. Older transcripts put the result inside the content blocks as a
+ * tool-result block carrying toolCallId. Both are read so neither shape loses its
+ * pairing.
+ */
+export function toolResultCallId(message) {
+  if (message?.role !== 'tool') return undefined
+  const id = message.source?.callId ?? message.toolCallId ?? message.tool_call_id
+  return id === undefined || id === null ? undefined : String(id)
+}
+
+/**
+ * Keep only tool call/result pairs that are complete on **both** sides.
+ *
+ * A call with no result is a step that was interrupted; sending it makes the
+ * conversation invalid for every later turn, because OpenAI-compatible servers require
+ * every tool_calls entry to be answered before the next user message. Dropping the
+ * pair loses that one step and keeps the rest of the conversation usable.
+ */
+export function resolveToolPairing(messages) {
+  const allResultIds = new Set()
+  for (const message of messages) {
+    const standalone = toolResultCallId(message)
+    if (standalone !== undefined) { allResultIds.add(standalone); continue }
+    for (const block of Array.isArray(message.content) ? message.content : []) {
+      if (block?.type === 'tool-result') allResultIds.add(String(block.toolCallId))
+    }
+  }
+  const keepCallIds = new Set()
+  for (const message of messages) {
+    if (message.role !== 'assistant') continue
+    const calls = (Array.isArray(message.content) ? message.content : [])
+      .filter((block) => block?.type === 'tool-call' && hasUsableToolName(block.name))
+    if (calls.length > 0 && calls.every((block) => allResultIds.has(String(block.id)))) {
+      for (const block of calls) keepCallIds.add(String(block.id))
+    }
+  }
+  return { keepCallIds, keepResultIds: new Set(keepCallIds) }
+}
+
+/**
+ * One user-side content array in OpenAI's shape, or undefined when it holds no image
+ * and should therefore be sent as a plain string.
+ *
+ * Images arrive as attachment references that imageUrls resolves to data URLs. A
+ * reference that failed to resolve becomes '[image unavailable]' text rather than a
+ * missing part -- the model then knows an image was meant to be there, which is better
+ * than silently answering as if the message were text-only.
+ */
+function userContentParts(content, imageUrls) {
+  const parts = []
+  let hasImage = false
+  for (const block of content) {
+    if (typeof block !== 'object' || block === null) continue
+    if (block.type === 'text') {
+      parts.push({ type: 'text', text: String(block.text ?? '') })
+      continue
+    }
+    if (block.type === 'image') {
+      const attachmentId = block.attachment?.attachmentId
+      const url = attachmentId === undefined ? undefined : imageUrls?.get(String(attachmentId))
+      parts.push(url === undefined ? { type: 'text', text: '[image unavailable]' } : { type: 'image_url', image_url: { url } })
+      hasImage = true
+      continue
+    }
+    if (block.type === 'tool-result' && Array.isArray(block.content)) {
+      const inner = userContentParts(block.content, imageUrls)
+      if (inner !== undefined) {
+        parts.push(...inner)
+        hasImage = true
+      } else {
+        parts.push({ type: 'text', text: contentToText(block.content) })
+      }
+    }
+  }
+  return hasImage && parts.length > 0 ? parts : undefined
+}
+
+/**
+ * The reasoning_content one assistant turn should send back, if any.
+ *
+ * **Only the newest assistant turn qualifies.** Replaying older thinking is what made a
+ * long session unusable rather than what kept it coherent: the model's own prior
+ * reasoning is re-derivable from the conversation it is written into, while the payload
+ * cost grows linearly with the number of steps and is paid on *every* turn.
+ *
+ * Measured 2026-11-11 against the live gateway, replayed history with reasoning:
+ *
+ *     0 turns      -> first token  1.5 s, total  4.2 s
+ *     30 turns     -> first token  3.5 s, total 37.6 s
+ *     60 turns     -> first token  3.1 s, total 48.4 s
+ *     100 turns    -> first token 14.7 s, total 61.3 s  (245 kB body)
+ *
+ * and an earlier 100-turn replay tripped `503 service is busy`. That curve is exactly
+ * the user-visible "message sent but nothing happens for a minute".
+ *
+ * The newest turn still matters: during a tool round-trip the model has just said "I am
+ * calling X to find Y" and needs to still be holding that plan when it reads the result.
+ * Dropping every turn would make a tool-using step restart its thinking mid-flight, so
+ * the newest one is kept and the cost stays flat instead of accumulating.
+ */
+function reasoningOf(message, newestAssistantId) {
+  if (message.id !== newestAssistantId) return ''
+  const content = Array.isArray(message.content) ? message.content : []
+  return content
+    .filter((block) => block?.type === 'reasoning')
+    .map((block) => String(block.text ?? ''))
+    .join('')
+}
+
+/** The id (or index fallback) of the last assistant message in the request. */
+function newestAssistantIdOf(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]
+    if (message?.role === 'assistant') return message.id ?? `@index:${index}`
+  }
+  return ''
+}
+
+/**
+ * Convert harness messages into the wire array.
+ *
+ * Reasoning is carried back for the newest assistant turn only; see {@link reasoningOf}
+ * for the measurement behind that rule.
+ */
+export function toWireMessages(messages, imageUrls) {
+  const wire = []
+  let pendingToolImages = []
+  const flushToolImages = () => {
+    if (pendingToolImages.length === 0) return
+    wire.push({ role: 'user', content: [{ type: 'text', text: TOOL_RESULT_IMAGE_TEXT }, ...pendingToolImages] })
+    pendingToolImages = []
+  }
+  const { keepCallIds, keepResultIds } = resolveToolPairing(messages)
+  const newestAssistantId = newestAssistantIdOf(messages)
+
+  // The identity used above falls back to a positional key when a synthetic message
+  // carries no id, so the same fallback has to be applied when reading it back.
+  const reasoningFor = (message, index) => reasoningOf(
+    { ...message, id: message.id ?? `@index:${index}` },
+    newestAssistantId
+  )
+
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index]
+    if (message.role === 'assistant') {
+      const content = Array.isArray(message.content) ? message.content : []
+      const toolCalls = content
+        .filter((block) => block?.type === 'tool-call' && keepCallIds.has(String(block.id)))
+        .map((block) => ({
+          id: String(block.id),
+          type: 'function',
+          function: { name: String(block.name), arguments: normalizeToolArguments(block.arguments) }
+        }))
+      const textContent = contentToText(content)
+      if (textContent.trim().length === 0 && toolCalls.length === 0) continue
+      flushToolImages()
+      const reasoning = reasoningFor(message, index)
+      wire.push({
+        role: 'assistant',
+        content: textContent.length === 0 && toolCalls.length > 0 ? null : textContent,
+        ...(reasoning.length > 0 ? { reasoning_content: reasoning } : {}),
+        ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {})
+      })
+      continue
+    }
+    if (message.role === 'system' || message.role === 'developer') {
+      flushToolImages()
+      wire.push({ role: 'system', content: contentToText(message.content) })
+      continue
+    }
+    // A tool result arrives as a message of its own and must stay a tool message.
+    const resultCallId = toolResultCallId(message)
+    if (resultCallId !== undefined) {
+      if (!keepResultIds.has(resultCallId)) continue
+      let resultText = '(no output)'
+      if (imageUrls !== undefined && Array.isArray(message.content)) {
+        const resultParts = userContentParts(message.content, imageUrls)
+        if (resultParts !== undefined) {
+          pendingToolImages.push(...resultParts.filter((part) => part.type !== 'text'))
+          const joined = resultParts.filter((part) => part.type === 'text').map((part) => String(part.text)).join('')
+          if (joined.length > 0) resultText = joined
+        } else {
+          resultText = contentToText(message.content) || '(no output)'
+        }
+      } else {
+        resultText = contentToText(message.content) || '(no output)'
+      }
+      wire.push({ role: 'tool', tool_call_id: resultCallId, content: resultText })
+      continue
+    }
+
+    const content = Array.isArray(message.content) ? message.content : []
+    const toolResults = content.filter((block) => block?.type === 'tool-result')
+    const regular = content.filter((block) => block?.type !== 'tool-result')
+    const text = contentToText(message.content)
+    const parts = userContentParts(regular, imageUrls)
+    if (parts !== undefined) {
+      flushToolImages()
+      wire.push({ role: 'user', content: parts })
+    } else if (text.trim().length > 0) {
+      flushToolImages()
+      wire.push({ role: 'user', content: text })
+    }
+    for (const result of toolResults) {
+      if (!keepResultIds.has(String(result.toolCallId))) continue
+      let resultText = '(no output)'
+      if (imageUrls !== undefined && Array.isArray(result.content)) {
+        const resultParts = userContentParts(result.content, imageUrls)
+        if (resultParts !== undefined) {
+          pendingToolImages.push(...resultParts.filter((part) => part.type !== 'text'))
+          const joined = resultParts.filter((part) => part.type === 'text').map((part) => String(part.text)).join('')
+          if (joined.length > 0) resultText = joined
+        } else {
+          resultText = contentToText(result.content) || '(no output)'
+        }
+      } else {
+        resultText = contentToText(result.content) || '(no output)'
+      }
+      wire.push({ role: 'tool', tool_call_id: String(result.toolCallId), content: resultText })
+    }
+  }
+  flushToolImages()
+  return wire
+}