@specific.dev/spectest 0.110.0 → 0.112.0

package/src/phone.ts

@@ -0,0 +1,330 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { mkdtemp, open, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { captureRecording, recordStep, reserveEvent, type StepBlock } from "./recorder.js";
+import { deepUnwrap } from "./inspect.js";
+
+export interface PhoneOptions {
+  /** SIP server in the environment, e.g. sip:5060. */
+  endpoint: string;
+  /** Caller identity, e.g. sip:+46700000000@spectest.test. */
+  from: string;
+  transport?: "udp" | "tcp";
+  username?: string;
+  password?: string;
+  language?: string;
+  voice?: "M1" | "M2" | "M3" | "M4" | "M5" | "F1" | "F2" | "F3" | "F4" | "F5";
+  timeoutMs?: number;
+}
+export interface CallOptions {
+  /** Poll until true or a nonempty transcript string, then wait for incoming silence.
+   * A returned string is displayed as this step's recipient response. */
+  waitFor?: () => boolean | string | Promise<boolean | string>;
+}
+export interface SpeechOptions extends CallOptions {
+  language?: string;
+  voice?: PhoneOptions["voice"];
+  speed?: number;
+}
+export interface Phone {
+  /** Connect, optionally wait for a predicate then silence, and record one step. */
+  call(destination: string, options?: CallOptions): Promise<void>;
+  /** Send the complete utterance, optionally wait for a predicate then silence, and record one isolated step. */
+  say(text: string, options?: SpeechOptions): Promise<void>;
+  hangup(): Promise<void>;
+  /** Close the phone; also performed on success, failure, and test timeout. */
+  close(): Promise<void>;
+}
+
+/** Metadata only. Audio remains on disk until pulled through phoneRecordingChunk. */
+export interface PhoneRecording {
+  id: string;
+  startedAtMs: number;
+  duration: number;
+  bytes: number;
+  contentType: "audio/webm";
+  encodingFinalizeMs?: number;
+  peaks: number[];
+  callerPeaks?: number[];
+  recipientPeaks?: number[];
+  error?: string;
+}
+type Reply = { id: number; error?: string; offset?: number };
+type AudioBlock = Extract<StepBlock, { type: "audio" }>;
+type PhoneStep = { playbackStart?: number; playbackEnd?: number; block: AudioBlock };
+const MAX_RECORDING_BYTES = 96 * 1024 * 1024;
+const parked = new Map<string, { path: string; directory: string; bytes: number }>();
+
+export async function phoneRecordingChunk(id: string, offset: unknown, limit: unknown) {
+  const entry = parked.get(id);
+  if (!entry) throw new Error("Unknown phone recording");
+  const start = Number(offset ?? 0), count = Number(limit ?? 6 * 1024 * 1024);
+  if (!Number.isSafeInteger(start) || start < 0 || start > entry.bytes || !Number.isSafeInteger(count) || count < 1 || count > 6 * 1024 * 1024) throw new Error("Invalid phone recording range");
+  const file = await open(entry.path, "r");
+  try {
+    const buffer = Buffer.alloc(Math.min(count, entry.bytes - start));
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, start);
+    return { b64: buffer.subarray(0, bytesRead).toString("base64"), offset: start, total: entry.bytes };
+  } finally { await file.close(); }
+}
+export async function releasePhoneRecording(id: string) {
+  const entry = parked.get(id);
+  if (entry) {
+    parked.delete(id);
+    await rm(entry.path, { force: true });
+    if (![...parked.values()].some(p => p.directory === entry.directory)) await rm(entry.directory, { recursive: true, force: true });
+  }
+  return { released: true };
+}
+
+class PhoneSession implements Phone {
+  private pending = new Map<number, { resolve: (r: Reply) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout>; position?: (event: string, offset: number) => void }>();
+  private nextId = 0;
+  private closed = false;
+  private failure?: Error;
+  private cancellation = new AbortController();
+  private tail: Promise<unknown> = Promise.resolve();
+  private child: ChildProcessWithoutNullStreams;
+  private exited: Promise<void>;
+  private closing?: Promise<void>;
+  private directory?: string;
+  private activeCall?: string;
+  private calls = new Map<string, { started: number; steps: PhoneStep[]; recording?: PhoneRecording }>();
+  constructor(private options: PhoneOptions, private caseStart: number, private reserveCall: () => void) {
+    if (!/^[a-zA-Z0-9.-]+(?::\d{1,5})?$/.test(options.endpoint)) throw new Error("phone.endpoint must be a hostname or IPv4 address with optional port");
+    if (!/^sip:[^\s<>]+$/.test(options.from)) throw new Error("phone.from must be a sip: URI");
+    if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) throw new Error("phone.timeoutMs must be positive");
+    this.child = spawn(process.env.SPECTEST_PHONE_PYTHON ?? "/opt/spectest/phone/bin/python", [fileURLToPath(new URL("./harness/phone.py", import.meta.url))], { stdio: ["pipe", "pipe", "pipe"] });
+    this.exited = new Promise(resolve => { this.child.once("close", () => resolve()); });
+    // Native logs can contain authentication headers. Never record them.
+    this.child.stderr.resume();
+    createInterface({ input: this.child.stdout }).on("line", line => {
+      let reply: Reply & { event?: string; sessionId?: string; offset?: number; startedAtMs: number; duration: number; bytes: number; peaks: number[]; callerPeaks?: number[]; recipientPeaks?: number[]; contentType: PhoneRecording["contentType"]; encodingFinalizeMs?: number };
+      try { reply = JSON.parse(line); } catch { return; }
+      if (reply.event === "recording" && reply.sessionId) {
+        const call = this.calls.get(reply.sessionId);
+        if (call) call.recording = { id: reply.sessionId, startedAtMs: reply.startedAtMs - this.caseStart, duration: reply.duration, bytes: reply.bytes, peaks: reply.peaks, callerPeaks: reply.callerPeaks, recipientPeaks: reply.recipientPeaks, contentType: reply.contentType, encodingFinalizeMs: reply.encodingFinalizeMs, error: reply.error };
+        return;
+      }
+      const waiter = this.pending.get(reply.id);
+      if (!waiter) return;
+      if (typeof reply.offset === "number" && Number.isFinite(reply.offset) && reply.offset >= 0) {
+        waiter.position?.(reply.event ?? "operation_ended", reply.offset);
+      }
+      if (reply.event === "speech_started" || reply.event === "operation_started") {
+        return;
+      }
+      clearTimeout(waiter.timer);
+      this.pending.delete(reply.id);
+      if (reply.error) waiter.reject(new Error(reply.error)); else waiter.resolve(reply);
+    });
+    this.child.on("error", () => this.fail(new Error("Phone runtime unavailable. Rebuild the golden image with phone support.")));
+    this.child.on("exit", () => this.fail(new Error("Phone runtime exited")));
+    this.child.stdin.on("error", () => this.fail(new Error("Phone runtime input closed")));
+  }
+  private fail(error: Error) {
+    this.closed = true;
+    this.failure ??= error;
+    this.cancellation.abort(this.failure);
+    for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(error); }
+    this.pending.clear();
+  }
+  private request(action: string, data: object = {}, timeout = this.options.timeoutMs ?? 30_000, position?: (event: string, offset: number) => void): Promise<Reply> {
+    if (this.closed) return Promise.reject(new Error("Phone is closed"));
+    const id = ++this.nextId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.fail(new Error(`Phone ${action} timed out after ${timeout}ms`)); void this.close(); }, timeout);
+      this.pending.set(id, { resolve, reject, timer, position });
+      this.child.stdin.write(JSON.stringify({ id, action, ...data }) + "\n");
+    });
+  }
+  async initialize(): Promise<this> {
+    this.directory = await mkdtemp(join(tmpdir(), "spectest-phone-"));
+    if (this.closed) throw this.failure ?? new Error("Phone is closed");
+    await this.request("open", { ...this.options, directory: this.directory }, 60_000);
+    return this;
+  }
+  private async waitForResponse(options: CallOptions): Promise<Reply & { response?: string }> {
+    const timeout = 30_000;
+    const deadline = performance.now() + timeout;
+    const controller = new AbortController();
+    const cancel = () => controller.abort(this.failure ?? new Error("Phone closed"));
+    this.cancellation.signal.addEventListener("abort", cancel, { once: true });
+    if (this.closed) cancel();
+    const timer = setTimeout(() => controller.abort(new Error(`Phone response wait timed out after ${timeout}ms`)), timeout);
+    const aborted = new Promise<never>((_, reject) => {
+      const rejectAbort = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", rejectAbort, { once: true });
+      if (controller.signal.aborted) rejectAbort();
+    });
+    // Probes are observations: suppress their internal events without affecting
+    // concurrent phones, and discard late results after timeout/case cleanup.
+    const branch = captureRecording();
+    try {
+      return await Promise.race([aborted, branch.run(async () => {
+        let response: string | undefined;
+        if (options.waitFor) {
+          for (;;) {
+            controller.signal.throwIfAborted();
+            const ready = deepUnwrap(await options.waitFor());
+            controller.signal.throwIfAborted();
+            if (ready) {
+              if (typeof ready === "string") response = ready;
+              break;
+            }
+            await delay(100, undefined, { signal: controller.signal });
+          }
+        }
+        controller.signal.throwIfAborted();
+        const remaining = Math.max(1, deadline - performance.now());
+        const reply = await this.request("wait_silence", { silenceMs: 700, timeoutMs: remaining }, remaining + 1000);
+        return { ...reply, response };
+      })]);
+    } finally {
+      clearTimeout(timer);
+      this.cancellation.signal.removeEventListener("abort", cancel);
+      controller.abort();
+      branch.finish(false);
+    }
+  }
+  private operation(action: string, title: string, data: object = {}, timeout?: number, options?: CallOptions): Promise<void> {
+    if (this.closed) return Promise.reject(new Error("Phone is closed"));
+    const work = this.tail.then(async () => {
+      if (this.closed) throw new Error("Phone is closed");
+      const reservation = reserveEvent(), start = Date.now();
+      if (action === "call") {
+        if (this.activeCall && !this.calls.get(this.activeCall)?.recording) throw new Error("Already in a call; hang up before dialing again");
+        this.reserveCall();
+        this.activeCall = randomUUID();
+        this.calls.set(this.activeCall, { started: start, steps: [] });
+        data = { ...data, sessionId: this.activeCall };
+      }
+      const text = action === "say" ? (data as { text: string }).text : "";
+      const blocks: StepBlock[] = [];
+      let step: PhoneStep | undefined;
+      if (this.activeCall) {
+        const block: AudioBlock = { type: "audio", sessionId: this.activeCall, text, start: 0, end: 0, duration: 0, peaks: [] };
+        if (action === "call" && options?.waitFor) block.waitedForSpeech = true;
+        step = { block };
+        this.calls.get(this.activeCall)!.steps.push(step);
+        // Retain the boundary for recording finalization, without rendering a
+        // player on the hangup step.
+        if (action !== "hangup") blocks.push(block);
+      } else if (text) blocks.push({ type: "text", text });
+      try {
+        let reply = await this.request(action, data, timeout, (event, offset) => {
+          if (!step) return;
+          if (event === "speech_started") step.playbackStart = offset;
+          if (event === "operation_started") {
+            step.playbackStart = offset;
+            const steps = this.calls.get(this.activeCall!)!.steps;
+            const previous = steps.at(-2);
+            // Dialing owns the greeting/idle audio up to the next operation.
+            if (previous && previous.playbackEnd === undefined) previous.playbackEnd = offset;
+          }
+          if (event === "operation_ended") step.playbackEnd = offset;
+        });
+        if (options?.waitFor) {
+          const waited = await this.waitForResponse(options);
+          reply = waited;
+          if (step && waited.response !== undefined) step.block.response = waited.response;
+        }
+        if ((action === "say" || options?.waitFor) && step) {
+          step.playbackEnd = reply.offset;
+        }
+        recordStep({ kind: "phone", title, blocks, status: "passed", durationMs: Date.now() - start }, reservation);
+        if (action === "hangup") this.activeCall = undefined;
+      } catch (error) {
+        if ((action === "say" || action === "call") && step) {
+          // A predicate can fail independently of the native transport. Sample
+          // its current position too; wall time is not an audio-file offset.
+          const position = this.closed ? undefined : await this.request("position").catch(() => undefined);
+          step.playbackEnd = this.closed ? undefined : position?.offset ?? step.playbackEnd;
+        }
+        recordStep({ kind: "phone", title, blocks, status: "failed", error: String(error), durationMs: Date.now() - start }, reservation);
+        throw error;
+      }
+    });
+    this.tail = work.catch(() => {});
+    return work;
+  }
+  call(destination: string, options: CallOptions = {}) {
+    if (!destination || /[\s<>\r\n]/.test(destination)) return Promise.reject(new Error("Invalid phone destination"));
+    if (options.waitFor !== undefined && typeof options.waitFor !== "function") return Promise.reject(new Error("phone.call waitFor must be a predicate"));
+    return this.operation("call", `Call ${destination}`, { destination }, undefined, options);
+  }
+  say(text: string, options: SpeechOptions = {}) {
+    if (!text.trim() || text.length > 2000) return Promise.reject(new Error("phone.say requires 1–2,000 characters"));
+    if (options.speed !== undefined && (!Number.isFinite(options.speed) || options.speed < 0.7 || options.speed > 2)) return Promise.reject(new Error("Speech speed must be between 0.7 and 2"));
+    if (options.waitFor !== undefined && typeof options.waitFor !== "function") return Promise.reject(new Error("phone.say waitFor must be a predicate"));
+    const { waitFor, ...voice } = options;
+    return this.operation("say", `Say ${JSON.stringify(text)}`, { ...voice, language: voice.language ?? this.options.language ?? "en", text }, 180_000, { waitFor });
+  }
+  hangup() { return this.operation("hangup", "Hang up"); }
+  close(): Promise<void> { return this.closing ??= this.dispose(); }
+  private async dispose() {
+    this.fail(new Error("Phone closed"));
+    this.child.stdin.end();
+    // EOF interrupts synthesis/playback, hangs up, and seals the recording.
+    const timer = setTimeout(() => this.child.kill("SIGKILL"), 10_000);
+    await this.exited;
+    clearTimeout(timer);
+    await this.tail;
+  }
+  async finish(record: boolean): Promise<PhoneRecording[]> {
+    await this.close();
+    const recordings: PhoneRecording[] = [];
+    for (const [id, call] of this.calls) {
+      const r: PhoneRecording = call.recording ?? { id, startedAtMs: call.started - this.caseStart, duration: 0, bytes: 0, contentType: "audio/webm", peaks: [], error: "Phone runtime exited before the call recording was finalized" };
+      const path = join(this.directory!, `${id}.webm`);
+      if (!r.error) {
+        const size = (await stat(path).catch(() => null))?.size;
+        if (size !== r.bytes || r.bytes < 44 || r.bytes > MAX_RECORDING_BYTES) r.error = "Call recording is missing or exceeds the size limit";
+      }
+      // Say owns transmission through its optional response wait. Unrelated
+      // work and later idle time stay only in the continuous call recording.
+      // Dial/hangup retain the surrounding call audio (including the greeting).
+      for (let i = 0; i < call.steps.length; i++) {
+        const step = call.steps[i]!;
+        const end = Math.min(r.duration, step.playbackEnd ?? call.steps[i + 1]?.playbackStart ?? r.duration);
+        Object.assign(step.block, { duration: r.duration, start: Math.min(end, step.playbackStart ?? 0), end });
+      }
+      if (record && !r.error) parked.set(id, { path, directory: this.directory!, bytes: r.bytes });
+      recordings.push(r);
+    }
+    if (this.directory && ![...parked.values()].some(p => p.directory === this.directory)) await rm(this.directory, { recursive: true, force: true });
+    return record ? recordings : [];
+  }
+}
+
+export function phoneScope(caseStart = Date.now(), { record = true } = {}) {
+  const sessions = new Set<PhoneSession>();
+  let closed = false, calls = 0;
+  let finished: Promise<PhoneRecording[]> | undefined;
+  // A fork inherits its parent's completed files. Discard those before opening
+  // this case's phones; the parent VM retains its own copies for archival.
+  const cleanup = (async () => {
+    // Calls from one phone share a directory; retire files sequentially so
+    // only the last release removes it.
+    for (const id of [...parked.keys()]) await releasePhoneRecording(id);
+  })();
+  return {
+    async open(options: PhoneOptions): Promise<Phone> {
+      await cleanup;
+      if (closed) throw new Error("Phone test scope has ended");
+      const session = new PhoneSession(options, caseStart, () => { if (++calls > 8) throw new Error("A case can record at most eight calls"); });
+      sessions.add(session);
+      try { return await session.initialize(); } catch (error) { await session.finish(false); throw error; }
+    },
+    async close() { closed = true; await Promise.all([...sessions].map(s => s.close())); },
+    finish() {
+      closed = true;
+      return finished ??= Promise.all([...sessions].map(s => s.finish(record))).then(records => records.flat());
+    },
+  };
+}

package/src/recorder.ts

@@ -964,6 +964,7 @@ export function recordEnv(
  * newer SDK's step degrades to the blocks the server knows.
  */
 export type StepBlock =
+  | { type: "audio"; sessionId: string; start: number; end: number; text: string; duration: number; peaks: number[]; waitedForSpeech?: boolean; response?: string }
   | { type: "text"; text: string }
   | { type: "code"; code: string; lang?: string; label?: string }
   | { type: "json"; value: unknown; label?: string }