@mars-sea/dsh-commandcode-provider 0.4.2 → 0.5.0

package/lib/index.d.ts

@@ -24,7 +24,7 @@ declare const KNOWN_EFFORTS: Readonly<Record<string, readonly string[]>>;
  */
 declare const KNOWN_IMAGE_MODELS: ReadonlySet<string>;
 /**
- * Models the official CLI's model table (`ZA` in command-code@1.27.1) marks
+ * Models the official CLI's model table (`ZA` in command-code@1.28.1) marks
  * `reasoning:!0` but defines no selectable `reasoning_effort` levels — they
  * think automatically, with Command Code driving the depth. This is the
  * authoritative "thinks, effort not adjustable" set: `KNOWN_EFFORTS` (which
@@ -32,7 +32,7 @@ declare const KNOWN_IMAGE_MODELS: ReadonlySet<string>;
  * effort levels, and this snapshot is not surfaced in the picker's compact
  * description — it exists for programmatic consumers.
  *
- * Source: the command-code@1.27.1 bundled model table (dist/cli.mjs, the `ZA`
+ * Source: the command-code@1.28.1 bundled model table (dist/cli.mjs, the `ZA`
  * object), cross-checked with https://commandcode.ai/docs/reference/cli/models.
  * Keep in sync via the dsh-commandcode-upstream skill.
  */
@@ -73,7 +73,7 @@ declare function compareByPlan(a: {
 }): number;
 /**
  * Subscription plan table, synced from the official CLI bundle's plan maps
- * (`Nn`/`$n` in command-code@1.27.1 `dist/cli.mjs`): subscription `planId`
+ * (`Nn`/`$n` in command-code@1.28.1 `dist/cli.mjs`): 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.
@@ -172,7 +172,7 @@ declare function peakPricingState(modelId: string, now?: number): 'peak' | 'off-
  * for models without time-of-day pricing.
  */
 declare function peakPricingLabel(modelId: string, now?: number): string | undefined;
-declare const COMMAND_CODE_CLI_VERSION = "1.27.1";
+declare const COMMAND_CODE_CLI_VERSION = "1.28.1";
 declare const DEFAULT_API_BASE = "https://api.commandcode.ai";
 declare const DEFAULT_GENERATE_MAX_TOKENS = 64000;
 declare const DEFAULT_MAX_OUTPUT_TOKENS = 65536;
@@ -248,6 +248,15 @@ interface CommandCodeAdapterDeps<C extends CommandCodeConnectionOptions = Comman
   options: () => C;
   /** Resolve a usable API key for the given connection facts, or throw `MISSING_CREDENTIAL`. */
   resolveApiKey: (connection: C) => Promise<string>;
+  /**
+   * Multi-account rotation hook: the request sent with `rejectedKey` was
+   * refused with 429 (`rate-limit`) or 401 (`invalid-credential`) before
+   * any response body streamed. The host marks that key and returns the next
+   * account's key to retry with, or `undefined` to surface the failure.
+   * Only pre-stream rejections rotate — a mid-stream failure never replays a
+   * partially consumed generation against another account.
+   */
+  rotateApiKey?: (rejectedKey: string, rejection: 'rate-limit' | 'invalid-credential', connection: C) => Promise<string | undefined>;
   /** HTTP transport override (tests); defaults to the global `fetch`. */
   fetchImpl?: typeof fetch;
   /** Resolve the optional durable attachment service for image input (tests); defaults to none. */
@@ -318,8 +327,8 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
   private catalog;
   private readonly fetchImpl;
   private readonly resolveAttachments;
-  private billingAccess;
-  private billingAccessInflight;
+  private readonly billingAccess;
+  private readonly billingAccessInflight;
   constructor(deps: CommandCodeAdapterDeps<C>);
   /**
    * Command Code is a metered subscription API: 429 (rate limit) and 5xx
@@ -359,16 +368,204 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
    * Each endpoint degrades independently: a failed one lands in `failures`
    * while the rest still report, so a transient outage never blanks the whole
    * view. Requires a usable API key (throws `MISSING_CREDENTIAL` otherwise).
+   * Pass `apiKey` to report on a specific account of a multi-account pool;
+   * the default resolves the currently active account.
    */
-  getUsage(): Promise<CommandCodeUsageReport>;
+  getUsage(apiKey?: string): Promise<CommandCodeUsageReport>;
+  /**
+   * Probe one account's five-hour window from `/alpha/billing/credits`. The
+   * multi-account pool calls this when every account is marked exhausted: an
+   * account whose window no longer reports `exceeded` is revived, and the
+   * `resetAt` values feed the "earliest reset" error message. Returns
+   * `undefined` when the probe itself failed (transport, non-200, or a
+   * payload without window limits) — a failed probe never changes pool state.
+   */
+  probeFiveHourWindow(apiKey: string): Promise<{
+    exceeded: boolean;
+    resetAt: number;
+  } | undefined>;
   stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }
 //#endregion
+//#region src/accounts.d.ts
+/** One extra account's raw configuration (composition config or settings). */
+interface CommandCodeAccountConfig {
+  /** Display label shown in the usage dashboard and settings page. */
+  label?: string;
+  /** Credential reference (environment-variable style name) holding this account's API key. */
+  apiKeyEnv?: string;
+  /** Literal API key (composition config only; never stored in settings). */
+  apiKey?: string;
+}
+/** One account slot after config normalization. */
+interface CommandCodeAccountSlot {
+  /** Stable id: `default` for the implicit first account, `account-N` for extras. */
+  id: string;
+  /** Display label (user-provided or generated). */
+  label: string;
+  /** Credential reference resolved through the seam; undefined for literal-only slots. */
+  ref?: CredentialRef | undefined;
+  /** Literal key from composition config. */
+  literal?: string | undefined;
+  /** Whether the official CLI auth file may back this slot (default slot only). */
+  allowAuthFile: boolean;
+}
+/** Why a key stopped serving requests. */
+type AccountRejection = 'rate-limit' | 'invalid-credential';
+/** One key's rotation state. */
+interface CommandCodeAccountState {
+  kind:
+  /** Marked by a 429; the window's reset time is unknown until probed. */
+  'unknown' |
+  /** Probed (or marked with a known reset): unusable until `until` (millis). */
+  'cooldown' |
+  /** Marked by a 401: skipped until the stored credential changes. */
+  'disabled';
+  /** Human-readable reason for the mark (e.g. `rate limited (429)`). */
+  reason: string;
+  /** Cooldown end in millis; 0 for the other kinds. */
+  until: number;
+}
+/** A slot paired with its resolved key (both pool-internal and UI-facing). */
+interface ResolvedAccount {
+  slot: CommandCodeAccountSlot;
+  key: string;
+  /** The key's current rotation state; undefined means usable. */
+  state: CommandCodeAccountState | undefined;
+}
+/** Five-hour window facts probed from `/alpha/billing/credits`. */
+interface FiveHourWindowProbe {
+  exceeded: boolean;
+  resetAt: number;
+}
+/** Everything the pool needs from the host; all seams are injected. */
+interface CommandCodeAccountPoolDeps {
+  /** The current account slots, re-read per resolution so settings changes apply live. */
+  slots(): readonly CommandCodeAccountSlot[];
+  /** Resolve one credential reference through the credentials service or the launch environment. */
+  resolveRef(ref: CredentialRef): Promise<string | undefined>;
+  /** The official CLI auth-file key (`~/.commandcode/auth.json`); default slot only. */
+  authFileKey(): string | undefined;
+  /** Probe one key's five-hour window; undefined when the probe itself failed. */
+  probeWindow(apiKey: string): Promise<FiveHourWindowProbe | undefined>;
+  /**
+   * The manually selected account (a slot id, e.g. `default` or an extra's
+   * credential reference), re-read per resolution. The preferred account
+   * serves whenever it is usable; an unknown id or an exhausted preferred
+   * account falls back to the first usable slot.
+   */
+  preferredId?(): string | undefined;
+}
+/**
+ * Whether an account with this rotation state can serve a request right now.
+ * `undefined` (never rejected) is usable; a cooldown becomes usable again
+ * once its reset time passes; `unknown` (429, reset unprobed) and
+ * `disabled` (401) are not.
+ */
+declare function accountUsable(state: CommandCodeAccountState | undefined): boolean;
+/**
+ * Pick the account that should serve now: the manually preferred slot when it
+ * is usable, otherwise the first usable account in rotation order; undefined
+ * when no account is usable. Shared by the pool (request path) and the plugin
+ * entry (the usage view's active badge) so both always agree.
+ */
+declare function selectActiveAccount(accounts: readonly ResolvedAccount[], preferredId: string | undefined): ResolvedAccount | undefined;
+/**
+ * The account pool. Rotation state is keyed by API key (never logged), so two
+ * slots resolving to the same credential share one mark, and a key changed in
+ * the credentials service starts with a clean slate.
+ */
+declare class CommandCodeAccountPool {
+  private readonly deps;
+  /** Rotation state by API key. */
+  private readonly states;
+  constructor(deps: CommandCodeAccountPoolDeps);
+  /**
+   * Resolve every slot's key, deduplicated by key (first slot wins). Slots
+   * without any resolvable key are omitted — they still appear in the
+   * settings page as unconfigured, they just cannot serve requests.
+   */
+  resolvedAccounts(): Promise<ResolvedAccount[]>;
+  /**
+   * Every slot paired with its resolved key and rotation state — NOT
+   * deduplicated: two slots sharing one credential both appear (the usage
+   * view reports them individually), while slots without any resolvable key
+   * are omitted. The serving path uses {@link resolvedAccounts} instead.
+   */
+  describeAccounts(): Promise<ResolvedAccount[]>;
+  /**
+   * Hand out the first usable account's key (the manually preferred account
+   * when usable, else rotation order). Returns `undefined` when no account
+   * resolves any key at all (the caller then reports the missing credential).
+   * Throws `RATE_LIMIT` — naming the earliest window reset — or
+   * `INVALID_CREDENTIAL` when accounts exist but none can serve.
+   *
+   * `options.exclude` skips one key during the probe-revival pass: the
+   * rotation hook excludes the just-rejected key so a probe that clears its
+   * window cannot re-offer the same key within the same request (the adapter
+   * refuses already-tried keys; the next request picks the revived key up).
+   */
+  resolveKey(options?: {
+    exclude?: string;
+  }): Promise<{
+    key: string;
+    slot: CommandCodeAccountSlot;
+  } | undefined>;
+  /**
+   * Record a rejection against one key. `rate-limit` (429) marks the key
+   * exhausted with an unknown reset (probed lazily at the next resolution
+   * once every account is marked); `invalid-credential` (401) disables the
+   * key until the stored credential changes.
+   */
+  markRejected(apiKey: string, rejection: AccountRejection): void;
+  /** One account's key: literal → credential seam → auth file (default slot). */
+  private resolveSlotKey;
+  /** Hand out the chosen account's key. */
+  private pick;
+}
+//#endregion
+//#region src/usage-wire.d.ts
+/** One account's usage entry in the multi-account report. */
+interface CommandCodeAccountUsage {
+  /** Stable slot id (`default`, `account-2`, …). */
+  id: string;
+  /** Display label (user-provided or generated). */
+  label: string;
+  /** Whether an API key resolved for this account. */
+  configured: boolean;
+  /** Whether this account currently serves requests (first usable slot). */
+  active: boolean;
+  /** Rotation mark: `''` (usable), `'rate-limit'`, or `'invalid-credential'`. */
+  mark: string;
+  /** Known cooldown end in millis; 0 when unknown or not cooling down. */
+  cooldownUntil: number;
+  /** The per-account report; `failures`-only when the fetch itself failed. */
+  report: CommandCodeUsageReport;
+}
+/** The settings page's account card data: one entry per configured account. */
+interface CommandCodeAccountsReport {
+  accounts: CommandCodeAccountUsage[];
+}
+/** Canonical `<namespace>/<method>` endpoint of the usage report Remote. */
+declare const USAGE_REPORT_ENDPOINT = "commandcode/report";
+/**
+ * The strict result codec both halves attach to the descriptor. Hand-rolled:
+ * the client bundle may not require a schema library, and `TypertSchema` is
+ * deliberately minimal so one `parse` function satisfies it.
+ */
+declare const usageReportSchema: TypertSchema<CommandCodeAccountsReport>;
+//#endregion
 //#region src/commands.d.ts
 /** Everything the command needs beyond the adapter itself. */
 interface CommandCodeCommandDeps<C extends CommandCodeConnectionOptions = CommandCodeConnectionOptions> {
   /** The registered adapter (for getUsage / listModels). */
   adapter: CommandCodeAdapter<C>;
+  /**
+   * Multi-account report source (wired by the plugin entry). Absent in
+   * programmatic setups, the command falls back to a single
+   * `adapter.getUsage()` report.
+   */
+  reports?: () => Promise<CommandCodeAccountsReport>;
 }
 /** The one registered `/commandcode` command. */
 declare function commandDefinition<C extends CommandCodeConnectionOptions>(deps: CommandCodeCommandDeps<C>): CommandDefinition;
@@ -380,6 +577,12 @@ declare function applyCommands<C extends CommandCodeConnectionOptions>(ctx: Cont
 interface CommandCodeUsageDeps<C extends CommandCodeConnectionOptions = CommandCodeConnectionOptions> {
   /** The registered adapter (for getUsage). */
   adapter: CommandCodeAdapter<C>;
+  /**
+   * Multi-account report source (wired by the plugin entry). Absent in
+   * programmatic setups, the service falls back to a single default-account
+   * entry around `adapter.getUsage()`.
+   */
+  reports?: () => Promise<CommandCodeAccountsReport>;
 }
 /**
  * The Remote receiver: a Cordis service the Gateway resolves by key
@@ -392,12 +595,14 @@ declare class CommandCodeUsageService<C extends CommandCodeConnectionOptions = C
   private readonly deps;
   constructor(ctx: Context, deps: CommandCodeUsageDeps<C>);
   /**
-   * Account, usage, and credit state for the settings page's account card.
-   * Degrades per endpoint like the `/commandcode` command (failures land in
-   * `report.failures`); throws `MISSING_CREDENTIAL` when no key resolves, which
-   * the Gateway folds into the failure branch the page renders as a hint.
+   * Account, usage, and credit state for the settings page's account card —
+   * one entry per pool account when the plugin entry wired `reports`, a
+   * single default-account entry otherwise. Degrades per endpoint like the
+   * `/commandcode` command (failures land in `report.failures`); throws
+   * `MISSING_CREDENTIAL` when no key resolves, which the Gateway folds into
+   * the failure branch the page renders as a hint.
    */
-  report(): Promise<CommandCodeUsageReport>;
+  report(): Promise<CommandCodeAccountsReport>;
 }
 /**
  * Provide the usage service and register its Remote descriptor. The registry
@@ -406,16 +611,6 @@ declare class CommandCodeUsageService<C extends CommandCodeConnectionOptions = C
  */
 declare function applyUsageRemote<C extends CommandCodeConnectionOptions>(ctx: Context, deps: CommandCodeUsageDeps<C>): void;
 //#endregion
-//#region src/usage-wire.d.ts
-/** Canonical `<namespace>/<method>` endpoint of the usage report Remote. */
-declare const USAGE_REPORT_ENDPOINT = "commandcode/report";
-/**
- * The strict result codec both halves attach to the descriptor. Hand-rolled:
- * the client bundle may not require a schema library, and `TypertSchema` is
- * deliberately minimal so one `parse` function satisfies it.
- */
-declare const usageReportSchema: TypertSchema<CommandCodeUsageReport>;
-//#endregion
 //#region src/index.d.ts
 declare const name = "llm-commandcode";
 declare const inject: string[];
@@ -452,6 +647,24 @@ interface Config {
    * full catalog visible). Set false to always list every model.
    */
   filterModelsByPlan?: boolean;
+  /**
+   * Extra accounts for multi-account rotation. The top-level
+   * `apiKey`/`apiKeyEnv` (plus the CLI auth file) always form the first
+   * (`default`) account; each entry here adds one more. When a request is
+   * rejected pre-stream with 429 (usage window exhausted) or 401, the next
+   * account's key retried transparently; when every account is exhausted the
+   * request fails with a `RATE_LIMIT` error naming the earliest window
+   * reset. Entries without `apiKey` or `apiKeyEnv` are ignored.
+   */
+  accounts?: CommandCodeAccountConfig[];
+  /**
+   * Manually selected active account: a slot id — `default`, or an extra
+   * account's credential reference (e.g. `COMMANDCODE_API_KEY_2`). The
+   * selected account serves whenever it is usable; an unknown id or an
+   * exhausted selected account falls back to the first usable slot (automatic
+   * rotation still applies). Unset means "first usable account".
+   */
+  activeAccount?: string;
 }
 declare const Config: z<Config>;
 /** One resolution's complete request facts: connection plus credential reference. */
@@ -467,5 +680,5 @@ interface ResolvedCommandCodeOptions extends CommandCodeConnectionOptions {
 declare function resolveAdapterOptions(config: Config): ResolvedCommandCodeOptions;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { BILLING_ACCESS_TTL_MS, COMMAND_CODE_CLI_VERSION, CommandCodeAdapter, type CommandCodeAdapterDeps, type CommandCodeBillingAccess, type CommandCodeCommandDeps, type CommandCodeConnectionOptions, type CommandCodeUsageDeps, type CommandCodeUsageReport, CommandCodeUsageService, Config, DEFAULT_API_BASE, DEFAULT_GENERATE_MAX_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_MODELS_CACHE_PATH, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, KNOWN_DEALS, KNOWN_EFFORTS, KNOWN_IMAGE_MODELS, KNOWN_PEAK_PRICING, KNOWN_PLANS, KNOWN_SUBSCRIPTION_PLANS, KNOWN_THINKING_MODELS, PLAN_LABELS, PLAN_ORDER, PROVIDER, type ResolveAttachments, ResolvedCommandCodeOptions, USAGE_REPORT_ENDPOINT, apply, applyCommands, applyUsageRemote, capabilityDescription, commandDefinition, compareByPlan, dealLabel, formatContext, inject, modelVisibleInPlan, name, peakPricingLabel, peakPricingState, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey, subscriptionPlanInfo, usageReportSchema };
+export { BILLING_ACCESS_TTL_MS, COMMAND_CODE_CLI_VERSION, type CommandCodeAccountConfig, CommandCodeAccountPool, type CommandCodeAccountSlot, type CommandCodeAccountState, type CommandCodeAccountUsage, type CommandCodeAccountsReport, CommandCodeAdapter, type CommandCodeAdapterDeps, type CommandCodeBillingAccess, type CommandCodeCommandDeps, type CommandCodeConnectionOptions, type CommandCodeUsageDeps, type CommandCodeUsageReport, CommandCodeUsageService, Config, DEFAULT_API_BASE, DEFAULT_GENERATE_MAX_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_MODELS_CACHE_PATH, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, KNOWN_DEALS, KNOWN_EFFORTS, KNOWN_IMAGE_MODELS, KNOWN_PEAK_PRICING, KNOWN_PLANS, KNOWN_SUBSCRIPTION_PLANS, KNOWN_THINKING_MODELS, PLAN_LABELS, PLAN_ORDER, PROVIDER, type ResolveAttachments, ResolvedCommandCodeOptions, USAGE_REPORT_ENDPOINT, accountUsable, apply, applyCommands, applyUsageRemote, capabilityDescription, commandDefinition, compareByPlan, dealLabel, formatContext, inject, modelVisibleInPlan, name, peakPricingLabel, peakPricingState, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey, selectActiveAccount, subscriptionPlanInfo, usageReportSchema };
 //# sourceMappingURL=index.d.ts.map