@mars-sea/dsh-commandcode-provider 0.10.1 → 0.10.2

package/lib/index.d.ts

@@ -24,7 +24,7 @@ declare function projectSlugFromPath(pathName: string): string;
 declare function resolveAuthFileApiKey(): string | undefined;
 /** Connection facts resolved fresh per request by the plugin entry. */
 interface CommandCodeConnectionOptions {
-  /** API base; the Provider API lives under it (`/alpha/generate`, `/provider/v1/models`). */
+  /** API base; the Provider API lives under it (`/alpha/generate`, `/provider/v1/chat/completions`, `/provider/v1/models`). */
   apiBase: string;
   /** Working directory reported to the API (project slug, config block). */
   workingDir: string;
@@ -46,10 +46,20 @@ interface CommandCodeConnectionOptions {
    */
   filterModelsByPlan?: boolean;
   /**
-   * Optional protocol override. `'auto'` (default) uses billing/cache plus
-   * Provider API fallback; `'cli'` forces `/alpha/generate`; `'openai'` forces
-   * `/provider/v1/chat/completions`. This is a connection-level test/operator
-   * seam and is intentionally not part of the plugin's user settings schema.
+   * Visible-model allowlist: catalog model ids shown in pickers. Empty or
+   * unset means "show everything"; applies after the subscription-tier filter.
+   * The settings page persists it; the catalog endpoint serves the full
+   * catalog regardless so the page can always offer every model.
+   */
+  visibleModels?: string[] | undefined;
+  /**
+   * Optional protocol hint. `'auto'` (default) uses billing/cache plus
+   * Provider API fallback; `'cli'` forces `/alpha/generate`; `'openai'`
+   * prefers `/provider/v1/chat/completions` but still falls back to the CLI
+   * transport on `upgrade_required` (Go-plan keys have no Provider API
+   * access — failing outright would strand them). This is a
+   * connection-level test/operator seam and is intentionally not part of
+   * the plugin's user settings schema.
    */
   protocol?: 'auto' | CommandCodeProtocol;
 }
@@ -193,10 +203,20 @@ declare class CommandCodeAdapter<C extends CommandCodeConnectionOptions = Comman
   providerRetryPolicy(_provider: string): ResolvedRetryPolicy;
   /** Refresh the catalog (live fetch, cache fallback) and return it. */
   private loadCatalog;
-  listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+  listModels(provider: string, opts?: {
+    unfiltered?: boolean;
+  }): Promise<readonly LlmModelInfo[]>;
   resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
   /** The headers every authenticated account endpoint shares. */
   private accountHeaders;
+  /**
+   * Fetch one account endpoint and parse its JSON body. Returns the HTTP
+   * status alongside the parsed record so each caller applies its own
+   * failure accounting: the billing probe fails open silently, the usage
+   * report books failures per endpoint. Non-2xx and non-record bodies come
+   * back without a record; only a transport throw propagates to the caller.
+   */
+  private fetchEndpointJson;
   /**
    * The billing facts behind the picker's plan filter, cached for
    * {@link BILLING_ACCESS_TTL_MS} and shared across concurrent callers.
@@ -582,8 +602,9 @@ interface CommandCodeBillingAccess {
 /**
  * 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`).
+ * a non-finite weight (corrupt billing fact), 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;
 /**
@@ -662,8 +683,8 @@ declare function planLabel(modelId: string): string | undefined;
 declare function dealLabel(modelId: string, now?: number): string | undefined;
 /**
  * Compact human-readable context window, e.g. `1_000_000 -> "1M"`,
- * `256_000 -> "256K"`, `262_144 -> "256K"` (floor to the nearest K).
- * Returns undefined for unknown/absent sizes.
+ * `256_000 -> "256K"`, `262_144 -> "262K"` (floor to the nearest K).
+ * Returns undefined for unknown/absent sizes; values under 1K render raw.
  */
 declare function formatContext(contextWindow: number | undefined): string | undefined;
 /**
@@ -705,12 +726,20 @@ declare const USAGE_REPORT_ENDPOINT = "commandcode/report";
  * deliberately minimal so one `parse` function satisfies it.
  */
 declare const usageReportSchema: TypertSchema<CommandCodeAccountsReport>;
-/** One catalog entry the settings page's routing-rule editor offers. */
+/** One catalog entry the settings page's model editors offer. */
 interface CommandCodeCatalogModel {
   /** Catalog model id (e.g. `deepseek/deepseek-v4-pro`). */
   id: string;
   /** Display name from the catalog. */
   name: string;
+  /**
+   * Minimum plan-tier key for this model (a `KNOWN_PLANS` value: `go`,
+   * `goat`, `pro`, `provider`, `max`), or undefined for models outside the
+   * snapshot. The settings page groups the model-editor dropdowns under
+   * tier headings from this — the browser cannot import the Host's
+   * capability snapshot, so the Host stamps it per entry.
+   */
+  tier?: string;
 }
 /** The model-catalog Remote result: the full catalog, sorted for picking. */
 interface CommandCodeCatalog {
@@ -812,8 +841,9 @@ declare const loginStatusSchema: TypertSchema<CommandCodeLoginStatus>;
 /**
  * The browser-login face the usage service exposes (`commandcode/login*`).
  * Backed by the Host-half {@link !CommandCodeLoginFlow} when the plugin entry
- * wired one; absent, the methods degrade to a no-op status so an old client
- * against a fresh page still answers instead of hanging.
+ * wired one; absent, `status`/`cancel` degrade to the idle status while
+ * `begin` rejects with a plain message (so the page's manual paste path
+ * stays the fallback instead of hanging).
  */
 interface LoginFlowFacade {
   /** Start (or rejoin) an attempt; rejects when it cannot start at all. */
@@ -834,9 +864,10 @@ interface CommandCodeUsageDeps<C extends CommandCodeConnectionOptions = CommandC
    */
   reports?: () => Promise<CommandCodeAccountsReport>;
   /**
-   * Model-catalog source for the routing-rule editor (wired by the plugin
+   * Model-catalog source for the settings page's model editors (the
+   * routing-rule editor and the visible-models filter; wired by the plugin
    * entry). Absent, the `models` endpoint answers an empty list — the page's
-   * rule editor degrades to the empty state.
+   * editors degrade to the empty state.
    */
   listModels?: () => Promise<CommandCodeCatalog>;
   /**
@@ -866,10 +897,11 @@ declare class CommandCodeUsageService<C extends CommandCodeConnectionOptions = C
    */
   report(): Promise<CommandCodeAccountsReport>;
   /**
-   * The model catalog for the settings page's routing-rule editor. The
-   * browser never calls the Command Code API directly — the Host serves the
-   * catalog (already fetched/cached by the adapter) so rules can be picked
-   * from the live model list instead of typed by hand.
+   * The full model catalog for the settings page's model editors (the
+   * routing-rule editor and the visible-models filter). The browser never
+   * calls the Command Code API directly — the Host serves the catalog
+   * (already fetched/cached by the adapter) so models can be picked from
+   * the live list instead of typed by hand.
    */
   models(): Promise<CommandCodeCatalog>;
   /**
@@ -1012,17 +1044,68 @@ declare class CommandCodeLoginFlow {
 declare const COMMANDCODE_SEARCH_PROVIDER_ID = "commandcode";
 /**
  * The factory-declared search provider id dsh ships by default (from
- * `dsh-base`'s cordis patch `web.config.searchProvider`). A plugin that wants
- * its own backend to win rewrites `WebRuntime.searchProviderId` to its own id;
- * disabling that plugin restores this value.
+ * `dsh-base`'s cordis patch `web.config.searchProvider`). Kept as a
+ * documented reference only: disabling this plugin's `webSearch` toggle
+ * restores the previously selected backend (see
+ * {@link applyCommandCodeSearchSelection}) — it never forces this default,
+ * because forcing it is what used to silence sibling search plugins such as
+ * modsearch even with Command Code search turned off (issue #26).
  */
 declare const DEFAULT_WEB_SEARCH_PROVIDER_ID = "deepseek-official";
 /**
  * Point the web seam's search selection at this plugin's provider (`commandcode`).
  * Sets the runtime field; the next search call honours it because `search()`
  * re-reads `searchProviderId` each time. Returns the prior id (or undefined).
+ * Never throws: a hardened/frozen runtime shape must not break the
+ * settings-save path that calls this — the provider simply stays
+ * registered-but-unselected (the boot-time `searchProvider: commandcode`
+ * cordis patch is the durable alternative).
+ *
+ * @deprecated Prefer {@link applyCommandCodeSearchSelection}: this overload
+ * always overwrites the displaced backend with the factory default on
+ * disable, so turning Command Code search off silences whichever provider
+ * was selected before (e.g. modsearch) instead of restoring it (issue #26).
  */
 declare function selectCommandCodeSearchProvider(web: WebRuntime, enable: boolean): string | undefined;
+/**
+ * Tracked web-search selection state for one mounted `WebRuntime`.
+ *
+ * `owner` marks whether this plugin currently owns the selection (i.e. it
+ * wrote `commandcode` and has not given it back yet). `displaced` is the
+ * backend id the plugin displaced when it took over — restored when the
+ * toggle turns off or the plugin unloads. `undefined` means "nothing was
+ * configured, leave auto-select" and must round-trip untouched: writing the
+ * factory default instead would still override a sibling plugin's own
+ * constructor-time pin.
+ */
+interface CommandCodeSearchSelection {
+  owner: boolean;
+  displaced: string | undefined;
+}
+/** Fresh selection state: the plugin starts out not owning the selection. */
+declare function commandCodeSearchSelection(): CommandCodeSearchSelection;
+/**
+ * Reach one end of the `webSearch` toggle without trampling sibling search
+ * providers (issue #26).
+ *
+ * - Enabling writes `commandcode` and remembers whatever it displaced. When
+ *   the plugin already owns the selection (e.g. a settings save while still
+ *   on), the original `displaced` value is kept — the field currently holds
+ *   our own id, which must never be mistaken for the user's backend.
+ * - Disabling hands the selection back to the remembered backend. When the
+ *   state holds no memory (a fresh boot straight into `webSearch: false`),
+ *   the field is left alone: the runtime's current value — a sibling's
+ *   cordis pin such as `searchProvider: modsearch`, or unset for
+ *   auto-select — already says what the user wants.
+ * - When the field already reads `commandcode` at first touch (e.g. a
+ *   surviving runtime the plugin did not set, or a manual
+ *   `searchProvider: commandcode` pin), `displaced` stays undefined so the
+ *   later disable is a no-op rather than a guess at the factory default.
+ *
+ * Never throws: like the low-level rewrite, a hardened runtime shape degrades
+ * to registered-but-unselected.
+ */
+declare function applyCommandCodeSearchSelection(web: WebRuntime, state: CommandCodeSearchSelection, enable: boolean): void;
 /** Per-request facts the provider needs, all injected so the class stays cordis-free and testable. */
 interface CommandCodeSearchProviderDeps {
   /** Resolve one usable Command Code key (credential seam → env → auth file), or undefined when none. */
@@ -1043,7 +1126,7 @@ declare class CommandCodeSearchProvider implements WebSearchProvider {
   private readonly deps;
   readonly id = "commandcode";
   constructor(deps: CommandCodeSearchProviderDeps);
-  /** Cheap local check; must not make network calls. Presence of a key path + a parseable base is enough. */
+  /** Cheap local check; must not make network calls. Presence of a parseable base is enough. */
   available(): boolean;
   search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
   private resolveKey;
@@ -1085,6 +1168,12 @@ interface Config {
    * full catalog visible). Set false to always list every model.
    */
   filterModelsByPlan?: boolean;
+  /**
+   * Visible-model allowlist: catalog model ids shown in pickers. Empty or
+   * unset means "show everything". Persisted by the settings page's model
+   * filter card; applies after the subscription-tier filter.
+   */
+  visibleModels?: string[];
   /**
    * Extra accounts for multi-account rotation. The top-level
    * `apiKey`/`apiKeyEnv` (plus the CLI auth file) always form the first
@@ -1116,12 +1205,15 @@ interface Config {
   /**
    * Whether to use Command Code as the backend for dsh's model-facing
    * `web_search` tool. When enabled, the plugin registers a `commandcode`
-   * search provider on `ctx.web` AND rewrites the web seam's selected
-   * `searchProviderId` to `commandcode` (so it wins over the shipped
-   * `deepseek-official`), using the SAME Command Code API key/base as chat.
-   * The rewrite rides dsh's internal `searchProviderId`, which is read per
-   * search call, so a setting change lands on the next search without a
-   * restart. Defaults to true.
+   * search provider on `ctx.web` AND selects `commandcode` in the web seam
+   * (so it wins over the shipped `deepseek-official` or a sibling search
+   * plugin's pin), using the SAME Command Code API key/base as chat. When
+   * disabled, the selection is handed back to whichever backend was there
+   * before — turning it off never forces the factory default, so a sibling
+   * search plugin (e.g. modsearch) keeps working (issue #26). The rewrite
+   * rides dsh's internal `searchProviderId`, which is read per search call,
+   * so a setting change lands on the next search without a restart.
+   * Defaults to true.
    */
   webSearch?: boolean;
   /**
@@ -1151,5 +1243,5 @@ interface ResolvedCommandCodeOptions extends CommandCodeConnectionOptions {
 declare function resolveAdapterOptions(config: Config): ResolvedCommandCodeOptions;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { type ApiKeyValidation, BILLING_ACCESS_TTL_MS, COMMANDCODE_SEARCH_PROVIDER_ID, 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 CommandCodeLoginCredentials, type CommandCodeLoginFailureReason, CommandCodeLoginFlow, type CommandCodeLoginFlowDeps, type CommandCodeLoginStatus, type CommandCodeModelAccountRule, CommandCodeSearchProvider, type CommandCodeSearchProviderDeps, 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, DEFAULT_WEB_SEARCH_PROVIDER_ID, KNOWN_DEALS, KNOWN_EFFORTS, KNOWN_IMAGE_MODELS, KNOWN_PEAK_PRICING, KNOWN_PLANS, KNOWN_SUBSCRIPTION_PLANS, KNOWN_THINKING_MODELS, LOGIN_ALLOWED_ORIGINS, LOGIN_BEGIN_ENDPOINT, LOGIN_BODY_LIMIT_BYTES, LOGIN_CANCEL_ENDPOINT, LOGIN_MAX_PORT_ATTEMPTS, LOGIN_START_PORT, LOGIN_STATUS_ENDPOINT, LOGIN_TIMEOUT_MS, type LoginFlowFacade, PLAN_LABELS, PLAN_ORDER, PROVIDER, type ResolveAttachments, ResolvedCommandCodeOptions, USAGE_REPORT_ENDPOINT, accountUsable, apply, applyCommands, applyUsageRemote, buildCommandAuthUrl, capabilityDescription, commandDefinition, compareByPlan, dealLabel, formatContext, inject, loginStatusSchema, matchModelRule, modelVisibleInPlan, name, parseLoginStatus, peakPricingLabel, peakPricingState, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey, selectAccountForModel, selectActiveAccount, selectCommandCodeSearchProvider, studioBaseForApiBase, subscriptionPlanInfo, usageReportSchema, validateCommandApiKey };
+export { type ApiKeyValidation, BILLING_ACCESS_TTL_MS, COMMANDCODE_SEARCH_PROVIDER_ID, 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 CommandCodeLoginCredentials, type CommandCodeLoginFailureReason, CommandCodeLoginFlow, type CommandCodeLoginFlowDeps, type CommandCodeLoginStatus, type CommandCodeModelAccountRule, CommandCodeSearchProvider, type CommandCodeSearchProviderDeps, type CommandCodeSearchSelection, 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, DEFAULT_WEB_SEARCH_PROVIDER_ID, KNOWN_DEALS, KNOWN_EFFORTS, KNOWN_IMAGE_MODELS, KNOWN_PEAK_PRICING, KNOWN_PLANS, KNOWN_SUBSCRIPTION_PLANS, KNOWN_THINKING_MODELS, LOGIN_ALLOWED_ORIGINS, LOGIN_BEGIN_ENDPOINT, LOGIN_BODY_LIMIT_BYTES, LOGIN_CANCEL_ENDPOINT, LOGIN_MAX_PORT_ATTEMPTS, LOGIN_START_PORT, LOGIN_STATUS_ENDPOINT, LOGIN_TIMEOUT_MS, type LoginFlowFacade, PLAN_LABELS, PLAN_ORDER, PROVIDER, type ResolveAttachments, ResolvedCommandCodeOptions, USAGE_REPORT_ENDPOINT, accountUsable, apply, applyCommandCodeSearchSelection, applyCommands, applyUsageRemote, buildCommandAuthUrl, capabilityDescription, commandCodeSearchSelection, commandDefinition, compareByPlan, dealLabel, formatContext, inject, loginStatusSchema, matchModelRule, modelVisibleInPlan, name, parseLoginStatus, peakPricingLabel, peakPricingState, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey, selectAccountForModel, selectActiveAccount, selectCommandCodeSearchProvider, studioBaseForApiBase, subscriptionPlanInfo, usageReportSchema, validateCommandApiKey };
 //# sourceMappingURL=index.d.ts.map