pi-crew 0.9.53 → 0.9.55

package/src/config/markers.ts

@@ -0,0 +1,330 @@
+import * as fs from "node:fs";
+
+/**
+ * Marker delimiters used to bracket pi-crew guidance sections inside
+ * markdown files (e.g. AGENTS.md).  Using HTML comments keeps them
+ * invisible when rendered.
+ */
+export const MARKER_START = "<!-- PI-CREW:GUIDANCE:START -->";
+export const MARKER_END = "<!-- PI-CREW:GUIDANCE:END -->";
+
+/** A single guidance section to inject between markers. */
+export interface GuidanceBlock {
+	/**
+	 * Unique identifier for this guidance section (e.g. "team-tool-usage").
+	 * Must match `/^[a-zA-Z0-9_-]+$/`.
+	 */
+	id: string;
+	/**
+	 * Markdown content to inject.
+	 *
+	 * **WARNING:** Content must be from trusted sources only. Guidance blocks
+	 * are injected into markdown files that AI agents read. Untrusted content
+	 * could contain prompt-injection payloads that manipulate agent behavior.
+	 */
+	content: string;
+	/** Higher priority = appears first. Default 0. */
+	priority?: number;
+}
+
+/** Regex for valid guidance block IDs. */
+const VALID_BLOCK_ID = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Sanitize guidance content to reduce prompt-injection risk.
+ *
+ * Strips HTML comment patterns and instruction-like directives that could
+ * be used for prompt injection. This is a best-effort defense — content
+ * should still come from trusted sources.
+ */
+/**
+ * Best-effort content sanitizer for guidance blocks.
+ *
+ * WARNING: This is NOT a security boundary. Content should come from trusted
+ * sources only. This sanitizer handles common injection patterns but cannot
+ * prevent all bypasses (e.g., base64, ROT13, semantic tricks).
+ */
+export function sanitizeGuidanceContent(content: string): string {
+	let sanitized = content;
+	// Strip zero-width and invisible Unicode characters (potential bypass vectors)
+	sanitized = sanitized.replace(/[\u200B-\u200F\u2028-\u202F\u2060-\u206F\uFEFF]/g, "");
+	// Strip HTML comments (potential instruction hiding)
+	sanitized = sanitized.replace(/<!--[\s\S]*?-->/g, "");
+	// Strip lines that look like system directives (e.g. "SYSTEM:", "INSTRUCTION:", "IGNORE PREVIOUS")
+	sanitized = sanitized.replace(/^\s*(?:SYSTEM|INSTRUCTION|IGNORE\s+PREVIOUS|OVERRIDE)\s*:.*$/gim, "");
+	// Collapse multiple blank lines left by removals
+	sanitized = sanitized.replace(/\n{3,}/g, "\n\n");
+	return sanitized.trim();
+}
+
+/** Result of an injection or removal operation. */
+export interface InjectionResult {
+	path: string;
+	modified: boolean;
+	/** Block IDs that were added or updated. */
+	added: string[];
+	/** Block IDs that were removed (content was empty). */
+	removed: string[];
+}
+
+/**
+ * Render a sorted list of guidance blocks into the markdown content that
+ * sits between the START and END markers.
+ *
+ * Each block is wrapped in its own id-tagged comment so we can later
+ * parse individual blocks back out.
+ */
+function renderBlocks(blocks: GuidanceBlock[]): string {
+	const sorted = [...blocks].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+	return sorted.map((block) => `<!-- PI-CREW:BLOCK:${block.id} -->\n${block.content}\n<!-- PI-CREW:/BLOCK:${block.id} -->`).join("\n\n");
+}
+
+/**
+ * Parse the inner marker content and return the set of block IDs present.
+ */
+export function extractGuidanceIds(content: string): string[] {
+	const ids: string[] = [];
+	const regex = /<!-- PI-CREW:BLOCK:([^\s>]+) -->/g;
+	let match: RegExpExecArray | null = regex.exec(content);
+	while (match !== null) {
+		const captured = match[1];
+		if (captured !== undefined) ids.push(captured);
+		match = regex.exec(content);
+	}
+	return ids;
+}
+
+/**
+ * Parse existing blocks from marker content into a map of id → GuidanceBlock.
+ */
+function parseExistingBlocks(inner: string): Map<string, GuidanceBlock> {
+	const map = new Map<string, GuidanceBlock>();
+	const regex = /<!-- PI-CREW:BLOCK:([^\s>]+) -->\n([\s\S]*?)<!-- PI-CREW:\/BLOCK:\1 -->/g;
+	let match: RegExpExecArray | null = regex.exec(inner);
+	while (match !== null) {
+		const id = match[1];
+		const blockContent = match[2];
+		if (id !== undefined && blockContent !== undefined) {
+			map.set(id, { id, content: blockContent.replace(/\n$/, "") });
+		}
+		match = regex.exec(inner);
+	}
+	return map;
+}
+
+/**
+ * Build the full marker section string.
+ */
+function buildMarkerSection(blocks: GuidanceBlock[]): string {
+	const body = renderBlocks(blocks);
+	return `\n${MARKER_START}\n${body}\n${MARKER_END}\n`;
+}
+
+/**
+ * Inject (or update) pi-crew guidance blocks inside `filePath`.
+ *
+ * - If the file does not exist, it is created with only the marker section.
+ * - If the file exists but has no markers, the marker section is appended.
+ * - If the file already has markers, existing blocks are merged with the
+ *   supplied `blocks`.  Blocks with matching IDs are overwritten; blocks
+ *   not present in `blocks` are preserved unless their content is empty
+ *   (handled via the `removeGuidance` helper instead).
+ * - Blocks whose `content` is an empty string are treated as "remove" —
+ *   they are excluded from the merged output.
+ * - Content outside the markers is preserved exactly.
+ */
+export function injectGuidance(filePath: string, blocks: GuidanceBlock[]): InjectionResult {
+	// Validate block IDs before processing (M1)
+	for (const block of blocks) {
+		if (!VALID_BLOCK_ID.test(block.id)) {
+			throw new Error(`Invalid guidance block ID '${block.id}': must match /^[a-zA-Z0-9_-]+$/.`);
+		}
+	}
+
+	const original = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8") : "";
+
+	const startIdx = original.indexOf(MARKER_START);
+	const endIdx = original.indexOf(MARKER_END);
+
+	let existingBlocks = new Map<string, GuidanceBlock>();
+	let before = original;
+	let after = "";
+
+	if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+		// Extract content around markers
+		before = original.slice(0, startIdx);
+		after = original.slice(endIdx + MARKER_END.length);
+
+		const inner = original.slice(startIdx + MARKER_START.length, endIdx);
+		existingBlocks = parseExistingBlocks(inner);
+	} else {
+		// No markers: whole file is "before"
+		before = original;
+		after = "";
+	}
+
+	// Merge: apply new blocks on top of existing
+	const added: string[] = [];
+	const removed: string[] = [];
+
+	for (const block of blocks) {
+		if (block.content === "") {
+			// Empty content signals removal
+			if (existingBlocks.has(block.id)) {
+				existingBlocks.delete(block.id);
+				removed.push(block.id);
+			}
+		} else {
+			existingBlocks.set(block.id, {
+				...block,
+				content: sanitizeGuidanceContent(block.content),
+			});
+			added.push(block.id);
+		}
+	}
+
+	const merged = [...existingBlocks.values()];
+
+	// Nothing to write if there are no blocks and no markers existed
+	const hadMarkers = startIdx !== -1;
+	if (merged.length === 0 && !hadMarkers) {
+		return { path: filePath, modified: false, added: [], removed: [] };
+	}
+
+	// If all blocks removed and markers existed, remove the whole section
+	if (merged.length === 0 && hadMarkers) {
+		const newContent = trimTrailingNewlines(before) + after;
+		if (newContent === original) {
+			return { path: filePath, modified: false, added: [], removed };
+		}
+		fs.writeFileSync(filePath, newContent, "utf-8");
+		return { path: filePath, modified: true, added: [], removed };
+	}
+
+	const section = buildMarkerSection(merged);
+	const newContent = trimTrailingNewlines(before) + section + trimLeadingNewlines(after);
+
+	if (newContent === original) {
+		return { path: filePath, modified: false, added: [], removed };
+	}
+
+	// Ensure parent directory exists
+	const dir = filePath.substring(0, Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\")));
+	if (dir && !fs.existsSync(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
+	}
+
+	fs.writeFileSync(filePath, newContent, "utf-8");
+	return { path: filePath, modified: true, added, removed };
+}
+
+/**
+ * Remove specific guidance blocks (by ID) or the entire marker section
+ * from `filePath`.
+ *
+ * - If `ids` is `undefined`, the entire marker section is removed.
+ * - If `ids` is an array, only the listed block IDs are removed.
+ * - Content outside markers is preserved exactly.
+ */
+export function removeGuidance(filePath: string, ids?: string[]): InjectionResult {
+	if (!fs.existsSync(filePath)) {
+		return { path: filePath, modified: false, added: [], removed: [] };
+	}
+
+	const original = fs.readFileSync(filePath, "utf-8");
+	const startIdx = original.indexOf(MARKER_START);
+	const endIdx = original.indexOf(MARKER_END);
+
+	if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+		return { path: filePath, modified: false, added: [], removed: [] };
+	}
+
+	const before = original.slice(0, startIdx);
+	const after = original.slice(endIdx + MARKER_END.length);
+	const inner = original.slice(startIdx + MARKER_START.length, endIdx);
+
+	if (ids === undefined) {
+		// Remove entire marker section
+		const allIds = extractGuidanceIds(inner);
+		const newContent = trimTrailingNewlines(before) + after;
+		if (newContent === original) {
+			return { path: filePath, modified: false, added: [], removed: [] };
+		}
+		fs.writeFileSync(filePath, newContent, "utf-8");
+		return { path: filePath, modified: true, added: [], removed: allIds };
+	}
+
+	// Remove specific block IDs
+	const existingBlocks = parseExistingBlocks(inner);
+	const removed: string[] = [];
+	for (const id of ids) {
+		if (existingBlocks.delete(id)) {
+			removed.push(id);
+		}
+	}
+
+	if (removed.length === 0) {
+		return { path: filePath, modified: false, added: [], removed: [] };
+	}
+
+	const merged = [...existingBlocks.values()];
+
+	if (merged.length === 0) {
+		const newContent = trimTrailingNewlines(before) + after;
+		fs.writeFileSync(filePath, newContent, "utf-8");
+		return { path: filePath, modified: true, added: [], removed };
+	}
+
+	const section = buildMarkerSection(merged);
+	const newContent = trimTrailingNewlines(before) + section + trimLeadingNewlines(after);
+	fs.writeFileSync(filePath, newContent, "utf-8");
+	return { path: filePath, modified: true, added: [], removed };
+}
+
+/**
+ * Generate standard pi-crew guidance blocks for injection into project
+ * files (e.g. AGENTS.md).
+ *
+ * @param version — current pi-crew package version for version-aware updates
+ */
+export function standardGuidanceBlocks(version: string): GuidanceBlock[] {
+	return [
+		{
+			id: "pi-crew-overview",
+			priority: 10,
+			content: [
+				"## pi-crew",
+				"",
+				`> Managed by **pi-crew v${version}** — do not edit this section manually.`,
+				"",
+				"pi-crew is a Pi extension for coordinated AI agent teams, workflows,",
+				"worktrees, and async task orchestration.",
+			].join("\n"),
+		},
+		{
+			id: "pi-crew-commands",
+			priority: 5,
+			content: [
+				"### Quick Commands",
+				"",
+				"| Command | Description |",
+				"|---|---|",
+				"| `team action='init'` | Initialize pi-crew for this project |",
+				"| `team action='run'` | Start a team run |",
+				"| `team action='status'` | Check run status |",
+				"| `team action='list'` | List available teams/agents/workflows |",
+				"| `team action='recommend'` | Get team/workflow recommendations |",
+			].join("\n"),
+		},
+	];
+}
+
+/** Remove trailing newlines from a string, ensuring at most one trailing newline. */
+function trimTrailingNewlines(s: string): string {
+	return s.replace(/\n+$/, "");
+}
+
+/** Remove leading newlines from a string. */
+function trimLeadingNewlines(s: string): string {
+	return s.replace(/^\n+/, "");
+}

package/src/config/resilient-parser.ts

@@ -0,0 +1,117 @@
+/**
+ * Per-field resilient config parsing — continues on error, collects all field-level issues.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { PiTeamsConfigSchema } from "../schema/config-schema.ts";
+import { type PiTeamsConfig, parseConfig } from "./config.ts";
+import { suggestConfigKey } from "./suggestions.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FieldError {
+	field: string;
+	message: string;
+	value: unknown;
+	suggestion?: string;
+}
+
+export interface ResilientParseResult {
+	config: Record<string, unknown>;
+	errors: FieldError[];
+	warnings: string[];
+	valid: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const KNOWN_TOP_LEVEL_KEYS: readonly string[] = Object.keys(PiTeamsConfigSchema.properties ?? {});
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a raw config value field-by-field.
+ *
+ * - Each top-level key is validated independently via TypeBox sub-schemas.
+ * - Fields that fail are recorded as errors but do not block others.
+ * - Unknown keys get a fuzzy suggestion via Levenshtein distance.
+ * - The returned `config` contains only successfully-parsed fields (via `parseConfig`).
+ */
+export function parseConfigResilient(raw: unknown): ResilientParseResult {
+	const errors: FieldError[] = [];
+	const warnings: string[] = [];
+
+	if (!isObject(raw)) {
+		return {
+			config: {},
+			errors: [
+				{
+					field: "config",
+					message: "config must be an object",
+					value: raw,
+				},
+			],
+			warnings,
+			valid: false,
+		};
+	}
+
+	// Collect unknown top-level keys with suggestions
+	for (const key of Object.keys(raw)) {
+		if (!KNOWN_TOP_LEVEL_KEYS.includes(key)) {
+			const suggestion = suggestConfigKey(key, KNOWN_TOP_LEVEL_KEYS);
+			errors.push({
+				field: key,
+				message: `unknown config key '${key}'`,
+				value: raw[key],
+				suggestion: suggestion ?? undefined,
+			});
+		}
+	}
+
+	// Use TypeBox per-field validation for known keys
+	for (const key of KNOWN_TOP_LEVEL_KEYS) {
+		if (!(key in raw)) continue;
+		const value = raw[key];
+		const subSchema = (PiTeamsConfigSchema.properties as Record<string, unknown>)[key];
+		if (subSchema && !Value.Check(subSchema as TSchema, value)) {
+			// Collect ALL errors for this field
+			const fieldErrors = [...Value.Errors(subSchema as TSchema, value)];
+			for (const err of fieldErrors) {
+				const errObj = err as unknown as Record<string, unknown>;
+				const msg = typeof errObj.message === "string" ? errObj.message : "invalid value";
+				errors.push({
+					field: key,
+					message: msg,
+					value,
+				});
+			}
+		}
+	}
+
+	// Build the valid subset using existing parseConfig (which silently drops invalid fields)
+	const parsed: PiTeamsConfig = parseConfig(raw);
+	const config: Record<string, unknown> = {};
+	for (const key of Object.keys(parsed)) {
+		const val = (parsed as Record<string, unknown>)[key];
+		if (val !== undefined) config[key] = val;
+	}
+
+	return {
+		config,
+		errors,
+		warnings,
+		valid: errors.length === 0,
+	};
+}

package/src/config/role-tools.ts

@@ -0,0 +1,118 @@
+/**
+ * Role-based tool configurations for pi-crew agents.
+ * Uses the excludeTools option from pi v0.77.0.
+ */
+
+export interface RoleToolConfig {
+	/** Explicit list of tools to use (if undefined, use all default tools) */
+	tools?: string[];
+	/** Tools to exclude from the default set */
+	excludeTools?: string[];
+}
+
+export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
+	// Explorer - Read-only exploration; bash is included for git log/show
+	// (decisions stream needs commit-history mining) but edit/write stay
+	// excluded. State-mutation safety is enforced separately by
+	// READ_ONLY_ROLES in role-permission.ts.
+	explorer: {
+		tools: ["read", "grep", "find", "ls", "glob", "bash"],
+		excludeTools: ["edit", "write", "web"],
+	},
+
+	// Analyst - Read and analyze, limited execution
+	analyst: {
+		excludeTools: ["edit", "write", "ask_question"],
+	},
+
+	// Planner - Read-only planning; emits plans as TEXT (runner persists result).
+	// F2/F3: strengthened to a read-only tool-set matching its READ_ONLY_ROLES
+	// classification. Deliverables are emitted as RESULT TEXT (consumed by
+	// adaptive-plan.ts / runner shared-output), NOT file writes — so the
+	// plan-approval gate boundary (planner = read-only) is preserved. Moving
+	// planner to WRITE_ROLES would fire the gate before planning, breaking the
+	// default/implementation workflows.
+	planner: {
+		tools: ["read", "grep", "find", "ls", "glob"],
+		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
+	},
+
+	// Critic - Read-only plan/design critique (F2: was missing from the map,
+	// so a custom critic agent had no tool-level read-only enforcement).
+	critic: {
+		tools: ["read", "grep", "find", "ls", "glob"],
+		excludeTools: ["edit", "write", "bash", "web"],
+	},
+
+	// Executor - Full access (default)
+	executor: {
+		// No restrictions - full tool access
+	},
+
+	// Reviewer - Read and review, no write
+	reviewer: {
+		tools: ["read", "grep", "find", "ls", "glob", "bash"],
+		excludeTools: ["edit", "write"],
+	},
+
+	// Writer - Documentation focused
+	writer: {
+		tools: ["read", "edit", "write", "ls"],
+		excludeTools: ["bash", "web", "ask_question"],
+	},
+
+	// Security Reviewer - Strict restrictions
+	// F1: key is hyphenated to match the runtime role string (agents/
+	// security-reviewer.md → "security-reviewer"). The underscore form never
+	// resolved at runtime (returned {}), silently dropping enforcement.
+	"security-reviewer": {
+		tools: ["read", "grep", "find"],
+		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
+	},
+
+	// Verifier - Runs tests (needs bash) but must NOT edit source (F4: moved
+	// from READ_ONLY_ROLES to WRITE_ROLES — the read-only prompt gate forbids
+	// the test-running redirects / cache writes its task requires, contradicting
+	// agents/verifier.md). Tool-set keeps bash but excludes edit/write so source
+	// integrity is preserved during verification. Mirrors cold-verifier behavior.
+	verifier: {
+		tools: ["read", "grep", "find", "ls", "bash"],
+		excludeTools: ["edit", "write", "web"],
+	},
+
+	// Test Engineer - Can write tests (F1: hyphenated key)
+	"test-engineer": {
+		tools: ["read", "edit", "write", "bash", "ls"],
+		excludeTools: ["web"],
+	},
+};
+
+/**
+ * Get tool configuration for a specific role.
+ */
+export function getToolConfig(role: string): RoleToolConfig {
+	// F1: normalize hyphen/underscore. Runtime role strings are hyphenated
+	// (agents/security-reviewer.md → "security-reviewer") but map keys were
+	// historically underscored, silently returning {} at runtime — the same
+	// defect class as the v0.9.10 writer incident (opposite direction:
+	// under-enforce instead of over-enforce). Accept both forms.
+	const key = role.includes("_") ? role.replaceAll("_", "-") : role;
+	return ROLE_TOOL_CONFIGS[key] ?? ROLE_TOOL_CONFIGS[role] ?? {};
+}
+
+/**
+ * Check if a role has any tool restrictions.
+ */
+export function hasToolRestrictions(role: string): boolean {
+	const config = getToolConfig(role);
+	return config.tools !== undefined || config.excludeTools !== undefined;
+}
+
+/**
+ * Get all restricted roles.
+ */
+export function getRestrictedRoles(): string[] {
+	return Object.entries(ROLE_TOOL_CONFIGS)
+		.filter(([, config]) => config.tools !== undefined || config.excludeTools !== undefined)
+		.map(([role]) => role);
+}

package/src/config/suggestions.ts

@@ -0,0 +1,75 @@
+/**
+ * Fuzzy config key suggestions — Levenshtein-based typo correction for pi-crew config keys.
+ *
+ * SECURITY NOTE: The levenshtein() function processes user-supplied input and compares
+ * against a known list. While the timing variance across edit distances is minimal
+ * and the input is typically config key names (not secrets), there is a theoretical
+ * timing attack risk if an attacker could measure response times for different inputs.
+ * Risk level: LOW — mitigated by the small alphabet (config key names only) and
+ * the fixed-size DP array used in this implementation.
+ */
+
+/**
+ * Classic Levenshtein edit distance between two strings.
+ * See security note above regarding timing attack considerations.
+ */
+export function levenshtein(a: string, b: string): number {
+	const la = a.length;
+	const lb = b.length;
+	if (la === 0) return lb;
+	if (lb === 0) return la;
+
+	// Single-row DP to keep memory O(min(n,m))
+	let prev = new Uint32Array(lb + 1);
+	let curr = new Uint32Array(lb + 1);
+
+	for (let j = 0; j <= lb; j++) prev[j] = j;
+
+	for (let i = 1; i <= la; i++) {
+		curr[0] = i;
+		for (let j = 1; j <= lb; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min(
+				prev[j] + 1, // deletion
+				curr[j - 1] + 1, // insertion
+				prev[j - 1] + cost, // substitution
+			);
+		}
+		const swap = prev;
+		prev = curr;
+		curr = swap;
+	}
+
+	return prev[lb];
+}
+
+const DEFAULT_MAX_DISTANCE = 3;
+
+/**
+ * Find the closest matching key from a list of valid keys.
+ * Case-insensitive. Returns null if no match within `maxDistance`.
+ */
+export function findClosestKey(input: string, validKeys: readonly string[], maxDistance: number = DEFAULT_MAX_DISTANCE): string | null {
+	if (validKeys.length === 0) return null;
+
+	const lower = input.toLowerCase();
+	let bestKey: string | null = null;
+	let bestDist = maxDistance + 1;
+
+	for (const key of validKeys) {
+		const dist = levenshtein(lower, key.toLowerCase());
+		if (dist < bestDist) {
+			bestDist = dist;
+			bestKey = key;
+		}
+	}
+
+	return bestDist <= maxDistance ? bestKey : null;
+}
+
+/**
+ * Convenience wrapper — suggest the closest known config key for a potentially mistyped input.
+ */
+export function suggestConfigKey(input: string, knownKeys: readonly string[]): string | null {
+	return findClosestKey(input, knownKeys);
+}