A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.
TypeScript
import * as childProcess from "node:child_process";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import type { AgentSupervisor } from "../src/supervisor.ts";
import { fakeSupervisor, tempDir, waitFor } from "./helpers.ts";
import { itServerMode } from "./support/windows.ts";
vi.mock("node:child_process", { spy: true });
const running: AgentSupervisor[] = [];
afterEach(async () => {
await Promise.all(running.splice(0).map((s) => s.stop()));
});
function track<T extends { supervisor: AgentSupervisor }>(value: T): T {
running.push(value.supervisor);
return value;
}
const STUBBORN_AGENT = `
process.on("SIGTERM", () => {});
process.stdin.setEncoding("utf8");
let buffer = "";
process.stdin.on("data", (chunk) => {
buffer += chunk;
for (;;) {
const newline = buffer.indexOf("\\n");
if (newline < 0) break;
const line = buffer.slice(0, newline);
buffer = buffer.slice(newline + 1);
if (!line) continue;
const record = JSON.parse(line);
if (record.type === "get_state") {
process.stdout.write(JSON.stringify({
type: "response", id: record.id, command: "get_state", success: true,
data: { sessionId: "stubborn" }
}) + "\\n");
}
}
});
process.stdin.on("end", () => process.stdin.resume());
setInterval(() => {}, 1000);
`;
describe("AgentSupervisor", () => {
it("enforces packaged Windows setup opt-outs after prepareSpawn on every spawn without launching the engine", async () => {
const runtime = join(process.cwd(), "packaged-runtime");
const script = join(runtime, "daemon", "node_modules", "gentle-pi", "bin", "gentle-shell.mjs");
const spawn = vi.spyOn(childProcess, "spawn").mockImplementation(() => {
throw new Error("spawn intercepted");
});
try {
const { supervisor } = fakeSupervisor({
platform: "win32",
args: [script, "--home", "/agent"],
env: { GENTLE_DOT_RUNTIME: runtime, GENTLE_SHELL_NO_AUTO_SETUP: "0" },
prepareSpawn: () => ({ GENTLE_PI_SKIP_GENTLE_AI_INSTALL: "0", PREPARED: "yes" }),
});
for (let attempt = 0; attempt < 2; attempt++) {
await expect(supervisor.start()).rejects.toThrow("spawn intercepted");
const options = spawn.mock.calls[attempt]?.[2] as childProcess.SpawnOptions;
expect(options.env).toMatchObject({
GENTLE_SHELL_NO_AUTO_SETUP: "1",
GENTLE_PI_SKIP_GENTLE_AI_INSTALL: "1",
PREPARED: "yes",
});
}
} finally {
spawn.mockRestore();
}
});
it("spawns the agent in RPC mode with the session dir and extra args", async () => {
const argsFile = join(tempDir(), "argv.json");
const { supervisor, dataDir } = track(
fakeSupervisor({ env: { ...process.env, FAKE_AGENT_ARGS_FILE: argsFile }, extraArgs: ["--x", "1"] }),
);
await supervisor.start();
const argv = JSON.parse(readFileSync(argsFile, "utf8")) as string[];
expect(argv).toEqual(["--mode", "rpc", "--session-dir", join(dataDir, "sessions"), "--x", "1"]);
expect(supervisor.state).toBe("ready");
});
itServerMode(
"starts the agent as the configured user, and as the daemon's own user without one (S25.8)",
async () => {
const own = { uid: process.getuid?.() ?? 0, gid: process.getgid?.() ?? 0 };
const processFile = join(tempDir(), "process.json");
const env = { ...process.env, FAKE_AGENT_PROCESS_FILE: processFile };
// Without a user, the agent runs as the daemon does today.
const plain = track(fakeSupervisor({ env }));
await plain.supervisor.start();
expect(JSON.parse(readFileSync(processFile, "utf8"))).toMatchObject(own);
await plain.supervisor.stop();
const as = track(fakeSupervisor({ env, user: own }));
await as.supervisor.start();
expect(JSON.parse(readFileSync(processFile, "utf8"))).toMatchObject(own);
expect(as.supervisor.state).toBe("ready");
},
);
it.skipIf((process.getuid?.() ?? 0) === 0)(
"applies the user to the spawn: one it cannot take is refused",
async () => {
const own = { uid: process.getuid?.() ?? 0, gid: process.getgid?.() ?? 0 };
const { supervisor } = track(
fakeSupervisor({ user: { uid: own.uid + 1, gid: own.gid }, startTimeoutMs: 2000 }),
);
await expect(supervisor.start()).rejects.toThrow();
expect(supervisor.state).not.toBe("ready");
},
);
it("correlates responses by id across concurrent commands", async () => {
const { supervisor } = track(fakeSupervisor());
await supervisor.start();
const [state, commands] = await Promise.all([
supervisor.request({ type: "get_state" }),
supervisor.request({ type: "get_commands" }),
]);
expect(state.command).toBe("get_state");
expect(commands.command).toBe("get_commands");
});
it("rejects a failed command with the agent's error", async () => {
const { supervisor } = track(fakeSupervisor());
await supervisor.start();
await expect(supervisor.request({ type: "switch_session", sessionPath: "/nope.jsonl" })).rejects.toThrow(
"Session not found",
);
});
it("forwards session events and tracks busy until agent_settled", async () => {
const { supervisor, events } = track(fakeSupervisor());
await supervisor.start();
await supervisor.request({ type: "prompt", message: "hello" });
await waitFor(() => events.some((e) => e.type === "agent_settled"));
expect(events.map((e) => e.type)).toContain("message_update");
expect(supervisor.busy).toBe(false);
});
it("is not left busy when the run settles before the prompt response is handled", async () => {
const { supervisor, events } = track(fakeSupervisor());
await supervisor.start();
await supervisor.request({ type: "prompt", message: "burst" });
expect(events.some((e) => e.type === "agent_settled")).toBe(true);
expect(supervisor.busy).toBe(false);
});
it("respawns after a crash, reopens the same conversation, and reports the interruption", async () => {
const { supervisor, events } = track(fakeSupervisor());
await supervisor.start();
await supervisor.request({ type: "prompt", message: "first" });
await waitFor(() => events.some((e) => e.type === "agent_settled"));
const sessionBefore = supervisor.sessionFile;
const pidBefore = supervisor.pid;
await supervisor.request({ type: "prompt", message: "crash" });
await waitFor(() => events.some((e) => e.type === "interrupted"));
expect(supervisor.state).toBe("ready");
expect(supervisor.pid).not.toBe(pidBefore);
expect(supervisor.sessionFile).toBe(sessionBefore);
const states = events.flatMap((e) => (e.type === "supervisor_state" && "state" in e ? [e.state] : []));
expect(states).toContain("restarting");
const history = await supervisor.request({ type: "get_messages" });
const texts = (history.data as { messages: { content: unknown }[] }).messages.map((m) => m.content);
expect(texts[0]).toBe("first");
});
it("does not report an interruption when the agent dies while idle", async () => {
const { supervisor, events } = track(fakeSupervisor());
await supervisor.start();
process.kill(supervisor.pid ?? 0, "SIGKILL");
await waitFor(
() =>
events.filter((e) => e.type === "supervisor_state" && "state" in e && e.state === "ready").length >=
2,
);
expect(events.some((e) => e.type === "interrupted")).toBe(false);
});
it("rejects pending commands when the agent exits", async () => {
const { supervisor } = track(fakeSupervisor());
await supervisor.start();
const pending = supervisor.request({ type: "noreply" });
process.kill(supervisor.pid ?? 0, "SIGKILL");
await expect(pending).rejects.toThrow(/agent exited/i);
});
it("reopens the last conversation after the daemon itself restarts", async () => {
const dataDir = tempDir();
const first = track(fakeSupervisor({ dataDir }));
await first.supervisor.start();
await first.supervisor.request({ type: "prompt", message: "remember me" });
await waitFor(() => first.events.some((e) => e.type === "agent_settled"));
await waitFor(() => first.supervisor.sessionFile && first.supervisor.sessionFile);
const session = first.supervisor.sessionFile;
await first.supervisor.stop();
const second = track(fakeSupervisor({ dataDir }));
await second.supervisor.start();
expect(second.supervisor.sessionFile).toBe(session);
});
it("restarts on request, keeping the conversation and without an interruption", async () => {
const { supervisor, events } = track(fakeSupervisor());
await supervisor.start();
await supervisor.request({ type: "prompt", message: "keep me" });
await waitFor(() => events.some((e) => e.type === "agent_settled"));
const session = supervisor.sessionFile;
const pid = supervisor.pid;
await supervisor.restart();
expect(supervisor.state).toBe("ready");
expect(supervisor.pid).not.toBe(pid);
expect(supervisor.sessionFile).toBe(session);
expect(events.some((e) => e.type === "interrupted")).toBe(false);
});
it("a restart asked while the engine starts waits for it, then replaces it once (S1)", async () => {
let spawns = 0;
const logs: string[] = [];
const { supervisor, events } = track(
fakeSupervisor({
env: { ...process.env, FAKE_AGENT_START_DELAY_MS: "300" },
prepareSpawn: () => {
spawns += 1;
return {};
},
log: (line) => logs.push(line),
}),
);
const starting = supervisor.start();
const firstPid = supervisor.pid;
// Two requests while starting (computer control, then connector files put back) make one restart.
const restarts = [supervisor.restart(), supervisor.restart()];
await expect(starting).resolves.toBeUndefined();
await Promise.all(restarts);
expect(supervisor.state).toBe("ready");
expect(spawns).toBe(2);
expect(supervisor.pid).not.toBe(firstPid);
const states = events.flatMap((e) => (e.type === "supervisor_state" && "state" in e ? [e.state] : []));
expect(states).toEqual(["starting", "ready", "restarting", "ready"]);
expect(events.some((e) => e.type === "interrupted")).toBe(false);
expect(logs.filter((line) => /exited unexpectedly|restart failed/.test(line))).toEqual([]);
});
it("a stop while a restart waits for the start starts nothing again", async () => {
let spawns = 0;
const { supervisor } = track(
fakeSupervisor({
env: { ...process.env, FAKE_AGENT_START_DELAY_MS: "300" },
prepareSpawn: () => {
spawns += 1;
return {};
},
}),
);
const starting = supervisor.start().catch(() => {});
const restarting = supervisor.restart();
await supervisor.stop();
await Promise.all([starting, restarting]);
await new Promise((resolve) => setTimeout(resolve, 200));
expect(spawns).toBe(1);
expect(supervisor.state).toBe("stopped");
expect(supervisor.pid).toBeUndefined();
});
it("a restart while ready replaces the engine right away, once", async () => {
let spawns = 0;
const { supervisor, events } = track(
fakeSupervisor({
prepareSpawn: () => {
spawns += 1;
return {};
},
}),
);
await supervisor.start();
await supervisor.restart();
expect(spawns).toBe(2);
const states = events.flatMap((e) => (e.type === "supervisor_state" && "state" in e ? [e.state] : []));
expect(states).toEqual(["starting", "ready", "restarting", "ready"]);
});
it("a stop during a restart starts nothing again (S35.2: the app quitting does both)", async () => {
const { supervisor } = track(fakeSupervisor());
await supervisor.start();
const restarting = supervisor.restart();
await supervisor.stop();
await restarting;
await new Promise((resolve) => setTimeout(resolve, 200));
expect(supervisor.state).toBe("stopped");
expect(supervisor.pid).toBeUndefined();
});
it("stops cleanly and reports the stopped state", async () => {
const { supervisor } = track(fakeSupervisor());
await supervisor.start();
await supervisor.stop();
expect(supervisor.state).toBe("stopped");
await expect(supervisor.request({ type: "get_state" })).rejects.toThrow(/not ready/i);
});
it("closes a cooperative agent within the production grace without escalation", async () => {
const escalations: boolean[] = [];
const { supervisor } = track(
fakeSupervisor({
// Keep the production grace: OS scheduling under suite load is not a 10ms contract.
terminateProcessTree: async (_child, force) => {
escalations.push(force);
return false;
},
}),
);
await supervisor.start();
await supervisor.stop();
expect(escalations).toEqual([]);
expect(supervisor.state).toBe("stopped");
expect(supervisor.pid).toBeUndefined();
});
it.each([
["win32", 12000],
["linux", 2000],
["darwin", 2000],
] as const)(
"coordinates default %s escalation windows without changing Unix timing",
async (platform, windowMs) => {
const escalations: boolean[] = [];
const { supervisor } = track(
fakeSupervisor({
platform,
command: process.execPath,
args: ["-e", STUBBORN_AGENT, "--"],
stopTimeoutMs: 1,
terminateProcessTree: async (child, force) => {
escalations.push(force);
if (force) child.kill("SIGKILL");
return true;
},
}),
);
await supervisor.start();
vi.useFakeTimers();
const stopped = supervisor.stop();
void stopped.catch(() => {});
try {
await vi.advanceTimersByTimeAsync(1);
expect(escalations).toEqual([false]);
await vi.advanceTimersByTimeAsync(windowMs - 1);
expect(escalations).toEqual([false]);
await vi.advanceTimersByTimeAsync(1);
expect(escalations).toEqual([false, true]);
await stopped;
expect(supervisor.state).toBe("stopped");
expect(supervisor.pid).toBeUndefined();
} finally {
vi.useRealTimers();
const pid = supervisor.pid;
// Only a positive PID is the owned fixture; a throw here would hide the test's own failure.
if (pid !== undefined && pid > 0) {
process.kill(pid, "SIGKILL");
await waitFor(() => supervisor.state === "stopped");
}
}
},
);
it("forces a Windows tree at once when the soft taskkill fails, without waiting the hard window", async () => {
// taskkill /T without /F cannot end a windowless console process: it exits 255 at once.
const escalations: boolean[] = [];
const { supervisor } = track(
fakeSupervisor({
platform: "win32",
command: process.execPath,
args: ["-e", STUBBORN_AGENT, "--"],
stopTimeoutMs: 1,
terminateProcessTree: async (child, force) => {
escalations.push(force);
if (!force) throw new Error("taskkill failed for process tree with exit code 255");
child.kill("SIGKILL");
return true;
},
}),
);
await supervisor.start();
vi.useFakeTimers();
const stopped = supervisor.stop();
void stopped.catch(() => {});
try {
await vi.advanceTimersByTimeAsync(1);
expect(escalations).toEqual([false, true]);
vi.useRealTimers();
await stopped;
expect(supervisor.state).toBe("stopped");
// The hard window's own escalation finds the child gone: nothing is forced twice.
expect(escalations).toEqual([false, true]);
} finally {
vi.useRealTimers();
}
});
it("never escalates on a root that already exited while its children still hold the pipes", async () => {
// The engine exits once its stdin closes, but close waits for children holding the inherited
// pipes: its PID is already free then, and Windows may reuse it.
const agent = `
const { spawn } = require("node:child_process");
spawn(process.execPath, ["-e", "setTimeout(() => {}, 1500)"], { stdio: "inherit" });
process.stdin.setEncoding("utf8");
let buffer = "";
process.stdin.on("data", (chunk) => {
buffer += chunk;
for (;;) {
const newline = buffer.indexOf("\\n");
if (newline < 0) break;
const record = JSON.parse(buffer.slice(0, newline));
buffer = buffer.slice(newline + 1);
if (record.type === "get_state")
process.stdout.write(JSON.stringify({ type: "response", id: record.id, command: "get_state", success: true, data: {} }) + "\\n");
}
});
process.stdin.on("end", () => process.exit(0));
`;
const escalations: boolean[] = [];
const { supervisor } = track(
fakeSupervisor({
platform: "win32",
command: process.execPath,
args: ["-e", agent, "--"],
stopTimeoutMs: 200,
hardStopTimeoutMs: 200,
terminationFailureTimeoutMs: 5000,
terminateProcessTree: async (_child, force) => {
escalations.push(force);
return true;
},
}),
);
await supervisor.start();
await supervisor.stop();
expect(supervisor.state).toBe("stopped");
expect(escalations).toEqual([]);
});
it("keeps both Windows default stages bounded without rejecting before taskkill can finish", async () => {
const escalations: boolean[] = [];
const { supervisor } = track(
fakeSupervisor({
platform: "win32",
command: process.execPath,
args: ["-e", STUBBORN_AGENT, "--"],
stopTimeoutMs: 1,
terminateProcessTree: async (_child, force) => {
escalations.push(force);
return false;
},
}),
);
await supervisor.start();
const pid = supervisor.pid;
const sessionId = supervisor.sessionId;
vi.useFakeTimers();
let failure: Error | undefined;
const stopped = supervisor.stop().catch((error) => {
failure = error;
});
try {
await vi.advanceTimersByTimeAsync(24000);
expect(failure).toBeUndefined();
expect(escalations).toEqual([false, true]);
await vi.advanceTimersByTimeAsync(1);
await stopped;
expect(failure?.message).toBe(`Failed to stop agent process ${pid} after bounded termination`);
expect(supervisor.pid).toBe(pid);
expect(supervisor.sessionId).toBe(sessionId);
} finally {
vi.useRealTimers();
// Only the current positive PID is the owned fixture; a throw here would hide the test's own failure.
if (pid && pid > 0 && supervisor.pid === pid) {
process.kill(pid, "SIGKILL");
await waitFor(() => supervisor.state === "stopped");
}
}
});
it("rejects stop actionably when bounded soft and hard termination do not close the child", async () => {
const escalations: boolean[] = [];
const { supervisor } = fakeSupervisor({
command: process.execPath,
args: ["-e", STUBBORN_AGENT, "--"],
stopTimeoutMs: 10,
hardStopTimeoutMs: 10,
terminationFailureTimeoutMs: 10,
terminateProcessTree: async (_child, force) => {
escalations.push(force);
return false;
},
});
await supervisor.start();
const pid = supervisor.pid;
await expect(supervisor.stop()).rejects.toThrow(/failed to stop agent process/i);
expect(escalations).toEqual([false, true]);
expect(supervisor.pid).toBe(pid);
if (!pid || pid <= 0) throw new Error("Missing owned test child PID");
process.kill(pid, "SIGKILL");
await waitFor(() => supervisor.state === "stopped");
});
it("a failed restart does not report ready, and the engine comes back once the old process closes", async () => {
const { supervisor, events } = fakeSupervisor({
command: process.execPath,
args: ["-e", STUBBORN_AGENT, "--"],
stopTimeoutMs: 10,
hardStopTimeoutMs: 10,
terminationFailureTimeoutMs: 10,
terminateProcessTree: async () => false,
});
await supervisor.start();
const pid = supervisor.pid;
if (!pid || pid <= 0) throw new Error("Missing owned test child PID");
await expect(supervisor.restart()).rejects.toThrow(/failed to stop agent process/i);
// The old engine is still current but no longer reachable: not shown as ready.
expect(supervisor.state).toBe("restarting");
expect(events.at(-1)).toEqual({ type: "supervisor_state", state: "restarting" });
await expect(supervisor.request({ type: "get_state" })).rejects.toThrow(/not ready/i);
process.kill(pid, "SIGKILL");
await waitFor(() => supervisor.state === "ready" && supervisor.pid !== pid);
// The replacement ignores escalation too: end it here, as the test owns both processes.
const next = supervisor.pid;
if (!next || next <= 0) throw new Error("Missing replacement test child PID");
const stopped = supervisor.stop();
process.kill(next, "SIGKILL");
await stopped;
expect(supervisor.state).toBe("stopped");
});
it("rejects restart actionably instead of spawning over a child that did not terminate", async () => {
const { supervisor } = fakeSupervisor({
command: process.execPath,
args: ["-e", STUBBORN_AGENT, "--"],
stopTimeoutMs: 10,
hardStopTimeoutMs: 10,
terminationFailureTimeoutMs: 10,
terminateProcessTree: async () => false,
});
await supervisor.start();
const pid = supervisor.pid;
await expect(supervisor.restart()).rejects.toThrow(/failed to stop agent process/i);
expect(supervisor.pid).toBe(pid);
if (!pid || pid <= 0) throw new Error("Missing owned test child PID");
const stopped = supervisor.stop();
process.kill(pid, "SIGKILL");
await stopped;
expect(supervisor.state).toBe("stopped");
});
});