@specific.dev/spectest 0.111.0 → 0.113.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";
@@ -42,6 +43,7 @@ import { isDesktopApp } from "./desktop.js";
 // each easy to restate subtly differently.
 import { buildArgFlags, buildContentKey as computeBuildContentKey, buildTargetFlags, imageTag, isGeneratedDockerignore, pickProjectIgnore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { startServices } from "./harness/service-graph.js";
+import { fakeFunctions, fakeFunctionParameters, callFakeFunction } from "./harness/fake-functions.js";
 import { dispatchFake } from "./harness/fake-websocket.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
@@ -4184,6 +4186,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 +4442,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 +4456,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 +4497,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 +4589,7 @@ async function runOne(testCase) {
     return {
         status: outcome.status,
         androidRecordings,
+        phoneRecordings,
         durationMs,
         log: chunks.join(""),
         events,
@@ -4928,6 +4938,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 +4956,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 +4997,7 @@ async function evalCode(code) {
         };
     }
     finally {
+        await phones.finish();
         fetchScope.active = false;
         restoreFetch();
         restoreConsole();
@@ -5274,6 +5287,21 @@ export function harnessMethods(state) {
         }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),
         interactiveSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup("setupInteractive")),
+        fakeFunctions: async (params) => exclusive(state, "inFlightTest", "a test or eval is already running", async () => {
+            const name = requireString(params, "fake");
+            const fake = FAKES.get(name);
+            if (!fake)
+                throw notFound(`Unknown fake: ${name}`);
+            await ensureFakeHelpers(name);
+            if (params.member === undefined)
+                return { functions: fakeFunctions(fake.helpers), parameters: fakeFunctionParameters(fake.helpers) };
+            const member = requireString(params, "member");
+            if (params.expressions !== undefined)
+                return callFakeFunction(fake.helpers, member, [], [], params.expressions);
+            if (!Array.isArray(params.args))
+                throw badRequest("args must be a JSON array");
+            return callFakeFunction(fake.helpers, member, params.args, params.omitted_args);
+        }),
         eval: async (params) => {
             const code = requireString(params, "code");
             return exclusive(state, "inFlightTest", "a test or eval is already running", () => {
@@ -5362,6 +5390,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) => {

package/dist/harness/fake-functions.d.ts

@@ -0,0 +1,18 @@
+/** Only own data properties are callable. Discovery never invokes getters. */
+export declare function fakeFunctions(helpers: Record<string, unknown>): string[];
+export declare function fakeFunctionParameters(helpers: Record<string, unknown>): {
+    [k: string]: import("./function-parameters.js").FunctionParameter[] | null;
+};
+/** Use the raw helpers: the test wrappers intentionally discard annotations
+ * when there is no recorder. Preserve both the value and its presentation. */
+export declare function callFakeFunction(helpers: Record<string, unknown>, member: string, args: unknown[], omittedArgs?: number[], expressions?: string[]): Promise<{
+    result: {} | null;
+    annotation: import("../annotate.js").RenderAnnotation | null;
+    error: null;
+    duration_ms: number;
+} | {
+    result: null;
+    annotation: null;
+    error: string;
+    duration_ms: number;
+}>;

package/dist/harness/fake-functions.js

@@ -0,0 +1,82 @@
+import { parse } from "acorn";
+import { functionParameters } from "./function-parameters.js";
+import { readAnnotation } from "../annotate.js";
+import { deepUnwrap } from "../inspect.js";
+import { safeSerialize } from "../recorder.js";
+import { runUninstrumented } from "./instrumentation-scope.js";
+/** Only own data properties are callable. Discovery never invokes getters. */
+export function fakeFunctions(helpers) {
+    return Object.getOwnPropertyNames(helpers).filter((name) => typeof Object.getOwnPropertyDescriptor(helpers, name)?.value === "function").sort();
+}
+export function fakeFunctionParameters(helpers) {
+    return Object.fromEntries(fakeFunctions(helpers).map(name => [name,
+        functionParameters(Object.getOwnPropertyDescriptor(helpers, name).value),
+    ]));
+}
+/** Use the raw helpers: the test wrappers intentionally discard annotations
+ * when there is no recorder. Preserve both the value and its presentation. */
+export async function callFakeFunction(helpers, member, args, omittedArgs = [], expressions) {
+    const fn = Object.getOwnPropertyDescriptor(helpers, member)?.value;
+    if (typeof fn !== "function")
+        throw new Error(`Unknown fake function: ${member}`);
+    if (!Array.isArray(omittedArgs) || omittedArgs.some(i => !Number.isInteger(i) || i < 0 || i >= args.length || args[i] !== null))
+        throw new Error("omitted_args must contain indices of null argument placeholders");
+    const omitted = new Set(omittedArgs);
+    const actualArgs = args.map((value, i) => omitted.has(i) ? undefined : value);
+    const start = Date.now();
+    try {
+        const value = await runUninstrumented(() => Reflect.apply(fn, helpers, expressions === undefined ? actualArgs : evaluateArguments(fn, expressions)));
+        const annotated = readAnnotation(value);
+        return {
+            result: safeSerialize(deepUnwrap(annotated ? annotated.value : value)) ?? null,
+            annotation: annotated?.annotation ?? null,
+            error: null,
+            duration_ms: Date.now() - start,
+        };
+    }
+    catch (error) {
+        return { result: null, annotation: null,
+            error: error instanceof Error ? error.message : String(error), duration_ms: Date.now() - start };
+    }
+}
+/** Expressions execute only in the environment, never in either dashboard.
+ * Compile every field before evaluating any, so a syntax error cannot partially
+ * execute the call. Keep actual JS values (undefined, Date, functions, etc.). */
+function evaluateArguments(fn, expressions) {
+    if (!Array.isArray(expressions) || expressions.some(source => typeof source !== "string"))
+        throw new Error("expressions must be an array of JavaScript expressions");
+    const parameters = functionParameters(fn);
+    const label = (index) => parameters?.[index]?.name ?? `Argument ${index + 1}`;
+    const withLabel = (index, action) => {
+        try {
+            return action();
+        }
+        catch (error) {
+            throw new Error(`${label(index)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const compiled = expressions.map((source, index) => withLabel(index, () => {
+        if (!source.trim())
+            return null;
+        const expression = `(${source}\n)`;
+        const program = parse(expression, { ecmaVersion: "latest" });
+        if (program.body.length !== 1 || program.body[0].type !== "ExpressionStatement")
+            throw new Error("Enter a single JavaScript expression.");
+        return new Function(`"use strict"; return ${expression};`);
+    }));
+    // Preserve interior omissions but avoid inventing trailing arguments.
+    while (compiled.length && compiled.at(-1) === null)
+        compiled.pop();
+    const args = [];
+    compiled.forEach((evaluate, index) => withLabel(index, () => {
+        const value = evaluate ? evaluate() : undefined;
+        if (parameters?.[index]?.rest) {
+            if (!Array.isArray(value))
+                throw new Error("Enter an array expression for the remaining arguments.");
+            args.push(...value);
+        }
+        else
+            args.push(value);
+    }));
+    return args;
+}

package/dist/harness/function-parameters.d.ts

@@ -0,0 +1,9 @@
+export interface FunctionParameter {
+    name: string;
+    has_default: boolean;
+    rest: boolean;
+    destructured: boolean;
+}
+/** Parse runtime JavaScript, never execute it (including default expressions).
+ * Null means opaque/unparseable, while [] means a known zero-argument helper. */
+export declare function functionParameters(fn: Function): FunctionParameter[] | null;

package/dist/harness/function-parameters.js

@@ -0,0 +1,42 @@
+import { parse } from "acorn";
+/** Parse runtime JavaScript, never execute it (including default expressions).
+ * Null means opaque/unparseable, while [] means a known zero-argument helper. */
+export function functionParameters(fn) {
+    const source = Function.prototype.toString.call(fn);
+    if (source.length > 256_000)
+        return null;
+    // Function/arrow expressions and object methods have different grammar.
+    for (const method of [false, true]) {
+        const text = method ? `({${source}})` : `(${source})`;
+        try {
+            const program = parse(text, { ecmaVersion: "latest", sourceType: "module" });
+            const statement = program.body[0];
+            if (statement?.type !== "ExpressionStatement")
+                continue;
+            let expression = statement.expression;
+            if (method) {
+                if (expression.type !== "ObjectExpression")
+                    continue;
+                const properties = expression.properties;
+                if (properties.length !== 1 || properties[0]?.type !== "Property")
+                    continue;
+                expression = properties[0].value;
+            }
+            if (expression.type !== "FunctionExpression" && expression.type !== "ArrowFunctionExpression")
+                continue;
+            return expression.params.map((parameter) => {
+                const rest = parameter.type === "RestElement";
+                let binding = rest ? parameter.argument : parameter;
+                const has_default = binding.type === "AssignmentPattern";
+                if (binding.type === "AssignmentPattern")
+                    binding = binding.left;
+                return {
+                    name: binding.type === "Identifier" ? binding.name : text.slice(binding.start, binding.end),
+                    has_default, rest, destructured: binding.type !== "Identifier",
+                };
+            });
+        }
+        catch { /* Native/bound functions and unsupported syntax stay opaque. */ }
+    }
+    return null;
+}