pi-crew 0.9.53 → 0.9.55

package/src/runtime/custom-tools/submit-result-tool.ts

@@ -0,0 +1,102 @@
+/**
+ * G1: Custom tool — submit_result.
+ *
+ * Registers a real `submit_result` tool in the Pi SDK session so that
+ * live-session workers can yield their result by calling a tool (instead of
+ * relying solely on prompt-based reminders).
+ *
+ * Adapted from oh-my-pi's `YieldTool` pattern. Uses Pi SDK's `defineTool()`
+ * and TypeBox schemas for validation.
+ */
+
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "@sinclair/typebox";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { YieldResult } from "../yield-handler.ts";
+
+const SubmitResultParams = Type.Object({
+	summary: Type.String({ description: "Summary of completed work." }),
+	artifacts: Type.Optional(
+		Type.Record(Type.String(), Type.String(), {
+			description: "Key-value map of artifact labels to file paths or content.",
+		}),
+	),
+	structuredData: Type.Optional(
+		Type.Record(Type.String(), Type.Unknown(), {
+			description: "Structured key-value data to pass back to the orchestrator.",
+		}),
+	),
+});
+
+type SubmitResultParams = Static<typeof SubmitResultParams>;
+
+interface SubmitResultDetails {
+	summary: string;
+	artifacts?: Record<string, string>;
+	structuredData?: Record<string, unknown>;
+}
+
+/**
+ * Create a `submit_result` tool definition that calls `onYield` when invoked.
+ *
+ * The tool is injected into the session via `createAgentSession({ customTools: [...] })`.
+ * When the model calls it, the result is captured via the `onYield` callback
+ * and the yield enforcement loop terminates.
+ */
+export function createSubmitResultTool(
+	onYield: (result: YieldResult) => void,
+): ToolDefinition<typeof SubmitResultParams, SubmitResultDetails> {
+	return defineTool({
+		name: "submit_result",
+		label: "Submit Result",
+		description:
+			"Submit final task result. Call when task complete. " +
+			"Provide summary, optional artifacts (file paths/content), optional structured data.",
+		parameters: SubmitResultParams,
+		promptSnippet: "Submit your task result when done using submit_result",
+		promptGuidelines: [
+			"Always call submit_result when your task is complete, even if you were unable to finish.",
+			"Include a clear summary of what was accomplished.",
+		],
+		async execute(
+			toolCallId: string,
+			params: SubmitResultParams,
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			_ctx: unknown,
+		): Promise<{
+			content: Array<{ type: "text"; text: string }>;
+			details: SubmitResultDetails;
+		}> {
+			const result: YieldResult = {
+				summary: params.summary,
+				toolCallId,
+				...(params.artifacts ? { artifacts: params.artifacts } : {}),
+				...(params.structuredData ? { structuredData: params.structuredData } : {}),
+			};
+			// Build response first so the model always gets confirmation
+			const response: {
+				content: Array<{ type: "text"; text: string }>;
+				details: SubmitResultDetails;
+			} = {
+				content: [
+					{
+						type: "text",
+						text: "Result submitted successfully. Thank you.",
+					},
+				],
+				details: {
+					summary: params.summary,
+					artifacts: params.artifacts,
+					structuredData: params.structuredData,
+				},
+			};
+			try {
+				onYield(result);
+			} catch (error) {
+				logInternalError("submit-result-tool.yield", error, toolCallId);
+			}
+			return response;
+		},
+	});
+}

package/src/runtime/deadletter.ts

@@ -0,0 +1,47 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest } from "../state/types.ts";
+
+import { logInternalError } from "../utils/internal-error.ts";
+
+export type DeadletterReason = "max-retries" | "heartbeat-dead" | "manual";
+
+export interface DeadletterEntry {
+	taskId: string;
+	runId: string;
+	reason: DeadletterReason;
+	attempts: number;
+	lastError?: string;
+	attemptId?: string;
+	timestamp: string;
+}
+
+export function deadletterPath(manifest: TeamRunManifest): string {
+	return path.join(manifest.stateRoot, "deadletter.jsonl");
+}
+
+export function appendDeadletter(manifest: TeamRunManifest, entry: DeadletterEntry): void {
+	try {
+		fs.mkdirSync(manifest.stateRoot, { recursive: true });
+		fs.appendFileSync(deadletterPath(manifest), `${JSON.stringify(entry)}\n`, "utf-8");
+	} catch (error) {
+		logInternalError("deadletter.append", error, `taskId=${entry.taskId}`);
+	}
+}
+
+export function readDeadletter(manifest: TeamRunManifest, maxEntries = 1000): DeadletterEntry[] {
+	const filePath = deadletterPath(manifest);
+	if (!fs.existsSync(filePath)) return [];
+	// Read last maxEntries lines only to limit memory.
+	const raw = fs.readFileSync(filePath, "utf-8");
+	const lines = raw.split(/\r?\n/).filter(Boolean);
+	const tail = lines.slice(-maxEntries);
+	return tail.flatMap((line) => {
+		try {
+			const parsed = JSON.parse(line) as DeadletterEntry;
+			return parsed && typeof parsed.taskId === "string" && typeof parsed.runId === "string" ? [parsed] : [];
+		} catch {
+			return [];
+		}
+	});
+}

package/src/runtime/delivery-coordinator.ts

@@ -0,0 +1,211 @@
+import type { NotificationDescriptor } from "../extension/notification-router.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface PendingDelivery {
+	runId: string;
+	payload: unknown;
+	timestamp: number;
+	type: "result" | "notification" | "steer";
+	generation?: number;
+}
+
+export interface DeliveryCoordinatorDeps {
+	/** Emit an event to the active Pi event bus. */
+	emit?: (event: string, data: unknown) => void;
+	/** Send a follow-up message to the active session (for notifications). */
+	sendFollowUp?: (title: string, body: string) => void;
+	/** Send a wake-up message to the active session (for async results). */
+	sendWakeUp?: (message: string) => void;
+}
+
+const PENDING_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+export class DeliveryCoordinator {
+	private active = false;
+	private generation = 0;
+	private pending: PendingDelivery[] = [];
+	private flushing = false;
+	private readonly deps: DeliveryCoordinatorDeps;
+	private ttlTimer: ReturnType<typeof setInterval> | undefined;
+	private timerStarted = false;
+	private ownerSessionId: string | undefined = undefined;
+
+	constructor(deps: DeliveryCoordinatorDeps) {
+		this.deps = deps;
+	}
+
+	activate(sessionId: string): void {
+		this.ownerSessionId = sessionId;
+		this.active = true;
+		this.flushQueuedResults();
+	}
+
+	deactivate(): void {
+		this.active = false;
+		this.ownerSessionId = undefined;
+		this.generation += 1;
+	}
+
+	isActive(): boolean {
+		return this.active;
+	}
+
+	getPendingCount(): number {
+		return this.pending.length;
+	}
+
+	deliverResult(runId: string, result: unknown): void {
+		if (this.active && this.deps.emit) {
+			try {
+				this.deps.emit("pi-crew:run-result", result);
+				return;
+			} catch (error) {
+				logInternalError("delivery-coordinator.deliverResult", error, `runId=${runId}`);
+			}
+		}
+		if (!this.flushing)
+			this.enqueue({
+				runId,
+				payload: result,
+				timestamp: Date.now(),
+				type: "result",
+			});
+	}
+
+	deliverNotification(notification: NotificationDescriptor): void {
+		let delivered = false;
+		if (this.active && this.deps.sendFollowUp) {
+			try {
+				this.deps.sendFollowUp(notification.title, notification.body ?? "");
+				delivered = true;
+			} catch (error) {
+				logInternalError("delivery-coordinator.deliverNotification", error, `id=${notification.id}`);
+			}
+		}
+		if (delivered) {
+			if (this.deps.emit) {
+				try {
+					this.deps.emit("pi-crew:notification", notification);
+				} catch {
+					/* secondary delivery, ignore errors */
+				}
+			}
+			return;
+		}
+		if (!this.flushing)
+			this.enqueue({
+				runId: notification.runId ?? "",
+				payload: notification,
+				timestamp: Date.now(),
+				type: "notification",
+			});
+	}
+
+	deliverSteer(runId: string, message: string): void {
+		if (this.active && this.deps.sendWakeUp) {
+			try {
+				this.deps.sendWakeUp(message);
+				return;
+			} catch (error) {
+				logInternalError("delivery-coordinator.deliverSteer", error, `runId=${runId}`);
+			}
+		}
+		if (!this.flushing)
+			this.enqueue({
+				runId,
+				payload: message,
+				timestamp: Date.now(),
+				type: "steer",
+			});
+	}
+
+	flushQueuedResults(): void {
+		if (!this.active || this.pending.length === 0) return;
+		// HIGH-16/ MEDIUM-16: Set flushing BEFORE splice to prevent re-entrancy
+		if (this.flushing) return;
+		this.flushing = true;
+		// Note: this.flushing is now set, so concurrent calls will exit early due to the check above
+		// This serves as a simple lock to prevent race conditions
+		const batch = this.pending.splice(0);
+		try {
+			const retryLater: PendingDelivery[] = [];
+			for (const delivery of batch) {
+				if (delivery.type === "steer" && delivery.generation !== undefined && delivery.generation !== this.generation) {
+					logInternalError("delivery-coordinator.flush.stale", undefined, `runId=${delivery.runId} type=${delivery.type}`);
+					continue;
+				}
+				try {
+					if (!this.deliverQueued(delivery))
+						retryLater.push({
+							...delivery,
+							generation: this.generation,
+						});
+				} catch (error) {
+					logInternalError("delivery-coordinator.flush", error, `runId=${delivery.runId} type=${delivery.type}`);
+					retryLater.push({
+						...delivery,
+						generation: this.generation,
+					});
+				}
+			}
+			this.pending.unshift(...retryLater);
+		} finally {
+			this.flushing = false;
+		}
+	}
+
+	dispose(): void {
+		this.deactivate();
+		this.pending.length = 0;
+		if (this.ttlTimer) {
+			clearInterval(this.ttlTimer);
+			this.ttlTimer = undefined;
+		}
+	}
+
+	private deliverQueued(delivery: PendingDelivery): boolean {
+		switch (delivery.type) {
+			case "result":
+				if (!this.deps.emit) return false;
+				this.deps.emit("pi-crew:run-result", delivery.payload);
+				return true;
+			case "notification": {
+				const notification = delivery.payload as NotificationDescriptor;
+				if (!this.deps.sendFollowUp) return false;
+				this.deps.sendFollowUp(notification.title, notification.body ?? "");
+				try {
+					this.deps.emit?.("pi-crew:notification", notification);
+				} catch {
+					// Secondary event delivery must not consume the user-facing notification.
+				}
+				return true;
+			}
+			case "steer": {
+				if (!this.deps.sendWakeUp) return false;
+				const message = typeof delivery.payload === "string" ? delivery.payload : String(delivery.payload);
+				this.deps.sendWakeUp(message);
+				return true;
+			}
+		}
+	}
+
+	private enqueue(delivery: PendingDelivery): void {
+		// Lazily start the TTL timer on first enqueue (only if never started)
+		if (!this.timerStarted) {
+			this.timerStarted = true;
+			this.ttlTimer = setInterval(() => this.evictExpired(), 60_000);
+			this.ttlTimer.unref();
+		}
+		this.pending.push({ ...delivery, generation: this.generation });
+	}
+
+	private evictExpired(): void {
+		const cutoff = Date.now() - PENDING_TTL_MS;
+		const before = this.pending.length;
+		this.pending = this.pending.filter((d) => d.timestamp > cutoff);
+		const evicted = before - this.pending.length;
+		if (evicted > 0) {
+			logInternalError("delivery-coordinator.evict", undefined, `evicted=${evicted} remaining=${this.pending.length}`);
+		}
+	}
+}

package/src/runtime/delta-conflict.ts

@@ -0,0 +1,348 @@
+/**
+ * Delta conflict detection for pi-crew import and resume operations.
+ *
+ * Compares incoming bundles against existing state to surface conflicts
+ * (file overwrites, status mismatches, schema drift, deleted resources)
+ * without blocking the operation — only reporting for user awareness.
+ */
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export type ConflictKind = "file_overwrite" | "state_mismatch" | "schema_drift" | "resource_deleted";
+
+export interface Conflict {
+	kind: ConflictKind;
+	/** File or resource path that is in conflict. */
+	path: string;
+	/** Current value or summary (optional). */
+	existing?: string;
+	/** Incoming value or summary (optional). */
+	incoming?: string;
+	severity: "error" | "warning";
+	autoResolvable: boolean;
+}
+
+export interface ConflictReport {
+	hasConflicts: boolean;
+	conflicts: Conflict[];
+	summary: { errors: number; warnings: number; autoResolvable: number };
+}
+
+export type ConflictStrategy = "skip" | "overwrite" | "merge";
+
+export interface ConflictResolution {
+	resolved: boolean;
+	action: string;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+interface TaskLike {
+	id: string;
+	status: string;
+	role?: string;
+	agent?: string;
+}
+
+function buildReport(conflicts: Conflict[]): ConflictReport {
+	const errors = conflicts.filter((c) => c.severity === "error").length;
+	const warnings = conflicts.filter((c) => c.severity === "warning").length;
+	const autoResolvable = conflicts.filter((c) => c.autoResolvable).length;
+	return {
+		hasConflicts: conflicts.length > 0,
+		conflicts,
+		summary: { errors, warnings, autoResolvable },
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Extract task-like objects from an unknown array, filtering out non-records.
+ */
+function extractTaskLikes(tasks: unknown[]): TaskLike[] {
+	return tasks
+		.filter(isRecord)
+		.map((t) => ({
+			id: typeof t.id === "string" ? t.id : "",
+			status: typeof t.status === "string" ? t.status : "",
+			role: typeof t.role === "string" ? t.role : undefined,
+			agent: typeof t.agent === "string" ? t.agent : undefined,
+		}))
+		.filter((t) => t.id !== "");
+}
+
+// ── Import Conflict Detection ──────────────────────────────────────────
+
+export interface ImportBundle {
+	manifest: Record<string, unknown>;
+	tasks: unknown[];
+	events?: unknown[];
+}
+
+export interface ExistingState {
+	manifest?: Record<string, unknown>;
+	tasks?: unknown[];
+}
+
+/**
+ * Detect conflicts between an import bundle and existing run state.
+ *
+ * Checks:
+ * - **schema_drift**: manifest `schemaVersion` differs between import and existing.
+ * - **file_overwrite**: artifact paths in the import bundle that already exist
+ *   in the current manifest's artifact list.
+ * - **state_mismatch**: task statuses differ between import and existing tasks.
+ * - **resource_deleted**: referenced agent/team/workflow in import does not exist
+ *   in the current state.
+ */
+export function detectImportConflicts(importBundle: ImportBundle, existingState: ExistingState): ConflictReport {
+	const conflicts: Conflict[] = [];
+	const { manifest: incoming, tasks: incomingTasks } = importBundle;
+	const { manifest: current, tasks: currentTasks } = existingState;
+
+	// ── Schema drift ─────────────────────────────────────────────────
+	if (current) {
+		const incomingVersion = incoming.schemaVersion;
+		const currentVersion = current.schemaVersion;
+		if (typeof incomingVersion !== "undefined" && typeof currentVersion !== "undefined" && incomingVersion !== currentVersion) {
+			conflicts.push({
+				kind: "schema_drift",
+				path: "manifest.schemaVersion",
+				existing: String(currentVersion),
+				incoming: String(incomingVersion),
+				severity: "warning",
+				autoResolvable: true,
+			});
+		}
+	}
+
+	// ── File overwrite (artifact collision) ──────────────────────────
+	const incomingArtifacts = Array.isArray(incoming.artifacts) ? incoming.artifacts : [];
+	const currentArtifacts = Array.isArray(current?.artifacts) ? current?.artifacts : [];
+
+	if (current && currentArtifacts.length > 0) {
+		const currentPaths = new Set(
+			currentArtifacts
+				.filter(isRecord)
+				.map((a) => (typeof a.path === "string" ? a.path : ""))
+				.filter((p) => p !== ""),
+		);
+
+		for (const artifact of incomingArtifacts) {
+			if (!isRecord(artifact)) continue;
+			const artifactPath = typeof artifact.path === "string" ? artifact.path : "";
+			if (artifactPath !== "" && currentPaths.has(artifactPath)) {
+				conflicts.push({
+					kind: "file_overwrite",
+					path: artifactPath,
+					existing: "present in current run",
+					incoming: "present in import bundle",
+					severity: "warning",
+					autoResolvable: true,
+				});
+			}
+		}
+	}
+
+	// ── State mismatch (task status differences) ─────────────────────
+	if (currentTasks && currentTasks.length > 0) {
+		const currentTaskMap = new Map(extractTaskLikes(currentTasks).map((t) => [t.id, t]));
+		const incomingTaskList = extractTaskLikes(incomingTasks);
+
+		for (const inTask of incomingTaskList) {
+			const curTask = currentTaskMap.get(inTask.id);
+			if (curTask && curTask.status !== inTask.status) {
+				conflicts.push({
+					kind: "state_mismatch",
+					path: `tasks/${inTask.id}`,
+					existing: curTask.status,
+					incoming: inTask.status,
+					severity: "error",
+					autoResolvable: false,
+				});
+			}
+		}
+	}
+
+	// ── Resource deleted (agent/team/workflow no longer in current) ──
+	if (current) {
+		const currentTeam = typeof current.team === "string" ? current.team : undefined;
+		const currentWorkflow = typeof current.workflow === "string" ? current.workflow : undefined;
+		const incomingTeam = typeof incoming.team === "string" ? incoming.team : undefined;
+		const incomingWorkflow = typeof incoming.workflow === "string" ? incoming.workflow : undefined;
+
+		if (incomingTeam && currentTeam && incomingTeam !== currentTeam) {
+			conflicts.push({
+				kind: "resource_deleted",
+				path: `team/${incomingTeam}`,
+				existing: currentTeam,
+				incoming: incomingTeam,
+				severity: "warning",
+				autoResolvable: true,
+			});
+		}
+
+		if (incomingWorkflow && currentWorkflow && incomingWorkflow !== currentWorkflow) {
+			conflicts.push({
+				kind: "resource_deleted",
+				path: `workflow/${incomingWorkflow}`,
+				existing: currentWorkflow,
+				incoming: incomingWorkflow,
+				severity: "warning",
+				autoResolvable: true,
+			});
+		}
+
+		// Check agent references from tasks vs current tasks
+		if (currentTasks && currentTasks.length > 0) {
+			const currentAgents = new Set(
+				extractTaskLikes(currentTasks)
+					.map((t) => t.agent)
+					.filter((a): a is string => a !== undefined),
+			);
+			const incomingTaskList = extractTaskLikes(incomingTasks);
+			for (const inTask of incomingTaskList) {
+				if (
+					inTask.agent &&
+					inTask.id !== "" &&
+					currentAgents.size > 0 &&
+					!currentAgents.has(inTask.agent) &&
+					// Only flag if there's a matching task id (agent was reassigned)
+					extractTaskLikes(currentTasks).some((ct) => ct.id === inTask.id)
+				) {
+					conflicts.push({
+						kind: "resource_deleted",
+						path: `agent/${inTask.agent}`,
+						existing: "not in current run",
+						incoming: inTask.agent,
+						severity: "warning",
+						autoResolvable: true,
+					});
+				}
+			}
+		}
+	}
+
+	return buildReport(conflicts);
+}
+
+// ── Resume Conflict Detection ──────────────────────────────────────────
+
+export interface SuspendedState {
+	tasks: unknown[];
+	artifacts: string[];
+}
+
+export interface CurrentState {
+	changedFiles: string[];
+	taskStatuses: Record<string, string>;
+}
+
+/**
+ * Detect conflicts when resuming a suspended run against current filesystem state.
+ *
+ * Checks:
+ * - **file_overwrite**: files changed since suspension.
+ * - **state_mismatch**: task statuses changed externally.
+ */
+export function detectResumeConflicts(suspendedState: SuspendedState, currentState: CurrentState): ConflictReport {
+	const conflicts: Conflict[] = [];
+	const { tasks: suspendedTasks, artifacts: suspendedArtifacts } = suspendedState;
+	const { changedFiles, taskStatuses } = currentState;
+
+	// ── File overwrite ───────────────────────────────────────────────
+	const changedSet = new Set(changedFiles);
+	for (const artifactPath of suspendedArtifacts) {
+		if (changedSet.has(artifactPath)) {
+			conflicts.push({
+				kind: "file_overwrite",
+				path: artifactPath,
+				existing: "modified since suspension",
+				incoming: "expected unchanged",
+				severity: "error",
+				autoResolvable: false,
+			});
+		}
+	}
+
+	// ── State mismatch ───────────────────────────────────────────────
+	const suspendedTaskList = extractTaskLikes(suspendedTasks);
+	for (const task of suspendedTaskList) {
+		const currentStatus = taskStatuses[task.id];
+		if (currentStatus !== undefined && currentStatus !== task.status) {
+			conflicts.push({
+				kind: "state_mismatch",
+				path: `tasks/${task.id}`,
+				existing: currentStatus,
+				incoming: task.status,
+				severity: "error",
+				autoResolvable: false,
+			});
+		}
+	}
+
+	return buildReport(conflicts);
+}
+
+// ── Conflict Resolution ────────────────────────────────────────────────
+
+/**
+ * Apply a resolution strategy to a conflict.
+ *
+ * - **skip**: skip the conflicting item (always resolves).
+ * - **overwrite**: replace existing with incoming (resolves for `file_overwrite`
+ *   and `schema_drift`; does not resolve `state_mismatch` or `resource_deleted`).
+ * - **merge**: attempt merge — resolves `state_mismatch` with merged status;
+ *   resolves others conditionally.
+ */
+export function resolveConflict(conflict: Conflict, strategy: ConflictStrategy): ConflictResolution {
+	switch (strategy) {
+		case "skip":
+			return { resolved: true, action: `Skipped ${conflict.path}` };
+
+		case "overwrite":
+			if (conflict.kind === "file_overwrite" || conflict.kind === "schema_drift") {
+				return {
+					resolved: true,
+					action: `Overwritten ${conflict.path} with incoming value`,
+				};
+			}
+			return {
+				resolved: false,
+				action: `Cannot overwrite ${conflict.kind} at ${conflict.path}; manual resolution required`,
+			};
+
+		case "merge":
+			if (conflict.kind === "state_mismatch") {
+				return {
+					resolved: true,
+					action: `Merged ${conflict.path}: kept existing=${conflict.existing ?? "?"}, incoming=${conflict.incoming ?? "?"}`,
+				};
+			}
+			if (conflict.kind === "resource_deleted") {
+				return {
+					resolved: true,
+					action: `Merged ${conflict.path}: using incoming resource reference`,
+				};
+			}
+			if (conflict.kind === "file_overwrite") {
+				return {
+					resolved: true,
+					action: `Merged ${conflict.path}: kept both versions`,
+				};
+			}
+			if (conflict.kind === "schema_drift") {
+				return {
+					resolved: true,
+					action: `Merged ${conflict.path}: using incoming schema version`,
+				};
+			}
+			return {
+				resolved: false,
+				action: `Cannot merge ${conflict.kind} at ${conflict.path}`,
+			};
+	}
+}