@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/internal-urls/history-protocol.ts

@@ -0,0 +1,113 @@
+/**
+ * Protocol handler for history:// URLs.
+ *
+ * Exposes agent transcripts as concise markdown. Live refs render from the
+ * in-memory message array; parked refs (session disposed, sessionFile
+ * retained) load read-only from the JSONL session file — no writer, no lock.
+ *
+ * URL forms:
+ * - history:// - Index of all registry agents (id, status, kind, last activity)
+ * - history://<agentId> - Concise markdown transcript of that agent
+ */
+import type { AgentRef } from "../registry/agent-registry";
+import { AgentRegistry } from "../registry/agent-registry";
+import { formatSessionHistoryMarkdown } from "../session/session-history-format";
+import { loadSessionMessagesReadOnly } from "../session/session-loader";
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+
+/** Humanize a last-activity timestamp as `Ns/Nm/Nh/Nd ago`. */
+function formatAgo(timestamp: number): string {
+	const diffMs = Math.max(0, Date.now() - timestamp);
+	const secs = Math.floor(diffMs / 1000);
+	if (secs < 60) return `${secs}s ago`;
+	const mins = Math.floor(secs / 60);
+	if (mins < 60) return `${mins}m ago`;
+	const hours = Math.floor(mins / 60);
+	if (hours < 24) return `${hours}h ago`;
+	return `${Math.floor(hours / 24)}d ago`;
+}
+
+/**
+ * Handler for history:// URLs.
+ *
+ * Resolves agent ids against the global AgentRegistry, serving transcripts
+ * for both live and parked agents.
+ */
+export class HistoryProtocolHandler implements ProtocolHandler {
+	readonly scheme = "history";
+	readonly immutable = false;
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const agentId = url.rawHost || url.hostname;
+		const registry = AgentRegistry.global();
+
+		if (!agentId) {
+			const content = this.#renderIndex(registry.list());
+			return {
+				url: url.href,
+				content,
+				contentType: "text/markdown",
+				size: Buffer.byteLength(content, "utf-8"),
+			};
+		}
+
+		let ref = registry.get(agentId);
+		if (!ref) {
+			// Case-insensitive fallback: agent ids are human-typed (e.g. AuthLoader).
+			const lower = agentId.toLowerCase();
+			ref = registry.list().find(candidate => candidate.id.toLowerCase() === lower);
+		}
+		if (!ref) {
+			const known = registry.list().map(candidate => candidate.id);
+			const knownStr = known.length > 0 ? known.join(", ") : "none";
+			throw new Error(`Unknown agent: ${agentId}\nKnown agents: ${knownStr}\nList all with history://`);
+		}
+
+		const notes: string[] = [];
+		let messages: unknown[];
+		if (ref.session) {
+			messages = ref.session.messages;
+			notes.push("Source: live session");
+		} else if (ref.sessionFile) {
+			messages = await loadSessionMessagesReadOnly(ref.sessionFile);
+			notes.push(`Source: session file (read-only, ${ref.status})`);
+		} else {
+			throw new Error(`Agent ${ref.id} has no transcript: session is gone and no session file was retained`);
+		}
+
+		const content = formatSessionHistoryMarkdown(messages, { title: `${ref.id} (${ref.status})` });
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: ref.sessionFile ?? undefined,
+			notes,
+		};
+	}
+
+	#renderIndex(refs: AgentRef[]): string {
+		const lines: string[] = ["# Agents", ""];
+		if (refs.length === 0) {
+			lines.push("No agents registered.");
+			return `${lines.join("\n")}\n`;
+		}
+		lines.push("| id | status | kind | parent | last activity |", "|---|---|---|---|---|");
+		for (const ref of refs) {
+			lines.push(
+				`| ${ref.id} | ${ref.status} | ${ref.kind} | ${ref.parentId ?? "—"} | ${formatAgo(ref.lastActivity)} |`,
+			);
+		}
+		lines.push("", "Read a transcript with `read history://<id>`.");
+		return `${lines.join("\n")}\n`;
+	}
+
+	async complete(): Promise<UrlCompletion[]> {
+		return AgentRegistry.global()
+			.list()
+			.map(ref => ({
+				value: ref.id,
+				description: `${ref.status} · ${ref.kind}${ref.parentId ? ` · parent ${ref.parentId}` : ""}`,
+			}));
+	}
+}

package/src/internal-urls/index.ts

@@ -10,6 +10,7 @@
 
 export * from "./agent-protocol";
 export * from "./artifact-protocol";
+export * from "./history-protocol";
 export * from "./issue-pr-protocol";
 export * from "./json-query";
 export * from "./local-protocol";

package/src/internal-urls/issue-pr-protocol.ts

@@ -23,6 +23,7 @@ import {
 	getOrFetchIssue,
 	getOrFetchPr,
 	getOrFetchPrDiff,
+	githubIssueJsonWithStateReasonFallback,
 	type PrDiffFile,
 	parsePositiveDecimalInt,
 	resolveDefaultRepoMemoized,
@@ -71,17 +72,24 @@ function parseListOptions(url: InternalUrl, scheme: Scheme, repo: string | undef
 	const stateRaw = url.searchParams.get("state");
 	const allowedStates: ParsedList["state"][] =
 		scheme === "pr" ? ["open", "closed", "merged", "all"] : ["open", "closed", "all"];
-	const state = (
-		stateRaw && (allowedStates as string[]).includes(stateRaw) ? stateRaw : "open"
-	) as ParsedList["state"];
+	if (stateRaw !== null && !(allowedStates as string[]).includes(stateRaw)) {
+		// Reject instead of silently falling back to "open": a typo'd state
+		// would otherwise return the open list, indistinguishable from "no
+		// matches for the requested state".
+		throw new Error(`Invalid ${scheme}:// list state '${stateRaw}'. Expected one of: ${allowedStates.join(", ")}.`);
+	}
+	const state = (stateRaw ?? "open") as ParsedList["state"];
 
 	const limitRaw = url.searchParams.get("limit");
 	let limit = LIST_LIMIT_DEFAULT;
 	if (limitRaw !== null) {
 		const parsed = parsePositiveDecimalInt(limitRaw);
-		if (parsed !== undefined) {
-			limit = Math.min(parsed, LIST_LIMIT_MAX);
+		if (parsed === undefined) {
+			throw new Error(
+				`Invalid ${scheme}:// list limit '${limitRaw}'. Expected a positive integer (max ${LIST_LIMIT_MAX}).`,
+			);
 		}
+		limit = Math.min(parsed, LIST_LIMIT_MAX);
 	}
 	return {
 		kind: "list",
@@ -287,7 +295,7 @@ async function fetchAndRenderList(
 	const cwd = resolveCwd(context);
 	const fields =
 		scheme === "issue"
-			? ["number", "title", "state", "stateReason", "author", "labels", "createdAt", "updatedAt", "url"]
+			? ["number", "title", "state", "author", "labels", "createdAt", "updatedAt", "url"]
 			: [
 					"number",
 					"title",
@@ -316,9 +324,14 @@ async function fetchAndRenderList(
 	if (options.author) args.push("--author", options.author);
 	if (options.label) args.push("--label", options.label);
 
-	const items = await git.github.json<Array<IssueListItem | PrListItem>>(cwd, args, context?.signal, {
-		repoProvided: true,
-	});
+	const items =
+		scheme === "issue"
+			? await githubIssueJsonWithStateReasonFallback<Array<IssueListItem>>(cwd, args, context?.signal, {
+					repoProvided: true,
+				})
+			: await git.github.json<Array<PrListItem>>(cwd, args, context?.signal, {
+					repoProvided: true,
+				});
 	const header =
 		scheme === "issue"
 			? `# Issues in ${repo} (${options.state}, up to ${options.limit})`

package/src/internal-urls/local-protocol.ts

@@ -26,6 +26,20 @@ function toLocalValidationError(error: unknown): Error {
 	const message = error instanceof Error ? error.message : String(error);
 	return new Error(message.replace("skill://", "local://"));
 }
+const WINDOWS_LOCAL_ROOT_MAX_CHARS = 180;
+
+function safeSessionId(options: LocalProtocolOptions): string {
+	const raw = options.getSessionId?.() ?? "session";
+	const safe = raw.replace(/[^a-zA-Z0-9_.-]/g, "_");
+	return safe.length > 0 ? safe : "session";
+}
+
+function shortLocalRoot(options: LocalProtocolOptions): string {
+	// Derive the short root from the stable session id, never the artifact path,
+	// so `SessionManager.moveTo()` and the resume-after-move flow keep finding
+	// the same `local://` directory the session wrote pre-move.
+	return path.join(os.tmpdir(), "prometheus-local", safeSessionId(options));
+}
 
 function getContentType(filePath: string): InternalResource["contentType"] {
 	const ext = path.extname(filePath).toLowerCase();
@@ -108,20 +122,28 @@ function extractRelativePath(url: InternalUrl): string {
 	return decoded;
 }
 
-export function resolveLocalRoot(options: LocalProtocolOptions): string {
+/** Resolve the session-scoped local:// root, shortening long Windows artifact paths before writes hit MAX_PATH. */
+export function resolveLocalRoot(options: LocalProtocolOptions, platform: NodeJS.Platform = process.platform): string {
 	const artifactsDir = options.getArtifactsDir?.();
 	if (artifactsDir) {
-		return path.resolve(artifactsDir, "local");
+		const candidate = path.resolve(artifactsDir, "local");
+		if (platform === "win32" && candidate.length >= WINDOWS_LOCAL_ROOT_MAX_CHARS) {
+			return shortLocalRoot(options);
+		}
+		return candidate;
 	}
 
-	const sessionId = options.getSessionId?.() ?? "session";
-	const safeSessionId = sessionId.replace(/[^a-zA-Z0-9_.-]/g, "_");
-	return path.join(os.tmpdir(), "prometheus-local", safeSessionId);
+	return path.join(os.tmpdir(), "prometheus-local", safeSessionId(options));
 }
 
-export function resolveLocalUrlToPath(input: string | InternalUrl, options: LocalProtocolOptions): string {
+/** Resolve a local:// URL to an on-disk path under the active session's local root. */
+export function resolveLocalUrlToPath(
+	input: string | InternalUrl,
+	options: LocalProtocolOptions,
+	platform: NodeJS.Platform = process.platform,
+): string {
 	const url = typeof input === "string" ? parseLocalUrl(input) : input;
-	const localRoot = path.resolve(resolveLocalRoot(options));
+	const localRoot = path.resolve(resolveLocalRoot(options, platform));
 	const relativePath = extractRelativePath(url);
 
 	if (!relativePath) {
@@ -133,6 +155,19 @@ export function resolveLocalUrlToPath(input: string | InternalUrl, options: Loca
 	return resolved;
 }
 
+/**
+ * On-disk roots the eval helpers (`read`/`write`/`append`) substitute for
+ * internal-URL schemes so e.g. `write("local://x.md")` lands where a later
+ * `read local://x.md` resolves — instead of a literal `local:/` directory under
+ * the cwd (a stdlib `pathlib.Path`/`path.resolve` collapses `local://` to
+ * `local:/`). Keyed by scheme without the `://`. Currently only `local`, but the
+ * shape is a map so additional file-backed schemes can be added without
+ * re-plumbing the worker boundary.
+ */
+export function buildEvalUrlRoots(options: LocalProtocolOptions): Record<string, string> {
+	return { local: resolveLocalRoot(options) };
+}
+
 /**
  * Protocol handler for local:// URLs.
  *

package/src/internal-urls/memory-protocol.ts

@@ -1,35 +1,13 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getAgentDir, isEnoent } from "@prometheus-ai/utils";
-import { getMemoryRoot, MEMORY_ARTIFACTS, recordGeneratedMemorySkillEvent } from "../memories";
+import { getMemoryRoot } from "../memories";
 import { AgentRegistry } from "../registry/agent-registry";
 import { validateRelativePath } from "./skill-protocol";
 import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
 
+const DEFAULT_MEMORY_FILE = "memory_summary.md";
 const MEMORY_NAMESPACE = "root";
-const MEMORY_ROOT_COMPLETIONS: ReadonlyArray<UrlCompletion> = [
-	{ value: MEMORY_NAMESPACE, description: "Project memory summary" },
-	{ value: `${MEMORY_NAMESPACE}/${MEMORY_ARTIFACTS.summary}`, description: "Project memory summary" },
-	{ value: `${MEMORY_NAMESPACE}/${MEMORY_ARTIFACTS.memory}`, description: "Full long-term project memory" },
-	{ value: `${MEMORY_NAMESPACE}/${MEMORY_ARTIFACTS.user}`, description: "Durable user profile" },
-	{
-		value: `${MEMORY_NAMESPACE}/${MEMORY_ARTIFACTS.selfImprovementReport}`,
-		description: "Self-improvement report and identity boundary",
-	},
-	{
-		value: `${MEMORY_NAMESPACE}/${MEMORY_ARTIFACTS.skillUsage}`,
-		description: "Generated memory skill provenance and usage sidecar",
-	},
-	{
-		value: `${MEMORY_NAMESPACE}/${MEMORY_ARTIFACTS.skillCuratorReport}`,
-		description: "Generated memory skill curator dry-run report",
-	},
-	{
-		value: `${MEMORY_NAMESPACE}/${MEMORY_ARTIFACTS.soulProposal}`,
-		description: "Approval-gated proposed SOUL.md patch, if present",
-	},
-	{ value: `${MEMORY_NAMESPACE}/skills/`, description: "Generated memory skill playbooks" },
-];
 
 /**
  * Snapshot of memory roots for every registered session, deduped.
@@ -74,7 +52,7 @@ export function resolveMemoryUrlToPath(url: InternalUrl, memoryRoot: string): st
 	const rawPathname = url.rawPathname ?? url.pathname;
 	const hasPath = rawPathname && rawPathname !== "/" && rawPathname !== "";
 	if (!hasPath) {
-		return path.resolve(memoryRoot, MEMORY_ARTIFACTS.summary);
+		return path.resolve(memoryRoot, DEFAULT_MEMORY_FILE);
 	}
 	let relativePath: string;
 	try {
@@ -129,11 +107,6 @@ async function tryResolveInRoot(url: InternalUrl, memoryRoot: string): Promise<I
 	}
 
 	const content = await Bun.file(realTargetPath).text();
-	const relativePath = path.relative(resolvedRoot, realTargetPath).split(path.sep).join("/");
-	const generatedSkill = relativePath.match(/^skills\/([^/]+)\/SKILL\.md$/);
-	if (generatedSkill) {
-		await recordGeneratedMemorySkillEvent(resolvedRoot, generatedSkill[1]!, "view").catch(() => false);
-	}
 	const ext = path.extname(realTargetPath).toLowerCase();
 	const contentType: InternalResource["contentType"] = ext === ".md" ? "text/markdown" : "text/plain";
 
@@ -191,6 +164,6 @@ export class MemoryProtocolHandler implements ProtocolHandler {
 
 	async complete(): Promise<UrlCompletion[]> {
 		if (memoryRootsFromRegistry().length === 0) return [];
-		return [...MEMORY_ROOT_COMPLETIONS];
+		return [{ value: MEMORY_NAMESPACE, description: "Project memory summary" }];
 	}
 }

package/src/internal-urls/router.ts

@@ -1,5 +1,5 @@
 /**
- * Internal URL router for internal protocols (agent://, artifact://, memory://, skill://, rule://, mcp://, prometheus://, local://).
+ * Internal URL router for internal protocols (`agent://`, `artifact://`, `history://`, `issue://`, `local://`, `mcp://`, `memory://`, `prometheus://`, `pr://`, `rule://`, `skill://`, and `vault://`).
  *
  * One process-global router with one handler per scheme. Access via
  * `InternalUrlRouter.instance()`. Handlers are stateless; per-session and
@@ -7,6 +7,7 @@
  */
 import { AgentProtocolHandler } from "./agent-protocol";
 import { ArtifactProtocolHandler } from "./artifact-protocol";
+import { HistoryProtocolHandler } from "./history-protocol";
 import { IssueProtocolHandler, PrProtocolHandler } from "./issue-pr-protocol";
 import { LocalProtocolHandler } from "./local-protocol";
 import { McpProtocolHandler } from "./mcp-protocol";
@@ -35,6 +36,7 @@ export class InternalUrlRouter {
 		this.register(new McpProtocolHandler());
 		this.register(new IssueProtocolHandler());
 		this.register(new PrProtocolHandler());
+		this.register(new HistoryProtocolHandler());
 	}
 
 	/** Process-global router instance. */

package/src/internal-urls/types.ts

@@ -1,7 +1,7 @@
 /**
  * Types for the internal URL routing system.
  *
- * Internal URLs (agent://, artifact://, memory://, skill://, rule://, mcp://, prometheus://, local://) are resolved by tools like read,
+ * Internal URLs (`agent://`, `artifact://`, `history://`, `issue://`, `local://`, `mcp://`, `memory://`, `prometheus://`, `pr://`, `rule://`, `skill://`, and `vault://`) are resolved by tools like read,
  * providing access to agent outputs and server resources without exposing filesystem paths.
  */
 

package/src/irc/bus.ts

@@ -0,0 +1,303 @@
+/**
+ * IrcBus - Process-global mailbox bus for agent-to-agent messaging.
+ *
+ * Replaces the old auto-reply model: a `send` never blocks on the recipient
+ * generating anything. Delivery resolves the recipient via the global
+ * AgentRegistry — parked agents are revived through the
+ * AgentLifecycleManager, idle agents are woken with a real turn, and busy
+ * agents receive the message as a non-interrupting aside at the next step
+ * boundary (see AgentSession.deliverIrcMessage). Replies are real turns by
+ * the recipient, observed via `wait` — with one exception: when the sender
+ * awaits a reply and the recipient is mid-turn with async execution
+ * disabled, the recipient session generates an ephemeral side-channel
+ * auto-reply (it may be blocked in a synchronous task spawn whose batch
+ * includes the sender, so a real turn could never happen in time).
+ */
+
+import { logger, Snowflake } from "@prometheus-ai/utils";
+import { AgentLifecycleManager } from "../registry/agent-lifecycle";
+import { AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
+import type { CustomMessage } from "../session/messages";
+
+export interface IrcMessage {
+	id: string;
+	/** Sender agent id. */
+	from: string;
+	/** Recipient agent id (resolved; "all" is expanded by the tool, not stored). */
+	to: string;
+	body: string;
+	ts: number;
+	/** Message id being answered. */
+	replyTo?: string;
+}
+
+export interface IrcDeliveryReceipt {
+	to: string;
+	outcome: "injected" | "woken" | "revived" | "failed";
+	error?: string;
+}
+
+interface IrcWaiter {
+	from?: string;
+	resolve: (msg: IrcMessage) => void;
+	cancel: () => void;
+}
+
+/** Mailbox cap per agent; oldest messages are dropped beyond it. */
+const MAILBOX_CAP = 100;
+
+export class IrcBus {
+	static #global: IrcBus | undefined;
+
+	static global(): IrcBus {
+		if (!IrcBus.#global) {
+			IrcBus.#global = new IrcBus();
+		}
+		return IrcBus.#global;
+	}
+
+	/** Reset the global bus. Test-only. */
+	static resetGlobalForTests(): void {
+		IrcBus.#global = undefined;
+	}
+
+	readonly #registry: AgentRegistry;
+	readonly #lifecycle: () => AgentLifecycleManager;
+	readonly #mailboxes = new Map<string, IrcMessage[]>();
+	readonly #waiters = new Map<string, IrcWaiter[]>();
+
+	constructor(registry: AgentRegistry = AgentRegistry.global(), lifecycle?: AgentLifecycleManager) {
+		this.#registry = registry;
+		// Lazy: the lifecycle global self-constructs against the global registry,
+		// so only touch it when a parked recipient actually needs reviving.
+		this.#lifecycle = () => lifecycle ?? AgentLifecycleManager.global();
+	}
+
+	/**
+	 * Fire-and-forget delivery. Never blocks on the recipient generating
+	 * anything: the receipt reports how the message reached the recipient
+	 * (waiter/aside = "injected", idle wake = "woken", park revival =
+	 * "revived"), not what they did with it.
+	 *
+	 * Mailbox semantics: a successfully delivered message never lingers in
+	 * the recipient's mailbox — injection/wake puts the full body into their
+	 * context, so buffering it too would double-deliver via a later
+	 * `wait`/`inbox` and inflate unread counts. Only a failed live hand-off
+	 * is buffered for the recipient to drain later.
+	 *
+	 * `opts.expectsReply` marks sends whose caller is blocked on an answer
+	 * (`send await:true`). It is forwarded to the recipient session so a
+	 * mid-turn recipient that cannot reach a step boundary (async execution
+	 * disabled — e.g. blocked in a synchronous task spawn awaiting the
+	 * sender's own batch) can generate an ephemeral side-channel auto-reply
+	 * instead of stranding the sender until timeout.
+	 */
+	async send(msg: Omit<IrcMessage, "id" | "ts">, opts?: { expectsReply?: boolean }): Promise<IrcDeliveryReceipt> {
+		const message: IrcMessage = { ...msg, id: Snowflake.next(), ts: Date.now() };
+		const ref = this.#registry.get(message.to);
+		if (!ref || ref.status === "aborted") {
+			return { to: message.to, outcome: "failed", error: `Unknown or terminated agent "${message.to}".` };
+		}
+
+		let revived = false;
+		if (ref.status === "parked") {
+			try {
+				await this.#lifecycle().ensureLive(message.to);
+				revived = true;
+			} catch (error) {
+				return {
+					to: message.to,
+					outcome: "failed",
+					error: error instanceof Error ? error.message : String(error),
+				};
+			}
+		}
+
+		// A pending `wait` from the recipient consumes the message directly —
+		// it is returned from their irc tool call and never hits the inbox or
+		// the session injection path.
+		const waiter = this.#takeMatchingWaiter(message.to, message.from);
+		if (waiter) {
+			waiter.resolve(message);
+			this.#relayToMainUi(message);
+			return { to: message.to, outcome: revived ? "revived" : "injected" };
+		}
+
+		const session = this.#registry.get(message.to)?.session;
+		if (!session) {
+			return { to: message.to, outcome: "failed", error: `Agent "${message.to}" has no live session.` };
+		}
+
+		try {
+			const delivery = await session.deliverIrcMessage(message, opts);
+			this.#relayToMainUi(message);
+			return { to: message.to, outcome: revived ? "revived" : delivery };
+		} catch (error) {
+			// Live hand-off failed (e.g. recipient disposed mid-shutdown): buffer
+			// the message so a later `wait`/`inbox` from the recipient can still
+			// pick it up. The receipt stays "failed" — the recipient has not
+			// seen it.
+			this.#enqueue(message);
+			return {
+				to: message.to,
+				outcome: "failed",
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	}
+
+	/**
+	 * Block until a message for `agentId` (optionally from `filter.from`)
+	 * arrives; consume + return it. Null on timeout (`timeoutMs <= 0` waits
+	 * forever). Rejects when `signal` aborts. By default, already-buffered
+	 * mail satisfies the wait before parking a future waiter; callers that
+	 * need a strictly future reply can disable that drain.
+	 */
+	async wait(
+		agentId: string,
+		filter: { from?: string },
+		timeoutMs: number,
+		signal?: AbortSignal,
+		options?: { drainPending?: boolean },
+	): Promise<IrcMessage | null> {
+		if (signal?.aborted) {
+			throw signal.reason instanceof Error ? signal.reason : new Error("IRC wait aborted");
+		}
+
+		if (options?.drainPending !== false) {
+			// Already-pending mail satisfies the wait without parking a waiter.
+			const pending = this.#takeFromMailbox(agentId, filter.from);
+			if (pending) return pending;
+		}
+
+		const { promise, resolve, reject } = Promise.withResolvers<IrcMessage | null>();
+		let timer: NodeJS.Timeout | undefined;
+		let onAbort: (() => void) | undefined;
+
+		const waiter: IrcWaiter = {
+			from: filter.from,
+			resolve: msg => {
+				cleanup();
+				resolve(msg);
+			},
+			cancel: () => {
+				cleanup();
+			},
+		};
+		const cleanup = (): void => {
+			this.#removeWaiter(agentId, waiter);
+			clearTimeout(timer);
+			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+		};
+
+		if (signal) {
+			onAbort = () => {
+				cleanup();
+				reject(signal.reason instanceof Error ? signal.reason : new Error("IRC wait aborted"));
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+		if (timeoutMs > 0) {
+			timer = setTimeout(() => {
+				cleanup();
+				resolve(null);
+			}, timeoutMs);
+			timer.unref?.();
+		}
+
+		let waiters = this.#waiters.get(agentId);
+		if (!waiters) {
+			waiters = [];
+			this.#waiters.set(agentId, waiters);
+		}
+		waiters.push(waiter);
+		return promise;
+	}
+
+	/** Drain (or peek) pending messages for `agentId`. */
+	inbox(agentId: string, opts?: { peek?: boolean }): IrcMessage[] {
+		const mailbox = this.#mailboxes.get(agentId);
+		if (!mailbox || mailbox.length === 0) return [];
+		if (opts?.peek) return [...mailbox];
+		this.#mailboxes.delete(agentId);
+		return mailbox;
+	}
+
+	unreadCount(agentId: string): number {
+		return this.#mailboxes.get(agentId)?.length ?? 0;
+	}
+
+	#enqueue(message: IrcMessage): void {
+		let mailbox = this.#mailboxes.get(message.to);
+		if (!mailbox) {
+			mailbox = [];
+			this.#mailboxes.set(message.to, mailbox);
+		}
+		mailbox.push(message);
+		if (mailbox.length > MAILBOX_CAP) {
+			const dropped = mailbox.shift();
+			logger.debug("IrcBus: mailbox full, dropped oldest message", {
+				agentId: message.to,
+				droppedId: dropped?.id,
+				droppedFrom: dropped?.from,
+			});
+		}
+	}
+
+	/** Resolve the OLDEST waiter for `agentId` whose from-filter accepts `from`. */
+	#takeMatchingWaiter(agentId: string, from: string): IrcWaiter | undefined {
+		const waiters = this.#waiters.get(agentId);
+		if (!waiters) return undefined;
+		const index = waiters.findIndex(waiter => !waiter.from || waiter.from === from);
+		if (index === -1) return undefined;
+		const [waiter] = waiters.splice(index, 1);
+		if (waiters.length === 0) this.#waiters.delete(agentId);
+		return waiter;
+	}
+
+	#removeWaiter(agentId: string, waiter: IrcWaiter): void {
+		const waiters = this.#waiters.get(agentId);
+		if (!waiters) return;
+		const index = waiters.indexOf(waiter);
+		if (index !== -1) waiters.splice(index, 1);
+		if (waiters.length === 0) this.#waiters.delete(agentId);
+	}
+
+	#takeFromMailbox(agentId: string, from?: string): IrcMessage | undefined {
+		const mailbox = this.#mailboxes.get(agentId);
+		if (!mailbox) return undefined;
+		const index = from ? mailbox.findIndex(msg => msg.from === from) : 0;
+		if (index === -1 || mailbox.length === 0) return undefined;
+		const [message] = mailbox.splice(index, 1);
+		if (mailbox.length === 0) this.#mailboxes.delete(agentId);
+		return message;
+	}
+
+	/**
+	 * Surface agent↔agent traffic as a display-only card on the main session
+	 * UI. Skipped when the main agent is either endpoint: as recipient its
+	 * own `deliverIrcMessage` (or `wait` tool result) already shows the
+	 * message, and as sender the irc send tool call already rendered the
+	 * outbound body — relaying it again would duplicate it in the transcript.
+	 */
+	#relayToMainUi(message: IrcMessage): void {
+		if (message.to === MAIN_AGENT_ID || message.from === MAIN_AGENT_ID) return;
+		const mainSession = this.#registry.get(MAIN_AGENT_ID)?.session;
+		if (!mainSession) return;
+		const record: CustomMessage = {
+			role: "custom",
+			customType: "irc:relay",
+			content: `[IRC \`${message.from}\` → \`${message.to}\`]\n\n${message.body}`,
+			display: true,
+			details: { from: message.from, to: message.to, body: message.body },
+			attribution: "agent",
+			timestamp: message.ts,
+		};
+		try {
+			mainSession.emitIrcRelayObservation(record);
+		} catch (error) {
+			// Display-only forwarding must never affect delivery semantics.
+			logger.debug("IrcBus: main UI relay failed", { to: message.to, error: String(error) });
+		}
+	}
+}