@selesai/code 0.5.28 → 0.6.1

package/dist/extensions/pi-subagents/test/unit/task-aware-routing.test.ts

@@ -0,0 +1,213 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	formatTaskAwareAgentRecommendation,
+	recommendTaskAwareAgent,
+} from "../../src/agents/task-aware-routing.ts";
+import type { AgentConfig } from "../../src/agents/agents.ts";
+
+function agent(name: string, overrides: Partial<AgentConfig> = {}): AgentConfig {
+	return {
+		name,
+		description: `${name} agent`,
+		systemPrompt: `${name} prompt`,
+		systemPromptMode: "append",
+		inheritProjectContext: false,
+		inheritSkills: false,
+		source: "builtin",
+		filePath: `/tmp/${name}.md`,
+		...overrides,
+	};
+}
+
+describe("recommendTaskAwareAgent", () => {
+	it("no-ops for empty or whitespace-only tasks", () => {
+		assert.equal(recommendTaskAwareAgent({ task: "", agents: [] }), undefined);
+		assert.equal(recommendTaskAwareAgent({ task: "   \n\t ", agents: [] }), undefined);
+	});
+
+	it("recommends a canonical writer for an implementation task, never a read-only agent", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("commentator", { tools: ["read", "grep"] }),
+				agent("builder"),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.intent, "implementation");
+		assert.equal(recommendation.agent?.name, "builder");
+		assert.equal(recommendation.agent?.role, "writer");
+		assert.equal(recommendation.agent?.roleBasis, "inferred");
+	});
+
+	it("recommends a read-only agent without known write tools, never a writer", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Review only; do not edit files",
+			agents: [
+				agent("builder"),
+				agent("commentator", { tools: ["read", "grep", "find", "ls"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.intent, "read-only");
+		assert.equal(recommendation.agent?.name, "commentator");
+		assert.equal(recommendation.agent?.role, "read-only");
+		assert.equal(recommendation.agent?.roleBasis, "inferred");
+	});
+
+	it("never recommends a read-only agent whose tools are unset or include bash", () => {
+		for (const candidate of [
+			agent("commentator"),
+			agent("commentator", { tools: ["read", "bash"] }),
+		]) {
+			const recommendation = recommendTaskAwareAgent({
+				task: "Review only; do not edit files",
+				agents: [candidate],
+			});
+			assert.ok(recommendation);
+			assert.equal(recommendation.agent, undefined);
+			assert.match(recommendation.next ?? "", /read-only role without known write tools/);
+		}
+	});
+
+	it("gives recovery guidance, not a guess, for unknown intent", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Look into this",
+			agents: [agent("builder"), agent("commentator", { tools: ["read", "grep"] })],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.intent, "unknown");
+		assert.equal(recommendation.agent, undefined);
+		assert.match(recommendation.next ?? "", /Clarify whether the task is read-only analysis\/review or implementation allowed to edit files/);
+	});
+
+	it("excludes disabled agents even when they match the task role", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("builder", { disabled: true }),
+				agent("fixer", { source: "project", acceptanceRole: "writer", tools: ["edit"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "fixer");
+	});
+
+	it("excludes agents denied by the capability ceiling allowedAgents", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [agent("builder"), agent("fixer", { source: "project", acceptanceRole: "writer", tools: ["edit"] })],
+			capabilityCeiling: { version: 1, allowedAgents: ["builder"], denyExtensions: false, sources: ["plan"] },
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "builder");
+	});
+
+	it("refuses a writer recommendation when allowedTools has no writer tool", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [agent("builder")],
+			capabilityCeiling: { version: 1, allowedTools: ["read", "grep"], denyExtensions: false, sources: ["plan"] },
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.intent, "implementation");
+		assert.equal(recommendation.agent, undefined);
+		assert.match(recommendation.next ?? "", /capability ceiling/);
+	});
+
+	it("recommends a writer when allowedTools includes a writer tool", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [agent("builder")],
+			capabilityCeiling: { version: 1, allowedTools: ["read", "edit"], denyExtensions: false, sources: ["plan"] },
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "builder");
+	});
+
+	it("prefers project over user, package, and builtin candidates", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("builder", { source: "builtin" }),
+				agent("builder", { source: "package" }),
+				agent("builder", { source: "user" }),
+				agent("builder", { source: "project" }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "builder");
+		assert.equal(recommendation.agent?.source, "project");
+	});
+
+	it("sorts equal candidates by canonical name", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("zeta-builder", { source: "user", acceptanceRole: "writer", tools: ["edit"] }),
+				agent("alpha-builder", { source: "user", acceptanceRole: "writer", tools: ["edit"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "alpha-builder");
+	});
+
+	it("prefers a declared role over an inferred role at the same source", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("builder", { source: "user" }),
+				agent("fixer", { source: "user", acceptanceRole: "writer", tools: ["edit"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "fixer");
+		assert.equal(recommendation.agent?.roleBasis, "declared");
+	});
+
+	it("never emits an alias as the recommended launch name", () => {
+		const recommendation = recommendTaskAwareAgent({
+			task: "Implement the fix",
+			agents: [
+				agent("canonical-builder", { aliases: ["developer"], source: "user", acceptanceRole: "writer", tools: ["edit"] }),
+			],
+		});
+		assert.ok(recommendation);
+		assert.equal(recommendation.agent?.name, "canonical-builder");
+	});
+});
+
+describe("formatTaskAwareAgentRecommendation", () => {
+	it("renders nothing for an empty-task no-op", () => {
+		assert.deepEqual(formatTaskAwareAgentRecommendation(undefined), []);
+	});
+
+	it("renders a safe recommendation with the canonical agent and explicit-launch note", () => {
+		const lines = formatTaskAwareAgentRecommendation({
+			intent: "implementation",
+			agent: { name: "builder", source: "project", role: "writer", roleBasis: "declared", reason: "declared writer role with write tools" },
+		});
+		assert.deepEqual(lines, [
+			"Task-aware advisory routing:",
+			"- Intent: implementation",
+			"- Recommended: builder (project)",
+			"- Reason: declared writer role with write tools",
+			"- Advisory only: no subagent was launched. To proceed, explicitly call subagent with this canonical agent name and the task.",
+		]);
+	});
+
+	it("renders recovery guidance without an agent name", () => {
+		const lines = formatTaskAwareAgentRecommendation({
+			intent: "unknown",
+			next: "Clarify whether the task is read-only analysis/review or implementation allowed to edit files.",
+		});
+		assert.deepEqual(lines, [
+			"Task-aware advisory routing:",
+			"- Intent: unknown",
+			"- Recommendation: none",
+			"- Next: Clarify whether the task is read-only analysis/review or implementation allowed to edit files.",
+			"- Advisory only: no subagent was launched.",
+		]);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/task-intent.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { classifyTaskMutationIntent, expectsImplementationMutation, taskMayMutate } from "../../src/runs/shared/task-intent.ts";
+import { classifyTaskMutationIntent, expectsImplementationMutation, resolveAgentRoutingRole, taskMayMutate } from "../../src/runs/shared/task-intent.ts";
 
 describe("classifyTaskMutationIntent", () => {
 	it("keeps write imperatives despite investigative wording", () => {
@@ -38,6 +38,9 @@ describe("classifyTaskMutationIntent", () => {
 		assert.equal(classifyTaskMutationIntent("builder", "Do not edit files. Tell me how to fix the bug.").kind, "read-only");
 		assert.equal(classifyTaskMutationIntent("builder", "Report on the extraction pipeline. Do not modify project/source files.").kind, "read-only");
 		assert.equal(classifyTaskMutationIntent("commentator", "Final correctness review after prior fixes. Inspect all changed files and tests. Do not modify project/source files. Report findings.").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("builder", `Verification-only task. Do not edit product/source/config files.
+   Run a disposable check, delete its temporary harness, and retain only
+   a sanitized report at an explicitly named artifact path.`).kind, "read-only");
 	});
 
 	it("strips repeated prohibition phrases before testing write intent", () => {
@@ -66,6 +69,28 @@ describe("classifyTaskMutationIntent", () => {
 	});
 });
 
+describe("resolveAgentRoutingRole", () => {
+	it("lets a declared acceptanceRole override name heuristics", () => {
+		assert.equal(resolveAgentRoutingRole("commentator", "writer"), "writer");
+		assert.equal(resolveAgentRoutingRole("builder", "read-only"), "read-only");
+		assert.equal(resolveAgentRoutingRole("custom-agent", "writer"), "writer");
+		assert.equal(resolveAgentRoutingRole("custom-agent", "read-only"), "read-only");
+	});
+
+	it("infers writer for builder-named agents and read-only for reviewer-style names", () => {
+		assert.equal(resolveAgentRoutingRole("builder"), "writer");
+		assert.equal(resolveAgentRoutingRole("package.builder"), "writer");
+		for (const name of ["architect", "commentator", "explorer", "recapper", "researcher", "analyst"]) {
+			assert.equal(resolveAgentRoutingRole(name), "read-only", name);
+		}
+	});
+
+	it("returns undefined for names without an established role", () => {
+		assert.equal(resolveAgentRoutingRole("custom-agent"), undefined);
+		assert.equal(resolveAgentRoutingRole("reviewer"), undefined);
+	});
+});
+
 describe("taskMayMutate", () => {
 	it("treats any bare write verb as write-capable", () => {
 		for (const task of ["Write the code", "Commit the changes", "Delete temporary data", "Remove obsolete assets", "Update dependencies"]) {

package/dist/extensions/pi-subagents/test/unit/tool-description.test.ts

@@ -9,8 +9,10 @@ import {
 	buildSubagentToolDescription,
 	COMPACT_SUBAGENT_TOOL_DESCRIPTION,
 	FULL_SUBAGENT_TOOL_DESCRIPTION,
+	SUBAGENT_PARENT_ROUTING_GUIDANCE,
 	SUBAGENT_SAFETY_GUIDANCE,
 } from "../../src/extension/tool-description.ts";
+import { BUILTIN_AGENT_NAMES } from "../../src/agents/agents.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../../src/runs/shared/pi-args.ts";
 
 const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -31,9 +33,12 @@ describe("registered subagent tool description", () => {
 	it("keeps full mode safe and free of hardcoded builtin agent names", () => {
 		const description = buildSubagentToolDescription();
 
-		for (const builtinName of ["scout", "worker", "planner"]) {
+		for (const builtinName of BUILTIN_AGENT_NAMES) {
 			assert.doesNotMatch(description, new RegExp(`\\b${builtinName}\\b`));
 		}
+		for (const legacyName of ["scout", "worker", "planner"]) {
+			assert.doesNotMatch(description, new RegExp(`\\b${legacyName}\\b`));
+		}
 		assert.match(description, /^To delegate work, call with \{ agent, task \}, \{ tasks \}, or \{ chain \}; omit action\./i);
 		assert.match(description, /Use action only for management\/control actions listed below/i);
 		assert.match(description, /use \{ action: "list" \} to inspect configured agents\/chains/i);
@@ -50,6 +55,11 @@ describe("registered subagent tool description", () => {
 		assert.doesNotMatch(description, /only for foreground runs/i);
 		assert.doesNotMatch(description, /omit for async\/background runs/i);
 		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
+		assert.match(description, /PARENT-ONLY SUBAGENT ROUTING/);
+		assert.match(description, /call \{ action: "list" \} and select only an executable entry using its current role, context, and tool metadata/i);
+		assert.match(description, /Keep tiny targeted reads and simple answers local/i);
+		assert.match(description, /broad local investigation, external research, and mutation\/implementation work/i);
+		assert.match(description, /parent remains the decision-maker and normally the sole writer/i);
 		assert.match(description, /Do not sleep or poll status just to wait/i);
 		assert.match(description, /use subagent_wait/i);
 		assert.match(description, /interactive session.*normally return control/i);
@@ -62,6 +72,10 @@ describe("registered subagent tool description", () => {
 		assert.match(description, /action: "steer"/);
 		assert.match(description, /schedule-list/);
 		assert.match(description, /action: "eject"/);
+		assert.match(description, /action: "eject", agent: "agent-name"/);
+		assert.match(description, /action: "disable", agent: "agent-name"/);
+		assert.match(description, /action: "enable", agent: "agent-name"/);
+		assert.match(description, /action: "reset", agent: "agent-name"/);
 		assert.match(description, /action: "disable"/);
 		assert.match(description, /action: "grant-spawn-budget"/);
 		assert.match(description, /root interactive parent/i);
@@ -97,6 +111,14 @@ describe("registered subagent tool description", () => {
 		assert.match(description, /PARALLEL/);
 		assert.match(description, /CHAIN/);
 		assert.match(description, /action without execution fields/i);
+		assert.match(description, /Parent-only routing/);
+		assert.match(description, /select only an executable entry using its current role, context, and tool metadata/i);
+		assert.match(description, /Keep tiny targeted reads and simple answers local/i);
+		assert.match(description, /broad local investigation, external research, and mutation\/implementation work/i);
+		assert.match(description, /parent remains the decision-maker and normally the sole writer/i);
+		for (const builtinName of BUILTIN_AGENT_NAMES) {
+			assert.doesNotMatch(description, new RegExp(`\\b${builtinName}\\b`));
+		}
 		assert.match(description, /subagent_wait/i);
 		assert.match(description, /interactive session.*normally return control/i);
 		assert.match(description, /Non-interactive runs.*auto-drain current-session work at agent_end/i);
@@ -127,6 +149,15 @@ describe("registered subagent tool description", () => {
 		assert.match(description, /count:/);
 	});
 
+	it("documents task-aware list advice as explicit-only in both modes", () => {
+		for (const description of [FULL_SUBAGENT_TOOL_DESCRIPTION, COMPACT_SUBAGENT_TOOL_DESCRIPTION]) {
+			assert.match(description, /\{ action: "list", task: "\.\.\." \}/);
+			assert.match(description, /advisory/i);
+			assert.match(description, /never launches/i);
+			assert.match(description, /explicitly call subagent|execute the recommended agent explicitly/i);
+		}
+	});
+
 	it("renders a custom project description with placeholders and mandatory safety guidance", () => {
 		const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-project-"));
 		const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-agent-"));
@@ -148,6 +179,8 @@ describe("registered subagent tool description", () => {
 		assert.match(description, new RegExp(escapeRegex(agentDir)));
 		assert.match(description, new RegExp(escapeRegex(projectConfigDir)));
 		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
+		assert.match(description, /PARENT-ONLY SUBAGENT ROUTING/);
+		assert.match(description, /select only an executable entry using its current role, context, and tool metadata/i);
 		assert.equal(warnings.length, 0);
 	});
 
@@ -213,7 +246,7 @@ describe("registered subagent tool description", () => {
 		assert.ok(warnings.some((message) => message.includes("Ignoring invalid toolDescriptionMode")));
 	});
 
-	function readRegisteredDescription(agentDir: string): string {
+	function readRegisteredTool(agentDir: string): { description: string; promptGuidelines?: string[] } {
 		const script = String.raw`
 			import registerSubagentExtension from "./src/extension/index.ts";
 			const events = { on() { return () => {}; }, emit() {} };
@@ -234,12 +267,15 @@ describe("registered subagent tool description", () => {
 			});
 			registerSubagentExtension(fakePi);
 			if (!registeredTool) throw new Error("tool not registered");
-			process.stdout.write(JSON.stringify(registeredTool.description));
+			process.stdout.write(JSON.stringify({
+				description: registeredTool.description,
+				promptGuidelines: registeredTool.promptGuidelines ?? null,
+			}));
 		`;
 		const output = execFileSync(
 			process.execPath,
 			[
-				"--experimental-transform-types",
+				"--experimental-strip-types",
 				"--import",
 				"./test/support/register-loader.mjs",
 				"--input-type=module",
@@ -248,7 +284,7 @@ describe("registered subagent tool description", () => {
 			],
 			{ cwd: projectRoot, env: parentToolEnv(agentDir), encoding: "utf-8" },
 		);
-		return JSON.parse(output) as string;
+		return JSON.parse(output) as { description: string; promptGuidelines?: string[] };
 	}
 
 	function writeExtensionConfig(agentDir: string, config: Record<string, unknown>): void {
@@ -259,25 +295,40 @@ describe("registered subagent tool description", () => {
 
 	it("registers full, compact, custom, and fallback descriptions from extension config", () => {
 		const defaultAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-default-"));
-		assert.equal(readRegisteredDescription(defaultAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredTool(defaultAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
 
 		const compactAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-compact-"));
 		writeExtensionConfig(compactAgentDir, { toolDescriptionMode: "compact" });
-		assert.equal(readRegisteredDescription(compactAgentDir), COMPACT_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredTool(compactAgentDir).description, COMPACT_SUBAGENT_TOOL_DESCRIPTION);
 
 		const customAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-custom-"));
 		writeExtensionConfig(customAgentDir, { toolDescriptionMode: "custom" });
 		fs.writeFileSync(path.join(customAgentDir, "subagent-tool-description.md"), "Registered custom description.", "utf-8");
-		const customDescription = readRegisteredDescription(customAgentDir);
+		const customDescription = readRegisteredTool(customAgentDir).description;
 		assert.match(customDescription, /Registered custom description/);
 		assert.match(customDescription, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
 
 		const missingCustomAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-missing-"));
 		writeExtensionConfig(missingCustomAgentDir, { toolDescriptionMode: "custom" });
-		assert.equal(readRegisteredDescription(missingCustomAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredTool(missingCustomAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
 
 		const invalidAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-invalid-"));
 		writeExtensionConfig(invalidAgentDir, { toolDescriptionMode: "tiny" });
-		assert.equal(readRegisteredDescription(invalidAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredTool(invalidAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
+	});
+
+	it("registers parent-only routing guidance as promptGuidelines on the parent tool", () => {
+		const defaultAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-guidelines-"));
+		const registered = readRegisteredTool(defaultAgentDir);
+
+		assert.ok(Array.isArray(registered.promptGuidelines), "parent subagent tool must expose promptGuidelines");
+		assert.equal(registered.promptGuidelines!.length, 1);
+		assert.equal(registered.promptGuidelines![0], SUBAGENT_PARENT_ROUTING_GUIDANCE);
+		assert.doesNotMatch(SUBAGENT_PARENT_ROUTING_GUIDANCE, new RegExp(BUILTIN_AGENT_NAMES.join("|")));
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /\{ action: "list" \}/);
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /executable entry/i);
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /tiny targeted reads and simple answers local/i);
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /broad local investigation, external research, and mutation\/implementation work/i);
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /decision-maker and normally the sole writer/i);
 	});
 });

package/dist/extensions/pi-subagents/test/unit/total-cost.test.ts

@@ -7,6 +7,7 @@ function resultWithUsage(usage: Usage): SingleResult {
 	return {
 		agent: "agent",
 		task: "task",
+		index: 0,
 		exitCode: 0,
 		messages: [],
 		usage,