pi-crew 0.1.51 → 0.2.1

package/src/runtime/live-session-health.ts

@@ -1,100 +1,100 @@
-/**
- * Phase 8: Monitoring and observability for live-session workers.
- *
- * Provides health checks, metrics collection, and diagnostics
- * for live-session workers running in-process.
- */
-
-export interface LiveSessionHealth {
-	/** Total number of registered live agents. */
-	totalAgents: number;
-	/** Number of agents currently running. */
-	runningAgents: number;
-	/** Number of agents in idle state. */
-	idleAgents: number;
-	/** Number of agents that have completed. */
-	completedAgents: number;
-	/** Number of agents that have failed. */
-	failedAgents: number;
-	/** Total tokens consumed across all live sessions. */
-	totalTokens: number;
-	/** Timestamp of this health snapshot. */
-	timestamp: string;
-}
-
-export interface LiveSessionMetrics {
-	agentId: string;
-	taskId: string;
-	status: string;
-	/** Accumulated usage from session stats. */
-	usage?: {
-		input?: number;
-		output?: number;
-		cacheRead?: number;
-		cacheWrite?: number;
-		cost?: number;
-		turns?: number;
-	};
-	/** Session duration in milliseconds. */
-	durationMs?: number;
-	/** Number of IRC messages received. */
-	ircMessagesReceived?: number;
-	/** Number of yield reminders sent. */
-	yieldReminders?: number;
-	/** Whether yield was called. */
-	yieldCalled: boolean;
-}
-
-/**
- * Collect health snapshot from live agent handles.
- */
-export function collectLiveSessionHealth(
-	agents: Array<{ status: string }>,
-	getUsage: (agentId: string) => { input?: number; output?: number; turns?: number } | undefined,
-): LiveSessionHealth {
-	let running = 0;
-	let idle = 0;
-	let completed = 0;
-	let failed = 0;
-	let totalTokens = 0;
-
-	for (const agent of agents) {
-		switch (agent.status) {
-			case "running": running++; break;
-			case "idle": idle++; break;
-			case "completed": completed++; break;
-			case "failed": failed++; break;
-		}
-	}
-
-	// Sum tokens from usage data
-	for (const agent of agents) {
-		const agentAny = agent as Record<string, unknown>;
-		const agentId = agentAny.agentId as string | undefined;
-		if (agentId) {
-			const usage = getUsage(agentId);
-			if (usage) {
-				totalTokens += (usage.input ?? 0) + (usage.output ?? 0);
-			}
-		}
-	}
-
-	return {
-		totalAgents: agents.length,
-		runningAgents: running,
-		idleAgents: idle,
-		completedAgents: completed,
-		failedAgents: failed,
-		totalTokens,
-		timestamp: new Date().toISOString(),
-	};
-}
-
-/**
- * Build a diagnostic summary string for logging.
- */
-export function formatLiveSessionDiagnostics(health: LiveSessionHealth): string {
-	return [
-		`[Live-Session Health] agents=${health.totalAgents} running=${health.runningAgents} idle=${health.idleAgents} completed=${health.completedAgents} failed=${health.failedAgents} tokens=${health.totalTokens}`,
-	].join("\n");
-}
+/**
+ * Phase 8: Monitoring and observability for live-session workers.
+ *
+ * Provides health checks, metrics collection, and diagnostics
+ * for live-session workers running in-process.
+ */
+
+export interface LiveSessionHealth {
+	/** Total number of registered live agents. */
+	totalAgents: number;
+	/** Number of agents currently running. */
+	runningAgents: number;
+	/** Number of agents in idle state. */
+	idleAgents: number;
+	/** Number of agents that have completed. */
+	completedAgents: number;
+	/** Number of agents that have failed. */
+	failedAgents: number;
+	/** Total tokens consumed across all live sessions. */
+	totalTokens: number;
+	/** Timestamp of this health snapshot. */
+	timestamp: string;
+}
+
+export interface LiveSessionMetrics {
+	agentId: string;
+	taskId: string;
+	status: string;
+	/** Accumulated usage from session stats. */
+	usage?: {
+		input?: number;
+		output?: number;
+		cacheRead?: number;
+		cacheWrite?: number;
+		cost?: number;
+		turns?: number;
+	};
+	/** Session duration in milliseconds. */
+	durationMs?: number;
+	/** Number of IRC messages received. */
+	ircMessagesReceived?: number;
+	/** Number of yield reminders sent. */
+	yieldReminders?: number;
+	/** Whether yield was called. */
+	yieldCalled: boolean;
+}
+
+/**
+ * Collect health snapshot from live agent handles.
+ */
+export function collectLiveSessionHealth(
+	agents: Array<{ status: string }>,
+	getUsage: (agentId: string) => { input?: number; output?: number; turns?: number } | undefined,
+): LiveSessionHealth {
+	let running = 0;
+	let idle = 0;
+	let completed = 0;
+	let failed = 0;
+	let totalTokens = 0;
+
+	for (const agent of agents) {
+		switch (agent.status) {
+			case "running": running++; break;
+			case "idle": idle++; break;
+			case "completed": completed++; break;
+			case "failed": failed++; break;
+		}
+	}
+
+	// Sum tokens from usage data
+	for (const agent of agents) {
+		const agentAny = agent as Record<string, unknown>;
+		const agentId = agentAny.agentId as string | undefined;
+		if (agentId) {
+			const usage = getUsage(agentId);
+			if (usage) {
+				totalTokens += (usage.input ?? 0) + (usage.output ?? 0);
+			}
+		}
+	}
+
+	return {
+		totalAgents: agents.length,
+		runningAgents: running,
+		idleAgents: idle,
+		completedAgents: completed,
+		failedAgents: failed,
+		totalTokens,
+		timestamp: new Date().toISOString(),
+	};
+}
+
+/**
+ * Build a diagnostic summary string for logging.
+ */
+export function formatLiveSessionDiagnostics(health: LiveSessionHealth): string {
+	return [
+		`[Live-Session Health] agents=${health.totalAgents} running=${health.runningAgents} idle=${health.idleAgents} completed=${health.completedAgents} failed=${health.failedAgents} tokens=${health.totalTokens}`,
+	].join("\n");
+}

package/src/runtime/loop-gates.ts

@@ -0,0 +1,129 @@
+/**
+ * Dual-gate loop control — determines whether a task should auto-resume
+ * based on meaningful progress and turn limits.
+ *
+ * Gate 1: At least one signal of meaningful progress must be true.
+ * Gate 2: The auto-resume turn count must be below the maximum.
+ *
+ * Distilled from pi-autoresearch's dual-gate loop pattern.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamTaskState } from "../state/types.ts";
+
+/**
+ * Signal indicating what kind of progress a task has made.
+ */
+export interface TaskProgressSignal {
+	/** Whether the task has edited files or produced non-empty results. */
+	editedFiles: boolean;
+	/** Whether the task has produced artifacts in the artifacts directory. */
+	producedArtifacts: boolean;
+	/** Whether the task has run tests (detected via result text). */
+	ranTests: boolean;
+}
+
+/**
+ * Runtime state for auto-resume turn tracking.
+ */
+export interface AutoResumeRuntime {
+	/** Current number of auto-resume turns taken. */
+	autoResumeTurns: number;
+	/** Maximum allowed auto-resume turns. */
+	maxTurns: number;
+}
+
+/** Keywords in result text that indicate tests were run. */
+const TEST_KEYWORDS = [
+	"test passed",
+	"test failed",
+	"tests passed",
+	"tests failed",
+	"test results",
+	"jest",
+	"vitest",
+	"mocha",
+	"pytest",
+	"npx test",
+	"npm test",
+	"cargo test",
+	"all tests",
+	"test suite",
+	"✓",
+	"✗",
+	"PASS ",
+	" FAIL ",
+] as const;
+
+/**
+ * Determine whether a task should auto-resume based on dual-gate logic.
+ *
+ * Gate 1 (meaningful progress): at least one of editedFiles, producedArtifacts,
+ *   or ranTests must be true.
+ * Gate 2 (turn limit): autoResumeTurns must be strictly less than maxTurns.
+ *
+ * Both gates must pass for auto-resume to be allowed.
+ */
+export function shouldAutoResume(runtime: AutoResumeRuntime, taskProgress: TaskProgressSignal): boolean {
+	// Gate 2: Turn limit check (check first — cheaper)
+	if (runtime.autoResumeTurns >= runtime.maxTurns) {
+		return false;
+	}
+
+	// Gate 1: Meaningful progress check
+	const hasProgress = taskProgress.editedFiles || taskProgress.producedArtifacts || taskProgress.ranTests;
+	if (!hasProgress) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Compute the task progress signal from a task's state and artifacts directory.
+ *
+ * - editedFiles: true if task has artifact files or a non-empty result
+ * - producedArtifacts: true if artifacts directory contains task-specific files
+ * - ranTests: true if result text contains test-related keywords
+ *
+ * @param task - The task state to analyze
+ * @param artifactsDir - Path to the artifacts directory
+ * @returns TaskProgressSignal indicating what progress was made
+ */
+export function computeTaskProgressSignal(task: TeamTaskState, artifactsDir: string): TaskProgressSignal {
+	// editedFiles: check if task has artifact descriptors or a non-empty result
+	const hasResultArtifact = task.resultArtifact !== undefined;
+	const hasNonEmptyResult = task.resultArtifact?.path !== undefined;
+	const editedFiles = hasResultArtifact || hasNonEmptyResult;
+
+	// producedArtifacts: check artifacts directory for task-specific files
+	let producedArtifacts = false;
+	if (artifactsDir && fs.existsSync(artifactsDir)) {
+		try {
+			const entries = fs.readdirSync(artifactsDir);
+			// Look for files/directories that START with the task ID prefix.
+			// Using startsWith instead of includes to avoid false positives
+			// from short task IDs like "01" matching unrelated entries.
+			const taskPrefix = task.id.replace(/[^a-zA-Z0-9_-]/g, "");
+			producedArtifacts = entries.some((entry) => {
+				const baseName = entry.split(".")[0] ?? entry;
+				return baseName.startsWith(taskPrefix);
+			});
+		} catch {
+			producedArtifacts = false;
+		}
+	}
+
+	// ranTests: check if result-related fields contain test keywords
+	let ranTests = false;
+	const textToSearch = [
+		task.error ?? "",
+		task.terminalEvidence ? JSON.stringify(task.terminalEvidence) : "",
+		task.diagnostics ? JSON.stringify(task.diagnostics) : "",
+	].join(" ");
+
+	const lowerText = textToSearch.toLowerCase();
+	ranTests = TEST_KEYWORDS.some((keyword) => lowerText.includes(keyword.toLowerCase()));
+
+	return { editedFiles, producedArtifacts, ranTests };
+}

package/src/runtime/metric-parser.ts

@@ -0,0 +1,40 @@
+/**
+ * Metric names that are denied to prevent prototype pollution.
+ */
+export const DENIED_METRIC_NAMES: ReadonlySet<string> = new Set([
+	"__proto__",
+	"constructor",
+	"prototype",
+]);
+
+const METRIC_LINE_RE = /^CREW_METRIC\s+(\w+)=(\S+)$/;
+
+/**
+ * Parse CREW_METRIC lines from worker stdout.
+ *
+ * Lines must match the pattern: `CREW_METRIC name=value`
+ * - `name` must be a word character sequence (alphanumeric + underscore)
+ * - `value` must parse as a valid finite number
+ * - Denied names (__proto__, constructor, prototype) are silently skipped
+ *
+ * @param output - Raw worker stdout text
+ * @returns Map of metric name → numeric value
+ */
+export function parseMetricLines(output: string): Record<string, number> {
+	const metrics: Record<string, number> = {};
+
+	for (const line of output.split("\n")) {
+		const match = METRIC_LINE_RE.exec(line);
+		if (!match) continue;
+
+		const [, name, rawValue] = match;
+		if (DENIED_METRIC_NAMES.has(name)) continue;
+
+		const value = Number(rawValue);
+		if (!Number.isFinite(value)) continue;
+
+		metrics[name] = value;
+	}
+
+	return metrics;
+}

package/src/runtime/notebook-helpers.ts

@@ -1,90 +1,90 @@
-export interface NotebookCell {
-  index: number;
-  cellType: "code" | "markdown" | "raw";
-  source: string;
-  outputs?: unknown[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface Notebook {
-  cells: NotebookCell[];
-  metadata?: Record<string, unknown>;
-  nbformat: number;
-}
-
-/** Check if a file path is a notebook */
-export function isNotebookPath(filePath: string): boolean {
-  return filePath.toLowerCase().endsWith(".ipynb");
-}
-
-function normalizeSource(source: unknown): string {
-  if (typeof source === "string") return source;
-  if (Array.isArray(source)) return source.join("");
-  return "";
-}
-
-/** Parse a .ipynb JSON file into a Notebook structure */
-export function parseNotebook(content: string): Notebook {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(content);
-  } catch {
-    return { cells: [], nbformat: 4 };
-  }
-  if (typeof raw !== "object" || raw === null) return { cells: [], nbformat: 4 };
-  const obj = raw as Record<string, unknown>;
-  const nbformat = typeof obj.nbformat === "number" ? obj.nbformat : 4;
-  const rawCells = Array.isArray(obj.cells) ? obj.cells : [];
-  const cells: NotebookCell[] = rawCells
-    .map((c: unknown, i: number): NotebookCell | null => {
-      if (typeof c !== "object" || c === null) return null;
-      const cell = c as Record<string, unknown>;
-      const cellType = cell.cell_type;
-      if (cellType !== "code" && cellType !== "markdown" && cellType !== "raw") return null;
-      return {
-        index: i,
-        cellType,
-        source: normalizeSource(cell.source),
-        outputs: Array.isArray(cell.outputs) ? cell.outputs : undefined,
-        metadata:
-          cell.metadata && typeof cell.metadata === "object" && !Array.isArray(cell.metadata)
-            ? (cell.metadata as Record<string, unknown>)
-            : undefined,
-      };
-    })
-    .filter((c: NotebookCell | null): c is NotebookCell => c !== null);
-  const metadata =
-    obj.metadata && typeof obj.metadata === "object" && !Array.isArray(obj.metadata)
-      ? (obj.metadata as Record<string, unknown>)
-      : undefined;
-  return { cells, metadata, nbformat };
-}
-
-/** Get a specific cell by index */
-export function getCell(notebook: Notebook, index: number): NotebookCell | undefined {
-  return notebook.cells.find((c) => c.index === index);
-}
-
-/** Update a cell's source content, returning a new Notebook */
-export function updateCell(notebook: Notebook, index: number, source: string): Notebook {
-  const cells = notebook.cells.map((c) =>
-    c.index === index ? { ...c, source } : c,
-  );
-  return { ...notebook, cells };
-}
-
-/** Serialize a Notebook back to .ipynb JSON string */
-export function serializeNotebook(notebook: Notebook): string {
-  const raw = {
-    nbformat: notebook.nbformat,
-    nbformat_minor: 5,
-    metadata: notebook.metadata ?? {},
-    cells: notebook.cells.map((c) => ({
-      cell_type: c.cellType,
-      source: c.source,
-      metadata: c.metadata ?? {},
-      ...(c.cellType === "code" ? { outputs: c.outputs ?? [], execution_count: null } : {}),
-    })),
-  };
-  return JSON.stringify(raw, null, 2) + "\n";
-}
+export interface NotebookCell {
+  index: number;
+  cellType: "code" | "markdown" | "raw";
+  source: string;
+  outputs?: unknown[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface Notebook {
+  cells: NotebookCell[];
+  metadata?: Record<string, unknown>;
+  nbformat: number;
+}
+
+/** Check if a file path is a notebook */
+export function isNotebookPath(filePath: string): boolean {
+  return filePath.toLowerCase().endsWith(".ipynb");
+}
+
+function normalizeSource(source: unknown): string {
+  if (typeof source === "string") return source;
+  if (Array.isArray(source)) return source.join("");
+  return "";
+}
+
+/** Parse a .ipynb JSON file into a Notebook structure */
+export function parseNotebook(content: string): Notebook {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(content);
+  } catch {
+    return { cells: [], nbformat: 4 };
+  }
+  if (typeof raw !== "object" || raw === null) return { cells: [], nbformat: 4 };
+  const obj = raw as Record<string, unknown>;
+  const nbformat = typeof obj.nbformat === "number" ? obj.nbformat : 4;
+  const rawCells = Array.isArray(obj.cells) ? obj.cells : [];
+  const cells: NotebookCell[] = rawCells
+    .map((c: unknown, i: number): NotebookCell | null => {
+      if (typeof c !== "object" || c === null) return null;
+      const cell = c as Record<string, unknown>;
+      const cellType = cell.cell_type;
+      if (cellType !== "code" && cellType !== "markdown" && cellType !== "raw") return null;
+      return {
+        index: i,
+        cellType,
+        source: normalizeSource(cell.source),
+        outputs: Array.isArray(cell.outputs) ? cell.outputs : undefined,
+        metadata:
+          cell.metadata && typeof cell.metadata === "object" && !Array.isArray(cell.metadata)
+            ? (cell.metadata as Record<string, unknown>)
+            : undefined,
+      };
+    })
+    .filter((c: NotebookCell | null): c is NotebookCell => c !== null);
+  const metadata =
+    obj.metadata && typeof obj.metadata === "object" && !Array.isArray(obj.metadata)
+      ? (obj.metadata as Record<string, unknown>)
+      : undefined;
+  return { cells, metadata, nbformat };
+}
+
+/** Get a specific cell by index */
+export function getCell(notebook: Notebook, index: number): NotebookCell | undefined {
+  return notebook.cells.find((c) => c.index === index);
+}
+
+/** Update a cell's source content, returning a new Notebook */
+export function updateCell(notebook: Notebook, index: number, source: string): Notebook {
+  const cells = notebook.cells.map((c) =>
+    c.index === index ? { ...c, source } : c,
+  );
+  return { ...notebook, cells };
+}
+
+/** Serialize a Notebook back to .ipynb JSON string */
+export function serializeNotebook(notebook: Notebook): string {
+  const raw = {
+    nbformat: notebook.nbformat,
+    nbformat_minor: 5,
+    metadata: notebook.metadata ?? {},
+    cells: notebook.cells.map((c) => ({
+      cell_type: c.cellType,
+      source: c.source,
+      metadata: c.metadata ?? {},
+      ...(c.cellType === "code" ? { outputs: c.outputs ?? [], execution_count: null } : {}),
+    })),
+  };
+  return JSON.stringify(raw, null, 2) + "\n";
+}

package/src/runtime/orphan-sentinel.ts

@@ -1,7 +1,7 @@
-/**
- * Orphan sentinel — DEPRECATED, replaced by parent-guard.ts.
- *
- * Keeping this file as a no-op placeholder until all references are removed.
- * Workers now self-monitor via startParentGuard() instead of relying on
- * an external sentinel process.
- */
+/**
+ * Orphan sentinel — DEPRECATED, replaced by parent-guard.ts.
+ *
+ * Keeping this file as a no-op placeholder until all references are removed.
+ * Workers now self-monitor via startParentGuard() instead of relying on
+ * an external sentinel process.
+ */

package/src/runtime/parallel-research.ts

@@ -1,44 +1,44 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
-
-export function sourcePiProjects(cwd: string): string[] {
-	const sourceDir = path.join(cwd, "Source");
-	try {
-		return fs.readdirSync(sourceDir, { withFileTypes: true })
-			.filter((entry) => entry.isDirectory() && entry.name.startsWith("pi-"))
-			.map((entry) => `Source/${entry.name}`)
-			.sort();
-	} catch {
-		return [];
-	}
-}
-
-export function chunkProjects(projects: string[], target = 6): string[][] {
-	const chunks = Array.from({ length: Math.min(Math.max(1, target), Math.max(1, projects.length)) }, () => [] as string[]);
-	projects.forEach((project, index) => chunks[index % chunks.length]!.push(project));
-	return chunks.filter((chunk) => chunk.length > 0);
-}
-
-export function expandParallelResearchWorkflow(workflow: WorkflowConfig, cwd: string): WorkflowConfig {
-	if (workflow.name !== "parallel-research") return workflow;
-	const projects = sourcePiProjects(cwd);
-	if (projects.length === 0) return workflow;
-	const chunks = chunkProjects(projects, Math.min(8, Math.max(4, Math.ceil(projects.length / 3))));
-	const exploreSteps: WorkflowStep[] = chunks.map((paths, index) => ({
-		id: `explore-shard-${index + 1}`,
-		role: "explorer",
-		parallelGroup: "explore",
-		reads: paths,
-		task: [`Explore this dynamic shard for: {goal}`, "", "Paths:", ...paths.map((item) => `- ${item}`), "", "Focus on purpose, architecture, runtime/UI patterns, package config, docs, and lessons for pi-crew."].join("\n"),
-	}));
-	return {
-		...workflow,
-		steps: [
-			{ id: "discover", role: "explorer", parallelGroup: "inventory", task: `Quickly inventory and validate ${projects.length} pi-* projects for: {goal}\n\nProjects:\n${projects.map((item) => `- ${item}`).join("\n")}\n\nDo not block shard work; summarize routing notes only.` },
-			...exploreSteps,
-			{ id: "synthesize", role: "analyst", dependsOn: exploreSteps.map((step) => step.id), task: "Synthesize all dynamic shard findings. Identify common patterns, gaps, and concrete recommendations. Use discover output if available, but prioritize completed shard outputs." },
-			{ id: "write", role: "writer", dependsOn: ["synthesize"], output: "research-summary.md", task: "Write a concise final summary with evidence, risks, and actionable next steps." },
-		],
-	};
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+
+export function sourcePiProjects(cwd: string): string[] {
+	const sourceDir = path.join(cwd, "Source");
+	try {
+		return fs.readdirSync(sourceDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && entry.name.startsWith("pi-"))
+			.map((entry) => `Source/${entry.name}`)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+export function chunkProjects(projects: string[], target = 6): string[][] {
+	const chunks = Array.from({ length: Math.min(Math.max(1, target), Math.max(1, projects.length)) }, () => [] as string[]);
+	projects.forEach((project, index) => chunks[index % chunks.length]!.push(project));
+	return chunks.filter((chunk) => chunk.length > 0);
+}
+
+export function expandParallelResearchWorkflow(workflow: WorkflowConfig, cwd: string): WorkflowConfig {
+	if (workflow.name !== "parallel-research") return workflow;
+	const projects = sourcePiProjects(cwd);
+	if (projects.length === 0) return workflow;
+	const chunks = chunkProjects(projects, Math.min(8, Math.max(4, Math.ceil(projects.length / 3))));
+	const exploreSteps: WorkflowStep[] = chunks.map((paths, index) => ({
+		id: `explore-shard-${index + 1}`,
+		role: "explorer",
+		parallelGroup: "explore",
+		reads: paths,
+		task: [`Explore this dynamic shard for: {goal}`, "", "Paths:", ...paths.map((item) => `- ${item}`), "", "Focus on purpose, architecture, runtime/UI patterns, package config, docs, and lessons for pi-crew."].join("\n"),
+	}));
+	return {
+		...workflow,
+		steps: [
+			{ id: "discover", role: "explorer", parallelGroup: "inventory", task: `Quickly inventory and validate ${projects.length} pi-* projects for: {goal}\n\nProjects:\n${projects.map((item) => `- ${item}`).join("\n")}\n\nDo not block shard work; summarize routing notes only.` },
+			...exploreSteps,
+			{ id: "synthesize", role: "analyst", dependsOn: exploreSteps.map((step) => step.id), task: "Synthesize all dynamic shard findings. Identify common patterns, gaps, and concrete recommendations. Use discover output if available, but prioritize completed shard outputs." },
+			{ id: "write", role: "writer", dependsOn: ["synthesize"], output: "research-summary.md", task: "Write a concise final summary with evidence, risks, and actionable next steps." },
+		],
+	};
+}