@mystilleef/pi-subagent 0.3.0 → 0.4.0

package/README.md

@@ -1,38 +1,81 @@
 # Subagent
 
-This `pi` extension provides a `subagent` tool designed for the
-[SPAE Framework](https://github.com/mystilleef/spae-framework).
+`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
+[action](https://raw.githubusercontent.com/mystilleef/pi-subagent/main/assets/parallel-agents-demo.mp4).
 
 ## Installation
 
+**Install from `npm`:**
+
 ```sh
 pi install npm:@mystilleef/pi-subagent
 ```
 
+**Try temporarily without installing:**
+
+```sh
+pi -e 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.
+- **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.
 
 ## Usage
 
-Invoke an agent with:
+**Run an agent with an optional task:**
 
 ```text
 /run agent [optional task]
 ```
 
-Stop running agents with:
+**Examples:**
+
+```text
+/run spec implement google login screen
+/run plan
+/run inspect
+/run build
+/run verify
+```
+
+**Use natural language to launch agents in parallel:**
+
+```text
+use the work agent to write a poem about linux; use the commit agent to make
+commits; use the query agent to summarize the project.
+```
+
+**Show active and completed jobs:**
+
+```text
+/jobs
+```
+
+**Cancel running `subagents`:**
 
 ```text
 /cancel-subagent
 ```
 
-## Workflow
+## _SPAE_ Workflow
 
-The [SPAE Framework](https://github.com/mystilleef/spae-framework) emphasizes a structured 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.
 
 | Phase | Agent                     | Purpose                                       |
 | ----- | ------------------------- | --------------------------------------------- |
@@ -42,4 +85,119 @@ The [SPAE Framework](https://github.com/mystilleef/spae-framework) emphasizes a
 | 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.
+## Agent definitions
+
+This package ships no agents. Define agents as Markdown files with YAML
+`frontmatter` and a Markdown system prompt body.
+
+**Discovery locations:**
+
+- User-global agents: `~/.pi/agents/*.md`
+- Project-local agents: nearest `.pi/agents/*.md`
+
+**Required `frontmatter`:**
+
+```yaml
+name: review
+description: Review code for correctness and maintainability.
+```
+
+**Optional `frontmatter`:**
+
+```yaml
+tools: read, bash, edit
+skills: code-review
+thinking: medium
+```
+
+**Accepted `thinking` values:**
+
+- `off`
+- `minimal`
+- `low`
+- `medium`
+- `high`
+- `xhigh`
+
+## Tool
+
+The extension also registers a `subagent` tool for model-driven
+delegation.
+
+**Inputs:**
+
+- `agent`: agent name.
+- `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.
+
+## Security
+
+`Subagents` launch child `pi --json` processes. Agents, tools, and
+extensions run with user permissions, so treat agent definitions like
+executable automation.
+
+**Trust guidance:**
+
+- Review project-local agents before running them.
+- Avoid delegating secrets unless the agent and tools need them.
+- 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 `1`.
+- `PI_SUBAGENT_MAX_OUTPUT_BYTES`: max returned output bytes. Default:
+  `50000`.
+- `PI_SUBAGENT_MAX_OUTPUT_LINES`: max returned output lines. Default:
+  `500`.
+
+## Troubleshooting
+
+**Missing agent:**
+
+- Confirm the file lives under `~/.pi/agents/` or the nearest
+  `.pi/agents/`.
+- Confirm `frontmatter` includes `name` and `description`.
+- Confirm `/run` uses the `name` value, not the filename.
+
+**Project-local agent prompt:**
+
+- Pi may request confirmation before loading project-local agents when
+  UI context exists.
+
+**Nested subagent blocked:**
+
+- Nested delegation hits the `PI_SUBAGENT_DEPTH` safety limit.
+- Run the child task directly from the parent session instead.
+
+**Truncated output:**
+
+- Raise `PI_SUBAGENT_MAX_OUTPUT_BYTES` or
+  `PI_SUBAGENT_MAX_OUTPUT_LINES`.
+- Ask the child agent for a shorter summary.
+
+## Development
+
+**Install dependencies:**
+
+```sh
+bun install
+```
+
+**Run full verification:**
+
+```sh
+bun verify
+```
+
+**Check npm package contents:**
+
+```sh
+bun pack:smoke
+```

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.3.0",
+  "version": "0.4.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"
+    "url": "git+https://github.com/mystilleef/pi-subagent.git"
   },
+  "bugs": {
+    "url": "https://github.com/mystilleef/pi-subagent/issues"
+  },
+  "homepage": "https://github.com/mystilleef/pi-subagent#readme",
   "keywords": [
+    "pi-package",
+    "pi-extension",
     "pi",
     "agent",
     "subagent",
@@ -23,7 +29,8 @@
   },
   "type": "module",
   "engines": {
-    "bun": ">=1.3.13"
+    "bun": ">=1.3.13",
+    "node": ">=18"
   },
   "files": [
     "src",
@@ -33,26 +40,37 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "video": "https://raw.githubusercontent.com/mystilleef/pi-subagent/main/assets/parallel-agents-demo.mp4"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
-    "verify": "bun check && bun test",
-    "coverage": "bun check && bun test --coverage",
-    "check": "biome check --fix --unsafe . && tsc --noEmit",
+    "verify": "bun fix && bun check && bun test",
+    "coverage": "bun fix && bun check && bun test --coverage",
+    "check": "biome check . && tsc --noEmit",
+    "fix": "biome check --write --unsafe .",
+    "pack:smoke": "bun scripts/pack-smoke.ts",
     "migrate": "biome migrate --write",
-    "release": "sh -c 'npm version \"$1\" && git push --follow-tags && bun publish --access public' --"
+    "release": "sh -c 'npm version \"$1\" -m \"chore(release): %s\" && git push --follow-tags' --"
   },
-  "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"
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
+    "@earendil-works/pi-agent-core": "^0.74.1",
+    "@earendil-works/pi-ai": "^0.74.1",
+    "@earendil-works/pi-coding-agent": "^0.74.1",
+    "@earendil-works/pi-tui": "^0.74.1",
     "@types/bun": "^1.3.14",
     "@types/node": "^25.8.0",
+    "typebox": "^1.1.38",
     "typescript": "^6.0.3"
   }
 }

package/src/cancel-command.ts

@@ -15,7 +15,9 @@ export async function cancelSubagentCommandHandler(
       return;
     }
     const options = [
-      ...jobs.map((job) => `${job.agentName} (${job.requestId})`),
+      ...jobs.map(
+        (job) => `${job.agentName} ${job.instanceName} (${job.requestId})`,
+      ),
       "All running subagents",
     ];
     const selection = await ctx.ui.select("Cancel subagent", options);

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   resetAgentDiscoveryCache,
 } from "./agent-cache.js";
 import { cancelSubagentCommandHandler } from "./cancel-command.js";
+import { jobsCommandHandler } from "./jobs-command.js";
 import { renderSubagentProgress } from "./progress.js";
 import { renderSubagentResultMessage } from "./run.js";
 import { runCommandHandler } from "./run-command.js";
@@ -38,6 +39,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI) {
       "Cancel active /run subagents: /cancel-subagent [requestId|all]",
     handler: async (args, ctx) => cancelSubagentCommandHandler(ctx, args),
   });
+  pi.registerCommand("jobs", {
+    description: "List all /run jobs and their statuses: /jobs",
+    handler: async (args, ctx) => jobsCommandHandler(ctx, args),
+  });
   pi.registerTool({
     name: "subagent",
     label: "Subagent",

package/src/instance-name.ts

@@ -0,0 +1,164 @@
+const DEFAULT_ADJECTIVES = [
+  "able",
+  "agile",
+  "alert",
+  "amber",
+  "ample",
+  "apt",
+  "arctic",
+  "avid",
+  "bold",
+  "brave",
+  "bright",
+  "brisk",
+  "calm",
+  "clever",
+  "cosmic",
+  "crisp",
+  "daring",
+  "dawn",
+  "eager",
+  "early",
+  "fair",
+  "fast",
+  "fierce",
+  "fine",
+  "fresh",
+  "gentle",
+  "golden",
+  "grand",
+  "happy",
+  "honest",
+  "jolly",
+  "keen",
+  "kind",
+  "lively",
+  "lucky",
+  "merry",
+  "mighty",
+  "nimble",
+  "noble",
+  "novel",
+  "patient",
+  "proud",
+  "quick",
+  "quiet",
+  "rapid",
+  "ready",
+  "sharp",
+  "smart",
+  "solid",
+  "steady",
+  "swift",
+  "tidy",
+  "vivid",
+  "warm",
+  "wise",
+] as const;
+
+const DEFAULT_NOUNS = [
+  "badger",
+  "beacon",
+  "bison",
+  "brook",
+  "cedar",
+  "comet",
+  "coral",
+  "coyote",
+  "crane",
+  "dolphin",
+  "eagle",
+  "ember",
+  "falcon",
+  "finch",
+  "forest",
+  "fox",
+  "gecko",
+  "glade",
+  "harbor",
+  "hawk",
+  "heron",
+  "island",
+  "jaguar",
+  "koala",
+  "lagoon",
+  "lemur",
+  "lynx",
+  "maple",
+  "meadow",
+  "otter",
+  "panda",
+  "panther",
+  "pelican",
+  "phoenix",
+  "puma",
+  "raven",
+  "reef",
+  "river",
+  "salmon",
+  "sparrow",
+  "summit",
+  "tiger",
+  "valley",
+  "violet",
+  "walrus",
+  "willow",
+  "wolf",
+  "wren",
+  "yak",
+  "zephyr",
+] as const;
+
+const usedInstanceNames = new Set<string>();
+
+let adjectives: readonly string[] = DEFAULT_ADJECTIVES;
+let nouns: readonly string[] = DEFAULT_NOUNS;
+let randomSource: () => number = Math.random;
+
+function normalizeRandomIndex(limit: number): number {
+  const value = randomSource();
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(limit - 1, Math.max(0, Math.floor(value * limit)));
+}
+
+function nameAt(index: number): string {
+  const adjective = adjectives[Math.floor(index / nouns.length)];
+  const noun = nouns[index % nouns.length];
+  return `${adjective}-${noun}`;
+}
+
+export function generateSubagentInstanceName(): string {
+  const capacity = adjectives.length * nouns.length;
+  if (usedInstanceNames.size >= capacity) {
+    throw new Error(
+      "No unused subagent instance names remain for this session.",
+    );
+  }
+  const start = normalizeRandomIndex(capacity);
+  for (let offset = 0; offset < capacity; offset += 1) {
+    const candidate = nameAt((start + offset) % capacity);
+    if (!usedInstanceNames.has(candidate)) {
+      usedInstanceNames.add(candidate);
+      return candidate;
+    }
+  }
+  throw new Error("No unused subagent instance names remain for this session.");
+}
+
+export function resetSubagentInstanceNamesForTest() {
+  usedInstanceNames.clear();
+  adjectives = DEFAULT_ADJECTIVES;
+  nouns = DEFAULT_NOUNS;
+  randomSource = Math.random;
+}
+
+export function configureSubagentInstanceNamesForTest(options: {
+  adjectives?: readonly string[];
+  nouns?: readonly string[];
+  randomSource?: () => number;
+}) {
+  usedInstanceNames.clear();
+  adjectives = options.adjectives ?? DEFAULT_ADJECTIVES;
+  nouns = options.nouns ?? DEFAULT_NOUNS;
+  randomSource = options.randomSource ?? Math.random;
+}

package/src/jobs-command.ts

@@ -0,0 +1,41 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import {
+  getAllProgressStates,
+  type SubagentProgressState,
+} from "./progress-state.js";
+import { listRunJobs } from "./run-registry.js";
+import { renderRunsBoard } from "./ui.js";
+
+export async function jobsCommandHandler(
+  ctx: ExtensionCommandContext,
+  _args: string,
+): Promise<void> {
+  const activeRequestIds = new Set(listRunJobs().map((j) => j.requestId));
+  const active: SubagentProgressState[] = [];
+  const completed: SubagentProgressState[] = [];
+  for (const s of getAllProgressStates()) {
+    if (activeRequestIds.has(s.requestId)) active.push(s);
+    else if (s.status !== "running") completed.push(s);
+  }
+  const all = [...active, ...completed];
+  if (all.length === 0) {
+    ctx.ui.notify("No /run jobs in this session.");
+    return;
+  }
+  const output = await ctx.ui.custom<string>(
+    (_tui, theme, _keybindings, done) => ({
+      invalidate() {},
+      render(width) {
+        const tuiLines = renderRunsBoard(all, theme, width).render(width);
+        const notifyWidth = Math.max(1, width - 2);
+        const notifyLines = renderRunsBoard(all, theme, notifyWidth).render(
+          notifyWidth,
+        );
+        done(notifyLines.join("\n"));
+        return tuiLines;
+      },
+    }),
+  );
+  ctx.ui.notify(output);
+}

package/src/progress-state.ts

@@ -1,3 +1,4 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import {
   isStatusOnlyFailure,
   isStatusOnlySuccess,
@@ -9,11 +10,35 @@ import {
 } from "./normalize.js";
 import type { SubagentDetails } from "./types.js";
 
+export type ThemeBg = "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
+
 export type ProgressStatus = "running" | "success" | "error" | "cancelled";
 
+export const STATUS_COLOR: Record<ProgressStatus, ThemeColor> = {
+  success: "success",
+  error: "error",
+  cancelled: "error",
+  running: "accent",
+};
+
+export const STATUS_ICON: Record<ProgressStatus, string> = {
+  success: "✓",
+  error: "✗",
+  cancelled: "⊘",
+  running: "⟳",
+};
+
+export const STATUS_BG: Record<ProgressStatus, ThemeBg> = {
+  success: "toolSuccessBg",
+  error: "toolErrorBg",
+  cancelled: "toolErrorBg",
+  running: "toolPendingBg",
+};
+
 export interface SubagentProgressState {
   requestId: string;
   agent: string;
+  instanceName?: string;
   taskPreview: string;
   status: ProgressStatus;
   startTime: number;
@@ -34,10 +59,12 @@ export function createProgressState(
   requestId: string,
   agent: string,
   task: string,
+  instanceName = requestId,
 ): void {
   store.set(requestId, {
     requestId,
     agent,
+    instanceName,
     taskPreview: makeTaskPreview(task),
     status: "running",
     startTime: Date.now(),
@@ -50,6 +77,9 @@ export function getProgressState(
 ): SubagentProgressState | undefined {
   return store.get(requestId);
 }
+export function getAllProgressStates(): SubagentProgressState[] {
+  return [...store.values()].sort((a, b) => b.startTime - a.startTime);
+}
 
 export function patchProgressState(
   requestId: string,
@@ -231,3 +261,53 @@ export function isToolCallPart(part: unknown): part is {
     typeof maybe.name === "string"
   );
 }
+
+/**
+ * Format a millisecond duration for compact display.
+ * Renders sub-minute durations as decimal seconds (`45.2s`),
+ * longer durations as minutes and whole seconds (`2m 15s`).
+ */
+export function formatElapsed(ms: number): string {
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const mins = Math.floor(ms / 60000);
+  const secs = Math.floor((ms % 60000) / 1000);
+  return `${mins}m ${secs}s`;
+}
+
+/**
+ * Format a raw token count for compact inline display.
+ * Values below 1000 rendered as-is. Larger counts use `k`
+ * or `M` suffixes with one decimal place, stripping trailing `.0`.
+ */
+export function formatTokenCount(count: number): string {
+  if (count < 1000) return String(count);
+  const unit = count >= 1_000_000 ? "M" : "k";
+  const divisor = count >= 1_000_000 ? 1_000_000 : 1000;
+  return `${trimTrailingZero((count / divisor).toFixed(1))}${unit}`;
+}
+
+function trimTrailingZero(value: string): string {
+  return value.endsWith(".0") ? value.slice(0, -2) : value;
+}
+
+export function formatContextPercent(state: SubagentProgressState): string {
+  const d = state.contextWindowTokens;
+  if (!d || d <= 0 || !Number.isFinite(d)) return "--%";
+  const n = state.contextTokens;
+  if (!n || n <= 0 || !Number.isFinite(n)) return "0%";
+  return `${Math.round((n / d) * 100)}%`;
+}
+
+/**
+ * Format the one-line statistics header for a subagent progress display.
+ * Includes tool count, context window usage, and elapsed time.
+ * When the subagent is still running (`durationMs` unset), elapsed is
+ * computed live from `startTime`.
+ *
+ * @returns Single line ending in `\n`, e.g. `"3 tools · 45% ctx · 12.3s\n"`
+ */
+export function formatHeaderStats(state: SubagentProgressState): string {
+  const elapsedMs = state.durationMs ?? Date.now() - state.startTime;
+  const toolLabel = state.toolCount === 1 ? "tool" : "tools";
+  return `${state.toolCount} ${toolLabel} · ${formatContextPercent(state)} ctx · ${formatElapsed(elapsedMs)}\n`;
+}