@mars-sea/dsh-commandcode-provider 0.11.1 → 0.11.3

package/lib/index.js

@@ -2,7 +2,8 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
-import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmAdapter, LlmError, ReasoningEffortId, ToolCallId, assertUsableApiKey, attributionHeaders, errorChain, isContextWindowExceededError, offloadRequestImagesWithPolicy, offloadedImageText, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import * as dshLlm from "@deepseek-ai/dsh-llm";
+import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmAdapter, LlmError, ReasoningEffortId, ToolCallId, assertUsableApiKey, attributionHeaders, errorChain, isContextWindowExceededError, offloadedImageText, resolveRetryPolicy, textOnlyImageText } from "@deepseek-ai/dsh-llm";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import { existsSync, readFileSync } from "node:fs";
@@ -385,6 +386,48 @@ const KNOWN_THINKING_MODELS = /* @__PURE__ */ new Set([
 	"inclusionai/ling-3.0-flash-sante:free"
 ]);
 /**
+* Catalog models the Provider API serves ONLY through `/provider/v1/messages`
+* (Anthropic Messages shape). Every other model in the catalog answers on
+* `/provider/v1/chat/completions`; these reject it outright with HTTP 400
+* `Model "<id>" must be called via /provider/v1/messages (Anthropic Messages
+* shape)`.
+*
+* Measured 2026-09-16 against the live catalog (command-code@1.54.0): all 69
+* models were posted to `/provider/v1/chat/completions`; exactly these eight
+* — the whole Claude family — refused, and every one of them is routed
+* normally by `/alpha/generate` (a lower-plan key gets the ordinary
+* `MODEL_NOT_IN_PLAN` 403 there, never a routing error). So the CLI transport
+* is a complete fallback and the adapter does not need a Messages transport.
+*
+* Note what this list is NOT: it is not a plan gate. `claude-sonnet-5` is
+* Pro-tier and `claude-opus-4-8` Provider-tier, so the accounts entitled to
+* these models are exactly the non-Go ones, which `resolveProtocol()` sends to
+* the Provider API by default — picking any Claude model there failed every
+* request before this snapshot existed.
+*
+* Keep in sync when models ship (see the dsh-commandcode-upstream skill).
+* `requiresMessagesEndpoint()` additionally treats any `claude-*` id as
+* Messages-only, so a Claude model added upstream is routed correctly by an
+* un-updated plugin instead of hard-failing with the 400 above; the worst case
+* of that rule going stale the other way (upstream teaching
+* `/provider/v1/chat/completions` to serve Claude) is one model riding the CLI
+* transport it already works on.
+*/
+const MESSAGES_ONLY_MODELS = /* @__PURE__ */ new Set([
+	"claude-sonnet-5",
+	"claude-sonnet-4-6",
+	"claude-fable-5-1",
+	"claude-fable-5",
+	"claude-opus-5",
+	"claude-opus-4-8",
+	"claude-opus-4-7",
+	"claude-haiku-4-5-20251001"
+]);
+/** True when the Provider API will only serve `modelId` via `/provider/v1/messages`. */
+function requiresMessagesEndpoint(modelId) {
+	return MESSAGES_ONLY_MODELS.has(modelId) || modelId.startsWith("claude-");
+}
+/**
 * The minimum subscription plan a model is included in, per the official plan
 * pages (`/docs/plans/go`, `/docs/plans/goat`, `/docs/plans/pro`, `/docs/plans/max`
 * and `/docs/resources/pricing-limits`). Each plan's model list is a superset of
@@ -2072,6 +2115,235 @@ function normalizeResolvedKey(value) {
 	return trimmed === "" ? void 0 : trimmed;
 }
 //#endregion
+//#region src/image-request.ts
+/**
+* Long edge one request image may keep, in pixels.
+*
+* 1568 is Anthropic's documented ceiling — their API downscales anything larger
+* before the model sees it — and it sits inside the high-detail band of the
+* OpenAI and Gemini tile schemes, so no upstream this gateway reaches reads
+* more detail than the target keeps. Screenshots from a Retina display are the
+* case this is for: 2880x1800 becomes 1568x980, a 3.4x pixel cut, and the
+* models lose nothing they would not have downscaled themselves.
+*/
+const REQUEST_IMAGE_MAX_LONG_EDGE = 1568;
+/**
+* Encoded bytes one request image may keep, before base64 expansion. The same
+* 1 MiB budget the harness's own multi-provider adapter defaults to; the
+* attachment service keeps its smallest quality-ladder output when no quality
+* fits, so this bounds bytes without ever refusing an image.
+*/
+const REQUEST_IMAGE_MAX_ENCODED_BYTES = 1048576;
+/**
+* Aspect-preserving projection onto a long-edge budget; never enlarges, and
+* never returns a zero dimension (a 1-px degenerate side is what the round of
+* an extreme aspect ratio can produce, and a 0 would make the encoder refuse).
+*
+* A local restatement of the helper 0.1.6 exports from `dsh-attachment`, which
+* 0.1.2–0.1.5 do not have; the math is the whole contract, so keeping the copy
+* here costs less than a version probe would.
+*/
+function longEdgeDimensions(width, height, longEdge) {
+	if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return {
+		width: Math.max(1, Math.round(width) || 1),
+		height: Math.max(1, Math.round(height) || 1)
+	};
+	if (longEdge >= Math.max(width, height)) return {
+		width,
+		height
+	};
+	return width >= height ? {
+		width: longEdge,
+		height: Math.max(1, Math.round(longEdge * height / width))
+	} : {
+		width: Math.max(1, Math.round(longEdge * width / height)),
+		height: longEdge
+	};
+}
+/**
+* The request target for one normalized attachment: its aspect ratio under the
+* long-edge budget, plus the byte budget every generation honours.
+*
+* The area is computed from the PROJECTED dimensions rather than the source's,
+* so ≤0.1.5's own pixel projection lands on the same geometry instead of
+* re-deriving a slightly different one from the original.
+*/
+function requestImageTarget(ref) {
+	const projected = longEdgeDimensions(ref.width, ref.height, REQUEST_IMAGE_MAX_LONG_EDGE);
+	return {
+		maxPixels: projected.width * projected.height,
+		width: projected.width,
+		height: projected.height,
+		maxBytes: REQUEST_IMAGE_MAX_ENCODED_BYTES
+	};
+}
+//#endregion
+//#region src/image-tokens.ts
+/**
+* Vision-token accounting for the model families Command Code routes to.
+*
+* The harness's token meter prices request images through
+* `LlmAdapter.imageRequestPricing(provider, model).priceImages(blocks)` and,
+* when a route declares nothing, falls back to a structural estimate that
+* charges a handful of tokens for ANY image. On an image-heavy session that is
+* not a rounding error: a screenshot loop can carry dozens of full-size images
+* that the heuristic prices at ~0 tokens each, so context pressure is
+* under-reported and the session walks into its own context window.
+*
+* This route is a gateway in front of many upstreams — one catalog id per model,
+* but the visual-token rule belongs to whoever serves it. So the estimate is per
+* FAMILY, using each vendor's published rule, and the families are recognised by
+* the catalog id (which names the vendor). Every formula is stated here rather
+* than imported: the only in-tree implementations live inside the official
+* adapters, and this plugin deliberately does not depend on those protocols.
+*
+* These are ESTIMATES for context accounting, not invoices — the provider's own
+* usage remains authoritative for a completed request, exactly as the published
+* per-token rates the session-cost readout uses are.
+*
+* @module dsh-commandcode-provider/image-tokens
+*/
+/**
+* Which family prices one catalog model id.
+*
+* `generic` is not "we do not know the model" but "we cannot tell its visual
+* rule apart from the known ones" — the Qwen, MiniMax, xAI, moonshot and
+* sakana families all publish patch- or tile-based accounting close to the
+* Anthropic rule, so the conservative fallback below covers them without
+* pretending to more precision than we have.
+*/
+function imageTokenFamily(modelId) {
+	const id = modelId.toLowerCase();
+	const vendor = id.includes("/") ? id.slice(0, id.indexOf("/")) : "";
+	if (id.startsWith("claude")) return "anthropic";
+	if (id.startsWith("gpt") || /^o[1-9]/.test(id)) return "openai";
+	if (vendor === "google" || id.startsWith("gemini")) return "google";
+	if (vendor === "deepseek") return "deepseek";
+	return "generic";
+}
+/**
+* Visual tokens one request image costs on the given family, at the dimensions
+* this route would actually send (see `./image-request.ts`).
+*/
+function imageTokenCost(family, width, height) {
+	switch (family) {
+		case "anthropic": return anthropicImageTokens(width, height);
+		case "openai": return openAiImageTokens(width, height);
+		case "google": return googleImageTokens(width, height);
+		case "deepseek": return deepSeekImageTokens(width, height);
+		default: return genericImageTokens(width, height);
+	}
+}
+/** Convenience for callers that have a model id: family lookup plus the rule. */
+function commandCodeImageTokens(modelId, width, height) {
+	return imageTokenCost(imageTokenFamily(modelId), width, height);
+}
+/**
+* Anthropic: the image is first scaled so its long edge is at most 1568 px
+* (never enlarged), then charged roughly one token per 750 pixels.
+* Source: Anthropic vision documentation, "Image size and token usage".
+*/
+function anthropicImageTokens(width, height) {
+	const projected = longEdgeDimensions(width, height, 1568);
+	return Math.max(1, Math.ceil(projected.width * projected.height / 750));
+}
+/**
+* OpenAI (high detail): scale to fit inside 2048x2048, then scale the shortest
+* side to 768 px, then charge an 85-token base plus 170 tokens per 512x512
+* tile. Source: OpenAI vision documentation, "Calculating costs".
+*/
+function openAiImageTokens(width, height) {
+	let scaled = {
+		width: Math.max(1, width),
+		height: Math.max(1, height)
+	};
+	const longest = Math.max(scaled.width, scaled.height);
+	if (longest > 2048) scaled = scaleBy(scaled, 2048 / longest);
+	const shortest = Math.min(scaled.width, scaled.height);
+	if (shortest > 768) scaled = scaleBy(scaled, 768 / shortest);
+	return 85 + 170 * (Math.ceil(scaled.width / 512) * Math.ceil(scaled.height / 512));
+}
+/**
+* Google Gemini: an image whose both sides are at most 384 px costs a flat 258
+* tokens; anything larger is cropped into 768x768 tiles of 258 tokens each.
+* Source: Gemini image-understanding documentation.
+*/
+function googleImageTokens(width, height) {
+	if (width <= 384 && height <= 384) return 258;
+	return 258 * Math.ceil(width / 768) * Math.ceil(height / 768);
+}
+/** 14-px patches, merged 3x3 into one token cell. */
+const DEEPSEEK_PATCH_SIZE = 14;
+const DEEPSEEK_DOWNSAMPLE_RATIO = 3;
+/** The provider's cap on tokens for one request image. */
+const DEEPSEEK_MAX_IMAGE_TOKENS = 1024;
+/** Total-pixel floor; a smaller image is enlarged before grid projection. */
+const DEEPSEEK_MIN_PIXELS = 295936;
+/**
+* DeepSeek: pad to 14-px patches, merge each 3x3 patch block into one token
+* cell, charge one token per cell plus one separator per row plus two framing
+* tokens, and cap one image at 1024 tokens by downscaling it aspect-preserving
+* (images below 544x544 are enlarged first).
+*
+* Mirrors `deepSeekImageTokens` in the official `dsh-llm-deepseek` adapter
+* (its `PATCH_SIZE`, `DOWNSAMPLE_RATIO`, `MAX_IMAGE_TOKENS` and `MIN_PIXELS`).
+* The official solver picks the largest grid that fits the cap; this restates
+* that as a bounded search over the scale factor, which lands on the same grid
+* without vendoring the closed-form solver.
+*/
+function deepSeekImageTokens(width, height) {
+	let scaled = {
+		width: Math.max(1, width),
+		height: Math.max(1, height)
+	};
+	const pixels = scaled.width * scaled.height;
+	if (pixels < DEEPSEEK_MIN_PIXELS) scaled = scaleBy(scaled, Math.sqrt(DEEPSEEK_MIN_PIXELS / pixels));
+	const direct = deepSeekGridTokens(scaled.width, scaled.height);
+	if (direct <= DEEPSEEK_MAX_IMAGE_TOKENS) return direct;
+	let low = 0;
+	let high = 1;
+	let best = direct;
+	for (let step = 0; step < 24; step += 1) {
+		const mid = (low + high) / 2;
+		const tokens = deepSeekGridTokens(Math.max(1, Math.round(scaled.width * mid)), Math.max(1, Math.round(scaled.height * mid)));
+		if (tokens <= DEEPSEEK_MAX_IMAGE_TOKENS) {
+			low = mid;
+			best = tokens;
+		} else high = mid;
+	}
+	return best;
+}
+/** One token grid's charge: every row carries a separator, plus two framing tokens. */
+function deepSeekGridTokens(width, height) {
+	const cellsWide = cellCount(width);
+	return cellCount(height) * (cellsWide + 1) + 2;
+}
+/** Token cells along one padded pixel axis. */
+function cellCount(length) {
+	const patches = Math.ceil(length / DEEPSEEK_PATCH_SIZE);
+	return Math.ceil(patches / DEEPSEEK_DOWNSAMPLE_RATIO);
+}
+/**
+* The conservative fallback for a family we cannot price exactly: the MOST
+* expensive of the three simple published rules at these dimensions.
+*
+* Chosen deliberately. Under-reporting context is what lets a session walk into
+* its own context window, while over-reporting only makes the meter cautious;
+* for the real families this covers (Qwen's 28-px patches, MiniMax, xAI,
+* moonshot, sakana) the Anthropic rule is the close one, and it is the maximum
+* at every size except the sub-384-px band, where Gemini's flat 258 wins.
+*/
+function genericImageTokens(width, height) {
+	return Math.max(anthropicImageTokens(width, height), openAiImageTokens(width, height), googleImageTokens(width, height));
+}
+/** Scale one dimension pair by a positive factor, rounded to whole pixels. */
+function scaleBy(size, factor) {
+	return {
+		width: Math.max(1, Math.round(size.width * factor)),
+		height: Math.max(1, Math.round(size.height * factor))
+	};
+}
+//#endregion
 //#region src/adapter.ts
 /**
 * DeepSeek Harness LLM adapter for the Command Code Provider API.
@@ -2131,6 +2403,28 @@ function numberValue(value) {
 function booleanValue(value) {
 	return typeof value === "boolean" ? value : void 0;
 }
+/**
+* Thinking text carried by an OpenRouter-shaped `reasoning_details` array
+* (`[{ type: 'reasoning.text', text, format, index }]`), concatenated in the
+* order the gateway sent it.
+*
+* Entries are read by their `text` member alone rather than filtered on
+* `type === 'reasoning.text'`: the sibling shapes in that protocol carry
+* `summary` or an encrypted blob instead of `text`, so a plain read already
+* ignores them, while a type filter would silently drop a text-bearing variant
+* added later — and losing thinking is the failure this exists to prevent.
+* Returns undefined when the array yields nothing, so the caller's `??` chain
+* keeps falling through instead of treating "no text" as a reasoning delta.
+*/
+function reasoningDetailsText(value) {
+	if (!Array.isArray(value)) return void 0;
+	let text = "";
+	for (const entry of value) {
+		if (!isRecord(entry)) continue;
+		text += stringValue(entry.text) ?? "";
+	}
+	return text === "" ? void 0 : text;
+}
 /** Parse a billing-period timestamp (ISO string or millis) into millis; 0 when absent/invalid. */
 function periodEndValue(value) {
 	const asNumber = numberValue(value);
@@ -2410,6 +2704,44 @@ async function writeModelsCache(cachePath, models) {
 	}
 }
 /**
+* Whether an inbound message is a tool RESULT — a `user`-role message the
+* producer tagged with `source: { kind: 'tool' }`.
+*
+* The tag is read defensively because it is PRODUCER-supplied and nothing
+* validates it: dsh-llm's `Message` type declares `source` required, but the
+* runtime never checks it and every adapter shipped before this one ignored the
+* field outright (`dsh-llm-deepseek` never reads it). A third-party plugin that
+* assembles its own history can therefore omit it and run correctly everywhere
+* else — dsh-mneme's memory pipeline did — which made this adapter, the first
+* to actually read the field, the first to crash on such a message with
+* `TypeError: Cannot read properties of undefined (reading 'kind')` in the
+* serialization phase, 0–8 ms in, before any request left the machine and with
+* nothing in the error naming the message or the producer (issue #47).
+*
+* Two rules keep an untagged message from costing the turn:
+*
+*  - A PRESENT tag is authoritative. `kind: 'user'`, `'model'`, `'plugin'` or
+*    any producer-added kind means "not a tool result", whatever the content
+*    looks like — the tag answers *who produced this*.
+*  - An ABSENT tag falls back to the content shape. A `user` message whose
+*    first block is a `tool-result` is a tool result by the harness's own
+*    definition (`ToolResultMessage` is exactly that shape with a
+*    `ToolMessageSource`), and the fallback is not cosmetic: `pairedToolCalls()`
+*    counts a `tool-result` block from ANY message, so classifying such a
+*    message as a plain user message would drop it at emission while its call
+*    still counted as paired — leaving the assistant's tool call unanswered on
+*    the wire, which the gateway rejects outright. FIRST block, not "any block":
+*    the tool-result branch reads `content[0]` and skips anything else, so
+*    claiming a mixed message as a tool result would discard its other blocks
+*    instead of sending them.
+*/
+function isToolResultMessage(message) {
+	if (message.role !== "user") return false;
+	const kind = message.source?.kind;
+	if (kind !== void 0) return kind === "tool";
+	return message.content?.[0]?.type === "tool-result";
+}
+/**
 * Collect the tool calls that have a paired tool result, plus each call's
 * name. The name map feeds the `toolName` of replayed tool results: some
 * backends (e.g. Google Gemini `functionResponse`) reject a result whose
@@ -2556,17 +2888,19 @@ const REQUEST_IMAGE_BUDGETS = [{
 	countQuantum: 12
 }];
 /**
-* Project request history under one image budget: the oldest images past it
-* become placeholder text in place, the newest keep their bytes, and a history
-* already inside the budget is returned as the SAME array — the caller uses
-* that identity to tell "nothing evicted" from "evicted".
+* Project request history under one image budget (≤0.1.5 engines only): the
+* oldest images past it become placeholder text in place, the newest keep their
+* bytes, and a history already inside the budget is returned as the SAME array
+* — the caller uses that identity to tell "nothing evicted" from "evicted".
 *
 * Nested tool-result images ride the same core walk, which is exactly right
 * for this adapter: an evicted `read_image` result surfaces its placeholder as
 * the tool message's own text, so no carrier user message is emitted for it.
 */
-function projectRequestImages(messages, budget) {
-	return offloadRequestImagesWithPolicy(messages, {
+function projectRequestImages(messages, budget, policy) {
+	const offload = policy.offloadRequestImagesWithPolicy;
+	if (typeof offload !== "function") return messages;
+	return offload(messages, {
 		representation: "base64",
 		maxBytes: budget.maxBytes,
 		maxImages: budget.maxImages,
@@ -2582,14 +2916,128 @@ function projectRequestImages(messages, budget) {
 * the raw history — otherwise a retry could reintroduce images the first rung
 * had already evicted.
 */
-function withImageBudget(options, budget) {
-	const projected = projectRequestImages(options.messages, budget);
+function withImageBudget(options, budget, policy) {
+	const projected = projectRequestImages(options.messages, budget, policy);
 	return projected === options.messages ? options : {
 		...options,
 		messages: [...projected]
 	};
 }
 /**
+* Stable provider-neutral code for "a request still carries more images than
+* this route will send; offload N of them and retry". Declared locally rather
+* than imported: the constant does not exist on the 0.1.2–0.1.5 peers this
+* plugin still supports, and importing it statically is the link-time failure
+* described above the budget constants.
+*/
+const IMAGE_OFFLOAD_REQUIRED_CODE = "IMAGE_OFFLOAD_REQUIRED";
+/** The installed engine's image policy; see {@link CoreImagePolicy}. */
+const CORE_IMAGE_POLICY = dshLlm;
+/**
+* The durable-offload contract this engine speaks, or undefined on ≤0.1.5.
+*
+* Both members are required together: a half-populated engine would either
+* lose the surface's marks (re-sending evicted images as pixels) or lose the
+* count (silently sending an over-budget body), and neither is worth a partial
+* opt-in. Absent, the adapter keeps its own transient projection instead.
+*/
+function surfaceImagePolicy(api = CORE_IMAGE_POLICY) {
+	return typeof api.projectOffloadedImages === "function" && typeof api.requiredImageOffload === "function" ? {
+		projectOffloadedImages: api.projectOffloadedImages,
+		requiredImageOffload: api.requiredImageOffload
+	} : void 0;
+}
+/**
+* The failure a route raises instead of evicting on its own (≥0.1.6). The
+* count is the ONE thing the harness needs: `dsh-compaction-image-offload`
+* records it as an `image/offload` event, marks that many oldest retained
+* occurrences, and retries the step.
+*
+* Deliberately outside `providerRetryPolicy()`'s whitelist: a byte-identical
+* resend cannot succeed, so the retry belongs to the surface mutation, not to
+* dsh-llm-retry. On a profile that does not mount that plugin the failure is
+* terminal — every shipped profile reaches it through dsh-base.
+*/
+function imageOffloadRequired(missing) {
+	const options = { offloadImages: missing };
+	return new LlmError(`commandcode request images exceed the route budget; ${missing} more oldest occurrence(s) must be offloaded.`, IMAGE_OFFLOAD_REQUIRED_CODE, options);
+}
+/** The budget in the shape the core counter takes (representation + the rung). */
+function coreBudget(budget) {
+	return {
+		representation: "base64",
+		...budget
+	};
+}
+/**
+* Exact request-version bytes of one retained occurrence. The declared
+* normalized size IS what this adapter inlines (the body is built from
+* `attachments.readImage`, base64-encoded), so the accounting matches the wire
+* byte for byte, and the core helper expands it for `base64` on its own.
+*/
+const imageVersionBytes = (block) => block.attachment.bytes;
+/**
+* ≥0.1.6 request options: the surface's durable marks become placeholder text,
+* and an over-budget history FAILS with the count to offload instead of being
+* evicted here. Throws rather than returning, so no caller can accidentally
+* send a body this route already knows is too large.
+*/
+function withSurfaceOffload(options, policy, budget) {
+	const marked = policy.projectOffloadedImages(options.messages, (ref) => offloadedImageText(ref));
+	const messages = marked === options.messages ? options.messages : [...marked];
+	const missing = policy.requiredImageOffload(messages, coreBudget(budget), imageVersionBytes);
+	if (missing > 0) throw imageOffloadRequired(missing);
+	return messages === options.messages ? options : {
+		...options,
+		messages
+	};
+}
+/**
+* One image's bytes for the wire: the attachment service's REQUEST VERSION when
+* it can produce one, else the normalized original.
+*
+* `readImage()` answers the stored original, which is what admission accepted —
+* not what a provider request should carry. `readImageRequest()` re-encodes to
+* the route target in `./image-request.ts` and caches the result under it, so
+* the same attachment costs one encode per target instead of one per occurrence,
+* and the base64 the wire expands is bounded (both the pixel budget and, more to
+* the point here, the encoded bytes). The fallback is for a backend that does
+* not implement the abstract method; every engine this plugin declares support
+* for does.
+*/
+async function readRequestImage(attachments, ref) {
+	if (typeof attachments.readImageRequest === "function") return (await attachments.readImageRequest(ref, requestImageTarget(ref))).data;
+	return (await attachments.readImage(ref)).data;
+}
+/**
+* Price one request occurrence.
+*
+* Two cases cost no vision tokens at all, and both are priced as their
+* model-visible TEXT so the caller's estimator can charge that instead: a model
+* that accepts text only (the harness projects those images to placeholder text
+* before the request), and an occurrence the session surface has already
+* offloaded (≥0.1.6 renders the same placeholder text in every later request).
+* A retained occurrence on this route contributes no text at all — the pixels
+* are inlined — so its price is the family's visual-token count and nothing else.
+*/
+function priceRequestImage(occurrence, model, imageCapable) {
+	const block = occurrence;
+	const ref = block.attachment ?? occurrence;
+	if (!imageCapable) return {
+		visualTokens: 0,
+		text: textOnlyImageText(ref)
+	};
+	if (block.offloaded === true) return {
+		visualTokens: 0,
+		text: offloadedImageText(ref)
+	};
+	const target = requestImageTarget(ref);
+	return {
+		visualTokens: commandCodeImageTokens(model, target.width, target.height),
+		text: ""
+	};
+}
+/**
 * Convert one image reference to the Command Code wire format, as the official
 * CLI does: `{ type: 'image', source: { type: 'base64', media_type, data } }`.
 * Bytes come from the durable attachment service; the media type is the one
@@ -2617,7 +3065,7 @@ async function messagesToCC(messages, readImage) {
 	};
 	for (const message of messages) {
 		if (message.role === "system") continue;
-		if (message.role === "user" && message.source.kind !== "tool") {
+		if (message.role === "user" && !isToolResultMessage(message)) {
 			flushPendingImages();
 			const parts = [];
 			for (const block of message.content) {
@@ -2660,7 +3108,7 @@ async function messagesToCC(messages, readImage) {
 			});
 			continue;
 		}
-		if (message.role === "user" && message.source.kind === "tool") {
+		if (isToolResultMessage(message)) {
 			const block = message.content[0];
 			if (!block || block.type !== "tool-result" || !paired.has(block.toolCallId)) continue;
 			const media = toolResultMedia(block);
@@ -2729,7 +3177,7 @@ async function messagesToOpenAI(messages, readImage) {
 	};
 	for (const message of messages) {
 		if (message.role === "system") continue;
-		if (message.role === "user" && message.source.kind !== "tool") {
+		if (message.role === "user" && !isToolResultMessage(message)) {
 			flushPendingImages();
 			const parts = [];
 			for (const block of message.content) {
@@ -2775,7 +3223,7 @@ async function messagesToOpenAI(messages, readImage) {
 			out.push(assistant);
 			continue;
 		}
-		if (message.role === "user" && message.source.kind === "tool") {
+		if (isToolResultMessage(message)) {
 			const block = message.content[0];
 			if (!block || block.type !== "tool-result" || !paired.has(block.toolCallId)) continue;
 			const media = toolResultMedia(block);
@@ -3106,6 +3554,15 @@ var CommandCodeAdapter = class extends LlmAdapter {
 	catalog = [];
 	fetchImpl;
 	resolveAttachments;
+	/** The engine's request-image policy, resolved once (tests may inject one). */
+	imagePolicy;
+	/**
+	* The ≥0.1.6 durable contract, or `undefined` on a ≤0.1.5 engine — where the
+	* adapter must evict its own history. Resolved once: the contract a process
+	* speaks cannot change while it runs, and resolving here keeps every request
+	* on the same branch (see {@link surfaceImagePolicy}).
+	*/
+	surfaceOffload;
 	billingAccess = /* @__PURE__ */ new Map();
 	billingAccessInflight = /* @__PURE__ */ new Map();
 	protocolCache = /* @__PURE__ */ new Map();
@@ -3114,6 +3571,8 @@ var CommandCodeAdapter = class extends LlmAdapter {
 		this.deps = deps;
 		this.fetchImpl = deps.fetchImpl ?? fetch;
 		this.resolveAttachments = deps.resolveAttachments;
+		this.imagePolicy = deps.imageOffload ?? CORE_IMAGE_POLICY;
+		this.surfaceOffload = surfaceImagePolicy(this.imagePolicy);
 	}
 	/**
 	* Display metadata for the picker's provider group header. The base class
@@ -3163,6 +3622,25 @@ var CommandCodeAdapter = class extends LlmAdapter {
 			}
 		}, "llm-commandcode: retryPolicy");
 	}
+	/**
+	* Visual-token pricing for one exact model route (see `./image-tokens.ts`).
+	*
+	* Without this the token meter prices EVERY image with its structural
+	* heuristic — a handful of tokens for a full screenshot — so an image-heavy
+	* session reports far less context than it is actually carrying. The price is
+	* computed at the dimensions this route would send (the same request target
+	* `readImageRequest` encodes to), so the estimate tracks the wire rather than
+	* the stored original.
+	*
+	* Both payload generations are handled, because they disagree: ≤0.1.5 hands
+	* over bare `ImageAttachmentRef`s, ≥0.1.6 hands over `ImageBlock`s that also
+	* carry the surface's `offloaded` mark. Returning a price per occurrence, in
+	* order, is a hard requirement — the meter throws when the counts differ.
+	*/
+	imageRequestPricing(_provider, model) {
+		const imageCapable = KNOWN_IMAGE_MODELS.has(model);
+		return { priceImages: (images) => images.map((image) => priceRequestImage(image, model, imageCapable)) };
+	}
 	/** Refresh the catalog (live fetch, cache fallback) and return it. */
 	async loadCatalog(signal) {
 		const { apiBase, modelsCachePath } = this.deps.options();
@@ -3341,10 +3819,25 @@ var CommandCodeAdapter = class extends LlmAdapter {
 	* wins; otherwise a cached (not network-fetched) billing tier of Go is
 	* treated as CLI-only. Unknown accounts default to Provider API and fall
 	* back only after an `upgrade_required` rejection.
+	*
+	* Models the Provider API serves ONLY through `/provider/v1/messages` (the
+	* Claude family — `requiresMessagesEndpoint()`) always take the CLI
+	* transport, on any tier and even under a forced `'openai'` preference:
+	* that option is documented as "prefer the Provider API, still fall back",
+	* and the 400 these models answer with is not a preference to be honoured
+	* but a hard refusal. `/alpha/generate` routes every one of them, so this
+	* costs nothing.
+	*
+	* That decision is deliberately NOT written to `protocolCache`. The cache is
+	* keyed by API key alone, so remembering it would pin the whole ACCOUNT to
+	* the CLI transport and drag every other model — DeepSeek, GLM, Qwen, all of
+	* which the Provider API serves correctly — off it until the entry expired.
 	*/
-	resolveProtocol(apiKey) {
+	resolveProtocol(apiKey, model) {
 		const forced = this.deps.options().protocol;
-		if (forced === "cli" || forced === "openai") return forced;
+		if (forced === "cli") return forced;
+		if (requiresMessagesEndpoint(model)) return "cli";
+		if (forced === "openai") return forced;
 		const cached = this.cachedProtocolUseCli(apiKey);
 		if (cached !== void 0) return cached ? "cli" : "openai";
 		if (this.cachedBillingTierWeight(apiKey) === GO_TIER_WEIGHT) {
@@ -3449,7 +3942,7 @@ var CommandCodeAdapter = class extends LlmAdapter {
 			if (!KNOWN_IMAGE_MODELS.has(options.model)) throw new LlmError(`Command Code model "${options.model}" does not support image input; switch to a Vision-capable model (see the model registry)`, "UNSUPPORTED_CONTENT");
 			const attachments = this.resolveAttachments?.();
 			if (attachments === void 0) throw new LlmError("Command Code image input requires the durable attachment service", "UNSUPPORTED_CONTENT");
-			readImage = (ref) => attachments.readImage(ref).then((stored) => stored.data);
+			readImage = (ref) => readRequestImage(attachments, ref);
 		}
 		const connection = this.deps.options();
 		let apiKey = await this.deps.resolveApiKey(connection, options.model);
@@ -3459,8 +3952,8 @@ var CommandCodeAdapter = class extends LlmAdapter {
 		const supported = KNOWN_EFFORTS[options.model];
 		const reasoningEffort = effort && effort !== "off" && supported?.includes(effort) ? effort : void 0;
 		const systemText = [options.system ?? "", ...options.messages.filter((m) => m.role === "system").map((m) => m.content.map(blockText).filter(Boolean).join("\n"))].filter(Boolean).join("\n\n");
-		let protocol = this.resolveProtocol(apiKey);
-		let requestOptions = withImageBudget(options, REQUEST_IMAGE_BUDGETS[0]);
+		let protocol = this.resolveProtocol(apiKey, options.model);
+		let requestOptions = this.surfaceOffload === void 0 ? withImageBudget(options, REQUEST_IMAGE_BUDGETS[0], this.imagePolicy) : withSurfaceOffload(options, this.surfaceOffload, REQUEST_IMAGE_BUDGETS[0]);
 		let imageBudgetIndex = 0;
 		const buildBody = async (target) => target === "cli" ? buildCliBody(requestOptions, connection, {
 			maxTokens,
@@ -3495,12 +3988,17 @@ var CommandCodeAdapter = class extends LlmAdapter {
 				continue;
 			}
 			if (attempt.status === 413 && imageBudgetIndex + 1 < REQUEST_IMAGE_BUDGETS.length) {
-				const tightened = withImageBudget(requestOptions, REQUEST_IMAGE_BUDGETS[imageBudgetIndex + 1]);
-				if (tightened !== requestOptions) {
-					imageBudgetIndex += 1;
-					requestOptions = tightened;
-					body = await buildBody(protocol);
-					continue;
+				if (this.surfaceOffload !== void 0) {
+					const missing = this.surfaceOffload.requiredImageOffload(requestOptions.messages, coreBudget(REQUEST_IMAGE_BUDGETS[imageBudgetIndex + 1]), imageVersionBytes);
+					if (missing > 0) throw imageOffloadRequired(missing);
+				} else {
+					const tightened = withImageBudget(requestOptions, REQUEST_IMAGE_BUDGETS[imageBudgetIndex + 1], this.imagePolicy);
+					if (tightened !== requestOptions) {
+						imageBudgetIndex += 1;
+						requestOptions = tightened;
+						body = await buildBody(protocol);
+						continue;
+					}
 				}
 			}
 			const rotate = this.deps.rotateApiKey;
@@ -3786,7 +4284,7 @@ function handleOpenAIEvent(asm, event) {
 	}
 	const choice = isRecord(choices[0]) ? choices[0] : {};
 	const delta = isRecord(choice.delta) ? choice.delta : {};
-	const reasoningDelta = stringValue(delta.reasoning) ?? stringValue(delta.reasoning_content) ?? "";
+	const reasoningDelta = stringValue(delta.reasoning) ?? stringValue(delta.reasoning_content) ?? reasoningDetailsText(delta.reasoning_details) ?? "";
 	if (reasoningDelta !== "") {
 		chunks.push(...closeText(asm));
 		if (asm.reasoningIndex < 0) {
@@ -3972,8 +4470,7 @@ const commandcodeCommand = {
 		resetSuffix: "重置 {when}",
 		partialFailures: "⚠️  部分端点失败: {list}",
 		noData: "（无数据 — 请检查 API 密钥）",
-		errorText: "获取 Command Code 用量失败：{message}",
-		imageGate: "当前会话已包含图片，而模型 {model} 不支持图片输入；请选择支持图片的模型，或先移除会话中的图片。"
+		errorText: "获取 Command Code 用量失败：{message}"
 	},
 	en: {
 		title: "📊 Command Code usage{account}",
@@ -4004,8 +4501,7 @@ const commandcodeCommand = {
 		resetSuffix: "resets {when}",
 		partialFailures: "⚠️  some endpoints failed: {list}",
 		noData: "(no data — check your API key)",
-		errorText: "Could not fetch Command Code usage: {message}",
-		imageGate: "This session already contains images, and model {model} does not accept image input; please select an image-capable model, or remove the images from the session first."
+		errorText: "Could not fetch Command Code usage: {message}"
 	}
 };
 /**
@@ -5582,6 +6078,108 @@ function applyCommandCodeTuiSettings(ctx, deps) {
 	return refresh;
 }
 //#endregion
+//#region src/transport-retry.ts
+/**
+* A bounded retry budget for `TRANSPORT` failures (issue #39, second report).
+*
+* The route's retry policy (`providerRetryPolicy` in `./adapter.ts`) is
+* deliberately near-unbounded: 1000 attempts with waits doubling to a 15-minute
+* cap. That shape exists for the failures a provider ASKS to have retried — an
+* exhausted 5-hour window, a Cloudflare 520 — where the wait is the point.
+*
+* A transport failure is not that. The reporter's second event at ~710k
+* context was `Connect Timeout Error ... timeout: 10000ms` (undici's own
+* connect timeout; this plugin's `requestTimeoutMs` is 60s) and, on another
+* attempt, `read ECONNRESET` against `/alpha/generate`. Because `TRANSPORT` is
+* in the whitelist, each of those entered the same 1000-attempt loop: with
+* `initialDelayMs: 500` doubling, the wait before attempt 11 alone is 512 s and
+* the cumulative wait before it is ~500 s — the "模型请求重试已取消（11/1000）·
+* 482s" the reporter photographed is that 512 s countdown, 30 s into it — and
+* those waits are counted BEFORE each retry attempt, not after it.
+*
+* A connection that cannot be established is either a sub-second blip (the
+* first few attempts recover it, invisibly) or an outage that no amount of
+* waiting inside one request will fix. So transport failures get their own
+* budget, and when it is exhausted the failure is surfaced with the diagnosis
+* instead of manufacturing a multi-minute stall. Waiting out a real outage is
+* the user's call — the next send starts a fresh budget — and
+* `dsh-llm-retry`'s window for rate limits is untouched.
+*
+* Deliberately NOT counted here: the pre-stream recovery the ADAPTER performs
+* inside one `stream()` call (account rotation on 429/401, the 413 image-budget
+* step-down, the Provider-API → CLI protocol switch). Those are invisible to
+* the caller and bounded on their own; this budget caps only the harness's
+* retry loop.
+*
+* Reset rule: the budget clears at each new STEP — one step is exactly one
+* model request (`step/start` is appended immediately before the call) — so the
+* cap is per logical request and the next step of the same turn gets its own
+* grace. `agent/status` → `idle` is NOT the reset signal even though it looks
+* like the natural one: the agent loop's `setPhase` emits it only on a status
+* CHANGE, and a turn's steps all run inside one `running` phase, so it never
+* fires between them — a budget reset only there would be per-turn, and an
+* outage would fail every later step of that turn immediately instead of
+* retrying each. `assistant/attempt` is wrong for the opposite reason: the loop
+* appends it for the FAILED attempt itself, *before* dispatching
+* `agent/request-error`, so resetting on it would clear the budget on every
+* failure and restore the very loop this module exists to stop.
+*
+* @module
+*/
+/** Failure code this budget covers. */
+const TRANSPORT_FAILURE_CODE = "TRANSPORT";
+/** One agent's live transport-failure count, keyed weakly so a dropped agent cannot leak. */
+const counts = /* @__PURE__ */ new WeakMap();
+/**
+* Count one attempt's outcome against the transport budget.
+*
+* @param agent - the identity the budget is scoped to (the agent object).
+* @param failureCode - the failed attempt's `LlmFailure.code`.
+* @param maxRetries - transport retries to absorb before the failure surfaces.
+* @returns `'ignored'` for any non-transport code (the route policy decides
+*   those, unchanged), `'retry'` while the budget has room, `'exhausted'` once
+*   it does not.
+*/
+function absorbTransportFailure(agent, failureCode, maxRetries) {
+	if (failureCode !== "TRANSPORT") return "ignored";
+	const used = counts.get(agent) ?? 0;
+	if (used >= maxRetries) return "exhausted";
+	counts.set(agent, used + 1);
+	return "retry";
+}
+/** Clear one agent's transport budget (a new step starts, or the turn ended). */
+function resetTransportFailures(agent) {
+	counts.delete(agent);
+}
+/**
+* What one session event means for the transport budget.
+*
+* Exported and pure on purpose: the choice of event is the part of this design
+* that is easy to get plausibly wrong (`agent/status` → `idle` looks like the
+* natural reset and is not one — see the module comment), so it is stated once,
+* here, where a test can pin it, instead of being implied by a listener body.
+*
+* @param type - the appended session event's type.
+* @returns `'reset'` for a new step (one model request), `'forget'` when the
+*   turn ended and the session → agent mapping is no longer needed, otherwise
+*   `'none'`.
+*/
+function transportResetAction(type) {
+	if (type === "step/start") return "reset";
+	if (type === "turn/end") return "forget";
+	return "none";
+}
+/**
+* The diagnosis a capped turn ends with. Bilingual, because the harness renders
+* a failed turn's message verbatim and this plugin's other user-facing failures
+* are bilingual too (see the adapter's error builders). It names the retry
+* budget and the checks that actually help, instead of the bare "fetch failed"
+* chain the retry chrome would otherwise show.
+*/
+function transportBudgetMessage(failureMessage, maxRetries) {
+	return `${failureMessage}；Command Code API 连接在连续重试后仍失败——已停止重试以免整轮卡死。插件已自动重试 ${maxRetries} 次。通常说明当前网络到 api.commandcode.ai 的连接不通，常见原因是代理未生效：DSH 只读取环境变量 HTTPS_PROXY/HTTP_PROXY（系统代理/PAC 不会被读取），请确认启动 DSH 的终端里已导出代理，或先关闭代理直连后重试。网络恢复后直接重发即可 — Command Code API transport still failed after ${maxRetries} automatic retries, which were stopped so the turn could not stall for minutes. This is a connectivity problem between this machine and api.commandcode.ai, not a context-window or request-size rejection. Common cause: the proxy is not reaching the harness — DSH reads HTTPS_PROXY/HTTP_PROXY from the environment only (a Windows system proxy/PAC setting is not consulted), so export it in the launching shell, or turn the proxy off and retry. Resend when the network recovers; the budget is per request and has been reset`;
+}
+//#endregion
 //#region src/index.ts
 /**
 * dsh-commandcode-provider — DeepSeek Harness LLM provider plugin for Command
@@ -5626,6 +6224,7 @@ const Config = z.object({
 	modelsCachePath: z.string(),
 	requestTimeoutMs: z.number().min(1).max(MAX_TIMER_DELAY_MS),
 	streamIdleTimeoutMs: z.number().min(1).max(MAX_TIMER_DELAY_MS),
+	transportMaxRetries: z.number().min(0).max(50),
 	filterModelsByPlan: z.boolean(),
 	visibleModels: z.array(z.string()),
 	/**
@@ -5767,6 +6366,36 @@ function apply(ctx, config) {
 		settingsPath: []
 	}]);
 	ctx.llm.registerAdapter([PROVIDER], adapter);
+	const transportMaxRetries = () => {
+		const value = current().transportMaxRetries;
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return 5;
+		return Math.min(Math.trunc(value), 50);
+	};
+	const sessionAgents = /* @__PURE__ */ new WeakMap();
+	ctx.on("agent/request-error", async ({ agent, failure, signal }, next) => {
+		if (signal.aborted) return next();
+		const session = Reflect.get(agent, "session");
+		if (typeof session === "object" && session !== null) sessionAgents.set(session, agent);
+		const decision = absorbTransportFailure(agent, failure.code, transportMaxRetries());
+		if (decision === "ignored") return next();
+		if (decision === "retry") return { kind: "retry" };
+		const message = transportBudgetMessage(failure.message, transportMaxRetries());
+		ctx.logger.warn(`llm-commandcode: transport retry budget exhausted for ${PROVIDER} (${TRANSPORT_FAILURE_CODE})`);
+		throw new Error(message);
+	});
+	ctx.on("session/event", (session, event) => {
+		const action = transportResetAction(event.type);
+		if (action === "forget") {
+			sessionAgents.delete(session);
+			return;
+		}
+		if (action !== "reset") return;
+		const agent = sessionAgents.get(session);
+		if (agent !== void 0) resetTransportFailures(agent);
+	});
+	ctx.on("agent/status", ({ agent, status }) => {
+		if (status === "idle") resetTransportFailures(agent);
+	});
 	const usageReports = async () => {
 		const described = await pool.describeAccounts();
 		const byId = new Map(described.map((account) => [account.slot.id, account]));