pi-crew 0.5.24 → 0.6.0

package/src/runtime/task-id.ts

@@ -0,0 +1,148 @@
+/**
+ * Hash-based task ID generation with adaptive length and hierarchical decomposition.
+ *
+ * Pattern origin: beads/internal/idgen/hash.go — SHA-256 → base36 encoding
+ * with birthday-paradox collision probability adaptation.
+ *
+ * IDs look like: `pc-a1b2` (prefix + base36 hash)
+ * Hierarchical: `pc-a1b2.1` (parent.child)
+ */
+
+import { createHash } from "node:crypto";
+
+// ── Configuration ────────────────────────────────────────────────────────
+
+const DEFAULT_PREFIX = "pc";
+const BASE36_CHARS = "0123456789abcdefghijklmnopqrstuvwxyz";
+
+interface AdaptiveIDConfig {
+	maxCollisionProbability: number;
+	minLength: number;
+	maxLength: number;
+}
+
+const DEFAULT_CONFIG: AdaptiveIDConfig = {
+	maxCollisionProbability: 0.25,
+	minLength: 3,
+	maxLength: 8,
+};
+
+// ── Core Functions ───────────────────────────────────────────────────────
+
+/**
+ * Generate a hash-based ID using SHA-256 → base36 encoding.
+ *
+ * @param content - String content to hash
+ * @param length - Desired hash length (3–8 chars)
+ * @returns Base36 hash string
+ */
+export function hashToBase36(content: string, length: number): string {
+	const hash = createHash("sha256").update(content).digest();
+	let result = "";
+	for (let i = 0; i < hash.length && result.length < length; i++) {
+		const byte = hash[i]!;
+		// Use modulo to map byte to base36
+		result += BASE36_CHARS[byte % 36]!;
+	}
+	return result.padEnd(length, "0").slice(0, length);
+}
+
+/**
+ * Calculate adaptive hash length based on existing ID count.
+ *
+ * Uses birthday-paradox formula: P(collision) ≈ 1 - e^(-n² / (2 * 36^L))
+ *
+ * @param existingCount - Number of existing IDs with the same prefix
+ * @param config - Adaptive configuration
+ * @returns Recommended hash length
+ */
+export function calculateAdaptiveLength(
+	existingCount: number,
+	config: AdaptiveIDConfig = DEFAULT_CONFIG,
+): number {
+	for (let length = config.minLength; length <= config.maxLength; length++) {
+		const totalPossibilities = Math.pow(36, length);
+		const probability = 1 - Math.exp(-(existingCount * existingCount) / (2 * totalPossibilities));
+		if (probability <= config.maxCollisionProbability) {
+			return length;
+		}
+	}
+	return config.maxLength;
+}
+
+/**
+ * Generate a deterministic hash-based task ID.
+ *
+ * @param parts - Content parts to hash (title, description, etc.)
+ * @param prefix - ID prefix (default: "pc")
+ * @param existingCount - Number of existing IDs (for adaptive length)
+ * @returns Hash-based ID like "pc-a1b2"
+ */
+export function generateTaskHashId(
+	parts: string[],
+	prefix = DEFAULT_PREFIX,
+	existingCount = 0,
+): string {
+	const content = parts.join("|");
+	const length = calculateAdaptiveLength(existingCount);
+	const hash = hashToBase36(content, length);
+	return `${prefix}-${hash}`;
+}
+
+// ── Hierarchical IDs ────────────────────────────────────────────────────
+
+export interface ParsedHierarchicalId {
+	parentId: string;
+	childNum: number;
+	isHierarchical: boolean;
+}
+
+/**
+ * Parse a hierarchical ID into parent and child number.
+ *
+ * Example: "pc-a1b2.3" → { parentId: "pc-a1b2", childNum: 3, isHierarchical: true }
+ */
+export function parseHierarchicalId(id: string): ParsedHierarchicalId {
+	const dotIndex = id.lastIndexOf(".");
+	if (dotIndex === -1 || dotIndex < 3) {
+		return { parentId: id, childNum: 0, isHierarchical: false };
+	}
+
+	const parentId = id.slice(0, dotIndex);
+	const childStr = id.slice(dotIndex + 1);
+	const childNum = Number.parseInt(childStr, 10);
+
+	if (!Number.isFinite(childNum) || childNum < 1) {
+		return { parentId: id, childNum: 0, isHierarchical: false };
+	}
+
+	return { parentId, childNum, isHierarchical: true };
+}
+
+/**
+ * Generate a child ID from a parent ID and child number.
+ *
+ * Example: childId("pc-a1b2", 3) → "pc-a1b2.3"
+ */
+export function childId(parentId: string, childNum: number): string {
+	return `${parentId}.${childNum}`;
+}
+
+// ── Dependency Types ─────────────────────────────────────────────────────
+
+/**
+ * Rich dependency types for task relationships.
+ *
+ * Pattern origin: beads/internal/types/types.go — 19 DependencyType constants
+ * Only "blocks" and "parent-child" affect execution ordering.
+ */
+export type DependencyType =
+	| "blocks"              // A must complete before B starts
+	| "parent-child"        // Hierarchical relationship
+	| "conditional-blocks"  // B runs only if A fails
+	| "waits-for"           // Fanout gate: wait for dynamic children
+	| "related"             // Association only (no ordering)
+	| "supersedes"          // A replaces B
+	| "duplicates"          // A duplicates B
+	| "delegated-from"      // A was delegated from B
+	| "validates";          // A validates B's output

package/src/runtime/task-runner/context-retrieval.ts

@@ -0,0 +1,172 @@
+/**
+ * Iterative retrieval loop — workers progressively discover needed context.
+ *
+ * Pattern origin: ECC/skills/iterative-retrieval/SKILL.md — 4-phase loop:
+ * Dispatch → Evaluate → Refine → Loop. Max 3 cycles. Convergence when
+ * ≥3 high-relevance files found AND no critical gaps.
+ *
+ * This module provides the scoring and convergence logic.
+ * The actual file discovery is delegated to the caller (prompt-builder or task-runner).
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface RetrievalQuery {
+	patterns: string[];
+	keywords: string[];
+	excludes: string[];
+	focusAreas?: string[];
+}
+
+export interface RelevanceEvaluation {
+	path: string;
+	relevance: number;     // 0.0–1.0
+	reason: string;
+	missingContext: string[];
+}
+
+export interface RetrievalResult {
+	query: RetrievalQuery;
+	evaluations: RelevanceEvaluation[];
+	cycle: number;
+	converged: boolean;
+}
+
+// ── Scoring ──────────────────────────────────────────────────────────────
+
+/**
+ * Score relevance of a file to a task description.
+ *
+ * Uses keyword matching as a heuristic. In production, this would be
+ * replaced by embedding-based similarity or BM25 scoring.
+ *
+ * @param filePath - Path to the file
+ * @param fileContent - Content of the file (or excerpt)
+ * @param keywords - Task-relevant keywords
+ * @returns Relevance score 0.0–1.0
+ */
+export function scoreRelevance(
+	filePath: string,
+	fileContent: string,
+	keywords: string[],
+): number {
+	if (keywords.length === 0) return 0;
+
+	const pathLower = filePath.toLowerCase();
+	const contentLower = fileContent.toLowerCase();
+	let matchCount = 0;
+	let weightedScore = 0;
+
+	for (const keyword of keywords) {
+		const kw = keyword.toLowerCase();
+		// Path match is worth more (file naming is intentional)
+		if (pathLower.includes(kw)) {
+			matchCount++;
+			weightedScore += 0.3;
+		}
+		// Content match
+		const contentMatches = contentLower.split(kw).length - 1;
+		if (contentMatches > 0) {
+			matchCount++;
+			// Diminishing returns for repeated matches
+			weightedScore += Math.min(0.2, 0.05 * Math.log2(contentMatches + 1));
+		}
+	}
+
+	// Normalize: if all keywords matched, score is high
+	const keywordCoverage = matchCount / keywords.length;
+	const rawScore = keywordCoverage * 0.6 + Math.min(weightedScore, 0.4);
+
+	return Math.min(1.0, Math.max(0.0, rawScore));
+}
+
+// ── Convergence ──────────────────────────────────────────────────────────
+
+const CONVERGENCE_MIN_HIGH_RELEVANCE = 3;
+const HIGH_RELEVANCE_THRESHOLD = 0.7;
+
+/**
+ * Check if retrieval has converged — enough high-relevance files found.
+ *
+ * @param evaluations - Current relevance evaluations
+ * @returns true if converged
+ */
+export function hasConverged(evaluations: RelevanceEvaluation[]): boolean {
+	const highRelevance = evaluations.filter((e) => e.relevance >= HIGH_RELEVANCE_THRESHOLD);
+	if (highRelevance.length < CONVERGENCE_MIN_HIGH_RELEVANCE) return false;
+
+	// Check for critical gaps — any evaluation with empty missingContext
+	const criticalGaps = evaluations.some(
+		(e) => e.relevance < 0.3 && e.missingContext.length > 0,
+	);
+
+	return !criticalGaps;
+}
+
+// ── Refinement ───────────────────────────────────────────────────────────
+
+/**
+ * Refine a retrieval query based on evaluation results.
+ *
+ * Extracts new keywords from high-relevance files, adds discovered
+ * terminology, and excludes confirmed-irrelevant paths.
+ *
+ * @param query - Original query
+ * @param evaluations - Results from the current cycle
+ * @returns Refined query for the next cycle
+ */
+export function refineQuery(
+	query: RetrievalQuery,
+	evaluations: RelevanceEvaluation[],
+): RetrievalQuery {
+	const newKeywords = new Set(query.keywords);
+	const newExcludes = new Set(query.excludes);
+	const newFocusAreas = new Set(query.focusAreas ?? []);
+
+	for (const eval_ of evaluations) {
+		if (eval_.relevance >= HIGH_RELEVANCE_THRESHOLD) {
+			// Extract potential keywords from the file path
+			const parts = eval_.path.replace(/[\\/]/g, "/").split("/");
+			for (const part of parts) {
+				// Skip common non-informative segments
+				if (part.length > 2 && !["src", "lib", "test", "dist", "node_modules"].includes(part)) {
+					// Use the filename stem as a keyword hint
+					const stem = part.replace(/\.[^.]+$/, "").replace(/[.-]/g, " ");
+					for (const word of stem.split(/\s+/)) {
+						if (word.length > 3) newKeywords.add(word);
+					}
+				}
+			}
+		}
+
+		if (eval_.relevance < 0.2) {
+			// Exclude confirmed-irrelevant paths
+			newExcludes.add(eval_.path);
+		}
+
+		// Track missing context as focus areas
+		for (const gap of eval_.missingContext) {
+			newFocusAreas.add(gap);
+		}
+	}
+
+	return {
+		patterns: query.patterns, // patterns don't change
+		keywords: [...newKeywords],
+		excludes: [...newExcludes],
+		focusAreas: newFocusAreas.size > 0 ? [...newFocusAreas] : undefined,
+	};
+}
+
+// ── Loop Control ─────────────────────────────────────────────────────────
+
+const MAX_CYCLES = 3;
+
+/**
+ * Determine if another retrieval cycle should run.
+ */
+export function shouldContinue(evaluations: RelevanceEvaluation[], cycle: number): boolean {
+	if (cycle >= MAX_CYCLES) return false;
+	if (hasConverged(evaluations)) return false;
+	return true;
+}

package/src/runtime/task-runner.ts

@@ -267,6 +267,25 @@ export async function runTeamTask(
 		const skillNames = input.skillNames ?? renderedSkills?.names;
 		const skillPaths = input.skillPaths ?? renderedSkills?.paths;
 
+		// Deterministic pre-step: run script, inject stdout into worker prompt
+		let preStepOutput: string | undefined;
+		if (input.step.preStepScript) {
+			const scriptTimeout = input.step.preStepTimeout ?? 30_000;
+			const scriptArgs = input.step.preStepArgs ?? [];
+			try {
+				const { execFileSync } = await import("node:child_process");
+				preStepOutput = execFileSync(input.step.preStepScript, scriptArgs, {
+					timeout: scriptTimeout,
+					encoding: "utf-8",
+					cwd: manifest.cwd,
+					maxBuffer: 1024 * 1024, // 1MB cap
+				});
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				throw new Error(`preStepScript failed: ${input.step.preStepScript}: ${msg}`);
+			}
+		}
+
 		const promptResult = await renderTaskPrompt(
 			manifest,
 			input.step,
@@ -274,7 +293,12 @@ export async function runTeamTask(
 			input.agent,
 			skillBlock,
 		);
-		const prompt = promptResult.full;
+		let prompt = promptResult.full;
+
+		// Inject deterministic pre-step output into prompt
+		if (preStepOutput) {
+			prompt += "\n\n---\n## Pre-Step Script Output\n\nThe following data was produced by a pre-step script. Use it as context for your task:\n\n<output>\n" + preStepOutput + "\n</output>\n";
+		}
 		const promptArtifact = writeArtifact(manifest.artifactsRoot, {
 			kind: "prompt",
 			relativePath: `prompts/${task.id}.md`,
@@ -1211,6 +1235,11 @@ export async function runTeamTask(
 			taskId: task.id,
 			message: error,
 		});
+
+		// Execute after_task_complete lifecycle hook (non-blocking)
+		const afterTaskReport = await executeHook("after_task_complete", { runId: manifest.runId, taskId: task.id, cwd: manifest.cwd, status: error ? "failed" : noYield ? "needs_attention" : "completed" });
+		appendHookEvent(manifest, afterTaskReport);
+
 		return { manifest, tasks };
 	} finally {
 		streamBridge?.dispose();

package/src/runtime/team-runner.ts

@@ -324,6 +324,13 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		// Emit run completion hook (100% reliable, fire-and-forget)
 		crewHooks.emit({ type: "run_completed", timestamp: new Date().toISOString(), runId: manifest.runId, data: { status: result.manifest.status, taskCount: result.tasks.length } });
 
+		// Execute after_run_complete lifecycle hook (non-blocking)
+		const afterRunReport = await executeHook("after_run_complete", { runId: manifest.runId, cwd: manifest.cwd, status: result.manifest.status });
+		appendHookEvent(manifest, afterRunReport);
+		if (afterRunReport.outcome === "block") {
+			logInternalError("team-runner.after_run_complete.blocked", new Error(afterRunReport.reason ?? "after_run_complete hook blocked"), `runId=${manifest.runId}`);
+		}
+
 		return result;
 	} catch (error) {
 		// P1: Catch unhandled errors — ensure manifest/tasks/agents are terminal so they don't stay "running" forever.

package/src/state/memory-store.ts

@@ -0,0 +1,244 @@
+/**
+ * 4-Tier Memory Consolidation System.
+ *
+ * Pattern origin: agentmemory — Working → Episodic → Semantic → Procedural.
+ * Ebbinghaus decay curve: S(t) = e^(-t/s) where s = strength.
+ * Frequently accessed memories strengthen. Tier promotion on access count.
+ * Token-budgeted injection for context window management.
+ *
+ * Tiers:
+ * - Working: Current run observations (capacity: 50)
+ * - Episodic: Recent run summaries (capacity: 200)
+ * - Semantic: Extracted patterns/knowledge (capacity: 1000)
+ * - Procedural: Learned skills/methods (capacity: 100)
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type MemoryTier = "working" | "episodic" | "semantic" | "procedural";
+
+export interface Memory {
+	id: string;
+	tier: MemoryTier;
+	content: string;
+	strength: number;        // 0.0–1.0
+	accessCount: number;
+	lastAccessed: number;    // epoch ms
+	createdAt: number;       // epoch ms
+	tags: string[];
+	sourceRunId?: string;
+}
+
+export interface MemoryConfig {
+	workingCapacity: number;
+	episodicCapacity: number;
+	semanticCapacity: number;
+	proceduralCapacity: number;
+	decayRate: number;        // Ebbinghaus parameter (higher = faster decay)
+	tokenBudget: number;      // max tokens to inject
+}
+
+const DEFAULT_CONFIG: MemoryConfig = {
+	workingCapacity: 50,
+	episodicCapacity: 200,
+	semanticCapacity: 1000,
+	proceduralCapacity: 100,
+	decayRate: 0.001,         // slow decay
+	tokenBudget: 2000,
+};
+
+const TIER_CAPACITIES: Record<MemoryTier, keyof MemoryConfig> = {
+	working: "workingCapacity",
+	episodic: "episodicCapacity",
+	semantic: "semanticCapacity",
+	procedural: "proceduralCapacity",
+};
+
+// ── Memory Operations ────────────────────────────────────────────────────
+
+/**
+ * Compute current strength using Ebbinghaus decay.
+ * S(t) = strength * e^(-elapsed_ms * decayRate)
+ */
+export function computeCurrentStrength(memory: Memory, config = DEFAULT_CONFIG): number {
+	const elapsedMs = Date.now() - memory.lastAccessed;
+	return memory.strength * Math.exp(-elapsedMs * config.decayRate);
+}
+
+/**
+ * Access a memory — strengthens it and updates access count.
+ * After N accesses, memory may be promoted to a higher tier.
+ */
+export function accessMemory(memory: Memory): Memory {
+	const newCount = memory.accessCount + 1;
+
+	// Strengthen: capped at 1.0
+	const newStrength = Math.min(1.0, memory.strength + 0.1);
+
+	// Tier promotion thresholds
+	let newTier = memory.tier;
+	if (newCount >= 10 && memory.tier === "working") newTier = "episodic";
+	if (newCount >= 20 && memory.tier === "episodic") newTier = "semantic";
+	if (newCount >= 30 && memory.tier === "semantic") newTier = "procedural";
+
+	return {
+		...memory,
+		strength: newStrength,
+		accessCount: newCount,
+		lastAccessed: Date.now(),
+		tier: newTier,
+	};
+}
+
+/**
+ * Create a new working memory.
+ */
+export function createMemory(content: string, tags: string[] = [], sourceRunId?: string): Memory {
+	return {
+		id: `mem-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+		tier: "working",
+		content,
+		strength: 0.5,
+		accessCount: 0,
+		lastAccessed: Date.now(),
+		createdAt: Date.now(),
+		tags,
+		sourceRunId,
+	};
+}
+
+// ── Memory Store ─────────────────────────────────────────────────────────
+
+export class MemoryStore {
+	private memories = new Map<string, Memory>();
+	private config: MemoryConfig;
+	private storePath?: string;
+
+	constructor(config: Partial<MemoryConfig> = {}, storePath?: string) {
+		this.config = { ...DEFAULT_CONFIG, ...config };
+		this.storePath = storePath;
+		if (storePath && existsSync(storePath)) {
+			this.load();
+		}
+	}
+
+	/**
+	 * Add a memory to the store, enforcing capacity limits.
+	 */
+	add(memory: Memory): void {
+		// Evict weakest if at capacity
+		const capacity = this.config[TIER_CAPACITIES[memory.tier]];
+		const tierMemories = [...this.memories.values()].filter((m) => m.tier === memory.tier);
+
+		if (tierMemories.length >= capacity) {
+			// Evict weakest memory in this tier
+			const weakest = tierMemories
+				.map((m) => ({ id: m.id, strength: computeCurrentStrength(m, this.config) }))
+				.sort((a, b) => a.strength - b.strength)[0];
+			if (weakest) this.memories.delete(weakest.id);
+		}
+
+		this.memories.set(memory.id, memory);
+	}
+
+	/**
+	 * Search memories by tags, returning strongest matches first.
+	 */
+	search(query: string, tags: string[] = [], limit = 10): Memory[] {
+		const queryLower = query.toLowerCase();
+
+		let results = [...this.memories.values()]
+			// Apply decay
+			.map((m) => ({ ...m, strength: computeCurrentStrength(m, this.config) }))
+			// Filter by minimum strength
+			.filter((m) => m.strength > 0.1)
+			// Score relevance
+			.map((m) => {
+				let score = m.strength;
+				if (m.content.toLowerCase().includes(queryLower)) score += 0.3;
+				if (tags.some((t) => m.tags.includes(t))) score += 0.2;
+				return { ...m, strength: score };
+			})
+			.sort((a, b) => b.strength - a.strength)
+			.slice(0, limit);
+
+		// Access side effect: strengthen returned memories
+		results = results.map((m) => accessMemory(m));
+		for (const m of results) {
+			this.memories.set(m.id, m);
+		}
+
+		return results;
+	}
+
+	/**
+	 * Inject memories into a prompt within a token budget.
+	 * Returns formatted text block.
+	 */
+	inject(query: string, tags: string[] = []): string {
+		const results = this.search(query, tags, 20);
+
+		if (results.length === 0) return "";
+
+		// Estimate tokens (4 chars ≈ 1 token)
+		const budget = this.config.tokenBudget;
+		let usedTokens = 0;
+		const selected: Memory[] = [];
+
+		for (const memory of results) {
+			const tokens = Math.ceil(memory.content.length / 4);
+			if (usedTokens + tokens > budget) break;
+			selected.push(memory);
+			usedTokens += tokens;
+		}
+
+		if (selected.length === 0) return "";
+
+		return "## Relevant Context from Previous Runs\n\n" +
+			selected.map((m) => `- [${m.tier}] ${m.content}`).join("\n") +
+			"\n";
+	}
+
+	/**
+	 * Get count of memories per tier.
+	 */
+	get stats(): Record<MemoryTier, number> {
+		const counts: Record<MemoryTier, number> = { working: 0, episodic: 0, semantic: 0, procedural: 0 };
+		for (const m of this.memories.values()) {
+			counts[m.tier]++;
+		}
+		return counts;
+	}
+
+	/**
+	 * Persist memories to disk.
+	 */
+	save(): void {
+		if (!this.storePath) return;
+		const entries = [...this.memories.values()];
+		try {
+			mkdirSync(path.dirname(this.storePath), { recursive: true });
+			writeFileSync(this.storePath, JSON.stringify(entries, null, 2), "utf-8");
+		} catch (error) {
+			logInternalError("memory-store.save", error, `path=${this.storePath}`);
+		}
+	}
+
+	private load(): void {
+		if (!this.storePath) return;
+		try {
+			const data = JSON.parse(readFileSync(this.storePath, "utf-8")) as Memory[];
+			for (const m of data) {
+				this.memories.set(m.id, m);
+			}
+		} catch (error) {
+			logInternalError("memory-store.load", error, `path=${this.storePath}`);
+		}
+	}
+}
+
+// Need path for mkdirSync in save()
+import path from "node:path";