import { mkdirSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; import { fauxAssistantMessage, fauxToolCall, getCurrentSystemPrompt, getCurrentTools, } from "@earendil-works/pi-ai"; import { ModelRegistry } from "@earendil-works/pi-coding-agent"; import { afterEach, describe, expect, it, vi } from "vitest"; import { createPiSession, type PiSession, } from "../../../test/fixture/create-pi-session.ts"; import voice from "../index.ts"; import { __test, VoiceController, type VoiceControllerEvent, } from "../src/controller.ts"; import { NativeVoiceCall } from "../src/native-call.ts"; let session: PiSession | undefined; const controllers: VoiceController[] = []; afterEach(async () => { for (const instance of controllers.splice(0)) instance.close(); await session?.dispose(); session = undefined; }); async function waitFor(check: () => boolean): Promise { for (let attempt = 0; attempt < 100; attempt++) { if (check()) return; await new Promise((resolve) => setTimeout(resolve, 10)); } throw new Error("Timed out waiting for voice turn."); } function controller() { if (!session) throw new Error("Missing fixture session."); const sent: Array<{ text: string; delivery: string | undefined }> = []; let executorActive = false; let cancellations = 0; const instance = new VoiceController({ sendUserMessage: (text: string, options?: { deliverAs?: string }) => { sent.push({ text, delivery: options?.deliverAs }); }, } as never); controllers.push(instance); instance.beginNative( { cwd: session.cwd, sessionManager: session.session.sessionManager, model: session.session.modelRuntime.getModel("faux", "faux-model"), modelRegistry: new ModelRegistry(session.session.modelRuntime), isIdle: () => !executorActive, isProjectTrusted: () => true, abort: () => { cancellations++; }, } as never, { modelSetting: "faux/faux-model", historyDirectory: join(session.cwd, "voice-history"), }, ); return { instance, sent, setExecutorActive: (value: boolean) => { executorActive = value; }, cancellations: () => cancellations, }; } describe("voice contract integration", () => { it("rejects removed browser options without starting native audio or a model", async () => { const start = vi .spyOn(NativeVoiceCall.prototype, "start") .mockResolvedValue(); try { session = await createPiSession({ extensionPaths: [], extensionFactories: [voice], }); await session.session.prompt("/voice browser --no-open"); expect(start).not.toHaveBeenCalled(); expect(session.session.messages).toHaveLength(0); expect(session.errors).toEqual([]); } finally { start.mockRestore(); } }); it("requires interactive Pi UI rather than launching audio in a headless session", async () => { const start = vi .spyOn(NativeVoiceCall.prototype, "start") .mockResolvedValue(); try { session = await createPiSession({ extensionPaths: [], extensionFactories: [voice], }); await session.session.prompt("/voice"); expect(start).not.toHaveBeenCalled(); expect(session.session.messages).toHaveLength(0); expect(session.errors).toEqual([]); } finally { start.mockRestore(); } }); it.each(["user", "project"])( "replaces discovered %s instructions with isolated voice contract", async (scope) => { let capturedPrompt = ""; let capturedTools: string[] = []; session = await createPiSession({ extensionPaths: [], responses: [ (context) => { capturedPrompt = getCurrentSystemPrompt(context.messages); capturedTools = getCurrentTools(context.messages).map( (tool) => tool.name, ); return fauxAssistantMessage( JSON.stringify({ heard: "Check status", reply: "Everything is ready.", hotwords: [], }), ); }, ], }); const [directory, prefix] = scope === "user" ? [session.agentDir, "USER"] : [session.cwd, "PROJECT"]; const sentinels = [ `${prefix}_SYSTEM_SENTINEL`, `${prefix}_APPEND_SENTINEL`, `${prefix}_AGENTS_SENTINEL`, ]; mkdirSync(directory, { recursive: true }); for (const [name, suffix] of [ ["SYSTEM.md", "SYSTEM"], ["APPEND_SYSTEM.md", "APPEND"], ["AGENTS.md", "AGENTS"], ] as const) writeFileSync(join(directory, name), `${prefix}_${suffix}_SENTINEL`); const voice = controller(); (voice.instance as any).receive("Check status", "faux/faux-model"); await waitFor( () => (voice.instance as any).transcript.at(-1)?.text === "Everything is ready.", ); expect( (voice.instance as any).child.settingsManager.getCompactionSettings() .enabled, ).toBe(false); expect( (voice.instance as any).child.settingsManager.getCacheWarmingMode(), ).toBe("off"); expect(session.session.settingsManager.getCompactionEnabled()).toBe(true); expect(capturedPrompt).toContain("You are Pi Voice"); expect(capturedPrompt).toContain("Speak as Pi: one identity"); expect(capturedPrompt).toContain("never that work finished."); expect(capturedPrompt).toContain( "Never mention or imply delegation, other agents, an executor", ); expect(capturedPrompt).toContain("Output exactly one JSON object"); for (const sentinel of sentinels) expect(capturedPrompt).not.toContain(sentinel); expect(capturedPrompt).not.toContain( "You are an expert software engineer", ); expect(capturedPrompt).not.toContain("Pi documentation"); expect(capturedTools).toEqual([ "voice_executor_state", "voice_history_query", "voice_executor_dispatch", "voice_executor_steer", "voice_executor_cancel", ]); expect((voice.instance as any).status).toBe("ready"); }, ); it.each([ { name: "non-reasoning", reasoning: false, levelMap: undefined, expected: "off", }, { name: "reasoning supports off and minimal", reasoning: true, levelMap: { off: "off", minimal: "minimal" }, expected: "off", }, { name: "reasoning supports low only", reasoning: true, levelMap: { off: null, minimal: null, low: "low" }, expected: "low", }, ])( "uses effective thinking level for $name models", async ({ name, reasoning, levelMap, expected }) => { let callbackReasoning: unknown = Symbol("not called"); session = await createPiSession({ extensionPaths: [], responses: [ fauxAssistantMessage( JSON.stringify({ heard: "Hello", reply: "Hi.", hotwords: [] }), ), ], }); const runtime = session.session.modelRuntime; const inherited = runtime.getRegisteredProviderConfig("faux"); if (!inherited) throw new Error("Missing scripted faux provider"); const streamSimple = inherited.streamSimple; if (!streamSimple) throw new Error("Missing scripted streaming implementation"); runtime.registerProvider("faux", { ...inherited, streamSimple: (...args: Parameters) => { callbackReasoning = args[2]?.reasoning; return streamSimple(...args); }, models: [ { id: `voice-${name.replaceAll(" ", "-")}`, name, reasoning, ...(levelMap ? { thinkingLevelMap: levelMap } : {}), input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200_000, maxTokens: 8192, }, ], }); const voice = controller(); (voice.instance as any).receive( "Hello", `faux/voice-${name.replaceAll(" ", "-")}`, ); await waitFor( () => (voice.instance as any).transcript.at(-1)?.text === "Hi.", ); expect((voice.instance as any).child.thinkingLevel).toBe(expected); expect(callbackReasoning).toBe(expected === "off" ? undefined : expected); }, ); it("surfaces provider failures instead of silently settling an empty reply", async () => { session = await createPiSession({ extensionPaths: [], responses: [ () => { throw new Error("fixture provider unavailable"); }, ], }); const voice = controller(); try { (voice.instance as any).receive("Hello", "faux/faux-model"); await waitFor(() => Boolean(voice.instance.nativeSnapshot().error)); expect(voice.instance.nativeSnapshot().error).toContain( "fixture provider unavailable", ); } finally { voice.instance.close(); } }); it("registers configured voice shortcuts through Pi's public extension API", async () => { session = await createPiSession({ extensionPaths: [fileURLToPath(new URL("../index.ts", import.meta.url))], userSettings: { voice: { toggleShortcut: "alt+ctrl+x", muteShortcut: "" }, }, }); expect(session.errors).toEqual([]); const [extension] = session.extensions; expect([...(extension?.shortcuts ?? new Map()).keys()]).toContain( "ctrl+alt+x", ); expect([...(extension?.shortcuts ?? new Map()).keys()]).not.toContain( "ctrl+alt+b", ); }); it("loads through Pi and releases its session lifecycle", async () => { session = await createPiSession({ extensionPaths: [fileURLToPath(new URL("../index.ts", import.meta.url))], }); expect(session.errors).toEqual([]); const [extension] = session.extensions; expect(extension?.commands.has("voice")).toBe(true); expect([...(extension?.tools ?? new Map()).keys()]).toEqual([]); await session.session.extensionRunner.emit({ type: "session_start", reason: "startup", }); await session.session.extensionRunner.emit({ type: "session_shutdown", reason: "quit", }); }); it("exposes queued tagged follow-ups and steering as parent user messages", async () => { let release: (() => void) | undefined; session = await createPiSession({ extensionPaths: [], responses: [ () => new Promise((resolve) => { release = () => resolve(fauxAssistantMessage("first finished")); }), fauxAssistantMessage("follow-up finished"), ], }); const users: string[] = []; session.session.subscribe((event) => { if (event.type !== "message_start" || event.message.role !== "user") return; const content = event.message.content; users.push( typeof content === "string" ? content : content .filter((part) => part.type === "text") .map((part) => part.text) .join("\n"), ); }); const initial = session.session.prompt("initial"); await waitFor(() => session!.providerState.callCount === 1); await session.session.followUp( "[Voice executor request id=voice-follow-up]\nfollow-up work", ); release?.(); await initial; expect(users).toContain( "[Voice executor request id=voice-follow-up]\nfollow-up work", ); let releaseSteer: (() => void) | undefined; session.setResponses([ () => new Promise((resolve) => { releaseSteer = () => resolve(fauxAssistantMessage("second finished")); }), fauxAssistantMessage("steer finished"), ]); const second = session.session.prompt("second"); await waitFor(() => session!.providerState.callCount === 3); await session.session.steer( "[Voice executor request id=voice-steer]\nsteer work", ); releaseSteer?.(); await second; expect(users).toContain( "[Voice executor request id=voice-steer]\nsteer work", ); }); it("replaces heard text in place and refreshes next-turn hotwords through Pi", async () => { const cases = [ { hotwords: ["ONNX"] }, { hotwords: [] }, { hotwords: ["Nushell", "Zig"] }, { hotwords: [], malformed: true }, ]; session = await createPiSession({ extensionPaths: [], responses: cases.map(({ hotwords, malformed }) => fauxAssistantMessage( malformed ? "not structured JSON" : JSON.stringify({ heard: "Use ONNX with Nushell.", reply: "Ready.", hotwords, }), ), ), }); const { instance } = controller(); const events: VoiceControllerEvent[] = []; instance.subscribe((event) => events.push(event)); for (const [index, candidate] of cases.entries()) { (instance as any).receive(`raw onyx ${index}`, "faux/faux-model"); await waitFor( () => events.filter((event) => event.type === "assistant-complete") .length === index + 1 && instance.nativeSnapshot().status === "ready", ); const hotwords = events.filter((event) => event.type === "hotwords"); expect(hotwords).toHaveLength(index + 1); expect(hotwords.at(-1)).toMatchObject({ terms: candidate.hotwords }); const users = instance .nativeSnapshot() .transcript.filter((entry) => entry.role === "user"); expect(users).toHaveLength(index + 1); if (!candidate.malformed) { expect(users.at(-1)?.text).toBe("Use ONNX with Nushell."); expect( events.filter((event) => event.type === "heard").at(-1), ).toMatchObject({ userTurnId: users.at(-1)?.id, text: users.at(-1)?.text, }); } } }); it("runs isolated child tools through Pi's scripted provider with immediate executor receipts", async () => { let receiptContext = ""; session = await createPiSession({ extensionPaths: [], responses: [ fauxAssistantMessage( fauxToolCall("voice_executor_dispatch", { text: "inspect status" }), ), (context) => { receiptContext = JSON.stringify(context.messages); return fauxAssistantMessage( JSON.stringify({ heard: "Please inspect status", reply: "I'm on it.", hotwords: [], }), ); }, ], }); const voice = controller(); (voice.instance as any).receive("Please inspect status", "faux/faux-model"); await waitFor( () => session!.providerState.callCount === 2 && (voice.instance as any).transcript.at(-1)?.text === "I'm on it.", ); expect((voice.instance as any).child.getActiveToolNames()).toEqual([ "voice_executor_state", "voice_history_query", "voice_executor_dispatch", "voice_executor_steer", "voice_executor_cancel", ]); expect(receiptContext).toContain('Receipt: {\\"id\\":'); expect(receiptContext).toContain('\\"accepted\\":true'); expect(voice.sent).toHaveLength(1); expect(voice.sent[0]).toMatchObject({ delivery: undefined }); expect( __test.requestIdFromMessage({ role: "user", content: voice.sent[0]?.text, }), ).toMatch(/^voice-/u); const tools = (voice.instance as any).tools(); voice.instance.onExecutorMessageStart({ role: "user", content: voice.sent[0]?.text, }); voice.setExecutorActive(true); const followUp = await tools .find((tool: { name: string }) => tool.name === "voice_executor_dispatch") .execute("tool", { text: "inspect after the current turn" }); const steer = await tools .find((tool: { name: string }) => tool.name === "voice_executor_steer") .execute("tool", { text: "use the latest result" }); await tools .find((tool: { name: string }) => tool.name === "voice_executor_cancel") .execute("tool", {}); expect(followUp.details).toMatchObject({ accepted: true, delivery: "followUp", }); expect(steer.details.id).toBe( __test.requestIdFromMessage({ role: "user", content: voice.sent[0]?.text, }), ); expect(followUp.details.id).not.toBe(steer.details.id); expect(steer.details).toMatchObject({ accepted: true, delivery: "steer" }); expect(voice.sent.at(-1)?.delivery).toBe("steer"); expect( __test.requestIdFromMessage({ role: "user", content: voice.sent.at(-1)?.text, }), ).toMatch(/^voice-/u); expect(voice.cancellations()).toBe(1); }); it("forwards one matching final executor result after settlement", async () => { let resultContext = ""; session = await createPiSession({ extensionPaths: [], responses: [ fauxAssistantMessage( fauxToolCall("voice_executor_dispatch", { text: "inspect status" }), ), fauxAssistantMessage( JSON.stringify({ heard: "Please inspect status", reply: "I'm on it.", hotwords: [], }), ), (context) => { resultContext = JSON.stringify(context.messages); return fauxAssistantMessage( JSON.stringify({ heard: "Please inspect status", reply: "I found the status is healthy.", hotwords: [], }), ); }, ], }); const voice = controller(); (voice.instance as any).receive("Please inspect status", "faux/faux-model"); await waitFor( () => session!.providerState.callCount === 2 && !(voice.instance as any).draining, ); const assistantTurnId = (voice.instance as any).activeTurn.assistantId; const request = voice.sent[0]; const id = __test.requestIdFromMessage({ role: "user", content: request?.text, }); expect(id).toMatch(/^voice-/u); voice.instance.onExecutorMessageStart({ role: "user", content: request?.text, }); // Pi emits assistant/tool starts throughout one executor request. voice.instance.onExecutorMessageStart({ role: "assistant" }); const toolCycle = { role: "assistant", stopReason: "toolUse", content: [ { type: "toolCall", id: "tool-1", name: "read", arguments: {} }, ], } as never; voice.instance.onExecutorMessageEnd(toolCycle); voice.instance.onExecutorMessageStart({ role: "tool" }); voice.instance.onExecutorMessageEnd({ role: "tool" }); voice.instance.onExecutorMessageStart({ role: "assistant" }); const final = fauxAssistantMessage("status is healthy") as never; voice.instance.onExecutorMessageEnd(final); voice.instance.onExecutorAgentEnd([toolCycle, final]); voice.instance.onExecutorSettled(); voice.instance.onExecutorSettled(); await new Promise((resolve) => setTimeout(resolve, 20)); expect(session.providerState.callCount).toBe(2); expect((voice.instance as any).pendingResults).toHaveLength(1); expect(voice.instance.turnBoundary(assistantTurnId)).toBe(true); await waitFor( () => session!.providerState.callCount === 3 && (voice.instance as any).transcript.at(-1)?.text === "I found the status is healthy.", ); expect(resultContext).toContain(' tool.name === "voice_executor_state"); const state = await stateTool.execute("inspect", {}); expect(state.details.job).toMatchObject({ id, status: "completed" }); voice.instance.close(); }); it("ignores unrelated executor finals and clears stale callbacks on close", () => { const instance = new VoiceController({ sendUserMessage: () => undefined, } as never); instance.start({ cwd: "/fixture", isIdle: () => true, } as never); (instance as any).onExecutorMessageEnd(fauxAssistantMessage("unrelated")); (instance as any).onExecutorSettled(); expect((instance as any).pendingResults).toEqual([]); instance.close(); (instance as any).onExecutorMessageStart({ role: "user", content: "[Voice executor request id=voice-stale]\\nwork", }); (instance as any).onExecutorSettled(); expect((instance as any).pendingResults).toEqual([]); }); it("stops an active scripted child turn without cancelling the executor", async () => { let resolveResponse: | ((value: ReturnType) => void) | undefined; session = await createPiSession({ extensionPaths: [], responses: [ () => new Promise((resolve) => { resolveResponse = resolve; }), ], }); const voice = controller(); (voice.instance as any).receive("Wait for it", "faux/faux-model"); await waitFor(() => session!.providerState.callCount === 1); (voice.instance as any).stopVoice(); resolveResponse?.(fauxAssistantMessage("late reply")); await waitFor(() => (voice.instance as any).status === "ready"); expect((voice.instance as any).transcript.at(-1)).toMatchObject({ role: "assistant", text: "", }); expect(voice.cancellations()).toBe(0); }); });