pi-crew 0.9.53 → 0.9.55

package/src/runtime/crew-hooks.ts

@@ -0,0 +1,227 @@
+/**
+ * Crew Hook System — a hook-based observation system for pi-crew runtime.
+ *
+ * Provides a reliable, fire-and-forget event system for observing crew lifecycle events.
+ * Hooks are executed synchronously without blocking the emitter.
+ *
+ * @example
+ * ```typescript
+ * import { crewHooks } from './runtime/crew-hooks.ts';
+ *
+ * // Register a hook
+ * const myHook = (event) => {
+ *   console.log(`Event: ${event.type}`, event);
+ * };
+ * crewHooks.register('task_started', myHook);
+ *
+ * // Emit an event
+ * crewHooks.emit({ type: 'task_started', timestamp: new Date().toISOString(), runId: 'run-123', taskId: 'task-1' });
+ *
+ * // Unregister when done
+ * crewHooks.unregister('task_started', myHook);
+ * ```
+ */
+
+import { logInternalError } from "../utils/internal-error.ts";
+
+/** Valid hook event types in the crew lifecycle. */
+export type CrewHookEventType = "task_started" | "task_completed" | "task_failed" | "run_completed" | "run_failed";
+
+/**
+ * A hook event emitted by the crew runtime.
+ */
+export interface CrewHookEvent {
+	/** The type of event being emitted. */
+	type: CrewHookEventType;
+	/** ISO timestamp of when the event occurred. */
+	timestamp: string;
+	/** The unique identifier of the run that generated this event. */
+	runId: string;
+	/** Optional task identifier (present for task-scoped events). */
+	taskId?: string;
+	/** Optional additional event data. */
+	data?: Record<string, unknown>;
+}
+
+/**
+ * A hook function that can be registered to receive crew events.
+ * May be synchronous or return a Promise (async hooks are fire-and-forget).
+ */
+export type CrewHook = (event: CrewHookEvent) => void | Promise<void>;
+
+/**
+ * Type guard to check if a value is a valid CrewHookEventType.
+ */
+export function isValidEventType(type: string): type is CrewHookEventType {
+	return (
+		type === "task_started" || type === "task_completed" || type === "task_failed" || type === "run_completed" || type === "run_failed"
+	);
+}
+
+/**
+ * Type guard to check if an object is a valid CrewHookEvent.
+ */
+export function isHookEvent(obj: unknown): obj is CrewHookEvent {
+	if (typeof obj !== "object" || obj === null) return false;
+	const event = obj as Record<string, unknown>;
+	return (
+		typeof event.type === "string" &&
+		isValidEventType(event.type) &&
+		typeof event.timestamp === "string" &&
+		typeof event.runId === "string" &&
+		(event.taskId === undefined || typeof event.taskId === "string") &&
+		(event.data === undefined || typeof event.data === "object")
+	);
+}
+
+/**
+ * Registry for managing and emitting crew lifecycle hooks.
+ *
+ * Hooks are stored in Sets for efficient insertion, deletion, and iteration.
+ * The emit() method executes all registered hooks synchronously without awaiting
+ * async completions, ensuring 100% reliable event firing without blocking.
+ */
+export class HookRegistry {
+	private readonly hooks: Map<CrewHookEventType, Set<CrewHook>>;
+
+	constructor() {
+		this.hooks = new Map();
+		// Initialize with empty Sets for all event types
+		const eventTypes: CrewHookEventType[] = ["task_started", "task_completed", "task_failed", "run_completed", "run_failed"];
+		for (const type of eventTypes) {
+			this.hooks.set(type, new Set());
+		}
+	}
+
+	/**
+	 * Register a hook to be called when the specified event type is emitted.
+	 *
+	 * @param eventType - The type of event to listen for
+	 * @param hook - The hook function to register
+	 */
+	register(eventType: CrewHookEventType, hook: CrewHook): void {
+		const hooksForType = this.hooks.get(eventType);
+		if (hooksForType) {
+			hooksForType.add(hook);
+		}
+	}
+
+	/**
+	 * Unregister a previously registered hook.
+	 *
+	 * @param eventType - The type of event the hook was registered for
+	 * @param hook - The hook function to remove
+	 */
+	unregister(eventType: CrewHookEventType, hook: CrewHook): void {
+		const hooksForType = this.hooks.get(eventType);
+		if (hooksForType) {
+			hooksForType.delete(hook);
+		}
+	}
+
+	/**
+	 * Emit an event to all registered hooks for that event type.
+	 *
+	 * This method executes all hooks synchronously and does not await async hooks.
+	 * Errors thrown by hooks are caught and logged but do not prevent other hooks
+	 * from executing or block the caller.
+	 *
+	 * @param event - The event to emit
+	 */
+	emit(event: CrewHookEvent): void {
+		// Validate event type using type guard
+		if (!isValidEventType(event.type)) {
+			logInternalError("crew-hooks.unknown-event-type", new Error(`Unknown event type: ${event.type}`));
+			return;
+		}
+
+		const hooksForType = this.hooks.get(event.type);
+		if (!hooksForType || hooksForType.size === 0) {
+			return;
+		}
+
+		// Execute all hooks - fire-and-forget pattern
+		// We iterate over a snapshot to allow safe modification during iteration
+		const hooksSnapshot = Array.from(hooksForType);
+		for (const hook of hooksSnapshot) {
+			try {
+				const result = hook(event);
+				// If the hook returns a Promise, we intentionally do NOT await it.
+				// This is the "fire-and-forget" pattern - async hooks run in background.
+				if (result instanceof Promise) {
+					// Attach a silent catch to prevent unhandled rejection warnings
+					result.catch((err) => {
+						logInternalError("crew-hooks.async", err, `event.type=${event.type}`);
+					});
+				}
+			} catch (err) {
+				// Catch synchronous errors but don't let them block other hooks
+				logInternalError("crew-hooks.sync", err, `event.type=${event.type}`);
+			}
+		}
+	}
+
+	/**
+	 * Get all hooks registered for a specific event type.
+	 *
+	 * Returns a snapshot of the current hooks. The returned array is a new copy,
+	 * so modifications to it won't affect the registry.
+	 *
+	 * @param eventType - The event type to query
+	 * @returns Array of registered hooks (may be empty)
+	 */
+	hooksFor(eventType: CrewHookEventType): CrewHook[] {
+		const hooksForType = this.hooks.get(eventType);
+		if (!hooksForType) {
+			return [];
+		}
+		return Array.from(hooksForType);
+	}
+
+	/**
+	 * Get the count of hooks registered for a specific event type.
+	 *
+	 * @param eventType - The event type to query
+	 * @returns Number of registered hooks
+	 */
+	count(eventType: CrewHookEventType): number {
+		const hooksForType = this.hooks.get(eventType);
+		return hooksForType?.size ?? 0;
+	}
+
+	/**
+	 * Remove all hooks for a specific event type.
+	 *
+	 * @param eventType - The event type to clear
+	 */
+	clear(eventType: CrewHookEventType): void {
+		const hooksForType = this.hooks.get(eventType);
+		if (hooksForType) {
+			hooksForType.clear();
+		}
+	}
+
+	/**
+	 * Remove all registered hooks across all event types.
+	 */
+	clearAll(): void {
+		for (const hooksForType of this.hooks.values()) {
+			hooksForType.clear();
+		}
+	}
+}
+
+/**
+ * Global singleton instance of HookRegistry for use throughout pi-crew.
+ *
+ * @example
+ * ```typescript
+ * import { crewHooks } from './runtime/crew-hooks.ts';
+ *
+ * // Simple logging hook
+ * crewHooks.register('task_completed', (event) => {
+ *   console.log(`Task ${event.taskId} completed in run ${event.runId}`);
+ * });
+ * ```
+ */
+export const crewHooks = new HookRegistry();

package/src/runtime/cross-extension-rpc.ts

@@ -0,0 +1,143 @@
+import * as crypto from "node:crypto";
+import { extractSignaturePayload, isHmacEnabled, verifyRpcSignature } from "../extension/rpc-hmac.ts";
+
+export interface EventBus {
+	on(event: string, handler: (data: unknown) => void): () => void;
+	emit(event: string, data: unknown): void;
+}
+
+export type RpcReply<T = void> = { success: true; data?: T } | { success: false; error: string };
+
+export const PROTOCOL_VERSION = 1;
+
+// H-2 fix (code-review 2026-06-23): the old authorization relied on a
+// self-declared `source === "pi-crew"` field, which any co-installed
+// extension on the shared event bus can spoof. We now also require an
+// unguessable per-process token. Only in-process pi-crew code can obtain it
+// via getCrewRpcToken(); a cross-extension attacker cannot forge a UUID it
+// has never seen. (A full fix still needs event-bus-level origin signing, but
+// this closes the trivial spoof.)
+let CREW_RPC_TOKEN: string | undefined;
+/** @internal Per-process token that legitimate in-process RPC callers must include. */
+export function getCrewRpcToken(): string {
+	if (!CREW_RPC_TOKEN) CREW_RPC_TOKEN = crypto.randomUUID();
+	return CREW_RPC_TOKEN;
+}
+
+export interface RpcDeps {
+	events: EventBus;
+	getCtx: () => unknown | undefined;
+	spawn: (type: string, prompt: string, options?: Record<string, unknown>) => string;
+	abort: (agentId: string) => boolean;
+}
+
+export interface RpcHandle {
+	unsubPing: () => void;
+	unsubSpawn: () => void;
+	unsubStop: () => void;
+}
+
+function handleRpc<P extends { requestId: string }>(
+	events: EventBus,
+	channel: string,
+	fn: (params: P) => unknown | Promise<unknown>,
+): () => void {
+	return events.on(channel, async (raw: unknown) => {
+		const params = raw as P;
+		// SECURITY: Validate requestId format to prevent channel injection.
+		if (!/^[a-zA-Z0-9_-]+$/.test(params.requestId)) {
+			throw new Error("Security: invalid requestId format");
+		}
+		// SECURITY: HMAC signature verification (when enabled).
+		if (isHmacEnabled()) {
+			const sigPayload = extractSignaturePayload(params);
+			if (!sigPayload) {
+				throw new Error("[pi-crew HMAC] Missing HMAC signature in RPC request.");
+			}
+			// Strip HMAC fields before verification (HMAC was signed over original params)
+			const originalParams = { ...params };
+			delete (originalParams as Record<string, unknown>).hmacVersion;
+			delete (originalParams as Record<string, unknown>).hmacOrigin;
+			delete (originalParams as Record<string, unknown>).hmacTimestamp;
+			delete (originalParams as Record<string, unknown>).hmacChannel;
+			delete (originalParams as Record<string, unknown>).hmacNonce;
+			delete (originalParams as Record<string, unknown>).hmacSignature;
+			const verification = verifyRpcSignature(sigPayload, originalParams);
+			if (!verification.valid) {
+				throw new Error(`[pi-crew HMAC] ${verification.reason}`);
+			}
+		}
+		try {
+			const data = await fn(params);
+			const reply: { success: true; data?: unknown } = { success: true };
+			if (data !== undefined) reply.data = data;
+			events.emit(`${channel}:reply:${params.requestId}`, reply);
+		} catch (err: unknown) {
+			events.emit(`${channel}:reply:${params.requestId}`, {
+				success: false,
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+	});
+}
+
+export function registerCrewRpcHandlers(deps: RpcDeps): RpcHandle {
+	const { events, getCtx, spawn, abort } = deps;
+
+	const unsubPing = handleRpc(events, "crew:rpc:ping", () => {
+		return { version: PROTOCOL_VERSION };
+	});
+
+	// SECURITY TRUST BOUNDARY: crew:rpc:spawn and crew:rpc:stop are privileged
+	// operations that create or terminate child processes. Any subscriber on
+	// the shared event bus can emit these events. In a multi-extension
+	// environment, this means a malicious extension could spawn/stop agents.
+	// Mitigations: HMAC origin signing (see rpc-hmac.ts) + per-process token
+	// (H-2) + legacy `source` identifier.
+	const CREW_RPC_SOURCE = "pi-crew";
+	const EXPECTED_TOKEN = getCrewRpcToken();
+
+	function validateRpcSource(params: { requestId: string; source?: string; token?: string }): boolean {
+		if (params.token !== EXPECTED_TOKEN) {
+			console.warn(
+				`[pi-crew SECURITY] RPC invocation rejected: missing/invalid token (source=${params.source ?? "(none)"}). ` +
+					`Privileged RPC requires the in-process token. Request may be from an untrusted extension.`,
+			);
+			return false;
+		}
+		if (!params.source || params.source !== CREW_RPC_SOURCE) {
+			console.warn(
+				`[pi-crew SECURITY] RPC invocation from unexpected source: ${params.source ?? "(none)"}. ` +
+					`Expected '${CREW_RPC_SOURCE}'. Request may be from an untrusted extension.`,
+			);
+			return false;
+		}
+		return true;
+	}
+
+	const unsubSpawn = handleRpc<{
+		requestId: string;
+		type: string;
+		prompt: string;
+		options?: Record<string, unknown>;
+		source?: string;
+		token?: string;
+	}>(events, "crew:rpc:spawn", (params) => {
+		if (!validateRpcSource(params)) throw new Error("Unauthorized: RPC spawn requires valid token and source='pi-crew'");
+		const ctx = getCtx();
+		if (!ctx) throw new Error("No active session");
+		return { id: spawn(params.type, params.prompt, params.options ?? {}) };
+	});
+
+	const unsubStop = handleRpc<{
+		requestId: string;
+		agentId: string;
+		source?: string;
+		token?: string;
+	}>(events, "crew:rpc:stop", (params) => {
+		if (!validateRpcSource(params)) throw new Error("Unauthorized: RPC stop requires valid token and source='pi-crew'");
+		if (!abort(params.agentId)) throw new Error("Agent not found");
+	});
+
+	return { unsubPing, unsubSpawn, unsubStop };
+}

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

@@ -0,0 +1,282 @@
+/**
+ * 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 "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "@sinclair/typebox";
+import { broadcastIrcMessage, listLiveAgents, respondAsBackground, sendIrcMessage } 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 prose reply (default: true for DM, false for broadcast). For DMs the recipient receives the message as a non-blocking background turn and its reply is returned to the caller. Broadcast always ignores this flag.",
+		}),
+	),
+});
+
+type IrcParams = Static<typeof IrcParams>;
+
+/**
+ * Output schema for the irc tool's `details` field.
+ * All fields are optional — only present when relevant to the operation.
+ *
+ * Schema:
+ *   op         — Always present. "send" | "list"
+ *   from       — Sender agent ID. Present on all responses.
+ *   to         — Recipient agent ID. Present on send responses.
+ *   delivered  — Array of agent IDs that received the message. Present on send.
+ *   notFound   — Array of agent IDs that were unknown or unavailable. Present on send.
+ *   peers      — Array of { id, status } for list operation.
+ *   error      — Human-readable error description. Present when the operation failed.
+ */
+interface IrcDetails {
+	op: "send" | "list";
+	from?: string;
+	to?: string;
+	delivered?: string[];
+	notFound?: string[];
+	peers?: Array<{ id: string; status: string }>;
+	/** Replies received from recipients (awaitReply DM path). */
+	replies?: Array<{ from: string; text: 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 },
+	};
+}
+
+async function executeSend(
+	selfId: string,
+	params: IrcParams,
+): Promise<{
+	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.",
+			},
+		};
+	}
+
+	// awaitReply defaults to true for DMs, false for broadcast. Broadcast
+	// always ignores the flag (fire-and-forget) — there is no single sender
+	// to receive a correlated reply from.
+	const isBroadcast = to === "all";
+	const wantsReply = !isBroadcast && (params.awaitReply ?? true);
+
+	const ircMessage: IrcMessage = {
+		from: selfId,
+		to,
+		content: message,
+		timestamp: new Date().toISOString(),
+		awaitReply: wantsReply,
+	};
+
+	const notFound: string[] = [];
+	const delivered: string[] = [];
+	const replies: Array<{ from: string; text: string }> = [];
+
+	try {
+		if (isBroadcast) {
+			// Broadcast: always fire-and-forget regardless of awaitReply.
+			const recipients = broadcastIrcMessage(selfId, ircMessage);
+			delivered.push(...recipients);
+		} else if (wantsReply) {
+			// DM with reply: use the non-blocking side-channel.
+			const agents = listLiveAgents();
+			const target = agents.find((a) => a.agentId === to);
+			if (!target || (target.status !== "running" && target.status !== "queued")) {
+				notFound.push(to);
+			} else {
+				const result = await respondAsBackground(to, selfId, message, {
+					awaitReply: true,
+				});
+				if (result.ok) {
+					delivered.push(to);
+					if (result.replyContent) replies.push({ from: to, text: result.replyContent });
+				} else if (result.timedOut) {
+					// Message was delivered (non-blocking), but no reply in time.
+					delivered.push(to);
+					replies.push({ from: to, text: `(no reply — timed out)` });
+				} else {
+					// Delivery channel unavailable or cancelled.
+					if (result.error === "cancelled") delivered.push(to);
+					else notFound.push(to);
+				}
+			}
+		} else {
+			// DM fire-and-forget (awaitReply explicitly false).
+			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 (replies.length > 0) {
+		lines.push("");
+		lines.push("## Replies");
+		for (const reply of replies) {
+			lines.push(`### ${reply.from}`);
+			lines.push(reply.text);
+		}
+	}
+	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,
+			replies: replies.length > 0 ? replies : undefined,
+		},
+	};
+}