@mystilleef/pi-subagent 0.9.0 → 0.10.1

package/README.md

@@ -1,16 +1,12 @@
-# Subagent
+# Subagents for pi
 
-`pi-subagent` adds isolated subagent orchestration to
-[Pi](https://github.com/earendil-works/pi). It provides a `subagent`
-tool and `/run` command for delegating work to specialized agents in
-separate child Pi processes. Designed especially for the `SPAE`
-framework, but doesn't require it.
-
-## Action
-
-Agents in
+Designed to orchestrate agents for the
+[SPAE framework](https://github.com/mystilleef/spae-framework). Agents
+in
 [action](https://raw.githubusercontent.com/mystilleef/pi-subagent/main/assets/parallel-agents-demo.mp4).
 
+---
+
 ## Installation
 
 **Install from `npm`:**
@@ -25,13 +21,19 @@ pi install npm:@mystilleef/pi-subagent
 pi -e npm:@mystilleef/pi-subagent
 ```
 
+---
+
 ## Features
 
 - **Asynchronous:** Agents run in the background.
 - **Parallel:** Run many agents simultaneously.
 - **Isolated:** Each delegated task receives a separate context window.
-- **Simple:** No complex orchestration workflow required.
-- **Bloat-free:** No bundled agents.
+- **Nested:** `Subagents` can spawn other `subagents`.
+- **Simple:** No complex orchestration syntax.
+- **Bloat-free:** No bundled agents. Write your own. Or use those from
+  the [SPAE Framework](https://github.com/mystilleef/spae-framework).
+
+---
 
 ## Usage
 
@@ -70,12 +72,16 @@ commits; use the query agent to summarize the project.
 /cancel-subagent
 ```
 
+---
+
 ## _SPAE_ Workflow
 
-`pi-subagent` supports the
-[`SPAE` Framework](https://github.com/mystilleef/spae-framework), but
-doesn't require it. `SPAE` provides pre-built agents and skills for a
-structured workflow.
+The official extension for the
+[SPAE Framework](https://github.com/mystilleef/spae-framework). The
+framework provides pre-built agents and skills for a structured, or
+orchestrated, workflow.
+
+### Structured
 
 | Phase | Agent                     | Purpose                                       |
 | ----- | ------------------------- | --------------------------------------------- |
@@ -85,32 +91,44 @@ structured workflow.
 | 4     | `/run build`              | Carry out tasks from `PLAN.md`                |
 | 5     | `/run verify`             | Verify implementation against `SPEC.md`       |
 
+### Orchestrated
+
+| Agent                            | Purpose                                       |
+| -------------------------------- | --------------------------------------------- |
+| `/run orchestrate <requirement>` | Run all phases of the `SPAE` workflow         |
+| `/run prepare <requirement>`     | Run preparatory phases of the `SPAE` workflow |
+| `/run spawn`                     | Spawn build agents for each task in a plan    |
+
+---
+
 ## Agent definitions
 
-This package ships no agents. Define agents as Markdown files with YAML
-`frontmatter` and a Markdown system prompt body.
+This extension ships no agents. Define agents as Markdown files with
+YAML `frontmatter` and a Markdown system prompt body.
 
-**Discovery locations:**
+### Discovery locations
 
 - User-global agents: `~/.pi/agents/*.md`
 - Project-local agents: nearest `.pi/agents/*.md`
 
-**Required `frontmatter`:**
+### Required front matter
 
 ```yaml
 name: review
 description: Review code for correctness and maintainability.
 ```
 
-**Optional `frontmatter`:**
+### Optional front matter
 
 ```yaml
 tools: read, bash, edit
 skills: code-review
 thinking: medium
+provider: deepseek
+model: deepseek-v4-flash
 ```
 
-**Accepted `thinking` values:**
+### Accepted thinking values
 
 - `off`
 - `minimal`
@@ -119,6 +137,8 @@ thinking: medium
 - `high`
 - `xhigh`
 
+---
+
 ## Tool
 
 The extension also registers a `subagent` tool for model-driven
@@ -130,9 +150,11 @@ delegation.
 - `task`: task prompt for the child agent.
 - `agentScope`: optional lookup scope, one of `user`, `project`, or
   `both`.
-- `debug`: optional flag that requests child diagnostic details. Full child
-  messages and raw internals require `PI_SUBAGENT_DEBUG_ENABLED=1` in the
-  host environment.
+- `debug`: optional flag that requests child diagnostic details. Full
+  child messages and raw internals require `PI_SUBAGENT_DEBUG_ENABLED=1`
+  in the host environment.
+
+---
 
 ## Security
 
@@ -144,39 +166,43 @@ executable automation.
 
 - Review project-local agents before running them.
 - Avoid delegating secrets unless the agent and tools need them.
-- Treat child-agent prompts, tool arguments, stderr, and debug transcripts as
-  potentially sensitive.
+- Treat child-agent prompts, tool arguments, `stderr`, and debug
+  transcripts as potentially sensitive.
 - Enable debug details only for trusted investigations. `debug: true` or
   `/run --debug` can expose child conversation transcripts, termination
-  internals, and stderr only when the host explicitly sets
+  internals, and `stderr` only when the host explicitly sets
   `PI_SUBAGENT_DEBUG_ENABLED=1`.
 - Prefer trusted repositories for shared agent definitions.
 - Remember that child agents can call their configured tools.
 
+---
+
 ## Configuration and limits
 
 **Environment variables:**
 
-- `PI_SUBAGENT_DEPTH`: current nested subagent depth counter set internally
-  for child processes.
-- `PI_SUBAGENT_MAX_DEPTH`: max nested subagent depth. Default: `3`. Values
-  above `10` clamp to the internal ceiling `10`; deeper nesting increases
-  cost, latency, and runaway delegation risk.
+- `PI_SUBAGENT_DEPTH`: current nested subagent depth counter set
+  internally for child processes.
+- `PI_SUBAGENT_MAX_DEPTH`: max nested subagent depth. Default: `3`.
+  Values above `10` clamp to the internal ceiling `10`; deeper nesting
+  increases cost, latency, and runaway delegation risk.
 - `PI_SUBAGENT_AGENT_END_GRACE_MS`: child process grace period after
   `agent_end` before forced termination. Default: `250`.
-- `PI_SUBAGENT_MAX_STDERR_BYTES`: max captured child stderr bytes. Default:
-  `10000`.
+- `PI_SUBAGENT_MAX_STDERR_BYTES`: max captured child `stderr` bytes.
+  Default: `10000`.
 - `PI_SUBAGENT_MAX_OUTPUT_BYTES`: max returned output bytes. Default:
   `50000`.
 - `PI_SUBAGENT_MAX_OUTPUT_LINES`: max returned output lines. Default:
   `500`.
 - `PI_SUBAGENT_DEBUG_ENABLED`: debug detail authorization. Set to `1` to
-  allow `debug: true` or `/run --debug` to include sanitized child messages,
-  termination internals, and stderr; unset values keep non-debug detail
-  behavior.
+  allow `debug: true` or `/run --debug` to include sanitized child
+  messages, termination internals, and `stderr`; unset values keep
+  non-debug detail behavior.
+
+Limit variables parse as positive integers. Empty, zero, negative,
+decimal, `Infinity`, and non-numeric values fall back to defaults.
 
-Limit variables parse as positive integers. Empty, zero, negative, decimal,
-`Infinity`, and non-numeric values fall back to defaults.
+---
 
 ## Troubleshooting
 
@@ -203,6 +229,8 @@ Limit variables parse as positive integers. Empty, zero, negative, decimal,
   `PI_SUBAGENT_MAX_OUTPUT_LINES`.
 - Ask the child agent for a shorter summary.
 
+---
+
 ## Development
 
 **Install dependencies:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -64,14 +64,14 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16",
-    "@earendil-works/pi-agent-core": "^0.78.1",
-    "@earendil-works/pi-ai": "^0.78.1",
-    "@earendil-works/pi-coding-agent": "^0.78.1",
-    "@earendil-works/pi-tui": "^0.78.1",
+    "@biomejs/biome": "^2.5.0",
+    "@earendil-works/pi-agent-core": "^0.79.3",
+    "@earendil-works/pi-ai": "^0.79.3",
+    "@earendil-works/pi-coding-agent": "^0.79.3",
+    "@earendil-works/pi-tui": "^0.79.3",
     "@types/bun": "^1.3.14",
-    "@types/node": "^25.9.2",
-    "typebox": "^1.2.2",
+    "@types/node": "^25.9.3",
+    "typebox": "^1.2.9",
     "typescript": "^6.0.3"
   }
 }

package/src/agent/agent-cache.ts

@@ -123,6 +123,7 @@ async function hashMarkdownFileAsync(
       .update(await fsPromises.readFile(path.join(dir, fileName)))
       .digest("hex");
   } catch {
+    /* missing or unreadable files return null to skip caching */
     return null;
   }
 }

package/src/agent/agents.ts

@@ -23,6 +23,8 @@ export interface AgentConfig {
   tools?: string[] | undefined;
   skills?: string[] | undefined;
   thinking?: ThinkingLevel | undefined;
+  model?: string | undefined;
+  provider?: string | undefined;
   systemPrompt: string;
   source: AgentSource;
   filePath: string;
@@ -74,6 +76,12 @@ function parseThinkingLevel(raw: unknown): ThinkingLevel | undefined {
     : undefined;
 }
 
+function parseOptionalString(raw: unknown): string | undefined {
+  if (typeof raw !== "string") return undefined;
+  const normalized = raw.trim();
+  return normalized.length > 0 ? normalized : undefined;
+}
+
 function parseAgentConfig(
   content: string,
   source: AgentSource,
@@ -83,6 +91,7 @@ function parseAgentConfig(
   try {
     parsed = parseFrontmatter<Record<string, unknown>>(content);
   } catch {
+    /* malformed frontmatter returns null to skip invalid agent files */
     return null;
   }
   const { frontmatter, body } = parsed;
@@ -98,22 +107,31 @@ function parseAgentConfig(
     tools: rawTools,
     skills: rawSkills,
     thinking: rawThinking,
+    model: rawModel,
+    provider: rawProvider,
   } = frontmatter;
   if (typeof name !== "string" || typeof description !== "string") return null;
   if (rawTools != null && typeof rawTools !== "string") return null;
   if (rawSkills != null && typeof rawSkills !== "string") return null;
   if (rawThinking != null && typeof rawThinking !== "string") return null;
+  if (rawModel != null && typeof rawModel !== "string") return null;
+  if (rawProvider != null && typeof rawProvider !== "string") return null;
   const tools = parseCommaList(rawTools);
   const skills = Object.hasOwn(frontmatter, "skills")
     ? (parseCommaList(rawSkills) ?? [])
     : undefined;
   const thinking = parseThinkingLevel(rawThinking);
+  const model = parseOptionalString(rawModel);
+  const provider = parseOptionalString(rawProvider);
+  if (provider !== undefined && model === undefined) return null;
   return {
     name,
     description,
     tools,
     skills,
     thinking,
+    model,
+    provider,
     systemPrompt: body,
     source,
     filePath,
@@ -130,6 +148,7 @@ async function loadAgentEntryAsync(
   try {
     content = await fsPromises.readFile(filePath, "utf-8");
   } catch {
+    /* unreadable files are skipped silently during agent discovery */
     return null;
   }
   return parseAgentConfig(content, source, filePath);
@@ -156,7 +175,7 @@ async function loadAgentsFromDirAsync(
   return { agents, markdownFiles };
 }
 
-export function isMarkdownDirent(entry: Dirent): boolean {
+function isMarkdownDirent(entry: Dirent): boolean {
   return (
     entry.name.endsWith(".md") && (entry.isFile() || entry.isSymbolicLink())
   );
@@ -175,6 +194,7 @@ export async function readMarkdownDirWithStatusAsync(
     const entries = await fsPromises.readdir(dir, { withFileTypes: true });
     return { entries: entries.filter(isMarkdownDirent), ok: true };
   } catch {
+    /* missing or inaccessible directories return empty listing */
     return { entries: [], ok: false };
   }
 }
@@ -187,6 +207,7 @@ export async function isDirectoryAsync(p: string): Promise<boolean> {
   try {
     return (await fsPromises.stat(p)).isDirectory();
   } catch {
+    /* stat failures indicate non-existent or inaccessible paths */
     return false;
   }
 }

package/src/child/child-events.ts

@@ -10,6 +10,7 @@ function tryFirstResult(details: unknown): Record<string, unknown> | null {
     if (typeof nested !== "object" || nested === null) return null;
     return nested as Record<string, unknown>;
   } catch {
+    /* malformed details structure returns null to use fallback preview */
     return null;
   }
 }
@@ -90,6 +91,7 @@ export function parseChildEventLine(line: string): ChildEventParseResult {
   try {
     event = JSON.parse(line);
   } catch {
+    /* malformed JSON lines are marked invalid for diagnostic reporting */
     return { kind: "invalid", line };
   }
   if (