@zhuxixi/pi-agent-board 0.3.0

package/src/core/events.mjs

@@ -0,0 +1,268 @@
+/**
+ * Reduce Pi JSON-mode worker events into an evolving RunStatus.
+ *
+ * Event vocabulary (verified against dist `agent-session.ts`; see docs/EXPLORATION.md §4):
+ *   first line: session header {type:"session",...}
+ *   message_start | message_update | message_end   (.message is an AgentMessage)
+ *   tool_execution_start {toolCallId,toolName,args}
+ *   tool_execution_end {toolCallId,toolName,result,isError}
+ *   turn_start | turn_end | agent_start | agent_end
+ * NOTE: `tool_result_end` (used by the subagent example) is never emitted — do not rely on it.
+ */
+import { deriveSummary, finalizeSemanticState } from "./derive.mjs";
+import { assistantText, detectNeedsInput, toolPath, toolSummary, truncate } from "./heuristics.mjs";
+
+/** @typedef {import("./types.mjs").RunConfig} RunConfig */
+/** @typedef {import("./types.mjs").RunStatus} RunStatus */
+
+const PREVIEW_MAX = 240;
+
+/**
+ * Build the initial status for a freshly-launched run.
+ * @param {RunConfig} config
+ * @param {number|null} pid
+ * @param {number} now
+ * @returns {RunStatus}
+ */
+export function createRunStatus(config, pid, now) {
+	/** @type {RunStatus} */
+	const status = {
+		version: 1,
+		runId: config.runId,
+		viewId: config.viewId,
+		pid,
+		startedAt: now,
+		endedAt: null,
+		exitCode: null,
+		kind: config.kind,
+		prompt: config.prompt,
+		model: config.model ?? null,
+		semanticState: "queued",
+		processState: "alive",
+		summary: "Queued",
+		lastActivityAt: now,
+		currentTool: null,
+		latestAssistantPreview: "",
+		question: null,
+		pendingQuestions: [],
+		error: null,
+		lastAgentActivityAt: null,
+		stopReason: null,
+		stoppedByUser: false,
+		turns: 0,
+		toolCount: 0,
+		eventCount: 0,
+		lastEventAt: null,
+		usage: null,
+		stallReason: null,
+		evidenceSummary: null,
+		autoState: null,
+	};
+	return status;
+}
+
+/**
+ * Apply a single worker event to `status` (mutates in place).
+ * @param {RunStatus} status
+ * @param {any} event
+ * @param {number} now
+ * @param {{ interactive?: boolean }} [opts]
+ * @returns {boolean} whether this event produced a user-visible change worth persisting.
+ */
+export function reduceEvent(status, event, now, opts = {}) {
+	if (!event || typeof event !== "object" || typeof event.type !== "string") return false;
+	let meaningful = false;
+	status.eventCount = (status.eventCount ?? 0) + 1;
+	status.lastEventAt = now;
+
+	switch (event.type) {
+		case "tool_execution_start": {
+			const name = event.toolName ?? event.args?.name ?? "tool";
+			const args = event.args ?? {};
+			status.toolCount += 1;
+			if (opts.interactive && name === "ask_questions") {
+				upsertPendingQuestion(status, event.toolCallId, questionFromArgs(args));
+			} else if (pendingQuestions(status).length === 0) {
+				status.currentTool = { name, path: toolPath(args), summary: toolSummary(name, args) };
+				status.semanticState = "working";
+			}
+			preservePendingQuestion(status);
+			status.lastActivityAt = now;
+			// Unread is keyed off the latest assistant message, not intermediate tool churn.
+			meaningful = true;
+			break;
+		}
+		case "tool_execution_end": {
+			if (event.isError) status.error = `Tool ${event.toolName ?? ""} failed`.trim();
+			if (opts.interactive && event.toolName === "ask_questions") removePendingQuestion(status, event.toolCallId);
+			status.currentTool = null;
+			status.semanticState = "working";
+			status.question = null;
+			preservePendingQuestion(status);
+			status.lastActivityAt = now;
+			// Unread is keyed off the latest assistant message, not intermediate tool churn.
+			meaningful = true;
+			break;
+		}
+		case "message_start": {
+			if (event.message?.role === "assistant") {
+				status.semanticState = "working";
+				preservePendingQuestion(status);
+				status.lastActivityAt = now;
+			}
+			break;
+		}
+		case "message_end": {
+			const msg = event.message;
+			if (msg?.usage || event.usage) status.usage = mergeUsage(status.usage ?? null, msg?.usage ?? event.usage);
+			if (msg?.role === "assistant") {
+				status.turns += 1;
+				if (msg.model && !status.model) status.model = msg.model;
+				if (msg.stopReason) status.stopReason = msg.stopReason;
+				if (msg.errorMessage) status.error = msg.errorMessage;
+				else if (msg.stopReason === "stop") status.error = null;
+				const text = assistantText(msg);
+				if (text) {
+					// Store the full latest text (truncated) so peek shows meaningful output;
+					// deriveSummary() condenses it to a first sentence for the row.
+					status.latestAssistantPreview = truncate(text, PREVIEW_MAX);
+					const nb = detectNeedsInput(text);
+					status.question = nb.question;
+				}
+				status.semanticState = "working";
+				preservePendingQuestion(status);
+				status.lastActivityAt = now;
+				status.lastAgentActivityAt = now;
+				meaningful = true;
+			}
+			break;
+		}
+		case "agent_start":
+		case "turn_start":
+		case "turn_end":
+			status.lastActivityAt = now;
+			break;
+		default:
+			break;
+	}
+
+	if (meaningful) status.summary = deriveSummary(status);
+	return meaningful;
+}
+
+/**
+ * Mark a run finished and compute its terminal state + summary.
+ * @param {RunStatus} status
+ * @param {{ exitCode:number|null, stoppedByUser?:boolean, openEnded?:boolean }} opts
+ * @param {number} now
+ * @returns {RunStatus}
+ */
+export function finalizeRun(status, opts, now) {
+	status.endedAt = now;
+	status.exitCode = opts.exitCode;
+	status.processState = "exited";
+	status.pid = null;
+	status.stoppedByUser = Boolean(opts.stoppedByUser);
+	status.currentTool = null;
+
+	const hadPendingQuestions = pendingQuestions(status).length > 0;
+	status.pendingQuestions = [];
+	const nb = detectNeedsInput(status.latestAssistantPreview);
+	// An exited interactive tool can no longer accept an answer. Keep only an
+	// independently detected assistant question, never the stale tool prompt.
+	if (hadPendingQuestions) status.question = nb.question;
+	const needsInput = nb.needsInput || Boolean(status.question);
+	if (needsInput && !status.question) status.question = nb.question;
+
+	status.semanticState = finalizeSemanticState({
+		exitCode: status.exitCode,
+		stopReason: status.stopReason,
+		stoppedByUser: status.stoppedByUser,
+		needsInput,
+		openEnded: opts.openEnded,
+	});
+	status.lastActivityAt = now;
+	status.summary = deriveSummary(status);
+	return status;
+}
+
+/**
+ * Project a RunStatus into the row-level ViewState written to `state.json`.
+ * @param {RunStatus} status
+ * @param {number} now
+ * @returns {import("./types.mjs").ViewState}
+ */
+export function projectViewState(status, now, previousState = null) {
+	return {
+		version: 1,
+		viewId: status.viewId,
+		currentRunId: status.runId,
+		semanticState: status.semanticState,
+		processState: status.processState,
+		summary: status.summary,
+		lastActivityAt: status.lastActivityAt,
+		updatedAt: now,
+		needsInput: status.semanticState === "needs_input",
+		hasError: status.semanticState === "failed",
+		latestAssistantPreview: status.latestAssistantPreview,
+		latestTool: status.currentTool ? { name: status.currentTool.name, path: status.currentTool.path } : null,
+		question: status.question,
+		pendingQuestions: pendingQuestions(status),
+		error: status.error,
+		lastVisitedAt: previousState?.lastVisitedAt ?? null,
+		lastAgentActivityAt: status.lastAgentActivityAt ?? previousState?.lastAgentActivityAt ?? null,
+		review: status.evidenceSummary ?? previousState?.review,
+		diagnostics: previousState?.diagnostics,
+		autoState: status.autoState ?? previousState?.autoState ?? null,
+		followUps: previousState?.followUps,
+		steering: previousState?.steering,
+	};
+}
+
+/** @param {import("./types.mjs").RunStatus} status */
+function pendingQuestions(status) {
+	if (!Array.isArray(status.pendingQuestions)) status.pendingQuestions = [];
+	return status.pendingQuestions;
+}
+
+function questionFromArgs(args) {
+	for (const item of Array.isArray(args?.questions) ? args.questions : []) {
+		const question = String(item?.question ?? "").trim();
+		if (question) return question;
+	}
+	return "Answer the pending question";
+}
+
+function upsertPendingQuestion(status, toolCallId, question) {
+	const id = String(toolCallId ?? "ask_questions");
+	const pending = pendingQuestions(status);
+	const existing = pending.find((item) => item.toolCallId === id);
+	if (existing) existing.question = question;
+	else pending.push({ toolCallId: id, question });
+}
+
+function removePendingQuestion(status, toolCallId) {
+	const id = String(toolCallId ?? "ask_questions");
+	status.pendingQuestions = pendingQuestions(status).filter((item) => item.toolCallId !== id);
+}
+
+function preservePendingQuestion(status) {
+	const first = pendingQuestions(status)[0];
+	if (!first) return;
+	status.currentTool = null;
+	status.semanticState = "needs_input";
+	status.question = first.question;
+}
+
+/** @param {import("./types.mjs").EvidenceUsage|null} current @param {any} usage */
+function mergeUsage(current, usage) {
+	if (!usage || typeof usage !== "object") return current;
+	const input = Number(usage.inputTokens ?? usage.input_tokens ?? usage.prompt_tokens ?? 0) || 0;
+	const output = Number(usage.outputTokens ?? usage.output_tokens ?? usage.completion_tokens ?? 0) || 0;
+	const total = Number(usage.totalTokens ?? usage.total_tokens ?? input + output) || input + output;
+	return {
+		inputTokens: (current?.inputTokens ?? 0) + input,
+		outputTokens: (current?.outputTokens ?? 0) + output,
+		totalTokens: (current?.totalTokens ?? 0) + total,
+	};
+}

package/src/core/evidence.mjs

@@ -0,0 +1,242 @@
+/** Review evidence extraction and persistence helpers. */
+import { assistantText, classifyCommand, toolFileOperation, truncate } from "./heuristics.mjs";
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+
+/** @param {{ viewId:string, runId?:string|null, now?:number, source?:string }} opts @returns {import("./types.mjs").EvidenceSnapshot} */
+export function emptyEvidenceSnapshot(opts) {
+	const now = opts.now ?? Date.now();
+	return {
+		version: 1,
+		viewId: opts.viewId,
+		runId: opts.runId ?? null,
+		updatedAt: now,
+		outcome: "unknown",
+		ready: false,
+		summary: "",
+		commands: [],
+		fileChanges: [],
+		errors: [],
+		assistantEvidence: [],
+		usage: null,
+		eventCount: 0,
+		source: opts.source ?? "events",
+	};
+}
+
+/** @param {any} snapshot @param {{ viewId:string, runId?:string|null }} fallback @returns {import("./types.mjs").EvidenceSnapshot} */
+export function normalizeEvidenceSnapshot(snapshot, fallback) {
+	const base = emptyEvidenceSnapshot({ viewId: fallback.viewId, runId: fallback.runId ?? null });
+	if (!snapshot || typeof snapshot !== "object") return base;
+	return {
+		...base,
+		...snapshot,
+		viewId: typeof snapshot.viewId === "string" ? snapshot.viewId : base.viewId,
+		runId: typeof snapshot.runId === "string" ? snapshot.runId : (snapshot.runId === null ? null : base.runId),
+		commands: Array.isArray(snapshot.commands) ? snapshot.commands : [],
+		fileChanges: Array.isArray(snapshot.fileChanges) ? snapshot.fileChanges : [],
+		errors: Array.isArray(snapshot.errors) ? snapshot.errors : [],
+		assistantEvidence: Array.isArray(snapshot.assistantEvidence) ? snapshot.assistantEvidence : [],
+		usage: snapshot.usage && typeof snapshot.usage === "object" ? snapshot.usage : null,
+	};
+}
+
+/** @param {string} root @param {string} viewId */
+export function readEvidence(root, viewId) {
+	return normalizeEvidenceSnapshot(readJson(P.evidencePath(root, viewId), null), { viewId });
+}
+
+/** @param {string} root @param {import("./types.mjs").EvidenceSnapshot} snapshot */
+export function writeEvidence(root, snapshot) {
+	const normalized = normalizeEvidenceSnapshot(snapshot, { viewId: snapshot.viewId, runId: snapshot.runId ?? null });
+	normalized.updatedAt = Date.now();
+	atomicWriteJson(P.evidencePath(root, normalized.viewId), normalized);
+	return normalized;
+}
+
+/** @param {string} root @param {string} viewId @param {string} runId */
+export function readRunEvidence(root, viewId, runId) {
+	return normalizeEvidenceSnapshot(readJson(P.runEvidencePath(root, viewId, runId), null), { viewId, runId });
+}
+
+/** @param {string} root @param {import("./types.mjs").EvidenceSnapshot} snapshot */
+export function writeRunEvidence(root, snapshot) {
+	const normalized = normalizeEvidenceSnapshot(snapshot, { viewId: snapshot.viewId, runId: snapshot.runId ?? null });
+	normalized.updatedAt = Date.now();
+	if (normalized.runId) atomicWriteJson(P.runEvidencePath(root, normalized.viewId, normalized.runId), normalized);
+	return normalized;
+}
+
+/** @param {import("./types.mjs").EvidenceSnapshot} snapshot @returns {import("./types.mjs").ReviewSummary} */
+export function summarizeEvidence(snapshot) {
+	const s = normalizeEvidenceSnapshot(snapshot, { viewId: snapshot?.viewId ?? "" });
+	const failedCommandCount = s.commands.filter((c) => c.status === "failed").length;
+	const latestAssistantEvidence = s.assistantEvidence[s.assistantEvidence.length - 1]?.text ?? "";
+	return {
+		ready: Boolean(s.ready),
+		outcome: s.outcome ?? "unknown",
+		fileChangeCount: s.fileChanges.length,
+		commandCount: s.commands.length,
+		failedCommandCount,
+		errorCount: s.errors.length,
+		latestAssistantEvidence: truncate(latestAssistantEvidence, 180),
+		updatedAt: s.updatedAt ?? null,
+	};
+}
+
+/** @param {import("./types.mjs").EvidenceSnapshot} snapshot @param {Partial<import("./types.mjs").EvidenceCommand>} command */
+export function upsertEvidenceCommand(snapshot, command) {
+	const id = command.id ?? `cmd_${snapshot.commands.length + 1}`;
+	const existing = snapshot.commands.find((c) => c.id === id);
+	const commandText = String(command.command || existing?.command || "");
+	const next = {
+		id,
+		at: command.at ?? existing?.at ?? Date.now(),
+		command: commandText,
+		kind: command.kind ?? existing?.kind ?? classifyCommand(commandText),
+		status: command.status ?? existing?.status ?? "unknown",
+		exitCode: command.exitCode ?? existing?.exitCode ?? null,
+		durationMs: command.durationMs ?? existing?.durationMs ?? null,
+		outputPreview: command.outputPreview ?? existing?.outputPreview ?? "",
+	};
+	if (existing) Object.assign(existing, next);
+	else snapshot.commands.push(next);
+	snapshot.updatedAt = Date.now();
+	return next;
+}
+
+/** @param {import("./types.mjs").EvidenceSnapshot} snapshot @param {Partial<import("./types.mjs").EvidenceFileChange>} change */
+export function upsertEvidenceFileChange(snapshot, change) {
+	const p = String(change.path ?? "").trim();
+	if (!p) return null;
+	const existing = snapshot.fileChanges.find((f) => f.path === p);
+	const now = Date.now();
+	if (existing) {
+		existing.lastSeenAt = now;
+		existing.count = (existing.count ?? 0) + 1;
+		if (change.action) existing.action = change.action;
+		if (change.toolName) existing.toolName = change.toolName;
+		snapshot.updatedAt = now;
+		return existing;
+	}
+	const next = {
+		path: p,
+		action: change.action ?? "unknown",
+		toolName: change.toolName ?? null,
+		firstSeenAt: change.firstSeenAt ?? now,
+		lastSeenAt: change.lastSeenAt ?? now,
+		count: change.count ?? 1,
+	};
+	snapshot.fileChanges.push(next);
+	snapshot.updatedAt = now;
+	return next;
+}
+
+/** @param {import("./types.mjs").EvidenceSnapshot} snapshot @param {Partial<import("./types.mjs").EvidenceError>} error */
+export function recordEvidenceError(snapshot, error) {
+	const next = {
+		at: error.at ?? Date.now(),
+		source: error.source ?? "event",
+		message: String(error.message ?? "Unknown error"),
+		toolName: error.toolName ?? null,
+	};
+	snapshot.errors.push(next);
+	snapshot.updatedAt = next.at;
+	return next;
+}
+
+/** @param {import("./types.mjs").EvidenceSnapshot} snapshot @param {string} text @param {{ at?:number }} [opts] */
+export function recordAssistantEvidence(snapshot, text, opts = {}) {
+	const cleaned = String(text || "").replace(/\s+/g, " ").trim();
+	if (!cleaned) return null;
+	const next = { at: opts.at ?? Date.now(), text: truncate(cleaned, 12_000) };
+	snapshot.assistantEvidence.push(next);
+	snapshot.summary = truncate(cleaned, 240);
+	snapshot.updatedAt = next.at;
+	return next;
+}
+
+/** @param {import("./types.mjs").EvidenceSnapshot} base @param {import("./types.mjs").EvidenceSnapshot} incoming */
+export function mergeEvidenceSnapshot(base, incoming) {
+	for (const c of incoming.commands ?? []) upsertEvidenceCommand(base, c);
+	for (const f of incoming.fileChanges ?? []) upsertEvidenceFileChange(base, f);
+	for (const e of incoming.errors ?? []) recordEvidenceError(base, e);
+	for (const a of incoming.assistantEvidence ?? []) recordAssistantEvidence(base, a.text, { at: a.at });
+	base.outcome = incoming.outcome ?? base.outcome;
+	base.ready = Boolean(incoming.ready || base.ready);
+	base.usage = mergeUsage(base.usage, incoming.usage);
+	base.updatedAt = Date.now();
+	return base;
+}
+
+/** @param {import("./types.mjs").EvidenceSnapshot} snapshot @param {any} event @param {number} now */
+export function reduceEvidence(snapshot, event, now = Date.now()) {
+	if (!event || typeof event !== "object") return false;
+	snapshot.eventCount = (snapshot.eventCount ?? 0) + 1;
+	let changed = false;
+	if (event.type === "tool_execution_start") {
+		const name = event.toolName ?? event.args?.name ?? "tool";
+		const args = event.args ?? {};
+		if (name === "bash" && typeof args.command === "string") {
+			upsertEvidenceCommand(snapshot, { id: event.toolCallId, at: now, command: args.command, kind: classifyCommand(args.command), status: "started" });
+			changed = true;
+		}
+		const fileOp = toolFileOperation(name, args);
+		if (fileOp) {
+			upsertEvidenceFileChange(snapshot, { path: fileOp.path, action: fileOp.action, toolName: name, firstSeenAt: now, lastSeenAt: now });
+			changed = true;
+		}
+	} else if (event.type === "tool_execution_end") {
+		const name = event.toolName ?? "tool";
+		if (name === "bash") {
+			upsertEvidenceCommand(snapshot, {
+				id: event.toolCallId,
+				at: now,
+				command: event.args?.command ?? "",
+				status: event.isError ? "failed" : "passed",
+				exitCode: event.isError ? 1 : 0,
+				outputPreview: truncate(String(event.result ?? ""), 500),
+			});
+			changed = true;
+		}
+		if (event.isError) {
+			recordEvidenceError(snapshot, { at: now, source: "tool", toolName: name, message: `Tool ${name} failed` });
+			changed = true;
+		}
+	} else if (event.type === "message_end" && event.message?.role === "assistant") {
+		const text = assistantText(event.message);
+		if (text) {
+			recordAssistantEvidence(snapshot, text, { at: now });
+			changed = true;
+		}
+		snapshot.usage = mergeUsage(snapshot.usage, event.message?.usage ?? event.usage ?? null);
+	} else if (event.usage) {
+		snapshot.usage = mergeUsage(snapshot.usage, event.usage);
+		changed = true;
+	}
+	if (changed) snapshot.updatedAt = now;
+	return changed;
+}
+
+/** @param {import("./types.mjs").EvidenceSnapshot} snapshot @param {import("./types.mjs").RunStatus} status @param {number} now */
+export function finalizeEvidence(snapshot, status, now = Date.now()) {
+	snapshot.outcome = status.semanticState === "idle" ? "ready" : status.semanticState;
+	snapshot.ready = status.semanticState === "idle" || status.semanticState === "completed";
+	snapshot.usage = mergeUsage(snapshot.usage, status.usage ?? null);
+	snapshot.updatedAt = now;
+	return snapshot;
+}
+
+/** @param {import("./types.mjs").EvidenceUsage|null} a @param {any} b */
+function mergeUsage(a, b) {
+	if (!b || typeof b !== "object") return a ?? null;
+	const current = a ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+	const input = Number(b.inputTokens ?? b.input_tokens ?? b.prompt_tokens ?? 0) || 0;
+	const output = Number(b.outputTokens ?? b.output_tokens ?? b.completion_tokens ?? 0) || 0;
+	const total = Number(b.totalTokens ?? b.total_tokens ?? input + output) || input + output;
+	return {
+		inputTokens: (current.inputTokens ?? 0) + input,
+		outputTokens: (current.outputTokens ?? 0) + output,
+		totalTokens: (current.totalTokens ?? 0) + total,
+	};
+}