@chaotic1988/pi-subagent 0.2.0

package/README.md

@@ -0,0 +1,46 @@
+# pi-subagent
+
+A [pi](https://github.com/mariozechner/pi) extension for delegating tasks to subagents. Each subagent runs as an in-process SDK session with its own isolated context window — ideal for parallel work, specialist prompts, or keeping noisy subtasks out of your main session.
+
+## Install
+
+```bash
+pi install npm:@chaotic1988/pi-subagent
+```
+
+## Quick Start
+
+**1. Define an agent** (e.g. `~/.pi/agent/agents/reviewer.md`):
+
+```yaml
+---
+name: reviewer
+description: Reviews code for quality and correctness
+---
+
+You are a thorough code reviewer. Focus on correctness, clarity, and edge cases.
+Respond with a brief summary followed by a bullet list of specific issues.
+```
+
+**2. Use it in a task**
+
+Single agent:
+```json
+{
+  "agent": "reviewer",
+  "task": "Review src/auth.ts for security issues"
+}
+```
+
+Parallel agents:
+```json
+{
+  "tasks": [
+    { "agent": "reviewer", "task": "Review src/auth.ts" },
+    { "agent": "reviewer", "task": "Review src/api.ts" },
+    { "agent": "reviewer", "task": "Review src/utils.ts" }
+  ]
+}
+```
+
+For full documentation — agent configuration, discovery rules, frontmatter reference, and more — see the [User Guide](docs/user-guide.md).

package/agent.ts

@@ -0,0 +1,163 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DefaultPackageManager, type ExtensionContext, getAgentDir, parseFrontmatter, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+export interface AgentConfig {
+    name: string;
+    description: string;
+    tools?: string[];
+    model?: string;
+    thinkingLevel?: string;
+    /** undefined = no extensions; non-empty = exactly these extensions */
+    extensions?: string[];
+    /** undefined = no skills; non-empty = exactly these skill names */
+    skills?: string[];
+    systemPrompt: string;
+    source: "user" | "project";
+    filePath: string;
+}
+
+
+export function parseCommaList(value: unknown): string[] | undefined {
+    if (typeof value !== "string") return undefined;
+    const parts = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+}
+
+function substituteEnvVars(paths: string[] | undefined): string[] | undefined {
+    if (!paths) return paths;
+    return paths.map((p) => p.replace(/\$\{(\w+)\}/g, (match, name) => process.env[name] ?? match));
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+    const agents: AgentConfig[] = [];
+
+    if (!fs.existsSync(dir)) {
+        return agents;
+    }
+
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.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 = path.join(dir, entry.name);
+        let content: string;
+        try {
+            content = fs.readFileSync(filePath, "utf-8");
+        } catch {
+            continue;
+        }
+
+        const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
+
+        if (!frontmatter.name || !frontmatter.description) {
+            continue;
+        }
+
+        agents.push({
+            name: frontmatter.name as string,
+            description: frontmatter.description as string,
+            tools: parseCommaList(frontmatter.tools),
+            model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+            thinkingLevel: typeof frontmatter.thinkingLevel === "string" ? frontmatter.thinkingLevel : undefined,
+            extensions: substituteEnvVars(parseCommaList(frontmatter.extensions)),
+            skills: parseCommaList(frontmatter.skills),
+            systemPrompt: body,
+            source,
+            filePath,
+        });
+    }
+
+    return agents;
+}
+
+function isDirectory(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function getPackageAgentsDirs(
+    settings: SettingsManager,
+    packages: DefaultPackageManager,
+    scope: "user" | "project",
+): string[] {
+    const pkgList =
+        scope === "user"
+            ? settings.getGlobalSettings().packages ?? []
+            : settings.getProjectSettings().packages ?? [];
+    const dirs: string[] = [];
+    for (const pkg of pkgList) {
+        const source = typeof pkg === "string" ? pkg : pkg.source;
+        const root = packages.getInstalledPath(source, scope);
+        if (root) {
+            const agentsDir = path.join(root, "agents");
+            if (isDirectory(agentsDir)) dirs.push(agentsDir);
+        }
+    }
+    return dirs;
+}
+
+function getExtensionAgentsDirs(baseDir: string): string[] {
+    const extDir = path.join(baseDir, "extensions");
+    if (!isDirectory(extDir)) return [];
+    const dirs: string[] = [];
+    for (const entry of fs.readdirSync(extDir, { withFileTypes: true })) {
+        if (entry.isDirectory() || entry.isSymbolicLink()) {
+            const agentsDir = path.join(extDir, entry.name, "agents");
+            if (isDirectory(agentsDir)) dirs.push(agentsDir);
+        }
+    }
+    return dirs;
+}
+
+export function discoverAgents(ctx: ExtensionContext): AgentConfig[] {
+    const agentDir = getAgentDir();
+    const settings = SettingsManager.create(ctx.cwd, agentDir);
+    const packages = new DefaultPackageManager({ cwd: ctx.cwd, agentDir, settingsManager: settings });
+
+    const agentMap = new Map<string, AgentConfig>();
+
+    // User: lowest → highest precedence
+    for (const dir of [
+        ...getPackageAgentsDirs(settings, packages, "user"),
+        ...getExtensionAgentsDirs(agentDir),
+        path.join(agentDir, "agents"),
+    ]) for (const agent of loadAgentsFromDir(dir, "user")) agentMap.set(agent.name, agent);
+
+    // Project: overwrites user; lowest → highest precedence
+    if (ctx.isProjectTrusted()) {
+        for (const dir of [
+            ...getPackageAgentsDirs(settings, packages, "project"),
+            ...getExtensionAgentsDirs(path.join(ctx.cwd, ".pi")),
+            path.join(ctx.cwd, ".pi", "agents"),
+        ]) for (const agent of loadAgentsFromDir(dir, "project")) agentMap.set(agent.name, agent);
+    }
+
+    return Array.from(agentMap.values());
+}
+
+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,
+    };
+}

package/docs/user-guide.md

@@ -0,0 +1,127 @@
+# pi-subagent User Guide
+
+## Concepts
+
+pi-subagent lets you delegate tasks to **subagents** — in-process SDK sessions that run with their own isolated context window. Each subagent is a fresh session: it doesn't share your current conversation history, tools state, or context. This makes subagents ideal for parallelising independent work, keeping expensive or noisy subtasks out of your main context, or applying a specialist prompt to a specific problem.
+
+---
+
+## Defining an Agent
+
+An agent is a `.md` file with a YAML frontmatter header. The body of the file is appended to the agent's system prompt.
+
+```yaml
+---
+name: my-agent
+description: Does a specific thing well
+model: anthropic/claude-sonnet-4.6
+tools: read,bash,edit
+---
+
+You are a specialist in X. Keep responses concise.
+Always confirm before making destructive changes.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Identifier used when invoking the tool |
+| `description` | Yes | Shown in agent listings |
+| `model` | No | `<provider>/<id>` format (e.g. `anthropic/claude-sonnet-4.6`). Resolution failure (malformed, not found, no auth) halts the run with an error. Falls back to the SDK default if absent. |
+| `thinkingLevel` | No | `off \| minimal \| low \| medium \| high \| xhigh`. Clamped to the model's supported levels by the SDK. Falls back to the SDK default if absent. |
+| `tools` | No | Comma-separated list of allowed tools; all tools if absent |
+| `extensions` | No | Omit or empty → none; list of paths → exactly those extensions loaded. Supports `${ENV_VAR}` substitution. |
+| `skills` | No | Omit or empty → none; list of names → exactly those skills loaded |
+
+### `extensions` and `skills`
+
+Subagents start with **no extensions and no skills** by default. The agent config must list them explicitly.
+
+| Frontmatter | Behaviour |
+|-------------|-----------|
+| Field absent or empty | No extensions/skills loaded |
+| `extensions` with paths (`extensions: /path/a, /path/b`) | Exactly those extensions loaded. |
+| `skills` with names (`skills: my-skill, other-skill`) | Exactly those skills loaded. |
+
+---
+
+## Agent Discovery
+
+pi-subagent scans several locations at startup. Agents are loaded in two phases: **user** first, then **project**. Within each phase, later entries overwrite earlier ones on name collision. Because the project phase runs second, **project agents win over user agents** with the same name.
+
+Project-scoped agents are only loaded when the project is trusted.
+
+| Phase | Order (low → high) | Scope |
+|---|---|---|
+| User | installed packages → user extensions → `~/.pi/agent/agents` | `"user"` |
+| Project | installed packages → project extensions → `cwd/.pi/agents` | `"project"` |
+
+---
+
+## Env-Var Substitution in Extension Paths
+
+`${VAR_NAME}` tokens in `extensions` path lists are substituted from `process.env` at load time. Unknown variables are left as-is.
+
+This is useful for extensions that bundle both an agent definition and skills: the extension can register its own install path as an environment variable, and the agent frontmatter can reference it without hardcoding an absolute path.
+
+```typescript
+// In your extension's index.ts, set the variable before agents are loaded:
+process.env.MY_EXT_DIR = __dirname;
+```
+
+```yaml
+---
+name: my-bundled-agent
+description: Agent that uses extensions from the same package
+extensions: ${MY_EXT_DIR}/extensions/my-ext
+---
+```
+
+This works regardless of whether the extension is installed globally, per-project, from git, or from npm.
+
+---
+
+## Modes
+
+### Single Mode
+
+Dispatch one task to one named agent:
+
+```json
+{
+  "agent": "my-agent",
+  "task": "Summarise the changes in the last 10 commits",
+  "cwd": "/path/to/repo"
+}
+```
+
+`cwd` is optional; the subagent inherits the caller's working directory if omitted.
+
+### Parallel Mode
+
+Dispatch multiple tasks concurrently (up to 8 tasks, max 4 running at once):
+
+```json
+{
+  "tasks": [
+    { "agent": "reviewer", "task": "Review src/auth.ts for security issues" },
+    { "agent": "reviewer", "task": "Review src/api.ts for security issues" },
+    { "agent": "docs-writer", "task": "Write JSDoc for src/utils.ts" }
+  ]
+}
+```
+
+Each task in the array accepts the same fields as single mode (`agent`, `task`, `cwd`).
+
+---
+
+## Tips
+
+- **Keep system prompts focused.** Subagents have isolated context — a tight, specific system prompt produces better results than a general-purpose one.
+
+- **Use `skills:` to prevent skill bleed.** Subagents load no skills by default. If you want to keep it that way, omit the `skills` field or leave it empty.
+
+- **Debug with session logs.** Every subagent run persists a session under `~/.pi/agent/sessions/`. Open the session in pi to replay the conversation and inspect what the subagent did.
+
+- **Name agents clearly.** The calling agent selects subagents by name. A name like `security-reviewer` is easier to select correctly than `reviewer`.