@narumitw/pi-subagents 0.53.0 → 1.0.0

package/src/auto-transport.ts

@@ -1,4 +1,5 @@
-import { discoverAgents, type SubagentSettings } from "./agents.js";
+import { discoverAgents } from "./agents/discovery.js";
+import type { SubagentSettings } from "./agents/types.js";
 import type { ManagedAgent, TurnOutcome } from "./registry.js";
 import { isWriteCapable } from "./stateful-safety.js";
 import type { SubagentTransport } from "./transport.js";

package/src/automation.ts

@@ -9,7 +9,9 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
-import { discoverAgents, getBuiltInAgent, type SubagentSettings } from "./agents.js";
+import { getBuiltInAgent } from "./agents/built-ins.js";
+import { discoverAgents } from "./agents/discovery.js";
+import type { SubagentSettings } from "./agents/types.js";
 import {
 	AutomationRequestSchema,
 	parseAutomationRequest,
@@ -39,7 +41,10 @@ import {
 	type SubagentDetails,
 } from "./runner.js";
 import { boundedPrivateText } from "./safe-text.js";
-import { DEFAULT_DELEGATION_CWD_POLICY, resolveBlockingMaxParallelTasks } from "./settings.js";
+import {
+	DEFAULT_DELEGATION_CWD_POLICY,
+	resolveBlockingMaxParallelTasks,
+} from "./settings/inspection.js";
 import {
 	type CompiledWorkflowPlan,
 	compileWorkflowPlan,

package/src/capability-router.ts

@@ -1,4 +1,4 @@
-import { type AgentConfig, resolveAgentToolNames } from "./agents.js";
+import { type AgentConfig, resolveAgentToolNames } from "./agents/types.js";
 import type { CapabilityHint } from "./capabilities.js";
 
 export interface CapabilityRouteRequest {

package/src/completion-delivery.ts

@@ -1,18 +1,20 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { CompletionDelivery } from "./agents.js";
+import type { CompletionDelivery } from "./agents/types.js";
 import { redactPrivateText } from "./context.js";
-import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
+import { DEFAULT_MAX_CONTEXT_BYTES, MAX_TOOL_MESSAGE_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;
+	completionId: string;
+	runId: string;
+	generation: number;
 	agentId: string;
 	agent: string;
 	state: string;
@@ -39,13 +41,15 @@ type CompletionPi = Pick<ExtensionAPI, "sendMessage">;
 
 export interface CompletionDeliveryBrokerOptions {
 	onDeliveryError?: (error: unknown) => void;
-	onDelivered?: (completions: readonly AgentTurnCompletion[], deliveredAt: number) => void;
+	onAcknowledged?: (completions: readonly AgentTurnCompletion[], acknowledgedAt: 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 readonly knownCompletionIds = new Set<string>();
+	private awaitingParentAck: AgentTurnCompletion[] = [];
 	private flushTimer?: NodeJS.Timeout;
 	private wakeInFlight = false;
 	private closed = false;
@@ -58,7 +62,8 @@ export class CompletionDeliveryBroker {
 	) {}
 
 	enqueue(completion: AgentTurnCompletion): void {
-		if (this.closed) return;
+		if (this.closed || this.knownCompletionIds.has(completion.completionId)) return;
+		this.knownCompletionIds.add(completion.completionId);
 		this.pending.push(completion);
 		this.scheduleFlush();
 	}
@@ -73,6 +78,14 @@ export class CompletionDeliveryBroker {
 		this.scheduleFlush();
 	}
 
+	onParentContext(messages: readonly unknown[]): void {
+		this.acknowledgeVisible(completionIdsFromContext(messages));
+		if (this.awaitingParentAck.length > 0) {
+			this.pending = [...this.awaitingParentAck.splice(0), ...this.pending];
+		}
+		this.scheduleFlush();
+	}
+
 	onParentSettled(): void {
 		this.wakeInFlight = false;
 		this.scheduleFlush();
@@ -89,18 +102,21 @@ export class CompletionDeliveryBroker {
 		let canWake = this.shouldWakeRoot();
 		for (let index = 0; index < batches.length; index++) {
 			const triggerTurn = canWake && index === batches.length - 1;
-			const message = buildCompletionMessage(batches[index]);
+			const batch = batches[index];
+			const message = buildCompletionMessage(batch);
 			if (triggerTurn) this.wakeInFlight = true;
+			this.awaitingParentAck.push(...batch);
 			try {
 				this.pi.sendMessage(message, { deliverAs: "steer", triggerTurn });
-				this.notifyDelivered(batches[index]);
 			} catch (primaryError) {
+				this.removeAwaiting(batch);
 				if (triggerTurn) this.wakeInFlight = false;
 				canWake = false;
+				this.awaitingParentAck.push(...batch);
 				try {
 					this.pi.sendMessage(message, { deliverAs: "nextTurn", triggerTurn: false });
-					this.notifyDelivered(batches[index]);
 				} catch (fallbackError) {
+					this.removeAwaiting(batch);
 					this.pending = [...batches.slice(index).flat(), ...this.pending];
 					try {
 						this.options.onDeliveryError?.(
@@ -123,6 +139,8 @@ export class CompletionDeliveryBroker {
 		if (this.flushTimer) clearTimeout(this.flushTimer);
 		this.flushTimer = undefined;
 		this.pending = [];
+		this.awaitingParentAck = [];
+		this.knownCompletionIds.clear();
 	}
 
 	private scheduleFlush(): void {
@@ -133,14 +151,34 @@ export class CompletionDeliveryBroker {
 		}, COMPLETION_BATCH_DELAY_MS);
 	}
 
-	private notifyDelivered(completions: readonly AgentTurnCompletion[]): void {
+	private acknowledgeVisible(visibleIds: ReadonlySet<string>): void {
+		if (visibleIds.size === 0) return;
+		const completions = [...this.awaitingParentAck, ...this.pending].filter((completion) =>
+			visibleIds.has(completion.completionId),
+		);
+		if (completions.length === 0) return;
+		const acknowledgedIds = new Set(completions.map((completion) => completion.completionId));
+		this.awaitingParentAck = this.awaitingParentAck.filter(
+			(completion) => !acknowledgedIds.has(completion.completionId),
+		);
+		this.pending = this.pending.filter(
+			(completion) => !acknowledgedIds.has(completion.completionId),
+		);
+		for (const completion of completions) this.knownCompletionIds.delete(completion.completionId);
 		try {
-			this.options.onDelivered?.(completions, (this.options.now ?? Date.now)());
+			this.options.onAcknowledged?.(completions, (this.options.now ?? Date.now)());
 		} catch {
-			// Delivery already succeeded, so observer failures cannot requeue it.
+			// Context assembly already observed the message, so observer failures cannot retract it.
 		}
 	}
 
+	private removeAwaiting(completions: readonly AgentTurnCompletion[]): void {
+		const removed = new Set(completions.map((completion) => completion.completionId));
+		this.awaitingParentAck = this.awaitingParentAck.filter(
+			(completion) => !removed.has(completion.completionId),
+		);
+	}
+
 	private isRootIdle(): boolean {
 		try {
 			return this.ctx.isIdle();
@@ -159,6 +197,33 @@ export class CompletionDeliveryBroker {
 	}
 }
 
+function completionIdsFromContext(messages: readonly unknown[]): Set<string> {
+	const ids = new Set<string>();
+	for (const message of messages) {
+		if (!message || typeof message !== "object" || Array.isArray(message)) continue;
+		const record = message as Record<string, unknown>;
+		if (record.role !== "custom" || record.customType !== "pi-subagent-completion") continue;
+		const details = record.details;
+		if (!details || typeof details !== "object" || Array.isArray(details)) continue;
+		const metadata = details as Record<string, unknown>;
+		if (
+			metadata.protocol === PI_SUBAGENTS_RPC_PROTOCOL &&
+			typeof metadata.completionId === "string"
+		) {
+			ids.add(metadata.completionId);
+		}
+		if (!Array.isArray(metadata.completions)) continue;
+		for (const completion of metadata.completions) {
+			if (!completion || typeof completion !== "object" || Array.isArray(completion)) continue;
+			const item = completion as Record<string, unknown>;
+			if (item.protocol === PI_SUBAGENTS_RPC_PROTOCOL && typeof item.completionId === "string") {
+				ids.add(item.completionId);
+			}
+		}
+	}
+	return ids;
+}
+
 function chunkCompletions(completions: AgentTurnCompletion[]): AgentTurnCompletion[][] {
 	const batches: AgentTurnCompletion[][] = [];
 	for (let index = 0; index < completions.length; index += MAX_COMPLETIONS_PER_MESSAGE) {
@@ -204,6 +269,9 @@ function buildCompletionMessage(completions: AgentTurnCompletion[]): CompletionM
 function completionMetadata(completion: AgentTurnCompletion): CompletionMetadata {
 	return {
 		protocol: PI_SUBAGENTS_RPC_PROTOCOL,
+		completionId: completion.completionId,
+		runId: completion.runId,
+		generation: completion.generation,
 		agentId: completion.agent.id,
 		agent: completion.agent.agent,
 		state: completion.agent.state,
@@ -234,6 +302,9 @@ export function buildDetachedCompletionMessage(completion: AgentTurnCompletion):
 		[
 			"Message Type: SUBAGENT_COMPLETION",
 			`Protocol: ${PI_SUBAGENTS_RPC_PROTOCOL}`,
+			`Completion ID: ${completion.completionId}`,
+			`Run ID: ${completion.runId}`,
+			`Generation: ${completion.generation}`,
 			`Agent ID: ${completion.agent.id}`,
 			`Agent: ${agentName}`,
 			`Task: ${task}`,

package/src/config-status.ts

@@ -4,11 +4,11 @@ import type {
 	ConsultationCwdPolicy,
 	ConsultResourcePolicy,
 	DelegationCwdPolicy,
-} from "./agents.js";
+} from "./agents/types.js";
 import type { SubagentSettingsRuntime } from "./config-ui.js";
 import { safeTerminalLine as safeTerminalText } from "./safe-text.js";
+import type { DelegationWorkflow } from "./settings/inspection.js";
 import {
-	type DelegationWorkflow,
 	inspectBlockingParallelLimitSettings,
 	inspectCompletionDeliverySettings,
 	inspectConsultResourceSettings,

package/src/config-ui.ts

@@ -1,11 +1,11 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import {
-	type CompletionDelivery,
-	type ConsultationCwdPolicy,
-	type ConsultResourcePolicy,
-	type DelegationCwdPolicy,
-	discoverAgents,
-} from "./agents.js";
+import { discoverAgents } from "./agents/discovery.js";
+import type {
+	CompletionDelivery,
+	ConsultationCwdPolicy,
+	ConsultResourcePolicy,
+	DelegationCwdPolicy,
+} from "./agents/types.js";
 import {
 	completionLabel,
 	consultationCwdLabel,
@@ -38,8 +38,8 @@ import {
 } from "./parallel-limit-ui.js";
 import type { ManagedAgent } from "./registry.js";
 import { safeTerminalLine as safeTerminalText } from "./safe-text.js";
+import type { DelegationWorkflow } from "./settings/inspection.js";
 import {
-	type DelegationWorkflow,
 	hasOwn,
 	inspectBlockingParallelLimitSettings,
 	inspectCompletionDeliverySettings,

package/src/consult-resources.ts

@@ -1,4 +1,4 @@
-import type { ConsultResourcePolicy } from "./agents.js";
+import type { ConsultResourcePolicy } from "./agents/types.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
 import type { ChildLaunchPolicy } from "./runner.js";

package/src/consult.ts

@@ -8,17 +8,16 @@ import {
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
+import { DEFAULT_AGENT_CATALOG_MAX_ITEMS } from "./agents/catalog.js";
+import { type AgentDiscoveryResult, discoverAgents } from "./agents/discovery.js";
 import {
 	type AgentConfig,
-	type AgentDiscoveryResult,
 	type AgentScope,
 	type ConsultResourcePolicy,
-	DEFAULT_AGENT_CATALOG_MAX_ITEMS,
-	discoverAgents,
 	isThinkingLevel,
 	type SubagentSettings,
 	THINKING_LEVELS,
-} from "./agents.js";
+} from "./agents/types.js";
 import { resolveConsultTools } from "./consult-policy.js";
 import { renderConsultCall, renderConsultResult } from "./consult-render.js";
 import { resolveConsultResourceLaunchPolicy } from "./consult-resources.js";
@@ -27,7 +26,10 @@ import {
 	type ResolvedSubagentTarget,
 	resolveSubagentTarget,
 } from "./cwd-policy.js";
-import { assertSubagentDepthAllowed, resolveDefaultSubagentTimeoutMs } from "./execution.js";
+import {
+	assertSubagentDepthAllowed,
+	resolveDefaultSubagentTimeoutMs,
+} from "./execution/runtime-policy.js";
 import {
 	DEFAULT_MAX_CONTEXT_BYTES,
 	DEFAULT_MAX_STDERR_BYTES,
@@ -45,8 +47,8 @@ import { boundedPrivateText, boundText, safeDisplayPath, safeTerminalLine } from
 import {
 	DEFAULT_CONSULT_RESOURCE_POLICY,
 	DEFAULT_CONSULTATION_CWD_POLICY,
-	resolveSubagentThinkingLevel,
-} from "./settings.js";
+} from "./settings/inspection.js";
+import { resolveSubagentThinkingLevel } from "./settings.js";
 
 const ConsultScopeSchema = StringEnum(["user", "project", "both"] as const, {
 	default: "user",

package/src/create-stateful-transport.ts

@@ -1,5 +1,6 @@
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { discoverAgents, type SubagentSettings, type SubagentTransportKind } from "./agents.js";
+import { discoverAgents } from "./agents/discovery.js";
+import type { SubagentSettings, SubagentTransportKind } from "./agents/types.js";
 import { AutoTransport } from "./auto-transport.js";
 import {
 	type ChildSessionFactory,

package/src/cwd-policy.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, ProjectTrustStore } from "@earendil-works/pi-coding-agent";
-import type { ConsultationCwdPolicy, DelegationCwdPolicy } from "./agents.js";
+import type { ConsultationCwdPolicy, DelegationCwdPolicy } from "./agents/types.js";
 import { safeTerminalLine } from "./safe-text.js";
 
 export type TargetBoundary = "current-workspace" | "external";

package/src/execution/budget.ts

@@ -0,0 +1,56 @@
+import type { AgentConfig } from "../agents/types.js";
+import type { TurnLimits } from "../turn-budget.js";
+
+export interface ExecutionBudget {
+	timeoutMs: number;
+	workTimeoutReason: "work_timeout" | "orchestration_timeout";
+	workTimeoutReportLimit: number;
+}
+
+export function resolveConfiguredTimeout(
+	agents: readonly AgentConfig[],
+	agentName: string,
+	localTimeoutMs: number | undefined,
+	topLevelTimeoutMs: number | undefined,
+	defaultTimeoutMs: number,
+): number {
+	return (
+		localTimeoutMs ??
+		topLevelTimeoutMs ??
+		agents.find((agent) => agent.name === agentName)?.timeoutMs ??
+		defaultTimeoutMs
+	);
+}
+
+export function mergeTurnLimits(local: TurnLimits | undefined, fallback: TurnLimits): TurnLimits {
+	return {
+		idleTimeoutMs: local?.idleTimeoutMs ?? fallback.idleTimeoutMs,
+		maxTurns: local?.maxTurns ?? fallback.maxTurns,
+		maxToolCalls: local?.maxToolCalls ?? fallback.maxToolCalls,
+	};
+}
+
+export function calculateExecutionBudget(input: {
+	requestedTimeoutMs: number;
+	orchestrationDeadline?: number;
+	totalTimeoutMs?: number;
+	now: number;
+}): ExecutionBudget | undefined {
+	if (input.orchestrationDeadline === undefined) {
+		return {
+			timeoutMs: input.requestedTimeoutMs,
+			workTimeoutReason: "work_timeout",
+			workTimeoutReportLimit: input.requestedTimeoutMs,
+		};
+	}
+	const remaining = Math.floor(input.orchestrationDeadline - input.now);
+	if (remaining < 1) return undefined;
+	const orchestrationLimited = remaining < input.requestedTimeoutMs;
+	return {
+		timeoutMs: Math.min(input.requestedTimeoutMs, remaining),
+		workTimeoutReason: orchestrationLimited ? "orchestration_timeout" : "work_timeout",
+		workTimeoutReportLimit: orchestrationLimited
+			? Math.floor(input.totalTimeoutMs as number)
+			: input.requestedTimeoutMs,
+	};
+}

package/src/execution/runtime-policy.ts

@@ -0,0 +1,19 @@
+export const FALLBACK_TIMEOUT_MS = 10 * 60 * 1000;
+
+export function parsePositiveInteger(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function resolveDefaultSubagentTimeoutMs(): number {
+	return parsePositiveInteger(process.env.PI_SUBAGENT_TIMEOUT_MS) ?? FALLBACK_TIMEOUT_MS;
+}
+
+export function assertSubagentDepthAllowed(): void {
+	const depth = Number.parseInt(process.env.PI_SUBAGENT_DEPTH ?? "0", 10) || 0;
+	const maxDepth = parsePositiveInteger(process.env.PI_SUBAGENT_MAX_DEPTH) ?? 1;
+	if (depth >= maxDepth) {
+		throw new Error(`Subagent recursion depth limit reached (${maxDepth})`);
+	}
+}

package/src/execution-plan.ts

@@ -8,7 +8,7 @@ import {
 	type AgentSource,
 	resolveAgentToolNames,
 	type SubagentThinkingLevel,
-} from "./agents.js";
+} from "./agents/types.js";
 import type { TargetPolicyAudit } from "./cwd-policy.js";
 import type { DelegationContract } from "./delegation-contract.js";
 import type { SubagentResultFormat } from "./result-contract.js";

package/src/execution-profiles.ts

@@ -1,4 +1,4 @@
-import type { SubagentThinkingLevel } from "./agents.js";
+import type { SubagentThinkingLevel } from "./agents/types.js";
 import { readSubagentSettings, updateAgentSettingsPatch } from "./settings.js";
 
 export const EXECUTION_PROFILES = ["fast", "balanced", "deep"] as const;

package/src/execution-ui.ts

@@ -1,5 +1,5 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { AgentConfig, SubagentThinkingLevel } from "./agents.js";
+import type { AgentConfig, SubagentThinkingLevel } from "./agents/types.js";
 import {
 	applyExecutionProfile,
 	EXECUTION_PROFILES,