@aeondave/pi-persona 1.15.2

package/src/core/nudge.ts

@@ -0,0 +1,238 @@
+/**
+ * DelegationNudge — a pure state machine that watches the supervisor's OWN tool-result stream
+ * and, when hands-on work burns too much context without a hand-off, returns a short reminder to
+ * append to the offending tool's result. This is the runtime reinforcement the static persona
+ * prompt cannot give: the persona directive sits at the TOP of the context and its behavioral pull
+ * decays as recent tool output balloons ("delegate the breadth" loses the tug-of-war against 50
+ * commands of momentum). The nudge lands in RECENT context — on the very command that triggered
+ * it — where a decaying system-prompt line has no force.
+ *
+ * The trigger is REPETITION, not raw volume. The antipattern the persona warns against is "chaining
+ * sweeps by hand" — a RUN of substantive hands-on commands with no hand-off (a dirbust/spray/enum
+ * loop). Output volume alone is a poor proxy: a single big file read is high-volume but a legitimate
+ * one-shot that belongs to reading-budget-discipline (grep-first), not delegation. So the primary
+ * trigger counts consecutive SUBSTANTIVE hands-on tool calls since the last hand-off — a tiny call
+ * (echo/cd/one-line check) is orchestration glue and does not advance the run; a run reaching the
+ * threshold is a by-hand sweep. Tool identity is not required (a real sweep mixes read/grep/curl). A
+ * high single-command threshold stays as a SECONDARY trigger for a genuinely enormous one-shot dump
+ * (a sign it should have been detached/quarantined). A hand-off (delegate/council) resets the run;
+ * nothing else does.
+ *
+ * Backoff: repeating the identical reminder is noise once the operator has seen it and kept going —
+ * often because the work is session-bound and cannot be delegated at all (a live shell / tunnel a
+ * sub-agent can't inherit; from the supervisor side that loop is indistinguishable from a delegable
+ * sweep, so no signal can separate them). Each un-actioned nudge WIDENS the next run window (n× the
+ * base): the reminder lands early, then de-escalates. Pure — no I/O, fully unit-testable.
+ */
+
+/** Tools that mean "the operator handed work off" — they end (reset) a by-hand run. */
+const HANDOFF_TOOLS = new Set(["delegate", "council"]);
+/** Supervision glue: collecting a delegated result (`intercom wait`/`result`) or arming a
+ *  `timer` is neither hands-on work nor a hand-off. Their payloads are large by nature, so
+ *  counting them would punish the exact behavior the nudge exists to encourage. They neither
+ *  advance nor reset the run, and never nudge. */
+const GLUE_TOOLS = new Set(["intercom", "timer"]);
+/** Mutation tools often return only a terse acknowledgement. Their output size is not a useful
+ * proxy for the amount of direct coding work, so every call counts as substantive. */
+const MUTATING_TOOLS = new Set(["edit", "write", "apply_patch"]);
+
+/** Stable, fixed-size identity for an untrusted failed tool result. The input is streamed through
+ * the hash and never retained in the nudge state; the stored key is only the length + 32-bit digest. */
+function fingerprintFailure(text: string): string {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < text.length; i++) {
+		hash ^= text.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return `${text.length}:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+export interface NudgeThresholds {
+	/** A single result at/above this many chars is a fat one-shot dump — nudge on its own. Kept
+	 *  high so a normal large file read doesn't trip it; only a linpeas/ffuf-scale dump does. */
+	singleHeavyChars: number;
+	/** A run of this many consecutive SUBSTANTIVE hands-on commands (no hand-off) is a by-hand
+	 *  sweep — the primary trigger. Counts steps, not bytes, so one big read never trips it. */
+	runLength: number;
+	/** A command whose output is below this many chars is orchestration glue (echo/cd/one-line
+	 *  check), not a sweep step: it does not advance the run counter. */
+	minStepChars: number;
+	/** Minimum cumulative burn (chars since last hand-off) before a sweep run can fire. Without
+	 *  this, 5 tiny git/grep commands (200 chars each = 1000 total ≈ 0k tokens) trip the nudge
+	 *  and renderNudge prints "~0k tokens" — advice to "delegate what burns context" when nothing
+	 *  burned. This floor gates the sweep so it only fires when the burn is substantive.
+	 *  Defaults to `DEFAULT_NUDGE_THRESHOLDS.minSweepBurnChars` when omitted. */
+	minSweepBurnChars?: number;
+	/** Number of identical consecutive failed hand-off reminders to suppress before repeating one. */
+	failedHandoffBackoff?: number;
+}
+
+export const DEFAULT_NUDGE_THRESHOLDS: NudgeThresholds = {
+	singleHeavyChars: 40_000, // ~10k tokens in one command — a fat one-shot dump
+	runLength: 5, // 5 substantive hands-on commands in a row without a hand-off = a by-hand sweep.
+	// The standing delegation brief (core/brief.ts) carries the default every turn; this is the
+	// reactive backstop for the supervisor who grinds a sweep through it anyway.
+	minStepChars: 200, // below this a command is glue, not a sweep step
+	minSweepBurnChars: 8_000, // ~2k tokens cumulative — below this the sweep is cheap triage, not a grind
+	failedHandoffBackoff: 1, // suppress one identical immediate repair reminder; the failure remains visible
+};
+
+/** chars → ~thousands of tokens (≈4 chars/token), for the human-facing nudge text. */
+const toK = (chars: number): number => Math.round(chars / 4 / 1000);
+
+/**
+ * Keep runtime reinforcement structured for both its semantic tool-result copy and the dedicated
+ * TUI card. It is never moved to a hidden-only context channel; expanding either surface reveals
+ * the same labelled checkpoint.
+ */
+function renderVisibleCheckpoint(title: string, lines: readonly string[]): string {
+	return [`⟢ pi-persona · ${title}`, ...lines.map((line) => `  ${line}`)].join("\n");
+}
+
+/**
+ * Honest lead: name what actually tripped the nudge. A single fat dump blames THAT command; a
+ * cumulative streak names the accumulated burn (never the tiny command that merely crossed the
+ * line — printing its ~0k size looked like the nudge fired on nothing). The tail acknowledges that
+ * not all burn is delegable: work bound to one interactive session a sub-agent can't inherit
+ * (a live shell, a specific tunnel) stays with you — then the fix is to keep it lean, not to hand off.
+ */
+function renderNudge(reason: "dump" | "sweep", run: number, burn: number, size: number): string {
+	const signal =
+		reason === "dump"
+			? [`Trigger: one direct tool result · ~${toK(size)}k estimated output tokens.`, `Scope: ~${toK(burn)}k in the current direct-work streak.`]
+			: [`Trigger: ${run} substantive direct tool calls · ~${toK(burn)}k estimated output tokens.`, "Scope: since the last successful hand-off."];
+	return renderVisibleCheckpoint("delegation checkpoint", [
+		...signal,
+		"Action: delegate independent work; repair weak hand-offs, then re-dispatch.",
+		"Keep local: session-bound work; keep it lean and grep-first.",
+	]);
+}
+
+export class DelegationNudge {
+	private run = 0; // consecutive SUBSTANTIVE hands-on calls since the last hand-off
+	private burn = 0; // cumulative output chars since the last hand-off (for the message only)
+	private lastNudgeRun = 0; // run length at which we last nudged (the re-arm baseline)
+	private nudges = 0; // cumulative nudges fired since the last hand-off (drives backoff)
+	private failedHandoffKey: string | undefined;
+	private failedHandoffRepeats = 0;
+	private readonly t: NudgeThresholds;
+
+	constructor(thresholds: NudgeThresholds = DEFAULT_NUDGE_THRESHOLDS) {
+		this.t = thresholds;
+	}
+
+	/** Clear the run — call on a new session or persona switch. */
+	reset(): void {
+		this.run = 0;
+		this.burn = 0;
+		this.lastNudgeRun = 0;
+		this.nudges = 0;
+		this.failedHandoffKey = undefined;
+		this.failedHandoffRepeats = 0;
+	}
+
+	/**
+	 * Feed one supervisor tool result: its tool name, output length, and optionally its text identity.
+	 * The text is fingerprinted immediately and never retained. Returns the reminder text to append to
+	 * that result, or undefined to leave the result untouched.
+	 */
+	observe(toolName: string, size: number, handoffSucceeded = true, failureText?: string): string | undefined {
+		if (GLUE_TOOLS.has(toolName)) return undefined;
+		if (HANDOFF_TOOLS.has(toolName)) {
+			if (!handoffSucceeded) {
+				const normalizedSize = Math.max(0, Math.floor(size));
+				const identity = failureText === undefined ? `size:${normalizedSize}` : fingerprintFailure(failureText);
+				const key = `${toolName}:${identity}`;
+				if (key === this.failedHandoffKey) {
+					this.failedHandoffRepeats += 1;
+					const suppress = Math.max(0, Math.floor(this.t.failedHandoffBackoff ?? DEFAULT_NUDGE_THRESHOLDS.failedHandoffBackoff ?? 0));
+					if (this.failedHandoffRepeats <= suppress) return undefined;
+					this.failedHandoffRepeats = 0;
+				} else {
+					this.failedHandoffKey = key;
+					this.failedHandoffRepeats = 0;
+				}
+				return renderVisibleCheckpoint("hand-off repair", [
+					"Trigger: hand-off failed before useful work landed; direct-work streak remains active.",
+					"Action: fix agent/model/brief/tool grant, then re-dispatch.",
+				]);
+			}
+			// The operator delegated successfully — the by-hand run is over; the hand-off itself never nudges.
+			this.reset();
+			return undefined;
+		}
+		// A failed hand-off is only deduplicated when the next event is another failed hand-off;
+		// direct work starts a fresh repair sequence.
+		this.failedHandoffKey = undefined;
+		this.failedHandoffRepeats = 0;
+		const step = Math.max(0, size);
+		this.burn += step;
+		// Only a substantive step advances the run; a trivial call is orchestration glue, not a sweep
+		// step (it neither advances nor resets the run — a stray echo mid-sweep doesn't break it).
+		if (MUTATING_TOOLS.has(toolName) || step >= this.t.minStepChars) this.run += 1;
+		// Backoff: each un-actioned nudge widens the next run window, so a long non-delegable
+		// session-bound loop is reminded ONCE then left alone; a real runaway grind still trips the
+		// widened window; a hand-off resets it. The dump trigger gets the same de-escalation —
+		// repeated fat one-shots (a legit review loop) must not re-fire the identical reminder on
+		// every result: after the first dump nudge, a full base window of further work must pass.
+		const window = this.t.runLength * (this.nudges + 1);
+		const dumpReady = this.nudges === 0 || this.run - this.lastNudgeRun >= this.t.runLength * this.nudges;
+		const single = size >= this.t.singleHeavyChars && dumpReady;
+		const burnFloor = this.t.minSweepBurnChars ?? DEFAULT_NUDGE_THRESHOLDS.minSweepBurnChars ?? 0;
+		const sweep = this.run - this.lastNudgeRun >= window && this.burn >= burnFloor;
+		if (!single && !sweep) return undefined;
+		this.lastNudgeRun = this.run;
+		this.nudges += 1;
+		return renderNudge(sweep ? "sweep" : "dump", this.run, this.burn, size);
+	}
+}
+
+/**
+ * PersistenceNudge — the counterweight to premature surrender. Where {@link DelegationNudge} fires
+ * when the supervisor grinds work BY HAND, this fires when a delegated leg comes back having GIVEN
+ * UP: the child's report carries an explicit surrender/blocked marker. It returns a reminder to
+ * append to that very result — in RECENT context, on the leg that just landed — that a delegating
+ * supervisor must not bank a premature block: confirm it names a genuine missing capability, else
+ * steer it back with the recovery pass or re-dispatch. This is the runtime half of the operator
+ * protocol's "reject premature surrender" rule; the top-of-prompt persona directive has decayed by
+ * the time a blocked leg returns.
+ *
+ * Keyed on the ecosystem's OWN explicit protocol tokens (an operator emits `[BLOCKED: need X]`, a CTF
+ * leg emits `FLAG: UNKNOWN`) — never a fuzzy "sounds stuck" guess, so it does not misfire on ordinary
+ * prose. It inspects only `delegate`/`council` results (a child's report); the supervisor's own tools
+ * are DelegationNudge's job, so the two never fire on the same event. Pure — no I/O, unit-testable.
+ */
+
+/** Tools whose result is a delegated child's report (where a surrender can surface). */
+const REPORT_TOOLS = new Set(["delegate", "council"]);
+
+/** Explicit surrender/blocked markers the operator + CTF protocols emit (operator.md). */
+const SURRENDER_MARKERS: readonly RegExp[] = [/\[BLOCKED\b/i, /\bFLAG:\s*UNKNOWN\b/i];
+
+const PERSISTENCE_NOTE = renderVisibleCheckpoint("delegated result needs verification", [
+	"Trigger: a delegated leg returned BLOCKED/UNKNOWN.",
+	"Verify: accept only concrete external blockers (access, credentials, or tools).",
+	"Otherwise: run the recovery pass or re-dispatch with a sharper brief.",
+]);
+
+export class PersistenceNudge {
+	/**
+	 * Feed one supervisor tool result: its tool name and the full text of the result. Returns the
+	 * reminder to append when a delegated leg's report signals premature surrender, else undefined.
+	 * The SYNC path (a `delegate`/`council` tool_result the supervisor sees inline).
+	 */
+	observe(toolName: string, text: string): string | undefined {
+		if (!REPORT_TOOLS.has(toolName)) return undefined;
+		return this.scan(text);
+	}
+
+	/**
+	 * Tool-agnostic surrender check on already-known-to-be-a-leg-report text. The ASYNC path uses
+	 * this: a background run (the interactive default) delivers its report through the completion
+	 * notifier as a fresh follow-up, NOT a `delegate` tool_result, so {@link observe}'s tool gate
+	 * would never see it — the caller has already established the text is a settled leg's output.
+	 */
+	scan(text: string): string | undefined {
+		return SURRENDER_MARKERS.some((re) => re.test(text)) ? PERSISTENCE_NOTE : undefined;
+	}
+}

package/src/core/ownership.ts

@@ -0,0 +1,102 @@
+/** Shared write-set overlap — used by delegate and the exocom work ledger. Pure. */
+import { posix, win32 } from "node:path";
+
+export interface WriteSetOwner {
+	agent?: string;
+	writeSet?: string[];
+}
+
+interface NormalizedWritePath {
+	value: string;
+	windows: boolean;
+}
+
+export function normalizeWritePath(raw: string): NormalizedWritePath {
+	const trimmed = raw.trim();
+	// Case-folding is decided PER PATH by its syntax, never by the host platform: a plan is
+	// authored on one OS and may execute on another, so the overlap answer must not change
+	// with the machine. Backslashes, a drive letter, or a UNC prefix mark a Windows path
+	// (case-insensitive); plain slash-separated ownership names stay case-sensitive.
+	const windows = trimmed.includes("\\") || /^[A-Za-z]:[\\/]/.test(trimmed) || trimmed.startsWith("\\\\");
+	const normalized = (windows ? win32.normalize(trimmed) : posix.normalize(trimmed)).replaceAll("\\", "/");
+	const value = normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+	return { value: windows ? value.toLowerCase() : value, windows };
+}
+
+export function pathsOverlap(a: NormalizedWritePath, b: NormalizedWritePath): boolean {
+	const left = a.windows || b.windows ? a.value.toLowerCase() : a.value;
+	const right = a.windows || b.windows ? b.value.toLowerCase() : b.value;
+	const isAncestor = (parent: string, child: string): boolean => {
+		if (parent === "/") return child.startsWith("/");
+		if (parent === ".") return !child.startsWith("/");
+		return child.startsWith(`${parent}/`);
+	};
+	return left === right || isAncestor(left, right) || isAncestor(right, left);
+}
+
+export interface WriteSetOverlap {
+	firstIndex: number;
+	secondIndex: number;
+	firstPath: string;
+	secondPath: string;
+}
+
+/** Find equal/ancestor-descendant write-set collisions in deterministic owner/path order. */
+export function findWriteSetOverlaps(tasks: readonly WriteSetOwner[]): WriteSetOverlap[] {
+	const overlaps: WriteSetOverlap[] = [];
+	for (let i = 0; i < tasks.length; i++) {
+		const first = tasks[i];
+		if (!first) continue;
+		for (let j = i + 1; j < tasks.length; j++) {
+			const second = tasks[j];
+			if (!second) continue;
+			for (const firstPath of first.writeSet ?? []) {
+				if (!firstPath.trim()) continue;
+				for (const secondPath of second.writeSet ?? []) {
+					if (!secondPath.trim()) continue;
+					if (pathsOverlap(normalizeWritePath(firstPath), normalizeWritePath(secondPath))) {
+						overlaps.push({ firstIndex: i, secondIndex: j, firstPath, secondPath });
+					}
+				}
+			}
+		}
+	}
+	return overlaps;
+}
+
+/** Undefined when the path is a repository-relative ownership name; otherwise a reason. */
+export function writeSetPathError(path: string): string | undefined {
+	if (typeof path !== "string" || !path.trim()) return "empty writeSet path";
+	const raw = path.trim();
+	const slash = raw.replaceAll("\\", "/");
+	const normalized = posix.normalize(slash);
+	if (posix.isAbsolute(slash) || win32.isAbsolute(raw) || normalized === ".." || normalized.startsWith("../")) {
+		return 'outside the repository-relative ownership namespace; use "." for the repository root';
+	}
+	return undefined;
+}
+
+/** Return an actionable error for a parallel write-set collision; undefined means safe to spawn.
+ *  Lives here (not in `tools/delegate.ts`) so a strategy can call it without importing a tool
+ *  module — `delegate.ts` re-exports it unchanged for its own call sites. */
+export function validateParallelWriteSets(tasks: readonly WriteSetOwner[]): string | undefined {
+	for (const [index, task] of tasks.entries()) {
+		for (const path of task.writeSet ?? []) {
+			const err = writeSetPathError(path);
+			if (!err) continue;
+			if (err.startsWith("empty")) {
+				return `delegate: task[${index}] ("${task.agent}") has an empty writeSet path; remove it or provide a repository-relative path.`;
+			}
+			return `delegate: task[${index}] ("${task.agent}") writeSet path "${path}" is ${err}.`;
+		}
+	}
+	const overlap = findWriteSetOverlaps(tasks)[0];
+	if (!overlap) return undefined;
+	const first = tasks[overlap.firstIndex];
+	const second = tasks[overlap.secondIndex];
+	return (
+		`delegate: parallel writeSet overlap between task[${overlap.firstIndex}] ("${first?.agent ?? "?"}") ` +
+		`path "${overlap.firstPath}" and task[${overlap.secondIndex}] ("${second?.agent ?? "?"}") ` +
+		`path "${overlap.secondPath}". Split the paths, serialize these tasks, or remove the overlap before spawning.`
+	);
+}

package/src/core/permissions.ts

@@ -0,0 +1,56 @@
+/**
+ * opencode-style allow/deny permission resolution over glob patterns.
+ *
+ * Pure module — no Pi imports. One resolver shared by persona `tools`/`delegate`/
+ * `skills` gating, agent tool allowlists, and the `EffectiveCapabilities` builder.
+ */
+
+/** An allow/deny block of glob patterns (`*` = any run, `?` = exactly one char). */
+export interface Permission {
+	allow?: string[];
+	deny?: string[];
+}
+
+// Patterns are fixed (a persona's allow/deny lists), but `isAllowed` runs on every `tool_call`
+// and across the whole tool registry on each persona switch — so compile each glob once.
+const globCache = new Map<string, RegExp>();
+const GLOB_CACHE_MAX = 256;
+
+/** Compile a glob (`*`, `?`) into a full-string-anchored RegExp; all other
+ *  characters are matched literally (regex metacharacters are escaped). Memoised. */
+function globToRegExp(pattern: string): RegExp {
+	const cached = globCache.get(pattern);
+	if (cached) return cached;
+	let body = "";
+	for (const ch of pattern) {
+		if (ch === "*") body += ".*";
+		else if (ch === "?") body += ".";
+		else body += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	}
+	const re = new RegExp(`^${body}$`);
+	if (globCache.size >= GLOB_CACHE_MAX) globCache.clear();
+	globCache.set(pattern, re);
+	return re;
+}
+
+function matchesAny(name: string, patterns: string[]): boolean {
+	return patterns.some((p) => globToRegExp(p).test(name));
+}
+
+/**
+ * Resolve whether `name` is permitted by an opencode-style block.
+ *
+ * - **deny wins:** a match in `deny` → denied.
+ * - **allowlist mode:** if `allow` is present, only matching names are allowed
+ *   (`allow: []` ⇒ lockdown; `allow: ["*"]` ⇒ allow all).
+ * - **denylist mode:** `deny` only ⇒ allow everything except denied.
+ * - **absent block** (no `allow`/`deny`, or `perm` undefined) ⇒ `defaultAllow`.
+ */
+export function isAllowed(name: string, perm: Permission | undefined, defaultAllow = true): boolean {
+	const deny = perm?.deny;
+	if (deny !== undefined && matchesAny(name, deny)) return false;
+	const allow = perm?.allow;
+	if (allow !== undefined) return matchesAny(name, allow);
+	if (deny !== undefined) return true; // denylist mode: not denied ⇒ allowed
+	return defaultAllow;
+}

package/src/core/pi-compat.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Oldest Pi this extension is written against. 0.83 made `message_update` delta-only (src/engine/stream.ts);
+ *  older hosts are feature-detected where cheap but are not supported. Keep in sync with README.md;
+ *  npm host peers use "*" because Pi supplies them through its extension loader. */
+export const MIN_PI_VERSION = "0.83.0";
+
+function parse(v: string): [number, number, number] | undefined {
+	const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+	return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+
+export function satisfiesFloor(version: string, floor: string): boolean {
+	const a = parse(version), b = parse(floor);
+	if (!a || !b) return false;
+	for (let i = 0; i < 3; i++) { if (a[i]! !== b[i]!) return a[i]! > b[i]!; }
+	return true;
+}
+
+function resolveHostEntry(): string | undefined {
+	// The host package is ESM-only (no CJS `main`), so `createRequire(...).resolve` throws
+	// ERR_PACKAGE_PATH_NOT_EXPORTED for it — `import.meta.resolve` is tried first because it
+	// follows an `exports` map with no `main`/`require` condition. `createRequire` stays as a
+	// fallback for any host build that does publish one.
+	try {
+		return fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+	} catch { /* fall through */ }
+	try {
+		return createRequire(import.meta.url).resolve("@earendil-works/pi-coding-agent");
+	} catch { /* unresolved host */ }
+	return undefined;
+}
+
+/** Best-effort: the host's package.json is not in its `exports` map, so resolve the entry and read the file. */
+export function installedPiVersion(): string | undefined {
+	const entry = resolveHostEntry();
+	if (!entry) return undefined;
+	let dir = dirname(entry);
+	for (let i = 0; i < 6; i++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { name?: string; version?: string };
+			if (pkg.name === "@earendil-works/pi-coding-agent" && typeof pkg.version === "string") return pkg.version;
+		} catch { /* climb */ }
+		dir = dirname(dir);
+	}
+	return undefined;
+}