Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 35 additions & 26 deletions src/server/responses/combo-stream-preflight.ts
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,8 @@ function snapshotMetadataIsSafe(snapshot: Record<string, unknown>): boolean {
if (typeof snapshot.tool_choice === "string" && !["none", "auto", "required"].includes(snapshot.tool_choice)) return false;
if (snapshot.tool_choice != null && typeof snapshot.tool_choice !== "string") {
if (!recordWithOnly(snapshot.tool_choice, ["type", "name", "namespace", "function"])
|| !["function", "custom", "tool_search"].includes(String(snapshot.tool_choice.type))
|| typeof snapshot.tool_choice.type !== "string"
|| !["function", "custom", "tool_search"].includes(snapshot.tool_choice.type)
|| (snapshot.tool_choice.name != null && typeof snapshot.tool_choice.name !== "string")
|| (snapshot.tool_choice.namespace != null && typeof snapshot.tool_choice.namespace !== "string")) return false;
const selected = snapshot.tool_choice.function;
Expand All @@ -160,7 +161,8 @@ function snapshotMetadataIsSafe(snapshot: Record<string, unknown>): boolean {
|| (snapshot.text.verbosity != null && typeof snapshot.text.verbosity !== "string")) return false;
const format = snapshot.text.format;
if (format != null && (!recordWithOnly(format, ["type", "name", "description", "schema", "strict"])
|| !["text", "json_object", "json_schema"].includes(String(format.type))
|| typeof format.type !== "string"
|| !["text", "json_object", "json_schema"].includes(format.type)
|| (format.name != null && typeof format.name !== "string")
|| (format.description != null && typeof format.description !== "string")
|| (format.schema != null && !isRecord(format.schema))
Expand Down Expand Up @@ -665,31 +667,38 @@ export async function preflightComboStreamResponse(
onOpaquePayload: () => { outputCommitted = true; },
onParsedPayload: payload => {
if (terminalStatus !== undefined || outputCommitted || retryableTerminalPayload) return;
if (payload !== null && typeof payload === "object" && !Array.isArray(payload)
&& (payload as { type?: unknown }).type === "response.created") responseCreated = true;
const retryable = retryableTerminalFor(payload);
const matchedBareError = retryable && payload !== null && typeof payload === "object"
&& !Array.isArray(payload) && (payload as { type?: unknown }).type === "error";
// A zero-output bare error is terminal evidence. Explicit client errors stay
// committed; unknown and retryable upstream failures may advance the combo.
const heldReasoning = options?.requiredToolPrelude && requiredToolReasoningPrelude(payload);
if (heldReasoning) holdDeadline ??= new Promise(resolve => {
holdTimer = setTimeout(() => resolve("hold-expired"), COMBO_REQUIRED_TOOL_REASONING_HOLD_MS);
});
if (comboStreamPayloadCommitsOutput(payload) && !matchedBareError && !heldReasoning) outputCommitted = true;
if (options?.requiredToolPrelude && payload && typeof payload === "object") {
const event = payload as { type?: unknown; response?: { output?: unknown; error?: { code?: unknown; retryable?: unknown } } };
const output = event.response?.output;
const contractFailure = event.type === "response.failed" && event.response?.error?.code === REQUIRED_TOOL_CONTRACT_CODE
&& event.response.error.retryable !== false && Array.isArray(output) && output.every(item =>
item !== null && typeof item === "object" && !Array.isArray(item)
&& ["message", "reasoning"].includes((item as { type: string }).type));
// Other lifecycle/terminal snapshots can hide effects too. Only our checked contract
// failure may discard a terminal-only text snapshot that was held in its entirety.
if (output !== undefined && (!Array.isArray(output) || output.length > 0) && !contractFailure) outputCommitted = true;
try {
if (payload !== null && typeof payload === "object" && !Array.isArray(payload)
&& (payload as { type?: unknown }).type === "response.created") responseCreated = true;
const retryable = retryableTerminalFor(payload);
const matchedBareError = retryable && payload !== null && typeof payload === "object"
&& !Array.isArray(payload) && (payload as { type?: unknown }).type === "error";
// A zero-output bare error is terminal evidence. Explicit client errors stay
// committed; unknown and retryable upstream failures may advance the combo.
const heldReasoning = options?.requiredToolPrelude && requiredToolReasoningPrelude(payload);
if (heldReasoning) holdDeadline ??= new Promise(resolve => {
holdTimer = setTimeout(() => resolve("hold-expired"), COMBO_REQUIRED_TOOL_REASONING_HOLD_MS);
});
if (comboStreamPayloadCommitsOutput(payload) && !matchedBareError && !heldReasoning) outputCommitted = true;
if (options?.requiredToolPrelude && payload && typeof payload === "object") {
const event = payload as { type?: unknown; response?: { output?: unknown; error?: { code?: unknown; retryable?: unknown } } };
const output = event.response?.output;
const contractFailure = event.type === "response.failed" && event.response?.error?.code === REQUIRED_TOOL_CONTRACT_CODE
&& event.response.error.retryable !== false && Array.isArray(output) && output.every(item =>
item !== null && typeof item === "object" && !Array.isArray(item)
&& ["message", "reasoning"].includes((item as { type: string }).type));
// Other lifecycle/terminal snapshots can hide effects too. Only our checked contract
// failure may discard a terminal-only text snapshot that was held in its entirety.
if (output !== undefined && (!Array.isArray(output) || output.length > 0) && !contractFailure) outputCommitted = true;
}
if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
if (retryable) retryableTerminalPayload = payload as Record<string, unknown>;
} catch {
// The generic inspector swallows observer errors. Replay requires a successful proof
// of no effects, so a failed classification keeps this attempt and its original bytes.
outputCommitted = true;
retryableTerminalPayload = undefined;
}
if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
if (retryable) retryableTerminalPayload = payload as Record<string, unknown>;
},
onTerminal: status => { terminalStatus = status; },
});
Expand Down
2 changes: 2 additions & 0 deletions structure/transports/responses-combo-boundaries.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,8 @@ resend gate decides. Control frames (`response.in_progress`, `response.queued`,
not advance the stage. Once output commits the stream or a terminal ends inspection, a later read
error belongs to the relay and never reaches the resend gate. A lifecycle event with output, an error, incomplete details, a contradictory
status, a replay-unsafe mark, unknown event or snapshot fields, or unsafe nested metadata commits the original stream.
Snapshot selector types are validated without coercion. A replay-classification exception also
commits the original stream, preserving its bytes and preventing a replacement attempt.
An SSE event name that conflicts with its JSON type, an opaque frame,
or an unfinished output/error/terminal frame on a rejected read also keeps the original bytes and
read error; the last SSE event field is authoritative. A clean EOF before output or a terminal is offered only to the native reset recovery
Expand Down
53 changes: 53 additions & 0 deletions tests/routing/combo-stream-preflight.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1277,6 +1277,59 @@ describe("combo stream preflight", () => {
})).toBe(true);
});

for (const field of ["tool_choice", "text.format"] as const) {
for (const separateChunks of [false, true]) {
test(`malformed ${field} cannot discard hosted output before failure (separate chunks: ${separateChunks})`, async () => {
const malformed = { type: { toString: null } };
const response = {
id: "completed-hosted-work", status: "in_progress",
output: [{ type: "mcp_call", id: "completed-call", status: "completed", name: "act", arguments: "{}", output: "done" }],
...(field === "tool_choice" ? { tool_choice: malformed } : { text: { format: malformed } }),
};
const payloads = [
{ type: "response.created", response },
{ type: "response.failed", response: { id: response.id, status: "failed", output: [], error: { code: "server_error", message: "busy" } } },
];
const frames = payloads.map(payload => `data: ${JSON.stringify(payload)}\n\n`);
const original = new Response(new ReadableStream<Uint8Array>({ start(controller) {
for (const frame of separateChunks ? frames : [frames.join("")]) controller.enqueue(new TextEncoder().encode(frame));
controller.close();
} }), { headers: { "content-type": "text/event-stream" } });
const result = await preflightComboStreamResponse(original, { model: "m1", provider: "a" });
expect(result.kind).toBe("accepted");
expect(result.response.status).toBe(200);
expect(await result.response.text()).toBe(frames.join(""));
expect(comboStreamPayloadCommitsOutput(payloads[0])).toBe(true);
});
}
}

test("a replay classifier exception commits the original stream", async () => {
const payloads = [
{ type: "response.created", response: { id: "original", status: "in_progress", output: [] } },
{ type: "response.failed", response: { status: "failed", output: [], error: { code: "server_error", message: "busy" } } },
];
const original = sse(...payloads);
const expected = await original.clone().text();
const result = await preflightComboStreamResponse(original, { model: "m1", provider: "a" }, payload => {
if ((payload as { type: string }).type === "response.created") throw new Error("classification unavailable");
return true;
});
expect(result.kind).toBe("accepted");
expect(result.response.status).toBe(200);
expect(await result.response.text()).toBe(expected);
});

test("valid selector metadata with no output still permits terminal failover", async () => {
const result = await preflightComboStreamResponse(sse(
{ type: "response.created", response: { id: "empty", status: "in_progress", output: [], tool_choice: { type: "function", name: "read" }, text: { format: { type: "text" } } } },
{ type: "response.failed", response: { status: "failed", output: [], error: { code: "server_error", message: "busy" } } },
), { model: "m1", provider: "a" });
expect(result.kind).toBe("failed");
expect(result.response.status).toBe(502);
await result.response.body?.cancel();
});

for (const type of ["response.created", "response.in_progress", "response.queued", "response.heartbeat"]) {
for (const extra of [
{ output_text: "already produced" },
Expand Down
Loading