pi-subagents 0.35.0 → 0.36.0

package/src/runs/background/subagent-wait.ts

@@ -38,6 +38,7 @@
  * polling.
  */
 
+import * as fs from "node:fs";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import {
 	listBackgroundWorkWakeChannels,
@@ -48,6 +49,7 @@ import {
 import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
 import {
 	ASYNC_DIR,
+	INTERCOM_DETACH_REQUEST_EVENT,
 	RESULTS_DIR,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
 	SUBAGENT_FOREGROUND_COMPLETE_EVENT,
@@ -89,6 +91,8 @@ export interface WaitEventBus {
 
 export interface SubagentWaitDeps {
 	state: SubagentState;
+	/** Stream live wait status into Pi's pending tool row. */
+	onUpdate?: (result: AgentToolResult<Details>) => void;
 	asyncDirRoot?: string;
 	resultsDir?: string;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
@@ -118,6 +122,7 @@ export interface SubagentWaitDeps {
 
 /** Bus channels that indicate a run changed state or needs attention. */
 const WAKE_CHANNELS = [
+	INTERCOM_DETACH_REQUEST_EVENT,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
 	SUBAGENT_FOREGROUND_COMPLETE_EVENT,
 	SUBAGENT_CONTROL_EVENT,
@@ -214,9 +219,26 @@ function summarizeForegroundChildren(run: ForegroundResumeRun, indices: Set<numb
 	return [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(", ");
 }
 
+function foregroundChildrenNeedingAttention(run: ForegroundResumeRun, indices: Set<number>) {
+	return run.children.filter((child) => indices.has(child.index) && child.status === "detached" && child.activityState === "needs_attention");
+}
+
+function formatForegroundAttention(run: ForegroundResumeRun, children: ReturnType<typeof foregroundChildrenNeedingAttention>, elapsedMs: number): AgentToolResult<Details> {
+	const childList = children.map((child) => `${child.agent}${child.index !== undefined ? `#${child.index}` : ""}`).join(", ");
+	return result(
+		`Waited ${formatDuration(elapsedMs)} for remembered detached foreground run "${run.runId}"; attention required. ${children.length} child run(s) need attention: ${childList}. Reply to any pending supervisor request, then call subagent_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,
+	);
+}
+
 /** A running run that has flagged it needs the parent's attention. */
 function needsAttention(run: AsyncRunSummary): boolean {
-	return run.activityState === "needs_attention";
+	return run.activityState === "needs_attention" || run.steps.some((step) => step.activityState === "needs_attention");
+}
+
+function hasSupervisorTool(run: AsyncRunSummary): boolean {
+	return run.currentTool === "contact_supervisor"
+		|| run.currentTool === "intercom"
+		|| run.steps.some((step) => step.currentTool === "contact_supervisor" || step.currentTool === "intercom");
 }
 
 function backgroundWorkIdentity(item: RegisteredBackgroundWorkItem): string {
@@ -239,6 +261,7 @@ function activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps
 		resultsDir,
 		kill: deps.kill,
 		now: deps.now,
+		...(params.id ? { runId: params.id } : {}),
 	});
 	return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
 }
@@ -257,6 +280,7 @@ function allRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps):
 		resultsDir,
 		kill: deps.kill,
 		now: deps.now,
+		...(params.id ? { runId: params.id } : {}),
 	});
 	return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
 }
@@ -283,6 +307,101 @@ function result(text: string, isError = false): AgentToolResult<Details> {
 	};
 }
 
+const TRANSCRIPT_TAIL_BYTES = 128 * 1024;
+const TRANSCRIPT_PREVIEW_LINES = 3;
+const TRANSCRIPT_PREVIEW_WIDTH = 220;
+
+interface TranscriptActivity {
+	currentTool?: string;
+	currentToolArgs?: string;
+	latestAt?: number;
+	recent: string[];
+}
+
+function compactTranscriptText(value: unknown, maxWidth = TRANSCRIPT_PREVIEW_WIDTH): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const compact = value.replace(/\s+/g, " ").trim();
+	if (!compact) return undefined;
+	return compact.length <= maxWidth ? compact : `${compact.slice(0, Math.max(1, maxWidth - 1))}…`;
+}
+
+function readTranscriptActivity(transcriptPath: string | undefined): TranscriptActivity | undefined {
+	if (!transcriptPath) return undefined;
+	let fd: number | undefined;
+	try {
+		const stat = fs.statSync(transcriptPath);
+		if (!stat.isFile() || stat.size <= 0) return undefined;
+		const start = Math.max(0, stat.size - TRANSCRIPT_TAIL_BYTES);
+		const length = stat.size - start;
+		const buffer = Buffer.allocUnsafe(length);
+		fd = fs.openSync(transcriptPath, "r");
+		const bytesRead = fs.readSync(fd, buffer, 0, length, start);
+		let lines = buffer.subarray(0, bytesRead).toString("utf-8").split(/\r?\n/);
+		if (start > 0) lines = lines.slice(1); // The first tail line may be partial JSON.
+
+		let currentTool: string | undefined;
+		let currentToolArgs: string | undefined;
+		let latestAt: number | undefined;
+		const recent: string[] = [];
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			let record: Record<string, unknown>;
+			try {
+				record = JSON.parse(line) as Record<string, unknown>;
+			} catch {
+				continue; // Concurrent append can leave the final line temporarily incomplete.
+			}
+			if (typeof record.ts === "number" && Number.isFinite(record.ts)) latestAt = record.ts;
+			if (record.recordType === "tool_start" && typeof record.toolName === "string") {
+				currentTool = record.toolName;
+				currentToolArgs = compactTranscriptText(record.argsPreview, 140);
+				const preview = currentToolArgs ? `${currentTool}: ${currentToolArgs}` : currentTool;
+				recent.push(`tool: ${preview}`);
+				continue;
+			}
+			if (record.recordType === "tool_end") {
+				currentTool = undefined;
+				currentToolArgs = undefined;
+				continue;
+			}
+			if (record.recordType === "message") {
+				if (record.sourceEventType === "initial_prompt" || record.role === "user") continue;
+				const text = compactTranscriptText(record.text);
+				if (text) recent.push(`${typeof record.role === "string" ? record.role : "message"}: ${text}`);
+				continue;
+			}
+			if (record.recordType === "stdout" || record.recordType === "stderr") {
+				const text = compactTranscriptText(record.text);
+				if (text) recent.push(`${record.recordType}: ${text}`);
+			}
+		}
+		return { currentTool, currentToolArgs, latestAt, recent: recent.slice(-TRANSCRIPT_PREVIEW_LINES) };
+	} catch {
+		return undefined;
+	} finally {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* best-effort close */ }
+		}
+	}
+}
+
+function detachedForegroundWaitUpdate(run: ForegroundResumeRun, pendingIndices: Set<number>, nowMs: number, elapsedMs: number): AgentToolResult<Details> {
+	const lines = [`Waiting for detached foreground run "${run.runId}" · ${formatDuration(elapsedMs)}`];
+	for (const child of run.children) {
+		if (!pendingIndices.has(child.index) || child.status !== "detached") continue;
+		const activity = readTranscriptActivity(child.transcriptPath);
+		const age = activity?.latestAt !== undefined ? ` · activity ${formatDuration(Math.max(0, nowMs - activity.latestAt))} ago` : "";
+		lines.push(`${child.agent} · working after supervisor handoff${age}`);
+		if (activity?.currentTool) {
+			lines.push(`  current: ${activity.currentTool}${activity.currentToolArgs ? `: ${activity.currentToolArgs}` : ""}`);
+		}
+		for (const preview of activity?.recent ?? []) lines.push(`  ${preview}`);
+		if (!activity && child.transcriptPath) lines.push("  live transcript has no new activity yet");
+		if (!child.transcriptPath) lines.push("  live transcript unavailable; waiting for completion event");
+	}
+	return result(lines.join("\n"));
+}
+
 async function waitForDetachedForegroundRun(
 	run: ForegroundResumeRun,
 	signal: AbortSignal | undefined,
@@ -295,21 +414,25 @@ async function waitForDetachedForegroundRun(
 	const initialDetachedIndices = new Set(run.children.filter((child) => child.status === "detached").map((child) => child.index));
 	while (true) {
 		if (deps.state.currentSessionId !== run.sessionId) {
-			return result(`Wait stopped because the active session changed while remembered foreground run "${run.runId}" was still detached. Return to the originating session to inspect or wait for it.`, true);
+			return result(`Wait stopped because the active session changed while remembered foreground run "${run.runId}" was still detached. Return to the originating session to inspect or wait for it. Reply to any pending supervisor request before resuming or launching a replacement.`, true);
 		}
 		const current = deps.state.foregroundRuns?.get(run.runId);
 		if (!current || current.sessionId !== run.sessionId) {
 			return result(`Remembered foreground run "${run.runId}" disappeared before a terminal child result was recorded. Completion cannot be confirmed; do not launch a replacement without checking the originating child session.`, true);
 		}
 		const pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === "detached");
+		const attention = deps.stopOnAttention === false ? [] : foregroundChildrenNeedingAttention(current, initialDetachedIndices);
+		if (attention.length > 0) return formatForegroundAttention(current, attention, now() - startedAt);
 		if (pending.length === 0) {
 			const outcome = summarizeForegroundChildren(current, initialDetachedIndices);
 			return result(
 				`Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run "${run.runId}"; done. Outcome: ${outcome || "no recovered child status"}. Completion event observed; inspect with subagent({ action: "status", id: "${run.runId}" }) for recovered output.`,
 			);
 		}
+		const updateNow = now();
+		deps.onUpdate?.(detachedForegroundWaitUpdate(current, initialDetachedIndices, updateNow, updateNow - startedAt));
 		if (signal?.aborted) {
-			return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Remembered foreground run "${run.runId}" remains detached.`, true);
+			return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Remembered foreground run "${run.runId}" remains detached. Reply to any pending supervisor request before resuming or launching a replacement.`, true);
 		}
 		if (now() - startedAt >= timeoutMs) {
 			return result(
@@ -446,8 +569,11 @@ export async function waitForSubagents(
 	}
 
 	const relevantAttention = attention.filter((run) => initialAsyncIds.has(run.id));
+	const supervisorAttentionHint = relevantAttention.some(hasSupervisorTool)
+		? " Reply to any pending supervisor request. If subagent_supervisor({ action: \"pending\" }) is empty, check intercom({ action: \"pending\" }) because an external intercom tool may own the request."
+		: "";
 	const attentionNote = relevantAttention.length > 0
-		? ` ${relevantAttention.length} run(s) need attention: ${relevantAttention.map((run) => run.id).join(", ")} — inspect with subagent({ action: "status" }) then steer a top-level live async child, resume a paused/completed/failed child, or interrupt explicitly.`
+		? ` ${relevantAttention.length} run(s) need attention: ${relevantAttention.map((run) => run.id).join(", ")} —${supervisorAttentionHint} inspect with subagent({ action: "status" }) then steer a top-level live async child, resume a paused/completed/failed child, or interrupt explicitly.`
 		: "";
 	const stillRunning = active.filter((run) => initialAsyncIds.has(run.id)).length
 		+ providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;

package/src/runs/background/wait-tool.ts

@@ -18,8 +18,8 @@ In an interactive chat, do not call this merely to wait: return control to the u
 
 Provider jobs are session-scoped and identified exactly, so replacing one job with another cannot hide a completion. Provider extensions must be explicitly loaded in this process. In a child agent, keep \`subagent_wait\` in the child tool allowlist and load each provider through the agent's extensions or subagentOnlyExtensions; this tool never loads providers or grants tools itself.${enabled ? "" : "\n\nConfigured behavior: subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`,
 		parameters: SubagentWaitParams,
-		execute(_id, params, signal) {
-			return waitForSubagents(params, signal, { state, events: pi.events, enabled });
+		execute(_id, params, signal, onUpdate) {
+			return waitForSubagents(params, signal, { state, events: pi.events, enabled, onUpdate });
 		},
 	};
 	pi.registerTool(tool);