Skip to content

Commit a616078

Browse files
committed
feat(translator): bound every translation buffer with a mandatory turn budget
Every bidirectional translation path now draws from one required budget: 2 MiB per assembled tool call, 32 MiB per client turn across all charged copies, threaded from the ingress boundary through adapters, retries, image and web-search loops, and the outbound folds. Streaming deltas that are emitted rather than retained stay transient; genuine Responses passthrough and MCP payloads sit on an observation-only lease so neither acquires a second hard cap. The Cursor transport gains byte-based backpressure with frame-size admission while keeping the stricter 1024-event queue cap, and the image, OAuth, and Grok serialized tails get admission gates that reject before enqueue. The four translator observed ids now appear in the app-owned memory payload, completing the 040 integration contract.
1 parent 80dd175 commit a616078

93 files changed

Lines changed: 3601 additions & 450 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/adapters/anthropic.ts‎

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import { neutralizeIdentity } from "./identity";
2222
import { CLAUDE_CODE_HEADERS, claudeCodeSessionId } from "./client-fingerprint";
2323
import { buildNonOpenAIToolCatalogNudgeForTools } from "./tool-catalog-nudge";
2424
import { decodeServerSentEvents } from "../lib/sse-decoder";
25+
import { isTranslatorBudgetExceededError, retainTranslatedEventBatch, type TranslatorBudget } from "../lib/translator-budget";
2526

2627
/** Map a user content part to an Anthropic content block (text or image source). */
2728
function toAnthropicContentPart(p: OcxContentPart): unknown {
@@ -783,12 +784,13 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
783784
return { url, method: "POST", headers, body: JSON.stringify(body) };
784785
},
785786

786-
async *parseStream(response: Response): AsyncGenerator<AdapterEvent> {
787+
async *parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator<AdapterEvent> {
787788
if (!response.body) {
788789
yield { type: "error", message: "No response body" };
789790
return;
790791
}
791792

793+
const budgetEncoder = new TextEncoder();
792794
let currentBlockType = "";
793795
let currentToolCallId = "";
794796
let currentToolCallName = "";
@@ -807,7 +809,8 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
807809
};
808810
};
809811

810-
for await (const record of decodeServerSentEvents(response.body, { includeComments: true })) {
812+
try {
813+
for await (const record of decodeServerSentEvents(response.body, { includeComments: true, translatorBudget: budget })) {
811814
if (record.kind === "comment") {
812815
yield { type: "heartbeat" };
813816
continue;
@@ -837,6 +840,7 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
837840
currentToolCallId = usableToolUseId(block.id);
838841
currentToolCallName = toolNames.fromWire(block.name ?? "");
839842
currentToolCallJson = "";
843+
budget.openCall(currentToolCallId);
840844
yield { type: "tool_call_start", id: currentToolCallId, name: currentToolCallName };
841845
}
842846
if (block.type === "redacted_thinking" && typeof block.data === "string") {
@@ -866,7 +870,17 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
866870
// response.function_call_arguments.delta frame, so withholding fragments until
867871
// block close would leave a started call showing empty arguments. A copy is kept
868872
// to validate the assembled payload at content_block_stop.
869-
currentToolCallJson += delta.partial_json;
873+
const previousBytes = budgetEncoder.encode(currentToolCallJson).byteLength;
874+
const nextBytes = previousBytes + budgetEncoder.encode(delta.partial_json).byteLength;
875+
const reservation = budget.reserveTransient(nextBytes, { kind: "tool_args", callId: currentToolCallId });
876+
try {
877+
currentToolCallJson += delta.partial_json;
878+
reservation.commitRetained();
879+
budget.releaseRetained(previousBytes, { kind: "tool_args", callId: currentToolCallId });
880+
} catch (error) {
881+
reservation.release();
882+
throw error;
883+
}
870884
yield { type: "tool_call_delta", arguments: delta.partial_json };
871885
}
872886
break;
@@ -886,6 +900,7 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
886900
return;
887901
}
888902
yield { type: "tool_call_end" };
903+
budget.closeCall(currentToolCallId);
889904
currentToolCallId = "";
890905
currentToolCallJson = "";
891906
}
@@ -910,6 +925,18 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
910925
}
911926
}
912927
}
928+
} catch (error) {
929+
if (!isTranslatorBudgetExceededError(error)) throw error;
930+
yield {
931+
type: "error",
932+
status: 502,
933+
errorType: "upstream_error",
934+
code: "translation_buffer_limit",
935+
message: "upstream translation buffer exceeded the safe limit",
936+
};
937+
} finally {
938+
if (currentToolCallId) budget.closeCall(currentToolCallId);
939+
}
913940
if (!emittedDone) {
914941
// Fail closed on transport EOF. Compatible providers may omit message_stop after message_delta.stop_reason.
915942
if (pendingStopReason !== undefined) {
@@ -930,8 +957,11 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
930957
}
931958
},
932959

933-
async parseResponse(response: Response): Promise<AdapterEvent[]> {
960+
async parseResponse(response: Response, budget: TranslatorBudget): Promise<AdapterEvent[]> {
934961
const json = await response.json() as Record<string, unknown>;
962+
const responseBytes = new TextEncoder().encode(JSON.stringify(json)).byteLength;
963+
budget.chargeRetained(responseBytes, { kind: "retained_collectors" });
964+
try {
935965
const events: AdapterEvent[] = [];
936966
const content = json.content as { type: string; text?: string; id?: string; name?: string; input?: unknown; thinking?: string; reasoning?: string; signature?: string; data?: string }[] | undefined;
937967
if (content) {
@@ -962,7 +992,11 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
962992
usage: usageFromAnthropic(usage),
963993
...(stopReason ? { stopReason } : {}),
964994
});
995+
retainTranslatedEventBatch(events, budget);
965996
return events;
997+
} finally {
998+
budget.releaseRetained(responseBytes, { kind: "retained_collectors" });
999+
}
9661000
},
9671001

9681002
};

‎src/adapters/azure.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { ProviderAdapter } from "./base";
1+
import type { IncomingMeta, ProviderAdapter } from "./base";
22
import type { OcxParsedRequest, OcxProviderConfig } from "../types";
33
import { createResponsesPassthroughAdapter } from "./openai-responses";
44

@@ -12,15 +12,15 @@ export function createAzureAdapter(provider: OcxProviderConfig): ProviderAdapter
1212
...inner,
1313
name: "azure-openai",
1414

15-
async buildRequest(parsed: OcxParsedRequest) {
15+
async buildRequest(parsed: OcxParsedRequest, incoming: IncomingMeta) {
1616
if (provider.authMode === "forward") {
1717
throw new Error("azure-openai does not support forward auth mode");
1818
}
1919
if (typeof provider.apiKey !== "string" || provider.apiKey.trim() === "") {
2020
throw new Error("azure-openai requires a non-empty apiKey");
2121
}
2222

23-
const request = await inner.buildRequest(parsed);
23+
const request = await inner.buildRequest(parsed, incoming);
2424
const unresolvedPlaceholder = request.url.match(/\{[^}]*\}/)?.[0] ?? request.url.match(/[{}]/)?.[0];
2525
if (unresolvedPlaceholder) {
2626
throw new Error(`azure-openai baseUrl contains unresolved ${unresolvedPlaceholder} — set your real resource URL`);

‎src/adapters/base.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
import type { AdapterEvent, OcxParsedRequest } from "../types";
2+
import type { TranslatorBudget } from "../lib/translator-budget";
23

34
/** Metadata about the caller's incoming request, for auth-forwarding adapters. */
45
export interface IncomingMeta {
56
headers: Headers;
7+
translatorBudget: TranslatorBudget;
68
abortSignal?: AbortSignal;
79
/**
810
* Image-normalization ladder bias for upstream-413 tightened retries: every image
@@ -26,12 +28,12 @@ export interface ProviderAdapter {
2628
* (e.g. Vertex AI ADC token) return a Promise. Sync adapters return the object directly; callers
2729
* must `await` the result (awaiting a non-Promise is a no-op).
2830
*/
29-
buildRequest(parsed: OcxParsedRequest, incoming?: IncomingMeta): AdapterRequest | Promise<AdapterRequest>;
31+
buildRequest(parsed: OcxParsedRequest, incoming: IncomingMeta): AdapterRequest | Promise<AdapterRequest>;
3032

3133
fetchResponse?(request: AdapterRequest, ctx?: AdapterFetchContext): Promise<Response>;
3234

33-
parseStream(response: Response): AsyncGenerator<AdapterEvent>;
34-
parseResponse?(response: Response): Promise<AdapterEvent[]>;
35+
parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator<AdapterEvent>;
36+
parseResponse?(response: Response, budget: TranslatorBudget): Promise<AdapterEvent[]>;
3537
runTurn?(
3638
parsed: OcxParsedRequest,
3739
incoming: IncomingMeta,
@@ -44,6 +46,8 @@ export interface AdapterRequest {
4446
method: string;
4547
headers: Record<string, string>;
4648
body: string;
49+
/** Releases observation of a serialized request body after its final fetch attempt settles. */
50+
releaseBodyObservation?: () => void;
4751
/** Exact reasoning parameter emitted by the adapter, for request-log diagnostics only. */
4852
reasoningLog?: {
4953
effectiveEffort: string;

‎src/adapters/cursor.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { createHash } from "node:crypto";
22
import type { AdapterEvent, OcxProviderConfig } from "../types";
33
import type { ProviderAdapter } from "./base";
4+
import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
45
import { cursorExecDeniedMessage, cursorRequestDeclaresFullAccess } from "./cursor/exec-policy";
56
import { isCursorBenignCancelError, isCursorInvalidArgumentError, safeCursorErrorMessage } from "./cursor/cursor-errors";
67
import { isCursorExternalWireModel } from "./cursor/discovery";
@@ -78,7 +79,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
7879
}
7980
try {
8081
const makeTransport = deps.createTransport ?? createLiveCursorTransport;
81-
const kv = deps.kv ?? createCursorKvStore();
82+
const kv = deps.kv ?? createCursorKvStore({}, incoming.translatorBudget);
8283
const rekeyContextUsage = deps.rekeyContextUsage ?? rekeyCursorContextUsage;
8384
// Namespace thread→conversation derivation by the authenticated Cursor credential so
8485
// shared-proxy tenants with different Cursor accounts cannot collide on a parent thread id.
@@ -118,6 +119,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
118119
{
119120
provider,
120121
headers: incoming.headers,
122+
translatorBudget: incoming.translatorBudget,
121123
requestDeclaresFullAccess: cursorRequestDeclaresFullAccess(activeRequest),
122124
},
123125
activeRequest,
@@ -178,7 +180,16 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
178180
} catch (err) {
179181
if (isCursorBenignCancelError(err)) return;
180182
const partialUsage = (err as { partialUsage?: import("../types").OcxUsage }).partialUsage;
181-
emit({ type: "error", message: safeCursorTransportError(err), ...(partialUsage ? { usage: partialUsage } : {}) });
183+
emit({
184+
type: "error",
185+
message: isTranslatorBudgetExceededError(err)
186+
? "upstream translation buffer exceeded the safe limit"
187+
: safeCursorTransportError(err),
188+
...(isTranslatorBudgetExceededError(err)
189+
? { status: 502, errorType: "upstream_error", code: "translation_buffer_limit" }
190+
: {}),
191+
...(partialUsage ? { usage: partialUsage } : {}),
192+
});
182193
}
183194
},
184195
};

‎src/adapters/cursor/framing.ts‎

Lines changed: 55 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ export interface DecodedConnectFrames {
2626
remainder: Uint8Array;
2727
}
2828

29+
interface CopyReservation {
30+
commitRetained(): void;
31+
release(): void;
32+
}
33+
2934
export class ConnectFrameError extends Error {
3035
constructor(
3136
public readonly code: ConnectFrameErrorCode,
@@ -65,19 +70,35 @@ export function encodeConnectFrame(
6570
return frame;
6671
}
6772

68-
export function tryDecodeConnectFrame(input: Uint8Array, offset = 0): DecodedConnectFrame | null {
73+
export function tryDecodeConnectFrame(
74+
input: Uint8Array,
75+
offset = 0,
76+
maxPayloadBytes = MAX_CONNECT_FRAME_PAYLOAD_BYTES,
77+
reservePayloadCopy?: (bytes: number) => CopyReservation | undefined,
78+
): DecodedConnectFrame | null {
6979
assertOffset(input, offset);
7080
if (input.length - offset < CONNECT_FRAME_HEADER_BYTES) return null;
7181

7282
const view = new DataView(input.buffer, input.byteOffset + offset, input.byteLength - offset);
7383
const flags = view.getUint8(0);
7484
const length = view.getUint32(1, false);
85+
if (length > maxPayloadBytes) {
86+
throw new ConnectFrameError("payload_too_large", `Connect frame payload too large: ${length}`);
87+
}
7588
const readBytes = CONNECT_FRAME_HEADER_BYTES + length;
7689
if (input.length - offset < readBytes) return null;
7790

7891
const payloadStart = offset + CONNECT_FRAME_HEADER_BYTES;
7992
const payloadEnd = payloadStart + length;
80-
const payload = input.slice(payloadStart, payloadEnd);
93+
const reservation = reservePayloadCopy?.(length);
94+
let payload: Uint8Array;
95+
try {
96+
payload = input.slice(payloadStart, payloadEnd);
97+
reservation?.commitRetained();
98+
} catch (error) {
99+
reservation?.release();
100+
throw error;
101+
}
81102
return {
82103
frame: {
83104
flags,
@@ -108,21 +129,49 @@ export function decodeConnectFrames(input: Uint8Array): ConnectFrame[] {
108129
return frames;
109130
}
110131

111-
export function decodeAvailableConnectFrames(input: Uint8Array): DecodedConnectFrames {
132+
export function decodeAvailableConnectFrames(
133+
input: Uint8Array,
134+
maxPayloadBytes = MAX_CONNECT_FRAME_PAYLOAD_BYTES,
135+
availableFrameSlots = Number.POSITIVE_INFINITY,
136+
reservePayloadCopy?: (bytes: number) => CopyReservation | undefined,
137+
): DecodedConnectFrames {
112138
const frames: ConnectFrame[] = [];
113139
let offset = 0;
114-
while (offset < input.length) {
115-
const decoded = tryDecodeConnectFrame(input, offset);
140+
while (offset < input.length && frames.length < availableFrameSlots) {
141+
const decoded = tryDecodeConnectFrame(input, offset, maxPayloadBytes, reservePayloadCopy);
116142
if (!decoded) break;
117143
frames.push(decoded.frame);
118144
offset += decoded.readBytes;
119145
}
146+
const remainderBytes = offset === input.length ? 0 : bufferedPayloadBytes(input, offset);
147+
const remainderReservation = reservePayloadCopy?.(remainderBytes);
148+
let remainder: Uint8Array;
149+
try {
150+
remainder = offset === input.length ? new Uint8Array() : input.slice(offset);
151+
remainderReservation?.commitRetained();
152+
} catch (error) {
153+
remainderReservation?.release();
154+
throw error;
155+
}
120156
return {
121157
frames,
122-
remainder: offset === input.length ? new Uint8Array() : input.slice(offset),
158+
remainder,
123159
};
124160
}
125161

162+
function bufferedPayloadBytes(input: Uint8Array, start: number): number {
163+
let offset = start;
164+
let payloadBytes = 0;
165+
while (input.byteLength - offset >= CONNECT_FRAME_HEADER_BYTES) {
166+
const length = new DataView(input.buffer, input.byteOffset + offset, input.byteLength - offset).getUint32(1, false);
167+
const available = Math.min(length, input.byteLength - offset - CONNECT_FRAME_HEADER_BYTES);
168+
payloadBytes += available;
169+
if (available < length) break;
170+
offset += CONNECT_FRAME_HEADER_BYTES + length;
171+
}
172+
return payloadBytes;
173+
}
174+
126175
function assertOffset(input: Uint8Array, offset: number): void {
127176
if (!Number.isInteger(offset) || offset < 0 || offset > input.length) {
128177
throw new ConnectFrameError("invalid_offset", `Invalid Connect frame offset: ${offset}`);

‎src/adapters/cursor/kv-store.ts‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import type { TranslatorBudget } from "../../lib/translator-budget";
2+
13
export interface CursorKvStore {
24
get(key: string): Uint8Array | undefined;
35
set(key: string, value: Uint8Array): void;
@@ -7,19 +9,44 @@ function cloneBytes(value: Uint8Array): Uint8Array {
79
return new Uint8Array(value);
810
}
911

10-
export function createCursorKvStore(seed: Record<string, Uint8Array> = {}): CursorKvStore {
12+
export function createCursorKvStore(
13+
seed: Record<string, Uint8Array>,
14+
budget: TranslatorBudget,
15+
): CursorKvStore {
1116
const values = new Map<string, Uint8Array>();
17+
const encoder = new TextEncoder();
18+
const sizes = new Map<string, number>();
1219
for (const [key, value] of Object.entries(seed)) {
20+
const bytes = encoder.encode(key).byteLength + value.byteLength;
21+
budget.chargeRetained(bytes, { kind: "cursor_kv" });
1322
values.set(key, cloneBytes(value));
23+
sizes.set(key, bytes);
1424
}
1525

1626
return {
1727
get(key) {
1828
const value = values.get(key);
19-
return value ? cloneBytes(value) : undefined;
29+
if (!value) return undefined;
30+
budget.chargeRetained(value.byteLength, { kind: "cursor_kv" });
31+
const cloned = cloneBytes(value);
32+
queueMicrotask(() => budget.releaseRetained(value.byteLength, { kind: "cursor_kv" }));
33+
return cloned;
2034
},
2135
set(key, value) {
22-
values.set(key, cloneBytes(value));
36+
const nextBytes = encoder.encode(key).byteLength + value.byteLength;
37+
const previousBytes = sizes.get(key) ?? 0;
38+
const reservation = budget.reserveTransient(nextBytes, { kind: "cursor_kv" });
39+
let cloned: Uint8Array;
40+
try {
41+
cloned = cloneBytes(value);
42+
} catch (error) {
43+
reservation.release();
44+
throw error;
45+
}
46+
values.set(key, cloned);
47+
sizes.set(key, nextBytes);
48+
reservation.commitRetained();
49+
budget.releaseRetained(previousBytes, { kind: "cursor_kv" });
2350
},
2451
};
2552
}

0 commit comments

Comments
 (0)