@goodandready/dsh-clinebot 0.5.33 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to `@goodandready/dsh-clinebot` will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1] - 2026-10-21
+
+### Fixed
+- **ClineBot-only session cost**: the composer now reads the plugin's per-session `bySession` bucket instead of the host's session-wide `tokenUsage`. A conversation that also used OpenCode can no longer inflate the ClineBot estimate.
+- **Last request in the tooltip**: each session bucket retains the latest ClineBot request; the native token pill title now shows the ClineBot session cost and the last request cost.
+- **Free estimates**: priced requests that cost zero render as `Free` instead of `$0.0000`.
+
+### Added
+- `GET /dsh-clinebot/stats/session?sessionId=...` returns the ClineBot-only aggregate for one DSH session, including the last request.
+
+## [0.6.0] - 2026-10-20
+
+### Added
+- **Native `ctx.llm` adapter**: `ClineBotAdapter` now owns streaming, model metadata, reasoning effort, pre-first-token account failover, retry policy and provider status. The legacy `llm-pi-ai` provider + loopback proxy is no longer required for chat.
+- **Quota panel**: the sidebar opens a center-column `Quota / Analytics` panel through `layout.selectPanel`, with header refresh/close, account tabs, 120s auto-refresh and explicit `no key` / `endpoint unreachable` / `not registered` states. A modal fallback is used when the host panel API is unavailable.
+- **Three fixed quota rows**: the sidebar always shows `5-Hour`, `Weekly` and `Monthly` limits with reset countdowns, `—` for unavailable windows and the active account in the tooltip.
+- **Analytics v2**: persistent stats now track cache read/write tokens, estimated cost, TTFT, latency and bounded per-session buckets. The panel adds 7/30/90-day ranges, a weekday×hour request heatmap, peak-hour summary, by-hour strip and model filter; `GET /dsh-clinebot/analytics` exposes the aggregates and the store keeps 95 days with best-effort backfill.
+- **Native composer cost**: the session estimate is appended to the host token-usage pill (`N tok · Cache hit X% · ≈ $...` / `Free`) instead of a second dock pill; its tooltip breaks down input, output, cache and reasoning tokens. The cost read-out is scoped to ClineBot model selections so OpenCode sessions keep their own provider estimate.
+- **Local price table**: `lib/model-prices.js` resolves per-model estimates with user overrides and `estimate` / `override` provenance; `GET /dsh-clinebot/prices` feeds the composer. Unknown models display `unpriced` instead of `$0`.
+- **dsh-TUI settings**: `ClineBot` section for API key, base URL, plan filtering, web search, sidebar quota, active account, context window and output cap.
+- **Account surface**: live per-account usage, inline rename, clear key, pin/unpin and delete with inline confirmation; `GET /dsh-clinebot/accounts/usage`, `POST /accounts/rename`, `POST /accounts/key/clear`.
+- **Calm settings UI**: staged single-save configuration, collapsible groups, SVG stroke icons and native primitives; no emojis in the client bundle. Neutral surfaces, compact tables and 8px progress bars follow the OpenCode provider visual language.
+- **Coverage**: 240 tests total (238 pass, 2 platform skips, 0 failures); client bundle 251.8 KB, below the 256 KiB DSH Store limit.
+
+### Changed
+- Retargeted to **DSH `0.2.1-rc.2`** (`engines.dsh`) with peer dependencies on `dsh-llm`, `dsh-attachment`, `dsh-credentials`, `dsh-settings`, `dsh-commands` and `dsh-web`.
+- New installs default to `transport: "adapter"`. Settings, models and account actions are grouped; model and account ops stay immediate.
+- Composer cost now reads the live price endpoint and respects `showComposerCost`; `/stats/export?detailed=1` adds cache, cost, TTFT and latency columns.
+
+### Deprecated
+- `transport: "pi-ai"`, `proxyMode`, `lib/proxy-server.js`, `lib/proxy-token.js`, `lib/routes/proxy.js` and the `llm/stream` hook remain for one release as a compatibility fallback. They will be removed in 0.7.0.
+
 ## [0.5.33] - 2026-10-19
 
 ### Security

package/README.md

@@ -4,11 +4,13 @@
 
 <h3>Native ClineBot / ClinePass Provider Companion for DeepSeek Harness</h3>
 
+<p><b>0.6.0</b> moves chat onto a native <code>ctx.llm</code> adapter. Requires DSH <code>0.2.1-rc.2</code>. The legacy <code>llm-pi-ai</code> + loopback-proxy path remains available behind <code>transport: "pi-ai"</code> for one release.</p>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-clinebot.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
   <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
 </p>
 
 <!-- Author Showcase Link -->
@@ -66,59 +68,73 @@ Integrating ClinePass into DeepSeek Harness (DSH) natively poses key challenges:
 ```mermaid
 graph LR
     subgraph UI [DSH Web Interface]
-        Page["Dedicated Page (Settings -> ClineBot)"]
-        QuotaBar["5-Hour & Weekly Progress Bars & Warning Banner"]
-        KeyInput["Direct Key Paste & Save"]
-        ModelPick["Dynamic Model Sync & Picker Controls"]
-        StatsCard["Session Metrics Telemetry"]
+        Settings["Settings -> ClineBot"]
+        Dashboard["Quota / Analytics panel"]
+        Composer["Composer cost read-out"]
+        Picker["Model picker"]
     end
 
-    subgraph PluginHost [dsh-clinebot Host Runtime]
-        HttpEndpoints["API: /dsh-clinebot/*"]
-        ClientCore["lib/cline-client.js"]
-        ModelCatalog["lib/models.js (Curated + Dynamic Plan)"]
-        SlashCmd["Command: /cline"]
+    subgraph PluginHost [dsh-clinebot Runtime]
+        Routes["HTTP: /dsh-clinebot/*"]
+        Adapter["lib/adapter.js (ctx.llm LlmAdapter)"]
+        Transport["lib/transport/cline-transport.js"]
+        Pool["account-pool + session-router"]
+        Stats["stats-storage v2 + model-prices"]
+        TUI["dsh-TUI settings section"]
     end
 
-    subgraph DSHCore [DeepSeek Harness Services]
-        Credentials["Credentials Service (~/.dsh/.credentials.yaml)"]
-        PiAi["Settings: llm-pi-ai.providers.clinebot"]
+    subgraph DSHCore [DeepSeek Harness 0.2.1-rc.2]
+        Llm["ctx.llm"]
+        Credentials["ctx.credentials"]
+        Web["ctx.web / settings / commands"]
     end
 
-    subgraph Upstream [Cline Cloud]
-        ClinePass["api.cline.bot/api/v1/chat/completions"]
-        ClineQuota["api.cline.bot/api/v1/users/me/plan/usage-limits"]
-        ClinePlan["api.cline.bot/api/v1/users/me/plan"]
+    subgraph Upstream [ClinePass]
+        Chat["api.cline.bot/api/v1/chat/completions"]
+        Quota["users/me/plan/usage-limits"]
+        Plan["users/me/plan"]
     end
 
-    Page -->|GET /status & /usage| HttpEndpoints
-    KeyInput -->|POST /save-key| HttpEndpoints
-    ModelPick -->|POST /models/sync| HttpEndpoints
-    HttpEndpoints --> Credentials
-    HttpEndpoints --> ClientCore
-    ClientCore --> ModelCatalog
-    HttpEndpoints -->|Atomic Mutate| PiAi
-    ClientCore -->|Chat| ClinePass
-    ClientCore -->|Usage Limits| ClineQuota
-    ClientCore -->|Plan Features| ClinePlan
+    Settings --> Routes
+    Dashboard --> Routes
+    Composer --> Routes
+    Picker --> Llm
+    Llm --> Adapter
+    Adapter --> Pool
+    Adapter --> Transport
+    Transport --> Chat
+    Adapter --> Stats
+    Routes --> Stats
+    Routes --> Credentials
+    TUI --> Routes
+    Adapter --> Quota
+    Adapter --> Plan
 ```
 
 ---
 
 ## ✨ Features & Module Breakdown
 
+* **`lib/adapter.js`**:
+  Registers the `ClineBotAdapter` directly on `ctx.llm`: streaming, model catalogue, reasoning effort, pre-first-token account failover, retry policy, usage accounting and provider metadata.
+* **`lib/transport/cline-transport.js`**:
+  OpenAI-compatible SSE transport with connect/idle timeouts, abort handling and upstream error classification. The legacy proxy imports the same parser.
 * **`lib/models.js`**:
-  Manages the dynamic subscription catalog and fallback models with full reasoning effort mappings (`off: null`, `low`, `medium`, `high`, `max`), upstream 200k context limit declarations, user-defined custom models, and dynamic subscription plan model parsing (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
+  Dynamic subscription catalogue, curated fallback properties, reasoning efforts, custom models and plan parsing (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
+* **`lib/model-prices.js`**:
+  Explicit local cost estimates with per-model overrides. Unknown models stay `unpriced` instead of being reported as $0.
+* **`lib/stats-storage.js`**:
+  Persistent JSON telemetry v2: cache buckets, estimated cost, TTFT/latency, sessions and day/month/model/account aggregates. v1 files upgrade on read.
+* **`lib/account-pool.js` / `lib/session-router.js`**:
+  Credential discovery, usage-aware least-used and round-robin rotation, sticky sessions and cooldown recovery.
 * **`lib/cline-client.js`**:
-  * `fetchUsageLimits`: queries `GET /users/me/plan/usage-limits`, `GET /users/me/plan`, and `GET /users/me` with in-memory caching.
-  * `sessionStats` / `recordSessionRequest`: in-memory telemetry recording requests count, tokens, latency, and timestamps.
-  * `saveCredentialKey`: writes credentials directly into `~/.dsh/.credentials.yaml`.
-  * `smokeChat`: tests latency via non-streaming ping and updates session metrics.
-  * `buildPiAiProvider`: builds the DSH `llm-pi-ai` structure (`api: 'openai-completions'`) with full reasoning effort protocol compliance (`compat.supportsReasoningEffort: true`).
+  `fetchUsageLimits`, credential save, smoke test, model cache and the legacy `llm-pi-ai` provider builder used only by `transport: "pi-ai"`.
 * **`lib/index.js`**:
-  Cordis service module managing routes (including `POST /dsh-clinebot/models/sync`), quota warnings threshold evaluation, credentials, and registering the `/cline` slash command.
+  Cordis lifecycle: adapter registration, optional HTTP routes, quota warnings, `/cline` command, migration of the legacy provider and TUI section registration.
+* **`lib/tui-settings.js`**:
+  `dsh-TUI` section for key, base URL, model filters, active account, context window and output cap.
 * **`lib/client.js`**:
-  Configuration page on the plugin row (`plugins.row.config`) with live quota bars, an exhaustion warning, session metrics, one-click plan sync, and a fallback plugins card (`settings.plugin.item`). There is no `settings.section` sidebar entry.
+  Native `settings.section` plus provider card, sidebar meter, center-column quota/analytics panel (modal fallback) and composer cost read-out. No emojis, no full-page panel swap.
 
 ---
 
@@ -128,8 +144,19 @@ graph LR
 dsh plugin --profile web add @goodandready/dsh-clinebot
 ```
 
+Requires **DSH `0.2.1-rc.2`** and Node 22+. New installs use `transport: "adapter"` and register directly with `ctx.llm`. Set `transport: "pi-ai"` only if you still need the legacy `llm-pi-ai` provider and loopback proxy for one release.
+
 Restart your DeepSeek Harness instance and refresh the browser.
 
+### 0.6.0 endpoints
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /dsh-clinebot/analytics?groupBy=model\|day\|session&from=&to=` | Aggregated requests, tokens, estimated cost, success rate and TTFT |
+| `GET /dsh-clinebot/prices` | Local price table used by the composer read-out |
+| `GET /dsh-clinebot/accounts/usage` | Per-account quota snapshot |
+| `GET /dsh-clinebot/stats/export?detailed=1` | CSV with cache, cost, TTFT and latency columns |
+
 ---
 
 ## 💬 Slash-Command `/cline`

package/README.ru.md

@@ -4,11 +4,13 @@
 
 <h3>Нативное подключение провайдера ClineBot / ClinePass для DeepSeek Harness</h3>
 
+<p><b>0.6.0</b> переводит чат на нативный адаптер <code>ctx.llm</code>. Требуется DSH <code>0.2.1-rc.2</code>. Старый путь <code>llm-pi-ai</code> + loopback-прокси остаётся за флагом <code>transport: "pi-ai"</code> на один релиз.</p>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
   <a href="../LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-clinebot.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
   <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
 </p>
 
 <!-- Обязательная кнопка перехода на витрину всех проектов -->

package/README.zh.md

@@ -4,11 +4,13 @@
 
 <h3>适用于 DeepSeek Harness 的 ClineBot / ClinePass 原生模型提供商伴侣插件</h3>
 
+<p><b>0.6.0</b> 将聊天迁移到原生 <code>ctx.llm</code> 适配器。需要 DSH <code>0.2.1-rc.2</code>。旧的 <code>llm-pi-ai</code> + 回环代理路径保留一个版本，通过 <code>transport: "pi-ai"</code> 启用。</p>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
   <a href="../LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-clinebot.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
   <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
 </p>
 
 <!-- 作者所有项目展示页面链接 -->

package/lib/adapter-messages.js

@@ -0,0 +1,237 @@
+/**
+ * Translate DSH request messages and tools into ClinePass's OpenAI-compatible
+ * wire shape. Files are projected to text handles; images are resolved through
+ * the attachment seam into request-sized bytes.
+ */
+
+const IMAGE_MAX_EDGE = 1568
+const IMAGE_MAX_BYTES = 1024 * 1024
+
+/**
+ * Concatenate text blocks.
+ * @param {readonly Record<string, unknown>[]} blocks
+ * @returns {string}
+ */
+function textOf(blocks) {
+  if (!Array.isArray(blocks)) return ''
+  return blocks
+    .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('')
+}
+
+/**
+ * Stable placeholder for one file block.
+ * @param {Record<string, unknown>} block
+ * @returns {string}
+ */
+function fileText(block) {
+  const ref = block?.attachment && typeof block.attachment === 'object' ? block.attachment : null
+  if (!ref) return '[File omitted]'
+  const name = typeof ref.name === 'string' && ref.name ? ref.name : 'attachment'
+  const bytes = Number.isFinite(Number(ref.bytes)) ? Number(ref.bytes) : null
+  return `[File: ${name}${bytes === null ? '' : `, ${bytes} bytes`}]`
+}
+
+/**
+ * Placeholder for an image that cannot be resolved or was deliberately offloaded.
+ * @param {Record<string, unknown>} block
+ * @returns {string}
+ */
+function imagePlaceholder(block) {
+  const ref = block?.attachment && typeof block.attachment === 'object' ? block.attachment : null
+  const name = typeof ref?.name === 'string' && ref.name ? ref.name : 'image'
+  const mediaType = typeof ref?.mediaType === 'string' ? ref.mediaType : 'image'
+  if (block?.offloaded === true) {
+    return `[Image: ${name} (${mediaType}) — previously analyzed and omitted from this request]`
+  }
+  return `[Image: ${name} (${mediaType})]`
+}
+
+/**
+ * Request-image target for ClinePass's gateway.
+ * @param {Record<string, unknown>} ref
+ * @returns {{ width: number, height: number, maxBytes: number }}
+ */
+function imageTarget(ref) {
+  const width = Math.max(1, Number(ref?.width) || IMAGE_MAX_EDGE)
+  const height = Math.max(1, Number(ref?.height) || IMAGE_MAX_EDGE)
+  const scale = Math.min(1, IMAGE_MAX_EDGE / Math.max(width, height))
+  return {
+    width: Math.max(1, Math.round(width * scale)),
+    height: Math.max(1, Math.round(height * scale)),
+    maxBytes: IMAGE_MAX_BYTES,
+  }
+}
+
+/**
+ * Resolve one image block to a data URL.
+ * @param {Record<string, unknown>} block
+ * @param {unknown} attachments
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<string>}
+ */
+async function imageToUrl(block, attachments, signal) {
+  if (block?.offloaded === true) return imagePlaceholder(block)
+  const ref = block?.attachment && typeof block.attachment === 'object' ? block.attachment : null
+  if (!ref) return imagePlaceholder(block)
+  if (!attachments || typeof attachments.readImageRequest !== 'function') {
+    return imagePlaceholder(block)
+  }
+  try {
+    const requestImage = await attachments.readImageRequest(ref, imageTarget(ref), signal)
+    if (!requestImage?.data) return imagePlaceholder(block)
+    const base64 = Buffer.from(requestImage.data).toString('base64')
+    return `data:${requestImage.mediaType || ref.mediaType || 'image/png'};base64,${base64}`
+  } catch {
+    return imagePlaceholder(block)
+  }
+}
+
+/**
+ * Build OpenAI-compatible content for one user/developer message.
+ * @param {readonly Record<string, unknown>[]} blocks
+ * @param {unknown} attachments
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<string | Record<string, unknown>[]>}
+ */
+async function userContent(blocks, attachments, signal) {
+  const content = []
+  let hasImage = false
+  for (const block of Array.isArray(blocks) ? blocks : []) {
+    if (!block || typeof block !== 'object') continue
+    if (block.type === 'text' && typeof block.text === 'string' && block.text !== '') {
+      content.push({ type: 'text', text: block.text })
+    } else if (block.type === 'image') {
+      hasImage = true
+      content.push({ type: 'image_url', image_url: { url: await imageToUrl(block, attachments, signal) } })
+    } else if (block.type === 'file') {
+      content.push({ type: 'text', text: fileText(block) })
+    } else if (block.type === 'tool-result') {
+      const resultText = textOf(block.content)
+      if (resultText) content.push({ type: 'text', text: resultText })
+    }
+  }
+  if (!hasImage) {
+    return content.filter((part) => part.type === 'text').map((part) => part.text).join('\n')
+  }
+  return content
+}
+
+/**
+ * Build an assistant message with text, reasoning replay, and tool calls.
+ * @param {Record<string, unknown>} message
+ * @param {unknown} attachments
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function assistantMessage(message, attachments, signal) {
+  const blocks = Array.isArray(message.content) ? message.content : []
+  const text = textOf(blocks)
+  const reasoning = blocks
+    .filter((block) => block && block.type === 'reasoning' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('')
+  const toolCalls = blocks
+    .filter((block) => block && block.type === 'tool-call')
+    .map((block) => ({
+      id: String(block.id || ''),
+      type: 'function',
+      function: {
+        name: String(block.name || ''),
+        arguments: typeof block.arguments === 'string' ? block.arguments : JSON.stringify(block.arguments ?? {}),
+      },
+    }))
+
+  const out = {
+    role: 'assistant',
+    content: text === '' ? null : text,
+    ...(reasoning ? { reasoning_content: reasoning } : {}),
+    ...(toolCalls.length ? { tool_calls: toolCalls } : {}),
+  }
+
+  // Some assistant content may include images. ClinePass's chat shape cannot
+  // represent assistant-side images, so they become deterministic text.
+  for (const block of blocks) {
+    if (block?.type === 'image') {
+      out.content = `${out.content || ''}${out.content ? '\n' : ''}${imagePlaceholder(block)}`
+    }
+  }
+  return out
+}
+
+/**
+ * Build the complete OpenAI-compatible payload.
+ *
+ * @param {{
+ *   provider: string,
+ *   model: string,
+ *   messages: readonly Record<string, unknown>[],
+ *   system?: string,
+ *   tools?: readonly Record<string, unknown>[],
+ *   temperature?: number,
+ *   maxTokens?: number,
+ *   stop?: readonly string[],
+ *   signal?: AbortSignal,
+ * }} options
+ * @param {{ attachments?: unknown }} [deps]
+ * @returns {Promise<{ messages: Record<string, unknown>[], tools: Record<string, unknown>[] }>}
+ */
+export async function buildOpenAiPayload(options, { attachments } = {}) {
+  const messages = []
+
+  if (typeof options.system === 'string' && options.system !== '') {
+    messages.push({ role: 'system', content: options.system })
+  }
+
+  for (const message of Array.isArray(options.messages) ? options.messages : []) {
+    if (!message || typeof message !== 'object') continue
+    const role = String(message.role || '')
+    const blocks = Array.isArray(message.content) ? message.content : []
+
+    if (role === 'system') {
+      const text = textOf(blocks)
+      if (text !== '') messages.push({ role: 'system', content: text })
+      continue
+    }
+    if (role === 'developer') {
+      const text = textOf(blocks)
+      if (text !== '') messages.push({ role: 'system', content: text })
+      continue
+    }
+    if (role === 'assistant') {
+      messages.push(await assistantMessage(message, attachments, options.signal))
+      continue
+    }
+    if (role === 'tool') {
+      const callId = message.toolCallId
+        || message.source?.callId
+        || blocks.find((block) => block?.type === 'tool-result')?.toolCallId
+        || ''
+      messages.push({
+        role: 'tool',
+        tool_call_id: String(callId),
+        content: textOf(blocks) || (message.isError ? '[tool error]' : ''),
+      })
+      continue
+    }
+    // `user` and identity-free request inputs.
+    const content = await userContent(blocks, attachments, options.signal)
+    messages.push({ role: 'user', content })
+  }
+
+  const tools = (Array.isArray(options.tools) ? options.tools : [])
+    .filter((tool) => tool && typeof tool === 'object')
+    .map((tool) => ({
+      type: 'function',
+      function: {
+        name: String(tool.name || ''),
+        description: String(tool.description || ''),
+        parameters: tool.parameters && typeof tool.parameters === 'object'
+          ? tool.parameters
+          : { type: 'object', properties: {} },
+      },
+    }))
+
+  return { messages, tools }
+}