pi-herdr-spawn 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 duskoide
+
+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,106 @@
+# pi-herdr-spawn
+
+Spawn pi agents in isolated Herdr panes to execute tasks in parallel.
+
+## Installation
+
+```bash
+pi install npm:pi-herdr-spawn
+```
+
+Or via git:
+
+```bash
+pi install git:github.com/duskoide/pi-herdr-spawn
+```
+
+## Usage
+
+### Slash Commands
+
+After installing, restart pi or run `/reload`:
+
+```bash
+# Basic usage - spawn with auto-generated name
+/spawn Run tests and report failures
+
+# With custom name
+/spawn Review code pi-reviewer
+
+# With custom name and model
+/spawn Review code pi-reviewer claude-sonnet-5
+
+# Quick spawn (shorthand)
+/spawnp Run the linter and fix errors
+
+# List running agents
+/spawnlist
+
+# Kill a specific agent
+/spawnkill pi-test-runner
+```
+
+### Tool Usage
+
+You can also use the `spawn_pi` tool directly:
+
+```
+spawn_pi({
+  prompt: "Run tests and report any failures",
+  name: "pi-test-runner",
+  model: "gpt-4o",
+  timeout: 180000,
+  direction: "right"
+})
+```
+
+### Command Line
+
+```bash
+~/.pi/agent/bin/herdr-spawn.sh <agent-name> "<prompt>" [--model <model>] [--timeout <ms>]
+
+# Example:
+~/.pi/agent/bin/herdr-spawn.sh pi-test "Run npm test and report results" --timeout 180000
+```
+
+## How It Works
+
+1. **Creates a new pane** - Splits the current pane to create an isolated terminal
+2. **Starts pi agent** - Launches a fresh pi instance in the new pane
+3. **Sends your prompt** - Submits the task and waits for completion
+4. **Reads the response** - Gets the agent's output
+5. **Cleans up** - Closes the pane and stops the agent automatically
+
+## Requirements
+
+- Pi must be running inside a Herdr-managed pane (`HERDR_ENV=1`)
+- Herdr must be installed and running
+
+## Use Cases
+
+### Parallel Testing
+
+```bash
+/spawn npm test pi-tests
+/spawn npm run lint pi-linter
+/spawn npm run typecheck pi-types
+```
+
+### Code Review
+
+```
+spawn_pi({ prompt: "Review the recent git changes and suggest improvements" })
+```
+
+### Long-Running Tasks
+
+```
+spawn_pi({ 
+  prompt: "Run the build process and report any errors",
+  timeout: 300000 
+})
+```
+
+## License
+
+MIT

package/bin/herdr-spawn.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# herdr-spawn.sh - Spawn a pi agent in a new Herdr pane
+#
+# Usage: herdr-spawn.sh <agent-name> <prompt> [--model <model>] [--timeout <ms>]
+#
+# Example:
+#   herdr-spawn.sh pi-test "Run tests and report results"
+#   herdr-spawn.sh pi-reviewer "Review the code changes" --model gpt-4o
+#   herdr-spawn.sh pi-builder "Build project" --model claude-sonnet-5 --timeout 180000
+
+set -euo pipefail
+
+# Check Herdr environment
+if [[ "${HERDR_ENV:-}" != "1" ]]; then
+  echo "Error: Not running in Herdr environment" >&2
+  exit 1
+fi
+
+# Parse required arguments
+AGENT_NAME="${1:?Usage: herdr-spawn.sh <agent-name> <prompt> [--model <model>] [--timeout <ms>]}"
+PROMPT="${2:?Usage: herdr-spawn.sh <agent-name> <prompt> [--model <model>] [--timeout <ms>]}"
+
+# Parse optional arguments
+MODEL=""
+TIMEOUT="120000"
+shift 2 || true
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --model)
+      MODEL="$2"
+      shift 2
+      ;;
+    --timeout)
+      TIMEOUT="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate agent name (lowercase, hyphens, max 31 chars)
+if [[ ! "$AGENT_NAME" =~ ^[a-z][a-z0-9_-]{0,30}$ ]]; then
+  echo "Error: Agent name must be lowercase letters, numbers, hyphens; max 31 chars" >&2
+  exit 1
+fi
+
+# Get current pane context
+CURRENT_PANE=$(herdr pane current --current)
+PANE_ID=$(echo "$CURRENT_PANE" | jq -r '.result.pane.pane_id')
+
+if [[ -z "$PANE_ID" ]]; then
+  echo "Error: Could not get current pane ID" >&2
+  exit 1
+fi
+
+# Create new pane
+NEW_PANE=$(herdr pane split --current --direction right --cwd "$PWD" --no-focus)
+NEW_PANE_ID=$(echo "$NEW_PANE" | jq -r '.result.pane.pane_id')
+
+if [[ -z "$NEW_PANE_ID" ]]; then
+  echo "Error: Could not create new pane" >&2
+  exit 1
+fi
+
+# Start pi agent (with optional model)
+START_CMD="herdr agent start \"$AGENT_NAME\" --kind pi --pane \"$NEW_PANE_ID\""
+if [[ -n "$MODEL" ]]; then
+  START_CMD="$START_CMD -- --model \"$MODEL\""
+fi
+
+START_RESULT=$(eval "$START_CMD")
+AGENT_STATUS=$(echo "$START_RESULT" | jq -r '.result.agent.agent_status')
+
+if [[ "$AGENT_STATUS" == "unknown" ]]; then
+  echo "Error: Failed to start agent" >&2
+  exit 1
+fi
+
+# Send prompt
+PROMPT_RESULT=$(herdr agent prompt "$AGENT_NAME" "$PROMPT" --wait --timeout "$TIMEOUT")
+PROMPT_STATUS=$(echo "$PROMPT_RESULT" | jq -r '.type')
+
+if [[ "$PROMPT_STATUS" != "agent_prompted" ]]; then
+  echo "Error: Failed to send prompt" >&2
+  exit 1
+fi
+
+# Read response
+RESPONSE=$(herdr agent read "$AGENT_NAME" --source recent-unwrapped --lines 100)
+
+# Output results
+cat <<EOF
+{
+  "pane_id": "$NEW_PANE_ID",
+  "agent_name": "$AGENT_NAME",
+  "model": "${MODEL:-parent}",
+  "status": "completed",
+  "response": $(echo "$RESPONSE" | jq -Rs .)
+}
+EOF
+
+# Cleanup: Close the pane (this also stops the agent)
+herdr pane close "$NEW_PANE_ID" > /dev/null 2>&1 || true

package/extensions/herdr-spawn.ts

@@ -0,0 +1,310 @@
+import { z } from "zod";
+
+const SpawnPiInput = z.object({
+  prompt: z.string().describe("The prompt to send to the spawned pi agent"),
+  name: z
+    .string()
+    .optional()
+    .describe(
+      "Unique name for the agent (lowercase, hyphens, max 31 chars). Auto-generated if not provided."
+    ),
+  model: z
+    .string()
+    .optional()
+    .describe(
+      "Model to use for the spawned agent (e.g., 'gpt-4o', 'claude-sonnet-5', 'provider/model-id'). Uses parent model if not specified."
+    ),
+  timeout: z
+    .number()
+    .optional()
+    .default(120000)
+    .describe("Timeout in milliseconds for the prompt (default: 120000)"),
+  direction: z
+    .enum(["right", "down"])
+    .optional()
+    .default("right")
+    .describe("Pane split direction (default: right)"),
+});
+
+export default function herdrSpawn() {
+  return {
+    name: "herdr-spawn",
+    description:
+      "Spawn a pi agent in a new Herdr pane to execute tasks in parallel. Use when you need to run work in a separate pane without blocking the current session.",
+    commands: [
+      {
+        name: "spawn",
+        description:
+          "Spawn a pi agent in a new pane to execute a task. Usage: /spawn <prompt> [name] [model] [timeout]",
+        execute: async (args: string) => {
+          // Parse command args: /spawn <prompt> [name] [model] [timeout]
+          const parts = args.trim().split(/\s+/);
+          
+          if (parts.length === 0 || !parts[0]) {
+            return {
+              message: "Usage: /spawn <prompt> [agent-name] [model] [timeout-ms]\n\nExamples:\n/spawn Run tests and report failures\n/spawn Review code pi-review gpt-4o\n/spawn Build project pi-builder claude-sonnet-5 300000",
+            };
+          }
+          
+          const prompt = parts[0];
+          const name = parts[1] || `pi-${Date.now().toString(36)}`;
+          const model = parts[2] || undefined;
+          const timeout = parts[3] ? parseInt(parts[3]) : 120000;
+          
+          // Check Herdr environment
+          if (process.env.HERDR_ENV !== "1") {
+            return {
+              error: "Not running in Herdr environment. Cannot spawn pane.",
+            };
+          }
+          
+          try {
+            const { execSync } = require("child_process");
+            
+            // Create new pane
+            const splitResult = execSync(
+              `herdr pane split --current --direction right --cwd "${process.env.PWD}" --no-focus`,
+              { encoding: "utf-8" }
+            );
+            const split = JSON.parse(splitResult);
+            const newPaneId = split.result?.pane?.pane_id;
+            
+            if (!newPaneId) {
+              return { error: "Could not create new pane" };
+            }
+            
+            // Build start command with optional model
+            let startCmd = `herdr agent start "${name}" --kind pi --pane "${newPaneId}"`;
+            if (model) {
+              startCmd += ` -- --model "${model}"`;
+            }
+            
+            // Start agent
+            execSync(startCmd, { encoding: "utf-8" });
+            
+            // Send prompt
+            const escapedPrompt = prompt.replace(/"/g, '\\"');
+            execSync(
+              `herdr agent prompt "${name}" "${escapedPrompt}" --wait --timeout ${timeout}`,
+              { encoding: "utf-8" }
+            );
+            
+            // Read response
+            const response = execSync(
+              `herdr agent read "${name}" --source recent-unwrapped --lines 100`,
+              { encoding: "utf-8" }
+            );
+            
+            // Cleanup
+            execSync(`herdr pane close "${newPaneId}" 2>/dev/null || true`, {
+              encoding: "utf-8",
+            });
+            
+            return {
+              message: `✅ Agent \"${name}\" completed in pane ${newPaneId}\n\n${response}`,
+            };
+          } catch (error: any) {
+            return { error: `Failed: ${error.message}` };
+          }
+        },
+      },
+      {
+        name: "spawnp",
+        description:
+          "Quick spawn: /spawnp <prompt> [model] - spawns agent with auto-generated name",
+        execute: async (args: string) => {
+          if (!args.trim()) {
+            return { error: "Usage: /spawnp <prompt> [model]" };
+          }
+          // Delegate to /spawn with auto-generated name
+          const autoName = `pi-${Date.now().toString(36)}`;
+          return this.commands!.find((c) => c.name === "spawn")!.execute(
+            `${args.trim()} ${autoName} ${args.split(' ').slice(1).join(' ') || ''}`.trim()
+          );
+        },
+      },
+      {
+        name: "spawnlist",
+        description: "List all currently running spawned agents",
+        execute: async () => {
+          if (process.env.HERDR_ENV !== "1") {
+            return { error: "Not running in Herdr environment" };
+          }
+          
+          try {
+            const { execSync } = require("child_process");
+            const result = execSync("herdr agent list", { encoding: "utf-8" });
+            const agents = JSON.parse(result);
+            
+            if (!agents.result?.agents?.length) {
+              return { message: "No agents currently running." };
+            }
+            
+            const list = agents.result.agents
+              .map((a: any) => `- ${a.name} (${a.agent_status}) in ${a.pane_id}`)
+              .join("\n");
+            
+            return { message: `Running agents:\n${list}` };
+          } catch (error: any) {
+            return { error: `Failed: ${error.message}` };
+          }
+        },
+      },
+      {
+        name: "spawnkill",
+        description: "Kill a spawned agent by name: /spawnkill <agent-name>",
+        execute: async (args: string) => {
+          const agentName = args.trim();
+          if (!agentName) {
+            return { error: "Usage: /spawnkill <agent-name>" };
+          }
+          
+          if (process.env.HERDR_ENV !== "1") {
+            return { error: "Not running in Herdr environment" };
+          }
+          
+          try {
+            const { execSync } = require("child_process");
+            
+            // Get agent info to find pane ID
+            const agentInfo = execSync(`herdr agent get "${agentName}"`, {
+              encoding: "utf-8",
+            });
+            const agent = JSON.parse(agentInfo);
+            const paneId = agent.result?.agent?.pane_id;
+            
+            if (!paneId) {
+              return { error: `Agent "${agentName}" not found` };
+            }
+            
+            // Close the pane (this stops the agent)
+            execSync(`herdr pane close "${paneId}"`, { encoding: "utf-8" });
+            
+            return { message: `✅ Killed agent "${agentName}" in pane ${paneId}` };
+          } catch (error: any) {
+            return { error: `Failed: ${error.message}` };
+          }
+        },
+      },
+    ],
+    tools: [
+      {
+        name: "spawn_pi",
+        description:
+          "Spawn a pi agent in a new Herdr pane, send a prompt, wait for response, and return the result. The pane is automatically closed after completion.",
+        inputSchema: SpawnPiInput,
+        execute: async (input: z.infer<typeof SpawnPiInput>) => {
+          // Check if we're in Herdr
+          const herdrEnv = process.env.HERDR_ENV;
+          if (herdrEnv !== "1") {
+            return {
+              error: "Not running in Herdr environment. Cannot spawn pane.",
+            };
+          }
+
+          const { prompt, timeout = 120000, direction = "right" } = input;
+          const agentName =
+            input.name ||
+            `pi-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+
+          // Validate agent name
+          if (!/^[a-z][a-z0-9_-]{0,30}$/.test(agentName)) {
+            return {
+              error:
+                "Agent name must be lowercase letters, numbers, hyphens; max 31 chars",
+            };
+          }
+
+          try {
+            // We'll use bash commands to interact with herdr CLI
+            // since this extension runs in the pi process
+            
+            // Get current pane context
+            const currentResult = await execCommand(
+              "herdr pane current --current"
+            );
+            const current = JSON.parse(currentResult);
+            const currentPaneId = current.result?.pane?.pane_id;
+            
+            if (!currentPaneId) {
+              return { error: "Could not get current pane ID" };
+            }
+            
+            // Create new pane
+            const splitResult = await execCommand(
+              `herdr pane split --current --direction ${direction} --cwd "${process.env.PWD}" --no-focus`
+            );
+            const split = JSON.parse(splitResult);
+            const newPaneId = split.result?.pane?.pane_id;
+            
+            if (!newPaneId) {
+              return { error: "Could not create new pane" };
+            }
+            
+            // Build agent start command with optional model argument
+            let startCmd = `herdr agent start "${agentName}" --kind pi --pane "${newPaneId}"`;
+            if (model) {
+              startCmd += ` -- --model "${model}"`;
+            }
+            
+            // Start pi agent
+            const startResult = await execCommand(startCmd);
+            const start = JSON.parse(startResult);
+            
+            if (!start.result?.agent?.agent_status) {
+              return { error: "Failed to start agent" };
+            }
+            
+            // Send prompt (escape quotes in prompt)
+            const escapedPrompt = prompt.replace(/"/g, '\\"');
+            const promptResult = await execCommand(
+              `herdr agent prompt "${agentName}" "${escapedPrompt}" --wait --timeout ${timeout}`
+            );
+            const promptRes = JSON.parse(promptResult);
+
+            if (promptRes.type !== "agent_prompted") {
+              // Cleanup on failure
+              await execCommand(`herdr pane close "${newPaneId}" 2>/dev/null || true`);
+              return { error: "Failed to send prompt" };
+            }
+
+            // Read response
+            const readResult = await execCommand(
+              `herdr agent read "${agentName}" --source recent-unwrapped --lines 100`
+            );
+
+            // Cleanup: close the pane
+            await execCommand(`herdr pane close "${newPaneId}" 2>/dev/null || true`);
+
+            return {
+              pane_id: newPaneId,
+              agent_name: agentName,
+              status: "completed",
+              response: readResult,
+            };
+          } catch (error) {
+            return {
+              error: `Failed to spawn pi agent: ${error.message}`,
+            };
+          }
+        },
+      },
+    ],
+  };
+}
+
+// Helper function to execute bash commands
+async function execCommand(command: string): Promise<string> {
+  const { execSync } = require("child_process");
+  try {
+    return execSync(command, {
+      encoding: "utf-8",
+      timeout: 30000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (error: any) {
+    throw new Error(
+      `Command failed: ${command}\n${error.stderr || error.message}`
+    );
+  }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "pi-herdr-spawn",
+  "version": "1.0.0",
+  "description": "Spawn pi agents in isolated Herdr panes for parallel task execution",
+  "keywords": ["pi-package", "herdr", "agent", "spawn", "parallel", "multiplexer"],
+  "author": "duskoide",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duskoide/pi-herdr-spawn"
+  },
+  "pi": {
+    "skills": ["./skills"],
+    "extensions": ["./extensions"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/skills/herdr-spawn/README.md

@@ -0,0 +1,40 @@
+# Herdr Spawn Skill
+
+Spawn pi agents in isolated Herdr panes to execute tasks in parallel.
+
+## Quick Start
+
+After installing this package with `pi install npm:pi-herdr-spawn`, use the slash commands:
+
+```bash
+# Basic usage - spawn with auto-generated name
+/spawn Run tests and report failures
+
+# With custom name
+/spawn Review code pi-reviewer
+
+# With custom name and model
+/spawn Review code pi-reviewer claude-sonnet-5
+
+# Quick spawn (shorthand)
+/spawnp Run the linter and fix errors
+
+# List running agents
+/spawnlist
+
+# Kill a specific agent
+/spawnkill pi-test-runner
+```
+
+## How It Works
+
+1. **Creates a new pane** - Splits the current pane to create an isolated terminal
+2. **Starts pi agent** - Launches a fresh pi instance in the new pane
+3. **Sends your prompt** - Submits the task and waits for completion
+4. **Reads the response** - Gets the agent's output
+5. **Cleans up** - Closes the pane and stops the agent automatically
+
+## Requirements
+
+- Pi must be running inside a Herdr-managed pane (`HERDR_ENV=1`)
+- Herdr must be installed and running

package/skills/herdr-spawn/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: herdr-spawn
+description: Spawns a pi agent in a new Herdr pane to execute isolated tasks in parallel. Use when you need to run work in a separate pane without blocking the current session.
+---
+
+# Herdr Spawn
+
+Spawn pi agents in isolated Herdr panes to execute tasks in parallel.
+
+## When to Use
+
+- Running long tasks without blocking the current session
+- Parallel execution of independent tasks
+- Isolating potentially destructive operations
+- Running background monitoring or testing
+
+## Workflow
+
+### 1. Verify Herdr Environment
+
+```bash
+test "${HERDR_ENV:-}" = 1 && echo "In Herdr" || echo "Not in Herdr"
+```
+
+If not in Herdr, report the error and stop.
+
+### 2. Get Current Context
+
+```bash
+herdr pane current --current
+```
+
+Extract the `pane_id` from the response.
+
+### 3. Create New Pane
+
+Split to create a sibling pane (preserves working directory and user focus):
+
+```bash
+herdr pane split --current --direction right --cwd "$PWD" --no-focus
+```
+
+Extract the new `pane_id` from `.result.pane.pane_id`.
+
+### 4. Start Pi Agent
+
+Start a pi agent with a unique, descriptive name. Optionally specify a model:
+
+```bash
+# Without model (uses parent's model)
+herdr agent start <unique-name> --kind pi --pane <new-pane-id>
+
+# With specific model
+herdr agent start <unique-name> --kind pi --pane <new-pane-id> -- --model <model-id>
+```
+
+**Naming rules:**
+- Lowercase letters, numbers, hyphens only
+- Maximum 31 characters
+- Must be unique among live agents
+- Example: `pi-test-runner`, `pi-refactor-auth`
+
+**Model examples:**
+- `gpt-4o` - Fast, good for simple tasks
+- `claude-sonnet-5` - Strong reasoning
+- `provider/model-id` - Full provider specification
+
+### 5. Send Prompt and Wait
+
+Submit the task and wait for completion:
+
+```bash
+herdr agent prompt <agent-name> "<prompt>" --wait --timeout 120000
+```
+
+For complex tasks, increase the timeout.
+
+### 6. Read Response
+
+Get the agent's output:
+
+```bash
+herdr agent read <agent-name> --source recent-unwrapped --lines 100
+```
+
+### 7. Report Results
+
+Provide:
+- Pane ID where the agent ran
+- Agent name
+- Complete response from the agent
+- Any errors encountered
+
+### 8. Cleanup (Important!)
+
+After getting the response, close the agent and pane to free resources:
+
+```bash
+# Close the pane (this also stops the agent)
+herdr pane close <pane-id>
+```
+
+**Note:** Closing the pane automatically stops any agent running in it. Only close panes you created!
+
+## Example Usage
+
+**User request:** "Run tests in a separate pane using a fast model"
+
+**Agent execution:**
+1. Verify Herdr environment
+2. Create new pane: `herdr pane split --current --direction right --cwd /home/pn --no-focus`
+3. Start agent with model: `herdr agent start pi-test-run --kind pi --pane w7:p2 -- --model gpt-4o`
+4. Send prompt: `herdr agent prompt pi-test-run "Run the test suite with 'npm test' and report any failures" --wait`
+5. Read output: `herdr agent read pi-test-run --source recent-unwrapped --lines 150`
+6. Report: "Tests completed in pane w7:p2. 15 tests passed, 2 failed. Here are the failures: ..."
+7. Cleanup: `herdr pane close w7:p2`
+
+**User request:** "Review code with claude-sonnet-5"
+
+**Agent execution:**
+1. Verify Herdr environment
+2. Create new pane
+3. Start agent with model: `herdr agent start pi-review --kind pi --pane w7:p3 -- --model claude-sonnet-5`
+4. Send prompt: `herdr agent prompt pi-review "Review the recent code changes" --wait`
+5. Read output
+6. Report results
+7. Cleanup
+
+## Important Notes
+
+- Always use `--no-focus` to keep the user's focus on the original pane
+- Use unique agent names to avoid conflicts
+- The spawned agent has access to the same tools and context as the parent
+- For very long tasks, consider using `--timeout` with appropriate values
+- If reading output fails (alternate screen), ask the agent to write results to a file and read that instead