cartethyia 2.6.7 → 2.7.1

package/src/providers/default-registry.ts

@@ -366,10 +366,11 @@ export const PROVIDER_CAPABILITIES = {
     // catalog row behind it.
     // Dispatch base, not the catalog base: `/zen/v1/models` publishes the
     // listing while `/inference/v1/models` answers 404, and a byte-exact replay
-    // against `/inference/v1` returned 200 where `/zen/v1` did not.
+    // against `/inference/v1` returned 200 where `/zen/v1` did not. The wire
+    // paths are the 2.1 family-segment shapes on the `/inference` origin.
     endpointPathsByWireFamily: {
-      chat: "/inference/v1/chat/completions",
-      responses: "/inference/v1/responses",
+      chat: "/inference/openai/v1/chat/completions",
+      responses: "/inference/openai/v1/responses",
     },
     loadAdapter: async () => createApiKeyAdapter((await import("./integrations/opencode/provider")).OPENCODE_FREE_SPEC),
     loadModels: async () => (await import("./integrations/opencode/provider")).OPENCODE_FREE_MODELS,
@@ -386,8 +387,8 @@ export const PROVIDER_CAPABILITIES = {
   },
   "opencode-zen": {
     endpointPathsByWireFamily: {
-      chat: "/inference/v1/chat/completions",
-      responses: "/inference/v1/responses",
+      chat: "/inference/openai/v1/chat/completions",
+      responses: "/inference/openai/v1/responses",
     },
     loadAdapter: async () => createApiKeyAdapter((await import("./integrations/opencode/provider")).OPENCODE_ZEN_SPEC),
     loadModels: async () => (await import("./integrations/opencode/provider")).OPENCODE_ZEN_MODELS,
@@ -554,6 +555,21 @@ export const PROVIDER_CAPABILITIES = {
       });
     },
   },
+  inception: {
+    // Chat only: Mercury 3 / 2.5 / 2 answer the OpenAI-compatible chat wire.
+    // The base is version-rooted (`/v1`), so the path is declared below it.
+    endpointPathsByWireFamily: { chat: "/chat/completions" },
+    loadAdapter: async () => createApiKeyAdapter((await import("./integrations/inception/provider")).INCEPTION_SPEC),
+    loadModels: async () => (await import("./integrations/inception/provider")).INCEPTION_MODELS,
+    // The listing is bearer-authenticated and the whole provider is pinned to
+    // its free allowance, so every fetched row is stamped free-tier.
+    loadModelDiscovery: async () => async ({ baseUrl, credential, fetcher }) =>
+      (await import("./integrations/inception/provider")).discoverInceptionFreeModels({
+        baseUrl,
+        ...(typeof credential === "string" && credential.length > 0 ? { credential } : {}),
+        ...(fetcher === undefined ? {} : { fetcher }),
+      }),
+  },
   openrouter: {
     loadAdapter: async () => createApiKeyAdapter((await import("./integrations/openrouter/provider")).OPENROUTER_SPEC),
     // One dynamic import for both halves: this registry lazy-loads every

package/src/providers/discovery/probe-phases.ts

@@ -168,6 +168,8 @@ export interface ProbeTarget {
    * so the probe tests the route, not an empty stand-in.
    */
   readonly capabilityProfile: Readonly<Record<string, boolean>>;
+  /** The model row's output ceiling, when it declares one. */
+  readonly outputLimit?: number | null;
 }
 
 /**
@@ -217,10 +219,11 @@ export async function resolveProbeTarget(args: {
   let serviceKind: ServiceKind = requestedServiceKind;
   // Capability columns for the row the probe lands on. Resolved alongside the
   // wire so the profile describes the same row the probe dispatches to.
-  let capabilitySource: { modalities: unknown; reasoning: boolean; toolCall: boolean } = {
+  let capabilitySource: { modalities: unknown; reasoning: boolean; toolCall: boolean; outputLimit: number | null } = {
     modalities: null,
     reasoning: false,
     toolCall: false,
+    outputLimit: null,
   };
   if (request.wireFamily) {
     wireFamily = request.wireFamily as WireFamily;
@@ -242,6 +245,7 @@ export async function resolveProbeTarget(args: {
         modalities: staticDef.modalities,
         reasoning: staticDef.reasoning,
         toolCall: staticDef.toolCall,
+        outputLimit: staticDef.outputLimit ?? null,
       };
     } else {
       const existing = await db
@@ -252,6 +256,7 @@ export async function resolveProbeTarget(args: {
           modalities: models.modalities,
           reasoning: models.reasoning,
           toolCall: models.toolCall,
+          outputLimit: models.outputLimit,
         })
         .from(models)
         .where(
@@ -277,6 +282,7 @@ export async function resolveProbeTarget(args: {
           modalities: existing[0].modalities,
           reasoning: existing[0].reasoning,
           toolCall: existing[0].toolCall,
+          outputLimit: existing[0].outputLimit ?? null,
         };
       } else {
         if (requestedServiceKind !== "llm") {
@@ -334,7 +340,7 @@ export async function resolveProbeTarget(args: {
     toolCall: capabilitySource.toolCall,
     providerId,
   });
-  return { wireFamily, serviceKind, endpointPath, sourceSurface, capabilityProfile };
+  return { wireFamily, serviceKind, endpointPath, sourceSurface, capabilityProfile, outputLimit: capabilitySource.outputLimit };
 }
 
 /** The account a probe selected, or the operator-facing reason it could not. */
@@ -752,12 +758,19 @@ export function computeProbeVerdict(args: {
           : status !== undefined
             ? `upstream ${status}`
             : undefined;
+    // A 429 that names a free-tier usage limit is upstream quota state, not a
+    // payload or egress defect — label it as the throttle it is instead of a
+    // generic probe failure.
+    const throttled =
+      status === 429 ||
+      providerStatus === 429 ||
+      /free usage limit|rate limit|throttl/i.test(base);
     // The toast title already names the model. Repeating `provider/model via
     // wire path` in the body made the operator read the same identity twice
     // and buried the upstream sentence. The wire family stays, because that is
     // the one fact the title does not carry; the path is noise next to it.
     const tagged = statusTag !== undefined ? `${pretty} (${statusTag})` : pretty;
-    errorMessage = `${wireFamily} — ${tagged}${upstreamReq ? ` [req ${upstreamReq}]` : ""}`;
+    errorMessage = `${wireFamily} — ${throttled ? "Upstream rate limit (HTTP 429): " : ""}${tagged}${upstreamReq ? ` [req ${upstreamReq}]` : ""}`;
 
   } else if (terminal?.type === "terminal" && terminal.state !== "complete") {
     // Read the terminal's own detail before falling back to the stop reason.

package/src/providers/discovery/probing-service.ts

@@ -192,7 +192,7 @@ export class ProviderProbingService {
     const providerWireRow = await this.loadProviderWireRow(providerId);
     const requiresAccount = providerWireRow?.requiresAccount ?? true;
 
-    const { wireFamily, serviceKind, endpointPath, sourceSurface, capabilityProfile } = await resolveProbeTarget({
+    const { wireFamily, serviceKind, endpointPath, sourceSurface, capabilityProfile, outputLimit } = await resolveProbeTarget({
       db: this.db,
       bundledModelCatalog: this.bundledModelCatalog,
       defaultEndpoints: this.defaultEndpoints,
@@ -253,6 +253,9 @@ export class ProviderProbingService {
       // over capabilities the route actually has (`prompt_caching`, `tools`,
       // `reasoning`), reporting a healthy provider as broken.
       capabilities: capabilityProfile,
+      // The model row's own output ceiling, so a probe with a max-output
+      // ceiling (OpenCode free) shapes with the model's limit, not a guess.
+      ...(outputLimit == null ? {} : { output_limit: outputLimit }),
     };
 
     const probeSignal = AbortSignal.timeout(30_000);

package/src/providers/integrations/anthropic.ts

@@ -17,7 +17,7 @@ import type { CanonicalEvent, CanonicalRequest } from "../../protocol/canonical-
 import { GatewayError } from "../../protocol/gateway-error";
 import { buildClaudeMessagesRequest, filterClaudeCustomHeaders } from "./shared/claude-messages";
 import { sendClaudeMessagesRequest } from "../../protocol/upstream/send-claude-messages";
-import { applyParamQuirks } from "../../transport/translation/quirks";
+import { applyParamQuirks } from "../../protocol/translation/quirks";
 import type { ProviderDispatchTarget, ProviderAdapter, ProviderDispatchContext, ProviderId } from "../provider-contracts";
 import { providerBaseUrl } from "../provider-metadata";
 

package/src/providers/integrations/buddy/buddy-catalog-shared.ts

@@ -42,7 +42,6 @@ export const BUDDY_INTL_EFFORTS: Readonly<Record<string, readonly string[]>> = {
   "glm-5.2": ["high", "xhigh"],
   "glm-5.3": ["low", "high", "max"],
   hy3: ["low", "high"],
-  "hy3-preview": ["low", "high"],
   "hy4-preview-f": ["high"],
 };
 export const BUDDY_CN_EFFORTS: Readonly<Record<string, readonly string[]>> = {
@@ -54,7 +53,6 @@ export const BUDDY_CN_EFFORTS: Readonly<Record<string, readonly string[]>> = {
   "glm-5.3": ["low", "high", "max"],
   "glm-5.3-flash": ["low", "high", "max"],
   hy3: ["low", "high"],
-  "hy3-preview": ["low", "high"],
   "hy4-preview": ["high"],
 };
 
@@ -336,7 +334,7 @@ export const BUDDY_SHARED_RAW: readonly BuddyRawEntry[] = [
   ["glm-5.1", "GLM-5.1", true, false, 200_000, 131_072],
   ["glm-5.2", "GLM-5.2", true, true, 1_000_000, 48_000],
   ["glm-5.3", "GLM-5.3", true, true, 1_000_000, 48_000],
-  ["glm-5.3-flash", "GLM-5.3 Flash", true, true, 1_000_000, 32_000],
+  ["glm-5.3-flash", "GLM-5.3 Flash", true, false, 1_000_000, 32_000],
   ["glm-5v-turbo", "GLM-5V Turbo", true, true, 200_000, 131_072],
   ["gpt-5.3-codex", "GPT-5.3 Codex", true, true, 400_000, 128_000],
   ["gpt-5.4", "GPT-5.4", true, true, 272_000, 72_000],
@@ -351,7 +349,6 @@ export const BUDDY_SHARED_RAW: readonly BuddyRawEntry[] = [
   ["grok-4.6", "Grok 4.6", true, true, 500_000, 500_000],
   ["grok-4.7", "Grok 4.7", true, true, 500_000, 128_000],
   ["hy3", "Hy3", true, true, 192_000, 64_000, true],
-  ["hy3-preview", "Hy3 Preview", true, false, 262_144, 64_000],
   ["hy4-preview", "Hy4 Preview", true, true, 1_000_000, 64_000, true],
   ["hy4-preview-f", "Hy4 Preview F", true, true, 1_000_000, 64_000, true],
   ["kimi-k2.5", "Kimi K2.5", true, false, 164_000, 262_144],

package/src/providers/integrations/buddy/buddy-chat-shared.ts

@@ -21,14 +21,14 @@ import { createHash } from "node:crypto";
 import { completeRequiredSchema } from "../../../protocol/codecs";
 import type { CanonicalRequest } from "../../../protocol/canonical-model";
 import { isRecord } from "../../../protocol/codecs";
-import { applyDeepSeekReasoning, applyOpenAIReasoning, backfillDeepSeekReasoningContent, clampedEffortOutputFloor } from "../../provider-reasoning";
+import { applyDeepSeekReasoning, applyOpenAIReasoning, backfillDeepSeekReasoningContent, clampedEffortOutputFloor } from "../../../protocol/reasoning";
 import { BUDDY_CN_EFFORTS, BUDDY_INTL_EFFORTS, BUDDY_SHARED_RAW } from "./buddy-catalog-shared";
 // Imported for the CN roster only: a CN-only id has no row in the shared
 // table, and without one `raiseOutputForRaisedEffort` silently no-ops, so a
 // raised effort still answers inside a budget sized for the lower one. It is
 // read inside the function below — never at module init — so the cycle with
 // cn-provider (which imports this module) resolves before any call.
-import { CODEBUDDY_CN_RAW } from "./codebuddy/cn-provider";
+import { CODEBUDDY_CN_RAW } from "./codebuddy/cn-catalog";
 import { buddyAccountUid } from "./buddy-oauth-shared";
 import type { ProviderDispatchContext } from "../../provider-contracts";
 
@@ -987,13 +987,146 @@ export function ensureBuddyLeadingSystem(
  * (`11151`), then guarantee a leading system turn (`11128`). The system text
  * is the variant's own prompt, so each pre-payload hook passes its prompt in.
  */
-function finalizeBuddyMessages(
+/**
+ * Longest message text that gets an automatic ephemeral prompt-cache marker,
+ * mirroring the reference gateway (`MIN_AUTO_CACHE_TEXT_LENGTH`).
+ */
+const MIN_AUTO_CACHE_TEXT_LENGTH = 1024;
+
+/**
+ * Marks one message's text content cacheable in place: the system turn and the
+ * last user turn are the long, stable ones a prefix cache serves best. A
+ * string message becomes a typed text block; a text part inside an array gets
+ * `cache_control: {type: "ephemeral"}`. Only the first qualifying text part of
+ * a message is marked, like the reference.
+ */
+function markCacheableTextContent(message: Record<string, unknown>): void {
+  const content = message["content"];
+  if (typeof content === "string") {
+    if (content.trim().length >= MIN_AUTO_CACHE_TEXT_LENGTH) {
+      message["content"] = [
+        { type: "text", text: content, cache_control: { type: "ephemeral" } },
+      ];
+    }
+    return;
+  }
+  if (!Array.isArray(content)) return;
+  for (let index = 0; index < content.length; index += 1) {
+    const part = content[index];
+    if (!isRecord(part) || part["type"] !== "text") continue;
+    const text = typeof part["text"] === "string" ? part["text"] : "";
+    if (text.trim().length >= MIN_AUTO_CACHE_TEXT_LENGTH && part["cache_control"] === undefined) {
+      content[index] = { ...part, cache_control: { type: "ephemeral" } };
+      return;
+    }
+  }
+}
+
+/**
+ * Auto-injects ephemeral prompt-cache markers on the system turn and the last
+ * user turn when the caller declared none. Mirrors `applyPromptCacheControl` in
+ * the reference gateway: an explicit `cache_control` anywhere is respected and
+ * disables the auto-pass so the caller's own caching strategy wins.
+ */
+export function applyBuddyAutoPromptCache(messages: Array<Record<string, unknown>>): void {
+  const hasExplicit = messages.some((message) =>
+    Array.isArray(message["content"]) &&
+    (message["content"] as Array<Record<string, unknown>>).some(
+      (part) => isRecord(part) && part["cache_control"] !== undefined,
+    ),
+  );
+  if (hasExplicit) return;
+  if (messages.length === 0) return;
+  const first = messages[0];
+  if (isRecord(first) && first["role"] === "system") markCacheableTextContent(first);
+  let lastUser = -1;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (isRecord(messages[index]) && messages[index]!["role"] === "user") {
+      lastUser = index;
+      break;
+    }
+  }
+  if (lastUser >= 0) markCacheableTextContent(messages[lastUser]!);
+}
+
+/**
+ * Strips the `content` key from assistant tool_calls-only turns.
+ *
+ * Mirrors the reference gateway's OpenAI transcript: an assistant turn that
+ * only asks for tools carries `tool_calls` and no content at all (Go's
+ * `omitzero`-style SDKs omit the key rather than send `null`/`""`). Keeping
+ * an empty string content invites the upstream to fall back to its prose/DSML
+ * channel; omitting the key keeps it on the structured `tool_calls` channel.
+ */
+export function omitBuddyAssistantToolCallContent(messages: Array<Record<string, unknown>>): void {
+  for (const message of messages) {
+    if (!isRecord(message) || message["role"] !== "assistant") continue;
+    const calls = message["tool_calls"];
+    if (!Array.isArray(calls) || calls.length === 0) continue;
+    const content = message["content"];
+    if (typeof content === "string" && content.trim().length === 0) {
+      delete message["content"];
+    } else if (Array.isArray(content) && content.length === 0) {
+      delete message["content"];
+    }
+  }
+}
+
+/**
+ * Forwards the caller's parallel tool-call intent onto the buddy wire.
+ *
+ * The canonical control is `generation_controls.parallel_tool_calls`; the
+ * reference gateway always passes it through so upstream keeps the structured
+ * tool channel, and the same is applied here.
+ */
+export function injectBuddyParallelToolCalls(
+  payload: Record<string, unknown>,
+  request: CanonicalRequest,
+): void {
+  const parallel = request.generation_controls?.parallel_tool_calls;
+  if (parallel !== undefined) payload["parallel_tool_calls"] = parallel;
+}
+
+export interface BuddyMessageFinalizeOptions {
+  /** The fixed leading system prompt installed on the wire. */
+  readonly leadPrompt: string;
+  /** Coalesce consecutive user turns (default true). */
+  readonly coalesceConsecutiveUser?: boolean;
+  /** Drop empty-content turns the upstream rejects (default true). */
+  readonly dropEmpty?: boolean;
+  /** Guarantee the wire opens with a system turn (default true). */
+  readonly ensureLeadingSystem?: boolean;
+  /** Omit content on assistant tool_calls-only turns (default true). */
+  readonly omitToolCallContent?: boolean;
+  /** Auto-inject ephemeral prompt-cache markers (default true). */
+  readonly autoPromptCache?: boolean;
+}
+
+/**
+ * The single authoritative buddy message-shape pipeline. Every variant runs
+ * the same sequence — coalesce, drop empty turns, guarantee the leading system
+ * turn, omit content on tool_calls-only assistant turns, then auto-cache — so
+ * the wire shape cannot drift between CodeBuddy intl, CN, and WorkBuddy.
+ */
+export function finalizeBuddyMessages(
   messages: Array<Record<string, unknown>>,
-  systemPrompt: string,
+  options: BuddyMessageFinalizeOptions,
 ): void {
-  coalesceConsecutiveUserMessages(messages);
-  dropEmptyBuddyMessages(messages);
-  ensureBuddyLeadingSystem(messages, systemPrompt);
+  if (options.coalesceConsecutiveUser !== false) {
+    coalesceConsecutiveUserMessages(messages);
+  }
+  if (options.dropEmpty !== false) {
+    dropEmptyBuddyMessages(messages);
+  }
+  if (options.ensureLeadingSystem !== false) {
+    ensureBuddyLeadingSystem(messages, options.leadPrompt);
+  }
+  if (options.omitToolCallContent !== false) {
+    omitBuddyAssistantToolCallContent(messages);
+  }
+  if (options.autoPromptCache !== false) {
+    applyBuddyAutoPromptCache(messages);
+  }
 }
 
 /**
@@ -1035,5 +1168,5 @@ export function applyBuddySystemPrompt(
       messages.push({ ...message });
     }
   }
-  finalizeBuddyMessages(messages, systemPrompt);
+  finalizeBuddyMessages(messages, { leadPrompt: systemPrompt });
 }

package/src/providers/integrations/buddy/buddy-checkin.ts

@@ -24,6 +24,7 @@ import { providerBaseUrl } from "../../provider-metadata";
 import { sleep } from "../../../shared/sleep";
 import { WORKBUDDY_DOMAIN } from "./workbuddy/shared";
 import { BUDDY_PROVIDER_IDS } from "../../provider-metadata";
+import { QODER_CHECKIN_PROVIDER_IDS } from "../qoder/qoder-checkin";
 import {
   buildWorkBuddyUserAgent,
   getWorkBuddyClientVersion,
@@ -38,7 +39,10 @@ import { codebuddyDomain, type CodeBuddyVariant } from "./codebuddy/shared";
  * shared family set so this list cannot drift from the health recorder's or the
  * request preparer's.
  */
-export const DAILY_CHECKIN_PROVIDER_IDS: readonly string[] = [...BUDDY_PROVIDER_IDS];
+export const DAILY_CHECKIN_PROVIDER_IDS: readonly string[] = [
+  ...BUDDY_PROVIDER_IDS,
+  ...QODER_CHECKIN_PROVIDER_IDS,
+];
 
 /** Abort budget for one upstream check-in request. */
 const TIMEOUT_MS = 15_000;

package/src/providers/integrations/buddy/buddy-growth-shared.ts

@@ -337,35 +337,6 @@ export async function redeemBuddyStreakTier(
 // 3. Streak lottery
 // ---------------------------------------------------------------------------
 
-const LOTTERY_CHANCES_PATH = "/activity/growth/lottery/chances";
-const LOTTERY_DRAW_PATH = "/activity/growth/lottery/draw";
-
-/** Remaining draw chances granted by a redeemed tier. */
-export async function readBuddyLotteryChances(
-  options: BuddyGrowthCall,
-): Promise<number | null> {
-  const reply = await call(options, "GET", LOTTERY_CHANCES_PATH);
-  if (!reply.ok || reply.data === null) return null;
-  const value = Number(reply.data["balance"]);
-  return Number.isFinite(value) ? value : null;
-}
-
-/**
- * Draws once. A fresh `client_token` per draw: reusing one lets the upstream
- * treat the draw as a duplicate and swallow it.
- */
-export async function drawBuddyLottery(
-  options: BuddyGrowthCall,
-): Promise<BuddyGrowthResult> {
-  const reply = await call(options, "POST", LOTTERY_DRAW_PATH, {
-    client_token: clientToken(options, "draw"),
-  });
-  if (refused(reply, 400, ["insufficient", "disabled", "no chance", "未开启"])) {
-    return { state: "not_eligible", error: null, credit: null };
-  }
-  return done(reply);
-}
-
 // ---------------------------------------------------------------------------
 // 4. Cat travel
 // ---------------------------------------------------------------------------
@@ -523,56 +494,3 @@ export async function adoptFirstBuddy(
   return done(reply);
 }
 
-// ---------------------------------------------------------------------------
-// 6. Trial gift pack + gift/compensation claims
-// ---------------------------------------------------------------------------
-
-const TRIAL_PATH = "/billing/ide/trial";
-const GIFT_PATH = "/billing/meter/claim-gift";
-const COMPENSATION_PATH = "/billing/meter/claim-compensation";
-/** "Already claimed" on the trial pack. */
-const TRIAL_ALREADY_CODE = 14051;
-
-/**
- * Claims the one-off trial credit pack.
- *
- * International only: the reference reports the CN hosts do not serve this
- * endpoint at all, and a 404 there is a `skip`, not a failure.
- */
-export async function claimBuddyTrial(
-  options: BuddyGrowthCall,
-): Promise<BuddyGrowthResult> {
-  const reply = await call(options, "POST", TRIAL_PATH, {});
-  if (coded(reply, TRIAL_ALREADY_CODE) || refused(reply, 400, ["14051"])) {
-    return { state: "already", error: null, credit: null };
-  }
-  // Not served on this host at all — a 404/405 here is a routing fact, not an
-  // account problem.
-  if (reply.status === 404 || reply.status === 405) {
-    return { state: "skipped", error: null, credit: null };
-  }
-  return done(reply);
-}
-
-/**
- * Claims the newcomer gift, if one is present.
- *
- * Once per account; a business error afterwards is the normal "already claimed"
- * answer and is never a failure.
- */
-export async function claimBuddyGift(
-  options: BuddyGrowthCall,
-): Promise<BuddyGrowthResult> {
-  const reply = await call(options, "POST", GIFT_PATH, {});
-  if (!reply.ok) return { state: "already", error: null, credit: null };
-  return done(reply);
-}
-
-/** Claims an activity compensation, if one is present. Same once-only semantics. */
-export async function claimBuddyCompensation(
-  options: BuddyGrowthCall,
-): Promise<BuddyGrowthResult> {
-  const reply = await call(options, "POST", COMPENSATION_PATH, {});
-  if (!reply.ok) return { state: "already", error: null, credit: null };
-  return done(reply);
-}

package/src/providers/integrations/buddy/buddy-identity.ts

@@ -1,4 +1,5 @@
 import type { ProviderDispatchContext } from "../../provider-contracts";
+import { createHash } from "node:crypto";
 import { decodeJwtPayload } from "../../authentication/oauth-flow-store";
 
 /**
@@ -96,3 +97,27 @@ export function buddyEnterprise(context?: ProviderDispatchContext): string | und
   }
   return undefined;
 }
+
+/**
+ * Per-account device binding (`qimei36`) for the buddy providers.
+ *
+ * The desktop auth state sends `X-Device-Id-List: {"qimei36":"…"}` alongside
+ * the Turing token — a second, independent device identity. Pinning it per
+ * account makes every account in a pool present a distinct device to the
+ * upstream risk control instead of sharing the machine's single fingerprint.
+ *
+ * Resolution order:
+ * 1. `auth_state.qimei36` — explicit operator-set binding (imported or edited).
+ * 2. Determinstic derivation from the internal account id (sha256 → 32 hex).
+ *    This keeps the binding stable across restarts without a database write,
+ *    and gives each freshly-added account its own id automatically.
+ *
+ * Returns `undefined` only when no account id is available (unauthenticated).
+ */
+export function resolveBuddyDeviceBinding(context?: ProviderDispatchContext): string | undefined {
+  const explicit = context?.credential.auth_state?.["qimei36"];
+  if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
+  const accountId = context?.credential.account_id;
+  if (accountId === undefined || accountId.length === 0) return undefined;
+  return createHash("sha256").update(`wb2a:qimei36:${accountId}`).digest("hex").slice(0, 32);
+}