@zhuxixi/pi-agent-board 0.3.0

package/src/core/follow-up-queue.mjs

@@ -0,0 +1,193 @@
+/** Durable FIFO follow-up queue helpers. */
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import { newFollowUpId } from "./ids.mjs";
+import { truncate } from "./heuristics.mjs";
+import { withViewLockSync } from "./locks.mjs";
+import * as P from "./paths.mjs";
+
+/** @param {string} viewId @param {number} [now] @returns {import("./types.mjs").FollowUpQueue} */
+export function emptyFollowUpQueue(viewId, now = Date.now()) {
+	return { version: 1, viewId, nextSeq: 1, updatedAt: now, items: [] };
+}
+
+/** @param {string} root @param {string} viewId */
+export function readFollowUpQueue(root, viewId) {
+	return normalizeQueue(readJson(P.followUpQueuePath(root, viewId), null), viewId);
+}
+
+/** @param {string} root @param {import("./types.mjs").FollowUpQueue} queue */
+export function writeFollowUpQueue(root, queue) {
+	const normalized = normalizeQueue(queue, queue.viewId);
+	normalized.updatedAt = Date.now();
+	atomicWriteJson(P.followUpQueuePath(root, normalized.viewId), normalized);
+	return normalized;
+}
+
+/** @param {import("./types.mjs").FollowUpQueue} queue @returns {import("./types.mjs").FollowUpSummary} */
+export function summarizeFollowUpQueue(queue) {
+	const q = normalizeQueue(queue, queue?.viewId ?? "");
+	const queued = q.items.filter((i) => i.status === "queued");
+	const claimed = q.items.filter((i) => i.status === "claimed");
+	const last = [...queued].sort((a, b) => b.createdAt - a.createdAt)[0] ?? null;
+	return {
+		queuedCount: queued.length,
+		claimedCount: claimed.length,
+		lastQueuedAt: last?.createdAt ?? null,
+		lastQueuedPreview: last ? truncate(last.text, 120) : null,
+	};
+}
+
+/** @param {string} root @param {string} viewId @param {string} text @param {{ kind?: import("./types.mjs").FollowUpKind, source?: string, delivery?: "auto"|"now"|"queue" }} [opts] */
+export function enqueueFollowUp(root, viewId, text, opts = {}) {
+	const clean = String(text || "").trim();
+	if (!clean) return { ok: false, error: "Empty follow-up" };
+	return withViewLockSync(root, viewId, "queue", () => {
+		const queue = readFollowUpQueue(root, viewId);
+		const now = Date.now();
+		const item = {
+			id: newFollowUpId(),
+			seq: queue.nextSeq,
+			viewId,
+			kind: opts.kind ?? "reply",
+			text: clean,
+			createdAt: now,
+			updatedAt: now,
+			status: "queued",
+			source: opts.source ?? "user",
+			delivery: opts.delivery ?? "auto",
+			runId: null,
+			claimedAt: null,
+			completedAt: null,
+			attempts: 0,
+			error: null,
+		};
+		queue.nextSeq += 1;
+		queue.items.push(item);
+		writeFollowUpQueue(root, queue);
+		return { ok: true, item, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null }} [opts] */
+export function claimNextFollowUp(root, viewId, opts = {}) {
+	return withViewLockSync(root, viewId, "queue", () => {
+		const queue = readFollowUpQueue(root, viewId);
+		const item = queue.items.filter((i) => i.status === "queued").sort((a, b) => a.seq - b.seq)[0];
+		if (!item) return { ok: false, error: "No queued follow-up" };
+		item.status = "claimed";
+		item.claimedAt = Date.now();
+		item.updatedAt = item.claimedAt;
+		item.attempts = (item.attempts ?? 0) + 1;
+		item.runId = opts.runId ?? item.runId ?? null;
+		writeFollowUpQueue(root, queue);
+		return { ok: true, item, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {string} itemId @param {{ runId?: string|null }} [opts] */
+export function completeFollowUp(root, viewId, itemId, opts = {}) {
+	return updateItem(root, viewId, itemId, (item) => {
+		item.status = "completed";
+		item.completedAt = Date.now();
+		item.updatedAt = item.completedAt;
+		if (opts.runId) item.runId = opts.runId;
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {string} itemId @param {string} error */
+export function failFollowUp(root, viewId, itemId, error) {
+	return updateItem(root, viewId, itemId, (item) => {
+		item.status = "failed";
+		item.error = String(error || "Follow-up failed");
+		item.updatedAt = Date.now();
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {string} itemId */
+export function releaseFollowUp(root, viewId, itemId) {
+	return updateItem(root, viewId, itemId, (item) => {
+		item.status = "queued";
+		item.claimedAt = null;
+		item.updatedAt = Date.now();
+	});
+}
+
+/** @param {string} root @param {string} viewId */
+export function removeLastFollowUp(root, viewId) {
+	return withViewLockSync(root, viewId, "queue", () => {
+		const queue = readFollowUpQueue(root, viewId);
+		const queued = queue.items.filter((i) => i.status === "queued").sort((a, b) => b.seq - a.seq);
+		const last = queued[0];
+		if (!last) return { ok: false, error: "No queued follow-up" };
+		last.status = "cancelled";
+		last.updatedAt = Date.now();
+		writeFollowUpQueue(root, queue);
+		return { ok: true, item: last, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {string} root @param {string} viewId */
+export function clearQueuedFollowUps(root, viewId) {
+	return withViewLockSync(root, viewId, "queue", () => {
+		const queue = readFollowUpQueue(root, viewId);
+		let cancelled = 0;
+		for (const item of queue.items) {
+			if (item.status === "queued") {
+				item.status = "cancelled";
+				item.updatedAt = Date.now();
+				cancelled += 1;
+			}
+		}
+		writeFollowUpQueue(root, queue);
+		return { ok: true, cancelled, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {string} itemId @param {(item: import("./types.mjs").FollowUpItem) => void} mutate */
+function updateItem(root, viewId, itemId, mutate) {
+	return withViewLockSync(root, viewId, "queue", () => {
+		const queue = readFollowUpQueue(root, viewId);
+		const item = queue.items.find((i) => i.id === itemId);
+		if (!item) return { ok: false, error: "Unknown follow-up" };
+		mutate(item);
+		writeFollowUpQueue(root, queue);
+		return { ok: true, item, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {any} queue @param {string} viewId @returns {import("./types.mjs").FollowUpQueue} */
+function normalizeQueue(queue, viewId) {
+	const base = emptyFollowUpQueue(viewId || queue?.viewId || "");
+	if (!queue || typeof queue !== "object") return base;
+	const items = Array.isArray(queue.items) ? queue.items.map((item, idx) => normalizeItem(item, viewId, idx + 1)) : [];
+	return {
+		version: 1,
+		viewId: typeof queue.viewId === "string" ? queue.viewId : base.viewId,
+		nextSeq: Math.max(Number(queue.nextSeq ?? 1) || 1, items.reduce((m, i) => Math.max(m, i.seq + 1), 1)),
+		updatedAt: Number(queue.updatedAt ?? Date.now()) || Date.now(),
+		items,
+	};
+}
+
+/** @param {any} item @param {string} viewId @param {number} seq */
+function normalizeItem(item, viewId, seq) {
+	const now = Date.now();
+	const status = ["queued", "claimed", "completed", "failed", "cancelled"].includes(item?.status) ? item.status : "queued";
+	return {
+		id: typeof item?.id === "string" ? item.id : newFollowUpId(),
+		seq: Number(item?.seq ?? seq) || seq,
+		viewId: typeof item?.viewId === "string" ? item.viewId : viewId,
+		kind: ["reply", "plan_request", "plan_approval", "plan_change"].includes(item?.kind) ? item.kind : "reply",
+		text: String(item?.text ?? ""),
+		createdAt: Number(item?.createdAt ?? now) || now,
+		updatedAt: Number(item?.updatedAt ?? now) || now,
+		status,
+		source: typeof item?.source === "string" ? item.source : "user",
+		delivery: ["auto", "now", "queue"].includes(item?.delivery) ? item.delivery : "auto",
+		runId: typeof item?.runId === "string" ? item.runId : null,
+		claimedAt: Number.isFinite(item?.claimedAt) ? item.claimedAt : null,
+		completedAt: Number.isFinite(item?.completedAt) ? item.completedAt : null,
+		attempts: Number(item?.attempts ?? 0) || 0,
+		error: typeof item?.error === "string" ? item.error : null,
+	};
+}

package/src/core/heuristics.mjs

@@ -0,0 +1,240 @@
+/**
+ * Pure text heuristics: extracting assistant text, detecting questions/blockers,
+ * summarizing tool calls, and formatting relative times. No I/O, fully unit-tested.
+ */
+
+/**
+ * Join the text content blocks of an assistant message into a single string.
+ * Accepts the message object as emitted in JSON mode (`message.content` is an array
+ * of `{type,...}` blocks, or, defensively, a plain string).
+ * @param {any} message
+ * @returns {string}
+ */
+export function assistantText(message) {
+	if (!message) return "";
+	const content = message.content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((b) => b && b.type === "text" && typeof b.text === "string")
+		.map((b) => b.text)
+		.join("\n")
+		.trim();
+}
+
+/**
+ * Collect tool-call blocks from an assistant message.
+ * @param {any} message
+ * @returns {Array<{name:string, arguments:Record<string,any>}>}
+ */
+export function toolCalls(message) {
+	const content = message?.content;
+	if (!Array.isArray(content)) return [];
+	return content
+		.filter((b) => b && b.type === "toolCall")
+		.map((b) => ({ name: b.name, arguments: b.arguments ?? {} }));
+}
+
+const QUESTION_PHRASES = [
+	"need your input",
+	"need some input",
+	"which option",
+	"should i",
+	"shall i",
+	"please confirm",
+	"could you confirm",
+	"can you confirm",
+	"let me know",
+	"do you want",
+	"would you like",
+	"how would you like",
+	"what would you like",
+	"which one",
+	"please clarify",
+	"can you clarify",
+	"waiting for your",
+];
+
+/**
+ * Decide whether the latest assistant text is asking the user a question / is blocked,
+ * and extract the question sentence if so.
+ * @param {string} text
+ * @returns {{ needsInput: boolean, question: string|null }}
+ */
+export function detectNeedsInput(text) {
+	const trimmed = (text || "").trim();
+	if (!trimmed) return { needsInput: false, question: null };
+
+	const lower = trimmed.toLowerCase();
+	const sentences = splitSentences(trimmed);
+	const last = sentences[sentences.length - 1] ?? trimmed;
+
+	// Strongest signal: the message ends on a question mark.
+	if (/\?\s*$/.test(trimmed)) {
+		const q = [...sentences].reverse().find((s) => s.includes("?")) ?? last;
+		return { needsInput: true, question: q.trim() };
+	}
+
+	for (const phrase of QUESTION_PHRASES) {
+		if (lower.includes(phrase)) {
+			const hit = sentences.find((s) => s.toLowerCase().includes(phrase)) ?? last;
+			return { needsInput: true, question: hit.trim() };
+		}
+	}
+
+	return { needsInput: false, question: null };
+}
+
+/**
+ * Split text into sentences (rough; good enough for previews/blocker extraction).
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function splitSentences(text) {
+	return (text || "")
+		.replace(/\s+/g, " ")
+		.trim()
+		.split(/(?<=[.!?])\s+/)
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+/**
+ * First sentence (or first line) of an assistant message, for compact previews.
+ * @param {string} text
+ * @returns {string}
+ */
+export function firstSentence(text) {
+	const sentences = splitSentences(text);
+	return sentences[0] ?? "";
+}
+
+const PATH_KEYS = ["file_path", "path", "filePath", "file", "filename"];
+
+/**
+ * Best-effort target path from a tool call's arguments.
+ * @param {Record<string,any>} args
+ * @returns {string|null}
+ */
+export function toolPath(args) {
+	if (!args || typeof args !== "object") return null;
+	for (const k of PATH_KEYS) {
+		if (typeof args[k] === "string" && args[k]) return args[k];
+	}
+	if (typeof args.pattern === "string" && args.pattern) return args.pattern;
+	return null;
+}
+
+/**
+ * Human one-liner for an in-progress tool call, e.g. "Editing src/auth.ts".
+ * @param {string} name
+ * @param {Record<string,any>} args
+ * @returns {string}
+ */
+export function toolSummary(name, args) {
+	const p = toolPath(args);
+	const base = p ? baseName(p) : null;
+	switch (name) {
+		case "edit":
+			return base ? `Editing ${base}` : "Editing files";
+		case "write":
+			return base ? `Writing ${base}` : "Writing files";
+		case "read":
+			return base ? `Reading ${base}` : "Reading files";
+		case "ls":
+			return base ? `Listing ${base}` : "Listing files";
+		case "find":
+			return p ? `Finding ${p}` : "Finding files";
+		case "grep":
+			return p ? `Searching /${p}/` : "Searching";
+		case "bash": {
+			const cmd = typeof args?.command === "string" ? args.command.trim() : "";
+			if (!cmd) return "Running command";
+			const kind = classifyCommand(cmd);
+			if (kind === "test") return "Running tests";
+			if (kind === "build") return "Building";
+			if (kind === "lint") return "Linting";
+			if (kind === "git") return `git ${cmd.replace(/^git\s+/, "").split(/\s+/)[0] ?? ""}`.trim();
+			return `Running ${truncate(cmd, 32)}`;
+		}
+		default:
+			return base ? `${capitalize(name)} ${base}` : capitalize(name);
+	}
+}
+
+/**
+ * Classify a shell command for review evidence.
+ * @param {string} command
+ * @returns {"test"|"build"|"lint"|"git"|"install"|"other"}
+ */
+export function classifyCommand(command) {
+	const cmd = String(command || "").trim();
+	if (!cmd) return "other";
+	if (/\b(test|vitest|jest|pytest|go test|cargo test|npm test|pnpm test|yarn test)\b/.test(cmd)) return "test";
+	if (/\b(build|tsc|webpack|vite build|make|cargo build|go build)\b/.test(cmd)) return "build";
+	if (/\b(lint|eslint|biome|ruff|clippy)\b/.test(cmd)) return "lint";
+	if (/^(git|gh)\b/.test(cmd)) return "git";
+	if (/\b(npm install|npm ci|pnpm install|yarn install|bun install)\b/.test(cmd)) return "install";
+	return "other";
+}
+
+/** @param {string} command @param {number} [n] */
+export function commandPreview(command, n = 120) {
+	return truncate(String(command || "").replace(/\s+/g, " ").trim(), n);
+}
+
+/**
+ * Detect file mutation operations from tool name/args.
+ * @param {string} name
+ * @param {Record<string,any>} args
+ * @returns {{ path:string, action:"edited"|"written"|"deleted"|"unknown" }|null}
+ */
+export function toolFileOperation(name, args) {
+	const p = toolPath(args);
+	if (!p) return null;
+	if (["edit", "multi_edit", "apply_patch"].includes(name)) return { path: p, action: "edited" };
+	if (["write", "create_file"].includes(name)) return { path: p, action: "written" };
+	if (["delete", "rm", "remove_file"].includes(name)) return { path: p, action: "deleted" };
+	return null;
+}
+
+/** @param {string} p */
+export function baseName(p) {
+	const parts = String(p).split(/[\\/]/).filter(Boolean);
+	return parts[parts.length - 1] ?? p;
+}
+
+/** @param {string} s */
+function capitalize(s) {
+	return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+/**
+ * Truncate to `n` chars with an ellipsis (counts characters, not display width).
+ * @param {string} s
+ * @param {number} n
+ * @returns {string}
+ */
+export function truncate(s, n) {
+	const str = String(s ?? "");
+	if (str.length <= n) return str;
+	return `${str.slice(0, Math.max(0, n - 1))}…`;
+}
+
+/**
+ * Compact relative age, e.g. "10s", "2m", "3h", "4d".
+ * @param {number} fromMs
+ * @param {number} [nowMs]
+ * @returns {string}
+ */
+export function relativeTime(fromMs, nowMs = Date.now()) {
+	const diff = Math.max(0, nowMs - fromMs);
+	const s = Math.floor(diff / 1000);
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m}m`;
+	const h = Math.floor(m / 60);
+	if (h < 24) return `${h}h`;
+	const d = Math.floor(h / 24);
+	return `${d}d`;
+}

package/src/core/ids.mjs

@@ -0,0 +1,35 @@
+/** ID generation for views and runs. */
+import { randomBytes } from "node:crypto";
+
+/** @param {string} prefix @returns {string} e.g. "view_8f3a1c2b". */
+export function genId(prefix) {
+	return `${prefix}_${randomBytes(5).toString("hex")}`;
+}
+
+/** @returns {string} a new view (row) id. */
+export const newViewId = () => genId("view");
+
+/** @returns {string} a new run id. */
+export const newRunId = () => genId("run");
+
+/** @returns {string} a new follow-up queue item id. */
+export const newFollowUpId = () => genId("follow");
+
+/**
+ * Derive a short, filesystem-safe slug from a free-text task, for display names.
+ * @param {string} text
+ * @param {number} [maxWords]
+ * @returns {string}
+ */
+export function slugifyTask(text, maxWords = 5) {
+	const words = String(text)
+		.toLowerCase()
+		.replace(/[`'"]/g, "")
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+		.split(/\s+/)
+		.filter(Boolean)
+		.slice(0, maxWords);
+	const slug = words.join("-");
+	return slug || "task";
+}

package/src/core/invocation.mjs

@@ -0,0 +1,43 @@
+/**
+ * Resolve how to invoke the `pi` worker and the `node` runner across install shapes:
+ *  - pi as `dist/cli.js` under system node  → piCommand=node, piArgsPrefix=[cli.js]
+ *  - pi as a bun-compiled binary            → piCommand="pi" (on PATH)
+ *  - generic node/bun runtime               → piCommand=execPath
+ * Mirrors the logic in the official subagent example's getPiInvocation().
+ */
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+
+/** @returns {boolean} true when process.execPath is a generic node/bun runtime (not a compiled app). */
+function isGenericRuntime() {
+	const name = path.basename(process.execPath).toLowerCase();
+	return /^(node|bun)(\.exe)?$/.test(name);
+}
+
+/**
+ * Compute `{ piCommand, piArgsPrefix }` for spawning the pi worker.
+ * @returns {{ piCommand: string, piArgsPrefix: string[] }}
+ */
+export function resolvePiInvocation() {
+	const script = process.argv[1];
+	const isBunVirtual = typeof script === "string" && script.startsWith("/$bunfs/root/");
+	if (script && !isBunVirtual && existsSync(script)) {
+		// Running the pi cli script under a runtime — re-run the same script.
+		return { piCommand: process.execPath, piArgsPrefix: [script] };
+	}
+	if (!isGenericRuntime()) {
+		// Compiled pi binary invoked directly.
+		return { piCommand: process.execPath, piArgsPrefix: [] };
+	}
+	// Fallback: rely on `pi` being on PATH.
+	return { piCommand: "pi", piArgsPrefix: [] };
+}
+
+/**
+ * Resolve a real `node` executable to run the detached `.mjs` runner.
+ * @returns {string}
+ */
+export function resolveNode() {
+	if (isGenericRuntime()) return process.execPath;
+	return "node";
+}