cartethyia 2.7.4 → 2.7.5

package/src/providers/integrations/qoder/qoder.ts

@@ -12,6 +12,7 @@ import {
 } from "../../../transport/failure-policy";
 import { GatewayError } from "../../../protocol/gateway-error";
 import { resolveImageSource } from "../../../protocol/codecs";
+import { reasoningEffortFromIntent } from "../../../protocol/reasoning";
 import type {
   CanonicalEvent,
   CanonicalRequest,
@@ -21,14 +22,14 @@ import type {
   ToolDefinition,
 } from "../../../protocol/canonical-model";
 import { toolResultParts, toolCallParts } from "../../../protocol/canonical-model";
-import { decodeSseEvents } from "../../../protocol/sse-decoder";
+import { decodeQoderSseEvents } from "./qoder-sse";
 import { usageFromProvider, readReasoningText } from "../../provider-usage";
 import { readCredentialSecret, assertWireFamily, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type ProviderId } from "../../provider-contracts";
 import type { ModelDefinition } from "../../provider-model-definition";
 import { parseQoderOAuthState } from "./qoder-oauth";
 import { getQoderVersion } from "../../operations/client-versions";
 import { abortGatewayError, createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
-import { qoderMachineOs } from "../../operations/cli-platform";
+import { qoderMachineOs, qoderMachineHostname } from "../../operations/cli-platform";
 import { qoderIdeChatUrl, qoderInferenceCandidates, QODER_CHAT_PATH, QODER_REALMS, type QoderRealm } from "./qoder-realm";
 import {
   QODER_CN_MODEL_CONFIGS,
@@ -117,26 +118,6 @@ export const MODERN_PROFILE: QoderModeProfile = {
 
 const QODER_PROVIDER_ID = "qoder" as const;
 
-export const QODER_MODEL_CONFIGS: Record<
-  string,
-  { id: string; display_name: string; max_input_tokens: number; max_output_tokens?: number; is_vl: boolean; is_reasoning: boolean; source?: string }
-> = {
-  auto: { id: "auto", display_name: "Auto", max_input_tokens: 180000, is_vl: true, is_reasoning: false },
-  ultimate: { id: "ultimate", display_name: "Ultimate", max_input_tokens: 180000, is_vl: true, is_reasoning: true },
-  performance: { id: "performance", display_name: "Performance", max_input_tokens: 272000, is_vl: true, is_reasoning: false },
-  efficient: { id: "efficient", display_name: "Efficient", max_input_tokens: 180000, is_vl: true, is_reasoning: false },
-  lite: { id: "lite", display_name: "Lite", max_input_tokens: 180000, is_vl: false, is_reasoning: true },
-  qmodel: { id: "qmodel", display_name: "Qwen 3.6 Plus", max_input_tokens: 180000, is_vl: true, is_reasoning: false },
-  qmodel_latest: { id: "qmodel_latest", display_name: "Qwen 3.7 Max", max_input_tokens: 1000000, is_vl: true, is_reasoning: false },
-  qmodel_preview: { id: "qmodel_preview", display_name: "Qwen 3.8 Max", max_input_tokens: 1000000, is_vl: true, is_reasoning: false },
-  dmodel: { id: "dmodel", display_name: "DeepSeek V4 Pro", max_input_tokens: 180000, is_vl: true, is_reasoning: true },
-  dfmodel: { id: "dfmodel", display_name: "DeepSeek V4 Flash", max_input_tokens: 180000, is_vl: true, is_reasoning: true },
-  gm51model: { id: "gm51model", display_name: "GLM 5.1", max_input_tokens: 180000, is_vl: true, is_reasoning: true },
-  kmodel: { id: "kmodel", display_name: "Kimi K2.6", max_input_tokens: 256000, is_vl: true, is_reasoning: false },
-  mmodel: { id: "mmodel", display_name: "MiniMax M2.7", max_input_tokens: 180000, is_vl: true, is_reasoning: false },
-  kmodel_latest: { id: "kmodel_latest", display_name: "Kimi K2.7 Latest", max_input_tokens: 256000, is_vl: true, is_reasoning: false },
-};
-
 const QODER_APPCODE = "cosy";
 const QODER_SIG_SECRET = "d2FyLCB3YXIgbmV2ZXIgY2hhbmdlcw==";
 /**
@@ -182,7 +163,19 @@ interface QoderModelConfig {
   max_output_tokens?: number;
   is_vl: boolean;
   is_reasoning: boolean;
+  /**
+   * Whether upstream publishes this row as free. Only an explicit `true`
+   * marks the model as free-tier; absent or `false` means billed/unknown, so
+   * a 402/116 there is genuine quota exhaustion, not a free-tier entitlement
+   * refusal, and must not trigger a legacy-surface fallback.
+   */
+  is_free?: boolean;
   source?: string;
+  /**
+   * Reasoning effort to send when the caller did not ask for one. Some models
+   * on the IDE surface stream no reasoning unless an effort is present.
+   */
+  default_reasoning_effort?: string;
 }
 
 function qoderMd5(value: string | Uint8Array): string {
@@ -456,12 +449,29 @@ function qoderEnvelopeMessage(rec: Record<string, unknown>): string {
   return extractUpstreamMessage(rec);
 }
 
-function qoderEnvelopeToFrames(data: string): Array<{ event: string | null; data: string }> {
+export function qoderEnvelopeToFrames(data: string): Array<{ event: string | null; data: string }> {
   if (data === "[DONE]") return [{ event: null, data: "[DONE]" }];
   let envelope: unknown;
+  // The IDE surface sometimes embeds literal newlines inside JSON string
+  // values (e.g. the raw_usage event carries keys like
+  // `"data_policy_preferre\n\nnd_count"`). Those bytes are not valid JSON, so
+  // the first parse fails; when it does, salvage the event by escaping the
+  // raw newlines inside string values and parse again. The repaired text is
+  // also what the direct-chunk branch hands to the chunk parser below, so its
+  // own `JSON.parse` succeeds too.
+  let repaired = data;
   try {
     envelope = JSON.parse(data);
   } catch {
+    const attempted = escapeJsonRawNewlines(data);
+    if (attempted !== data) {
+      try {
+        envelope = JSON.parse(attempted);
+        repaired = attempted;
+      } catch {
+        envelope = undefined;
+      }
+    }
   }
   if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) return [];
   const rec = envelope as Record<string, unknown>;
@@ -505,11 +515,61 @@ function qoderEnvelopeToFrames(data: string): Array<{ event: string | null; data
   if (body === "[DONE]") return [{ event: null, data: "[DONE]" }];
   if (typeof body === "string") return [{ event: null, data: body.replace(/\r?\n/g, "") }];
   // Direct OpenAI chunk (IDE surface): no envelope body, but a `choices` array
-  // is present. Pass the raw data through so the chunk parser sees it.
-  if (Array.isArray(rec["choices"])) return [{ event: null, data }];
+  // is present. Pass the (repaired) raw data through so the chunk parser sees
+  // it.
+  if (Array.isArray(rec["choices"])) return [{ event: null, data: repaired }];
   return [];
 }
 
+/**
+ * Escapes raw newline bytes that appear inside JSON string values.
+ *
+ * The IDE surface emits `data:` events whose JSON payload contains literal
+ * newlines inside strings (the terminal `raw_usage` event carries keys like
+ * `"data_policy_preferre\n\nnd_count"`). `JSON.parse` rejects those bytes, so
+ * before parsing we rewrite each raw `\n` found inside a string to the two
+ * characters `\n`. Bytes outside strings (whitespace, structural separators)
+ * are left untouched.
+ */
+function escapeJsonRawNewlines(data: string): string {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < data.length; i += 1) {
+    const ch = data[i]!;
+    if (inString) {
+      if (escaped) {
+        out += ch;
+        escaped = false;
+        continue;
+      }
+      if (ch === "\\") {
+        out += ch;
+        escaped = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+        out += ch;
+        continue;
+      }
+      if (ch === "\n" || ch === "\r") {
+        out += "\\n";
+        continue;
+      }
+      out += ch;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+
 function qoderStableHash(prefix: string, ...parts: string[]): string {
   const h = createHash("sha256");
   h.update(prefix);
@@ -563,13 +623,23 @@ function qoderMaxContextFor(modelId: string, modelConfig: QoderModelConfig, real
   return modelConfig.max_input_tokens;
 }
 
-function qoderRequestedMaxTokens(request: CanonicalRequest, modelConfig: QoderModelConfig): number {
+function qoderRequestedMaxTokens(
+  request: CanonicalRequest,
+  modelConfig: QoderModelConfig,
+  realm: QoderRealm,
+): number {
   /**
    * The ceiling is the roster's stated one. A fixed 32k fallback would clamp
    * every model alike, so a request asking for more would be silently lowered
-   * no matter which model it named.
+   * no matter which model it named. A discovered row carries no
+   * `max_output_tokens` (upstream's model list reports none), so consult the
+   * static roster for the key before the 65_536 last resort — and keep that
+   * last resort only when neither the caller nor the roster states a limit.
    */
-  const configured = typeof modelConfig.max_output_tokens === "number" ? modelConfig.max_output_tokens : 65_536;
+  const configured =
+    typeof modelConfig.max_output_tokens === "number"
+      ? modelConfig.max_output_tokens
+      : qoderRosterMaxOutput(modelConfig.id, realm) ?? 65_536;
   const controls = request.generation_controls as Record<string, unknown>;
   const requested =
     typeof controls["max_tokens"] === "number"
@@ -580,6 +650,17 @@ function qoderRequestedMaxTokens(request: CanonicalRequest, modelConfig: QoderMo
   return typeof requested === "number" && requested > 0 ? Math.min(requested, configured) : configured;
 }
 
+/**
+ * The static roster's stated output ceiling for one key, when the roster states
+ * one. Dispatch builds a live-discovered model's config without an output limit
+ * (upstream's model list reports none); this lookup restores the roster's
+ * ceiling so such a model is not capped at the 65_536 last resort.
+ */
+function qoderRosterMaxOutput(modelId: string, realm: QoderRealm): number | undefined {
+  const configs = realm === "cn" ? QODER_CN_MODEL_CONFIGS : QODER_INTL_MODEL_CONFIGS;
+  return configs[modelId]?.max_output_tokens;
+}
+
 /**
  * Whether this model needs the prior turn's reasoning echoed back.
  *
@@ -908,16 +989,32 @@ export function buildQoderRequest(
   }
   const latestUserMessage = [...qoderMessages].reverse().find((m) => m["role"] === "user");
   const latestUserText = typeof latestUserMessage?.["content"] === "string" ? (latestUserMessage["content"] as string) : "";
-  const maxTokens = qoderRequestedMaxTokens(request, modelConfig);
+  const maxTokens = qoderRequestedMaxTokens(request, modelConfig, realm);
   const reasoning = modelConfig.is_reasoning === true;
+  // 1:1 with the IDE worker's `FTn` legacy builder, which sends reasoning
+  // effort as a top-level camelCase field (`reasoningEffort`), derived from
+  // the canonical intent when one is present. Omitted entirely when the
+  // caller asked for no reasoning, matching the reference's conditional send.
+  // When the caller sends no intent but the model needs the push to think
+  // (verified live: Sonus/Cantus stream no reasoning without it), use the
+  // roster's default effort.
+  const reasoningEffort =
+    reasoningEffortFromIntent(request.reasoning) ?? modelConfig.default_reasoning_effort;
   const sessionId = qoderStableHash("qoder-session", auth.userId, modelId);
   const recordId = qoderStableRecordId(modelId, allMessages, maxTokens);
   return {
+    // 1:1 with the IDE worker's `FTn` legacy request builder, which always
+    // sends a top-level `model` equal to the resolved roster key (falling
+    // back to "auto" only when no key is known). The upstream honours
+    // `model_config.key` for actual dispatch and echoes a fixed "auto" in
+    // stream chunks, but the field is part of the wire shape the IDE sends.
+    model: modelId,
     request_id: randomUUID(),
     request_set_id: recordId,
     chat_record_id: recordId,
     session_id: sessionId,
     stream: true,
+    ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
     ...(MODERN_PROFILE.emptyAliyunUserType ? { aliyun_user_type: "" } : {}),
     chat_task: "FREE_INPUT",
     is_reply: true,
@@ -957,8 +1054,9 @@ export function buildQoderRequest(
       max_input_tokens: qoderMaxContextFor(modelId, modelConfig, realm),
       // Mirrors the roster's stated ceiling. A fixed 32k fallback would be sent
       // for every model alike, so the request would declare a cap the catalog
-      // does not publish.
-      max_output_tokens: modelConfig.max_output_tokens ?? 65_536,
+      // does not publish. A discovered model's config carries no output limit,
+      // so consult the roster for the key before the 65_536 last resort.
+      max_output_tokens: modelConfig.max_output_tokens ?? qoderRosterMaxOutput(modelId, realm) ?? 65_536,
       source: modelConfig.source ?? "system",
     },
     messages: qoderMessages,
@@ -1003,6 +1101,16 @@ export function buildQoderIdeRequest(
     messages,
     stream: true,
     stream_options: { include_usage: true },
+    // The same reasoning-effort field the legacy surface uses; without it the
+    // IDE surface streams no thinking for models that need the push (Sonus,
+    // Cantus). Undefined when the caller asked for none and the roster has no
+    // default, matching the legacy builder.
+    ...(legacy.reasoningEffort === undefined ? {} : { reasoningEffort: legacy.reasoningEffort }),
+    // The full wire config (model key, window, output ceiling, tier) the legacy
+    // surface sends. The IDE surface reads the same block, so shipping it keeps
+    // the request the same shape for every Qoder model — including lite's 1M
+    // window and 64k output cap.
+    ...(legacy.model_config === undefined ? {} : { model_config: legacy.model_config }),
     metadata: {
       context: {
         request_id: legacy.request_id,
@@ -1023,7 +1131,16 @@ export function buildQoderIdeRequest(
   };
 }
 
-/** Identity headers for the modern model-server surface (plain bearer). */
+/**
+ * Identity headers for the modern model-server surface (plain bearer).
+ *
+ * Mirrors the desktop IDE's `openResponse` exactly: the IDE sends the five
+ * OpenAI-surface headers (Authorization, Content-Type, Accept, X-Request-ID,
+ * X-Session-ID) and the global client-identity interceptor adds Cosy-Version,
+ * Cosy-ClientType, Cosy-MachineOS, and Cosy-MachineHostname (for infer-sse
+ * requests). It does NOT send Cosy-MachineId / Cosy-MachineToken /
+ * Cosy-MachineType on this surface, so neither do we.
+ */
 function qoderIdeHeaders(auth: QoderAuth, version: string): Record<string, string> {
   return {
     Authorization: `Bearer ${auth.securityOauthToken}`,
@@ -1034,10 +1151,7 @@ function qoderIdeHeaders(auth: QoderAuth, version: string): Record<string, strin
     "Cosy-Version": version,
     "Cosy-ClientType": "5",
     "Cosy-MachineOS": qoderMachineOs(),
-    "Cosy-MachineHostname": "DESKTOP-QODER",
-    "Cosy-MachineId": auth.machineId,
-    "Cosy-MachineToken": auth.machineId,
-    "Cosy-MachineType": "5",
+    "Cosy-MachineHostname": qoderMachineHostname(),
   };
 }
 
@@ -1057,6 +1171,141 @@ async function callQoderIde(
   });
 }
 
+/**
+ * True when the modern model-server surface refused the request on entitlement
+ * grounds. This only detects the refusal — whether a legacy fallback is worth
+ * trying is the caller's decision, and it is gated on the model being free-tier
+ * (see `dispatch`).
+ *
+ * The upstream's refusal envelope is `{"code":116,"error":"quota exceeded"}`
+ * on HTTP 402. The IDE's own error set classifies 116 as a quota/entitlement
+ * failure (not an auth error), and the gRPC surface reports the same code as
+ * status 13. For a free-tier model this is an entitlement refusal the legacy
+ * COSY surface will serve with the same credential; for a billed model the
+ * same code is genuine quota exhaustion (Qoder's daily exhaustion and cooldown
+ * run on a 1-day cycle) and must surface as-is so the quota/cooldown path can
+ * see it. A 401/403 or a model-level error is never fallback-class either way.
+ */
+function qoderIdeEntitlementRefused(response: Response): boolean {
+  // Status alone is the signal; the body is left intact for
+  // `mapUpstreamHttpError` to surface if the fallback also fails.
+  return response.status === 402;
+}
+
+/**
+ * Qoder upstream streams are flaky: the IDE surface sometimes answers a full
+ * normal stop with reasoning only and no output text/tool calls (observed ~1
+ * in 4 runs with Sonus). That is not a valid completion — the lab would show a
+ * thought with "No text came back". Replay such a stream before committing to
+ * it. Buffering the body is required: the decision is only knowable after the
+ * stream ends, and the bytes are replayed to the canonical parser.
+ */
+interface QoderStreamDrain {
+  readonly bytes: Uint8Array;
+  readonly meaningful: boolean;
+  readonly thoughtOnly: boolean;
+}
+
+async function drainQoderResponse(
+  response: Response,
+  signal: AbortSignal,
+): Promise<QoderStreamDrain> {
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  const reader = response.body!.getReader();
+  try {
+    for (;;) {
+      if (signal.aborted) break;
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        chunks.push(value);
+        total += value.byteLength;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  let dataEvents = 0;
+  let meaningful = false;
+  let thoughtOnly = false;
+  const decoder = new TextDecoder();
+  const text = decoder.decode(bytes);
+  for (const frame of text.split(/\r?\n\r?\n/)) {
+    if (frame.trim().length === 0) continue;
+    const dataLines: string[] = [];
+    for (const line of frame.split(/\r?\n/)) {
+      if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+    }
+    const data = dataLines.join("\n").trim();
+    if (data.length === 0 || data === "[DONE]") continue;
+    dataEvents++;
+    for (const { data: frameData } of qoderEnvelopeToFrames(data)) {
+      if (frameData === "[DONE]") continue;
+      let json: Record<string, unknown>;
+      try {
+        json = JSON.parse(frameData) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const choices = json["choices"];
+      if (!Array.isArray(choices)) continue;
+      for (const choice of choices as Array<Record<string, unknown>>) {
+        const delta = choice["delta"] as Record<string, unknown> | undefined;
+        if (delta === undefined) continue;
+        if (typeof delta["content"] === "string" && (delta["content"] as string).length > 0) {
+          meaningful = true;
+          return { bytes, meaningful, thoughtOnly };
+        }
+        if (Array.isArray(delta["tool_calls"]) && (delta["tool_calls"] as unknown[]).length > 0) {
+          meaningful = true;
+          return { bytes, meaningful, thoughtOnly };
+        }
+        if (
+          typeof delta["reasoning_content"] === "string" &&
+          (delta["reasoning_content"] as string).length > 0
+        ) {
+          thoughtOnly = true;
+        }
+      }
+    }
+  }
+  return { bytes, meaningful, thoughtOnly };
+}
+
+/**
+ * Runs the IDE request up to `1 + maxReplays` times, returning the first
+ * response whose stream carried real output (text or tool calls). A 200 with
+ * no output (empty or thought-only) is replayed rather than surfaced.
+ */
+async function fetchQoderIdeWithEmptyRecovery(
+  requestOnce: () => Promise<Response>,
+  signal: AbortSignal,
+  maxReplays = 2,
+): Promise<Response> {
+  let last: Response | undefined;
+  for (let attempt = 0; attempt <= maxReplays; attempt += 1) {
+    const res = await requestOnce();
+    if (!res.ok || !res.body) return res;
+    const drain = await drainQoderResponse(res, signal);
+    last = new Response(drain.bytes as BodyInit, {
+      status: 200,
+      headers: { "content-type": "text/event-stream", "cache-control": "no-cache" },
+    });
+    if (drain.meaningful) return last;
+  }
+  return last!;
+}
+
+export { fetchQoderIdeWithEmptyRecovery };
+
 // Stream transformation — decode SSE, unwrap COSY envelope, map OpenAI chat chunks to CanonicalEvent
 
 function mapQoderFinishReason(raw: unknown): CanonicalStopReason | undefined {
@@ -1073,7 +1322,7 @@ export async function* qoderBodyToCanonicalEvents(
   model: string,
 ): AsyncIterable<CanonicalEvent> {
   let seq = 1;
-  yield { type: "response_start", sequence_number: seq++, model } as CanonicalEvent;
+  let started = false;
   let finishReason: unknown = undefined;
   let rawUsage: Record<string, unknown> | undefined = undefined;
   let hasTerminal = false;
@@ -1088,7 +1337,7 @@ export async function* qoderBodyToCanonicalEvents(
   let leakBuf = "";
   let leakFrames = 0;
 
-  for await (const sse of decodeSseEvents(body, { signal })) {
+  for await (const sse of decodeQoderSseEvents(body, signal)) {
     const sseData = sse.data;
     let frames: Array<{ event: string | null; data: string }>;
     try {
@@ -1101,6 +1350,10 @@ export async function* qoderBodyToCanonicalEvents(
       if (!data) continue;
       if (data === "[DONE]") {
         hasTerminal = true;
+        if (!started) {
+          yield { type: "response_start", sequence_number: seq++, model } as CanonicalEvent;
+          started = true;
+        }
         continue;
       }
       let json: Record<string, unknown>;
@@ -1109,6 +1362,18 @@ export async function* qoderBodyToCanonicalEvents(
       } catch {
         continue;
       }
+      // The upstream names the real model in each chunk. Use the first one we
+      // see for the opening event so the client sees the same model the
+      // provider actually served, not the (virtual) id that was requested.
+      if (!started && typeof json["model"] === "string") {
+        const upstreamModel = (json["model"] as string).trim();
+        yield {
+          type: "response_start",
+          sequence_number: seq++,
+          model: upstreamModel.length > 0 ? upstreamModel : model,
+        } as CanonicalEvent;
+        started = true;
+      }
       // IDE surface error event: `{"code":"invalid_model_error","message":"..."}`
       // carries no choices. Surface it as an upstream failure instead of an
       // empty successful stream.
@@ -1312,10 +1577,13 @@ export async function* qoderBodyToCanonicalEvents(
     }
   }
   // A `[DONE]` frame from the IDE surface may be the only terminal signal (the
-  // per-delta `finish_reason` is empty and `raw_usage` is not always sent), so
+  // //-delta `finish_reason` is empty and `raw_usage` is not always sent), so
   // a clean end-of-stream with no finish reason is a normal stop, not a
   // truncation. If no terminal arrived at all, still synthesize one (prevents
   // truncation error).
+  if (!started) {
+    yield { type: "response_start", sequence_number: seq++, model } as CanonicalEvent;
+  }
   if (hasTerminal && finishReason === undefined) finishReason = "stop";
   const stopReason = mapQoderFinishReason(finishReason);
   const _providerStop = typeof finishReason === "string" ? finishReason : undefined;
@@ -1330,17 +1598,13 @@ export async function* qoderBodyToCanonicalEvents(
   } as CanonicalEvent;
 }
 
-// Model catalog — maps QODER_MODEL_CONFIGS (provider) to Cartethyia ModelDefinition
+// Model catalog — maps the realm's roster to Cartethyia ModelDefinition
 
 /**
  * The intl catalog this provider publishes.
  *
- * `QODER_MODEL_CONFIGS` is not the source here: it freezes most rows at 180k
- * while the upstream reports 1M for the same keys. That number is not
- * cosmetic: it is sent upstream as `model_config.max_input_tokens`, so a stale
- * low value tells Qoder the conversation window is small and makes it behave
- * that way. Both the published catalog and the dispatched request come from the
- * realm's roster, which carries the upstream's own numbers.
+ * The published catalog and the dispatched request both come from the realm's
+ * roster, which carries the upstream's own numbers.
  */
 export const QODER_MODELS: readonly ModelDefinition[] = QODER_INTL_MODELS;
 
@@ -1356,10 +1620,20 @@ interface QoderAdapterOptions {
    * Which chat surface to dispatch on.
    *
    * `ide` (default) uses the modern model-server surface
-   * (`/model/v1/chat/completions`, plain bearer, OpenAI-shaped chunks): it
-   * streams immediately. The legacy `cosy` surface (`/algo/.../agent_chat_generation`)
-   * answers `10605 isQueued` and parks requests in a server queue, so it is a
-   * fallback, not a default.
+   * (`/model/v1/chat/completions`) — the wire the IDE/QoderWake actually
+   * speaks, echoes the real model key, and carries 1M context + xhigh
+   * reasoning. When that surface answers an entitlement refusal (HTTP 402 /
+   * `{"code":116,"error":"quota exceeded"}`, seen on free-tier accounts),
+   * dispatch falls back to the legacy COSY surface
+   * (`/algo/.../agent_chat_generation`) — but only for a free-tier model
+   * row (`is_free: true`). A billed model answering 402/116 is genuine quota
+   * exhaustion (Qoder's daily exhaustion / cooldown run on a 1-day cycle) and
+   * surfaces as-is, so the exhausted state is never masked by a fallback.
+   * Live verification (2026-11-02): the modern surface answers 116 for
+   * free-tier accounts that stream fine over COSY, while entitled accounts
+   * stream on the modern surface with the real model echoed.
+   *
+   * `cosy` forces only the legacy surface (the pre-fallback behavior).
    */
   readonly surface?: "ide" | "cosy";
 }
@@ -1448,19 +1722,37 @@ class QoderAdapter implements ProviderAdapter {
       // a CN credential to `*.qoder.sh` is refused outright. The host order
       // follows the token kind: job tokens (`jt-...`) belong on `api2`, which
       // is the only intl host that serves them (`api3` answers "Login expired").
-      const url =
-        candidate.endpoint_path && candidate.endpoint_path.startsWith("http")
-          ? candidate.endpoint_path
-          : this.surface === "ide"
-            ? qoderIdeChatUrl(this.realm)
-            : `${qoderInferenceCandidates(this.realm, auth.securityOauthToken)[0] ?? ""}${QODER_CHAT_PATH}`;
-
-      // The modern IDE surface streams immediately and needs no COSY signing;
-      // the legacy COSY surface is kept as an explicit fallback.
-      const response =
+
+      // The modern `ide` surface streams immediately, needs no COSY signing,
+      // and echoes the real model key — it is the default. Fall back to the
+      // legacy COSY surface only when BOTH hold: the modern surface refused on
+      // entitlement grounds (HTTP 402 / code 116) AND the dispatched model is a
+      // free-tier row (`is_free: true`). For a free-tier model this is the
+      // entitlement refusal the legacy surface serves with the same credential;
+      // for a billed model the same code is genuine quota exhaustion (Qoder's
+      // daily exhaustion / cooldown run on a 1-day cycle), so it must surface
+      // as-is — falling back would hide the exhausted state and starve the
+      // quota/cooldown signal. A 401/403/model error never triggers fallback.
+      const ideUrl = candidate.endpoint_path?.startsWith("http") ? candidate.endpoint_path : qoderIdeChatUrl(this.realm);
+      const cosyUrl = candidate.endpoint_path?.startsWith("http")
+        ? candidate.endpoint_path
+        : `${qoderInferenceCandidates(this.realm, auth.securityOauthToken)[0] ?? ""}${QODER_CHAT_PATH}`;
+      const ideRequest = () =>
+        callQoderIde(ideUrl, buildQoderIdeRequest(modelId, request, modelConfig, auth, this.realm, version), auth, lifecycle.signal, fetcher, version);
+      const cosyRequest = () =>
+        callQoder(cosyUrl, buildQoderRequest(modelId, request, modelConfig, auth, this.realm), modelId, auth, lifecycle.signal, fetcher, version);
+      let response =
         this.surface === "ide"
-          ? await callQoderIde(url, buildQoderIdeRequest(modelId, request, modelConfig, auth, this.realm, version), auth, lifecycle.signal, fetcher, version)
-          : await callQoder(url, buildQoderRequest(modelId, request, modelConfig, auth, this.realm), modelId, auth, lifecycle.signal, fetcher, version);
+          ? await fetchQoderIdeWithEmptyRecovery(ideRequest, lifecycle.signal)
+          : await cosyRequest();
+      if (
+        !response.ok &&
+        this.surface === "ide" &&
+        qoderIdeEntitlementRefused(response) &&
+        modelConfig.is_free === true
+      ) {
+        response = await cosyRequest();
+      }
       if (!response.ok) throw await mapUpstreamHttpError(response, "qoder");
       if (!response.body) throw new GatewayError("platform_unavailable", 502, "Qoder returned empty body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       // Headers arrived: the pre-stream deadline has served its purpose.

package/src/providers/integrations/shared/connect.ts

@@ -5,24 +5,6 @@
 // end-of-stream trailer. Compression and trailer semantics stay at the call
 // sites; this module owns only the envelope arithmetic.
 
-/** Payload is gzip-compressed. */
-export const CONNECT_COMPRESSED_FLAG = 0x01;
-/** Frame carries the end-of-stream trailer rather than a message. */
-export const CONNECT_END_STREAM_FLAG = 0x02;
-
-/** One decoded Connect envelope. */
-interface ConnectFrame {
-  readonly flags: number;
-  readonly payload: Uint8Array;
-}
-
-interface ConsumeConnectFramesOptions {
-  /** Reject frames whose declared payload exceeds this many bytes. */
-  readonly maxPayloadBytes?: number;
-  /** Builds the error thrown for an oversized frame; defaults to a plain `Error`. */
-  readonly oversizeError?: (declaredLength: number) => Error;
-}
-
 /** Initial allocation for a frame buffer that has not received a chunk yet. */
 const FRAME_BUFFER_MIN_BYTES = 4096;
 /** Ceiling on the spare capacity kept above the live length when growing. */
@@ -84,39 +66,3 @@ export class FrameBuffer {
     this.start = 0;
   }
 }
-
-/** Wraps `payload` in a 5-byte Connect envelope. */
-export function frameConnectMessage(payload: Uint8Array, flags = 0) {
-  const frame = Buffer.alloc(5 + payload.length);
-  frame.writeUInt8(flags, 0);
-  frame.writeUInt32BE(payload.length, 1);
-  frame.set(payload, 5);
-  return frame;
-}
-
-/**
- * Splits every complete Connect frame out of `buffer`, in order. Returns the
- * trailing bytes that do not yet form a complete frame so a streaming caller
- * can prepend them to the next chunk and call again.
- */
-export function consumeConnectFrames(
-  buffer: Buffer,
-  options: ConsumeConnectFramesOptions = {},
-): { frames: ConnectFrame[]; rest: Buffer } {
-  const frames: ConnectFrame[] = [];
-  let pending = buffer;
-  while (pending.length >= 5) {
-    const flags = pending[0] ?? 0;
-    const length = pending.readUInt32BE(1);
-    if (options.maxPayloadBytes !== undefined && length > options.maxPayloadBytes) {
-      throw (
-        options.oversizeError?.(length) ??
-        new Error(`Connect frame length ${length} exceeds cap`)
-      );
-    }
-    if (pending.length < 5 + length) break;
-    frames.push({ flags, payload: pending.subarray(5, 5 + length) });
-    pending = pending.subarray(5 + length);
-  }
-  return { frames, rest: pending };
-}