@mars-sea/dsh-commandcode-provider 0.12.0 → 0.12.2

package/lib/index.d.ts

@@ -6,8 +6,30 @@ import { WebRuntime, WebSearchProvider, WebSearchRequest, WebSearchResult } from
 import { Context } from "@deepseek-ai/cordis";
 import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
 import { CommandDefinition } from "@deepseek-ai/dsh-commands";
+//#region src/request-timing.d.ts
+type Phase = 'credentials' | 'images' | 'body' | 'serialization' | 'headers';
+type Outcome = 'finished' | 'error' | 'aborted' | 'cancelled';
+interface RequestTimingSummary {
+  version: 1;
+  startedAt: number;
+  model: string;
+  outcome: Outcome;
+  errorCode?: string;
+  totalMs: number;
+  phasesMs: Record<Phase, number>;
+  firstByteMs?: number;
+  firstContentMs?: number;
+  attempts: Array<{
+    protocol: string;
+    bodyBytes: number;
+    headersMs: number;
+    status?: number;
+  }>;
+}
+type RequestTimingSink = (summary: RequestTimingSummary) => void | Promise<void>;
+//#endregion
 //#region src/adapter.d.ts
-declare const COMMAND_CODE_CLI_VERSION = "1.68.0";
+declare const COMMAND_CODE_CLI_VERSION = "1.73.0";
 declare const DEFAULT_API_BASE = "https://api.commandcode.ai";
 /**
  * The output budget this bundle asks for, and the ceiling it will never exceed.
@@ -25,9 +47,16 @@ declare const DEFAULT_API_BASE = "https://api.commandcode.ai";
  * (a 64 000 request answered headers in 1.28 s against 1.57 s for 131 072) but
  * it did cap what a model could ever say in one turn.
  *
- * This is only an UPPER bound. `requestContextBudget` lowers it per request
- * from the prompt actually being sent, so raising the ceiling cannot push a
- * large session over its window.
+ * No client-side clamp is applied on top of this: an earlier version pre-shrank
+ * `max_tokens` from an estimate of the prompt already sent (`requestContextBudget()`,
+ * issue #67), but that estimate over-corrected on ordinary long conversations —
+ * exactly the "output gets cut short as the conversation grows" symptom issue #74
+ * reported — while a live A/B probe (2026-09-30, `stealth/space-bunny-alpha`,
+ * ~19.6% over its 1,000,000-token window with no client-side shrink) showed the
+ * endpoint answers a genuine overflow with an unambiguous `400 … exceeds the
+ * model's context window`, which `isContextOverflowDetail()` below already
+ * classifies as `CONTEXT_WINDOW_EXCEEDED` independently of this constant. See
+ * [决策记录](../docs/决策记录.md).
  */
 declare const DEFAULT_GENERATE_MAX_TOKENS = 131072;
 /**
@@ -42,8 +71,18 @@ declare const DEFAULT_GENERATE_MAX_TOKENS = 131072;
 declare const DEFAULT_MAX_OUTPUT_TOKENS = 131072;
 /** How long the picker's plan-filter billing facts stay cached before refetching. */
 declare const BILLING_ACCESS_TTL_MS: number;
-/** Endpoint protocol selected for one generate call. */
-type CommandCodeProtocol = 'cli' | 'openai';
+/**
+ * Endpoint protocol selected for one generate call.
+ *
+ * `messages` is the Anthropic Messages surface at
+ * `{apiBase}/provider/v1/messages`, the only Provider API route the Claude
+ * family answers (posted to `/chat/completions` they refuse with `400 Model
+ * "<id>" must be called via /provider/v1/messages`). `openai` is the
+ * documented Chat Completions surface; `cli` is Command Code's private
+ * `/alpha/generate` transport, kept for Go-plan keys (the one plan without
+ * Provider API access) and as the `upgrade_required` fallback.
+ */
+type CommandCodeProtocol = 'cli' | 'openai' | 'messages';
 /**
  * Head-of-request timeout: how long to wait for the first response byte.
  *
@@ -181,6 +220,8 @@ interface AccountRotationContext {
 }
 /** Everything the adapter needs beyond the request itself. */
 interface CommandCodeAdapterDeps<C extends CommandCodeConnectionOptions = CommandCodeConnectionOptions> {
+  /** 可选的数值耗时接收器；不接收提示词、凭据或错误正文。 */
+  onRequestTiming?: RequestTimingSink;
   /** Resolve the current connection facts (fresh per request, settings-aware). */
   options: () => C;
   /**
@@ -326,6 +367,7 @@ interface CommandCodeUsageReport {
 declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = CommandCodeConnectionOptions> extends LlmAdapter {
   private readonly deps;
   private catalog;
+  private catalogState;
   private readonly fetchImpl;
   private readonly resolveAttachments;
   /**
@@ -336,24 +378,32 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
   private readonly billingAccess;
   private readonly billingAccessInflight;
   private readonly protocolCache;
+  /** Namespace account-derived facts by gateway without exposing the key. */
+  private accountCacheKey;
   /**
    * Consecutive header timeouts for the last request shape, counted ACROSS
    * `stream()` calls: dsh-llm-retry re-invokes this same instance, so this is
-   * the only place a streak can live. One slot rather than a map is the point —
-   * the claim is "consecutive", and a single record cannot grow.
-   */
-  private headerTimeoutStreak;
+   * the only place a streak can live. Keyed by `sessionId` (not by `agent`:
+   * `GenerateOptions` carries no agent reference, only `sessionId`) so
+   * concurrent sessions on this one shared adapter instance cannot clear or
+   * inflate each other's count. A call with no `sessionId` (a one-shot,
+   * session-less caller) falls back to {@link GLOBAL_HEADER_TIMEOUT_KEY},
+   * matching the old single-slot behavior for exactly that case. Bounded by
+   * {@link MAX_HEADER_TIMEOUT_STREAK_ENTRIES} with FIFO eviction (`Map`
+   * preserves insertion order) since the key space is per-session rather than
+   * per-account/model, so it is not naturally small like `protocolCache`.
+   */
+  private readonly headerTimeoutStreaks;
+  private static readonly MAX_HEADER_TIMEOUT_STREAK_ENTRIES;
   constructor(deps: CommandCodeAdapterDeps<C>);
   /**
    * Grade one failed attempt: a headers timeout that repeats on an unchanged
    * payload eventually leaves the retryable whitelist.
    *
    * `providerRetryPolicy()` cannot express this itself — dsh-llm's
-   * `NormalRetryPolicyConfig` carries a single scalar `maxRetries` next to the
-   * code list, so there is no per-code limit to lower. Escalating from here is
-   * the only way to keep `RATE_LIMIT` / `SERVER` / `TRANSPORT` retryable (each
-   * carries a real "try again later" signal) while stopping the one code that,
-   * repeated unchanged, only burns the user's session.
+   * `NormalRetryPolicyConfig` carries one `maxRetries` for every listed code.
+   * Escalating here stops repeated identical header timeouts with a specific
+   * diagnosis; the agent listener separately caps ordinary transient errors.
    *
    * @returns the error to surface: unchanged for any other failure, the
    * original timeout below the threshold, and a terminal one at it.
@@ -368,12 +418,11 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
    */
   providerInfo(provider: string): LlmProviderInfo;
   /**
-   * Near-unbounded retry for transient failures only (`mode: 'normal'` with
-   * an explicit 1000-attempt cap — opencode-style persistence without the
-   * unbounded loop): `RATE_LIMIT`/`SERVER`/`TIMEOUT`/`TRANSPORT`/
-   * `EMPTY_RESPONSE` retry up to 1000 times with waits doubling from 500 ms
-   * and capping at 15 minutes (±10% jitter), so an exhausted 5-hour window
-   * recovers in-session instead of failing after two tries. Permanent failures
+   * The official executor owns backoff and provider reset waits. Its high
+   * route-wide cap lets a confirmed `RATE_LIMIT` window recover in-session;
+   * our request-error listener limits `SERVER`/`TIMEOUT`/`EMPTY_RESPONSE`/
+   * `THROTTLED` to three retries and `TRANSPORT` to its separate budget.
+   * Waits double from 500 ms and cap at 15 minutes (±10% jitter). Permanent failures
    * (an invalid key's `INVALID_CREDENTIAL`, `UNSUPPORTED_CONTENT`, plan
    * rejections) are absent from the whitelist and surface immediately instead
    * of looping. Waits the pool/adapter attach as `providerRetryAfterMs` are
@@ -397,7 +446,11 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
    * 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 currentCatalogState;
+  /** 直接生成也使用本地可信目录，不额外联网；并发冷请求共用一次文件读取。 */
+  private catalogForGenerate;
+  /** 共享一次刷新；调用者取消只结束自己的等待，不取消其他调用者的请求。 */
   private loadCatalog;
   listModels(provider: string, opts?: {
     unfiltered?: boolean;
@@ -406,9 +459,8 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
    * The per-model allowance bracket this account POOL falls into, or undefined
    * when there is nothing honest to show.
    *
-   * The pricing page publishes a per-model monthly allowance for GOAT and Pro
-   * only — its own words are "the boost is a per-model allowance, so it lives on
-   * the plans that have them" — so a pool whose highest plan is Go, Provider,
+   * The pricing page publishes per-model monthly allowances for Go, GOAT and
+   * Pro. A pool whose highest plan is Provider,
    * Max or Ultra gets undefined rather than a neighbouring tier's figure. Taking
    * the HIGHEST tier matches the question the picker already answers for a pool
    * (see `modelVisibleForAnyAccount`): what the user can reach, not what the one
@@ -416,7 +468,7 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
    * too — an unreachable billing endpoint yields undefined, which hides the
    * allowance instead of inventing one.
    */
-  allowanceTier(): Promise<'goat' | 'pro' | undefined>;
+  allowanceTier(): Promise<'go' | 'goat' | 'pro' | undefined>;
   resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
   /** The headers every authenticated account endpoint shares. */
   private accountHeaders;
@@ -466,25 +518,36 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
   /** Fresh cached billing tier weight for a key, or undefined when not known. */
   private cachedBillingTierWeight;
   /** Cached protocol decision for a key, or undefined when expired/unknown. */
-  private cachedProtocolUseCli;
+  private cachedProtocol;
   private rememberProtocol;
   /**
-   * Choose the initial protocol for one request. A fresh protocol cache entry
-   * 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.
+   * True when the catalog routes `model` to `/provider/v1/messages`.
    *
-   * 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.
+   * The catalog's own `supported_endpoints` is authoritative (it is what
+   * upstream publishes per model); `requiresMessagesEndpoint()` — the
+   * `claude-*` prefix rule — is the fallback for a catalog entry that carries
+   * no route list, which is the shape every pre-1.55 cache file has.
+   */
+  private routesToMessages;
+  /**
+   * Choose the initial protocol for one request.
+   *
+   * Models the Provider API serves only through `/provider/v1/messages` (the
+   * Claude family) take the Messages 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 on
+   * Chat Completions (`Model "<id>" must be called via /provider/v1/messages`)
+   * is a hard refusal, not a preference to honour.
    *
    * That decision is deliberately NOT written to `protocolCache`, which is
-   * keyed by API key alone: remembering it would pin the whole ACCOUNT to the
-   * CLI transport and drag every other model off it until the entry expired.
+   * keyed by gateway and API key: it depends on the model, not just the account, so
+   * remembering it would pin the whole ACCOUNT to one transport and drag
+   * every other model along (issue #46).
+   *
+   * Otherwise a fresh protocol cache entry wins, then a cached (not
+   * network-fetched) billing tier of Go — the one plan without Provider API
+   * access. Unknown accounts default to Chat Completions and fall back to the
+   * CLI transport only after an `upgrade_required` rejection.
    */
   private resolveProtocol;
   /**
@@ -535,6 +598,26 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
     resetAt: number;
   } | undefined>;
   stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+  /**
+   * One turn, with at most one output-ceiling downshift.
+   *
+   * The ceiling a model accepts is not published anywhere the request can be
+   * built from (see `modelOutputTokenLimit`), and the endpoint states it only
+   * by refusing. That refusal is worth one retry rather than a failed turn: the
+   * harness's own recovery for it — compact the context — cannot help, because
+   * nothing about the context is wrong, and resending the identical request
+   * would be refused identically (issue #71). Reading the stated ceiling off
+   * the rejection turns one wasted turn into one, for good: it is recorded
+   * process-wide, so the next request for this model is built correctly
+   * without spending the round trip again.
+   *
+   * Only BEFORE the first chunk reaches the host. Once a delta has been
+   * delivered the answer is already partly on screen, and a second request
+   * would duplicate it — so from that point the error stands and says what is
+   * actually wrong. One downshift per turn, and a second refusal surfaces.
+   */
+  private streamRequest;
+  private streamAttempt;
 }
 //#endregion
 //#region src/accounts.d.ts
@@ -728,6 +811,26 @@ declare class CommandCodeAccountPool {
     key: string;
     slot: CommandCodeAccountSlot;
   } | undefined>;
+  /**
+   * Which account is serving right now, for display (the settings page's
+   * account card, the sidebar usage stats) — without consuming a request's
+   * `tried` budget and without throwing when nothing can serve.
+   *
+   * Reads and self-heals exactly like {@link resolveKey} would: an `unknown`
+   * mark on the pinned account is re-probed (throttled the same way, sharing
+   * the same per-key timestamp), and a pool where nothing currently resolves
+   * gets one batch probe pass too. Without this, the badge read a possibly
+   * stale mark forever — nothing but an actual generate request ever cleared
+   * an `unknown` mark, so a page left open with no chat activity kept
+   * showing "switched to the fallback account" long after a real request
+   * would have quietly recovered (issue #51's follow-up report: the account
+   * card and the sidebar stats both stuck on the wrong account).
+   *
+   * No `model` parameter: the badge describes the pool as a whole, not one
+   * request, so model-routing rules are deliberately not consulted here —
+   * matching what the direct `selectActiveAccount` call this replaces did.
+   */
+  activeAccount(): Promise<ResolvedAccount | undefined>;
   /**
    * Record a rejection against one key. A `throttled` rejection (the plain 429
    * that named no window) marks the key with the `throttle` cause, leaving
@@ -793,6 +896,26 @@ declare class CommandCodeAccountPool {
    * read as "never usable again" to {@link accountUsable}, so `unknown` it is.
    */
   private stampWindowMark;
+  /**
+   * The explicit-account fallback re-check: when `chosen` (what rotation
+   * would currently serve) is not the account the user actually asked for,
+   * re-probe that explicit account's mark before accepting the fallback —
+   * so a rate-limit mark never demotes the user's own selection for good
+   * (issue #51). Returns the revived account, or `undefined` when there is
+   * nothing to revive (explicit account already serving, not due for a
+   * probe, or the probe found it still exceeded). Shared by {@link resolveKey}
+   * (the request path) and {@link activeAccount} (the display path), so both
+   * agree on what "currently usable" means instead of drifting apart.
+   */
+  private reviveExplicit;
+  /**
+   * Probe every marked account's real usage window when nothing currently
+   * resolves. Disabled (401) keys are not probed — an invalid key stays
+   * invalid. A throwing probe counts as "unknown" (like a failed one): it
+   * must not turn the all-exhausted path into a raw rejection instead of
+   * RATE_LIMIT. Shared by {@link resolveKey} and {@link activeAccount}.
+   */
+  private probeAllMarked;
   /** Hand out the chosen account's key. */
   private pick;
 }
@@ -821,7 +944,7 @@ declare const KNOWN_EFFORTS: Readonly<Record<string, readonly string[]>>;
 declare const KNOWN_IMAGE_MODELS: ReadonlySet<string>;
 /**
  * Models WITHOUT a zero-data-retention upstream, per the official CLI's own
- * registry (`command-code@1.68.0` `dist/cli.mjs`): `modelSupportsZdr(id)` is
+ * registry (`command-code@1.73.0` `dist/cli.mjs`): `modelSupportsZdr(id)` is
  * exactly `!nonZdrSet.has(canonicalize(id))`, and `knownModelSupportsZdr`
  * carries the same membership in the sibling route table — the UNION of both
  * is this set. Reading only the sibling route table would drop `meituan/
@@ -882,7 +1005,7 @@ declare const KNOWN_THINKING_MODELS: ReadonlySet<string>;
  * `/docs/plans/max` and `/docs/resources/pricing-limits`). Each plan's model
  * list is a superset of the one below it: Go ⊂ GOAT ⊂ Pro ⊂ Provider/Max.
  * Models absent from every plan list (Claude Opus/Fable, Fugu Ultra) are
- * Provider-tier. Re-verified at command-code@1.68.0 (2026-09-29): 84 catalog
+ * Provider-tier. Re-verified at command-code@1.73.0 (2026-10-01): 86 catalog
  * ids at 53/62/76/84 cumulative, a strict superset chain — every release since
  * 1.49.0 has been additive with no tier move, and per-entry tags below name the
  * release that added each row.
@@ -911,7 +1034,7 @@ declare function compareByPlan(a: {
 /**
  * Subscription plan table, synced from the official CLI bundle's plan maps
  * (located by the `"individual-go"` key in `dist/cli.mjs`, re-verified unchanged
- * through command-code@1.68.0): subscription `planId` prefix → display name and
+ * through command-code@1.73.0): subscription `planId` prefix → display name and
  * the plan's monthly credit total. This is the account's own subscription
  * (from `/alpha/billing/subscriptions`) — distinct from {@link KNOWN_PLANS},
  * which maps catalog models to their minimum tier.
@@ -1107,11 +1230,11 @@ interface CommandCodeCatalogModel {
    * Per-model MONTHLY allowance in USD: how much of the plan's monthly credit
    * pool this one model may draw, already resolved by the Host against the
    * account pool's highest plan (the pricing page publishes an allowance for
-   * GOAT and Pro only). Undefined when that plan has no published allowance
+   * Go, GOAT and Pro). Undefined when that plan has no published allowance
    * (Go, Provider, Max, Ultra) or when billing could not be read — the browser
    * shows nothing rather than guessing a neighbouring tier's figure.
    *
-   * Deliberately a plain number and not the `{ goat, pro }` pair: the bracket is
+   * Deliberately a plain number and not the `{ go, goat, pro }` map: the bracket is
    * a Host decision that already depends on facts the browser does not hold, and
    * shipping both figures would invite a second, divergent rule here. Note this
    * is dollars per MONTH, unlike every rate in `CommandCodePriceTable`.
@@ -1365,7 +1488,7 @@ declare class CommandCodeUsageService<C extends CommandCodeConnectionOptions = C
 declare function applyUsageRemote<C extends CommandCodeConnectionOptions>(ctx: Context, deps: CommandCodeUsageDeps<C>): void;
 //#endregion
 //#region src/login.d.ts
-/** Give up on the browser after this long without a callback (mirrors the CLI). */
+/** 登录总期限包含浏览器回调、密钥验证与存储，不能在收到回调后撤掉保护。 */
 declare const LOGIN_TIMEOUT_MS = 120000;
 /** First local port the flow tries (mirrors the CLI). */
 declare const LOGIN_START_PORT = 5959;
@@ -1428,7 +1551,7 @@ declare function studioBaseForApiBase(apiBase: string): string;
  * tests). Mirrors the CLI's verdicts: 401 → invalid_key, other non-OK →
  * server_error, transport failure → network_error.
  */
-declare function validateCommandApiKey(fetchImpl: typeof fetch, apiBase: string, apiKey: string): Promise<ApiKeyValidation>;
+declare function validateCommandApiKey(fetchImpl: typeof fetch, apiBase: string, apiKey: string, signal?: AbortSignal): Promise<ApiKeyValidation>;
 /**
  * One browser-login attempt machine. Single-flight by design: `begin()` while
  * waiting returns the live attempt's status instead of starting a second one;
@@ -1443,6 +1566,7 @@ declare class CommandCodeLoginFlow {
   private statusValue;
   private server;
   private timer;
+  private attemptAbort;
   /** Settle hooks of the live attempt's callback promise. */
   private settle;
   /**
@@ -1522,7 +1646,9 @@ declare class CommandCodeLoginFlow {
   /** Map a tagged settle rejection onto the status face. */
   private failFrom;
   private clearTimer;
-  /** Close the server and watchdog without touching the published status. */
+  /** 消费一次回调后关闭监听；保留总期限以约束后续验证。 */
+  private closeCallback;
+  /** 结束整个尝试，同时中止验证请求，迟到结果由所有权检查拦截。 */
   private teardown;
 }
 //#endregion
@@ -1798,9 +1924,9 @@ interface Config {
   offloadSeenImagesForCache?: boolean;
   /**
    * 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; a transport failure is not
+   * defaults to 5. The route's policy allows long waits for confirmed usage
+   * windows, while ordinary transient errors have a separate three-retry
+   * budget. A transport failure is not
    * one of those, and after ~15.5 s of grace the wait is pure stall, so it is
    * capped here (issue #39). 0 surfaces every transport failure immediately.
    */