A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.
TypeScript
import { execFile } from "node:child_process";
import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { createRequire } from "node:module";
import { homedir } from "node:os";
import { delimiter, dirname, join } from "node:path";
import { bundledGentleShell } from "./config.ts";
import { directAccess, type EngineAccess } from "./engine-access.ts";
import { resolveEngramBin, runtimeDir } from "./runtime.ts";
/**
* The folder with the `pi` executable bundled with the daemon. The engine's
* first-run setup needs `pi` on PATH, and a clean machine has none. An installed
* app carries a relocatable `pi` in `<runtime>/bin`; pnpm's shim is not relocatable.
*/
interface IsolationOptions {
platform?: NodeJS.Platform;
/** Source shim directories, injectable for platform-independent tests. */
sourceBinDirs?: string[];
}
function bundledBinDir(base: NodeJS.ProcessEnv, options: IsolationOptions): string | undefined {
const runtime = runtimeDir(base);
if (runtime) return join(runtime, "bin");
const require = createRequire(import.meta.url);
const bins =
options.sourceBinDirs ??
(require.resolve.paths("@earendil-works/pi-coding-agent") ?? []).map((dir) => join(dir, ".bin"));
const names = (options.platform ?? process.platform) === "win32" ? ["pi", "pi.cmd", "pi.exe"] : ["pi"];
for (const bin of bins) {
if (names.some((name) => existsSync(join(bin, name)))) return bin;
}
return undefined;
}
/** Creates `path` with mode 0700, and tightens it to 0700 when it already exists. */
export function ensurePrivateDir(path: string): void {
mkdirSync(path, { recursive: true, mode: 0o700 });
chmodSync(path, 0o700);
}
/** The file gentle-shell writes into a home it created (gentle-pi `bin/gentle-shell.mjs`). */
export const ENGINE_HOME_MARKER = ".gentle-shell-home";
/** The bundled gentle-pi's version, which gentle-shell names in its marker; informational only. */
function engineVersion(): string | undefined {
try {
const manifest = join(dirname(bundledGentleShell()), "..", "package.json");
return (JSON.parse(readFileSync(manifest, "utf8")) as { version?: string }).version;
} catch {
return undefined;
}
}
/**
* Marks the assistant's own engine home as gentle-shell's (S35.3, #13). gentle-shell runs its
* first-run setup (the companion packages) only in a home it created: one that did not exist, or
* that holds its marker. The daemon writes `auth.json` and `mcp.json` there before the engine's
* first start, so without the marker the engine took the home for someone else's and never set
* it up. The marker has gentle-shell's own format (`{"createdBy":"gentle-shell","version":…}`; it
* checks only that the file exists). One already there is left as it is. Call it only for the
* default `<data>/agent`: a home the user chose may be theirs, and is never marked.
*/
export function claimEngineHome(
agentHome: string,
log: (line: string) => void = () => {},
access: EngineAccess = directAccess,
): void {
const content = `${JSON.stringify({ createdBy: "gentle-shell", version: engineVersion() })}\n`;
try {
access(() => {
ensurePrivateDir(agentHome);
writeFileSync(join(agentHome, ENGINE_HOME_MARKER), content, { flag: "wx", mode: 0o600 });
});
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "EEXIST")
log(`could not mark the engine's home as its own: ${(error as Error).message}`);
}
}
/** Variables that could point the engine back at the user's own setup. */
const INHERITED_HOMES = ["PI_CODING_AGENT_DIR", "GENTLE_PI_AGENT_HOME", "GENTLE_SHELL_CONFIG"];
/**
* What a subagent run sets for its child engines (gentle-pi `lib/agents-runner.ts`), and the command
* line those children would run instead of the engine. The assistant's engine is never a child, and
* its children run the same engine as it does.
*/
const SUBAGENT_VARIABLES = [
"GENTLE_PI_AGENTS_CHILD",
"GENTLE_PI_AGENTS_OWNED_IPC",
"GENTLE_PI_AGENTS_PARENT_PERMISSION_FD",
"GENTLE_PI_AGENTS_PI",
];
/** What only the daemon may hold: the server's connector secrets key (S25.8). */
const DAEMON_ONLY = ["GENTLE_DOT_SECRETS_KEY"];
/** Subagents are on unless `GENTLE_DOT_SUBAGENTS` is `off`, `0`, or `false`. */
export function subagentsEnabled(base: NodeJS.ProcessEnv): boolean {
const value = base.GENTLE_DOT_SUBAGENTS?.trim().toLowerCase();
return !(value === "off" || value === "0" || value === "false");
}
/** The memory project every memory the assistant saves or searches belongs to. */
export const MEMORY_PROJECT = "gentle-dot";
/** The memory server port of the private memory (`GENTLE_DOT_ENGRAM=private`). */
export const PRIVATE_ENGRAM_PORT = "7438";
/**
* Names the memory project of `workspace` through Engram's per-folder setting
* (`.engram/config.json`), which Engram reads before any other detection.
*/
export function ensureMemoryProject(workspace: string, access: EngineAccess = directAccess): void {
const file = join(workspace, ".engram", "config.json");
access(() => {
ensurePrivateDir(join(workspace, ".engram"));
// Written next to it and renamed over it: a link planted at its place is replaced, never followed.
const temp = `${file}.${process.pid}.tmp`;
writeFileSync(temp, `${JSON.stringify({ project_name: MEMORY_PROJECT })}\n`);
renameSync(temp, file);
});
}
/**
* The engine's environment: its own HOME (`<dataDir>/home`, mode 0700) with
* the XDG folders under it (on Windows `USERPROFILE`, `APPDATA` and `LOCALAPPDATA`), because
* parts of the engine write to fixed places under the home folder. PATH is kept (on Windows as one `PATH` key, whatever its spelling), with the bundled `pi` folder first, and so is the user's git identity,
* through `GIT_CONFIG_GLOBAL` pointing at their real `~/.gitconfig`.
*
* Memory is the user's global Engram: Engram ties a server to its data folder
* (by default under HOME), so `ENGRAM_DATA_DIR` points at the user's real one
* (`GENTLE_DOT_ENGRAM_DATA_DIR` overrides it) and the memory plugin accepts the
* user's server. The user's own `ENGRAM_PORT` and `ENGRAM_URL` are kept.
* `GENTLE_DOT_ENGRAM=private` instead runs a memory of its own under the
* engine's home, on port 7438 (`GENTLE_DOT_ENGRAM_PORT` overrides it).
* The server's connector secrets key (`GENTLE_DOT_SECRETS_KEY`, S25.8) is never passed on.
* Subagents are on (`GENTLE_PI_AGENTS=1`) unless `GENTLE_DOT_SUBAGENTS=off`: their child engines
* reach connectors only through the daemon's proxy, like the engine itself (S25.4).
*
* Without a `TMPDIR` (the installed app's launch on Linux), the engine gets a
* private one under its home: it caches compiled extensions in the temporary
* folder, and a shared `/tmp` would let another local user plant that cache.
*
* An installed app (`GENTLE_DOT_RUNTIME`) also names the Engram binary
* (`ENGRAM_BIN`, see `resolveEngramBin`), since its PATH has no user folders.
*/
export function isolatedAgentEnv(
base: NodeJS.ProcessEnv,
dataDir: string,
access: EngineAccess = directAccess,
options: IsolationOptions = {},
): NodeJS.ProcessEnv {
const platform = options.platform ?? process.platform;
const home = join(dataDir, "home");
access(() => ensurePrivateDir(home));
const realHome = base.HOME || (platform === "win32" && base.USERPROFILE) || homedir();
const env: NodeJS.ProcessEnv = {
...base,
HOME: home,
XDG_CONFIG_HOME: join(home, ".config"),
XDG_DATA_HOME: join(home, ".local", "share"),
XDG_CACHE_HOME: join(home, ".cache"),
XDG_STATE_HOME: join(home, ".local", "state"),
};
for (const key of [...INHERITED_HOMES, ...SUBAGENT_VARIABLES, ...DAEMON_ONLY]) delete env[key];
if (platform === "win32") {
const tmp = join(home, ".cache", "tmp");
env.USERPROFILE = home;
env.TEMP = env.TMP = env.TMPDIR = tmp;
// Windows' counterparts of the XDG folders, so the engine's tools keep no state in the user's.
env.APPDATA = join(home, "AppData", "Roaming");
env.LOCALAPPDATA = join(home, "AppData", "Local");
access(() => {
ensurePrivateDir(tmp);
ensurePrivateDir(env.APPDATA as string);
ensurePrivateDir(env.LOCALAPPDATA as string);
});
} else if (!base.TMPDIR) {
const tmp = join(home, ".cache", "tmp");
env.TMPDIR = tmp;
access(() => ensurePrivateDir(tmp));
}
// Windows spells the variable `Path`, and a copy of its environment keeps that key: reading
// `PATH` found nothing, and a second `PATH` key beside it won, leaving the engine only the bundled
// folder (found by Row0902). On Windows it is read whatever its spelling and kept as one `PATH`.
let path = base.PATH;
if (platform === "win32") {
const keys = Object.keys(env).filter((key) => key.toUpperCase() === "PATH");
path = keys.map((key) => env[key]).find((value) => value !== undefined);
for (const key of keys) delete env[key];
if (path !== undefined) env.PATH = path;
}
const bin = bundledBinDir(base, options);
if (bin) {
const windows = platform === "win32";
const separator = windows ? ";" : delimiter;
// Windows paths ignore case and a trailing separator, so the bundled folder is not kept twice.
const same = (part: string) =>
windows
? part.replace(/[\\/]+$/, "").toLowerCase() === bin.replace(/[\\/]+$/, "").toLowerCase()
: part === bin;
const rest = (path ?? "").split(separator).filter((part) => part && !same(part));
env.PATH = [bin, ...rest].join(separator);
}
// The user's own Gentle Shell setting is not the assistant's.
env.GENTLE_PI_AGENTS = subagentsEnabled(base) ? "1" : "0";
if (base.GENTLE_DOT_ENGRAM === "private") {
env.ENGRAM_PORT = base.GENTLE_DOT_ENGRAM_PORT || PRIVATE_ENGRAM_PORT;
delete env.ENGRAM_URL;
delete env.ENGRAM_DATA_DIR;
} else {
env.ENGRAM_DATA_DIR =
base.GENTLE_DOT_ENGRAM_DATA_DIR || base.ENGRAM_DATA_DIR || join(realHome, ".engram");
}
const runtime = runtimeDir(base);
if (runtime) env.ENGRAM_BIN = resolveEngramBin(base, runtime, { home: realHome, platform });
const gitConfig = join(realHome, ".gitconfig");
if (!base.GIT_CONFIG_GLOBAL && existsSync(gitConfig)) env.GIT_CONFIG_GLOBAL = gitConfig;
return env;
}
type Listener = { kind: "empty" | "failed" | "ambiguous" } | { kind: "one"; pid: number };
interface PrivateMemoryOptions {
platform?: NodeJS.Platform;
/** Bounded command execution seam; errors must not be reported as empty output. */
runListenerCommand?: (
command: string,
args: readonly string[],
) => Promise<{ code: number; stdout: string; stderr: string }>;
kill?: (pid: number, signal: "SIGTERM") => void;
health?: (port: string) => Promise<{ instance_id?: unknown } | undefined>;
}
/**
* Owns cleanup only after confirming an empty private port before startup.
* A failed or ambiguous lookup refuses ownership, not startup: the daemon starts,
* logs it, and leaves that memory server running when it closes. An invalid port
* is a configuration error and does stop startup. Before termination, both the
* private data identity and a repeated stable listener PID must match.
* PID reuse after the final check remains possible; nothing is killed by name.
*/
export async function privateMemory(
base: NodeJS.ProcessEnv,
dataDir: string,
log: (line: string) => void,
access: EngineAccess = directAccess,
options: PrivateMemoryOptions = {},
): Promise<{ stop(): Promise<void> } | undefined> {
if (base.GENTLE_DOT_ENGRAM !== "private") return undefined;
const port = base.GENTLE_DOT_ENGRAM_PORT || PRIVATE_ENGRAM_PORT;
if (
!/^\d+$/.test(port) ||
!Number.isSafeInteger(Number(port)) ||
Number(port) < 1 ||
Number(port) > 65535
) {
throw new Error("Cannot start private memory: port must be an integer from 1 to 65535");
}
const before = await listeningPid(port, options);
if (before.kind === "one") return undefined;
if (before.kind !== "empty") {
// Not knowing is no reason to keep the assistant from starting, nor to claim the server.
log(`cannot verify private memory listener on port ${port} (${before.kind} lookup); will not stop it`);
return undefined;
}
return {
async stop() {
const listener = await listeningPid(port, options);
if (listener.kind !== "one") {
if (listener.kind !== "empty")
log(`cannot verify private memory listener on port ${port}; left running`);
return;
}
let expected: string;
try {
const file = join(dataDir, "home", ".engram", ".instance-id");
expected = access(() => readFileSync(file, "utf8")).trim();
} catch {
return;
}
const health = await (options.health ?? memoryHealth)(port).catch(() => undefined);
if (!expected || health?.instance_id !== expected) {
log(`the memory server on port ${port} serves other data; left running`);
return;
}
const again = await listeningPid(port, options);
if (again.kind !== "one" || again.pid !== listener.pid) {
log(`the private memory listener changed on port ${port}; left running`);
return;
}
try {
(options.kill ?? process.kill)(listener.pid, "SIGTERM");
log(`stopped the private memory server (pid ${listener.pid})`);
} catch (error) {
log(`could not stop private memory server (pid ${listener.pid}): ${String(error)}`);
}
},
};
}
function memoryHealth(port: string): Promise<{ instance_id?: unknown } | undefined> {
return fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(2000) })
.then((response) => response.json() as Promise<{ instance_id?: unknown }>)
.catch(() => undefined);
}
/**
* How long the listener lookup may take. Windows starts PowerShell and queries CIM, which can take
* several seconds on a busy machine (startup, many processes); a lookup that runs out is a failed
* lookup, and private memory then refuses to start.
*/
export function listenerLookupTimeoutMs(platform: NodeJS.Platform): number {
return platform === "win32" ? 15_000 : 5000;
}
function runListenerCommand(
command: string,
args: readonly string[],
): Promise<{ code: number; stdout: string; stderr: string }> {
return new Promise((resolve) => {
execFile(
command,
[...args],
{
encoding: "utf8",
timeout: listenerLookupTimeoutMs(command === "powershell.exe" ? "win32" : process.platform),
windowsHide: true,
},
(error, stdout, stderr) => {
resolve({
code: error ? (typeof error.code === "number" ? error.code : -1) : 0,
stdout: String(stdout),
stderr: String(stderr),
});
},
);
});
}
/** Enumerate Windows listeners before filtering, so an unused port is not a query error. */
async function listeningPid(port: string, options: PrivateMemoryOptions): Promise<Listener> {
const windows = (options.platform ?? process.platform) === "win32";
const command = windows ? "powershell.exe" : "lsof";
const args = windows
? [
"-NoLogo",
"-NoProfile",
"-NonInteractive",
"-Command",
`$ErrorActionPreference='Stop'; $ProgressPreference='SilentlyContinue'; try { Get-NetTCPConnection -State Listen -ErrorAction Stop | Where-Object { $_.LocalPort -eq ${Number(port)} } | Select-Object -ExpandProperty OwningProcess } catch { [Console]::Error.WriteLine($_.Exception.Message); exit 1 }`,
]
: ["-w", "-t", "-n", "-P", `-iTCP:${port}`, "-sTCP:LISTEN"];
try {
const result = await (options.runListenerCommand ?? runListenerCommand)(command, args);
const text = result.stdout.trim();
// lsof exits 1 for no matches. Missing commands, diagnostics and timeouts are failures.
if (!windows && result.code === 1 && !text && !result.stderr.trim()) return { kind: "empty" };
if (result.code !== 0 || result.stderr.trim()) return { kind: "failed" };
if (!text) return { kind: "empty" };
const values = text.split(/\r?\n/).map((value) => value.trim());
if (values.some((value) => !/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))))
return { kind: "failed" };
const pids = [...new Set(values.map(Number))];
return pids.length === 1 ? { kind: "one", pid: pids[0] as number } : { kind: "ambiguous" };
} catch {
return { kind: "failed" };
}
}