Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
10.5 KB
Raw Blame
// A4: with GENTLE_DOT_ENGRAM=private, the memory server the engine starts outlives it. The daemon
// stops it when it closes, only when the daemon caused it (nothing listened on the private port
// at start) and it serves the private data folder. The memory server here is a stand-in on a
// free port; nothing is stopped by name, only the PIDs this test started.
import { type ChildProcess, execFileSync, spawn } from "node:child_process";
import { mkdirSync, writeFileSync } from "node:fs";
import { type AddressInfo, createServer } from "node:net";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { startDaemon } from "../src/daemon.ts";
import { listenerLookupTimeoutMs, privateMemory } from "../src/isolation.ts";
import { FAKE_AGENT, tempDir, waitFor } from "./helpers.ts";

const hasLsof = (() => {
	try {
		execFileSync("which", ["lsof"], { stdio: "ignore" });
		return true;
	} catch {
		return false;
	}
})();

const started: ChildProcess[] = [];
afterEach(() => {
	for (const child of started.splice(0))
		if (child.exitCode === null && child.signalCode === null) child.kill();
});

function freePort(): Promise<number> {
	return new Promise((resolve) => {
		const server = createServer();
		server.listen(0, "127.0.0.1", () => {
			const { port } = server.address() as { port: number };
			server.close(() => resolve(port));
		});
	});
}

/** A memory server stand-in: answers /health with its instance id, like Engram. */
async function memoryServer(port: number, instanceId: string): Promise<ChildProcess> {
	const child = spawn(
		process.execPath,
		[
			"-e",
			`require("http").createServer((q, s) => s.end(JSON.stringify({ status: "ok", instance_id: ${JSON.stringify(instanceId)} }))).listen(${port}, "127.0.0.1", () => console.log("up"))`,
		],
		{ stdio: ["ignore", "pipe", "ignore"] },
	);
	started.push(child);
	await new Promise((resolve) => child.stdout?.once("data", resolve));
	return child;
}

const running = (child: ChildProcess) => child.exitCode === null && child.signalCode === null;

async function daemon(port: number) {
	const dataDir = tempDir();
	// The private memory's data folder is under the engine's home: <data>/home/.engram.
	mkdirSync(join(dataDir, "home", ".engram"), { recursive: true });
	writeFileSync(join(dataDir, "home", ".engram", ".instance-id"), "private-instance\n");
	return startDaemon({
		port: 0,
		host: "127.0.0.1",
		dataDir,
		workspace: join(dataDir, "workspace"),
		uiDir: dataDir,
		agentCommand: process.execPath,
		agentArgs: [FAKE_AGENT],
		agentHome: join(dataDir, "agent"),
		agentEnv: {
			PATH: process.env.PATH,
			HOME: tempDir(),
			GENTLE_DOT_ENGRAM: "private",
			GENTLE_DOT_ENGRAM_PORT: String(port),
		},
	});
}

describe.skipIf(!hasLsof)("private memory server (A4)", () => {
	it("stops the private memory server it caused to start, by PID, when it closes", async () => {
		const port = await freePort();
		const d = await daemon(port);
		const memory = await memoryServer(port, "private-instance");
		await d.close();
		await waitFor(() => !running(memory));
		expect(memory.signalCode).toBe("SIGTERM");
	});

	it("leaves a memory server that was already running, or that serves other data", async () => {
		const before = await freePort();
		const already = await memoryServer(before, "private-instance");
		const first = await daemon(before);
		await first.close();
		const other = await freePort();
		const second = await daemon(other);
		const foreign = await memoryServer(other, "someone-else");
		await second.close();
		await new Promise((resolve) => setTimeout(resolve, 300));
		expect(running(already)).toBe(true);
		expect(running(foreign)).toBe(true);
	});
});

describe("private memory listener lookup", () => {
	it("gives Windows' PowerShell lookup time to start on a busy machine, and lsof the usual bound", () => {
		expect(listenerLookupTimeoutMs("win32")).toBe(15_000);
		expect(listenerLookupTimeoutMs("linux")).toBe(5000);
		expect(listenerLookupTimeoutMs("darwin")).toBe(5000);
	});
});

describe.runIf(process.platform === "win32")("private memory listener lookup on Windows", () => {
	it("finds a real listener through PowerShell and reports a free port as empty", async () => {
		const server = createServer();
		await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));
		const port = String((server.address() as AddressInfo).port);
		const env = { GENTLE_DOT_ENGRAM: "private", GENTLE_DOT_ENGRAM_PORT: port };
		try {
			// Someone already listens (this process): private memory claims nothing.
			expect(await privateMemory(env, tempDir(), () => {})).toBeUndefined();
		} finally {
			await new Promise<void>((done) => server.close(() => done()));
		}
		// Nothing listens now: the daemon would own the server it causes to start.
		expect(await privateMemory(env, tempDir(), () => {})).toBeDefined();
	}, 60_000);
});

describe("private memory ownership safeguards", () => {
	async function fixture(
		outputs: Array<{ code: number; stdout: string; stderr?: string }>,
		instance = "owned",
	) {
		const dataDir = tempDir();
		mkdirSync(join(dataDir, "home", ".engram"), { recursive: true });
		writeFileSync(join(dataDir, "home", ".engram", ".instance-id"), "owned\n");
		const runListenerCommand = vi.fn(async (_command: string, _args: readonly string[]) => {
			const next = outputs.shift();
			if (!next) throw new Error("unexpected lookup");
			return { stderr: "", ...next };
		});
		const kill = vi.fn();
		const health = vi.fn(async () => ({ instance_id: instance }));
		const port = String(await freePort());
		const base = { GENTLE_DOT_ENGRAM: "private", GENTLE_DOT_ENGRAM_PORT: port };
		const options = { platform: "win32" as const, runListenerCommand, kill, health };
		return { dataDir, base, options, kill, runListenerCommand, port };
	}
	const empty = { code: 0, stdout: "" };
	const one = { code: 0, stdout: "12345\r\n12345\r\n" };

	it("terminates only a stable positive PID with matching health identity", async () => {
		const f = await fixture([empty, one, one]);
		const owned = await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options);
		expect(owned).toBeDefined();
		await owned?.stop();
		expect(f.kill).toHaveBeenCalledExactlyOnceWith(12345, "SIGTERM");
		expect(f.runListenerCommand).toHaveBeenCalledTimes(3);
		expect(f.runListenerCommand.mock.calls[0]?.[0]).toBe("powershell.exe");
	});

	it.each([
		{ code: 2, stdout: "", stderr: "lookup failed" },
		{ code: 0, stdout: "0" },
		{ code: 0, stdout: "garbage" },
		{ code: 0, stdout: "12345\n12346" },
	])("starts without claiming ownership when the startup lookup is uncertain: %j", async (output) => {
		const f = await fixture([output]);
		const log = vi.fn();
		expect(await privateMemory(f.base, f.dataDir, log, undefined, f.options)).toBeUndefined();
		expect(log).toHaveBeenCalledWith(
			`cannot verify private memory listener on port ${f.port} (${output.code === 0 && output.stdout.includes("\n") ? "ambiguous" : "failed"} lookup); will not stop it`,
		);
		expect(f.kill).not.toHaveBeenCalled();
	});

	it("does not claim a pre-existing listener", async () => {
		const f = await fixture([one]);
		expect(await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options)).toBeUndefined();
		expect(f.kill).not.toHaveBeenCalled();
	});

	it.each([
		{ code: 2, stdout: "", stderr: "lookup failed" },
		{ code: 0, stdout: "0" },
		{ code: 0, stdout: "12345\n12346" },
	])("leaves a listener alone when close lookup is uncertain: %j", async (output) => {
		const f = await fixture([empty, output]);
		await (await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options))?.stop();
		expect(f.kill).not.toHaveBeenCalled();
	});

	it("does not terminate when the PID changes after the health check", async () => {
		const f = await fixture([empty, one, { code: 0, stdout: "12346" }]);
		await (await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options))?.stop();
		expect(f.kill).not.toHaveBeenCalled();
	});

	it("does not terminate another memory instance", async () => {
		const f = await fixture([empty, one], "foreign");
		await (await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options))?.stop();
		expect(f.kill).not.toHaveBeenCalled();
	});

	it("does not take a failed command for an empty port, and still starts", async () => {
		const f = await fixture([]);
		f.runListenerCommand.mockRejectedValueOnce(new Error("spawn failed"));
		const log = vi.fn();
		expect(await privateMemory(f.base, f.dataDir, log, undefined, f.options)).toBeUndefined();
		expect(log).toHaveBeenCalledWith(expect.stringMatching(/cannot verify .* will not stop it/));
		expect(f.kill).not.toHaveBeenCalled();
	});

	it("preserves the Unix no-match exit code and verifies stable ownership before stopping", async () => {
		const f = await fixture([{ code: 1, stdout: "" }, one, one]);
		await (
			await privateMemory(f.base, f.dataDir, () => {}, undefined, { ...f.options, platform: "linux" })
		)?.stop();
		expect(f.kill).toHaveBeenCalledExactlyOnceWith(12345, "SIGTERM");
		expect(f.runListenerCommand.mock.calls[0]?.[0]).toBe("lsof");
	});

	it("asks lsof for no warnings, so a successful lookup is not read as failed", async () => {
		// lsof warns on stderr even when the lookup works (gvfs, Docker overlay mounts), and any
		// stderr is a failed lookup: `-w` keeps those warnings out, real failures keep their exit code.
		const f = await fixture([{ code: 1, stdout: "" }]);
		await privateMemory(f.base, f.dataDir, () => {}, undefined, { ...f.options, platform: "linux" });
		expect(f.runListenerCommand.mock.calls[0]?.[1]).toContain("-w");
	});

	it("does not terminate when health is unavailable or the stored instance id is empty", async () => {
		const f = await fixture([empty, one]);
		await (
			await privateMemory(f.base, f.dataDir, () => {}, undefined, {
				...f.options,
				health: async () => undefined,
			})
		)?.stop();
		expect(f.kill).not.toHaveBeenCalled();
		const other = await fixture([empty, one]);
		writeFileSync(join(other.dataDir, "home", ".engram", ".instance-id"), "\n");
		await (await privateMemory(other.base, other.dataDir, () => {}, undefined, other.options))?.stop();
		expect(other.kill).not.toHaveBeenCalled();
	});

	it.each(["0", "65536", "123;exit"])(
		"rejects invalid port %s before querying or terminating anything",
		async (port) => {
			const f = await fixture([]);
			await expect(
				privateMemory({ ...f.base, GENTLE_DOT_ENGRAM_PORT: port }, f.dataDir, () => {}, undefined, f.options),
			).rejects.toThrow("private memory");
			expect(f.runListenerCommand).not.toHaveBeenCalled();
			expect(f.kill).not.toHaveBeenCalled();
		},
	);
});