cartethyia 2.7.3 → 2.7.5

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

@@ -50,6 +50,7 @@ import {
   resolveProbeAdapter,
   resolveProbeTarget,
   selectProbeAccount,
+  selectUsableAccount,
   wireContextFrom,
   type ProbeProviderRow,
 } from "./probe-phases";
@@ -304,7 +305,7 @@ export class ProviderProbingService {
             throw new GatewayError(
               "capability_unsupported",
               400,
-              `Provider ${providerId} has no web search transport`,
+              `Provider ${providerId} has no web search transport (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
             );
           }
           const searchProbeQuery = request.prompt?.trim() || "Cartethyia gateway probe";
@@ -325,14 +326,14 @@ export class ProviderProbingService {
             snippet: hit.snippet,
           }));
           if (!response.results || response.results.length === 0) {
-            dispatchError = new GatewayError("platform_unavailable", 502, "web search returned no results");
+            dispatchError = new GatewayError("platform_unavailable", 502, "web search returned no results (request {requestId}). The upstream came back empty-handed — retry 🌙");
           }
         } else if (serviceKind === "systemone") {
           if (typeof adapter.systemone !== "function") {
             throw new GatewayError(
               "capability_unsupported",
               400,
-              `Provider ${providerId} has no System One transport`,
+              `Provider ${providerId} has no System One transport (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
             );
           }
           const response = await adapter.systemone(
@@ -360,14 +361,14 @@ export class ProviderProbingService {
             dispatchError = new GatewayError(
               response.status >= 500 ? "platform_unavailable" : "invalid_request",
               response.status,
-              `System One upstream error: ${raw.slice(0, 240)}`,
+              `System One upstream error (request {requestId}): ${raw.slice(0, 240)}`,
             );
           } else {
             let parsed: unknown;
             try {
               parsed = raw ? JSON.parse(raw) : null;
             } catch {
-              dispatchError = new GatewayError("platform_unavailable", 502, "System One returned invalid JSON");
+              dispatchError = new GatewayError("platform_unavailable", 502, "System One returned invalid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙");
             }
             if (parsed !== null && parsed !== undefined) {
               const answers =
@@ -381,7 +382,7 @@ export class ProviderProbingService {
                 dispatchError = new GatewayError(
                   "platform_unavailable",
                   502,
-                  "System One returned no answers",
+                  "System One returned no answers (request {requestId}). The upstream came back empty-handed — retry 🌙",
                 );
               }
             }
@@ -709,7 +710,7 @@ export class ProviderProbingService {
           throw new GatewayError(
             "transport_unavailable",
             502,
-            `Model discovery failed for ${providerId}: ${error instanceof Error ? error.message : "unknown error"}`,
+            `Model discovery failed for ${providerId}: ${error instanceof Error ? error.message : "unknown error"} (request {requestId}). The connection ghosted us — come back in a moment 👻`,
             {},
             "upstream",
           );
@@ -718,7 +719,7 @@ export class ProviderProbingService {
           throw new GatewayError(
             "transport_unavailable",
             502,
-            `Model discovery failed for ${providerId}: endpoint returned no usable models`,
+            `Model discovery failed for ${providerId}: endpoint returned no usable models (request {requestId}). The upstream came back empty-handed — retry 🌙`,
             {},
             "upstream",
           );
@@ -764,7 +765,7 @@ export class ProviderProbingService {
             throw new GatewayError(
               "transport_unavailable",
               502,
-              `Model discovery failed for ${providerId}: ${error instanceof Error ? error.message : "unknown error"}`,
+              `Model discovery failed for ${providerId}: ${error instanceof Error ? error.message : "unknown error"} (request {requestId}). The connection ghosted us — come back in a moment 👻`,
               {},
               "upstream",
             );
@@ -799,7 +800,7 @@ export class ProviderProbingService {
         throw new GatewayError(
           "invalid_request",
           400,
-          `Add an account for ${providerId} first — model listing needs a credential.`,
+          `Add an account for ${providerId} first — model listing needs a credential (request {requestId}). Wrong key, right door — check the credential 🔑`,
           {},
           "cartethyia",
         );
@@ -811,7 +812,7 @@ export class ProviderProbingService {
         throw new GatewayError(
           "invalid_request",
           400,
-          `Add an account for ${providerId} before fetching its models.`,
+          `Add an account for ${providerId} before fetching its models (request {requestId}). Wrong key, right door — check the credential 🔑`,
           {},
           "cartethyia",
         );
@@ -821,7 +822,7 @@ export class ProviderProbingService {
       throw new GatewayError(
         "capability_unsupported",
         400,
-        `${providerId} publishes no model-listing endpoint. Its catalog ships with Cartethyia; new models appear with an update.`,
+        `${providerId} publishes no model-listing endpoint (request {requestId}). Its catalog ships with Cartethyia; new models appear with an update. Know your tools — this one just isn't in the box 🧰`,
         {},
         "cartethyia",
       );
@@ -915,6 +916,9 @@ export class ProviderProbingService {
         source: discDef?.freeTier === true ? "auto_free" : "discovered",
         sourceUpdatedAt,
         enabled: true,
+        ...(discDef?.dialect === undefined && knownDefinition?.dialect === undefined
+          ? {}
+          : { dialect: discDef?.dialect ?? knownDefinition?.dialect }),
       });
     }
     // One statement per chunk (500, the account-health batch step) instead of
@@ -936,6 +940,7 @@ export class ProviderProbingService {
             cost: sql`excluded.cost`,
             proOnly: sql`excluded.pro_only`,
             freeTier: sql`excluded.free_tier`,
+            dialect: sql`excluded.dialect`,
             // The proposed row's own source, not a constant: a free-tier
             // discovery and an ordinary one write the same upsert, and pinning
             // this to `discovered` would relabel every free-tier row on the
@@ -1000,14 +1005,7 @@ export class ProviderProbingService {
           globalOrOwnedBy(providerAccounts.tenantId, tenantId),
         ),
       );
-    const now = Date.now();
-    const usable = rows
-      .filter(
-        (row) =>
-          row.status !== "disabled" &&
-          (row.cooldownUntil === null || row.cooldownUntil.getTime() <= now),
-      )
-      .sort((left, right) => Number(right.tenantId !== null) - Number(left.tenantId !== null))[0];
+    const usable = selectUsableAccount(rows);
     if (!usable?.credentialCiphertext) return undefined;
     const authState = isRecord(usable.authState) ? usable.authState as Readonly<Record<string, unknown>> : undefined;
     return {

package/src/providers/integrations/agentrouter/agentrouter.ts

@@ -11,15 +11,24 @@
 // `x-stainless-*` family, `x-claude-code-session-id`, and `anthropic-version`
 // for operator-supplied headers, so they are layered onto the built headers
 // at this call site instead.
-import { GatewayError } from "../../../protocol/gateway-error";
 import type { CanonicalEvent, CanonicalRequest } from "../../../protocol/canonical-model";
-import { readCredentialSecret, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext } from "../../provider-contracts";
+import { readCredentialSecret, assertWireFamily, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext } from "../../provider-contracts";
 import { providerBaseUrl } from "../../provider-metadata";
 import { buildClaudeMessagesRequest } from "../shared/claude-messages";
 import { sendClaudeMessagesRequest } from "../../../protocol/upstream/send-claude-messages";
+import { ANTHROPIC_BETA_CAPABILITIES } from "../claude/claude-betas";
 
 export const AGENTROUTER_PROVIDER_ID = "agentrouter" as const;
-export const AGENTROUTER_BASE_URL = `${providerBaseUrl("agentrouter")}/v1/messages?beta=true`;
+const AGENTROUTER_BASE_URL = `${providerBaseUrl("agentrouter")}/v1/messages?beta=true`;
+
+/** The CLI beta set, typed against the canonical Anthropic beta vocabulary. */
+const AGENTROUTER_ANTHROPIC_BETAS: ReadonlyArray<
+  keyof typeof ANTHROPIC_BETA_CAPABILITIES
+> = [
+  "claude-code-20250219",
+  "interleaved-thinking-2025-05-14",
+  "effort-2025-11-24",
+];
 
 /**
  * The AgentRouter CLI fingerprint headers. Every value is part of the
@@ -30,7 +39,7 @@ export const AGENTROUTER_BASE_URL = `${providerBaseUrl("agentrouter")}/v1/messag
  */
 function agentRouterFingerprintHeaders(stream: boolean): Record<string, string> {
   return {
-    "anthropic-beta": "claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24",
+    "anthropic-beta": AGENTROUTER_ANTHROPIC_BETAS.join(","),
     "anthropic-dangerous-direct-browser-access": "true",
     "x-app": "cli",
     "user-agent": "claude-cli/2.1.195 (external, sdk-cli)",
@@ -87,7 +96,7 @@ class AgentRouterAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "messages") {
-      throw new GatewayError("capability_unsupported", 400, `agentrouter supports messages only, got ${candidate.wire_family}`);
+      assertWireFamily(candidate, "messages", "agentrouter");
     }
     const apiKey = readCredentialSecret(context.credential, "AgentRouter API key is required");
 

package/src/providers/integrations/alibabacp/alibabacp.ts

@@ -61,7 +61,7 @@ function alibabaSpec(envelope: AlibabaCodingPlanEnvelope): ApiKeyProviderSpec {
 function alibabaEnvelope(context: ProviderDispatchContext): AlibabaCodingPlanEnvelope {
   const secret = context.credential.secret;
   if (secret === undefined || secret.length === 0) {
-    throw new GatewayError("invalid_request", 400, "alibabacp: credential is missing a secret value");
+    throw new GatewayError("invalid_request", 400, "alibabacp: credential is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑");
   }
   let envelope: AlibabaCodingPlanEnvelope;
   try {
@@ -70,7 +70,7 @@ function alibabaEnvelope(context: ProviderDispatchContext): AlibabaCodingPlanEnv
     throw new GatewayError(
       "invalid_request",
       400,
-      `alibabacp: ${error instanceof Error ? error.message : "stored credential is not an Alibaba envelope"}`,
+      `alibabacp: ${error instanceof Error ? error.message : "stored credential is not an Alibaba envelope"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
   return envelope;

package/src/providers/integrations/anthropic.ts

@@ -18,6 +18,7 @@ import { GatewayError } from "../../protocol/gateway-error";
 import { buildClaudeMessagesRequest, filterClaudeCustomHeaders } from "./shared/claude-messages";
 import { sendClaudeMessagesRequest } from "../../protocol/upstream/send-claude-messages";
 import { applyParamQuirks } from "../../protocol/translation/quirks";
+import { assertCredentialKind, assertWireFamily } from "../provider-contracts";
 import type { ProviderDispatchTarget, ProviderAdapter, ProviderDispatchContext, ProviderId } from "../provider-contracts";
 import { providerBaseUrl } from "../provider-metadata";
 
@@ -58,18 +59,10 @@ export class AnthropicApiKeyAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "messages") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `${this.provider_id} supports messages only`,
-      );
+      assertWireFamily(candidate, "messages", this.provider_id);
     }
     if (context.credential.credential_kind !== "api_key") {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `${this.provider_id}: x-api-key credential required (got credential_kind=${context.credential.credential_kind})`,
-      );
+      assertCredentialKind(context.credential, "api_key", this.provider_id);
     }
     if (
       context.credential.secret === undefined ||
@@ -78,7 +71,7 @@ export class AnthropicApiKeyAdapter implements ProviderAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        `${this.provider_id}: API key is missing a secret value`,
+        `${this.provider_id}: API key is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑`,
       );
     }
     const apiKey = new TextDecoder().decode(context.credential.secret);

package/src/providers/integrations/antigravity/antigravity-oauth.ts

@@ -212,4 +212,3 @@ export class AntigravityOAuthClient extends OAuthClient {
 }
 
 export const antigravityOAuthClient = new AntigravityOAuthClient();
-export { exchangeCodeForToken };

package/src/providers/integrations/antigravity/antigravity-protocol.ts

@@ -257,8 +257,6 @@ export function normalizeAntigravityToolSchemas(request: CanonicalRequest): Cano
 const lastGoodEndpoints = new Map<string, string>();
 const LAST_GOOD_ENDPOINT_MAX = 256;
 
-const DEFAULT_ORDER_INDEX = Number.MAX_SAFE_INTEGER;
-
 /**
  * Records the endpoint that just served a successful turn. Call this with the
  * `endpoint` reported by empty-stream recovery (or the URL that produced a
@@ -301,18 +299,6 @@ export function orderAntigravityEndpoints(
   return [sticky, ...endpoints.slice(0, index), ...endpoints.slice(index + 1)];
 }
 
-/**
- * Position of `endpoint` in the caller's own endpoint order, used to log a
- * failover without the caller re-deriving the list.
- */
-export function antigravityEndpointOrderIndex(
-  endpoints: readonly string[],
-  endpoint: string,
-): number {
-  const index = endpoints.indexOf(endpoint);
-  return index < 0 ? DEFAULT_ORDER_INDEX : index;
-}
-
 // Model discovery (`v1internal:fetchAvailableModels`) — live catalog.
 
 const ANTIGRAVITY_DISCOVERY_PATH = "/v1internal:fetchAvailableModels";

package/src/providers/integrations/antigravity/antigravity.ts

@@ -46,6 +46,7 @@ import {
   loadAntigravityProject,
   normalizeAntigravityToolSchemas,
 } from "./antigravity-protocol";
+import { assertCredentialKind, assertWireFamily } from "../../provider-contracts";
 import type { ImageGenerationOutcome, ProviderDispatchTarget, ProviderAdapter, ProviderDispatchContext, WebSearchOutcome, WebSearchResult } from "../../provider-contracts";
 import { providerBaseUrl } from "../../provider-metadata";
 import { abortGatewayError, createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
@@ -188,18 +189,10 @@ class AntigravityAdapter implements ProviderAdapter {
       candidate.wire_family !== "responses" &&
       candidate.wire_family !== "messages"
     ) {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `antigravity supports chat/responses/messages, got ${candidate.wire_family}`,
-      );
+      assertWireFamily(candidate, ["chat", "responses", "messages"], "antigravity");
     }
     if (context.credential.credential_kind !== "oauth") {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `antigravity: Google OAuth credential required (got credential_kind=${context.credential.credential_kind})`,
-      );
+      assertCredentialKind(context.credential, "oauth", "antigravity");
     }
     const accessToken = context.credential.secret
       ? new TextDecoder().decode(context.credential.secret).trim()
@@ -208,7 +201,7 @@ class AntigravityAdapter implements ProviderAdapter {
       throw new GatewayError(
         "authentication_failed",
         401,
-        "antigravity: OAuth access token is required",
+        "antigravity: OAuth access token is required (request {requestId}). Wrong key, right door — check the credential 🔑",
       );
     }
 
@@ -360,7 +353,7 @@ class AntigravityAdapter implements ProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          "antigravity returned empty stream",
+          "antigravity returned empty stream (request {requestId}). The upstream came back empty-handed — retry 🌙",
           {},
           "upstream",
         );
@@ -508,7 +501,7 @@ class AntigravityAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): Promise<WebSearchOutcome> {
     const query = typeof body.query === "string" ? body.query.trim() : "";
-    if (!query) throw new GatewayError("invalid_request", 400, "search query is required");
+    if (!query) throw new GatewayError("invalid_request", 400, "search query is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
     const rawMax = body.max_results;
     const maxResults =
       typeof rawMax === "number" && Number.isFinite(rawMax)
@@ -531,7 +524,7 @@ class AntigravityAdapter implements ProviderAdapter {
     }
     const results = normalizeAntigravityGrounding(grounded, maxResults);
     if (results.length === 0)
-      throw new GatewayError("platform_unavailable", 502, "Antigravity search returned no grounded results");
+      throw new GatewayError("platform_unavailable", 502, "Antigravity search returned no grounded results (request {requestId}). The upstream came back empty-handed — retry 🌙");
     return { results, total_results: results.length };
   }
 
@@ -541,21 +534,17 @@ class AntigravityAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): Promise<ImageGenerationOutcome> {
     if (context.credential.credential_kind !== "oauth") {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `antigravity: Google OAuth credential required (got credential_kind=${context.credential.credential_kind})`,
-      );
+      assertCredentialKind(context.credential, "oauth", "antigravity");
     }
     const accessToken = context.credential.secret
       ? new TextDecoder().decode(context.credential.secret).trim()
       : "";
     if (!accessToken) {
-      throw new GatewayError("authentication_failed", 401, "antigravity: OAuth access token is required");
+      throw new GatewayError("authentication_failed", 401, "antigravity: OAuth access token is required (request {requestId}). Wrong key, right door — check the credential 🔑");
     }
     const prompt = imagePrompt(body);
     const model = candidate.model_id.length > 0 ? candidate.model_id : typeof body.model === "string" ? body.model : "";
-    if (model.length === 0) throw new GatewayError("invalid_request", 400, "model is required");
+    if (model.length === 0) throw new GatewayError("invalid_request", 400, "model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
     const outboundFetch: typeof fetch = (context.outbound_fetch as unknown as typeof fetch) ?? this.fetchFn;
     const projectId = await loadAntigravityProject(accessToken, {
       baseUrl: this.baseUrl,
@@ -624,7 +613,7 @@ class AntigravityAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        `Antigravity image generation unreachable: ${error instanceof Error ? error.message : String(error)}`,
+        `Antigravity image generation unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         {},
         "upstream",
       );
@@ -646,12 +635,12 @@ class AntigravityAdapter implements ProviderAdapter {
       try {
         parsed = JSON.parse(event.data);
       } catch {
-        throw new GatewayError("platform_unavailable", 502, "Antigravity image stream returned malformed JSON", {}, "upstream");
+        throw new GatewayError("platform_unavailable", 502, "Antigravity image stream returned malformed JSON (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       }
       images.push(...geminiInlineImages(parsed));
     }
     if (images.length === 0) {
-      throw new GatewayError("platform_unavailable", 502, "Antigravity image generation returned no image", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "Antigravity image generation returned no image (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     return { created: imageCreatedSeconds(), data: images };
   }
@@ -769,7 +758,7 @@ export class AntigravitySessionStore {
  * `"-" + (sha256(first-user-text)[0:8] & INT63 | random <9e18)`.
  * A positive or hyphenated-UUID value here is a one-glance synthetic signal.
  */
-export function signedAntigravitySessionId(seed?: string): string {
+function signedAntigravitySessionId(seed?: string): string {
   if (seed !== undefined && /^-?\d+$/.test(seed)) return seed;
   const text = seed !== undefined && seed.length > 0 ? seed : randomUUID();
   const head = BigInt(`0x${createHash("sha256").update(text).digest("hex").slice(0, 8)}`);
@@ -780,7 +769,7 @@ export function signedAntigravitySessionId(seed?: string): string {
 }
 
 /** Thinking budget per wire model, matching the client's effort tiers. */
-export function antigravityThinkingBudget(modelId: string): number | undefined {
+function antigravityThinkingBudget(modelId: string): number | undefined {
   if (!modelId.includes("claude") && !modelId.includes("gemini-3")) return undefined;
   if (modelId.endsWith("-low")) return 1_000;
   if (modelId.endsWith("-medium")) return 4_000;

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

@@ -160,7 +160,7 @@ export function makeBuddyCnImageModels(
  * plan rather than about the model. A pro account serves all six. The pill is
  * therefore a hint about a free account, and a dispatch is what settles it.
  *
- * @see `.skills/cartethyia-reverse-engineering/references/codebuddy-dispatch-headers.md`
+ * @see `documentation/research/codebuddy/2026-10-19-codebuddy-chat-dispatch-headers.md`
  */
 export const BUDDY_PRO_ONLY_MODEL_IDS: ReadonlySet<string> = new Set([
   "primary-model",
@@ -273,7 +273,7 @@ export function makeBuddyModel(
   endpoint?: string,
   realm: "intl" | "cn" = "intl",
 ): ModelDefinition {
-  if (!entry[0]) throw new GatewayError("invalid_request", 400, "invalid model");
+  if (!entry[0]) throw new GatewayError("invalid_request", 400, "invalid model (request {requestId}). Check the shape of what you sent — then resend 🪞");
   const image = BUDDY_IMAGE_MODEL_ID_SET.has(entry[0]);
   const efforts = (realm === "cn" ? BUDDY_CN_EFFORTS : BUDDY_INTL_EFFORTS)[entry[0].toLowerCase()];
   // Refused on free is only a question for the intl realm. cbcn serves every

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

@@ -168,10 +168,11 @@ export function normalizeBuddyToolNames(payload: Record<string, unknown>): void
  * Both realms have a "let the backend choose" id, and the reference rewrites
  * `auto` onto it before anything downstream keys on the name — so eligibility,
  * cooldowns and the catalog all see one id. CN's is `default`; intl's is
- * `default-model`.
+ * `default-model` (confirmed from live CLI session logs, which send
+ * `model=default-model` for the intl auto path).
  */
 const BUDDY_AUTO_TARGET: Readonly<Record<"intl" | "cn", string>> = {
-  intl: "auto",
+  intl: "default-model",
   cn: "default",
 };
 
@@ -348,8 +349,8 @@ const DSH_MINIMAL_PATTERN = buddyTemplatePattern("You are a helpful software eng
 const DSH_DIRECT_PATTERN = buddyTemplatePattern("You are DeepSeek Harness");
 const DSH_WEB_GUI_PATTERN = buddyTemplatePattern("DeepSeek Harness Web GUI");
 
-/** The identity DSH role prompts are rewritten to; matches the donor gateway. */
-const DSH_WORKBUDDY_IDENTITY = "You are WorkBuddy, a powerful AI assistant";
+/** The identity DSH role prompts are rewritten to; neutral and minimal. */
+const DSH_WORKBUDDY_IDENTITY = "You are a helpful assistant";
 
 /**
  * Rewrites DeepSeek Harness role identities in one message's text back to the
@@ -425,6 +426,20 @@ export const clineReasoningReplayPrepares: readonly ((
   },
 ];
 
+/**
+ * The reference injects `cache_retention` on every chat body: `long` by
+ * default, `short` when prompt caching for 1h is disabled
+ * (`CODEBUDDY_DISABLE_PROMPT_CACHING_1H`). Matching the client keeps the
+ * upstream's prompt-caching behavior and price on the same path the CLI uses.
+ */
+function injectBuddyCacheRetention(payload: Record<string, unknown>): void {
+  if (payload["cache_retention"] !== undefined) return;
+  const disabled =
+    process.env.CODEBUDDY_DISABLE_PROMPT_CACHING_1H?.trim() === "1" ||
+    process.env.CODEBUDDY_DISABLE_PROMPT_CACHING_1H?.trim().toLowerCase() === "true";
+  payload["cache_retention"] = disabled ? "short" : "long";
+}
+
 /**
  * Payload prefix shared by the buddy pre-payload hooks: force `stream=true`,
  * apply the provider's DeepSeek thinking contract, opt `reasoning_summary` in
@@ -437,6 +452,7 @@ export function buddyPrePayloadCommon(
   context?: ProviderDispatchContext,
 ): void {
   injectBuddyPromptCacheKey(payload, request, context);
+  injectBuddyCacheRetention(payload);
   // `auto` and `default-model` are the same upstream model under two names, and
   // the reference resolves one to the other everywhere — catalog, eligibility,
   // cooldown keys. Treating them as two independent rows meant a client that

package/src/providers/integrations/buddy/buddy-cli-headers.ts

@@ -3,51 +3,19 @@
  *
  * Everything here comes from the two reference gateways, which agree: the
  * desktop product sends conversation/tracing headers and a device token, while
- * the CLI sends the agent envelope plus the OpenAI Node SDK fingerprint. The
- * CLI still drops the browser *transport* headers (`origin`, `referer`,
- * `accept-language`) and the device token, but keeps the request-shape markers
- * (`x-requested-with`, `x-codebuddy-request`) the reference sends on every call
- * regardless of transport — see the CLI branches in each provider's
- * `*-shared.ts`.
+ * the CLI sends the agent envelope. The CLI still drops the browser *transport*
+ * headers (`origin`, `referer`, `accept-language`) and the device token, but
+ * keeps the request-shape markers (`x-requested-with`, `x-codebuddy-request`)
+ * the reference sends on every call regardless of transport — see the CLI
+ * branches in each provider's `*-shared.ts`.
  *
- * The SDK fingerprint is pinned, not host-derived. Both references pin a fixed
- * set (codebuddy2api pins Linux/x64/v24.21.0); this gateway pins the macOS set
- * instead, so every CLI dispatch presents one consistent client fingerprint no
- * matter which machine the gateway runs on. A host-derived fingerprint would
- * advertise whatever OS the process happens to run under — a value no upstream
- * risk model has seen for this client brand, and an easy outlier to key on.
+ * The CLI's cloud chat transport is axios (`RestOperations`), not the OpenAI
+ * Node SDK, so it sends **no** `x-stainless-*` fingerprint. The reference's
+ * chat request helper sets only `Content-Type`, `Accept`, and `Authorization`
+ * before the conversation/agent/identity headers are injected; the stainless
+ * set belongs to the SDK-backed secondary clients, not to CodeBuddy chat.
  */
 
-/** OpenAI Node SDK 6.25.0 `x-stainless-*` fingerprint; both references agree. */
-const STAINLESS_PACKAGE_VERSION = "6.25.0";
-
-/**
- * The pinned Node runtime the fingerprint claims. Held constant across
- * dispatches: a drifting `process.version` would advertise a different Node
- * build per deployment, which is not what one installed client looks like.
- */
-const STAINLESS_RUNTIME_VERSION = "v24.21.0";
-
-/**
- * The SDK fingerprint headers.
- *
- * `x-stainless-timeout` is in the hub only and `x-stainless-retry-count` is in
- * both; the SDK sends both, so both go out. The OS/arch pair is the pinned
- * macOS fingerprint rather than this process's host.
- */
-export function buddyStainlessHeaders(): Record<string, string> {
-  return {
-    "x-stainless-lang": "js",
-    "x-stainless-package-version": STAINLESS_PACKAGE_VERSION,
-    "x-stainless-os": "MacOS",
-    "x-stainless-arch": "x64",
-    "x-stainless-runtime": "node",
-    "x-stainless-runtime-version": STAINLESS_RUNTIME_VERSION,
-    "x-stainless-retry-count": "0",
-    "x-stainless-timeout": "1200",
-  };
-}
-
 /**
  * The trace family the CLI carries as a child span.
  *
@@ -69,13 +37,18 @@ export function buddyCliTraceHeaders(
 /**
  * The full CLI identity envelope, minus what each caller already supplies.
  *
- * The caller keeps ownership of `User-Agent`, `X-IDE-*`, `X-Domain`, and the
- * conversation family, because those vary by provider and realm: only the
- * headers that are the same for every CLI dispatch are built here.
+ * The caller keeps ownership of `User-Agent`, `X-IDE-*`, `X-Domain`, the
+ * conversation family, and the OAuth identity headers; only the headers that
+ * are the same for every CLI dispatch are built here.
+ *
+ * No `x-stainless-*` fingerprint: the CLI's chat transport is axios, not the
+ * OpenAI Node SDK. `X-Private-Data` is added by the caller only when the
+ * dispatch is actually private — the reference never sends it as `false`.
  */
 export function buddyCliHeaders(args: {
   readonly userId: string;
   readonly enterpriseId?: string | undefined;
+  readonly privateData?: boolean;
 }): Record<string, string> {
   const enterpriseId =
     args.enterpriseId !== undefined && args.enterpriseId.trim().length > 0
@@ -89,12 +62,7 @@ export function buddyCliHeaders(args: {
     // of the three, so "other" is the honest value rather than a guess.
     "X-Agent-Runtime": "other",
     "X-User-Id": args.userId,
-    // The reference sends the flag either way, `true` only for an enterprise
-    // id. A personal account stays `false`; an enterprise account flips to
-    // `true` and names the enterprise, because the two travel together — a
-    // `true` with no id, or an id under `false`, is a combination no real
-    // client produces.
-    "X-Private-Data": enterpriseId === undefined ? "false" : "true",
+    ...(args.privateData === true ? { "X-Private-Data": "true" } : {}),
     ...(enterpriseId === undefined
       ? {}
       : {
@@ -104,6 +72,5 @@ export function buddyCliHeaders(args: {
           // reads both.
           "X-Tenant-Id": enterpriseId,
         }),
-    ...buddyStainlessHeaders(),
   };
 }

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

@@ -100,12 +100,43 @@ export async function fetchBuddyDirectoryModels(args: {
   readonly fetcher?: typeof fetch | undefined;
 }): Promise<readonly ModelDefinition[] | null> {
   const fetcher = args.fetcher ?? globalThis.fetch;
-  const primary = await fetchBuddyDirectoryOnce(args, fetcher, BUDDY_CONFIG_PATH);
-  if (primary !== null) return primary;
-  // Both references rank `/v3/config` above the personal-models path, but this
-  // repo has only ever called the latter, so the fallback keeps today's
-  // behaviour intact for a host that answers one and not the other.
-  return await fetchBuddyDirectoryOnce(args, fetcher, args.modelsPath);
+  // Fetch both catalog scopes and merge them. `/v3/config` is ranked higher and
+  // is the primary source (matches the reference gateways), but the personal
+  // models path carries models the v3 response does not always publish — so a
+  // single-source read can silently miss models that are callable. Merging with
+  // dedupe by model id gives the union, mirroring the upstream codebuddy2api
+  // catalog aggregation. Each failure falls through to the other source, so a
+  // host that answers only one behaves exactly as it does today.
+  const v3 = await fetchBuddyDirectoryOnce(args, fetcher, BUDDY_CONFIG_PATH);
+  const personal = await fetchBuddyDirectoryOnce(args, fetcher, args.modelsPath);
+  if (v3 !== null && personal !== null) return mergeBuddyDirectories(v3, personal);
+  return v3 ?? personal;
+}
+
+/**
+ * Merges two buddy directory reads into one roster, preserving each source's
+ * declaration order and de-duplicating by model id. `primary` wins when both
+ * sources declare the same id; models present only in `supplemental` are
+ * appended. Both lists are already filtered (disabled/CLI-roster/not-chat),
+ * so the merge only has to combine them.
+ */
+function mergeBuddyDirectories(
+  primary: readonly ModelDefinition[],
+  supplemental: readonly ModelDefinition[],
+): readonly ModelDefinition[] {
+  const seen = new Set<string>();
+  const merged: ModelDefinition[] = [];
+  for (const model of primary) {
+    if (seen.has(model.modelId)) continue;
+    seen.add(model.modelId);
+    merged.push(model);
+  }
+  for (const model of supplemental) {
+    if (seen.has(model.modelId)) continue;
+    seen.add(model.modelId);
+    merged.push(model);
+  }
+  return merged;
 }
 
 /** Reads one directory path; `null` on any transport, status, or shape miss. */