cartethyia 2.7.3 → 2.7.5

package/src/providers/integrations/cursor/cursor.ts

@@ -27,6 +27,7 @@ import type {
 } from "../../../protocol/canonical-model";
 import { resolveImageSource, splitDataUrl } from "../../../protocol/codecs";
 import { IMAGE_CLAMP_MAX_BYTES } from "../../../protocol/image-clamp";
+import { applyCacheMode } from "../../provider-usage";
 import type { ProviderAdapter, ProviderDispatchContext, ProviderDispatchTarget } from "../../provider-contracts";
 import { readCredentialSecret } from "../../provider-contracts";
 import type { Http2BidiEndReason, ValidatedHttp2BidiStream } from "../../../network/http2-bidi";
@@ -62,6 +63,7 @@ import { defaultParameterValues, fetchCursorModels } from "./cursor-catalog";
 import type { CursorModelInfo } from "./cursor-catalog";
 import { decodeValueToJson, decodeStructEntriesToJson } from "./protocol/struct";
 import { cursorVariantForExecArgs } from "./protocol/tool-canonical";
+import { fnv1a32 } from "../shared/hash";
 
 /**
  * Client-heartbeat cadence for every Cursor Run.
@@ -81,8 +83,38 @@ const CURSOR_HEARTBEAT_INTERVAL_MS = 5_000;
  * every dispatch.
  */
 const CURSOR_ROSTER_TTL_MS = 300_000;
-/** credential → { roster, fetchedAt } for the parameter lookup. */
+/**
+ * credential → { roster, fetchedAt } for the parameter lookup.
+ *
+ * Keyed by an FNV-1a digest of the credential rather than the raw token so a
+ * long-lived map does not hold live credentials as keys. Bounded by
+ * `ROSTER_CACHE_MAX` with oldest-first eviction: the TTL is only checked on
+ * read, so without a cap rotated tokens would grow the map without bound.
+ */
+const ROSTER_CACHE_MAX = 1024;
 const rosterCache = new Map<string, { roster: readonly CursorModelInfo[]; fetchedAt: number }>();
+
+function rosterCacheSet(credential: string, roster: readonly CursorModelInfo[]): void {
+  const key = String(fnv1a32(credential));
+  rosterCache.delete(key); // re-set moves the entry to newest position
+  rosterCache.set(key, { roster, fetchedAt: Date.now() });
+  while (rosterCache.size > ROSTER_CACHE_MAX) {
+    const oldest = rosterCache.keys().next().value;
+    if (oldest === undefined) break;
+    rosterCache.delete(oldest);
+  }
+}
+
+/**
+ * Test-only access to the roster cache (cap/eviction/TTL behavior is covered
+ * by `test/providers/cursor-roster-cache.test.ts` without a full dispatch).
+ */
+export const rosterCacheForTests = {
+  size: (): number => rosterCache.size,
+  set: rosterCacheSet,
+  get: (credential: string): { roster: readonly CursorModelInfo[]; fetchedAt: number } | undefined =>
+    rosterCache.get(String(fnv1a32(credential))),
+};
 /** Client-heartbeat cadence the Cursor edge expects (donor `heartbeatMs`). */
 const CURSOR_HEARTBEAT_INTERVAL_OVERRIDE = (() => {
   const raw = process.env.CARTETHYIA_CURSOR_HEARTBEAT_MS?.trim();
@@ -152,14 +184,14 @@ function finishImage(bytes: Uint8Array): CursorImageInput {
     throw new GatewayError(
       "invalid_request",
       400,
-      "Cursor accepts PNG, JPEG, WebP and GIF image input only",
+      "Cursor accepts PNG, JPEG, WebP and GIF image input only (request {requestId}). Check the shape of what you sent — then resend 🪞",
     );
   }
   if (bytes.byteLength > MAX_IMAGE_BYTES) {
     throw new GatewayError(
       "invalid_request",
       400,
-      `Cursor image input exceeds the ${MAX_IMAGE_BYTES}-byte limit`,
+      `Cursor image input exceeds the ${MAX_IMAGE_BYTES}-byte limit (request {requestId}). We love long reads, but not that long 📚`,
     );
   }
   return { data: bytes, mimeType };
@@ -183,7 +215,7 @@ async function resolveImageInput(
   if (dataUrl !== undefined) {
     const bytes = base64ToBytes(dataUrl.data);
     if (bytes === undefined) {
-      throw new GatewayError("invalid_request", 400, "Cursor image attachment is not valid base64");
+      throw new GatewayError("invalid_request", 400, "Cursor image attachment is not valid base64 (request {requestId}). Check the shape of what you sent — then resend 🪞");
     }
     return finishImage(bytes);
   }
@@ -192,7 +224,7 @@ async function resolveImageInput(
     throw new GatewayError(
       "invalid_request",
       400,
-      "Cursor image URLs must be HTTPS; private and non-TLS sources are not fetched",
+      "Cursor image URLs must be HTTPS; private and non-TLS sources are not fetched (request {requestId}). Check the shape of what you sent — then resend 🪞",
     );
   }
   const fetcher = context.outbound_attachment_fetch;
@@ -200,7 +232,7 @@ async function resolveImageInput(
     throw new GatewayError(
       "invalid_request",
       400,
-      "Cursor has no validated egress to fetch this image URL",
+      "Cursor has no validated egress to fetch this image URL (request {requestId}). All roads blocked — time to find a new route 🗺️",
     );
   }
   // Redirects are not followed: reject the response rather than letting a
@@ -222,7 +254,7 @@ async function resolveImageInput(
     throw new GatewayError(
       "invalid_request",
       400,
-      `Cursor image input exceeds the ${MAX_IMAGE_BYTES}-byte limit`,
+      `Cursor image input exceeds the ${MAX_IMAGE_BYTES}-byte limit (request {requestId}). We love long reads, but not that long 📚`,
     );
   }
   return finishImage(body);
@@ -249,7 +281,7 @@ function usageFromTurnEnded(turnEnded: Record<string, unknown>): UsageRecord {
   const input = count(turnEnded["input_tokens"]);
   const output = count(turnEnded["output_tokens"]);
   const cacheRead = count(turnEnded["cache_read"]);
-  return {
+  return applyCacheMode({
     input_tokens: input,
     cached_input_tokens: cacheRead,
     cache_write_tokens: count(turnEnded["cache_write"]),
@@ -258,7 +290,7 @@ function usageFromTurnEnded(turnEnded: Record<string, unknown>): UsageRecord {
     reasoning_tokens: count(turnEnded["reasoning_tokens"]),
     estimated_cost: null,
     total_tokens: input + output,
-  };
+  });
 }
 
 function nonEmptyStringOf(value: unknown): string | undefined {
@@ -503,7 +535,7 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        "This tool result cannot be matched to a live Cursor Run; resend the complete conversation.",
+        "This tool result cannot be matched to a live Cursor Run (request {requestId}); resend the complete conversation. The session went cold — reconnect or resend 🔌",
       );
     }
     const resolvedAll = pending.map((item) => cursorRunSessions.resolveCall(item.callId, scope));
@@ -530,7 +562,7 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        "This tool result refers to a Cursor tool call that is no longer pending. Resend the complete conversation.",
+        "This tool result refers to a Cursor tool call that is no longer pending (request {requestId}). Resend the complete conversation. The session went cold — reconnect or resend 🔌",
         { callIds: pending.map((item) => item.callId) },
       );
     }
@@ -538,12 +570,12 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        "These tool results belong to different Cursor Runs; resend them one Run at a time.",
+        "These tool results belong to different Cursor Runs (request {requestId}); resend them one Run at a time. The session went cold — reconnect or resend 🔌",
       );
     }
     const session = cursorRunSessions.get(runId);
     if (session === undefined) {
-      throw new GatewayError("invalid_request", 400, "Cursor Run is no longer live");
+      throw new GatewayError("invalid_request", 400, "Cursor Run is no longer live (request {requestId}). The session went cold — reconnect or resend 🔌");
     }
     const handle = this.#handles.get(runId);
     if (handle === undefined) {
@@ -605,7 +637,7 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "admission_unavailable",
         503,
-        "Cursor requires validated HTTP/2 egress; none is configured for this route",
+        "Cursor requires validated HTTP/2 egress (request {requestId}); none is configured for this route. No bridge to cross — configure a pool first 🏗️",
         { providerId: CURSOR_PROVIDER_ID },
       );
     }
@@ -784,7 +816,7 @@ class CursorAdapter implements ProviderAdapter {
             : new GatewayError(
                 "platform_unavailable",
                 502,
-                `Cursor Run failed: ${error instanceof Error ? error.message : String(error)}`,
+                `Cursor Run failed (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The upstream came back empty-handed — retry 🌙`,
                 { providerId: CURSOR_PROVIDER_ID },
                 "upstream",
               );
@@ -828,7 +860,7 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        `Cursor Run origin could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+        `Cursor Run origin could not be resolved (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         { providerId: CURSOR_PROVIDER_ID },
         "upstream",
       );
@@ -846,7 +878,8 @@ class CursorAdapter implements ProviderAdapter {
     credential: string,
     context: ProviderDispatchContext,
   ): Promise<readonly CursorModelInfo[]> {
-    const cached = rosterCache.get(credential);
+    const key = String(fnv1a32(credential));
+    const cached = rosterCache.get(key);
     if (cached !== undefined && Date.now() - cached.fetchedAt < CURSOR_ROSTER_TTL_MS) {
       return cached.roster;
     }
@@ -858,7 +891,7 @@ class CursorAdapter implements ProviderAdapter {
           : { fetcher: context.outbound_fetch as unknown as typeof fetch }),
         signal: context.abort_signal,
       });
-      rosterCache.set(credential, { roster, fetchedAt: Date.now() });
+      rosterCacheSet(credential, roster);
       return roster;
     } catch {
       return cached?.roster ?? [];
@@ -890,7 +923,7 @@ class CursorAdapter implements ProviderAdapter {
         }
         const message = item;
         if (context.abort_signal.aborted) {
-          failure = new GatewayError("transport_closed", 499, "request was cancelled");
+          failure = new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
           break;
         }
         const execServer = recordOf(message["exec_server_message"]);
@@ -994,7 +1027,7 @@ class CursorAdapter implements ProviderAdapter {
           : new GatewayError(
               "platform_unavailable",
               502,
-              `Cursor Run failed: ${error instanceof Error ? error.message : String(error)}`,
+              `Cursor Run failed (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The upstream came back empty-handed — retry 🌙`,
               { providerId: CURSOR_PROVIDER_ID },
               "upstream",
             );

package/src/providers/integrations/cursor/protocol/framing.ts

@@ -71,59 +71,3 @@ export function* streamFrames(buffer: Uint8Array): Generator<Frame, void, void>
     offset = start + len
   }
 }
-
-export async function* asyncStreamFrames(
-  stream: ReadableStream<Uint8Array>,
-): AsyncGenerator<Frame, void, void> {
-  const reader = stream.getReader()
-  const chunks: Uint8Array[] = []
-  let pendingLength = 0
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done && chunks.length === 0) return
-      if (value) {
-        chunks.push(value)
-        pendingLength += value.length
-      }
-
-      // Try to parse frames from accumulated data
-      const merged = mergeChunks(chunks)
-      const frames = Array.from(streamFrames(merged))
-      const consumed = frames.reduce((sum, f) => sum + 5 + f.payload.length, 0)
-
-      if (frames.length > 0) {
-        for (const frame of frames) {
-          yield frame
-        }
-        // Keep any trailing bytes for next iteration
-        const remaining = merged.subarray(consumed)
-        chunks.length = 0
-        if (remaining.length > 0) {
-          chunks.push(remaining)
-          pendingLength = remaining.length
-        } else {
-          pendingLength = 0
-        }
-      }
-
-      if (done) return
-    }
-  } finally {
-    reader.releaseLock()
-  }
-}
-
-function mergeChunks(chunks: Uint8Array[]): Uint8Array {
-  const first = chunks[0]
-  if (chunks.length === 1 && first !== undefined) return first
-  const total = chunks.reduce((s, c) => s + c.length, 0)
-  const merged = new Uint8Array(total)
-  let offset = 0
-  for (const c of chunks) {
-    merged.set(c, offset)
-    offset += c.length
-  }
-  return merged
-}

package/src/providers/integrations/cursor/protocol/messages.ts

@@ -2282,99 +2282,3 @@ export function decodeMessage<T = Record<string, unknown>>(
   const decoded = type.decode(data)
   return type.toObject(decoded, { defaults: true, json: true, longs: Number }) as T
 }
-
-/** Decode without inventing absent proto defaults (used for byte-stable snapshots). */
-export function decodeMessageSparse<T = Record<string, unknown>>(
-  typeName: string,
-  data: Uint8Array,
-): T {
-  const root = getMessageTypes()
-  const type = root.lookupType(typeName)
-  const decoded = type.decode(data)
-  return type.toObject(decoded, { json: true, longs: Number }) as T
-}
-
-type RawField = {
-  field: number
-  wireType: number
-  varint?: string
-  fixed?: number | string
-  bytes?: Uint8Array
-}
-
-/** Schema-free walk of one message's top-level wire fields (no nested descent). */
-function readRawFields(buf: Uint8Array): RawField[] {
-  const reader = protobuf.Reader.create(buf)
-  const fields: RawField[] = []
-  while (reader.pos < reader.len) {
-    const tag = reader.uint32()
-    const field = tag >>> 3
-    const wireType = tag & 7
-    switch (wireType) {
-      case 0:
-        fields.push({ field, wireType, varint: reader.uint64().toString() })
-        break
-      case 1:
-        fields.push({ field, wireType, fixed: reader.fixed64().toString() })
-        break
-      case 2:
-        fields.push({ field, wireType, bytes: reader.bytes() })
-        break
-      case 5:
-        fields.push({ field, wireType, fixed: reader.fixed32() })
-        break
-      default:
-        // Groups (3/4) aren't used on this wire; bail rather than desync the reader.
-        return fields
-    }
-  }
-  return fields
-}
-
-/**
- * Diagnostic-only: walk AgentServerMessage.interaction_update(1).turn_ended(14)
- * without going through our hand-written TurnEnded schema, so a `cache_write`/
- * `reasoning_tokens` question can be checked against the raw wire instead of
- * guessed. Confirmed field ids 1-5 (input/output/cache_read/cache_write/
- * reasoning) decode correctly. Live captures routinely include `f4` explicitly
- * as `0` while `f3` (cache_read) and `f5` (reasoning) are non-zero — Cursor's
- * agent TurnEnded populates the field but does not report write counts here.
- */
-export function debugWalkTurnEnded(payload: Uint8Array): string {
-  try {
-    const top = readRawFields(payload)
-    const iuField = top.find((f) => f.field === 1 && f.wireType === 2)
-    if (!iuField?.bytes) return "(no interaction_update field)"
-    const iu = readRawFields(iuField.bytes)
-    const teField = iu.find((f) => f.field === 14 && f.wireType === 2)
-    if (!teField?.bytes) return "(no turn_ended field in interaction_update)"
-    const te = readRawFields(teField.bytes)
-    return te
-      .map(
-        (f) =>
-          `f${f.field}:wt${f.wireType}=${f.varint ?? f.fixed ?? (f.bytes ? `bytes[${f.bytes.length}]` : "?")}`,
-      )
-      .join(" ")
-  } catch (e) {
-    return `(walk failed: ${(e as Error).message})`
-  }
-}
-
-/**
- * Decode a protobuf sub-message from a frame payload that wraps it in
- * a top-level field key + length varint.  Skips the outer wrapper and
- * decodes the inner body as `typeName`.
- */
-export function decodeWrappedMessage<T = Record<string, unknown>>(
-  typeName: string,
-  data: Uint8Array,
-): T {
-  let offset = 1 // skip field key
-  // skip varint length
-  while (offset < data.length) {
-    const b = data[offset] ?? 0
-    offset++
-    if (!(b & 0x80)) break
-  }
-  return decodeMessage<T>(typeName, data.subarray(offset))
-}

package/src/providers/integrations/factory/factory.ts

@@ -106,7 +106,7 @@ function factoryClientHeaders(orgId: string): Record<string, string> {
  * (`packages/ai/src/providers/factory-droid.ts:271` — `"x-api-provider":
  * input.upstream`), so a value outside it has no meaning on this wire.
  */
-export const FACTORY_DROID_UPSTREAMS = [
+const FACTORY_DROID_UPSTREAMS = [
   "fireworks",
   "baseten",
   "mistral",
@@ -123,7 +123,7 @@ export const FACTORY_DROID_UPSTREAMS = [
   "databricks",
 ] as const;
 
-export type FactoryDroidUpstream = (typeof FACTORY_DROID_UPSTREAMS)[number];
+type FactoryDroidUpstream = (typeof FACTORY_DROID_UPSTREAMS)[number];
 
 const FACTORY_DROID_UPSTREAM_SET: ReadonlySet<string> = new Set(FACTORY_DROID_UPSTREAMS);
 
@@ -154,7 +154,7 @@ function logDroppedUpstream(reason: string, value: string): void {
  * unmapped failure. Omitting falls back to Factory's default routing, which is
  * the behavior a request that names no upstream already gets.
  */
-export function factoryApiProviderHeader(
+function factoryApiProviderHeader(
   options: Readonly<Record<string, unknown>> | undefined,
 ): Record<string, string> {
   const value = options?.["factory_api_provider"];
@@ -179,7 +179,7 @@ export function factoryApiProviderHeader(
  * `/api/cli/whoami` reported. An account with no recorded residency is the
  * global host, which is Factory's default.
  */
-export function factoryBaseUrl(context: ProviderDispatchContext): string {
+function factoryBaseUrl(context: ProviderDispatchContext): string {
   const region = context.credential.auth_state?.["region"];
   return region === "eu" ? FACTORY_DROID_EU_BASE_URL : FACTORY_DROID_BASE_URL;
 }
@@ -200,7 +200,7 @@ export function factoryBaseUrl(context: ProviderDispatchContext): string {
  * operator wrote into `auth_state`. The two-axis read is kept because the donor
  * needs it, not because we currently populate the second axis.
  */
-export function factoryInferenceRegion(
+function factoryInferenceRegion(
   context: ProviderDispatchContext,
 ): "global" | "us" | "eu" {
   const state = context.credential.auth_state;
@@ -266,11 +266,11 @@ const REGION_UPSTREAMS: Readonly<Record<"global" | "us" | "eu", readonly Factory
  * is, which is a property of the route rather than of the request. The donor's
  * own message text is preserved as the `reason` so the mapping is traceable.
  */
-export function factoryRegionUnavailable(modelId: string, region: string): GatewayError {
+function factoryRegionUnavailable(modelId: string, region: string): GatewayError {
   return new GatewayError(
     "capability_unsupported",
     400,
-    `factory: ${modelId} is unavailable in this account region (${region})`,
+    `factory: ${modelId} is unavailable in this account region (${region}) (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
     { model: modelId, region, reason: "Factory Droid model is unavailable in this account region." },
   );
 }
@@ -294,7 +294,7 @@ export function factoryRegionUnavailable(modelId: string, region: string): Gatew
  * Sending `configured_order` without that discovery would claim a rotation we
  * never resolved.
  */
-export function factoryRoutingSourceHeader(request: CanonicalRequest): Record<string, string> {
+function factoryRoutingSourceHeader(request: CanonicalRequest): Record<string, string> {
   const continuing = request.messages.some((message) => message.role === "assistant");
   return { "x-provider-routing-source": continuing ? "session_lock" : "registry_default" };
 }
@@ -313,7 +313,7 @@ export function factoryRoutingSourceHeader(request: CanonicalRequest): Record<st
  * donor's own region-unavailable error rather than an upstream 4xx this layer
  * cannot explain.
  */
-export function factoryRegionCheckedApiProviderHeader(
+function factoryRegionCheckedApiProviderHeader(
   request: CanonicalRequest,
   context: ProviderDispatchContext,
 ): Record<string, string> {
@@ -330,7 +330,7 @@ export function factoryRegionCheckedApiProviderHeader(
 }
 
 /** The two routing headers together, as every Factory wire sends them. */
-export function factoryRoutingHeaders(
+function factoryRoutingHeaders(
   request: CanonicalRequest,
   context: ProviderDispatchContext,
 ): Record<string, string> {
@@ -351,7 +351,7 @@ export function factoryRoutingHeaders(
 function factoryEnvelope(context: ProviderDispatchContext): { token: string; orgId: string } {
   const secret = context.credential.secret;
   if (secret === undefined || secret.length === 0) {
-    throw new GatewayError("invalid_request", 400, "factory: credential is missing a secret value");
+    throw new GatewayError("invalid_request", 400, "factory: credential is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑");
   }
   try {
     const envelope = decodeFactoryDroidCredential(secret);
@@ -360,7 +360,7 @@ function factoryEnvelope(context: ProviderDispatchContext): { token: string; org
     throw new GatewayError(
       "invalid_request",
       400,
-      `factory: ${error instanceof Error ? error.message : "stored credential is not a Factory Droid envelope"}`,
+      `factory: ${error instanceof Error ? error.message : "stored credential is not a Factory Droid envelope"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
 }
@@ -523,7 +523,7 @@ class FactoryDroidAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "factory gemini returned empty stream",
+        "factory gemini returned empty stream (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );

package/src/providers/integrations/gemini.ts

@@ -6,7 +6,7 @@ import { mapUpstreamHttpError } from "../../transport/failure-policy";
 import type { CanonicalEvent, CanonicalRequest, CanonicalStopReason } from "../../protocol/canonical-model";
 import { decodeSseEvents } from "../../protocol/sse-decoder";
 import { usageFromProvider } from "../provider-usage";
-import { readCredentialSecret, type ImageGenerationOutcome, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type WebSearchOutcome, type WebSearchResult } from "../provider-contracts";
+import { readCredentialSecret, assertWireFamily, type ImageGenerationOutcome, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type WebSearchOutcome, type WebSearchResult } from "../provider-contracts";
 import type { ModelDefinition } from "../provider-model-definition";
 import { fetchOpenAICompatibleModels } from "../discovery/openai-model-discovery";
 import { isRecord } from "../../protocol/codecs";
@@ -181,7 +181,7 @@ class GeminiAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "chat" && candidate.wire_family !== "responses" && candidate.wire_family !== "messages") {
-      throw new GatewayError("capability_unsupported", 400, `gemini supports chat/responses/messages, got ${candidate.wire_family}`);
+      assertWireFamily(candidate, ["chat", "responses", "messages"], "gemini");
     }
     const apiKey = readCredentialSecret(context.credential, "Gemini API key is required");
 
@@ -262,7 +262,7 @@ class GeminiAdapter implements ProviderAdapter {
         return;
       }
 
-      if (!response.body) throw new GatewayError("platform_unavailable", 502, "Gemini returned empty stream", {}, "upstream");
+      if (!response.body) throw new GatewayError("platform_unavailable", 502, "Gemini returned empty stream (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       let seq = 1;
       yield { type: "response_start", sequence_number: seq++, model: request.model } as CanonicalEvent;
       const state = { started: true, stopped: false, activeCalls: new Set<string>() };
@@ -339,7 +339,7 @@ class GeminiAdapter 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)
@@ -368,7 +368,7 @@ class GeminiAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        `Gemini search unreachable: ${error instanceof Error ? error.message : String(error)}`,
+        `Gemini search unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
       );
     }
     if (!response.ok) throw await mapUpstreamHttpError(response, "gemini search");
@@ -376,11 +376,11 @@ class GeminiAdapter implements ProviderAdapter {
     try {
       data = await response.json();
     } catch {
-      throw new GatewayError("platform_unavailable", 502, "Gemini search returned invalid JSON");
+      throw new GatewayError("platform_unavailable", 502, "Gemini search returned invalid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙");
     }
     const results = normalizeGroundingResults(data, maxResults);
     if (results.length === 0)
-      throw new GatewayError("platform_unavailable", 502, "Gemini search returned no grounded results");
+      throw new GatewayError("platform_unavailable", 502, "Gemini search returned no grounded results (request {requestId}). The upstream came back empty-handed — retry 🌙");
     return { results, total_results: results.length };
   }
 
@@ -391,7 +391,7 @@ class GeminiAdapter implements ProviderAdapter {
   ): Promise<ImageGenerationOutcome> {
     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 apiKey = readCredentialSecret(context.credential, "Gemini API key is required");
     const outboundFetch = context.outbound_fetch ?? this.fetchFn;
     const lifecycle = createUpstreamDeadlineLifecycle(context);
@@ -418,7 +418,7 @@ class GeminiAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        `Gemini image generation unreachable: ${error instanceof Error ? error.message : String(error)}`,
+        `Gemini image generation unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         {},
         "upstream",
       );
@@ -430,11 +430,11 @@ class GeminiAdapter implements ProviderAdapter {
     try {
       data = await response.json();
     } catch {
-      throw new GatewayError("platform_unavailable", 502, "Gemini image generation returned invalid JSON", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "Gemini image generation returned invalid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     const images = geminiInlineImages(data);
     if (images.length === 0) {
-      throw new GatewayError("platform_unavailable", 502, "Gemini image generation returned no image", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "Gemini image generation returned no image (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     return { created: imageCreatedSeconds(), data: images };
   }