Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
import type {
BoundedToolResult,
BuildFollowUpTranscriptInput,
ExecutedToolResult,
ToolCall,
} from "./toolLoopTypes";
/**
* Pure transcript builder for the server-owned tool loop (spec §5.2).
*
* `serializeBoundedToolResult` serializes one executed tool result to JSON text
* and, when it exceeds a UTF-8 byte budget, truncates it at code-point
* boundaries with a `[TRUNCATED N BYTES BY OMNIROUTE]` marker whose own bytes
* count against the budget.
*
* `buildFollowUpSourceBody` appends the assistant tool-call turn and the
* bounded tool results to the source-format `messages` array. It never mutates
* its inputs, rejects orphan/mixed calls before building anything, and consumes
* the total output budget per-tool in result order.
*/
export const MAX_RESULT_BYTES_PER_TOOL = 32_768;
export const MAX_RESULT_BYTES_TOTAL = 65_536;
const NON_SERIALIZABLE_ERROR = "Tool result is not JSON-serializable";
function assertValidBudget(name: string, value: number): void {
if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
throw new RangeError(`${name} must be a non-negative finite integer, got ${value}`);
}
}
function markerFor(droppedBytes: number): string {
return `[TRUNCATED ${droppedBytes} BYTES BY OMNIROUTE]`;
}
/**
* Returns the longest code-point-aligned prefix of `text` whose UTF-8 byte
* length does not exceed `maxBytes`. Iterating `for...of` over a string yields
* full code points, so surrogate pairs (astral CJK, emoji) are never split and
* the result is always valid UTF-8.
*/
function truncateToCodePointBoundary(text: string, maxBytes: number): string {
let out = "";
let bytes = 0;
for (const codePoint of text) {
const codePointBytes = Buffer.byteLength(codePoint, "utf8");
if (bytes + codePointBytes > maxBytes) break;
out += codePoint;
bytes += codePointBytes;
}
return out;
}
function projectSerializable(value: unknown): unknown {
if (value === undefined) return null;
if (value instanceof Error) return { error: value.message };
if (typeof value === "bigint") return value.toString();
return value;
}
export function serializeBoundedToolResult(value: unknown, maxBytes: number): BoundedToolResult {
assertValidBudget("maxBytes", maxBytes);
const projected = projectSerializable(value);
let serialized: string | undefined;
try {
const raw = JSON.stringify(projected);
serialized = typeof raw === "string" ? raw : undefined;
} catch {
serialized = undefined;
}
// Top-level function/symbol (JSON.stringify returns undefined, not a string)
// and serialization exceptions (cycles, nested BigInt, exotic objects) all
// resolve to the fixed non-serializable error shape.
if (serialized === undefined) {
serialized = JSON.stringify({ error: NON_SERIALIZABLE_ERROR });
}
const originalBytes = Buffer.byteLength(serialized, "utf8");
if (originalBytes <= maxBytes) {
return { text: serialized, truncated: false, originalBytes };
}
const fullMarker = markerFor(originalBytes);
const fullMarkerBytes = Buffer.byteLength(fullMarker, "utf8");
// The full marker alone does not fit: return its code-point-safe UTF-8 prefix
// (maxBytes 0 yields the empty string).
if (maxBytes <= fullMarkerBytes) {
return {
text: truncateToCodePointBoundary(fullMarker, maxBytes),
truncated: true,
originalBytes,
};
}
// Reserve marker space first, then take the longest valid prefix of the text.
// `dropped <= originalBytes` so markerFor(dropped) is never longer than the
// reserved marker; the total therefore stays within maxBytes.
const prefixBudget = maxBytes - fullMarkerBytes;
const prefix = truncateToCodePointBoundary(serialized, prefixBudget);
const droppedBytes = originalBytes - Buffer.byteLength(prefix, "utf8");
return {
text: prefix + markerFor(droppedBytes),
truncated: true,
originalBytes,
};
}
function safeStringifyArguments(value: Record<string, unknown>): string {
try {
const raw = JSON.stringify(value);
return typeof raw === "string" ? raw : "{}";
} catch {
return "{}";
}
}
function validateCallsAndResults(toolCalls: ToolCall[], results: ExecutedToolResult[]): void {
if (toolCalls.length !== results.length) {
throw new Error(
`buildFollowUpSourceBody requires toolCalls (${toolCalls.length}) and results (${results.length}) to have the same length`
);
}
const callIds = toolCalls.map((call) => call.id);
const resultIds = results.map((result) => result.id);
if (new Set(callIds).size !== callIds.length) {
throw new Error("buildFollowUpSourceBody requires unique tool call ids");
}
if (new Set(resultIds).size !== resultIds.length) {
throw new Error("buildFollowUpSourceBody requires unique tool result ids");
}
const resultIdSet = new Set(resultIds);
for (const id of callIds) {
if (!resultIdSet.has(id)) {
throw new Error(
`buildFollowUpSourceBody requires every tool call to have a matching result (missing: ${id})`
);
}
}
for (const result of results) {
const call = toolCalls.find((c) => c.id === result.id);
if (call && call.name !== result.name) {
throw new Error(
`buildFollowUpSourceBody: result name "${result.name}" for id "${result.id}" does not match tool call name "${call.name}"`
);
}
}
}
function extractOpenAIMessage(response: Record<string, unknown>): Record<string, unknown> | null {
const choice = Array.isArray(response.choices) ? (response.choices[0] as unknown) : null;
if (choice && typeof choice === "object") {
const message = (choice as Record<string, unknown>).message;
if (message && typeof message === "object" && !Array.isArray(message)) {
return message as Record<string, unknown>;
}
}
if (
response.message &&
typeof response.message === "object" &&
!Array.isArray(response.message)
) {
return response.message as Record<string, unknown>;
}
return null;
}
/**
* Returns the assistant tool_calls exactly as the previous response carried
* them (provenance preserved), restricted to calls with a matching result.
* Falls back to reconstructing the OpenAI wire shape from the parsed
* `toolCalls` when the response has no tool_calls of its own.
*
* When the previous response does carry tool_calls, validates that each
* call ID appears exactly once with the correct name (fails closed on
* partial, duplicate, or mismatched entries).
*/
function resolveOpenAIAssistantToolCalls(
previousResponse: Record<string, unknown>,
toolCalls: ToolCall[],
matchedIds: Set<string>
): unknown[] {
let originalToolCalls: unknown[] = [];
const prevMessage = extractOpenAIMessage(previousResponse);
if (prevMessage && Array.isArray(prevMessage.tool_calls)) {
originalToolCalls = prevMessage.tool_calls as unknown[];
}
if (originalToolCalls.length === 0 && toolCalls.length > 0) {
originalToolCalls = toolCalls.map((call) => ({
id: call.id,
type: "function",
function: { name: call.name, arguments: safeStringifyArguments(call.arguments) },
}));
}
// Validate when previous response carries its own tool_calls.
const hasOwnToolCalls =
prevMessage && Array.isArray(prevMessage.tool_calls) && prevMessage.tool_calls.length > 0;
if (hasOwnToolCalls) {
const idCounts = new Map<string, number>();
const idNames = new Map<string, string>();
for (const raw of originalToolCalls) {
if (!raw || typeof raw !== "object") continue;
const rec = raw as Record<string, unknown>;
const id = typeof rec.id === "string" ? rec.id : undefined;
if (id === undefined) continue;
idCounts.set(id, (idCounts.get(id) ?? 0) + 1);
if (idNames.has(id)) continue;
const fn = rec.function;
if (
fn &&
typeof fn === "object" &&
typeof (fn as Record<string, unknown>).name === "string"
) {
idNames.set(id, (fn as Record<string, unknown>).name as string);
}
}
for (const call of toolCalls) {
if (!matchedIds.has(call.id)) continue;
const count = idCounts.get(call.id) ?? 0;
if (count !== 1) {
throw new Error(
`buildFollowUpSourceBody: previous response tool_calls must contain exactly one match per call ID (id "${call.id}" has ${count})`
);
}
const prevName = idNames.get(call.id);
if (prevName !== undefined && prevName !== call.name) {
throw new Error(
`buildFollowUpSourceBody: previous response tool_call "${call.id}" name "${prevName}" does not match tool call name "${call.name}"`
);
}
}
}
return originalToolCalls.filter((call) => {
if (!call || typeof call !== "object") return false;
const record = call as Record<string, unknown>;
const id = typeof record.id === "string" ? record.id : record.call_id;
return typeof id === "string" && matchedIds.has(id);
});
}
/**
* Resolves tool_use blocks from the Claude previous response. When content
* blocks are present, validates that each call ID appears exactly once with
* the correct name (fails closed on partial, duplicate, or mismatched).
* Non-tool content blocks (text, thinking, reasoning) are preserved in their
* original order; only tool_use blocks are filtered to matched IDs.
*/
function resolveClaudeToolUseBlocks(
previousResponse: Record<string, unknown>,
toolCalls: ToolCall[],
matchedIds: Set<string>
): unknown[] {
if (Array.isArray(previousResponse.content)) {
const blocks = previousResponse.content as unknown[];
// Validate when content has tool_use blocks for matched IDs.
const idCounts = new Map<string, number>();
const idNames = new Map<string, string>();
for (const block of blocks) {
if (!block || typeof block !== "object") continue;
const rec = block as Record<string, unknown>;
if (rec.type !== "tool_use" || typeof rec.id !== "string") continue;
if (!matchedIds.has(rec.id)) continue;
idCounts.set(rec.id, (idCounts.get(rec.id) ?? 0) + 1);
if (idNames.has(rec.id)) continue;
if (typeof rec.name === "string") {
idNames.set(rec.id, rec.name);
}
}
for (const call of toolCalls) {
if (!matchedIds.has(call.id)) continue;
const count = idCounts.get(call.id) ?? 0;
if (count !== 1) {
throw new Error(
`buildFollowUpSourceBody: previous response content must contain exactly one tool_use match per call ID (id "${call.id}" has ${count})`
);
}
const prevName = idNames.get(call.id);
if (prevName !== undefined && prevName !== call.name) {
throw new Error(
`buildFollowUpSourceBody: previous response tool_use "${call.id}" name "${prevName}" does not match tool call name "${call.name}"`
);
}
}
// Match prepareClaudeRequest: keep all thinking/signature blocks, keep
// ordinary content only before the first tool_use, and retain only the
// tool_use blocks whose results are being replayed.
let foundToolUse = false;
const replayBlocks: unknown[] = [];
for (const block of blocks) {
if (!block || typeof block !== "object") continue;
const rec = block as Record<string, unknown>;
if (rec.type === "tool_use") {
foundToolUse = true;
if (typeof rec.id === "string" && matchedIds.has(rec.id)) replayBlocks.push(block);
continue;
}
if (rec.type === "thinking" || rec.type === "redacted_thinking" || !foundToolUse) {
replayBlocks.push(block);
}
}
return replayBlocks;
}
return toolCalls.map((call) => ({
type: "tool_use",
id: call.id,
name: call.name,
input: call.arguments,
}));
}
export function buildFollowUpSourceBody(
input: BuildFollowUpTranscriptInput
): Record<string, unknown> {
const { sourceBody, previousResponse, toolCalls, results, sourceFormat } = input;
const maxResultBytes = input.maxResultBytes ?? MAX_RESULT_BYTES_PER_TOOL;
const maxTotalResultBytes = input.maxTotalResultBytes ?? MAX_RESULT_BYTES_TOTAL;
if (sourceFormat !== "openai" && sourceFormat !== "claude") {
throw new Error('sourceFormat must be "openai" or "claude"');
}
assertValidBudget("maxResultBytes", maxResultBytes);
assertValidBudget("maxTotalResultBytes", maxTotalResultBytes);
if (!Array.isArray(sourceBody.messages)) {
throw new Error("buildFollowUpSourceBody requires sourceBody.messages array");
}
validateCallsAndResults(toolCalls, results);
// When a pre-serialized map is provided (from the loop's own budget pass),
// use its text verbatim instead of re-serializing. Otherwise serialize with
// the standard budget logic.
const serializedResultTextById = input.serializedResultTextById;
let boundedResults: BoundedToolResult[];
if (serializedResultTextById) {
boundedResults = results.map((result) => {
const text = serializedResultTextById.get(result.id) ?? "";
return { text, truncated: false, originalBytes: Buffer.byteLength(text, "utf8") };
});
} else {
let remainingBytes = maxTotalResultBytes;
boundedResults = results.map((result) => {
const itemMaxBytes = Math.min(maxResultBytes, remainingBytes);
const bounded = serializeBoundedToolResult(result.result, itemMaxBytes);
remainingBytes -= Buffer.byteLength(bounded.text, "utf8");
return bounded;
});
}
const matchedIds = new Set(results.map((result) => result.id));
const messages = [...(sourceBody.messages as unknown[])];
if (sourceFormat === "openai") {
const prevMessage = extractOpenAIMessage(previousResponse);
const previousContent = prevMessage && "content" in prevMessage ? prevMessage.content : null;
const assistantMessage: Record<string, unknown> = {
role: "assistant",
content: previousContent ?? null,
};
const assistantToolCalls = resolveOpenAIAssistantToolCalls(
previousResponse,
toolCalls,
matchedIds
);
if (assistantToolCalls.length > 0) {
assistantMessage.tool_calls = assistantToolCalls;
}
messages.push(assistantMessage);
boundedResults.forEach((bounded, index) => {
messages.push({
role: "tool",
tool_call_id: results[index].id,
content: bounded.text,
});
});
return { ...sourceBody, messages, stream: false };
}
// Claude Messages: the original assistant tool_use turn, then a separate
// user tool_result message. A tool_result must never share the assistant
// content — Anthropic rejects it (openai-to-claude.ts:323).
const toolUseBlocks = resolveClaudeToolUseBlocks(previousResponse, toolCalls, matchedIds);
messages.push({ role: "assistant", content: toolUseBlocks });
messages.push({
role: "user",
content: boundedResults.map((bounded, index) => ({
type: "tool_result",
tool_use_id: results[index].id,
content: bounded.text,
})),
});
return { ...sourceBody, messages };
}