@johnnywu/pi-subagents 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 1.0.0 (2026-05-30)
+
+
+### Bug Fixes
+
+* simplify subagent tool log rendering ([aea9cfe](https://github.com/jwu/pi-subagents/commit/aea9cfea9c53ea62273a5be41bd923b20522c833))
+* **subagent:** move usage summary after markdown output in expanded mode ([8fecce0](https://github.com/jwu/pi-subagents/commit/8fecce0ae2d318e101e75e3484b7d3010fddcdb5))
+
+
+### Features
+
+* add subagent extension core ([b524b4e](https://github.com/jwu/pi-subagents/commit/b524b4e1f8acb175360e526e99b4f52ca43ee460))
+* improve subagent progress rendering ([92f40b6](https://github.com/jwu/pi-subagents/commit/92f40b60730d44b459970580ba675c1d020303dd))
+* improve subagent result rendering ([699587f](https://github.com/jwu/pi-subagents/commit/699587fd9aed6cd5f59780e1d2ee21aeb8d1a304))
+* **render:** 折叠态输出摘要改为原始文本截断，与 builtin 工具一致 ([18de536](https://github.com/jwu/pi-subagents/commit/18de5367b25f70035404911d31446bbabb340d1b))
+
+# Changelog
+
+## [1.0.0] - 2026-05-29
+
+### Added
+- Initial project scaffolding

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jwu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# pi-subagents
+
+Sub-agents extension for [pi](https://github.com/badlogic/pi-mono) coding agent.
+
+## Install
+
+```bash
+pi install npm:@johnnywu/pi-subagents
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type-check
+bun run typecheck
+
+# Format
+bun run format
+
+# Release (local, requires GH_TOKEN and NPM_TOKEN)
+bun run release
+```
+
+This project uses [semantic-release](https://semantic-release.gitbook.io) with [conventional commits](https://www.conventionalcommits.org/).
+
+## License
+
+MIT

package/extensions/agent-loader.ts

@@ -0,0 +1,180 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export type ThinkingLevel = 'off' | 'low' | 'medium' | 'high';
+export type SystemPromptMode = 'replace' | 'append';
+export type AgentSource = 'global' | 'project';
+
+export interface AgentConfig {
+  name: string;
+  description?: string;
+  tools: string[];
+  model?: string;
+  thinking: ThinkingLevel;
+  systemPromptMode: SystemPromptMode;
+  allowedAgents?: string[];
+  maxDepth: number;
+  prompt: string;
+  source: AgentSource;
+  filePath: string;
+}
+
+export interface AgentDefinitionWarning {
+  filePath: string;
+  message: string;
+}
+
+export interface AgentDefinitionResult {
+  agents: AgentConfig[];
+  warnings: AgentDefinitionWarning[];
+}
+
+export interface AgentDefinitionFs {
+  listFiles(dir: string): Promise<string[]>;
+  readFile(filePath: string): Promise<string>;
+}
+
+export interface LoadAgentDefinitionsOptions {
+  cwd?: string;
+  globalDir?: string;
+  projectDir?: string;
+  fs?: AgentDefinitionFs;
+}
+
+const defaultFs: AgentDefinitionFs = {
+  async listFiles(dir) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      return entries
+        .filter((entry) => entry.isFile() || entry.isSymbolicLink())
+        .map((entry) => path.join(dir, entry.name))
+        .sort();
+    } catch {
+      return [];
+    }
+  },
+  readFile(filePath) {
+    return fs.readFile(filePath, 'utf8');
+  },
+};
+
+export function defaultGlobalAgentsDir(): string {
+  return path.join(os.homedir(), '.pi', 'agent', 'agents');
+}
+
+export function defaultProjectAgentsDir(cwd = process.cwd()): string {
+  return path.join(cwd, '.pi', 'agents');
+}
+
+function splitCsv(value: string | undefined): string[] {
+  return (value ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseFrontmatter(content: string): { data: Record<string, string>; body: string } {
+  if (!content.startsWith('---\n')) throw new Error('missing frontmatter');
+  const end = content.indexOf('\n---', 4);
+  if (end === -1) throw new Error('missing frontmatter terminator');
+
+  const rawFrontmatter = content.slice(4, end);
+  const body = content.slice(end + '\n---'.length).replace(/^\n/, '');
+  const data: Record<string, string> = {};
+
+  for (const line of rawFrontmatter.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const separator = trimmed.indexOf(':');
+    if (separator === -1) throw new Error(`invalid frontmatter line: ${line}`);
+    const key = trimmed.slice(0, separator).trim();
+    const value = trimmed.slice(separator + 1).trim();
+    if (!key) throw new Error(`invalid frontmatter key: ${line}`);
+    data[key] = value.replace(/^['"]|['"]$/g, '');
+  }
+
+  return { data, body };
+}
+
+function parseAgentFile(content: string, filePath: string, source: AgentSource): AgentConfig {
+  const { data, body } = parseFrontmatter(content);
+  if (!data.name) throw new Error('missing required field: name');
+
+  const thinking = (data.thinking ?? 'off') as ThinkingLevel;
+  if (!['off', 'low', 'medium', 'high'].includes(thinking)) {
+    throw new Error(`invalid thinking: ${data.thinking}`);
+  }
+
+  const systemPromptMode = (data.systemPrompt ?? 'replace') as SystemPromptMode;
+  if (!['replace', 'append'].includes(systemPromptMode)) {
+    throw new Error(`invalid systemPrompt: ${data.systemPrompt}`);
+  }
+
+  const maxDepth = data.maxDepth === undefined ? 10 : Number(data.maxDepth);
+  if (!Number.isInteger(maxDepth) || maxDepth < 0) {
+    throw new Error(`invalid maxDepth: ${data.maxDepth}`);
+  }
+
+  const allowedAgents = splitCsv(data.allowedAgents);
+
+  return {
+    name: data.name,
+    description: data.description,
+    tools: splitCsv(data.tools),
+    model: data.model || undefined,
+    thinking,
+    systemPromptMode,
+    allowedAgents: allowedAgents.length > 0 ? allowedAgents : undefined,
+    maxDepth,
+    prompt: body,
+    source,
+    filePath,
+  };
+}
+
+async function loadDirectory(
+  dir: string,
+  source: AgentSource,
+  fileSystem: AgentDefinitionFs,
+  warnings: AgentDefinitionWarning[],
+): Promise<AgentConfig[]> {
+  const agents: AgentConfig[] = [];
+  const seen = new Set<string>();
+
+  for (const filePath of await fileSystem.listFiles(dir)) {
+    if (!filePath.endsWith('.md')) continue;
+
+    try {
+      const agent = parseAgentFile(await fileSystem.readFile(filePath), filePath, source);
+      if (seen.has(agent.name)) continue;
+      seen.add(agent.name);
+      agents.push(agent);
+    } catch (error) {
+      warnings.push({
+        filePath,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return agents;
+}
+
+export async function loadAgentDefinitions(
+  options: LoadAgentDefinitionsOptions = {},
+): Promise<AgentDefinitionResult> {
+  const fileSystem = options.fs ?? defaultFs;
+  const globalDir = options.globalDir ?? defaultGlobalAgentsDir();
+  const projectDir = options.projectDir ?? defaultProjectAgentsDir(options.cwd);
+  const warnings: AgentDefinitionWarning[] = [];
+
+  const globalAgents = await loadDirectory(globalDir, 'global', fileSystem, warnings);
+  const projectAgents = await loadDirectory(projectDir, 'project', fileSystem, warnings);
+
+  const byName = new Map<string, AgentConfig>();
+  for (const agent of globalAgents) byName.set(agent.name, agent);
+  for (const agent of projectAgents) byName.set(agent.name, agent);
+
+  return { agents: [...byName.values()], warnings };
+}

package/extensions/index.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { loadAgentDefinitions } from './agent-loader.ts';
+import { registerSubagentTool } from './subagent-tool.ts';
+
+export default async function (pi: ExtensionAPI) {
+  const result = await loadAgentDefinitions({ cwd: process.cwd() });
+
+  for (const warning of result.warnings) {
+    console.warn(`[pi-subagents] skipped ${warning.filePath}: ${warning.message}`);
+  }
+
+  registerSubagentTool(pi, { agents: result.agents });
+}