@yandy0725/pi-subagents 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# pi-subagents
+
+A [pi](https://pi.dev) extension providing a focused, in-process sub-agent core — autonomous agents that run inside the same pi runtime (no spawned subprocesses), plus a typed API and lifecycle events other extensions build on.
+
+## Features
+
+- **In-process & native** — agents share the same pi runtime: same tool names, calling conventions, and UI patterns
+- **Parallel background agents** — spawn multiple agents with automatic queuing (configurable concurrency, default 4)
+- **Live widget UI** — persistent widget showing animated spinners, live tool activity, token counts, and colored status icons
+- **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: system prompts, model, thinking, tools
+- **Mid-run steering** — inject messages into running agents to redirect work without restarting
+- **Session resume** — pick up where an agent left off, preserving full conversation context
+- **Graceful turn limits** — agents get a "wrap up" warning before hard abort
+- **Case-insensitive types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work
+- **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs
+- **Context inheritance** — optionally fork the parent conversation into a sub-agent
+- **Styled notifications** — background results render as themed notification boxes
+- **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) via `pi.events`
+
+## Install
+
+```bash
+pi install npm:@yandy0725/pi-subagents
+```
+
+## Quick Start
+
+The parent agent spawns sub-agents using the `subagent` tool:
+
+```text
+subagent({
+  subagent_type: "Explore",
+  prompt: "Find all files that handle authentication",
+  description: "Find auth files",
+  run_in_background: true,
+})
+```
+
+Foreground agents block until complete. Background agents return an ID immediately and notify on completion.
+
+## Default Agent Types
+
+| Type | Tools | Model | Description |
+|------|-------|-------|-------------|
+| `general-purpose` | all | inherit | Full parent system prompt — same rules, same conventions |
+| `Explore` | read, bash, grep, find, ls | haiku (fallback: inherit) | Fast codebase exploration (read-only) |
+| `Plan` | read, bash, grep, find, ls | inherit | Software architect for implementation planning (read-only) |
+
+## Custom Agents
+
+Define custom agent types by creating `.md` files in `.pi/agents/<name>.md`:
+
+```markdown
+---
+description: Security Code Reviewer
+tools: read, grep, find, bash
+model: anthropic/claude-opus-4-6
+thinking: high
+max_turns: 30
+---
+
+You are a security auditor. Review code for vulnerabilities...
+```
+
+Agents are discovered from `.pi/agents/<name>.md` (project) and `~/.pi/agent/agents/<name>.md` (global). Project-level overrides global.
+
+## Tools
+
+### `subagent`
+
+Launch a sub-agent.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | yes | The task for the agent |
+| `description` | string | yes | Short 3-5 word summary (shown in UI) |
+| `subagent_type` | string | yes | Agent type (built-in or custom) |
+| `model` | string | no | Model override (`provider/modelId` or fuzzy name) |
+| `thinking` | string | no | off / minimal / low / medium / high / xhigh |
+| `max_turns` | number | no | Max agentic turns (unlimited by default) |
+| `run_in_background` | boolean | no | Run without blocking |
+| `resume` | string | no | Agent ID to resume a previous session |
+| `inherit_context` | boolean | no | Fork parent conversation into agent |
+
+### `get_subagent_result`
+
+Check status and retrieve results from a background agent.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | yes | Agent ID to check |
+| `wait` | boolean | no | Wait for completion |
+| `verbose` | boolean | no | Include full conversation log |
+
+### `steer_subagent`
+
+Send a steering message to a running agent.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | yes | Agent ID to steer |
+| `message` | string | yes | Message to inject into agent conversation |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/subagents:settings` | Configure concurrency, turn limits |
+| `/subagents:sessions` | View a subagent's session transcript |
+
+## Concurrency
+
+Background agents are subject to a configurable concurrency limit (default: 4). Excess agents queue automatically. Foreground agents bypass the queue.
+
+## Persistent Settings
+
+Settings set via `/subagents:settings` persist in `<cwd>/.pi/subagents.json` (project) and can be overridden globally in `~/.pi/agent/subagents.json`.
+
+## Events
+
+Lifecycle events emitted via `pi.events` for other extensions to consume:
+
+| Event | When |
+|-------|------|
+| `subagents:created` | Background agent registered |
+| `subagents:started` | Agent transitions to running |
+| `subagents:completed` | Agent finished successfully |
+| `subagents:failed` | Agent errored, stopped, or aborted |
+| `subagents:steered` | Steering message sent |
+| `subagents:compacted` | Agent session compacted |
+| `subagents:settings_loaded` | Persisted settings applied |
+| `subagents:settings_changed` | Settings mutation applied |
+
+## Permission System Integration
+
+When `@yandy0725/pi-permission-system` is installed, the package integrates automatically:
+- Per-agent permission policies via YAML frontmatter
+- Tool filtering before agent start
+- `ask`-state forwarding from child to parent UI
+
+## Development
+
+```bash
+npm run typecheck        # tsc --noEmit
+npm run check            # biome check
+npm test                 # vitest run
+```
+
+## Acknowledgments
+
+This project is a friendly fork of [@gotgenes/pi-subagents](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents) by [Chris Lasher](https://github.com/gotgenes), which began as a fork of [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents). Thank you to all original authors for their work that made this package possible.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,155 @@
+# pi-subagents
+
+[Pi](https://pi.dev) 扩展，提供聚焦的进程内子代理核心——在同一 pi 运行时内运行的自主代理（无需生成子进程），外加类型化 API 和生命周期事件供其他扩展构建。
+
+## 功能
+
+- **进程内原生** — 代理共享同一 pi 运行时：相同的工具名、调用约定和 UI 模式
+- **并行后台代理** — 同时启动多个代理，自动排队（可配置并发数，默认 4）
+- **实时 Widget UI** — 持久化的编辑器上方组件，带动态旋转指示器、实时工具活动、token 计数和彩色状态图标
+- **自定义代理类型** — 在 `.pi/agents/<name>.md` 中通过 YAML frontmatter 定义：系统提示词、模型、思考等级、工具限制
+- **运行中转向** — 向运行中的代理注入消息，无需重启即可改变工作方向
+- **会话恢复** — 从上次中断处继续，保留完整对话上下文
+- **优雅轮次限制** — 代理在硬中止前收到"收尾"警告
+- **大小写不敏感** — `"explore"`、`"Explore"`、`"EXPLORE"` 均可
+- **模糊模型选择** — 按名称（`"haiku"`、`"sonnet"`）而非完整 ID 指定模型
+- **上下文继承** — 可选择将父对话分叉给子代理
+- **风格化通知** — 后台结果渲染为主题化通知框
+- **事件总线** — 通过 `pi.events` 发出生命周期事件（`subagents:created`、`started`、`completed`、`failed`、`steered`、`compacted`）
+
+## 安装
+
+```bash
+pi install npm:@yandy0725/pi-subagents
+```
+
+## 快速开始
+
+父代理使用 `subagent` 工具启动子代理：
+
+```text
+subagent({
+  subagent_type: "Explore",
+  prompt: "Find all files that handle authentication",
+  description: "Find auth files",
+  run_in_background: true,
+})
+```
+
+前台代理阻塞直到完成。后台代理立即返回 ID，完成后通知。
+
+## 默认代理类型
+
+| 类型 | 工具 | 模型 | 描述 |
+|------|------|------|------|
+| `general-purpose` | 全部 | 继承父级 | 完整父级系统提示词——相同规则、相同约定 |
+| `Explore` | read, bash, grep, find, ls | haiku（回退：继承） | 快速代码库探索（只读） |
+| `Plan` | read, bash, grep, find, ls | 继承父级 | 软件架构师，实现方案设计（只读） |
+
+## 自定义代理
+
+在 `.pi/agents/<name>.md` 中创建 `.md` 文件定义自定义代理类型：
+
+```markdown
+---
+description: 安全代码审查
+tools: read, grep, find, bash
+model: anthropic/claude-opus-4-6
+thinking: high
+max_turns: 30
+---
+
+你是一名安全审计员。审查代码漏洞...
+```
+
+代理从 `.pi/agents/<name>.md`（项目级）和 `~/.pi/agent/agents/<name>.md`（全局）发现。项目级覆盖全局。
+
+## 工具
+
+### `subagent`
+
+启动子代理。
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `prompt` | string | 是 | 代理要执行的任务 |
+| `description` | string | 是 | 3-5 词简短描述（UI 中显示） |
+| `subagent_type` | string | 是 | 代理类型（内置或自定义） |
+| `model` | string | 否 | 模型覆盖（`provider/modelId` 或模糊名称） |
+| `thinking` | string | 否 | off / minimal / low / medium / high / xhigh |
+| `max_turns` | number | 否 | 最大代理轮次（默认无限制） |
+| `run_in_background` | boolean | 否 | 后台运行不阻塞 |
+| `resume` | string | 否 | 恢复之前会话的代理 ID |
+| `inherit_context` | boolean | 否 | 将父对话分叉给子代理 |
+
+### `get_subagent_result`
+
+检查后台代理的状态并获取结果。
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `agent_id` | string | 是 | 要检查的代理 ID |
+| `wait` | boolean | 否 | 等待完成 |
+| `verbose` | boolean | 否 | 包含完整对话日志 |
+
+### `steer_subagent`
+
+向运行中的代理发送转向消息。
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `agent_id` | string | 是 | 要转向的代理 ID |
+| `message` | string | 是 | 注入代理对话的消息 |
+
+## 命令
+
+| 命令 | 描述 |
+|------|------|
+| `/subagents:settings` | 配置并发数、轮次限制 |
+| `/subagents:sessions` | 查看子代理的会话记录 |
+
+## 并发控制
+
+后台代理受可配置并发限制约束（默认 4）。超出限制的代理自动排队。前台代理绕过队列。
+
+## 持久化设置
+
+通过 `/subagents:settings` 设置的参数持久化到 `<cwd>/.pi/subagents.json`（项目级），也可在 `~/.pi/agent/subagents.json` 中设置全局默认值。
+
+## 事件
+
+通过 `pi.events` 发出的生命周期事件，供其他扩展消费：
+
+| 事件 | 触发时机 |
+|------|----------|
+| `subagents:created` | 后台代理已注册 |
+| `subagents:started` | 代理转入运行状态 |
+| `subagents:completed` | 代理成功完成 |
+| `subagents:failed` | 代理出错/停止/中止 |
+| `subagents:steered` | 转向消息已发送 |
+| `subagents:compacted` | 代理会话已压缩 |
+| `subagents:settings_loaded` | 持久化设置已应用 |
+| `subagents:settings_changed` | 设置变更已生效 |
+
+## 权限系统集成
+
+当安装了 `@yandy0725/pi-permission-system` 时，本包自动集成：
+- 通过 YAML frontmatter 为各代理类型设置权限策略
+- Agent 启动前过滤工具
+- `ask` 状态从子代理转发到父级 UI
+
+## 开发
+
+```bash
+npm run typecheck        # tsc --noEmit
+npm run check            # biome check
+npm test                 # vitest run
+```
+
+## 致谢
+
+本项目是 [@gotgenes/pi-subagents](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents)（作者 [Chris Lasher](https://github.com/gotgenes)）的友好分支，后者源自 [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)。感谢所有原作者的工作使本包成为可能。
+
+## 许可证
+
+MIT

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@yandy0725/pi-subagents",
+	"publishConfig": {
+		"access": "public"
+	},
+	"version": "0.1.0",
+	"description": "Focused, in-process sub-agent core for pi — autonomous agents plus a typed API and lifecycle events",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/yandy/pi-packages",
+		"directory": "pi-subagents"
+	},
+	"type": "module",
+	"keywords": [
+		"pi-package"
+	],
+	"files": [
+		"index.ts",
+		"src/"
+	],
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome lint .",
+		"format": "biome format --write .",
+		"check": "biome check ."
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": ">=0.74.0",
+		"@earendil-works/pi-coding-agent": ">=0.74.0",
+		"@earendil-works/pi-tui": ">=0.74.0"
+	},
+	"dependencies": {
+		"@sinclair/typebox": "^0.34.49"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.0",
+		"@types/node": "^22.0.0",
+		"typescript": "~5.7.0",
+		"vitest": "^3.0.0"
+	}
+}

package/src/config/agent-types.ts

@@ -0,0 +1,127 @@
+/**
+ * agent-types.ts — Unified agent type registry.
+ *
+ * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
+ * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
+ */
+
+import { DEFAULT_AGENTS } from "../config/default-agents";
+import type { AgentConfig } from "../types";
+
+// ── AgentConfigLookup interface ──────────────────────────────────────────────
+
+/**
+ * Narrow registry interface for consumers that only need config resolution.
+ * Prefer this over the full `AgentTypeRegistry` in function signatures (ISP).
+ */
+export interface AgentConfigLookup {
+	resolveAgentConfig(type: string): AgentConfig;
+	getToolNamesForType(type: string): string[];
+}
+
+// ── AgentTypeRegistry class ──────────────────────────────────────────────────
+
+/**
+ * Injectable registry of all agent configurations (defaults + user-defined).
+ *
+ * Replaces the module-scoped `agents` Map and its companion free functions.
+ * The constructor accepts a `loadUserAgents` callback to defer disk I/O to the
+ * call site, keeping this class side-effect-free and easy to test.
+ */
+export class AgentTypeRegistry implements AgentConfigLookup {
+	private agents = new Map<string, AgentConfig>();
+
+	/** The three embedded default agent names. */
+	static readonly DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as const;
+
+	constructor(private loadUserAgents: () => Map<string, AgentConfig>) {
+		this.reload();
+	}
+
+	/**
+	 * Re-scan user agents and rebuild the registry.
+	 * Starts with DEFAULT_AGENTS, then overlays whatever `loadUserAgents()` returns.
+	 */
+	reload(): void {
+		this.agents.clear();
+		for (const [name, config] of DEFAULT_AGENTS) {
+			this.agents.set(name, config);
+		}
+		for (const [name, config] of this.loadUserAgents()) {
+			this.agents.set(name, config);
+		}
+	}
+
+	/** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
+	resolveType(name: string): string | undefined {
+		return this.resolveKey(name);
+	}
+
+	/** Get all enabled type names (for spawning and tool descriptions). */
+	getAvailableTypes(): string[] {
+		return [...this.agents.entries()].filter(([_, config]) => config.enabled !== false).map(([name]) => name);
+	}
+
+	/** Get all type names including disabled (for UI listing). */
+	getAllTypes(): string[] {
+		return [...this.agents.keys()];
+	}
+
+	/** Get names of default agents currently in the registry. */
+	getDefaultAgentNames(): string[] {
+		return [...this.agents.entries()].filter(([_, config]) => config.isDefault === true).map(([name]) => name);
+	}
+
+	/** Get names of user-defined agents (non-defaults) currently in the registry. */
+	getUserAgentNames(): string[] {
+		return [...this.agents.entries()].filter(([_, config]) => config.isDefault !== true).map(([name]) => name);
+	}
+
+	/** Check if a type is valid and enabled (case-insensitive). */
+	isValidType(type: string): boolean {
+		const key = this.resolveKey(type);
+		if (!key) return false;
+		return this.agents.get(key)?.enabled !== false;
+	}
+
+	/** Get built-in tool names for a type (case-insensitive). */
+	getToolNamesForType(type: string): string[] {
+		const key = this.resolveKey(type);
+		const raw = key ? this.agents.get(key) : undefined;
+		const config = raw?.enabled !== false ? raw : undefined;
+		const names = config?.builtinToolNames?.length ? config.builtinToolNames : [...BUILTIN_TOOL_NAMES];
+		return names;
+	}
+
+	/** Resolve agent config with guaranteed non-null return. Falls back: unknown → general-purpose → absolute fallback. */
+	resolveAgentConfig(type: string): AgentConfig {
+		const key = this.resolveKey(type);
+		const config = key ? this.agents.get(key) : undefined;
+		if (config) return config;
+
+		const gp = this.agents.get("general-purpose");
+		if (gp) return gp;
+
+		// Absolute fallback (should never happen in practice)
+		return {
+			name: type,
+			displayName: "Agent",
+			description: "General-purpose agent for complex, multi-step tasks",
+			builtinToolNames: BUILTIN_TOOL_NAMES,
+			systemPrompt: "",
+			promptMode: "append",
+		};
+	}
+
+	private resolveKey(name: string): string | undefined {
+		if (this.agents.has(name)) return name;
+		const lower = name.toLowerCase();
+		for (const key of this.agents.keys()) {
+			if (key.toLowerCase() === lower) return key;
+		}
+		return undefined;
+	}
+}
+
+/** All known built-in tool names. */
+export const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];

package/src/config/custom-agents.ts

@@ -0,0 +1,109 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_TOOL_NAMES } from "../config/agent-types";
+import { debugLog } from "../debug";
+import type { AgentConfig, ThinkingLevel } from "../types";
+
+/**
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project: <cwd>/.pi/agents/*.md
+ *   2. Global:  $PI_CODING_AGENT_DIR/agents/*.md (default: ~/.pi/agent/agents/*.md)
+ *
+ * Project-level agents override global ones with the same name.
+ * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ */
+export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
+	const globalDir = join(getAgentDir(), "agents");
+	const projectDir = join(cwd, ".pi", "agents");
+
+	const agents = new Map<string, AgentConfig>();
+	loadFromDir(globalDir, agents, "global"); // lower priority
+	loadFromDir(projectDir, agents, "project"); // higher priority (overwrites)
+	return agents;
+}
+
+/** Load agent configs from a directory into the map. */
+function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "project" | "global"): void {
+	if (!existsSync(dir)) return;
+
+	let files: string[];
+	try {
+		files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+	} catch (err) {
+		debugLog("readdirSync agents dir", err);
+		return;
+	}
+
+	for (const file of files) {
+		const name = basename(file, ".md");
+
+		let content: string;
+		try {
+			content = readFileSync(join(dir, file), "utf-8");
+		} catch (err) {
+			debugLog("readFileSync agent file", err);
+			continue;
+		}
+
+		const { frontmatter: fm, body } = parseFrontmatter(content);
+
+		agents.set(name, {
+			name,
+			displayName: str(fm.display_name),
+			description: str(fm.description) ?? name,
+			builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+			model: str(fm.model),
+			thinking: str(fm.thinking) as ThinkingLevel | undefined,
+			maxTurns: nonNegativeInt(fm.max_turns),
+			systemPrompt: body.trim(),
+			promptMode: fm.prompt_mode === "replace" ? "replace" : "append",
+			inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
+			runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
+			enabled: fm.enabled !== false, // default true; explicitly false disables
+			source,
+		});
+	}
+}
+
+// ---- Field parsers ----
+// All follow the same convention: omitted → default, "none"/empty → nothing, value → exact.
+
+/** Extract a string or undefined. */
+function str(val: unknown): string | undefined {
+	return typeof val === "string" ? val : undefined;
+}
+
+/** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
+function nonNegativeInt(val: unknown): number | undefined {
+	return typeof val === "number" && val >= 0 ? val : undefined;
+}
+
+/**
+ * Parse a raw CSV field value into items, or undefined if absent/empty/"none".
+ */
+function parseCsvField(val: unknown): string[] | undefined {
+	if (val === undefined || val === null) return undefined;
+	// eslint-disable-next-line @typescript-eslint/no-base-to-string -- val is already narrowed past null/undefined; String() is the intended coercion here
+	const s = String(val).trim();
+	if (!s || s === "none") return undefined;
+	const items = s
+		.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+	return items.length > 0 ? items : undefined;
+}
+
+/**
+ * Parse a comma-separated list field with defaults.
+ * omitted → defaults; "none"/empty → []; csv → listed items.
+ */
+function csvList(val: unknown, defaults: string[]): string[] {
+	if (val === undefined || val === null) return defaults;
+	return parseCsvField(val) ?? [];
+}