dsh-connect-workbuddy 4.14.1 → 5.0.0

package/lib/index.d.ts

@@ -574,6 +574,27 @@ declare class WorkBuddyCredentialStore {
   }>;
 }
 //#endregion
+//#region src/image-gen.d.ts
+/**
+ * 产品配置 `data.models` 里的一个媒体模型条目。
+ *
+ * 实测上游只给三个字段（`{"id":"hunyuan-image-alpha","name":"Hunyuan Image Alpha",
+ * "tags":["text-to-image"]}`），没有 credits、没有上下文长度。不要在这里补
+ * 上游没有的字段——那正是「不猜」红线的反面。
+ */
+interface WorkBuddyMediaModel {
+  readonly id: string;
+  readonly name: string;
+  readonly tags: readonly string[];
+}
+/** 上游成功响应的归一化结果。`url` 与 `b64` 至少有一个。 */
+interface WorkBuddyImageOutcome {
+  readonly url?: string;
+  readonly b64?: string;
+  readonly created?: number;
+  readonly credit?: number;
+}
+//#endregion
 //#region src/promo.d.ts
 /**
  * WorkBuddy promotion & tier badges — the upstream's own "this model is on
@@ -747,6 +768,59 @@ interface WorkBuddyPromo {
   priority: number;
 }
 //#endregion
+//#region src/busy.d.ts
+/**
+ * WorkBuddy model load — the "繁忙程度" line the WorkBuddy client draws under a
+ * model, read from the upstream's own probe and rendered next to the model name.
+ *
+ * WHY A SEPARATE REQUEST, AND WHY IT COSTS ALMOST NOTHING. Load is NOT part of
+ * the model directory: `/v3/config` lists models and prices, and says nothing
+ * about how busy each one is right now. The app asks a dedicated probe —
+ * `POST /v2/chat/busy { models: [...] }` — and so does this plugin, exactly once
+ * per model-picker refresh, batched at the upstream's own limit of 50 ids per
+ * call. The probe is read-only and free (no credits, no account mutation):
+ * measured 2026-10-21 on the CN gateway, HTTP 200 with
+ *
+ *   {"code":0,"msg":"OK","requestId":"…","data":[
+ *     {"model":"hy3","busy_level":"busy"},
+ *     {"model":"deepseek-v4.1-flash","busy_level":"congested"}]}
+ *
+ * IDENTICAL ON EVERY CN HOST AND UNDER EITHER CLIENT IDENTITY. `copilot.tencent.com`,
+ * `www.workbuddy.cn` and `www.codebuddy.cn` answer byte-for-byte the same list,
+ * and so do the CLI user agent (`CLI/2.63.2 CodeBuddy/2.63.2`) and the app's
+ * product identity (`WorkBuddy/5.8.3 WorkBuddy/5.8.3 CLI/2.161.0`). Unlike
+ * `/v3/config`, this endpoint is not channel-sensitive, so the plugin asks it as
+ * the CLI agent it already is on the chat path — no product identity needed.
+ *
+ * THE LEVELS ARE THE APP'S OWN ENUM, and anything outside it is `unknown`:
+ * `idle` / `normal` / `busy` / `congested` / `unavailable`. The app's own words
+ * (from its `im-channels` bundle, `chatInput.modelSelector.busy.*`) are
+ * 空闲 / 轻微拥堵 / 极度拥堵 / 不可用; English reads Idle / Slightly congested /
+ * Extremely congested / Unavailable.
+ *
+ * WHY THE LABELS LIVE HERE AND NOT IN THE UPSTREAM CLIENT. The probe returns a
+ * machine level, never text: the same response is drawn differently by the app
+ * (an icon for `congested`, a word for the rest), so the rendering decision
+ * belongs with the renderer. This module keeps the words, the tone, and the
+ * "which levels are worth drawing at all" rule in one place.
+ *
+ * NOTHING HERE IS PERSISTED. Load is a fact about THIS MINUTE: a cached level
+ * that survives a restart is a lie, and the model directory is saved to disk
+ * while a level must not be. So the level is attached to the catalog entry at
+ * refresh time and nowhere else — see `attachBusyLevels` and `src/index.ts`.
+ *
+ * @module dsh-connect-workbuddy/busy
+ */
+/**
+ * One model's load, in the upstream's vocabulary.
+ *
+ * `unknown` is the plugin's own value, not the upstream's: it is what an
+ * unusable entry becomes (a missing level, a level outside the enum, a model the
+ * probe did not answer for). It is deliberately distinct from `normal` — "we
+ * were told nothing" must not be drawn as "all good".
+ */
+type WorkBuddyBusyLevel = 'idle' | 'normal' | 'busy' | 'congested' | 'unavailable' | 'unknown';
+//#endregion
 //#region src/upstream.d.ts
 /** WorkBuddy region selected by the credential's login domain. */
 type WorkBuddyRegion = 'cn' | 'global';
@@ -802,7 +876,27 @@ type UpstreamErrorKind = 'hard_credit' |
  * later and each attempt teaches the pool a false fact about a credential
  * that was never the problem.
  */
-'channel_reject' | 'not_found' | 'server' | 'client';
+'channel_reject' |
+/**
+ * The upstream put this request in a queue instead of running it: business
+ * codes `6020` (waiting, with a position), `6021` (queue full), `6022` (this
+ * user already holds the maximum). See `src/queue.ts`.
+ *
+ * Its own kind because it is the ONE failure where the credential was fine,
+ * the request was fine, and the server already accepted the work — telling the
+ * user "请求失败" or rotating accounts is wrong on both counts. A queued
+ * request follows the MODEL and the shared queue, not the account, so another
+ * account is handed the same position: NOT failover-worthy (see
+ * `isFailoverWorthy` in the shim).
+ *
+ * Classified BEFORE the plain status branches: the queue condition arrives as
+ * a business code and the HTTP status it rides on is incidental (observed on
+ * 200-shaped envelopes and on 429/500). Without this member it fell through to
+ * `server`/`soft_rate`, both of which DO fail over — so hitting a queue walked
+ * the whole account pool, burning a real request per account, before saying
+ * "you are #8777 in line".
+ */
+'model_queue' | 'not_found' | 'server' | 'client';
 /** Reasoning capability as the upstream catalog declares it. */
 interface WorkBuddyReasoning {
   supportedEfforts?: readonly string[];
@@ -864,6 +958,16 @@ interface WorkBuddyUpstreamModel {
    * not where the document was read. See `src/promo.ts`.
    */
   promos?: readonly WorkBuddyPromo[];
+  /**
+   * How busy this model is RIGHT NOW, from the upstream's own probe
+   * (`POST /v2/chat/busy`, see `src/busy.ts`).
+   *
+   * Deliberately NOT part of the catalog document, and deliberately not
+   * persisted: the directory is a fact that survives a restart, a load level is
+   * a fact about the minute it was measured. It is stamped onto the in-memory
+   * catalog entry at refresh time and disappears with the process.
+   */
+  busyLevel?: WorkBuddyBusyLevel;
 }
 /** One billing package as the upstream returns it, dates already parsed. */
 interface WorkBuddyCreditPackage {
@@ -1231,6 +1335,48 @@ declare class WorkBuddyUpstreamClient {
    * one step upstream of it).
    */
   fetchModels(credential: WorkBuddyCredential, signal?: AbortSignal, keepModelIds?: readonly string[]): Promise<readonly WorkBuddyUpstreamModel[]>;
+  /**
+   * Read how busy each model is right now, from the upstream's own probe.
+   *
+   * Batched at the upstream's ceiling (`WORKBUDDY_BUSY_BATCH_SIZE`), because the
+   * probe takes a list of ids and answers only about the ids it was given.
+   *
+   * Throws on anything that is not a clean `code: 0`, like every other reader in
+   * this class — the CALLER decides that a failed load probe is survivable and
+   * catches it. Nothing here is persisted: the level belongs to the refresh that
+   * asked for it.
+   */
+  fetchModelBusy(credential: WorkBuddyCredential, modelIds: readonly string[], signal?: AbortSignal): Promise<Map<string, WorkBuddyBusyLevel>>;
+  /**
+   * 读该账号所属区的产品配置，挑出带 `text-to-image` 标签的媒体模型。
+   *
+   * 走的是和 {@link fetchModels} 同一条 `/v3/config`（国内区与国际区都答），
+   * 区别只在这里保留 `data.models` 的媒体条目、而不是投影成 CLI 聊天目录。
+   * 国内区实测 62 条模型里只有 `hunyuan-image-alpha` 带 `text-to-image`；
+   * 国际区一条都没有 —— 所以本方法对国际区返回空数组，而不是编一个模型出来。
+   *
+   * 这是一次 EXTRA 读取，不是「复用目录那一次」：`fetchModels` 的结果被投影成
+   * 聊天目录就丢掉了媒体标签，所以这里必须再读一遍同一份文档。它是只读 GET、
+   * 不花积分，且工具侧有 5 分钟缓存，但「零新增请求」的说法不成立，别那么写。
+   * 国内区与 {@link fetchModels} 一样走 `/v3` → `/v2` 降级：上游一旦不答
+   * `/v3`，聊天目录会降级而这里不能变成一个原始异常。
+   */
+  fetchMediaModels(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<readonly WorkBuddyMediaModel[]>;
+  /**
+   * 发一次文生图请求。
+   *
+   * 端点、请求体、响应解析全部照抄官方 CLI 的 ImageService（见 `image-gen.ts`
+   * 的模块注释）。实测单张 5.71 credits，产物是 24 小时有效的 COS 签名 URL。
+   *
+   * 失败分两层：HTTP 非 2xx 交给 {@link describeImageFailure} 翻成带 code 的
+   * 错误（401/403 提示重新登录、404 提示该区没有生图路由、429 提示限流）；
+   * HTTP 200 但信封 `code !== 0` 由 {@link parseImageResponse} 处理。
+   */
+  generateImage(credential: WorkBuddyCredential, request: {
+    readonly model: string;
+    readonly prompt: string;
+    readonly size?: string;
+  }, signal?: AbortSignal): Promise<WorkBuddyImageOutcome>;
   /** Query today's check-in status without changing account state. */
   fetchCheckinStatus(credential: WorkBuddyCredential): Promise<WorkBuddyCheckinStatus>;
   /**
@@ -2938,6 +3084,15 @@ type WorkBuddyWebUsage =
    * "关闭不了" report.
    */
   showCreditsInMainUi?: boolean;
+  /**
+   * Whether the model may call the image-generation tool here (opt-in).
+   *
+   * Travels on the Host's answer for the same reason as the fields around it,
+   * and matters more: a checkbox rendering a stale value would let the user
+   * believe the spending capability was ON when it is off, or leave it on
+   * after a switch-off that never landed.
+   */
+  imageToolEnabled?: boolean;
   /** WHERE this region's readout sits (issue #62); absent means `composer`. */
   creditPosition?: WorkBuddyCreditPosition;
   message?: string;
@@ -2974,6 +3129,15 @@ type WorkBuddyWebUsage =
    * settings mirror.
    */
   showCreditsInMainUi?: boolean;
+  /**
+   * Whether the model may call the image-generation tool here (opt-in).
+   *
+   * Travels on the Host's answer for the same reason as the fields around it,
+   * and matters more: a checkbox rendering a stale value would let the user
+   * believe the spending capability was ON when it is off, or leave it on
+   * after a switch-off that never landed.
+   */
+  imageToolEnabled?: boolean;
   /** WHERE this region's readout sits (issue #62); absent means `composer`. */
   creditPosition?: WorkBuddyCreditPosition;
   source?: 'desktop' | 'dsh';
@@ -3419,6 +3583,14 @@ interface WorkBuddyStatusRouteOptions {
    * existed, so a Host that predates it renders exactly as it used to.
    */
   creditPosition?(region: WorkBuddyRegion): WorkBuddyCreditPosition;
+  /**
+   * Whether the model may call the image-generation tool in this region.
+   *
+   * Optional, and absent reads as OFF — the opposite of the fields above. This
+   * one authorizes the MODEL to spend credits on its own, so an older Host that
+   * cannot answer must not be read as consent.
+   */
+  imageToolEnabled?(region: WorkBuddyRegion): boolean;
   /**
    * Send one real-volume request to each named model of a region and report what
    * came back.
@@ -3824,6 +3996,15 @@ interface WorkBuddyRegionState {
    * written before this switch existed keeps whatever the default was.
    */
   showCreditsInMainUi?: boolean;
+  /**
+   * Whether the model may call the image-generation tool here (opt-IN).
+   *
+   * The only switch in this interface where an ABSENT value means OFF. Every
+   * other flag here governs something the user can undo by clicking again;
+   * this one authorizes the model to spend real credits on its own, so an
+   * upgrade — or a config whose value could not be read — must leave it off.
+   */
+  imageToolEnabled?: boolean;
   /**
    * WHERE this region's credit readout sits (issue #62).
    *