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

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?: {
@@ -274,6 +327,19 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
    * 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.
    */
   private resolveProtocol;
   /**
@@ -1491,6 +1557,18 @@ interface Config {
   requestTimeoutMs?: number;
   /** Milliseconds a stream may stall before being treated as a dead connection; defaults to 300s. */
   streamIdleTimeoutMs?: number;
+  /**
+   * Transport failures one request absorbs before the failure is surfaced;
+   * defaults to 5. The route's retry policy is near-unbounded on purpose (1000
+   * attempts, waits doubling to 15 minutes) because that shape is for the
+   * failures a provider asks to have retried — an exhausted rate-limit window,
+   * a gateway 520. A transport failure is not one of those: the first attempts
+   * recover an ordinary blip (the default 5 retries are scheduled 0.5/1/2/4/8 s
+   * after the failures before them, so ~15.5 s of grace), and after that the
+   * wait is pure stall, so the retries are capped here. Raise it on a genuinely
+   * flaky link; 0 surfaces every transport failure immediately.
+   */
+  transportMaxRetries?: number;
   /**
    * Whether the model picker hides models above the account's subscription
    * tier; defaults to true. The filter fails open (unknown plan, billing