@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/completion-delivery.ts

@@ -0,0 +1,257 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CompletionDelivery } from "./agents.js";
+import { redactPrivateText } from "./context.js";
+import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
+import type { AgentTurnCompletion, ManagedAgent } from "./registry.js";
+import { safeTerminalText } from "./safe-text.js";
+import { PI_SUBAGENTS_RPC_PROTOCOL } from "./transport-types.js";
+
+const MAX_TOOL_MESSAGE_BYTES = 2 * 1024;
+const MAX_COMPLETION_ERROR_BYTES = 512;
+const MAX_COMPLETIONS_PER_MESSAGE = 16;
+const COMPLETION_BATCH_DELAY_MS = 10;
+
+interface CompletionMetadata {
+	protocol: typeof PI_SUBAGENTS_RPC_PROTOCOL;
+	agentId: string;
+	agent: string;
+	state: string;
+	transport?: string;
+	structuredResult?: ManagedAgent["structuredResult"];
+	outcome?: ManagedAgent["outcome"];
+	capabilityGrant?: ManagedAgent["capabilityGrant"];
+}
+
+interface CompletionMessage {
+	customType: "pi-subagent-completion";
+	content: string;
+	display: true;
+	details:
+		| CompletionMetadata
+		| {
+				completionCount: number;
+				completions: CompletionMetadata[];
+		  };
+}
+
+type CompletionContext = Pick<ExtensionContext, "hasPendingMessages" | "isIdle">;
+type CompletionPi = Pick<ExtensionAPI, "sendMessage">;
+
+export interface CompletionDeliveryBrokerOptions {
+	onDeliveryError?: (error: unknown) => void;
+	onDelivered?: (completions: readonly AgentTurnCompletion[], deliveredAt: number) => void;
+	now?: () => number;
+}
+
+/** Owns bounded completion batching and at most one idle-root wake for one parent session. */
+export class CompletionDeliveryBroker {
+	private pending: AgentTurnCompletion[] = [];
+	private flushTimer?: NodeJS.Timeout;
+	private wakeInFlight = false;
+	private closed = false;
+
+	constructor(
+		private readonly pi: CompletionPi,
+		private readonly ctx: CompletionContext,
+		private delivery: CompletionDelivery,
+		private readonly options: CompletionDeliveryBrokerOptions = {},
+	) {}
+
+	enqueue(completion: AgentTurnCompletion): void {
+		if (this.closed) return;
+		this.pending.push(completion);
+		this.scheduleFlush();
+	}
+
+	setDelivery(value: CompletionDelivery): void {
+		this.delivery = value;
+		this.scheduleFlush();
+	}
+
+	onParentTurnStart(): void {
+		this.wakeInFlight = false;
+		this.scheduleFlush();
+	}
+
+	onParentSettled(): void {
+		this.wakeInFlight = false;
+		this.scheduleFlush();
+	}
+
+	flush(): void {
+		if (this.closed || this.pending.length === 0) return;
+		if (this.flushTimer) clearTimeout(this.flushTimer);
+		this.flushTimer = undefined;
+		if (this.delivery === "auto-resume" && !this.isRootIdle()) return;
+
+		const completions = this.pending.splice(0);
+		const batches = chunkCompletions(completions);
+		let canWake = this.shouldWakeRoot();
+		for (let index = 0; index < batches.length; index++) {
+			const triggerTurn = canWake && index === batches.length - 1;
+			const message = buildCompletionMessage(batches[index]);
+			if (triggerTurn) this.wakeInFlight = true;
+			try {
+				this.pi.sendMessage(message, { deliverAs: "steer", triggerTurn });
+				this.notifyDelivered(batches[index]);
+			} catch (primaryError) {
+				if (triggerTurn) this.wakeInFlight = false;
+				canWake = false;
+				try {
+					this.pi.sendMessage(message, { deliverAs: "nextTurn", triggerTurn: false });
+					this.notifyDelivered(batches[index]);
+				} catch (fallbackError) {
+					this.pending = [...batches.slice(index).flat(), ...this.pending];
+					try {
+						this.options.onDeliveryError?.(
+							new AggregateError(
+								[primaryError, fallbackError],
+								"Detached subagent completion delivery failed",
+							),
+						);
+					} catch {
+						// Delivery retention must survive a failing observer.
+					}
+					return;
+				}
+			}
+		}
+	}
+
+	close(): void {
+		this.closed = true;
+		if (this.flushTimer) clearTimeout(this.flushTimer);
+		this.flushTimer = undefined;
+		this.pending = [];
+	}
+
+	private scheduleFlush(): void {
+		if (this.closed || this.pending.length === 0 || this.flushTimer) return;
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = undefined;
+			this.flush();
+		}, COMPLETION_BATCH_DELAY_MS);
+	}
+
+	private notifyDelivered(completions: readonly AgentTurnCompletion[]): void {
+		try {
+			this.options.onDelivered?.(completions, (this.options.now ?? Date.now)());
+		} catch {
+			// Delivery already succeeded, so observer failures cannot requeue it.
+		}
+	}
+
+	private isRootIdle(): boolean {
+		try {
+			return this.ctx.isIdle();
+		} catch {
+			return false;
+		}
+	}
+
+	private shouldWakeRoot(): boolean {
+		if (this.delivery !== "auto-resume" || this.wakeInFlight) return false;
+		try {
+			return !this.ctx.hasPendingMessages();
+		} catch {
+			return false;
+		}
+	}
+}
+
+function chunkCompletions(completions: AgentTurnCompletion[]): AgentTurnCompletion[][] {
+	const batches: AgentTurnCompletion[][] = [];
+	for (let index = 0; index < completions.length; index += MAX_COMPLETIONS_PER_MESSAGE) {
+		batches.push(completions.slice(index, index + MAX_COMPLETIONS_PER_MESSAGE));
+	}
+	return batches;
+}
+
+function buildCompletionMessage(completions: AgentTurnCompletion[]): CompletionMessage {
+	if (completions.length === 1) {
+		const completion = completions[0];
+		return {
+			customType: "pi-subagent-completion",
+			content: buildDetachedCompletionMessage(completion),
+			display: true,
+			details: completionMetadata(completion),
+		};
+	}
+	const content = truncateUtf8(
+		[
+			"Message Type: SUBAGENT_COMPLETION_BATCH",
+			`Protocol: ${PI_SUBAGENTS_RPC_PROTOCOL}`,
+			`Completion Count: ${completions.length}`,
+			...completions.flatMap((completion, index) => [
+				"",
+				`--- Completion ${index + 1} of ${completions.length} ---`,
+				buildDetachedCompletionMessage(completion),
+			]),
+		].join("\n"),
+		DEFAULT_MAX_CONTEXT_BYTES,
+	).text;
+	return {
+		customType: "pi-subagent-completion",
+		content,
+		display: true,
+		details: {
+			completionCount: completions.length,
+			completions: completions.map(completionMetadata),
+		},
+	};
+}
+
+function completionMetadata(completion: AgentTurnCompletion): CompletionMetadata {
+	return {
+		protocol: PI_SUBAGENTS_RPC_PROTOCOL,
+		agentId: completion.agent.id,
+		agent: completion.agent.agent,
+		state: completion.agent.state,
+		...(completion.agent.telemetry?.transport
+			? { transport: completion.agent.telemetry.transport }
+			: {}),
+		...(completion.agent.structuredResult
+			? { structuredResult: completion.agent.structuredResult }
+			: {}),
+		...(completion.agent.outcome ? { outcome: completion.agent.outcome } : {}),
+		...(completion.agent.capabilityGrant
+			? { capabilityGrant: completion.agent.capabilityGrant }
+			: {}),
+	};
+}
+
+export function buildDetachedCompletionMessage(completion: AgentTurnCompletion): string {
+	const task = sanitizeCompletionLine(completion.task, 256) || "(unknown task)";
+	const agentName = sanitizeCompletionLine(completion.agent.agent, 128) || "(unknown agent)";
+	const output = safeTerminalText(redactPrivateText(completion.output));
+	const error = completion.error
+		? truncateUtf8(
+				safeTerminalText(redactPrivateText(completion.error)),
+				MAX_COMPLETION_ERROR_BYTES,
+			).text
+		: "";
+	return truncateUtf8(
+		[
+			"Message Type: SUBAGENT_COMPLETION",
+			`Protocol: ${PI_SUBAGENTS_RPC_PROTOCOL}`,
+			`Agent ID: ${completion.agent.id}`,
+			`Agent: ${agentName}`,
+			`Task: ${task}`,
+			`State: ${completion.agent.state}`,
+			...(error.trim() ? ["Error:", error] : []),
+			"Payload:",
+			output.trim() ? output : "(no output)",
+		].join("\n"),
+		MAX_TOOL_MESSAGE_BYTES,
+	).text;
+}
+
+function sanitizeCompletionLine(value: string, maxBytes: number): string {
+	return (
+		truncateUtf8(redactPrivateText(value), maxBytes)
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: Strip untrusted terminal controls.
+			.text.replace(/[\u0000-\u001f\u007f]+/g, " ")
+			.replace(/\s+/g, " ")
+			.trim()
+	);
+}

package/src/config-status.ts

@@ -0,0 +1,221 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type {
+	CompletionDelivery,
+	ConsultationCwdPolicy,
+	ConsultResourcePolicy,
+	DelegationCwdPolicy,
+} from "./agents.js";
+import type { SubagentSettingsRuntime } from "./config-ui.js";
+import { safeTerminalLine as safeTerminalText } from "./safe-text.js";
+import {
+	type DelegationWorkflow,
+	inspectBlockingParallelLimitSettings,
+	inspectCompletionDeliverySettings,
+	inspectConsultResourceSettings,
+	inspectCwdPolicySettings,
+	inspectDelegationWorkflowSettings,
+	inspectStatefulLimitSettings,
+	inspectStatefulTransportSettings,
+} from "./settings.js";
+import type { StatefulSubagentRuntimeStatus } from "./stateful.js";
+import {
+	formatConfiguredDetachedLimitDivergence,
+	formatConfiguredDetachedLimits,
+	formatDetachedLimitSummary,
+} from "./stateful-limit-ui.js";
+import { STATEFUL_LIMIT_DEFINITIONS } from "./stateful-limits.js";
+import { workflowLabel } from "./workflow-ui.js";
+
+export function showSubagentStatus(
+	ctx: ExtensionCommandContext,
+	runtime: SubagentSettingsRuntime,
+): void {
+	if (ctx.mode !== "tui" && !ctx.hasUI) return;
+	const snapshot = inspectCompletionDeliverySettings();
+	ctx.ui.notify(
+		formatStatus(runtime.getRuntimeStatus(), snapshot, runtime),
+		snapshot.error ? "warning" : "info",
+	);
+}
+
+export function showSubagentHelp(
+	ctx: ExtensionCommandContext,
+	runtime: SubagentSettingsRuntime,
+): void {
+	if (ctx.mode !== "tui" && !ctx.hasUI) return;
+	ctx.ui.notify(helpLines(runtime).join("\n"), "info");
+}
+
+export function statusLines(runtime: SubagentSettingsRuntime): string[] {
+	const snapshot = inspectCompletionDeliverySettings();
+	return formatStatus(runtime.getRuntimeStatus(), snapshot, runtime).split("\n");
+}
+
+export function helpLines(runtime: SubagentSettingsRuntime): string[] {
+	const snapshot = inspectCompletionDeliverySettings();
+	const cwdPolicy = inspectCwdPolicySettings();
+	const parallelLimit = inspectBlockingParallelLimitSettings();
+	const detachedLimits = inspectStatefulLimitSettings();
+	const transport = inspectStatefulTransportSettings();
+	return [
+		"/subagents — choose delegation workflow, manage current agents, and configure agent tools",
+		"/subagents settings — configure target locations, trusted resources, and async completion",
+		"/subagents status — show current-session and user-setting values",
+		"/subagents help — show this help",
+		"Target policies control startup directories and resources, not filesystem access or sandboxing.",
+		"Manage saved folder trust with Pi /trust and restart Pi after changing it.",
+		`Runtime consultation target: ${consultationCwdLabel(runtime.getConsultationCwdPolicy())}`,
+		`Configured consultation target: ${consultationCwdLabel(cwdPolicy.consultation.value)} (${cwdPolicy.consultation.source})`,
+		`Runtime delegation target: ${delegationCwdLabel(runtime.getDelegationCwdPolicy())}`,
+		`Configured delegation target: ${delegationCwdLabel(cwdPolicy.delegation.value)} (${cwdPolicy.delegation.source})`,
+		`Maximum parallel workers: ${runtime.getMaxParallelTasks()} per blocking call`,
+		`Configured parallel limit: ${parallelLimit.value} (${parallelLimit.source})`,
+		`Detached limits: ${formatDetachedLimitSummary(runtime.getRuntimeStatus())}`,
+		`Configured transport: ${transport.value} (${transport.source})`,
+		...(detachedLimits.values
+			? [`Configured detached limits: ${formatConfiguredDetachedLimits(detachedLimits.values)}`]
+			: ["Configured detached limits: unavailable; repair user settings"]),
+		"Detached limits and transport apply after /reload; clear retained agents first if their work must not be interrupted.",
+		`User settings: ${safeTerminalText(snapshot.path)}`,
+	];
+}
+
+export function formatManagerSummary(
+	runtime: SubagentSettingsRuntime,
+	status: StatefulSubagentRuntimeStatus,
+	configured: ReturnType<typeof inspectDelegationWorkflowSettings>,
+): string {
+	const current = currentWorkflow(runtime, status);
+	const cwdPolicy = inspectCwdPolicySettings();
+	const consult = inspectConsultResourceSettings();
+	const detachedLimits = inspectStatefulLimitSettings();
+	const transport = inspectStatefulTransportSettings();
+	const detachedDivergence = detachedLimits.values
+		? formatConfiguredDetachedLimitDivergence(status, detachedLimits.values)
+		: undefined;
+	return [
+		`Delegation: ${workflowLabel(current)}`,
+		`Completion: ${completionLabel(status.completionDelivery)}`,
+		`Consult target: ${consultationCwdLabel(runtime.getConsultationCwdPolicy())}`,
+		`Delegation target: ${delegationCwdLabel(runtime.getDelegationCwdPolicy())}`,
+		`Consult resources: ${consultResourceLabel(runtime.getConsultResourcePolicy())}`,
+		`Parallel workers: max ${runtime.getMaxParallelTasks()} per blocking call`,
+		`Detached limits: ${formatDetachedLimitSummary(status)}`,
+		`Transport: ${status.transport}`,
+		`Configured transport: ${transport.value} · ${transport.source}`,
+		`Configured consult target: ${consultationCwdLabel(cwdPolicy.consultation.value)} · ${cwdPolicy.consultation.source}`,
+		`Configured delegation target: ${delegationCwdLabel(cwdPolicy.delegation.value)} · ${cwdPolicy.delegation.source}`,
+		`Configured consult resources: ${consultResourceLabel(consult.value)} · ${consult.source}`,
+		`Settings: ${safeTerminalText(cwdPolicy.path)}`,
+		`Agents: ${status.activeAgents} active · ${status.retainedAgents} retained`,
+		...(detachedDivergence ? [detachedDivergence] : []),
+		...(configured.value !== current
+			? [`Configured after reload: ${workflowLabel(configured.value)}`]
+			: []),
+		...(configured.error || detachedLimits.error
+			? ["Settings need repair; open Advanced settings for details."]
+			: []),
+	].join("\n");
+}
+
+function formatStatus(
+	status: StatefulSubagentRuntimeStatus,
+	snapshot: ReturnType<typeof inspectCompletionDeliverySettings>,
+	runtime?: SubagentSettingsRuntime,
+): string {
+	const configuredWorkflow = inspectDelegationWorkflowSettings();
+	const consult = inspectConsultResourceSettings();
+	const cwdPolicy = inspectCwdPolicySettings();
+	const parallelLimit = inspectBlockingParallelLimitSettings();
+	const detachedLimits = inspectStatefulLimitSettings();
+	const transport = inspectStatefulTransportSettings();
+	const current = runtime ? currentWorkflow(runtime, status) : configuredWorkflow.value;
+	return [
+		"Current session",
+		`  Delegation: ${workflowLabel(current)}`,
+		`  Async runtime: ${status.initialized ? "initialized" : status.enabled ? "not initialized" : "disabled"}`,
+		`  Transport: ${status.transport}`,
+		`  Configured transport: ${transport.value} (${transport.source})`,
+		`  Completion: ${completionLabel(status.completionDelivery)}`,
+		`  Consultation target: ${consultationCwdLabel(runtime?.getConsultationCwdPolicy() ?? cwdPolicy.consultation.value)}`,
+		`  Delegation target: ${delegationCwdLabel(runtime?.getDelegationCwdPolicy() ?? cwdPolicy.delegation.value)}`,
+		`  Consultation resources: ${consultResourceLabel(runtime?.getConsultResourcePolicy() ?? consult.value)}`,
+		`  Maximum parallel workers: ${runtime?.getMaxParallelTasks() ?? parallelLimit.value} per blocking call`,
+		`  Detached limits: ${formatDetachedLimitSummary(status)}`,
+		`  Agents: ${status.activeAgents} active, ${status.retainedAgents} retained`,
+		"User settings",
+		`  Delegation source: ${configuredWorkflow.source}`,
+		`  Configured delegation: ${workflowLabel(configuredWorkflow.value)}`,
+		`  Completion source: ${snapshot.source}`,
+		`  Configured completion: ${completionLabel(snapshot.value)}`,
+		`  Configured parallel limit: ${parallelLimit.value}`,
+		`  Parallel limit source: ${parallelLimit.source}`,
+		...(detachedLimits.values
+			? STATEFUL_LIMIT_DEFINITIONS.map((definition) => {
+					const configured = detachedLimits.values?.[definition.field];
+					return `  Configured ${definition.label.toLowerCase()}: ${configured?.value} (${configured?.source})`;
+				})
+			: ["  Configured detached limits: unavailable"]),
+		`  Configured consultation target: ${consultationCwdLabel(cwdPolicy.consultation.value)}`,
+		`  Consultation target source: ${cwdPolicy.consultation.source}`,
+		`  Configured delegation target: ${delegationCwdLabel(cwdPolicy.delegation.value)}`,
+		`  Delegation target source: ${cwdPolicy.delegation.source}`,
+		`  Configured consultation resources: ${consultResourceLabel(consult.value)}`,
+		`  Consultation resource source: ${consult.source}`,
+		`  Path: ${safeTerminalText(snapshot.path)}`,
+		configuredWorkflow.error ||
+		snapshot.error ||
+		cwdPolicy.error ||
+		parallelLimit.error ||
+		detachedLimits.error ||
+		transport.error
+			? `  Warning: ${safeTerminalText(configuredWorkflow.error ?? snapshot.error ?? cwdPolicy.error ?? parallelLimit.error ?? detachedLimits.error ?? transport.error ?? "invalid settings")}`
+			: "  Warning: none",
+		configuredWorkflow.value !== current
+			? "Configured delegation differs from this session. Run /reload to apply it."
+			: "Manual file changes require /reload.",
+	].join("\n");
+}
+
+export function currentWorkflow(
+	runtime: SubagentSettingsRuntime,
+	status: StatefulSubagentRuntimeStatus,
+): DelegationWorkflow {
+	const blocking = runtime.getBlockingEnabled();
+	if (blocking && status.enabled) return "all";
+	if (status.enabled) return "async-only";
+	if (blocking) return "blocking-only";
+	return "disabled";
+}
+
+export function completionLabel(value: CompletionDelivery): string {
+	return value === "auto-resume" ? "Resume automatically when finished" : "Wait until my next turn";
+}
+
+export function consultationCwdLabel(value: ConsultationCwdPolicy): string {
+	return value === "current-workspace"
+		? "Current workspace only"
+		: "Anywhere · untrusted targets inherit nothing";
+}
+
+export function delegationCwdLabel(value: DelegationCwdPolicy): string {
+	switch (value) {
+		case "trusted-targets":
+			return "Current or saved-trusted folders";
+		case "current-workspace":
+			return "Current workspace only";
+		case "anywhere":
+			return "Anywhere · normal Pi permissions";
+	}
+}
+
+export function consultResourceLabel(value: ConsultResourcePolicy): string {
+	switch (value) {
+		case "project-context":
+			return "Project context only";
+		case "none":
+			return "No inherited resources";
+		case "all":
+			return "All trusted resources";
+	}
+}