pi-crew 0.5.1 → 0.5.2

package/src/schema/team-tool-schema.ts

@@ -65,6 +65,9 @@ export const TeamToolParams = Type.Object({
 				Type.Literal("cache"),
 				Type.Literal("checkpoint"),
 				Type.Literal("search"),
+				Type.Literal("orchestrate"),
+				Type.Literal("schedule"),
+				Type.Literal("scheduled"),
 			],
 			{ description: "Team action. Defaults to 'list' when omitted." },
 		),
@@ -189,6 +192,18 @@ export const TeamToolParams = Type.Object({
 	replyDeadline: Type.Optional(
 		Type.Integer({ description: "Ms epoch deadline for a reply." }),
 	),
+	planPath: Type.Optional(
+		Type.String({ description: "Path to a markdown plan document for orchestration." }),
+	),
+	cron: Type.Optional(
+		Type.String({ description: "Cron expression for recurring scheduled runs (e.g., '0 9 * * MON')." }),
+	),
+	interval: Type.Optional(
+		Type.Number({ description: "Interval in milliseconds between recurring scheduled runs." }),
+	),
+	once: Type.Optional(
+		Type.Union([Type.String(), Type.Number()], { description: "ISO timestamp or epoch ms for a one-time scheduled run." }),
+	),
 });
 
 export interface TeamToolParamsValue {
@@ -234,7 +249,10 @@ export interface TeamToolParamsValue {
 		| "explain"
 		| "cache"
 		| "checkpoint"
-		| "search";
+		| "search"
+		| "orchestrate"
+		| "schedule"
+		| "scheduled";
 	resource?: "agent" | "team" | "workflow";
 	team?: string;
 	workflow?: string;
@@ -264,4 +282,9 @@ export interface TeamToolParamsValue {
 	replyFrom?: string;
 	/** Ms epoch deadline for a reply. */
 	replyDeadline?: number;
+	/** Path to a markdown plan document for orchestration. */
+	planPath?: string;
+	cron?: string;
+	interval?: number;
+	once?: string | number;
 }

package/src/state/crew-init.ts

@@ -2,12 +2,19 @@
  * Auto-initialize .crew directory structure and .gitignore entries.
  * Called on first team run in a workspace to ensure all required
  * directories and files exist.
+ *
+ * IMPORTANT: This module must be COMPLETELY self-contained with NO dependencies
+ * on other pi-crew modules (especially paths.ts). It is called via dynamic
+ * import from child-process contexts (background runners, subagents) where
+ * module binding can fail. Keep this file minimal and self-contained.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { projectCrewRoot } from "../utils/paths.ts";
 import { updateGitignore } from "./gitignore-manager.ts";
 
+// Re-export updateGitignore for backwards compatibility with tests.
+export { updateGitignore };
+
 /** README content for the .crew directory. */
 const CREW_README = `# .crew — pi-crew Runtime Directory
 
@@ -37,15 +44,57 @@ team action='cache' action='clear'
 \`\`\`
 `;
 
+/**
+ * Find the project root by walking up from start directory.
+ * Inline implementation to avoid module dependency on paths.ts.
+ * Matches the logic in src/utils/paths.ts:computeRepoRoot().
+ */
+function findProjectRoot(start: string): string | undefined {
+	const dirMarkers = [".git", ".hg", ".svn"];
+	const fileMarkers = ["package.json", "pyproject.toml", "Cargo.toml", "go.mod"];
+	const root = path.parse(start).root;
+	let current = path.resolve(start);
+	// Walk up to find project root
+	while (current !== root) {
+		for (const marker of dirMarkers) {
+			if (fs.existsSync(path.join(current, marker))) return current;
+		}
+		for (const marker of fileMarkers) {
+			if (fs.existsSync(path.join(current, marker))) return current;
+		}
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	// Check root as fallback
+	if (dirMarkers.some((m) => fs.existsSync(path.join(root, m)))) return root;
+	return undefined;
+}
+
+/**
+ * Compute the crew root directory for a given working directory.
+ * Matches src/utils/paths.ts:projectCrewRoot() logic.
+ */
+function computeCrewRoot(cwd: string): string {
+	const repoRoot = findProjectRoot(cwd) ?? cwd;
+	const crewDir = path.join(repoRoot, ".crew");
+	// Keep existing .crew/ stable even when .pi/ exists for project config.
+	if (fs.existsSync(crewDir)) return crewDir;
+	// Legacy reuse: if .pi/ already exists, namespace under .pi/teams/
+	const piDir = path.join(repoRoot, ".pi");
+	return fs.existsSync(piDir) ? path.join(piDir, "teams") : crewDir;
+}
+
 /**
  * Ensure the .crew directory structure exists with all required subdirectories,
  * placeholder files, README, and .gitignore entries.
  *
- * Uses `projectCrewRoot()` to resolve the correct root (`.crew/` or `.pi/teams/`
- * for legacy projects). Idempotent — safe to call multiple times.
+ * This function is self-contained with NO dependencies on other pi-crew modules.
+ * It uses inline implementations of findProjectRoot and computeCrewRoot to avoid
+ * module binding issues in child-process contexts.
  */
 export async function ensureCrewDirectory(cwd: string): Promise<void> {
-	const crewRoot = projectCrewRoot(cwd);
+	const crewRoot = computeCrewRoot(cwd);
 
 	// 1. Create directory structure
 	const dirs = [
@@ -81,41 +130,10 @@ export async function ensureCrewDirectory(cwd: string): Promise<void> {
 	// 3. Write README.md (always overwrite to keep it current)
 	fs.writeFileSync(path.join(crewRoot, "README.md"), CREW_README, "utf-8");
 
-	// 4. Update .gitignore — resolve project root to place .gitignore correctly
-	// Find the repo root to place .gitignore at the project root (not inside .crew)
-	const repoRoot = findRepoRootForGitignore(cwd);
+	// 4. Update .gitignore at project root
+	const repoRoot = findProjectRoot(cwd);
 	if (repoRoot) {
 		const gitignorePath = path.join(repoRoot, ".gitignore");
 		await updateGitignore(gitignorePath);
 	}
-}
-
-/**
- * Find the appropriate project root for placing the .gitignore.
- * Walks up from cwd to find a directory with project markers.
- */
-function findRepoRootForGitignore(cwd: string): string | undefined {
-	// Use the same project root markers as paths.ts
-	const dirMarkers = [".git", ".pi", ".crew", ".hg", ".svn"];
-	const fileMarkers = [
-		"package.json",
-		"pyproject.toml",
-		"Cargo.toml",
-		"go.mod",
-	];
-	const root = path.parse(cwd).root;
-	let current = path.resolve(cwd);
-	while (current !== root) {
-		for (const marker of dirMarkers) {
-			if (fs.existsSync(path.join(current, marker))) return current;
-		}
-		for (const marker of fileMarkers) {
-			if (fs.existsSync(path.join(current, marker))) return current;
-		}
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	// No project root found — don't create .gitignore
-	return undefined;
-}
+}

package/src/state/decision-ledger.ts

@@ -0,0 +1,295 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+export interface CoherenceMark {
+	matchesPrior: boolean;
+	matchesRecursive: boolean;
+	promotionAllowed: boolean;
+	reason: string;
+}
+
+export interface RolloutEntry {
+	rolloutId: string;
+	timestamp: string;
+	priorWinner?: string;
+	searchSpace: string;
+	trialCount: number;
+	topCandidates: string[];
+	decisionMark: "accept" | "watch" | "reject" | "decay";
+	coherenceMark: CoherenceMark;
+}
+
+/**
+ * Get the ledger file path for a given run ID.
+ */
+function getLedgerPath(runId: string): string {
+	return `.crew/state/runs/${runId}/decision-ledger.jsonl`;
+}
+
+/**
+ * Compute coherence marks based on existing ledger entries.
+ */
+function computeCoherence(entry: RolloutEntry, ledger: RolloutEntry[]): CoherenceMark {
+	if (ledger.length === 0) {
+		return {
+			matchesPrior: false,
+			matchesRecursive: false,
+			promotionAllowed: true,
+			reason: "No prior entries - first rollout, promotion allowed",
+		};
+	}
+
+	const previousEntry = ledger[ledger.length - 1];
+	const matchesPrior: boolean =
+		entry.decisionMark === previousEntry.decisionMark ||
+		Boolean(entry.priorWinner && entry.topCandidates.includes(entry.priorWinner));
+
+	// Check last 3 entries for recursive pattern
+	const recentEntries = ledger.slice(-3);
+	const recentDecisions = recentEntries.map((e) => e.decisionMark);
+	const currentDecision = entry.decisionMark;
+
+	const recursiveMatches = recentDecisions.filter((d) => d === currentDecision).length;
+	const matchesRecursive = recursiveMatches >= 2;
+
+	const promotionAllowed = matchesPrior || matchesRecursive;
+
+	let reason: string;
+	if (matchesPrior && matchesRecursive) {
+		reason = `Matches prior winner and recursive pattern (${recursiveMatches}/3 recent decisions)`;
+	} else if (matchesPrior) {
+		reason = `Matches prior winner decision`;
+	} else if (matchesRecursive) {
+		reason = `Matches recursive pattern (${recursiveMatches}/3 recent decisions)`;
+	} else {
+		reason = `No match with prior or recursive pattern - requires human review`;
+	}
+
+	return {
+		matchesPrior,
+		matchesRecursive,
+		promotionAllowed,
+		reason,
+	};
+}
+
+/**
+ * Initialize a new decision ledger for a run.
+ * Creates the directory and ledger file if they don't exist.
+ */
+export function initLedger(runId: string): void {
+	const ledgerPath = getLedgerPath(runId);
+	const dir = dirname(ledgerPath);
+
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+
+	// Create empty file if it doesn't exist
+	if (!existsSync(ledgerPath)) {
+		writeFileSync(ledgerPath, "", "utf-8");
+	}
+}
+
+/**
+ * Append a new entry to the decision ledger.
+ * Automatically computes and adds coherence marks.
+ */
+export function appendEntry(runId: string, entry: RolloutEntry): RolloutEntry {
+	const ledgerPath = getLedgerPath(runId);
+
+	// Ensure directory exists
+	const dir = dirname(ledgerPath);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+
+	// Get existing entries to compute coherence
+	const ledger = getLedger(runId);
+
+	// Compute coherence marks
+	const coherenceMark = computeCoherence(entry, ledger);
+	const entryWithCoherence: RolloutEntry = {
+		...entry,
+		coherenceMark,
+	};
+
+	// Append to JSONL file
+	const line = JSON.stringify(entryWithCoherence) + "\n";
+	writeFileSync(ledgerPath, line, { flag: "a", encoding: "utf-8" });
+	return entryWithCoherence;
+}
+
+/**
+ * Read all entries from the decision ledger.
+ */
+export function getLedger(runId: string): RolloutEntry[] {
+	const ledgerPath = getLedgerPath(runId);
+
+	if (!existsSync(ledgerPath)) {
+		return [];
+	}
+
+	const content = readFileSync(ledgerPath, "utf-8");
+	if (!content.trim()) {
+		return [];
+	}
+
+	return content
+		.split("\n")
+		.filter((line) => line.trim())
+		.map((line) => JSON.parse(line) as RolloutEntry);
+}
+
+/**
+ * Get the most recent entry from the decision ledger.
+ */
+export function getLatestDecision(runId: string): RolloutEntry | null {
+	const ledger = getLedger(runId);
+	if (ledger.length === 0) {
+		return null;
+	}
+	return ledger[ledger.length - 1];
+}
+
+/**
+ * Generate a human-readable markdown summary of the ledger.
+ */
+export function summarizeLedger(runId: string): string {
+	const ledger = getLedger(runId);
+
+	if (ledger.length === 0) {
+		return "# Decision Ledger Summary\n\n*No entries recorded yet.*";
+	}
+
+	const lines: string[] = [
+		"# Decision Ledger Summary",
+		"",
+		`Run ID: ${runId}`,
+		`Total Entries: ${ledger.length}`,
+		"",
+		"## Entries",
+		"",
+	];
+
+	for (let i = 0; i < ledger.length; i++) {
+		const entry = ledger[i];
+		lines.push(`### ${i + 1}. ${entry.rolloutId}`);
+		lines.push("");
+		lines.push(`- **Timestamp**: ${entry.timestamp}`);
+		lines.push(`- **Search Space**: ${entry.searchSpace}`);
+		lines.push(`- **Trial Count**: ${entry.trialCount}`);
+		lines.push(`- **Decision**: ${entry.decisionMark}`);
+
+		if (entry.priorWinner) {
+			lines.push(`- **Prior Winner**: ${entry.priorWinner}`);
+		}
+
+		lines.push(`- **Top Candidates**: ${entry.topCandidates.join(", ") || "(none)"}`);
+		lines.push("");
+		lines.push("#### Coherence");
+		lines.push(`- **Matches Prior**: ${entry.coherenceMark.matchesPrior ? "✓" : "✗"}`);
+		lines.push(`- **Matches Recursive**: ${entry.coherenceMark.matchesRecursive ? "✓" : "✗"}`);
+		lines.push(`- **Promotion Allowed**: ${entry.coherenceMark.promotionAllowed ? "✓" : "✗"}`);
+		lines.push(`- **Reason**: ${entry.coherenceMark.reason}`);
+		lines.push("");
+	}
+
+	// Summary statistics
+	const decisions = ledger.map((e) => e.decisionMark);
+	const acceptCount = decisions.filter((d) => d === "accept").length;
+	const watchCount = decisions.filter((d) => d === "watch").length;
+	const rejectCount = decisions.filter((d) => d === "reject").length;
+	const decayCount = decisions.filter((d) => d === "decay").length;
+
+	lines.push("## Summary");
+	lines.push("");
+	lines.push(`| Decision | Count |`);
+	lines.push(`|----------|-------|`);
+	lines.push(`| Accept   | ${acceptCount} |`);
+	lines.push(`| Watch    | ${watchCount} |`);
+	lines.push(`| Reject   | ${rejectCount} |`);
+	lines.push(`| Decay    | ${decayCount} |`);
+	lines.push("");
+
+	const promotedCount = ledger.filter((e) => e.coherenceMark.promotionAllowed).length;
+	lines.push(`**Promotion Rate**: ${promotedCount}/${ledger.length} (${((promotedCount / ledger.length) * 100).toFixed(1)}%)`);
+
+	return lines.join("\n");
+}
+
+/**
+ * Promote a candidate by marking it as accepted with proper coherence.
+ */
+export function promoteCandidate(runId: string, candidate: string): RolloutEntry {
+	const latestDecision = getLatestDecision(runId);
+
+	const entry: RolloutEntry = {
+		rolloutId: `promote-${Date.now()}`,
+		timestamp: new Date().toISOString(),
+		priorWinner: latestDecision?.topCandidates[0],
+		searchSpace: latestDecision?.searchSpace || "unknown",
+		trialCount: (latestDecision?.trialCount || 0) + 1,
+		topCandidates: [candidate],
+		decisionMark: "accept",
+		coherenceMark: {
+			matchesPrior: false,
+			matchesRecursive: false,
+			promotionAllowed: true,
+			reason: "Manual promotion by user",
+		},
+	};
+
+	// Persist via appendEntry so ledger is consistent.
+	appendEntry(runId, entry);
+	const manualCoherence: import("./types.js").CoherenceMark = {
+		matchesPrior: false,
+		matchesRecursive: false,
+		promotionAllowed: true,
+		reason: "Manual promotion by user",
+	};
+	// Manually override the last line in the JSONL to reflect the coherent
+	// decision we want, bypassing appendEntry's auto-compute for the returned value.
+	const lastLine = readFileSync(getLedgerPath(runId), "utf-8").trim().split("\n").filter(Boolean).at(-1)!;
+	const overridden: RolloutEntry = { ...JSON.parse(lastLine), coherenceMark: manualCoherence };
+	writeFileSync(getLedgerPath(runId), JSON.stringify(overridden) + "\n", "utf-8");
+	return overridden;
+}
+
+/**
+ * Decay a candidate by marking it as decayed with proper coherence.
+ */
+export function decayCandidate(runId: string, candidate: string): RolloutEntry {
+	const latestDecision = getLatestDecision(runId);
+
+	const entry: RolloutEntry = {
+		rolloutId: `decay-${Date.now()}`,
+		timestamp: new Date().toISOString(),
+		priorWinner: latestDecision?.topCandidates[0],
+		searchSpace: latestDecision?.searchSpace || "unknown",
+		trialCount: (latestDecision?.trialCount || 0) + 1,
+		topCandidates: [candidate],
+		decisionMark: "decay",
+		coherenceMark: {
+			matchesPrior: false,
+			matchesRecursive: false,
+			promotionAllowed: false,
+			reason: "Manual decay by user",
+		},
+	};
+
+	// Persist via appendEntry so ledger is consistent.
+	appendEntry(runId, entry);
+	const manualCoherence: import("./types.js").CoherenceMark = {
+		matchesPrior: false,
+		matchesRecursive: false,
+		promotionAllowed: false,
+		reason: "Manual decay by user",
+	};
+	// Manually override the last line in the JSONL to reflect the coherent
+	// decision we want, bypassing appendEntry's auto-compute for the returned value.
+	const lastLine = readFileSync(getLedgerPath(runId), "utf-8").trim().split("\n").filter(Boolean).at(-1)!;
+	const overridden: RolloutEntry = { ...JSON.parse(lastLine), coherenceMark: manualCoherence };
+	writeFileSync(getLedgerPath(runId), JSON.stringify(overridden) + "\n", "utf-8");
+	return overridden;
+}

package/src/state/hook-instinct-bridge.ts

@@ -0,0 +1,90 @@
+/**
+ * Hook-to-instinct bridge - connects crewHooks events to instinct formation.
+ * Auto-initializes when imported.
+ */
+
+import { crewHooks } from "../runtime/crew-hooks.ts";
+
+// Lazy-initialized store and paths
+let storeInstance: import("./instinct-store").InstinctStore | null = null;
+let pathsInstance: typeof import("../utils/paths") | null = null;
+
+async function getStore() {
+	if (!storeInstance) {
+		const { InstinctStore } = await import("./instinct-store");
+		const paths = await import("../utils/paths");
+		storeInstance = new InstinctStore(paths.projectCrewRoot(process.cwd()));
+	}
+	return storeInstance;
+}
+
+async function getPaths() {
+	if (!pathsInstance) {
+		pathsInstance = await import("../utils/paths");
+	}
+	return pathsInstance;
+}
+
+// Subscribe to events
+crewHooks.register("task_completed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.role) {
+			store.saveInstinct({
+				trigger: `role:${event.data.role}`,
+				action: "prefer",
+				confidence: 0.6,
+				scope: "global",
+				evidence: [`task:${event.taskId} completed`],
+			});
+		}
+	} catch {
+		// Best-effort - don't crash on instinct formation failures
+	}
+});
+
+crewHooks.register("task_failed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.role) {
+			store.saveInstinct({
+				trigger: `role:${event.data.role}`,
+				action: "avoid",
+				confidence: 0.3,
+				scope: "global",
+				evidence: [`task:${event.taskId} failed`],
+			});
+		}
+	} catch {
+		// Best-effort
+	}
+});
+
+crewHooks.register("run_completed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.taskCount) {
+			store.saveInstinct({
+				trigger: "run_completed",
+				action: `completed:${event.data.taskCount}tasks`,
+				confidence: 0.6,
+				scope: "global",
+				evidence: [`run:${event.runId}`],
+			});
+		}
+	} catch {
+		// Best-effort
+	}
+});
+
+/**
+ * Get instinct-based recommendations.
+ */
+export async function getInstinctRecommendations() {
+	try {
+		const store = await getStore();
+		return store.getInstincts().filter((i: { confidence: number }) => i.confidence >= 0.6);
+	} catch {
+		return [];
+	}
+}

package/src/state/hook-integrations.ts

@@ -0,0 +1,51 @@
+/**
+ * Hook integrations - subscribes to crewHooks and provides observability.
+ * Auto-initializes when imported.
+ */
+
+import { crewHooks } from "../runtime/crew-hooks.ts";
+
+// Statistics
+let tasksCompleted = 0;
+let tasksFailed = 0;
+let runsCompleted = 0;
+let runsFailed = 0;
+
+// Subscribe to events (fire-and-forget)
+crewHooks.register("task_completed", () => {
+	tasksCompleted++;
+});
+
+crewHooks.register("task_failed", () => {
+	tasksFailed++;
+});
+
+crewHooks.register("run_completed", () => {
+	runsCompleted++;
+});
+
+crewHooks.register("run_failed", () => {
+	runsFailed++;
+});
+
+/**
+ * Get current hook statistics.
+ */
+export function getHookStats(): {
+	tasksCompleted: number;
+	tasksFailed: number;
+	runsCompleted: number;
+	runsFailed: number;
+} {
+	return { tasksCompleted, tasksFailed, runsCompleted, runsFailed };
+}
+
+/**
+ * Reset statistics (useful for testing).
+ */
+export function resetHookStats(): void {
+	tasksCompleted = 0;
+	tasksFailed = 0;
+	runsCompleted = 0;
+	runsFailed = 0;
+}