@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/inspect.ts

@@ -13,26 +13,38 @@ import {
 	type DelegationCwdPolicy,
 	discoverAgents,
 } from "./agents.js";
+import { projectCapabilityManifest } from "./capabilities.js";
 import { resolveConsultTools } from "./consult-policy.js";
+import { buildContextSnapshot, type ContextMode } from "./context.js";
 import { renderInspectCall, renderInspectResult } from "./inspect-render.js";
+import { DEFAULT_MAX_CONTEXT_BYTES } from "./limits.js";
+import { resolvePiInvocation } from "./pi-invocation.js";
 import type { AgentRunInspectionDetail, AgentRunInspectionSummary } from "./registry.js";
 import { boundedPrivateText, boundText, safeDisplayPath, safeTerminalLine } from "./safe-text.js";
 import {
+	inspectBlockingParallelLimitSettings,
 	inspectCompletionDeliverySettings,
 	inspectConsultResourceSettings,
 	inspectCwdPolicySettings,
 	inspectDelegationWorkflowSettings,
+	inspectStatefulLimitSettings,
+	inspectStatefulTransportSettings,
 	inspectSubagentSettings,
 	resolveDelegationWorkflow,
 } from "./settings.js";
 import type { StatefulSubagentRuntimeStatus } from "./stateful.js";
+import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
+import { inspectSessionWorkflows } from "./work-item-persistence.js";
 
 const INSPECT_ACTIONS = [
 	"list_agents",
 	"get_agent",
 	"list_runs",
 	"get_run",
+	"list_workflows",
+	"get_workflow",
 	"list_models",
+	"preview_context",
 	"status",
 	"diagnose",
 ] as const;
@@ -43,6 +55,10 @@ const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
 });
 
 const LimitSchema = Type.Number({ minimum: 1, maximum: 100, multipleOf: 1 });
+const ContextModeSchema = Type.Union([
+	StringEnum(["none", "all", "summary"] as const),
+	Type.Number({ minimum: 1, multipleOf: 1 }),
+]);
 const MAX_DETAILS_LIST_BYTES = 40 * 1024;
 
 export const SubagentInspectParams = Type.Object(
@@ -50,9 +66,12 @@ export const SubagentInspectParams = Type.Object(
 		action: StringEnum(INSPECT_ACTIONS),
 		agent: Type.Optional(Type.String({ minLength: 1 })),
 		agentId: Type.Optional(Type.String({ minLength: 1 })),
+		workflowId: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 		agentScope: Type.Optional(AgentScopeSchema),
 		limit: Type.Optional(LimitSchema),
 		includeClosed: Type.Optional(Type.Boolean({ default: false })),
+		context: Type.Optional(ContextModeSchema),
+		contextEntryIds: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
 	},
 	{ additionalProperties: false },
 );
@@ -61,6 +80,7 @@ export type SubagentInspectParams = Static<typeof SubagentInspectParams>;
 
 export interface SubagentInspectRuntime {
 	getBlockingEnabled(): boolean;
+	getMaxParallelTasks(): number;
 	getConsultResourcePolicy(): "project-context" | "none" | "all";
 	getConsultationCwdPolicy(): ConsultationCwdPolicy;
 	getDelegationCwdPolicy(): DelegationCwdPolicy;
@@ -79,7 +99,10 @@ type ValidatedInspectOperation =
 	| { action: "get_agent"; agent: string; agentScope: AgentScope }
 	| { action: "list_runs"; includeClosed: boolean; limit: number }
 	| { action: "get_run"; agentId: string }
+	| { action: "list_workflows"; limit: number }
+	| { action: "get_workflow"; workflowId: string }
 	| { action: "list_models"; limit: number }
+	| { action: "preview_context"; context: ContextMode; contextEntryIds?: string[] }
 	| { action: "status" }
 	| { action: "diagnose" };
 
@@ -88,7 +111,7 @@ export function registerSubagentInspect(pi: ExtensionAPI, runtime: SubagentInspe
 		name: "subagent_inspect",
 		label: "Inspect Subagents",
 		description:
-			"Inspect available subagent definitions, models, retained runs, runtime status, and diagnostics without changing subagent or workspace state. This tool never starts a child, sends or acknowledges messages, interrupts or closes runs, changes settings, or modifies files.",
+			"Inspect available subagent definitions, models, retained runs, persisted blocking workflows, runtime status, and diagnostics without changing subagent or workspace state. This tool never starts a child, sends or acknowledges messages, interrupts or closes runs, changes settings, or modifies files.",
 		promptSnippet: "Inspect subagent metadata and runtime state without changing it",
 		parameters: SubagentInspectParams,
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx): Promise<InspectToolResult> {
@@ -118,7 +141,10 @@ export function validateInspectParams(params: unknown): ValidatedInspectOperatio
 		get_agent: ["action", "agent", "agentScope"],
 		list_runs: ["action", "includeClosed", "limit"],
 		get_run: ["action", "agentId"],
+		list_workflows: ["action", "limit"],
+		get_workflow: ["action", "workflowId"],
 		list_models: ["action", "limit"],
+		preview_context: ["action", "context", "contextEntryIds"],
 		status: ["action"],
 		diagnose: ["action"],
 	};
@@ -148,9 +174,24 @@ export function validateInspectParams(params: unknown): ValidatedInspectOperatio
 	if (action === "get_run") {
 		return { action, agentId: requiredString(values.agentId, action, "agentId") };
 	}
+	if (action === "list_workflows") {
+		return { action, limit: optionalLimit(values.limit, 50) };
+	}
+	if (action === "get_workflow") {
+		return { action, workflowId: requiredString(values.workflowId, action, "workflowId") };
+	}
 	if (action === "list_models") {
 		return { action, limit: optionalLimit(values.limit, 50) };
 	}
+	if (action === "preview_context") {
+		const context = optionalContextMode(values.context);
+		const contextEntryIds = optionalStringArray(values.contextEntryIds, "contextEntryIds");
+		return {
+			action,
+			context: values.context === undefined && contextEntryIds ? "all" : context,
+			...(contextEntryIds ? { contextEntryIds } : {}),
+		};
+	}
 	return { action };
 }
 
@@ -204,9 +245,59 @@ async function executeSubagentInspect(
 		}
 		return inspectResult({ action: operation.action, run: projectRun(run, ctx) });
 	}
+	if (operation.action === "list_workflows" || operation.action === "get_workflow") {
+		const owner =
+			ctx.sessionManager.getSessionId?.() ??
+			ctx.sessionManager.getSessionFile?.() ??
+			`ephemeral:${ctx.cwd}`;
+		const inspected = inspectSessionWorkflows(owner, {
+			maxStoredWorkflows: operation.action === "list_workflows" ? operation.limit : 64,
+		});
+		if (operation.action === "list_workflows") {
+			const selected = boundedProjection(
+				inspected.workflows,
+				operation.limit,
+				projectWorkflowSummary,
+			);
+			return inspectResult({
+				action: operation.action,
+				workflows: selected.items,
+				returned: selected.items.length,
+				omitted: inspected.omitted + selected.omitted,
+				invalid: inspected.invalid,
+			});
+		}
+		const workflow = inspected.workflows.find(
+			(candidate) => candidate.workflowId === operation.workflowId,
+		);
+		if (!workflow) {
+			throw new Error(
+				`Unknown persisted workflow: ${boundedPrivateText(operation.workflowId, 256)}`,
+			);
+		}
+		return inspectResult({ action: operation.action, workflow: projectWorkflow(workflow) });
+	}
 	if (operation.action === "list_models") {
 		return inspectResult({ action: operation.action, ...projectModels(ctx, operation.limit) });
 	}
+	if (operation.action === "preview_context") {
+		const snapshot = buildContextSnapshot(
+			ctx.sessionManager.getBranch(),
+			operation.context,
+			DEFAULT_MAX_CONTEXT_BYTES,
+			operation.contextEntryIds,
+		);
+		return inspectResult({
+			action: operation.action,
+			preview: {
+				mode: operation.context,
+				turns: snapshot.turns,
+				sourceCount: snapshot.sourceIds.length,
+				bytes: Buffer.byteLength(snapshot.text, "utf8"),
+				truncated: snapshot.truncated,
+			},
+		});
+	}
 	if (operation.action === "status") {
 		return inspectResult({ action: operation.action, status: projectStatus(runtime) });
 	}
@@ -215,6 +306,8 @@ async function executeSubagentInspect(
 	const userDiscovery = discoverAgents(ctx.cwd, "user", settings.settings);
 	const modelCount = availableModelCount(ctx);
 	const runtimeStatus = runtime.getRuntimeStatus();
+	const rpcCapability = inspectRpcCapability();
+	const inProcessCapability = await inspectInProcessCapability();
 	const checks = [
 		{
 			name: "settings",
@@ -244,6 +337,20 @@ async function executeSubagentInspect(
 				? "Stateful runtime initialized."
 				: "Stateful runtime not initialized.",
 		},
+		{
+			name: "in-process-sdk",
+			status: inProcessCapability.error ? "fail" : "pass",
+			message: inProcessCapability.error
+				? boundedPrivateText(inProcessCapability.error, 2 * 1024)
+				: "Required public Pi in-process session APIs are available.",
+		},
+		{
+			name: "rpc-cli",
+			status: rpcCapability.error ? "fail" : "pass",
+			message: rpcCapability.error
+				? boundedPrivateText(rpcCapability.error, 2 * 1024)
+				: "The exact loaded Pi CLI is available for persistent RPC transport.",
+		},
 		{
 			name: "consultation",
 			status: runtime.getBlockingEnabled() && modelCount > 0 ? "pass" : "fail",
@@ -280,6 +387,7 @@ function projectAgent(
 				: safeDisplayPath(agent.filePath, ctx.cwd),
 		model: agent.model ? boundedPrivateText(agent.model, 256) : undefined,
 		thinkingLevel: agent.thinkingLevel,
+		capabilityManifest: projectCapabilityManifest(agent.capabilityManifest),
 		...(includeTools
 			? { tools, toolCount: agent.tools?.length }
 			: { toolCount: agent.tools?.length }),
@@ -305,6 +413,67 @@ function projectRun(run: AgentRunInspectionDetail, ctx: ExtensionContext): Recor
 		cwd: safeDisplayPath(run.cwd, ctx.cwd),
 		workspaceMode: run.workspaceMode ?? "shared",
 		thinkingLevel: run.thinkingLevel,
+		timeoutMs: run.timeoutMs,
+		currentTimeoutMs: run.currentTimeoutMs,
+		idleTimeoutMs: run.idleTimeoutMs,
+		currentIdleTimeoutMs: run.currentIdleTimeoutMs,
+		maxTurns: run.maxTurns,
+		currentMaxTurns: run.currentMaxTurns,
+		maxToolCalls: run.maxToolCalls,
+		currentMaxToolCalls: run.currentMaxToolCalls,
+		context: {
+			turns: run.contextTurns ?? 0,
+			sources: run.contextSources ?? 0,
+			bytes: run.contextBytes ?? 0,
+			truncated: run.contextTruncated === true,
+		},
+		contract: run.contract
+			? {
+					version: run.contract.version,
+					level: run.contract.level,
+					taskId: boundedPrivateText(run.contract.taskId, 256),
+					enforcement: run.contract.enforcement,
+					dependencies: run.contract.dependencies.length,
+					acceptanceCriteria: run.contract.acceptanceCriteria.length,
+					requiredEvidence: run.contract.requiredEvidence.length,
+				}
+			: undefined,
+		resultFormat: run.resultFormat ?? "text",
+		structuredResult: run.structuredResult,
+		termination: run.termination,
+		outcome: run.outcome,
+		capabilityGrant: run.capabilityGrant
+			? {
+					version: run.capabilityGrant.version,
+					id: run.capabilityGrant.id,
+					executionPlanId: run.capabilityGrant.executionPlanId,
+					taskGeneration: run.capabilityGrant.taskGeneration,
+					issuedAt: run.capabilityGrant.issuedAt,
+					expiresAt: run.capabilityGrant.expiresAt,
+					state: run.capabilityGrant.state,
+					revokedAt: run.capabilityGrant.revokedAt,
+					revocationReason: run.capabilityGrant.revocationReason,
+				}
+			: undefined,
+		executionPlan: run.executionPlan
+			? {
+					...run.executionPlan,
+					target: {
+						...run.executionPlan.target,
+						cwd: safeDisplayPath(run.executionPlan.target.cwd, ctx.cwd),
+						trust: { ...run.executionPlan.target.trust, sourcePath: undefined },
+					},
+				}
+			: undefined,
+		semanticSnapshot: run.semanticSnapshot
+			? {
+					version: run.semanticSnapshot.version,
+					digest: run.semanticSnapshot.digest,
+					components: { ...run.semanticSnapshot.components },
+				}
+			: undefined,
+		semanticCompatibility: run.semanticCompatibility,
+		telemetry: run.telemetry,
 		currentTask: run.currentTask ? boundedPrivateText(run.currentTask, 2 * 1024) : undefined,
 		error: run.error ? boundedPrivateText(run.error, 2 * 1024) : undefined,
 		target: run.target
@@ -333,6 +502,77 @@ function projectRun(run: AgentRunInspectionDetail, ctx: ExtensionContext): Recor
 	};
 }
 
+function projectWorkflowSummary(workflow: WorkItemLedgerSnapshot): Record<string, unknown> {
+	return {
+		workflowId: boundedPrivateText(workflow.workflowId, 256),
+		generation: workflow.generation,
+		itemCount: workflow.items.length,
+		states: Object.fromEntries(
+			[...new Set(workflow.items.map((item) => item.state))]
+				.sort()
+				.map((state) => [state, workflow.items.filter((item) => item.state === state).length]),
+		),
+	};
+}
+
+function projectWorkflow(workflow: WorkItemLedgerSnapshot): Record<string, unknown> {
+	const projected = boundedProjection(workflow.items, 64, (item) => ({
+		id: boundedPrivateText(item.id, 256),
+		state: item.state,
+		generation: item.generation,
+		taskGeneration: item.taskGeneration,
+		dependencies: item.dependencies.map((value) => boundedPrivateText(value, 256)),
+		assignedAgentId: item.assignedAgentId
+			? boundedPrivateText(item.assignedAgentId, 256)
+			: undefined,
+		acceptedExecutionPlanId: item.acceptedExecutionPlanId,
+		artifacts: item.artifacts.map((artifact) => ({
+			id: boundedPrivateText(artifact.id, 256),
+			kind: boundedPrivateText(artifact.kind, 256),
+			version: boundedPrivateText(artifact.version, 256),
+			producerTaskId: artifact.producerTaskId
+				? boundedPrivateText(artifact.producerTaskId, 256)
+				: undefined,
+			generation: artifact.generation,
+			verified: artifact.verified,
+		})),
+		verificationAccepted: item.verificationAccepted,
+		stagedTreeIdentity: item.stagedTreeIdentity
+			? {
+					version: item.stagedTreeIdentity.version,
+					kind: item.stagedTreeIdentity.kind,
+					digest: item.stagedTreeIdentity.digest,
+				}
+			: undefined,
+		verificationReceipt: item.verificationReceipt
+			? {
+					version: item.verificationReceipt.version,
+					decision: item.verificationReceipt.decision,
+					targetTaskId: boundedPrivateText(item.verificationReceipt.targetTaskId, 256),
+					targetTaskGeneration: item.verificationReceipt.targetTaskGeneration,
+					targetExecutionPlanId: item.verificationReceipt.targetExecutionPlanId,
+					verifierTaskId: boundedPrivateText(item.verificationReceipt.verifierTaskId, 256),
+					verifierTaskGeneration: item.verificationReceipt.verifierTaskGeneration,
+					verifierExecutionPlanId: item.verificationReceipt.verifierExecutionPlanId,
+					treeIdentity: item.verificationReceipt.treeIdentity,
+					summary: boundedPrivateText(item.verificationReceipt.summary, 8 * 1024),
+					evidenceCount: item.verificationReceipt.evidence.length,
+					limitationCount: item.verificationReceipt.limitations.length,
+					createdAt: item.verificationReceipt.createdAt,
+					truncated: item.verificationReceipt.truncated,
+				}
+			: undefined,
+		outcomeReason: item.outcomeReason
+			? boundedPrivateText(item.outcomeReason, 2 * 1024)
+			: undefined,
+	}));
+	return {
+		...projectWorkflowSummary(workflow),
+		items: projected.items,
+		omittedItems: projected.omitted,
+	};
+}
+
 function projectModels(ctx: ExtensionContext, limit: number): Record<string, unknown> {
 	const scoped = ctx.scopedModels ?? [];
 	const candidates =
@@ -365,13 +605,34 @@ function projectStatus(runtime: SubagentInspectRuntime): Record<string, unknown>
 	const resources = inspectConsultResourceSettings();
 	const cwdPolicy = inspectCwdPolicySettings();
 	const completion = inspectCompletionDeliverySettings();
+	const parallelLimit = inspectBlockingParallelLimitSettings();
+	const detachedLimits = inspectStatefulLimitSettings();
+	const transport = inspectStatefulTransportSettings();
+	const configuredDetachedLimits = detachedLimits.values
+		? Object.fromEntries(
+				Object.entries(detachedLimits.values).map(([field, snapshot]) => [field, snapshot.value]),
+			)
+		: undefined;
+	const configuredDetachedLimitSources = detachedLimits.values
+		? Object.fromEntries(
+				Object.entries(detachedLimits.values).map(([field, snapshot]) => [field, snapshot.source]),
+			)
+		: undefined;
 	return {
 		workflow,
 		configuredWorkflow: configured.value,
 		configuredWorkflowSource: configured.source,
 		stateful,
+		statefulLimits: stateful.limits,
+		configuredTransport: transport.value,
+		configuredTransportSource: transport.source,
+		configuredStatefulLimits: configuredDetachedLimits,
+		configuredStatefulLimitSources: configuredDetachedLimitSources,
 		configuredCompletionDelivery: completion.value,
 		configuredCompletionDeliverySource: completion.source,
+		maxParallelTasks: runtime.getMaxParallelTasks(),
+		configuredMaxParallelTasks: parallelLimit.value,
+		configuredMaxParallelTasksSource: parallelLimit.source,
 		consultResources: runtime.getConsultResourcePolicy(),
 		consultationCwdPolicy: runtime.getConsultationCwdPolicy(),
 		configuredConsultationCwdPolicy: cwdPolicy.consultation.value,
@@ -383,15 +644,54 @@ function projectStatus(runtime: SubagentInspectRuntime): Record<string, unknown>
 		consultResourcesSource: resources.source,
 		settingsPath: safeDisplayPath(resources.path, process.cwd()),
 		settingsError:
-			configured.error || resources.error || cwdPolicy.error || completion.error
+			configured.error ||
+			resources.error ||
+			cwdPolicy.error ||
+			completion.error ||
+			parallelLimit.error ||
+			detachedLimits.error ||
+			transport.error
 				? boundedPrivateText(
-						configured.error ?? resources.error ?? cwdPolicy.error ?? completion.error ?? "",
+						configured.error ??
+							resources.error ??
+							cwdPolicy.error ??
+							completion.error ??
+							parallelLimit.error ??
+							detachedLimits.error ??
+							transport.error ??
+							"",
 						2 * 1024,
 					)
 				: undefined,
 	};
 }
 
+async function inspectInProcessCapability(): Promise<{ error?: string }> {
+	try {
+		const moduleSpecifier = "@earendil-works/pi-coding-agent";
+		const core = await import(moduleSpecifier);
+		for (const name of [
+			"createAgentSessionServices",
+			"createAgentSessionFromServices",
+			"resolveCliModel",
+		] as const) {
+			if (typeof core[name] !== "function") return { error: `Pi core does not export ${name}()` };
+		}
+		return {};
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function inspectRpcCapability(): { error?: string } {
+	try {
+		resolvePiInvocation(["--mode", "rpc", "--no-session"]);
+		return {};
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
 function availableModelCount(ctx: ExtensionContext): number {
 	return (ctx.scopedModels?.length ?? 0) > 0
 		? ctx.scopedModels.length
@@ -450,6 +750,24 @@ function requiredString(value: unknown, action: string, field: string): string {
 	return value;
 }
 
+function optionalContextMode(value: unknown): ContextMode {
+	if (value === undefined) return "none";
+	if (value === "none" || value === "all" || value === "summary") return value;
+	if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) return value;
+	throw new Error("subagent_inspect context must be none, all, summary, or a positive integer");
+}
+
+function optionalStringArray(value: unknown, field: string): string[] | undefined {
+	if (value === undefined) return undefined;
+	if (
+		!Array.isArray(value) ||
+		!value.every((item) => typeof item === "string" && item.length > 0)
+	) {
+		throw new Error(`subagent_inspect ${field} must be an array of non-empty strings`);
+	}
+	return [...value];
+}
+
 function optionalLimit(value: unknown, defaultValue: number): number {
 	if (value === undefined) return defaultValue;
 	if (!Number.isSafeInteger(value) || (value as number) < 1 || (value as number) > 100) {

package/src/integration-controller.ts

@@ -0,0 +1,98 @@
+import * as path from "node:path";
+
+export interface ManagedIntegrationExpectation {
+	taskId: string;
+	taskGeneration: number;
+	baseRepositoryGeneration: string;
+	dependencyVersions: Record<string, string>;
+	readSetVersions: Record<string, string>;
+	executionPlanId: string;
+	allowedScopes: string[];
+	patchDigest: string;
+	requiredEvidence: string[];
+}
+
+export interface ManagedIntegrationCandidate extends ManagedIntegrationExpectation {
+	changedPaths: string[];
+	evidence: Record<string, string>;
+	verifier: {
+		freshContext: boolean;
+		exactIntegratedTree: boolean;
+		status: "accepted" | "rework" | "rejected";
+	};
+}
+
+export interface ManagedIntegrationAcceptance {
+	status: "accepted";
+	taskId: string;
+	taskGeneration: number;
+	patchDigest: string;
+	executionPlanId: string;
+}
+
+export function verifyManagedIntegration(
+	expected: ManagedIntegrationExpectation,
+	candidate: ManagedIntegrationCandidate,
+): ManagedIntegrationAcceptance {
+	if (
+		candidate.taskId !== expected.taskId ||
+		candidate.taskGeneration !== expected.taskGeneration
+	) {
+		throw new Error("Managed integration rejected stale task generation");
+	}
+	if (candidate.baseRepositoryGeneration !== expected.baseRepositoryGeneration) {
+		throw new Error("Managed integration rejected stale base repository generation");
+	}
+	if (candidate.executionPlanId !== expected.executionPlanId) {
+		throw new Error("Managed integration rejected stale execution plan identity");
+	}
+	if (!sameRecord(candidate.dependencyVersions, expected.dependencyVersions)) {
+		throw new Error("Managed integration rejected stale dependency versions");
+	}
+	if (!sameRecord(candidate.readSetVersions, expected.readSetVersions)) {
+		throw new Error("Managed integration rejected stale read-set versions");
+	}
+	if (candidate.patchDigest !== expected.patchDigest) {
+		throw new Error("Managed integration rejected patch digest mismatch");
+	}
+	const allowedScopes = expected.allowedScopes.map(normalizedPath);
+	if (
+		!candidate.changedPaths.every((changedPath) => {
+			const normalizedChangedPath = normalizedPath(changedPath);
+			return allowedScopes.some(
+				(scope) =>
+					normalizedChangedPath === scope ||
+					normalizedChangedPath.startsWith(`${scope}${path.sep}`),
+			);
+		})
+	) {
+		throw new Error("Managed integration rejected a path outside the accepted scope");
+	}
+	if (expected.requiredEvidence.some((id) => !candidate.evidence[id])) {
+		throw new Error("Managed integration rejected missing required evidence");
+	}
+	if (!candidate.verifier.freshContext || !candidate.verifier.exactIntegratedTree) {
+		throw new Error("Managed integration requires a fresh verifier on the exact integrated tree");
+	}
+	if (candidate.verifier.status !== "accepted") {
+		throw new Error(`Managed integration verifier returned ${candidate.verifier.status}`);
+	}
+	return {
+		status: "accepted",
+		taskId: expected.taskId,
+		taskGeneration: expected.taskGeneration,
+		patchDigest: expected.patchDigest,
+		executionPlanId: expected.executionPlanId,
+	};
+}
+
+function normalizedPath(value: string): string {
+	if (!value || value.includes("\0")) throw new Error("Managed integration scope is invalid");
+	return path.resolve(path.sep, value.replaceAll("\\", path.sep));
+}
+
+function sameRecord(left: Record<string, string>, right: Record<string, string>): boolean {
+	const leftEntries = Object.entries(left).sort(([a], [b]) => a.localeCompare(b));
+	const rightEntries = Object.entries(right).sort(([a], [b]) => a.localeCompare(b));
+	return JSON.stringify(leftEntries) === JSON.stringify(rightEntries);
+}

package/src/limits.ts

@@ -4,6 +4,9 @@ export const DEFAULT_MAX_OUTPUT_BYTES = DEFAULT_MAX_BYTES;
 export const DEFAULT_MAX_STDERR_BYTES = 16 * 1024;
 export const DEFAULT_MAX_CONTEXT_BYTES = DEFAULT_MAX_BYTES;
 export const MAX_SUBAGENT_TIMEOUT_MS = 2_147_483_647;
+export const DEFAULT_MAX_PARALLEL_TASKS = 8;
+export const MAX_CONFIGURABLE_PARALLEL_TASKS = 64;
+export const MAX_BLOCKING_PARALLEL_CONCURRENCY = 4;
 export const DEFAULT_MAX_MESSAGES = 200;
 export const TRUNCATION_MARKER = "\n… [truncated by pi-subagents]";
 export const TAIL_TRUNCATION_MARKER = "… [truncated by pi-subagents]\n";

package/src/orchestration-metrics.ts

@@ -0,0 +1,109 @@
+import type { SingleResult } from "./runner.js";
+import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
+
+export interface OrchestrationMetrics {
+	workItems: number;
+	completed: number;
+	failedOrBlocked: number;
+	invalidated: number;
+	requiredTransfers: number;
+	resolvedTransfers: number;
+	transferCoverage: number;
+	attempts: number;
+	hedgedTasks: number;
+	requestedTools: number;
+	effectiveRequestedTools: number;
+	permissionPrecision: number;
+	workerReportedVerification: number;
+	executorAcceptedVerification: number;
+	verificationRework: number;
+	verificationRejected: number;
+	verificationInvalid: number;
+	verificationTreeMismatch: number;
+	panelValidReviews?: number;
+	panelFailedReviews?: number;
+	panelBlockingObjections?: number;
+	panelDissent?: number;
+	panelSynthesisState?: string;
+}
+
+export function calculateOrchestrationMetrics(
+	workflow: WorkItemLedgerSnapshot | undefined,
+	results: SingleResult[],
+	panel?: {
+		validReviewCount: number;
+		failedReviewCount: number;
+		blockingObjectionCount: number;
+		dissentCount: number;
+		state: string;
+	},
+): OrchestrationMetrics {
+	const items = workflow?.items ?? [];
+	const requiredTransfers = items.reduce((sum, item) => sum + item.inputArtifacts.length, 0);
+	const resolvedTransfers = items.reduce(
+		(sum, item) => sum + Object.keys(item.inputArtifactVersions).length,
+		0,
+	);
+	const requestedTools = results.reduce(
+		(sum, result) => sum + (result.executionPlan?.requestedTools.length ?? 0),
+		0,
+	);
+	const effectiveRequestedTools = results.reduce((sum, result) => {
+		const plan = result.executionPlan;
+		if (!plan) return sum;
+		return (
+			sum +
+			plan.requestedTools.filter((tool) => plan.effectiveTools?.includes(tool) === true).length
+		);
+	}, 0);
+	return {
+		workItems: items.length,
+		completed: items.filter((item) => item.state === "completed").length,
+		failedOrBlocked: items.filter((item) =>
+			["failed", "blocked", "needs-input", "interrupted"].includes(item.state),
+		).length,
+		invalidated: items.filter((item) => ["stale", "invalidated"].includes(item.state)).length,
+		requiredTransfers,
+		resolvedTransfers,
+		transferCoverage: requiredTransfers === 0 ? 1 : resolvedTransfers / requiredTransfers,
+		attempts: results.reduce((sum, result) => sum + (result.attemptCount ?? 1), 0),
+		hedgedTasks: results.filter((result) => result.hedged).length,
+		requestedTools,
+		effectiveRequestedTools,
+		permissionPrecision: requestedTools === 0 ? 1 : effectiveRequestedTools / requestedTools,
+		workerReportedVerification: results.filter(
+			(result, index) =>
+				!items[index]?.verifierFor &&
+				result.structuredResult?.version === "pi-subagents:result:v2" &&
+				result.structuredResult.verification.some(
+					(verification) => verification.status === "passed",
+				),
+		).length,
+		executorAcceptedVerification: items.filter((item) => item.verificationAccepted).length,
+		verificationRework: items.filter(
+			(item) => !item.verifierFor && item.verificationReceipt?.decision === "rework",
+		).length,
+		verificationRejected: items.filter(
+			(item) => !item.verifierFor && item.verificationReceipt?.decision === "reject",
+		).length,
+		verificationInvalid: items.filter(
+			(item) => !item.verifierFor && item.outcomeReason === "verification-receipt-invalid",
+		).length,
+		verificationTreeMismatch: items.filter(
+			(item) =>
+				!item.verifierFor &&
+				["verification-tree-mismatch", "verification-tree-unavailable"].includes(
+					item.outcomeReason ?? "",
+				),
+		).length,
+		...(panel
+			? {
+					panelValidReviews: panel.validReviewCount,
+					panelFailedReviews: panel.failedReviewCount,
+					panelBlockingObjections: panel.blockingObjectionCount,
+					panelDissent: panel.dissentCount,
+					panelSynthesisState: panel.state,
+				}
+			: {}),
+	};
+}