@mars-sea/dsh-commandcode-provider 0.2.4 → 0.4.0

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import z from "@deepseek-ai/schemastery";
 import { GenerateOptions, LlmAdapter, LlmModelInfo, LlmResolvedModelInfo, ResolvedRetryPolicy, StreamChunk } from "@deepseek-ai/dsh-llm";
 import { CredentialRef } from "@deepseek-ai/dsh-credentials";
+import { TypertRemoteService, TypertSchema } from "@deepseek-ai/dsh-typert-protocol";
 import { Context } from "@deepseek-ai/cordis";
 import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
 import { CommandDefinition } from "@deepseek-ai/dsh-commands";
@@ -70,6 +71,56 @@ declare function compareByPlan(a: {
   id: string;
   name: string;
 }): number;
+/**
+ * Subscription plan table, synced from the official CLI bundle's plan maps
+ * (`Nn`/`$n` in command-code@1.26.0 `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.
+ *
+ * `tierWeight` is plugin-added (not from the CLI maps): the plan's rank on
+ * the {@link PLAN_ORDER} scale, used by the picker's plan filter
+ * ({@link modelVisibleInPlan}) to hide models above the account's tier.
+ */
+declare const KNOWN_SUBSCRIPTION_PLANS: Readonly<Record<string, {
+  name: string;
+  monthlyCredits: number;
+  tierWeight: number;
+}>>;
+/**
+ * Resolve a subscription `planId` (e.g. `individual-pro-v1`) to its display
+ * name and monthly credit total, mirroring the CLI's `getPlanInfo`:
+ * normalize (lowercase, `_` → `-`), then longest-prefix match so
+ * `individual-pro-v1` wins over `individual-pro`. Unknown ids return
+ * `undefined`.
+ */
+declare function subscriptionPlanInfo(planId: string): {
+  name: string;
+  monthlyCredits: number;
+  tierWeight: number;
+} | undefined;
+/**
+ * The billing facts the picker's plan filter needs, fetched by mirroring the
+ * CLI's `createBilling` flow (whoami → orgId, then `/alpha/billing/subscriptions`
+ * for the plan id and `/alpha/billing/credits` for the on-demand balances).
+ */
+interface CommandCodeBillingAccess {
+  /** Account plan tier weight on the {@link PLAN_ORDER} scale; undefined when the plan is unknown. */
+  tierWeight: number | undefined;
+  /**
+   * Purchased + free on-demand credit balance. The official access model
+   * (`evaluateModelAccess` in the CLI) allows every model when the account
+   * holds any on-demand credits — the plan gate only applies at zero balance.
+   */
+  onDemandCredits: number;
+}
+/**
+ * Whether the picker lists `modelId` for an account with the given billing
+ * access. Fails open at every uncertainty: no billing data, an unknown plan,
+ * or a model outside {@link KNOWN_PLANS} all keep the model visible — the
+ * server remains the final gate (`403 MODEL_NOT_IN_PLAN`).
+ */
+declare function modelVisibleInPlan(modelId: string, access: CommandCodeBillingAccess | undefined): boolean;
 /**
  * Active pricing deals per the official pricing page
  * (`/docs/resources/pricing-limits#deals`). Each entry records the model's
@@ -95,10 +146,38 @@ interface KnownDeal {
   free?: boolean;
 }
 declare const KNOWN_DEALS: Readonly<Record<string, KnownDeal>>;
+/**
+ * Models with time-of-day (peak/off-peak) pricing, per the official pricing
+ * page (`/docs/resources/pricing-limits`). Since 2026-08-16 16:00 UTC, DeepSeek
+ * charges by the hour: peak hours are 01:00–04:00 and 06:00–10:00 UTC (7h/day,
+ * full price); the other 17 hours are off-peak at half price. The picker shows
+ * the *current* state as a compact label (`Peak`/`Half`) matching the English
+ * noun style of the other markers (`Image`, `FREE`), so a developer can tell at
+ * a glance whether calling the model right now is cheap or expensive.
+ *
+ * Keep in sync with the official pricing page when the model set or the peak
+ * windows change (see the dsh-commandcode-upstream skill).
+ */
+declare const KNOWN_PEAK_PRICING: ReadonlySet<string>;
+/**
+ * Whether `now` (defaults to `Date.now()`) falls in a peak-pricing hour for
+ * time-of-day-priced models. `undefined` for models outside the snapshot.
+ */
+declare function peakPricingState(modelId: string, now?: number): 'peak' | 'off-peak' | undefined;
+/**
+ * Compact label for the current peak/off-peak state: `Peak` (full price) or
+ * `Half` (off-peak, half price). These English nouns match the picker's other
+ * markers (`Go`, `Image`, `FREE`), and since they appear only on time-of-day
+ * priced models they double as a "priced by the hour" signal. Returns undefined
+ * for models without time-of-day pricing.
+ */
+declare function peakPricingLabel(modelId: string, now?: number): string | undefined;
 declare const COMMAND_CODE_CLI_VERSION = "1.26.0";
 declare const DEFAULT_API_BASE = "https://api.commandcode.ai";
 declare const DEFAULT_GENERATE_MAX_TOKENS = 64000;
 declare const DEFAULT_MAX_OUTPUT_TOKENS = 65536;
+/** How long the picker's plan-filter billing facts stay cached before refetching. */
+declare const BILLING_ACCESS_TTL_MS: number;
 /** Head-of-request timeout: how long to wait for the first response byte. */
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
 /** Stream idle timeout: a generation that stalls this long is a dead connection. */
@@ -124,9 +203,10 @@ declare function dealLabel(modelId: string, now?: number): string | undefined;
 declare function formatContext(contextWindow: number | undefined): string | undefined;
 /**
  * Compact one-line summary for the model picker: plan tier, then any active
- * deal (discount or FREE), then `Image` for Vision-capable models, then the
- * context window. Text-only models simply omit the Image marker — "Text only"
- * adds nothing the picker needs to show.
+ * deal (discount or FREE), then the current peak/off-peak state (`Peak`/`Half`)
+ * for time-of-day-priced models, then `Image` for Vision-capable models, then
+ * the context window. Text-only models simply omit the Image marker — "Text
+ * only" adds nothing the picker needs to show.
  */
 declare function capabilityDescription(modelId: string, contextWindow?: number, now?: number): string;
 declare function projectSlugFromPath(pathName: string): string;
@@ -148,6 +228,13 @@ interface CommandCodeConnectionOptions {
   requestTimeoutMs: number;
   /** Milliseconds a stream may stall before it is treated as a dead connection (default 300s). */
   streamIdleTimeoutMs: number;
+  /**
+   * Whether the picker hides models above the account's subscription tier
+   * (default true). The filter fails open: unknown plan, billing-endpoint
+   * failure, a positive on-demand credit balance, or an unmapped model all
+   * keep the full catalog visible. Set false to always list every model.
+   */
+  filterModelsByPlan?: boolean;
 }
 /**
  * Resolve the durable attachment service, or undefined when the host does not
@@ -204,11 +291,25 @@ interface CommandCodeCredits {
     resetAt: number;
   };
 }
+/** Subscription plan state from `/alpha/billing/subscriptions`. */
+interface CommandCodePlan {
+  /** Raw subscription plan id (e.g. `individual-pro`); empty when unreported. */
+  planId: string;
+  /** Display name (e.g. `Pro`); falls back to the raw id for unknown plans. */
+  name: string;
+  /** Raw subscription status (`active`, `trialing`, `past_due`, …); empty when unreported. */
+  status: string;
+  /** The plan's monthly credit total per {@link KNOWN_SUBSCRIPTION_PLANS}; null for unknown plans. */
+  monthlyCredits: number | null;
+  /** Billing period end in millis; 0 when the endpoint did not report one. */
+  currentPeriodEnd: number;
+}
 /** Everything the usage endpoints report, fetched together. */
 interface CommandCodeUsageReport {
   account?: CommandCodeAccount;
   usage?: CommandCodeUsage;
   credits?: CommandCodeCredits;
+  plan?: CommandCodePlan;
   /** Endpoint failures degrade the report instead of failing it. */
   failures: string[];
 }
@@ -217,6 +318,8 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
   private catalog;
   private readonly fetchImpl;
   private readonly resolveAttachments;
+  private billingAccess;
+  private billingAccessInflight;
   constructor(deps: CommandCodeAdapterDeps<C>);
   /**
    * Command Code is a metered subscription API: 429 (rate limit) and 5xx
@@ -231,9 +334,28 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
   private loadCatalog;
   listModels(provider: string): Promise<readonly LlmModelInfo[]>;
   resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+  /** The headers every authenticated account endpoint shares. */
+  private accountHeaders;
+  /**
+   * The billing facts behind the picker's plan filter, cached for
+   * {@link BILLING_ACCESS_TTL_MS} and shared across concurrent callers.
+   * `undefined` means "unknown — show everything" (fail-open).
+   */
+  private loadBillingAccess;
+  /**
+   * The billing facts behind the picker's plan filter, mirroring the CLI's
+   * `createBilling` flow: whoami yields the org id, then the subscriptions
+   * and credits endpoints answer in parallel. The plan id is honored only
+   * when the subscription reports an active-ish status (the CLI's rule); when
+   * the subscriptions endpoint fails entirely, `credits.planId` is the
+   * fallback (the CLI stamps plan identity from it too). Any failure resolves
+   * to `undefined` (fail-open) rather than breaking the picker.
+   */
+  private fetchBillingAccess;
   /**
-   * Fetch account, usage, and credit state from the Command Code account
-   * endpoints (`/alpha/whoami`, `/alpha/usage/summary`, `/alpha/billing/credits`).
+   * Fetch account, usage, credit, and subscription state from the Command
+   * Code account endpoints (`/alpha/whoami`, `/alpha/usage/summary`,
+   * `/alpha/billing/credits`, `/alpha/billing/subscriptions`).
    * 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).
@@ -253,6 +375,47 @@ declare function commandDefinition<C extends CommandCodeConnectionOptions>(deps:
 /** Register the command on `ctx.commands` (called from the plugin entry). */
 declare function applyCommands<C extends CommandCodeConnectionOptions>(ctx: Context, deps: CommandCodeCommandDeps<C>): void;
 //#endregion
+//#region src/usage-remote.d.ts
+/** Everything the usage service needs beyond its Cordis context. */
+interface CommandCodeUsageDeps<C extends CommandCodeConnectionOptions = CommandCodeConnectionOptions> {
+  /** The registered adapter (for getUsage). */
+  adapter: CommandCodeAdapter<C>;
+}
+/**
+ * The Remote receiver: a Cordis service the Gateway resolves by key
+ * (`commandcodeUsage`) and binds to the wire namespace (`commandcode`). The
+ * base class stamps the `typertRemote` binding the Gateway validates on every
+ * dispatch; no decorators are needed because the descriptor is registered
+ * explicitly (strict path) rather than discovered from source markers.
+ */
+declare class CommandCodeUsageService<C extends CommandCodeConnectionOptions = CommandCodeConnectionOptions> extends TypertRemoteService {
+  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.
+   */
+  report(): Promise<CommandCodeUsageReport>;
+}
+/**
+ * Provide the usage service and register its Remote descriptor. The registry
+ * contribution is tied to this fiber's lifetime: the registry's own
+ * `register()` effect would otherwise outlive the plugin.
+ */
+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[];
@@ -282,6 +445,13 @@ interface Config {
   requestTimeoutMs?: number;
   /** Milliseconds a stream may stall before being treated as a dead connection; defaults to 300s. */
   streamIdleTimeoutMs?: number;
+  /**
+   * Whether the model picker hides models above the account's subscription
+   * tier; defaults to true. The filter fails open (unknown plan, billing
+   * endpoint failure, or a positive on-demand credit balance all keep the
+   * full catalog visible). Set false to always list every model.
+   */
+  filterModelsByPlan?: boolean;
 }
 declare const Config: z<Config>;
 /** One resolution's complete request facts: connection plus credential reference. */
@@ -297,5 +467,5 @@ interface ResolvedCommandCodeOptions extends CommandCodeConnectionOptions {
 declare function resolveAdapterOptions(config: Config): ResolvedCommandCodeOptions;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { COMMAND_CODE_CLI_VERSION, CommandCodeAdapter, type CommandCodeAdapterDeps, type CommandCodeCommandDeps, type CommandCodeConnectionOptions, type CommandCodeUsageReport, 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_PLANS, KNOWN_THINKING_MODELS, PLAN_LABELS, PLAN_ORDER, PROVIDER, type ResolveAttachments, ResolvedCommandCodeOptions, apply, applyCommands, capabilityDescription, commandDefinition, compareByPlan, dealLabel, formatContext, inject, name, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey };
+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 };
 //# sourceMappingURL=index.d.ts.map