pi-anchorloop 0.0.0-stage → 2.0.1

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "pi-anchorloop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.1",
+  "description": "Agent workflow skills for pi: one entry skill per task type, each with playbooks, over a shared Align → Anchor → Act → Verify loop, plus loop extensions (anchor gate, decision trail tool, Jev second thought, skill validator, stream rules).",
+  "author": "Wei Hung",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wayne930242/anchorloop.git"
+  },
+  "homepage": "https://github.com/wayne930242/anchorloop#readme",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "anchorloop",
+    "agent-workflow",
+    "skills",
+    "playbooks"
+  ],
+  "files": [
+    "pi",
+    "skills",
+    "hooks/validate_tool_use.py",
+    "hooks/validators/*.py",
+    "README.md",
+    "README.zh-TW.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./pi/validate-tool-use.ts",
+      "./pi/ttsr.ts",
+      "./pi/anchor-gate.ts",
+      "./pi/decision-tool.ts",
+      "./pi/second-thought.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/pi/anchor-gate.ts

@@ -0,0 +1,84 @@
+/**
+ * pi extension: warns once when write or edit runs before the assistant has
+ * stated a `Reality anchor:` line since the user's latest message.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const ANCHOR = /Reality anchor:/;
+const EXEMPT_IN_PROJECT = ["scratch", "docs/specs"];
+const EXEMPT_ROOTS = [tmpdir(), "/tmp", "/var/folders"];
+const EXEMPT_EXTENSIONS = [".md", ".txt", ".html", ".htm"];
+
+export const WARNING =
+	"anchorloop anchor gate: a change ran before the reply stated " +
+	"`Reality anchor: <the exact check that observes the result, and its checkpoint>`.";
+
+type Block = { type: string; text?: string };
+type Message = { role?: string; content?: string | Block[] };
+
+function statesAnchor(message: Message): boolean {
+	if (message.role !== "assistant" || !Array.isArray(message.content)) return false;
+	return message.content.some((block) => block.type === "text" && ANCHOR.test(block.text ?? ""));
+}
+
+/** The real path of `path`, resolving symlinks such as /var → /private/var through its nearest existing parent. */
+function real(path: string): string {
+	if (existsSync(path)) return realpathSync(path);
+	const parent = dirname(path);
+	return parent === path ? path : join(real(parent), basename(path));
+}
+
+function within(root: string, target: string): boolean {
+	const rel = relative(root, target);
+	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/** Markdown, text, and HTML files, scratch and spec folders in the project, and temp files outside it; a project that lives in a temp dir is still gated. */
+export function exempt(filePath: string, cwd: string): boolean {
+	if (EXEMPT_EXTENSIONS.includes(extname(filePath).toLowerCase())) return true;
+	const root = real(cwd);
+	const target = real(resolve(cwd, filePath));
+	if (within(root, target)) return EXEMPT_IN_PROJECT.some((dir) => within(join(root, dir), target));
+	return EXEMPT_ROOTS.some((tmp) => within(real(tmp), target));
+}
+
+export default function (pi: ExtensionAPI) {
+	let anchored = false;
+	let warned = false;
+
+	pi.on("session_start", (_event, ctx) => {
+		anchored = false;
+		const branch = ctx.sessionManager.getBranch() as Array<{ type: string; message?: Message }>;
+		for (let i = branch.length - 1; i >= 0; i--) {
+			const message = branch[i].type === "message" ? branch[i].message : undefined;
+			if (!message) continue;
+			if (message.role === "user") return;
+			if (statesAnchor(message)) {
+				anchored = true;
+				return;
+			}
+		}
+	});
+
+	// User messages that steer a running loop end here too, so the gate closes for each of them.
+	pi.on("message_end", (event) => {
+		const message = event.message as Message;
+		if (message.role === "user") {
+			anchored = false;
+			warned = false;
+		}
+		else if (statesAnchor(message)) anchored = true;
+	});
+
+	pi.on("tool_call", (event, ctx) => {
+		if (anchored || warned || (event.toolName !== "write" && event.toolName !== "edit")) return;
+		const filePath = (event.input as { path?: unknown }).path;
+		if (typeof filePath !== "string" || exempt(filePath, ctx.cwd)) return;
+		warned = true;
+		ctx.ui.notify(WARNING, "warning");
+	});
+}

package/pi/decision-tool.ts

@@ -0,0 +1,88 @@
+/**
+ * pi extension: the `anchorloop_decision` tool appends single-line rows to a
+ * decision trail TSV. Adapted from pstack's show-me-your-work log.sh
+ * (MIT, (c) 2026 Lauren Tan).
+ */
+
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, writeSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const HEADER = ["ts", "decision", "why", "evidence", "result"];
+const FORMULA_LEADS = ["=", "+", "-", "@", '"'];
+const TRAIL_PATH = /^scratch\/decisions-[^/]+\.tsv$/;
+
+function clean(cell: string): string {
+	const flat = cell.replace(/[\t\r\n]/g, " ");
+	return FORMULA_LEADS.some((lead) => flat.startsWith(lead)) ? `'${flat}` : flat;
+}
+
+function readRows(log: string): string[][] {
+	if (!existsSync(log)) return [];
+	return readFileSync(log, "utf-8")
+		.split("\n")
+		.slice(1)
+		.filter(Boolean)
+		.map((line) => line.split("\t"));
+}
+
+export function appendRow(log: string, cells: string[], now = new Date()): string {
+	mkdirSync(dirname(log), { recursive: true });
+	const ts = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+	const row = `${[ts, ...cells.map(clean)].join("\t")}\n`;
+	const data = existsSync(log) && statSync(log).size > 0 ? row : `${HEADER.join("\t")}\n${row}`;
+	// One O_APPEND write per row, so parallel writers never interleave inside a row.
+	const fd = openSync(log, "a");
+	try {
+		const bytes = Buffer.from(data);
+		const written = writeSync(fd, bytes);
+		if (written !== bytes.length) throw new Error(`short write: ${written} of ${bytes.length} bytes`);
+	} finally {
+		closeSync(fd);
+	}
+	return row;
+}
+
+export function startRow(log: string, runId: string): string {
+	const rows = readRows(log);
+	const span = rows.length > 0 ? `${rows[0][0]}..${rows.at(-1)?.[0]}` : "empty trail";
+	return appendRow(log, ["start", `picked up after ${rows.length} earlier rows (${span})`, runId, "open"]);
+}
+
+type Params = { log: string; start?: string; decision?: string; why?: string; evidence?: string; result?: string };
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "anchorloop_decision",
+		label: "Decision trail",
+		description:
+			"Append one row to a decision trail TSV (scratch/decisions-<task-slug>.tsv): a fork chosen, a unit completed, a pivot, or a blocker. " +
+			"Pass `start` with your run id instead of the row fields when picking up a trail another run wrote.",
+		parameters: {
+			type: "object",
+			properties: {
+				log: { type: "string", description: "Trail path, relative to the working directory" },
+				start: { type: "string", description: "Run id; writes a start row and ignores the row fields" },
+				decision: { type: "string", description: "What was chosen or done, one line" },
+				why: { type: "string", description: "The reason in plain words" },
+				evidence: { type: "string", description: "A pointer: commit, file:line, or artifact path" },
+				result: { type: "string", description: "Outcome or predicate state" },
+			},
+			required: ["log"],
+			additionalProperties: false,
+		},
+		async execute(_toolCallId: string, params: Params, _signal: unknown, _onUpdate: unknown, ctx: { cwd: string }) {
+			const log = resolve(ctx.cwd, params.log);
+			if (!TRAIL_PATH.test(relative(ctx.cwd, log))) throw new Error("log must be scratch/decisions-<task-slug>.tsv");
+			let row: string;
+			if (params.start) {
+				row = startRow(log, params.start);
+			} else {
+				const cells = [params.decision, params.why, params.evidence, params.result];
+				if (cells.some((cell) => !cell)) throw new Error("decision, why, evidence, and result are all required");
+				row = appendRow(log, cells as string[]);
+			}
+			return { content: [{ type: "text", text: `appended to ${params.log}: ${row.trim()}` }], details: undefined };
+		},
+	});
+}

package/pi/second-thought.ts

@@ -0,0 +1,242 @@
+/**
+ * pi extension: before a run that changed something settles, asks Jev whether the
+ * final reply shows the request met, what review it needs, and how good it is.
+ * Only what the user typed counts as the request: messages that extensions send
+ * (intercom, monitor wakes) do not replace it. A run they start is sent with
+ * `trigger: wake` and the message that woke it, and is judged on what that message asks.
+ * A run that arranged a wake (a monitor, a loop, a subagent) is waiting, not finished,
+ * and is not judged. Jev also says whether the reply is a
+ * checkpoint, a point that hands work back to the user; a reply that only acknowledges,
+ * reports progress, or waits gets no reminder. A wake run is asked a stricter checkpoint
+ * question, since with the general one Jev counts a reply to a routine liveness or health
+ * check as handing work back. A wrong review tier or low quality gets one
+ * advisory continuation per run; a low done score is only shown. The agent is never
+ * blocked. Only the request, the trigger, the wake message, and the final reply are sent.
+ * A subagent session registers nothing: the agent that spawned it judges its result.
+ */
+
+import { type ExtensionAPI, parseSkillBlock } from "@earendil-works/pi-coding-agent";
+
+export const ENTRY_TYPE = "anchorloop-second-thought";
+const WORK_TOOLS = new Set(["write", "edit", "bash"]);
+const WAIT_TOOLS = new Set(["MonitorCreate", "LoopCreate", "goal_wait", "subagent", "subagent_resume", "subagent_send"]);
+const REQUEST_CHARS = 1500;
+const WAKE_CHARS = 1500;
+const REPLY_CHARS = 3000;
+const TIMEOUT_MS = 15_000;
+
+export const THRESHOLDS = { checkpointBelow: 0.5, doneBelow: 0.25, qualityBelow: 1.5, reviewTier: "full" };
+
+export const QUESTIONS = {
+	checkpoint: {
+		type: "bool" as const,
+		instructions:
+			"Is `reply` a point where the agent hands work back to the user? `trigger` is `user` when the user's message started this run and `wake` when an automated message (a monitor, a loop, another agent) did.",
+		criteria: {
+			true: "the reply delivers a result, reports the request finished or blocked, or asks the user to decide",
+			false: "the reply only acknowledges a message, reports interim progress, or says the agent is waiting on something it started",
+		},
+	},
+	done: {
+		type: "bool" as const,
+		instructions:
+			"Does `reply` show, with evidence, that the work this run took on is fully met? That work is `request`, or, when `trigger` is `wake`, what `wake` asks in service of `request`.",
+		criteria: {
+			true: "every part of the request has observed evidence in the reply: command output, a test result, or an artifact",
+			false: "some part failed, was skipped, is left for later, or rests only on a claim",
+		},
+	},
+	review: {
+		type: "choice" as const,
+		instructions: "What review should the change described in `reply` get before it is merged or released?",
+		criteria: {
+			none: "trivial, fully covered by a passing check",
+			focused: "one independent reviewer on the changed lines",
+			full: "independent review plus an adversarial pass: security, data, permissions, migration, or a shared contract",
+		},
+	},
+	quality: {
+		type: "score" as const,
+		instructions: "How acceptable is the delivered work against the work this run took on: `request`, or `wake` when `trigger` is `wake`?",
+		criteria: [
+			"unacceptable: wrong or broken",
+			"weak: works but misses requirements",
+			"acceptable: meets the request",
+			"strong: meets it with direct evidence and no excess",
+		],
+	},
+};
+
+// Replayed on the 26 wake-run advisories of one long session, this question let through 1 of
+// the 21 status or liveness replies instead of all 21, and 3 of the 5 delivered results.
+export const WAKE_CHECKPOINT = {
+	type: "bool" as const,
+	instructions:
+		"Is `reply` a point where the agent hands work back to the user? `trigger` is `user` when the user's message started this run and `wake` when an automated message (a monitor, a loop, another agent) did; `wake` is that message. A reply to a routine check that `wake` asked for is not a checkpoint.",
+	criteria: {
+		true: "the reply delivers a finished result or artifact, reports the user's request finished or blocked, or asks the user to decide",
+		false: "the reply acknowledges a message, reports the status, health, load, or progress of work that is still running, or says the agent is waiting on something",
+	},
+};
+
+type Block = { type: string; text?: string };
+type Answers = Record<string, { type: string; probability?: number; choice?: string; probabilities?: Record<string, number>; score?: number }>;
+export type Verdict = { checkpoint: number; done: number; review: string; reviewProbability: number; quality: number };
+
+export function readVerdict(answers: Answers): Verdict | undefined {
+	const { checkpoint, done, review, quality } = answers;
+	if (checkpoint?.type !== "bool" || done?.type !== "bool" || review?.type !== "choice" || quality?.type !== "score") return undefined;
+	const choice = review.choice ?? "";
+	return {
+		checkpoint: checkpoint.probability ?? 0,
+		done: done.probability ?? 0,
+		review: choice,
+		reviewProbability: review.probabilities?.[choice] ?? 0,
+		quality: quality.score ?? 0,
+	};
+}
+
+export function concerns(verdict: Verdict): string[] {
+	const found: string[] = [];
+	if (verdict.checkpoint < THRESHOLDS.checkpointBelow) return found;
+	if (verdict.done < THRESHOLDS.doneBelow) found.push("request not shown met");
+	if (verdict.review === THRESHOLDS.reviewTier) found.push("needs full independent review");
+	if (verdict.quality < THRESHOLDS.qualityBelow) found.push("result below the request");
+	return found;
+}
+
+export function needsRecheck(verdict: Verdict): boolean {
+	return verdict.review === THRESHOLDS.reviewTier || verdict.quality < THRESHOLDS.qualityBelow;
+}
+
+export function message(verdict: Verdict, found: string[], recheck: boolean): string {
+	return (
+		`Second thought (Jev, advisory): done ${verdict.done.toFixed(2)}, review ${verdict.review}, ` +
+		`quality ${verdict.quality.toFixed(2)}/3; ${found.join("; ")}.` +
+		(recheck ? " Recheck your evidence; continue only if it fails." : "") +
+		" No reply needed. Clear finished or stale todos; continue any unfinished work."
+	);
+}
+
+function text(content: unknown): string {
+	if (typeof content === "string") return content.trim();
+	if (!Array.isArray(content)) return "";
+	return (content as Block[])
+		.filter((block) => block.type === "text")
+		.map((block) => block.text ?? "")
+		.join("\n")
+		.trim();
+}
+
+// pi-herdr-agents marks its children with PI_SUBAGENT_ID, pi-subagents with PI_SUBAGENT_CHILD,
+// and avtc's pi-subagent with PI_SUBAGENT_CHILD_AGENT plus PI_SUBAGENT_PARENT_PID.
+export function isSubagent(env: NodeJS.ProcessEnv = process.env): boolean {
+	return Boolean(env.PI_SUBAGENT_ID) || env.PI_SUBAGENT_CHILD === "1" || Boolean(env.PI_SUBAGENT_CHILD_AGENT && env.PI_SUBAGENT_PARENT_PID);
+}
+
+export default function (pi: ExtensionAPI) {
+	if (isSubagent()) return;
+	let request = "";
+	let reply = "";
+	let worked = false;
+	let waiting = false;
+	let asked = false;
+	// A run is `user` once a message the user typed lands in it; otherwise a wake started it.
+	let trigger: "user" | "wake" = "wake";
+	// The automated message that started a wake run: the last one to land before the run's first reply.
+	let wake = "";
+	// Texts extensions sent as user messages that have not landed yet; matched by content,
+	// since another handler may swallow an input or a queue may be cleared before it lands.
+	const sent = new Map<string, number>();
+
+	pi.on("session_start", () => {
+		sent.clear();
+	});
+
+	pi.on("input", (event) => {
+		if (event.source !== "extension") return;
+		const said = event.text.trim();
+		sent.set(said, (sent.get(said) ?? 0) + 1);
+	});
+
+	// Each run is judged once, on its own work. State resets once the session settles, so a
+	// continuation (this extension's recheck, or one after compaction) stays in the same run.
+	// An extension text still pending then was swallowed or dropped and will not land.
+	pi.on("agent_settled", () => {
+		sent.clear();
+		reply = "";
+		worked = false;
+		waiting = false;
+		asked = false;
+		trigger = "wake";
+		wake = "";
+	});
+
+	pi.on("tool_call", (event) => {
+		if (WORK_TOOLS.has(event.toolName)) worked = true;
+		if (WAIT_TOOLS.has(event.toolName)) waiting = true;
+	});
+
+	// A message the user typed, including one that steers a running loop, starts a new request.
+	pi.on("message_end", (event) => {
+		const msg = event.message as { role?: string; content?: unknown; customType?: string };
+		const said = text(msg.content);
+		if (msg.role === "custom") {
+			if (msg.customType !== ENTRY_TYPE && !reply && said) wake = said;
+		} else if (msg.role === "user") {
+			const pending = sent.get(said) ?? 0;
+			if (pending > 0) {
+				if (pending === 1) sent.delete(said);
+				else sent.set(said, pending - 1);
+				if (!reply) wake = said;
+				return;
+			}
+			const skill = parseSkillBlock(said);
+			request = skill ? (skill.userMessage ?? `/skill:${skill.name}`) : said;
+			reply = "";
+			worked = false;
+			asked = false;
+			trigger = "user";
+			wake = "";
+		} else if (msg.role === "assistant" && said) {
+			reply = said;
+		}
+	});
+
+	pi.on("agent_before_settle", async (event, ctx) => {
+		if (asked || !worked || waiting || !reply || !request || event.outcome !== "completed") return;
+		asked = true;
+		const record = (data: Record<string, unknown>) => ({ type: "custom" as const, customType: ENTRY_TYPE, data });
+		const jev = ctx.modelRegistry.findOfType("classifier", "typesafe", "jev-latest");
+		type AuthModel = Parameters<typeof ctx.modelRegistry.hasConfiguredAuth>[0];
+		// SAFETY: hasConfiguredAuth is typed for chat models but reads only `provider`, which a classifier has too.
+		if (!jev || !ctx.modelRegistry.hasConfiguredAuth(jev as unknown as AuthModel)) return;
+		let verdict: Verdict | undefined;
+		let reason = "";
+		try {
+			const result = await ctx.modelRegistry.classify(
+				jev,
+				{
+					state: { request: request.slice(0, REQUEST_CHARS), trigger, wake: wake.slice(0, WAKE_CHARS), reply: reply.slice(-REPLY_CHARS) },
+					questions: trigger === "wake" ? { ...QUESTIONS, checkpoint: WAKE_CHECKPOINT } : QUESTIONS,
+				},
+				{ signal: AbortSignal.any([AbortSignal.timeout(TIMEOUT_MS), ...(ctx.signal ? [ctx.signal] : [])]) },
+			);
+			verdict = result.stopReason === "stop" ? readVerdict(result.answers as Answers) : undefined;
+			reason = result.stopReason;
+		} catch (error) {
+			reason = error instanceof Error ? error.message : String(error);
+		}
+		if (!verdict) return { entries: [record({ verdict: "unknown", reason })] };
+		const found = concerns(verdict);
+		if (found.length === 0) return { entries: [record({ ...verdict, concerns: [] })] };
+		const recheck = needsRecheck(verdict);
+		return {
+			entries: [
+				record({ ...verdict, concerns: found }),
+				{ type: "custom_message" as const, customType: ENTRY_TYPE, content: message(verdict, found, recheck), display: true },
+			],
+			...(recheck ? { continue: true } : {}),
+		};
+	});
+}