@kukonce/dsh-loomy 0.0.0-stage → 0.3.2

package/src/llm/adapter.js

@@ -0,0 +1,698 @@
+/**
+ * The Loomy wire adapter.
+ *
+ * Duck-typed against the harness `LlmAdapter` contract (`providerInfo`, `listModels`,
+ * `resolveModel`, `prepareCall` -> `{ model, stream }`) instead of importing
+ * `@deepseek-ai/dsh-llm`. Two reasons: the npm package stays installable on its own,
+ * and a duplicate copy of the harness package cannot make `instanceof` checks fail.
+ *
+ * Wire shape, all on one OpenAI-compatible endpoint:
+ *
+ *   POST {gateway}/chat/completions
+ *   Authorization: Bearer <session>   and   token: <session>   (both are checked)
+ *   traceparent: 00-<32hex>-<16hex>-01      (the gateway stalls without it)
+ *   loomy-version, X-Loomy-Request-Purpose   (metering attribution)
+ *
+ * Streaming is the only mode that carries `reasoning_content`, which is where most of
+ * a reasoning model's tokens go. Measured 2026-11-11: with the default catalog effort,
+ * a two-sentence reply spent ~130 reasoning characters and ~35 answer characters, and
+ * `max_tokens` counts both. That is why the adapter raises a too-small ceiling instead of
+ * letting the answer be silently truncated (see `resolveBudget`).
+ */
+
+import { randomUUID } from 'node:crypto'
+
+import { CLIENT_VERSION, GATEWAY_BASE_URL, PURPOSE_CHAT_MESSAGE } from '../core/endpoints.js'
+import { localDayKey } from '../core/http.js'
+import { accountOf } from '../account/auth.js'
+import { recordPointsSpent } from '../account/credits.js'
+import { isChatModel, loadCatalog, placeholderEntry } from '../account/models.js'
+import { isAuthFailure, markExpired, sessionOf } from '../account/session.js'
+import { classifyEnding, isTruncatedArguments, normalizeToolArguments } from './endings.js'
+import { SSE_DONE, readSse } from './sse.js'
+import { hasUsableToolName, toWireMessages } from './wire.js'
+
+/** How long a live catalog stays fresh inside one adapter instance. */
+const CATALOG_TTL_MS = 10 * 60_000
+
+/**
+ * The floor this adapter puts under `max_tokens`.
+ *
+ * Reasoning models bill their thinking against the same ceiling as their answer, and
+ * the thinking is not optional: with a 200-token ceiling the whole budget went to
+ * reasoning and the reply came back empty with `finish_reason: length`. 1024 leaves
+ * room for a short thinking pass plus a real answer, which is what a tool-calling step
+ * needs. A caller asking for more keeps its own value.
+ */
+const MIN_OUTPUT_TOKENS = 1024
+
+/** Reasoning effort ids, in the order the picker offers them. */
+const EFFORT_LABELS = {
+  none: 'None',
+  low: 'Low',
+  medium: 'Medium',
+  high: 'High',
+  xhigh: 'Extra high'
+}
+
+const effortName = (id) => EFFORT_LABELS[id] ?? id.charAt(0).toUpperCase() + id.slice(1)
+
+/**
+ * Build the error the harness classifies.
+ *
+ * `code` is what the retry policy and the transcript read, so it is set on both the
+ * error itself (for a caller that inspects it) and on a `failure` object (for the
+ * adapter-failure normalizer, which reads only that shape).
+ */
+function llmError(message, code, extra = {}) {
+  const error = new Error(message)
+  error.name = 'LlmError'
+  error.code = code
+  Object.assign(error, extra)
+  error.failure = { message, code, ...(extra.status === undefined ? {} : { status: extra.status }) }
+  return error
+}
+
+/** A readable reason out of a gateway error body, which comes in several shapes. */
+function errorDetail(body) {
+  try {
+    const data = JSON.parse(body)
+    const localized = typeof data?.error?.message === 'string' ? data.error.message : undefined
+    const parts = [
+      localized,
+      typeof data?.desc === 'string' ? data.desc : undefined,
+      typeof data?.message === 'string' ? data.message : undefined,
+      typeof data?.msg === 'string' ? data.msg : undefined
+    ].filter((value) => typeof value === 'string' && value.length > 0)
+    if (parts.length > 0) return parts.join(' ')
+  } catch {
+    // not JSON: fall through to the raw prefix
+  }
+  const raw = String(body ?? '')
+  // The gateway answers an upstream failure with a full HTML error page. Pasted into a
+  // transcript that is unreadable, and it buries the one fact worth keeping -- which
+  // proxy produced it. Reduce it to a single line naming the origin when there is one.
+  if (/<html/i.test(raw)) {
+    const origin = /<(?:center|address|hr)[^>]*>\s*([^<\s][^<]{0,60})\s*</i.exec(raw)?.[1]?.trim()
+    const title = /<title>([^<]{0,120})<\/title>/i.exec(raw)?.[1]?.trim()
+    return [title, origin !== undefined && origin !== title ? `（来自 ${origin}）` : ''].filter(Boolean).join('')
+      || '上游返回了一个 HTML 错误页'
+  }
+  return raw.slice(0, 400)
+}
+
+/**
+ * Map an HTTP failure onto the harness failure code.
+ *
+ * `100002` is Loomy's own "session is dead" code and arrives with a 200 on the points
+ * API, but the gateway uses a plain 401/403 -- both have to read as `AUTH` or the retry
+ * package will happily rerun a request that cannot succeed.
+ */
+function httpErrorCode(status, body) {
+  if (status === 401 || status === 403) return 'AUTH'
+  if (status === 429) return 'RATE_LIMIT'
+  if (status === 400) {
+    return /context|too long|prompt is too long|exceed/i.test(String(body)) ? 'CONTEXT_WINDOW_EXCEEDED' : 'INVALID_REQUEST'
+  }
+  if (/insufficient|积分余额不足|points/i.test(String(body))) return 'QUOTA'
+  if (status >= 500) return 'SERVER'
+  return status >= 400 ? `HTTP_${status}` : 'UNKNOWN'
+}
+
+/** `traceparent` per the W3C trace-context format. */
+function traceparent() {
+  const trace = randomUUID().replace(/-/gu, '')
+  const span = randomUUID().replace(/-/gu, '').slice(0, 16)
+  return `00-${trace}-${span}-01`
+}
+
+/**
+ * Merge two usage reports, keeping the larger of each counter.
+ *
+ * The gateway sends usage once at the end, but a proxied stream can repeat it; summing
+ * would double-count the prompt, so the merge takes the max, which is correct for both.
+ */
+function mergeUsage(previous, next) {
+  if (next === undefined) return previous
+  if (previous === undefined) return next
+  const pick = (key) => {
+    const a = previous[key]
+    const b = next[key]
+    if (typeof a !== 'number') return b
+    if (typeof b !== 'number') return a
+    return Math.max(a, b)
+  }
+  return {
+    inputTokens: pick('inputTokens'),
+    outputTokens: pick('outputTokens'),
+    ...(previous.cacheReadTokens === undefined && next.cacheReadTokens === undefined
+      ? {}
+      : { cacheReadTokens: pick('cacheReadTokens') }),
+    ...(previous.reasoningTokens === undefined && next.reasoningTokens === undefined
+      ? {}
+      : { reasoningTokens: pick('reasoningTokens') })
+  }
+}
+
+/**
+ * Describe a stream that ended without its terminator.
+ *
+ * The remote's reason is not observable, so the report carries what is: how much
+ * arrived, how long it took, and how long the silence before the cut.
+ */
+function describeCut({ receivedBytes, startedAt, lastDataAt }) {
+  const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1)
+  const silence = ((Date.now() - lastDataAt) / 1000).toFixed(1)
+  const size = receivedBytes < 1024 ? `${receivedBytes} B` : `${(receivedBytes / 1024).toFixed(1)} kB`
+  return `收到 ${size}，用时 ${elapsed}s，最后一段数据在 ${silence}s 前`
+}
+
+/* -- the adapter ------------------------------------------------------------ */
+
+export class LoomyAdapter {
+  /**
+   * @param {object} ctx - Cordis context (uses `ctx.get('attachments')` and `ctx.logger`).
+   * @param {object} account - one entry from the account table.
+   * @param {string} provider - the route this adapter serves.
+   */
+  constructor(ctx, account, provider) {
+    this.ctx = ctx
+    this.account = account
+    this.provider = provider
+    /** A per-conversation identity, used for the prompt-cache key. */
+    this.sessionId = randomUUID().replace(/-/gu, '')
+    this.catalog = undefined
+    this.catalogAt = 0
+    this.catalogSource = 'none'
+  }
+
+  get displayName() {
+    const label = this.account.label.length > 0 ? this.account.label : this.account.id
+    return `Loomy (${label})`
+  }
+
+  /** The adapter's identity for one route; registration refuses a mismatched id. */
+  providerInfo(provider) {
+    return { id: provider, name: this.displayName }
+  }
+
+  /**
+   * Part of the duck-typed registration surface.
+   *
+   * The method has to exist: registration calls it directly, and a missing one throws
+   * during `registerAdapter`, which fails the whole plugin apply() -- no providers, no
+   * routes, a panel that answers 404. Returning undefined means "use the defaults".
+   */
+  providerRetryPolicy() {
+    return undefined
+  }
+
+  /** Also part of the duck-typed surface, called when a request carries images. */
+  imageRequestPricing() {
+    return undefined
+  }
+
+  /** Preserve the normalized image as-is: this route does not resize. */
+  imageRequestTarget(_provider, _model, image) {
+    return { width: image.width, height: image.height, maxBytes: image.bytes }
+  }
+
+  /** A fresh conversation identity, used after an auth or cache-key reset. */
+  rotateIdentity() {
+    this.sessionId = randomUUID().replace(/-/gu, '')
+  }
+
+  /** The session string, re-read from disk so a re-login takes effect immediately. */
+  currentAccount() {
+    const latest = accountOf(this.account.id)
+    if (latest !== undefined) this.account = latest
+    return this.account
+  }
+
+  /**
+   * The account's live catalog, cached in memory for {CATALOG_TTL_MS}.
+   *
+   * The on-disk copy behind {loadCatalog} outlives this object, so a restart during an
+   * outage still offers the last list the account could see.
+   */
+  async models() {
+    const fresh = this.catalog !== undefined && Date.now() - this.catalogAt < CATALOG_TTL_MS
+    if (fresh) return this.catalog
+    const account = this.currentAccount()
+    const session = sessionOf(account)
+    const loaded = await loadCatalog(account.id, session)
+    this.catalog = loaded.entries
+    this.catalogSource = loaded.source
+    this.catalogAt = Date.now()
+    if (loaded.isAuthError === true) markExpired(account.id, '模型列表读取被拒绝')
+    return this.catalog
+  }
+
+  /** Drop the in-memory catalog so the next call sees a freshly signed-in account. */
+  invalidateCatalog() {
+    this.catalog = undefined
+    this.catalogAt = 0
+    this.catalogSource = 'none'
+  }
+
+  /** One catalog entry, or a stand-in so a known id stays callable during an outage. */
+  async entryOf(model) {
+    const catalog = await this.models()
+    return catalog.find((entry) => entry.id === model) ?? placeholderEntry(model)
+  }
+
+  /**
+   * The models the picker may offer.
+   *
+   * `inputModalities` is required by the harness's model picker, and an entry whose
+   * modalities are missing makes the picker drop the whole provider group -- which looks
+   * exactly like "the plugin is not installed". So a catalog entry always carries at
+   * least `['text']`.
+   */
+  async listModels(provider) {
+    let catalog
+    try {
+      catalog = await this.models()
+    } catch (error) {
+      this.ctx.logger.warn(`[loomy] ${this.account.id}: 读取模型列表失败 -- ${error instanceof Error ? error.message : String(error)}`)
+      return []
+    }
+    // Generation models are listed in the same catalog and share the same URL, but
+    // answer 404 to /chat/completions; the picker only offers what can answer a turn.
+    const offered = catalog.filter((entry) => isChatModel(entry))
+    const skipped = catalog.length - offered.length
+    this.ctx.logger.info(`[loomy] ${this.account.id}: 选择器读取目录 -> ${offered.length} 个可选（来源 ${this.catalogSource}）${skipped > 0 ? `，${skipped} 个生图模型不计入` : ''}`)
+    return offered.map((entry) => ({
+      provider,
+      id: entry.id,
+      name: entry.name,
+      inputModalities: entry.input.length > 0 ? [...entry.input] : ['text']
+    }))
+  }
+
+  /**
+   * Declared metadata for one model.
+   *
+   * The harness validates this hard: an empty `name`, a non-integer `contextWindow`, or a
+   * `reasoning.defaultEffort` outside the declared efforts makes the picker reject the
+   * provider. Every field below is therefore either absent or well-formed.
+   */
+  async resolveModel(provider, model) {
+    let entry
+    try {
+      entry = await this.entryOf(model)
+    } catch {
+      entry = placeholderEntry(model)
+    }
+    const efforts = Array.isArray(entry.efforts) ? entry.efforts : []
+    const defaultEffort = entry.defaultEffort !== undefined && efforts.includes(entry.defaultEffort)
+      ? entry.defaultEffort
+      : (efforts.includes('medium') ? 'medium' : efforts[0])
+    return {
+      provider,
+      id: model,
+      name: entry.name.length > 0 ? entry.name : model,
+      inputModalities: entry.input.length > 0 ? [...entry.input] : ['text'],
+      ...(typeof entry.contextLength === 'number' ? { context: { contextWindow: entry.contextLength } } : {}),
+      ...(typeof entry.maxOutputTokens === 'number' ? { defaultMaxTokens: entry.maxOutputTokens } : {}),
+      ...(efforts.length === 0 ? {} : {
+        reasoning: {
+          efforts: efforts.map((id) => ({ id, name: effortName(id) })),
+          ...(defaultEffort === undefined ? {} : { defaultEffort })
+        }
+      })
+    }
+  }
+
+  /** Bind metadata and the dispatch to one generation of this adapter. */
+  async prepareCall(provider, model) {
+    return {
+      model: await this.resolveModel(provider, model),
+      stream: (options) => this.stream(options)
+    }
+  }
+
+  /**
+   * Resolve image attachment references to data URLs.
+   *
+   * The harness stores images behind the `attachments` service; the gateway wants either
+   * a URL or an inline data URL, so each reference is read once and encoded. A reference
+   * that fails to read is left out -- the wire converter then substitutes placeholder
+   * text rather than dropping the message.
+   */
+  async resolveImages(messages) {
+    const refs = new Map()
+    const collect = (content) => {
+      if (!Array.isArray(content)) return
+      for (const block of content) {
+        if (block?.type === 'image' && block.attachment?.attachmentId !== undefined) {
+          refs.set(String(block.attachment.attachmentId), block.attachment)
+        }
+        if (Array.isArray(block?.content)) collect(block.content)
+      }
+    }
+    for (const message of messages) collect(message.content)
+    if (refs.size === 0) return undefined
+    const attachments = this.ctx.get('attachments')
+    const urls = new Map()
+    for (const [id, ref] of refs) {
+      try {
+        const stored = await attachments?.readImage?.(ref)
+        const mediaType = stored?.ref?.mediaType
+        if (stored?.data !== undefined && typeof mediaType === 'string') {
+          urls.set(id, `data:${mediaType};base64,${Buffer.from(stored.data).toString('base64')}`)
+        }
+      } catch (error) {
+        this.ctx.logger.warn(`[loomy] ${this.account.id}: 读取图片附件 ${id} 失败 -- ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+    return urls.size === 0 ? undefined : urls
+  }
+
+  /**
+   * The output ceiling for one call.
+   *
+   * A reasoning model spends its `max_tokens` on thinking first, so a small ceiling
+   * produces an empty answer with `finish_reason: length` -- a silent truncation the user
+   * reads as "the model refused". Raising the floor is the only fix available from this
+   * side; hiding the reasoning would break the transcript's reasoning blocks.
+   */
+  resolveBudget(options, entry) {
+    const requested = typeof options.maxTokens === 'number' && Number.isSafeInteger(options.maxTokens) && options.maxTokens > 0
+      ? options.maxTokens
+      : (typeof entry.maxOutputTokens === 'number' ? entry.maxOutputTokens : undefined)
+    if (requested === undefined) return undefined
+    return Math.max(requested, MIN_OUTPUT_TOKENS)
+  }
+
+  /**
+   * The request body.
+   *
+   * Reasoning effort is chosen from what the catalog declares, never from the model's
+   * name: the caller's own choice wins when the model has it, then the model's default,
+   * then `medium` when offered, then the first declared level. A model that declares no
+   * levels gets no field at all, which lets the deployment decide.
+   */
+  buildBody(options, model, entry, imageUrls) {
+    const messages = toWireMessages(options.messages ?? [], imageUrls)
+    if (typeof options.system === 'string' && options.system.length > 0) {
+      messages.unshift({ role: 'system', content: options.system })
+    }
+    // The gateway rejects an empty conversation outright (HTTP 400), and a request with
+    // no system message is accepted but judged differently; the desktop client always
+    // sends one, so do the same.
+    if (messages.length === 0 || messages[0].role !== 'system') {
+      messages.unshift({ role: 'system', content: 'You are a helpful assistant.' })
+    }
+
+    const body = {
+      model,
+      messages,
+      stream: true,
+      // Asking for usage explicitly is the only way to get the accounting frame, and the
+      // token meter is what makes the context gauge and the cost line work.
+      stream_options: { include_usage: true },
+      // Server-side prefix cache. Without a stable key the hit rate is always zero.
+      prompt_cache_key: this.sessionId
+    }
+
+    const tools = options.tools?.map((tool) => ({
+      type: 'function',
+      function: { name: tool.name, description: tool.description, parameters: tool.parameters }
+    }))
+    if (tools !== undefined && tools.length > 0) body.tools = tools
+    if (options.temperature !== undefined) body.temperature = options.temperature
+    if (Array.isArray(options.stop) && options.stop.length > 0) body.stop = options.stop
+
+    const budget = this.resolveBudget(options, entry)
+    if (budget !== undefined) body.max_tokens = budget
+
+    const efforts = Array.isArray(entry.efforts) ? entry.efforts : []
+    const preferred = efforts.includes(options.reasoningEffort)
+      ? options.reasoningEffort
+      : (efforts.includes(entry.defaultEffort) ? entry.defaultEffort : undefined)
+    const effort = preferred ?? (efforts.includes('medium') ? 'medium' : efforts[0])
+    if (effort !== undefined) body.reasoning_effort = effort
+    return body
+  }
+
+  /**
+   * Request headers.
+   *
+   * Both auth spellings are sent because the two halves of the same host disagree about
+   * which they read: the points API reads `token`, the gateway reads `Authorization`,
+   * and a request carrying only one of them is rejected by the other. `traceparent` is
+   * not decoration -- measured on the live gateway, an otherwise valid request without
+   * it hangs until the client times out.
+   */
+  headers(session) {
+    return {
+      Authorization: `Bearer ${session}`,
+      token: session,
+      Accept: 'text/event-stream',
+      'Content-Type': 'application/json',
+      traceparent: traceparent(),
+      'loomy-version': CLIENT_VERSION,
+      'X-Loomy-Request-Purpose': PURPOSE_CHAT_MESSAGE
+    }
+  }
+
+  /** The single wire call, with transport failures mapped onto the harness vocabulary. */
+  async send(session, body, signal) {
+    try {
+      return await fetch(`${GATEWAY_BASE_URL}/chat/completions`, {
+        method: 'POST',
+        headers: this.headers(session),
+        body,
+        signal
+      })
+    } catch (error) {
+      if (signal?.aborted === true) throw error
+      throw llmError(`${this.provider}: 传输失败 -- ${error instanceof Error ? error.message : String(error)}`, 'TRANSPORT', { cause: error })
+    }
+  }
+
+  /**
+   * Stream one model call.
+   *
+   * One provider attempt only: retrying belongs to `@deepseek-ai/dsh-llm-retry`, which
+   * runs at the persisted step boundary. The exception is a 401/403, where the session
+   * may simply have been retired -- but there is no refresh endpoint to try, so that ends
+   * as an AUTH failure the panel turns into a re-login prompt.
+   */
+  async *stream(options) {
+    const model = options.model
+    const account = this.currentAccount()
+    const session = sessionOf(account)
+    const entry = await this.entryOf(model)
+    const imageUrls = await this.resolveImages(options.messages ?? [])
+    const payload = JSON.stringify(this.buildBody(options, model, entry, imageUrls))
+    const startedAt = Date.now()
+    const state = { receivedBytes: 0, lastDataAt: startedAt }
+
+    let response = await this.send(session, payload, options.signal)
+    let rejection = ''
+    if (!response.ok) {
+      rejection = await response.text().catch(() => '')
+      const code = httpErrorCode(response.status, rejection)
+      if (code === 'AUTH') markExpired(account.id, '模型请求被拒绝（HTTP ' + response.status + '）')
+      throw llmError(
+        `${this.provider}: 模型请求失败（HTTP ${response.status}）${errorDetail(rejection)}`,
+        code,
+        { status: response.status }
+      )
+    }
+
+    const blocks = []
+    let nextIndex = 0
+    let finishReason
+    let streamEnded = false
+    let usage
+    const toolCalls = new Map()
+    const toolOrder = []
+    const toolIds = new Map()
+
+    const textBlock = () => {
+      let block = blocks.find((candidate) => candidate.kind === 'text')
+      if (block === undefined) {
+        block = { index: nextIndex, kind: 'text', text: '' }
+        nextIndex += 1
+        blocks.push(block)
+      }
+      return block
+    }
+    const reasoningBlock = () => {
+      let block = blocks.find((candidate) => candidate.kind === 'reasoning')
+      if (block === undefined) {
+        block = { index: nextIndex, kind: 'reasoning', text: '' }
+        nextIndex += 1
+        blocks.push(block)
+      }
+      return block
+    }
+
+    const finishChunk = (reason) => ({
+      type: 'finish',
+      reason,
+      response: {
+        kind: 'loomy',
+        version: 1,
+        api: 'openai-completions',
+        provider: this.provider,
+        model,
+        stopReason: finishReason ?? reason.kind,
+        ...(usage === undefined ? {} : { outputTokens: usage.outputTokens }),
+        blocks: blocks.map((block) => ({ type: block.kind }))
+      }
+    })
+
+    try {
+      for await (const payloadLine of readSse(response, state)) {
+        if (payloadLine === SSE_DONE) {
+          streamEnded = true
+          break
+        }
+        let data
+        try {
+          data = JSON.parse(payloadLine)
+        } catch {
+          continue
+        }
+        if (data.error !== undefined) {
+          throw llmError(`${this.provider}: ${data.error?.message ?? '未知错误'}`, 'SERVER')
+        }
+        if (data.choices === undefined && typeof data.code === 'string' && data.code !== '000000') {
+          throw llmError(`${this.provider}: code=${data.code} ${errorDetail(payloadLine)}`, 'INVALID_REQUEST')
+        }
+        const choice = data.choices?.[0]
+        const delta = choice?.delta ?? {}
+        if (typeof choice?.finish_reason === 'string' && choice.finish_reason.length > 0) {
+          finishReason = choice.finish_reason
+        }
+
+        if (typeof delta.content === 'string' && delta.content.length > 0) {
+          const block = textBlock()
+          if (block.text.length === 0) yield { type: 'block-start', index: block.index, blockType: 'text' }
+          block.text += delta.content
+          yield { type: 'text-delta', index: block.index, text: delta.content }
+        }
+        if (typeof delta.reasoning_content === 'string' && delta.reasoning_content.length > 0) {
+          const block = reasoningBlock()
+          if (block.text.length === 0) yield { type: 'block-start', index: block.index, blockType: 'reasoning' }
+          block.text += delta.reasoning_content
+          yield { type: 'reasoning-delta', index: block.index, text: delta.reasoning_content }
+        }
+
+        for (const call of delta.tool_calls ?? []) {
+          const wireIndex = call.index ?? 0
+          if (typeof call.id === 'string' && call.id.length > 0) toolIds.set(wireIndex, call.id)
+          const callId = toolIds.get(wireIndex) ?? `call_${wireIndex}`
+          let block = toolCalls.get(wireIndex)
+          if (block === undefined) {
+            block = { index: nextIndex, text: '', callId, announced: false, name: undefined }
+            nextIndex += 1
+            toolCalls.set(wireIndex, block)
+          }
+          block.callId = callId
+          if (typeof call.function?.name === 'string' && call.function.name.length > 0) {
+            block.name = call.function.name
+          }
+          block.text += call.function?.arguments ?? ''
+          // Arguments are collected, not streamed on: a call whose arguments are cut
+          // short must not reach the harness at all, and once a delta is emitted there
+          // is no taking it back (the assembler keeps an open tool block).
+          if (!block.announced && hasUsableToolName(block.name)) {
+            block.announced = true
+            toolOrder.push(block.index)
+          }
+        }
+
+        if (data.usage !== undefined && data.usage !== null) {
+          const promptTokens = data.usage.prompt_tokens ?? 0
+          const cachedTokens = data.usage.prompt_tokens_details?.cached_tokens ?? 0
+          const reasoningTokens = data.usage.completion_tokens_details?.reasoning_tokens
+          usage = mergeUsage(usage, {
+            inputTokens: cachedTokens > 0 ? promptTokens - cachedTokens : promptTokens,
+            outputTokens: data.usage.completion_tokens ?? 0,
+            ...(cachedTokens > 0 ? { cacheReadTokens: cachedTokens } : {}),
+            ...(typeof reasoningTokens === 'number' && reasoningTokens > 0 ? { reasoningTokens } : {})
+          })
+          // The accounting frame is also where the turn's point cost surfaces.
+          // Recorded the moment it arrives so a mid-stream abort still books the
+          // part the gateway billed; the projection in /state reads this file.
+          if (typeof data.usage.points_consumed === 'number' && data.usage.points_consumed > 0) {
+            recordPointsSpent(account.id, data.usage.points_consumed)
+          }
+          yield { type: 'usage', usage }
+        }
+      }
+    } catch (error) {
+      // A user abort is not a network failure and must be rethrown untouched; a real
+      // socket error becomes a retryable TRANSPORT ending so the step can recover.
+      if (options.signal?.aborted === true) throw error
+      if (error?.name === 'LlmError') throw error
+      const detail = describeCut({ receivedBytes: state.receivedBytes, startedAt, lastDataAt: state.lastDataAt })
+      this.ctx.logger.warn(`[loomy] ${account.id}: ${model} 的响应在网络层中断（${detail}；${error instanceof Error ? error.message : String(error)}）`)
+      yield finishChunk({
+        kind: 'error',
+        failure: {
+          message: `${this.provider}: 响应流在网络层中断（${detail}；可重试的传输错误）`,
+          code: 'TRANSPORT'
+        }
+      })
+      return
+    }
+
+    for (const index of toolOrder.sort((left, right) => left - right)) {
+      const block = [...toolCalls.values()].find((candidate) => candidate.index === index)
+      if (block === undefined || !hasUsableToolName(block.name)) continue
+      if (isTruncatedArguments(block.text)) continue
+      yield { type: 'block-start', index, blockType: 'tool-call' }
+      yield { type: 'tool-call-delta', index, id: block.callId, name: block.name, argumentsDelta: block.text }
+      yield {
+        type: 'block-end',
+        index,
+        block: {
+          type: 'tool-call',
+          id: block.callId,
+          name: block.name,
+          arguments: normalizeToolArguments(block.text)
+        }
+      }
+    }
+
+    const prose = blocks.find((block) => block.kind === 'text')
+    if (prose !== undefined) {
+      yield { type: 'block-end', index: prose.index, block: { type: 'text', text: prose.text } }
+    }
+    const reasoning = blocks.find((block) => block.kind === 'reasoning')
+    if (reasoning !== undefined && reasoning.text.trim().length > 0) {
+      yield { type: 'block-end', index: reasoning.index, block: { type: 'reasoning', text: reasoning.text } }
+    }
+
+    const argsTruncated = [...toolCalls.values()].some((block) => isTruncatedArguments(block.text))
+    const orphanCalls = [...toolCalls.values()].filter((block) => !hasUsableToolName(block.name) && block.text.trim().length > 0).length
+    const blockCount = blocks.length + toolOrder.length
+    const ending = classifyEnding({
+      streamEnded,
+      finishReason,
+      argsTruncated,
+      orphanCalls,
+      blockCount,
+      hasTools: toolOrder.length > 0
+    }, this.provider)
+
+    if (ending.note === 'cut') {
+      const detail = describeCut({ receivedBytes: state.receivedBytes, startedAt, lastDataAt: state.lastDataAt })
+      this.ctx.logger.warn(`[loomy] ${account.id}: ${model} 的响应在 finish_reason/[DONE] 之前中断（${detail}），按传输错误上报，可自动重试`)
+      ending.failure.message = `${ending.failure.message}（${detail}）`
+    } else if (ending.note === 'filtered') {
+      this.ctx.logger.warn(`[loomy] ${account.id}: ${model} 的上游以内容审核中断了回答，不重试`)
+    } else if (ending.note === 'budget' || ending.note === 'empty-budget') {
+      this.ctx.logger.warn(`[loomy] ${account.id}: ${model} 的输出达到上限，本步被截断（输出 ${usage?.outputTokens ?? '未知'} tokens）`)
+    } else if (ending.note === 'done-without-reason') {
+      this.ctx.logger.warn(`[loomy] ${account.id}: ${model} 的响应以 [DONE] 收尾但没有 finish_reason，按 stop 处理`)
+    }
+    yield finishChunk(ending)
+  }
+}