@goodandready/dsh-clinebot 0.5.33 → 0.6.0

package/lib/transport/cline-transport.js

@@ -0,0 +1,314 @@
+/**
+ * ClinePass OpenAI-compatible transport primitives.
+ *
+ * This module owns the wire boundary: request construction helpers, SSE framing,
+ * usage extraction, timeout/abort handling, and provider error classification.
+ * It intentionally contains no account routing or DSH adapter policy.
+ */
+
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+let packageVersion = '0.6.0'
+try {
+  packageVersion = require('../../package.json').version || packageVersion
+} catch {
+  /* fallback when package.json is unavailable */
+}
+
+export const USER_AGENT = `@goodandready/dsh-clinebot/${packageVersion}`
+export const DEFAULT_CONNECT_TIMEOUT_MS = 15000
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 30000
+export const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024
+
+/**
+ * Build the abort-shaped error every transport caller understands.
+ * @param {string} [message]
+ * @returns {Error}
+ */
+export function abortError(message = 'Request aborted') {
+  const error = new Error(message)
+  error.name = 'AbortError'
+  error.code = 'ABORTED'
+  return error
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isAbortError(error) {
+  return Boolean(error && (error.name === 'AbortError' || error.code === 'ABORTED'))
+}
+
+/**
+ * Normalize an OpenAI-compatible usage payload into DSH's disjoint token buckets.
+ *
+ * `prompt_tokens` includes cached input, while DSH expects `inputTokens` to be
+ * uncached input only. Cache read/write buckets are reported separately.
+ *
+ * @param {Record<string, unknown>} usage
+ * @returns {{ inputTokens: number, outputTokens: number, totalTokens?: number, cacheReadTokens?: number, cacheWriteTokens?: number, reasoningTokens?: number, promptTokens: number, completionTokens: number }}
+ */
+export function extractUsage(usage) {
+  if (!usage || typeof usage !== 'object') {
+    return { inputTokens: 0, outputTokens: 0, promptTokens: 0, completionTokens: 0 }
+  }
+  const promptTokens = Math.max(0, Number(usage.prompt_tokens) || 0)
+  const completionTokens = Math.max(0, Number(usage.completion_tokens) || 0)
+  const cacheReadTokens = Math.max(0, Number(
+    usage.prompt_tokens_details?.cached_tokens ||
+    usage.cache_read_input_tokens ||
+    usage.cached_tokens ||
+    0
+  ))
+  const cacheWriteTokens = Math.max(0, Number(
+    usage.prompt_tokens_details?.cache_write_tokens ||
+    usage.cache_creation_input_tokens ||
+    0
+  ))
+  const reasoningTokens = Math.max(0, Number(
+    usage.completion_tokens_details?.reasoning_tokens ||
+    usage.reasoning_tokens ||
+    usage.prompt_tokens_details?.reasoning_tokens ||
+    0
+  ))
+  const inputTokens = Math.max(0, promptTokens - cacheReadTokens - cacheWriteTokens)
+  const totalTokens = Number.isFinite(Number(usage.total_tokens))
+    ? Math.max(0, Number(usage.total_tokens))
+    : promptTokens + completionTokens
+
+  return {
+    inputTokens,
+    outputTokens: completionTokens,
+    ...(totalTokens > 0 ? { totalTokens } : {}),
+    ...(cacheReadTokens > 0 ? { cacheReadTokens } : {}),
+    ...(cacheWriteTokens > 0 ? { cacheWriteTokens } : {}),
+    ...(reasoningTokens > 0 ? { reasoningTokens } : {}),
+    promptTokens,
+    completionTokens,
+  }
+}
+
+/**
+ * Classify a non-2xx upstream response into an adapter error code.
+ *
+ * @param {number} status
+ * @param {string} [bodyText]
+ * @returns {{ code: string, retryable: boolean, message: string }}
+ */
+export function classifyUpstreamStatus(status, bodyText = '') {
+  const detail = String(bodyText || '').slice(0, 500)
+  const lower = detail.toLowerCase()
+  if (status === 401 || status === 403) {
+    return { code: 'AUTH', retryable: false, message: `ClinePass authentication failed (HTTP ${status})${detail ? `: ${detail}` : ''}` }
+  }
+  if (status === 429) {
+    return { code: 'RATE_LIMIT', retryable: true, message: `ClinePass rate limit exceeded (HTTP 429)${detail ? `: ${detail}` : ''}` }
+  }
+  if (status === 402 || /quota|credit|usage limit|insufficient/i.test(lower)) {
+    return { code: 'QUOTA_EXCEEDED', retryable: true, message: `ClinePass quota exhausted (HTTP ${status})${detail ? `: ${detail}` : ''}` }
+  }
+  if (status === 400 && /context|too long|maximum context|token limit/i.test(lower)) {
+    return { code: 'CONTEXT_WINDOW_EXCEEDED', retryable: false, message: `Context window exceeded (HTTP 400)${detail ? `: ${detail}` : ''}` }
+  }
+  if (status >= 500) {
+    return { code: 'PROVIDER_ERROR', retryable: true, message: `ClinePass upstream error (HTTP ${status})${detail ? `: ${detail}` : ''}` }
+  }
+  return { code: 'UPSTREAM_ERROR', retryable: false, message: `ClinePass request failed (HTTP ${status})${detail ? `: ${detail}` : ''}` }
+}
+
+/**
+ * Read a response body with a hard size bound.
+ *
+ * @param {Response} response
+ * @param {{ maxBytes?: number }} [options]
+ * @returns {Promise<string>}
+ */
+export async function readResponseText(response, { maxBytes = DEFAULT_MAX_BODY_BYTES } = {}) {
+  if (!response?.body) return ''
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder('utf8')
+  let size = 0
+  let out = ''
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.byteLength
+      if (size > maxBytes) {
+        throw new Error(`Upstream response exceeded ${maxBytes} bytes`)
+      }
+      out += decoder.decode(value, { stream: true })
+    }
+    out += decoder.decode()
+    return out
+  } finally {
+    try { reader.releaseLock() } catch {}
+  }
+}
+
+/**
+ * Whether a response is an SSE stream.
+ * @param {Response} response
+ * @returns {boolean}
+ */
+export function isEventStream(response) {
+  return String(response?.headers?.get?.('content-type') || '').toLowerCase().includes('text/event-stream')
+}
+
+/**
+ * Send one OpenAI-compatible chat completion request.
+ *
+ * The connect timeout covers headers only; once headers arrive the caller owns
+ * the stream and applies its own idle watchdog.
+ *
+ * @param {{
+ *   baseUrl: string,
+ *   apiKey: string,
+ *   body: Record<string, unknown>,
+ *   signal?: AbortSignal,
+ *   connectTimeoutMs?: number,
+ *   extraHeaders?: Record<string, string>,
+ * }} options
+ * @returns {Promise<Response>}
+ */
+export async function requestChatCompletion({
+  baseUrl,
+  apiKey,
+  body,
+  signal,
+  connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS,
+  extraHeaders = {},
+}) {
+  const connectCtrl = new AbortController()
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    connectCtrl.abort(abortError(`Upstream connect timeout after ${connectTimeoutMs}ms`))
+  }, Math.max(1, Number(connectTimeoutMs) || DEFAULT_CONNECT_TIMEOUT_MS))
+  if (typeof timer.unref === 'function') timer.unref()
+  const combined = signal
+    ? AbortSignal.any([signal, connectCtrl.signal])
+    : connectCtrl.signal
+
+  try {
+    return await fetch(`${String(baseUrl).replace(/\/+$/, '')}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+        Accept: 'text/event-stream, application/json',
+        'User-Agent': USER_AGENT,
+        ...extraHeaders,
+      },
+      body: JSON.stringify(body),
+      signal: combined,
+      keepalive: true,
+    })
+  } catch (error) {
+    if (timedOut) {
+      const timeoutError = new Error(`Upstream connect timeout after ${connectTimeoutMs}ms`)
+      timeoutError.code = 'CONNECT_TIMEOUT'
+      timeoutError.cause = error
+      throw timeoutError
+    }
+    throw error
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Parse one SSE block's `data:` payload.
+ * @param {string} raw
+ * @returns {Record<string, unknown> | { done: true } | { raw: string } | undefined}
+ */
+function parseSseBlock(raw) {
+  const lines = String(raw || '').replace(/\r\n/g, '\n').split('\n')
+  const dataLines = []
+  for (const line of lines) {
+    if (!line.startsWith('data:')) continue
+    dataLines.push(line.slice(5).replace(/^ /, ''))
+  }
+  if (dataLines.length === 0) return undefined
+  const data = dataLines.join('\n').trim()
+  if (data === '') return undefined
+  if (data === '[DONE]') return { done: true }
+  try {
+    return JSON.parse(data)
+  } catch {
+    return { raw: data }
+  }
+}
+
+/**
+ * Read SSE events from an OpenAI-compatible response as parsed objects.
+ *
+ * Yields `{ done: true }` for `[DONE]`, parsed JSON objects otherwise, and
+ * `{ raw }` for unrecognized non-JSON payloads. Throws an abort-shaped error
+ * when the caller signal aborts, and a `STREAM_IDLE_TIMEOUT` error when no
+ * bytes arrive for `idleTimeoutMs`.
+ *
+ * @param {Response} response
+ * @param {{ signal?: AbortSignal, idleTimeoutMs?: number }} [options]
+ * @returns {AsyncGenerator<Record<string, unknown> | { done: true } | { raw: string }>}
+ */
+export async function* readSseEvents(response, {
+  signal,
+  idleTimeoutMs = DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+} = {}) {
+  if (!response?.body) return
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder('utf8')
+  let buffer = ''
+
+  async function readWithIdle() {
+    let timer = null
+    try {
+      return await Promise.race([
+        reader.read(),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => {
+            const error = new Error(`Stream idle timeout after ${idleTimeoutMs}ms`)
+            error.code = 'STREAM_IDLE_TIMEOUT'
+            reject(error)
+          }, Math.max(1, Number(idleTimeoutMs) || DEFAULT_STREAM_IDLE_TIMEOUT_MS))
+          if (typeof timer.unref === 'function') timer.unref()
+        }),
+      ])
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
+  try {
+    while (true) {
+      if (signal?.aborted) {
+        try { await reader.cancel('aborted') } catch {}
+        throw abortError()
+      }
+      const { done, value } = await readWithIdle()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      buffer = buffer.replace(/\r\n/g, '\n')
+      let boundary = buffer.indexOf('\n\n')
+      while (boundary >= 0) {
+        const block = buffer.slice(0, boundary)
+        buffer = buffer.slice(boundary + 2)
+        const parsed = parseSseBlock(block)
+        if (parsed !== undefined) yield parsed
+        boundary = buffer.indexOf('\n\n')
+      }
+    }
+    buffer += decoder.decode()
+    const tail = parseSseBlock(buffer)
+    if (tail !== undefined) yield tail
+  } catch (error) {
+    try { await reader.cancel(error?.message || 'stream error') } catch {}
+    if (signal?.aborted) throw abortError()
+    throw error
+  } finally {
+    try { reader.releaseLock() } catch {}
+  }
+}

package/lib/tui-settings.js

@@ -0,0 +1,158 @@
+/**
+ * dsh-TUI settings section.
+ *
+ * The TUI owns its settings screen and only accepts declarations. The API key
+ * is a secret field written through the credentials seam; every other field is
+ * a normal settings path in the `dsh-clinebot` namespace.
+ */
+
+import { publicConfig } from './config.js'
+import { DEFAULT_API_KEY_ENV } from './credential-refs.js'
+
+function boolFormat(value) {
+  return value === false ? 'false' : 'true'
+}
+
+function boolParse(text) {
+  return { kind: 'set', value: String(text).trim() === 'true' }
+}
+
+/**
+ * Build the section descriptor from live configuration.
+ * @param {{ live: () => Record<string, unknown> }} deps
+ */
+export function buildTuiSection({ live }) {
+  const pub = publicConfig(live())
+  const apiKeyRef = pub.apiKeyEnv || DEFAULT_API_KEY_ENV
+  const accounts = Array.isArray(pub.accounts) ? pub.accounts : []
+  const fields = [
+    {
+      path: ['apiKey'],
+      group: 'connection',
+      kind: 'text',
+      label: 'API key',
+      secret: { ref: apiKeyRef },
+      hint: `Stored in the credential store as ${apiKeyRef}, never in configuration files.`,
+    },
+    {
+      path: ['baseUrl'],
+      group: 'connection',
+      kind: 'text',
+      label: 'API base',
+      placeholder: 'https://api.cline.bot/api/v1',
+      format: (value) => String(value || ''),
+      parse: (text) => {
+        const value = String(text).trim()
+        return value === '' ? { kind: 'clear' } : { kind: 'set', value }
+      },
+    },
+    {
+      path: ['filterModelsByPlan'],
+      group: 'models',
+      kind: 'boolean',
+      label: 'Hide out-of-plan models',
+      hint: 'Fails open when the plan cannot be resolved.',
+      format: boolFormat,
+      parse: boolParse,
+    },
+    {
+      path: ['webSearch'],
+      group: 'models',
+      kind: 'boolean',
+      label: 'Serve web search with ClineBot',
+      format: boolFormat,
+      parse: boolParse,
+    },
+    {
+      path: ['showSidebarQuota'],
+      group: 'models',
+      kind: 'boolean',
+      label: 'Show sidebar quota card',
+      format: boolFormat,
+      parse: boolParse,
+    },
+    {
+      path: ['activeAccount'],
+      group: 'advanced',
+      kind: 'text',
+      label: 'Active account',
+      hint: 'An account id, or auto to follow the rotation order.',
+      options: [
+        { value: 'auto', label: 'Automatic (rotation order)' },
+        ...accounts.map((account) => ({
+          value: String(account.apiKeyEnv || ''),
+          label: String(account.label || account.apiKeyEnv || ''),
+        })).filter((option) => option.value !== ''),
+      ],
+      format: (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : 'auto'),
+      parse: (text) => {
+        const value = String(text).trim()
+        return value === '' || value === 'auto' ? { kind: 'clear' } : { kind: 'set', value }
+      },
+    },
+    {
+      path: ['contextWindow'],
+      group: 'advanced',
+      kind: 'number',
+      label: 'Global context window',
+      hint: '0 follows the catalog; per-model overrides win.',
+      format: (value) => (Number(value) > 0 ? String(Number(value)) : ''),
+      parse: (text) => {
+        const value = Number(text)
+        return Number.isFinite(value) && value > 0 ? { kind: 'set', value: Math.trunc(value) } : { kind: 'clear' }
+      },
+    },
+    {
+      path: ['maxOutputTokens'],
+      group: 'advanced',
+      kind: 'number',
+      label: 'Output cap (-1 derived, 0 omit)',
+      hint: 'A positive value tightens the model output cap; 0 sends no max_tokens.',
+      format: (value) => String(Number.isFinite(Number(value)) ? Number(value) : -1),
+      parse: (text) => {
+        const value = Number(text)
+        return Number.isInteger(value) && value >= -1 ? { kind: 'set', value } : undefined
+      },
+    },
+  ]
+
+  return {
+    ns: 'dsh-clinebot',
+    title: 'ClineBot',
+    descriptions: { en: 'ClineBot (ClinePass) connection and model controls.', zh: 'ClineBot（ClinePass）连接与模型设置。' },
+    groups: [
+      { id: 'connection', title: 'Connection', descriptions: { zh: '连接' } },
+      { id: 'models', title: 'Models', descriptions: { zh: '模型' } },
+      { id: 'advanced', title: 'Advanced', descriptions: { zh: '高级' } },
+    ],
+    fields,
+  }
+}
+
+/**
+ * Register the TUI section when the host provides the seam.
+ * @param {object} ctx
+ * @param {{ live: () => Record<string, unknown> }} deps
+ */
+export function applyTuiSettings(ctx, { live }) {
+  if (typeof ctx?.inject !== 'function') return
+  ctx.inject(['tuiSettingsSections'], (tuiCtx) => {
+    let service
+    try {
+      service = tuiCtx?.tuiSettingsSections || tuiCtx?.get?.('tuiSettingsSections')
+    } catch {
+      service = undefined
+    }
+    if (!service || typeof service.register !== 'function') return
+    try {
+      const dispose = service.register(buildTuiSection({ live }))
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(() => () => {
+          try { dispose() } catch {}
+        }, 'dsh-clinebot: tui settings')
+      }
+    } catch (error) {
+      ctx?.logger?.warn?.('[dsh-clinebot] Could not register TUI settings: ' + (error?.message || error))
+    }
+  })
+}

package/package.json

@@ -1,77 +1,113 @@
-{
-  "name": "@goodandready/dsh-clinebot",
-  "version": "0.5.33",
-  "description": "DeepSeek Harness companion for ClineBot / ClinePass: dynamic subscription models sync, quota exhaustion warnings, session metrics, dedicated settings page, live usage limits, and /cline slash-command.",
-  "license": "MIT",
-  "type": "module",
-  "main": "./lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./client": "./lib/client.js",
-    "./package.json": "./package.json",
-    "./cordis.patch.yml": "./cordis.patch.yml"
-  },
-  "files": [
-    "lib/",
-    "cordis.patch.yml",
-    "README.md",
-    "README.ru.md",
-    "README.zh.md",
-    "CHANGELOG.md",
-    "LICENSE",
-    "media/visual-verification.png"
-  ],
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek-harness",
-    "cline",
-    "clinebot",
-    "clinepass",
-    "openai-compatible",
-    "llm-provider",
-    "usage-dashboard",
-    "quota-limits"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/GooDAnDReaDY/dsh-clinebot.git"
-  },
-  "scripts": {
-    "build:client": "node scripts/build-client.js",
-    "test": "node scripts/build-client.js && node --import ./test/_setup.mjs --test test/*.test.js"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-ui-slots",
-        "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-settings"
-      ]
-    }
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-credentials": "^0.1.7-rc.2 || ^0.2.0-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2 || ^0.2.0-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
-  "devDependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "eslint": "^9.39.5"
-  },
-  "homepage": "https://github.com/GooDAnDReaDY/dsh-clinebot#readme",
-  "bugs": {
-    "url": "https://github.com/GooDAnDReaDY/dsh-clinebot/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@goodandready/dsh-clinebot",
+  "version": "0.6.0",
+  "description": "DeepSeek Harness companion for ClineBot / ClinePass: dynamic subscription models sync, quota exhaustion warnings, session metrics, dedicated settings page, live usage limits, and /cline slash-command.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "README.md",
+    "README.ru.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "media/visual-verification.png"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cline",
+    "clinebot",
+    "clinepass",
+    "openai-compatible",
+    "llm-provider",
+    "usage-dashboard",
+    "quota-limits"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GooDAnDReaDY/dsh-clinebot.git"
+  },
+  "scripts": {
+    "build:client": "node scripts/build-client.js",
+    "test": "node scripts/build-client.js && node --import ./test/_setup.mjs --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=22",
+    "dsh": "0.2.1-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": "0.2.1-rc.2",
+      "dshReleases": {
+        "0.2.1-rc.2": "compatible"
+      }
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-attachment": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-commands": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-credentials": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-web": "0.2.1-rc.2",
+    "@deepseek-ai/schemastery": "~3.18.5",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-attachment": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-commands": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-web": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-attachment": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-brand": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepseek-ai/schemastery": "~3.18.5",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.39.5",
+    "typescript": "^6.0.3"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-clinebot#readme",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-clinebot/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}