@alphacoder-v0/pi-loops 0.22.8 → 0.24.0

package/src/pi-resolver.d.mts

@@ -0,0 +1 @@
+export function piPackage(): string;

package/src/pi-resolver.mjs

@@ -1,20 +1,99 @@
 // 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.
+// PI_LOOPS_PI_PACKAGE names pi's package dir; else pi's managed install (the `pi` on PATH, then the
+// agent directory's); else the one beside this Node; else the global npm install.
 import { execSync } from "node:child_process";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 
+const PI_SCOPE = path.join("@earendil-works", "pi-coding-agent");
+const hasPi = (dir) => fs.existsSync(path.join(dir, "package.json"));
+
+/**
+ * pi's managed install under `agentDir`: `install/current-version` names a release, and the release
+ * holds pi under `install/releases/<version>/node_modules`. Undefined when the version file is not
+ * there or not a plain version, or when that release has no pi in it.
+ */
+function managedPi(agentDir) {
+	let version;
+	try {
+		version = fs.readFileSync(path.join(agentDir, "install", "current-version"), "utf8").trim();
+	} catch {
+		return undefined; // not a managed install
+	}
+	// The same check pi's own launcher (`<agentDir>/bin/pi`) makes before it trusts the file.
+	if (!/^[0-9A-Za-z._+-]+$/.test(version) || version === "." || version === "..") return undefined;
+	const dir = path.join(agentDir, "install", "releases", version, "node_modules", PI_SCOPE);
+	return hasPi(dir) ? dir : undefined;
+}
+
+/** The first `pi` on `pathEnv`, with every link followed; undefined when there is none. */
+function piOnPath(pathEnv) {
+	for (const entry of (pathEnv ?? "").split(path.delimiter)) {
+		if (!entry) continue;
+		try {
+			const real = fs.realpathSync(path.join(entry, "pi"));
+			if (fs.statSync(real).isFile()) return real;
+		} catch {
+			/* no pi in this directory */
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Where pi's package is, and every place looked at on the way. Pure apart from reading the disk:
+ * the environment (which `npm root -g` runs in too), this Node's path and the `npm root -g` question
+ * are passed in.
+ */
+export function findPiPackage({ env = process.env, execPath = process.execPath, npmRoot = () => execSync("npm root -g", { encoding: "utf8", env, stdio: ["ignore", "pipe", "ignore"] }).trim() } = {}) {
+	const looked = [];
+	const told = env.PI_LOOPS_PI_PACKAGE;
+	if (told) {
+		if (hasPi(told)) return { dir: told, looked };
+		looked.push(`${told} (PI_LOOPS_PI_PACKAGE)`);
+	}
+	// A managed install: `pi` on PATH links to `<agentDir>/bin/pi`, a launcher beside `install/`.
+	const onPath = piOnPath(env.PATH);
+	if (onPath && path.basename(onPath) === "pi" && path.basename(path.dirname(onPath)) === "bin") {
+		const root = path.dirname(path.dirname(onPath));
+		const found = managedPi(root);
+		if (found) return { dir: found, looked };
+		looked.push(`${path.join(root, "install")} (the pi on PATH, ${onPath})`);
+	}
+	const home = env.HOME || os.homedir();
+	const agentDir = env.PI_CODING_AGENT_DIR ? env.PI_CODING_AGENT_DIR.replace(/^~(?=$|\/)/, home) : path.join(home, ".pi", "agent");
+	const managed = managedPi(agentDir);
+	if (managed) return { dir: managed, looked };
+	looked.push(path.join(agentDir, "install"));
+	const beside = path.join(path.dirname(path.dirname(execPath)), "lib", "node_modules", PI_SCOPE);
+	if (hasPi(beside)) return { dir: beside, looked };
+	looked.push(beside);
+	// The last resort, and the one that can fail on its own: no npm on PATH.
+	try {
+		const global = path.join(npmRoot(), PI_SCOPE);
+		if (hasPi(global)) return { dir: global, looked };
+		looked.push(`${global} (npm root -g)`);
+	} catch {
+		looked.push("npm root -g (npm did not answer)");
+	}
+	return { dir: undefined, looked };
+}
+
+/** The one error for no pi anywhere: every place `findPiPackage` looked at, and the way out. */
+export function noPiError(looked) {
+	return new Error(`no pi package found; looked in ${looked.join(", ")}. Set PI_LOOPS_PI_PACKAGE to the directory of your @earendil-works/pi-coding-agent install`);
+}
+
 let pkg;
-/** pi's package directory: what was told, else the one beside this Node, else the global install. */
+/** pi's package directory (see `findPiPackage`), or an error that names every place looked at. */
 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"));
+	const { dir, looked } = findPiPackage();
+	if (!dir) throw noPiError(looked);
+	return (pkg = dir);
 }
 // Relative to pi's package directory.
 const MAP = {
@@ -24,6 +103,28 @@ const MAP = {
 	"@earendil-works/pi-tui": "node_modules/@earendil-works/pi-tui/dist/index.js",
 	typebox: "node_modules/typebox/build/index.mjs",
 };
+/**
+ * Where one of pi's packages is: nested under pi's own node_modules (npm's layout for a global pi),
+ * else beside pi (a hoisted install, or pnpm's store, where pi's real directory sits among its
+ * dependencies). Only the nested place was looked at, and anywhere else the background process —
+ * which every loop now runs in — could not start.
+ */
+function piFile(rel) {
+	const dir = piPackage();
+	const nested = path.join(dir, rel);
+	if (!rel.startsWith("node_modules/") || fs.existsSync(nested)) return nested;
+	let real = dir;
+	try {
+		real = fs.realpathSync(dir);
+	} catch {
+		/* not there: the nested path is as good an answer */
+	}
+	// Only where Node itself would look: the node_modules that holds pi's scope directory.
+	const root = path.dirname(path.dirname(real));
+	if (path.basename(root) !== "node_modules") return nested;
+	const beside = path.join(root, rel.slice("node_modules/".length));
+	return fs.existsSync(beside) ? beside : nested;
+}
 /**
  * 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`
@@ -31,10 +132,9 @@ const MAP = {
  * 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);
+		const file = piFile(rel);
 		if (fs.existsSync(file)) out[specifier] = file;
 	}
 	return out;
@@ -42,7 +142,7 @@ export function piAliases() {
 export async function resolve(specifier, context, next) {
 	const rel = MAP[specifier];
 	if (rel) {
-		const file = path.join(piPackage(), rel);
+		const file = piFile(rel);
 		if (fs.existsSync(file)) return { url: pathToFileURL(file).href, shortCircuit: true };
 	}
 	return next(specifier, context);

package/src/presence.ts

@@ -1,19 +1,14 @@
 /**
- * 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).
+ * Presence: the one file per live pi that pi-loops 0.22 windows write under `<dir>/presence/`
+ * (refreshed every tick, pruned after 90 s or a dead pid). This build no longer writes it: who
+ * holds a conversation is the lease's question (src/lease.ts). It is still read during an upgrade,
+ * to see a conversation a 0.22 window has open (`olderPiOnSession`), and so the host's dead-session
+ * sweep does not park a plain job whose session is open only there. Deleted with the 0.22 bridge.
  */
 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 { withinProject } from "./paths.ts";
 import { stamp } from "./schedule.ts";
 
 export const PRESENCE_STALE_MS = 90_000;
@@ -29,6 +24,8 @@ export interface PresenceEntry {
 	cwd: string;
 	/** "host" = the headless process that keeps the clock while no interactive pi is open. */
 	kind?: PresenceKind;
+	/** Written by builds that take a session lease (src/lease.ts). Its absence marks a 0.22.x pi, which fires a shared session's plain jobs without one. */
+	leases?: true;
 	heartbeatAt: string;
 }
 
@@ -89,60 +86,12 @@ export class PresenceRegistry {
 	}
 }
 
-/** 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);
-}
-
-/** A worktree, a symlinked path or a subdirectory is the same project, as the runtime treats it. */
-export function sameProject(a: string, b: string): boolean {
-	return withinProject(b, a) || withinProject(a, b);
-}
-
-/**
- * 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);
+/** A live pi without session leases that has `sessionId` open too: both would fire its plain jobs. */
+export function olderPiOnSession(entries: PresenceEntry[], sessionId: string | undefined, self: PresenceSelf): PresenceEntry | undefined {
+	if (!sessionId) return undefined;
+	return entries.find((e) => e.sessionId === sessionId && !e.leases && e.kind !== "host" && !isSelf(e, self));
 }
 
 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

@@ -52,6 +52,15 @@ export function capChars(text: string, max: number): string {
 	return `${chars.slice(0, max).join("")}…`;
 }
 
+/**
+ * A person's reason and a finding's text go inside the `[dismissed]` block as data. Written as they
+ * are, a `[/dismissed]` in either would end the block early and put the rest of the line where the
+ * run reads its task; spaced, it reads the same to a person and closes nothing.
+ */
+function unclosing(text: string): string {
+	return text.replace(/\[\/(\s*)dismissed\]/gi, "[/ dismissed]");
+}
+
 export function composeLoopPrompt(action: string, previousState: string | undefined, meta?: { name?: string; runAt?: string; dismissed?: DismissedFeedback[] }): string {
 	const state = previousState && previousState.trim() ? capChars(previousState, LOOP_STATE_MAX_CHARS) : FIRST_RUN_MARKER;
 	/**
@@ -64,7 +73,7 @@ export function composeLoopPrompt(action: string, previousState: string | undefi
 	const feedback = dismissed.length
 		? [
 				`${DISMISSED_OPEN} (findings of yours a person dismissed since your previous run, and why — do not report these again unless what they describe has changed; put what you need to remember that in your notes)`,
-				...dismissed.map((d) => `- "${capChars(d.text.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS)}" — ${capChars(d.reason.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS)}`),
+				...dismissed.map((d) => `- "${unclosing(capChars(d.text.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS))}" — ${unclosing(capChars(d.reason.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS))}`),
 				DISMISSED_CLOSE,
 				"",
 			]

package/src/recipe.ts

@@ -40,6 +40,8 @@ export interface RecipeJob {
 export interface RecipeManifest {
 	name: string;
 	summary: string;
+	/** One sentence of at most twelve words: what the loop does, as a starter card shows it. */
+	line?: string;
 	needsTracker: boolean;
 	levels: AutonomyLevel[];
 	/**
@@ -92,6 +94,45 @@ export type PreflightCheck = (typeof PREFLIGHT_CHECKS)[number];
 
 export const RECIPE_TIERS = ["starter", "advanced"] as const;
 export type RecipeTier = (typeof RECIPE_TIERS)[number];
+/**
+ * Who owns the loops an install creates. pi writes a conversation's session file only once it holds
+ * a user or assistant message, and `/recipe add` is neither (a starter's Add in a new page
+ * conversation is the usual case): a loop named after that conversation would name one that never
+ * exists. Such an install's loops belong to the project instead, with no creating conversation.
+ */
+export function installScope(sessionFile: string | undefined, exists: (p: string) => boolean = fs.existsSync): { projectOwned?: true } {
+	return sessionFile && exists(sessionFile) ? {} : { projectOwned: true };
+}
+
+/** The order an empty project is offered the starters in; one not named here comes after, by name. */
+export const STARTER_ORDER = ["daily-digest", "pr-watch", "changelog-draft"] as const;
+/** How many starters an empty project is offered. */
+export const STARTERS_SHOWN = 3;
+
+/** A starter as the page offers it: `Add` installs it with `--level report`, so it reads only. */
+export interface Starter {
+	name: string;
+	summary: string;
+	/** The card's one line: the manifest's `line`, or its summary when it has none. */
+	line: string;
+	readsOnly: boolean;
+	needsTracker: boolean;
+	budgetHintUsd?: number;
+}
+
+/** The starters an empty project is offered: `starter` recipes that have a `report` level, in `STARTER_ORDER`. */
+export function starters(recipes: readonly Recipe[]): Starter[] {
+	const rank = (name: string) => {
+		const at = (STARTER_ORDER as readonly string[]).indexOf(name);
+		return at < 0 ? STARTER_ORDER.length : at;
+	};
+	return recipes
+		.map((r) => r.manifest)
+		.filter((m) => m.tier === "starter" && m.levels.includes("report"))
+		.sort((a, b) => rank(a.name) - rank(b.name) || a.name.localeCompare(b.name))
+		.slice(0, STARTERS_SHOWN)
+		.map((m) => ({ name: m.name, summary: m.summary, line: m.line ?? m.summary, readsOnly: true, needsTracker: m.needsTracker, ...(m.budgetHintUsd !== undefined ? { budgetHintUsd: m.budgetHintUsd } : {}) }));
+}
 
 export const MANIFEST_FILE = "recipe.toml";
 export const RECORD_FILE = ".recipe.json";
@@ -165,6 +206,7 @@ export function parseManifest(text: string, opts: { now?: number } = {}): Recipe
 	const name = requireStr(doc, "name", where);
 	if (!NAME_RE.test(name)) throw new Error(`${where}: name must be lowercase letters, digits and dashes (got "${name}")`);
 	const summary = requireStr(doc, "summary", where);
+	const line = str(doc, "line", where);
 	const levelsRaw = strList(doc, "levels", where);
 	if (!levelsRaw?.length) throw new Error(`${where}: levels must list at least one of ${AUTONOMY_LEVELS.join(", ")}`);
 	const levels: AutonomyLevel[] = [];
@@ -227,7 +269,7 @@ export function parseManifest(text: string, opts: { now?: number } = {}): Recipe
 		}
 		jobs.push(job);
 	}
-	return { name, summary, needsTracker: bool(doc, "needs_tracker", where) ?? false, levels, tier: tierRaw as RecipeTier, usefulWhen, needs, needsPropose, setup, files, budgetHintUsd: budget as number | undefined, jobs };
+	return { name, summary, line, needsTracker: bool(doc, "needs_tracker", where) ?? false, levels, tier: tierRaw as RecipeTier, usefulWhen, needs, needsPropose, setup, files, budgetHintUsd: budget as number | undefined, jobs };
 }
 
 /** Relative, inside the directory, and a single file: no `..`, no absolute path, no trailing slash. */