repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/voice/__tests__/contract.test.ts
Rawimport { 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<void> {
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<typeof streamSimple>) => {
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('<work-result id=\\"');
expect(resultContext).toContain("status is healthy");
expect(voice.sent).toHaveLength(1);
voice.instance.onExecutorMessageStart({
role: "user",
content: "unrelated queued work",
});
const stateTool = (voice.instance as any)
.tools()
.find((tool: { name: string }) => 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<typeof fauxAssistantMessage>) => 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);
});
});