pi-crew 0.1.45 → 0.1.49

package/src/runtime/custom-tools/irc-tool.ts

@@ -0,0 +1,201 @@
+/**
+ * G1: Custom tool — irc.
+ *
+ * Registers a real `irc` tool in the Pi SDK session so that
+ * live-session workers can send messages to other live agents.
+ *
+ * Operations:
+ * - `list`: List currently visible peer agents
+ * - `send`: Send a message to a specific agent or broadcast to all
+ *
+ * Adapted from oh-my-pi's `IrcTool` pattern. Uses the live-agent-manager
+ * for routing messages between in-process workers.
+ */
+
+import { defineTool, type ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { Type, type Static } from "@sinclair/typebox";
+import { listLiveAgents, sendIrcMessage, broadcastIrcMessage } from "../live-agent-manager.ts";
+import type { IrcMessage } from "../live-irc.ts";
+
+const IrcParams = Type.Object({
+	op: Type.Union(
+		[
+			Type.Literal("send", { description: "Send a message to one peer or to all peers." }),
+			Type.Literal("list", { description: "List currently visible peers." }),
+		],
+		{ description: "IRC operation." },
+	),
+	to: Type.Optional(
+		Type.String({
+			description: 'Recipient agent ID or "all" to broadcast.',
+		}),
+	),
+	message: Type.Optional(
+		Type.String({
+			description: "Message body to deliver.",
+		}),
+	),
+	awaitReply: Type.Optional(
+		Type.Boolean({
+			description: "Wait for a reply (default: true for DM, false for broadcast). Not yet supported — messages are fire-and-forget.",
+		}),
+	),
+});
+
+type IrcParams = Static<typeof IrcParams>;
+
+interface IrcDetails {
+	op: "send" | "list";
+	from?: string;
+	to?: string;
+	delivered?: string[];
+	notFound?: string[];
+	peers?: Array<{ id: string; status: string }>;
+	error?: string;
+}
+
+/**
+ * Create an `irc` tool definition for a specific agent.
+ *
+ * @param selfId — This agent's ID (runId:taskId format)
+ */
+export function createIrcTool(
+	selfId: string,
+): ToolDefinition<typeof IrcParams, IrcDetails> {
+	return defineTool({
+		name: "irc",
+		label: "IRC",
+		description:
+			"Send messages to other live agents in same team. " +
+			'Use `op: "list"` to see peers, `op: "send"` with `to` (agent ID or "all") and `message` to communicate.',
+		parameters: IrcParams,
+		promptSnippet: "Send messages to other live agents via the irc tool",
+		promptGuidelines: [
+			"Use irc to coordinate with other agents when you need information or want to share findings.",
+			'Use `op: "list"` first to discover available peers.',
+		],
+		async execute(
+			_toolCallId: string,
+			params: IrcParams,
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			_ctx: unknown,
+		): Promise<{ content: Array<{ type: "text"; text: string }>; details: IrcDetails }> {
+			if (params.op === "list") {
+				return executeList(selfId);
+			}
+			if (params.op === "send") {
+				return executeSend(selfId, params);
+			}
+			return {
+				content: [{ type: "text", text: "Unknown irc op." }],
+				details: { op: params.op, from: selfId, error: "Unknown operation." },
+			};
+		},
+	});
+}
+
+function executeList(selfId: string): { content: Array<{ type: "text"; text: string }>; details: IrcDetails } {
+	const agents = listLiveAgents();
+	const peers = agents
+		.filter((a) => a.agentId !== selfId && (a.status === "running" || a.status === "queued"))
+		.map((a) => ({ id: a.agentId, status: a.status }));
+
+	const lines: string[] = [];
+	if (peers.length === 0) {
+		lines.push("No other live agents.");
+	} else {
+		lines.push(`${peers.length} peer(s):`);
+		for (const peer of peers) {
+			lines.push(`- ${peer.id} (${peer.status})`);
+		}
+	}
+
+	return {
+		content: [{ type: "text", text: lines.join("\n") }],
+		details: { op: "list", from: selfId, peers },
+	};
+}
+
+function executeSend(
+	selfId: string,
+	params: IrcParams,
+): { content: Array<{ type: "text"; text: string }>; details: IrcDetails } {
+	const to = params.to?.trim();
+	const message = params.message?.trim();
+
+	if (!to) {
+		return {
+			content: [{ type: "text", text: '`to` is required for op="send".' }],
+			details: { op: "send", from: selfId, error: "Missing 'to' field." },
+		};
+	}
+	if (!message) {
+		return {
+			content: [{ type: "text", text: '`message` is required for op="send".' }],
+			details: { op: "send", from: selfId, to, error: "Missing 'message' field." },
+		};
+	}
+	if (to === selfId) {
+		return {
+			content: [{ type: "text", text: "Cannot send a message to yourself." }],
+			details: { op: "send", from: selfId, to, error: "Self-message not allowed." },
+		};
+	}
+
+	const ircMessage: IrcMessage = {
+		from: selfId,
+		to,
+		content: message,
+		timestamp: new Date().toISOString(),
+		awaitReply: params.awaitReply,
+	};
+
+	const notFound: string[] = [];
+	const delivered: string[] = [];
+
+	try {
+		if (to === "all") {
+			const recipients = broadcastIrcMessage(selfId, ircMessage);
+			delivered.push(...recipients);
+		} else {
+			// DM to specific agent
+			const agents = listLiveAgents();
+			const target = agents.find((a) => a.agentId === to);
+			if (!target || (target.status !== "running" && target.status !== "queued")) {
+				notFound.push(to);
+			} else {
+				try {
+					sendIrcMessage(to, ircMessage);
+					delivered.push(to);
+				} catch {
+					notFound.push(to);
+				}
+			}
+		}
+	} catch {
+		// Agent deregistered during routing — treat as not found
+		notFound.push(to);
+	}
+
+	const lines: string[] = [];
+	if (delivered.length > 0) {
+		lines.push(`Delivered to ${delivered.length} peer(s): ${delivered.join(", ")}`);
+	} else {
+		lines.push("No recipients received the message.");
+	}
+	if (notFound.length > 0) {
+		lines.push(`Unknown / unavailable peers: ${notFound.join(", ")}`);
+	}
+
+	return {
+		content: [{ type: "text", text: lines.join("\n") }],
+		details: {
+			op: "send",
+			from: selfId,
+			to,
+			delivered: delivered.length > 0 ? delivered : undefined,
+			notFound: notFound.length > 0 ? notFound : undefined,
+		},
+	};
+}

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

@@ -0,0 +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;
+		},
+	});
+}

package/src/runtime/deadletter.ts

@@ -12,6 +12,7 @@ export interface DeadletterEntry {
 	reason: DeadletterReason;
 	attempts: number;
 	lastError?: string;
+	attemptId?: string;
 	timestamp: string;
 }
 

package/src/runtime/delivery-coordinator.ts

@@ -25,6 +25,7 @@ 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;
 
@@ -63,7 +64,7 @@ export class DeliveryCoordinator {
 				logInternalError("delivery-coordinator.deliverResult", error, `runId=${runId}`);
 			}
 		}
-		this.enqueue({ runId, payload: result, timestamp: Date.now(), type: "result" });
+		if (!this.flushing) this.enqueue({ runId, payload: result, timestamp: Date.now(), type: "result" });
 	}
 
 	deliverNotification(notification: NotificationDescriptor): void {
@@ -84,7 +85,7 @@ export class DeliveryCoordinator {
 			}
 			return;
 		}
-		this.enqueue({ runId: notification.runId ?? "", payload: notification, timestamp: Date.now(), type: "notification" });
+		if (!this.flushing) this.enqueue({ runId: notification.runId ?? "", payload: notification, timestamp: Date.now(), type: "notification" });
 	}
 
 	deliverSteer(runId: string, message: string): void {
@@ -96,36 +97,32 @@ export class DeliveryCoordinator {
 				logInternalError("delivery-coordinator.deliverSteer", error, `runId=${runId}`);
 			}
 		}
-		this.enqueue({ runId, payload: message, timestamp: Date.now(), type: "steer" });
+		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);
-		for (const delivery of batch) {
-			if (delivery.generation !== undefined && delivery.generation !== this.generation) {
-				logInternalError("delivery-coordinator.flush.stale", undefined, `runId=${delivery.runId} type=${delivery.type}`);
-				continue;
-			}
-			try {
-				switch (delivery.type) {
-					case "result":
-						this.deliverResult(delivery.runId, delivery.payload);
-						break;
-					case "notification": {
-						const notification = delivery.payload as NotificationDescriptor;
-						this.deliverNotification(notification);
-						break;
-					}
-					case "steer": {
-						const message = typeof delivery.payload === "string" ? delivery.payload : String(delivery.payload);
-						this.deliverSteer(delivery.runId, message);
-						break;
-					}
+		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 });
 				}
-			} catch (error) {
-				logInternalError("delivery-coordinator.flush", error, `runId=${delivery.runId} type=${delivery.type}`);
 			}
+			this.pending.unshift(...retryLater);
+		} finally {
+			this.flushing = false;
 		}
 	}
 
@@ -138,6 +135,32 @@ export class DeliveryCoordinator {
 		}
 	}
 
+	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 });
 	}

package/src/runtime/effectiveness.ts

@@ -0,0 +1,81 @@
+import { permissionForRole } from "./role-permission.ts";
+import type { CrewRuntimeConfig } from "../config/config.ts";
+import type { PolicyDecision, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+
+export type EffectivenessGuardMode = "off" | "warn" | "block" | "fail";
+export type WorkerExecutionState = "enabled" | "disabled/scaffold";
+export type RunEffectivenessSeverity = "ok" | "warning" | "blocked" | "failed";
+
+export interface RunEffectivenessSummary {
+	completed: number;
+	observable: number;
+	noObservedWorkTaskIds: string[];
+	needsAttentionTaskIds: string[];
+	workerExecution: WorkerExecutionState;
+	guardMode: EffectivenessGuardMode;
+	severity: RunEffectivenessSeverity;
+}
+
+export function taskHasObservableWorkerActivity(task: TeamTaskState): boolean {
+	return Boolean(
+		(task.agentProgress?.toolCount ?? 0) > 0
+		|| task.usage
+		|| task.transcriptArtifact
+		|| task.modelAttempts?.some((attempt) => attempt.success)
+		|| task.jsonEvents,
+	);
+}
+
+export function resolveEffectivenessGuardMode(runtimeConfig: CrewRuntimeConfig | undefined, manifest?: TeamRunManifest): EffectivenessGuardMode {
+	const configured = runtimeConfig?.effectivenessGuard;
+	if (configured === "off" || configured === "warn" || configured === "block" || configured === "fail") return configured;
+	if (manifest?.runtimeResolution?.safety === "explicit_dry_run") return "off";
+	return "warn";
+}
+
+export function evaluateRunEffectiveness(input: { manifest?: TeamRunManifest; tasks: TeamTaskState[]; executeWorkers: boolean; runtimeConfig?: CrewRuntimeConfig }): RunEffectivenessSummary {
+	const completedTasks = input.tasks.filter((task) => task.status === "completed");
+	const noObservedWorkTasks = completedTasks.filter((task) => !taskHasObservableWorkerActivity(task));
+	const needsAttentionTasks = input.tasks.filter((task) => task.agentProgress?.activityState === "needs_attention");
+	const workerExecution: WorkerExecutionState = input.executeWorkers ? "enabled" : "disabled/scaffold";
+	const guardMode = resolveEffectivenessGuardMode(input.runtimeConfig, input.manifest);
+	const observable = Math.max(0, completedTasks.length - noObservedWorkTasks.length - needsAttentionTasks.length);
+	let severity: RunEffectivenessSeverity = "ok";
+	if (input.executeWorkers && guardMode !== "off" && noObservedWorkTasks.length > 0) {
+		severity = guardMode === "fail" ? "failed" : guardMode === "block" ? "blocked" : "warning";
+		// P0.1: default warn escalates to blocked for mutating-role tasks without observed work
+		if (severity === "warning" && noObservedWorkTasks.some((task) => permissionForRole(task.role) !== "read_only")) {
+			severity = "blocked";
+		}
+	}
+	return {
+		completed: completedTasks.length,
+		observable,
+		noObservedWorkTaskIds: noObservedWorkTasks.map((task) => task.id),
+		needsAttentionTaskIds: needsAttentionTasks.map((task) => task.id),
+		workerExecution,
+		guardMode,
+		severity,
+	};
+}
+
+export function formatRunEffectivenessLines(summary: RunEffectivenessSummary): string[] {
+	return [
+		`Score: ${summary.observable}/${Math.max(1, summary.completed)} completed task(s) with observable worker activity`,
+		`Worker execution: ${summary.workerExecution}`,
+		`Guard: ${summary.guardMode} severity=${summary.severity}`,
+		`No observable worker activity: ${summary.noObservedWorkTaskIds.length ? summary.noObservedWorkTaskIds.join(", ") : "none"}`,
+		`Needs attention: ${summary.needsAttentionTaskIds.length ? summary.needsAttentionTaskIds.join(", ") : "none"}`,
+	];
+}
+
+export function effectivenessPolicyDecision(summary: RunEffectivenessSummary): PolicyDecision | undefined {
+	if (summary.severity !== "warning" && summary.severity !== "blocked" && summary.severity !== "failed") return undefined;
+	const action = summary.severity === "failed" ? "fail" : summary.severity === "blocked" ? "block" : "notify";
+	return {
+		action,
+		reason: "ineffective_worker",
+		message: `Run effectiveness guard ${summary.guardMode}: no observable worker activity for ${summary.noObservedWorkTaskIds.join(", ")}.`,
+		createdAt: new Date().toISOString(),
+	};
+}

package/src/runtime/event-stream-bridge.ts

@@ -0,0 +1,90 @@
+import { runEventBus } from "../ui/run-event-bus.ts";
+import { subprocessToolRegistry, type SubprocessToolEvent } from "./subprocess-tool-registry.ts";
+
+export interface StreamBridgeEvent {
+	runId: string;
+	taskId: string;
+	eventType: string;
+	toolName?: string;
+	toolArgs?: string;
+	intent?: string;
+	tokens?: number;
+	timestamp: number;
+	extractedToolData?: Record<string, unknown>;
+}
+
+const activeBridges = new Map<string, (event: StreamBridgeEvent) => void>();
+
+export function registerStreamBridge(runId: string): { handler: (event: StreamBridgeEvent) => void; dispose: () => void } {
+	const existing = activeBridges.get(runId);
+	if (existing) {
+		return { handler: existing, dispose: () => unregisterStreamBridge(runId) };
+	}
+
+	const handler = (event: StreamBridgeEvent) => {
+		runEventBus.emit({
+			type: "worker_status",
+			runId: event.runId,
+			taskId: event.taskId,
+			data: event,
+		});
+	};
+
+	activeBridges.set(runId, handler);
+	return { handler, dispose: () => unregisterStreamBridge(runId) };
+}
+
+export function unregisterStreamBridge(runId: string): void {
+	activeBridges.delete(runId);
+}
+
+export function bridgeEventFromJsonEvent(runId: string, taskId: string, event: unknown): StreamBridgeEvent | null {
+	if (!event || typeof event !== "object") return null;
+	const record = event as Record<string, unknown>;
+	const type = typeof record.type === "string" ? record.type : "";
+
+	const result: StreamBridgeEvent = {
+		runId,
+		taskId,
+		eventType: type,
+		timestamp: Date.now(),
+	};
+
+	if (typeof record.toolName === "string") result.toolName = record.toolName;
+	if (record.args && typeof record.args === "object") {
+		try {
+			result.toolArgs = JSON.stringify(record.args).slice(0, 200);
+		} catch {
+			/* skip */
+		}
+	}
+	if (typeof record.intent === "string") result.intent = record.intent;
+
+	// Extract tokens from usage/message_end events
+	const usage = record.usage ?? (record.message as Record<string, unknown> | undefined)?.usage;
+	if (usage && typeof usage === "object") {
+		const u = usage as Record<string, unknown>;
+		const input = typeof u.input === "number" ? u.input : 0;
+		const output = typeof u.output === "number" ? u.output : 0;
+		if (input || output) result.tokens = input + output;
+	}
+
+	// Attach extracted tool data via subprocess tool registry
+	if (result.toolName && subprocessToolRegistry.hasHandler(result.toolName)) {
+		const handler = subprocessToolRegistry.getHandler(result.toolName);
+		if (handler?.extractData) {
+			const extracted = handler.extractData({
+				toolName: result.toolName,
+				toolCallId: (record.toolCallId as string) ?? "",
+				args: record.args as Record<string, unknown> | undefined,
+				result: record.result as SubprocessToolEvent["result"],
+				isError: record.isError as boolean | undefined,
+			});
+			if (extracted !== undefined) {
+				result.extractedToolData = { [result.toolName]: extracted };
+			}
+		}
+	}
+
+	return result;
+}

package/src/runtime/live-agent-control.ts

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import type { TeamRunManifest } from "../state/types.ts";
 import { agentStateFile, ensureAgentStateDir } from "./crew-agent-records.ts";
 
-export type LiveAgentControlOperation = "steer" | "stop" | "resume";
+export type LiveAgentControlOperation = "steer" | "follow-up" | "stop" | "resume";
 
 export interface LiveAgentControlRequest {
 	id: string;
@@ -75,6 +75,7 @@ export async function applyLiveAgentControlRequest(input: { request: LiveAgentCo
 	if (request.agentId && request.agentId !== agentId && request.agentId !== taskId) return false;
 	seenRequestIds?.add(request.id);
 	if (request.operation === "steer") await session.steer?.(request.message ?? "Please report current status and wrap up if possible.");
+	else if (request.operation === "follow-up") await session.prompt?.(request.message ?? "Please continue with the follow-up request.", { source: "api", expandPromptTemplates: false });
 	else if (request.operation === "resume") await session.prompt?.(request.message ?? "Please resume and report final status.", { source: "api", expandPromptTemplates: false });
 	else if (request.operation === "stop") await session.abort?.();
 	return true;