@mystilleef/pi-subagent 0.8.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,8 +150,11 @@ delegation.
 - `task`: task prompt for the child agent.
 - `agentScope`: optional lookup scope, one of `user`, `project`, or
   `both`.
-- `debug`: optional flag that includes full child messages in result
-  details.
+- `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
 
@@ -143,19 +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.
+- 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
+  `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`: nested subagent depth guard. Nested calls stop at
-  depth `3`.
+- `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_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.
+
+Limit variables parse as positive integers. Empty, zero, negative,
+decimal, `Infinity`, and non-numeric values fall back to defaults.
+
+---
 
 ## Troubleshooting
 
@@ -173,7 +220,7 @@ executable automation.
 
 **Nested subagent blocked:**
 
-- Nested delegation hits the `PI_SUBAGENT_DEPTH` safety limit.
+- Nested delegation hits the `PI_SUBAGENT_MAX_DEPTH` safety limit.
 - Run the child task directly from the parent session instead.
 
 **Truncated output:**
@@ -182,6 +229,8 @@ executable automation.
   `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.8.0",
+  "version": "0.10.1",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -50,7 +50,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome check --write --unsafe --error-on-warnings .",
     "migrate": "biome migrate --write",
-    "coverage": "bun test --coverage",
+    "coverage": "bun test --parallel --parallel-delay=0",
     "check": "bun lint && bun typecheck",
     "verify": "bun migrate && bun check && bun coverage",
     "pack:smoke": "bun scripts/pack-smoke.ts",
@@ -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.1",
-    "typebox": "^1.2.1",
+    "@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

@@ -20,9 +20,11 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 export interface AgentConfig {
   name: string;
   description: string;
-  tools?: string[];
-  skills?: string[];
-  thinking?: ThinkingLevel;
+  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

@@ -1,21 +1,20 @@
 import { makeToolPreview } from "../output/normalize.js";
 import type { ToolActivity } from "../shared/types.js";
 
-// Extracts results[0] from details; null-safe for malformed input.
 function tryFirstResult(details: unknown): Record<string, unknown> | null {
   try {
     if (typeof details !== "object" || details === null) return null;
-    const results = (details as Record<string, unknown>).results;
+    const results = (details as Record<string, unknown>)["results"];
     if (!Array.isArray(results) || results.length === 0) return null;
     const nested = results[0];
     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;
   }
 }
 
-// Malformed details (null result) falls back to { toolName }.
 function parseToolActivity(
   toolName: string,
   partialResult: { content?: unknown; details?: unknown },
@@ -24,23 +23,25 @@ function parseToolActivity(
   if (!nestedRecord) return { toolName, inputSummary: toolName };
   const isSubagent = toolName === "subagent";
   const activity: ToolActivity = { toolName };
-  const agent = typeof nestedRecord.agent === "string" && nestedRecord.agent;
+  const agent =
+    typeof nestedRecord["agent"] === "string" && nestedRecord["agent"];
   activity.inputSummary =
     isSubagent && agent ? makeToolPreview(toolName, nestedRecord) : toolName;
   if (
-    typeof nestedRecord.instanceName === "string" &&
-    nestedRecord.instanceName
+    typeof nestedRecord["instanceName"] === "string" &&
+    nestedRecord["instanceName"]
   ) {
-    activity.instanceName = nestedRecord.instanceName;
+    activity.instanceName = nestedRecord["instanceName"] as string;
   }
-  const progress = nestedRecord.progress;
+  const progress = nestedRecord["progress"];
   if (typeof progress === "object" && progress !== null) {
-    const activeToolActivity = (progress as Record<string, unknown>)
-      .activeToolActivity;
+    const activeToolActivity = (progress as Record<string, unknown>)[
+      "activeToolActivity"
+    ];
     if (
       typeof activeToolActivity === "object" &&
       activeToolActivity !== null &&
-      typeof (activeToolActivity as Record<string, unknown>).toolName ===
+      typeof (activeToolActivity as Record<string, unknown>)["toolName"] ===
         "string"
     ) {
       const childActivity = activeToolActivity as ToolActivity;
@@ -90,27 +91,28 @@ 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 (
     typeof event === "object" &&
     event !== null &&
     "type" in event &&
-    typeof (event as Record<string, unknown>).type === "string" &&
-    KNOWN_TYPES.has((event as Record<string, unknown>).type as string)
+    typeof (event as Record<string, unknown>)["type"] === "string" &&
+    KNOWN_TYPES.has((event as Record<string, unknown>)["type"] as string)
   ) {
     const record = event as Record<string, unknown>;
-    if (record.type === TOOL_EXECUTION_UPDATE_EVENT) {
+    if (record["type"] === TOOL_EXECUTION_UPDATE_EVENT) {
       if (
-        typeof record.toolName !== "string" ||
-        typeof record.partialResult !== "object" ||
-        record.partialResult === null
+        typeof record["toolName"] !== "string" ||
+        typeof record["partialResult"] !== "object" ||
+        record["partialResult"] === null
       ) {
         return { kind: "unknown", event };
       }
-      record.toolActivity = parseToolActivity(
-        record.toolName as string,
-        record.partialResult as { content?: unknown; details?: unknown },
+      record["toolActivity"] = parseToolActivity(
+        record["toolName"] as string,
+        record["partialResult"] as { content?: unknown; details?: unknown },
       );
     }
     return { kind: "known", event: event as ChildKnownEvent };