The library data in this demo is synthetic software test data.
Idle
``` **controller.mjs** ```javascript // The same controller runs in the browser and in the synthetic local checks. export class ToolController { constructor({ send, runTool, status, fatal, setTimer = setTimeout, clearTimer = clearTimeout }) { Object.assign(this, { send, runTool, status, fatal, setTimer, clearTimer }); this.epoch = 0; this.rounds = 0; this.counter = 0; this.responses = new Map(); this.pending = null; this.closed = false; } abortPending() { if (!this.pending) return; this.pending.abort.abort(); if (this.pending.timer) this.clearTimer(this.pending.timer); this.pending = null; } close() { this.closed = true; this.epoch++; this.abortPending(); this.responses.clear(); } fail(message) { if (this.closed) return; this.status(message); this.close(); this.fatal(message); } interrupt() { if (this.closed) return; this.epoch++; this.rounds = 0; this.abortPending(); this.status("Speech detected; interrupted result discarded"); } async handle(event) { if (this.closed) return; if (event.type === "error") { this.fail(`Realtime error: ${event.error?.code || event.error?.message || "unknown"}`); return; } if (event.type === "input_audio_buffer.speech_started") { this.interrupt(); return; } if (event.type === "response.created") { if (event.response?.id) this.responses.set(event.response.id, this.epoch); return; } if (event.type === "conversation.item.done") { const p = this.pending; const id = event.item?.id; if (!p || p.epoch !== this.epoch || !p.acks.has(id)) return; p.acks.delete(id); if (p.acks.size === 0) { if (p.timer) this.clearTimer(p.timer); this.pending = null; if (!p.abort.signal.aborted && !this.closed && p.epoch === this.epoch) { this.status("All tool outputs acknowledged; resuming response"); this.send({ type: "response.create" }); } } return; } if (event.type !== "response.done") return; const response = event.response; const id = response?.id; const responseEpoch = this.responses.get(id); this.responses.delete(id); if (responseEpoch === undefined || responseEpoch !== this.epoch) return; this.status(`Response ${id}: ${response.status || "unknown"}`); if (response.status !== "completed") return; // Never execute partial/cancelled calls. const calls = (response.output || []).filter(item => item.type === "function_call"); if (!calls.length) return; if (this.pending) { this.fail("Overlapping tool batches in one turn"); return; } if (calls.length > 8 || ++this.rounds > 3) { this.fail("Tool call or round bound reached"); return; } const ids = new Set(); for (const call of calls) { if (call.status !== "completed" || !call.call_id || ids.has(call.call_id)) { this.fail("Incomplete or repeated function call ID"); return; } ids.add(call.call_id); } const p = { epoch: this.epoch, abort: new AbortController(), acks: new Set(), timer: null }; this.pending = p; this.status(`Executing ${calls.length} read-only local call(s) from ${id}`); const outputs = await Promise.all(calls.map(async call => { try { return { call, result: await this.runTool(call, p.abort.signal) }; } catch { return { call, result: { ok: false, error: "Local lookup failed" } }; } })); if (this.closed || this.pending !== p || p.epoch !== this.epoch || p.abort.signal.aborted) return; try { for (const { call, result } of outputs) { const itemId = `tool_output_${++this.counter}`; p.acks.add(itemId); this.send({ type: "conversation.item.create", event_id: `tool_event_${this.counter}`, item: { id: itemId, type: "function_call_output", call_id: call.call_id, output: JSON.stringify(result) } }); this.status(`Sent result for ${call.call_id}`); } p.timer = this.setTimer(() => this.fail("Tool output acknowledgement timed out"), 8000); } catch { this.fail("Could not send tool outputs"); } } } ``` **protocol-check.mjs** ```javascript import assert from "node:assert/strict"; import { ToolController } from "./controller.mjs"; const deferred = () => { let resolve, reject; const promise = new Promise((a, b) => { resolve = a; reject = b; }); return { promise, resolve, reject }; }; const tick = () => new Promise(resolve => setImmediate(resolve)); const call = (id, name = "get_demo_hours") => ({ type: "function_call", status: "completed", call_id: id, name, arguments: "{}" }); const created = id => ({ type: "response.created", response: { id } }); const done = (id, status, output = []) => ({ type: "response.done", response: { id, status, output } }); function harness(runTool = async x => ({ ok: true, value: x.name })) { const sent = [], statuses = [], failures = []; const timers = new Map(); let nextTimer = 0; const controller = new ToolController({ send: e => sent.push(e), runTool, status: s => statuses.push(s), fatal: e => failures.push(e), setTimer: callback => { const id = ++nextTimer; timers.set(id, callback); return id; }, clearTimer: id => timers.delete(id) }); return { controller, sent, statuses, failures, timers }; } // Mixed audio/message output, two asynchronous calls resolved in reverse order. { const a = deferred(), b = deferred(); const h = harness(x => x.call_id === "call_A" ? a.promise : b.promise); await h.controller.handle(created("resp_1")); const work = h.controller.handle(done("resp_1", "completed", [ { type: "message", status: "completed", content: [{ type: "output_audio", transcript: "Checking." }] }, call("call_A"), call("call_B", "get_demo_address") ])); b.resolve({ ok: true, value: "address" }); await tick(); assert.equal(h.sent.length, 0, "first finished lookup must not send or resume early"); a.resolve({ ok: true, value: "hours" }); await work; assert.deepEqual(h.sent.map(x => x.item?.call_id), ["call_A", "call_B"]); assert.equal(h.sent.filter(x => x.type === "response.create").length, 0); await h.controller.handle({ type: "conversation.item.done", item: { id: h.sent[1].item.id } }); assert.equal(h.sent.filter(x => x.type === "response.create").length, 0); await h.controller.handle({ type: "conversation.item.done", item: { id: h.sent[0].item.id } }); assert.equal(h.sent.filter(x => x.type === "response.create").length, 1, "one resume after both item acknowledgements"); } // One local lookup error does not erase the other result. { const h = harness(async x => { if (x.call_id === "bad") throw Error("synthetic failure"); return { ok: true, value: "fixture" }; }); await h.controller.handle(created("resp_2")); await h.controller.handle(done("resp_2", "completed", [call("bad"), call("good")])); assert.equal(JSON.parse(h.sent[0].item.output).ok, false); assert.equal(JSON.parse(h.sent[1].item.output).ok, true); for (const e of h.sent.slice()) await h.controller.handle({ type: "conversation.item.done", item: { id: e.item.id } }); assert.equal(h.sent.filter(x => x.type === "response.create").length, 1); } // Partial/cancelled responses never dispatch a call. for (const status of ["failed", "incomplete", "cancelled"]) { const h = harness(); await h.controller.handle(created(`resp_${status}`)); await h.controller.handle(done(`resp_${status}`, status, [call("ignored")])); assert.equal(h.sent.length, 0); } // Distinct rounds are bounded, and missing/duplicate IDs are rejected. { const h = harness(); for (let i = 1; i <= 3; i++) { await h.controller.handle(created(`round_${i}`)); await h.controller.handle(done(`round_${i}`, "completed", [call(`call_${i}`)])); const last = h.sent.at(-1); await h.controller.handle({ type: "conversation.item.done", item: { id: last.item.id } }); } await h.controller.handle(created("round_4")); await h.controller.handle(done("round_4", "completed", [call("too_many")])); assert.match(h.failures[0], /bound/); assert.equal(h.sent.filter(x => x.type === "response.create").length, 3); } { const h = harness(); await h.controller.handle(created("dup")); await h.controller.handle(done("dup", "completed", [call("same"), call("same")])); assert.match(h.failures[0], /repeated/); } // User speech or Stop invalidates in-flight lookups and ignores their late results. for (const mode of ["speech", "stop"]) { const d = deferred(), h = harness(() => d.promise); await h.controller.handle(created(`resp_${mode}`)); const work = h.controller.handle(done(`resp_${mode}`, "completed", [call("late")])); if (mode === "speech") await h.controller.handle({ type: "input_audio_buffer.speech_started" }); else h.controller.close(); d.resolve({ ok: true, value: "late fixture" }); await work; assert.equal(h.sent.length, 0); } // A late response completion or acknowledgement from the interrupted turn cannot resume it. { const h = harness(); await h.controller.handle(created("old")); await h.controller.handle({ type: "input_audio_buffer.speech_started" }); await h.controller.handle(done("old", "completed", [call("late_call")])); assert.equal(h.sent.length, 0); await h.controller.handle(created("new")); await h.controller.handle(done("new", "completed", [call("fresh_call")])); const output = h.sent[0]; await h.controller.handle({ type: "input_audio_buffer.speech_started" }); await h.controller.handle({ type: "conversation.item.done", item: { id: output.item.id } }); assert.equal(h.sent.filter(x => x.type === "response.create").length, 0); } // Missing server acknowledgement closes instead of speculatively resuming. { const h = harness(); await h.controller.handle(created("no_ack")); await h.controller.handle(done("no_ack", "completed", [call("one")])); assert.equal(h.timers.size, 1); [...h.timers.values()][0](); assert.match(h.failures[0], /timed out/); assert.equal(h.sent.filter(x => x.type === "response.create").length, 0); } console.log("Synthetic controller checks passed: ordering, single resume, error isolation, bounds and interruption."); ``` **browser-check.mjs** ```javascript import assert from "node:assert/strict"; import fs from "node:fs"; import vm from "node:vm"; import { ToolController } from "./controller.mjs"; const html = fs.readFileSync(new URL("./index.html", import.meta.url), "utf8"); const script = html.match(/