taskplane 0.22.17 → 0.23.0

package/extensions/taskplane/extension.ts

@@ -32,7 +32,21 @@ import { runMigrations } from "./migrations.ts";
 import { serializeWorkspaceConfig, applySerializedState, deserializeWorkspaceConfig } from "./engine-worker.ts";
 import type { EngineWorkerData, WorkerToMainMessage } from "./engine-worker.ts";
 import { cleanupPostIntegrate, formatPostIntegrateCleanup, sweepStaleArtifacts, formatPreflightSweep, rotateSupervisorLogs, formatLogRotation } from "./cleanup.ts";
-import { writeMailboxMessage } from "./mailbox.ts";
+import {
+	writeMailboxMessage,
+	readOutbox,
+	readOutboxHistory,
+	discoverMailboxAgentIds,
+	writeBroadcastMessage,
+	checkRateLimit,
+	recordSend,
+	appendMailboxAuditEvent,
+} from "./mailbox.ts";
+import {
+	readRegistrySnapshot,
+	isProcessAlive as registryIsProcessAlive,
+	isTerminalStatus,
+} from "./process-registry.ts";
 import type { MailboxMessageType } from "./types.ts";
 import {
 	activateSupervisor,
@@ -3515,19 +3529,22 @@ export default function (pi: ExtensionAPI) {
 		label: "Start Batch",
 		description:
 			"Start a new orchestration batch. Target is \"all\" to run all pending tasks, " +
-			"or a specific task area name or path. The batch runs asynchronously — " +
-			"use orch_status() to monitor progress.",
+			"a task area name, a directory path, or one or more PROMPT.md paths. " +
+			"The batch runs asynchronously — use orch_status() to monitor progress.",
 		promptSnippet: "orch_start(target) — start a new batch",
 		promptGuidelines: [
 			"Call orch_start to begin executing pending tasks as a batch.",
-			'Use target="all" to run all pending tasks, or specify a task area name or path.',
+			'Use target="all" to run all pending tasks.',
+			"Specify a task area name to run all pending tasks in that area.",
+			"Specify a PROMPT.md path to run a single task: target=\"taskplane-tasks/TP-101/PROMPT.md\"",
+			"Specify multiple space-separated PROMPT.md paths to run specific tasks: target=\"path/TP-001/PROMPT.md path/TP-002/PROMPT.md\"",
 			"Cannot start if a batch is already running — check orch_status() first.",
 			"The batch runs asynchronously. The tool returns immediately with an ACK.",
 			"After starting, use orch_status() to track progress.",
 		],
 		parameters: Type.Object({
 			target: Type.String({
-				description: 'Target to run: "all" for all pending tasks, or a task area name/path',
+				description: 'Target to run: "all" for all pending tasks, a task area name, a directory path, or one or more PROMPT.md paths (space-separated)',
 			}),
 		}),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -3689,6 +3706,34 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	function collectKnownAgentIds(stateRoot: string, state: PersistedBatchState): string[] {
+		const ids = new Set<string>();
+
+		// Runtime V2 source of truth first.
+		const registry = readRegistrySnapshot(stateRoot, state.batchId);
+		if (registry) {
+			for (const manifest of Object.values(registry.agents)) {
+				if (manifest.role !== "worker" && manifest.role !== "reviewer" && manifest.role !== "merger") continue;
+				if (isTerminalStatus(manifest.status) || !registryIsProcessAlive(manifest.pid)) continue;
+				ids.add(manifest.agentId);
+			}
+		}
+
+		// Legacy fallback from lane naming when registry is absent/empty.
+		if (ids.size === 0) {
+			const orchConfig = execCtx?.orchestratorConfig;
+			const tmuxPrefix = orchConfig?.orchestrator?.tmux_prefix ?? "orch";
+			const opId = orchConfig ? resolveOperatorId(orchConfig) : "op";
+			for (const lane of state.lanes) {
+				ids.add(`${lane.tmuxSessionName}-worker`);
+				ids.add(`${lane.tmuxSessionName}-reviewer`);
+				ids.add(`${tmuxPrefix}-${opId}-merge-${lane.laneNumber}`);
+			}
+		}
+
+		return [...ids];
+	}
+
 	/**
 	 * Send a steering message to a running agent via the mailbox system.
 	 *
@@ -3722,19 +3767,8 @@ export default function (pi: ExtensionAPI) {
 			return `❌ Batch ${state.batchId} is in terminal phase (${state.phase}). Start or resume a batch before sending messages.`;
 		}
 
-		// Build the set of valid agent session names from batch state
-		const validSessions = new Set<string>();
-		const orchConfig = execCtx?.orchestratorConfig;
-		const tmuxPrefix = orchConfig?.orchestrator?.tmux_prefix ?? "orch";
-		const opId = orchConfig ? resolveOperatorId(orchConfig) : "op";
-
-		for (const lane of state.lanes) {
-			// Worker and reviewer are derived from lane session name
-			validSessions.add(`${lane.tmuxSessionName}-worker`);
-			validSessions.add(`${lane.tmuxSessionName}-reviewer`);
-			// Merger: {tmuxPrefix}-{opId}-merge-{laneNumber}
-			validSessions.add(`${tmuxPrefix}-${opId}-merge-${lane.laneNumber}`);
-		}
+		// Build valid runtime agent IDs (registry-first, legacy fallback).
+		const validSessions = new Set<string>(collectKnownAgentIds(stateRoot, state));
 
 		// Validate target session
 		if (!validSessions.has(to)) {
@@ -3742,11 +3776,38 @@ export default function (pi: ExtensionAPI) {
 			return `❌ Unknown session "${to}" in batch ${state.batchId}.\nValid targets: ${examples}${validSessions.size > 5 ? ` (${validSessions.size} total)` : ""}`;
 		}
 
-		// Guard: ensure the target tmux session is currently alive.
-		// Prevents false-positive "message sent" confirmations when the
-		// batch is paused/stopped or the agent session has already exited.
-		if (!tmuxHasSession(to)) {
-			return `❌ Session "${to}" is not currently running. Use orch_status() or orch_resume() before sending messages.`;
+		// Guard: ensure the target agent is currently alive.
+		// Check process registry first (Runtime V2), fall back to TMUX (legacy).
+		let agentAlive = false;
+		try {
+			const registry = readRegistrySnapshot(stateRoot, state.batchId);
+			if (registry && registry.agents[to]) {
+				const manifest = registry.agents[to];
+				agentAlive = !isTerminalStatus(manifest.status) && registryIsProcessAlive(manifest.pid);
+			} else {
+				// No registry entry — fall back to TMUX for legacy batches
+				agentAlive = tmuxHasSession(to);
+			}
+		} catch {
+			// Registry read failed — fall back to TMUX
+			agentAlive = tmuxHasSession(to);
+		}
+		if (!agentAlive) {
+			return `❌ Agent "${to}" is not currently running. Use orch_status() or orch_resume() before sending messages.`;
+		}
+
+		// Rate limiting (TP-106)
+		const rateCheck = checkRateLimit(to);
+		if (!rateCheck.allowed) {
+			const waitSec = Math.ceil((rateCheck.retryAfterMs ?? 0) / 1000);
+			appendMailboxAuditEvent(stateRoot, state.batchId, {
+				type: "message_rate_limited",
+				from: "supervisor",
+				to,
+				reason: "per-agent rate limit",
+				retryAfterMs: rateCheck.retryAfterMs,
+			});
+			return `⏳ Rate limited: wait ${waitSec}s before sending another message to \`${to}\`.`;
 		}
 
 		// Write message to inbox
@@ -3756,6 +3817,16 @@ export default function (pi: ExtensionAPI) {
 				type: messageType as MailboxMessageType,
 				content,
 			});
+			recordSend(to);
+			appendMailboxAuditEvent(stateRoot, state.batchId, {
+				type: "message_sent",
+				from: "supervisor",
+				to,
+				messageId: msg.id,
+				messageType,
+				contentPreview: content.slice(0, 200),
+				broadcast: false,
+			});
 			return `✅ Message sent to \`${to}\` (batch ${state.batchId})\n` +
 				`- **ID:** ${msg.id}\n` +
 				`- **Type:** ${messageType}\n` +
@@ -3766,6 +3837,192 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
+	// ── TP-106: read_agent_replies tool ───────────────────────
+
+	pi.registerTool({
+		name: "read_agent_replies",
+		label: "Read Agent Replies",
+		description:
+			"Read reply and escalation messages from agents (non-consuming). " +
+			"Returns pending and already-acked outbox messages from a specific agent or all agents. " +
+			"Messages are never removed by reading — this is a durable history view.",
+		promptSnippet: "read_agent_replies(from?) \u2014 read replies/escalations from agents (read-only, non-consuming)",
+		promptGuidelines: [
+			"Call read_agent_replies to check if any agent has sent a reply or escalation.",
+			"Omit 'from' to read replies from all agents.",
+			"Provide 'from' with an agent ID to read replies from a specific agent.",
+			"This is non-consuming: replies remain visible after reading (pending + acked history).",
+		],
+		parameters: Type.Object({
+			from: Type.Optional(Type.String({
+				description: "Agent ID to read replies from (omit for all agents)",
+			})),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const result = doReadAgentReplies(params.from, ctx);
+				return { content: [{ type: "text" as const, text: result }], details: undefined };
+			} catch (err) {
+				return {
+					content: [{ type: "text" as const, text: `Error reading replies: ${err instanceof Error ? err.message : String(err)}` }],
+					details: undefined,
+				};
+			}
+		},
+	});
+
+	/**
+	 * Read agent replies/escalations. Non-consuming (read-only):
+	 * reads both pending outbox and processed (acked) messages so
+	 * replies are never lost from the supervisor's view.
+	 *
+	 * @since TP-091 (lifecycle semantics hardened)
+	 */
+	function doReadAgentReplies(from: string | undefined, ctx: ExtensionContext): string {
+		const stateRoot = resolveToolStateRoot(ctx);
+		const state = loadBatchState(stateRoot);
+		if (!state) return "❌ No batch state found.";
+
+		// TP-091: when from is omitted, union live agents + mailbox history roots
+		// so replies from agents no longer active are still visible.
+		const agentIds = from
+			? [from]
+			: [...new Set([
+				...collectKnownAgentIds(stateRoot, state),
+				...discoverMailboxAgentIds(stateRoot, state.batchId),
+			])];
+
+		// TP-091: read full outbox history (pending + processed) for durable visibility
+		const allEntries: Array<{ agentId: string; message: import("./types.ts").MailboxMessage; acked: boolean }> = [];
+		for (const agentId of agentIds) {
+			const history = readOutboxHistory(stateRoot, state.batchId, agentId);
+			for (const entry of history) {
+				allEntries.push({ agentId, ...entry });
+			}
+		}
+
+		if (allEntries.length === 0) {
+			return from
+				? `No replies from \`${from}\` in batch ${state.batchId}.`
+				: `No agent replies in batch ${state.batchId}.`;
+		}
+
+		const lines: string[] = [`📨 **Agent Replies** (${allEntries.length} message(s))\n`];
+		for (const { agentId, message, acked } of allEntries) {
+			const ts = new Date(message.timestamp).toISOString().slice(0, 16).replace("T", " ");
+			const statusTag = acked ? " *(acked)*" : " *(pending)*";
+			lines.push(`### ${message.type.toUpperCase()} from \`${agentId}\`${statusTag}`);
+			lines.push(`- **Time:** ${ts}`);
+			lines.push(`- **ID:** ${message.id}`);
+			if (message.replyTo) lines.push(`- **Reply to:** ${message.replyTo}`);
+			lines.push(`- **Content:** ${message.content.slice(0, 500)}`);
+			lines.push("");
+		}
+
+		return lines.join("\n");
+	}
+
+	// ── TP-106: broadcast_message tool ────────────────────────
+
+	pi.registerTool({
+		name: "broadcast_message",
+		label: "Broadcast Message",
+		description:
+			"Send a message to all active agents. " +
+			"The message is written to the broadcast directory and delivered to all agents at their next turn boundary.",
+		promptSnippet: "broadcast_message(content, type?) \u2014 send message to all agents",
+		promptGuidelines: [
+			"Call broadcast_message to send a message to all active agents at once.",
+			"Default type is 'info'. Other types: 'steer', 'abort'.",
+			"Messages are limited to 4KB.",
+			"Rate limiting is all-or-none: if ANY recipient is rate-limited, the entire broadcast is rejected.",
+		],
+		parameters: Type.Object({
+			content: Type.String({
+				description: "Message content (max 4KB)",
+			}),
+			type: Type.Optional(Type.Union(
+				[Type.Literal("steer"), Type.Literal("info"), Type.Literal("abort")],
+				{ description: 'Message type (default: "info")' },
+			)),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const result = doBroadcastMessage(params.content, params.type ?? "info", ctx);
+				return { content: [{ type: "text" as const, text: result }], details: undefined };
+			} catch (err) {
+				return {
+					content: [{ type: "text" as const, text: `Error broadcasting: ${err instanceof Error ? err.message : String(err)}` }],
+					details: undefined,
+				};
+			}
+		},
+	});
+
+	function doBroadcastMessage(content: string, messageType: string, ctx: ExtensionContext): string {
+		const stateRoot = resolveToolStateRoot(ctx);
+		const state = loadBatchState(stateRoot);
+		if (!state) return "❌ No batch state found.";
+		if (isBatchTerminal(state.phase)) {
+			return `❌ Batch ${state.batchId} is in terminal phase (${state.phase}).`;
+		}
+
+		const validTypes = new Set(["steer", "info", "abort"]);
+		if (!validTypes.has(messageType)) {
+			return `❌ Invalid broadcast type "${messageType}". Valid types: steer, info, abort.`;
+		}
+
+		const recipients = collectKnownAgentIds(stateRoot, state);
+		if (recipients.length === 0) {
+			return `❌ No known agents found in batch ${state.batchId} for broadcast delivery.`;
+		}
+
+		const blocked = recipients
+			.map((agentId) => ({ agentId, check: checkRateLimit(agentId) }))
+			.filter(({ check }) => !check.allowed);
+		if (blocked.length > 0) {
+			for (const b of blocked) {
+				appendMailboxAuditEvent(stateRoot, state.batchId, {
+					type: "message_rate_limited",
+					from: "supervisor",
+					to: b.agentId,
+					reason: "broadcast blocked by per-agent rate limit",
+					retryAfterMs: b.check.retryAfterMs,
+				});
+			}
+			const preview = blocked.slice(0, 5).map(b => `${b.agentId} (${Math.ceil((b.check.retryAfterMs ?? 0) / 1000)}s)`).join(", ");
+			return `⏳ Broadcast rate limited for ${blocked.length}/${recipients.length} agent(s): ${preview}${blocked.length > 5 ? " ..." : ""}`;
+		}
+
+		try {
+			const msg = writeBroadcastMessage(stateRoot, state.batchId, {
+				from: "supervisor",
+				type: messageType as MailboxMessageType,
+				content,
+			});
+			for (const agentId of recipients) {
+				recordSend(agentId);
+			}
+			appendMailboxAuditEvent(stateRoot, state.batchId, {
+				type: "message_sent",
+				from: "supervisor",
+				to: "_broadcast",
+				messageId: msg.id,
+				messageType,
+				contentPreview: content.slice(0, 200),
+				broadcast: true,
+			});
+			return `✅ Broadcast sent (batch ${state.batchId})\n` +
+				`- **ID:** ${msg.id}\n` +
+				`- **Type:** ${messageType}\n` +
+				`- **Recipients:** ${recipients.length}\n` +
+				`- **Size:** ${Buffer.byteLength(content, "utf8")} bytes\n` +
+				`Message will be delivered to all agents at their next turn boundary.`;
+		} catch (err) {
+			return `❌ Failed to broadcast: ${err instanceof Error ? err.message : String(err)}`;
+		}
+	}
+
 	function resolveToolStateRoot(context: ExtensionContext): string {
 		return execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? context.cwd;
 	}
@@ -4148,7 +4405,16 @@ export default function (pi: ExtensionAPI) {
 	function doListActiveAgents(ctx: ExtensionContext): string {
 		const stateRoot = resolveToolStateRoot(ctx);
 
-		// Get tmux sessions
+		// Try Runtime V2 registry first
+		const state = loadBatchState(stateRoot);
+		if (state) {
+			const registry = readRegistrySnapshot(stateRoot, state.batchId);
+			if (registry && Object.keys(registry.agents).length > 0) {
+				return formatRegistryAgents(registry, state);
+			}
+		}
+
+		// Fall back to TMUX-based discovery for legacy batches
 		let sessions: string[] = [];
 		try {
 			const output = execSync('tmux list-sessions -F "#{session_name}"', {
@@ -4158,13 +4424,12 @@ export default function (pi: ExtensionAPI) {
 			}).trim();
 			sessions = output ? output.split("\n").map(s => s.trim()).filter(Boolean) : [];
 		} catch {
-			return "❌ tmux not available or no sessions running.";
+			return "❌ No active agents found (no registry and no tmux sessions).";
 		}
 
-		if (sessions.length === 0) return "❌ No tmux sessions found.";
+		if (sessions.length === 0) return "❌ No active agents found.";
 
-		// Load batch state for task/lane mapping
-		const state = loadBatchState(stateRoot);
+		// state already loaded above for registry check (may be null)
 
 		// Build a map of session name → lane-state data
 		const laneStates: Record<string, any> = {};
@@ -4244,6 +4509,35 @@ export default function (pi: ExtensionAPI) {
 		return lines.join("\n");
 	}
 
+
+	// ── TP-106: Registry-based agent list formatter ────────────────
+
+	function formatRegistryAgents(registry: import("./types.ts").RuntimeRegistry, _batchState: PersistedBatchState | null): string {
+		const agents = Object.values(registry.agents);
+		if (agents.length === 0) return "❌ No agents in registry.";
+
+		const lines: string[] = [];
+		lines.push(`👥 **Active Agents** (${agents.length} registered)
+`);
+
+		for (const m of agents) {
+			const alive = !isTerminalStatus(m.status) && registryIsProcessAlive(m.pid);
+			const icon = alive ? "🟢" : "🔴";
+			const parts: string[] = [`**${m.agentId}**`];
+			parts.push(`role: ${m.role}`);
+			if (m.laneNumber != null) parts.push(`lane: ${m.laneNumber}`);
+			if (m.taskId) parts.push(`task: ${m.taskId}`);
+			parts.push(`status: ${m.status}`);
+			if (alive) {
+				const elapsed = Math.round((Date.now() - m.startedAt) / 1000);
+				parts.push(`elapsed: ${elapsed}s`);
+			}
+			lines.push(`- ${icon} ${parts.join(" · ")}`);
+		}
+
+		return lines.join("\n");
+	}
+
 	// ── Settings TUI ─────────────────────────────────────────────────
 
 	pi.registerCommand("taskplane-settings", {