pi-crew 0.9.53 → 0.9.55

package/src/runtime/resilient-edit.ts

@@ -0,0 +1,153 @@
+/**
+ * Resilient edit wrapper — uses the cascading replace() engine as a fallback
+ * when the native edit tool fails with "old_string not found".
+ *
+ * Multi-agent runs (crew workers) often provide slightly-wrong oldText:
+ *   - indentation drift (tabs vs spaces)
+ *   - trailing whitespace differences
+ *   - line-ending normalization (\r\n vs \n)
+ *
+ * The native edit tool is exact-match only and fails hard on these. This
+ * wrapper catches that failure and retries with the cascading engine, which
+ * tries (in order): exact → escape-normalized → line-trimmed → block-anchor →
+ * whitespace-normalized → trimmed-boundary.
+ *
+ * CONFLICT AWARENESS: pi-diff (`@heyhuynhgiabuu/pi-diff`) also overrides the
+ * edit tool with its own replace() integration. To avoid double-wrapping,
+ * this module is OPT-IN via the `CREW_RESILIENT_EDIT=1` env var, and
+ * auto-disables if pi-diff is detected in the loaded extensions.
+ *
+ * Usage (in register.ts, guarded):
+ *   if (process.env.CREW_RESILIENT_EDIT === "1") {
+ *       wrapEditWithResilientReplace(pi);
+ *   }
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ReplaceResult, replace } from "../runtime/replace.ts";
+
+interface EditToolLike {
+	name: string;
+	description: string;
+	parameters: unknown;
+	execute: (toolCallId: string, params: unknown, signal: unknown, onUpdate: unknown) => Promise<unknown>;
+}
+
+interface EditParams {
+	path?: string;
+	filePath?: string;
+	oldString?: string;
+	old_string?: string;
+	newString?: string;
+	new_string?: string;
+	replaceAll?: boolean;
+	replace_all?: boolean;
+}
+
+interface EditResult {
+	content?: unknown[];
+	[key: string]: unknown;
+}
+
+const NOT_FOUND_PATTERNS = [/old_string not found/i, /oldstring not found/i, /no match/i, /could not find/i, /string not found/i];
+
+function isNotFoundResult(result: unknown): boolean {
+	if (!result || typeof result !== "object") return false;
+	const r = result as EditResult;
+	const text = JSON.stringify(r.content ?? r);
+	return NOT_FOUND_PATTERNS.some((re) => re.test(text));
+}
+
+/** Detect whether pi-diff is loaded (to avoid double-wrapping edit). */
+function isPiDiffLoaded(pi: ExtensionAPI): boolean {
+	try {
+		const piExt = pi as unknown as { extensions?: unknown[] | Record<string, unknown>; _extensions?: unknown[] };
+		const extensions = piExt?.extensions ?? piExt?._extensions ?? [];
+		const names = Array.isArray(extensions)
+			? extensions.map((e: unknown) => (typeof e === "string" ? e : ((e as { name?: string })?.name ?? "")))
+			: Object.keys(extensions as Record<string, unknown>);
+		return names.some((n: string) => typeof n === "string" && n.includes("pi-diff"));
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Wrap the native `edit` tool so that on "old_string not found" failures, it
+ * retries using the cascading replace() engine (lenient matching).
+ *
+ * @param pi      the Pi extension API
+ * @param tools   optional injected tool registry (for testing)
+ * @returns true if the wrapper was applied, false if skipped
+ */
+export function wrapEditWithResilientReplace(pi: ExtensionAPI, tools?: { edit: EditToolLike }): boolean {
+	// Auto-disable if pi-diff is present (it has its own replace integration).
+	if (isPiDiffLoaded(pi)) {
+		return false;
+	}
+
+	const t = tools ?? (pi as unknown as { tools?: { edit?: EditToolLike } }).tools;
+	if (!t?.edit?.execute) return false;
+
+	const nativeExecute = t.edit.execute.bind(t.edit);
+
+	t.edit.execute = async function resilientExecute(
+		toolCallId: string,
+		params: unknown,
+		signal: unknown,
+		onUpdate: unknown,
+	): Promise<unknown> {
+		try {
+			const result = await nativeExecute(toolCallId, params, signal, onUpdate);
+			if (!isNotFoundResult(result)) return result;
+			// Fall through to resilient retry.
+			return await retryWithReplace(params as EditParams, toolCallId, signal, onUpdate);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			if (NOT_FOUND_PATTERNS.some((re) => re.test(msg))) {
+				return await retryWithReplace(params as EditParams, toolCallId, signal, onUpdate);
+			}
+			throw err;
+		}
+	};
+
+	return true;
+
+	async function retryWithReplace(params: EditParams, toolCallId: string, signal: unknown, onUpdate: unknown): Promise<unknown> {
+		const filePath = params.path ?? params.filePath;
+		const oldStr = params.oldString ?? params.old_string;
+		const newStr = params.newString ?? params.new_string;
+		const replaceAll = params.replaceAll ?? params.replace_all ?? false;
+
+		if (!filePath || typeof oldStr !== "string" || typeof newStr !== "string") {
+			// Can't retry — rethrow a not-found style error.
+			throw new Error("old_string not found (and resilient retry skipped: missing path/old/new)");
+		}
+
+		// LAZY: defer dynamic import of node:fs/promises to its call site.
+		const fs = await import("node:fs/promises");
+		let content: string;
+		try {
+			content = await fs.readFile(filePath, "utf8");
+		} catch (readErr) {
+			throw new Error(`resilient edit: could not read ${filePath}: ${readErr instanceof Error ? readErr.message : String(readErr)}`);
+		}
+
+		const result: ReplaceResult = replace(content, oldStr, newStr, {
+			replaceAll,
+		});
+		if (!result.changed) {
+			throw new Error(`old_string not found (resilient cascade exhausted, strategy=${result.strategy})`);
+		}
+
+		await fs.writeFile(filePath, result.content, "utf8");
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Edited ${filePath} via resilient cascade (strategy: ${result.strategy}).`,
+				},
+			],
+			_replaceStrategy: result.strategy,
+		};
+	}
+}

package/src/runtime/result-extractor.ts

@@ -0,0 +1,217 @@
+/**
+ * Structured Result Extractor — attempts to extract structured data from worker output.
+ * Tries multiple extraction strategies before falling back to raw text.
+ *
+ * Round-13 P0-3: optional `schema` (TypeBox `TSchema`) — when provided, extracted
+ * data is validated against the schema via `Value.Check`. On mismatch, the result
+ * is `structured:false` with an explanatory `error`. Backward compatible: when
+ * schema is undefined, behavior is identical to the previous regex-based extractor.
+ */
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+export interface ExtractedResult {
+	/** Whether structured data was successfully extracted */
+	structured: boolean;
+	/** Parsed structured data (if structured=true AND validated against schema if provided) */
+	data: unknown;
+	/** Raw text output (always available) */
+	rawText: string;
+	/** Error message if extraction was attempted but failed */
+	error?: string;
+}
+
+/**
+ * Extract structured result from raw worker output text.
+ * Tries strategies in order: direct JSON, fenced JSON, key-value markers, scan.
+ *
+ * @param raw - the raw text output from a worker
+ * @param schema - optional TypeBox schema. When provided, the extracted value is
+ *                 validated; mismatch produces `{structured:false, error:...}`.
+ */
+export function extractStructuredResult(raw: string, schema?: TSchema): ExtractedResult {
+	const trimmed = raw.trim();
+	if (!trimmed) {
+		return { structured: false, data: null, rawText: raw };
+	}
+
+	// Strategy 1: Direct JSON parse (entire output is JSON)
+	const directResult = tryDirectJson(trimmed);
+	if (directResult !== undefined) {
+		return finalize(directResult, raw, schema);
+	}
+
+	// Strategy 2: Extract from ```json ... ``` fence
+	const fencedResult = tryFencedJson(trimmed);
+	if (fencedResult !== undefined) {
+		return finalize(fencedResult, raw, schema);
+	}
+
+	// Strategy 3: Extract from markers like "RESULT:" or "OUTPUT:"
+	const markerResult = tryMarkerExtraction(trimmed);
+	if (markerResult !== undefined) {
+		return finalize(markerResult, raw, schema);
+	}
+
+	// Strategy 4: Scan for the first JSON object/array anywhere in text.
+	// Models often add prose preamble/epilogue ("Here's my review:", "Let me analyze...")
+	// around the JSON. This catches JSON embedded in sentences, lists, or prose.
+	const scannedResult = tryScanJson(trimmed);
+	if (scannedResult !== undefined) {
+		return finalize(scannedResult, raw, schema);
+	}
+
+	return { structured: false, data: null, rawText: raw };
+}
+
+/**
+ * After extracting a candidate object, validate it against the optional TypeBox schema.
+ * When no schema is given, behavior is the legacy "structured:true" path.
+ * When a schema is given and validation fails, return structured:false with a
+ * clear error message (caller can surface this in the AgentResult).
+ *
+ * NOTE: TypeBox 0.34.49's `Value.Check` returns a boolean and does not expose
+ * per-error paths in its public API. We use the boolean + a fallback "type mismatch"
+ * description. Scripts that need detailed diagnostics can wrap their own validator.
+ */
+function finalize(candidate: unknown, raw: string, schema: TSchema | undefined): ExtractedResult {
+	if (!schema) {
+		return { structured: true, data: candidate, rawText: raw };
+	}
+	const ok = Value.Check(schema, candidate);
+	if (ok) {
+		return { structured: true, data: candidate, rawText: raw };
+	}
+	return {
+		structured: false,
+		data: null,
+		rawText: raw,
+		error: `structured output does not match schema: expected shape ${describeSchemaShape(schema)}, got ${describeValue(candidate)}`,
+	};
+}
+
+function describeValue(value: unknown): string {
+	try {
+		const json = JSON.stringify(value);
+		return json.length > 200 ? `${json.slice(0, 200)}…` : json;
+	} catch {
+		return typeof value;
+	}
+}
+
+function describeSchemaShape(schema: unknown): string {
+	if (!schema || typeof schema !== "object") return "any";
+	const obj = schema as Record<string, unknown>;
+	const kind = obj.kind as string | undefined;
+	const type = obj.type as string | undefined;
+	if (kind === "object" || type === "object") {
+		const properties = obj.properties;
+		if (!properties || typeof properties !== "object") return "object";
+		return `object<${Object.keys(properties as Record<string, unknown>).join(",")}>`;
+	}
+	if (kind === "array" || type === "array") return "array";
+	if (type === "string") return "string";
+	if (type === "number" || type === "integer") return "number";
+	if (type === "boolean") return "boolean";
+	if (Array.isArray(obj.anyOf) || Array.isArray(obj.oneOf)) return "union";
+	return "any";
+}
+
+function tryDirectJson(text: string): unknown | undefined {
+	if (!text.startsWith("{") && !text.startsWith("[")) return undefined;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+}
+
+function tryFencedJson(text: string): unknown | undefined {
+	const match = text.match(/```json\s*\n([\s\S]*?)\n\s*```/);
+	if (!match?.[1]) return undefined;
+	try {
+		return JSON.parse(match[1].trim());
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Strategy 4: Scan for the first balanced JSON object/array anywhere in text.
+ * Robust against prose preamble/epilogue that models add around JSON output.
+ * Returns the first valid JSON value found, or undefined.
+ */
+function tryScanJson(text: string): unknown | undefined {
+	// Find the first '{' or '[' in the text.
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (ch !== "{" && ch !== "[") continue;
+		const rest = text.slice(i);
+		const end = findMatchingBracket(rest);
+		if (end <= 0) continue;
+		const candidate = rest.slice(0, end);
+		try {
+			return JSON.parse(candidate);
+		} catch {
+			// intentional parse fallback
+		}
+	}
+	return undefined;
+}
+
+function tryMarkerExtraction(text: string): unknown | undefined {
+	// Try to find JSON after common markers
+	const markers = ["RESULT:", "OUTPUT:", "ANSWER:", "### Result\n", "## Output\n"];
+	for (const marker of markers) {
+		const idx = text.indexOf(marker);
+		if (idx === -1) continue;
+		const after = text.slice(idx + marker.length).trim();
+		// Try JSON parse on text after marker
+		if (after.startsWith("{") || after.startsWith("[")) {
+			try {
+				return JSON.parse(after);
+			} catch {
+				// Try to find just the JSON object/array
+				const jsonEnd = findMatchingBracket(after);
+				if (jsonEnd > 0) {
+					try {
+						return JSON.parse(after.slice(0, jsonEnd));
+					} catch {
+						// intentional parse fallback
+					}
+				}
+			}
+		}
+	}
+	return undefined;
+}
+
+function findMatchingBracket(text: string): number {
+	const openChar = text[0];
+	const closeChar = openChar === "{" ? "}" : "]";
+	let depth = 0;
+	let inString = false;
+	let escape = false;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (escape) {
+			escape = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escape = true;
+			continue;
+		}
+		if (ch === '"') {
+			inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (ch === openChar) depth++;
+		if (ch === closeChar) {
+			depth--;
+			if (depth === 0) return i + 1;
+		}
+	}
+	return -1;
+}

package/src/runtime/retry-executor.ts

@@ -0,0 +1,109 @@
+import { sleep } from "../utils/sleep.ts";
+import { throwIfCancelled } from "./cancellation.ts";
+
+export interface RetryPolicy {
+	maxAttempts: number;
+	backoffMs: number;
+	jitterRatio: number;
+	exponentialFactor: number;
+	retryableErrors?: string[];
+	/**
+	 * CORE-3 — per-task spawn budget cap. Maximum total worker spawns
+	 * (runWorker/runChildPi calls) allowed across ALL retry attempts × model
+	 * fallback iterations for a single task. When omitted or 0, the budget
+	 * auto-computes as `attemptModels.length × (maxAttempts + 1)` in
+	 * task-runner.ts (always ≥ 1 full attempt above the theoretical max).
+	 * Set explicitly to override the auto-computed value.
+	 */
+	maxTotalSpawns?: number;
+}
+
+export interface RetryAttemptInfo {
+	attempt: number;
+	attemptId: string;
+}
+
+export interface RetryHooks {
+	onAttemptFailed?: (attempt: number, error: Error, nextDelayMs: number, info: RetryAttemptInfo) => void;
+	onRetryGivenUp?: (attempts: number, error: Error, info: RetryAttemptInfo) => void;
+	attemptId?: (attempt: number) => string;
+	signal?: AbortSignal;
+}
+
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+	maxAttempts: 3,
+	backoffMs: 1000,
+	jitterRatio: 0.3,
+	exponentialFactor: 2,
+};
+
+function asError(error: unknown): Error {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+function globToRegex(pattern: string): RegExp {
+	const escaped = pattern
+		.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+		.replace(/\*/g, ".*")
+		.replace(/\?/g, ".");
+	return new RegExp(`^${escaped}$`, "i");
+}
+
+function isRetryable(error: Error, policy: RetryPolicy): boolean {
+	const patterns = policy.retryableErrors ?? [];
+	if (!patterns.length) return true;
+	return patterns.some((pattern) => globToRegex(pattern).test(error.message));
+}
+
+export function calculateRetryDelay(attempt: number, policy: RetryPolicy = DEFAULT_RETRY_POLICY, random = Math.random): number {
+	const base = policy.backoffMs * policy.exponentialFactor ** Math.max(0, attempt - 1);
+	const jitter = (random() * 2 - 1) * policy.jitterRatio * base;
+	return Math.max(0, base + jitter);
+}
+
+function retryAttemptInfo(attempt: number, hooks: RetryHooks): RetryAttemptInfo {
+	return {
+		attempt,
+		attemptId: hooks.attemptId?.(attempt) ?? `retry_attempt_${attempt}`,
+	};
+}
+
+export async function executeWithRetry<T>(
+	fn: (attempt: number, info: RetryAttemptInfo) => Promise<T>,
+	policy: RetryPolicy = DEFAULT_RETRY_POLICY,
+	hooks: RetryHooks = {},
+): Promise<T> {
+	const normalized: RetryPolicy = {
+		...DEFAULT_RETRY_POLICY,
+		...policy,
+		maxAttempts: Math.max(1, policy.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts),
+	};
+	let lastError: Error | undefined;
+	for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
+		throwIfCancelled(hooks.signal);
+		const info = retryAttemptInfo(attempt, hooks);
+		try {
+			return await fn(attempt, info);
+		} catch (error) {
+			lastError = asError(error);
+			// Never retry if aborted — sleep() would immediately reject on every attempt.
+			if (hooks.signal?.aborted) {
+				hooks.onRetryGivenUp?.(attempt, lastError, info);
+				throw lastError;
+			}
+			if (attempt >= normalized.maxAttempts || !isRetryable(lastError, normalized)) {
+				hooks.onRetryGivenUp?.(attempt, lastError, info);
+				throw lastError;
+			}
+			const delay = calculateRetryDelay(attempt, normalized);
+			hooks.onAttemptFailed?.(attempt, lastError, delay, info);
+			try {
+				await sleep(delay, hooks.signal);
+			} catch (sleepError) {
+				if (hooks.signal?.aborted) throwIfCancelled(hooks.signal);
+				throw sleepError;
+			}
+		}
+	}
+	throw lastError ?? new Error("Retry failed without error.");
+}