@narumitw/pi-subagents 0.53.0 → 0.54.0

package/README.md

@@ -480,7 +480,55 @@ Run an explicit dependency workflow:
 }
 ```
 
-A verification-gated implementation declares one distinct verifier:
+Managed verified execution is an explicit per-workflow contract.
+The executor infers the final mutating integration owner when none is declared, synthesizes one distinct read-only verifier, runs declared deterministic checks in a disposable Git worktree overlaid with the submitted state, and accepts only the exact unchanged submitted state.
+Every deterministic check has a stable evidence ID, a direct executable with argument-array invocation, and an optional relative `cwd` and timeout.
+Only `git`, `node`, `npm`, and `npx` are accepted; shell command strings fail before child allocation.
+The integration owner must request `structured-v2`, declare a non-empty `writePaths` scope, and name current required evidence through its delegation contract.
+Every required evidence ID must match a currently passed executor-owned check; worker-authored artifact metadata never satisfies that binding.
+
+```json
+{
+  "workflow": {
+    "verifiedExecution": {
+      "verifierAgent": "reviewer",
+      "maxReworkCycles": 1,
+      "checks": [
+        {
+          "id": "focused-test",
+          "command": "npm",
+          "args": ["test", "--", "feature"],
+          "timeoutMs": 120000
+        }
+      ]
+    },
+    "tasks": [
+      {
+        "id": "implementation",
+        "agent": "worker",
+        "task": "Implement the contracted change.",
+        "writePaths": ["src", "test"],
+        "acceptanceCriteria": ["The focused regression test passes"],
+        "resultFormat": "structured-v2",
+        "contract": {
+          "version": "pi-subagents:delegation:v2",
+          "level": "full",
+          "taskId": "implementation",
+          "objective": "Implement the contracted change",
+          "requiredEvidence": ["focused-test"],
+          "sideEffectPolicy": "mutating"
+        }
+      }
+    ]
+  }
+}
+```
+
+An advanced caller may provide the verifier task instead of letting the executor synthesize it.
+That task must directly and only depend on the integration owner, use `structured-v2`, select the configured distinct verifier agent, and declare an enforced read-only contract without shell or custom tools.
+The executor narrows accepted verifier authority to `read` even when the selected agent normally has broader tools, and disables verifier extensions, skills, prompt templates, and inherited context files.
+
+The older explicit verifier contract remains available as a compatibility gate without managed integration:
 
 ```json
 {
@@ -528,10 +576,26 @@ A task that explicitly requires independent verification must have exactly one d
 The producer stops in `awaiting-verification`, its own passing verification claims remain untrusted, and ordinary downstream tasks stay blocked until the executor records an accepted verifier receipt.
 The verifier runs alone in a fresh subprocess context against one bounded Git-visible tree identity and must encode `verification-accepted`, `verification-rework`, or `verification-rejected` through the documented `structured-v2` status and reason fields.
 Dirty-tree identity covers at most 1 MiB across separately framed staged and unstaged binary diffs plus bounded non-ignored untracked paths and bytes; submodules, unsupported states, and changing trees fail closed.
-A rework or rejection preserves bounded evidence but does not replay the producer automatically.
-This acceptance gate does not isolate operating-system effects and does not make shared-workspace mutation into manager-controlled patch integration.
-Explicit workflow transitions are also atomically persisted as mode-0600, private-text-redacted snapshots for current-session `list_workflows` and `get_workflow` inspection; running and awaiting-verification tasks inspect as `interrupted`, and no prior side effect is automatically resumed.
-When a v1 ledger is restored, legacy self-reported verification flags and artifact trust are cleared because they have no executor receipt.
+The compatibility gate preserves bounded rework or rejection evidence but does not replay the producer automatically.
+
+With `verifiedExecution`, execution completion and acceptance are separate `pi-subagents:work-acceptance:v1` states.
+A worker's own verification, confidence, prose, consensus, or exit status cannot move `pending` acceptance to `accepted`.
+The executor-owned `pi-subagents:verification-receipt:v1` binds both tree captures, patch digest, changed paths, accepted scope, target and verifier generations and `ExecutionPlan` IDs, verifier identity, acceptance criteria, required current evidence, and bounded deterministic check receipts.
+Each receipt is capped at 12 KiB, each stored check stream at 2 KiB, and oversized acceptance evidence fails closed rather than expanding tool details.
+The verifier receives the original objective, current artifact metadata, immutable tree identity, and executor-owned check output rather than the worker narrative.
+Verifier mutation, a stale or replaced generation, a failed or unsafe check, missing evidence, wrong scope, patch, plan, tree, or identity, cancellation, timeout, and unsupported Git state all produce non-success.
+One verifier `rework` decision may rotate the worker and verifier generations when `maxReworkCycles` is `1`; prior grants are revoked, prior evidence remains history, only current requirements and findings are added, and a second rejection is terminal.
+Crashes, timeouts, cancellation, ambiguous settlement, and drift are never replayed.
+The disposable check worktree includes bounded tracked and non-ignored untracked files and is removed after checks.
+When the repository has a local `node_modules` directory, the worktree is nested beneath it so normal Node and npm resolution can read the installed dependency tree without copying it.
+The worktree isolates repository build output, but it does not make the installed dependency tree read-only and is not an operating-system sandbox for processes, network, secrets, absolute paths, or host credentials.
+The accepted state remains the selected shared workspace; no general patch merge or conflict resolver is added.
+
+Omitting `verifiedExecution` preserves prior workflow behavior, including the older explicit verifier gate above.
+To downgrade, finish active workflows, remove `verifiedExecution`, and either use the explicit `verifierFor` compatibility form or perform verification in the parent.
+Older package versions reject the unknown managed contract rather than silently providing its guarantees.
+Explicit workflow transitions are atomically persisted as mode-0600, private-text-redacted snapshots for current-session `list_workflows` and `get_workflow` inspection; in-flight execution or acceptance restores as interrupted non-success, and no prior side effect is automatically resumed.
+Legacy v1 and v2 records without acceptance fields retain their prior completed terminal meaning, while v1 self-reported verification flags and artifact trust remain untrusted.
 
 ## 🔁 Stateful agents
 
@@ -1010,7 +1074,12 @@ packages/pi-subagents/
 │   ├── execution-plan.ts         # Executor-owned authority and resource resolution
 │   ├── work-item-ledger.ts       # Persistent dependency and artifact state machine
 │   ├── work-item-persistence.ts  # Atomic redacted workflow state and inspection
-│   ├── workflow-verification.ts  # Executor-owned independent-verifier receipts
+│   ├── workflow-verification.ts  # Compatibility independent-verifier receipts
+│   ├── verified-execution-contract.ts # Explicit managed-verification request boundary
+│   ├── workflow-completion-controller.ts # Sole opted-in terminal acceptance owner
+│   ├── verification-harness.ts   # Disposable deterministic check execution
+│   ├── verification-receipt.ts   # Strict executor-owned managed receipts
+│   ├── verified-execution-benchmark.ts # Matched offline acceptance/cost fixture
 │   ├── workflow-tree-identity.ts # Bounded exact Git-visible tree identities
 │   ├── integration-controller.ts # Fail-closed canonical integration admission
 │   ├── adaptive-scheduler.ts     # Dependency, capacity, budget, and conflict scheduling

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.53.0",
+	"version": "0.54.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/agents/built-ins.ts

@@ -0,0 +1,124 @@
+/**
+ * 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: "scout",
+		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: [
+			"You are a scout subagent. Explore the codebase quickly and report grounded findings.",
+			"Do not edit files. Prefer read, grep, find, ls, and safe bash inspection commands.",
+			"Return concise bullets with exact file paths, symbols, and open questions.",
+		].join("\n"),
+	},
+	{
+		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: [
+			"You are a planner subagent. Produce executable, verifiable plans only.",
+			"Do not modify files. Ground the plan in the repository's actual structure.",
+			"Call out assumptions, risks, sequencing, and verification commands.",
+		].join("\n"),
+	},
+	{
+		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: [
+			"You are a reviewer subagent. Review changes adversarially and assess claims against the code and existing evidence.",
+			"Do not edit files or run tests, builds, benchmarks, formatters, or other long-running verification commands.",
+			"Inspect code, diffs, test definitions, and existing verification evidence. Recommend any additional commands for the main agent to run.",
+			"Report PASS, FAIL, or PARTIAL with evidence, commands inspected, and specific follow-ups.",
+		].join("\n"),
+	},
+	{
+		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(),
+	},
+	{
+		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(),
+	},
+	{
+		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(),
+	},
+];
+
+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 process.",
+		"Complete the delegated task directly. Keep scope tight and avoid unrelated changes.",
+		"When done, summarize files changed, commands run, and any remaining risks.",
+	].join("\n");
+}

package/src/agents/catalog.ts

@@ -0,0 +1,224 @@
+/**
+ * Bounded, sanitized model-facing agent catalog formatting.
+ */
+
+import { BUILT_IN_AGENTS } from "./built-ins.js";
+import {
+	type AgentDiscoveryOptions,
+	type AgentDiscoveryResult,
+	discoverAgents,
+} from "./discovery.js";
+import type { AgentConfig, SubagentSettings } from "./types.js";
+
+export function formatAgentList(
+	agents: AgentConfig[],
+	maxItems: number,
+): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	const remaining = agents.length - listed.length;
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining,
+	};
+}
+
+export interface AgentCatalog {
+	/** The effective catalog for the default invocation scope. */
+	user: AgentDiscoveryResult;
+	/** The project-scope catalog; custom project definitions are loaded only after project trust. */
+	project?: AgentDiscoveryResult;
+}
+
+export interface AgentCatalogFormatOptions {
+	maxItems?: number;
+	maxDescriptionLength?: number;
+	maxCharacters?: number;
+}
+
+export interface AgentCatalogFormatResult {
+	text: string;
+	omitted: number;
+}
+
+export const DEFAULT_AGENT_CATALOG_MAX_ITEMS = 32;
+export const DEFAULT_AGENT_CATALOG_MAX_DESCRIPTION_LENGTH = 240;
+export const DEFAULT_AGENT_CATALOG_MAX_CHARACTERS = 6_000;
+export const DEFAULT_AGENT_CATALOG_MAX_FILES_PER_SCOPE = 128;
+export const DEFAULT_AGENT_CATALOG_MAX_FILE_BYTES = 64 * 1024;
+export const DEFAULT_AGENT_CATALOG_MAX_TOTAL_BYTES_PER_SCOPE = 2 * 1024 * 1024;
+
+const BUILT_IN_AGENT_ORDER = new Map(BUILT_IN_AGENTS.map((agent, index) => [agent.name, index]));
+
+function compareCatalogAgents(left: AgentConfig, right: AgentConfig): number {
+	const leftBuiltInOrder = BUILT_IN_AGENT_ORDER.get(left.name);
+	const rightBuiltInOrder = BUILT_IN_AGENT_ORDER.get(right.name);
+	if (leftBuiltInOrder !== undefined || rightBuiltInOrder !== undefined) {
+		if (leftBuiltInOrder === undefined) return 1;
+		if (rightBuiltInOrder === undefined) return -1;
+		return leftBuiltInOrder - rightBuiltInOrder;
+	}
+	return left.name.localeCompare(right.name);
+}
+
+function normalizeCatalogDescription(description: string, maxLength: number): string {
+	const normalized = description.replace(/\s+/gu, " ").trim();
+	if (normalized.length <= maxLength) return normalized;
+	const suffix = "…";
+	return `${normalized.slice(0, Math.max(0, maxLength - suffix.length)).trimEnd()}${suffix}`;
+}
+
+type CatalogScope = "user" | "project" | "project-fallback";
+
+function catalogAgentLine(
+	agent: AgentConfig,
+	scope: CatalogScope,
+	userNames: ReadonlySet<string>,
+	maxDescriptionLength: number,
+): string {
+	const scopeLabel =
+		scope === "user"
+			? 'agentScope: "user"'
+			: scope === "project"
+				? 'requires agentScope: "project" or "both"'
+				: 'requires agentScope: "project" ("both" selects the user definition)';
+	const collision =
+		scope !== "user" && userNames.has(agent.name)
+			? scope === "project"
+				? "; overrides the default user definition for project/both"
+				: "; scope-specific fallback for the default user override"
+			: "";
+	return `- ${agent.name} [source: ${agent.source}; ${scopeLabel}${collision}] — ${normalizeCatalogDescription(agent.description, maxDescriptionLength)}`;
+}
+
+/**
+ * Format the effective agent variants that the parent model can invoke.
+ *
+ * User-authored descriptions are prompt text, so this formatter deliberately normalizes and bounds
+ * them. Project definitions are supplied separately by the caller so an untrusted project is never
+ * read merely to build model-facing metadata.
+ */
+export function formatAgentCatalog(
+	catalog: AgentCatalog,
+	options: AgentCatalogFormatOptions = {},
+): AgentCatalogFormatResult {
+	const maxItems = Math.max(0, options.maxItems ?? DEFAULT_AGENT_CATALOG_MAX_ITEMS);
+	const maxDescriptionLength = Math.max(
+		1,
+		options.maxDescriptionLength ?? DEFAULT_AGENT_CATALOG_MAX_DESCRIPTION_LENGTH,
+	);
+	const maxCharacters = Math.max(1, options.maxCharacters ?? DEFAULT_AGENT_CATALOG_MAX_CHARACTERS);
+	const userDiscoveryIncomplete =
+		(catalog.user.omittedAgentDefinitions ?? 0) > 0 ||
+		catalog.user.metadataDiscoveryIncomplete === true;
+	const projectDiscoveryIncomplete =
+		(catalog.project?.omittedAgentDefinitions ?? 0) > 0 ||
+		catalog.project?.metadataDiscoveryIncomplete === true;
+	const discoveredUserAgents = [...catalog.user.agents].sort(compareCatalogAgents);
+	const discoveredProjectScopeAgents = [...(catalog.project?.agents ?? [])].sort(
+		compareCatalogAgents,
+	);
+	const userAgents = userDiscoveryIncomplete ? [] : discoveredUserAgents;
+	const projectScopeAgents = projectDiscoveryIncomplete ? [] : discoveredProjectScopeAgents;
+	const projectAgents = projectScopeAgents.filter((agent) => agent.source === "project");
+	const discoveredUserByName = new Map(discoveredUserAgents.map((agent) => [agent.name, agent]));
+	const userByName = new Map(userAgents.map((agent) => [agent.name, agent]));
+	const userNames = new Set(userByName.keys());
+	const potentialProjectFallbackAgents = discoveredProjectScopeAgents.filter(
+		(agent) =>
+			agent.source === "built-in" && discoveredUserByName.get(agent.name)?.source === "user",
+	);
+	const projectFallbackAgents =
+		userDiscoveryIncomplete || projectDiscoveryIncomplete ? [] : potentialProjectFallbackAgents;
+	const allEntries = [
+		...userAgents.map((agent) => ({ agent, scope: "user" as const })),
+		...projectAgents.map((agent) => ({ agent, scope: "project" as const })),
+		...projectFallbackAgents.map((agent) => ({ agent, scope: "project-fallback" as const })),
+	];
+	const boundedEntries = allEntries.slice(0, maxItems);
+	const suppressedMetadataEntries =
+		(userDiscoveryIncomplete ? discoveredUserAgents.length : 0) +
+		(projectDiscoveryIncomplete
+			? discoveredProjectScopeAgents.filter((agent) => agent.source === "project").length +
+				potentialProjectFallbackAgents.length
+			: 0);
+	const discoveryOmissions =
+		(catalog.user.omittedAgentDefinitions ?? 0) +
+		(catalog.project?.omittedAgentDefinitions ?? 0) +
+		suppressedMetadataEntries;
+	const discoveryIncomplete =
+		catalog.user.metadataDiscoveryIncomplete === true ||
+		catalog.project?.metadataDiscoveryIncomplete === true;
+
+	const render = (entries: typeof allEntries, omitted: number): string => {
+		const lines = [
+			"Available agent definitions (metadata only; runtime validation and trust remain authoritative).",
+		];
+		const userLines = entries
+			.filter((entry) => entry.scope === "user")
+			.map((entry) => catalogAgentLine(entry.agent, entry.scope, userNames, maxDescriptionLength));
+		if (userLines.length > 0) {
+			lines.push('Default scope (agentScope: "user"):');
+			lines.push(...userLines);
+		}
+		const projectLines = entries
+			.filter((entry) => entry.scope !== "user")
+			.map((entry) => catalogAgentLine(entry.agent, entry.scope, userNames, maxDescriptionLength));
+		if (projectLines.length > 0) {
+			lines.push("Trusted project/scope variants (use the required agentScope shown):");
+			lines.push(...projectLines);
+		}
+		const collisionNames = entries
+			.filter((entry) => entry.scope !== "user" && userNames.has(entry.agent.name))
+			.map((entry) => entry.agent.name);
+		if (collisionNames.length > 0 && projectLines.length > 0) {
+			const precedence = entries
+				.filter((entry) => entry.scope !== "user" && userNames.has(entry.agent.name))
+				.map((entry) =>
+					entry.scope === "project"
+						? `${entry.agent.name}: user with "user", project with "project"/"both"`
+						: `${entry.agent.name}: user with "user"/"both", built-in with "project"`,
+				);
+			lines.push(`Same-name precedence: ${precedence.join("; ")}.`);
+		}
+		if (omitted > 0) {
+			lines.push(
+				`[${omitted} additional agent definition${omitted === 1 ? "" : "s"} omitted due to metadata bounds or incomplete discovery.]`,
+			);
+		}
+		if (discoveryIncomplete) {
+			lines.push("[Agent metadata discovery was incomplete; some definitions may be unavailable.]");
+		}
+		return lines.join("\n");
+	};
+
+	let listedCount = boundedEntries.length;
+	let text = render(
+		boundedEntries.slice(0, listedCount),
+		allEntries.length - listedCount + discoveryOmissions,
+	);
+	while (text.length > maxCharacters && listedCount > 0) {
+		listedCount -= 1;
+		text = render(
+			boundedEntries.slice(0, listedCount),
+			allEntries.length - listedCount + discoveryOmissions,
+		);
+	}
+	return { text, omitted: allEntries.length - listedCount + discoveryOmissions };
+}
+
+export function discoverAgentCatalog(
+	cwd: string,
+	projectTrusted: boolean,
+	config?: SubagentSettings,
+): AgentCatalog {
+	const options: AgentDiscoveryOptions = {
+		maxFiles: DEFAULT_AGENT_CATALOG_MAX_FILES_PER_SCOPE,
+		maxFileBytes: DEFAULT_AGENT_CATALOG_MAX_FILE_BYTES,
+		maxTotalBytes: DEFAULT_AGENT_CATALOG_MAX_TOTAL_BYTES_PER_SCOPE,
+	};
+	return {
+		user: discoverAgents(cwd, "user", config, options),
+		project: projectTrusted ? discoverAgents(cwd, "project", config, options) : undefined,
+	};
+}