@narumitw/pi-subagents 2.1.4 → 3.0.0

package/docs/pi-subagents-diagrams.md

@@ -1,183 +0,0 @@
-# pi-subagents Architecture Diagrams
-
-These diagrams describe the main `pi-subagents` components, detached-agent lifecycle, transport selection, and verified workflow.
-
-## Overall architecture
-
-```mermaid
-flowchart TB
-    Root["Main Pi Agent<br/>Planning, integration, verification, and final answer"]
-    Extension["pi-subagents Extension"]
-    Settings["User Settings<br/>pi-subagents.json"]
-    Catalog["Agent Catalog<br/>built-in / user / project"]
-    UI["/subagents Manager<br/>pi-tui-kit"]
-
-    Root --> Extension
-    Settings --> Extension
-    Catalog --> Extension
-    UI <--> Extension
-
-    subgraph Surfaces["Tool Surfaces"]
-        Blocking["subagent<br/>Blocking workflows"]
-        Consult["subagent_consult<br/>Synchronous read-only consultation"]
-        Stateful["Detached lifecycle<br/>spawn / send / manage / mailbox"]
-        Inspect["subagent_inspect<br/>Read-only diagnostics"]
-    end
-
-    Extension --> Blocking
-    Extension --> Consult
-    Extension --> Stateful
-    Extension --> Inspect
-
-    Blocking --> BlockingExecution["Blocking Execution<br/>single / parallel / chain / workflow / panel"]
-    Consult --> ConsultPolicy["Read-only tool intersection<br/>read / grep / find / ls"]
-    Stateful --> Registry["Agent Registry<br/>queue / generations / hierarchy"]
-    Inspect --> Snapshots["Safe projections<br/>runs / workflows / models / status"]
-
-    Registry --> Persistence["Persistent State and Completion Outbox"]
-    Registry --> TransportSelector["Transport Selector"]
-    BlockingExecution --> Runner["Subprocess Runner"]
-    ConsultPolicy --> Runner
-
-    TransportSelector --> InProcess["In-process<br/>Low startup overhead"]
-    TransportSelector --> RPC["Retained RPC process<br/>Process isolation and retained history"]
-    TransportSelector --> Subprocess["Fresh subprocess<br/>Custom-tool compatibility"]
-
-    Registry --> Delivery["Completion Routing"]
-    Delivery --> Root
-```
-
-## Detached-agent execution and completion delivery
-
-```mermaid
-sequenceDiagram
-    participant R as Root Agent
-    participant E as Extension
-    participant P as Policy / Preflight
-    participant G as Agent Registry
-    participant T as Transport
-    participant S as Persistent State
-    participant D as Completion Broker
-
-    R->>E: subagent_spawn(task, contract, budgets)
-    E->>P: Check cwd, trust, agent scope, and capacity
-    P-->>E: Approved execution plan
-    E->>G: Create agent, generation, and runId
-    G->>S: Persist starting / queued state
-    E-->>R: Immediately return agentId and taskPath
-
-    Note over R: Root continues non-overlapping local work
-
-    G->>T: runTurn() when capacity is available
-    T-->>G: Bounded progress / telemetry
-    T-->>G: Terminal outcome
-
-    G->>G: Classify completed / failed / blocked / interrupted
-    G->>G: Create completionId and outbox record
-    G->>S: Persist terminal state and completion first
-    S-->>G: Durable
-
-    G->>D: Route to the direct parent or nearest live ancestor
-
-    alt next-turn
-        D-->>R: Steer without waking an idle root
-    else auto-resume
-        D-->>R: Trigger a synthesis turn after the root settles
-    end
-
-    R->>E: subagent_send(agentId, follow-up)
-    E->>G: Start a new generation while retaining agent history
-    G->>T: Execute the follow-up
-
-    R->>E: subagent_manage(close)
-    E->>G: Release descendants child-first
-    G->>T: Shutdown / release
-    G->>S: Update or remove retained state
-```
-
-The system persists each completion before notifying its parent so that a process interruption does not permanently lose the result.
-
-## Automatic transport selection
-
-```mermaid
-flowchart TD
-    Start["Create a detached agent"]
-    Explicit{"Was transport explicitly selected?"}
-    UseExplicit["Use the selected transport"]
-    BuiltIn{"Are all effective tools<br/>Pi built-in tools?"}
-    ReadOnly{"Is the tool set read-only?"}
-    InProcess["in-process<br/>Retained SDK session"]
-    RPC["rpc<br/>Retained independent Pi process"]
-    Subprocess["subprocess<br/>Fresh process for each turn"]
-    Run["Create the child and accept the prompt"]
-    Failure["Startup or execution failure<br/>Report failure without switching transport"]
-    Note["After a child is created or may have accepted work,<br/>automatic fallback is forbidden to prevent duplicate side effects"]
-
-    Start --> Explicit
-    Explicit -- "Yes" --> UseExplicit
-    Explicit -- "No, use auto" --> BuiltIn
-
-    BuiltIn -- "No, includes extension/custom tools" --> Subprocess
-    BuiltIn -- "Yes" --> ReadOnly
-
-    ReadOnly -- "Yes" --> InProcess
-    ReadOnly -- "No, includes bash/edit/write" --> RPC
-
-    UseExplicit --> Run
-    InProcess --> Run
-    RPC --> Run
-    Subprocess --> Run
-    Run --> Failure
-    Failure -.-> Note
-```
-
-Read-only classification is based on effective tool permissions rather than promises written in the task prompt.
-
-## Verified workflow and acceptance barrier
-
-```mermaid
-flowchart TD
-    Request["Caller-authored workflow"]
-    Validate["Validate DAG, contracts, dependencies, and budgets"]
-    Preflight["Preflight every cwd, agent, scope, and authority"]
-    Ledger["Create the WorkItem Ledger"]
-    Scheduler["Adaptive Scheduler<br/>dependency / capacity / budget / conflict"]
-    Worker["Execute Worker"]
-    Result["Parse structured-v2<br/>Record artifacts and tree identity"]
-    NeedsVerify{"Is independent verification required?"}
-    OrdinaryDone["Complete the ordinary workflow item"]
-
-    Checks["Run executor-owned checks<br/>in a disposable worktree"]
-    ChecksPass{"Did every check pass?"}
-    Verifier["Independent read-only Verifier<br/>Different agent and generation"]
-    Receipt["Create verification receipt<br/>Bind patch, tree, plan, and evidence"]
-    Decision{"Verifier decision"}
-
-    Accept["Acceptance Controller<br/>Mark accepted"]
-    Rework{"Is rework capacity available?"}
-    Rotate["Revoke old grants<br/>Rotate worker/verifier generations"]
-    Reject["rejected / non-success"]
-    Finish["Workflow terminal result"]
-
-    Request --> Validate --> Preflight --> Ledger --> Scheduler
-    Scheduler --> Worker --> Result --> NeedsVerify
-
-    NeedsVerify -- "No" --> OrdinaryDone --> Finish
-    NeedsVerify -- "Yes" --> Checks
-    Checks --> ChecksPass
-    ChecksPass -- "No" --> Reject
-    ChecksPass -- "Yes" --> Verifier
-    Verifier --> Receipt --> Decision
-
-    Decision -- "accepted" --> Accept --> Finish
-    Decision -- "rework" --> Rework
-    Decision -- "rejected" --> Reject
-
-    Rework -- "Yes, at most once" --> Rotate --> Scheduler
-    Rework -- "No" --> Reject
-    Reject --> Finish
-```
-
-A worker's own claim that verification passed cannot move acceptance from `pending` to `accepted`.
-
-Only executor-owned checks, an independent verifier, and the acceptance controller can complete acceptance.

package/src/adaptive-scheduler.ts

@@ -1,224 +0,0 @@
-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"
-	| "verification-barrier";
-
-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 readyVerifier = ready.find((item) => item.verifierFor !== undefined);
-		if (readyVerifier) {
-			const verifierMayStart = effectiveConcurrency > 0 && options.activeCount === 0;
-			return {
-				policy: ADAPTIVE_SCHEDULER_POLICY,
-				workflowId: snapshot.workflowId,
-				workflowGeneration: snapshot.generation,
-				effectiveConcurrency: verifierMayStart ? 1 : 0,
-				selected: verifierMayStart ? [readyVerifier.id] : [],
-				decisions: snapshot.items
-					.map((item) => ({
-						id: item.id,
-						reason:
-							item.id === readyVerifier.id
-								? verifierMayStart
-									? ("selected" as const)
-									: ("capacity-exhausted" as const)
-								: item.state === "ready"
-									? ("verification-barrier" as const)
-									: item.state === "pending"
-										? ("dependency-not-ready" as const)
-										: ("state-not-ready" as const),
-						criticalPathDepth: depth.get(item.id) ?? 0,
-					}))
-					.sort((left, right) => left.id.localeCompare(right.id)),
-			};
-		}
-		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-policy.ts

@@ -1,78 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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/built-ins.ts

@@ -1,71 +0,0 @@
-/**
- * Built-in agent definitions and prompt construction.
- */
-
-import { type AgentCapabilityManifest, CAPABILITY_MANIFEST_VERSION } from "../capabilities.js";
-import type { AgentConfig } from "./types.js";
-
-export const BUILT_IN_AGENTS: AgentConfig[] = [
-	{
-		name: "explorer",
-		description:
-			"Read-only codebase exploration for specific questions; returns concise findings with paths and evidence.",
-		tools: ["read", "grep", "find", "ls"],
-		capabilityManifest: builtInManifest(["repository-search", "code-evidence"], "read", [
-			"evidence-gathering",
-		]),
-		thinkingLevel: "low",
-		source: "built-in",
-		filePath: "built-in:explorer",
-		systemPrompt: [
-			"You are an explorer subagent. Explore the codebase for specific, well-scoped questions and report grounded findings.",
-			"Do not edit files, run shell commands, or use any tool outside the read-only inspection set.",
-			"Do not install dependencies, run formatters, start servers, run tests, or execute long-running commands.",
-			"Return concise bullets with exact file paths, symbols, and open questions.",
-		].join("\n"),
-	},
-	{
-		name: "worker",
-		description: "Bounded implementation and command-execution worker with clear ownership.",
-		capabilityManifest: builtInManifest(
-			["implementation", "command-execution", "repository-modification"],
-			"write",
-		),
-		source: "built-in",
-		filePath: "built-in:worker",
-		systemPrompt: workerSystemPrompt(),
-	},
-];
-
-export function getBuiltInAgent(name: string): AgentConfig | undefined {
-	const agent = BUILT_IN_AGENTS.find((candidate) => candidate.name === name);
-	return agent ? structuredClone(agent) : undefined;
-}
-
-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 child context.",
-		"Complete only the bounded delegated implementation slice and respect its assigned file or responsibility ownership.",
-		"Keep scope tight, avoid unrelated changes, and do not overwrite concurrent work outside your ownership.",
-		"The main agent owns integration and final verification; report changed files, commands run, and remaining risks for that handoff.",
-	].join("\n");
-}