directionallylocal 0.2.0 → 0.4.0

package/dist/local/check.js

@@ -0,0 +1,194 @@
+/**
+ * Whether this computer can run the agents: platform, Docker (whichever runtime the user
+ * has), a patched Node, git, and disk. Read-only: every probe goes through `System`.
+ */
+import { dirname, join } from "node:path";
+import { agentCapacity, parseDfFreeGb, parseInterfaceIp, parseOsRelease } from "../detect.js";
+import { nodeAdvisory } from "../node-advisory.js";
+import { LOCAL_CELL_MEMORY_MB, LOCAL_MIN_DISK_GB } from "./layout.js";
+const DOCKER_INFO = "{{.ServerVersion}}|{{.OperatingSystem}}|{{.MemTotal}}|{{.NCPU}}";
+export async function checkComputer(system, options) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const home = options.home;
+    const [osName, df, git] = await Promise.all([
+        describeOs(system, platform),
+        system.probe("df", ["-Pk", home]),
+        system.probe("git", ["--version"]),
+    ]);
+    const dockerCli = await findDockerCli(system, home);
+    const { docker, denied } = dockerCli ? await findDocker(system, dockerCli, home, platform, env) : { docker: undefined, denied: false };
+    const dockerApp = platform === "darwin" && !docker ? await installedDockerApp(system, home) : undefined;
+    const bridge = platform === "linux" ? await system.probe("ip", ["-4", "-o", "addr", "show", "docker0"]) : undefined;
+    const systemd = platform === "linux" ? await system.probe("systemctl", ["--user", "is-system-running"]) : undefined;
+    const execPath = options.execPath ?? process.execPath;
+    return {
+        platform,
+        osName,
+        arch: options.arch ?? process.arch,
+        node: { path: await stableNodePath(system, execPath), version: options.nodeVersion ?? process.versions.node },
+        git: git.code === 0 ? git.stdout.trim().replace(/^git version /, "") : undefined,
+        diskFreeGb: parseDfFreeGb(df.stdout),
+        dockerCli,
+        docker,
+        dockerApp,
+        bridgeIp: bridge ? parseInterfaceIp(bridge.stdout) : undefined,
+        // "degraded" (one failed unit somewhere) still runs ours fine.
+        systemdUser: systemd ? ["running", "degraded", "starting"].includes(systemd.stdout.trim()) : false,
+        dockerDenied: denied,
+    };
+}
+/** What stops setup before it changes anything, each with how to fix it. */
+export function computerProblems(facts) {
+    const problems = [];
+    if (facts.platform !== "darwin" && facts.platform !== "linux") {
+        return [`Running agents on this computer works on macOS and Linux, not ${facts.platform}. Set up a server instead: curl -fsSL https://directionallylocal.run | sh`];
+    }
+    if (facts.platform === "linux" && !facts.systemdUser) {
+        problems.push("A systemd user session is needed to keep the agents running (systemctl --user). Log in to a desktop session, or set up a server instead.");
+    }
+    const node = nodeAdvisory(facts.node.version);
+    if (!node.ok) {
+        problems.push(`${node.message} ${facts.platform === "darwin" ? "Update Node (brew upgrade node, or nodejs.org)" : "Update Node (nodejs.org or your package manager)"}, then run this again.`);
+    }
+    if (!facts.git) {
+        problems.push(facts.platform === "darwin" ? "git isn't installed. Install it with: xcode-select --install" : "git isn't installed. Install it with your package manager (e.g. sudo apt install git).");
+    }
+    if (!facts.docker)
+        problems.push(dockerFix(facts));
+    if (facts.diskFreeGb < LOCAL_MIN_DISK_GB) {
+        problems.push(`At least ${LOCAL_MIN_DISK_GB} GB of free disk is needed for the sandbox image and workspaces (found ${facts.diskFreeGb} GB).`);
+    }
+    return problems;
+}
+function dockerFix(facts) {
+    if (facts.platform === "linux") {
+        if (facts.dockerDenied)
+            return "Docker is installed but you can't use it. Add yourself to the docker group (sudo usermod -aG docker $USER), log out and back in, then run this again.";
+        if (facts.dockerCli)
+            return "Docker isn't running. Start it (sudo systemctl start docker, or open Docker Desktop), then run this again.";
+        return "Docker isn't installed. Install Docker Engine (https://docs.docker.com/engine/install/) or Docker Desktop, then run this again.";
+    }
+    if (facts.dockerApp)
+        return `${facts.dockerApp} is installed but didn't start. Open it, wait until it says it's running, then run this again.`;
+    if (facts.dockerCli)
+        return "Docker isn't running. Start Docker Desktop, OrbStack, or colima (colima start), then run this again.";
+    return "Docker isn't installed. Install Docker Desktop (https://www.docker.com/products/docker-desktop/), OrbStack (brew install orbstack), or colima (brew install colima docker && colima start), then run this again.";
+}
+/** How many agents fit at once, by what Docker has (the VM on macOS). */
+export function localCapacity(docker) {
+    return agentCapacity({ memoryMb: docker.memoryMb, cpus: docker.cpus }, LOCAL_CELL_MEMORY_MB);
+}
+export function supportedPlatform(platform) {
+    return platform === "darwin" || platform === "linux" ? platform : undefined;
+}
+async function describeOs(system, platform) {
+    if (platform === "darwin") {
+        const version = (await system.probe("sw_vers", ["-productVersion"])).stdout.trim();
+        return version ? `macOS ${version}` : "macOS";
+    }
+    if (platform === "linux")
+        return parseOsRelease(await system.readFile("/etc/os-release") ?? "").prettyName || "Linux";
+    return platform;
+}
+async function findDockerCli(system, home) {
+    const onPath = (await system.probe("sh", ["-c", "command -v docker"])).stdout.trim();
+    if (onPath)
+        return onPath;
+    // Launched from a GUI or a fresh shell, the runtimes' own bin dirs may not be on PATH.
+    for (const candidate of [
+        "/usr/local/bin/docker",
+        "/opt/homebrew/bin/docker",
+        "/Applications/Docker.app/Contents/Resources/bin/docker",
+        join(home, ".orbstack", "bin", "docker"),
+        "/usr/bin/docker",
+    ]) {
+        if (await system.exists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * The Docker endpoint to use. Hotcell talks to Docker through DOCKER_HOST (not the CLI's
+ * context), and a LaunchAgent has none of the shell's environment, so this resolves the
+ * endpoint once and the services get it explicitly. A DOCKER_HOST the user set wins.
+ */
+async function findDocker(system, cli, home, platform, env) {
+    const candidates = [];
+    if (env.DOCKER_HOST?.trim()) {
+        candidates.push(env.DOCKER_HOST.trim());
+    }
+    else {
+        const context = (await system.probe(cli, ["context", "inspect", "--format", "{{.Endpoints.docker.Host}}"])).stdout.trim();
+        if (context)
+            candidates.push(context);
+        const sockets = platform === "darwin"
+            ? [join(home, ".docker", "run", "docker.sock"), join(home, ".orbstack", "run", "docker.sock"), join(home, ".colima", "default", "docker.sock"), join(home, ".colima", "docker.sock"), "/var/run/docker.sock"]
+            : ["/var/run/docker.sock", ...(env.XDG_RUNTIME_DIR ? [join(env.XDG_RUNTIME_DIR, "docker.sock")] : [])];
+        for (const socket of sockets)
+            if (await system.exists(socket))
+                candidates.push(`unix://${socket}`);
+    }
+    let denied = false;
+    for (const host of [...new Set(candidates)]) {
+        const info = await system.probe(cli, ["info", "--format", DOCKER_INFO], { env: { DOCKER_HOST: host } });
+        if (/permission denied/i.test(info.stderr))
+            denied = true;
+        const [version, os, memTotal, ncpu] = info.stdout.trim().split("|");
+        if (info.code !== 0 || !version)
+            continue;
+        return {
+            docker: {
+                host,
+                runtime: runtimeName(host, os ?? ""),
+                version,
+                memoryMb: Math.round(Number(memTotal) / 1024 / 1024) || 0,
+                cpus: Number(ncpu) || 0,
+            },
+            denied: false,
+        };
+    }
+    return { docker: undefined, denied };
+}
+function runtimeName(host, os) {
+    if (host.includes("/.orbstack/") || /orbstack/i.test(os))
+        return "OrbStack";
+    if (host.includes("/.colima/"))
+        return "colima";
+    if (/docker desktop/i.test(os) || host.includes("/.docker/run/"))
+        return "Docker Desktop";
+    if (host.includes("/run/user/"))
+        return "Docker (rootless)";
+    return "Docker";
+}
+/** Docker Desktop or OrbStack, installed as an app; undefined when neither is. */
+export async function installedDockerApp(system, home) {
+    for (const [name, path] of [
+        ["Docker Desktop", "/Applications/Docker.app"],
+        ["OrbStack", "/Applications/OrbStack.app"],
+        ["Docker Desktop", join(home, "Applications", "Docker.app")],
+        ["OrbStack", join(home, "Applications", "OrbStack.app")],
+    ]) {
+        if (await system.exists(path))
+            return name;
+    }
+    return undefined;
+}
+/**
+ * A Node path that survives upgrades: Homebrew's versioned Cellar path disappears on the
+ * next `brew upgrade`, but its opt/ link follows the formula, security fixes included.
+ */
+export async function stableNodePath(system, execPath) {
+    const match = execPath.match(/^(.*)\/Cellar\/(node(?:@\d+)?)\/[^/]+\/bin\/node$/);
+    if (match) {
+        const opt = `${match[1]}/opt/${match[2]}/bin/node`;
+        if (await system.exists(opt))
+            return opt;
+    }
+    return execPath;
+}
+/** PATH for the services: Node, the docker CLI, git, and the system's basics. */
+export function servicePath(facts) {
+    const dirs = [dirname(facts.node.path), ...(facts.dockerCli ? [dirname(facts.dockerCli)] : []), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+    return [...new Set(dirs)].join(":");
+}

package/dist/local/cli.js

@@ -0,0 +1,43 @@
+/** `dl local status` and `dl local uninstall [--purge]`: agents running on this computer. */
+import { homedir } from "node:os";
+import { localStatus, uninstallFromThisComputer } from "./setup.js";
+export const LOCAL_HELP = `  dl local status         agents on this computer: running?, where, how many fit
+  dl local uninstall [--purge]   stop and remove them (--purge also deletes keys and data)
+`;
+export async function localCommand(args, flags, io, colors, ui, options = {}) {
+    const [sub = "status"] = args;
+    if (sub === "status") {
+        io.out(formatLocalStatus(await localStatus(options), colors, options.home ?? homedir()));
+        return 0;
+    }
+    if (sub === "uninstall") {
+        await uninstallFromThisComputer({ ui, purge: Boolean(flags.purge), ...options });
+        ui.finish();
+        return 0;
+    }
+    io.err(`  Unknown: dl local ${sub}\n\n${LOCAL_HELP}`);
+    return 2;
+}
+export function formatLocalStatus(status, c, home) {
+    const short = (path) => (path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path);
+    if (!status.installed || !status.state) {
+        const leftovers = status.services.hotcell.installed || status.services.autopilot.installed;
+        return `\n  ${c.bold("Directionally Local")}  ${c.dim("isn't set up on this computer.")}\n${leftovers ? `\n  ${c.yellow("!")} Its services are still registered; remove them with: dl local uninstall\n` : ""}\n`;
+    }
+    const { state, services } = status;
+    const mark = (ok) => (ok ? c.green("✓") : c.red("✗"));
+    const line = (ok, label, detail) => `  ${mark(ok)} ${label.padEnd(12)}${c.dim(detail)}\n`;
+    const describe = (entry) => entry.running ? `running${entry.pid ? ` (pid ${entry.pid})` : ""}` : entry.installed ? "stopped" : "not installed";
+    const healthy = services.hotcell.running && services.autopilot.running && status.answering && status.dockerRunning;
+    return [
+        `\n  ${c.bold("Directionally Local")}  ${c.dim("on this computer")}  ${healthy ? c.green("running") : c.red("needs attention")}\n\n`,
+        line(status.dockerRunning, "Docker", status.dockerRunning ? state.dockerRuntime : `${state.dockerRuntime} isn't running; start it`),
+        line(services.hotcell.running, "Hotcell", `${describe(services.hotcell)} · 127.0.0.1:${state.ports.hotcell} · ${state.hotcellVersion}`),
+        line(services.autopilot.running && status.answering, "Autopilot", `${describe(services.autopilot)}${status.answering ? "" : ", not answering"} · ${state.url} · ${state.autopilotVersion}`),
+        `\n  ${c.dim("Fits")}        ${status.capacity !== undefined ? `~${status.capacity} agents at once (estimate, from Docker's memory)` : "unknown while Docker is stopped"}\n`,
+        `  ${c.dim("Installed")}   ${short(status.paths.current)}\n`,
+        `  ${c.dim("Logs")}        ${short(status.paths.logs)}\n`,
+        `  ${c.dim("Starts")}      at login (${status.platform === "darwin" ? "LaunchAgents" : "systemd --user"}); tasks pause while this computer sleeps\n`,
+        healthy ? "\n" : `\n  ${c.dim("Fix it by running setup again; it repairs and keeps your keys.")}\n\n`,
+    ].join("");
+}

package/dist/local/keys.js

@@ -0,0 +1,100 @@
+/**
+ * `dl keys` for "on this computer": the same as on a server, in the user's home. The
+ * OpenRouter key goes to Hotcell's 0600 file keystore over stdin (HOTCELL_KEYSTORE=file,
+ * see setup.ts for why not the Keychain), the GitHub token to the 0600 github.env, and
+ * the service that reads it (a LaunchAgent or a systemd user unit) restarts.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { checkKey, githubListing, hotcellKeyListed, KeyRejectedError } from "../keys.js";
+import { RealSystem } from "../system.js";
+import { supportedPlatform } from "./check.js";
+import { LOCAL_SERVICES, localGithubEnv, localHotcellBin, localPaths, parseLocalEnvFile, serviceFile } from "./layout.js";
+import { httpStatus } from "./probes.js";
+import { userId } from "./services.js";
+import { hotcellCliEnv } from "./setup.js";
+import { readLocalState } from "./state.js";
+async function installed(options) {
+    const home = options.home ?? homedir();
+    const platform = supportedPlatform(options.platform ?? process.platform);
+    if (!platform)
+        throw new Error("Agents run on this computer only on macOS and Linux.");
+    const system = options.system ?? new RealSystem(() => { });
+    const paths = localPaths(home, platform);
+    const state = await readLocalState(system, paths);
+    if (!state)
+        throw new Error("Directionally Local isn't set up on this computer; run dl setup.");
+    return {
+        system,
+        home,
+        platform,
+        paths,
+        state,
+        node: options.execPath ?? process.execPath,
+        sleep: options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+}
+/** Stores the key where setup does, restarts the service that reads it, and waits for it to answer. */
+export async function setLocalKey(which, value, options = {}) {
+    const key = value.trim();
+    const checked = await checkKey(which, key, options.fetchImpl);
+    if (checked.problem)
+        throw new KeyRejectedError(checked.problem);
+    const ctx = await installed(options);
+    const { system, paths, state, node } = ctx;
+    const uid = await userId(system);
+    if (which === "openrouter") {
+        await system.run(node, [localHotcellBin(paths), "keys", "add", "openrouter", "--stdin"], {
+            input: key,
+            env: hotcellCliEnv(paths),
+            describe: "hotcell keys add openrouter --stdin",
+        });
+        await restartService(ctx, uid, "hotcell");
+        await waitUntil(ctx, "Hotcell", async () => await httpStatus(system, node, `http://127.0.0.1:${state.ports.hotcell}/`) > 0);
+        return { ok: true, key: which, detail: "replaced in Hotcell; Hotcell restarted" };
+    }
+    await system.writeFile(paths.githubEnv, localGithubEnv(key), { mode: 0o600, secret: true });
+    await restartService(ctx, uid, "autopilot");
+    // Without a token the Aster API answers 401: up, and refusing strangers.
+    await waitUntil(ctx, "Autopilot", async () => await httpStatus(system, node, `${state.url}/api/v1/health`) === 401);
+    return { ok: true, key: which, detail: `${checked.detail ? `${checked.detail}; ` : ""}Autopilot restarted` };
+}
+/** Which keys this computer's install has; never their values. */
+export async function listLocalKeys(options = {}) {
+    const { system, paths, node } = await installed(options);
+    let openrouter = { key: "openrouter", set: false };
+    if (await system.exists(localHotcellBin(paths))) {
+        const listed = await system.probe(node, [localHotcellBin(paths), "keys", "ls"], { env: { ...hotcellCliEnv(paths), NO_COLOR: "1" } });
+        if (listed.code === 0)
+            openrouter = { key: "openrouter", ...hotcellKeyListed(listed.stdout, "openrouter") };
+    }
+    const token = parseLocalEnvFile(await system.readFile(paths.githubEnv)).GITHUB_TOKEN;
+    return [openrouter, await githubListing(token, options.fetchImpl)];
+}
+/**
+ * Restarts one service so it reads its keys again: `launchctl kickstart -k` on macOS (or
+ * bootstrap, when it isn't loaded), `systemctl --user restart` on Linux.
+ */
+async function restartService(ctx, uid, service) {
+    const { system, platform, paths } = ctx;
+    if (platform === "darwin") {
+        const restarted = await system.run("launchctl", ["kickstart", "-k", `gui/${uid}/${LOCAL_SERVICES[service].label}`], { allowFailure: true });
+        if (restarted.code === 0)
+            return;
+        const file = serviceFile(paths, platform, service);
+        if (!(await system.exists(file)))
+            throw new Error(`The ${service} service isn't installed on this computer; run dl setup to repair it.`);
+        await system.run("launchctl", ["bootstrap", `gui/${uid}`, file]);
+        return;
+    }
+    await system.run("systemctl", ["--user", "restart", LOCAL_SERVICES[service].unit]);
+}
+async function waitUntil(ctx, what, ready) {
+    for (let attempt = 0; attempt < 60; attempt++) {
+        if (await ready())
+            return;
+        await ctx.sleep(1_000);
+    }
+    const log = join(ctx.paths.logs, LOCAL_SERVICES[what === "Hotcell" ? "hotcell" : "autopilot"].log);
+    throw new Error(`${what} didn't come back up; see ${log.startsWith(`${ctx.home}/`) ? `~${log.slice(ctx.home.length)}` : log}`);
+}

package/dist/local/layout.js

@@ -0,0 +1,227 @@
+/**
+ * "On this computer": where everything lives in the user's home, and the files written
+ * there. Nothing here needs root. Secrets sit in 0600 env files that `node --env-file`
+ * reads, so they never appear in a launchd plist, a systemd unit, or any command line.
+ */
+import { join } from "node:path";
+export function localPaths(home, platform) {
+    const root = join(home, ".directionallylocal");
+    const config = join(root, "config");
+    const autopilotHome = join(root, "autopilot");
+    return {
+        home,
+        root,
+        releases: join(root, "releases"),
+        current: join(root, "current"),
+        logs: join(root, "logs"),
+        state: join(root, "state.json"),
+        config,
+        hotcellEnv: join(config, "hotcell.env"),
+        autopilotEnv: join(config, "autopilot.env"),
+        githubEnv: join(config, "github.env"),
+        asterConfig: join(config, "aster.json"),
+        hotcellHome: join(root, "hotcell"),
+        autopilotHome,
+        workspace: join(autopilotHome, "workspaces", "default"),
+        services: platform === "darwin" ? join(home, "Library", "LaunchAgents") : join(home, ".config", "systemd", "user"),
+    };
+}
+/** launchd labels and systemd user units, prefixed so they never clash with a user's own Hotcell. */
+export const LOCAL_SERVICES = {
+    hotcell: { label: "com.directionallylocal.hotcell", unit: "directionallylocal-hotcell.service", log: "hotcell.log" },
+    autopilot: { label: "com.directionallylocal.autopilot", unit: "directionallylocal-autopilot.service", log: "autopilot.log" },
+};
+export function serviceFile(paths, platform, service) {
+    const entry = LOCAL_SERVICES[service];
+    return join(paths.services, platform === "darwin" ? `${entry.label}.plist` : entry.unit);
+}
+/** Preferred ports; each moves up to the next free one when something else has it. */
+export const PREFERRED_PORTS = {
+    autopilot: 4096,
+    hotcell: 4750,
+    hotcellProxy: 4751,
+    hotcellEgress: 4752,
+    githubProxy: 4760,
+};
+export const LOCAL_CELL_MEMORY_MB = 1024;
+export const LOCAL_MIN_DISK_GB = 10;
+export const PAIRED_NAME = "this-computer";
+export function localHotcellBin(paths) {
+    return join(paths.current, "node_modules", "hotcell", "dist", "index.js");
+}
+export function localAutopilotBin(paths) {
+    return join(paths.current, "node_modules", "autopilot-ai", "bin", "autopilot.mjs");
+}
+/**
+ * KEY=value lines for `node --env-file`. Values with spaces or `#` (a home like
+ * "/Users/Jane Doe") are double-quoted, which Node's parser understands.
+ */
+export function localEnvFile(header, values) {
+    const lines = Object.entries(values).map(([key, value]) => {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(key) || /[\n\r"]/.test(value))
+            throw new Error(`invalid env entry ${key}`);
+        return `${key}=${/[\s#'`$\\]/.test(value) ? `"${value}"` : value}`;
+    });
+    return `# ${header}\n# Written by directionallylocal; re-running setup keeps your values.\n${lines.join("\n")}\n`;
+}
+export function parseLocalEnvFile(text) {
+    const values = {};
+    for (const line of (text ?? "").split("\n")) {
+        const match = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/);
+        if (match)
+            values[match[1]] = match[2].replace(/^"(.*)"$/, "$1");
+    }
+    return values;
+}
+export function localHotcellEnv(input) {
+    const { paths, ports } = input;
+    return localEnvFile("Hotcell daemon (sandboxes + credential gateway), on this computer", {
+        HOTCELL_HOME: paths.hotcellHome,
+        // A 0600 file, not the login keychain: see setup.ts for why.
+        HOTCELL_KEYSTORE: "file",
+        HOTCELL_DB: join(paths.hotcellHome, "state.db"),
+        HOTCELL_BACKUP_DIR: join(paths.hotcellHome, "backups"),
+        HOTCELL_HOST: "127.0.0.1",
+        HOTCELL_PORT: String(ports.hotcell),
+        HOTCELL_PROXY_PORT: String(ports.hotcellProxy),
+        HOTCELL_API_KEY: input.apiKey,
+        HOTCELL_DRIVER: "container",
+        HOTCELL_EGRESS_HOST: input.net.listenHost,
+        HOTCELL_EGRESS_PORT: String(ports.hotcellEgress),
+        HOTCELL_EGRESS_ADVERTISE_HOST: "host.docker.internal",
+    });
+}
+export function localAutopilotEnv(input) {
+    const { paths, ports } = input;
+    return localEnvFile("Autopilot server (Aster API), on this computer", {
+        AUTOPILOT_ASTER_CONFIG: paths.asterConfig,
+        AUTOPILOT_ASTER_DB: join(paths.autopilotHome, "aster.db"),
+        AUTOPILOT_RUNS_DB: join(paths.autopilotHome, "runs.db"),
+        AUTOPILOT_PUBLIC_URL: `http://127.0.0.1:${ports.autopilot}`,
+        // The model key lives only in Hotcell; no model calls from this computer itself.
+        AUTOPILOT_ASTER_MEMORY: "off",
+        AUTOPILOT_HOTCELL_ENDPOINT: `http://127.0.0.1:${ports.hotcell}`,
+        AUTOPILOT_HOTCELL_API_KEY: input.hotcellApiKey,
+        AUTOPILOT_HOTCELL_DRIVER: "container",
+        AUTOPILOT_HOTCELL_IMAGE: input.image,
+        AUTOPILOT_HOTCELL_NETWORKED: "true",
+        AUTOPILOT_HOTCELL_ANY_MODEL: "true",
+        AUTOPILOT_HOTCELL_SLEEP_AFTER_MS: "900000",
+        AUTOPILOT_HOTCELL_MEMORY_MB: String(LOCAL_CELL_MEMORY_MB),
+        AUTOPILOT_HOTCELL_CPUS: "1",
+        AUTOPILOT_HOTCELL_PIDS: "512",
+        AUTOPILOT_HOTCELL_SPEND_CAP_USD: "10",
+        AUTOPILOT_HOTCELL_TOKEN_TTL_MS: String(30 * 24 * 60 * 60 * 1000),
+        // Cells clone and push through Autopilot's repository-scoped proxy; the token stays here.
+        AUTOPILOT_ASTER_GITHUB_PROXY_LISTEN: `${input.net.listenHost}:${ports.githubProxy}`,
+        AUTOPILOT_ASTER_GITHUB_PROXY_URL: `http://host.docker.internal:${ports.githubProxy}`,
+    });
+}
+export function localGithubEnv(token) {
+    return localEnvFile("GitHub credential for cloning, pushing, and opening PRs (never sent to sandboxes)", { GITHUB_TOKEN: token });
+}
+export function localAsterConfig(paths) {
+    return `${JSON.stringify({
+        models: "openrouter",
+        workspaces: [{ id: "default", displayName: "Default workspace", rootPath: paths.workspace }],
+    }, null, 2)}\n`;
+}
+export function serviceSpecs(input) {
+    const { paths } = input;
+    const docker = input.dockerHost ? { DOCKER_HOST: input.dockerHost } : {};
+    return {
+        hotcell: {
+            service: "hotcell",
+            description: "Hotcell sandbox daemon (Directionally Local)",
+            node: input.node,
+            envFiles: [paths.hotcellEnv],
+            args: [localHotcellBin(paths), "start", "--foreground", "--defaults"],
+            // Its own HOME, so nothing falls back to a user's own ~/.hotcell.
+            env: { HOME: paths.hotcellHome, PATH: input.path, ...docker },
+            workingDirectory: paths.hotcellHome,
+            log: join(paths.logs, LOCAL_SERVICES.hotcell.log),
+        },
+        autopilot: {
+            service: "autopilot",
+            description: "Autopilot server (Directionally Local)",
+            node: input.node,
+            envFiles: [paths.autopilotEnv, paths.githubEnv],
+            args: [localAutopilotBin(paths), "serve", "--hostname", "127.0.0.1", "--port", String(input.ports.autopilot)],
+            // Its own HOME and XDG dirs: a user's own Autopilot config and keys are never picked up.
+            env: { HOME: paths.autopilotHome, PATH: input.path, ...autopilotXdg(paths), ...docker },
+            workingDirectory: paths.autopilotHome,
+            log: join(paths.logs, LOCAL_SERVICES.autopilot.log),
+        },
+    };
+}
+export function autopilotXdg(paths) {
+    return {
+        XDG_CONFIG_HOME: join(paths.autopilotHome, ".config"),
+        XDG_STATE_HOME: join(paths.autopilotHome, ".local", "state"),
+        XDG_DATA_HOME: join(paths.autopilotHome, ".local", "share"),
+        XDG_CACHE_HOME: join(paths.autopilotHome, ".cache"),
+    };
+}
+function xml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** A LaunchAgent: starts at login, restarted if it exits, logs under ~/.directionallylocal/logs. */
+export function launchAgentPlist(spec) {
+    const program = [spec.node, ...spec.envFiles.map((file) => `--env-file=${file}`), ...spec.args];
+    const env = Object.entries(spec.env).map(([key, value]) => `    <key>${xml(key)}</key>\n    <string>${xml(value)}</string>`).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- ${xml(spec.description)}. Written by directionallylocal; remove with: dl local uninstall -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LOCAL_SERVICES[spec.service].label}</string>
+  <key>ProgramArguments</key>
+  <array>
+${program.map((arg) => `    <string>${xml(arg)}</string>`).join("\n")}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>${xml(spec.workingDirectory)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProcessType</key>
+  <string>Standard</string>
+  <key>StandardOutPath</key>
+  <string>${xml(spec.log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(spec.log)}</string>
+</dict>
+</plist>
+`;
+}
+function systemdQuote(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
+}
+/** A systemd user unit: starts with the user's session (default.target), restarted on exit. */
+export function systemdUserUnit(spec, after) {
+    const program = [spec.node, ...spec.envFiles.map((file) => `--env-file=${file}`), ...spec.args];
+    return `[Unit]
+Description=${spec.description}
+${after ? `After=${after}\nWants=${after}\n` : ""}
+[Service]
+Type=simple
+${Object.entries(spec.env).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`).join("\n")}
+WorkingDirectory=${spec.workingDirectory}
+ExecStart=${program.map(systemdQuote).join(" ")}
+Restart=always
+RestartSec=5
+StandardOutput=append:${spec.log}
+StandardError=append:${spec.log}
+
+[Install]
+WantedBy=default.target
+`;
+}

package/dist/local/probes.js

@@ -0,0 +1,22 @@
+/**
+ * Exit 0 when HOST:PORT is free. Connecting first catches a listener on 0.0.0.0, which
+ * macOS would still let us bind 127.0.0.1 next to.
+ */
+export const PORT_FREE_SCRIPT = [
+    "const net=require('net');const [h,p]=[process.argv[1],Number(process.argv[2])];",
+    "const c=net.connect(p,h);c.once('connect',()=>{c.destroy();process.exit(1)});",
+    "c.once('error',()=>{const s=net.createServer();s.once('error',()=>process.exit(1));s.listen(p,h,()=>s.close(()=>process.exit(0)))});",
+].join("");
+/** Prints the HTTP status of GET URL (0 if nothing answers); a bearer token, if any, comes on stdin. */
+export const HTTP_STATUS_SCRIPT = [
+    "let t='';process.stdin.on('data',d=>t+=d).on('end',async()=>{",
+    "try{const r=await fetch(process.argv[1],{headers:t.trim()?{authorization:'Bearer '+t.trim()}:{},signal:AbortSignal.timeout(5000)});",
+    "console.log(r.status)}catch{console.log(0)}});",
+].join("");
+export async function portFree(system, node, host, port) {
+    return (await system.probe(node, ["-e", PORT_FREE_SCRIPT, host, String(port)])).code === 0;
+}
+export async function httpStatus(system, node, url, token = "") {
+    const result = await system.probe(node, ["-e", HTTP_STATUS_SCRIPT, url], { input: token });
+    return Number(result.stdout.trim()) || 0;
+}

package/dist/local/services.js

@@ -0,0 +1,68 @@
+import { LOCAL_SERVICES, launchAgentPlist, serviceFile, systemdUserUnit, } from "./layout.js";
+const ORDER = ["hotcell", "autopilot"];
+export async function userId(system) {
+    const uid = (await system.probe("id", ["-u"])).stdout.trim();
+    if (!/^\d+$/.test(uid))
+        throw new Error("Couldn't tell which user this is (id -u).");
+    if (uid === "0")
+        throw new Error("Run this as yourself, not as root or with sudo: the agents run as your user.");
+    return uid;
+}
+/** Writes the service definition, then starts (or restarts) it. */
+export async function installService(system, manager, spec) {
+    const { platform, paths } = manager;
+    const file = serviceFile(paths, platform, spec.service);
+    await system.mkdir(paths.services, { mode: platform === "darwin" ? 0o755 : 0o700 });
+    if (platform === "darwin") {
+        await system.writeFile(file, launchAgentPlist(spec), { mode: 0o644 });
+        await stopService(system, manager, spec.service);
+        const target = `gui/${manager.uid}/${LOCAL_SERVICES[spec.service].label}`;
+        // A service the user disabled stays disabled across bootstrap; setup means "on".
+        await system.run("launchctl", ["enable", target], { allowFailure: true });
+        // bootout returns before launchd has let go of the label; bootstrap can briefly fail with EIO.
+        for (let attempt = 1;; attempt++) {
+            const result = await system.run("launchctl", ["bootstrap", `gui/${manager.uid}`, file], { allowFailure: true });
+            if (result.code === 0)
+                break;
+            if (attempt >= 5)
+                throw new Error(`launchd wouldn't start ${spec.service}: ${(result.stderr || result.stdout).trim()}`);
+            await manager.sleep(1_000);
+        }
+        return;
+    }
+    const unit = LOCAL_SERVICES[spec.service].unit;
+    await system.writeFile(file, systemdUserUnit(spec, spec.service === "autopilot" ? LOCAL_SERVICES.hotcell.unit : undefined), { mode: 0o644 });
+    await system.run("systemctl", ["--user", "daemon-reload"]);
+    await system.run("systemctl", ["--user", "enable", unit]);
+    await system.run("systemctl", ["--user", "restart", unit]);
+}
+export async function stopService(system, manager, service) {
+    if (manager.platform === "darwin") {
+        await system.run("launchctl", ["bootout", `gui/${manager.uid}/${LOCAL_SERVICES[service].label}`], { allowFailure: true });
+    }
+    else {
+        await system.run("systemctl", ["--user", "disable", "--now", LOCAL_SERVICES[service].unit], { allowFailure: true });
+    }
+}
+/** Stops and deletes both service definitions. */
+export async function removeServices(system, manager) {
+    for (const service of [...ORDER].reverse()) {
+        await stopService(system, manager, service);
+        await system.remove(serviceFile(manager.paths, manager.platform, service));
+    }
+    if (manager.platform === "linux") {
+        await system.run("systemctl", ["--user", "daemon-reload"], { allowFailure: true });
+        await system.run("systemctl", ["--user", "reset-failed"], { allowFailure: true });
+    }
+}
+export async function serviceState(system, manager, service) {
+    const installed = await system.exists(serviceFile(manager.paths, manager.platform, service));
+    if (manager.platform === "darwin") {
+        const printed = await system.probe("launchctl", ["print", `gui/${manager.uid}/${LOCAL_SERVICES[service].label}`]);
+        const running = printed.code === 0 && /^\s*state = running\s*$/m.test(printed.stdout);
+        const pid = Number(printed.stdout.match(/^\s*pid = (\d+)\s*$/m)?.[1]);
+        return { installed, running, ...(pid ? { pid } : {}) };
+    }
+    const active = await system.probe("systemctl", ["--user", "is-active", LOCAL_SERVICES[service].unit]);
+    return { installed, running: active.stdout.trim() === "active" };
+}