Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
// Record/replay for legacy Chat Completions and native Responses. Legacy
// cassettes keep their text-only contract; Responses attests exact decoded
// HTTP entity bytes and binds the full transport policy.
import { createHash, randomUUID } from "node:crypto";
import {
existsSync,
mkdirSync,
readFileSync,
renameSync,
unlinkSync,
writeFileSync,
} from "node:fs";
import { createServer, type IncomingMessage, type Server } from "node:http";
import { dirname } from "node:path";
import { containsSecret } from "./env";
import { normalizeIds } from "./harness";
import type { CapturedRequest, ModelServerHandle } from "./model-server";
import {
applyRequestPolicy,
createInvocationBudget,
DEFAULT_TRANSPORT_LIMITS,
type InvocationBudget,
type PublicHeaderProfile,
publicHeaderProfile,
type TransportIdentity,
transportIdentity,
type WireApi,
} from "./transport";
import { instructionContentTextOf } from "./wire";
export interface ResponseByteEvidence {
bodyBase64: string;
byteCount: number;
sha256: string;
status: number;
contentType: string | null;
}
export interface CassetteRound {
round: number;
requestHash: string;
digest: { systemChars: number; toolCount: number; roles: string[]; lastUserText: string };
/** Legacy Chat payload and decoded compatibility field for Responses. */
sse: string;
usage?: Record<string, unknown>;
inboundPath?: string;
requestBodyBase64?: string;
requestByteCount?: number;
requestSha256?: string;
response?: ResponseByteEvidence;
terminalStatus?: "completed" | "incomplete" | "failed" | "missing";
/** Chat Completions HTTP status. Absent on historical text-only cassettes. */
httpStatus?: number;
}
export interface Cassette {
scenario: string;
provider: string;
model: string;
resolvedModel?: string;
recordedAt: string;
rounds: CassetteRound[];
/** Absent means the historical Chat Completions text-only schema. */
wireApi?: WireApi;
transport?: TransportIdentity;
attempts?: CassetteAttempt[];
}
export interface CassetteAttempt {
attempt: number;
phase: "admission" | "forward" | "response" | "complete";
status: "rejected" | "failed" | "recorded";
detail?: string;
}
interface ResponsesTerminal {
status: CassetteRound["terminalStatus"];
usage?: Record<string, unknown>;
model: string | null;
}
function sha256(value: string | Uint8Array): string {
return createHash("sha256").update(value).digest("hex");
}
function ssePayloads(sse: string): unknown[] {
const payloads: unknown[] = [];
for (const line of sse.split(/\r?\n/)) {
if (!line.startsWith("data:")) continue;
const payload = line.slice(5).trim();
if (!payload || payload === "[DONE]") continue;
try {
payloads.push(JSON.parse(payload));
} catch {
// A protocol-specific parser decides whether malformed data is fatal.
}
}
return payloads;
}
export function modelFromSse(sse: string, wireApi: WireApi = "chat-completions"): string | null {
if (wireApi === "responses") return responsesTerminalFromSse(sse).model;
for (const line of sse.split("\n")) {
if (!line.startsWith("data: ")) continue;
const payload = line.slice(6).trim();
if (payload === "[DONE]") break;
try {
const model = (JSON.parse(payload) as { model?: unknown }).model;
if (typeof model === "string" && model.length > 0) return model;
} catch {
// Legacy parser ignores malformed chunks.
}
}
return null;
}
export function usageFromSse(
sse: string,
wireApi: WireApi = "chat-completions",
): Record<string, unknown> | undefined {
if (wireApi === "responses") return responsesTerminalFromSse(sse).usage;
let usage: Record<string, unknown> | undefined;
for (const line of sse.split("\n")) {
if (!line.startsWith("data:")) continue;
const payload = line.slice(5).trim();
if (payload === "[DONE]") break;
try {
const candidate = (JSON.parse(payload) as { usage?: unknown }).usage;
if (candidate !== null && typeof candidate === "object" && !Array.isArray(candidate)) {
usage = candidate as Record<string, unknown>;
}
} catch {
// Legacy parser ignores malformed chunks.
}
}
return usage;
}
export function responsesTerminalFromSse(sse: string): ResponsesTerminal {
const terminals = ssePayloads(sse).filter((payload) => {
const type = (payload as { type?: unknown }).type;
return (
type === "response.completed" || type === "response.incomplete" || type === "response.failed"
);
}) as Array<{ type: string; response?: unknown }>;
if (terminals.length === 0) return { status: "missing", model: null };
if (terminals.length !== 1) throw new Error("Responses stream has duplicate terminal events");
const terminal = terminals[0];
const response =
terminal.response && typeof terminal.response === "object"
? (terminal.response as Record<string, unknown>)
: {};
const usage =
response.usage && typeof response.usage === "object" && !Array.isArray(response.usage)
? (response.usage as Record<string, unknown>)
: undefined;
const model = typeof response.model === "string" && response.model ? response.model : null;
const responseStatus = response.status;
if (
(terminal.type === "response.completed" && responseStatus !== "completed") ||
(terminal.type === "response.incomplete" && responseStatus !== "incomplete") ||
(terminal.type === "response.failed" && responseStatus !== "failed")
) {
throw new Error("Responses terminal event/status mismatch");
}
const status =
terminal.type === "response.completed"
? "completed"
: terminal.type === "response.incomplete"
? "incomplete"
: "failed";
return { status, usage, model };
}
/** Historical Chat hash. Keep byte-for-byte semantics for existing cassettes. */
export function hashRequest(body: Record<string, unknown>): string {
const messages = (body.messages ?? []) as Array<Record<string, unknown>>;
const tools = (body.tools ?? []) as Array<{ function?: { name?: string } }>;
const canonical = JSON.stringify(
normalizeIds({
messages: messages.map((m) => ({ role: m.role, content: m.content, tc: m.tool_calls })),
tools: tools.map((t) => t.function?.name),
}),
);
return sha256(canonical).slice(0, 16);
}
/** Transport-bound Chat hash. Includes tool schemas, temperature, and model options. */
export function hashChatRequest(body: Record<string, unknown>): string {
return sha256(JSON.stringify(normalizeIds(body)));
}
export function hashResponsesRequest(body: Record<string, unknown>): string {
return sha256(JSON.stringify(normalizeIds(body)));
}
function hashRoundRequest(
body: Record<string, unknown>,
wireApi: WireApi,
transportBound: boolean,
): string {
if (wireApi === "responses") return hashResponsesRequest(body);
return transportBound ? hashChatRequest(body) : hashRequest(body);
}
function responseInput(body: Record<string, unknown>): Array<Record<string, unknown>> {
return Array.isArray(body.input) ? (body.input as Array<Record<string, unknown>>) : [];
}
function digestOf(body: Record<string, unknown>, wireApi: WireApi): CassetteRound["digest"] {
if (wireApi === "chat-completions") {
const messages = (body.messages ?? []) as Array<Record<string, unknown>>;
const lastUser = [...messages].reverse().find((m) => m.role === "user");
return {
systemChars: instructionContentTextOf(messages).length,
toolCount: ((body.tools ?? []) as unknown[]).length,
roles: messages.map((m) => String(m.role)),
lastUserText: String(lastUser?.content ?? "").slice(0, 120),
};
}
const input = responseInput(body);
const instructions = typeof body.instructions === "string" ? body.instructions : "";
const instructionItems = input.filter(
(item) => item.role === "system" || item.role === "developer",
);
const instructionText = instructionItems
.map((item) =>
typeof item.content === "string" ? item.content : JSON.stringify(item.content ?? ""),
)
.join("\n");
const lastUser = [...input].reverse().find((item) => item.role === "user");
return {
systemChars: [instructions, instructionText].filter(Boolean).join("\n").length,
toolCount: ((body.tools ?? []) as unknown[]).length,
roles: input.map((item) => String(item.role ?? item.type ?? "?")),
lastUserText: String(lastUser?.content ?? "").slice(0, 120),
};
}
function captureRequest(
round: number,
body: Record<string, unknown>,
wireApi: WireApi,
): CapturedRequest {
const digest = digestOf(body, wireApi);
const tools = (body.tools ?? []) as Array<{ name?: string; function?: { name?: string } }>;
return {
round,
systemChars: digest.systemChars,
toolNames: tools.map((tool) => tool.name ?? tool.function?.name ?? "?"),
messages:
wireApi === "responses"
? responseInput(body).map((item) => ({
role: String(item.role ?? item.type ?? "?"),
content:
typeof item.content === "string" ? item.content : JSON.stringify(item.content ?? ""),
toolCalls: item.type === "function_call" ? [String(item.name ?? "?")] : [],
}))
: ((body.messages ?? []) as Array<Record<string, unknown>>).map((message) => ({
role: String(message.role),
content:
typeof message.content === "string"
? message.content
: JSON.stringify(message.content ?? ""),
toolCalls: ((message.tool_calls ?? []) as Array<{ function?: { name?: string } }>).map(
(tool) => tool.function?.name ?? "?",
),
})),
raw: body,
};
}
function validateResponseEvidence(round: CassetteRound): void {
if (!round.response) throw new Error(`Responses round ${round.round} has no byte evidence`);
const bytes = Buffer.from(round.response.bodyBase64, "base64");
if (bytes.toString("base64") !== round.response.bodyBase64) {
throw new Error(`Responses round ${round.round} has invalid base64`);
}
if (bytes.byteLength !== round.response.byteCount) {
throw new Error(`Responses round ${round.round} response byte count mismatch`);
}
if (sha256(bytes) !== round.response.sha256) {
throw new Error(`Responses round ${round.round} response sha256 mismatch`);
}
const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
if (round.sse !== decoded) throw new Error(`Responses round ${round.round} sse/bytes mismatch`);
if (containsSecret(decoded)) throw new Error(`Responses round ${round.round} contains a secret`);
if (
!Number.isInteger(round.response.status) ||
round.response.status < 100 ||
round.response.status > 599
) {
throw new Error(`Responses round ${round.round} has invalid HTTP status`);
}
if (
round.response.contentType !== null &&
(typeof round.response.contentType !== "string" || /[\r\n\0]/.test(round.response.contentType))
) {
throw new Error(`Responses round ${round.round} has invalid content type`);
}
if (!round.inboundPath || !round.requestBodyBase64 || !round.requestSha256) {
throw new Error(`Responses round ${round.round} has incomplete request evidence`);
}
const requestBytes = Buffer.from(round.requestBodyBase64, "base64");
if (requestBytes.toString("base64") !== round.requestBodyBase64) {
throw new Error(`Responses round ${round.round} request base64 invalid`);
}
if (
requestBytes.byteLength !== round.requestByteCount ||
sha256(requestBytes) !== round.requestSha256
) {
throw new Error(`Responses round ${round.round} request byte evidence mismatch`);
}
const requestText = new TextDecoder("utf-8", { fatal: true }).decode(requestBytes);
if (containsSecret(requestText))
throw new Error(`Responses round ${round.round} request contains a secret`);
const request = JSON.parse(requestText) as Record<string, unknown>;
if (hashResponsesRequest(request) !== round.requestHash) {
throw new Error(`Responses round ${round.round} normalized request hash mismatch`);
}
}
export function validateCassette(cassette: Cassette): void {
const declaredWireApi = (cassette as { wireApi?: unknown }).wireApi;
const hasResponsesEvidence = cassette.rounds.some((round) =>
[
"inboundPath",
"requestBodyBase64",
"requestByteCount",
"requestSha256",
"response",
"terminalStatus",
].some((field) => field in round),
);
const hasResponsesSseEvents = cassette.rounds.some((round) =>
ssePayloads(round.sse).some((payload) => {
const type = (payload as { type?: unknown }).type;
return typeof type === "string" && type.startsWith("response.");
}),
);
if (declaredWireApi === undefined) {
if (cassette.transport || hasResponsesEvidence || hasResponsesSseEvents) {
throw new Error(
"cassette has transport or Responses evidence without a wireApi discriminator",
);
}
assertChatResolvedModel(cassette);
return;
}
if (declaredWireApi !== "chat-completions" && declaredWireApi !== "responses") {
throw new Error(`unknown cassette wireApi: ${String(declaredWireApi)}`);
}
if (!cassette.transport || cassette.transport.wireApi !== declaredWireApi) {
throw new Error("cassette wireApi does not match its transport identity");
}
const expected = transportIdentity({
wireApi: declaredWireApi,
maxOutputTokens:
declaredWireApi === "responses"
? (cassette.transport.requestPolicy.maxOutputTokens ?? undefined)
: undefined,
limits: cassette.transport.limits,
publicHeadersSha256: cassette.transport.publicHeadersSha256,
// Reconstruct the policy that was RECORDED, not the factory default — a
// judge cassette stamped with its true zero-retry policy must survive
// replay instead of failing the identity check here.
...(declaredWireApi === "chat-completions"
? { retryPolicy: cassette.transport.retryPolicy }
: {}),
});
if (JSON.stringify(expected) !== JSON.stringify(cassette.transport)) {
throw new Error(`${declaredWireApi} cassette transport identity is invalid`);
}
if (declaredWireApi === "chat-completions") {
if (hasResponsesEvidence || hasResponsesSseEvents) {
throw new Error("Chat cassette contains Responses-only round evidence");
}
assertChatResolvedModel(cassette);
return;
}
for (const round of cassette.rounds) {
validateResponseEvidence(round);
if (!cassette.transport.inboundPaths.includes(round.inboundPath as string)) {
throw new Error(`Responses round ${round.round} inbound path mismatch`);
}
const request = JSON.parse(
new TextDecoder("utf-8", { fatal: true }).decode(
Buffer.from(round.requestBodyBase64 as string, "base64"),
),
) as Record<string, unknown>;
if (
JSON.stringify(applyRequestPolicy(request, cassette.transport)) !== JSON.stringify(request)
) {
throw new Error(`Responses round ${round.round} request policy mismatch`);
}
const terminal = responsesTerminalFromSse(round.sse);
if (
terminal.status !== round.terminalStatus ||
terminal.model !== (cassette.resolvedModel ?? terminal.model)
) {
throw new Error(`Responses round ${round.round} terminal metadata mismatch`);
}
if (JSON.stringify(terminal.usage) !== JSON.stringify(round.usage)) {
throw new Error(`Responses round ${round.round} usage mismatch`);
}
}
}
function assertChatResolvedModel(cassette: Cassette): void {
for (const round of cassette.rounds) {
const model = modelFromSse(round.sse, "chat-completions");
if (model && cassette.resolvedModel && model !== cassette.resolvedModel) {
throw new Error(`Chat round ${round.round} model mismatch`);
}
}
}
export function readCassette(file: string): Cassette {
const cassette = JSON.parse(readFileSync(file, "utf8")) as Cassette;
validateCassette(cassette);
return cassette;
}
export function attemptsFromEndpoint(
endpoint: Pick<ModelServerHandle, "attempts"> | undefined,
): CassetteAttempt[] {
return (endpoint?.attempts ?? []).map((attempt) => ({
attempt: attempt.attempt,
phase: attempt.phase as CassetteAttempt["phase"],
status: attempt.status as CassetteAttempt["status"],
...(typeof attempt.detail === "string" ? { detail: attempt.detail } : {}),
}));
}
export function adoptRetryEvidence(
success: Cassette,
attemptLists: ReadonlyArray<readonly CassetteAttempt[] | undefined>,
): Cassette {
const attempts = attemptLists
.flatMap((list) => list ?? [])
.map((attempt, index) => ({ ...attempt, attempt: index }));
return { ...success, attempts };
}
export function mergeRetryCassettes(success: Cassette, prior: readonly Cassette[]): Cassette {
return adoptRetryEvidence(success, [
...prior.map((cassette) => cassette.attempts),
success.attempts,
]);
}
export function readCassetteEvidence(file: string): Cassette {
try {
return readCassette(file);
} catch {
return JSON.parse(readFileSync(file, "utf8")) as Cassette;
}
}
export function writeCassette(file: string, cassette: Cassette): void {
validateCassette(cassette);
const payload = `${JSON.stringify(cassette, null, "\t")}\n`;
if (containsSecret(payload)) {
throw new Error(`refus d'écrire la cassette ${file} : le blob contient une valeur secrète`);
}
mkdirSync(dirname(file), { recursive: true });
const temporary = `${file}.tmp-${process.pid}-${randomUUID()}`;
writeFileSync(temporary, payload, "utf8");
try {
renameSync(temporary, file);
} catch (error) {
if (existsSync(temporary)) unlinkSync(temporary);
throw error;
}
}
export function cassetteExists(file: string): boolean {
return existsSync(file);
}
async function readIncoming(req: IncomingMessage, maxBytes: number): Promise<Buffer> {
const chunks: Buffer[] = [];
let total = 0;
for await (const chunk of req) {
const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
total += bytes.byteLength;
if (total > maxBytes) throw new Error(`request body exceeds ${maxBytes} bytes`);
chunks.push(bytes);
}
return Buffer.concat(chunks);
}
async function readResponseBytes(response: Response, maxBytes: number): Promise<Buffer> {
if (!response.body) return Buffer.alloc(0);
const chunks: Uint8Array[] = [];
let total = 0;
const reader = response.body.getReader();
for (;;) {
const { done, value } = await reader.read();
if (done) break;
total += value.byteLength;
if (total > maxBytes) {
await reader.cancel();
throw new Error(`response body exceeds ${maxBytes} bytes`);
}
chunks.push(value);
}
return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
}
function decodeUtf8(bytes: Uint8Array): string {
return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
}
function upstreamUrl(base: string, suffix: string): string {
return `${base.replace(/\/$/, "")}${suffix}`;
}
export async function startRecorder(options: {
upstream: string;
file?: string;
scenario: string;
provider: string;
model: string;
wireApi?: WireApi;
transport?: TransportIdentity;
publicHeaders?: PublicHeaderProfile;
budget?: InvocationBudget;
}): Promise<ModelServerHandle> {
const wireApi = options.wireApi ?? "chat-completions";
const transport =
options.transport ??
(wireApi === "responses" ? transportIdentity({ wireApi, maxOutputTokens: 2048 }) : undefined);
if (wireApi === "responses" && !transport) throw new Error("Responses requires transport policy");
const effectiveTransport =
transport ??
transportIdentity({ wireApi: "chat-completions", limits: DEFAULT_TRANSPORT_LIMITS });
if (effectiveTransport.wireApi !== wireApi) {
throw new Error("wireApi does not match transport identity");
}
const budget = options.budget ?? createInvocationBudget(effectiveTransport.limits);
const configuredPublicHeaders = options.publicHeaders ?? publicHeaderProfile({});
if (configuredPublicHeaders.sha256 !== effectiveTransport.publicHeadersSha256) {
throw new Error("configured public headers do not match transport identity");
}
const requests: CapturedRequest[] = [];
const rounds: CassetteRound[] = [];
const attempts: CassetteAttempt[] = [];
let resolvedModel: string | null = null;
let round = 0;
let attemptNumber = 0;
const recordedAt = new Date().toISOString();
const writeCurrentCassette = (): void => {
if (!options.file || rounds.length === 0) return;
writeCassette(options.file, {
scenario: options.scenario,
provider: options.provider,
model: options.model,
...(resolvedModel ? { resolvedModel } : {}),
recordedAt,
rounds: [...rounds].sort((left, right) => left.round - right.round),
...(wireApi === "responses" || options.wireApi !== undefined || options.transport
? { wireApi, transport: effectiveTransport }
: {}),
attempts: [...attempts],
});
};
const retainAttempt = (attempt: CassetteAttempt): void => {
attempts.push(attempt);
if (!options.file) return;
const attemptFile = `${options.file}.attempts.json`;
const payload = `${JSON.stringify({ schema: 1, attempts }, null, "\t")}\n`;
if (containsSecret(payload)) throw new Error("attempt receipt contains a secret");
mkdirSync(dirname(attemptFile), { recursive: true });
writeFileSync(attemptFile, payload, "utf8");
// A later failure has no raw round to append, but it may still have reached
// the provider. Refresh only the safe attempt metadata on the last complete
// cassette so measurement accounting cannot silently lose that attempt.
writeCurrentCassette();
};
const server: Server = createServer(async (req, res) => {
const attempt = attemptNumber++;
const inboundPath = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
if (!effectiveTransport.inboundPaths.includes(inboundPath)) {
retainAttempt({
attempt,
phase: "admission",
status: "rejected",
detail: "protocol/path mismatch",
});
res.writeHead(404, { "content-type": "application/json" });
res.end('{"error":"workbench proxy: protocol/path mismatch"}');
return;
}
let incoming: Buffer;
try {
incoming = await readIncoming(req, effectiveTransport.limits.maxRequestBytes);
} catch (error) {
retainAttempt({
attempt,
phase: "admission",
status: "rejected",
detail: "request body too large",
});
res.writeHead(413, { "content-type": "application/json" });
res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
return;
}
let parsed: Record<string, unknown>;
try {
parsed = JSON.parse(decodeUtf8(incoming)) as Record<string, unknown>;
} catch {
retainAttempt({
attempt,
phase: "admission",
status: "rejected",
detail: "request is not UTF-8 JSON",
});
res.writeHead(400, { "content-type": "application/json" });
res.end('{"error":"workbench proxy: request body is not UTF-8 JSON"}');
return;
}
let effectiveBody: Record<string, unknown>;
try {
effectiveBody = applyRequestPolicy(parsed, effectiveTransport);
} catch {
retainAttempt({
attempt,
phase: "admission",
status: "rejected",
detail: "request policy mismatch",
});
res.writeHead(400, { "content-type": "application/json" });
res.end('{"error":"workbench proxy: request policy mismatch"}');
return;
}
const effectiveBytes =
wireApi === "responses" ? Buffer.from(JSON.stringify(effectiveBody)) : incoming;
if (containsSecret(decodeUtf8(effectiveBytes))) {
retainAttempt({
attempt,
phase: "admission",
status: "rejected",
detail: "secret in request body",
});
res.writeHead(400, { "content-type": "application/json" });
res.end('{"error":"workbench proxy: secret in request body"}');
return;
}
try {
budget.reserveRequest(effectiveBytes.byteLength);
} catch (error) {
retainAttempt({
attempt,
phase: "admission",
status: "rejected",
detail: "invocation budget rejected request",
});
res.writeHead(429, { "content-type": "application/json" });
res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
return;
}
const myRound = round++;
requests.push(captureRequest(myRound, effectiveBody, wireApi));
const auth = req.headers.authorization;
const controller = new AbortController();
const untrack = budget.track(controller);
const timeoutMs = Math.min(effectiveTransport.limits.requestTimeoutMs, budget.remainingMs());
const timer = setTimeout(() => controller.abort(), timeoutMs);
let upstreamResponse: Response;
let responseBytes: Buffer;
try {
upstreamResponse = await fetch(
upstreamUrl(options.upstream, effectiveTransport.upstreamPathSuffix),
{
method: "POST",
redirect: "error",
headers: {
"content-type": "application/json",
accept: "text/event-stream",
...(auth ? { authorization: auth } : {}),
...configuredPublicHeaders.headers,
},
body: new Uint8Array(effectiveBytes),
signal: controller.signal,
},
);
responseBytes = await readResponseBytes(
upstreamResponse,
effectiveTransport.limits.maxResponseBytes,
);
} catch {
retainAttempt({
attempt,
phase: "forward",
status: "failed",
detail: "redirect, timeout, transport, or body limit",
});
res.writeHead(502, { "content-type": "application/json" });
res.end(
wireApi === "chat-completions"
? '{"error":"workbench proxy: upstream redirect or transport failure"}'
: '{"error":"workbench proxy: upstream redirect, timeout, or transport failure"}',
);
return;
} finally {
clearTimeout(timer);
untrack();
}
let decoded: string;
try {
decoded = decodeUtf8(responseBytes);
} catch {
retainAttempt({
attempt,
phase: "response",
status: "failed",
detail: "response is not valid UTF-8",
});
res.writeHead(502, { "content-type": "application/json" });
res.end('{"error":"workbench proxy: upstream body is not valid UTF-8"}');
return;
}
if (containsSecret(decoded) || (auth && decoded.includes(auth))) {
retainAttempt({
attempt,
phase: "response",
status: "failed",
detail: "unsafe upstream response",
});
res.writeHead(502, { "content-type": "application/json" });
res.end('{"error":"workbench proxy: unsafe upstream response"}');
return;
}
let terminal: ResponsesTerminal | undefined;
try {
terminal = wireApi === "responses" ? responsesTerminalFromSse(decoded) : undefined;
} catch {
retainAttempt({
attempt,
phase: "response",
status: "failed",
detail: "invalid Responses terminal sequence",
});
res.writeHead(502, { "content-type": "application/json" });
res.end('{"error":"workbench proxy: invalid Responses terminal sequence"}');
return;
}
const observedModel = terminal?.model ?? modelFromSse(decoded, wireApi);
if (observedModel) {
if (resolvedModel && observedModel !== resolvedModel) {
retainAttempt({
attempt,
phase: "response",
status: "failed",
detail: "resolved model changed mid-measurement",
});
res.writeHead(502, { "content-type": "application/json" });
res.end('{"error":"workbench proxy: resolved model changed mid-measurement"}');
return;
}
resolvedModel = observedModel;
}
const usage = terminal?.usage ?? usageFromSse(decoded, wireApi);
const responseEvidence: ResponseByteEvidence = {
bodyBase64: responseBytes.toString("base64"),
byteCount: responseBytes.byteLength,
sha256: sha256(responseBytes),
status: upstreamResponse.status,
contentType: upstreamResponse.headers.get("content-type"),
};
const recordedRound: CassetteRound = {
round: myRound,
requestHash: hashRoundRequest(
effectiveBody,
wireApi,
Boolean(options.transport || options.wireApi),
),
digest: digestOf(effectiveBody, wireApi),
sse: decoded,
...(usage ? { usage } : {}),
...(wireApi === "responses"
? {
inboundPath,
requestBodyBase64: effectiveBytes.toString("base64"),
requestByteCount: effectiveBytes.byteLength,
requestSha256: sha256(effectiveBytes),
response: responseEvidence,
terminalStatus: terminal?.status ?? "missing",
}
: { httpStatus: responseEvidence.status }),
};
rounds.push(recordedRound);
retainAttempt({ attempt, phase: "complete", status: "recorded" });
const headers: Record<string, string> =
wireApi === "chat-completions" ? { "content-type": "text/event-stream" } : {};
if (wireApi === "responses" && responseEvidence.contentType) {
headers["content-type"] = responseEvidence.contentType;
}
res.writeHead(responseEvidence.status, headers);
res.end(responseBytes);
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
const addr = server.address();
if (!addr || typeof addr === "string") throw new Error("recorder has no address");
return {
url: `http://127.0.0.1:${addr.port}/v1`,
requests,
attempts,
get resolvedModel() {
return resolvedModel;
},
close: () => {
budget.abort();
server.close();
},
};
}
export interface ReplayHandle extends ModelServerHandle {
staleRounds: number[];
servedRounds: Array<{
round: number;
terminalStatus: CassetteRound["terminalStatus"] | "legacy-or-unknown";
usage: Record<string, unknown> | null;
status: number;
contentType: string | null;
bodySha256: string;
}>;
assertFresh: () => void;
}
export function strictReplayRequested(): boolean {
return process.env.WB_STRICT === "1";
}
export async function startReplay(options: {
file: string;
onStale?: "warn" | "throw";
}): Promise<ReplayHandle> {
const cassette = readCassette(options.file);
const wireApi = cassette.wireApi ?? "chat-completions";
const transport =
cassette.transport ??
transportIdentity({ wireApi: "chat-completions", limits: DEFAULT_TRANSPORT_LIMITS });
const requests: CapturedRequest[] = [];
const staleRounds: number[] = [];
const servedRounds: ReplayHandle["servedRounds"] = [];
let round = 0;
const server: Server = createServer(async (req, res) => {
const inboundPath = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
if (!transport.inboundPaths.includes(inboundPath)) {
staleRounds.push(round);
res.writeHead(404, { "content-type": "application/json" });
res.end('{"error":"workbench replay: protocol/path mismatch"}');
return;
}
let incoming: Buffer;
try {
incoming = await readIncoming(req, transport.limits.maxRequestBytes);
} catch {
res.writeHead(413, { "content-type": "application/json" });
res.end('{"error":"workbench replay: request too large"}');
return;
}
let parsed: Record<string, unknown>;
try {
parsed = JSON.parse(decodeUtf8(incoming)) as Record<string, unknown>;
} catch {
res.writeHead(400, { "content-type": "application/json" });
res.end('{"error":"workbench replay: request is not UTF-8 JSON"}');
return;
}
let effectiveBody: Record<string, unknown>;
try {
effectiveBody = applyRequestPolicy(parsed, transport);
} catch {
staleRounds.push(round);
res.writeHead(409, { "content-type": "application/json" });
res.end('{"error":"workbench replay: request policy mismatch"}');
return;
}
const myRound = round++;
requests.push(captureRequest(myRound, effectiveBody, wireApi));
const stored = cassette.rounds[myRound];
if (!stored) {
staleRounds.push(myRound);
res.writeHead(409, { "content-type": "application/json" });
res.end('{"error":"workbench replay: cassette exhausted"}');
return;
}
const requestHash = hashRoundRequest(
effectiveBody,
wireApi,
Boolean(cassette.transport) && wireApi !== "responses",
);
if (
requestHash !== stored.requestHash ||
(stored.inboundPath && stored.inboundPath !== inboundPath)
) {
staleRounds.push(myRound);
}
if (wireApi === "responses" && stored.response) {
const bytes = Buffer.from(stored.response.bodyBase64, "base64");
const observed = responsesTerminalFromSse(decodeUtf8(bytes));
servedRounds.push({
round: myRound,
terminalStatus: observed.status,
usage: observed.usage ?? null,
status: stored.response.status,
contentType: stored.response.contentType,
bodySha256: sha256(bytes),
});
const headers: Record<string, string> = {};
if (stored.response.contentType) headers["content-type"] = stored.response.contentType;
res.writeHead(stored.response.status, headers);
res.end(bytes);
return;
}
const httpStatus = stored.httpStatus ?? 200;
res.writeHead(httpStatus, { "content-type": "text/event-stream" });
servedRounds.push({
round: myRound,
terminalStatus: "legacy-or-unknown",
usage: usageFromSse(stored.sse) ?? null,
status: httpStatus,
contentType: "text/event-stream",
bodySha256: sha256(Buffer.from(stored.sse)),
});
res.end(stored.sse);
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
const addr = server.address();
if (!addr || typeof addr === "string") throw new Error("replay has no address");
const strict = options.onStale === "throw" || strictReplayRequested();
return {
url: `http://127.0.0.1:${addr.port}/v1`,
requests,
staleRounds,
servedRounds,
assertFresh: () => {
if (round < cassette.rounds.length) {
for (let missing = round; missing < cassette.rounds.length; missing += 1) {
if (!staleRounds.includes(missing)) staleRounds.push(missing);
}
}
if (staleRounds.length === 0) return;
const message =
`cassette ${options.file} périmée aux rounds ${staleRounds.join(", ")} — ` +
"les instructions, schémas, historique, protocole ou politique de transport ont changé";
if (strict) throw new Error(message);
process.stderr.write(`[workbench] ${message}\n`);
},
close: () => server.close(),
};
}