@alphacoder-v0/pi-loops 0.17.3

package/src/host-control.ts

@@ -0,0 +1,203 @@
+/**
+ * The headless host: a `node` process running `src/host.ts` that keeps the clock (loops,
+ * trigger checks, MCP pushes) while no interactive pi is open on this machine. The last
+ * interactive pi to quit starts it; the first to open takes the clock back and the host exits.
+ * `host.json` under the loops dir names the running host; `host.log` is its output.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { pidAlive, writeFileAtomic } from "./lock.ts";
+import type { PresenceEntry } from "./presence.ts";
+import { stamp } from "./schedule.ts";
+
+export interface HostRecord {
+	pid: number;
+	host: string;
+	startedAt: string;
+	node: string;
+	/** The host entry as it appears in the process's argv, for an exact command-line match. */
+	entry?: string;
+}
+
+export const HOST_FILE = "host.json";
+export const HOST_LOG = "host.log";
+
+export function readHost(dir: string): HostRecord | undefined {
+	try {
+		const rec = JSON.parse(fs.readFileSync(path.join(dir, HOST_FILE), "utf8")) as HostRecord;
+		return rec && typeof rec.pid === "number" ? rec : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Is `pid` really our host? A record can outlive its process (SIGKILL, power loss) and the pid
+ * be recycled, so besides liveness we require the record to postdate the last boot and, where
+ * /proc exists, the command line to be the host entry.
+ */
+export function hostProcessMatches(rec: HostRecord): boolean {
+	if (!pidAlive(rec.pid)) return false;
+	const booted = Date.now() - os.uptime() * 1000;
+	if (Number.isFinite(booted) && Date.parse(rec.startedAt) < booted - 60_000) return false;
+	const isOurs = (argv: string[]) => (rec.entry ? argv.includes(rec.entry) : argv.some((a) => a.endsWith("host.ts")));
+	try {
+		return isOurs(fs.readFileSync(`/proc/${rec.pid}/cmdline`, "utf8").split("\0"));
+	} catch {
+		/* no /proc (macOS): ask ps */
+	}
+	try {
+		const command = execFileSync("ps", ["-o", "command=", "-p", String(rec.pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+		return isOurs(command.trim().split(/\s+/));
+	} catch {
+		return true; // liveness + boot time is all we can check
+	}
+}
+
+/** The host process on this machine, if it is alive. A stale record is removed. */
+export function liveHost(dir: string): HostRecord | undefined {
+	const rec = readHost(dir);
+	if (!rec) return undefined;
+	if (rec.host !== os.hostname()) return undefined;
+	if (hostProcessMatches(rec)) return rec;
+	fs.rmSync(path.join(dir, HOST_FILE), { force: true });
+	return undefined;
+}
+
+/** A record whose process is gone means the host crashed (it removes the record on a clean exit). */
+export function crashedHost(dir: string): HostRecord | undefined {
+	const rec = readHost(dir);
+	if (!rec || rec.host !== os.hostname()) return undefined;
+	if (hostProcessMatches(rec)) return undefined;
+	fs.rmSync(path.join(dir, HOST_FILE), { force: true });
+	return rec;
+}
+
+export function writeHostRecord(dir: string, rec: HostRecord): void {
+	writeFileAtomic(path.join(dir, HOST_FILE), `${JSON.stringify(rec, null, 2)}\n`);
+}
+
+export function clearHostRecord(dir: string, pid?: number): void {
+	const rec = readHost(dir);
+	if (pid !== undefined && rec && rec.pid !== pid) return;
+	fs.rmSync(path.join(dir, HOST_FILE), { force: true });
+}
+
+/** SIGTERM the host (it stops its scheduler and exits); returns the pid or undefined when none ran. */
+export function stopHost(dir: string): number | undefined {
+	const rec = liveHost(dir);
+	if (!rec) return undefined;
+	try {
+		process.kill(rec.pid, "SIGTERM");
+	} catch {
+		/* already gone */
+	}
+	fs.rmSync(path.join(dir, HOST_FILE), { force: true });
+	return rec.pid;
+}
+
+/**
+ * Hand the clock to a headless host when the last interactive pi on this machine quits and
+ * there is something for it to keep running. Pure, so the decision is testable.
+ */
+export function shouldHandOff(input: { auto: boolean; presence: PresenceEntry[]; selfPid: number; selfInstance?: string; hostName: string; enabledLoops: number; enabledRules: number; pushServers: number; hostAlive: boolean }): { handOff: boolean; reason: string } {
+	if (!input.auto) return { handOff: false, reason: "[host] auto = false" };
+	if (input.hostAlive) return { handOff: false, reason: "a host is already running" };
+	const others = input.presence.filter((e) => e.host === input.hostName && e.kind !== "host" && !(e.pid === input.selfPid && (!input.selfInstance || e.instance === input.selfInstance)));
+	if (others.length) return { handOff: false, reason: `${others.length} other interactive pi still open` };
+	if (!input.enabledLoops && !input.enabledRules && !input.pushServers) return { handOff: false, reason: "nothing to keep running" };
+	return { handOff: true, reason: `${input.enabledLoops} loop(s), ${input.enabledRules} rule(s), ${input.pushServers} push source(s)` };
+}
+
+/**
+ * MCP servers the host can do something with: a push either injects (inbox) or is evaluated
+ * against rules — a tool-only server with no rules is nothing to stay up for.
+ */
+export function hostPushWork(servers: Array<{ injectSummary?: boolean; injectAndRun?: boolean }>, enabledRules: number): number {
+	return servers.filter((s) => s.injectSummary || s.injectAndRun || enabledRules > 0).length;
+}
+
+/**
+ * `node [--experimental-strip-types] --import <register> <host-entry.mjs>`: TypeScript needs the flag
+ * before Node 23.6. The entry is the `.mjs` and not `host.ts` on purpose — under an npm install this
+ * package sits below node_modules, where Node refuses to strip types at all and only the jiti route
+ * inside src/ts-entry.mjs can open the file.
+ */
+export function hostSpawnArgs(nodeVersion: string, registerPath: string, entryPath: string): string[] {
+	const [major, minor] = nodeVersion.replace(/^v/, "").split(".").map(Number);
+	const strip = major < 23 || (major === 23 && minor < 6) ? ["--experimental-strip-types"] : [];
+	return [...strip, "--import", registerPath, entryPath];
+}
+
+/** Where pi itself lives, for the host's module resolver: `<pi package>/dist/bundle/cli.js` is what runs us. */
+export function piPackageDir(argv1 = process.argv[1]): string | undefined {
+	if (!argv1) return undefined;
+	try {
+		argv1 = fs.realpathSync(argv1); // `pi` is usually a bin symlink into the package
+	} catch {
+		/* keep as is */
+	}
+	let dir = path.dirname(argv1);
+	for (let i = 0; i < 4; i++) {
+		if (fs.existsSync(path.join(dir, "package.json")) && /pi-coding-agent/.test(dir)) return dir;
+		dir = path.dirname(dir);
+	}
+	return undefined;
+}
+
+export interface SpawnHostOptions {
+	dir: string;
+	packageDir: string;
+	piPackage?: string;
+	/** The handing-off pi's model and thinking level: the host's defaults for unpinned work. */
+	model?: string;
+	thinking?: string;
+	node?: string;
+	nodeVersion?: string;
+}
+
+/** Start the host detached, logging to `host.log`; returns its pid. */
+export function spawnHost(opts: SpawnHostOptions): number {
+	if ((process.versions as any).bun) throw new Error("the headless host needs node (pi is running under bun)");
+	const node = opts.node ?? process.execPath;
+	const args = hostSpawnArgs(opts.nodeVersion ?? process.version, path.join(opts.packageDir, "src", "register-pi.mjs"), path.join(opts.packageDir, "src", "host-entry.mjs"));
+	fs.mkdirSync(opts.dir, { recursive: true });
+	const log = fs.openSync(path.join(opts.dir, HOST_LOG), "a");
+	const child = spawn(node, args, {
+		detached: true,
+		stdio: ["ignore", log, log],
+		cwd: os.homedir(),
+		env: { ...process.env, PI_LOOPS_DIR: opts.dir, ...(opts.piPackage ? { PI_LOOPS_PI_PACKAGE: opts.piPackage } : {}), ...(opts.model ? { PI_LOOPS_HOST_MODEL: opts.model } : {}), ...(opts.thinking ? { PI_LOOPS_HOST_THINKING: opts.thinking } : {}) },
+	});
+	fs.closeSync(log);
+	// A spawn failure surfaces on the next tick; without a listener it would crash the quitting pi.
+	child.once("error", (err) => {
+		try {
+			fs.appendFileSync(path.join(opts.dir, HOST_LOG), `${stamp()} could not start the host: ${err?.message ?? err}\n`);
+		} catch {
+			/* nothing left to tell */
+		}
+	});
+	child.unref();
+	if (!child.pid) throw new Error("could not start the headless host");
+	// The host writes host.json itself, under a lock, once it knows no other host is running.
+	return child.pid;
+}
+
+/**
+ * Wait briefly for a spawned host to record itself. `spawn` returns a pid the instant it is called,
+ * so a host that dies during module resolution (a `PI_LOOPS_PI_PACKAGE` pointing at the wrong pi,
+ * a missing dependency) used to be announced as a successful hand-off, leaving all automation off
+ * with nothing but a line in `host.log`.
+ */
+export async function waitForHost(dir: string, pid: number, timeoutMs = 3000): Promise<boolean> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (readHost(dir)?.pid === pid) return true;
+		if (!pidAlive(pid)) return false;
+		await new Promise((r) => setTimeout(r, 100));
+	}
+	return readHost(dir)?.pid === pid;
+}

package/src/host-entry.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// The headless host's entry point (see src/host.ts), spawned by src/host-control.ts as
+// `node --import <pkg>/src/register-pi.mjs <pkg>/src/host-entry.mjs`. host.ts cannot be the entry
+// itself: under an npm install it sits below node_modules, where Node refuses to strip types, so the
+// same dual load the CLI uses has to happen here too (src/ts-entry.mjs).
+import { importTs } from "./ts-entry.mjs";
+
+try {
+	await importTs(import.meta.url, "./host.ts");
+} catch (err) {
+	// stdout and stderr are the host log; a line there is what `pi-loops host start` points a person at.
+	process.stderr.write(`pi-loops host: ${err?.message ?? err}\n`);
+	process.exit(1);
+}

package/src/host-runtime.ts

@@ -0,0 +1,222 @@
+/**
+ * What the headless host runs (see host.ts for the process shell): the same LoopScheduler and
+ * TriggerRuntime as the extension, wired for a process that has no chat — promotions go to the
+ * inbox, control-plane operations by sub-agents are audited into `triggers-audit.jsonl`, and the
+ * process leaves as soon as an interactive pi owns the clock. Injected so it can be unit-tested.
+ */
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import * as path from "node:path";
+import type { LoopsConfig } from "./config.ts";
+import { HookRunner, truncateSummary } from "./hooks.ts";
+import { PI_BUILTIN_TOOL_NAMES } from "./mcp.ts";
+import { redact } from "./redact.ts";
+import type { SubagentRequest, SubagentRunner } from "./runner.ts";
+import { LoopScheduler, type SessionSnapshot } from "./scheduler.ts";
+import { SubagentSlots } from "./slots.ts";
+import { type LoopJob, newId } from "./store.ts";
+import { type ToolHost, automationTools, createLoopJob } from "./tools.ts";
+import { TriggerRuntime } from "./trigger-runtime.ts";
+import { auditCronFinish, auditCronStart, TriggerStore, controlPlanePreflight } from "./triggers.ts";
+
+export interface HostRuntimeDeps {
+	dir: string;
+	config: () => LoopsConfig;
+	/** The host's own defaults: no cwd, the settings' model and thinking level. */
+	session: () => SessionSnapshot;
+	runner: SubagentRunner;
+	/** MCP tool definitions of the host's own (user-level) servers, for every sub-session. */
+	mcpTools: () => ToolDefinition<any, any>[];
+	/** That project's own MCP servers, connected on demand: the host has no project of its own. */
+	projectMcpTools?: (cwd: string, taken: Set<string>) => Promise<ToolDefinition<any, any>[]>;
+	/** Whether pi has a saved trust decision for exactly this directory (src/trust.ts). Default: no. */
+	isProjectTrusted?: (cwd: string) => boolean;
+	log: (message: string) => void;
+	/** Called when an interactive pi owns the clock: the host has nothing left to do. */
+	exit: (code: number) => void | Promise<void>;
+}
+
+export interface HostRuntime {
+	scheduler: LoopScheduler;
+	triggers: TriggerRuntime;
+	/** The tools a sub-session started by this host gets (its cwd and model, not the host's). */
+	customTools: (req: SubagentRequest) => Promise<ToolDefinition<any, any>[]>;
+	start(): void;
+	stop(): Promise<void>;
+}
+
+export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
+	const { dir, log } = deps;
+	let triggers: TriggerRuntime;
+	let exiting = false;
+
+	/* ------------------------------------------------------ lifecycle hooks */
+
+	/**
+	 * hooks.toml, fired around the runs the host starts: `run_start` and `run_end` (docs/hooks.md).
+	 * One runner per run — the host has no project of its own, so each run brings the project the
+	 * rules and the payload are about.
+	 */
+	const runHooks = new Map<string, HookRunner>();
+
+	function hookRunnerFor(job: LoopJob, runId: string): HookRunner | undefined {
+		// A model can pick a job's cwd (`cron_create` takes one) and nobody is here to answer a trust
+		// prompt, so a project's own hooks.toml needs pi's saved trust for that exact directory —
+		// the same bar the host puts in front of a project's MCP servers.
+		const trusted = !!deps.isProjectTrusted?.(job.cwd);
+		const runner = new HookRunner({
+			loopsDir: dir,
+			projectCwd: job.cwd,
+			allowProjectHooks: trusted && deps.config().allowProjectHooks,
+			// The run is this "session": its id is what pairs an `agent_start` with its `agent_end`.
+			getSession: () => ({ sessionId: runId, cwd: job.cwd, model: job.model ?? deps.session().model, thinking: job.thinking ?? deps.session().thinking }),
+			warn: (msg) => log(`hooks: ${msg}`),
+			// The host log is where "what did my automation do last night" is answered, so a hook that
+			// prints something has somewhere to print it here too.
+			log: (msg) => log(msg),
+		});
+		runner.load();
+		// `allow_project_hooks` in the user's own hooks.toml (or PI_ALLOW_PROJECT_HOOKS) opts every
+		// project in at once. That is a decision about projects the user opens, not about a directory
+		// this process was merely pointed at, so an untrusted one loses its rules again here.
+		if (!trusted) {
+			const kept = runner.hooks.filter((h) => h.source === "user");
+			if (kept.length !== runner.hooks.length) {
+				log(`hooks: ignoring ${runner.hooks.length - kept.length} project hook rule(s) in ${job.cwd}: pi has not trusted that directory`);
+				runner.hooks.length = 0;
+				runner.hooks.push(...kept);
+			}
+		}
+		for (const d of runner.diagnostics) log(`hooks: ${d}`);
+		if (!runner.hooks.length) return undefined;
+		runHooks.set(runId, runner);
+		return runner;
+	}
+
+	/**
+	 * One counter for every sub-agent this process starts — loop runs and trigger checks alike — so
+	 * `[cron] max_concurrent_runs` bounds what the host actually runs (src/slots.ts). No /goal here:
+	 * the host has no conversation to hold to a condition.
+	 */
+	const slots = new SubagentSlots(() => deps.config().maxConcurrentRuns);
+
+	const scheduler = new LoopScheduler({
+		dir,
+		kind: "host",
+		slots,
+		getSession: deps.session,
+		getSettings: () => ({ maxConcurrentRuns: deps.config().maxConcurrentRuns, catchUp: deps.config().cronCatchUp, dailyBudgetUsd: deps.config().dailyBudgetUsd }),
+		runner: deps.runner,
+		// No dead-session parking here: that is a decision the interactive leader can show the user.
+		hooks: {
+			// Plain (inject) jobs belong to a chat; the host has none, so they stay dormant here.
+			onInject: () => undefined,
+			onRunStart: (job, runId) => {
+				// The same rows the interactive extension writes: without them `/triggers audit` is
+				// blank for every hour the host had the clock.
+				auditCronStart(triggers.store, job, runId);
+				log(`loop ${job.name ?? job.id}: run ${runId.slice(0, 12)} started`);
+				// Never awaited: a webhook that hangs must not hold up the run it is announcing (the
+				// scheduler calls this synchronously). `.catch` because a rejection nobody owns takes
+				// the host down — hooks warn per rule, so there is nothing else to do with one.
+				const hooks = hookRunnerFor(job, runId);
+				if (hooks) void hooks.fire({ event: "run_start", run_job: job.name ?? job.id, run_id: runId, message_summary: truncateSummary(`${job.name ?? job.id}: ${job.prompt}`) }).catch((err: any) => log(`hooks: ${redact(err?.message ?? String(err))}`));
+			},
+			onCatchUp: (job) => log(`loop ${job.name ?? job.id}: catching up a missed tick`),
+			onRunFinished: ({ job, record, result }) => {
+				auditCronFinish(triggers.store, job, record, result.stopReason === "aborted");
+				log(`loop ${job.name ?? job.id}: ${record.ok ? "ok" : `FAILED (${redact(record.error ?? "")})`} · ${record.findings} finding(s)${record.usage?.cost ? ` · $${record.usage.cost.toFixed(3)}` : ""}`);
+				const hooks = runHooks.get(record.runId);
+				if (!hooks) return;
+				// `$PI_RUN_OK` alone answers "did last night's loop fail" — the thing the host exists to
+				// be able to tell someone.
+				const label = job.name ?? job.id;
+				const summary = record.ok ? `${label}: ok · ${record.findings} finding(s)` : `${label}: failed: ${record.error ?? "unknown error"}`;
+				// Its own hooks are the last thing a run does; the runner is dropped once they have run
+				// (until then `stop()` still has to drain it).
+				const forget = () => void runHooks.delete(record.runId);
+				void hooks
+					.fire({ event: "run_end", run_job: label, run_id: record.runId, run_ok: record.ok, run_findings: record.findings, run_error: record.error ? redact(record.error) : null, run_cost_usd: record.usage?.cost ?? null, message_summary: truncateSummary(summary) })
+					.then(forget, forget);
+			},
+			onTick: async (now, leader) => {
+				if (!leader) {
+					if (exiting) return;
+					exiting = true;
+					log("an interactive pi owns the clock; exiting");
+					await deps.exit(0);
+					return;
+				}
+				await triggers.tick(now, leader);
+			},
+			log: (msg) => log(redact(msg)),
+		},
+	});
+
+	const toInbox = async (content: string, trigger: { sourceLabel: string; traceId: string; cwd?: string }) => {
+		await scheduler.inbox.append({ source: `trigger:${trigger.sourceLabel}`, text: content.replace(/^\[Trigger [^\]]+\]\s*/, ""), runId: trigger.traceId, jobId: trigger.sourceLabel, cwd: trigger.cwd ?? "" });
+		return "inbox" as const;
+	};
+	triggers = new TriggerRuntime({
+		store: new TriggerStore(dir),
+		jobStore: scheduler.store,
+		getSession: deps.session,
+		pollIntervalSecs: deps.config().triggerPollIntervalSecs,
+		runTimeoutMs: deps.config().triggerRunTimeoutMs,
+		runner: deps.runner,
+		dedupFile: path.join(dir, "dedup.json"),
+		slots,
+		budget: () => scheduler.budgetState(),
+		self: scheduler.self,
+		presence: () => scheduler.presenceList(),
+		isLeader: () => scheduler.isLeader,
+		hooks: {
+			// No chat here: everything a rule would have promoted lands in the inbox.
+			onPromote: toInbox,
+			onInjectAndRun: toInbox,
+			onFinished: (o) => log(`trigger ${o.trigger.traceId.slice(0, 8)} ${o.delivery} ${o.ok ? "ok" : `FAILED (${redact(o.error ?? "")})`}${o.matchedRules.length ? ` matched ${o.matchedRules.length}` : ""}`),
+			log: (msg) => log(redact(msg)),
+		},
+	});
+
+	/** The tools' host for one sub-session: that run's cwd and model, not the process defaults. */
+	const toolHostFor = (req: Pick<SubagentRequest, "cwd" | "model" | "thinking">): ToolHost => {
+		const host: ToolHost = {
+			scheduler,
+			triggers,
+			session: () => ({ ...deps.session(), cwd: req.cwd, model: req.model ?? deps.session().model, thinking: req.thinking ?? deps.session().thinking }),
+			createJob: (input, scope) => createLoopJob(host, input, scope),
+			// The cron_control_plane audit has no session to live in here; /triggers audit shows it instead.
+			cronControlAudit: (op, actor, before, after) => {
+				const job = after ?? before;
+				const id = newId("audit");
+				triggers.store.appendAudit({ cwd: req.cwd, type: "cron_control_plane", traceId: id, state: op, sourceLabel: actor, eventLabel: job?.id, summary: job ? `${job.name ?? job.id}: ${job.prompt}` : undefined, details: { before_enabled: before?.enabled, after_enabled: after?.enabled } });
+				log(`cron control plane: ${op} by ${actor} ${job?.id ?? ""}`);
+				return id;
+			},
+			// Nobody can approve here: Prompt-class operations are denied fail-closed.
+			confirmTool: async (_ctx, request, atHop) => controlPlanePreflight({ hop: Math.max(1, atHop), hasUI: false }, request.label),
+			refreshBadge: () => undefined,
+		};
+		return host;
+	};
+
+	return {
+		scheduler,
+		triggers,
+		customTools: async (req) => {
+			const shared = deps.mcpTools();
+			const automation = automationTools({ hop: req.hop, actor: "sub-agent", parentSessionId: req.parentSessionId, parentCwd: req.parentCwd }, toolHostFor(req));
+			const taken = new Set([...PI_BUILTIN_TOOL_NAMES, ...shared.map((t) => t.name), ...automation.map((t) => t.name)]);
+			const project = req.cwd ? ((await deps.projectMcpTools?.(req.cwd, taken)) ?? []) : [];
+			return [...shared, ...project, ...automation];
+		},
+		start: () => scheduler.start(),
+		stop: async () => {
+			await triggers.stop();
+			await scheduler.stop();
+			// The runs are over; their hooks may still be in flight. Same bounded wait as the
+			// interactive path, so a "the run failed" webhook survives the host being told to quit.
+			await Promise.all([...runHooks.values()].map((h) => h.drain(3000)));
+		},
+	};
+}