@specific.dev/spectest 0.111.0 → 0.113.0

package/src/components/replayFake-handler.test.ts

@@ -163,6 +163,11 @@ describe("scripted behavior on replay fakes", () => {
         extends: fileURLToPath(new URL("../../tsconfig.json", import.meta.url)),
         compilerOptions: {
           noEmit: true,
+          // The WebSocket regression suite also typechecks the example key.
+          // Resolve its public import without relying on a local file: install.
+          paths: {
+            "@specific.dev/spectest/components": [fileURLToPath(new URL("./index.ts", import.meta.url))],
+          },
           rootDir: fileURLToPath(new URL("../../../", import.meta.url)),
           typeRoots: [fileURLToPath(new URL("../../node_modules/@types", import.meta.url))],
         },

package/src/components/replayFake-websocket.test.ts

@@ -262,3 +262,169 @@ test("an abandoned handshake cancels the connection before open", async () => {
   expect(h.state.websocketSessions.size).toBe(0);
   expect(h.state.websocketErrors).toEqual([]);
 });
+
+test("output hooks select previous candidates; record and replay preserve timing without quiet", async () => {
+  const server = new WebSocketServer({ port: 0, host: "127.0.0.1" });
+  await once(server, "listening");
+  cleanup.push(() => { for (const c of server.clients) c.terminate(); server.close(); });
+  server.on("connection", ws => {
+    let count = 0;
+    ws.send("opening");
+    ws.on("message", () => { if (++count === 3) setTimeout(() => { ws.send("answer"); ws.close(4001, "done"); }, 25); });
+  });
+  const key: WebSocketKey<{ outputs: number }> = {
+    initial: { outputs: 0 },
+    input(state, message) { return { state, key: message === "noise" ? null : message }; },
+    output(state, message) { return { state: { outputs: state.outputs + 1 }, anchorPreviousInput: message === "answer" }; },
+  };
+  let record!: CassetteWebSocket;
+  let complete!: () => void;
+  const done = new Promise<void>(resolve => complete = resolve);
+  const errors: Error[] = [];
+  const r = await recordWebSocket({
+    url: `ws://voice.test:${(server.address() as { port: number }).port}/live`, ip: "127.0.0.1", host: "voice.test", headers: {}, protocols: [], request,
+    match: websocketMatcher(key), redact: s => s, secrets: [], label: "anchored",
+    captured: value => record = value,
+    finished(_session, error) { if (error) errors.push(error); complete(); },
+  });
+  cleanup.push(() => r.session.cancel());
+  const socket: FakeWebSocket = { readyState: 1, send() {}, close() {} };
+  await r.handlers.open!(socket);
+  await r.handlers.message!(socket, "previous");
+  await r.handlers.message!(socket, "candidate");
+  await r.handlers.message!(socket, "candidate");
+  await done;
+  expect(errors).toEqual([]);
+  expect(record.inputMode).toBe("anchors");
+  expect(record.inputs).toEqual([websocketMatcher(() => "candidate")("x")!]);
+  expect(record.inputOccurrences).toEqual([2]);
+  expect(record.messages[0].afterInput).toBe(0);
+  expect(record.messages[1]).toMatchObject({ afterInput: 1, data: "answer" });
+  expect(record.messages[1].delayMs).toBeGreaterThanOrEqual(20);
+  expect(record.messages[1].delayMs).toBeLessThan(500);
+  const h = await harness([record], key), c = await h.connect();
+  await tick(); expect(c.sent).toEqual(["opening"]);
+  await c.message("noise"); await c.message("previous"); await c.message("candidate");
+  await tick(40); expect(c.sent).toEqual(["opening"]);
+  await c.message("candidate");
+  await tick(5); expect(c.sent).toEqual(["opening"]);
+  await tick(45); expect(c.sent).toEqual(["opening", "answer"]);
+  await c.close(4001, "done"); expect(h.state.websocketErrors).toEqual([]);
+  expect(key.initial.outputs).toBe(0);
+});
+
+test("candidate batches normalize chunking and output state feeds subsequent inputs", async () => {
+  const key: WebSocketKey<{ turn: number; position: number }> = {
+    initial: { turn: 0, position: 0 },
+    input(state, message) {
+      const keys = Array.from(String(message), () => ({ turn: state.turn, position: ++state.position }));
+      return { state, keys };
+    },
+    output(state, message) { return { state: message === "next" ? { turn: state.turn + 1, position: 0 } : state, anchorPreviousInput: true }; },
+  };
+  const hash = (turn: number, position: number) => websocketMatcher(() => ({ turn, position }))("x")!;
+  const h = await harness([{ request, inputMode: "anchors", inputs: [hash(0, 3), hash(1, 2)], inputOccurrences: [1, 1], messages: [
+    { afterInput: 1, delayMs: 0, type: "text", data: "next" },
+    { afterInput: 2, delayMs: 0, type: "text", data: "done" },
+  ] }], key);
+  const c = await h.connect();
+  await c.message("a"); await c.message("bc"); await tick(); expect(c.sent).toEqual(["next"]);
+  await c.message("de"); await tick(); expect(c.sent).toEqual(["next", "done"]);
+  await c.close(); expect(h.state.websocketErrors).toEqual([]);
+});
+
+test("unmatched candidates cannot extend the required anchor deadline", async () => {
+  const key: WebSocketKey<null> = { initial: null,
+    input(state, message) { return { state, key: message }; },
+    output(state) { return { state, anchorPreviousInput: true }; },
+  };
+  const h = await harness([{ request, inputMode: "anchors", inputs: [websocketMatcher(() => "wanted")("x")!], inputOccurrences: [1], messages: [] }], key, 30);
+  const c = await h.connect();
+  for (let i = 0; i < 6; i++) { await c.message("unrelated"); await tick(10); }
+  expect(h.state.websocketErrors.join()).toContain("required input never arrived");
+});
+
+test("anchor validation and hook failures are explicit", async () => {
+  const key: WebSocketKey<null> = { initial: null,
+    input(state, message) { return { state, key: message }; },
+    output(state) { return { state, anchorPreviousInput: true }; },
+  };
+  const h = await harness([], key);
+  const input = websocketMatcher(() => "x")("x")!;
+  for (const counts of [[], [0], [1.2], [2, 1]]) {
+    expect(() => h.helpers.replay(cassette([{ request, inputMode: "anchors", inputs: counts.length === 2 ? [input, input] : [input], inputOccurrences: counts, messages: [] }]))).toThrow("occurrence");
+  }
+  h.helpers.replay(cassette([{ request, inputs: [], messages: [] }]));
+  await expect(h.connect()).rejects.toThrow("re-record");
+  const asyncInput = websocketMatcher({ ...key, input: async () => ({ state: null, key: null }) } as any);
+  expect(() => asyncInput.candidates!("x")).toThrow("synchronous");
+  const asyncOutput = websocketMatcher({ ...key, output: async () => ({ state: null, anchorPreviousInput: true }) } as any);
+  expect(() => asyncOutput.output!("x")).toThrow("synchronous");
+  expect(() => websocketMatcher({ ...key, output: () => ({ state: null }) } as any).output!("x")).toThrow("anchorPreviousInput");
+});
+
+test("output hook cannot mutate binary playback and can select an opening with no input", async () => {
+  const key: WebSocketKey<null> = { initial: null,
+    input(state) { return { state, key: null }; },
+    output(state, message) { if (message instanceof Uint8Array) message.fill(0); return { state, anchorPreviousInput: true }; },
+  };
+  const h = await harness([{ request, inputMode: "anchors", inputs: [], inputOccurrences: [], messages: [
+    { afterInput: 0, delayMs: 0, type: "binary", data: "Af8=" },
+  ] }], key);
+  const c = await h.connect(); await tick();
+  expect(c.sent).toEqual([new Uint8Array([1, 255])]);
+  await c.close(); expect(h.state.websocketErrors).toEqual([]);
+});
+
+export function inferredHooks() {
+  return replayFake({ name: "inferred", host: "voice.test", websocketKey: {
+    initial: { position: 0 },
+    input(state, message) {
+      const position: number = state.position;
+      // @ts-expect-error state is inferred from initial
+      const wrong: string = state.position;
+      return { state: { position: position + 1 }, key: message };
+    },
+    output(state) { return { state, anchorPreviousInput: state.position > 0 }; },
+  } });
+}
+
+test("GPT-Live candidates normalize chunking and select fast speech without caller silence", async () => {
+  const { liveKey } = await import("../../../examples/phone-receptionist/spectest/live-key.js");
+  const audio = (pcm: Buffer) => JSON.stringify({ type: "session.input_audio.append", audio: pcm.toString("base64") });
+  const response = JSON.stringify({ type: "session.output_audio.delta", delta: Buffer.alloc(960, 16).toString("base64") });
+  const a = websocketMatcher(liveKey), b = websocketMatcher(liveKey);
+  expect(a.candidates!(audio(Buffer.alloc(1920)))).toEqual([]);
+  const speech = Buffer.alloc(960 * 3, 16);
+  const whole = a.candidates!(audio(speech));
+  const split = [speech.subarray(0, 300), speech.subarray(300, 1140), speech.subarray(1140)]
+    .flatMap(pcm => b.candidates!(audio(pcm)));
+  expect(whole).toEqual(split); expect(whole).toHaveLength(3);
+  expect(a.output!(response)).toBe(true); // No quiet samples at all.
+  expect(a.candidates!(audio(Buffer.alloc(960, 16)))).toEqual([]); // Same ongoing utterance.
+  expect(a.candidates!(audio(Buffer.alloc(960)))).toEqual([]);
+  expect(a.candidates!(audio(Buffer.alloc(960, 16)))).toHaveLength(1); // Next turn.
+  expect(a.output!(response)).toBe(true);
+});
+
+
+test("a reached response anchor catches up older output without adding its stale clock delay", async () => {
+  const key: WebSocketKey<null> = { initial: null,
+    input(state, message) { return { state, key: message }; },
+    output(state) { return { state, anchorPreviousInput: true }; },
+  };
+  const messages = Array.from({length: 200}, (_, index) => ({
+    afterInput: 0, delayMs: 3000 + index, type: "text" as const, data: `quiet-${index}`,
+  }));
+  const h = await harness([{ request, inputMode: "anchors",
+    inputs: [websocketMatcher(() => "go")("x")!], inputOccurrences: [1], messages: [
+      ...messages, {afterInput: 1, delayMs: 20, type: "text", data: "response"},
+    ],
+  }], key);
+  const c = await h.connect();
+  await tick(); expect(c.sent).toEqual([]);
+  await c.message("go");
+  await tick(60);
+  expect(c.sent).toEqual([...messages.map(m => m.data), "response"]);
+  await c.close(); expect(h.state.websocketErrors).toEqual([]);
+});

package/src/components/replayFake.ts

@@ -177,7 +177,10 @@ export interface ReplayFakeOptions<
    *  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/src/daemon.ts

@@ -1,3 +1,4 @@
+import { phoneScope, phoneRecordingChunk, releasePhoneRecording, type PhoneRecording } 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";
@@ -92,6 +93,7 @@ import {
   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,
@@ -3531,6 +3533,7 @@ async function runProjectSetupInner(hook: "setup" | "setupInteractive"): Promise
 // ────────────────────────────────────────────────────────────────────────
 
 interface RunResult {
+  phoneRecordings: PhoneRecording[];
   androidRecordings: AndroidRecording[];
   status: "passed" | "failed";
   durationMs: number;
@@ -5061,6 +5064,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   const start = Date.now();
   const nativeAndroid = androidScope(testCase.id, start);
   let androidRecordings: AndroidRecording[] = [];
+  let phoneRecordings: PhoneRecording[] = [];
   const chunks: string[] = [];
   const origStdout = process.stdout.write.bind(process.stdout);
   const origStderr = process.stderr.write.bind(process.stderr);
@@ -5359,6 +5363,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   // a real error rather than getting attributed to the test.
   const base = await spectestContext();
 
+  const phones = phoneScope(start);
   const ctx: TestContext<unknown> = {
     ...base,
     // exec/terminal/poll wrap their results at runtime (the recorder is
@@ -5372,6 +5377,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     android: nativeAndroid.open,
     desktop: desktopOpener(start, testCase.id, sessions, browserDetaches),
     mcp: openMcp,
+    phone: phones.open,
     testName: testCase.name,
     parent,
   };
@@ -5415,6 +5421,9 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     };
   } 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();
@@ -5497,6 +5506,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   return {
     status: outcome.status,
     androidRecordings,
+    phoneRecordings,
     durationMs,
     log: chunks.join(""),
     events,
@@ -5915,6 +5925,7 @@ async function evalCode(code: string): Promise<EvalResult> {
   // snippets don't require a /load round-trip first.
   const base = await spectestContext();
 
+  const phones = phoneScope(start, { record: false });
   const ctx: TestContext<undefined> = {
     ...base,
     // Bun does not propagate the import() caller's AsyncLocalStorage into
@@ -5932,6 +5943,7 @@ async function evalCode(code: string): Promise<EvalResult> {
     android: nativeAndroid.open,
     desktop: desktopOpener(start, "eval", sessions, browserDetaches, artifactCollector),
     mcp: openMcp,
+    phone: phones.open,
     testName: "eval",
     parent: undefined,
   };
@@ -5978,6 +5990,7 @@ async function evalCode(code: string): Promise<EvalResult> {
       error: { message: explainEvalExportError(code, message), stack: e.stack },
     };
   } finally {
+    await phones.finish();
     fetchScope.active = false;
     restoreFetch();
     restoreConsole();
@@ -6320,6 +6333,19 @@ export function harnessMethods(state: RouteState): MethodTable {
         () => 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 as string[]);
+      if (!Array.isArray(params.args)) throw badRequest("args must be a JSON array");
+      return callFakeFunction(fake.helpers!, member, params.args, params.omitted_args as number[] | undefined);
+    }),
+
     eval: async (params) => {
       const code = requireString(params, "code");
       return exclusive(state, "inFlightTest", "a test or eval is already running", () => {
@@ -6408,6 +6434,8 @@ export function harnessMethods(state: RouteState): MethodTable {
 
     // 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/src/fake-functions.test.ts

@@ -0,0 +1,62 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("daemon dispatch discovers cached helpers, preserves annotations and excludes concurrent evals", async () => {
+  const root = await mkdtemp(join(tmpdir(), "spectest-fake-functions-"));
+  try {
+    await mkdir(join(root, "spectest"));
+    await writeFile(join(root, "spectest/index.ts"), `
+      import { defineEnvironment, defineFake, annotate } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
+      const env = defineEnvironment({ name: "helpers", services: {}, fakes: {
+        mail: defineFake({ name: "mail", hostnames: ["mail.test"], handler: () => new Response("ok"), helpers: () => {
+          let count = 0;
+          return {
+            receipt(amount) { count += amount; return annotate({ subject: "Receipt " + count }, "email"); },
+            async wait() { await globalThis.gate; return count; },
+          };
+        } }),
+      }});
+      export default env.project({});
+    `);
+    const script = `
+      import { strict as assert } from "node:assert";
+      import { METHODS } from ${JSON.stringify(new URL("./daemon.ts", import.meta.url).href)};
+      await METHODS.load({});
+      {
+        const discovery = await METHODS.fakeFunctions({fake:"mail"});
+        assert.deepEqual(discovery.functions, ["receipt", "wait"]);
+        assert.deepEqual(discovery.parameters.receipt, [{ name: "amount", has_default: false, rest: false, destructured: false }]);
+        assert.deepEqual(discovery.parameters.wait, []);
+      }
+      await assert.rejects(METHODS.fakeFunctions({fake:"missing"}), /Unknown fake/);
+      await assert.rejects(METHODS.fakeFunctions({fake:"mail", member:"receipt", args:{}}), /JSON array/);
+      for (const count of [1, 2]) {
+        const result = await METHODS.fakeFunctions({fake:"mail", member:"receipt", expressions:["2 - 1"]});
+        assert.equal(result.result.subject, "Receipt " + count);
+        assert.equal(result.annotation.kind, "email");
+        assert.equal(result.annotation.message.subject, result.result.subject);
+      }
+      let release;
+      globalThis.gate = new Promise(r => release = r);
+      const pending = METHODS.fakeFunctions({fake:"mail", member:"wait", expressions:[]});
+      await assert.rejects(METHODS.eval({code:"export default 1"}), /already running/);
+      await assert.rejects(METHODS.fakeFunctions({fake:"mail"}), /already running/);
+      release();
+      assert.equal((await pending).result, 2);
+      {
+        const discovery = await METHODS.fakeFunctions({fake:"mail"});
+        assert.deepEqual(discovery.functions, ["receipt", "wait"]);
+        assert.deepEqual(discovery.parameters.receipt, [{ name: "amount", has_default: false, rest: false, destructured: false }]);
+        assert.deepEqual(discovery.parameters.wait, []);
+      }
+      process.exit(0);
+    `;
+    const child = Bun.spawn([process.execPath, "--eval", script], {
+      env: { ...process.env, SPECTEST_APP_DIR: root }, stdout: "pipe", stderr: "pipe",
+    });
+    const [code, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+    expect(code, stdout + stderr).toBe(0);
+  } finally { await rm(root, { recursive: true, force: true }); }
+}, 20000);

package/src/harness/fake-functions.test.ts

@@ -0,0 +1,77 @@
+import { expect, test } from "bun:test";
+import { annotate } from "../annotate.js";
+import { fakeFunctions, callFakeFunction } from "./fake-functions.js";
+
+test("discovery includes only own data functions and never runs getters", async () => {
+  const helpers = Object.create({ inherited() { throw new Error("no"); } });
+  Object.defineProperties(helpers, {
+    getter: { get() { throw new Error("no"); } },
+    value: { value: 42 },
+    own: { value() {} },
+  });
+  expect(fakeFunctions(helpers)).toEqual(["own"]);
+  for (const name of ["getter", "inherited", "constructor", "toString", "missing", "value"])
+    await expect(callFakeFunction(helpers, name, [])).rejects.toThrow("Unknown fake function");
+});
+
+test("calls preserve receiver, arguments, live state, and async return values", async () => {
+  const helpers = { count: 0, async add(value: { amount: number }) { this.count += value.amount; return this.count; } };
+  expect((await callFakeFunction(helpers, "add", [{ amount: 3 }])).result).toBe(3);
+  expect((await callFakeFunction(helpers, "add", [{ amount: 2 }])).result).toBe(5);
+});
+
+test("email and chat annotations survive separately from the raw value", async () => {
+  const value = { subject: "Receipt", html: "<p>Paid</p>" };
+  const helpers = {
+    email: () => annotate(value, "email"),
+    chat: async () => annotate({ original: 1 }, "chat", [{ side: "other", text: "Hello" }]),
+    empty() {},
+    fail() { throw new Error("declined"); },
+    async reject() { throw new Error("offline"); },
+  };
+  const email = await callFakeFunction(helpers, "email", []);
+  expect(email.result).toEqual(value);
+  expect(email.annotation).toEqual({ kind: "email", message: value });
+  const chat = await callFakeFunction(helpers, "chat", []);
+  expect(chat.result).toEqual({ original: 1 });
+  expect(chat.annotation?.kind).toBe("chat");
+  expect((await callFakeFunction(helpers, "empty", [])).result).toBeNull();
+  expect((await callFakeFunction(helpers, "fail", [])).error).toBe("declined");
+  expect((await callFakeFunction(helpers, "reject", [])).error).toBe("offline");
+});
+
+test("evaluates JavaScript expressions with defaults, rest and non-JSON values", async () => {
+  const helpers = {
+    values(label = "default", ...items: unknown[]) { return [label, ...items]; },
+    inspect(date: Date, callback: (n: number) => number) { return [date.getUTCFullYear(), callback(4)]; },
+    count(...items: unknown[]) { return items.length; },
+  };
+  const call = (member: string, expressions: string[]) => callFakeFunction(helpers, member, [], [], expressions);
+  expect((await call("values", ["'123'", "[1 + 2, { ok: true }, null]"])).result).toEqual(["123", 3, { ok: true }, null]);
+  expect((await call("values", ["", "[false]"])).result).toEqual(["default", false]);
+  expect((await call("values", ["undefined", ""])).result).toEqual(["default"]);
+  expect((await call("inspect", ["new Date('2026-01-01')", "n => n * 2"])).result).toEqual([2026, 8]);
+  expect((await call("count", [""])).result).toBe(0);
+  expect((await call("values", ["'x'", "42"])).error).toContain("items: Enter an array expression");
+});
+
+test("rejects invalid expressions before evaluating fields or invoking a helper", async () => {
+  let calls = 0;
+  const helpers = { send(to: unknown, body: unknown) { calls++; return [to, body]; } };
+  const globals = globalThis as typeof globalThis & { expressionCalls?: number };
+  globals.expressionCalls = 0;
+  try {
+    const call = (expressions: string[]) => callFakeFunction(helpers, "send", [], [], expressions);
+    expect((await call(["++globalThis.expressionCalls", "{broken"])).error).toContain("body:");
+    expect(globals.expressionCalls).toBe(0);
+    expect((await call(["1); globalThis.expressionCalls++; (2", "''"])).error).toContain("to:");
+    expect((await call(["unquotedMissingName", "''"])).error).toContain("to:");
+    expect(calls).toBe(0);
+    await expect(callFakeFunction(helpers, "missing", [], [], ["++globalThis.expressionCalls"])).rejects.toThrow("Unknown fake function");
+    expect(globals.expressionCalls).toBe(0);
+    expect((await call(["++globalThis.expressionCalls", "'hello' // trailing comment"])).result).toEqual([1, "hello"]);
+    expect(globals.expressionCalls).toBe(1);
+    expect(calls).toBe(1);
+    expect((await callFakeFunction({ max: Math.max }, "max", [], [], ["1 + 2", "10"])).result).toBe(10);
+  } finally { delete globals.expressionCalls; }
+});

package/src/harness/fake-functions.ts

@@ -0,0 +1,78 @@
+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: Record<string, unknown>): string[] {
+  return Object.getOwnPropertyNames(helpers).filter((name) =>
+    typeof Object.getOwnPropertyDescriptor(helpers, name)?.value === "function",
+  ).sort();
+}
+
+export function fakeFunctionParameters(helpers: Record<string, unknown>) {
+  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: Record<string, unknown>, member: string, args: unknown[], omittedArgs: number[] = [], expressions?: string[]) {
+  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: Function, expressions: string[]): unknown[] {
+  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: number) => parameters?.[index]?.name ?? `Argument ${index + 1}`;
+  const withLabel = <T>(index: number, action: () => T): T => {
+    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: unknown[] = [];
+  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/src/harness/function-parameters.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "bun:test";
+import { functionParameters } from "./function-parameters.js";
+import { callFakeFunction, fakeFunctionParameters } from "./fake-functions.js";
+
+const p = (name: string, has_default = false, rest = false, destructured = false) => ({ name, has_default, rest, destructured });
+
+test("reads runtime names from methods, arrows, async and generator functions", () => {
+  const methods = { send(to: string, subject: string, text: string) {}, async load(id: number) {}, *items(limit = 3) {} };
+  expect(fakeFunctionParameters(methods)).toEqual({ send: [p("to"), p("subject"), p("text")], load: [p("id")], items: [p("limit", true)] });
+  expect(functionParameters(value => value)).toEqual([p("value")]);
+  expect(functionParameters(async value => value)).toEqual([p("value")]);
+  expect(functionParameters(function named(ångström: string) {})).toEqual([p("ångström")]);
+  expect(functionParameters(() => 42)).toEqual([]);
+});
+
+test("handles nested defaults, commas, comments and patterns without evaluating anything", () => {
+  let calls = 0;
+  const fn = (first = (++calls, /[,)]/), /* not,a,param */ second = (x = [1, 2]) => x,
+    third = `a,${[1, 2].join(",")}`, { to, subject: title } = { to: "a", subject: "b" }, [a, b] = [1, 2], ...rest: unknown[]) => {};
+  const result = functionParameters(fn)!;
+  expect(result.map(v => [v.has_default, v.rest, v.destructured])).toEqual([
+    [true, false, false], [true, false, false], [true, false, false], [true, false, true], [true, false, true], [false, true, false],
+  ]);
+  expect(result.slice(0, 3).map(v => v.name)).toEqual(["first", "second", "third"]);
+  expect(result[3].name).toContain("to");
+  expect(result[3].name).toContain("subject");
+  expect(result[4].name).toMatch(/^\[/);
+  expect(result[5].name).toBe("rest");
+  expect(calls).toBe(0);
+});
+
+test("opaque functions stay unknown and user-supplied toString is never called", () => {
+  const fn = (name: string) => name;
+  Object.defineProperty(fn, "toString", { get() { throw new Error("do not inspect"); } });
+  expect(functionParameters(fn)).toEqual([p("name")]);
+  expect(functionParameters(fn.bind(null))).toBeNull();
+  expect(functionParameters(Math.max)).toBeNull();
+});
+
+test("omitted slots trigger defaults while explicit null and later arguments are preserved", async () => {
+  const helpers = { send(to = "default", text: unknown, ...extra: unknown[]) { return [to, text, ...extra]; } };
+  expect((await callFakeFunction(helpers, "send", [null, "123", false, { ok: true }], [0])).result).toEqual(["default", "123", false, { ok: true }]);
+  expect((await callFakeFunction(helpers, "send", [null, "text"])).result).toEqual([null, "text"]);
+  for (const omitted of [[-1], [2], [0.5], [1]]) await expect(callFakeFunction(helpers, "send", [null, "text"], omitted)).rejects.toThrow("omitted_args");
+});

package/src/harness/function-parameters.ts

@@ -0,0 +1,43 @@
+import { parse, type Node, type Expression, type Pattern, type FunctionExpression, type ArrowFunctionExpression } from "acorn";
+
+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 function functionParameters(fn: Function): FunctionParameter[] | null {
+  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: Node = statement.expression;
+      if (method) {
+        if (expression.type !== "ObjectExpression") continue;
+        const properties = (expression as Extract<Expression, { type: "ObjectExpression" }>).properties;
+        if (properties.length !== 1 || properties[0]?.type !== "Property") continue;
+        expression = properties[0].value;
+      }
+      if (expression.type !== "FunctionExpression" && expression.type !== "ArrowFunctionExpression") continue;
+      return (expression as FunctionExpression | ArrowFunctionExpression).params.map((parameter) => {
+        const rest = parameter.type === "RestElement";
+        let binding: Pattern = 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;
+}