cartethyia 2.7.2 → 2.7.4

package/src/persistence/stores/share-store.ts

@@ -155,7 +155,18 @@ export type SharedApiKeyIssueResult =
       readonly keyPrefix: string;
       readonly createdAt: Date;
     }
-  | { readonly kind: "link_unavailable" };
+  | { readonly kind: "link_unavailable" }
+  | {
+      readonly kind: "already_issued";
+      readonly parentKeyId: string;
+      readonly tenantId: string;
+    }
+  | {
+      readonly kind: "slot_full";
+      readonly parentKeyId: string;
+      readonly tenantId: string;
+      readonly limit: number;
+    };
 
 type ApiKeyRow = typeof apiKeys.$inferSelect;
 type ShareLinkRow = typeof shareLinks.$inferSelect;
@@ -485,6 +496,53 @@ export class DrizzleShareLinkStore implements ShareLinkStore {
       );
       if (!activeLink) return { kind: "link_unavailable" };
 
+      // One child key per canonical client IP. The public route mints from an
+      // enrollment link, and a bot replaying the same URL from one IP was
+      // creating an unbounded number of children (observed: 331k `api_keys`
+      // rows from two Google Cloud IPs in three days). If this (parent, IP)
+      // pair already has a live child, that is the same enrollment — return it
+      // as `already_issued` instead of minting another.
+      if (material.clientIpKey.length > 0) {
+        const existing = await tx
+          .select({ id: apiKeys.id })
+          .from(apiKeys)
+          .where(
+            and(
+              eq(apiKeys.parentKeyId, parent.id),
+              eq(apiKeys.issuedClientIpKey, material.clientIpKey),
+              isNull(apiKeys.revokedAt),
+            ),
+          )
+          .limit(1);
+        if (existing[0] !== undefined) {
+          return {
+            kind: "already_issued",
+            parentKeyId: parent.id,
+            tenantId: parent.tenantId,
+          };
+        }
+      }
+
+      // Slot cap: a template may bound how many concurrently-active children
+      // exist. The public link is mint-able by anyone, so without this cap a
+      // bot rotating egress IPs (CDN edges, cloud egress, proxies) could mint
+      // without bound — observed: 331k children in three days. The count is
+      // live children only; revoked children free their slot for reuse.
+      if (parent.maxChildren !== null && parent.maxChildren !== undefined) {
+        const liveCount = await tx
+          .select({ value: sql<number>`count(*) filter (where ${apiKeys.revokedAt} is null)` })
+          .from(apiKeys)
+          .where(eq(apiKeys.parentKeyId, parent.id));
+        if (Number(liveCount[0]?.value ?? 0) >= parent.maxChildren) {
+          return {
+            kind: "slot_full",
+            parentKeyId: parent.id,
+            tenantId: parent.tenantId,
+            limit: parent.maxChildren,
+          };
+        }
+      }
+
       // The label is `hint + random`, capped at 12 chars — never the
       // parent's full label plus a suffix, which grew past every table
       // column it rendered in. Built here (not imported from the console
@@ -493,6 +551,12 @@ export class DrizzleShareLinkStore implements ShareLinkStore {
       const suffix = randomInt(1000, 10_000).toString();
       const label =
         hint.length === 0 ? `key-${suffix}` : `${hint}-${suffix}`.slice(0, 12);
+      // Child rows carry identity + scopes only. Auth resolves every policy
+      // field from the parent (`policy = parent ?? row`), so copying notes,
+      // limits, model_list, denylist, etc. was pure write-amplification.
+      // Nullable policy columns stay NULL; `model_access_mode` takes its
+      // NOT NULL default ('whitelist'). Keep in sync with migration 0029 and
+      // `normalizeShareChildPolicy` in `src/console/backup/store.ts`.
       const [child] = await tx
         .insert(apiKeys)
         .values({
@@ -506,18 +570,6 @@ export class DrizzleShareLinkStore implements ShareLinkStore {
           scopes: parent.scopes,
           keyPrefix: material.keyPrefix,
           keyEncrypted: null,
-          notesTitle: parent.notesTitle,
-          notesSubtitle: parent.notesSubtitle,
-          notesBody: parent.notesBody,
-          requestsPerMinute: parent.requestsPerMinute,
-          dailyTokenLimit: parent.dailyTokenLimit,
-          monthlyTokenLimit: parent.monthlyTokenLimit,
-          lifetimeTokenBudget: parent.lifetimeTokenBudget,
-          maxConcurrentRequests: parent.maxConcurrentRequests,
-          modelPrefix: parent.modelPrefix,
-          modelAccessMode: parent.modelAccessMode,
-          modelList: parent.modelList,
-          clientRouterDenylist: parent.clientRouterDenylist,
           lifetimeTokensConsumed: 0,
         })
         .returning({ id: apiKeys.id, tenantId: apiKeys.tenantId, createdAt: apiKeys.createdAt });

package/src/persistence/stores/telemetry-store.ts

@@ -1,9 +1,10 @@
 import { readdir, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { sql } from "drizzle-orm";
+import { inArray, sql } from "drizzle-orm";
 import { affectedRows, currentTimestamp, laterOf } from "../dialect";
 import type { CartethyiaDatabase } from "../db-handle";
 import {
+  apiKeys,
   telemetryEvents,
   telemetryPayloads,
   telemetryUsageTotals,
@@ -54,7 +55,7 @@ function addUsageDelta(
   delta.outputTokens += row.outputTokens ?? 0;
 }
 
-function aggregateUsage(rows: readonly (typeof telemetryEvents.$inferInsert)[]) {
+export function aggregateUsage(rows: readonly (typeof telemetryEvents.$inferInsert)[]) {
   const deltas = new Map<string, UsageTotalDelta>();
   for (const row of rows) {
     addUsageDelta(deltas, row, "account", row.accountId);
@@ -117,6 +118,31 @@ export class DrizzleTelemetryStore {
     this.eventWriter = eventWriter;
   }
 
+  /**
+   * Resolves the share-template key for each distinct api key in a batch.
+   *
+   * The template is the key itself when it is a top-level template, or its
+   * parent when it is a minted child. The column is denormalized onto the
+   * event so family rollups do not depend on the key row surviving.
+   */
+  private async resolveFamilyTemplateIds(
+    rows: readonly (typeof telemetryEvents.$inferInsert)[],
+  ): Promise<Map<string, string>> {
+    const ids = [
+      ...new Set(
+        rows
+          .map((row) => row.apiKeyId)
+          .filter((id): id is string => typeof id === "string" && id.length > 0),
+      ),
+    ];
+    if (ids.length === 0) return new Map();
+    const resolved = await this.db
+      .select({ id: apiKeys.id, parentKeyId: apiKeys.parentKeyId })
+      .from(apiKeys)
+      .where(inArray(apiKeys.id, ids));
+    return new Map(resolved.map((row) => [row.id, row.parentKeyId ?? row.id]));
+  }
+
   /**
    * Applies usage deltas inside an enclosing transaction.
    *
@@ -137,11 +163,34 @@ export class DrizzleTelemetryStore {
       left.tenantId.localeCompare(right.tenantId)
       || left.identityType.localeCompare(right.identityType)
       || left.entityId.localeCompare(right.entityId));
+    // Resolve the share-template key for each api_key identity in the batch so
+    // the durable totals row carries it — family reads then survive the key
+    // row being deleted.
+    const apiKeyIds = [
+      ...new Set(
+        ordered
+          .filter((delta) => delta.identityType === "api_key")
+          .map((delta) => delta.entityId),
+      ),
+    ];
+    const familyTemplates = new Map<string, string>();
+    if (apiKeyIds.length > 0) {
+      const keyRows = await tx
+        .select({ id: apiKeys.id, parentKeyId: apiKeys.parentKeyId })
+        .from(apiKeys)
+        .where(inArray(apiKeys.id, apiKeyIds));
+      for (const row of keyRows) {
+        familyTemplates.set(row.id, row.parentKeyId ?? row.id);
+      }
+    }
     const now = new Date();
     await tx
       .insert(telemetryUsageTotals)
       .values(ordered.map((delta) => ({
         ...delta,
+        ...(delta.identityType === "api_key" && familyTemplates.has(delta.entityId)
+          ? { familyTemplateKeyId: familyTemplates.get(delta.entityId) }
+          : {}),
         requests: delta.requests,
         errors: delta.errors,
         inputTokens: delta.inputTokens,
@@ -171,6 +220,13 @@ export class DrizzleTelemetryStore {
     // The file accepts anything, so a malformed row would be written and then
     // retried forever without ever failing. Rejecting it here keeps the buffer's
     // drop-and-count contract: one bad row fails the batch, once.
+    const familyTemplates = await this.resolveFamilyTemplateIds(rows);
+    for (const row of rows) {
+      if (typeof row.apiKeyId === "string" && row.apiKeyId.length > 0) {
+        const template = familyTemplates.get(row.apiKeyId);
+        if (template !== undefined) row.familyTemplateKeyId = template;
+      }
+    }
     const unique: Array<typeof telemetryEvents.$inferInsert> = [];
     const ids = new Set<string>();
     for (const row of rows) {

package/src/persistence/system-prompt-store.ts

@@ -0,0 +1,104 @@
+// Persistence for tenant system-prompt injection settings.
+//
+// One row per tenant. Mutations bump the settings revision so the dispatch
+// path's revision-keyed reader converges immediately (same mechanism as the
+// runtime-preferences cache).
+import { eq } from "drizzle-orm";
+import type { CartethyiaDatabase } from "./db-handle";
+import { tenantSystemPrompts } from "./schema";
+import type {
+  ProviderPromptEntry,
+  PromptSetting,
+  TenantSystemPrompts,
+} from "../console/system-prompt/contracts";
+import {
+  EMPTY_TENANT_SYSTEM_PROMPTS,
+  SYSTEM_PROMPT_MODEL_LIMIT,
+  SYSTEM_PROMPT_PROVIDER_LIMIT,
+  isPromptSetting,
+  parseSystemPromptModelKey,
+} from "../console/system-prompt/contracts";
+import { bumpSettingsRevision } from "./settings-revision";
+
+/** The stored row, normalized. Absent row reads as the empty configuration. */
+export type StoredTenantSystemPrompts = TenantSystemPrompts;
+
+/**
+ * Reads the tenant's stored configuration, defensively normalized: a
+ * hand-edited or legacy row must not poison the dispatch path, so malformed
+ * entries are dropped rather than trusted.
+ */
+export async function readTenantSystemPrompts(
+  db: CartethyiaDatabase,
+  tenantId: string,
+): Promise<StoredTenantSystemPrompts> {
+  const rows = await db
+    .select({
+      global: tenantSystemPrompts.global,
+      providers: tenantSystemPrompts.providers,
+      models: tenantSystemPrompts.models,
+    })
+    .from(tenantSystemPrompts)
+    .where(eq(tenantSystemPrompts.tenantId, tenantId))
+    .limit(1);
+  const row = rows[0];
+  if (row === undefined) return EMPTY_TENANT_SYSTEM_PROMPTS;
+
+  const providers: Record<string, ProviderPromptEntry> = {};
+  for (const [providerId, entry] of Object.entries(row.providers ?? {})) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const candidate = entry as Partial<ProviderPromptEntry>;
+    if (typeof candidate.followGlobal !== "boolean") continue;
+    if (candidate.followGlobal === false) {
+      if (!isPromptSetting(candidate.setting)) continue;
+      providers[providerId] = { followGlobal: false, setting: candidate.setting };
+    } else {
+      providers[providerId] = { followGlobal: true };
+    }
+  }
+
+  const models: Record<string, PromptSetting> = {};
+  for (const [key, setting] of Object.entries(row.models ?? {})) {
+    if (parseSystemPromptModelKey(key) === null) continue;
+    if (!isPromptSetting(setting)) continue;
+    models[key] = setting;
+  }
+
+  return {
+    global: row.global !== null && isPromptSetting(row.global) ? row.global : null,
+    providers,
+    models,
+  };
+}
+
+/** Upserts the tenant's configuration and bumps the settings revision. */
+export async function writeTenantSystemPrompts(
+  db: CartethyiaDatabase,
+  tenantId: string,
+  next: TenantSystemPrompts,
+): Promise<void> {
+  // Keep the row bounded even though the API already enforces the caps: a
+  // direct store caller must not be able to plant an unbounded map.
+  const providers = Object.entries(next.providers).slice(0, SYSTEM_PROMPT_PROVIDER_LIMIT);
+  const models = Object.entries(next.models).slice(0, SYSTEM_PROMPT_MODEL_LIMIT);
+  const values = {
+    global: next.global,
+    providers: Object.fromEntries(providers),
+    models: Object.fromEntries(models),
+    updatedAt: new Date(),
+  };
+  await db
+    .insert(tenantSystemPrompts)
+    .values({ tenantId, ...values })
+    .onConflictDoUpdate({ target: tenantSystemPrompts.tenantId, set: values });
+  bumpSettingsRevision();
+}
+
+/** Clears the tenant's configuration entirely (console "reset" path). */
+export async function clearTenantSystemPrompts(
+  db: CartethyiaDatabase,
+  tenantId: string,
+): Promise<void> {
+  await db.delete(tenantSystemPrompts).where(eq(tenantSystemPrompts.tenantId, tenantId));
+  bumpSettingsRevision();
+}

package/src/protocol/codecs.ts

@@ -480,7 +480,7 @@ export function assertBoundedJsonDepth(value: unknown): void {
 
 function assertBoundedDepthWalk(value: unknown, depth: number): void {
   if (depth > MAX_JSON_DEPTH)
-    throw new GatewayError("invalid_request", 400, `The request body is nested deeper than this endpoint accepts (${MAX_JSON_DEPTH} levels). Flatten the payload.`);
+    throw new GatewayError("invalid_request", 400, `The request body is nested deeper than this endpoint accepts (${MAX_JSON_DEPTH} levels) (request {requestId}). Flatten the payload. Check the shape of what you sent — then resend 🪞`);
   if (Array.isArray(value)) {
     for (const item of value) assertBoundedDepthWalk(item, depth + 1);
     return;
@@ -1038,7 +1038,7 @@ export function filterProviderCustomHeaders(
   for (const [rawName, rawValue] of Object.entries(input)) {
     const name = rawName.toLowerCase();
     if (!HEADER_TOKEN.test(name)) {
-      throw new GatewayError("invalid_request", 400, `invalid custom header name: ${rawName}`, {
+      throw new GatewayError("invalid_request", 400, `invalid custom header name: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`, {
         header: rawName,
       });
     }
@@ -1047,7 +1047,7 @@ export function filterProviderCustomHeaders(
       extraReserved.has(name) ||
       name.startsWith("x-forwarded-")
     ) {
-      throw new GatewayError("invalid_request", 400, `custom header is protected: ${rawName}`, {
+      throw new GatewayError("invalid_request", 400, `custom header is protected: ${rawName} (request {requestId}). Not allowed by policy — no hard feelings 🫂`, {
         header: rawName,
       });
     }
@@ -1055,7 +1055,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value must be a string: ${rawName}`,
+        `custom header value must be a string: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         { header: rawName },
       );
     }
@@ -1063,7 +1063,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value exceeds 4KiB: ${rawName}`,
+        `custom header value exceeds 4KiB: ${rawName} (request {requestId}). We love long reads, but not that long 📚`,
         { header: rawName },
       );
     }
@@ -1071,7 +1071,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value contains control characters: ${rawName}`,
+        `custom header value contains control characters: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         { header: rawName },
       );
     }

package/src/protocol/gateway-error.ts

@@ -6,12 +6,14 @@ export type GatewayErrorCode =
   | "capability_unsupported"
   | "ambiguous_model"
   | "model_not_found"
+  | "model_not_allowed"
   | "upstream_not_found"
   | "context_length_exceeded"
   | "request_too_large"
   | "accounts_unavailable"
   | "accounts_rate_limited"
   | "capacity_exhausted"
+  | "upstream_overloaded"
   | "provider_capacity_exhausted"
   | "upstream_queued"
   | "proxy_pool_capacity_exceeded"
@@ -22,8 +24,10 @@ export type GatewayErrorCode =
   | "proxy_pool_unhealthy"
   | "invalid_pool_limits"
   | "admission_unavailable"
+  | "route_unavailable"
   | "slug_reserved"
   | "quota_exceeded"
+  | "rate_limited"
   | "authentication_failed"
   | "policy_rejected"
   | "invalid_request"
@@ -52,8 +56,7 @@ export type GatewayErrorCode =
   | "proxy_unreachable"
   | "tool_call_loop_detected"
   | "client_router_denied"
-  | "shutting_down"
-  | "restart_for_update";
+  | "shutting_down";
 
 /** Identifies which boundary produced a safe public error. */
 export type GatewayErrorOrigin = "cartethyia" | "upstream" | "network";
@@ -226,7 +229,7 @@ export function capabilityUnsupported(
   return new GatewayError(
     "capability_unsupported",
     400,
-    `The selected route does not support capability: ${capability}`,
+    `The selected route does not support capability: ${capability} (request {requestId}). Drop the ${capability} part of the request, or route to a model that accepts it. Know your tools — this one just isn't in the box 🧰`,
     { capability, ...details },
   );
 }

package/src/protocol/image-generation.ts

@@ -22,7 +22,7 @@ const OPENAI_ASPECT_RATIOS: Readonly<Record<string, string>> = {
 export function imagePrompt(body: Record<string, unknown>): string {
   if (typeof body.prompt === "string" && body.prompt.trim().length > 0) return body.prompt;
   if (!Array.isArray(body.messages)) {
-    throw new GatewayError("invalid_request", 400, "prompt is required");
+    throw new GatewayError("invalid_request", 400, "prompt is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   const texts: string[] = [];
   for (const message of body.messages) {
@@ -41,7 +41,7 @@ export function imagePrompt(body: Record<string, unknown>): string {
     }
   }
   const prompt = texts.join("\n").trim();
-  if (prompt.length === 0) throw new GatewayError("invalid_request", 400, "prompt is required");
+  if (prompt.length === 0) throw new GatewayError("invalid_request", 400, "prompt is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   return prompt;
 }
 

package/src/protocol/reasoning.ts

@@ -50,19 +50,83 @@ export function applyDeepSeekReasoning(payload: Record<string, unknown>): void {
     payload["reasoning_effort"] = "high";
 }
 
+/**
+ * Model families whose Chat-compatible upstream enforces the DeepSeek replay
+ * rule: every prior assistant turn must carry `reasoning_content`, or the
+ * upstream refuses the whole request with
+ * `Missing required parameter: 'messages[N].reasoning_content'`. Seen on
+ * Cline's resold `reflection/beam-free` (2026-10-30) and on the buddy
+ * DeepSeek family. Cline, OpenRouter, Hermes, and Kilo share one chat wire,
+ * so the rule is stated once, keyed on the model family.
+ */
+const REASONING_REPLAY_MODEL_RE = /(?:deepseek|reflection\/beam)/i;
+
+/**
+ * Ensures every assistant turn carries `reasoning_content` for model families
+ * whose upstream enforces the DeepSeek replay rule. The rule demands the field
+ * on *every* earlier assistant message — presence, not content — and the
+ * upstream rejects an absent field with
+ * `Missing required parameter: 'messages[N].reasoning_content'` even when the
+ * turn genuinely has no trace to replay. Clients that already learned the rule
+ * send `reasoning_content: ""` for exactly those turns (see the chat surface
+ * parser), so an empty string is the honest value for a turn with nothing to
+ * replay. Existing values are never overwritten.
+ *
+ * Unlike `backfillDeepSeekReasoningContent`, this runs only for the
+ * OpenAI-compatible resellers (Cline/OpenRouter/Hermes/Kilo), not the buddy
+ * family, whose upstream rejects empty reasoning as "stripped" and drops it.
+ */
+export function ensureChatReasoningReplayPresence(payload: Record<string, unknown>): void {
+  const model = typeof payload["model"] === "string" ? payload["model"] : "";
+  if (!REASONING_REPLAY_MODEL_RE.test(model)) return;
+  const messages = payload["messages"];
+  if (!Array.isArray(messages)) return;
+  const thinking = payload["thinking"];
+  const thinkingEnabled = isRecord(thinking) && thinking["type"] === "enabled";
+  const hasTrace = messages.some(
+    (message) =>
+      isRecord(message) &&
+      ((typeof message["reasoning"] === "string" && message["reasoning"].length > 0) ||
+        "reasoning_content" in message),
+  );
+  // Same gate as the backfill: a request that never entered thinking mode and
+  // carries no reasoning anywhere has nothing the model could demand, so do
+  // not start marking its turns as thinking turns.
+  if (!thinkingEnabled && !hasTrace) return;
+  for (const message of messages) {
+    if (!isRecord(message) || message["role"] !== "assistant") continue;
+    if (typeof message["reasoning_content"] === "string") continue;
+    message["reasoning_content"] = "";
+  }
+}
+
 /** Backfills DeepSeek assistant reasoning_content required for replayed turns. */
 export function backfillDeepSeekReasoningContent(payload: Record<string, unknown>): void {
+  const model = typeof payload["model"] === "string" ? payload["model"] : "";
   const thinking = payload["thinking"];
   const thinkingEnabled = isRecord(thinking) && thinking["type"] === "enabled";
   const messages = payload["messages"];
   if (!Array.isArray(messages)) return;
+  const requiresReplay = REASONING_REPLAY_MODEL_RE.test(model);
   const hasTrace = messages.some(
     (message) =>
       isRecord(message) &&
       ((typeof message["reasoning"] === "string" && message["reasoning"].length > 0) ||
         "reasoning_content" in message),
   );
-  if (!thinkingEnabled && !hasTrace) return;
+  if (!thinkingEnabled && !requiresReplay && !hasTrace) return;
+  // As an *input* (a caller replays a prior turn), the model's own `reasoning`
+  // key is the canonical record of a thinking turn. Without it there is no
+  // trace to replay, so an assistant turn stays bare even under the hard rule;
+  // fabricating `""` would be read by the upstream as "thinking mode with the
+  // reasoning stripped" and reject the request anyway.
+  const hasModelReasoning = messages.some(
+    (message) =>
+      isRecord(message) &&
+      typeof message["reasoning"] === "string" &&
+      message["reasoning"].length > 0,
+  );
+  if (requiresReplay && !thinkingEnabled && !hasModelReasoning && !hasTrace) return;
   for (const message of messages) {
     if (!isRecord(message) || message["role"] !== "assistant") continue;
     if (typeof message["reasoning_content"] === "string") continue;

package/src/protocol/request/chat.ts

@@ -549,6 +549,7 @@ export function canonicalToChatPayload(
     ...(options.maxOutputTokens === undefined ? {} : { maxOutputTokens: options.maxOutputTokens }),
   });
   delete payload["max_tokens"];
+  delete payload["max_completion_tokens"];
   if (bounded !== undefined) payload[tokenLimitField] = bounded;
   return payload;
 }

package/src/protocol/response/chat.ts

@@ -472,8 +472,8 @@ export async function* decodeChatSseStream(
         "platform_unavailable",
         502,
         error instanceof Error
-          ? `Malformed SSE event: ${error.message}`
-          : "Malformed SSE event",
+          ? `Malformed SSE event: ${error.message} (request {requestId}). The upstream sent something we can't read — retry 🌙`
+          : `Malformed SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙`,
         {},
         "upstream",
       );

package/src/protocol/response/codex.ts

@@ -364,7 +364,7 @@ export class CodexStreamFrameProcessor {
       throw new GatewayError(
         "tool_call_loop_detected",
         502,
-        "Codex whitespace-loop guard tripped: tool call emitted only whitespace argument deltas past the safety threshold",
+        "Codex whitespace-loop guard tripped (request {requestId}): tool call emitted only whitespace argument deltas past the safety threshold. Caught in a loop — breaking the cycle 🔁",
         { call_key: key, event_count: next.count, char_count: next.chars },
       );
     }

package/src/protocol/response/gemini.ts

@@ -124,7 +124,7 @@ export function decodeGeminiStreamEvent(
     throw new GatewayError(
       "platform_unavailable",
       502,
-      error instanceof Error ? `Malformed SSE event: ${error.message}` : "Malformed SSE event",
+      error instanceof Error ? `Malformed SSE event: ${error.message} (request {requestId}). The upstream sent something we can't read — retry 🌙` : `Malformed SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙`,
       {},
       "upstream",
     );

package/src/protocol/response/messages.ts

@@ -51,7 +51,7 @@ export function parseClaudeContent(value: unknown, isOAuth = false): ContentPart
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Claude response tool_use is missing id or name",
+        "Claude response tool_use is missing id or name (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );
@@ -69,7 +69,7 @@ export function parseClaudeContent(value: unknown, isOAuth = false): ContentPart
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Claude response tool_result is missing tool_use_id",
+        "Claude response tool_result is missing tool_use_id (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );
@@ -467,7 +467,7 @@ export async function* parseClaudeSseStream(
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Malformed Claude SSE event",
+        "Malformed Claude SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙",
         {},
         "upstream",
       );
@@ -476,7 +476,7 @@ export async function* parseClaudeSseStream(
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Invalid Claude SSE event",
+        "Invalid Claude SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙",
         {},
         "upstream",
       );
@@ -492,7 +492,7 @@ export async function* parseClaudeSseStream(
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Claude stream ended before message_stop",
+      "Claude stream ended before message_stop (request {requestId}). The upstream came back empty-handed — retry 🌙",
       {},
       "upstream",
     );

package/src/protocol/response/responses.ts

@@ -336,8 +336,8 @@ export async function* decodeResponsesSseStream(
         "platform_unavailable",
         502,
         error instanceof Error
-          ? `Malformed SSE event: ${error.message}`
-          : "Malformed SSE event",
+          ? `Malformed SSE event: ${error.message} (request {requestId}). The upstream sent something we can't read — retry 🌙`
+          : `Malformed SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙`,
         {},
         "upstream",
       );

package/src/protocol/sse-decoder.ts

@@ -57,14 +57,14 @@ const DEFAULT_MAX_EVENT_BYTES = 4 * 1024 * 1024;
 // `upstream` origin keeps the public envelope from prefixing it
 // a gateway-branded message, which blamed the gateway for the provider's bytes.
 function oversized(what: string): GatewayError {
-  return new GatewayError("platform_unavailable", 502, `SSE ${what} exceeds size bound`, {}, "upstream");
+  return new GatewayError("platform_unavailable", 502, `SSE ${what} exceeds size bound (request {requestId}). The upstream sent more than we can hold — retry 🌙`, {}, "upstream");
 }
 
 export async function* decodeSseEvents(
   body: ReadableStream<Uint8Array> | null,
   opts: SseDecodeOptions = {},
 ): AsyncIterable<SseEvent> {
-  if (body === null) throw new GatewayError("platform_unavailable", 502, "SSE response has no body", {}, "upstream");
+  if (body === null) throw new GatewayError("platform_unavailable", 502, "SSE response has no body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   const maxEventBytes = opts.maxEventBytes ?? DEFAULT_MAX_EVENT_BYTES;
   const maxLineBytes = opts.maxLineBytes ?? maxEventBytes;
   const signal = opts.signal;
@@ -163,7 +163,18 @@ export async function* decodeSseEvents(
     // not 502 the request: only `event:`/`data:` carry payload, the rest is
     // heartbeat/metadata. Unknown colon-prefixed fields are ignored.
     if (/^[a-zA-Z0-9_-]+:/.test(line)) return;
-    throw new GatewayError("platform_unavailable", 502, "Malformed SSE line", {}, "upstream");
+    // Some vendors (Qoder IDE /model/v1) emit a single `data:` event whose JSON
+    // payload contains literal newlines, so the event arrives as several lines:
+    // the first has the `data:` prefix, the rest are bare continuations. Treat
+    // a bare line as a continuation of the open `data:` event rather than a
+    // malformed stream. A bare line with no open data is still an error.
+    if (dataLines.length > 0) {
+      dataLines.push(line);
+      eventBytes += line.length;
+      if (eventBytes > maxEventBytes) throw oversized("event");
+      return;
+    }
+    throw new GatewayError("platform_unavailable", 502, "Malformed SSE line (request {requestId}). The upstream sent something we can't read — retry 🌙", {}, "upstream");
   }
 
   try {

package/src/protocol/translation/capabilities.ts

@@ -259,7 +259,7 @@ export function ensureMaxTokensForThinking(
     throw new GatewayError(
       "invalid_request",
       400,
-      `Anthropic thinking budget requires max_tokens greater than ${buffer}; got ${currentMax} with budget ${budget}`,
+      `Anthropic thinking budget requires max_tokens greater than ${buffer}; got ${currentMax} with budget ${budget} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
       { budget_tokens: budget, max_tokens: currentMax },
     );
   }
@@ -364,7 +364,7 @@ function validateCacheBreakpoints(hint: CacheHint | undefined): void {
     throw new GatewayError(
       "invalid_request",
       400,
-      `cache_hint declares ${hint.list.length} breakpoints; at most ${MAX_CACHE_BREAKPOINTS} are supported`,
+      `cache_hint declares ${hint.list.length} breakpoints; at most ${MAX_CACHE_BREAKPOINTS} are supported (request {requestId}). Check the shape of what you sent — then resend 🪞`,
       { breakpoint_count: hint.list.length, max_breakpoints: MAX_CACHE_BREAKPOINTS },
     );
   }