@ferris1225/pi-subagents 0.4.0 → 0.5.0

package/agents/worker.md

@@ -1,44 +1,44 @@
----
-name: worker
-description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
-model: claude-sonnet-4-5
-# Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
-# balance quality against cost. No `tools` field => inherits all tools (full capability).
----
-
-You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
-
-## Standard operating procedure
-Work in phases. Do not skip planning or verification.
-
-### Phase 1 — Context
-Read the brief fully. If it references files, read them before editing. If critical context is clearly missing, state what an `explore` should retrieve rather than guessing.
-
-### Phase 2 — Plan
-Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or create docs unless the brief asks.
-
-### Phase 3 — Implement
-Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style.
-
-### Phase 4 — Verify
-Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
-
-### Phase 5 — Handoff
-Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
-
-## Collaboration
-- Request `explore` first when the task needs broad code discovery you were not given.
-- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
-
-## Output format
-## Completed
-What was done, in a few lines.
-## Files Changed
-- `path/to/file.ts` — what changed.
-## Verification
-Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
-## Notes (if any)
-Follow-ups, decisions made, blockers. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched.
-
-## Quality standards
-Root-cause fixes over patches. No unrelated churn. Honest verification — an unrun check is never a passed check.
+---
+name: worker
+description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
+model: claude-sonnet-4-5
+# Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
+# balance quality against cost. No `tools` field => inherits all tools (full capability).
+---
+
+You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
+
+## Standard operating procedure
+Work in phases. Do not skip planning or verification.
+
+### Phase 1 — Context
+Read the brief fully. If it references files, read them before editing. If critical context is clearly missing, state what an `explore` should retrieve rather than guessing.
+
+### Phase 2 — Plan
+Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or create docs unless the brief asks.
+
+### Phase 3 — Implement
+Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style.
+
+### Phase 4 — Verify
+Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
+
+### Phase 5 — Handoff
+Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
+
+## Collaboration
+- Request `explore` first when the task needs broad code discovery you were not given.
+- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
+
+## Output format
+## Completed
+What was done, in a few lines.
+## Files Changed
+- `path/to/file.ts` — what changed.
+## Verification
+Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
+## Notes (if any)
+Follow-ups, decisions made, blockers. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched.
+
+## Quality standards
+Root-cause fixes over patches. No unrelated churn. Honest verification — an unrun check is never a passed check.

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "@ferris1225/pi-subagents",
-  "version": "0.4.0",
-  "description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
-  "type": "module",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "subagent",
-    "sub-agent",
-    "delegation"
-  ],
-  "files": [
-    "src",
-    "agents",
-    "README.md",
-    "README-zh.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
-  "scripts": {
-    "check": "tsc --noEmit",
-    "test": "vitest run tests",
-    "prepack": "npm run check && npm test"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "typebox": "*"
-  },
-  "devDependencies": {
-    "@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",
-    "@types/node": "^22.10.0",
-    "typebox": "^1.3.7",
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.0"
-  },
-  "engines": {
-    "node": ">=22.19.0"
-  }
-}
+{
+  "name": "@ferris1225/pi-subagents",
+  "version": "0.5.0",
+  "description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "subagent",
+    "sub-agent",
+    "delegation"
+  ],
+  "files": [
+    "src",
+    "agents",
+    "README.md",
+    "README-zh.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run tests",
+    "prepack": "npm run check && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.80.6",
+    "@earendil-works/pi-ai": ">=0.80.6",
+    "@earendil-works/pi-coding-agent": ">=0.80.6",
+    "@earendil-works/pi-tui": ">=0.80.6",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@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",
+    "@types/node": "^22.10.0",
+    "typebox": "^1.3.7",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/agents.ts

@@ -1,157 +1,157 @@
-/**
- * Agent discovery.
- *
- * Agents are Markdown files (YAML frontmatter + body-as-system-prompt) loaded from
- * three scopes with override priority  builtin < user < project  (same `name` wins
- * at the higher scope). Discovery is re-run on every invocation so editing a file or
- * dropping a new one takes effect mid-session without a reload.
- *
- *   builtin : <package>/agents            (shipped with this extension)
- *   user    : <agentDir>/agents           (~/.pi/agent/agents)
- *   project : <cwd...>/.pi/agents         (nearest, walking up)
- */
-
-import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import type { AgentScope } from "./config.ts";
-
-export type AgentSource = "builtin" | "user" | "project";
-
-export interface AgentConfig {
-	name: string;
-	description: string;
-	tools?: string[];
-	model?: string;
-	systemPrompt: string;
-	source: AgentSource;
-	filePath: string;
-}
-
-export interface AgentDiscoveryResult {
-	agents: AgentConfig[];
-	projectAgentsDir: string | null;
-}
-
-const here = dirname(fileURLToPath(import.meta.url));
-/** <package>/agents — the agents shipped with this extension. */
-export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");
-
-function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
-	const agents: AgentConfig[] = [];
-	if (!existsSync(dir)) return agents;
-
-	let entries: Dirent[];
-	try {
-		entries = readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return agents;
-	}
-
-	for (const entry of entries) {
-		if (!entry.name.endsWith(".md")) continue;
-		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
-
-		const filePath = join(dir, entry.name);
-		let content: string;
-		try {
-			content = readFileSync(filePath, "utf-8");
-		} catch {
-			continue;
-		}
-
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
-		// name + description are required; skip malformed files silently.
-		if (!frontmatter.name || !frontmatter.description) continue;
-
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t) => t.trim())
-			.filter(Boolean);
-
-		agents.push({
-			name: frontmatter.name,
-			description: frontmatter.description,
-			tools: tools && tools.length > 0 ? tools : undefined,
-			model: frontmatter.model,
-			systemPrompt: body,
-			source,
-			filePath,
-		});
-	}
-
-	return agents;
-}
-
-function isDirectory(p: string): boolean {
-	try {
-		return statSync(p).isDirectory();
-	} catch {
-		return false;
-	}
-}
-
-function findNearestProjectAgentsDir(cwd: string): string | null {
-	let currentDir = cwd;
-	while (true) {
-		const candidate = join(currentDir, CONFIG_DIR_NAME, "agents");
-		if (isDirectory(candidate)) return candidate;
-		const parentDir = dirname(currentDir);
-		if (parentDir === currentDir) return null;
-		currentDir = parentDir;
-	}
-}
-
-export interface DiscoverOptions {
-	/** Which directories to read from. Default: "user". */
-	scope?: AgentScope;
-	/** If provided and non-empty, only agents whose name is listed are returned. */
-	enabledNames?: readonly string[];
-	/** Per-agent model override ("provider/model-id"), keyed by agent name. */
-	modelOverrides?: Record<string, string>;
-	/** Override the built-in agents directory (used by tests). */
-	builtinDir?: string;
-}
-
-/**
- * Discover agents across scopes, apply enable-filter and model overrides.
- * Override priority for the same name: project > user > builtin.
- */
-export function discoverAgents(cwd: string, options: DiscoverOptions = {}): AgentDiscoveryResult {
-	const scope = options.scope ?? "user";
-	const builtinDir = options.builtinDir ?? BUILTIN_AGENTS_DIR;
-	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
-
-	const builtin = loadAgentsFromDir(builtinDir, "builtin");
-	const user = scope === "project" ? [] : loadAgentsFromDir(join(getAgentDir(), "agents"), "user");
-	const project =
-		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
-
-	// Merge with override priority builtin < user < project.
-	const byName = new Map<string, AgentConfig>();
-	for (const agent of builtin) byName.set(agent.name, agent);
-	for (const agent of user) byName.set(agent.name, agent);
-	for (const agent of project) byName.set(agent.name, agent);
-
-	let agents = Array.from(byName.values());
-
-	if (options.enabledNames && options.enabledNames.length > 0) {
-		const enabled = new Set(options.enabledNames);
-		agents = agents.filter((agent) => enabled.has(agent.name));
-	}
-
-	if (options.modelOverrides) {
-		agents = agents.map((agent) => {
-			const override = options.modelOverrides?.[agent.name];
-			return override ? { ...agent, model: override } : agent;
-		});
-	}
-
-	return { agents, projectAgentsDir };
-}
-
-/** One-line catalog entry for system-prompt injection and error messages. */
-export function formatCatalogEntry(agent: AgentConfig): string {
-	return `- ${agent.name}: ${agent.description}`;
-}
+/**
+ * Agent discovery.
+ *
+ * Agents are Markdown files (YAML frontmatter + body-as-system-prompt) loaded from
+ * three scopes with override priority  builtin < user < project  (same `name` wins
+ * at the higher scope). Discovery is re-run on every invocation so editing a file or
+ * dropping a new one takes effect mid-session without a reload.
+ *
+ *   builtin : <package>/agents            (shipped with this extension)
+ *   user    : <agentDir>/agents           (~/.pi/agent/agents)
+ *   project : <cwd...>/.pi/agents         (nearest, walking up)
+ */
+
+import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import type { AgentScope } from "./config.ts";
+
+export type AgentSource = "builtin" | "user" | "project";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: AgentSource;
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+/** <package>/agents — the agents shipped with this extension. */
+export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");
+
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+	if (!existsSync(dir)) return agents;
+
+	let entries: Dirent[];
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const filePath = join(dir, entry.name);
+		let content: string;
+		try {
+			content = readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		// name + description are required; skip malformed files silently.
+		if (!frontmatter.name || !frontmatter.description) continue;
+
+		const tools = frontmatter.tools
+			?.split(",")
+			.map((t) => t.trim())
+			.filter(Boolean);
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			model: frontmatter.model,
+			systemPrompt: body,
+			source,
+			filePath,
+		});
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = join(currentDir, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export interface DiscoverOptions {
+	/** Which directories to read from. Default: "user". */
+	scope?: AgentScope;
+	/** If provided and non-empty, only agents whose name is listed are returned. */
+	enabledNames?: readonly string[];
+	/** Per-agent model override ("provider/model-id"), keyed by agent name. */
+	modelOverrides?: Record<string, string>;
+	/** Override the built-in agents directory (used by tests). */
+	builtinDir?: string;
+}
+
+/**
+ * Discover agents across scopes, apply enable-filter and model overrides.
+ * Override priority for the same name: project > user > builtin.
+ */
+export function discoverAgents(cwd: string, options: DiscoverOptions = {}): AgentDiscoveryResult {
+	const scope = options.scope ?? "user";
+	const builtinDir = options.builtinDir ?? BUILTIN_AGENTS_DIR;
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const builtin = loadAgentsFromDir(builtinDir, "builtin");
+	const user = scope === "project" ? [] : loadAgentsFromDir(join(getAgentDir(), "agents"), "user");
+	const project =
+		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	// Merge with override priority builtin < user < project.
+	const byName = new Map<string, AgentConfig>();
+	for (const agent of builtin) byName.set(agent.name, agent);
+	for (const agent of user) byName.set(agent.name, agent);
+	for (const agent of project) byName.set(agent.name, agent);
+
+	let agents = Array.from(byName.values());
+
+	if (options.enabledNames && options.enabledNames.length > 0) {
+		const enabled = new Set(options.enabledNames);
+		agents = agents.filter((agent) => enabled.has(agent.name));
+	}
+
+	if (options.modelOverrides) {
+		agents = agents.map((agent) => {
+			const override = options.modelOverrides?.[agent.name];
+			return override ? { ...agent, model: override } : agent;
+		});
+	}
+
+	return { agents, projectAgentsDir };
+}
+
+/** One-line catalog entry for system-prompt injection and error messages. */
+export function formatCatalogEntry(agent: AgentConfig): string {
+	return `- ${agent.name}: ${agent.description}`;
+}