pi-crew 0.2.3 → 0.2.5

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

@@ -1,90 +1,90 @@
-/**
- * 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 "@mariozechner/pi-coding-agent";
-import { Type, type Static } from "@sinclair/typebox";
-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 {
-				// Yield handler failure should not prevent tool response
-			}
-			return response;
-		},
-	});
-}
+/**
+ * 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 "@mariozechner/pi-coding-agent";
+import { Type, type Static } from "@sinclair/typebox";
+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 {
+				// Yield handler failure should not prevent tool response
+			}
+			return response;
+		},
+	});
+}

package/src/runtime/deadletter.ts

@@ -1,47 +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 [];
-		}
-	});
-}
+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

@@ -1,177 +1,177 @@
-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 ownerSessionId: string | undefined;
-	private active = false;
-	private generation = 0;
-	private pending: PendingDelivery[] = [];
-	private flushing = false;
-	private readonly deps: DeliveryCoordinatorDeps;
-	private ttlTimer: ReturnType<typeof setInterval> | undefined;
-
-	constructor(deps: DeliveryCoordinatorDeps) {
-		this.deps = deps;
-		this.ttlTimer = setInterval(() => this.evictExpired(), 60_000);
-		this.ttlTimer.unref();
-	}
-
-	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;
-		// H7: Set flushing BEFORE splice to prevent re-entrancy
-		if (this.flushing) return;
-		this.flushing = true;
-		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 {
-		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}`);
-		}
-	}
+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 ownerSessionId: string | undefined;
+	private active = false;
+	private generation = 0;
+	private pending: PendingDelivery[] = [];
+	private flushing = false;
+	private readonly deps: DeliveryCoordinatorDeps;
+	private ttlTimer: ReturnType<typeof setInterval> | undefined;
+
+	constructor(deps: DeliveryCoordinatorDeps) {
+		this.deps = deps;
+		this.ttlTimer = setInterval(() => this.evictExpired(), 60_000);
+		this.ttlTimer.unref();
+	}
+
+	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;
+		// H7: Set flushing BEFORE splice to prevent re-entrancy
+		if (this.flushing) return;
+		this.flushing = true;
+		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 {
+		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}`);
+		}
+	}
 }