@mystilleef/pi-subagent 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lateef Alabi-Oki
+
+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,45 @@
+# Subagent
+
+This `pi` extension provides a `subagent` tool designed for the
+[SPAE Framework](https://github.com/mystilleef/spae-framework).
+
+## Installation
+
+```sh
+pi install npm:@mystilleef/pi-subagent
+```
+
+## Features
+
+- **Asynchronous:** Agents always run in background.
+- **Parallel:** Run more than one agents simultaneously.
+- **Simplicity:** No advanced orchestration workflows.
+- **Bloat-free:** No pre-installed agents.
+
+## Usage
+
+Invoke an agent with:
+
+```text
+/run agent [optional task]
+```
+
+Stop running agents with:
+
+```text
+/cancel-subagent
+```
+
+## Workflow
+
+The [SPAE Framework](https://github.com/mystilleef/spae-framework) emphasizes a structured workflow.
+
+| Phase | Agent                     | Purpose                                       |
+| ----- | ------------------------- | --------------------------------------------- |
+| 1     | `/run spec <requirement>` | Distill requirements into `SPEC.md`           |
+| 2     | `/run plan`               | Decompose `SPEC.md` into an atomic task graph |
+| 3     | `/run inspect`            | Perform gap analysis and optimize `PLAN.md`   |
+| 4     | `/run build`              | Carry out tasks from `PLAN.md`                |
+| 5     | `/run verify`             | Verify implementation against `SPEC.md`       |
+
+Visit the [SPAE Framework](https://github.com/mystilleef/spae-framework) for pre-packaged agents and their associated skills.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@mystilleef/pi-subagent",
+  "version": "0.3.0",
+  "description": "Pi subagent for the SPAE Framework",
+  "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mystilleef/pi-subagent.git"
+  },
+  "keywords": [
+    "pi",
+    "agent",
+    "subagent",
+    "orchestration",
+    "ai",
+    "llm"
+  ],
+  "module": "src/index.ts",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.13"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "verify": "bun check && bun test",
+    "coverage": "bun check && bun test --coverage",
+    "check": "biome check --fix --unsafe . && tsc --noEmit",
+    "migrate": "biome migrate --write",
+    "release": "sh -c 'npm version \"$1\" && git push --follow-tags && bun publish --access public' --"
+  },
+  "dependencies": {
+    "@earendil-works/pi-agent-core": "^0.74.0",
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0",
+    "typebox": "^1.1.38"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.8.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/agent-cache.ts

@@ -0,0 +1,41 @@
+import path from "node:path";
+import {
+  type AgentDiscoveryResult,
+  type AgentScope,
+  discoverAgents,
+} from "./agents.js";
+
+export type AgentDiscoveryCacheEntry = AgentDiscoveryResult & { ts: number };
+export type AgentDiscoveryCache = Map<string, AgentDiscoveryCacheEntry>;
+export const AGENT_DISCOVERY_CACHE_TTL_MS = 3_000;
+const sharedAgentDiscoveryCache: AgentDiscoveryCache = new Map();
+
+export function resetAgentDiscoveryCache(): void {
+  sharedAgentDiscoveryCache.clear();
+}
+
+export function getCachedAgentDiscovery(
+  cwd: string,
+  scope: AgentScope,
+  cache: AgentDiscoveryCache = sharedAgentDiscoveryCache,
+  cacheTtlMs = AGENT_DISCOVERY_CACHE_TTL_MS,
+): AgentDiscoveryCacheEntry {
+  const key = `${path.resolve(cwd)}\0${scope}`;
+  const now = Date.now();
+  const entry = cache.get(key);
+  if (entry && now - entry.ts <= cacheTtlMs) return entry;
+  const nextEntry = { ...discoverAgents(cwd, scope), ts: now };
+  cache.set(key, nextEntry);
+  return nextEntry;
+}
+
+export function getCachedAgentCompletions(
+  prefix: string,
+  cwd = process.cwd(),
+  cache: AgentDiscoveryCache = sharedAgentDiscoveryCache,
+  cacheTtlMs = AGENT_DISCOVERY_CACHE_TTL_MS,
+): { value: string; label: string }[] {
+  return getCachedAgentDiscovery(cwd, "both", cache, cacheTtlMs)
+    .agents.filter((agent) => agent.name.startsWith(prefix))
+    .map((agent) => ({ value: agent.name, label: agent.name }));
+}

package/src/agents.ts

@@ -0,0 +1,178 @@
+/**
+ * Agent discovery and configuration
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export type AgentScope = "user" | "project" | "both";
+
+export type ThinkingLevel =
+  | "off"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+
+const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  tools?: string[];
+  skills?: string[];
+  thinking?: ThinkingLevel;
+  systemPrompt: string;
+  source: "user" | "project";
+  filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+  agents: AgentConfig[];
+  projectAgentsDir: string | null;
+}
+
+function parseCommaList(raw: unknown): string[] | undefined {
+  if (typeof raw !== "string") return undefined;
+  const items = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
+function parseThinkingLevel(raw: unknown): ThinkingLevel | undefined {
+  if (typeof raw !== "string") return undefined;
+  const normalized = raw.trim().toLowerCase();
+  return (THINKING_LEVELS as readonly string[]).includes(normalized)
+    ? (normalized as ThinkingLevel)
+    : undefined;
+}
+
+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;
+    }
+    let parsed: ReturnType<typeof parseFrontmatter<Record<string, unknown>>>;
+    try {
+      parsed = parseFrontmatter<Record<string, unknown>>(content);
+    } catch {
+      continue;
+    }
+    const { frontmatter, body } = parsed;
+    if (
+      typeof frontmatter !== "object" ||
+      frontmatter === null ||
+      Array.isArray(frontmatter)
+    )
+      continue;
+    const {
+      name,
+      description,
+      tools: rawTools,
+      skills: rawSkills,
+      thinking: rawThinking,
+    } = frontmatter;
+    if (typeof name !== "string" || typeof description !== "string") continue;
+    if (rawTools != null && typeof rawTools !== "string") continue;
+    if (rawSkills != null && typeof rawSkills !== "string") continue;
+    if (rawThinking != null && typeof rawThinking !== "string") continue;
+    const tools = parseCommaList(rawTools);
+    const skills = Object.hasOwn(frontmatter, "skills")
+      ? (parseCommaList(rawSkills) ?? [])
+      : undefined;
+    const thinking = parseThinkingLevel(rawThinking);
+    agents.push({
+      name,
+      description,
+      tools,
+      skills,
+      thinking,
+      systemPrompt: body,
+      source,
+      filePath,
+    });
+  }
+  return agents;
+}
+
+function isDirectory(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+  let currentDir = cwd;
+  while (true) {
+    const candidate = path.join(currentDir, ".pi", "agents");
+    if (isDirectory(candidate)) return candidate;
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return null;
+    currentDir = parentDir;
+  }
+}
+
+export function discoverAgents(
+  cwd: string,
+  scope: AgentScope,
+): AgentDiscoveryResult {
+  const userDir = path.join(getAgentDir(), "agents");
+  const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+  const userAgents =
+    scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+  const projectAgents =
+    scope === "user" || !projectAgentsDir
+      ? []
+      : loadAgentsFromDir(projectAgentsDir, "project");
+  const agentMap = new Map<string, AgentConfig>();
+  for (const agent of userAgents) agentMap.set(agent.name, agent);
+  for (const agent of projectAgents) agentMap.set(agent.name, agent);
+  return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}
+
+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/src/cancel-command.ts

@@ -0,0 +1,49 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { cancelAllRunJobs, cancelRunJob, listRunJobs } from "./run-registry.js";
+
+const CANCEL_REASON = "Cancelled by /cancel-subagent";
+
+export async function cancelSubagentCommandHandler(
+  ctx: ExtensionCommandContext,
+  args: string,
+): Promise<void> {
+  const target = args.trim();
+  if (!target) {
+    const jobs = listRunJobs();
+    if (jobs.length === 0) {
+      ctx.ui.notify("No active /run jobs.");
+      return;
+    }
+    const options = [
+      ...jobs.map((job) => `${job.agentName} (${job.requestId})`),
+      "All running subagents",
+    ];
+    const selection = await ctx.ui.select("Cancel subagent", options);
+    if (selection === undefined) return;
+    if (selection === "All running subagents") {
+      const count = cancelAllRunJobs(CANCEL_REASON);
+      ctx.ui.notify(`Cancelled ${count} /run job${count === 1 ? "" : "s"}.`);
+      return;
+    }
+    const requestId = selection.match(/\((.*)\)$/)?.[1];
+    if (requestId) {
+      cancelRunJob(requestId, CANCEL_REASON);
+      ctx.ui.notify(`Cancelled /run job ${requestId}.`);
+    }
+    return;
+  }
+  if (target === "all") {
+    const count = cancelAllRunJobs(CANCEL_REASON);
+    ctx.ui.notify(
+      count === 0
+        ? "No active /run jobs."
+        : `Cancelled ${count} /run job${count === 1 ? "" : "s"}.`,
+    );
+    return;
+  }
+  if (cancelRunJob(target, CANCEL_REASON)) {
+    ctx.ui.notify(`Cancelled /run job ${target}.`);
+    return;
+  }
+  ctx.ui.notify(`No active /run job ${target}.`);
+}

package/src/child-events.ts

@@ -0,0 +1,32 @@
+type ChildKnownEvent =
+  | { type: "message_end"; message: unknown }
+  | { type: "tool_result_end"; message: unknown }
+  | { type: "agent_end"; messages?: unknown; stopReason?: string };
+
+export type ChildEventParseResult =
+  | { kind: "known"; event: ChildKnownEvent }
+  | { kind: "unknown"; event: unknown }
+  | { kind: "invalid"; line: string };
+
+const KNOWN_TYPES = new Set(["message_end", "tool_result_end", "agent_end"]);
+
+export function parseChildEventLine(line: string): ChildEventParseResult {
+  if (typeof line !== "string" || !line.trim())
+    return { kind: "invalid", line };
+  let event: unknown;
+  try {
+    event = JSON.parse(line);
+  } catch {
+    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)
+  ) {
+    return { kind: "known", event: event as ChildKnownEvent };
+  }
+  return { kind: "unknown", event };
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  getCachedAgentCompletions,
+  resetAgentDiscoveryCache,
+} from "./agent-cache.js";
+import { cancelSubagentCommandHandler } from "./cancel-command.js";
+import { renderSubagentProgress } from "./progress.js";
+import { renderSubagentResultMessage } from "./run.js";
+import { runCommandHandler } from "./run-command.js";
+import {
+  formatStartJobStatus,
+  SubagentParams,
+  startSubagentJob,
+} from "./subagent-orchestrator.js";
+import { renderSubagentCall, renderSubagentResult } from "./ui.js";
+
+export { SubagentParams };
+
+export function resetAgentCache() {
+  resetAgentDiscoveryCache();
+}
+
+export default function registerSubagentExtension(pi: ExtensionAPI) {
+  pi.registerMessageRenderer("subagent-progress", renderSubagentProgress);
+  pi.registerMessageRenderer("subagent-result", renderSubagentResultMessage);
+  pi.registerCommand("run", {
+    description: "Run a subagent directly: /run <agent> [task]",
+    getArgumentCompletions: async (prefix: string) =>
+      getCachedAgentCompletions(prefix),
+    handler: async (args, ctx) =>
+      runCommandHandler(pi, ctx as ExtensionContext, args),
+  });
+  pi.registerCommand("cancel-subagent", {
+    description:
+      "Cancel active /run subagents: /cancel-subagent [requestId|all]",
+    handler: async (args, ctx) => cancelSubagentCommandHandler(ctx, args),
+  });
+  pi.registerTool({
+    name: "subagent",
+    label: "Subagent",
+    description: "Delegate a task to a subagent with isolated context.",
+    parameters: SubagentParams,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const result = await startSubagentJob(
+        pi,
+        ctx,
+        params,
+        signal ?? undefined,
+      );
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: formatStartJobStatus(params.agent, result),
+          },
+        ],
+        details: result.makeDetails([]),
+      };
+    },
+    renderCall(args, theme, _context) {
+      return renderSubagentCall(args, theme);
+    },
+    renderResult(result, display, theme, _context) {
+      return renderSubagentResult(result, theme, display);
+    },
+  });
+}

package/src/normalize.ts

@@ -0,0 +1,109 @@
+export const TERMINAL_SENTENCE_MAX_CHARS = 100;
+
+export function normalizeSummaryValue(value: string): string {
+  const normalized = value.trim().replace(/\s+/g, " ");
+  const wrapper = normalized.match(/^(?:`([^`]+)`|\*\*([^*]+)\*\*)$/);
+  if (wrapper) return (wrapper[1] ?? wrapper[2] ?? "").trim();
+  return normalized;
+}
+
+export function extractSemanticToolTarget(
+  toolName: string,
+  args: Record<string, unknown>,
+  forceJson = false,
+): string {
+  if (forceJson) return JSON.stringify(args);
+  if (toolName === "bash" && typeof args.command === "string")
+    return args.command;
+  if (
+    ["read", "write", "edit", "file_search"].includes(toolName) &&
+    typeof args.path === "string"
+  )
+    return args.path;
+  if (toolName === "subagent") {
+    const parts = [];
+    if (typeof args.agent === "string") parts.push(args.agent);
+    if (typeof args.task === "string")
+      parts.push(normalizeSummaryValue(args.task));
+    if (typeof args.agentScope === "string") parts.push(`[${args.agentScope}]`);
+    if (parts.length) return parts.join(" ");
+    return JSON.stringify(args);
+  }
+  return "";
+}
+
+export function isTranscriptNoiseLine(line: string): boolean {
+  return /^(?:(?:hello|hi|hey)(?:[!,.?:;]+|\s|$)|reasoning:|raw log:|apolog(?:y|ies)|sorry\b)/i.test(
+    line,
+  );
+}
+
+export function isFailureDiagnosticLine(line: string): boolean {
+  return /^(?:at\s+|error:|failed:|failure:|exception:|traceback\b|caused by:)/i.test(
+    line,
+  );
+}
+
+export function filterOutputLines(output: string): string[] {
+  return output
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(
+      (l) => l && !isTranscriptNoiseLine(l) && !isFailureDiagnosticLine(l),
+    );
+}
+
+export function stripTerminalStatusPrefixes(value: string): string {
+  return value.replace(/^(?:(?:success|failure):\s*)+/i, "");
+}
+
+export function truncateText(text: string, limit: number): string {
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit - 1)}…`;
+}
+
+export function normalizeTerminalSentence(
+  value: string,
+  limit = TERMINAL_SENTENCE_MAX_CHARS,
+): string {
+  const unwrapped = value
+    .replace(/^\s*(?:[-*>]\s*)+/, "")
+    .replace(/^\s*#{1,6}\s+/, "")
+    .replace(/^\s*`{1,3}([^`]+)`{1,3}\s*$/, "$1")
+    .replace(/^\s*\*\*([^*]+)\*\*\s*$/, "$1")
+    .replace(/^\s*__([^_]+)__\s*$/, "$1");
+  const withoutStatusPrefix = stripTerminalStatusPrefixes(unwrapped);
+  const withoutLabel = withoutStatusPrefix.replace(
+    /^\s*(?:status|summary|result|output|message|error|check|outcome|project summary):\s+/i,
+    "",
+  );
+  const normalizedOnce = normalizeSummaryValue(withoutLabel);
+  const stripped = normalizedOnce.replace(/[\s.!,;:—–-]+$/g, "");
+  const collapsed = normalizeSummaryValue(stripped);
+  return truncateText(collapsed, limit);
+}
+
+export const TOOL_PREVIEW_MAX_CHARS = 120;
+
+export function makeToolPreview(
+  toolName: string,
+  args: Record<string, unknown> | undefined,
+): string {
+  if (!args || Object.keys(args).length === 0) return toolName;
+  const target = normalizeSummaryValue(
+    extractSemanticToolTarget(toolName, args),
+  );
+  if (!target) return toolName;
+  return truncateText(
+    normalizeSummaryValue(`${toolName}: ${target}`),
+    TOOL_PREVIEW_MAX_CHARS,
+  );
+}
+
+export function isStatusOnlySuccess(value: string): boolean {
+  return /^(?:success|done)$/i.test(value.trim());
+}
+
+export function isStatusOnlyFailure(value: string): boolean {
+  return /^(?:failure|failed|error)$/i.test(value.trim());
+}