@narumitw/pi-subagents 0.49.3 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.49.3",
+	"version": "0.51.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",
@@ -23,6 +23,9 @@
 			"./src/index.ts"
 		]
 	},
+	"piExtension": {
+		"lifecycle": "stable"
+	},
 	"scripts": {
 		"check": "biome check . && npm run typecheck",
 		"format": "biome check --write .",
@@ -37,11 +40,11 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.7",
-		"@earendil-works/pi-agent-core": "0.83.0",
-		"@earendil-works/pi-ai": "0.83.0",
-		"@earendil-works/pi-coding-agent": "0.83.0",
-		"@earendil-works/pi-tui": "0.83.0",
-		"typebox": "1.3.10",
+		"@earendil-works/pi-agent-core": "0.84.1",
+		"@earendil-works/pi-ai": "0.84.1",
+		"@earendil-works/pi-coding-agent": "0.84.1",
+		"@earendil-works/pi-tui": "0.84.1",
+		"typebox": "1.3.11",
 		"typescript": "7.0.2"
 	},
 	"dependencies": {
@@ -51,6 +54,6 @@
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",
-		"directory": "extensions/pi-subagents"
+		"directory": "packages/pi-subagents"
 	}
 }

package/src/adaptive-scheduler.ts

@@ -0,0 +1,196 @@
+import * as path from "node:path";
+import type { WorkItemLedgerSnapshot, WorkItemRecord } from "./work-item-ledger.js";
+
+export const ADAPTIVE_SCHEDULER_POLICY = "dependency-aware-v1" as const;
+
+export type SchedulingReason =
+	| "selected"
+	| "dependency-not-ready"
+	| "state-not-ready"
+	| "budget-exhausted"
+	| "capacity-exhausted"
+	| "scope-conflict";
+
+export interface SchedulingDecisionItem {
+	id: string;
+	reason: SchedulingReason;
+	criticalPathDepth: number;
+}
+
+export interface SchedulingDecision {
+	policy: typeof ADAPTIVE_SCHEDULER_POLICY;
+	workflowId: string;
+	workflowGeneration: number;
+	effectiveConcurrency: number;
+	selected: string[];
+	decisions: SchedulingDecisionItem[];
+}
+
+export interface AdaptiveSchedulerOptions {
+	maxConcurrency: number;
+	activeCount: number;
+	transportCapacity: number;
+	remainingBudgetMs: number;
+	activeReadPaths?: string[];
+	activeWritePaths?: string[];
+	activeOwnershipKeys?: string[];
+	activeMutatingCount?: number;
+	maxMutatingConcurrency?: number;
+}
+
+export class AdaptiveScheduler {
+	decide(snapshot: WorkItemLedgerSnapshot, options: AdaptiveSchedulerOptions): SchedulingDecision {
+		validateOptions(options);
+		const depth = criticalPathDepths(snapshot.items);
+		const ready = snapshot.items
+			.filter((item) => item.state === "ready")
+			.sort(
+				(left, right) =>
+					(depth.get(right.id) ?? 0) - (depth.get(left.id) ?? 0) || left.id.localeCompare(right.id),
+			);
+		const availableSlots = Math.max(
+			0,
+			Math.min(
+				options.maxConcurrency - options.activeCount,
+				options.transportCapacity - options.activeCount,
+				ready.length,
+			),
+		);
+		const effectiveConcurrency = options.remainingBudgetMs > 0 ? availableSlots : 0;
+		const selected: string[] = [];
+		let mutatingCount = options.activeMutatingCount ?? 0;
+		const maxMutatingConcurrency = options.maxMutatingConcurrency ?? 2;
+		const selectedReadPaths = normalizedScopes(options.activeReadPaths ?? []);
+		const selectedWritePaths = normalizedScopes(options.activeWritePaths ?? []);
+		const selectedOwnership = new Set(options.activeOwnershipKeys ?? []);
+		const reasons = new Map<string, SchedulingReason>();
+		for (const item of ready) {
+			if (options.remainingBudgetMs <= 0) {
+				reasons.set(item.id, "budget-exhausted");
+				continue;
+			}
+			if (
+				selected.length >= effectiveConcurrency ||
+				(item.sideEffectPolicy !== "read-only" && mutatingCount >= maxMutatingConcurrency)
+			) {
+				reasons.set(item.id, "capacity-exhausted");
+				continue;
+			}
+			if (hasConflict(item, selectedReadPaths, selectedWritePaths, selectedOwnership)) {
+				reasons.set(item.id, "scope-conflict");
+				continue;
+			}
+			selected.push(item.id);
+			if (item.sideEffectPolicy !== "read-only") mutatingCount++;
+			reasons.set(item.id, "selected");
+			for (const scope of normalizedScopes(item.readPaths)) selectedReadPaths.add(scope);
+			for (const scope of normalizedScopes(item.writePaths)) selectedWritePaths.add(scope);
+			for (const key of item.ownershipKeys) selectedOwnership.add(key);
+		}
+		const decisions = snapshot.items
+			.map((item) => ({
+				id: item.id,
+				reason:
+					reasons.get(item.id) ??
+					(item.state === "pending" ? "dependency-not-ready" : "state-not-ready"),
+				criticalPathDepth: depth.get(item.id) ?? 0,
+			}))
+			.sort((left, right) => left.id.localeCompare(right.id));
+		return {
+			policy: ADAPTIVE_SCHEDULER_POLICY,
+			workflowId: snapshot.workflowId,
+			workflowGeneration: snapshot.generation,
+			effectiveConcurrency,
+			selected,
+			decisions,
+		};
+	}
+}
+
+function hasConflict(
+	item: WorkItemRecord,
+	readPaths: ReadonlySet<string>,
+	writePaths: ReadonlySet<string>,
+	ownership: ReadonlySet<string>,
+): boolean {
+	const candidateReads = normalizedScopes(item.readPaths);
+	const candidateWrites = normalizedScopes(item.writePaths);
+	return (
+		[...candidateWrites].some(
+			(scope) => overlapsAny(scope, readPaths) || overlapsAny(scope, writePaths),
+		) ||
+		[...candidateReads].some((scope) => overlapsAny(scope, writePaths)) ||
+		item.ownershipKeys.some((key) => ownership.has(key))
+	);
+}
+
+function normalizedScopes(values: readonly string[]): Set<string> {
+	return new Set(values.map(normalizeScope));
+}
+
+function normalizeScope(value: string): string {
+	const normalized = path.posix.normalize(value.trim().replace(/\\+/gu, "/"));
+	if (
+		normalized === "." ||
+		normalized === ".." ||
+		normalized.startsWith("../") ||
+		normalized.startsWith("/") ||
+		/^[A-Za-z]:\//u.test(normalized)
+	) {
+		return "";
+	}
+	return normalized.replace(/^\.\//u, "").replace(/\/$/u, "");
+}
+
+function overlapsAny(scope: string, candidates: ReadonlySet<string>): boolean {
+	return [...candidates].some((candidate) => scopesOverlap(scope, candidate));
+}
+
+function scopesOverlap(left: string, right: string): boolean {
+	if (!left || !right || left === right) return true;
+	return left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function criticalPathDepths(items: WorkItemRecord[]): Map<string, number> {
+	const byId = new Map(items.map((item) => [item.id, item]));
+	const memo = new Map<string, number>();
+	const visit = (id: string): number => {
+		const cached = memo.get(id);
+		if (cached !== undefined) return cached;
+		const item = byId.get(id);
+		if (!item || item.dependents.length === 0) {
+			memo.set(id, 0);
+			return 0;
+		}
+		const value = 1 + Math.max(...item.dependents.map(visit));
+		memo.set(id, value);
+		return value;
+	};
+	for (const item of items) visit(item.id);
+	return memo;
+}
+
+function validateOptions(options: AdaptiveSchedulerOptions): void {
+	for (const [name, value] of [
+		["maxConcurrency", options.maxConcurrency],
+		["activeCount", options.activeCount],
+		["transportCapacity", options.transportCapacity],
+	] as const) {
+		if (!Number.isSafeInteger(value) || value < (name === "activeCount" ? 0 : 1)) {
+			throw new Error(
+				`${name} must be a ${name === "activeCount" ? "non-negative" : "positive"} safe integer`,
+			);
+		}
+	}
+	for (const [name, value] of [
+		["activeMutatingCount", options.activeMutatingCount ?? 0],
+		["maxMutatingConcurrency", options.maxMutatingConcurrency ?? 2],
+	] as const) {
+		if (!Number.isSafeInteger(value) || value < (name === "activeMutatingCount" ? 0 : 1)) {
+			throw new Error(`${name} has an invalid bound`);
+		}
+	}
+	if (!Number.isFinite(options.remainingBudgetMs) || options.remainingBudgetMs < 0) {
+		throw new Error("remainingBudgetMs must be a non-negative finite number");
+	}
+}

package/src/admission-benchmark.ts

@@ -0,0 +1,95 @@
+export const ADMISSION_BENCHMARK_VERSION = "pi-subagents:admission-benchmark:v1" as const;
+
+export const ADMISSION_BENCHMARK_ARMS = [
+	"strong-single",
+	"one-child",
+	"equal-budget-best-of-n",
+	"naive-parallel",
+	"fixed-two-child",
+	"admission-selected",
+] as const;
+
+export type AdmissionBenchmarkArm = (typeof ADMISSION_BENCHMARK_ARMS)[number];
+
+export interface AdmissionBenchmarkProtocol {
+	version: typeof ADMISSION_BENCHMARK_VERSION;
+	model: string;
+	evaluator: string;
+	taskIds: string[];
+	pairedSeeds: number[];
+	maxTokens: number;
+	maxCost: number;
+	maxWallClockMs: number;
+	maxRetries: number;
+	maxMutatingChildren: number;
+	maxRecursiveDepth: number;
+	arms: AdmissionBenchmarkArm[];
+}
+
+export interface AdmissionBenchmarkAdapter {
+	arm: AdmissionBenchmarkArm;
+	model: string;
+	evaluator: string;
+	maxTokens: number;
+	maxCost: number;
+	maxWallClockMs: number;
+	maxRetries: number;
+	mutatingChildren: number;
+	recursiveDepth: number;
+}
+
+export interface AdmissionBenchmarkDryRun {
+	version: typeof ADMISSION_BENCHMARK_VERSION;
+	pairedInstances: number;
+	arms: AdmissionBenchmarkArm[];
+	valid: true;
+}
+
+export function validateAdmissionBenchmark(
+	protocol: AdmissionBenchmarkProtocol,
+	adapters: AdmissionBenchmarkAdapter[],
+): AdmissionBenchmarkDryRun {
+	if (protocol.version !== ADMISSION_BENCHMARK_VERSION) {
+		throw new Error("Unsupported admission benchmark protocol");
+	}
+	if (protocol.taskIds.length < 1 || protocol.pairedSeeds.length < 2) {
+		throw new Error("Admission benchmark requires tasks and repeated paired seeds");
+	}
+	if (
+		protocol.maxMutatingChildren < 0 ||
+		protocol.maxMutatingChildren > 2 ||
+		protocol.maxRecursiveDepth !== 0
+	) {
+		throw new Error("Admission benchmark permits at most two mutating children and no recursion");
+	}
+	const expectedArms = [...new Set(protocol.arms)].sort();
+	if (expectedArms.length !== ADMISSION_BENCHMARK_ARMS.length) {
+		throw new Error("Admission benchmark must declare every comparison arm");
+	}
+	for (const arm of ADMISSION_BENCHMARK_ARMS) {
+		const adapter = adapters.find((candidate) => candidate.arm === arm);
+		if (!adapter) throw new Error(`Missing admission benchmark adapter: ${arm}`);
+		if (
+			adapter.model !== protocol.model ||
+			adapter.evaluator !== protocol.evaluator ||
+			adapter.maxTokens !== protocol.maxTokens ||
+			adapter.maxCost !== protocol.maxCost ||
+			adapter.maxWallClockMs !== protocol.maxWallClockMs ||
+			adapter.maxRetries !== protocol.maxRetries
+		) {
+			throw new Error(`Admission benchmark adapter ${arm} violates matched resources`);
+		}
+		if (
+			adapter.mutatingChildren > protocol.maxMutatingChildren ||
+			adapter.recursiveDepth > protocol.maxRecursiveDepth
+		) {
+			throw new Error(`Admission benchmark adapter ${arm} exceeds width or depth`);
+		}
+	}
+	return {
+		version: ADMISSION_BENCHMARK_VERSION,
+		pairedInstances: protocol.taskIds.length * protocol.pairedSeeds.length,
+		arms: [...ADMISSION_BENCHMARK_ARMS],
+		valid: true,
+	};
+}

package/src/admission-policy.ts

@@ -0,0 +1,78 @@
+export const DELEGATION_ADMISSION_VERSION = "pi-subagents:admission:v1" as const;
+
+export type DelegationAdmissionRecommendation =
+	| "parent-owned-direct"
+	| "one-child"
+	| "one-child-plus-verification"
+	| "bounded-two-child"
+	| "abstain-insufficient-evidence";
+
+export interface DelegationAdmissionInput {
+	contextPressure: "low" | "medium" | "high";
+	independentWorkItems: number;
+	coupling: "dense" | "sparse";
+	verificationRequired: boolean;
+	verificationAvailable: boolean;
+	capabilitiesSupported: boolean;
+	budgetAllowsChildren: boolean;
+	generationCurrent: boolean;
+	requirementsComplete: boolean;
+}
+
+export interface DelegationAdmissionDecision {
+	version: typeof DELEGATION_ADMISSION_VERSION;
+	recommendation: DelegationAdmissionRecommendation;
+	reasonCodes: string[];
+	benefitHypothesis: string;
+	auditOnly: true;
+}
+
+export function evaluateDelegationAdmission(
+	input: DelegationAdmissionInput,
+): DelegationAdmissionDecision {
+	if (!input.generationCurrent)
+		return decision("abstain-insufficient-evidence", ["stale-generation"]);
+	if (!input.requirementsComplete) {
+		return decision("abstain-insufficient-evidence", ["requirements-incomplete"]);
+	}
+	if (!input.capabilitiesSupported) {
+		return decision("abstain-insufficient-evidence", ["capability-unsupported"]);
+	}
+	if (!input.budgetAllowsChildren) {
+		return decision("parent-owned-direct", ["child-budget-insufficient"]);
+	}
+	if (input.independentWorkItems >= 2 && input.coupling === "sparse") {
+		return decision(
+			"bounded-two-child",
+			["declared-independent-work"],
+			"parallel-critical-path-reduction",
+		);
+	}
+	if (input.verificationRequired) {
+		return input.verificationAvailable
+			? decision(
+					"one-child-plus-verification",
+					["independent-verification-required"],
+					"independent-error-detection",
+				)
+			: decision("abstain-insufficient-evidence", ["verification-unavailable"]);
+	}
+	if (input.contextPressure === "high") {
+		return decision("one-child", ["declared-context-pressure"], "context-isolation");
+	}
+	return decision("parent-owned-direct", ["delegation-benefit-not-established"]);
+}
+
+function decision(
+	recommendation: DelegationAdmissionRecommendation,
+	reasonCodes: string[],
+	benefitHypothesis = "none",
+): DelegationAdmissionDecision {
+	return {
+		version: DELEGATION_ADMISSION_VERSION,
+		recommendation,
+		reasonCodes,
+		benefitHypothesis,
+		auditOnly: true,
+	};
+}

package/src/agent-projection.ts

@@ -0,0 +1,53 @@
+import type { ManagedAgent } from "./registry.js";
+
+export interface AgentProjectionLimits {
+	maxAgents: number;
+	maxDepth?: number;
+}
+
+/**
+ * Select the newest restorable agent trees without orphaning child records.
+ *
+ * Complete ancestor chains are selected together, then returned in their original
+ * order so persistence and restore behavior stay deterministic.
+ */
+export function projectAgentRecords(
+	agents: readonly ManagedAgent[],
+	limits: AgentProjectionLimits,
+): ManagedAgent[] {
+	const byId = new Map(agents.map((agent) => [agent.id, agent]));
+	const selected = new Set<string>();
+	const maxDepth = limits.maxDepth ?? Number.MAX_SAFE_INTEGER;
+	const newestFirst = agents
+		.map((agent, index) => ({ agent, index }))
+		.sort(
+			(left, right) => right.agent.updatedAt - left.agent.updatedAt || right.index - left.index,
+		);
+
+	for (const { agent } of newestFirst) {
+		const chain = ancestorChain(agent, byId);
+		if (!chain || chain.length - 1 > maxDepth) continue;
+		const missing = chain.filter((candidate) => !selected.has(candidate.id));
+		if (selected.size + missing.length > limits.maxAgents) continue;
+		for (const candidate of missing) selected.add(candidate.id);
+	}
+
+	return agents.filter((agent) => selected.has(agent.id));
+}
+
+function ancestorChain(
+	agent: ManagedAgent,
+	byId: ReadonlyMap<string, ManagedAgent>,
+): ManagedAgent[] | undefined {
+	const chain: ManagedAgent[] = [];
+	const seen = new Set<string>();
+	let current: ManagedAgent | undefined = agent;
+	while (current) {
+		if (seen.has(current.id)) return undefined;
+		seen.add(current.id);
+		chain.unshift(current);
+		if (!current.parentId) return chain;
+		current = byId.get(current.parentId);
+	}
+	return undefined;
+}

package/src/agents.ts

@@ -5,6 +5,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import {
+	type AgentCapabilityManifest,
+	CAPABILITY_MANIFEST_VERSION,
+	normalizeCapabilityManifest,
+} from "./capabilities.js";
 
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
@@ -18,6 +23,12 @@ export type AgentScope = "user" | "project" | "both";
 
 export type AgentSource = "built-in" | "user" | "project";
 
+export const DEFAULT_PI_TOOL_NAMES = ["read", "bash", "edit", "write"] as const;
+
+export function resolveAgentToolNames(tools: readonly string[] | undefined): string[] {
+	return [...new Set(tools ?? DEFAULT_PI_TOOL_NAMES)];
+}
+
 export interface AgentConfig {
 	name: string;
 	description: string;
@@ -25,6 +36,7 @@ export interface AgentConfig {
 	model?: string;
 	thinkingLevel?: SubagentThinkingLevel;
 	timeoutMs?: number;
+	capabilityManifest?: AgentCapabilityManifest;
 	systemPrompt: string;
 	source: AgentSource;
 	filePath: string;
@@ -37,7 +49,7 @@ export interface SubagentAgentConfig {
 	timeoutMs?: number | null;
 }
 
-export type SubagentTransportKind = "subprocess" | "in-process";
+export type SubagentTransportKind = "subprocess" | "in-process" | "rpc" | "auto";
 
 export type CompletionDelivery = "next-turn" | "auto-resume";
 
@@ -66,6 +78,7 @@ export interface SubagentCwdPolicySettings {
 
 export interface SubagentBlockingSettings {
 	enabled?: boolean;
+	maxParallelTasks?: number;
 }
 
 export interface SubagentRuntimeSettings {
@@ -97,6 +110,9 @@ const BUILT_IN_AGENTS: AgentConfig[] = [
 		description:
 			"Read-only codebase reconnaissance; returns concise findings with paths and evidence.",
 		tools: ["read", "grep", "find", "ls", "bash"],
+		capabilityManifest: builtInManifest(["repository-search", "code-evidence"], "read", [
+			"evidence-gathering",
+		]),
 		source: "built-in",
 		filePath: "built-in:scout",
 		systemPrompt: [
@@ -109,6 +125,10 @@ const BUILT_IN_AGENTS: AgentConfig[] = [
 		name: "planner",
 		description: "Turns reconnaissance into a lean implementation or migration plan.",
 		tools: ["read", "grep", "find", "ls"],
+		capabilityManifest: builtInManifest(
+			["task-decomposition", "implementation-planning", "migration-planning"],
+			"read",
+		),
 		source: "built-in",
 		filePath: "built-in:planner",
 		systemPrompt: [
@@ -121,6 +141,11 @@ const BUILT_IN_AGENTS: AgentConfig[] = [
 		name: "reviewer",
 		description: "Independent code review agent that inspects existing verification evidence.",
 		tools: ["read", "grep", "find", "ls", "bash"],
+		capabilityManifest: builtInManifest(
+			["code-review", "evidence-review", "security-baseline"],
+			"read",
+			["independent-review"],
+		),
 		source: "built-in",
 		filePath: "built-in:reviewer",
 		systemPrompt: [
@@ -133,6 +158,10 @@ const BUILT_IN_AGENTS: AgentConfig[] = [
 	{
 		name: "worker",
 		description: "General-purpose implementation worker with the default Pi tool set.",
+		capabilityManifest: builtInManifest(
+			["implementation", "command-execution", "repository-modification"],
+			"write",
+		),
 		source: "built-in",
 		filePath: "built-in:worker",
 		systemPrompt: workerSystemPrompt(),
@@ -140,6 +169,10 @@ const BUILT_IN_AGENTS: AgentConfig[] = [
 	{
 		name: "general",
 		description: "Alias for worker; kept for model-generated subagent names.",
+		capabilityManifest: builtInManifest(
+			["implementation", "command-execution", "repository-modification"],
+			"write",
+		),
 		source: "built-in",
 		filePath: "built-in:general",
 		systemPrompt: workerSystemPrompt(),
@@ -147,12 +180,35 @@ const BUILT_IN_AGENTS: AgentConfig[] = [
 	{
 		name: "general-purpose",
 		description: "Alias for worker; compatible with common subagent naming conventions.",
+		capabilityManifest: builtInManifest(
+			["implementation", "command-execution", "repository-modification"],
+			"write",
+		),
 		source: "built-in",
 		filePath: "built-in:general-purpose",
 		systemPrompt: workerSystemPrompt(),
 	},
 ];
 
+function builtInManifest(
+	capabilities: string[],
+	filesystem: "read" | "write",
+	verificationRoles: string[] = [],
+): AgentCapabilityManifest {
+	return {
+		version: CAPABILITY_MANIFEST_VERSION,
+		capabilities,
+		modalities: ["text"],
+		resultFormats: ["text", "structured-v1", "structured-v2"],
+		authority: { filesystem },
+		verificationRoles,
+		contextStrengths: ["repository"],
+		costHint: filesystem === "read" ? "low" : "medium",
+		latencyHint: filesystem === "read" ? "low" : "medium",
+		limitations: [],
+	};
+}
+
 function workerSystemPrompt(): string {
 	return [
 		"You are a focused worker subagent running in an isolated Pi process.",
@@ -296,6 +352,7 @@ function loadAgentsFromDir(
 			thinkingLevel: isThinkingLevel(frontmatter.thinkingLevel)
 				? frontmatter.thinkingLevel
 				: undefined,
+			capabilityManifest: normalizeCapabilityManifest(frontmatter.capabilityManifest),
 			systemPrompt: body,
 			source,
 			filePath,