@alphacoder-v0/pi-loops 0.17.3

package/src/pi-resolver.mjs

@@ -0,0 +1,49 @@
+// Where pi's packages are, for everything that runs outside pi's own loader: the `node --import` hook
+// for the headless host (src/host-entry.mjs) and the tests, and the jiti aliases in src/ts-entry.mjs.
+// PI_LOOPS_PI_PACKAGE names pi's package dir; else the one beside this Node, else the global install.
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+
+let pkg;
+/** pi's package directory: what was told, else the one beside this Node, else the global install. */
+export function piPackage() {
+	if (pkg) return pkg;
+	const told = process.env.PI_LOOPS_PI_PACKAGE;
+	if (told && fs.existsSync(path.join(told, "package.json"))) return (pkg = told);
+	const guess = path.join(path.dirname(path.dirname(process.execPath)), "lib", "node_modules", "@earendil-works", "pi-coding-agent");
+	if (fs.existsSync(path.join(guess, "package.json"))) return (pkg = guess);
+	return (pkg = path.join(execSync("npm root -g", { encoding: "utf8" }).trim(), "@earendil-works", "pi-coding-agent"));
+}
+// Relative to pi's package directory.
+const MAP = {
+	"@earendil-works/pi-coding-agent": "dist/index.js",
+	"@earendil-works/pi-ai": "node_modules/@earendil-works/pi-ai/dist/index.js",
+	"@earendil-works/pi-agent-core": "node_modules/@earendil-works/pi-agent-core/dist/index.js",
+	"@earendil-works/pi-tui": "node_modules/@earendil-works/pi-tui/dist/index.js",
+	typebox: "node_modules/typebox/build/index.mjs",
+};
+/**
+ * The same map as an absolute-path table, which is the shape jiti's `alias` option wants — for when
+ * jiti loads this package's TypeScript instead of Node (src/ts-entry.mjs). It is derived from `MAP`
+ * rather than written twice so the two routes cannot resolve pi differently. Entries whose file is
+ * missing are dropped, exactly as the hook below declines to short-circuit for them.
+ */
+export function piAliases() {
+	const dir = piPackage();
+	const out = {};
+	for (const [specifier, rel] of Object.entries(MAP)) {
+		const file = path.join(dir, rel);
+		if (fs.existsSync(file)) out[specifier] = file;
+	}
+	return out;
+}
+export async function resolve(specifier, context, next) {
+	const rel = MAP[specifier];
+	if (rel) {
+		const file = path.join(piPackage(), rel);
+		if (fs.existsSync(file)) return { url: pathToFileURL(file).href, shortCircuit: true };
+	}
+	return next(specifier, context);
+}

package/src/presence.ts

@@ -0,0 +1,143 @@
+/**
+ * Presence registry: which pi processes are alive on this machine, in which project and
+ * session. One small file per process under `<dir>/presence/`, refreshed on every scheduler
+ * tick and removed on shutdown; stale entries (no heartbeat for 90 s, or a dead pid on this
+ * host) are ignored and pruned.
+ *
+ * It restores what session scoping would give for free: a dynamic rule is checked by the pi
+ * session that created it, and failing that by a pi that is *in that project*, so promotions land
+ * in the right chat. Only when no pi is open there does the machine leader step in (and the result
+ * goes to the inbox).
+ */
+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 { realpathish } from "./paths.ts";
+import { stamp } from "./schedule.ts";
+
+export const PRESENCE_STALE_MS = 90_000;
+
+export type PresenceKind = "interactive" | "host";
+
+export interface PresenceEntry {
+	pid: number;
+	host: string;
+	/** Distinguishes scheduler instances inside one process (reload, tests). */
+	instance: string;
+	sessionId?: string;
+	cwd: string;
+	/** "host" = the headless process that keeps the clock while no interactive pi is open. */
+	kind?: PresenceKind;
+	heartbeatAt: string;
+}
+
+export type PresenceSelf = Omit<PresenceEntry, "heartbeatAt">;
+
+export class PresenceRegistry {
+	readonly dir: string;
+	readonly file: string;
+	private readonly self: PresenceSelf;
+
+	constructor(dir: string, self: PresenceSelf) {
+		this.dir = path.join(dir, "presence");
+		this.self = self;
+		this.file = path.join(this.dir, `${self.host.replace(/[^A-Za-z0-9._-]/g, "_")}-${self.pid}-${self.instance}.json`);
+	}
+
+	/** Refresh this process's entry (session and cwd may change between ticks). */
+	heartbeat(now: number, current?: Partial<Pick<PresenceEntry, "sessionId" | "cwd">>): void {
+		const entry: PresenceEntry = { ...this.self, ...current, heartbeatAt: stamp(now) };
+		writeFileAtomic(this.file, `${JSON.stringify(entry)}\n`);
+	}
+
+	remove(): void {
+		fs.rmSync(this.file, { force: true });
+	}
+
+	/** Live entries on every host; stale ones are pruned as a side effect (best effort). */
+	list(now: number): PresenceEntry[] {
+		let names: string[];
+		try {
+			names = fs.readdirSync(this.dir);
+		} catch {
+			return [];
+		}
+		const out: PresenceEntry[] = [];
+		for (const name of names) {
+			if (!name.endsWith(".json")) continue;
+			const file = path.join(this.dir, name);
+			let e: PresenceEntry | undefined;
+			try {
+				e = JSON.parse(fs.readFileSync(file, "utf8")) as PresenceEntry;
+			} catch {
+				continue;
+			}
+			if (!e || typeof e.pid !== "number" || typeof e.cwd !== "string") continue;
+			const age = now - Date.parse(e.heartbeatAt);
+			const mine = e.pid === this.self.pid && e.host === this.self.host && e.instance === this.self.instance;
+			// A negative age means that machine's clock is ahead of ours; such an entry would never
+			// age out and would keep a dead session's plain jobs from ever being parked.
+			const stale = !mine && (Number.isNaN(age) || age > PRESENCE_STALE_MS || age < -PRESENCE_STALE_MS || (e.host === this.self.host && !pidAlive(e.pid)));
+			if (stale) {
+				fs.rmSync(file, { force: true });
+				continue;
+			}
+			out.push(e);
+		}
+		return out;
+	}
+}
+
+/** A root so broad that containment would mean "everything": never treated as one project. */
+function tooBroad(dir: string): boolean {
+	return dir === "/" || dir === os.homedir() || path.dirname(dir) === dir;
+}
+
+/** True when `p` is the project rooted at `root` or a directory inside it, symlinks resolved. */
+export function withinProject(root: string, p: string): boolean {
+	const a = realpathish(root);
+	const b = realpathish(p);
+	if (!a || !b) return false;
+	if (a === b) return true;
+	// Containment is what makes a worktree or a subdirectory the same project. `/` and `$HOME`
+	// contain everything, so a rule created with one of those as its cwd governs only itself.
+	if (tooBroad(a)) return false;
+	const rel = path.relative(a, b);
+	return !!rel && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/**
+ * The process that should act for the project rooted at `cwd` on `host`: a live pi opened in it —
+ * or in a subdirectory of it, or through a symlink to it — lowest pid as the tie-break so every
+ * process computes the same answer. `undefined` when no pi is open there: the caller falls back
+ * to the machine leader.
+ */
+export function chooseCwdOwner(entries: PresenceEntry[], cwd: string, host: string): PresenceEntry | undefined {
+	const here = entries.filter((e) => e.host === host && e.kind !== "host" && withinProject(cwd, e.cwd));
+	if (!here.length) return undefined;
+	return [...here].sort((a, b) => a.pid - b.pid || a.instance.localeCompare(b.instance))[0];
+}
+
+/**
+ * The process that evaluates one rule of the project rooted at `cwd`.
+ *
+ * Rules are machine-global, which is what lets them outlive the session that created them — and it
+ * costs the one thing a per-session file would have given away: knowing whose conversation a
+ * promotion belongs in. This is how that is won back. While the creating session is open on this
+ * host it owns its rule; once that session is gone the project's cwd owner takes it, and only with
+ * no pi open in the project at all does the machine leader (whose results go to the inbox, having
+ * no conversation to claim).
+ */
+export function chooseRuleOwner(entries: PresenceEntry[], cwd: string, host: string, sessionId?: string): PresenceEntry | undefined {
+	const session = sessionId ? entries.find((e) => e.sessionId === sessionId && e.host === host && e.kind !== "host") : undefined;
+	return session ?? chooseCwdOwner(entries, cwd, host);
+}
+
+export function isSelf(entry: PresenceEntry | undefined, self: PresenceSelf): boolean {
+	return !!entry && entry.pid === self.pid && entry.host === self.host && entry.instance === self.instance;
+}
+
+export function localHost(): string {
+	return os.hostname();
+}

package/src/protocol.ts

@@ -0,0 +1,198 @@
+/**
+ * The loop output protocol — plain text, provider-agnostic, matching
+ * docs/loops.md: the sub-agent ends its reply with <loop-state>…</loop-state>
+ * and zero or more <inbox>…</inbox> tags. Extraction never fails a run.
+ */
+
+export const LOOP_STATE_MAX_CHARS = 2000;
+export const INBOX_TEXT_MAX_CHARS = 500;
+export const INBOX_TAGS_PER_RUN = 16;
+/**
+ * How many `<inbox>` tags are read out of one reply at all. Past this the dropped-finding count
+ * stops being exact, which is the right trade: a reply carrying a thousand findings is a runaway,
+ * not a report, and scanning it to the end only puts a number on how far it ran away.
+ */
+const MAX_INBOX_TAGS_SCANNED = 1000;
+export const FIRST_RUN_MARKER = "(first run)";
+/**
+ * The two lines that bracket the job's own text in a composed prompt. They are part of the protocol,
+ * so they are named here and read here (`jobTextOf`): the transcript view used to carry its own
+ * copies of both literals, and a prompt reworded on one side silently stopped being parsed on the other.
+ */
+export const LOOP_STATE_CLOSE = "[/loop-state]";
+export const OUTPUT_PROTOCOL_HEADING = "Output protocol (mandatory):";
+
+export function capChars(text: string, max: number): string {
+	const chars = Array.from(text.trim());
+	if (chars.length <= max) return chars.join("");
+	return `${chars.slice(0, max).join("")}…`;
+}
+
+export function composeLoopPrompt(action: string, previousState: string | undefined, meta?: { name?: string; runAt?: string }): string {
+	const state = previousState && previousState.trim() ? capChars(previousState, LOOP_STATE_MAX_CHARS) : FIRST_RUN_MARKER;
+	const header = meta?.name ? `You are running the recurring loop "${meta.name}"` : "You are running a recurring loop";
+	/**
+	 * The run time, and how to write one.
+	 *
+	 * The notes this prompt asks for hold watermarks — "everything up to here has been seen" — and
+	 * a watermark is a time the model writes in whatever shape it likes. That was survivable while
+	 * a loop belonged to one machine. It does not: a job with no `host` runs on any machine sharing
+	 * the `$HOME` (scheduler.ts, and `/cron set <ref> --host -` asks for exactly that), so run N can
+	 * write "checked up to 20:00" in Shanghai and run N+1 read it in New York.
+	 *
+	 * The stamp carries its offset; this asks for the same of anything the model writes back. It
+	 * goes in this line rather than in the protocol block below, which is quoted verbatim.
+	 */
+	const when = meta?.runAt ? ` (current run started ${meta.runAt}; write any time in your notes with its offset, as that one has)` : "";
+	return [
+		`${header}${when}. This is a background run: nobody is watching, and your final reply is parsed by a program.`,
+		"",
+		"[loop-state] (your notes from the previous run of this recurring job)",
+		state,
+		LOOP_STATE_CLOSE,
+		"",
+		action.trim(),
+		"",
+		OUTPUT_PROTOCOL_HEADING,
+		`- End your reply with <loop-state>notes for the next run</loop-state> — it REPLACES the saved state; keep it under ${LOOP_STATE_MAX_CHARS} characters and make it the information your next run needs (baselines, ids already seen, watermarks).`,
+		"- For each finding a human should act on, emit <inbox>one concise line</inbox>. No findings → no inbox tags; do not invent work.",
+		"- Keep everything after the last tool call short so the tags are not truncated.",
+	].join("\n");
+}
+
+/** Last `<tag>…</tag>` block, trimmed. Unclosed tags are ignored. */
+export function extractTagBlock(text: string, tag: string): string | undefined {
+	const open = `<${tag}>`;
+	const close = `</${tag}>`;
+	const start = text.lastIndexOf(open);
+	if (start < 0) return undefined;
+	const rest = text.slice(start + open.length);
+	const end = rest.indexOf(close);
+	if (end < 0) return undefined;
+	return rest.slice(0, end).trim();
+}
+
+/** Every `<tag>…</tag>` block in order, capped at `max`. Empty bodies are skipped. */
+export function extractTagAll(text: string, tag: string, max: number): string[] {
+	const open = `<${tag}>`;
+	const close = `</${tag}>`;
+	const out: string[] = [];
+	let rest = text;
+	while (out.length < max) {
+		const start = rest.indexOf(open);
+		if (start < 0) break;
+		const after = rest.slice(start + open.length);
+		const end = after.indexOf(close);
+		if (end < 0) break;
+		const body = after.slice(0, end).trim();
+		if (body) out.push(body);
+		rest = after.slice(end + close.length);
+	}
+	return out;
+}
+
+/** Remove protocol blocks for display. */
+export function stripProtocolTags(text: string): string {
+	let out = text;
+	for (const tag of ["loop-state", "inbox"]) {
+		const re = new RegExp(`<${tag}>[\\s\\S]*?</${tag}>`, "g");
+		out = out.replace(re, "");
+	}
+	return out
+		.split("\n")
+		.map((l) => l.trimEnd())
+		.filter((l, i, arr) => !(l.trim() === "" && (i === 0 || arr[i - 1].trim() === "")))
+		.join("\n")
+		.trim();
+}
+
+/**
+ * The job's own text out of a composed loop prompt: what sits between the state block and the
+ * protocol block (`composeLoopPrompt`). A prompt this does not recognise is returned whole, which is
+ * what a display wants — a prompt from somewhere else is still the best thing to show.
+ */
+export function jobTextOf(prompt: string): string {
+	return prompt.split(LOOP_STATE_CLOSE).pop()?.split(OUTPUT_PROTOCOL_HEADING)[0] ?? prompt;
+}
+
+/* ---------------------------------------------------------- maker/checker */
+
+export const CHECKER_MARKER = "You are the checker for a recurring loop";
+
+/**
+ * A second sub-agent adversarially
+ * reviews the maker's findings before they reach the inbox. Plain-text protocol again:
+ * one <verdict n="i">keep|drop</verdict> per finding, reason inside the tag body after
+ * the verdict word; a <rewrite n="i">…</rewrite> may replace the finding's text.
+ */
+export function composeCheckerPrompt(action: string, makerState: string | undefined, findings: string[], meta?: { name?: string }): string {
+	const list = findings.map((f, i) => `${i + 1}. ${f}`).join("\n");
+	return [
+		`${CHECKER_MARKER}${meta?.name ? ` "${meta.name}"` : ""}. A separate agent (the maker) just ran this loop and reported the findings below. Your job is adversarial: assume each finding may be wrong, stale, duplicated, trivial, or unsupported, and verify it independently with the tools available (read files, run commands, query APIs) before you decide. Do not trust the maker's notes as evidence.`,
+		"",
+		"[loop-goal]",
+		action.trim(),
+		"[/loop-goal]",
+		"",
+		"[maker-notes]",
+		makerState?.trim() || FIRST_RUN_MARKER,
+		"[/maker-notes]",
+		"",
+		"[findings]",
+		list,
+		"[/findings]",
+		"",
+		OUTPUT_PROTOCOL_HEADING,
+		'- For EVERY numbered finding emit exactly one <verdict n="i">keep — reason</verdict> or <verdict n="i">drop — reason</verdict>. keep = a human should still act on it; drop = false, stale, duplicate, not actionable, or not worth attention.',
+		'- If a kept finding is imprecise, add <rewrite n="i">one corrected line</rewrite> to replace its text.',
+		"- Do not invent new findings. Do not emit <inbox> or <loop-state> tags.",
+		"- Keep everything after the last tool call short so the tags are not truncated.",
+	].join("\n");
+}
+
+export interface CheckerVerdict {
+	n: number;
+	verdict: "keep" | "drop";
+	reason: string;
+	rewrite?: string;
+}
+
+/** Verdicts by finding number (1-based). Findings without a verdict are absent from the map. */
+export function parseCheckerOutput(text: string): Map<number, CheckerVerdict> {
+	const out = new Map<number, CheckerVerdict>();
+	for (const m of text.matchAll(/<verdict\s+n="?(\d+)"?\s*>([\s\S]*?)<\/verdict>/g)) {
+		const n = Number(m[1]);
+		const body = m[2].trim();
+		const word = /^(keep|drop)\b/i.exec(body);
+		if (!n || !word) continue;
+		const reason = body
+			.slice(word[0].length)
+			.replace(/^[\s—:\-–]+/, "")
+			.replace(/\s+/g, " ")
+			.trim();
+		out.set(n, { n, verdict: word[1].toLowerCase() as "keep" | "drop", reason });
+	}
+	for (const m of text.matchAll(/<rewrite\s+n="?(\d+)"?\s*>([\s\S]*?)<\/rewrite>/g)) {
+		const v = out.get(Number(m[1]));
+		const body = m[2].replace(/\s+/g, " ").trim();
+		if (v && v.verdict === "keep" && body) v.rewrite = capChars(body, INBOX_TEXT_MAX_CHARS);
+	}
+	return out;
+}
+
+export interface ParsedRunOutput {
+	state?: string;
+	findings: string[];
+	droppedFindings: number;
+}
+
+export function parseRunOutput(text: string): ParsedRunOutput {
+	const stateRaw = extractTagBlock(text, "loop-state");
+	const all = extractTagAll(text, "inbox", MAX_INBOX_TAGS_SCANNED);
+	const findings = all.slice(0, INBOX_TAGS_PER_RUN).map((f) => capChars(f.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS));
+	return {
+		state: stateRaw === undefined ? undefined : capChars(stateRaw, LOOP_STATE_MAX_CHARS),
+		findings,
+		droppedFindings: Math.max(0, all.length - INBOX_TAGS_PER_RUN),
+	};
+}

package/src/redact.ts

@@ -0,0 +1,61 @@
+/**
+ * Secret redaction for anything that reaches a screen, a log or a gist.
+ *
+ * Loop prompts and sub-agent output routinely carry tokens ("check the API with key sk-…"), and
+ * what this project prints is read hours later by whoever opens the inbox or the audit. Every
+ * preview goes through here, so a token cannot be echoed back out of a place that outlives the run.
+ */
+const REDACTORS: Array<[string, RegExp]> = [
+	["openai_anthropic_key", /sk-[A-Za-z0-9_-]{20,}/g],
+	["aws_access_key", /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g],
+	["github_token", /\bgh[ousp]_[A-Za-z0-9]{30,}\b/g],
+	["github_fine_grained", /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g],
+	["slack_token", /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g],
+	["google_api_key", /\bAIza[0-9A-Za-z_-]{35}\b/g],
+	["bearer_token", /Bearer\s+[A-Za-z0-9._\-]{16,}/g],
+	// Browser login and loopback OAuth callback URLs carry auth state or one-time codes.
+	["login_url", /https?:\/\/[^\s]+\/login\?[^\s]+/g],
+	["callback_url", /http:\/\/127\.0\.0\.1:[0-9]+\/callback(?:\?[^\s]+)?/g],
+	["jwt", /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g],
+	["url_credentials", /(https?:\/\/)[^\s/:@]+:[^\s/@]+@/g],
+	["env_assignment", /\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY|APIKEY)[A-Z0-9_]*)=(['"]?)[^\s'"]{8,}\2/g],
+	// A whole transcript can be uploaded now (`/session-share`), so the net covers the shapes a secret takes
+	// in a file rather than only in a prompt: config and JSON pairs, PEM blocks, and the vendors
+	// whose keys use `_` where the older patterns expected `-`.
+	["stripe_key", /\b[sprk]k_(?:live|test)_[A-Za-z0-9]{16,}\b/g],
+	["private_key_block", /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g],
+	["keyed_value", /\b([A-Za-z0-9_.-]*(?:token|secret|password|passwd|api[_-]?key|apikey|credential)[A-Za-z0-9_.-]*)("|')?(\s*[:=]\s*)("|')?(?!\[REDACTED:)([^\s"',]{8,})\4?/gi],
+];
+
+export function redact(input: string): string {
+	let out = input;
+	for (const [label, re] of REDACTORS) {
+		re.lastIndex = 0;
+		out = out.replace(re, (match, ...groups) => {
+			if (label === "url_credentials") return `${groups[0]}[REDACTED:${label}]@`;
+			if (label === "env_assignment") return `${groups[0]}=[REDACTED:${label}]`;
+			// Keep the name, mask the value: "which key was it" is the useful half of the line.
+			if (label === "keyed_value") {
+				// The name, its closing quote and the separator are the reader's half of the line; only
+				// the value is replaced, so `"api_key": "…"` stays valid JSON and `X=…` stays a shell line.
+				const [name, nameQuote, separator, valueQuote] = groups as [string, string | undefined, string, string | undefined];
+				const q = valueQuote ?? "";
+				return `${name}${nameQuote ?? ""}${separator}${q}[REDACTED:${label}]${q}`;
+			}
+			return `[REDACTED:${label}]`;
+		});
+	}
+	return out;
+}
+
+/** Redacted and capped, but with the text's own line structure intact: capped, never reflowed. */
+export function capRedacted(input: string, maxChars: number): string {
+	const chars = Array.from(redact(input));
+	return chars.length > maxChars ? `${chars.slice(0, maxChars).join("")}…` : chars.join("");
+}
+
+/** Redacted, collapsed to one line and capped: for the one-line previews a TUI row shows. */
+export function previewRedacted(input: string, maxChars: number): string {
+	const chars = Array.from(redact(input).replace(/\s+/g, " ").trim());
+	return chars.length > maxChars ? `${chars.slice(0, maxChars).join("")}…` : chars.join("");
+}

package/src/register-pi.mjs

@@ -0,0 +1,3 @@
+// `node --import ./src/register-pi.mjs …` — resolve pi's packages outside pi's own loader.
+import { register } from "node:module";
+register("./pi-resolver.mjs", import.meta.url);

package/src/runner.ts

@@ -0,0 +1,149 @@
+/**
+ * Sub-agent runs. A run is a fresh conversation (no parent history)
+ * with the parent's tools, model and skills, executed by a `SubagentRunner`. The production
+ * runner (`sdk-runner.ts`) opens the conversation *inside the interactive pi process* through
+ * pi's SDK, in-process, so the parent's live MCP servers, `-e`
+ * extensions and system prompt are shared. Tests inject a fake runner.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface RunnerUsage {
+	input: number;
+	output: number;
+	/** Cached prompt tokens (pi bills them differently from `input`); optional — a fake runner may omit them. */
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost: number;
+	turns: number;
+}
+
+export interface RunnerResult {
+	ok: boolean;
+	timedOut: boolean;
+	/** Final assistant text (last assistant message with text content). */
+	text: string;
+	errorMessage?: string;
+	stopReason?: string;
+	/**
+	 * The run finished, but not as configured — a pinned model that no longer resolves, say. Kept
+	 * apart from `errorMessage` so a self-healed run is not reported as a failure.
+	 */
+	warning?: string;
+	model?: string;
+	/** What the run had to do to get through: silent provider retries and context compactions. */
+	retries?: number;
+	compactions?: number;
+	usage: RunnerUsage;
+	sessionId?: string;
+	/** Transcript file when `sessionDir` was given. */
+	sessionFile?: string;
+	/** Kept for run records: 0 on success, 1 on failure (there is no child process any more). */
+	exitCode?: number;
+}
+
+export interface SubagentRequest {
+	cwd: string;
+	prompt: string;
+	/** "provider/id"; undefined → the interactive session's current model. */
+	model?: string;
+	thinking?: string;
+	/** Allowlist of tool names (built-in, MCP and automation tools alike). */
+	tools?: string[];
+	/**
+	 * Called once the sub-session's transcript file exists, so a run in flight can be inspected
+	 * while it is still going (`/cron trace <job> live`) rather than only after it finishes.
+	 */
+	onSessionFile?: (file: string) => void;
+	timeoutMs: number;
+	signal?: AbortSignal;
+	/** Keep the transcript here (a pi session file); omit for an in-memory run. */
+	sessionDir?: string;
+	/** Trigger hop: 1 for a sub-agent of the interactive pi, for cycle suppression. */
+	hop: number;
+	/** The interactive session this run acts for; plain cron jobs it schedules bind to it. */
+	parentSessionId?: string;
+	parentCwd?: string;
+	kind: "loop" | "checker" | "trigger";
+	jobId?: string;
+	runId?: string;
+	traceId?: string;
+}
+
+export type SubagentRunner = (req: SubagentRequest) => Promise<RunnerResult>;
+
+export function failedRun(message: string, extra: Partial<RunnerResult> = {}): RunnerResult {
+	return { ok: false, exitCode: 1, timedOut: false, text: "", errorMessage: message, usage: { input: 0, output: 0, cost: 0, turns: 0 }, ...extra };
+}
+
+/* ------------------------------------------- the parent's runtime shape */
+
+/** What the interactive pi was started with that a sub-agent should share. */
+export interface ParentRuntimeFlags {
+	extensionPaths: string[];
+	skillPaths: string[];
+	promptTemplatePaths: string[];
+	appendSystemPrompt: string[];
+	systemPrompt?: string;
+	noSkills: boolean;
+	noExtensions: boolean;
+	noContextFiles: boolean;
+	noPromptTemplates: boolean;
+}
+
+/**
+ * A sub-agent may run in another project's cwd, and pi resolves `-e ./ext.ts` against its cwd
+ * and loads explicit `-e` paths regardless of trust — so a relative path is pinned to the
+ * parent's cwd here, or a same-named file in an untrusted project would be executed. Package
+ * specs (`npm:…`, `git:…`, bare names) are left alone.
+ */
+export function absolutizeFlagValue(value: string, parentCwd: string): string {
+	if (/^(npm|git|https?|file):/.test(value)) return value;
+	if (value.startsWith("~/")) return path.join(process.env.HOME ?? "", value.slice(2));
+	if (value.startsWith("./") || value.startsWith("../") || value.includes("/") || value === "." || value === "..") return path.resolve(parentCwd, value);
+	if (fs.existsSync(path.resolve(parentCwd, value))) return path.resolve(parentCwd, value);
+	return value;
+}
+
+/** Parse the parent pi's argv for the flags a sub-agent inherits. Secrets, identity, mode and tool selection stay with the job. */
+export function parentRuntimeFlags(argv: string[], parentCwd = process.cwd()): ParentRuntimeFlags {
+	const out: ParentRuntimeFlags = { extensionPaths: [], skillPaths: [], promptTemplatePaths: [], appendSystemPrompt: [], noSkills: false, noExtensions: false, noContextFiles: false, noPromptTemplates: false };
+	const valued = new Set(["-e", "--extension", "--skill", "--prompt-template", "--append-system-prompt", "--system-prompt"]);
+	const skipValued = new Set(["--api-key", "--provider", "--model", "--thinking", "--session", "--session-id", "--session-dir", "--fork", "--name", "-n", "--models", "--tools", "-t", "--exclude-tools", "-xt", "--mode", "--export", "--list-models", "--tui-mode", "--use-theme", "--theme", "--trigger-poll-secs"]);
+	const take = (flag: string, value: string) => {
+		switch (flag) {
+			case "-e":
+			case "--extension":
+				out.extensionPaths.push(absolutizeFlagValue(value, parentCwd));
+				break;
+			case "--skill":
+				out.skillPaths.push(absolutizeFlagValue(value, parentCwd));
+				break;
+			case "--prompt-template":
+				out.promptTemplatePaths.push(absolutizeFlagValue(value, parentCwd));
+				break;
+			case "--append-system-prompt":
+				out.appendSystemPrompt.push(value);
+				break;
+			case "--system-prompt":
+				out.systemPrompt = value;
+				break;
+		}
+	};
+	for (let i = 2; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--") break;
+		if (valued.has(a)) {
+			if (i + 1 < argv.length) take(a, argv[++i]);
+		} else if (a === "--no-skills" || a === "-ns") out.noSkills = true;
+		else if (a === "--no-extensions" || a === "-ne") out.noExtensions = true;
+		else if (a === "--no-context-files" || a === "-nc") out.noContextFiles = true;
+		else if (a === "--no-prompt-templates" || a === "-np") out.noPromptTemplates = true;
+		else if (skipValued.has(a)) i++;
+		else if (a.startsWith("--") && a.includes("=")) {
+			const [k, v] = a.split(/=(.*)/s);
+			if (valued.has(k)) take(k, v);
+		}
+	}
+	return out;
+}