@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,679 lines • 75.9 kB
text/typescript
/*
* Derived from rsvedant/opencode-windsurf-auth (src/cloud-direct/), MIT licensed,
* Copyright (c) 2026 Vedant. The full notice is in ./index.ts.
*/
/**
* Cloud-direct streaming chat. Talks to
* `server.codeium.com/exa.api_server_pb.ApiServerService/GetChatMessage`
* with no local language_server in the path. Returns an async iterable of
* CloudChatEvent deltas (text, reasoning, tool calls, usage, finish) so the
* caller can stream straight into opencodex's internal AdapterEvent model.
*
* What this supports:
* - Single- or multi-turn chat using the prompt-and-history pattern the LS
* uses (flatten history into one ChatMessagePrompt list)
* - All free Windsurf/Cognition models (swe-1-7, swe-1-7-lightning, etc.)
* and any model the user's api_key is entitled to
* - Streaming (uses Connect-streaming envelope, emits deltas as they arrive)
* - Tool definitions (encoded via `encodeToolDef`) and tool-call events
* (tool_call_start, tool_call_args) decoded from the response stream
* - Usage and finish-reason events for terminal completion
*
* Wire-protocol: Connect-RPC streaming over HTTPS with manual protobuf
* encoding (see `wire.ts`).
*/
import * as crypto from 'crypto';
import * as zlib from 'zlib';
import {
encodeMessage,
encodeString,
encodeVarintField,
frameConnectStream,
iterFields,
parseConnectFrames,
} from './wire.js';
import { buildMetadata } from './metadata.js';
import { getCachedUserJwt } from './auth.js';
import { getCachedCatalog, ModelNotAvailableError, type CacheEntry } from './catalog.js';
import { anySignal, cancelBodyOnAbort } from '../../../lib/abort.js';
import { parseRetryAfterFromMessage } from '../../../lib/retry-delay.js';
import { resolveDevinApiBaseUrl } from '../../../oauth/devin/api-base.js';
import { normalizeDevinToolParameters } from './tool-schema.js';
/**
* Connect-RPC streaming inactivity timeout. If the cloud sends zero bytes
* for this long after the last chunk, we abort the fetch. The cloud's own
* idle limit is around 90s on most models; we set ours a little above so
* we only trigger when the server has genuinely stopped responding.
*/
const CLOUD_STREAM_IDLE_MS = 120_000;
/**
* Budget for the response HEADERS, which is not the same thing as a connect
* timeout. Cognition holds the headers until the model produces its first
* token, so on a high-effort reasoning model this bounds generation. A 60s
* value killed live swe-2 high turns at exactly 60000ms with no output while
* a sibling call on the same account was still alive at 76s, which is the
* defect this constant exists to record.
*
* It has to be at least as generous as the body idle budget above. The cost of
* the larger value is bounded and understood: a peer that goes silent at the
* TCP level without sending RST/FIN now hangs for this long instead of 60s. A
* peer that actually dies still rejects immediately. This timer is the only
* bound on that case once `timeout: 0` is set on the fetch, so it must not be
* removed. Override with OPENCODEX_DEVIN_TTFB_MS.
*/
const CLOUD_STREAM_HEADERS_DEFAULT_MS = 300_000;
/** Upper bound for the override, so a stray value cannot wedge a turn forever. */
const CLOUD_STREAM_HEADERS_MAX_MS = 1_800_000;
function cloudStreamHeadersMs(): number {
const raw = process.env.OPENCODEX_DEVIN_TTFB_MS?.trim();
if (!raw) return CLOUD_STREAM_HEADERS_DEFAULT_MS;
const parsed = Number(raw);
if (!Number.isFinite(parsed) || parsed <= 0) return CLOUD_STREAM_HEADERS_DEFAULT_MS;
return Math.min(parsed, CLOUD_STREAM_HEADERS_MAX_MS);
}
/** Test seam for the headers budget; the resolver itself stays private. */
export const cloudStreamHeadersMsForTests = cloudStreamHeadersMs;
/** Maximum acceptable Connect-RPC frame length (16 MB). */
const MAX_FRAME_LEN = 16 * 1024 * 1024;
/** Bound the wire field before allocating its decoded UTF-8 string. */
const MAX_SIGNATURE_TYPE_BYTES = 4 * 1024;
/**
* PromptCacheOptions.type = EPHEMERAL. Marks the system prefix as a cache entry
* the server may reuse on the next turn of the same session.
*/
const PROMPT_CACHE_EPHEMERAL = 1;
/**
* Per-identity session/cascade ID cache. Cloud uses these for server-side
* context caching across turns of the same conversation; if we mint a fresh
* sessionId on every call (which we used to), every turn looks like a
* brand-new session and the prompt-cache hit ratio is zero.
* Single-process scope is enough: opencode lives in one runtime for a TUI
* session, and CLI one-shots don't benefit from caching anyway.
*/
interface SessionIds {
sessionId: string;
cascadeId: string;
}
/**
* Cache key for one Devin credential on one host.
*
* The credential itself used to be the Map key. Hashing it keeps the raw token
* out of any structure a heap dump or debugger would walk, and gives the other
* per-account caches a name they can share. 16 hex is 64 bits, which against a
* bounded single-process map is not a collision risk worth widening the key for.
*/
export function devinCacheIdentity(apiKey: string, host: string): string {
return crypto.createHash('sha256').update(`${host}\x1f${apiKey}`).digest('hex').slice(0, 16);
}
/**
* Bounded the same way the adapter bounds its cascade-id map: a long-running
* proxy sees one entry per (host, api_key) pair, and nothing ever evicted them.
*/
const SESSION_CACHE_MAX = 256;
const sessionCache = new Map<string, SessionIds>();
function getOrAllocateSessionIds(apiKey: string, host: string, cascadeIdOverride?: string): SessionIds {
const key = devinCacheIdentity(apiKey, host);
let ids = sessionCache.get(key);
if (!ids) {
ids = {
sessionId: crypto.randomUUID(),
cascadeId: cascadeIdOverride ?? allocateCascadeId(),
};
if (sessionCache.size >= SESSION_CACHE_MAX) {
const oldest = sessionCache.keys().next().value;
if (oldest !== undefined) sessionCache.delete(oldest);
}
sessionCache.set(key, ids);
} else if (cascadeIdOverride && ids.cascadeId !== cascadeIdOverride) {
// Caller explicitly requested a different cascadeId — honor it.
ids = { sessionId: ids.sessionId, cascadeId: cascadeIdOverride };
sessionCache.set(key, ids);
}
return ids;
}
/**
* Drop the cached session for ONE identity, after that account signs out or is
* switched away from.
*
* This replaces a global clear(). The proxy serves several accounts from one
* process, so clearing every entry on a per-provider logout would strip the
* session and cascade of accounts that were mid-turn. That is why the global
* version was never safe to call, and why nothing ever called it.
*
* A turn already in flight is unaffected: it received its SessionIds object at
* request start and never re-reads the map, so it finishes on the session it
* began with and the next turn allocates fresh.
*/
export function invalidateSessionIdentity(identity: string): void {
sessionCache.delete(identity);
}
// ----------------------------------------------------------------------------
// Per-conversation cascade state — generated client-side; cloud lazy-registers
// ----------------------------------------------------------------------------
/**
* Allocate a fresh cascade UUID. The cloud lazy-registers cascade_id on first
* use — confirmed empirically (random UUID accepted, model responded). One
* cascade_id per opencode-CLI conversation is fine; reuse across turns to
* preserve server-side context.
*/
export function allocateCascadeId(): string {
return crypto.randomUUID();
}
// ----------------------------------------------------------------------------
// Request encoders
// ----------------------------------------------------------------------------
/**
* ChatMessagePrompt {
* #2 source: enum CHAT_MESSAGE_SOURCE_USER=1 / ASSISTANT=2 / SYSTEM=3 / TOOL=4
* #3 prompt: string (text content)
* #4 num_tokens: int (rough estimate)
* #5 safe_for_code_telemetry: bool (1 = ok to log)
* #9 tool_result_is_error: bool (tool prompts only)
* #10 images: repeated ImageData (multimodal)
* #11 thinking: string (assistant reasoning, replayed)
* #12 signature: string (opaque attestation for #11)
* #18 signature_type: string
* }
*
* ImageData (exa.codeium_common_pb.ImageData) {
* #1 base64_data: string
* #2 mime_type: string
* #3 caption: string (optional)
* }
*/
function encodeImageData(img: { mimeType: string; base64Data: string; caption?: string }): Buffer {
const parts: Buffer[] = [
encodeString(1, img.base64Data),
encodeString(2, img.mimeType),
];
if (img.caption) parts.push(encodeString(3, img.caption));
return Buffer.concat(parts);
}
/**
* Encode one ChatToolCall sub-message:
* {#1 id, #2 name, #3 arguments_json}
* Verified against `exa.codeium_common_pb.ChatToolCall` from extension.js.
*/
function encodeChatToolCall(tc: { id: string; name: string; arguments: string }): Buffer {
return Buffer.concat([
encodeString(1, tc.id),
encodeString(2, tc.name),
encodeString(3, tc.arguments),
]);
}
function encodeChatMessagePrompt(
content: ContentPart[],
source: number,
opts?: {
toolCallId?: string;
toolCalls?: Array<{ id: string; name: string; arguments: string }>;
thinking?: string;
signature?: string;
signatureType?: string;
isError?: boolean;
},
): Buffer {
const textParts = content.filter((p): p is { type: 'text'; text: string } => p.type === 'text');
const imageParts = content.filter((p): p is { type: 'image'; mimeType: string; base64Data: string; caption?: string } => p.type === 'image');
const joined = textParts.map((p) => p.text).join('\n');
const parts: Buffer[] = [
// #1 message_id. The verified turn-1 capture stamps one on every prompt.
encodeString(1, crypto.randomUUID()),
encodeVarintField(2, source),
encodeString(3, joined),
];
// Tool-result message: attach the id of the call this result answers.
// Without it, the model can't pair multi-tool conversations.
if (opts?.toolCallId) {
parts.push(encodeString(7, opts.toolCallId));
}
// Accepted live on a tool prompt. Only some models act on it, so the adapter
// also keeps an in-band marker in the text.
if (opts?.isError) parts.push(encodeVarintField(9, 1));
// Assistant message with tool_calls: encode each as a ChatToolCall.
if (opts?.toolCalls && opts.toolCalls.length > 0) {
for (const tc of opts.toolCalls) {
parts.push(encodeMessage(6, encodeChatToolCall(tc)));
}
}
for (const img of imageParts) {
parts.push(encodeMessage(10, encodeImageData(img)));
}
// Reasoning replay. This adapter used to assert that Cognition has no
// reasoning-replay field and drop the assistant's own thinking, so a
// reasoning model restarted its chain on every turn of a tool loop. Two
// independent clients of the same service write it here: #11 thinking,
// #12 signature, #18 signature_type on the assistant prompt.
if (opts?.thinking) parts.push(encodeString(11, opts.thinking));
if (opts?.signature) parts.push(encodeString(12, opts.signature));
if (opts?.signatureType) parts.push(encodeString(18, opts.signatureType));
return Buffer.concat(parts);
}
const SOURCE_BY_ROLE: Record<string, number> = {
user: 1,
assistant: 2,
// Never sent as a prompt source: the leading system text goes in request #2,
// and a later system message is collapsed into the next user turn below.
system: 1,
tool: 4,
};
/**
* Collapse `role:'system'` entries that follow the conversation start into the
* immediately-following user message. The leading run of system messages never
* reaches here; it is the request's #2 system prompt. With S0 already sent as #2:
*
* [{user: "U1"}, {assistant: "A1"}, {system: "S1"}, {system: "S2"}, {user: "U2"}]
*
* becomes
*
* [{user: "U1"}, {assistant: "A1"}, {user: "<system>\nS1\n\nS2\n</system>\nU2"}]
*
* If there's no following user message, the trailing system messages get
* appended as a synthesized user turn. A request made only of system messages
* keeps no #2 and comes through here whole, so its prompt list is never empty.
*/
function collapseSystemIntoUser(messages: ChatHistoryItem[]): ChatHistoryItem[] {
const out: ChatHistoryItem[] = [];
let pendingSystem: string[] = [];
const flushTextOf = (content: ContentPart[]): string =>
content.filter((p): p is { type: 'text'; text: string } => p.type === 'text')
.map((p) => p.text).join('\n');
for (const m of messages) {
if (m.role === 'system') {
const parts = normalizeContent(m.content);
const text = flushTextOf(parts);
if (text) pendingSystem.push(text);
} else if (m.role === 'user' && pendingSystem.length > 0) {
const userParts = normalizeContent(m.content);
const userText = flushTextOf(userParts);
const userImages = userParts.filter((p) => p.type === 'image');
const wrapped = `<system>\n${pendingSystem.join('\n\n')}\n</system>\n${userText}`;
const newContent: ContentPart[] = [{ type: 'text', text: wrapped }, ...userImages];
out.push({ role: 'user', content: newContent });
pendingSystem = [];
} else {
// Flush accumulated system text before any non-system, non-user turn
// (assistant / tool) so system instructions keep their leading position
// instead of being deferred to a trailing synthesized user message.
if (pendingSystem.length > 0) {
out.push({
role: 'user',
content: [{ type: 'text', text: `<system>\n${pendingSystem.join('\n\n')}\n</system>` }],
});
pendingSystem = [];
}
out.push(m);
}
}
if (pendingSystem.length > 0) {
// Trailing system messages with no following user turn — convert to a
// standalone user message so they still reach the model.
out.push({
role: 'user',
content: [{ type: 'text', text: `<system>\n${pendingSystem.join('\n\n')}\n</system>` }],
});
}
return out;
}
/**
* CompletionConfiguration — mirrors the LS-shipped defaults, lets the caller
* override the obvious knobs.
*/
/** Output cap when neither the caller nor the catalog named one. */
const DEFAULT_MAX_OUTPUT_TOKENS = 8192;
/**
* CompletionConfiguration #3 is `max_newlines`, not a token count and not an
* input ceiling: live, a value of 5 did not truncate a 25-line answer. It is
* still sent, at the value every turn has carried, so the request shape the
* service accepts does not change.
*/
const MAX_NEWLINES = 128_000;
/**
* Cognition rejects a temperature of exactly 0 with the same opaque internal
* error it uses for a malformed request, so a client asking for deterministic
* output would fail every turn. Clamp to the smallest value the wire accepts
* rather than silently substituting the service default, which would be a
* different answer than the caller asked for.
*/
const MIN_TEMPERATURE = 0.0001;
function safeTemperature(value: number | undefined): number {
if (value === undefined) return 0.7;
return value <= 0 ? MIN_TEMPERATURE : value;
}
function encodeCompletionConfiguration(opts: {
maxOutputTokens?: number;
temperature?: number;
topK?: number;
topP?: number;
}): Buffer {
const enc64 = (fieldNum: number, n: number): Buffer => {
const b = Buffer.alloc(8);
b.writeDoubleLE(n, 0);
return Buffer.concat([Buffer.from([(fieldNum << 3) | 1]), b]);
};
// Tag map, verified by building the same turn with a working client and
// diffing the encoded messages field by field: #2 is the OUTPUT cap and #3 is
// max_newlines. This layout once had those two swapped, so a caller's output
// cap landed in #3 and a large value in #2, and the request came back as an
// opaque "an internal error occurred" — for every turn, on every account,
// which is why free and paid failed identically. #6 and #11 are not part of
// the message the service accepts.
return Buffer.concat([
encodeVarintField(1, 1),
encodeVarintField(2, opts.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS),
encodeVarintField(3, MAX_NEWLINES),
enc64(5, safeTemperature(opts.temperature)),
encodeVarintField(7, opts.topK ?? 40),
enc64(8, opts.topP ?? 1.0),
]);
}
/**
* Multimodal content part — text or image.
*
* Text: `{ type: 'text', text: '...' }`
* Image: `{ type: 'image', mimeType: 'image/png', base64Data: '...' [, caption: '...'] }`
*
* Matches the OpenAI/@ai-sdk multimodal message shape — we accept their
* `image_url: { url: 'data:image/png;base64,...' }` form via {@link parseContent}.
*/
export type ContentPart =
| { type: 'text'; text: string }
| { type: 'image'; mimeType: string; base64Data: string; caption?: string };
export interface ChatHistoryItem {
role: 'user' | 'assistant' | 'system' | 'tool';
/**
* Either a plain string or an array of {@link ContentPart}. Plain strings are
* shorthand for `[{ type: 'text', text: '...' }]`.
*/
content: string | ContentPart[];
/**
* For `role: 'tool'` only — the id of the assistant's preceding tool_call
* this message answers. Required by the cloud's chat backend to pair
* tool results with calls; without it, multi-tool conversations can't
* tell the model which call produced which result. Encoded as
* ChatMessagePrompt field #7 (verified against the Windsurf bundled
* extension.js proto schema `exa.chat_pb.ChatMessagePrompt`).
*/
tool_call_id?: string;
/**
* For `role: 'assistant'` only — the tool calls the assistant emitted.
* Encoded as ChatMessagePrompt field #6 (repeated ChatToolCall, where
* each ChatToolCall has #1 id, #2 name, #3 arguments_json).
*/
tool_calls?: Array<{ id: string; name: string; arguments: string }>;
/**
* For `role: 'assistant'` only — the model's own reasoning from that turn,
* replayed so a reasoning model does not restart its chain on the next one.
* Encoded as ChatMessagePrompt #11 with its #12 signature and #18
* signature_type.
*/
thinking?: string;
signature?: string;
signature_type?: string;
/** For `role: 'tool'` only — the tool failed. Encoded as ChatMessagePrompt #9. */
is_error?: boolean;
}
/**
* Normalize ChatHistoryItem content into structured parts. Accepts strings,
* OpenAI multimodal `[{type:'text',text}, {type:'image_url',image_url}]`, and
* our own `[{type:'image', mimeType, base64Data}]`.
*/
function normalizeContent(content: string | ContentPart[] | unknown): ContentPart[] {
if (typeof content === 'string') return [{ type: 'text', text: content }];
if (!Array.isArray(content)) return [];
const out: ContentPart[] = [];
// Each element may follow our own ContentPart shape, the OpenAI multimodal
// `image_url` shape, or be malformed — narrow defensively per branch.
const parts = content as Array<Record<string, unknown>>;
for (const p of parts) {
if (!p || typeof p !== 'object') continue;
if (p.type === 'text' && typeof p.text === 'string') {
out.push({ type: 'text', text: p.text });
} else if (p.type === 'image' && typeof p.base64Data === 'string') {
const mimeType = typeof p.mimeType === 'string' ? p.mimeType : 'image/png';
const caption = typeof p.caption === 'string' ? p.caption : undefined;
out.push({ type: 'image', mimeType, base64Data: p.base64Data, caption });
} else if (p.type === 'image_url' && p.image_url) {
// OpenAI/@ai-sdk shape — parse data: URL into base64 + mime.
const imgRef = p.image_url as string | { url?: string };
const url: string = typeof imgRef === 'string' ? imgRef : (imgRef.url ?? '');
const m = url.match(/^data:([^;]+);base64,(.+)$/);
if (m) out.push({ type: 'image', mimeType: m[1], base64Data: m[2] });
else if (url) out.push({ type: 'text', text: `[image url: ${url}]` });
}
}
return out;
}
export interface ToolDef {
/** Function name. */
name: string;
/** Plain-English description. */
description: string;
/** JSON Schema for the function's arguments. */
parameters: unknown;
}
/**
* Streaming event emitted by the cloud-direct chat loop.
*
* - `text` : incremental visible content from the assistant
* - `reasoning` : incremental internal thinking (Anthropic-style, kept
* separate from visible content; @ai-sdk consumers can
* render in a collapsed/grey region)
* - `tool_call_*` : function-calling deltas (id+name once, args streamed)
* - `finish` : stream terminated cleanly with a reason
* - `usage` : final token-accounting block (input/output/total counts)
*/
export type CloudChatEvent =
| { kind: 'text'; text: string }
| { kind: 'reasoning'; text: string }
/**
* `delta_signature` (#10) — the opaque attestation for the reasoning this
* turn produced. Without decoding it there is nothing to put in the prompt's
* #12 on the next turn, so the replay would always be unsigned.
*/
| { kind: 'reasoning_signature'; signature: string; signatureType?: string }
| { kind: 'tool_call_start'; id: string; name: string }
| {
kind: 'tool_call_args';
argsDelta: string;
/**
* Tool-call id this delta belongs to, when the cloud surfaced one in
* this frame. Cognition's wire format only carries id on the START
* frame today, so most argsDelta events arrive without one — callers
* route those to the most-recent-start by convention. If Cognition
* ever interleaves args across calls, the consumer should prefer
* `id` over the rolling lastToolCallId.
*/
id?: string;
}
// Note: there is no `tool_call_end` event. Cognition's wire format
// signals the end of a tool call implicitly — args just stop arriving
// for the current id and either a new `tool_call_start` fires or the
// stream finishes. Consumers should treat each `tool_call_start` as
// ending the previous call.
| { kind: 'finish'; reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' }
| {
kind: 'usage';
promptTokens?: number;
completionTokens?: number;
totalTokens?: number;
/**
* Tokens served from the cache. Surfaced separately so callers tracking
* cost can distinguish them from fresh input tokens (Anthropic / OpenAI
* both bill cache reads cheaper than fresh prompts).
*/
cachedInputTokens?: number;
/** Tokens written to the cache on this request (Anthropic-style). */
cacheCreationInputTokens?: number;
/** Reasoning tokens (gpt-5-x reasoning models, Claude thinking variants). */
reasoningTokens?: number;
};
interface BuildArgs {
apiKey: string;
userJwt?: string;
modelUid: string;
messages: ChatHistoryItem[];
cascadeId: string;
/**
* GetChatMessageRequest #17 prompt_id. Optional because it is omitted on a
* first turn; the working client only reuses one across a later tool loop.
*/
promptId?: string;
sessionId: string;
requestId: bigint;
triggerId: string;
tools?: ToolDef[];
/** Default 5 = CHAT_MESSAGE_REQUEST_TYPE_CASCADE (matches captured LS body). */
requestType?: number;
completionOpts?: {
maxOutputTokens?: number;
temperature?: number;
topK?: number;
topP?: number;
};
}
/**
* ChatToolDefinition proto, observed in the LS upstream traffic:
* { #1 name (string), #2 description (string), #3 parameters_schema (JSON string) }
*
* Truncation note: Codeium's tool validator rejects very long descriptions
* with a generic `failed_precondition: "Unable to process request due to an
* MCP configuration issue."` error. opencode ships some tools (notably `bash`)
* with ~9.6 KB descriptions packed with examples and rules. We truncate to a
* conservative `MAX_DESC_LEN` and append an ellipsis so the cloud accepts
* them. The model still gets the first chunk of the description (where the
* essential signature lives); detailed examples are sacrificed for
* compatibility.
*/
/**
* The Codeium tool validator rejects any tool whose description hits exactly
* 7,000 chars (or more) with a misleading `failed_precondition: "Unable to
* process request due to an MCP configuration issue."` error. Binary-search
* verified to char-precision:
* - 6,999 chars → server accepts
* - 7,000 chars → server returns MCP error
*
* The limit is per-description, content-sensitive (plain `a`-repeats up to
* 20K work fine; the bash description's exact byte at position 6999 trips
* it). We truncate to the maximum-1 (6,998) for a one-char safety margin.
*
* We do NOT need to aggregate-cap — 200K total tool descriptions across 200
* tools was confirmed to pass server-side. Only per-string length is gated.
*/
const MAX_TOOL_DESC_LEN = 6998;
/**
* Cognition's cloud enforces a case-sensitive, whitespace-exact exact-phrase
* blocklist on tool descriptions. Binary-search isolated the trigger to the
* 7-word phrase "Takes a task_id parameter identifying the task" — verbatim,
* capital T, single spaces — which causes a `permission_denied` trailer error
* regardless of model or account tier. Any deviation (lowercase, reword,
* reorder, extra whitespace) passes. The phrase appears verbatim in Claude
* Code's built-in TaskOutput tool description.
*
* Rewrite known triggers to meaning-preserving forms. This is a
* Cognition-specific constraint alongside the length limit above; if
* Cognition adds more blocklisted phrases, extend this table and add a
* regression test in tests/devin-adapter.test.ts.
*
* Not every entry is matched the same way. The Claude Code phrase above is
* case-sensitive and whitespace-exact, but the two Codex entries below are
* not: against a live account, lowercasing the first word and doubling an
* interior space both still produced `permission_denied`, while changing any
* single word passed. So those two match case-insensitively with flexible
* whitespace and an optional comma, and the rewrite swaps only the leading
* verb — the smallest edit measured to clear the filter.
*
* These two sentences are Codex's own built-in `exec_command` and
* `write_stdin` descriptions, verbatim. Every Codex turn carries them, so
* before this table knew about them the cloud refused literally every request
* from a Codex client — a bare "hi" included — while the same account
* answered a hand-built request with an ordinary shell tool. The visible
* symptom was the adapter's own blocklist message pointing back at this
* table, which is why they are named here rather than left to the next person
* to re-bisect.
*
* The fourth entry is not a tool description at all: it is a sentence from
* Codex's `<permissions instructions>` escalation boilerplate, which Codex
* injects into the system prompt. Binary-search against a live account
* isolated the trigger to the clause "asking the user if they want to allow
* the action in `justification` parameter" — the whole bullet was required
* (every sub-phrase passed alone), matching flexibly on whitespace and case
* like the other Codex entries. The rewrite swaps "if they want to allow"
* for "whether to allow", verified live to clear the filter while preserving
* the instruction's meaning.
*
* Scope note: the sanitizer only ever touches *instruction surfaces* —
* tool descriptions and the #2 system prompt, where a meaning-preserving
* reword loses nothing. It deliberately does NOT touch data fields:
* message text (#3), replayed thinking (#11), and tool-call arguments
* (#6.3) carry literal content (patches, exact needles, quoted file bytes)
* where a rewrite would silently change what the model did or sees. If a
* blocklisted phrase reaches the cloud inside one of those, the request is
* refused and the caller sees the upstream `permission_denied` — which is
* the correct failure, better than corrupting the data.
*/
const COGNITION_BLOCKLIST_REWRITES: ReadonlyArray<[RegExp, string]> = [
[/\bTakes a task_id parameter identifying the task\b/g, "Accepts a task_id parameter identifying the task"],
[
/\bRuns\s+a\s+command\s+in\s+a\s+PTY,?\s+returning\s+output\s+or\s+a\s+session\s+ID\s+for\s+ongoing\s+interaction\b/gi,
"Executes a command in a PTY, returning output or a session ID for ongoing interaction",
],
[
/\bWrites\s+characters\s+to\s+an\s+existing\s+unified\s+exec\s+session\s+and\s+returns\s+recent\s+output\b/gi,
"Sends characters to an existing unified exec session and returns recent output",
],
[
/\basking\s+the\s+user\s+if\s+they\s+want\s+to\s+allow\s+the\s+action\s+in\s+`?justification`?\s+parameter\b/gi,
"asking the user whether to allow the action in the `justification` parameter",
],
];
function sanitizeTextForCognition(text: string): string {
let out = text;
for (const [pattern, replacement] of COGNITION_BLOCKLIST_REWRITES) {
out = out.replace(pattern, replacement);
}
return out;
}
/** Test-only: exercise the Cognition blocklist rewrite directly. */
export function sanitizeToolDescriptionForCognitionForTests(description: string): string {
return sanitizeTextForCognition(description);
}
/** Test-only: exercise the sanitizer used for system text and tool descriptions. */
export function sanitizeTextForCognitionForTests(text: string): string {
return sanitizeTextForCognition(text);
}
/** Description as transmitted on the Cognition wire, also used by overflow estimation. */
export function prepareToolDescriptionForCognition(description: string): string {
const rawDesc = sanitizeTextForCognition(description);
return rawDesc.length > MAX_TOOL_DESC_LEN
? rawDesc.slice(0, MAX_TOOL_DESC_LEN - 24) + '\n…(truncated for cloud)'
: rawDesc;
}
function encodeToolDef(tool: ToolDef, modelUid: string): Buffer {
const desc = prepareToolDescriptionForCognition(tool.description ?? '');
return Buffer.concat([
encodeString(1, tool.name),
encodeString(2, desc),
encodeString(3, JSON.stringify(normalizeDevinToolParameters(modelUid, tool.parameters ?? {}))),
]);
}
export function buildGetChatMessageRequestForTests(args: BuildArgs): Buffer {
return buildGetChatMessageRequest(args);
}
function buildGetChatMessageRequest(args: BuildArgs): Buffer {
const metadata = buildMetadata({
apiKey: args.apiKey,
userJwt: args.userJwt,
sessionId: args.sessionId,
requestId: args.requestId,
triggerId: args.triggerId,
// GetChatMessage accepts only the calibrated identity shape.
cloudChatShape: true,
});
// The leading system messages become request #2. Measured live on swe-1-6
// with a ~6.7k-token system prompt: turn 2 read 6688 of 6715 prompt tokens
// from cache in #2, against 7072 of 7097 when the same text was collapsed
// into the first user prompt, so the cache ratio is unchanged and the prompt
// is smaller. The model obeyed an instruction given only in #2.
// A request with only system text keeps it as a user prompt: #2 alone would
// leave the request with no prompt at all.
const firstNonSystem = args.messages.findIndex((m) => m.role !== 'system');
const leadingSystem = firstNonSystem === -1 ? [] : args.messages.slice(0, firstNonSystem);
const systemPrompt = leadingSystem
.map((m) => normalizeContent(m.content)
.filter((p): p is { type: 'text'; text: string } => p.type === 'text')
.map((p) => p.text).join('\n'))
.filter(Boolean)
.join('\n\n');
const sanitizedSystemPrompt = sanitizeTextForCognition(systemPrompt);
const collapsed = collapseSystemIntoUser(args.messages.slice(leadingSystem.length));
const promptParts = collapsed.map((m) =>
encodeMessage(
3,
encodeChatMessagePrompt(
normalizeContent(m.content),
SOURCE_BY_ROLE[m.role] ?? 1,
// Thread tool_call_id (for tool results) + tool_calls (for assistant
// turns that fired tools) into the proto. Cloud rejects multi-tool
// conversations otherwise — it can't pair a tool result with the
// assistant call that produced it.
{
toolCallId: m.role === 'tool' ? m.tool_call_id : undefined,
toolCalls: m.role === 'assistant' ? m.tool_calls : undefined,
thinking: m.role === 'assistant' ? m.thinking : undefined,
signature: m.role === 'assistant' ? m.signature : undefined,
signatureType: m.role === 'assistant' ? m.signature_type : undefined,
isError: m.role === 'tool' ? m.is_error : undefined,
},
),
),
);
const completion = encodeCompletionConfiguration(args.completionOpts ?? {});
const toolParts: Buffer[] = (args.tools ?? []).map((t) =>
encodeMessage(10, encodeToolDef(t, args.modelUid)),
);
// Field layout from mitm capture of the LS:
// #1 metadata
// #3 chat_message_prompts (repeated — one element per history turn)
// #7 request_type (varint enum)
// #8 completion_configuration
// #10 tools (repeated ChatToolDefinition)
// #13 prompt_cache_options
// #15 CortexTrajectoryReference
// #16 cascade_id (string)
// #17 prompt_id (string)
// #21 chat_model_uid (string)
// #22 execution_id (string)
return Buffer.concat([
encodeMessage(1, metadata),
// #2 system_prompt is always written, empty when the caller had none.
encodeString(2, sanitizedSystemPrompt),
...promptParts,
encodeVarintField(7, args.requestType ?? 5),
encodeMessage(8, completion),
...toolParts,
// #13 prompt_cache_options: { type: EPHEMERAL }. Reusing a session id is only
// half of prompt caching — without this the server creates no cache entry and
// every turn re-reads the whole prefix, which is why the sessionId reuse above
// was not producing the hit ratio its comment claims. The native client sends
// it and records real savings; sending it unconditionally matches both the
// native client and CLIProxyAPIPlus, which places it outside its tools gate.
encodeMessage(13, encodeVarintField(1, PROMPT_CACHE_EPHEMERAL)),
// #15 CortexTrajectoryReference: { id, 1, 4 }. Present on every verified
// request.
encodeMessage(15, Buffer.concat([
encodeString(1, crypto.randomUUID()),
encodeVarintField(2, 1),
encodeVarintField(3, 4),
])),
encodeString(16, args.cascadeId),
encodeVarintField(20, 1),
encodeString(21, args.modelUid),
// #17 prompt_id is deliberately omitted. It is a user-exchange id that only
// appears from the second turn onward and is reused across that turn's tool
// loop; a fresh per-request uuid matches neither shape.
]);
}
// ----------------------------------------------------------------------------
// Response parsing — pull `delta_text` (top-level field #9) out of each frame
// ----------------------------------------------------------------------------
/**
* Decode a single streaming ChatMessage proto frame into one or more
* CloudChatEvents. Captured shape (from a tool-using swe-1.6 chat):
*
* ChatMessage {
* #1 bot_id (string)
* #2 timestamp { seconds, nanos }
* #5 finish_reason (varint — 10 = "tool_calls" observed, others unknown)
* #6 ToolCallDelta {
* #1 id (string, only on first tool-call frame)
* #2 name (string, only on first tool-call frame)
* #3 arguments_delta (string, JSON fragment, streamed)
* }
* #7 ChatStatus { #6 status_code, #9 model_name }
* #9 delta_text (string)
* #12 (fixed64) some_hash
* #17 (string) message_uuid
* #28 UsageStats { #1 label, ... }
* }
*
* #9 appears both at top-level (text delta) AND inside #7 (model_name).
* iterFields walks top-level only, so we don't confuse the two.
*
* #5 is the finish_reason. Observed value `10` = tool_calls finish. We map
* any non-zero to 'tool_calls' for now (and let the caller fall back to
* 'stop' if no tool_call deltas were emitted).
*/
export function* decodeChatFrame(proto: Buffer): Generator<CloudChatEvent> {
// Field 7 is `ModelUsageStats`, the authoritative per-turn accounting, and
// field 28 is `response_dimension_groups` — the rows the IDE renders. The
// decoder below reads 28 because a capture happened to expose metric-looking
// strings there (`ResponseDimension.uid` is its field 5, which is what the
// entry walker treats as `metric_id`), and that works only when the service
// chose to render cache rows. Field 7 carries cache read and cache write
// unconditionally, which is why a cached Devin turn used to report a bare
// total with no cached subset.
//
// Both fields arrive in the same message and the adapter keeps the last usage
// event it sees, so this cannot be a plain "decode both": field 7 has to
// suppress field 28 within the message. It is yielded before the rest of the
// frame rather than after it, so a frame that also carries finish (field 5)
// still reports usage ahead of the turn's end, and the order does not depend
// on where the service happens to place the field.
let authoritativeUsage: CloudChatEvent | null = null;
for (const f of iterFields(proto)) {
if (f.num === 7 && f.wire === 2 && Buffer.isBuffer(f.value)) {
authoritativeUsage = decodeModelUsageStats(f.value as Buffer);
if (authoritativeUsage) break;
}
}
if (authoritativeUsage) yield authoritativeUsage;
let signatureType: string | undefined;
for (const f of iterFields(proto)) {
if (f.num === 21 && f.wire === 2 && Buffer.isBuffer(f.value) && f.value.length <= MAX_SIGNATURE_TYPE_BYTES) signatureType = f.value.toString('utf8') || undefined;
}
for (const f of iterFields(proto)) {
if (f.num === 3 && f.wire === 2 && Buffer.isBuffer(f.value)) {
// Visible delta_text — what the user should SEE in the chat.
//
// We previously had this mapping inverted (#3 = thinking, #9 = visible),
// which produced two compounding bugs in the TUI:
// 1. The model's CoT was rendered as plain content, so the user saw
// "The user wants me to X..." instead of the answer.
// 2. The actual answer (which lives in #3) was silently dropped — so
// the assistant turn appeared to end after the CoT with nothing
// after, matching the "model wrote reasoning then went silent"
// symptom the user reported.
// Verified live: prompted swe-1.6 with "explain then answer 2+2"; #3
// streamed "2+2=4 because... 4" while #9 streamed the meta-narration
// "The user wants me to perform a reasoning task...".
const s = (f.value as Buffer).toString('utf8');
if (s) yield { kind: 'text', text: s };
} else if (f.num === 9 && f.wire === 2 && Buffer.isBuffer(f.value)) {
// Internal thinking / chain-of-thought. Surface as `reasoning` so
// @ai-sdk consumers (opencode TUI) render it in a collapsed grey
// block instead of inline with the answer.
const s = (f.value as Buffer).toString('utf8');
if (s) yield { kind: 'reasoning', text: s };
} else if (f.num === 10 && f.wire === 2 && Buffer.isBuffer(f.value)) {
const s = (f.value as Buffer).toString('utf8');
// #21 delta_signature_type arrives in the same frame; the prompt replays it as #18.
if (s) yield { kind: 'reasoning_signature', signature: s, ...(signatureType ? { signatureType } : {}) };
} else if (f.num === 6 && f.wire === 2 && Buffer.isBuffer(f.value)) {
let id: string | undefined;
let name: string | undefined;
let argsDelta: string | undefined;
for (const sf of iterFields(f.value as Buffer)) {
if (sf.wire === 2 && Buffer.isBuffer(sf.value)) {
const s = (sf.value as Buffer).toString('utf8');
if (sf.num === 1) id = s;
else if (sf.num === 2) name = s;
else if (sf.num === 3) argsDelta = s;
}
}
if (id !== undefined && name !== undefined) {
yield { kind: 'tool_call_start', id, name };
}
if (argsDelta !== undefined) {
// Pass through `id` when this frame carries one (Cognition only
// sets it on the start frame today, but defending against future
// interleaving). Callers should prefer `id` over their rolling
// lastToolCallId when both are available.
yield { kind: 'tool_call_args', argsDelta, ...(id !== undefined ? { id } : {}) };
}
} else if (f.num === 5 && f.wire === 0) {
const v = Number(f.value);
// exa.codeium_common_pb.StopReason → OpenAI finish_reason.
// Source of truth: Windsurf extension.js sets `setEnumType("StopReason", [...])`
// 0 UNSPECIFIED → "stop" (no signal — treat as natural end)
// 1 INCOMPLETE → "length" (request cut short, model wanted more)
// 2 STOP_PATTERN → "stop" (model emitted its stop sequence — NORMAL)
// 3 MAX_TOKENS → "length"
// 4-9 internal → "stop"
// 10 FUNCTION_CALL → "tool_calls"
// 11 CONTENT_FILTER → "content_filter"
// 12 NON_INSERTION → "stop"
// 13 ERROR → "stop" (errors come as Connect trailer, not via this)
//
// We had 2 and 3 swapped previously, which made the model's normal
// STOP_PATTERN look like "length" → @ai-sdk treated complete responses
// as truncated. That was the "model wrote reasoning then went silent"
// symptom the user kept hitting.
let reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' = 'stop';
if (v === 10) reason = 'tool_calls';
else if (v === 11) reason = 'content_filter';
else if (v === 1 || v === 3) reason = 'length';
// else stays 'stop' for 0/2/4-9/12/13
yield { kind: 'finish', reason };
} else if (f.num === 28 && f.wire === 2 && Buffer.isBuffer(f.value)) {
if (authoritativeUsage) continue;
const usage = decodeUsageBlock(f.value as Buffer);
if (usage) yield usage;
}
}
}
/**
* UsageStats block at proto field #28. Captured shape (mitm of a real call):
*
* UsageStats {
* #1 label = "Token Usage"
* #2 entries [
* UsageEntry {
* #1 label = "Input tokens" / "Output tokens" / "Cached tokens" / ...
* #2 value (fixed32 — IEEE 754 float, OpenAI-style count cast)
* #3 unit = " tokens"
* #5 metric_id = "input_tokens" / "output_tokens" / ...
* },
* ...
* ]
* }
*
* We extract the standard input/output counts and synthesize a `total`.
* Anything else (cached, reasoning_tokens, …) is dropped for v1.
*/
function decodeUsageBlock(buf: Buffer): CloudChatEvent | null {
let promptTokens: number | undefined;
let completionTokens: number | undefined;
let cachedInputTokens: number | undefined;
let cacheCreationInputTokens: number | undefined;
let reasoningTokens: number | undefined;
for (const f of iterFields(buf)) {
// Each UsageEntry lives at field 2 (repeated). Field 1 is the block label
// ("Token Usage"); skip.
if (f.num !== 2 || f.wire !== 2 || !Buffer.isBuffer(f.value)) continue;
// Observed entry shape:
// UsageEntry {
// #4 (sub-message) {
// #1 label = "Input tokens" / "Output tokens"
// #2 (fixed32) value (IEEE 754 LE float — count as float)
// #3 unit = " token"
// #4 unit_plural = " tokens"
// }
// #5 metric_id = "input_tokens" / "output_tokens" / "cached_input_tokens" / ...
// }
let entryMetric: string | undefined;
let entryValue: number | undefined;
for (const sf of iterFields(f.value as Buffer)) {
if (sf.num === 5 && sf.wire === 2 && Buffer.isBuffer(sf.value)) {
entryMetric = (sf.value as Buffer).toString('utf8');
} else if (sf.num === 4 && sf.wire === 2 && Buffer.isBuffer(sf.value)) {
// Recurse into the displayed-dimension submessage to pull the fixed32
// value at its field 2.
for (const ssf of iterFields(sf.value as Buffer)) {
if (ssf.num === 2 && ssf.wire === 5 && Buffer.isBuffer(ssf.value)) {
entryValue = (ssf.value as Buffer).readFloatLE(0);
break;
}
}
}
}
if (entryMetric && entryValue !== undefined && Number.isFinite(entryValue)) {
const n = Math.round(entryValue);
if (entryMetric === 'input_tokens') promptTokens = n;
else if (entryMetric === 'output_tokens') completionTokens = n;
else if (entryMetric === 'cached_input_tokens' || entryMetric === 'cache_read_input_tokens') {
cachedInputTokens = (cachedInputTokens ?? 0) + n;
} else if (entryMetric === 'cache_creation_input_tokens') {
cacheCreationInputTokens = (cacheCreationInputTokens ?? 0) + n;
} else if (entryMetric === 'reasoning_tokens' || entryMetric === 'output_reasoning_tokens') {
reasoningTokens = (reasoningTokens ?? 0) + n;
}
}
}
if (promptTokens === undefined && completionTokens === undefined) return null;
// totalTokens reflects what OpenAI's API counts as billable: input +
// output. Cached / cache-creation / reasoning subtotals are surfaced as
// additional fields so callers that want a fuller picture (e.g. cost
// breakdown for reasoning models) can read them, but they're NOT
// double-counted into total.
const total = (promptTokens ?? 0) + (completionTokens ?? 0);
return {
kind: 'usage',
promptTokens,
completionTokens,
totalTokens: total > 0 ? total : undefined,
cachedInputTokens,
cacheCreationInputTokens,
reasoningTokens,
};
}
/**
* `exa.codeium_common_pb.ModelUsageStats` at GetChatMessageResponse field 7.
*
* ModelUsageStats {
* #2 input_tokens uint64
* #3 output_tokens uint64
* #4 cache_write_tokens uint64
* #5 cache_read_tokens uint64
* }
*
* Plain varints, so the field-28 entry walker — which descends a
* length-delimited sub-message and reads a fixed32 float — cannot read this at
* all. It needs its own decoder.
*
* Whether Cognition's `input_tokens` already includes the cached tokens is not
* settled. oh-my-pi sums all four into its total, which suggests exclusive, but
* that is their convention rather than a measurement of this field. Guessing
* wrong in the inclusive direction is the expensive mistake: `normalizeCostTokens`
* only rejects `read + write > input`, so an inflated input passes validation and
* bills cached tokens at the uncached rate.
*
* So the shape is derived from the frame instead of assumed. An input that
* already covers the cache is left alone; one that cannot possibly cover it is
* folded. Both branches agree on the case that motivated this — a 58k prompt
* that is 57k cache read and 1k fresh reads as 58k with a 57k cached subset —
* and neither can emit `read + write > input`. Replace the derivation with a
* fixed mapping once a live frame settles the question.
*/
export function decodeModelUsageStats(buf: Buffer): CloudChatEvent | null {
let wireInput: number | undefined;
let output: number | undefined;
let cacheWrite: number | undefined;
let cacheRead: number | undefined;
for (const f of iterFields(buf)) {
if (f.wire !== 0) continue;
const n = Number(f.value);
if (!Number.isFinite(n) || n < 0) continue;
if (f.num === 2) wireInput = n;
else if (f.num === 3) output = n;
else if (f.num === 4) cacheWrite = n;
else if (f.num === 5) cacheRead = n;
}
if (wireInput === undefined && output === undefined && cacheRead === undefined && cacheWrite === undefined) {
return null;
}
const read = cacheRead ?? 0;
const write = cacheWrite ?? 0;
const rawInput = wireInput ?? 0;
const promptTokens = rawInput >= read + write ? rawInput : rawInput + read + write;
const completionTokens = output ?? 0;
const total = promptTokens + completionTokens;
return {
kind: 'usage',
promptTokens,
completionTokens,
totalTokens: total > 0 ? total : undefined,
cachedInputTokens: cacheRead,
cacheCreationInputTokens: cacheWrite,
reasoningTokens: undefined,
};
}
// ----------------------------------------------------------------------------
// Public API: streamChat
// ----------------------------------------------------------------------------
export interface CloudChatRequest {
/** Persistent OAuth-issued api_key (`devin-session-token$<JWT>`). */
apiKey: string;
/** Pre-resolved API server URL from RegisterUser (falls back to default). */
apiServerUrl?: string;
/** Model UID — e.g. `swe-1-6`, `kimi-k2-6`, `claude-opus-4-7-medium`. */
modelUid: string;
/** Chat history. */
messages: ChatHistoryItem[];
/**
* Tool definitions available to the model. Cloud encodes these in the
* GetChatMessage request's `tools` field (proto #10). When set, the model
* may emit `tool_call_start`/`_args`/`_end` events instead of plain text.
*/
tools?: ToolDef[];
/** Cascade ID — reuse across turns of the same conversation. */
cascadeId?: string;
/** Optional sampling overrides. */
completionOpts?: BuildArgs['completionOpts'];
/** Override request_type (default = 5, CASCADE). */
requestType?: number;
/**
* Catalog the caller already resolved this turn. An explicit `null`
* records a failed lookup: the pre-flight below then skips its own fetch
* instead of paying a second catalog timeout on the same turn. Omit the
* field to let the pre-flight perform its own cached lookup.
*/
catalog?: CacheEntry | null;
/** Abort signal — closes the fetch stream. */
signal?: AbortSignal;
/** Executor for the inference POST only; catalog and JWT RPCs retain their own transport. */
executor?: typeof globalThis.fetch;
}
export class CloudChatError extends Error {
constructor(
message: string,
public readonly code?: string,
public readonly traceId?: string,
/**
* Upstream HTTP status, when the failure was a status line rather than a
* Connect trailer. Without it the adapter's message reaches
* `inferHttpStatusFromAdapterMessage`, which does not parse `HTTP 429`, so
* a live rate limit was classified 502 and core's failover never rotated.
*/
public readonly status?: number,
/**
* Provider-stated recovery delay in seconds. The trailer parser extracts
* it while the raw upstream text is still available, because the thrown
* message is content-free: the stated-reset retry reads this typed field
* instead of scraping untrusted trailer text out of error.message.
*/
public readonly retryAfterSeconds?: number,
) {
super(message);
this.name = 'CloudChatError';
}
}
const TRACE_ID_RE = /\(trace ID: ([0-9a-f]+)\)/i;
const SAFE_CONNECT_CODES = new Set([
'canceled', 'unknown', 'invalid_argument', 'deadline_exceeded', 'not_found', 'already_exists',
'permission_denied', 'resource_exhausted', 'failed_precondition', 'aborted', 'out_of_range',
'unimplemented', 'internal', 'unavailable', 'data_loss', 'unauthenticated',
]);
function safeConnectCode(value: unknown): string | undefined {
return typeof value === 'string' && SAFE_CONNECT_CODES.has(value) ? value : undefined;
}
/**
* A quota refusal Cognition delivers as `permission_denied`.
*
* "Your limit will reset in 13 minutes" and "Reached overall message rate
* limit" are caps, not authorization failures. Classified as 403 they invite
* the client to retry straight into a live cap; as 429 the proxy backs off and
* can rotate.
*/
const TRAILER_QUOTA_RE = /\b(?:limit will reset|rate limit|quota exceeded|out of credits)\b/i;
/**
* Connect error code to HTTP status.
*
* Without this only the HTTP status line reached the adapter, so a cap or an
* expired credential delivered as an EOS trailer fell through to
* `inferHttpStatusFromAdapterMessage` and became a generic 502 — which is not
* retryable-with-backoff, not an auth prompt, and not something core's failover
* acts on.
*/
export function connectTrailerHttpStatus(code: string | undefined, message: string): number | undefined {
if (code === 'permission_denied' && TRAILER_QUOTA_RE.test(message)) return 429;
switch (code) {
case 'unauthenticated': return 401;
case 'permission_denied': return 403;
case 'resource_exhausted': return 429;
case 'not_found': return 404;
case 'unavailable': return 503;
case 'deadline_exceeded': return 504;
case 'unimplemented': return 501;
case 'invalid_argument':
case 'failed_precondition':
case 'out_of_range': return 400;
case 'internal':
case 'unknown':
case 'data_loss': return 502;
default: return undefined;
}
}
/**
* Stream chat events from the cloud. Yields CloudChatEvent (text deltas, tool
* call deltas, finish reason). Use `streamChatText` for legacy text-only iteration.
*
* On error (auth fail, quota exhausted, malformed request) throws a
* CloudChatError with the cloud's `code` + `traceId` for diagnostics.
*/
export async function* streamChatEvents(req: CloudChatRequest): AsyncGenerator<CloudChatEvent> {
// The api-server host comes from RegisterUser through the credential store.
// Validate it here too: this request body carries the api_key, so an
// unallowlisted host is credential exfiltration rather than a wrong endpoint.
const host = resolveDevinApiBaseUrl(req.apiServerUrl);
// The hosted chat path does not require the short-lived user_jwt; the working
// reference omits it by default. Minting it is opt-in so a mint failure or a
// JWT the chat service does not accept cannot break every turn.
const userJwt = process.env.OPENCODEX_DEVIN_SEND_USER_JWT === "1"
? await getCachedUserJwt(req.apiKey, host, req.signal)
: undefined;
// Pre-flight: consult the per-account model catalog. Cognition's cloud
// returns an opaque `permission_denied: "an internal error occurred (trace
// ID: ...)"` for every chat call that targets a model not enabled on the
// caller's tier — issue #14. The catalog's `disabled` flag is the
// authoritative source for "can this account run this UID"; we surface a
// named error here so the user knows why instead of guessing.
//
// Best-effort: if the catalog fetch fails (network, auth, schema drift) we
// pass through to the chat call. The cloud will still surface its own
// error and the trailer-error path below enriches the message in-place.
// Treat an empty catalog (schema drift / unexpected response) as "no catalog"
// so chat passes through instead of failing every request.
const catalog = req.catalog !== undefined
? req.catalog
: await getCachedCatalog(req.apiKey, host, req.signal).catch(() => null);
if (catalog && catalog.byUid.size > 0) {
const entry = catalog.byUid.get(req.modelUid);
if (!entry) {
throw new ModelNotAvailableError(req.modelUid, req.modelUid, 'not_listed');
}
if (entry.disabled) {
throw new ModelNotAvailableError(req.modelUid, entry.label, 'disabled');
}
}
// Reuse session + cascade ids across calls for the same (apiKey, host).
// Without this, every turn looks like a brand-new server-side session
// and the cloud's prompt cache never hits — significant cost regression
// for long conversations.
const sessionIds = getOrAllocateSessionIds(req.apiKey, host, req.cascadeId);
const proto = buildGetChatMessageRequest({
apiKey: req.apiKey,
userJwt,
modelUid: req.modelUid,
messages: req.messages,
tools: req.tools,
cascadeId: sessionIds.cascadeId,
sessionId: sessionIds.sessionId,
requestId: BigInt(Date.now()),
triggerId: crypto.randomUUID(),
requestType: req.requestType,
completionOpts: req.completionOpts,
});
// The request envelope goes up uncompressed. A gzipped GetChatMessage frame is
// rejected with the same opaque `invalid_argument: an internal error occurred`
// the short fingerprint produces, and it is one of three things that have to be
// right together — the other two are the doubled Basic credential and the
// 732-character Metadata #31.
const framed = frameConnectStream(proto, false);
const body = new Blob([new Uint8Array(framed)], { type: "application/connect+proto" });
// Compose the caller signal with a deadline on the response HEADERS. The
// timer is cleared in the finally below, which runs when `await fetch`
// resolves — and fetch resolves on headers, not on the first body byte. An
// earlier comment here claimed "once any byte arrives", which was wrong and
// hid the defect: Cognition withholds headers until the first token, so this
// budget is a generation deadline. Body silence after headers is a separate
// budget, the per-chunk idle timer in the read loop below.
const ttfbController = new AbortController();
const headersMs = cloudStreamHeadersMs();
// Abort with no reason and remember that we are the one who fired. Bun rejects
// the fetch with its own AbortError rather than handing back `signal.reason`,
// so attaching a typed error to abort() would be discarded; the catch below is
// what actually produces a classifiable failure.
let headersDeadlineFired = false;
const ttfbTimer = setTimeout(() => {
headersDeadlineFired = true;
ttfbController.abort();
}, headersMs);
const ttfbSignal = ttfbController.signal;
// Compose req.signal + ttfbSignal. AbortSignal.any was added in Node
// 20.3 / Bun 1.0; our `engines` allows Node ≥18, so on Node 18-20.2 the
// built-in is missing. The previous fallback `req.signal ?? ttfbSignal`
// silently discarded one of the two signals (TTFB if caller passed
// one), defeating the timeout guard. anySignal() is a real polyfill.
const composed = req.signal ? anySignal([req.signal, ttfbSignal]) : undefined;
const initialSignal: AbortSignal = composed?.signal ?? ttfbSignal;
let resp: Response;
try {
resp = await (req.executor ?? globalThis.fetch)(`${host}/exa.api_server_pb.ApiServerService/GetChatMessage`, {
method: 'POST',
headers: {
'Content-Type': 'application/connect+proto',
'Connect-Protocol-Version': '1',
'Connect-Accept-Encoding': 'gzip',
// The credential is the session token doubled and dash-joined. A single
// copy is refused with permission_denied. The protobuf body keeps one
// copy, in Metadata #3.
Authorization: `Basic ${req.apiKey}-${req.apiKey}`,
'User-Agent': 'connect-es/2.0.0',
Accept: '*/*',
},
body,
redirect: 'error',
signal: initialSignal,
// Bun applies its own fetch idle timeout (~5 minutes) on top of ours.
// Two independent deadlines on the same hop means the shorter one wins
// silently and this function can no longer explain its own failure, so
// the deadline above is made the single authority. Same reason as
// src/server/responses/fetch-helpers.ts.
timeout: 0,
} as RequestInit);
} catch (err) {
if (headersDeadlineFired) {
// Ours, not the upstream failing. Raised as a typed error with an explicit
// status because devinErrorClassification reads CloudChatError.status and
// would otherwise return {} for a bare Error, leaving src/lib/errors.ts to
// guess from the message text. The message deliberately no longer says
// "timeout", so the status is the only thing carrying the classification.
throw new CloudChatError(
`cloud-direct: no response headers within ${headersMs}ms`,
undefined,
undefined,
504,
);
}
throw err;
} finally {
clearTimeout(ttfbTimer);
// The composed signal only guards the headers hop; the body is cancelled
// through cancelBodyOnAbort below. Detaching here keeps a long-lived caller
// signal from collecting one listener per turn.
composed?.cleanup();
}
if (!resp.ok) {
// The body is not echoed into the message. This error reaches the adapter's
// error event and /api/logs, and a Connect error can quote the request that
// produced it - which is the request holding the api_key.
//
// The status line is carried on the error. A cap or an expired credential
// delivered instead as a Connect EOS trailer is mapped by
// connectTrailerHttpStatus at the trailer sites below.
const error = new CloudChatError(`GetChatMessage failed (HTTP ${resp.status})`, undefined, undefined, resp.status);
// No consumer will drain this body. Cancellation must neither replace the
// status error nor delay it if a transport's cancel promise never settles.
try {
void resp.body?.cancel(error).catch(() => undefined);
} catch { /* Non-conforming streams can throw synchronously from cancel. */ }
throw error;
}
if (!resp.body) {
throw new CloudChatError('GetChatMessage response had no body stream');
}
// Cancel the body when the client goes away. Without this the read loop never
// observes req.signal after headers arrive: the turn keeps draining until the
// idle timer fires, and the stream then ends without an EOS trailer, which
// this function would report as a truncated upstream response rather than as
// the cancellation it actually was.
const detachBodyCancel = cancelBodyOnAbort(resp.body, req.signal);
// Incremental parsing. We previously did `pending = Buffer.concat([pending,
// chunk])` per chunk — O(n²) over a long stream because every chunk copies
// every buffered byte again. Now we keep a queue of arriving chunks with a
// running offset; we only `Buffer.concat` when a frame straddles a chunk
// boundary, and we slice/drop fully-consumed chunks immediately. For
// typical 50-200KB responses this is ~5x faster and produces zero waste.
const chunkQueue: Buffer[] = [];
let queuedBytes = 0;
// Bun + Node ReadableStream readers diverge on the type-level shape
// (Bun's includes a `readMany` method); both work the same at runtime.
const reader = resp.body.getReader() as ReadableStreamDefaultReader<Uint8Array>;
let trailerError: { code?: string; message: string; opaqueDenial: boolean; retryAfterSeconds?: number; traceId?: string } | null = null;
let sawEos = false;
/**
* Try to read the next `n` bytes from the chunk queue WITHOUT consuming
* them. Returns null if not enough buffered.
*/
function peek(n: number): Buffer | null {
if (queuedBytes < n) return null;
if (chunkQueue.length === 1 && chunkQueue[0].length >= n) {
return chunkQueue[0].slice(0, n);
}
// Cross-chunk peek — concat just the prefix we need.
const parts: Buffer[] = [];
let remaining = n;
for (const c of chunkQueue) {
if (remaining <= 0) break;
if (c.length <= remaining) {
parts.push(c);
remaining -= c.length;
} else {
parts.push(c.slice(0, remaining));
remaining = 0;
}
}
return Buffer.concat(parts, n);
}
/** Drop the first `n` bytes from the chunk queue. */
function drop(n: number): void {
queuedBytes -= n;
let remaining = n;
while (remaining > 0 && chunkQueue.length > 0) {
const head = chunkQueue[0];
if (head.length <= remaining) {
chunkQueue.shift();
remaining -= head.length;
} else {
chunkQueue[0] = head.slice(remaining);
remaining = 0;
}
}
}
// Track the idle timer at outer scope so the finally block can clear it
// regardless of how we exit the read loop (clean done, throw, etc).
// Previously this lived inside `try { ... }` and was only cleared on
// normal exit — an error path left a 120s timer in the event loop and
// the process refused to exit promptly.
let idleTimer: ReturnType<typeof setTimeout> | null = null;
try {
const resetIdle = (): Promise<{ value?: Uint8Array; done: boolean }> => {
if (idleTimer) clearTimeout(idleTimer);
const idleController = new AbortController();
idleTimer = setTimeout(
() => idleController.abort(new Error(`cloud-direct: idle timeout (${CLOUD_STREAM_IDLE_MS}ms with no bytes)`)),
CLOUD_STREAM_IDLE_MS,
);
// Race the reader.read() against idle abort. When abort wins, we
// also actively `cancel()` the underlying body stream so the
// pending read() resolves promptly with done=true instead of
// hanging on the now-dead TCP socket until the OS notices.
//
// Promise-handling carefully: the reader.read() promise can settle
// AFTER the outer race rejects (we cancelled, the read eventually
// sees the cancellation and either resolves with done=true or
// rejects with an abort error). We attach an explicit `.catch(()=>{})`
// on the read promise so any post-race rejection doesn't surface as
// an unhandled-rejection warning in the host runtime.
return new Promise((resolve, reject) => {
let settled = false;
const settle = (fn: () => void): void => {
if (settled) return;
settled = true;
fn();
};
const readP = reader.read();
// Defensive: swallow any post-race rejection. If the outer promise
// already settled via the abort listener, we still need a handler
// attached to readP or Node logs an unhandledRejection.
readP.catch(() => { /* swallowed; outer promise already rejected */ });
idleController.signal.addEventListener('abort', () => {
try { void resp.body?.cancel(idleController.signal.reason ?? new Error('idle abort')); } catch { /* */ }
settle(() => reject(idleController.signal.reason ?? new Error('idle abort')));
}, { once: true });
readP.then(
(v) => settle(() => resolve(v)),
(e) => settle(() => reject(e)),
);
});
};
while (true) {
const { value, done } = await resetIdle();
if (done) break;
if (value) {
chunkQueue.push(Buffer.from(value));
queuedBytes += value.length;
}
// Drain every complete frame currently buffered.
while (queuedBytes >= 5) {
const header = peek(5);
if (!header) break;
const flags = header[0];
const len = header.readUInt32BE(1);
// Cap frame length to prevent memory exhaustion from a corrupt/malicious
// length prefix. 16MB is well above any legitimate Connect-RPC frame.
if (len > MAX_FRAME_LEN) {
throw new CloudChatError(`Connect frame length ${len} exceeds ${MAX_FRAME_LEN} byte cap`);
}
if (queuedBytes < 5 + len) break; // frame still arriving
drop(5);
const raw = peek(len) ?? Buffer.alloc(0);
drop(len);
let payload = raw;
if (flags & 0x01) {
try {
// MAX_FRAME_LEN caps the COMPRESSED frame, so without an output cap
// a 16 MiB gzip frame can still inflate to gigabytes. The inbound
// request path (src/server/request-decompress.ts) already bounds
// decompression the same way.
payload = zlib.gunzipSync(raw, { maxOutputLength: MAX_FRAME_LEN });
} catch (gzipErr) {
const code = (gzipErr as NodeJS.ErrnoException).code;
if (code === 'ERR_BUFFER_TOO_LARGE') {
throw new CloudChatError(`Connect frame inflates past the ${MAX_FRAME_LEN} byte cap`, 'frame_too_large');
}
// Corrupt compressed frame — surface as a CloudChatError instead
// of falling through and re-parsing raw gzip bytes as proto
// (which used to misparse silently downstream).
throw new CloudChatError(`Connect frame gunzip failed: ${(gzipErr as Error).message}`);
}
}
const eos = (flags & 0x02) !== 0;
if (eos) {
sawEos = true;
// Trailer: {} on success, {"error":{code,message}} on failure.
const text = payload.toString('utf8');
if (text && text.includes('"error"')) {
let code: string | undefined;
let message = '';
try {
const j = JSON.parse(text) as { error?: { code?: string; message?: string } };
code = safeConnectCode(j.error?.code);
if (typeof j.error?.message === 'string') message = j.error.message;
} catch { /* malformed trailers still become a content-free error */ }
const traceMatch = message.match(TRACE_ID_RE);
trailerError = {
code,
message,
opaqueDenial: /an internal error occurred/i.test(message),
// Parsed here, where the raw text still exists: the thrown error
// is content-free, so the stated-reset retry consumes this typed
// field rather than the upstream sentence.
retryAfterSeconds: parseRetryAfterFromMessage(message),
traceId: traceMatch?.[1],
};
}
continue;
}
yield* decodeChatFrame(payload);
}
}
} finally {
// Always clear the idle timer. The previous "clear on normal exit
// only" path leaked a 120s setTimeout into the event loop on any
// throw (idle timeout, gunzip error, trailer error, etc), keeping
// the process from exiting promptly.
if (idleTimer) clearTimeout(idleTimer);
// Cancel the underlying body stream on any non-clean exit so the TCP
// connection is released. `releaseLock` alone leaves the body in a
// dangling state; we have to call `cancel` on the response body
// itself (cancel-via-reader requires holding the lock). Fire and
// forget — there's nothing meaningful to do if cancel rejects.
try { reader.releaseLock(); } catch { /* */ }
try { void resp.body?.cancel(); } catch { /* */ }
}
if (trailerError) {
// Cognition uses `permission_denied: "an internal error occurred (trace
// ID: …)"` as a catch-all for "your account can't run this model" — same
// root cause issue #14 reported. The pre-flight above catches this when
// the catalog disagrees with the call, but the catalog can lag (a model
// that was enabled at fetch time may have been gated between then and
// now) or be missing (network failure caused a fall-through). When the
// trailer is this exact shape, swap in a message that names the
// model and explains the likely cause rather than re-passing
// Cognition's opaque text. Raw trailer messages never leave this
// parser: they can reflect the credential carried by the request.
// Both codes carry this shape. Cognition uses `invalid_argument` for a
// request it could not accept and `permission_denied` for one it would not,
// and the message body is the same opaque sentence either way.
const isOpaqueDenial =
(trailerError.code === 'permission_denied' || trailerError.code === 'invalid_argument') &&
trailerError.opaqueDenial;
if (isOpaqueDenial) {
const enriched =
`Cognition denied this request for model "${req.modelUid}" with the opaque ` +
`"an internal error occurred" message, which it uses for both a malformed ` +
`request and a refused one. In practice this has meant the request, not ` +
`the account: the same sentence came back for every turn until the ` +
`CompletionConfiguration tag map was corrected, and a temperature of ` +
`exactly 0 still produces it. Check the request before the plan — ` +
`tests/providers/devin-hardening.test.ts pins the field layout the ` +
`service accepts. If the request is unchanged and this is new, the ` +
`account's model access is the next thing to check. ` +
`(cloud trace ID: ${trailerError.traceId ?? 'n/a'})`;
throw new CloudChatError(
enriched,
trailerError.code,
trailerError.traceId,
connectTrailerHttpStatus(trailerError.code, trailerError.message),
trailerError.retryAfterSeconds,
);
}
// Cognition also returns `permission_denied` when a tool description
// contains a blocklisted phrase that the sanitizer above did not catch
// (e.g. Cognition added a new phrase). Surface a clear message so the
// user knows to check tool descriptions rather than suspect auth/tier.
// Only blame the blocklist when tools were actually sent. Asserting it for
// every permission_denied sent users to inspect a tool table that had
// nothing to do with an ordinary ACL or tier denial.
if (trailerError.code === 'permission_denied' && (req.tools?.length ?? 0) > 0) {
const enriched =
`Cognition denied this request (permission_denied). If tool descriptions ` +
`are present, a blocklisted phrase may have triggered this — see the ` +
`COGNITION_BLOCKLIST_REWRITES table in cloud-direct/chat.ts. ` +
`(cloud trace ID: ${trailerError.traceId ?? 'n/a'})`;
throw new CloudChatError(
enriched,
trailerError.code,
trailerError.traceId,
connectTrailerHttpStatus(trailerError.code, trailerError.message),
trailerError.retryAfterSeconds,
);
}
// Raw trailer messages never leave this parser: they can reflect the
// credential carried by the request. The allowlisted code and the hex
// trace id are the only upstream-controlled fields that reach the error.
// The stated delay rides along in our own words so a client can still
// tell how long to wait when local retry gives up, exceeds its cap, or
// is disabled. The `~` marks the delay as approximate; the shared
// parser accepts it once after Retry-After, so the outer client cooldown
// reads this same delay back from the message.
throw new CloudChatError(
`Cognition chat failed${trailerError.code ? ` (${trailerError.code})` : ''} ` +
`(cloud trace ID: ${trailerError.traceId ?? 'n/a'})` +
(trailerError.retryAfterSeconds === undefined
? ''
: `; retry after ~${trailerError.retryAfterSeconds}s`),
trailerError.code,
trailerError.traceId,
connectTrailerHttpStatus(trailerError.code, trailerError.message),
trailerError.retryAfterSeconds,
);
}
// Truncation detection: the cloud always terminates a successful stream
// with an EOS trailer. If we hit `done` from the body reader without one,
// the connection dropped mid-frame and any bytes still in the queue are
// garbage. Previously those leftover bytes were silently discarded and
// the consumer saw a clean stop with no error — looked like the model
// had finished. Now we surface it.
detachBodyCancel();
if (req.signal?.aborted) {
// The caller cancelled. The missing EOS trailer is the expected consequence
// of that cancellation, not evidence that the cloud dropped the response.
return;
}
if (!sawEos) {
throw new CloudChatError(
`Cloud stream ended without EOS trailer (${queuedBytes} bytes orphaned). ` +
`Connection likely dropped mid-response.`,
'truncated_stream',
);
}
}
/**
* Back-compat: yield text content only (drops tool calls). The plugin uses
* streamChatEvents directly when it needs to surface tool_calls.
*/
export async function* streamChat(req: CloudChatRequest): AsyncGenerator<string> {
for await (const ev of streamChatEvents(req)) {
if (ev.kind === 'text') yield ev.text;
}
}
// `parseConnectFrames` is no longer needed by streamChat itself, but exported
// from wire.ts for one-shot callers + tests.
void parseConnectFrames;