@alphacoder-v0/pi-loops 0.17.3

package/src/config.ts

@@ -0,0 +1,103 @@
+/**
+ * `~/.pi/agent/loops/config.toml`:
+ *
+ *   allow_project_hooks = false
+ *   [triggers]
+ *   poll_interval_secs = 600
+ *   run_timeout_secs = 900        # cap on a check/action sub-agent
+ *   [cron]
+ *   catch_up = true               # fire the tick a loop missed while no pi was open (false wins over --catchup)
+ *   max_concurrent_runs = 3       # sub-agents in flight at once — loop runs and trigger checks share it
+ *   [hooks]
+ *   mode = "sync"                 # sync = awaited inline; async = queued off the turn
+ *   [host]
+ *   auto = true                   # when the last pi quits, a headless host keeps loops and triggers running
+ *   [limits]
+ *   daily_budget_usd = 5.0        # stop dispatching once today's automation has cost this much (0 = no cap)
+ *   [danger]
+ *   allow = ["rm -rf /var/cache/x"]  # command prefixes an unattended run may use anyway
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseToml } from "./toml.ts";
+import { DEFAULT_TRIGGER_POLL_INTERVAL_SECS } from "./triggers.ts";
+
+export interface LoopsConfig {
+	allowProjectHooks: boolean;
+	triggerPollIntervalSecs: number;
+	triggerRunTimeoutMs: number;
+	cronCatchUp: boolean;
+	maxConcurrentRuns: number;
+	hooksMode: "sync" | "async";
+	/** Start the headless host when the last interactive pi quits with automation configured. */
+	hostAuto: boolean;
+	/** Stop dispatching once automation has spent this much today (local time). 0 = no cap. */
+	dailyBudgetUsd: number;
+	/** Command prefixes an unattended run may use despite the dangerous-command gate. */
+	allowCommands: string[];
+	errors: string[];
+}
+
+export const DEFAULT_TRIGGER_RUN_TIMEOUT_SECS = 15 * 60;
+export const DEFAULT_MAX_CONCURRENT_RUNS = 3;
+
+/**
+ * An on/off environment override, read the way a person would write one: `PI_<NAME>=1` or `=true`,
+ * either case. One reader for all of them, so a spelling that works in one place works everywhere.
+ * Anything that is not `1` or `true` is off, so a typo fails closed.
+ */
+export function envFlag(name: string): boolean {
+	const value = process.env[`PI_${name}`];
+	return value === "1" || value?.toLowerCase() === "true";
+}
+
+export function loadConfig(dir: string): LoopsConfig {
+	const cfg: LoopsConfig = { allowProjectHooks: false, triggerPollIntervalSecs: DEFAULT_TRIGGER_POLL_INTERVAL_SECS, triggerRunTimeoutMs: DEFAULT_TRIGGER_RUN_TIMEOUT_SECS * 1000, cronCatchUp: true, maxConcurrentRuns: DEFAULT_MAX_CONCURRENT_RUNS, hooksMode: "sync", hostAuto: true, dailyBudgetUsd: 0, allowCommands: [], errors: [] };
+	const file = path.join(dir, "config.toml");
+	const positiveInt = (section: string, key: string, v: unknown, apply: (n: number) => void) => {
+		if (v === undefined) return;
+		if (typeof v === "number" && v >= 1) apply(Math.floor(v));
+		else cfg.errors.push(`${section}: ignoring invalid ${key} in ${file}: \`[${section}] ${key}\` must be at least 1`);
+	};
+	try {
+		const doc = parseToml(fs.readFileSync(file, "utf8"));
+		if (doc.allow_project_hooks === true) cfg.allowProjectHooks = true;
+		const t = doc.triggers as any;
+		if (t && t.poll_interval_secs !== undefined) {
+			if (typeof t.poll_interval_secs === "number" && t.poll_interval_secs >= 1) cfg.triggerPollIntervalSecs = Math.floor(t.poll_interval_secs);
+			else cfg.errors.push(`triggers: ignoring invalid poll interval in ${file}: \`[triggers] poll_interval_secs\` must be at least 1`);
+		}
+		positiveInt("triggers", "run_timeout_secs", t?.run_timeout_secs, (n) => (cfg.triggerRunTimeoutMs = n * 1000));
+		const c = doc.cron as any;
+		if (c && c.catch_up !== undefined) {
+			if (typeof c.catch_up === "boolean") cfg.cronCatchUp = c.catch_up;
+			else cfg.errors.push(`cron: ignoring invalid catch_up in ${file}: must be true or false`);
+		}
+		positiveInt("cron", "max_concurrent_runs", c?.max_concurrent_runs, (n) => (cfg.maxConcurrentRuns = n));
+		const dg = doc.danger as any;
+		if (dg && dg.allow !== undefined) {
+			if (Array.isArray(dg.allow) && dg.allow.every((x: unknown) => typeof x === "string")) cfg.allowCommands = dg.allow as string[];
+			else cfg.errors.push(`danger: ignoring invalid allow in ${file}: [danger] allow must be a list of command prefixes`);
+		}
+		const lim = doc.limits as any;
+		if (lim && lim.daily_budget_usd !== undefined) {
+			const n = lim.daily_budget_usd;
+			if (typeof n === "number" && Number.isFinite(n) && n >= 0) cfg.dailyBudgetUsd = n;
+			else cfg.errors.push(`limits: ignoring invalid daily_budget_usd in ${file}: must be a number of dollars ≥ 0 (0 = no cap)`);
+		}
+		const ho = doc.host as any;
+		if (ho && ho.auto !== undefined) {
+			if (typeof ho.auto === "boolean") cfg.hostAuto = ho.auto;
+			else cfg.errors.push(`host: ignoring invalid auto in ${file}: must be true or false`);
+		}
+		const h = doc.hooks as any;
+		if (h && h.mode !== undefined) {
+			if (h.mode === "sync" || h.mode === "async") cfg.hooksMode = h.mode;
+			else cfg.errors.push(`hooks: ignoring invalid mode in ${file}: \`[hooks] mode\` must be "sync" or "async"`);
+		}
+	} catch (err: any) {
+		if (err?.code !== "ENOENT") cfg.errors.push(`${file}: ${err?.message ?? err}`);
+	}
+	if (envFlag("ALLOW_PROJECT_HOOKS")) cfg.allowProjectHooks = true;
+	return cfg;
+}

package/src/danger.ts

@@ -0,0 +1,128 @@
+/**
+ * The dangerous-command policy for runs nobody is watching.
+ *
+ * pi has no built-in denylist — it asks the person at the keyboard instead, which is the right
+ * answer while there is one. A scheduled run has nobody to ask, so an unattended loop would
+ * otherwise be free to run `rm -rf /` or `git push --force main`. This module is the whole policy
+ * as one function; `src/subagent-guard.ts` is what applies it inside every sub-session.
+ */
+import * as os from "node:os";
+
+/**
+ * The patterns, widened where the obvious ones are trivially evaded.
+ * They run against a *dequoted* copy of the command (see `dequote`), because `su''do` and
+ * `sh""utdown` are the same program to a shell and no word-boundary rule survives them.
+ */
+const PATTERNS: Array<[label: string, re: RegExp]> = [
+	["sudo invocation", /\b(sudo|doas|pkexec)\b/],
+	// Stopping at the first pipe is not enough; a command can reach a shell through any number of them.
+	["curl/wget piped into a shell", /\b(curl|wget)\b[\s\S]*\|\s*\S*\b(bash|sh|zsh|fish|dash|ksh)\b/],
+	["dd writing to a block device", /\bdd\b[^\n]*\bof=\/dev\/(disk|sd[a-z]|nvme|hd[a-z])/],
+	["mkfs / format command", /\bmkfs(\.|\s)/],
+	// Requiring 777 immediately after chmod misses any flag (-R) walks past it.
+	["chmod 777 on an absolute path", /\bchmod\b(\s+-\S+)*\s+0?777\s+\//],
+	["shutdown / reboot / halt", /\b(shutdown|reboot|halt|poweroff)\b/],
+	// Matching only `--force`/`-f` misses `+main`, which is the same thing through a refspec.
+	["git push --force on main/master", /\bgit\s+push\b[^\n]*(--force|--force-with-lease|\s-f\b|\s\+)[^\n]*\b(main|master)\b/],
+	["piping or substituting into eval", /(\|\s*eval\b|\beval\s+["'`]?\$\()/],
+	[":(){:|:&};: forkbomb", /:\(\)\s*\{\s*:\|:&\s*\}\s*;\s*:/],
+];
+
+/** Shell syntax that starts a second command; an allowlist entry must not carry one along. */
+const CHAINS = /[;&|\n\r`$(){}<>]/;
+
+/**
+ * Does allowlist entry `entry` cover `command`? An entry means that command and nothing else.
+ * "Arguments may follow" cannot be made safe: `rm -rf /var/cache/x /` needs no metacharacter at
+ * all, and an allowed wrapper (`ssh host`, `docker run`, `timeout 5`) would carry a whole second
+ * program as its arguments. The only latitude is a path strictly inside the one the entry ends
+ * with, which is narrower than what the entry already permits.
+ */
+function allows(entry: string, command: string): boolean {
+	const a = entry.trim();
+	if (!a) return false;
+	if (command === a) return true;
+	if (!command.startsWith(`${a}/`)) return false;
+	const rest = command.slice(a.length);
+	// `/var/cache/mybuild/../..` starts inside the allowed path and ends somewhere else; whitespace
+	// would mean a second operand rather than a deeper path.
+	return !rest.includes("..") && !/\s/.test(rest) && !CHAINS.test(rest);
+}
+
+/**
+ * Remove quoting that changes nothing for the shell but hides a word from a regex: `su''do`,
+ * `sh""utdown`, `r''m -rf /`.
+ *
+ * The dequoted copy is what both halves of the policy see — the pattern scan and the `rm` walk — and
+ * that is deliberate. It removes only empty quote pairs and backslashes before letters, neither of
+ * which a shell would have kept, so `rm` is still found under `r""m` and `$HOME` under `\\$HOME`.
+ * The quoting that decides an operand is still there for `normalizeOperand` to strip: `rm -rf "/"`
+ * arrives here unchanged and is refused for the target it names. Where the two copies could differ
+ * at all (`rm -rf "''/"`, a directory literally called `''`) the dequoted one refuses and the
+ * original allows — and in an unattended run, refusing is the direction to be wrong in.
+ */
+function dequote(command: string): string {
+	return command.replace(/''|""/g, "").replace(/\\(?=[a-zA-Z])/g, "");
+}
+
+/** Strip one layer of quoting and expand $HOME / ${HOME} / ~. */
+function normalizeOperand(token: string, home: string | undefined): string {
+	let t = token.trim();
+	if (t.length >= 2 && ((t[0] === '"' && t.endsWith('"')) || (t[0] === "'" && t.endsWith("'")))) t = t.slice(1, -1);
+	if (!home) return t;
+	t = t.replace(/\$\{HOME\}|\$HOME/g, home);
+	if (t === "~") return home;
+	if (t.startsWith("~/")) return home + t.slice(1);
+	return t;
+}
+
+const RECURSIVE = /^(-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)$/;
+const FORCE = /^(-[a-zA-Z]*f[a-zA-Z]*|--force)$/;
+
+/**
+ * An `rm` bearing both a recursive and a force flag, aimed at `/`, any absolute path, or $HOME.
+ * Every command cluster reachable through `;`, `&&`, `||`, `|` is checked,
+ * plus the ones a substitution opens — `echo $(rm -rf /)` runs the `rm` just as surely.
+ */
+function rmRecursiveForceOnDangerousTarget(command: string, home: string | undefined): string | undefined {
+	for (const cluster of command.split(/;|&&|\|\||\||\n|`|\$\(|\)/)) {
+		const tokens = cluster.trim().split(/\s+/).filter(Boolean);
+		const rmAt = tokens.findIndex((t) => t === "rm" || t.endsWith("/rm"));
+		if (rmAt < 0) continue;
+		const args = tokens.slice(rmAt + 1);
+		let recursive = false;
+		let force = false;
+		for (const a of args) {
+			if (RECURSIVE.test(a)) recursive = true;
+			if (FORCE.test(a)) force = true;
+		}
+		if (!recursive || !force) continue;
+		for (const a of args) {
+			if (a.startsWith("-")) continue;
+			// With no known home the `~`/$HOME rules cannot fire, but `/` and absolute paths still do.
+			const target = normalizeOperand(a, home);
+			if (target === "/") return "rm recursive+force on /";
+			if (home && (target === home || target.startsWith(`${home}/`) || target === "~" || target.startsWith("~/"))) return "rm recursive+force on $HOME or ~";
+			if (target.startsWith("/")) return "rm recursive+force on absolute path";
+			// `X=/; rm -rf $X` reads as a relative path here, and the guard cannot know what the
+			// variable holds. An unattended `rm -r -f` at an unknown target is refused on that basis.
+			if (/[$`]/.test(target)) return "rm recursive+force on an unresolved target";
+		}
+	}
+	return undefined;
+}
+
+/** The reason this shell command is refused for an unattended run, or undefined when it is fine. */
+export function dangerousCommandReason(command: string, home: string = process.env.HOME || os.homedir(), allow: readonly string[] = []): string | undefined {
+	if (!command) return undefined;
+	// An allowlist entry permits that command and arguments after it — but nothing chained onto it.
+	// A bare prefix match would make `allow = ["rm -rf /var/cache/mybuild"]` also mean
+	// `rm -rf /var/cache/mybuild; rm -rf /`, handing arbitrary shell to the one actor this gate
+	// exists to stop. Deliberately not a regex: this is a list a person writes in a config file,
+	// and a wrong regex there fails open.
+	const trimmed = command.trim();
+	if (allow.some((a) => allows(a, trimmed))) return undefined;
+	const scanned = dequote(command);
+	for (const [label, re] of PATTERNS) if (re.test(scanned)) return label;
+	return rmRecursiveForceOnDangerousTarget(scanned, home || undefined);
+}

package/src/goal.ts

@@ -0,0 +1,178 @@
+import { stamp } from "./schedule.ts";
+/**
+ * `/goal`: a stop condition the agent is held to.
+ *
+ * Everything pi-loops otherwise schedules is time- or event-driven. A goal is the one mechanism
+ * that asks "am I done yet" — after every settled turn an evaluator (a model call with no tools and
+ * only a bounded transcript) judges the user's condition. `{ok:false}` sends the agent back to work
+ * with what is missing, up to a continuation budget; `{ok:true}` stops; an evaluator that itself
+ * fails pauses rather than looping — an evaluator that cannot answer must not become a machine
+ * that keeps paying for turns.
+ */
+
+/** Each state change is appended to the session, so `--resume` finds it. */
+export const GOAL_ENTRY = "goal_state";
+/** How many times the agent may be sent back to work before the goal pauses itself. */
+export const MAX_CONTINUATIONS = 8;
+/** How much of the transcript the evaluator is shown. */
+export const TRANSCRIPT_CHAR_LIMIT = 40_000;
+
+export type GoalStatus = "pursuing" | "paused" | "achieved" | "budget_limited" | "cleared";
+
+export interface GoalState {
+	condition: string;
+	status: GoalStatus;
+	iterations: number;
+	lastReason?: string;
+	updatedAt: string;
+}
+
+/** A cleared or achieved goal no longer holds the session. */
+export function goalActive(state: GoalState): boolean {
+	return state.status === "pursuing" || state.status === "paused" || state.status === "budget_limited";
+}
+
+export interface EvaluatorDecision {
+	ok: boolean;
+	reason: string;
+}
+
+export function newGoal(condition: string, now = new Date()): GoalState {
+	return { condition, status: "pursuing", iterations: 0, updatedAt: stamp(now.getTime()) };
+}
+
+/** The newest state in a session's entries, or undefined when the goal was cleared or never set. */
+export function latestGoal(entries: Array<{ type?: string; customType?: string; data?: unknown }>): GoalState | undefined {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const e = entries[i] as any;
+		if (e?.customType !== GOAL_ENTRY) continue;
+		const data = e.data as GoalState | undefined;
+		if (!data || typeof data.condition !== "string" || typeof data.status !== "string") continue;
+		if (data.status === "cleared") return undefined;
+		// `iterations` is the continuation budget. A session entry is only as trustworthy as what
+		// wrote it (an imported archive carries these verbatim), and a non-number would make
+		// `iterations + 1 >= MAX_CONTINUATIONS` false forever — an unbounded self-prompting loop.
+		return { ...data, iterations: Number.isInteger(data.iterations) && data.iterations >= 0 ? data.iterations : 0 };
+	}
+	return undefined;
+}
+
+/**
+ * The transcript the evaluator sees: `role: text` per message, truncated from the front so the most
+ * recent evidence always survives the cap.
+ */
+export function transcriptFromMessages(messages: Array<{ role?: string; content?: unknown }>, limit = TRANSCRIPT_CHAR_LIMIT): string {
+	const lines: string[] = [];
+	for (const m of messages) {
+		const role = typeof m?.role === "string" ? m.role : "unknown";
+		const text = renderContent(m?.content);
+		if (text) lines.push(`${role}: ${text}`);
+	}
+	const joined = lines.join("\n");
+	return joined.length <= limit ? joined : `…\n${joined.slice(joined.length - limit)}`;
+}
+
+function renderContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const block of content) {
+		const b = block as any;
+		if (typeof b?.text === "string") parts.push(b.text);
+		else if (b?.type === "toolCall") parts.push(`<tool_call ${b.name ?? "?"}>`);
+		else if (b?.type === "thinking") parts.push("<thinking>");
+	}
+	return parts.join(" ").trim();
+}
+
+/** The evaluator's system and user prompts, joined: pi-loops has one prompt channel. */
+export function evaluatorPrompt(condition: string, transcript: string): string {
+	return [
+		"You are evaluating a stop-condition hook in pi-loops.",
+		"Read the conversation transcript carefully, then judge whether the user-provided condition is satisfied.",
+		"You cannot call tools. Only use explicit evidence in the transcript.",
+		"Your response must be a JSON object with one of these shapes:",
+		'{"ok": true, "reason": "<quote evidence from the transcript that satisfies the condition>"}',
+		'{"ok": false, "reason": "<quote what is missing or what blocks the condition>"}',
+		"Always include a reason field, quoting specific text from the transcript whenever possible.",
+		'If the transcript does not contain clear evidence that the condition is satisfied, return {"ok": false, "reason": "insufficient evidence in transcript"}.',
+		"",
+		`Goal condition:\n${condition}`,
+		"",
+		`Conversation transcript:\n${transcript}`,
+	].join("\n");
+}
+
+/** Parsing a decision: bare JSON, or the first `{`…`}` in the reply. An empty reason is an error. */
+export function parseDecision(text: string): EvaluatorDecision {
+	const trimmed = text.trim();
+	const candidates = [trimmed];
+	const start = trimmed.indexOf("{");
+	const end = trimmed.lastIndexOf("}");
+	if (start >= 0 && end > start) candidates.push(trimmed.slice(start, end + 1));
+	for (const candidate of candidates) {
+		let parsed: any;
+		try {
+			parsed = JSON.parse(candidate);
+		} catch {
+			continue;
+		}
+		if (!parsed || typeof parsed.ok !== "boolean" || typeof parsed.reason !== "string") continue;
+		if (!parsed.reason.trim()) throw new Error("goal evaluator returned an empty reason");
+		return { ok: parsed.ok, reason: parsed.reason };
+	}
+	throw new Error(`goal evaluator returned invalid JSON: ${tailChars(trimmed, 300)}`);
+}
+
+function tailChars(text: string, maxChars: number): string {
+	const chars = Array.from(text);
+	return chars.length <= maxChars ? text : chars.slice(chars.length - maxChars).join("");
+}
+
+/** What the agent is sent back to work with. */
+export function continuationPrompt(condition: string, reason: string): string {
+	return `The current /goal is not satisfied yet.\n\nGoal condition:\n${condition}\n\nGoal evaluator says what is missing or blocking completion:\n${reason}\n\nContinue working toward the goal. Do not claim completion until the transcript contains explicit evidence that satisfies the condition.`;
+}
+
+export type GoalAction = { kind: "stop" } | { kind: "continue"; prompt: string } | { kind: "pause"; reason: string };
+
+/** What a decision does to the state, and what happens next. */
+export function applyDecision(state: GoalState, decision: EvaluatorDecision, now = new Date()): { state: GoalState; action: GoalAction } {
+	const next: GoalState = { ...state, iterations: state.iterations + 1, lastReason: decision.reason, updatedAt: stamp(now.getTime()) };
+	if (decision.ok) return { state: { ...next, status: "achieved" }, action: { kind: "stop" } };
+	if (next.iterations >= MAX_CONTINUATIONS) {
+		return { state: { ...next, status: "budget_limited" }, action: { kind: "pause", reason: `goal continuation limit reached (${MAX_CONTINUATIONS}); resume with /goal resume` } };
+	}
+	return { state: next, action: { kind: "continue", prompt: continuationPrompt(next.condition, decision.reason) } };
+}
+
+/**
+ * Whether the session has moved off the point the goal was judged at, so a continuation would be
+ * delivered as a follow-up on somebody else's turn. The evaluator reads for up to two minutes and
+ * the session takes input the whole time: a question typed meanwhile would be answered under the
+ * goal's continuation prompt instead of its own.
+ *
+ * `entries` is the current branch root-first (pi's `sessionManager.getBranch()`), `at` the leaf id
+ * captured before the evaluation started. A moved leaf is not enough on its own: run cards, panel
+ * snapshots and the goal's own state entries all append there and mean nothing here — only a user
+ * message the goal did not send. The goal's own previous continuation is never one of them; the
+ * turn that carried it had settled before this evaluation began, so it is already behind `at`.
+ */
+export function branchMovedSince(entries: Array<{ id: string; type: string; message?: { role?: string } }>, at: string | null): boolean {
+	if (at === null) return false; // nothing to compare against (an empty session): behave as before
+	const from = entries.findIndex((e) => e.id === at);
+	// Rewound, forked or edited: the branch the goal was judged on is not the one we are on.
+	if (from < 0) return true;
+	return entries.slice(from + 1).some((e) => e.type === "message" && e.message?.role === "user");
+}
+
+/** An evaluator that could not decide never loops the agent: it pauses and says why. */
+export function pauseFor(state: GoalState, reason: string, now = new Date()): { state: GoalState; action: GoalAction } {
+	return { state: { ...state, status: "paused", lastReason: reason, updatedAt: stamp(now.getTime()) }, action: { kind: "pause", reason } };
+}
+
+/** One line for `/goal` and the panel. */
+export function goalLine(state: GoalState): string {
+	const iter = `${state.iterations}/${MAX_CONTINUATIONS}`;
+	return `${state.status} (${iter} continuations)${state.lastReason ? `: ${state.lastReason}` : ""}`;
+}