@narumitw/pi-subagents 0.43.0 → 0.46.0

package/src/consult-render.ts

@@ -0,0 +1,194 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import {
+	getMarkdownTheme,
+	type Theme,
+	type ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { ConsultDetails, SubagentConsultParams } from "./consult.js";
+import { formatUsageStats } from "./render.js";
+import {
+	COLLAPSED_ANSWER_LINES,
+	COLLAPSED_LIST_LIMIT,
+	expansionHint,
+	previewLines,
+	projectRenderActivity,
+	type RenderStatus,
+	recordValue,
+	renderActivityLines,
+	renderFallbackResult,
+	safeBlock,
+	safeLine,
+	statusBadge,
+	stringValue,
+	type ToolRendererContext,
+	textResult,
+	toolHeader,
+} from "./render-common.js";
+
+export function renderConsultCall(args: Partial<SubagentConsultParams>, theme: Theme) {
+	const scope = args.agentScope ?? "user";
+	const text = [
+		toolHeader(theme, "subagent_consult", args.agent, [`[${scope}]`, "read-only"]),
+		`  ${theme.fg("dim", safeLine(args.task, "...", 2 * 1024))}`,
+	].join("\n");
+	return new Text(text, 0, 0);
+}
+
+export function renderConsultResult(
+	result: AgentToolResult<ConsultDetails>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	context: ToolRendererContext<SubagentConsultParams>,
+) {
+	const details = recordValue(result.details);
+	if (!details || !recordValue(details.policy)) {
+		return renderFallbackResult(result, options, theme, context.isError);
+	}
+
+	const progress = recordValue(details.progress);
+	const child = recordValue(details.child);
+	const status = consultStatus(details, progress, options, context.isError);
+	const agent = safeLine(details.agent, safeLine(context.args?.agent, "subagent"), 256);
+	const source = safeLine(details.agentSource, "unknown", 128);
+	const usage = recordValue(progress?.usage ?? child?.usage);
+	const usageText = formatUnknownUsage(
+		usage,
+		stringValue(details.model) || undefined,
+		stringValue(details.thinkingLevel) || undefined,
+		stringValue(progress?.actualProvider ?? child?.actualProvider) || undefined,
+		stringValue(progress?.actualModel ?? child?.actualModel) || undefined,
+	);
+	const effectiveTools = stringList(recordValue(details.policy)?.effectiveTools);
+	const activity = projectRenderActivity(progress?.recentActivity);
+	const activityTotal = Math.max(
+		activity.length,
+		typeof progress?.recentActivityTotal === "number" ? progress.recentActivityTotal : 0,
+	);
+	const answer = safeBlock(textResult(result), "", 50 * 1024).trim();
+
+	if (options.expanded) {
+		const container = new Container();
+		container.addChild(
+			new Text(
+				`${statusBadge(theme, status)} · ${theme.fg("toolTitle", theme.bold(agent))}${theme.fg("muted", ` (${source})`)}`,
+				0,
+				0,
+			),
+		);
+		if (usageText) container.addChild(new Text(theme.fg("dim", usageText), 0, 0));
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
+		container.addChild(
+			new Text(theme.fg("dim", safeBlock(context.args?.task, "(unavailable)", 50 * 1024)), 0, 0),
+		);
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "─── Policy ───"), 0, 0));
+		container.addChild(new Text(theme.fg("dim", policySummary(details.policy)), 0, 0));
+		if (activity.length > 0) {
+			container.addChild(new Spacer(1));
+			container.addChild(new Text(theme.fg("muted", "─── Activity ───"), 0, 0));
+			container.addChild(
+				new Text(renderActivityLines(activity, theme, undefined, activityTotal), 0, 0),
+			);
+		}
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "─── Answer ───"), 0, 0));
+		if (answer) container.addChild(new Markdown(answer, 0, 0, getMarkdownTheme()));
+		else
+			container.addChild(
+				new Text(
+					theme.fg("muted", options.isPartial ? "(waiting for output)" : "(no output)"),
+					0,
+					0,
+				),
+			);
+		return container;
+	}
+
+	const lines = [
+		`${statusBadge(theme, status)} · ${theme.fg("toolTitle", theme.bold(agent))}${theme.fg("muted", ` (${source})`)}`,
+	];
+	if (usageText) lines.push(theme.fg("dim", usageText));
+	if (effectiveTools.length > 0 && options.isPartial) {
+		lines.push(theme.fg("dim", `tools: ${effectiveTools.join(", ")}`));
+	}
+	if (activity.length > 0) {
+		lines.push(renderActivityLines(activity, theme, COLLAPSED_LIST_LIMIT, activityTotal));
+	} else if (options.isPartial) {
+		lines.push(
+			theme.fg("muted", status === "starting" ? "(starting child)" : "(waiting for activity)"),
+		);
+	} else if (answer) {
+		lines.push(theme.fg("toolOutput", previewLines(answer, COLLAPSED_ANSWER_LINES)));
+	} else {
+		const error = safeBlock(child?.error, "", 2 * 1024).trim();
+		lines.push(theme.fg(status === "failed" ? "error" : "muted", error || "(no output)"));
+	}
+	if (!options.isPartial) lines.push(expansionHint());
+	return new Text(lines.filter(Boolean).join("\n"), 0, 0);
+}
+
+function consultStatus(
+	details: Record<string, unknown>,
+	progress: Record<string, unknown> | undefined,
+	options: ToolRenderResultOptions,
+	isError: boolean,
+): RenderStatus {
+	if (details.cancelled === true) return "cancelled";
+	if (isError || details.isError === true) {
+		const child = recordValue(details.child);
+		return child?.aborted === true && child?.timedOut !== true ? "cancelled" : "failed";
+	}
+	if (options.isPartial) return progress?.phase === "starting" ? "starting" : "running";
+	return "completed";
+}
+
+function stringList(value: unknown): string[] {
+	return Array.isArray(value)
+		? value.flatMap((item) => (typeof item === "string" ? [safeLine(item, "", 256)] : []))
+		: [];
+}
+
+function policySummary(value: unknown): string {
+	const policy = recordValue(value);
+	if (!policy) return "(unavailable)";
+	const resources = recordValue(policy.effectiveResources);
+	const tools = stringList(policy.effectiveTools);
+	return [
+		`tools: ${tools.length > 0 ? tools.join(", ") : "none"}`,
+		`resources: ${safeLine(resources?.policy ?? policy.requestedResources, "unknown", 256)}`,
+		`extensions: ${safeLine(policy.extensions, "unknown", 128)}`,
+		`session persistence: ${safeLine(policy.sessionPersistence, "unknown", 128)}`,
+		`retained agent: ${policy.retainedAgent === false ? "no" : "unknown"}`,
+	].join("\n");
+}
+
+function formatUnknownUsage(
+	value: Record<string, unknown> | undefined,
+	model?: string,
+	thinkingLevel?: string,
+	actualProvider?: string,
+	actualModel?: string,
+): string {
+	const usage = value ?? {};
+	return formatUsageStats(
+		{
+			input: safeNumber(usage.input),
+			output: safeNumber(usage.output),
+			cacheRead: safeNumber(usage.cacheRead),
+			cacheWrite: safeNumber(usage.cacheWrite),
+			cost: safeNumber(usage.cost),
+			contextTokens: safeNumber(usage.contextTokens),
+			turns: safeNumber(usage.turns),
+		},
+		model,
+		thinkingLevel as never,
+		actualProvider,
+		actualModel,
+	);
+}
+
+function safeNumber(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}

package/src/consult.ts

@@ -21,6 +21,12 @@ import {
 	THINKING_LEVELS,
 } from "./agents.js";
 import { resolveConsultTools } from "./consult-policy.js";
+import { renderConsultCall, renderConsultResult } from "./consult-render.js";
+import {
+	assertConsultationTargetAllowed,
+	type ResolvedSubagentTarget,
+	resolveSubagentTarget,
+} from "./cwd-policy.js";
 import { assertSubagentDepthAllowed, resolveDefaultSubagentTimeoutMs } from "./execution.js";
 import {
 	DEFAULT_MAX_CONTEXT_BYTES,
@@ -37,7 +43,11 @@ import {
 	type SubagentDetails,
 } from "./runner.js";
 import { boundedPrivateText, boundText, safeDisplayPath, safeTerminalLine } from "./safe-text.js";
-import { DEFAULT_CONSULT_RESOURCE_POLICY, resolveSubagentThinkingLevel } from "./settings.js";
+import {
+	DEFAULT_CONSULT_RESOURCE_POLICY,
+	DEFAULT_CONSULTATION_CWD_POLICY,
+	resolveSubagentThinkingLevel,
+} from "./settings.js";
 
 const ConsultScopeSchema = StringEnum(["user", "project", "both"] as const, {
 	default: "user",
@@ -80,6 +90,30 @@ export interface RegisterSubagentConsultOptions {
 	invocationOverride?: { command: string; argsPrefix?: string[] };
 }
 
+export interface ConsultProgressActivity {
+	type: "text" | "toolCall";
+	text?: string;
+	name?: "read" | "grep" | "find" | "ls";
+	args?: Record<string, string | number | boolean>;
+}
+
+export interface ConsultProgress {
+	phase: "starting" | "running";
+	recentActivity: ConsultProgressActivity[];
+	recentActivityTotal: number;
+	actualProvider?: string;
+	actualModel?: string;
+	usage: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		cost: number;
+		contextTokens: number;
+		turns: number;
+	};
+}
+
 export interface ConsultDetails {
 	agent: string;
 	agentSource: string;
@@ -91,6 +125,13 @@ export interface ConsultDetails {
 	policy: {
 		requestedTools: string[] | null;
 		effectiveTools: string[];
+		cwdBoundary: "current-workspace" | "external";
+		targetTrust: {
+			kind: string;
+			projectTrusted: boolean;
+			sourcePath?: string;
+			warning?: string;
+		};
 		requestedResources: ConsultResourcePolicy;
 		effectiveResources: {
 			policy: ConsultResourcePolicy;
@@ -99,11 +140,13 @@ export interface ConsultDetails {
 			skills: boolean;
 			promptTemplates: boolean;
 		};
+		resourceDowngradeReason?: string;
 		extensions: "disabled";
 		sessionPersistence: "disabled";
 		retainedAgent: false;
 	};
 	child?: Record<string, unknown>;
+	progress?: ConsultProgress;
 	cancelled?: boolean;
 	isError?: boolean;
 	truncated?: boolean;
@@ -143,12 +186,12 @@ export function registerSubagentConsult(
 		cancelAndWaitForChildren("Subagent consultation session shut down"),
 	);
 
-	const baseDescription =
-		"Run one ephemeral subagent synchronously under enforced read-only tool and resource policies and return its answer. The child can use only the effective subset of Pi's built-in read, grep, find, and ls tools. Shell commands, file writes, extension tools, detached lifecycle operations, and persistent agent state are disabled.";
+	const baseDescription = () =>
+		`Run one ephemeral subagent synchronously under enforced read-only tool and resource policies and return its answer. The child can use only the effective subset of Pi's built-in read, grep, find, and ls tools. Shell commands, file writes, extension tools, detached lifecycle operations, and persistent agent state are disabled. Working-directory target policy: ${options.getSettings()?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY}; configured trusted-target resources: ${options.getSettings()?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY}; allowed targets without effective trust inherit no target/project resources. This is not a filesystem sandbox.`;
 	const definition: ToolDefinition<typeof SubagentConsultParams, ConsultDetails> = {
 		name: "subagent_consult",
 		label: "Consult Read-only Subagent",
-		description: baseDescription,
+		description: baseDescription(),
 		promptSnippet: "Consult one constrained read-only subagent and wait for its answer",
 		promptGuidelines: [
 			"Use subagent_consult for bounded reconnaissance, planning, or review whose result is required in the current turn.",
@@ -187,6 +230,12 @@ export function registerSubagentConsult(
 				active.delete(ownedController);
 			}
 		},
+		renderCall(args, theme) {
+			return renderConsultCall(args, theme);
+		},
+		renderResult(result, renderOptions, theme, context) {
+			return renderConsultResult(result, renderOptions, theme, context);
+		},
 	};
 	pi.registerTool<typeof SubagentConsultParams, ConsultDetails>(definition);
 	pi.on("tool_result", (event) => {
@@ -194,7 +243,7 @@ export function registerSubagentConsult(
 		if ((event.details as ConsultDetails | undefined)?.isError) return { isError: true };
 	});
 	return (catalog: string) => {
-		definition.description = catalog ? `${baseDescription}\n\n${catalog}` : baseDescription;
+		definition.description = catalog ? `${baseDescription()}\n\n${catalog}` : baseDescription();
 		pi.registerTool<typeof SubagentConsultParams, ConsultDetails>(definition);
 	};
 }
@@ -294,6 +343,15 @@ async function executeConsult(
 		throw new Error("Project-local subagent definitions require a trusted project");
 	}
 	const settings = options.getSettings();
+	const target = resolveSubagentTarget({
+		workspace: ctx.cwd,
+		requestedCwd: operation.cwd,
+		currentProjectTrusted: ctx.isProjectTrusted(),
+	});
+	assertConsultationTargetAllowed(
+		target,
+		settings?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY,
+	);
 	const discovery = discoverAgents(ctx.cwd, operation.agentScope, settings);
 	const agent = discovery.agents.find((candidate) => candidate.name === operation.agent);
 	if (!agent) {
@@ -302,7 +360,7 @@ async function executeConsult(
 				`Available agents for agentScope "${operation.agentScope}": ${formatAvailableConsultAgents(discovery)}`,
 		);
 	}
-	const setup = resolveConsultSetup(operation, agent, settings, ctx);
+	const setup = resolveConsultSetup(operation, agent, settings, target);
 
 	if (agent.source === "project" && operation.confirmProjectAgents) {
 		if (!ctx.hasUI) {
@@ -323,6 +381,8 @@ async function executeConsult(
 		}
 	}
 	assertCurrentRequest(signal, isCurrent);
+	emitUpdate(consultStartingUpdate(setup.details));
+	assertCurrentRequest(signal, isCurrent);
 	const runChild = options.runChild ?? ((request) => runConsultChild(request, options));
 	const child = runChild({
 		agent: setup.agent,
@@ -376,19 +436,13 @@ function resolveConsultSetup(
 	operation: ReturnType<typeof validateConsultParams>,
 	agent: AgentConfig,
 	settings: SubagentSettings | undefined,
-	ctx: ExtensionContext,
+	target: ResolvedSubagentTarget,
 ) {
-	const cwd = canonicalDirectory(operation.cwd ?? ctx.cwd, "subagent consultation cwd");
-	const workspace = canonicalDirectory(ctx.cwd, "current workspace");
-	const resourcePolicy = settings?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY;
-	if (!isWithin(cwd, workspace) && resourcePolicy !== "none") {
-		throw new Error(
-			`Subagent consultation cwd is outside the current workspace; consult.resources must be "none": ${safeTerminalLine(cwd)}`,
-		);
-	}
+	const requestedResourcePolicy = settings?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY;
+	const resourcePolicy = target.trust.projectTrusted ? requestedResourcePolicy : "none";
 	const effectiveTools = resolveConsultTools(agent.tools);
-	const projectTrusted = ctx.isProjectTrusted();
-	const launchPolicy = resourceLaunchPolicy(resourcePolicy, projectTrusted, workspace);
+	const projectTrusted = target.trust.projectTrusted;
+	const launchPolicy = resourceLaunchPolicy(resourcePolicy, projectTrusted, target.cwd);
 	launchPolicy.tools = effectiveTools;
 	const thinkingLevel = resolveSubagentThinkingLevel([agent], agent.name, operation.thinkingLevel);
 	const timeoutMs = operation.timeoutMs ?? agent.timeoutMs ?? resolveDefaultSubagentTimeoutMs();
@@ -413,7 +467,7 @@ function resolveConsultSetup(
 		agent: boundedPrivateText(agent.name, 256),
 		agentSource: agent.source,
 		agentScope: operation.agentScope,
-		cwd: safeDisplayPath(cwd, workspace),
+		cwd: safeDisplayPath(target.cwd, target.workspace),
 		model: agent.model ? boundedPrivateText(agent.model, 256) : undefined,
 		thinkingLevel,
 		timeoutMs,
@@ -423,8 +477,20 @@ function resolveConsultSetup(
 					? null
 					: agent.tools.slice(0, 100).map((tool) => boundedPrivateText(tool, 256)),
 			effectiveTools,
-			requestedResources: resourcePolicy,
+			cwdBoundary: target.boundary,
+			targetTrust: {
+				kind: target.trust.kind,
+				projectTrusted,
+				sourcePath: target.trust.sourcePath
+					? safeDisplayPath(target.trust.sourcePath, target.workspace)
+					: undefined,
+				warning: target.trust.warning,
+			},
+			requestedResources: requestedResourcePolicy,
 			effectiveResources,
+			...(resourcePolicy !== requestedResourcePolicy
+				? { resourceDowngradeReason: `Target trust is ${target.trust.kind}` }
+				: {}),
 			extensions: "disabled",
 			sessionPersistence: "disabled",
 			retainedAgent: false,
@@ -432,7 +498,7 @@ function resolveConsultSetup(
 	};
 	return {
 		agent: childAgent,
-		cwd,
+		cwd: target.cwd,
 		resourcePolicy,
 		effectiveTools,
 		thinkingLevel,
@@ -471,6 +537,21 @@ async function runConsultChild(
 	);
 }
 
+function consultStartingUpdate(details: ConsultDetails): AgentToolResult<ConsultDetails> {
+	return {
+		content: [{ type: "text", text: "Read-only subagent consultation starting." }],
+		details: {
+			...details,
+			progress: {
+				phase: "starting",
+				recentActivity: [],
+				recentActivityTotal: 0,
+				usage: emptyProgressUsage(),
+			},
+		},
+	};
+}
+
 function consultUpdate(
 	result: SingleResult,
 	details: ConsultDetails,
@@ -478,7 +559,69 @@ function consultUpdate(
 	const output = boundText(getResultFinalOutput(result) || "(running...)");
 	return {
 		content: [{ type: "text", text: output.text }],
-		details: { ...details, child: projectChildResult(result) },
+		details: {
+			...details,
+			child: projectChildResult(result),
+			progress: projectConsultProgress(result),
+		},
+	};
+}
+
+const CONSULT_ACTIVITY_ARGUMENTS: Record<"read" | "grep" | "find" | "ls", readonly string[]> = {
+	read: ["path", "file_path", "offset", "limit"],
+	grep: ["pattern", "path", "glob", "limit"],
+	find: ["pattern", "path", "limit"],
+	ls: ["path", "limit"],
+};
+
+function projectConsultProgress(result: SingleResult): ConsultProgress {
+	const recentActivity: ConsultProgressActivity[] = [];
+	for (const item of result.recentActivity ?? []) {
+		if (item.type === "text") {
+			const text = boundedPrivateText(item.text, 1024).trim();
+			if (text) recentActivity.push({ type: "text", text });
+			continue;
+		}
+		if (!Object.hasOwn(CONSULT_ACTIVITY_ARGUMENTS, item.name)) continue;
+		const name = item.name as keyof typeof CONSULT_ACTIVITY_ARGUMENTS;
+		const args: Record<string, string | number | boolean> = {};
+		for (const key of CONSULT_ACTIVITY_ARGUMENTS[name]) {
+			const value = item.args[key];
+			if (typeof value === "string") args[key] = safeTerminalLine(value, 512);
+			else if (typeof value === "number" && Number.isFinite(value)) args[key] = value;
+			else if (typeof value === "boolean") args[key] = value;
+		}
+		recentActivity.push({ type: "toolCall", name, args });
+	}
+	return {
+		phase: "running",
+		recentActivity,
+		recentActivityTotal: Math.max(recentActivity.length, result.recentActivityTotal ?? 0),
+		actualProvider: result.actualProvider
+			? boundedPrivateText(result.actualProvider, 256)
+			: undefined,
+		actualModel: result.actualModel ? boundedPrivateText(result.actualModel, 256) : undefined,
+		usage: {
+			input: result.usage.input,
+			output: result.usage.output,
+			cacheRead: result.usage.cacheRead,
+			cacheWrite: result.usage.cacheWrite,
+			cost: result.usage.cost,
+			contextTokens: result.usage.contextTokens,
+			turns: result.usage.turns,
+		},
+	};
+}
+
+function emptyProgressUsage(): ConsultProgress["usage"] {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		cost: 0,
+		contextTokens: 0,
+		turns: 0,
 	};
 }
 
@@ -623,22 +766,6 @@ function usageFromResult(result: SingleResult): Usage {
 	};
 }
 
-function canonicalDirectory(value: string, label: string): string {
-	try {
-		const resolved = fs.realpathSync(value);
-		if (!fs.statSync(resolved).isDirectory()) throw new Error("not a directory");
-		return resolved;
-	} catch (error) {
-		const reason = error instanceof Error ? error.message : String(error);
-		throw new Error(`Invalid ${label}: ${safeTerminalLine(value)} (${safeTerminalLine(reason)})`);
-	}
-}
-
-function isWithin(candidate: string, root: string): boolean {
-	const relative = path.relative(root, candidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
 function assertCurrentRequest(signal: AbortSignal, isCurrent: () => boolean): void {
 	if (signal.aborted || !isCurrent()) throw abortError("Subagent consultation owner was replaced");
 }