@chaotic1988/pi-subagent 0.2.0

package/runner.ts

@@ -0,0 +1,295 @@
+/**
+ * SDK-based runner for subagent execution.
+ *
+ * Creates in-process AgentSession instances instead of spawning child processes.
+ * Handles model resolution, resource loading, event subscription, and abort signals.
+ */
+
+import type { Message, Model, Api } from "@earendil-works/pi-ai";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import {
+    type AgentSessionEvent,
+    AuthStorage,
+    createAgentSession,
+    DefaultResourceLoader,
+    getAgentDir,
+    ModelRegistry,
+    SessionManager,
+    SettingsManager,
+    type Skill,
+    type ResourceDiagnostic,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentConfig } from "./agent.js";
+
+export interface UsageStats {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    contextTokens: number;
+    turns: number;
+}
+
+export interface SingleResult {
+    agent: string;
+    agentSource: "user" | "project" | "unknown";
+    task: string;
+    exitCode: number;
+    messages: Message[];
+    stderr: string;
+    usage: UsageStats;
+    model?: string;
+    stopReason?: string;
+    errorMessage?: string;
+}
+
+export type OnUpdateCallback = (result: SingleResult) => void;
+
+// ---------------------------------------------------------------------------
+// Model resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a "<provider>/<id>" model string through the registry.
+ * Returns the `Model<Api>` on success, or an error string on failure.
+ * No silent fallback — the caller must handle errors.
+ */
+export function resolveModel(
+    registry: ModelRegistry,
+    name: string,
+): Model<Api> | string {
+    const i = name.indexOf("/");
+    if (i < 0) {
+        return `malformed model "${name}", expected <provider>/<id>`;
+    }
+    const provider = name.slice(0, i);
+    const id = name.slice(i + 1);
+    const model = registry.find(provider, id);
+    if (!model) {
+        return `model "${name}" not found`;
+    }
+    if (!registry.hasConfiguredAuth(model)) {
+        return `no auth configured for provider "${provider}"`;
+    }
+    return model;
+}
+
+// ---------------------------------------------------------------------------
+// Resource loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a ResourceLoader for an agent session.
+ * - No extensions / no skills by default (explicit-only).
+ * - System prompt appended when non-empty.
+ */
+export function buildResourceLoader(agent: AgentConfig, cwd: string): DefaultResourceLoader {
+    const exts: string[] = agent.extensions ?? [];
+    const skills: string[] = agent.skills ?? [];
+
+    return new DefaultResourceLoader({
+        cwd,
+        agentDir: getAgentDir(),
+        appendSystemPrompt: agent.systemPrompt?.trim() ? [agent.systemPrompt] : undefined,
+
+        noExtensions: true,
+        additionalExtensionPaths: exts.length > 0 ? exts : undefined,
+
+        noSkills: skills.length === 0,
+        skillsOverride:
+            skills.length > 0
+                ? (base: { skills: Skill[]; diagnostics: ResourceDiagnostic[] }) => ({
+                        skills: base.skills.filter((s) => skills.includes(s.name)),
+                        diagnostics: base.diagnostics,
+                    })
+                : undefined,
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Single agent run
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a single agent via an in-process SDK session.
+ */
+export async function runAgent(
+    agent: AgentConfig,
+    task: string,
+    cwd: string,
+    modelRegistry: ModelRegistry,
+    authStorage: AuthStorage,
+    signal?: AbortSignal,
+    onUpdate?: OnUpdateCallback,
+): Promise<SingleResult> {
+    const result: SingleResult = {
+        agent: agent.name,
+        agentSource: agent.source,
+        task,
+        exitCode: 0,
+        messages: [],
+        stderr: "",
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+    };
+    let session: Awaited<ReturnType<typeof createAgentSession>>["session"] | undefined;
+
+    try {
+        let model: Model<Api> | undefined;
+        let thinkingLevel: ThinkingLevel | undefined;
+
+        if (agent.model) {
+            const resolved = resolveModel(modelRegistry, agent.model);
+            if (typeof resolved === "string") {
+                result.exitCode = 1;
+                result.errorMessage = resolved;
+                return result;
+            }
+            model = resolved;
+            thinkingLevel = agent.thinkingLevel as ThinkingLevel | undefined;
+        }
+
+        const loader = buildResourceLoader(agent, cwd);
+        await loader.reload();
+
+        const { session: createdSession } = await createAgentSession({
+            cwd,
+            model,
+            thinkingLevel,
+            tools: agent.tools,
+            resourceLoader: loader,
+            sessionManager: SessionManager.create(cwd),
+            authStorage,
+            modelRegistry,
+            settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
+        });
+        session = createdSession;
+
+        session.subscribe((event: AgentSessionEvent) => {
+            if (event.type === "turn_end") {
+                result.usage.turns++;
+                const msg = event.message as Message;
+                const u = (msg as any).usage;
+                if (u) {
+                    result.usage.input += u.input || 0;
+                    result.usage.output += u.output || 0;
+                    result.usage.cacheRead += u.cacheRead || 0;
+                    result.usage.cacheWrite += u.cacheWrite || 0;
+                    result.usage.cost += u.cost?.total || 0;
+                    result.usage.contextTokens = u.totalTokens || 0;
+                }
+                if (!result.model && (msg as any).model) result.model = (msg as any).model;
+                if ((msg as any).stopReason) result.stopReason = (msg as any).stopReason;
+                if ((msg as any).errorMessage) result.errorMessage = (msg as any).errorMessage;
+                result.messages.push(msg, ...event.toolResults);
+                onUpdate?.(result);
+            }
+        });
+
+        if (signal) {
+            if (signal.aborted) {
+                session.abort();
+            } else {
+                signal.addEventListener("abort", () => session!.abort(), { once: true });
+            }
+        }
+
+        await session.prompt(task);
+        result.exitCode = 0;
+        return result;
+    } catch (err) {
+        result.exitCode = 1;
+        result.errorMessage = err instanceof Error ? err.message : String(err);
+        return result;
+    } finally {
+        session?.dispose();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Parallel execution
+// ---------------------------------------------------------------------------
+
+async function mapWithConcurrencyLimit<TIn, TOut>(
+    items: TIn[],
+    concurrency: number,
+    fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+    if (items.length === 0) return [];
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    const results: TOut[] = new Array(items.length);
+    let nextIndex = 0;
+    const workers = new Array(limit).fill(null).map(async () => {
+        while (true) {
+            const current = nextIndex++;
+            if (current >= items.length) return;
+            results[current] = await fn(items[current], current);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+
+export const MAX_CONCURRENCY = 4;
+
+/**
+ * Run multiple agents in parallel with a concurrency cap.
+ */
+export async function runParallel(
+    cwd: string,
+    agents: AgentConfig[],
+    tasks: Array<{ agent: string; task: string; cwd?: string }>,
+    modelRegistry: ModelRegistry,
+    authStorage: AuthStorage,
+    signal?: AbortSignal,
+    onUpdate?: (results: SingleResult[]) => void,
+): Promise<SingleResult[]> {
+    // Track all results; exitCode: -1 = still running
+    const allResults: SingleResult[] = tasks.map((t) => ({
+        agent: t.agent,
+        agentSource: "unknown" as const,
+        task: t.task,
+        exitCode: -1,
+        messages: [],
+        stderr: "",
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+    }));
+
+    const emitUpdate = () => onUpdate?.([...allResults]);
+
+    const results = await mapWithConcurrencyLimit(tasks, MAX_CONCURRENCY, async (t, index) => {
+        const agent = agents.find((a) => a.name === t.agent);
+        if (!agent) {
+            const result: SingleResult = {
+                agent: t.agent,
+                agentSource: "unknown",
+                task: t.task,
+                exitCode: 1,
+                messages: [],
+                stderr: `Unknown agent: "${t.agent}"`,
+                usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+            };
+            allResults[index] = result;
+            emitUpdate();
+            return result;
+        }
+
+        const result = await runAgent(
+            agent,
+            t.task,
+            t.cwd ?? cwd,
+            modelRegistry,
+            authStorage,
+            signal,
+            (partial) => {
+                allResults[index] = partial;
+                emitUpdate();
+            },
+        );
+        allResults[index] = result;
+        emitUpdate();
+        return result;
+    });
+
+    return results;
+}

package/skills/authoring-agent-specs/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: authoring-agent-specs
+description: Authoring agent spec files (frontmatter + system prompt) for pi-subagent. Use when defining new agents, updating agent behavior, or scaffolding specialist prompts.
+---
+
+# Authoring Agent Specs
+
+Create well-formed agent spec files that pi-subagent can discover and invoke.
+
+## Agent Spec Format
+
+An agent is defined in a `.md` file with YAML frontmatter followed by a system prompt body.
+
+```markdown
+---
+name: my-agent
+description: One-line summary shown in agent listings
+model: anthropic/claude-sonnet-4.6
+tools: read,bash,edit,write
+---
+
+You are a specialist in X. Keep responses concise.
+Always confirm before making destructive changes.
+```
+
+### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Identifier used when invoking the agent. Lowercase, hyphens, numbers only. |
+| `description` | One-line summary shown in agent listings and the subagent tool description. |
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `model` | `<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` | `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` | Comma-separated allowed tools (e.g. `read,bash,edit`). All tools if absent. |
+| `extensions` | Omit or empty → none; list of paths → exactly those extensions loaded. Supports `${ENV_VAR}` substitution. |
+| `skills` | Omit or empty → none; list of names → exactly those skills loaded. |
+
+### `extensions` and `skills`
+
+Subagents start with **no extensions and no skills** by default. List them explicitly if the agent needs them.
+
+| 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. |
+
+## Where to Place Agents
+
+### User-level (available in all projects)
+
+```
+~/.pi/agent/agents/<name>.md
+```
+
+### Project-level (available in one project)
+
+```
+<project-root>/.pi/agents/<name>.md
+```
+
+### Bundled with an extension
+
+```
+<extension-dir>/agents/<name>.md
+```
+
+Choose based on scope:
+- **User-level** for personal agents you reuse across projects.
+- **Project-level** for agents specific to a codebase (e.g. a framework-specific reviewer).
+- **Extension-bundled** when distributing agents as part of a package.
+
+## Naming Rules
+
+- Lowercase letters, numbers, and hyphens only.
+- No leading, trailing, or consecutive hyphens.
+- The file name (minus `.md`) should match the `name` field for clarity, though pi-subagent reads the frontmatter `name`, not the filename.
+
+**Good:** `security-reviewer`, `docs-writer`, `perf-analyzer`
+**Bad:** `SecurityReviewer`, `-reviewer`, `code--reviewer`
+
+## System Prompt Guidelines
+
+The body after the frontmatter becomes the agent's system prompt. Effective prompts are:
+
+- **Role-specific.** Define what the agent is expert at.
+- **Constrained.** Specify output format (e.g. "Respond with a bullet list").
+- **Scoped.** State what the agent should NOT do.
+- **Concise.** Subagents have isolated context — tight prompts produce better results.
+
+## Examples
+
+### Code Reviewer
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for correctness, clarity, and security issues
+tools: read,find,grep,ls
+---
+
+You are a thorough code reviewer. For each file or diff you review:
+
+1. Identify correctness bugs and logic errors.
+2. Flag security vulnerabilities.
+3. Assess code clarity and naming.
+4. Suggest specific improvements.
+
+Respond with a brief summary followed by a bullet list of issues, grouped by severity (critical, warning, minor).
+```
+
+### Documentation Writer
+
+```markdown
+---
+name: docs-writer
+description: Writes clear, concise documentation and JSDoc comments
+tools: read,bash,edit,write
+---
+
+You write documentation. Follow these rules:
+
+- Use active voice and present tense.
+- Keep paragraphs under 4 sentences.
+- Include code examples for non-trivial APIs.
+- For JSDoc: include @param, @returns, and @throws when applicable.
+- Match the existing documentation style in the codebase.
+```
+
+### Agent with Explicit Extensions and Skills
+
+```markdown
+---
+name: code-reviewer-with-skill
+description: Reviews code using a custom review skill
+tools: read,bash,edit
+extensions: ./my-extension
+skills: code-review
+---
+
+You review code using the review skill for structured feedback.
+```

package/tests/agent.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+import { parseCommaList, formatAgentList } from "../agent.js";
+import type { AgentConfig } from "../agent.js";
+
+describe("parseCommaList", () => {
+    it("returns undefined for undefined input", () => {
+        expect(parseCommaList(undefined)).toBe(undefined);
+    });
+    
+    it("returns undefined for null input", () => {
+        expect(parseCommaList(null)).toBe(undefined);
+    });
+    
+    it("returns undefined for empty string", () => {
+        expect(parseCommaList("")).toBe(undefined);
+    });
+    
+    it("returns a single-element array for a single path", () => {
+        expect(parseCommaList("path/a")).toEqual(["path/a"]);
+    });
+    
+    it("splits a comma-separated string into an array", () => {
+        expect(parseCommaList("path/a, path/b")).toEqual(["path/a", "path/b"]);
+    });
+    
+    it("trims whitespace from each segment", () => {
+        expect(parseCommaList("  path/a  ,  path/b  ")).toEqual(["path/a", "path/b"]);
+    });
+    
+    it("returns undefined when all segments are empty after filtering", () => {
+        expect(parseCommaList(",")).toBe(undefined);
+    });
+    
+    it("returns undefined for non-string non-null input", () => {
+        expect(parseCommaList(42)).toBe(undefined);
+    });
+});
+
+describe("formatAgentList", () => {
+    const makeAgent = (name: string): AgentConfig => ({
+        name,
+        description: `${name} description`,
+        systemPrompt: "",
+        source: "user",
+        filePath: `/agents/${name}.md`,
+    });
+    
+    it("returns 'none' for an empty array", () => {
+        expect(formatAgentList([], 10)).toEqual({ text: "none", remaining: 0 });
+    });
+    
+    it("lists all agents when count is below maxItems", () => {
+        const agents = [makeAgent("alpha"), makeAgent("beta")];
+        const result = formatAgentList(agents, 10);
+        expect(result.remaining).toBe(0);
+        expect(result.text).toContain("alpha (user): alpha description");
+        expect(result.text).toContain("beta (user): beta description");
+    });
+    
+    it("limits output to maxItems and reports remaining count", () => {
+        const agents = [makeAgent("a"), makeAgent("b"), makeAgent("c")];
+        const result = formatAgentList(agents, 2);
+        expect(result.remaining).toBe(1);
+        expect(result.text).toContain("a (user)");
+        expect(result.text).toContain("b (user)");
+        expect(result.text).not.toContain("c (user)");
+    });
+    
+    it("formats each agent as 'name (source): description'", () => {
+        const agents = [makeAgent("my-agent")];
+        const result = formatAgentList(agents, 10);
+        expect(result.text).toBe("my-agent (user): my-agent description");
+    });
+});

package/tests/runner.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi } from "vitest";
+import { resolveModel, buildResourceLoader } from "../runner.js";
+
+// ---------------------------------------------------------------------------
+// resolveModel
+// ---------------------------------------------------------------------------
+
+describe("resolveModel", () => {
+    const mockModel = { id: "claude-sonnet-4-5", provider: "anthropic" };
+
+    const makeRegistry = (found: any = undefined, hasAuth = true) => ({
+        find: vi.fn().mockReturnValue(found),
+        hasConfiguredAuth: vi.fn().mockReturnValue(hasAuth),
+    });
+
+    it("returns error string for malformed name (no slash)", () => {
+        const registry = makeRegistry();
+        const result = resolveModel(registry as any, "claude-sonnet-4-5");
+        expect(result).toBe('malformed model "claude-sonnet-4-5", expected <provider>/<id>');
+    });
+
+    it("resolves well-formed provider/id via registry", () => {
+        const registry = makeRegistry(mockModel);
+        const result = resolveModel(registry as any, "anthropic/claude-sonnet-4-5");
+        expect(registry.find).toHaveBeenCalledWith("anthropic", "claude-sonnet-4-5");
+        expect(result).toBe(mockModel);
+    });
+
+    it("returns error string for unknown model", () => {
+        const registry = makeRegistry(undefined);
+        const result = resolveModel(registry as any, "unknown/model-x");
+        expect(result).toBe('model "unknown/model-x" not found');
+    });
+
+    it("returns error string when no auth is configured", () => {
+        const registry = makeRegistry(mockModel, false);
+        const result = resolveModel(registry as any, "anthropic/claude-sonnet-4-5");
+        expect(result).toBe('no auth configured for provider "anthropic"');
+    });
+
+    it("returns model when auth is configured", () => {
+        const registry = makeRegistry(mockModel, true);
+        const result = resolveModel(registry as any, "anthropic/claude-sonnet-4-5");
+        expect(result).toBe(mockModel);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// buildResourceLoader
+// ---------------------------------------------------------------------------
+
+describe("buildResourceLoader", () => {
+    const baseAgent = {
+        name: "test-agent",
+        description: "test",
+        systemPrompt: "You are a helper.",
+        source: "user" as const,
+        filePath: "/agents/test.md",
+    };
+
+    it("always sets noExtensions=true even when extensions are listed", () => {
+        // Without extensions
+        const loader1 = buildResourceLoader(baseAgent, "/tmp");
+        expect(loader1).toBeDefined();
+
+        // With extensions — noExtensions should still be true
+        const loader2 = buildResourceLoader(
+            { ...baseAgent, extensions: ["./ext-a"] },
+            "/tmp",
+        );
+        expect(loader2).toBeDefined();
+    });
+
+    it("sets noSkills=true when no skills", () => {
+        const loader = buildResourceLoader(baseAgent, "/tmp");
+        expect(loader).toBeDefined();
+    });
+
+    it("sets appendSystemPrompt when systemPrompt is non-empty", () => {
+        const loader = buildResourceLoader(baseAgent, "/tmp");
+        expect(loader).toBeDefined();
+    });
+
+    it("does not set appendSystemPrompt when systemPrompt is empty", () => {
+        const agent = { ...baseAgent, systemPrompt: "" };
+        const loader = buildResourceLoader(agent, "/tmp");
+        expect(loader).toBeDefined();
+    });
+
+    it("passes extensions as additionalExtensionPaths", () => {
+        const agent = { ...baseAgent, extensions: ["./ext-a", "./ext-b"] };
+        const loader = buildResourceLoader(agent, "/tmp");
+        expect(loader).toBeDefined();
+    });
+
+    it("filters skills by name", () => {
+        const agent = { ...baseAgent, skills: ["grep", "find"] };
+        const loader = buildResourceLoader(agent, "/tmp");
+        expect(loader).toBeDefined();
+    });
+
+    it("handles both extensions and skills", () => {
+        const agent = {
+            ...baseAgent,
+            extensions: ["./ext-a"],
+            skills: ["grep"],
+        };
+        const loader = buildResourceLoader(agent, "/tmp");
+        expect(loader).toBeDefined();
+    });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config";
+import { execSync } from "node:child_process";
+import path from "node:path";
+
+const globalRoot = execSync("pnpm root -g").toString().trim();
+const piCodingAgentEntry = path.join(
+    globalRoot,
+    "@earendil-works/pi-coding-agent/dist/index.js"
+);
+
+export default defineConfig({
+    resolve: {
+        alias: {
+            "@earendil-works/pi-coding-agent": piCodingAgentEntry,
+        },
+    },
+});