@rol1n/subagent 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# subagent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Delegate tasks to independent, full-powered Pi workers. The `subagent` tool returns after launch; completion or questions are delivered back to the parent session asynchronously.
+
+## Install
+
+```sh
+pi install npm:@rol1n/subagent
+```
+
+Also included in `@rol1n/pi-kit`. The parent and workers require the `pi` executable on PATH and their normal Pi authentication.
+
+## Use
+
+```json
+{"action":"spawn","name":"reviewer","cwd":"/existing/project","task":"Review the changed files and report findings."}
+{"action":"send","target":"reviewer","task":"Also inspect the error handling."}
+{"action":"stop","target":"reviewer"}
+```
+
+`model` optionally selects a worker model. `/subagent` shows active workers. Each worker inherits its own normal Pi capabilities; this is a delegation runtime, not a restricted execution environment.
+
+## Backends
+
+| Variable | Behavior |
+|---|---|
+| `PI_SUBAGENT_BACKEND=process` | Run silent background processes |
+| `PI_SUBAGENT_MUX=tmux` | Prefer tmux when running inside an available tmux session |
+| `PI_SUBAGENT_MUX=zellij` | Prefer Zellij when running inside an available Zellij session |
+
+Without a usable multiplexer, the worker backend falls back to a background process. Native Windows supports PowerShell launch commands and Zellij panes; tmux is for POSIX environments. Session transcripts and task artifacts are stored under `~/.pi/agent/`.
+
+## Other delegation packages
+
+Use [multi-harness](https://github.com/RolinShmily/pi-kit/tree/main/extensions/multi-harness) for Codex, Claude, or OpenCode peers. That package shares multiplexer helpers but provides a separate tool and does not automatically enable this extension's entrypoint. The bundled subagent skill file is reference material and is not registered by the package manifest.

package/extensions/subagent/README.md

@@ -0,0 +1,35 @@
+# subagent
+
+Delegate tasks to independent, full-powered Pi workers. The `subagent` tool returns after launch; completion or questions are delivered back to the parent session asynchronously.
+
+## Install
+
+```sh
+pi install npm:@rol1n/subagent
+```
+
+Also included in `@rol1n/pi-kit`. The parent and workers require the `pi` executable on PATH and their normal Pi authentication.
+
+## Use
+
+```json
+{"action":"spawn","name":"reviewer","cwd":"/existing/project","task":"Review the changed files and report findings."}
+{"action":"send","target":"reviewer","task":"Also inspect the error handling."}
+{"action":"stop","target":"reviewer"}
+```
+
+`model` optionally selects a worker model. `/subagent` shows active workers. Each worker inherits its own normal Pi capabilities; this is a delegation runtime, not a restricted execution environment.
+
+## Backends
+
+| Variable | Behavior |
+|---|---|
+| `PI_SUBAGENT_BACKEND=process` | Run silent background processes |
+| `PI_SUBAGENT_MUX=tmux` | Prefer tmux when running inside an available tmux session |
+| `PI_SUBAGENT_MUX=zellij` | Prefer Zellij when running inside an available Zellij session |
+
+Without a usable multiplexer, the worker backend falls back to a background process. Native Windows supports PowerShell launch commands and Zellij panes; tmux is for POSIX environments. Session transcripts and task artifacts are stored under `~/.pi/agent/`.
+
+## Other delegation packages
+
+Use [multi-harness](https://github.com/RolinShmily/pi-kit/tree/main/extensions/multi-harness) for Codex, Claude, or OpenCode peers. That package shares multiplexer helpers but provides a separate tool and does not automatically enable this extension's entrypoint. The bundled subagent skill file is reference material and is not registered by the package manifest.

package/extensions/subagent/bridge.ts

@@ -0,0 +1,171 @@
+/**
+ * subagent/bridge.ts — Subagent Worker Bridge
+ *
+ * Loaded exclusively inside the spawned worker Pi process via `-e <bridgePath>`.
+ * - Grants the worker an `ask_question` tool to consult the parent orchestrator.
+ * - Handles auto-exit on task completion (calling ctx.shutdown() so the pane closes cleanly).
+ * - Suppresses auto-exit while waiting for the parent's answer to `ask_question`.
+ * - Prevents recursive subagent spawning.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+
+export default function subagentBridge(pi: ExtensionAPI) {
+  if (process.env.PI_SUBAGENT_ACTIVE !== "1") {
+    return;
+  }
+
+  const workerName = process.env.PI_SUBAGENT_NAME || "worker";
+  const sessionFile = process.env.PI_SUBAGENT_SESSION;
+
+  let awaitingAnswer = false;
+
+  // Render a minimal indicator in the child worker's terminal
+  pi.on("session_start", (_event, ctx) => {
+    ctx.ui.setWidget(
+      "subagent-worker-banner",
+      (_tui, theme) => {
+        const box = new Box(1, 0, (text: string) => {
+          try {
+            return theme.bg("toolSuccessBg", text);
+          } catch {
+            return text;
+          }
+        });
+        const badge = theme.bold(theme.fg("accent", `[Worker: ${workerName}]`));
+        const hint = theme.fg("dim", " · Full Pi worker · ask_question available");
+        box.addChild(new Text(`${badge}${hint}`, 0, 0));
+        return box;
+      },
+      { placement: "aboveEditor" },
+    );
+  });
+
+  // When input arrives (e.g. parent reply or manual steer), answer is received
+  pi.on("input", () => {
+    awaitingAnswer = false;
+  });
+
+  pi.on("agent_start", () => {
+    awaitingAnswer = false;
+  });
+
+  pi.on("agent_end", (event, ctx) => {
+    if (awaitingAnswer) {
+      // Park in waiting state, do not exit
+      return;
+    }
+
+    const messages = (event as any).messages as any[] | undefined;
+    let errorMessage: string | undefined;
+
+    if (messages && messages.length > 0) {
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg?.role === "assistant") {
+          if (msg.stopReason === "error") {
+            errorMessage = typeof msg.errorMessage === "string" ? msg.errorMessage : "Agent ended with error";
+          }
+          break;
+        }
+      }
+    }
+
+    if (sessionFile) {
+      try {
+        writeFileSync(
+          `${sessionFile}.exit`,
+          JSON.stringify({
+            type: errorMessage ? "error" : "done",
+            ...(errorMessage ? { errorMessage } : {}),
+          }),
+        );
+      } catch {
+        // best effort
+      }
+    }
+
+    ctx.shutdown();
+  });
+
+  // Register `ask_question` tool
+  pi.registerTool({
+    name: "ask_question",
+    label: "Ask Orchestrator",
+    description:
+      "Ask the orchestrator (the parent agent that spawned you) a clarifying question and pause until they reply. " +
+      "Use when requirements are ambiguous, a critical decision needs confirmation, or you are blocked. " +
+      "Your session stays open while you wait — the answer will arrive as your next turn message.",
+    parameters: Type.Object({
+      question: Type.String({
+        description: "The question for the parent orchestrator. Include enough context for them to decide.",
+      }),
+    }),
+    async execute(_toolCallId, params, signal) {
+      if (!sessionFile) {
+        throw new Error("ask_question is only available within a managed subagent session.");
+      }
+
+      awaitingAnswer = true;
+      const askFile = `${sessionFile}.ask`;
+      const replyFile = `${sessionFile}.reply`;
+
+      const askData = {
+        name: workerName,
+        question: params.question,
+        timestamp: new Date().toISOString(),
+      };
+
+      writeFileSync(askFile, JSON.stringify(askData));
+
+      try {
+        while (!existsSync(replyFile)) {
+          if (signal?.aborted) {
+            throw new Error("Cancelled while waiting for parent reply");
+          }
+          await new Promise<void>((resolve, reject) => {
+            const timer = setTimeout(resolve, 200);
+            if (signal) {
+              const onAbort = () => {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", onAbort);
+                reject(new Error("Cancelled while waiting for parent reply"));
+              };
+              signal.addEventListener("abort", onAbort, { once: true });
+            }
+          });
+        }
+
+        const reply = readFileSync(replyFile, "utf-8");
+        try {
+          unlinkSync(replyFile);
+        } catch {}
+        awaitingAnswer = false;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Orchestrator answer:\n\n${reply}`,
+            },
+          ],
+          details: { question: params.question, reply },
+        };
+      } finally {
+        awaitingAnswer = false;
+        try {
+          if (existsSync(askFile)) unlinkSync(askFile);
+        } catch {}
+      }
+    },
+    renderCall(args, theme) {
+      const text =
+        theme.fg("toolTitle", theme.bold("ask_question ")) +
+        theme.fg("muted", String((args as any).question ?? ""));
+      return new Text(text, 0, 0);
+    },
+  });
+}