@mars-sea/dsh-commandcode-provider 0.11.0 → 0.11.2

package/lib/index.d.ts

@@ -1,10 +1,10 @@
 import z from "@deepseek-ai/schemastery";
-import { GenerateOptions, LlmAdapter, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ResolvedRetryPolicy, StreamChunk } from "@deepseek-ai/dsh-llm";
+import { GenerateOptions, LlmAdapter, LlmImageRequestPricing, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, Message, ResolvedRetryPolicy, StreamChunk } from "@deepseek-ai/dsh-llm";
 import { CredentialRef } from "@deepseek-ai/dsh-credentials";
 import { TypertRemoteService, TypertSchema } from "@deepseek-ai/dsh-typert-protocol";
 import { WebRuntime, WebSearchProvider, WebSearchRequest, WebSearchResult } from "@deepseek-ai/dsh-web";
 import { Context } from "@deepseek-ai/cordis";
-import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
+import { AttachmentStore, ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
 import { CommandDefinition } from "@deepseek-ai/dsh-commands";
 //#region src/adapter.d.ts
 declare const COMMAND_CODE_CLI_VERSION = "1.54.0";
@@ -22,6 +22,27 @@ declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
 declare function projectSlugFromPath(pathName: string): string;
 /** Read a usable Command Code credential from the official CLI auth file. */
 declare function resolveAuthFileApiKey(): string | undefined;
+/** One occurrence's exact request-version byte length, as the core counter wants it. */
+type ImageVersionBytes = (block: {
+  attachment: ImageAttachmentRef;
+}) => number;
+/**
+ * The installed engine's request-image policy, whichever generation it is.
+ *
+ * Every member is optional because the two generations never coexist: a
+ * ≤0.1.5 engine has only `offloadRequestImagesWithPolicy`, a ≥0.1.6 engine has
+ * only the other two. `CORE_IMAGE_POLICY` is the namespace object viewed
+ * through this shape, and `surfaceImagePolicy()` is the ONE place that decides
+ * which contract this process speaks.
+ */
+interface CoreImagePolicy {
+  /** ≤0.1.5: project history under a byte/count budget, adapter-owned and transient. */
+  offloadRequestImagesWithPolicy?: (messages: readonly Message[], policy: Record<string, unknown>) => readonly Message[];
+  /** ≥0.1.6: render the surface's durable offload marks as placeholder text. */
+  projectOffloadedImages?: (messages: readonly Message[], placeholder: (ref: ImageAttachmentRef) => string) => readonly Message[];
+  /** ≥0.1.6: how many more leading retained occurrences must be offloaded. */
+  requiredImageOffload?: (messages: readonly Message[], budget: Record<string, unknown>, versionBytes: ImageVersionBytes) => number;
+}
 /** Connection facts resolved fresh per request by the plugin entry. */
 interface CommandCodeConnectionOptions {
   /** API base; the Provider API lives under it (`/alpha/generate`, `/provider/v1/chat/completions`, `/provider/v1/models`). */
@@ -102,6 +123,13 @@ interface CommandCodeAdapterDeps<C extends CommandCodeConnectionOptions = Comman
   fetchImpl?: typeof fetch;
   /** Resolve the optional durable attachment service for image input (tests); defaults to none. */
   resolveAttachments?: ResolveAttachments;
+  /**
+   * Request-image policy override (tests); defaults to the installed engine's
+   * own helpers, whichever generation they belong to. Injecting it is the only
+   * way to exercise the ≥0.1.6 durable-offload contract while this checkout
+   * still compiles against the 0.1.2 peers.
+   */
+  imageOffload?: CoreImagePolicy;
 }
 /** Account identity from `/alpha/whoami`. */
 interface CommandCodeAccount {
@@ -202,6 +230,15 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
   private catalog;
   private readonly fetchImpl;
   private readonly resolveAttachments;
+  /** The engine's request-image policy, resolved once (tests may inject one). */
+  private readonly 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}).
+   */
+  private readonly surfaceOffload;
   private readonly billingAccess;
   private readonly billingAccessInflight;
   private readonly protocolCache;
@@ -232,6 +269,22 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
    * future config knob for it would apply on profile restart, not per request.
    */
   providerRetryPolicy(_provider: string): ResolvedRetryPolicy;
+  /**
+   * 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: string, model: string): LlmImageRequestPricing | undefined;
   /** Refresh the catalog (live fetch, cache fallback) and return it. */
   private loadCatalog;
   listModels(provider: string, opts?: {
@@ -1555,6 +1608,15 @@ interface Config {
    * Defaults to true.
    */
   webSearch?: boolean;
+  /**
+   * Whether the Web sidebar shows the plans & quota card
+   * (`sidebar.footer.action`). Defaults to false: the card is opt-in, so an
+   * unset document renders no quota surface in the sidebar and mounts no
+   * background usage poll for it. Only the sidebar entry is affected — the
+   * dashboard cell behind it stays registered, it simply has no trigger until
+   * the toggle is on. Read by the browser client; the adapter ignores it.
+   */
+  showSidebarQuota?: boolean;
   /**
    * Language override for the `/commandcode` Host-side command's user-facing
    * copy. Host commands cannot read the client's `ctx.locale`, so this is

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";
@@ -2072,6 +2073,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.
@@ -2556,17 +2786,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 +2814,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
@@ -3106,6 +3452,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 +3469,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 +3520,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();
@@ -3449,7 +3825,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);
@@ -3460,7 +3836,7 @@ var CommandCodeAdapter = class extends LlmAdapter {
 		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 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 +3871,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;
@@ -3972,8 +4353,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 +4384,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}"
 	}
 };
 /**
@@ -5638,6 +6017,7 @@ const Config = z.object({
 	*/
 	modelVisibility: z.dict(z.boolean()),
 	webSearch: z.boolean().default(true),
+	showSidebarQuota: z.boolean().default(false),
 	accounts: z.array(z.object({
 		label: z.string(),
 		apiKeyEnv: z.string().role("credential-ref"),