dsh-connect-workbuddy 2.2.1 → 2.3.1

package/lib/index.d.ts

@@ -512,6 +512,25 @@ type WorkBuddyChatResult = {
   kind: UpstreamErrorKind;
   message: string;
 };
+/**
+ * Chat answer that also carries the response headers.
+ *
+ * Used by the model probe, whose whole point is to ask "is this usable right
+ * now, and if not, when?" — and the only place an upstream ever names a
+ * cooldown is the `Retry-After` header, which {@link WorkBuddyChatResult}
+ * deliberately does not surface. Returning a separate shape keeps the ordinary
+ * chat path (and its callers) untouched.
+ */
+interface WorkBuddyProbeAnswer {
+  ok: boolean;
+  status: number;
+  /** Raw `Retry-After`, when the upstream sent one; null otherwise. */
+  retryAfter: string | null;
+  /** Failure body excerpt, only when `ok` is false. */
+  body?: string;
+  /** The live stream, only when `ok` is true. The caller drains and discards it. */
+  response?: Response;
+}
 /** Classify an upstream failure from its HTTP status and body excerpt. */
 declare function classifyUpstreamError(status: number, body: string): UpstreamErrorKind;
 /**
@@ -578,6 +597,20 @@ declare function parseUpstreamModel(value: unknown): WorkBuddyUpstreamModel | un
 declare class WorkBuddyUpstreamClient {
   /** POST the chat endpoint; a successful answer is the raw SSE response. */
   chatStream(credential: WorkBuddyCredential, bodyJson: string, signal?: AbortSignal): Promise<WorkBuddyChatResult>;
+  /**
+   * Send one minimal chat request for `bodyJson` and report the RAW answer.
+   *
+   * Shares {@link chatHeaders} and the chat base with {@link chatStream} on
+   * purpose: a probe is only meaningful if it reaches the same endpoint with the
+   * same authentication as a real request. The differences are deliberate and
+   * narrow — it returns the headers (for `Retry-After`) and the failure body
+   * (for classification) instead of a pre-classified error, so the probe module
+   * owns the interpretation and the network layer stays a transport.
+   *
+   * The caller MUST drain {@link WorkBuddyProbeAnswer.response}; an unread body
+   * holds the connection open.
+   */
+  probeChat(credential: WorkBuddyCredential, bodyJson: string, signal?: AbortSignal): Promise<WorkBuddyProbeAnswer>;
   /** POST the token-refresh endpoint; the caller merges the outcome. */
   refreshToken(credential: WorkBuddyCredential): Promise<WorkBuddyRefreshOutcome>;
   /**
@@ -1153,6 +1186,181 @@ declare function clearHostHeartbeat(): Promise<void>;
 /** The npm package version this build was produced from. */
 declare const WORKBUDDY_CONNECT_VERSION: string;
 //#endregion
+//#region src/probe.d.ts
+/**
+ * The system message every probe carries.
+ *
+ * Not decoration: the international gateway rejects a conversation that does not
+ * start with a system message (see the module note). A probe that omitted it
+ * would report every global model as broken.
+ */
+declare const PROBE_SYSTEM_PROMPT = "You are a connectivity check. Reply with a single word.";
+/**
+ * Output cap for a probe. One token is enough to prove the model answers.
+ *
+ * The probe's cost comes from its INPUT, not its output (see
+ * {@link PROBE_INPUT_TOKENS}), so paying for a long completion would add money
+ * without adding signal.
+ */
+declare const PROBE_MAX_TOKENS = 1;
+/**
+ * How much input a probe sends, in tokens.
+ *
+ * This is the whole point of the probe, and it is NOT a free choice. The
+ * upstream's rate limit (business code 6004) fires on request SIZE, measured on
+ * 2026-09-29 by varying only the input against one account and one model:
+ *
+ *   | input     | prompt_tokens the upstream counted | result |
+ *   | ---       | ---                                | ---    |
+ *   | ~10       | 38                                 | ok     |
+ *   | ~1,000    | 1,138                              | ok     |
+ *   | ~10,000   | 11,138                             | ok     |
+ *   | ~18,000   | 20,018                             | ok     |
+ *   | ~25,000   | 25,023                             | ok     |
+ *   | ~30,000   | ~32k                               | **429 / 6004** |
+ *
+ * So the threshold sits between 20k and 30k, a SINGLE large request is enough to
+ * trip it (it is not a running total), and each account reports its own reset
+ * time (two accounts at the same moment: `22:20:33` and `00:32:51`).
+ *
+ * A probe that sent a handful of tokens answered "usable" while every real
+ * request in a long conversation was refused — the probe was asking too small a
+ * question. 25k is sized to be a realistic long-conversation payload.
+ */
+declare const PROBE_INPUT_TOKENS = 25000;
+/**
+ * Build the request body for one probe.
+ *
+ * `stream` is forced because the upstream rejects non-streaming chat requests;
+ * `prepareChatBody` enforces that too, but sending it explicitly keeps this
+ * function's output valid on its own.
+ *
+ * Measured on the built artifact: 112,713 bytes of body, and the upstream
+ * counted `prompt_tokens: 25023` at a cost of `credit: 0.72`.
+ */
+declare function probeRequestBody(modelId: string): string;
+/**
+ * How one probe ended.
+ *
+ * `rate-limited` is split out from a generic failure because it is the one
+ * outcome the feature exists for: it means "this model works, but not right
+ * now". Everything else is a real, actionable failure or a success.
+ */
+type WorkBuddyProbeOutcome = 'ok' | 'rate-limited' | 'out-of-credit' | 'credential-rejected' | 'unavailable' | 'not-found' | 'failed';
+/**
+ * One probe result, as the card renders it.
+ *
+ * `retryAtMs` is present ONLY when the upstream actually stated a time (a
+ * `Retry-After` header, or the region's quota refresh point when the failure is
+ * an exhausted quota). Its absence is meaningful and must be rendered as "the
+ * upstream did not say", never as a locally invented countdown.
+ */
+interface WorkBuddyProbeResult {
+  modelId: string;
+  outcome: WorkBuddyProbeOutcome;
+  /** Round-trip time in ms, for a successful probe. */
+  elapsedMs?: number;
+  /** HTTP status the upstream answered with; 0 means the request never landed. */
+  status?: number;
+  /** Upstream's own words, redacted. Present on failures. */
+  message?: string;
+  /** A time the upstream named, in ms. Absent when it named none. */
+  retryAtMs?: number;
+  /** Where a supplied `retryAtMs` came from, so the card can say so. */
+  retrySource?: 'retry-after' | 'upstream-message' | 'quota-refresh';
+}
+/**
+ * Parse a `Retry-After` header value into an absolute time.
+ *
+ * Both RFC 9110 forms are accepted: delay-seconds (`120`) and an HTTP-date
+ * (`Wed, 21 Oct 2026 07:28:00 GMT`). Returns undefined for anything else,
+ * including the negative/zero delays some gateways emit — a "retry now" is not
+ * a cooldown and reporting it as one would be worse than saying nothing.
+ *
+ * `nowMs` is injected so the delay-seconds branch is testable without a clock.
+ */
+declare function parseRetryAfter(value: string | null, nowMs: number): number | undefined;
+/**
+ * The cooldown the upstream stated, if it stated one.
+ *
+ * Three sources, in order of authority:
+ *
+ * 1. `Retry-After` on the failure response. This is the upstream naming a time
+ *    for THIS request, so it wins.
+ * 2. The reset time the upstream writes into its own failure body (see
+ *    {@link parseUpstreamResetAt}). This is the case that actually fires on
+ *    this service: a 429 from the Chinese gateway carries code 6004 and a
+ *    `将在 … 重置` sentence, with no `Retry-After` header at all.
+ * 3. The region's monthly quota refresh point, but ONLY for an out-of-credit
+ *    outcome. A quota that resets at a known time is the one case where "when
+ *    can I use this again" has a real answer even without a header — and it is
+ *    the answer for the most common real limit on this service.
+ *
+ * A limited outcome with none of the three returns `{}`, which the card renders
+ * as "the upstream did not say when". That remains the honest answer for a
+ * genuinely timeless failure; inventing a number here would be pure fiction.
+ */
+declare function cooldownOf(input: {
+  outcome: WorkBuddyProbeOutcome;
+  retryAfter: string | null;
+  nowMs: number;
+  /** The upstream's own failure text, where a reset sentence may live. */
+  body?: string;
+  /** The region's next monthly quota refresh, when the upstream declares one. */
+  quotaRefreshAtMs?: number;
+}): Pick<WorkBuddyProbeResult, 'retryAtMs' | 'retrySource'>;
+/**
+ * Classify one failed probe into the card's outcome vocabulary.
+ *
+ * Built on `classifyUpstreamError` rather than re-testing status codes, so a
+ * probe and a real chat request can never disagree about what the same upstream
+ * answer means. The extra split here is `credential-rejected`, which the
+ * upstream signals with a non-JSON 401/403 edge page and which needs completely
+ * different advice (re-auth, not "wait").
+ */
+declare function outcomeOfFailure(status: number, body: string): WorkBuddyProbeOutcome;
+/**
+ * Read the credit this probe consumed out of an SSE stream, when the upstream
+ * reports it.
+ *
+ * Purely informational — the card shows it so a user can see how little a probe
+ * actually costs rather than having to trust a claim. Absent when the stream
+ * carried no `usage` block.
+ */
+declare function creditOfStream(text: string): number | undefined;
+/** Whether a probe outcome means the model answered. */
+declare function probeSucceeded(outcome: WorkBuddyProbeOutcome): boolean;
+/** What one probe needs from the upstream client. */
+interface WorkBuddyProbeClient {
+  probeChat(credential: WorkBuddyCredential, bodyJson: string, signal?: AbortSignal): Promise<{
+    ok: boolean;
+    status: number;
+    retryAfter: string | null;
+    body?: string;
+    response?: Response;
+  }>;
+}
+/**
+ * Run one probe for one model and reduce it to the card's row.
+ *
+ * The successful path drains the SSE stream purely to read the `credit` figure
+ * the upstream reports, then discards the rest: the question is whether this
+ * model answers a real-sized request, and `max_tokens: 1` means there is nothing
+ * else in the stream worth keeping.
+ *
+ * Never throws. A probe is a diagnostic the user asked for, so every failure is
+ * a RESULT — one dead model must not abort the batch and hide the other rows.
+ */
+declare function probeModel(input: {
+  client: WorkBuddyProbeClient;
+  credential: WorkBuddyCredential;
+  modelId: string;
+  nowMs: number;
+  /** The region's next monthly quota refresh, when known. */
+  quotaRefreshAtMs?: number;
+  signal?: AbortSignal;
+}): Promise<WorkBuddyProbeResult>;
+//#endregion
 //#region src/status-paths.d.ts
 /**
  * Node-free constants and types shared by the Host and browser halves.
@@ -1175,6 +1383,15 @@ declare const WORKBUDDY_MODELS_REFRESH_PATH = "/plugins/dsh-connect-workbuddy/mo
 declare const WORKBUDDY_ACCOUNTS_REFRESH_PATH = "/plugins/dsh-connect-workbuddy/accounts/refresh";
 /** Plugin-owned daily check-in action endpoint. */
 declare const WORKBUDDY_CHECKIN_PATH = "/plugins/dsh-connect-workbuddy/checkin";
+/**
+ * Plugin-owned model probe endpoint.
+ *
+ * Sends one minimal chat request per named model so the card can answer "is
+ * this model usable right now, and if it is limited, when can it be used
+ * again?". Lives on the Host because the credential must never reach the
+ * browser half.
+ */
+declare const WORKBUDDY_PROBE_PATH = "/plugins/dsh-connect-workbuddy/probe";
 /** Query parameter naming the region a card request addresses. */
 declare const WORKBUDDY_REGION_PARAM = "region";
 /** Every region, in card tab order. */
@@ -1444,6 +1661,38 @@ type WorkBuddyWebUsage =
   status: 'error';
   message: string;
 };
+/**
+ * Outcome vocabulary of one model probe, shared by the Host and the card.
+ *
+ * Mirrors `WorkBuddyProbeOutcome` in `./probe.ts`; kept as its own declaration
+ * here because this module is the node-free bridge and must not import the
+ * Host-side probe module (which pulls in the credential type).
+ */
+type WorkBuddyWebProbeOutcome = 'ok' | 'rate-limited' | 'out-of-credit' | 'credential-rejected' | 'unavailable' | 'not-found' | 'failed';
+/** One model's probe result, as the card renders it. */
+interface WorkBuddyWebProbeResult {
+  modelId: string;
+  outcome: WorkBuddyWebProbeOutcome;
+  /** Round-trip time in ms; present once the request landed. */
+  elapsedMs?: number;
+  /** HTTP status the upstream answered with; 0 means it never landed. */
+  status?: number;
+  /** Upstream's own words, already redacted. */
+  message?: string;
+  /**
+   * A time the upstream named for using this model again, in ms.
+   *
+   * ABSENT means the upstream named none, and the card must say exactly that.
+   * A client-invented countdown here would be fiction. Three sources fill it:
+   * a real `Retry-After` header; the reset sentence the upstream writes into
+   * its own failure BODY (`将在 … UTC+8 重置`, which is where this service
+   * actually puts it — its 429s carry no rate-limit header at all); or, for an
+   * exhausted quota, the region's own quota refresh point.
+   */
+  retryAtMs?: number;
+  /** Which of those three sources supplied {@link retryAtMs}. */
+  retrySource?: 'retry-after' | 'upstream-message' | 'quota-refresh';
+}
 /**
  * Deep copy of a settings value with every `{get(): T}` live reference replaced
  * by the value it resolves to.
@@ -1511,6 +1760,29 @@ interface WorkBuddyStatusRouteOptions {
    * committed settings value rather than a local guess.
    */
   regionEnabled(region: WorkBuddyRegion): boolean;
+  /**
+   * Send one real-volume request to each named model of a region and report what
+   * came back.
+   *
+   * Optional: it is the only dependency the card's test button needs, so a Host
+   * built without it (or a route mounted for a status-only consumer) simply
+   * answers 503 and the button reports that instead of failing the card.
+   *
+   * Every request costs real credits (measured `credit: 0.72` for one probe), so
+   * the card drives this ONE model per click and never as a batch.
+   */
+  probeModels?(region: WorkBuddyRegion, modelIds: readonly string[], options?: {
+    signal?: AbortSignal;
+  }): Promise<readonly WorkBuddyWebProbeResult[]>;
+  /**
+   * The region's next monthly quota refresh, when the upstream declares one.
+   *
+   * Used ONLY to answer "when can I use this again" for an out-of-credit
+   * outcome, which is the one cooldown the service actually states: a monthly
+   * resource that resets at a known time. Every other limited outcome has no
+   * time from any source and must be reported as such.
+   */
+  quotaRefreshAtMs?(region: WorkBuddyRegion): number | undefined;
   /**
    * Report whether a region still has at least one local sign-in.
    *
@@ -1739,4 +2011,4 @@ declare function legacyAttributionRegion(value: Config, accountsFor: (region: Wo
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { CREDENTIAL_REJECTED_CODE, Config, ENCRYPTED_CREDENTIAL_CODE, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, NATIVE_MODALITY_BY_MODEL_ID, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_APP_EXECUTABLE_ENV, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, type WorkBuddyCandidateFailure, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, type WorkBuddyCredentialRecovery, WorkBuddyCredentialRejectedError, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, WorkBuddyEncryptedCredentialError, type WorkBuddyEncryptedField, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyNativeModality, type WorkBuddyProbeStore, type WorkBuddyReasoning, type WorkBuddyRecoveryCandidate, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyUsabilityProbeOptions, apply, asVolatile, authFileName, classifyUpstreamError, clearAtRestKeyCache, clearHostHeartbeat, createAccountUsabilityProbe, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, deriveAtRestKey, deriveAtRestKeyId, deriveCatalog, fallbackModelsFor, fetchAtRestKeyPayload, findWorkbuddyAppExecutable, hasEncryptedCredentialFields, imageDefaultFor, inject, isCredentialRejectedError, isEncryptedCredentialError, isEncryptedFieldWrapper, isHeartbeatProcessAlive, isWorkbuddyBundle, legacyAttributionRegion, legacyWorkbuddyOwnAuthPath, macosBundleExecutable, macosNestedAppBundles, name, nativeModalityOf, nextRegionEnabled, nextRegionSlots, openEncryptedField, parseCreditMultiplier, parseReasoning, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readAtRestKey, readHostHeartbeat, regionCleared, regionEnabled, regionEnabledOf, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, resolveCredentialRecovery, selectAccountFor, settingsNamespaceOf, toPersistedWorkBuddyModel, unwrapVolatileDeep, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyAppExecutableCandidates, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };
+export { CREDENTIAL_REJECTED_CODE, Config, ENCRYPTED_CREDENTIAL_CODE, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, NATIVE_MODALITY_BY_MODEL_ID, PROBE_INPUT_TOKENS, PROBE_MAX_TOKENS, PROBE_SYSTEM_PROMPT, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_APP_EXECUTABLE_ENV, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROBE_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, type WorkBuddyCandidateFailure, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, type WorkBuddyCredentialRecovery, WorkBuddyCredentialRejectedError, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, WorkBuddyEncryptedCredentialError, type WorkBuddyEncryptedField, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyNativeModality, type WorkBuddyProbeClient, type WorkBuddyProbeOutcome, type WorkBuddyProbeResult, type WorkBuddyProbeStore, type WorkBuddyReasoning, type WorkBuddyRecoveryCandidate, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyUsabilityProbeOptions, apply, asVolatile, authFileName, classifyUpstreamError, clearAtRestKeyCache, clearHostHeartbeat, cooldownOf, createAccountUsabilityProbe, createWorkBuddyAdapter, createWorkBuddyShim, creditOfStream, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, deriveAtRestKey, deriveAtRestKeyId, deriveCatalog, fallbackModelsFor, fetchAtRestKeyPayload, findWorkbuddyAppExecutable, hasEncryptedCredentialFields, imageDefaultFor, inject, isCredentialRejectedError, isEncryptedCredentialError, isEncryptedFieldWrapper, isHeartbeatProcessAlive, isWorkbuddyBundle, legacyAttributionRegion, legacyWorkbuddyOwnAuthPath, macosBundleExecutable, macosNestedAppBundles, name, nativeModalityOf, nextRegionEnabled, nextRegionSlots, openEncryptedField, outcomeOfFailure, parseCreditMultiplier, parseReasoning, parseRetryAfter, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, probeModel, probeRequestBody, probeSucceeded, processStartTimeMs, readAtRestKey, readHostHeartbeat, regionCleared, regionEnabled, regionEnabledOf, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, resolveCredentialRecovery, selectAccountFor, settingsNamespaceOf, toPersistedWorkBuddyModel, unwrapVolatileDeep, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyAppExecutableCandidates, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };