taskplane 0.22.18 → 0.23.0

package/extensions/taskplane/mailbox.ts

@@ -24,7 +24,7 @@
  */
 
 import { join, dirname } from "path";
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, renameSync, unlinkSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, renameSync, unlinkSync, appendFileSync } from "fs";
 import { randomBytes } from "crypto";
 import type { MailboxMessage, MailboxMessageType, WriteMailboxMessageOpts } from "./types.ts";
 import { MAILBOX_DIR_NAME, MAILBOX_MAX_CONTENT_BYTES, MAILBOX_MESSAGE_TYPES } from "./types.ts";
@@ -339,3 +339,351 @@ export function isValidMailboxMessage(obj: unknown): obj is MailboxMessage {
 		typeof m.content === "string"
 	);
 }
+
+
+// ── Outbox (Agent → Supervisor, TP-106) ─────────────────────────
+
+/**
+ * Outbox directory for a specific agent session.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Batch ID
+ * @param sessionName - Agent ID / session name
+ * @returns Absolute path: `{stateRoot}/.pi/mailbox/{batchId}/{sessionName}/outbox/`
+ *
+ * @since TP-106
+ */
+export function sessionOutboxDir(stateRoot: string, batchId: string, sessionName: string): string {
+	return join(stateRoot, ".pi", MAILBOX_DIR_NAME, batchId, sessionName, "outbox");
+}
+
+/**
+ * Write a reply or escalation message to an agent's outbox.
+ *
+ * Used by agents (via bridge tools or direct write) to communicate
+ * back to the supervisor. The engine or lane-runner polls outbox
+ * directories and surfaces messages as supervisor alerts.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Current batch ID
+ * @param from - Agent ID writing the message
+ * @param opts - Message content and metadata
+ * @returns The written MailboxMessage
+ *
+ * @since TP-106
+ */
+export function writeOutboxMessage(
+	stateRoot: string,
+	batchId: string,
+	from: string,
+	opts: WriteMailboxMessageOpts,
+): MailboxMessage {
+	const outboxDir = sessionOutboxDir(stateRoot, batchId, from);
+	mkdirSync(outboxDir, { recursive: true });
+
+	const contentBytes = Buffer.byteLength(opts.content, "utf8");
+	if (contentBytes > MAILBOX_MAX_CONTENT_BYTES) {
+		throw new Error(
+			`Outbox message content exceeds ${MAILBOX_MAX_CONTENT_BYTES} byte limit (${contentBytes} bytes).`,
+		);
+	}
+
+	const timestamp = Date.now();
+	const nonce = randomBytes(3).toString("hex").slice(0, 5);
+	const id = `${timestamp}-${nonce}`;
+
+	const message: MailboxMessage = {
+		id,
+		batchId,
+		from,
+		to: "supervisor",
+		timestamp,
+		type: opts.type,
+		content: opts.content,
+		expectsReply: opts.expectsReply ?? false,
+		replyTo: opts.replyTo ?? null,
+	};
+
+	const finalFilename = `${id}.msg.json`;
+	const tempFilename = `${id}.msg.json.tmp`;
+	const tempPath = join(outboxDir, tempFilename);
+	const finalPath = join(outboxDir, finalFilename);
+
+	try {
+		writeFileSync(tempPath, JSON.stringify(message, null, 2) + "\n", "utf-8");
+		renameSync(tempPath, finalPath);
+	} catch (err) {
+		try { if (existsSync(tempPath)) unlinkSync(tempPath); } catch { /* cleanup */ }
+		throw new Error(`Failed to write outbox message: ${err instanceof Error ? err.message : String(err)}`);
+	}
+
+	return message;
+}
+
+/**
+ * Read pending outbox messages from an agent's outbox directory.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Batch ID
+ * @param agentId - Agent ID whose outbox to read
+ * @returns Array of outbox messages sorted by timestamp
+ *
+ * @since TP-106
+ */
+export function readOutbox(
+	stateRoot: string,
+	batchId: string,
+	agentId: string,
+): MailboxMessage[] {
+	const outboxDir = sessionOutboxDir(stateRoot, batchId, agentId);
+	if (!existsSync(outboxDir)) return [];
+
+	let entries: string[];
+	try {
+		entries = readdirSync(outboxDir);
+	} catch {
+		return [];
+	}
+
+	const msgFiles = entries.filter(f => f.endsWith(".msg.json") && !f.endsWith(".msg.json.tmp"));
+	const messages: MailboxMessage[] = [];
+
+	for (const filename of msgFiles) {
+		try {
+			const raw = readFileSync(join(outboxDir, filename), "utf-8");
+			const parsed = JSON.parse(raw);
+			if (isValidMailboxMessage(parsed)) {
+				messages.push(parsed);
+			}
+		} catch { /* skip malformed */ }
+	}
+
+	messages.sort((a, b) => a.timestamp - b.timestamp);
+	return messages;
+}
+
+/**
+ * Read all outbox messages (pending + processed) for durable history.
+ *
+ * Unlike readOutbox() which only reads pending messages, this function
+ * also reads outbox/processed/ so consumed replies remain visible to
+ * the supervisor via read_agent_replies.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Batch ID
+ * @param agentId - Agent ID whose outbox history to read
+ * @returns Array of { message, acked } sorted by timestamp
+ *
+ * @since TP-091
+ */
+export function readOutboxHistory(
+	stateRoot: string,
+	batchId: string,
+	agentId: string,
+): Array<{ message: MailboxMessage; acked: boolean }> {
+	const outboxDir = sessionOutboxDir(stateRoot, batchId, agentId);
+	const results: Array<{ message: MailboxMessage; acked: boolean }> = [];
+
+	for (const [dir, acked] of [[outboxDir, false], [join(outboxDir, "processed"), true]] as const) {
+		if (!existsSync(dir)) continue;
+		let entries: string[];
+		try { entries = readdirSync(dir); } catch { continue; }
+
+		const msgFiles = entries.filter(f => f.endsWith(".msg.json") && !f.endsWith(".msg.json.tmp"));
+		for (const filename of msgFiles) {
+			try {
+				const raw = readFileSync(join(dir, filename), "utf-8");
+				const parsed = JSON.parse(raw);
+				if (isValidMailboxMessage(parsed)) {
+					results.push({ message: parsed, acked });
+				}
+			} catch { /* skip malformed */ }
+		}
+	}
+
+	results.sort((a, b) => a.message.timestamp - b.message.timestamp);
+	return results;
+}
+
+/**
+ * Ack (consume) a specific outbox message by moving it to processed/.
+ *
+ * Returns false if the message is already gone (race-safe/idempotent).
+ *
+ * @since TP-106
+ */
+export function ackOutboxMessage(
+	stateRoot: string,
+	batchId: string,
+	agentId: string,
+	messageId: string,
+): boolean {
+	const outboxDir = sessionOutboxDir(stateRoot, batchId, agentId);
+	const processedDir = join(outboxDir, "processed");
+	const file = `${messageId}.msg.json`;
+	const srcPath = join(outboxDir, file);
+	const dstPath = join(processedDir, file);
+
+	try {
+		mkdirSync(processedDir, { recursive: true });
+		renameSync(srcPath, dstPath);
+		return true;
+	} catch (err: unknown) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return false;
+		process.stderr.write(
+			`[mailbox] WARNING: failed to ack outbox ${file}: ${err instanceof Error ? err.message : String(err)}\n`,
+		);
+		return false;
+	}
+}
+
+/**
+ * Discover all agent IDs that have mailbox directories for a batch.
+ * Returns directory names under .pi/mailbox/{batchId}/ excluding _broadcast.
+ * Used to find agents with historical messages even if no longer in the registry.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Batch ID
+ * @returns Array of agent IDs found in mailbox directories
+ *
+ * @since TP-091
+ */
+export function discoverMailboxAgentIds(
+	stateRoot: string,
+	batchId: string,
+): string[] {
+	const mbRoot = join(stateRoot, ".pi", MAILBOX_DIR_NAME, batchId);
+	if (!existsSync(mbRoot)) return [];
+	try {
+		const entries = readdirSync(mbRoot, { withFileTypes: true });
+		return entries
+			.filter(e => e.isDirectory() && e.name !== "_broadcast")
+			.map(e => e.name);
+	} catch {
+		return [];
+	}
+}
+
+
+export type MailboxAuditEventType =
+	| "message_sent"
+	| "message_delivered"
+	| "message_replied"
+	| "message_escalated"
+	| "message_rate_limited";
+
+/**
+ * Append a mailbox audit event to .pi/mailbox/{batchId}/events.jsonl.
+ *
+ * Best-effort: logs warning but never throws.
+ *
+ * @since TP-106
+ */
+export function appendMailboxAuditEvent(
+	stateRoot: string,
+	batchId: string,
+	event: {
+		type: MailboxAuditEventType;
+		ts?: number;
+		from?: string;
+		to?: string;
+		messageId?: string;
+		messageType?: string;
+		contentPreview?: string;
+		broadcast?: boolean;
+		reason?: string;
+		retryAfterMs?: number;
+	},
+): void {
+	const eventsPath = join(mailboxRoot(stateRoot, batchId), "events.jsonl");
+	try {
+		mkdirSync(dirname(eventsPath), { recursive: true });
+		appendFileSync(
+			eventsPath,
+			JSON.stringify({ batchId, ts: event.ts ?? Date.now(), ...event }) + "\n",
+			"utf-8",
+		);
+	} catch (err) {
+		process.stderr.write(
+			`[mailbox] WARNING: failed to append mailbox event: ${err instanceof Error ? err.message : String(err)}\n`,
+		);
+	}
+}
+
+
+// ── Broadcast (TP-106) ────────────────────────────────────────
+
+/**
+ * Write a broadcast message to all agents.
+ *
+ * The message is written to `_broadcast/inbox/`. Agent hosts check
+ * this directory alongside their own inbox on each `message_end`.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Current batch ID
+ * @param opts - Message content and metadata
+ * @returns The written MailboxMessage
+ *
+ * @since TP-106
+ */
+export function writeBroadcastMessage(
+	stateRoot: string,
+	batchId: string,
+	opts: WriteMailboxMessageOpts,
+): MailboxMessage {
+	return writeMailboxMessage(stateRoot, batchId, "_broadcast", {
+		...opts,
+		from: opts.from || "supervisor",
+	});
+}
+
+
+// ── Rate Limiting (TP-106) ─────────────────────────────────────
+
+/** Default rate limit: max 1 message per agent per 30 seconds. */
+export const RATE_LIMIT_WINDOW_MS = 30_000;
+
+/** In-memory rate limit tracker. Keyed by target agent ID. */
+const rateLimitTracker = new Map<string, number>();
+
+/**
+ * Check whether sending a message to a target is rate-limited.
+ *
+ * @param targetAgentId - Agent ID being sent to
+ * @param windowMs - Rate limit window in ms (default: 30_000)
+ * @returns Object with `allowed` and optional `retryAfterMs`
+ *
+ * @since TP-106
+ */
+export function checkRateLimit(
+	targetAgentId: string,
+	windowMs: number = RATE_LIMIT_WINDOW_MS,
+): { allowed: boolean; retryAfterMs?: number } {
+	const lastSent = rateLimitTracker.get(targetAgentId);
+	if (!lastSent) return { allowed: true };
+
+	const elapsed = Date.now() - lastSent;
+	if (elapsed >= windowMs) return { allowed: true };
+
+	return { allowed: false, retryAfterMs: windowMs - elapsed };
+}
+
+/**
+ * Record a send timestamp for rate limiting.
+ *
+ * @param targetAgentId - Agent ID that was sent to
+ *
+ * @since TP-106
+ */
+export function recordSend(targetAgentId: string): void {
+	rateLimitTracker.set(targetAgentId, Date.now());
+}
+
+/**
+ * Reset rate limit state (for testing).
+ * @since TP-106
+ */
+export function _resetRateLimits(): void {
+	rateLimitTracker.clear();
+}