dsh-cline-pass 0.1.0 → 0.2.0

package/README.en.md

@@ -27,7 +27,7 @@ You can also install a local directory or tarball:
 
 ```bash
 dsh plugin --profile web add /path/to/dsh-cline-pass
-dsh plugin --profile web add ./dsh-cline-pass-0.1.0.tgz
+dsh plugin --profile web add ./dsh-cline-pass-<version>.tgz
 ```
 
 Restart dsh after installation.

package/README.md

@@ -27,7 +27,7 @@ dsh plugin --profile web add dsh-cline-pass
 
 ```bash
 dsh plugin --profile web add /path/to/dsh-cline-pass
-dsh plugin --profile web add ./dsh-cline-pass-0.1.0.tgz
+dsh plugin --profile web add ./dsh-cline-pass-<version>.tgz
 ```
 
 安装后重启 dsh。
@@ -119,6 +119,10 @@ npm run test:live:reasoning
 
 上游渠道和故障转移行为参考了 MIT 许可的 [`cline-pass-switcher`](https://github.com/munmunjaklin458-afk/cline-pass-switcher)。
 
+## 友情链接
+
+[LinuxDo](https://linux.do/) — 真诚、友善、团结、专业，你的品质开源与技术社区
+
 ## License
 
 [MIT](LICENSE)

package/lib/adapter.js

@@ -30,6 +30,8 @@ import {
   errorText,
   injectPrefs,
   parseRouting,
+  pinAdherence,
+  pinWarnings,
   unwrapEnvelope,
 } from './protocol.js'
 import { parseServerSentEvents } from './engine.js'
@@ -56,6 +58,84 @@ export const DEFAULT_MAX_TOKENS = 32000
  * cap. These match the values the shipped adapters use.
  */
 export const DEFAULT_REQUEST_IMAGE_POLICY = { maxPixels: 4194304, maxBytes: 1048576 }
+/**
+ * Lead-in text for the user message that carries images recovered from tool
+ * results, matching the wording the shipped DeepSeek adapter uses.
+ */
+const TOOL_RESULT_IMAGE_TEXT = 'Attached image(s) from tool result:'
+
+/**
+ * Compute aspect-preserving integer dimensions within a total-pixel budget.
+ *
+ * Local copy of the harness's own projection: it is pure geometry, and this
+ * adapter must not add a hard dependency on `@deepseek-ai/dsh-attachment` for
+ * one helper. Mirrors `requestImageDimensions`, including the inward rounding
+ * and the "never enlarge a small image" rule.
+ *
+ * @param width - positive source width.
+ * @param height - positive source height.
+ * @param maxPixels - positive width-times-height cap.
+ * @returns projected dimensions.
+ */
+export function projectImageDimensions(width, height, maxPixels) {
+  const safeWidth = Number.isSafeInteger(width) && width > 0 ? width : 1
+  const safeHeight = Number.isSafeInteger(height) && height > 0 ? height : 1
+  const safeBudget = Number.isSafeInteger(maxPixels) && maxPixels > 0 ? maxPixels : DEFAULT_REQUEST_IMAGE_POLICY.maxPixels
+  const scale = Math.min(1, Math.sqrt(safeBudget / (safeWidth * safeHeight)))
+  if (scale === 1) return { width: safeWidth, height: safeHeight }
+  if (safeWidth >= safeHeight) {
+    let projectedWidth = Math.max(1, Math.floor(safeWidth * scale))
+    let projectedHeight = Math.max(1, Math.round((projectedWidth * safeHeight) / safeWidth))
+    while (projectedWidth * projectedHeight > safeBudget && projectedWidth > 1) {
+      projectedWidth -= 1
+      projectedHeight = Math.max(1, Math.round((projectedWidth * safeHeight) / safeWidth))
+    }
+    return { width: projectedWidth, height: projectedHeight }
+  }
+  let projectedHeight = Math.max(1, Math.floor(safeHeight * scale))
+  let projectedWidth = Math.max(1, Math.round((projectedHeight * safeWidth) / safeHeight))
+  while (projectedWidth * projectedHeight > safeBudget && projectedHeight > 1) {
+    projectedHeight -= 1
+    projectedWidth = Math.max(1, Math.round((projectedHeight * safeWidth) / safeHeight))
+  }
+  return { width: projectedWidth, height: projectedHeight }
+}
+
+/**
+ * Build the target object one attachment must be materialized at.
+ *
+ * The harness changed this contract between releases and the two shapes are
+ * mutually exclusive, not additive:
+ *
+ * - 0.1.2 - 0.1.5 validate `{maxPixels, maxBytes}` and project the dimensions
+ *   themselves;
+ * - 0.1.6+ validate `{width, height, maxBytes}` and take the dimensions as
+ *   given.
+ *
+ * A caller that sends only one shape fails on the other host — the newer one
+ * rejects a missing `width` with `Image request width must be a positive
+ * integer.`, which surfaces to the user as a failed turn on every image. Each
+ * validator reads only the fields it knows and ignores the rest, so one target
+ * carrying both the projected dimensions and the pixel budget satisfies either
+ * host. The dimensions are projected here with the same geometry the older
+ * host would have applied, so the rendered result is identical on both.
+ *
+ * @param ref - the durable attachment reference, which carries its own size.
+ * @param policy - the configured pixel and byte budget.
+ * @returns the request target for `readImageRequest`.
+ * @throws {LlmError} UNSUPPORTED_CONTENT when the reference carries no usable size.
+ */
+export function requestImageTarget(ref, policy) {
+  const maxPixels = policy?.maxPixels ?? DEFAULT_REQUEST_IMAGE_POLICY.maxPixels
+  const maxBytes = policy?.maxBytes ?? DEFAULT_REQUEST_IMAGE_POLICY.maxBytes
+  const width = ref?.width
+  const height = ref?.height
+  if (!Number.isSafeInteger(width) || width <= 0 || !Number.isSafeInteger(height) || height <= 0) {
+    throw new LlmError('The Cline Pass adapter received an image reference without usable dimensions.', 'UNSUPPORTED_CONTENT')
+  }
+  const projected = projectImageDimensions(width, height, maxPixels)
+  return { width: projected.width, height: projected.height, maxPixels, maxBytes }
+}
 
 const STREAM_IDLE_TIMEOUT_CODE = 'CLINE_PASS_STREAM_IDLE_TIMEOUT'
 
@@ -107,7 +187,7 @@ export async function prepareRequestImages(messages, attachments, policy, signal
     throw new LlmError('The Cline Pass adapter needs the durable attachment service to send image input.', 'UNSUPPORTED_CONTENT')
   }
   const ordered = [...refs.values()]
-  const prepared = await Promise.all(ordered.map((ref) => attachments.readImageRequest(ref, policy, signal)))
+  const prepared = await Promise.all(ordered.map((ref) => attachments.readImageRequest(ref, requestImageTarget(ref, policy), signal)))
   const versions = new Map()
   for (const [index, ref] of ordered.entries()) versions.set(ref.attachmentId, prepared[index])
   return versions
@@ -135,21 +215,55 @@ function serializeAssistant(message) {
   }
 }
 
+/**
+ * Resolve one image block into its OpenAI wire part.
+ *
+ * @throws {LlmError} UNSUPPORTED_CONTENT when its request bytes were not prepared.
+ */
+function imagePart(block, images) {
+  const version = images?.get(block.attachment?.attachmentId)
+  if (version === undefined) {
+    throw new LlmError('The Cline Pass adapter received an image it could not resolve into request bytes.', 'UNSUPPORTED_CONTENT')
+  }
+  return { type: 'image_url', image_url: { url: `data:${version.mediaType};base64,${toBase64(version.data)}` } }
+}
+
+/** Recursively collect image parts from blocks, including nested tool results. */
+function collectImageParts(blocks, images, target = []) {
+  for (const block of blocks ?? []) {
+    if (block.type === 'image') target.push(imagePart(block, images))
+    else if (block.type === 'tool-result') collectImageParts(block.content, images, target)
+  }
+  return target
+}
+
 /**
  * Convert the harness conversation to wire messages.
  *
  * Tool results become standalone `{ role: 'tool' }` messages. A user message
  * carrying an image switches to the OpenAI content-part array; a text-only one
  * keeps the plain-string form.
+ *
+ * An image nested in a tool result (read_image, a screenshot tool) has no
+ * OpenAI `tool` wire spelling, so it rides a following user message instead —
+ * the same shape the shipped adapters use.
  */
 function serializeMessages(messages, images) {
   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 = []
+  }
   for (const message of messages) {
     if (message.role === 'system') {
+      flushToolImages()
       wire.push({ role: 'system', content: flattenText(message.content) })
       continue
     }
     if (message.role === 'assistant') {
+      flushToolImages()
       wire.push(serializeAssistant(message))
       continue
     }
@@ -157,26 +271,24 @@ function serializeMessages(messages, images) {
     const parts = []
     for (const block of message.content ?? []) {
       if (block.type === 'text' && block.text.length > 0) parts.push({ type: 'text', text: block.text })
-      else if (block.type === 'image') {
-        const version = images?.get(block.attachment?.attachmentId)
-        if (version === undefined) {
-          throw new LlmError('The Cline Pass adapter received an image it could not resolve into request bytes.', 'UNSUPPORTED_CONTENT')
-        }
-        parts.push({ type: 'image_url', image_url: { url: `data:${version.mediaType};base64,${toBase64(version.data)}` } })
-      }
+      else if (block.type === 'image') parts.push(imagePart(block, images))
     }
     const hasImage = parts.some((part) => part.type === 'image_url')
     const text = parts.filter((part) => part.type === 'text').map((part) => part.text).join('')
-    if (hasImage) wire.push({ role: 'user', content: parts })
-    else if (text.length > 0 || toolResults.length === 0) wire.push({ role: 'user', content: text })
+    if (hasImage || text.length > 0 || toolResults.length === 0) {
+      flushToolImages()
+      wire.push({ role: 'user', content: hasImage ? parts : text })
+    }
     for (const result of toolResults) {
       wire.push({
         role: 'tool',
         tool_call_id: result.toolCallId,
         content: flattenText(result.content) || '(no output)',
       })
+      collectImageParts(result.content, images, pendingToolImages)
     }
   }
+  flushToolImages()
   return wire
 }
 
@@ -303,6 +415,31 @@ export function streamErrorCode(message, status) {
   return 'UPSTREAM'
 }
 
+/**
+ * Note the moment the first byte of a response body arrives.
+ *
+ * A pass-through stream: it reports once, on the first chunk, and forwards every
+ * chunk unchanged. A keep-alive comment or an early frame reaches this before it
+ * reaches the SSE parser, so the recorded moment is the gateway's first sign of
+ * life rather than the caller's first content.
+ *
+ * @param body - the response body stream.
+ * @param onFirst - called once, when the first chunk is seen.
+ * @returns a stream equivalent to `body`.
+ */
+function tapFirstByte(body, onFirst) {
+  let seen = false
+  return body.pipeThrough(new TransformStream({
+    transform(chunk, controller) {
+      if (!seen) {
+        seen = true
+        onFirst()
+      }
+      controller.enqueue(chunk)
+    },
+  }))
+}
+
 /**
  * Translate decoded SSE payloads into harness stream chunks.
  *
@@ -444,11 +581,15 @@ export class ClinePassAdapter extends LlmAdapter {
     const configured = connection.models.find((entry) => entry.id === model)
     const discovered = this.config.discoveredContext?.(model)
     const override = configured ?? { id: model }
+    // What the last official scan published about this model. Without it a model
+    // newer than this release resolves to the `text` fallback and the harness
+    // refuses every image for it, silently.
+    const published = this.config.publishedModel?.(model) ?? {}
     const resolved = resolveModelMetadata(provider, model, override, {
       contextWindow: discovered ?? connection.defaultContextWindow,
       maxTokens: connection.maxTokens,
       reasoning: connection.reasoningModels !== false,
-    })
+    }, published)
     // A probe that saw this model's real endpoints overrides the published
     // window: it is measured, not documented.
     return Promise.resolve(discovered === undefined
@@ -494,8 +635,38 @@ export class ClinePassAdapter extends LlmAdapter {
     const trace = []
     let delivered = false
     let lastError = null
+    /**
+     * When the caller saw its first chunk, in ms from the request's own start.
+     *
+     * Measured from `startedAt` rather than from the serving attempt so it can be
+     * read next to `ms`, which is also request-scoped: a failover attempt's dead
+     * time is part of what the user actually waited through. Zero means no chunk
+     * ever arrived, which is a fact worth keeping rather than a missing value.
+     */
+    let firstChunkMs = 0
+    /**
+     * When the gateway's first byte arrived, in ms from the request's own start.
+     *
+     * `ttft` answers "when did the caller see something"; this answers "when did
+     * the gateway start talking at all". The pair separates two very different
+     * stalls: a gateway that accepted the request and then sent nothing (both
+     * late) from one that keeps the socket warm while the model thinks — a
+     * keep-alive comment or an early frame produces bytes without producing a
+     * chunk, and only having both tells those apart.
+     */
+    let firstByteMs = 0
+    /**
+     * Accounts this request has already been refused by.
+     *
+     * The pool is offered as one account with a combined quota, so a refusal that
+     * is about the ACCOUNT — a spent window, a revoked key — moves to the next
+     * one instead of ending the request. `resolveAccount` answers `undefined` once
+     * nothing is left, which is when the real error is raised below.
+     */
+    const refused = new Set()
     for (const attempt of attempts) {
-      const account = await this.config.resolveAccount()
+      const account = await this.config.resolveAccount({ exclude: [...refused] })
+      if (account === undefined) break
       const body = injectPrefs(buildRequestBody(options, connection, images), meta, attempt)
       const attemptStarted = Date.now()
       const consumer = new AbortController()
@@ -534,9 +705,22 @@ export class ClinePassAdapter extends LlmAdapter {
           trace.push({ upstream: attempt.upstream ?? '(auto)', status: response.status, ms, note: detail.slice(0, 160) })
           this.config.learnUpstream(options.model, attempt.upstream, classifyUpstreamError(detail), detail, ms)
           lastError = new LlmError(`${detail || `HTTP ${response.status}`} [model=${options.model}]`, streamErrorCode(detail, response.status), { status: response.status })
-          // A rejected pin or a busy upstream is worth another candidate; an
-          // auth failure is not, so it is raised immediately.
-          if (lastError.code === 'AUTH' || lastError.code === QUOTA_EXCEEDED_CODE) throw lastError
+          // A rejected pin or a busy upstream is worth another candidate. An
+          // account-level refusal is worth another ACCOUNT: that is the whole
+          // point of a pool, and with one account the next attempt simply finds
+          // nothing left and this error is raised unchanged.
+          if (lastError.code === 'AUTH' || lastError.code === QUOTA_EXCEEDED_CODE) {
+            refused.add(account.name)
+            this.config.record(options.model, {
+              provider: null,
+              attempts: trace.map((row) => row.upstream),
+              ms: Date.now() - startedAt,
+              stream: true,
+              error: firstLine(lastError.message, 200),
+              code: lastError.code,
+              account: account.name,
+            })
+          }
           continue
         }
         if (response.body === null || response.body === undefined) {
@@ -545,11 +729,28 @@ export class ClinePassAdapter extends LlmAdapter {
         }
         let yielded = false
         const observed = { provider: null, canonical: null, pipeline: null }
-        const iterator = translate(tapRouting(parseServerSentEvents(response.body), observed))[Symbol.asyncIterator]()
+        // `body` in this scope is the request payload, so the response stream
+        // gets its own name.
+        const responseBody = tapFirstByte(response.body, () => {
+          if (firstByteMs === 0) firstByteMs = Date.now() - startedAt
+        })
+        const iterator = translate(tapRouting(parseServerSentEvents(responseBody), observed))[Symbol.asyncIterator]()
+        /**
+         * The usage frame, captured as it passes through.
+         *
+         * The gateway sends it in the last frames, after the content, so a record
+         * written when the stream ends has it — but only if the chunk was read on
+         * its way to the caller. `reasoningTokens` in particular is the number
+         * that explains a large time-to-first-chunk: it is thinking the caller
+         * cannot see, because this gateway does not stream it.
+         */
+        let usage = null
         try {
           for (;;) {
             const next = await watchdog.next(iterator)
             if (next.done === true) break
+            if (next.value?.type === 'usage') usage = next.value.usage
+            if (firstChunkMs === 0) firstChunkMs = Date.now() - startedAt
             yielded = true
             yield next.value
           }
@@ -562,21 +763,41 @@ export class ClinePassAdapter extends LlmAdapter {
           const ms = Date.now() - attemptStarted
           trace.push({ upstream: attempt.upstream ?? '(auto)', status: 200, ms, note: note.slice(0, 160) })
           this.config.learnUpstream(options.model, attempt.upstream, classifyUpstreamError(note), note, ms)
-          // Content already reached the caller: this is the answer's failure,
-          // not a reason to silently ask another channel. A missing account is
-          // fatal for the same reason — every candidate would fail the same way.
-          if (yielded || error?.code === 'AUTH' || error?.code === QUOTA_EXCEEDED_CODE) {
+          // Content already reached the caller: this is the answer's failure, and
+          // no retry can un-deliver it. Before any content, an account-level
+          // refusal (a spent window, a revoked key) moves to the next account —
+          // the pool exists to absorb exactly that.
+          const code = error instanceof LlmError ? error.code : 'TRANSPORT'
+          if (yielded) {
             this.config.record(options.model, {
               provider: observed.provider,
               canonical: observed.canonical,
               attempts: trace.map((row) => row.upstream),
               ms: Date.now() - startedAt,
+              ttfb: firstByteMs,
+              ttft: firstChunkMs,
               stream: true,
               error: note.slice(0, 200),
+              code,
               account: account.name,
             })
             throw error instanceof LlmError ? error : new LlmError(note, 'TRANSPORT', { cause: error })
           }
+          if (code === 'AUTH' || code === QUOTA_EXCEEDED_CODE) {
+            refused.add(account.name)
+            this.config.record(options.model, {
+              provider: observed.provider,
+              canonical: observed.canonical,
+              attempts: trace.map((row) => row.upstream),
+              ms: Date.now() - startedAt,
+              ttfb: firstByteMs,
+              ttft: firstChunkMs,
+              stream: true,
+              error: note.slice(0, 200),
+              code,
+              account: account.name,
+            })
+          }
           lastError = error instanceof LlmError ? error : new LlmError(note, 'TRANSPORT', { cause: error })
           continue
         } finally {
@@ -588,17 +809,42 @@ export class ClinePassAdapter extends LlmAdapter {
           }
         }
         delivered = true
-        trace.push({ upstream: attempt.upstream ?? '(auto)', status: 200, ms: Date.now() - attemptStarted, note: 'ok' })
+        // Which channel answered is read back from the stream, because a 200
+        // only proves someone answered. The router drops an unusable `only`
+        // without complaining, so "we asked for baseten" and "baseten served it"
+        // are different facts and only the second one is evidence.
+        const adherence = pinAdherence(attempt, { finalProvider: observed.provider })
+        const warnings = pinWarnings(attempt, meta)
+        trace.push({
+          upstream: attempt.upstream ?? '(auto)',
+          status: 200,
+          ms: Date.now() - attemptStarted,
+          note: adherence === 'not-adopted' || adherence === 'violated'
+            ? `pin not adopted: served by ${observed.provider ?? '(unknown)'}`
+            : 'ok',
+        })
         this.config.record(options.model, {
           provider: observed.provider ?? (attempt.upstream ?? null),
           canonical: observed.canonical,
           attempts: trace.map((row) => row.upstream),
           ms: Date.now() - startedAt,
+          ttfb: firstByteMs,
+          ttft: firstChunkMs,
           stream: true,
           error: null,
           account: account.name,
+          adherence,
+          warnings,
+          // What the request cost in tokens, and how much of that the model spent
+          // thinking invisibly — the two numbers that explain a large `ttft`.
+          usage,
+          effort: options.reasoningEffort ?? '',
         })
-        if (attempt.upstream !== null) this.config.learnUpstream(options.model, attempt.upstream, 'ok', '', Date.now() - attemptStarted)
+        // Only a pin the router actually honored proves the channel works.
+        // Marking it usable no matter who answered is how a false "available"
+        // reached the verdict map the exclusion allow-list is built from — the
+        // map then vouched for the very channels it was meant to exclude.
+        if (attempt.upstream !== null && adherence === 'adopted') this.config.learnUpstream(options.model, attempt.upstream, 'ok', '', Date.now() - attemptStarted)
         return
       } finally {
         watchdog[Symbol.dispose]()
@@ -610,6 +856,8 @@ export class ClinePassAdapter extends LlmAdapter {
         provider: null,
         attempts: trace.map((row) => row.upstream),
         ms: Date.now() - startedAt,
+        ttfb: firstByteMs,
+        ttft: firstChunkMs,
         stream: true,
         error: message.slice(0, 200),
         account: null,

package/lib/catalog.js

@@ -168,17 +168,25 @@ const SEAM_MODALITIES = new Set(['text', 'image'])
 /**
  * Resolve the metadata seam fields for one model.
  *
- * Precedence per field: the configured override, then the published catalog,
- * then the route-wide fallback.
+ * Precedence per field: the configured override, then the shipped catalog, then
+ * what the last official scan published, then the route-wide fallback.
  *
+ * The live scan sits below the shipped table rather than above it because the
+ * shipped entry is curated: models.dev reports `audio`/`video`/`pdf`, and the
+ * underscore-free spelling of a display name, neither of which the seam or the
+ * provider's own label wants. It exists to cover what the table cannot know —
+ * a model published after this release — so a multimodal model is never adopted
+ * as text-only just because it is new.
+ *
+ * @param discovered - metadata for this model from the last catalog scan.
  * @returns a descriptor the seam's `normalizeModelInfo` accepts.
  */
-export function resolveModelMetadata(provider, model, override, fallback) {
-  const published = catalogEntry(model) ?? {}
+export function resolveModelMetadata(provider, model, override, fallback, discovered = {}) {
+  const published = { ...(discovered ?? {}), ...(catalogEntry(model) ?? {}) }
   const name = pick(override?.name, published.name, model)
   const contextWindow = pick(override?.contextWindow, published.contextWindow, fallback.contextWindow)
   const maxTokens = pick(override?.maxTokens, published.maxTokens, fallback.maxTokens)
-  const modality = pick(override?.input, published.input, undefined)
+  const modality = pick(override?.input, published.input ?? published.inputModalities, undefined)
   const reasoning = override?.reasoning ?? published.reasoning ?? fallback.reasoning
   const offered = (modality ?? ['text']).filter((entry) => SEAM_MODALITIES.has(entry))
   return {