pi-crew 0.9.51 → 0.9.53

package/src/runtime/crew-hooks.ts

@@ -1,227 +0,0 @@
-/**
- * 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

@@ -1,143 +0,0 @@
-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

@@ -1,282 +0,0 @@
-/**
- * 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,
-		},
-	};
-}