pi-crew 0.1.46 → 0.1.49

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

@@ -1,88 +1,88 @@
-import * as fs from "node:fs";
-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" | "follow-up" | "stop" | "resume";
-
-export interface LiveAgentControlRequest {
-	id: string;
-	runId: string;
-	taskId: string;
-	agentId?: string;
-	operation: LiveAgentControlOperation;
-	message?: string;
-	createdAt: string;
-	processedAt?: string;
-	error?: string;
-}
-
-export interface LiveAgentControlCursor {
-	offset: number;
-}
-
-export function liveAgentControlPath(manifest: TeamRunManifest, taskId: string): string {
-	return path.join(ensureAgentStateDir(manifest, taskId), "live-control.jsonl");
-}
-
-function liveAgentControlFile(manifest: TeamRunManifest, taskId: string): string {
-	return agentStateFile(manifest, taskId, "live-control.jsonl");
-}
-
-function requestId(): string {
-	return `ctrl_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`;
-}
-
-export function appendLiveAgentControlRequest(manifest: TeamRunManifest, input: { taskId: string; agentId?: string; operation: LiveAgentControlOperation; message?: string }): LiveAgentControlRequest {
-	const request: LiveAgentControlRequest = {
-		id: requestId(),
-		runId: manifest.runId,
-		taskId: input.taskId,
-		agentId: input.agentId,
-		operation: input.operation,
-		message: input.message,
-		createdAt: new Date().toISOString(),
-	};
-	const filePath = liveAgentControlFile(manifest, input.taskId);
-	fs.appendFileSync(filePath, `${JSON.stringify(request)}\n`, "utf-8");
-	return request;
-}
-
-export function readLiveAgentControlRequests(manifest: TeamRunManifest, taskId: string, cursor: LiveAgentControlCursor = { offset: 0 }): { requests: LiveAgentControlRequest[]; cursor: LiveAgentControlCursor } {
-	let filePath: string;
-	try {
-		filePath = liveAgentControlFile(manifest, taskId);
-	} catch {
-		return { requests: [], cursor };
-	}
-	if (!fs.existsSync(filePath)) return { requests: [], cursor };
-	const text = fs.readFileSync(filePath, "utf-8");
-	const lines = text.split(/\r?\n/).filter(Boolean);
-	const requests = lines.slice(cursor.offset).flatMap((line) => {
-		try {
-			const parsed = JSON.parse(line) as LiveAgentControlRequest;
-			return parsed && parsed.runId === manifest.runId && parsed.taskId === taskId ? [parsed] : [];
-		} catch {
-			return [];
-		}
-	});
-	return { requests, cursor: { offset: lines.length } };
-}
-
-export async function applyLiveAgentControlRequest(input: { request: LiveAgentControlRequest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; seenRequestIds?: Set<string> }): Promise<boolean> {
-	const { request, taskId, agentId, session, seenRequestIds } = input;
-	if (seenRequestIds?.has(request.id)) return false;
-	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;
-}
-
-export async function applyLiveAgentControlRequests(input: { manifest: TeamRunManifest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; cursor: LiveAgentControlCursor; seenRequestIds?: Set<string> }): Promise<LiveAgentControlCursor> {
-	const batch = readLiveAgentControlRequests(input.manifest, input.taskId, input.cursor);
-	for (const request of batch.requests) await applyLiveAgentControlRequest({ request, taskId: input.taskId, agentId: input.agentId, session: input.session, seenRequestIds: input.seenRequestIds });
-	return batch.cursor;
-}
+import * as fs from "node:fs";
+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" | "follow-up" | "stop" | "resume";
+
+export interface LiveAgentControlRequest {
+	id: string;
+	runId: string;
+	taskId: string;
+	agentId?: string;
+	operation: LiveAgentControlOperation;
+	message?: string;
+	createdAt: string;
+	processedAt?: string;
+	error?: string;
+}
+
+export interface LiveAgentControlCursor {
+	offset: number;
+}
+
+export function liveAgentControlPath(manifest: TeamRunManifest, taskId: string): string {
+	return path.join(ensureAgentStateDir(manifest, taskId), "live-control.jsonl");
+}
+
+function liveAgentControlFile(manifest: TeamRunManifest, taskId: string): string {
+	return agentStateFile(manifest, taskId, "live-control.jsonl");
+}
+
+function requestId(): string {
+	return `ctrl_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`;
+}
+
+export function appendLiveAgentControlRequest(manifest: TeamRunManifest, input: { taskId: string; agentId?: string; operation: LiveAgentControlOperation; message?: string }): LiveAgentControlRequest {
+	const request: LiveAgentControlRequest = {
+		id: requestId(),
+		runId: manifest.runId,
+		taskId: input.taskId,
+		agentId: input.agentId,
+		operation: input.operation,
+		message: input.message,
+		createdAt: new Date().toISOString(),
+	};
+	const filePath = liveAgentControlFile(manifest, input.taskId);
+	fs.appendFileSync(filePath, `${JSON.stringify(request)}\n`, "utf-8");
+	return request;
+}
+
+export function readLiveAgentControlRequests(manifest: TeamRunManifest, taskId: string, cursor: LiveAgentControlCursor = { offset: 0 }): { requests: LiveAgentControlRequest[]; cursor: LiveAgentControlCursor } {
+	let filePath: string;
+	try {
+		filePath = liveAgentControlFile(manifest, taskId);
+	} catch {
+		return { requests: [], cursor };
+	}
+	if (!fs.existsSync(filePath)) return { requests: [], cursor };
+	const text = fs.readFileSync(filePath, "utf-8");
+	const lines = text.split(/\r?\n/).filter(Boolean);
+	const requests = lines.slice(cursor.offset).flatMap((line) => {
+		try {
+			const parsed = JSON.parse(line) as LiveAgentControlRequest;
+			return parsed && parsed.runId === manifest.runId && parsed.taskId === taskId ? [parsed] : [];
+		} catch {
+			return [];
+		}
+	});
+	return { requests, cursor: { offset: lines.length } };
+}
+
+export async function applyLiveAgentControlRequest(input: { request: LiveAgentControlRequest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; seenRequestIds?: Set<string> }): Promise<boolean> {
+	const { request, taskId, agentId, session, seenRequestIds } = input;
+	if (seenRequestIds?.has(request.id)) return false;
+	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;
+}
+
+export async function applyLiveAgentControlRequests(input: { manifest: TeamRunManifest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; cursor: LiveAgentControlCursor; seenRequestIds?: Set<string> }): Promise<LiveAgentControlCursor> {
+	const batch = readLiveAgentControlRequests(input.manifest, input.taskId, input.cursor);
+	for (const request of batch.requests) await applyLiveAgentControlRequest({ request, taskId: input.taskId, agentId: input.agentId, session: input.session, seenRequestIds: input.seenRequestIds });
+	return batch.cursor;
+}

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

@@ -1,4 +1,5 @@
 import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+import type { IrcMessage } from "./live-irc.ts";
 
 type LiveSessionHandle = {
 	steer?: (text: string) => Promise<void>;
@@ -16,14 +17,16 @@ export interface LiveAgentHandle {
 	status: CrewAgentRecord["status"];
 	pendingSteers: string[];
 	pendingFollowUps: string[];
+	/** Phase 7: Pending IRC messages for this agent. */
+	pendingMessages: IrcMessage[];
 }
 
 const liveAgents = new Map<string, LiveAgentHandle>();
 
-export function registerLiveAgent(input: Omit<LiveAgentHandle, "createdAt" | "updatedAt" | "pendingSteers" | "pendingFollowUps">): LiveAgentHandle {
+export function registerLiveAgent(input: Omit<LiveAgentHandle, "createdAt" | "updatedAt" | "pendingSteers" | "pendingFollowUps" | "pendingMessages">): LiveAgentHandle {
 	const now = new Date().toISOString();
 	const existing = liveAgents.get(input.agentId);
-	const handle: LiveAgentHandle = { ...input, createdAt: existing?.createdAt ?? now, updatedAt: now, pendingSteers: existing?.pendingSteers ?? [], pendingFollowUps: existing?.pendingFollowUps ?? [] };
+	const handle: LiveAgentHandle = { ...input, createdAt: existing?.createdAt ?? now, updatedAt: now, pendingSteers: existing?.pendingSteers ?? [], pendingFollowUps: existing?.pendingFollowUps ?? [], pendingMessages: existing?.pendingMessages ?? [] };
 	liveAgents.set(input.agentId, handle);
 	if (handle.pendingSteers.length && typeof handle.session.steer === "function") {
 		const pending = [...handle.pendingSteers];
@@ -101,3 +104,76 @@ export async function resumeLiveAgent(agentIdOrTaskId: string, prompt: string):
 export function clearLiveAgentsForTest(): void {
 	liveAgents.clear();
 }
+
+/** Phase 7/G4: Send an IRC message to a specific live agent (DM).
+ * Uses non-blocking delivery via sendCustomMessage when available.
+ * Falls back to session.prompt (blocking) when not.
+ */
+export function sendIrcMessage(targetAgentId: string, message: IrcMessage): void {
+	const handle = getLiveAgent(targetAgentId);
+	if (!handle) return;
+	handle.pendingMessages.push(message);
+	handle.updatedAt = new Date().toISOString();
+	// G4: Try non-blocking delivery via sendCustomMessage
+	const session = handle.session as Record<string, unknown>;
+	if (typeof session.sendCustomMessage === "function") {
+		try {
+			(session.sendCustomMessage as (msg: unknown, opts?: unknown) => void)(
+				{ customType: "irc", content: `[DM from ${message.from}] ${message.content}`, display: "collapsed" },
+				{ deliverAs: "followUp", triggerTurn: false },
+			);
+			return;
+		} catch {
+			// Fall through to prompt-based delivery
+		}
+	}
+	// Fallback: inject as prompt (blocking)
+	if (typeof handle.session.prompt === "function") {
+		const ircPrompt = `[Message from ${message.from}] ${message.content}`;
+		void handle.session.prompt(ircPrompt, { source: "api", expandPromptTemplates: false }).catch(() => {});
+	}
+}
+
+/** Phase 7/G4: Broadcast an IRC message to all live agents except the sender.
+ * Uses non-blocking delivery via sendCustomMessage when available.
+ * Returns recipient IDs.
+ */
+export function broadcastIrcMessage(fromAgentId: string, message: IrcMessage): string[] {
+	const recipients: string[] = [];
+	for (const handle of liveAgents.values()) {
+		if (handle.agentId === fromAgentId) continue;
+		if (handle.status !== "running" && handle.status !== "queued") continue;
+		handle.pendingMessages.push(message);
+		handle.updatedAt = new Date().toISOString();
+		// G4: Try non-blocking delivery
+		const session = handle.session as Record<string, unknown>;
+		if (typeof session.sendCustomMessage === "function") {
+			try {
+				(session.sendCustomMessage as (msg: unknown, opts?: unknown) => void)(
+					{ customType: "irc", content: `[Broadcast from ${message.from}] ${message.content}`, display: "collapsed" },
+					{ deliverAs: "followUp", triggerTurn: false },
+				);
+				recipients.push(handle.agentId);
+				continue;
+			} catch {
+				// Fall through to prompt-based delivery
+			}
+		}
+		// Fallback: inject as prompt
+		if (typeof handle.session.prompt === "function") {
+			const ircPrompt = `[Broadcast from ${message.from}] ${message.content}`;
+			void handle.session.prompt(ircPrompt, { source: "api", expandPromptTemplates: false }).catch(() => {});
+		}
+		recipients.push(handle.agentId);
+	}
+	return recipients;
+}
+
+/** Phase 7: Get pending IRC messages for an agent (and clear them). */
+export function drainIrcMessages(agentIdOrTaskId: string): IrcMessage[] {
+	const handle = getLiveAgent(agentIdOrTaskId);
+	if (!handle) return [];
+	const messages = [...handle.pendingMessages];
+	handle.pendingMessages.length = 0;
+	return messages;
+}

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

@@ -1,36 +1,36 @@
-import type { LiveAgentControlRequest } from "./live-agent-control.ts";
-
-export interface LiveControlRealtimeMessage {
-	type: "live-control";
-	version: 1;
-	request: LiveAgentControlRequest;
-}
-
-type Listener = (request: LiveAgentControlRequest) => void | Promise<void>;
-
-const listeners = new Set<Listener>();
-
-export function publishLiveControlRealtime(request: LiveAgentControlRequest): void {
-	for (const listener of [...listeners]) void listener(request);
-}
-
-export function subscribeLiveControlRealtime(listener: Listener): () => void {
-	listeners.add(listener);
-	return () => listeners.delete(listener);
-}
-
-export function liveControlRealtimeMessage(request: LiveAgentControlRequest): LiveControlRealtimeMessage {
-	return { type: "live-control", version: 1, request };
-}
-
-export function parseLiveControlRealtimeMessage(raw: unknown): LiveAgentControlRequest | undefined {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-	const message = raw as { type?: unknown; version?: unknown; request?: unknown };
-	if (message.type !== "live-control" || message.version !== 1 || !message.request || typeof message.request !== "object" || Array.isArray(message.request)) return undefined;
-	const request = message.request as Partial<LiveAgentControlRequest>;
-	return typeof request.id === "string" && typeof request.runId === "string" && typeof request.taskId === "string" && (request.operation === "steer" || request.operation === "follow-up" || request.operation === "stop" || request.operation === "resume") && typeof request.createdAt === "string" ? request as LiveAgentControlRequest : undefined;
-}
-
-export function clearLiveControlRealtimeForTest(): void {
-	listeners.clear();
-}
+import type { LiveAgentControlRequest } from "./live-agent-control.ts";
+
+export interface LiveControlRealtimeMessage {
+	type: "live-control";
+	version: 1;
+	request: LiveAgentControlRequest;
+}
+
+type Listener = (request: LiveAgentControlRequest) => void | Promise<void>;
+
+const listeners = new Set<Listener>();
+
+export function publishLiveControlRealtime(request: LiveAgentControlRequest): void {
+	for (const listener of [...listeners]) void listener(request);
+}
+
+export function subscribeLiveControlRealtime(listener: Listener): () => void {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+
+export function liveControlRealtimeMessage(request: LiveAgentControlRequest): LiveControlRealtimeMessage {
+	return { type: "live-control", version: 1, request };
+}
+
+export function parseLiveControlRealtimeMessage(raw: unknown): LiveAgentControlRequest | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const message = raw as { type?: unknown; version?: unknown; request?: unknown };
+	if (message.type !== "live-control" || message.version !== 1 || !message.request || typeof message.request !== "object" || Array.isArray(message.request)) return undefined;
+	const request = message.request as Partial<LiveAgentControlRequest>;
+	return typeof request.id === "string" && typeof request.runId === "string" && typeof request.taskId === "string" && (request.operation === "steer" || request.operation === "follow-up" || request.operation === "stop" || request.operation === "resume") && typeof request.createdAt === "string" ? request as LiveAgentControlRequest : undefined;
+}
+
+export function clearLiveControlRealtimeForTest(): void {
+	listeners.clear();
+}

package/src/runtime/live-extension-bridge.ts

@@ -0,0 +1,150 @@
+/**
+ * G5: Extension runner bridge for live-session workers.
+ *
+ * Bridges pi-crew's extension lifecycle with the Pi SDK session's
+ * extension runner. Verified against actual SDK API surface:
+ *
+ * Session methods:
+ *   - sendCustomMessage(message, options?)
+ *   - sendUserMessage(content, options?)
+ *   - getActiveToolNames() / setActiveToolsByName()
+ *   - getAllTools() / getToolDefinition()
+ *   - steer(text) / prompt(text, options?)
+ *   - abort()
+ *   - getContextUsage()
+ *   - bindExtensions()
+ *   - compact()
+ *   - getSessionStats()
+ *
+ * ExtensionRunner methods:
+ *   - initialize(apis, host)
+ *   - emit(event)
+ *   - hasHandlers(eventType)
+ *   - getAllRegisteredTools()
+ *   - onError(listener)
+ *   - shutdown()
+ *
+ * ExtensionContext actions (via registerTool):
+ *   - sendMessage / sendUserMessage / appendEntry / setLabel
+ *   - setActiveTools / getActiveTools / getAllTools
+ */
+
+import type { YieldResult } from "./yield-handler.ts";
+
+export interface ExtensionBridgeApis {
+	sendMessage: (message: unknown, options?: Record<string, unknown>) => void;
+	sendUserMessage: (content: unknown, options?: Record<string, unknown>) => void;
+	appendEntry: (customType: string, data: unknown) => void;
+	setLabel: (targetId: string, label: string) => void;
+	getActiveTools: () => string[];
+	getAllTools: () => string[];
+	setActiveTools: (toolNames: string[]) => void;
+}
+
+export interface ExtensionHostApis {
+	getModel: () => unknown;
+	isIdle: () => boolean;
+	abort: () => void;
+	hasPendingMessages: () => boolean;
+	shutdown: () => void;
+	getContextUsage: () => unknown;
+	getSystemPrompt: () => string;
+}
+
+/**
+ * Pi SDK session-like object with the methods we need.
+ * Verified against actual `createAgentSession().session` prototype.
+ */
+interface PiSdkSession {
+	sendCustomMessage: (message: unknown, options?: Record<string, unknown>) => void;
+	sendUserMessage: (content: unknown, options?: Record<string, unknown>) => void;
+	getActiveToolNames: () => string[];
+	getAllTools: () => string[];
+	setActiveToolsByName: (toolNames: string[]) => void;
+	steer: (text: string) => Promise<void>;
+	prompt: (text: string, options?: Record<string, unknown>) => Promise<void>;
+	abort: () => void | Promise<void>;
+	getContextUsage: () => unknown;
+	subscribe: (listener: (event: unknown) => void) => () => void;
+	bindExtensions: (bindings?: Record<string, unknown>) => Promise<void>;
+	compact: (options?: unknown) => void;
+	getSessionStats: () => unknown;
+	isStreaming?: boolean;
+	model?: unknown;
+	systemPrompt?: string;
+	pendingMessageCount?: number;
+}
+
+/**
+ * Build extension bridge APIs from a Pi SDK session.
+ * Returns null if the session doesn't support extension running.
+ */
+export function buildExtensionBridge(session: PiSdkSession): { apis: ExtensionBridgeApis; host: ExtensionHostApis } | null {
+	if (typeof session.sendCustomMessage !== "function") return null;
+
+	return {
+		apis: {
+			sendMessage: (message, options) => {
+				try {
+					session.sendCustomMessage(message, options);
+				} catch {
+					/* non-blocking */
+				}
+			},
+			sendUserMessage: (content, options) => {
+				try {
+					session.sendUserMessage(content, options);
+				} catch {
+					/* non-blocking */
+				}
+			},
+			appendEntry: () => {
+				// appendEntry requires sessionManager access which isn't directly on session
+				// This is a no-op placeholder; extensions that rely on it will gracefully degrade
+			},
+			setLabel: () => {
+				// setLabel requires sessionManager access — no-op placeholder
+			},
+			getActiveTools: () => {
+				try {
+					return session.getActiveToolNames();
+				} catch {
+					return [];
+				}
+			},
+			getAllTools: () => {
+				try {
+					return session.getAllTools();
+				} catch {
+					return session.getActiveToolNames();
+				}
+			},
+			setActiveTools: (toolNames) => {
+				try {
+					session.setActiveToolsByName(toolNames);
+				} catch {
+					/* ignore */
+				}
+			},
+		},
+		host: {
+			getModel: () => session.model,
+			isIdle: () => !session.isStreaming,
+			abort: () => {
+				void session.abort();
+			},
+			hasPendingMessages: () => (session.pendingMessageCount ?? 0) > 0,
+			shutdown: () => {
+				/* no-op for live-session — caller manages session lifecycle */
+			},
+			getContextUsage: () => {
+				try {
+					return session.getContextUsage();
+				} catch {
+					return undefined;
+				}
+			},
+			getSystemPrompt: () => session.systemPrompt ?? "",
+		},
+	};
+}

package/src/runtime/live-irc.ts

@@ -0,0 +1,92 @@
+/**
+ * Phase 7: Inter-agent communication for live-session workers.
+ *
+ * Provides IRC-like messaging between live-session workers, adapted from
+ * oh-my-pi's IrcTool pattern. Uses the existing LiveAgentHandle manager
+ * for message routing.
+ *
+ * Features:
+ * - DM: Send a message to a specific agent
+ * - Broadcast: Send a message to all live agents
+ * - Side-channel: Non-blocking message injection (via pendingFollowUps)
+ *
+ * For child-process workers, messages fall back to file-based mailbox.
+ */
+
+export type IrcOperation = "send" | "list";
+
+export interface IrcMessage {
+	from: string;
+	to: string;
+	content: string;
+	timestamp: string;
+	/** Whether the sender expects a reply. */
+	awaitReply?: boolean;
+}
+
+export interface IrcSendMessage {
+	op: IrcOperation;
+	/** Target agent ID or "all" for broadcast. */
+	to: string;
+	/** Message content. */
+	message: string;
+	/** Whether to wait for a reply (default: true for DM, false for broadcast). */
+	awaitReply?: boolean;
+}
+
+export interface IrcListResult {
+	peers: Array<{ id: string; name: string; status: string }>;
+}
+
+/**
+ * Build IRC peer roster for injection into system prompt.
+ * Lists all currently live agents except the caller.
+ */
+export function renderIrcPeerRoster(selfId: string, peers: Array<{ agentId: string; status: string }>): string {
+	const visible = peers.filter((p) => p.agentId !== selfId && (p.status === "running" || p.status === "idle"));
+	if (visible.length === 0) return "- (no other live agents)";
+	return visible.map((peer) => `- \`${peer.agentId}\` (${peer.status})`).join("\n");
+}
+
+/**
+ * Build the IRC system prompt section for a live-session worker.
+ */
+export function buildIrcSystemSection(selfId: string, peers: Array<{ agentId: string; status: string }>): string {
+	const roster = renderIrcPeerRoster(selfId, peers);
+	return [
+		"## Inter-Agent Communication",
+		`Your agent ID: \`${selfId}\``,
+		"You can send messages to other live agents via the `irc` tool.",
+		"Available peers:",
+		roster,
+	].join("\n");
+}
+
+/**
+ * Route an IRC message to the appropriate agent(s).
+ * Returns the list of agent IDs that received the message.
+ */
+export function routeIrcMessage(
+	message: IrcSendMessage,
+	selfId: string,
+	routing: {
+		sendDm: (agentId: string, content: string) => void;
+		broadcast: (content: string, excludeId: string) => string[];
+	},
+): { deliveredTo: string[]; error?: string } {
+	if (!message.to || !message.message?.trim()) {
+		return { deliveredTo: [], error: "Missing 'to' (agent ID or 'all') and 'message' fields." };
+	}
+	if (message.to === selfId) {
+		return { deliveredTo: [], error: "Cannot send a message to yourself." };
+	}
+
+	if (message.to === "all") {
+		const recipients = routing.broadcast(message.message, selfId);
+		return { deliveredTo: recipients };
+	}
+
+	// DM to specific agent
+	routing.sendDm(message.to, message.message);
+	return { deliveredTo: [message.to] };
+}