dsh-connect-workbuddy 3.1.0 → 3.4.0

package/lib/{host-heartbeat-DZnPggVT.js → host-heartbeat-C2_Zmuqq.js}

@@ -416,6 +416,19 @@ const CLIENT_UA = "CLI/2.63.2 CodeBuddy/2.63.2";
 const DESKTOP_UA = "WorkBuddy/5.5.2";
 const JSON_TIMEOUT_MS = 3e4;
 const ERROR_BODY_LIMIT = 4096;
+/**
+* Ceiling for one real-volume probe to get a RESPONSE, which is not a metadata
+* call.
+*
+* Much larger than {@link JSON_TIMEOUT_MS} on purpose: a probe posts ~25k input
+* tokens, so prompt processing legitimately takes a while before the first byte
+* comes back. It exists only to stop a connection that will NEVER answer — the
+* pool's batch is serial, so one hung member would otherwise block all the rest
+* with nothing in the UI to say which one it was. Ten seconds is comfortably
+* above a working gateway's first byte and far below a user's patience; the
+* budget covers the response only, never the one-line body that follows.
+*/
+const PROBE_TIMEOUT_MS = 1e4;
 /** Insufficient-credit markers, ASCII lowercase plus the original Chinese. */
 const HARD_CREDIT_MARKERS = [
 	"insufficient credit",
@@ -637,6 +650,67 @@ function normalizeToolChoice(obj) {
 	delete obj["tool_choice"];
 }
 /**
+* What a PREPARED request body declares, as the input to DSML recovery.
+*
+* This exists so the recovery path can answer the one question its gates turn
+* on — "was this tool name offered in THIS request?" — without a second parse
+* of the body and without a second source of truth. `prepareChatBody` has
+* already parsed it; this reads the same prepared JSON.
+*
+* Two facts make it cheap and exact:
+*
+*   - `tool_choice: "none"` deletes `tools` outright in
+*     {@link normalizeToolChoice}, so "no tools declared" is directly
+*     observable here rather than a separate condition to remember;
+*   - a pinned `tool_choice` arrives as the bare function name (the object form
+*     was flattened), so anything that is not `auto`/`required`/`none` is a pin.
+*
+* Returns `undefined` when the body declares nothing usable — malformed JSON,
+* no `tools` array, or an empty one. Callers must read that as "recovery is
+* off" (gate 3), not as "no information, so guess".
+*/
+function declaredTools(bodyJson) {
+	let body;
+	try {
+		body = JSON.parse(bodyJson);
+	} catch {
+		return;
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return void 0;
+	const obj = body;
+	const tools = obj["tools"];
+	if (!Array.isArray(tools)) return void 0;
+	const names = /* @__PURE__ */ new Set();
+	const requiredParameters = /* @__PURE__ */ new Map();
+	for (const value of tools) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+		const fn = value["function"];
+		if (typeof fn !== "object" || fn === null || Array.isArray(fn)) continue;
+		const definition = fn;
+		const name = typeof definition["name"] === "string" ? definition["name"] : "";
+		if (name === "") continue;
+		names.add(name);
+		const parameters = definition["parameters"];
+		if (typeof parameters !== "object" || parameters === null || Array.isArray(parameters)) continue;
+		const required = parameters["required"];
+		if (!Array.isArray(required)) continue;
+		const list = required.filter((entry) => typeof entry === "string" && entry !== "");
+		if (list.length > 0) requiredParameters.set(name, list);
+	}
+	if (names.size === 0) return void 0;
+	const pinned = typeof obj["tool_choice"] === "string" ? obj["tool_choice"].trim() : "";
+	const pinnedToolName = pinned !== "" && ![
+		"auto",
+		"required",
+		"none"
+	].includes(pinned.toLowerCase()) ? pinned : void 0;
+	return {
+		names,
+		requiredParameters,
+		...pinnedToolName === void 0 ? {} : { pinnedToolName }
+	};
+}
+/**
 * Gateway (openresty/APISIX) rejection of a token it no longer accepts.
 *
 * The business APIs answer JSON; an edge rejection answers an HTML error page
@@ -885,9 +959,26 @@ var WorkBuddyUpstreamClient = class {
 	*
 	* The caller MUST drain {@link WorkBuddyProbeAnswer.response}; an unread body
 	* holds the connection open.
+	*
+	* ALWAYS bounded in time. The pool's batch runner is serial and passes no
+	* signal, so without a ceiling here one stalled connection blocks every account
+	* behind it — the batch looks hung with no way to tell which member did it.
+	* A supplied signal is COMBINED with the timeout rather than replacing it, so
+	* the single-model route keeps its cancellation behaviour and still cannot
+	* hang forever.
+	*
+	* The ceiling covers ONLY the wait for a response — it is cleared the moment
+	* `fetch` resolves. Holding a timer over the body would put a healthy but slow
+	* model on the same clock as a dead endpoint, and the whole point of the
+	* period is to answer "did the upstream answer at all". A probe asks for a
+	* single token, so the body that follows is one SSE line.
 	*/
 	async probeChat(credential, bodyJson, signal) {
 		let response;
+		const ceiling = new AbortController();
+		const timer = setTimeout(() => {
+			ceiling.abort(/* @__PURE__ */ new Error(`no response within ${PROBE_TIMEOUT_MS}ms`));
+		}, PROBE_TIMEOUT_MS);
 		try {
 			response = await fetch(`${chatBase(credential)}/v2/chat/completions`, {
 				method: "POST",
@@ -896,7 +987,7 @@ var WorkBuddyUpstreamClient = class {
 					"Authorization": `Bearer ${credential.accessToken}`
 				},
 				body: bodyJson,
-				...signal === void 0 ? {} : { signal }
+				signal: signal === void 0 ? ceiling.signal : AbortSignal.any([signal, ceiling.signal])
 			});
 		} catch (error) {
 			return {
@@ -905,6 +996,8 @@ var WorkBuddyUpstreamClient = class {
 				retryAfter: null,
 				body: `transport error: ${String(error)}`
 			};
+		} finally {
+			clearTimeout(timer);
 		}
 		const retryAfter = response.headers.get("retry-after");
 		if (response.ok) return {
@@ -2459,7 +2552,7 @@ function generationOf(version) {
 //#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "3.1.0";
+const WORKBUDDY_CONNECT_VERSION = "3.4.0";
 //#endregion
 //#region src/host-heartbeat.ts
 /**
@@ -2617,4 +2710,4 @@ async function clearHostHeartbeat() {
 	await rm(workbuddyHostHeartbeatPath(), { force: true });
 }
 //#endregion
-export { workbuddyAppExecutableCandidates as $, CREDENTIAL_REJECTED_CODE as A, regionOf as B, defaultDesktopAuthPath as C, parseWorkBuddyAuth as D, legacyWorkbuddyOwnAuthPath as E, isCredentialRejectedError as F, fetchAtRestKeyPayload as G, clearAtRestKeyCache as H, parseCreditMultiplier as I, isWorkbuddyBundle as J, findWorkbuddyAppExecutable as K, parseReasoning as L, WorkBuddyCredentialRejectedError as M, WorkBuddyUpstreamClient as N, workbuddyAccountId as O, classifyUpstreamError as P, readAtRestKey as Q, parseUpstreamModel as R, defaultDesktopAuthDirs as S, isEncryptedCredentialError as T, deriveAtRestKey as U, WORKBUDDY_APP_EXECUTABLE_ENV as V, deriveAtRestKeyId as W, macosNestedAppBundles as X, macosBundleExecutable as Y, openEncryptedField as Z, WORKBUDDY_AUTH_FILE_ENV as _, readHostHeartbeat as a, authFileName as b, WORKBUDDY_CONNECT_VERSION as c, FALLBACK_WORKBUDDY_MODELS_GLOBAL as d, WorkBuddyCatalog as f, WORKBUDDY_AUTH_FILENAME as g, ENCRYPTED_CREDENTIAL_CODE as h, processStartTimeMs as i, WORKBUDDY_FALLBACK_SYSTEM_PROMPT as j, workbuddyOwnAuthPath as k, piAiRuntimeInfo as l, fallbackModelsFor as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, deriveCatalog as p, isEncryptedFieldWrapper as q, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS as u, WorkBuddyCredentialStore as v, hasEncryptedCredentialFields as w, defaultDesktopAuthCandidates as x, WorkBuddyEncryptedCredentialError as y, prepareChatBody as z };
+export { readAtRestKey as $, CREDENTIAL_REJECTED_CODE as A, prepareChatBody as B, defaultDesktopAuthPath as C, parseWorkBuddyAuth as D, legacyWorkbuddyOwnAuthPath as E, declaredTools as F, deriveAtRestKeyId as G, WORKBUDDY_APP_EXECUTABLE_ENV as H, isCredentialRejectedError as I, isEncryptedFieldWrapper as J, fetchAtRestKeyPayload as K, parseCreditMultiplier as L, WorkBuddyCredentialRejectedError as M, WorkBuddyUpstreamClient as N, workbuddyAccountId as O, classifyUpstreamError as P, openEncryptedField as Q, parseReasoning as R, defaultDesktopAuthDirs as S, isEncryptedCredentialError as T, clearAtRestKeyCache as U, regionOf as V, deriveAtRestKey as W, macosBundleExecutable as X, isWorkbuddyBundle as Y, macosNestedAppBundles as Z, WORKBUDDY_AUTH_FILE_ENV as _, readHostHeartbeat as a, authFileName as b, WORKBUDDY_CONNECT_VERSION as c, FALLBACK_WORKBUDDY_MODELS_GLOBAL as d, workbuddyAppExecutableCandidates as et, WorkBuddyCatalog as f, WORKBUDDY_AUTH_FILENAME as g, ENCRYPTED_CREDENTIAL_CODE as h, processStartTimeMs as i, WORKBUDDY_FALLBACK_SYSTEM_PROMPT as j, workbuddyOwnAuthPath as k, piAiRuntimeInfo as l, fallbackModelsFor as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, deriveCatalog as p, findWorkbuddyAppExecutable as q, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS as u, WorkBuddyCredentialStore as v, hasEncryptedCredentialFields as w, defaultDesktopAuthCandidates as x, WorkBuddyEncryptedCredentialError as y, parseUpstreamModel as z };

package/lib/index.d.ts

@@ -631,6 +631,19 @@ declare class WorkBuddyUpstreamClient {
    *
    * The caller MUST drain {@link WorkBuddyProbeAnswer.response}; an unread body
    * holds the connection open.
+   *
+   * ALWAYS bounded in time. The pool's batch runner is serial and passes no
+   * signal, so without a ceiling here one stalled connection blocks every account
+   * behind it — the batch looks hung with no way to tell which member did it.
+   * A supplied signal is COMBINED with the timeout rather than replacing it, so
+   * the single-model route keeps its cancellation behaviour and still cannot
+   * hang forever.
+   *
+   * The ceiling covers ONLY the wait for a response — it is cleared the moment
+   * `fetch` resolves. Holding a timer over the body would put a healthy but slow
+   * model on the same clock as a dead endpoint, and the whole point of the
+   * period is to answer "did the upstream answer at all". A probe asks for a
+   * single token, so the body that follows is one SSE line.
    */
   probeChat(credential: WorkBuddyCredential, bodyJson: string, signal?: AbortSignal): Promise<WorkBuddyProbeAnswer>;
   /** POST the token-refresh endpoint; the caller merges the outcome. */
@@ -793,12 +806,62 @@ interface WorkBuddyShim {
   /** Stop serving and destroy open connections. */
   close(): Promise<void>;
 }
+/**
+ * Supplies the credential to retry a failed chat request with.
+ *
+ * Called with every account id already tried for THIS request, the one that just
+ * failed LAST, and resolves to the next candidate — or `undefined` when the pool
+ * is off, empty, or exhausted, in which case the original failure is reported
+ * unchanged.
+ *
+ * The plugin owns the policy (which pool members count as usable, in what
+ * order); the shim owns only the retry loop and the wire-level rule that a
+ * retry may happen before anything has been written to the client.
+ */
+type WorkBuddyFailoverAccount = (triedAccountIds: readonly string[]) => Promise<WorkBuddyCredential | undefined>;
 /** Constructor dependencies. */
 interface WorkBuddyShimOptions {
   store: WorkBuddyCredentialStore;
   client: Pick<WorkBuddyUpstreamClient, 'chatStream'>;
   catalog: WorkBuddyCatalog;
   logger?: ShimLogger;
+  /**
+   * Pool failover for chat requests. Absent means no failover at all — the
+   * pre-pool behaviour, where the selected account serves and its failure is
+   * reported as-is.
+   */
+  failoverAccount?: WorkBuddyFailoverAccount;
+  /**
+   * Called before the FIRST attempt of every chat request, so the plugin can
+   * point the store at the account the pool's ranking says should serve.
+   *
+   * It exists because "who serves" and "who to retry with" are the same decision
+   * made at two moments: the ranking picks the first account, and after a failure
+   * picks the next one. The shim resolves the credential itself right after this
+   * returns, so the ranking never has to produce a credential — which keeps
+   * token REFRESH in one place (`store.resolve()`) instead of duplicating it on
+   * a path that would silently send expired tokens.
+   *
+   * Absent means the store's own selection always serves.
+   */
+  prepareAccount?: () => Promise<void>;
+  /**
+   * Called for every attempt that failed upstream, before the next one is tried.
+   *
+   * Exists so the plugin can RECORD the failure as a measurement. The ranking
+   * that picks the serving account reads the pool's STORED measurements, so
+   * without this an account that just answered 429 still reads as untested — and
+   * the next request picks it again and pays the same failed round trip before
+   * failing over.
+   *
+   * Fired without awaiting: a slow write must never delay the retry the user is
+   * waiting on, and the measurement only matters for LATER requests.
+   */
+  onAccountFailure?: (accountId: string, failure: {
+    status: number;
+    kind: UpstreamErrorKind;
+    message: string;
+  }) => void;
 }
 /**
  * Start the loopback endpoint. Requests must carry the shim's shared secret;
@@ -1468,6 +1531,20 @@ interface WorkBuddyPoolProbe {
    * must never be turned into a locally invented countdown.
    */
   retryAtMs?: number;
+  /**
+   * The upstream's own words on the failure, already redacted.
+   *
+   * Kept so the card can say WHY an account left the pool instead of repeating
+   * one generic sentence for a DNS failure, a gateway 502 and a request the user
+   * cancelled alike. Those three used to render as the SAME line, which left the
+   * user with a message they could not act on and no way to tell a broken
+   * account from a broken network.
+   *
+   * ABSENT for a success, and for any measurement written before this field
+   * existed: an `outcome` without a `message` is a complete, valid record, so
+   * old probe files stay readable rather than being discarded.
+   */
+  message?: string;
 }
 /** One account's live credit situation, as the pool ranks it. */
 interface WorkBuddyPoolCredits {
@@ -1874,6 +1951,15 @@ interface WorkBuddyWebPoolAccount {
     atMs: number;
     /** Only when the upstream named a time; never invented locally. */
     retryAtMs?: number;
+    /**
+     * Why it failed, in the upstream's own redacted words.
+     *
+     * Carried so the pool table can distinguish a DNS failure from a gateway
+     * 502 from a request the user cancelled, instead of repeating one generic
+     * sentence for all three. ABSENT on success and on measurements written
+     * before this field existed, so the card must render the bare outcome then.
+     */
+    message?: string;
   };
   /** Set when this account cannot serve right now. */
   excludedBy?: WorkBuddyWebPoolExclusion;
@@ -1907,8 +1993,13 @@ interface WorkBuddyWebPoolAccount {
  */
 interface WorkBuddyWebPool {
   enabled: boolean;
-  rotateByCredits: boolean;
-  autoTestIntervalMinutes: number;
+  /**
+   * Whether this region offers the daily check-in at all.
+   *
+   * The card hides the action entirely when false, rather than rendering a
+   * button whose only outcome is a refusal.
+   */
+  checkinSupported: boolean;
   /** The model a test would use right now; absent when none can be resolved. */
   targetModelId?: string;
   /**
@@ -1936,15 +2027,6 @@ interface WorkBuddyWebPool {
    * ran on ZERO accounts and reported success.
    */
   effectiveMemberAccountIds?: readonly string[];
-  /**
-   * The account rotation most recently moved billing TO, when it moved.
-   *
-   * Reported so the card can record a switch it did not perform: rotation
-   * happens on the Host (including on a timer), and the card is otherwise
-   * unable to tell a switch from an unchanged state — which would make
-   * "every switch is recorded" a promise the UI could not keep.
-   */
-  rotatedToAccountId?: string;
   accounts: readonly WorkBuddyWebPoolAccount[];
   /**
    * The models a manual target can be chosen from.
@@ -2093,8 +2175,6 @@ interface WorkBuddyPoolDeps {
   /** The region's stored preferences, resolved from the Host config. */
   preferences(region: WorkBuddyRegion): {
     enabled: boolean;
-    rotateByCredits: boolean;
-    autoTestIntervalMinutes: number;
     targetModelId: string;
     memberAccountIds: readonly string[];
   };
@@ -2110,14 +2190,6 @@ interface WorkBuddyPoolDeps {
    * checked) instead of passing the guard and running a batch over nothing.
    */
   effectiveMemberAccountIds?(region: WorkBuddyRegion): Promise<readonly string[]>;
-  /**
-   * The account rotation last redirected billing to, when it did.
-   *
-   * Reported so the card can log a switch that happened on the Host (possibly
-   * on a timer) — without it, "every switch leaves a record" is a promise the
-   * browser half has no way to keep.
-   */
-  rotatedToAccountId?(region: WorkBuddyRegion): Promise<string | undefined>;
   /**
    * Today's check-in state per account id.
    *
@@ -2125,6 +2197,8 @@ interface WorkBuddyPoolDeps {
    * entry) means "not read", which the card renders as unknown rather than as a
    * definite "not checked in" — a claim that would contradict the check-in the
    * user just performed.
+   *
+   * Only the CN region has a check-in to report; see {@link checkinSupported}.
    */
   checkedInToday?(region: WorkBuddyRegion): Promise<Readonly<Record<string, boolean>>>;
   /**
@@ -2137,6 +2211,16 @@ interface WorkBuddyPoolDeps {
   }[]>;
   /** The account currently billing traffic for the region, when known. */
   currentAccountId?(region: WorkBuddyRegion): Promise<string | undefined>;
+  /**
+   * Whether this region offers the daily check-in action at all.
+   *
+   * The CN app rewards a daily check-in; the international region is not offered
+   * one here, so its card must not show the button and its route must refuse the
+   * action. A capability rather than a region name compared in the browser: the
+   * policy belongs in the Host, and the card should not have to know which
+   * regions happen to have the feature.
+   */
+  checkinSupported?(region: WorkBuddyRegion): boolean;
   /**
    * Claim the daily reward for every account of one region.
    *
@@ -2145,8 +2229,15 @@ interface WorkBuddyPoolDeps {
    * reports "unavailable" instead of appearing to succeed.
    */
   checkin?(region: WorkBuddyRegion): Promise<readonly WorkBuddyPoolCheckinRow[]>;
-  /** Test every account of one region against the resolved target model. */
-  test?(region: WorkBuddyRegion, modelId: string): Promise<readonly WorkBuddyPoolTestRow[]>;
+  /**
+   * Test every account of one region against the resolved target model.
+   *
+   * `onRow` is optional and exists so the route can STREAM each account as it
+   * finishes. An older Host ignores it and answers with the whole batch at once;
+   * the route handles both, because a missing reporter must degrade to the
+   * previous behaviour rather than to no rows at all.
+   */
+  test?(region: WorkBuddyRegion, modelId: string, onRow?: (row: WorkBuddyPoolTestRow) => void): Promise<readonly WorkBuddyPoolTestRow[]>;
   /** The region's live catalog, used to resolve the free target model. */
   catalog?(region: WorkBuddyRegion): readonly WorkBuddyModelInfo[];
 }
@@ -2224,18 +2315,21 @@ interface WorkBuddyRegionState {
  * measurement living in the same slot would be rolled back by the next save.
  */
 interface WorkBuddyPoolPreferences {
-  /** Whether the pool is active for this region. Opt-in: default false. */
-  enabled?: boolean;
   /**
-   * Whether the plugin may choose the billed account by credits.
+   * Whether the pool is active for this region — which now means the
+   * FAILOVER switch, not a credit ranking.
    *
-   * Opt-in, and mutually exclusive with manual selection: while it is on, the
-   * card disables the account dropdown, because two writers deciding the same
-   * slot is exactly how "the dropdown says A but B is billed" happens.
+   * Opt-in: default false. While on, a chat request that fails upstream is
+   * retried against the other usable members of this region's pool, in order,
+   * until one serves it or none is left (see `src/shim.ts`). While off the
+   * plugin behaves exactly as it did before the pool existed: the account the
+   * user selected serves every request, and a failure is reported as-is.
+   *
+   * It deliberately does NOT change which account serves NEXT: failover is
+   * per-request borrowing, so the user's selection stays in effect and the
+   * card can keep reporting who really served.
    */
-  rotateByCredits?: boolean;
-  /** Minutes between automatic tests; clamped to 5..1440. */
-  autoTestIntervalMinutes?: number;
+  enabled?: boolean;
   /** Model id to test; `''` means auto-pick a free model from this region. */
   targetModelId?: string;
   /**