pi-crew 0.9.53 → 0.9.55

package/src/extension/notification-router.ts

@@ -0,0 +1,152 @@
+import { logInternalError } from "../utils/internal-error.ts";
+
+export type Severity = "info" | "warning" | "error" | "critical";
+
+export interface NotificationDescriptor {
+	id?: string;
+	severity: Severity;
+	source: string;
+	runId?: string;
+	title: string;
+	body?: string;
+	timestamp?: number;
+}
+
+export interface NotificationRouterOptions {
+	dedupWindowMs?: number;
+	batchWindowMs?: number;
+	quietHours?: string;
+	severityFilter?: Severity[];
+	sink?: (notification: NotificationDescriptor) => void;
+	now?: () => number;
+}
+
+const DEFAULT_SEVERITY_FILTER: Severity[] = ["warning", "error", "critical"];
+const SEVERITY_RANK: Record<Severity, number> = {
+	info: 0,
+	warning: 1,
+	error: 2,
+	critical: 3,
+};
+
+export function parseHHMMRange(range: string): {
+	startMin: number;
+	endMin: number;
+} {
+	const match = /^(\d{2}):(\d{2})-(\d{2}):(\d{2})$/.exec(range);
+	if (!match) throw new Error(`Invalid quiet-hours range '${range}'. Expected HH:MM-HH:MM.`);
+	const [, sh, sm, eh, em] = match;
+	const startHour = Number(sh);
+	const startMinute = Number(sm);
+	const endHour = Number(eh);
+	const endMinute = Number(em);
+	if (startHour > 23 || endHour > 23 || startMinute > 59 || endMinute > 59) throw new Error(`Invalid quiet-hours range '${range}'.`);
+	return {
+		startMin: startHour * 60 + startMinute,
+		endMin: endHour * 60 + endMinute,
+	};
+}
+
+export function isInQuietHours(range: string, now = new Date()): boolean {
+	const { startMin, endMin } = parseHHMMRange(range);
+	const current = now.getHours() * 60 + now.getMinutes();
+	if (startMin === endMin) return false;
+	return startMin <= endMin ? current >= startMin && current < endMin : current >= startMin || current < endMin;
+}
+
+function notificationKey(notification: NotificationDescriptor): string {
+	return notification.id ?? `${notification.source}:${notification.runId ?? "global"}:${notification.title}`;
+}
+
+function batchSeverity(items: NotificationDescriptor[]): Severity {
+	return items.reduce(
+		(highest, item) => (SEVERITY_RANK[item.severity] > SEVERITY_RANK[highest] ? item.severity : highest),
+		"info" as Severity,
+	);
+}
+
+export class NotificationRouter {
+	private readonly opts: NotificationRouterOptions;
+	private readonly deliver: (notification: NotificationDescriptor) => void;
+	private readonly seen = new Map<string, number>();
+	private batch: NotificationDescriptor[] = [];
+	private timer: ReturnType<typeof setTimeout> | undefined;
+	private static readonly SEEN_MAP_MAX_SIZE = 10000;
+
+	constructor(opts: NotificationRouterOptions = {}, deliver: (notification: NotificationDescriptor) => void) {
+		this.opts = opts;
+		this.deliver = deliver;
+	}
+
+	/**
+	 * Evict oldest entries from seen Map if it exceeds MAX_SIZE.
+	 * This prevents unbounded memory growth from notifications without TTL.
+	 */
+	private evictSeenIfNeeded(): void {
+		if (this.seen.size > NotificationRouter.SEEN_MAP_MAX_SIZE) {
+			// Sort by timestamp (oldest first) and keep only half
+			const entries = [...this.seen.entries()].sort((a, b) => a[1] - b[1]);
+			const keepCount = Math.floor(NotificationRouter.SEEN_MAP_MAX_SIZE / 2);
+			for (const [key] of entries.slice(0, entries.length - keepCount)) {
+				this.seen.delete(key);
+			}
+		}
+	}
+
+	enqueue(notification: NotificationDescriptor): boolean {
+		const now = this.opts.now?.() ?? Date.now();
+		const withTime = {
+			...notification,
+			timestamp: notification.timestamp ?? now,
+		};
+		try {
+			this.opts.sink?.(withTime);
+		} catch (sinkError) {
+			logInternalError("notification-sink", sinkError);
+		}
+		const filter = this.opts.severityFilter ?? DEFAULT_SEVERITY_FILTER;
+		if (!filter.includes(withTime.severity)) return false;
+		if (this.opts.quietHours && isInQuietHours(this.opts.quietHours, new Date(now))) return false;
+		const key = notificationKey(withTime);
+		const dedupWindow = this.opts.dedupWindowMs ?? 30_000;
+		const previous = this.seen.get(key);
+		if (previous !== undefined && now - previous < dedupWindow) return false;
+		this.seen.set(key, now);
+		this.evictSeenIfNeeded();
+		const batchWindow = this.opts.batchWindowMs ?? 0;
+		if (batchWindow <= 0) {
+			this.deliver(withTime);
+			return true;
+		}
+		this.batch.push(withTime);
+		if (!this.timer) this.timer = setTimeout(() => this.flush(), batchWindow);
+		return true;
+	}
+
+	flush(): void {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = undefined;
+		if (this.batch.length === 0) return;
+		const items = this.batch;
+		this.batch = [];
+		if (items.length === 1) {
+			this.deliver(items[0]!);
+			return;
+		}
+		this.deliver({
+			id: `batch:${items.map((item) => notificationKey(item)).join(",")}`,
+			severity: batchSeverity(items),
+			source: "batch",
+			title: `${items.length} pi-crew notifications`,
+			body: items.map((item) => `• ${item.title}`).join("\n"),
+			timestamp: this.opts.now?.() ?? Date.now(),
+		});
+	}
+
+	dispose(): void {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = undefined;
+		this.batch = [];
+		this.seen.clear();
+	}
+}

package/src/extension/notification-sink.ts

@@ -0,0 +1,54 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { logInternalError } from "../utils/internal-error.ts";
+import { redactSecrets } from "../utils/redaction.ts";
+import type { NotificationDescriptor } from "./notification-router.ts";
+
+export interface NotificationSink {
+	write(notification: NotificationDescriptor): void;
+	dispose(): void;
+}
+
+function rotateOldFiles(dir: string, retentionDays: number, now = Date.now()): void {
+	if (!fs.existsSync(dir)) return;
+	const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+		const filePath = path.join(dir, entry.name);
+		try {
+			if (fs.statSync(filePath).mtimeMs < cutoff) fs.unlinkSync(filePath);
+		} catch (error) {
+			logInternalError("notification-sink.rotate", error, filePath);
+		}
+	}
+}
+
+export function createJsonlSink(crewRoot: string, retentionDays = 7): NotificationSink {
+	const dir = path.join(crewRoot, "state", "notifications");
+	let lastRotateDate = "";
+	return {
+		write(notification: NotificationDescriptor): void {
+			try {
+				const timestamp = notification.timestamp ?? Date.now();
+				const date = new Date(timestamp).toISOString().slice(0, 10);
+				if (date !== lastRotateDate) {
+					rotateOldFiles(dir, retentionDays, timestamp);
+					lastRotateDate = date;
+				}
+				fs.mkdirSync(dir, { recursive: true });
+				const payload = redactSecrets({
+					...notification,
+					timestamp,
+				}) as NotificationDescriptor;
+				fs.appendFileSync(path.join(dir, `${date}.jsonl`), `${JSON.stringify(payload)}\n`, "utf-8");
+			} catch (error) {
+				logInternalError("notification-sink.write", error);
+			}
+		},
+		dispose(): void {
+			// Synchronous append-only sink has no resources to close.
+		},
+	};
+}
+
+export const __test__ = { rotateOldFiles };

package/src/extension/pi-api.ts

@@ -0,0 +1,56 @@
+/**
+ * pi-api.ts — pi-crew's stable seam against the Pi extension API.
+ *
+ * PURPOSE (roadmap Phase 0 / Pillar 4 "Pi-Native, Protocol-Aware"):
+ * Centralize every symbol pi-crew imports from
+ * `@earendil-works/pi-coding-agent` so that:
+ *   1. The coupling surface is auditable in ONE file (8 symbols today).
+ *   2. A Pi API rename/restructure requires updating only this seam.
+ *   3. New code imports from here ("./pi-api") rather than the raw package,
+ *      establishing the indirection that hedges Pi-coupling risk.
+ *
+ * COUpling SURFACE (kept intentionally small — public extension API only):
+ *   - ExtensionAPI              the registration entry point (pi)
+ *   - ExtensionContext          per-event/session context (ctx)
+ *   - ExtensionCommandContext   slash-command context
+ *   - ToolDefinition            tool schema type
+ *   - defineTool                tool factory
+ *   - createBashTool            built-in bash tool (for custom tooling)
+ *   - AgentSessionEvent         session event type
+ *   - BeforeAgentStartEvent     pre-turn system-prompt hook event
+ *
+ * NEW code should `import { ExtensionAPI, ExtensionContext } from "./pi-api"`.
+ * Existing files may keep their direct imports; migrate opportunistically
+ * (no big-bang refactor — see roadmap Phase 0 T0.3/T0.4 notes).
+ *
+ * Note: these are TYPE-level re-exports (erased at runtime). Runtime coupling
+ * to Pi is via the `pi` and `ctx` objects passed by Pi's loader — that is
+ * unavoidable and correct (pi-crew IS a Pi extension). This seam documents
+ * and centralizes the type-level surface.
+ */
+export type {
+	AgentSessionEvent,
+	BeforeAgentStartEvent,
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+export { createBashTool, defineTool } from "@earendil-works/pi-coding-agent";
+
+/**
+ * @deprecated Drift detector removed in Phase 5 follow-up to H1.
+ *
+ * History: this constant was meant to surface version-drift between
+ * dev-time type-check and runtime peer-dep version. pi-crew declares
+ * peer deps as `*` so the runtime version is set by whatever host pi
+ * install the user has — pinning this constant to a specific devDep
+ * range was a false invariant that did not reflect how extensions
+ * actually consume peer packages.
+ *
+ * Kept exported (now `"0.0.0-unset"`) only for any downstream consumers
+ * that may import it via re-exports. No diagnostic uses it anymore.
+ * Will be removed in a future major version.
+ */
+export const BUILT_AGAINST_PI_VERSION = "0.0.0-unset";

package/src/extension/plan-orchestrate.ts

@@ -0,0 +1,302 @@
+/**
+ * Plan Orchestrate — Decompose plan documents into agent chain commands.
+ *
+ * Parses tagged sections from markdown plan documents and builds commands
+ * for sequential agent chain execution based on ECC recommendations.
+ */
+
+import * as fs from "node:fs";
+
+/**
+ * Tag → Agent chain mapping from ECC recommendations.
+ */
+export const TAG_TO_CHAIN: Record<string, string[]> = {
+	design: ["planner", "architect"],
+	impl: ["tdd-guide", "lang-reviewer"],
+	security: ["security-reviewer", "lang-reviewer"],
+	build: ["build-error-resolver"],
+	test: ["test-engineer", "verifier"],
+	review: ["reviewer"],
+} as const;
+
+/**
+ * Options for plan orchestration.
+ */
+export interface OrchestrateOptions {
+	/** Path to the plan markdown document. */
+	planPath: string;
+}
+
+/**
+ * A single orchestrated step parsed from a plan section.
+ */
+export interface OrchestratedStep {
+	/** Unique step identifier. */
+	stepId: string;
+	/** Tag from the parsed section. */
+	tag: string;
+	/** Agent chain for this step. */
+	chain: string[];
+	/** Prompt/goal text extracted from the section. */
+	prompt: string;
+	/** Raw heading text if present. */
+	heading?: string;
+}
+
+/**
+ * Parse tagged sections from a plan markdown document.
+ *
+ * Expected format:
+ * ```markdown
+ * # Design Phase
+ * <!-- tag: design -->
+ * Design the authentication system...
+ *
+ * # Implementation
+ * <!-- tag: impl -->
+ * Implement the JWT auth...
+ * ```
+ *
+ * @param planPath - Path to the plan markdown document.
+ * @returns Array of OrchestratedStep parsed from the document.
+ */
+export function parsePlanDocument(planPath: string): OrchestratedStep[] {
+	if (!fs.existsSync(planPath)) {
+		throw new Error(`Plan document not found: ${planPath}`);
+	}
+
+	const content = fs.readFileSync(planPath, "utf-8");
+	return parsePlanDocumentContent(content);
+}
+
+/**
+ * Parse tagged sections from plan content string.
+ * This is the core parsing logic used by both parsePlanDocument and parsePlanDocumentSimple.
+ */
+function parsePlanDocumentContent(content: string): OrchestratedStep[] {
+	const steps: OrchestratedStep[] = [];
+
+	// Find all tag matches with their positions
+	const tagRegex = /<!--\s*tag:\s*(\w+)\s*-->/g;
+	const tagMatches: Array<{ tag: string; start: number; end: number }> = [];
+
+	let match: RegExpExecArray | null;
+	while ((match = tagRegex.exec(content)) !== null) {
+		tagMatches.push({
+			tag: match[1],
+			start: match.index,
+			end: match.index + match[0].length,
+		});
+	}
+
+	if (tagMatches.length === 0) {
+		return [];
+	}
+
+	// For each tag, extract the content before it (to get heading)
+	// and the content after it until either another tag or section
+	for (let i = 0; i < tagMatches.length; i++) {
+		const current = tagMatches[i];
+		const nextTagStart = i < tagMatches.length - 1 ? tagMatches[i + 1].start : content.length;
+
+		// Find the heading by looking back from the tag position.
+		// Use global regex to find ALL headings in the window, then take the LAST
+		// (nearest to the tag) — simple `.match()` only finds the FIRST heading.
+		const textBeforeTag = content.slice(Math.max(0, current.start - 500), current.start);
+		const headingRegex = /(^|\n)(#{1,6})\s+(.+?)(\n|$)/g;
+		let lastHeadingMatch: RegExpExecArray | null = null;
+		let hm: RegExpExecArray | null;
+		while ((hm = headingRegex.exec(textBeforeTag)) !== null) {
+			lastHeadingMatch = hm;
+		}
+		const heading = lastHeadingMatch ? lastHeadingMatch[3].trim() : undefined;
+
+		// Get content after the tag until next tag or heading
+		// Start from end of tag comment, skip any whitespace/newline
+		const afterTagContent = content.slice(current.end);
+
+		// Find the section content: capture until next heading (##) or next tag
+		const sectionEndMatch = afterTagContent.search(/(^|\n)(#{1,6}\s|\n<!--\s*tag:)/m);
+		const sectionContent = sectionEndMatch >= 0 ? afterTagContent.slice(0, sectionEndMatch) : afterTagContent;
+
+		// Extract prompt text - remove the tag comment lines and empty lines
+		const promptLines: string[] = [];
+		const lines = sectionContent.split("\n");
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("<!--")) continue;
+			promptLines.push(trimmed);
+		}
+
+		const prompt = promptLines.join("\n").trim();
+		if (!prompt) continue;
+
+		const chain = TAG_TO_CHAIN[current.tag] ?? [];
+
+		steps.push({
+			stepId: `step-${(i + 1).toString().padStart(2, "0")}-${current.tag}`,
+			tag: current.tag,
+			chain,
+			prompt,
+			heading,
+		});
+	}
+
+	return steps;
+}
+
+/**
+ * Alternative simpler parser for plans that use explicit tag blocks.
+ * Actually uses the same core logic as parsePlanDocument.
+ *
+ * @param planPath - Path to the plan markdown document.
+ * @returns Array of OrchestratedStep parsed from the document.
+ */
+export function parsePlanDocumentSimple(planPath: string): OrchestratedStep[] {
+	if (!fs.existsSync(planPath)) {
+		throw new Error(`Plan document not found: ${planPath}`);
+	}
+
+	const content = fs.readFileSync(planPath, "utf-8");
+	const steps = parsePlanDocumentContent(content);
+
+	if (steps.length === 0) {
+		// Try implicit detection
+		const tag = detectImplicitTag(content);
+		if (tag) {
+			return [
+				{
+					stepId: "step-01-unknown",
+					tag,
+					chain: TAG_TO_CHAIN[tag] ?? [],
+					prompt: content.trim(),
+				},
+			];
+		}
+	}
+
+	return steps;
+}
+
+/**
+ * Detect implicit tag from content keywords when no explicit tag is present.
+ */
+function detectImplicitTag(content: string): string | undefined {
+	const lowerContent = content.toLowerCase();
+	// Use word-boundary regex to avoid substring false matches.
+	// E.g., "implementation" must NOT trigger "impl" — only the word "implement" should.
+	const hasWord = (word: string): boolean => new RegExp(`\\b${word}\\b`).test(lowerContent);
+
+	if (hasWord("design") || hasWord("architecture")) return "design";
+	if (hasWord("implement") || hasWord("coding")) return "impl";
+	if (hasWord("security") || hasWord("audit")) return "security";
+	if (hasWord("build") || hasWord("compile")) return "build";
+	if (hasWord("test") || hasWord("verify")) return "test";
+	if (hasWord("review") || hasWord("feedback")) return "review";
+	return undefined;
+}
+
+/**
+ * Build agent chain command strings from orchestrated steps.
+ *
+ * @param steps - Array of OrchestratedStep to convert to commands.
+ * @returns Array of command strings for execution.
+ */
+export function buildAgentChain(steps: OrchestratedStep[]): string[] {
+	return steps.map((step) => {
+		const agentList = step.chain.join(",");
+		// Escape single quotes in the goal for shell safety
+		const escapedGoal = step.prompt.replace(/'/g, "'\\''");
+		return `team action='run' agent='${agentList}' goal='${escapedGoal}'`;
+	});
+}
+
+/**
+ * Build structured chain data (useful for programmatic use).
+ *
+ * @param steps - Array of OrchestratedStep to convert.
+ * @returns Array of chain objects with step data and commands.
+ */
+export function buildChainData(steps: OrchestratedStep[]): Array<{
+	step: OrchestratedStep;
+	commands: string[];
+}> {
+	return steps.map((step) => ({
+		step,
+		commands: buildAgentChain([step]),
+	}));
+}
+
+/**
+ * Parse and return a formatted overview of the plan.
+ *
+ * @param planPath - Path to the plan markdown document.
+ * @returns Summary string with step count and breakdown by tag.
+ */
+export function formatPlanOverview(planPath: string): string {
+	const steps = parsePlanDocument(planPath);
+
+	if (steps.length === 0) {
+		// Try simple parser
+		const simpleSteps = parsePlanDocumentSimple(planPath);
+		if (simpleSteps.length === 0) {
+			return "No tagged sections found in plan document.";
+		}
+		return formatStepsOverview(simpleSteps);
+	}
+
+	return formatStepsOverview(steps);
+}
+
+function formatStepsOverview(steps: OrchestratedStep[]): string {
+	const lines: string[] = [`Plan Orchestration: ${steps.length} step(s)`, ""];
+
+	const tagCounts: Record<string, number> = {};
+	for (const step of steps) {
+		tagCounts[step.tag] = (tagCounts[step.tag] ?? 0) + 1;
+	}
+
+	lines.push("Summary by tag:");
+	for (const [tag, count] of Object.entries(tagCounts)) {
+		const chain = TAG_TO_CHAIN[tag]?.join(", ") ?? "(unknown)";
+		lines.push(`  - ${tag}: ${count} step(s) → agents: ${chain}`);
+	}
+
+	lines.push("", "Steps:");
+	for (const step of steps) {
+		const preview = step.prompt.length > 60 ? step.prompt.slice(0, 60) + "..." : step.prompt;
+		// Include heading if available (e.g., "Security Review" from the plan's heading)
+		const headingPrefix = step.heading ? `${step.heading}: ` : "";
+		lines.push(`  ${step.stepId} [${step.tag}] ${step.chain.join(",")}: ${headingPrefix}${preview}`);
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Main orchestration function that parses a plan and returns pre-formatted output.
+ */
+export async function orchestratePlan(options: OrchestrateOptions): Promise<{
+	steps: OrchestratedStep[];
+	chain: string[];
+	overview: string;
+}> {
+	const { planPath } = options;
+
+	// Try primary parser first
+	let steps = parsePlanDocument(planPath);
+
+	// Fall back to simple parser if no results
+	if (steps.length === 0) {
+		steps = parsePlanDocumentSimple(planPath);
+	}
+
+	if (steps.length === 0) {
+		throw new Error(`No tagged sections found in plan document: ${planPath}`);
+	}
+
+	const chain = buildAgentChain(steps);
+	const overview = formatPlanOverview(planPath);
+
+	return { steps, chain, overview };
+}