@specific.dev/spectest 0.111.0 → 0.112.0

package/README.md

@@ -296,3 +296,44 @@ The classic viewer shows `mail.latest()` with Email/JSON tabs; JSON contains
 helper arguments and the returned value. The SPA retains its nested presentation.
 `annotate` always returns a box for the helper boundary; it does not attach views
 to arbitrary recorded results. See `spectest docs /services` for a complete example.
+
+## SIP phone calls
+
+```ts
+const phone = await ctx.phone({
+  endpoint: "sip:5060",
+  from: "sip:caller@spectest.test",
+  language: "sv",
+});
+await phone.call("receptionist");
+await phone.say("Hej! Jag vill boka en tid.");
+await phone.hangup();
+```
+
+The phone offers all installed codecs, preferring Opus then higher sample rates,
+with G.711 and other legacy codecs available as fallbacks. Recordings use 48 kHz
+mono PCM for capture and continuously encode it as 48 kbps VBR Opus/WebM.
+Encoding runs off the SIP callback thread and writes no intermediate WAV;
+the original audio timeline and waveform data are preserved.
+
+Supertonic 3 runs locally using models installed in the golden image. Each
+`call`, `say`, and `hangup` is recorded. One continuous recording captures
+both sides from dialing through hangup, including replies and pauses between
+steps. Each `say` clip starts when speech is transmitted, skipping generation
+time, and ends when that step completes. Both `call(destination, { waitFor })`
+and `say(text, { waitFor })` poll application state, then wait for incoming
+silence. For `call`, polling starts after the call connects, allowing the greeting
+to finish within the call step. For `say`, polling starts after outgoing playback.
+Without `waitFor`, `call` ends when connected and `say` ends after outgoing playback. The quiet
+period (700 ms), poll interval (100 ms), and wait timeout (30 seconds) are
+internal defaults for now. `waitFor` may return a nonempty transcript string
+instead of `true`; after the silence wait, it appears as **Response** below **Caller** in an indented chat row beneath the waveform. Return `false` or `""` to keep waiting. Your test supplies the text
+from application state or a fake; an async callback can wait and then return it.
+Playback starts muted and remembers your mute choice across steps, with
+overlapping blue caller and violet recipient waveforms and replay controls.
+Both sides play together from the same recording. Step playback trims silence at the edges of
+utterances and waited greetings; greetings also show the approximate time to
+first audio. Hangup steps have no player. The complete recording remains stored. Outgoing
+text remains a plain transcript; incoming audio is not transcribed automatically. Calls
+close and recordings finalize automatically at case end. This initial API requires
+SDK 0.112.0 and a golden image with phone support.

package/dist/components/replay-websocket.d.ts

@@ -9,6 +9,28 @@ export type WebSocketKey<S = unknown> = ((message: ReplayWebSocketMessage) => Ma
         state: S;
         key: MatchKey;
     };
+} | {
+    initial: S;
+    /** Candidate keys, not mandatory inputs. Emit multiple keys to normalize stream chunking. */
+    input(state: S, message: ReplayWebSocketMessage): {
+        state: S;
+    } & ({
+        key: MatchKey;
+        keys?: never;
+    } | {
+        keys: MatchKey[];
+        key?: never;
+    });
+    /** Runs on real output during recording and saved output during replay.
+     * Select the latest candidate as a timing anchor during recording only. */
+    output(state: S, message: ReplayWebSocketMessage): {
+        state: S;
+        anchorPreviousInput: boolean;
+    };
+};
+export type WebSocketMatcher = ((message: ReplayWebSocketMessage) => string | null) & {
+    candidates?: (message: ReplayWebSocketMessage) => string[];
+    output?: (message: ReplayWebSocketMessage) => boolean;
 };
 export interface WebSocketTiming {
     /** Number of emitted input keys required. Zero means connection opening. */
@@ -25,6 +47,10 @@ export interface CassetteWebSocket {
     request: CassetteRequest;
     protocol?: string;
     inputs: string[];
+    /** Only output-selected candidates are required in this mode. */
+    inputMode?: "anchors";
+    /** One-based occurrence of each selected hash in the full candidate stream. */
+    inputOccurrences?: number[];
     messages: CassetteWebSocketMessage[];
     /** Absent while recording a connection that is still open. */
     close?: WebSocketTiming & {
@@ -35,14 +61,14 @@ export interface CassetteWebSocket {
 }
 export declare function validateWebSocketKey<S>(key: WebSocketKey<S> | undefined): void;
 /** Clone once per connection; never retain incoming payloads. */
-export declare function websocketMatcher<S>(key?: WebSocketKey<S>): (message: ReplayWebSocketMessage) => string | null;
+export declare function websocketMatcher<S>(key?: WebSocketKey<S>): WebSocketMatcher;
 export declare function validateWebSocketRecording(record: CassetteWebSocket): void;
 export interface WebSocketSession {
     cancel(): void;
 }
 export declare function replayWebSocket(args: {
     recording: CassetteWebSocket;
-    match: (message: ReplayWebSocketMessage) => string | null;
+    match: WebSocketMatcher;
     label: string;
     timeoutMs: number;
     lifetime?: FakeWebSocketLifetime;
@@ -59,7 +85,7 @@ export declare function recordWebSocket(args: {
     headers: Record<string, string>;
     protocols: string[];
     request: CassetteRequest;
-    match: (message: ReplayWebSocketMessage) => string | null;
+    match: WebSocketMatcher;
     redact(value: string): string;
     secrets: {
         ref: string;

package/dist/components/replay-websocket.js

@@ -8,17 +8,61 @@ const require = createRequire(import.meta.url);
 const { WebSocket } = require(join(dirname(require.resolve("ws/package.json")), "index.js"));
 const MAX_BUFFER = 16 * 1024 * 1024;
 const MAX_PENDING = 1024;
+const MAX_CANDIDATE_KEYS = 65536;
+function occurrence(counts, key) {
+    if (!counts.has(key) && counts.size >= MAX_CANDIDATE_KEYS)
+        throw new Error("WebSocket candidate key limit exceeded");
+    const count = (counts.get(key) ?? 0) + 1;
+    counts.set(key, count);
+    return count;
+}
+function synchronous(value, label) {
+    if (value && typeof value === "object" && "then" in value) {
+        if (value instanceof Promise)
+            void value.catch(() => { });
+        throw new Error(`websocketKey ${label} must be synchronous`);
+    }
+    if (!value || typeof value !== "object" || !("state" in value))
+        throw new Error(`websocketKey ${label} must return state`);
+}
 export function validateWebSocketKey(key) {
     if (key === undefined || typeof key === "function")
         return;
-    if (!key || typeof key !== "object" || !("initial" in key) || typeof key.reduce !== "function") {
-        throw new Error("websocketKey must be a synchronous function or { initial, reduce }");
+    if (!key || typeof key !== "object" || !("initial" in key)
+        || !("reduce" in key && typeof key.reduce === "function" && !("input" in key) && !("output" in key)
+            || "input" in key && typeof key.input === "function" && "output" in key && typeof key.output === "function" && !("reduce" in key))) {
+        throw new Error("websocketKey must be a synchronous function, { initial, reduce }, or { initial, input, output }");
     }
     structuredClone(key.initial);
 }
 /** Clone once per connection; never retain incoming payloads. */
 export function websocketMatcher(key) {
     let state = key && typeof key !== "function" ? structuredClone(key.initial) : undefined;
+    if (key && typeof key === "object" && "input" in key) {
+        const input = (message) => {
+            const next = key.input(state, message);
+            synchronous(next, "input");
+            if (("key" in next) === ("keys" in next) || "keys" in next && !Array.isArray(next.keys))
+                throw new Error("websocketKey input must return { state, key } or { state, keys }");
+            const values = "keys" in next ? next.keys : [next.key];
+            if (values.length > MAX_PENDING)
+                throw new Error("WebSocket candidate batch limit exceeded");
+            const hashes = values.filter(value => value !== null).map(hashKey);
+            state = next.state;
+            return hashes;
+        };
+        return Object.assign((message) => input(message).at(-1) ?? null, {
+            candidates: input,
+            output(message) {
+                const next = key.output(state, message);
+                synchronous(next, "output");
+                if (typeof next.anchorPreviousInput !== "boolean")
+                    throw new Error("websocketKey output must return { state, anchorPreviousInput }");
+                state = next.state;
+                return next.anchorPreviousInput;
+            },
+        });
+    }
     return message => {
         if (!key)
             return createHash("sha256").update(typeof message === "string" ? "text:" : "binary:").update(message).digest("hex");
@@ -49,6 +93,21 @@ export function validateWebSocketRecording(record) {
         || !Array.isArray(record.messages)) {
         throw new Error("invalid WebSocket recording: expected request, input hashes and messages");
     }
+    if (record.inputMode !== undefined && record.inputMode !== "anchors")
+        throw new Error("invalid WebSocket input mode");
+    if (record.inputMode === "anchors") {
+        if (!Array.isArray(record.inputOccurrences) || record.inputOccurrences.length !== record.inputs.length)
+            throw new Error("invalid WebSocket anchor occurrences");
+        const seen = new Map();
+        record.inputs.forEach((key, index) => {
+            const count = record.inputOccurrences[index];
+            if (!Number.isSafeInteger(count) || count < 1 || count <= (seen.get(key) ?? 0))
+                throw new Error("invalid WebSocket anchor occurrence order");
+            seen.set(key, count);
+        });
+    }
+    else if (record.inputOccurrences !== undefined)
+        throw new Error("WebSocket occurrences require anchor mode");
     for (const message of record.messages) {
         if (!message || typeof message.data !== "string" || !["text", "binary"].includes(message.type)) {
             throw new Error("invalid WebSocket output message");
@@ -96,6 +155,9 @@ function closeSocket(socket, code, reason) {
 }
 export function replayWebSocket(args) {
     const { recording: record, label } = args;
+    if ((record.inputMode === "anchors") !== !!args.match.candidates)
+        throw new Error(`${label}: websocketKey mode changed; re-record this cassette`);
+    const occurrences = new Map();
     const lifetime = args.lifetime ?? new FakeWebSocketLifetime();
     let detach = () => { };
     let socket;
@@ -127,32 +189,61 @@ export function replayWebSocket(args) {
         if (position < record.inputs.length)
             deadline = setTimeout(() => fail(missing()), args.timeoutMs);
     };
+    const nextEvent = () => record.messages[output]
+        ?? (record.close?.initiator === "server" ? record.close : undefined);
+    const starts = record.inputMode === "anchors"
+        ? [...record.messages, ...(record.close?.initiator === "server" ? [record.close] : [])]
+            .filter((event, index, events) => index === 0 || event.afterInput !== events[index - 1].afterInput)
+        : [];
+    const dueAt = (event) => {
+        let due = barriers[event.afterInput] + event.delayMs;
+        // Input progress can be faster than the recording (e.g. cached TTS).
+        // Once a later anchor is reached, earlier output must not hold its response
+        // behind the old clock. Catch up in order, without dropping any messages.
+        for (const next of starts) {
+            if (next.afterInput > event.afterInput && barriers[next.afterInput] !== undefined) {
+                due = Math.min(due, barriers[next.afterInput] + next.delayMs);
+            }
+        }
+        return due;
+    };
     const schedule = () => {
         if (stopped || !socket || sentClose)
             return;
         clearTimeout(timer);
-        const event = record.messages[output] ?? (record.close?.initiator === "server" ? record.close : undefined);
+        const event = nextEvent();
         if (!event || barriers[event.afterInput] === undefined)
             return;
-        const delay = Math.max(0, barriers[event.afterInput] + event.delayMs - performance.now());
         timer = setTimeout(() => {
             if (stopped)
                 return;
             try {
-                if ("data" in event) {
-                    socket.send(event.type === "text" ? event.data : new Uint8Array(Buffer.from(event.data, "base64")));
-                    output++;
-                    schedule();
-                }
-                else {
-                    sentClose = true;
-                    closeSocket(socket, event.code, event.reason);
+                // Flush overdue output together; one timer per message would itself
+                // add latency when catching up a continuous stream of quiet audio.
+                for (let batch = 0; batch < MAX_PENDING && !stopped; batch++) {
+                    const event = nextEvent();
+                    if (!event || barriers[event.afterInput] === undefined)
+                        return;
+                    if (dueAt(event) > performance.now())
+                        break;
+                    if ("data" in event) {
+                        const message = event.type === "text" ? event.data : new Uint8Array(Buffer.from(event.data, "base64"));
+                        args.match.output?.(typeof message === "string" ? message : message.slice());
+                        socket.send(message);
+                        output++;
+                    }
+                    else {
+                        sentClose = true;
+                        closeSocket(socket, event.code, event.reason);
+                        return;
+                    }
                 }
+                schedule();
             }
             catch (error) {
                 fail(diagnostic(`playback failed: ${error.message}`));
             }
-        }, Math.min(delay, 2_147_483_647));
+        }, Math.min(Math.max(0, dueAt(event) - performance.now()), 2_147_483_647));
     };
     const session = {
         cancel() { finish(); socket?.close(1001, "replay cleanup"); },
@@ -174,13 +265,28 @@ export function replayWebSocket(args) {
             if (stopped)
                 return;
             try {
-                const actual = args.match(message);
-                if (actual === null)
-                    return;
-                const expected = record.inputs[position];
-                if (expected !== actual)
-                    throw new Error(`expected ${expected ?? "<exhausted>"}, actual ${actual}`);
-                barriers[++position] = performance.now();
+                if (args.match.candidates) {
+                    let matched = false;
+                    for (const actual of args.match.candidates(message)) {
+                        const count = occurrence(occurrences, actual);
+                        if (actual !== record.inputs[position] || count !== record.inputOccurrences[position])
+                            continue;
+                        barriers[++position] = performance.now();
+                        matched = true;
+                    }
+                    // Unselected candidates never extend the deadline.
+                    if (!matched)
+                        return;
+                }
+                else {
+                    const actual = args.match(message);
+                    if (actual === null)
+                        return;
+                    const expected = record.inputs[position];
+                    if (expected !== actual)
+                        throw new Error(`expected ${expected ?? "<exhausted>"}, actual ${actual}`);
+                    barriers[++position] = performance.now();
+                }
                 armDeadline();
                 schedule();
             }
@@ -229,9 +335,22 @@ export async function recordWebSocket(args) {
                 callback(null, args.ip, 4);
         }),
     });
-    const record = { request: args.request, inputs: [], messages: [] };
+    const record = { request: args.request, inputs: [], messages: [],
+        ...(args.match.candidates ? { inputMode: "anchors", inputOccurrences: [] } : {}),
+    };
+    const occurrences = new Map();
+    let candidate;
+    let candidateIndex = 0, selectedIndex = 0;
     let socket;
     let anchor = performance.now();
+    const selectCandidate = () => {
+        if (!candidate || candidate.index === selectedIndex)
+            return;
+        record.inputs.push(candidate.key);
+        record.inputOccurrences.push(candidate.count);
+        anchor = candidate.at;
+        selectedIndex = candidate.index;
+    };
     let stopped = false;
     let clientClosed = false;
     let upstreamClosure;
@@ -279,6 +398,9 @@ export async function recordWebSocket(args) {
             const message = binary ? new Uint8Array(bytes) : bytes.toString();
             // Redact bytes too: base64 encoding must not hide a brokered secret.
             const redacted = binary ? redactBinary(bytes, args.redact, args.secrets) : scrub(bytes.toString());
+            // Apply the same redacted output reducer that replay will see.
+            if (args.match.output?.(binary ? new Uint8Array(Buffer.from(redacted, "base64")) : redacted))
+                selectCandidate();
             record.messages.push({ ...timing(), type: binary ? "binary" : "text", data: redacted });
             if (socket)
                 socket.send(message);
@@ -302,6 +424,7 @@ export async function recordWebSocket(args) {
         }
         try {
             if (!clientClosed) {
+                selectCandidate();
                 upstreamClosure = { code, reason: reason.toString() };
                 record.close = { ...timing(), initiator: "server", code, reason: scrub(reason.toString()) };
             }
@@ -358,10 +481,18 @@ export async function recordWebSocket(args) {
             if (stopped)
                 return;
             try {
-                const signature = args.match(typeof message === "string" ? message : Uint8Array.from(message));
-                if (signature !== null) {
-                    record.inputs.push(signature);
-                    anchor = performance.now();
+                const input = typeof message === "string" ? message : Uint8Array.from(message);
+                if (args.match.candidates) {
+                    const at = performance.now();
+                    for (const key of args.match.candidates(input))
+                        candidate = { key, count: occurrence(occurrences, key), at, index: ++candidateIndex };
+                }
+                else {
+                    const signature = args.match(input);
+                    if (signature !== null) {
+                        record.inputs.push(signature);
+                        anchor = performance.now();
+                    }
                 }
                 const size = typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
                 if (size + upstream.bufferedAmount > MAX_BUFFER)
@@ -380,6 +511,7 @@ export async function recordWebSocket(args) {
                 return;
             try {
                 clientClosed = true;
+                selectCandidate();
                 record.close = { ...timing(), initiator: "client", code, reason: scrub(reason) };
                 closeSocket(upstream, code, reason);
                 openingTimer = setTimeout(() => finish(), 1_000);

package/dist/components/replayFake.d.ts

@@ -82,7 +82,10 @@ export interface ReplayFakeOptions<S = undefined, H extends Record<string, unkno
      *  matching dimensions or fallback apply when a key is supplied. */
     key?: ReplayKey;
     /** Complete messages (string or Uint8Array), synchronously reduced per connection.
-     * Return null to emit no input. Raw inputs are never stored; changing this
+     * Functions and { initial, reduce } emit required keys (null skips an input).
+     * { initial, input, output } emits candidates; output can select the previous
+     * candidate as a recorded timing anchor. Replay waits for those selected keys.
+     * Raw inputs are never stored; changing this
      * matcher can require re-recording. Defaults to SHA-256(type + bytes). */
     websocketKey?: WebSocketKey<W>;
     /** Maximum wait for each required input key; null-producing messages do not

package/dist/daemon.js

@@ -1,3 +1,4 @@
+import { phoneScope, phoneRecordingChunk, releasePhoneRecording } from "./phone.js";
 import { runWithBackgroundFailures } from "./harness/background-failures.js";
 import { generateHostCert as mintHostCert } from "./harness/certificate.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
@@ -4184,6 +4185,7 @@ async function runOne(testCase) {
     const start = Date.now();
     const nativeAndroid = androidScope(testCase.id, start);
     let androidRecordings = [];
+    let phoneRecordings = [];
     const chunks = [];
     const origStdout = process.stdout.write.bind(process.stdout);
     const origStderr = process.stderr.write.bind(process.stderr);
@@ -4439,6 +4441,7 @@ async function runOne(testCase) {
     // Built before installing the timeout so a slow client factory surfaces as
     // a real error rather than getting attributed to the test.
     const base = await spectestContext();
+    const phones = phoneScope(start);
     const ctx = {
         ...base,
         // exec/terminal/poll wrap their results at runtime (the recorder is
@@ -4452,6 +4455,7 @@ async function runOne(testCase) {
         android: nativeAndroid.open,
         desktop: desktopOpener(start, testCase.id, sessions, browserDetaches),
         mcp: openMcp,
+        phone: phones.open,
         testName: testCase.name,
         parent,
     };
@@ -4492,6 +4496,10 @@ async function runOne(testCase) {
     finally {
         if (timer)
             clearTimeout(timer);
+        phoneRecordings = await phones.finish();
+        const phoneErrors = phoneRecordings.flatMap(r => r.error ? [r.error] : []);
+        if (phoneErrors.length && outcome.status === "passed")
+            outcome = { status: "failed", error: { message: phoneErrors.join("\n") } };
         nativeAndroid.deactivate();
         RECORDING_EXEC = undefined;
         INTERCEPTORS.endScope();
@@ -4580,6 +4588,7 @@ async function runOne(testCase) {
     return {
         status: outcome.status,
         androidRecordings,
+        phoneRecordings,
         durationMs,
         log: chunks.join(""),
         events,
@@ -4928,6 +4937,7 @@ async function evalCode(code) {
     // loaded `spectestContext()` yields empty maps, so quick `await fetch(...)`
     // snippets don't require a /load round-trip first.
     const base = await spectestContext();
+    const phones = phoneScope(start, { record: false });
     const ctx = {
         ...base,
         // Bun does not propagate the import() caller's AsyncLocalStorage into
@@ -4945,6 +4955,7 @@ async function evalCode(code) {
         android: nativeAndroid.open,
         desktop: desktopOpener(start, "eval", sessions, browserDetaches, artifactCollector),
         mcp: openMcp,
+        phone: phones.open,
         testName: "eval",
         parent: undefined,
     };
@@ -4985,6 +4996,7 @@ async function evalCode(code) {
         };
     }
     finally {
+        await phones.finish();
         fetchScope.active = false;
         restoreFetch();
         restoreConsole();
@@ -5362,6 +5374,8 @@ export function harnessMethods(state) {
         },
         // One chunk of a parked replay bundle. Case ids are arbitrary user
         // strings, so they travel in params rather than a URL path.
+        phoneRecordingChunk: async (params) => phoneRecordingChunk(String(params.caseId ?? params.id), params.offset, params.limit),
+        releasePhoneRecording: async (params) => releasePhoneRecording(String(params.id)),
         androidRecordingChunk: async (params) => androidRecordingChunk(String(params.caseId ?? params.id), params.offset, params.limit),
         releaseAndroidRecording: async (params) => releaseAndroidRecording(String(params.id)),
         replayChunk: async (params) => {