dsh-workbuddy-bridge 0.2.0 → 0.3.1

package/lib/{variants-DP0Ho0Tc.js → heartbeat-DihKwwFX.js}

@@ -12,9 +12,8 @@ import { accessSync, constants, realpathSync, statSync } from "node:fs";
 * The international desktop app's version, used as the `/v3/config` UA.
 *
 * The App-shaped catalog is served only to a User-Agent carrying the product
-* name (see `docs/workbuddy-ai-international-research-2026-09-11.md` §2.7).
-* That document's conclusion recommended the space form `WorkBuddy AI/<v>`;
-* re-measured on 2026-09-11 the *space* form is rejected (HTTP 400, code
+* name. The 2026-09-11 research recommended the space form `WorkBuddy AI/<v>`;
+* re-measured the same day the *space* form is rejected (HTTP 400, code
 * 12403) while the terse `WorkBuddyAI/<v>` form — with or without the space
 * removed — returns the 21-model App document. The UA is therefore built from
 * the form verified in code, not from the earlier prose.
@@ -150,8 +149,9 @@ function appUserAgent(version) {
 //#endregion
 //#region src/protocol/client-identity.ts
 /**
-* The desktop-client identity chat requests present as (phase 1 of
-* `docs/upstream-identity-alignment-plan.md`).
+* The desktop-client identity chat requests present as (phase 1 of the upstream
+* identity alignment — unit-covered by `tests/client-identity.spec.ts`, and
+* re-checked against the real upstream by `scripts/client-identity-live-matrix.mjs`).
 *
 * Chat and its probe sibling carry the User-Agent shape the official desktop
 * client composes — `WorkBuddy/<v> <product>/<v> CLI/<cli>` — where the
@@ -163,7 +163,7 @@ function appUserAgent(version) {
 * a missing extension).
 *
 * Scope: chat and probe requests ONLY. Refresh, catalog, and billing keep
-* the headers they have always sent; the plan holds the blast radius to this
+* the headers they have always sent; this phase holds the blast radius to
 * one variable so the live verification matrix stays readable.
 *
 * @module dsh-workbuddy-bridge/client-identity
@@ -500,7 +500,7 @@ function parseJson(body) {
 * The reasoning-effort probe: decide whether a model's `reasoning_effort`
 * parameter is actually validated, and if so which canonical values it accepts.
 *
-* Implements `docs/reasoning-effort-probe-plan.md` §4. The order matters and is
+* The order below is what `tests/probe.spec.ts` asserts. It matters and is
 * not an optimization:
 *
 * 1. **Baseline** (no `reasoning_effort`) proves the model, credential, and
@@ -774,10 +774,10 @@ function originReferer(credential) {
 /** Headers every upstream request shares. */
 function commonHeaders(credential) {
 	return {
-		"Accept": "application/json, text/plain, */*",
+		Accept: "application/json, text/plain, */*",
 		"X-Requested-With": "XMLHttpRequest",
-		"Origin": originReferer(credential),
-		"Referer": `${originReferer(credential)}/`,
+		Origin: originReferer(credential),
+		Referer: `${originReferer(credential)}/`,
 		"User-Agent": CLIENT_UA
 	};
 }
@@ -812,8 +812,8 @@ function refreshHeaders(credential) {
 /** Billing request headers. */
 function billingHeaders(credential) {
 	const headers = {
-		"Authorization": `Bearer ${credential.accessToken}`,
-		"Accept": "application/json",
+		Authorization: `Bearer ${credential.accessToken}`,
+		Accept: "application/json",
 		"Content-Type": "application/json"
 	};
 	if (credential.uid !== "") headers["X-User-Id"] = credential.uid;
@@ -952,7 +952,7 @@ var WorkBuddyUpstreamClient = class {
 				method: "POST",
 				headers: {
 					...chatHeaders(credential, userAgent),
-					"Authorization": `Bearer ${credential.accessToken}`
+					Authorization: `Bearer ${credential.accessToken}`
 				},
 				body: region === "global" ? prepareInternationalChatBody(bodyJson) : bodyJson,
 				...signal === void 0 ? {} : { signal }
@@ -1288,7 +1288,7 @@ var WorkBuddyUpstreamClient = class {
 				method: "POST",
 				headers: {
 					...chatHeaders(credential, userAgent),
-					"Authorization": `Bearer ${credential.accessToken}`
+					Authorization: `Bearer ${credential.accessToken}`
 				},
 				body: JSON.stringify(payload),
 				signal
@@ -2342,6 +2342,107 @@ function discoveryIncomplete(detail) {
 const HELPER_SCRIPT = "process.stdout.write(String(process._linkedBinding(\"electron_browser_workbuddy_storage\").loggerGet()))";
 const HELPER_SCRIPT_ARGUMENT_FLAG = "-e";
 //#endregion
+//#region src/shared/paths.ts
+/** Node-free constants and types shared by the Host and browser halves. */
+/** Plugin-owned status endpoint consumed by its browser half. */
+const WORKBUDDY_STATUS_PATH = "/plugins/dsh-workbuddy-bridge/status";
+/**
+* Plugin-owned probe control endpoint.
+*
+* Separate from the status route because it accepts writes: the status route's
+* loopback Host/Origin guard protects against a DNS-rebinding *page*, which is
+* not the same as authorizing a state-changing action. This route therefore
+* also requires the in-memory key the browser half receives with the status
+* document.
+*/
+const WORKBUDDY_PROBE_PATH = "/plugins/dsh-workbuddy-bridge/probe";
+/**
+* The international (WorkBuddy AI) variant's own pair of routes.
+*
+* Kept as separate constants rather than a computed suffix so both halves
+* reference literal strings: the browser bundle and the host bundle are built
+* independently, and a shared expression is one build-config drift away from
+* the desk asking a route the host never mounted.
+*/
+const WORKBUDDY_AI_STATUS_PATH = "/plugins/dsh-workbuddy-bridge/ai/status";
+const WORKBUDDY_AI_PROBE_PATH = "/plugins/dsh-workbuddy-bridge/ai/probe";
+/**
+* Plugin-owned per-message credit route.
+*
+* A read-only GET taking `?sessionId=…`, answering `messageId → credit` for one
+* Session. It is its own route rather than a field of the status document
+* because the two have different lifetimes: the status document is per
+* *account* and is re-read when the account changes, while credit accounting
+* is per *Session* and grows as messages are sent.
+*
+* **One route for both variants, on purpose.** The accounting is attributed to
+* a DSH `messageId` before it is stored, and a message id belongs to one
+* Session regardless of which provider served it — a conversation can switch
+* between the two WorkBuddy products (or away from both) mid-thread. A route
+* per variant would force the message row to know which provider answered a
+* message *it is merely labelling*, and would strand every message whose turn
+* ran under the other variant.
+*
+* No key is required: the route only reads what this plugin already observed on
+* its own loopback stream, carries no credential material, and answers loopback
+* requests through the same Host/Origin guard as the status route.
+*/
+const WORKBUDDY_CREDIT_PATH = "/plugins/dsh-workbuddy-bridge/credit";
+//#endregion
+//#region src/variants.ts
+/**
+* The two WorkBuddy desktop apps this one plugin serves.
+*
+* Both products are the same client framework in different regions, and both
+* write their sign-in into the *same* shared `CodeBuddyExtension` auth
+* directory — they differ by file basename, base URL, catalog endpoint, and
+* display identity. Everything that varies between them is collected here as
+* one descriptor, so no module has to carry its own `if (international)`
+* branch and a third variant would be a data change rather than a refactor.
+*
+* This module is host-side (it names files and env vars). The browser half
+* takes the same ids and routes from the Node-free `status-paths.ts`, which
+* stays the single source shared by both halves.
+*
+* @module dsh-workbuddy-bridge/variants
+*/
+/** CN WorkBuddy first: the existing provider keeps its id, paths, and copy. */
+const WORKBUDDY_VARIANTS = [{
+	id: "workbuddy",
+	displayName: "WorkBuddy",
+	appName: "WorkBuddy",
+	region: "cn",
+	env: "WORKBUDDY_AUTH_FILE",
+	desktopFilename: "workbuddy-desktop.info",
+	ownFilename: ".workbuddy-auth.json",
+	probeFilename: ".workbuddy-probe.json",
+	catalogFilename: ".workbuddy-catalog.json",
+	visibilityFilename: ".workbuddy-model-visibility.json",
+	statusPath: WORKBUDDY_STATUS_PATH,
+	probePath: WORKBUDDY_PROBE_PATH
+}, {
+	id: "workbuddy-ai",
+	displayName: "WorkBuddy AI",
+	appName: "WorkBuddy AI",
+	region: "global",
+	env: "WORKBUDDY_AI_AUTH_FILE",
+	desktopFilename: "workbuddy-desktop-ai.info",
+	ownFilename: ".workbuddy-ai-auth.json",
+	probeFilename: ".workbuddy-ai-probe.json",
+	catalogFilename: ".workbuddy-ai-catalog.json",
+	visibilityFilename: ".workbuddy-ai-model-visibility.json",
+	statusPath: WORKBUDDY_AI_STATUS_PATH,
+	probePath: WORKBUDDY_AI_PROBE_PATH
+}];
+/** The CN variant; the plugin's long-standing default and compatibility anchor. */
+const CN_VARIANT = WORKBUDDY_VARIANTS[0];
+/** The international variant. */
+const AI_VARIANT = WORKBUDDY_VARIANTS[1];
+/** Look up a variant by provider id. */
+function variantFor(id) {
+	return WORKBUDDY_VARIANTS.find((variant) => variant.id === id);
+}
+//#endregion
 //#region src/credential/store.ts
 /**
 * WorkBuddy credential resolution. The primary source is the WorkBuddy
@@ -2528,6 +2629,38 @@ function isENOENT(error) {
 	return error?.code === "ENOENT";
 }
 /**
+* Which automatic at-rest key discovery this store may run, by variant.
+*
+* **One home for a rule that had three.** The choice used to be made at every
+* call site — `src/index.ts` and `src/cli/bin.ts` each spelled out
+* `discovery: variant.id === CN_VARIANT.id ? cnAppDiscovery() : 'none'` — and the
+* store's own default was a bare `new WorkBuddyAtRestKeyProvider()`, whose
+* discovery is `'none'`. So a caller that did neither got a provider that could
+* never open an encrypted credential: `scripts/live-e2e.mjs` was exactly that
+* caller, and it failed with `electron-binary-unavailable` on every platform
+* (2026-10-03, found by the release checklist). The store knows its variant, so
+* the choice belongs here.
+*
+* Why the difference is deliberate:
+*
+* - Only the CN WorkBuddy install has been verified to hold the key its envelopes
+*   name, and only its macOS/Windows layout is known, so CN may look for the app.
+* - A Global (WorkBuddy AI) encrypted credential has never been seen live, so that
+*   variant runs at `'none'` — no default path and no app search. A Global unlock
+*   must not silently execute the *CN* app's Electron. An explicit
+*   `WORKBUDDY_ELECTRON_BIN` still works for Global.
+*
+* **No variant** means the CN product's own default file —
+* `defaultDesktopAuthCandidates()` is the `workbuddy-desktop.info` path, never the
+* AI one — so it gets the same discovery CN does.
+*
+* A keyId mismatch is still reported as a diagnosis rather than a wrong open, and
+* the helper only runs if an encrypted credential is actually read.
+*/
+function atRestDiscoveryFor(variant) {
+	return variant === void 0 || variant.id === CN_VARIANT.id ? cnAppDiscovery() : "none";
+}
+/**
 * Read-only credential store with demand-driven refresh.
 *
 * Refresh policy: refresh only when the access token is inside the margin
@@ -2549,7 +2682,7 @@ var WorkBuddyCredentialStore = class {
 		this.refresh = options.refresh;
 		this.refreshMarginMs = options.refreshMarginMs ?? 3e5;
 		this.ownPath = options.ownPath ?? (options.variant ? join(resolveDshHome(), options.variant.ownFilename) : workbuddyOwnAuthPath());
-		this.keyProvider = options.keyProvider ?? new WorkBuddyAtRestKeyProvider();
+		this.keyProvider = options.keyProvider ?? new WorkBuddyAtRestKeyProvider({ discovery: atRestDiscoveryFor(options.variant) });
 		this.desktopPathOverride = options.desktopPath;
 	}
 	/**
@@ -2624,6 +2757,7 @@ var WorkBuddyCredentialStore = class {
 				expiresAtMs: credential.expiresAtMs,
 				...credential.refreshExpiresAtMs === void 0 ? {} : { refreshExpiresAtMs: credential.refreshExpiresAtMs },
 				...credential.nickname === void 0 ? {} : { nickname: credential.nickname },
+				...credential.uid === "" ? {} : { uid: credential.uid },
 				...credential.domain === "" ? {} : { domain: credential.domain },
 				source: credential.source
 			};
@@ -2663,7 +2797,7 @@ var WorkBuddyCredentialStore = class {
 			return refreshed;
 		} catch (error) {
 			if (credential.expiresAtMs > Date.now() + 3e4) return credential;
-			throw new Error(`workbuddy: token refresh failed and the access token is expired (${String(error)}); open the WorkBuddy desktop app once to sign in again`);
+			throw new Error(`workbuddy: token refresh failed and the access token is expired (${String(error)}); open the WorkBuddy desktop app once to sign in again`, { cause: error });
 		}
 	}
 	async saveOwn(credential) {
@@ -3553,33 +3687,8 @@ var WorkBuddyCatalog = class {
 	}
 };
 //#endregion
-//#region src/shared/paths.ts
-/** Node-free constants and types shared by the Host and browser halves. */
-/** Plugin-owned status endpoint consumed by its browser half. */
-const WORKBUDDY_STATUS_PATH = "/plugins/dsh-workbuddy-bridge/status";
-/**
-* Plugin-owned probe control endpoint.
-*
-* Separate from the status route because it accepts writes: the status route's
-* loopback Host/Origin guard protects against a DNS-rebinding *page*, which is
-* not the same as authorizing a state-changing action. This route therefore
-* also requires the in-process key the browser half receives with the status
-* document.
-*/
-const WORKBUDDY_PROBE_PATH = "/plugins/dsh-workbuddy-bridge/probe";
-/**
-* The international (WorkBuddy AI) variant's own pair of routes.
-*
-* Kept as separate constants rather than a computed suffix so both halves
-* reference literal strings: the browser bundle and the host bundle are built
-* independently, and a shared expression is one build-config drift away from
-* the desk asking a route the host never mounted.
-*/
-const WORKBUDDY_AI_STATUS_PATH = "/plugins/dsh-workbuddy-bridge/ai/status";
-const WORKBUDDY_AI_PROBE_PATH = "/plugins/dsh-workbuddy-bridge/ai/probe";
-//#endregion
 //#region src/version.ts
-const WORKBUDDY_BRIDGE_VERSION = "0.2.0";
+const WORKBUDDY_BRIDGE_VERSION = "0.3.1";
 //#endregion
 //#region src/web/heartbeat.ts
 /**
@@ -3750,58 +3859,4 @@ function isHeartbeatProcessAlive(heartbeat) {
 	return startAtMs <= heartbeat.registeredAt;
 }
 //#endregion
-//#region src/variants.ts
-/**
-* The two WorkBuddy desktop apps this one plugin serves.
-*
-* Both products are the same client framework in different regions, and both
-* write their sign-in into the *same* shared `CodeBuddyExtension` auth
-* directory — they differ by file basename, base URL, catalog endpoint, and
-* display identity. Everything that varies between them is collected here as
-* one descriptor, so no module has to carry its own `if (international)`
-* branch and a third variant would be a data change rather than a refactor.
-*
-* This module is host-side (it names files and env vars). The browser half
-* takes the same ids and routes from the Node-free `status-paths.ts`, which
-* stays the single source shared by both halves.
-*
-* @module dsh-workbuddy-bridge/variants
-*/
-/** CN WorkBuddy first: the existing provider keeps its id, paths, and copy. */
-const WORKBUDDY_VARIANTS = [{
-	id: "workbuddy",
-	displayName: "WorkBuddy",
-	appName: "WorkBuddy",
-	region: "cn",
-	env: "WORKBUDDY_AUTH_FILE",
-	desktopFilename: "workbuddy-desktop.info",
-	ownFilename: ".workbuddy-auth.json",
-	probeFilename: ".workbuddy-probe.json",
-	catalogFilename: ".workbuddy-catalog.json",
-	visibilityFilename: ".workbuddy-model-visibility.json",
-	statusPath: WORKBUDDY_STATUS_PATH,
-	probePath: WORKBUDDY_PROBE_PATH
-}, {
-	id: "workbuddy-ai",
-	displayName: "WorkBuddy AI",
-	appName: "WorkBuddy AI",
-	region: "global",
-	env: "WORKBUDDY_AI_AUTH_FILE",
-	desktopFilename: "workbuddy-desktop-ai.info",
-	ownFilename: ".workbuddy-ai-auth.json",
-	probeFilename: ".workbuddy-ai-probe.json",
-	catalogFilename: ".workbuddy-ai-catalog.json",
-	visibilityFilename: ".workbuddy-ai-model-visibility.json",
-	statusPath: WORKBUDDY_AI_STATUS_PATH,
-	probePath: WORKBUDDY_AI_PROBE_PATH
-}];
-/** The CN variant; the plugin's long-standing default and compatibility anchor. */
-const CN_VARIANT = WORKBUDDY_VARIANTS[0];
-/** The international variant. */
-const AI_VARIANT = WORKBUDDY_VARIANTS[1];
-/** Look up a variant by provider id. */
-function variantFor(id) {
-	return WORKBUDDY_VARIANTS.find((variant) => variant.id === id);
-}
-//#endregion
-export { normalizeCredits as A, FALLBACK_CN_APP_VERSION as B, desktopAuthCandidatesFor as C, cnAppDiscovery as D, WorkBuddyAtRestKeyProvider as E, PROBE_EFFORT_CANDIDATES as F, validCliVersion as G, fallbackChatIdentity as H, probeModel as I, installedAppVersion as J, WORKBUDDY_APP_VERSION_FILENAME as K, randomSentinel as L, prepareChatBody as M, prepareInternationalChatBody as N, WorkBuddyUpstreamClient as O, regionOf as P, classifyUpstreamError as R, defaultDesktopAuthPath as S, workbuddyOwnAuthPath as T, readCliVersion as U, chatUserAgent as V, resolveChatIdentity as W, resolveAppVersion as X, readBundleVersion as Y, validAppVersion as Z, WorkBuddyCatalog as _, WORKBUDDY_HOST_HEARTBEAT_FILENAME as a, WorkBuddyCredentialStore as b, processStartTimeMs as c, writeHostHeartbeat as d, WORKBUDDY_BRIDGE_VERSION as f, FALLBACK_WORKBUDDY_MODELS as g, FALLBACK_WORKBUDDY_AI_MODELS as h, variantFor as i, parseModelCatalog as j, modelWithCurrentPromotion as k, readHostHeartbeat as l, WORKBUDDY_STATUS_PATH as m, CN_VARIANT as n, clearHostHeartbeat as o, WORKBUDDY_PROBE_PATH as p, appUserAgent as q, WORKBUDDY_VARIANTS as r, isHeartbeatProcessAlive as s, AI_VARIANT as t, workbuddyHostHeartbeatPath as u, WORKBUDDY_AUTH_FILENAME as v, parseWorkBuddyAuth as w, defaultDesktopAuthCandidates as x, WORKBUDDY_AUTH_FILE_ENV as y, CN_APP_VERSION_FILENAME as z };
+export { parseModelCatalog as A, chatUserAgent as B, variantFor as C, WorkBuddyUpstreamClient as D, WORKBUDDY_STATUS_PATH as E, probeModel as F, WORKBUDDY_APP_VERSION_FILENAME as G, readCliVersion as H, randomSentinel as I, readBundleVersion as J, appUserAgent as K, classifyUpstreamError as L, prepareInternationalChatBody as M, regionOf as N, modelWithCurrentPromotion as O, PROBE_EFFORT_CANDIDATES as P, CN_APP_VERSION_FILENAME as R, WORKBUDDY_VARIANTS as S, WORKBUDDY_PROBE_PATH as T, resolveChatIdentity as U, fallbackChatIdentity as V, validCliVersion as W, validAppVersion as X, resolveAppVersion as Y, desktopAuthCandidatesFor as _, readHostHeartbeat as a, AI_VARIANT as b, WORKBUDDY_BRIDGE_VERSION as c, WorkBuddyCatalog as d, WORKBUDDY_AUTH_FILENAME as f, defaultDesktopAuthPath as g, defaultDesktopAuthCandidates as h, processStartTimeMs as i, prepareChatBody as j, normalizeCredits as k, FALLBACK_WORKBUDDY_AI_MODELS as l, WorkBuddyCredentialStore as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, WORKBUDDY_AUTH_FILE_ENV as p, installedAppVersion as q, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS as u, parseWorkBuddyAuth as v, WORKBUDDY_CREDIT_PATH as w, CN_VARIANT as x, workbuddyOwnAuthPath as y, FALLBACK_CN_APP_VERSION as z };

package/lib/index.d.ts

@@ -1,9 +1,51 @@
 import z from "@deepseek-ai/schemastery";
 import "@earendil-works/pi-ai";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
+import { IncomingMessage, ServerResponse } from "node:http";
 import { Context, Volatile } from "@deepseek-ai/cordis";
 import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
 //#region src/shared/paths.d.ts
+/**
+ * Plugin-owned per-message credit route.
+ *
+ * A read-only GET taking `?sessionId=…`, answering `messageId → credit` for one
+ * Session. It is its own route rather than a field of the status document
+ * because the two have different lifetimes: the status document is per
+ * *account* and is re-read when the account changes, while credit accounting
+ * is per *Session* and grows as messages are sent.
+ *
+ * **One route for both variants, on purpose.** The accounting is attributed to
+ * a DSH `messageId` before it is stored, and a message id belongs to one
+ * Session regardless of which provider served it — a conversation can switch
+ * between the two WorkBuddy products (or away from both) mid-thread. A route
+ * per variant would force the message row to know which provider answered a
+ * message *it is merely labelling*, and would strand every message whose turn
+ * ran under the other variant.
+ *
+ * No key is required: the route only reads what this plugin already observed on
+ * its own loopback stream, carries no credential material, and answers loopback
+ * requests through the same Host/Origin guard as the status route.
+ */
+declare const WORKBUDDY_CREDIT_PATH = "/plugins/dsh-workbuddy-bridge/credit";
+/**
+ * The credit route's answer: one Session's per-message costs.
+ *
+ * `credits` is keyed by DSH `messageId` and is always present (an empty object
+ * when nothing is recorded), so the browser half reads one shape instead of
+ * distinguishing "no data yet" from "no costs".
+ *
+ * A message *absent* from `credits` means this plugin observed no cost for it —
+ * a message predating the feature, a stream that failed before its final frame,
+ * or an upstream answer that carried no `credit` field. It never means zero, so
+ * the row renders nothing rather than a confident `0`.
+ *
+ * Distinct from {@link WorkBuddyWebCredits}, which is the account's *remaining*
+ * balance for the card. This one is what individual messages *spent*.
+ */
+interface WorkBuddyWebSessionCredits {
+  sessionId: string;
+  credits: Readonly<Record<string, number>>;
+}
 /**
  * Why no credential is usable, as a closed enum the browser half switches on.
  *
@@ -864,6 +906,14 @@ interface WorkBuddyAuthStatus {
   expiresAtMs?: number;
   refreshExpiresAtMs?: number;
   nickname?: string;
+  /**
+   * The account's own id (`account.uid`), when the credential carries one.
+   *
+   * The fallback display name: the desktop document is the only source of a
+   * nickname, and it does not always have one. Non-secret — the same identity
+   * the per-account state is keyed by, sent upstream as `X-User-Id`.
+   */
+  uid?: string;
   domain?: string;
   source?: 'desktop' | 'dsh';
   /**
@@ -891,9 +941,10 @@ interface WorkBuddyStoreOptions {
   refreshMarginMs?: number;
   /**
    * Resolver for WorkBuddy 5.6's at-rest protector key, needed when the
-   * desktop file stores encrypted token fields. Defaults to the real
-   * provider, which spawns the WorkBuddy Electron binary; tests stand in a
-   * stub. Structural so a store never depends on how the key is reached.
+   * desktop file stores encrypted token fields. Defaults to the real provider
+   * with the discovery this store's variant may run — see
+   * {@link atRestDiscoveryFor}. Tests stand in a stub; the shape is structural
+   * so a store never depends on how the key is reached.
    */
   keyProvider?: Pick<WorkBuddyAtRestKeyProvider, 'protectorKeyFor' | 'helperPath'>;
 }
@@ -1234,6 +1285,15 @@ interface WorkBuddyShimOptions {
   client: Pick<WorkBuddyUpstreamClient, 'chatStream'>;
   catalog: WorkBuddyCatalog;
   logger?: ShimLogger;
+  /**
+   * Observe what one upstream response cost, as the upstream reports it.
+   *
+   * Called at most once per response, at the frame carrying the number, with
+   * the stream's own response id (`cmb-…`) — the same id DSH records on the
+   * assistant message, which is what lets the Host half attribute a cost to a
+   * message instead of guessing.
+   */
+  observeCredit?: (responseId: string, credit: number) => void;
 }
 /**
  * Start the loopback endpoint. Requests carry any bearer; the loopback bind
@@ -1292,6 +1352,129 @@ interface WorkBuddyAdapter {
  */
 declare function createWorkBuddyAdapter(options: WorkBuddyAdapterOptions): WorkBuddyAdapter;
 //#endregion
+//#region src/llm/credit-log.d.ts
+/**
+ * Per-message credit accounting, as two plain registries the Host half fills.
+ *
+ * WorkBuddy reports what a message actually cost as a `credit` field on the
+ * last usage frame of its OpenAI-compatible SSE stream. That number is
+ * **server-supplied**: the desktop app accumulates `cost.amount` stage
+ * increments and never multiplies tokens by the catalog's `x0.79` multiplier
+ * (the multiplier is display copy). So the plugin must not invent a formula —
+ * it observes the number where it exists.
+ *
+ * The field travels on the stream the shim already proxies, and the same
+ * stream carries the upstream response id (`cmb-…`) that DSH records on the
+ * assistant message as `source.replayState.response.responseId`. That pair is
+ * what makes attribution exact rather than guessed:
+ *
+ * ```text
+ *   SSE id + SSE usage.credit  ──►  creditLog.record(id, credit)
+ *                                        │
+ *   session/event assistant/message ─────┴──► index.set(sessionId, messageId, credit)
+ *        (messageId, responseId)                      │
+ *                                              browser row fetches by messageId
+ * ```
+ *
+ * Both structures are pure data with no Host dependencies, so the matching
+ * rules are unit-testable without a Session, a socket, or an upstream.
+ *
+ * @module dsh-workbuddy-bridge/credit-log
+ */
+/**
+ * Bounded `responseId → credit` registry, with one-shot waiters.
+ *
+ * The waiter exists because the two writes race in principle: the shim sees the
+ * credit when the last SSE frame arrives, while the Session event that names
+ * the response id is appended when the stream settles. Either order must
+ * produce the same attribution, so a lookup that misses registers interest and
+ * is answered by the next `record` instead of silently reporting "unknown".
+ */
+declare class WorkBuddyCreditLog {
+  private readonly limit;
+  /**
+   * Insertion-ordered, so eviction is FIFO. A `Map` is used rather than an
+   * object because the response id is attacker-influenced text: a plain object
+   * would let `__proto__` reach the prototype chain.
+   */
+  private readonly credits;
+  /** Pending attributions, keyed by response id; each resolves at most once. */
+  private readonly waiters;
+  constructor(limit?: number);
+  /**
+   * Remember what one response cost.
+   *
+   * A non-finite or negative value is refused rather than stored: the field is
+   * remote input, and a `NaN` reaching the browser would render as `NaN` in the
+   * credit label instead of being reported as unknown.
+   */
+  record(responseId: string, credit: number): void;
+  /** What one response cost, or undefined when it was never observed. */
+  lookup(responseId: string): number | undefined;
+  /**
+   * Call `onCredit` once, when this response's credit becomes known.
+   *
+   * @returns a canceller; calling it after the credit landed is a no-op.
+   */
+  await(responseId: string, onCredit: (credit: number) => void): () => void;
+  /** Drop the oldest entries until the log is inside its bound. */
+  private evict;
+}
+/**
+ * `sessionId → messageId → credit`, the shape the browser row reads.
+ *
+ * Nested rather than a flat `messageId → credit` map so the route can answer
+ * one Session without shipping every Session's accounting, and so a Session's
+ * rows can be dropped as a unit.
+ */
+declare class WorkBuddySessionCreditIndex {
+  private readonly perSessionLimit;
+  /** Per-Session maps, each bounded independently. */
+  private readonly sessions;
+  constructor(perSessionLimit?: number);
+  /** Attribute one message's cost, refreshing its position in its Session. */
+  set(sessionId: string, messageId: string, credit: number): void;
+  /**
+   * One Session's accounting as a plain object, or an empty object when the
+   * Session has none. Always an object, never undefined: the browser half then
+   * needs no "no data yet" branch distinct from "no credits recorded".
+   */
+  forSession(sessionId: string): Record<string, number>;
+  /** Forget one Session's accounting, e.g. when it leaves the store. */
+  delete(sessionId: string): void;
+}
+//#endregion
+//#region src/web/credit.d.ts
+/** Constructor dependencies. */
+interface WorkBuddyCreditRouteOptions {
+  /** The accounting to read from; see {@link WorkBuddySessionCreditIndex}. */
+  credits: WorkBuddySessionCreditIndex;
+  /**
+   * Route path to mount, defaulting to the CN variant's. The international
+   * variant passes its own so the two halves never share a route: the browser
+   * bundle and the host bundle are built independently, and a computed path is
+   * one build-config drift away from asking a route that was never mounted.
+   */
+  path?: string;
+}
+/**
+ * One Session's accounting.
+ *
+ * A missing `sessionId` is answered with an empty document rather than an
+ * error: the browser half asks on behalf of whatever Session it is rendering,
+ * and "this Session has no recorded costs" is a normal, silent state — the row
+ * simply shows no label.
+ *
+ * @param deps - the accounting index.
+ * @param sessionId - the Session to answer for.
+ * @returns the document the browser half renders from.
+ */
+declare function workBuddySessionCredits(deps: WorkBuddyCreditRouteOptions, sessionId: string): WorkBuddyWebSessionCredits;
+/** The credit route's request handler, extracted so tests can mount it bare. */
+declare function workBuddyCreditHandler(deps: WorkBuddyCreditRouteOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** Mount the GET credit route on an optional webServer context. */
+declare function registerWorkBuddyCreditRoute(ctx: Context, deps: WorkBuddyCreditRouteOptions): void;
+//#endregion
 //#region src/catalog/store.d.ts
 /** Basename of the CN variant's saved catalog inside the Harness home. */
 declare const WORKBUDDY_CATALOG_FILENAME = ".workbuddy-catalog.json";
@@ -1639,4 +1822,4 @@ declare function visibilityAccountOf(credential: Pick<WorkBuddyCredential, 'uid'
  */
 declare function apply(ctx: Context, refs: ConfigRefs): void;
 //#endregion
-export { AI_VARIANT, type AppVersionInfo, CN_APP_VERSION_FILENAME, CN_VARIANT, type ChatIdentity, Config, ConfigRefs, FALLBACK_CN_APP_VERSION, FALLBACK_WORKBUDDY_AI_MODELS, FALLBACK_WORKBUDDY_MODELS, PROBE_EFFORT_CANDIDATES, type ProbeAttempt, type ProbeOutcome, type ProbeSender, type ResolveChatIdentityOptions, type UpstreamErrorKind, WORKBUDDY_APP_VERSION_FILENAME, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CATALOG_FILENAME, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_PROBE_FILENAME, WORKBUDDY_PROVIDER, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_VARIANTS, WORKBUDDY_VISIBILITY_FILENAME, type WorkBuddyAdapter, type WorkBuddyAppVersionSource, type WorkBuddyAuthStatus, WorkBuddyCatalog, type WorkBuddyCatalogFetch, WorkBuddyCatalogStore, type WorkBuddyChatResult, type WorkBuddyCredential, WorkBuddyCredentialStore, type WorkBuddyCredits, type WorkBuddyEffort, type WorkBuddyHostHeartbeat, type WorkBuddyModelBilling, type WorkBuddyModelInfo, type WorkBuddyModelReasoning, type WorkBuddyProbeRecord, WorkBuddyProbeService, type WorkBuddyProbeStatus, WorkBuddyProbeStore, type WorkBuddyProbeValidation, type WorkBuddyPromotion, type WorkBuddyRefreshOutcome, type WorkBuddyShim, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyVariant, WorkBuddyVisibilityStore, appUserAgent, apply, chatUserAgent, classifyUpstreamError, clearHostHeartbeat, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthPath, desktopAuthCandidatesFor, fallbackChatIdentity, fingerprintModel, inject, installedAppVersion, isHeartbeatProcessAlive, modelWithCurrentPromotion, name, normalizeCredits, parseModelCatalog, parseWorkBuddyAuth, prepareChatBody, prepareInternationalChatBody, probeModel, processStartTimeMs, randomSentinel, readBundleVersion, readCliVersion, readHostHeartbeat, regionOf, resolveAppVersion, resolveChatIdentity, validAppVersion, validCliVersion, variantFor, visibilityAccountOf, workbuddyCatalogPath, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, workbuddyProbePath, workbuddyVisibilityPath };
+export { AI_VARIANT, type AppVersionInfo, CN_APP_VERSION_FILENAME, CN_VARIANT, type ChatIdentity, Config, ConfigRefs, FALLBACK_CN_APP_VERSION, FALLBACK_WORKBUDDY_AI_MODELS, FALLBACK_WORKBUDDY_MODELS, PROBE_EFFORT_CANDIDATES, type ProbeAttempt, type ProbeOutcome, type ProbeSender, type ResolveChatIdentityOptions, type UpstreamErrorKind, WORKBUDDY_APP_VERSION_FILENAME, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CATALOG_FILENAME, WORKBUDDY_CREDIT_PATH, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_PROBE_FILENAME, WORKBUDDY_PROVIDER, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_VARIANTS, WORKBUDDY_VISIBILITY_FILENAME, type WorkBuddyAdapter, type WorkBuddyAppVersionSource, type WorkBuddyAuthStatus, WorkBuddyCatalog, type WorkBuddyCatalogFetch, WorkBuddyCatalogStore, type WorkBuddyChatResult, type WorkBuddyCredential, WorkBuddyCredentialStore, WorkBuddyCreditLog, type WorkBuddyCreditRouteOptions, type WorkBuddyCredits, type WorkBuddyEffort, type WorkBuddyHostHeartbeat, type WorkBuddyModelBilling, type WorkBuddyModelInfo, type WorkBuddyModelReasoning, type WorkBuddyProbeRecord, WorkBuddyProbeService, type WorkBuddyProbeStatus, WorkBuddyProbeStore, type WorkBuddyProbeValidation, type WorkBuddyPromotion, type WorkBuddyRefreshOutcome, WorkBuddySessionCreditIndex, type WorkBuddyShim, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyVariant, WorkBuddyVisibilityStore, type WorkBuddyWebSessionCredits, appUserAgent, apply, chatUserAgent, classifyUpstreamError, clearHostHeartbeat, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthPath, desktopAuthCandidatesFor, fallbackChatIdentity, fingerprintModel, inject, installedAppVersion, isHeartbeatProcessAlive, modelWithCurrentPromotion, name, normalizeCredits, parseModelCatalog, parseWorkBuddyAuth, prepareChatBody, prepareInternationalChatBody, probeModel, processStartTimeMs, randomSentinel, readBundleVersion, readCliVersion, readHostHeartbeat, regionOf, registerWorkBuddyCreditRoute, resolveAppVersion, resolveChatIdentity, validAppVersion, validCliVersion, variantFor, visibilityAccountOf, workBuddyCreditHandler, workBuddySessionCredits, workbuddyCatalogPath, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, workbuddyProbePath, workbuddyVisibilityPath };