@johnnygreco/pizza-pi 0.1.1

package/node_modules/pi-interactive-subagents/pi-extension/subagents/plan-skill.md

@@ -0,0 +1,225 @@
+---
+name: plan
+description: >
+  Planning workflow. Spawns a spec agent to clarify WHAT to build, then a
+  planner agent to figure out HOW. Use when asked to "plan", "brainstorm",
+  "I want to build X", or "let's design". Requires the subagents extension
+  and a supported multiplexer (cmux/tmux/zellij).
+---
+
+# Plan
+
+A planning workflow that separates WHAT (spec) from HOW (plan). First a spec agent clarifies intent and requirements with the user, then a planner figures out the technical approach and creates todos.
+
+**Announce at start:** "Let me take a quick look, then I'll send a scout to map the codebase before we start the spec session."
+
+---
+
+## Tab Titles
+
+Use `set_tab_title` to keep the user informed of progress in the multiplexer UI. Update the title at every phase transition.
+
+| Phase         | Title example                                                  |
+| ------------- | -------------------------------------------------------------- |
+| Assessment    | `🔍 Assessing: <short task>`                                   |
+| Scouting      | `🔍 Scouting: <short task>`                                    |
+| Spec          | `📝 Spec: <short task>`                                        |
+| Planning      | `💬 Planning: <short task>`                                    |
+| Review plan   | `📋 Review: <short task>`                                      |
+| Executing     | `🔨 Executing: 1/3 — <short task>` (update counter per worker) |
+| Reviewing     | `🔎 Reviewing: <short task>`                                   |
+| Done          | `✅ Done: <short task>`                                        |
+
+Name subagents with context too:
+
+- Scout: `"🔍 Scout"` (default is fine)
+- Spec: `"📝 Spec"`
+- Planner: `"💬 Planner"`
+- Workers: `"🔨 Worker 1/3"`, `"🔨 Worker 2/3"`, etc.
+- Reviewer: `"🔎 Reviewer"`
+
+---
+
+## The Flow
+
+```
+Phase 1: Quick Assessment (main session — 30s orientation)
+    ↓
+Phase 2: Scout (autonomous — deep codebase context)
+    ↓
+Phase 3: Spawn Spec Agent (interactive — clarifies WHAT, has scout context)
+    ↓
+Phase 4: Spawn Planner Agent (interactive — figures out HOW, has scout context)
+    ↓
+    Optional: Re-scout if spec/planner significantly changed scope
+    ↓
+Phase 5: Review Plan & Todos (main session)
+    ↓
+Phase 6: Execute Todos (workers — receive plan + scout context)
+    ↓
+Phase 7: Review
+```
+
+---
+
+## Phase 1: Quick Assessment
+
+Quick orientation — just enough to give the scout a focused mission:
+
+```bash
+ls -la
+find . -type f -name "*.ts" | head -20  # or relevant extension
+cat package.json 2>/dev/null | head -30
+```
+
+Spend ~30 seconds. You're looking for: tech stack, project shape, and the area relevant to the user's request. This tells you what to ask the scout to focus on.
+
+---
+
+## Phase 2: Scout
+
+**Always spawn a scout before spec/planner.** The scout's context feeds into both — it helps the spec agent ask better questions and helps the planner make better design decisions.
+
+```typescript
+subagent({
+  name: "🔍 Scout",
+  agent: "scout",
+  task: "Analyze the codebase for [user's request area]. Map file structure, key modules, patterns, conventions, and existing code related to [feature area]. Focus on what a spec agent and planner would need to understand.",
+});
+```
+
+**Wait for the scout to finish.** Read the scout's context artifact — you'll pass it to both spec and planner.
+
+---
+
+## Phase 3: Spawn Spec Agent
+
+Spawn the interactive spec agent with the scout's context. The `spec` agent clarifies intent, requirements, effort level, and success criteria (ISC) with the user.
+
+```typescript
+subagent({
+  name: "📝 Spec",
+  agent: "spec",
+  interactive: true,
+  task: `Define spec: [what the user wants to build]
+
+Scout context:
+[paste scout findings here — file structure, conventions, patterns, relevant code]`,
+});
+```
+
+**The user works with the spec agent.** When done, they press Ctrl+D and the spec artifact path is returned.
+
+---
+
+## Phase 4: Spawn Planner Agent
+
+Read the spec artifact, then spawn the planner. Pass both the spec AND the scout context. The planner takes these as input and figures out the technical approach — explores options, validates design, runs a premortem, writes the plan, and creates todos with mandatory code examples/references.
+
+```typescript
+// Read the spec first
+read_artifact({ name: "specs/YYYY-MM-DD-<name>.md" });
+
+subagent({
+  name: "💬 Planner",
+  agent: "planner",
+  interactive: true,
+  task: `Plan implementation for spec: specs/YYYY-MM-DD-<name>.md
+
+Scout context:
+[paste scout findings here — same context from Phase 2]`,
+});
+```
+
+**The user works with the planner.** The planner will NOT re-clarify requirements — that's already done in the spec. It focuses on technical approach, design validation, premortem risk analysis, and creating well-scoped todos.
+
+When done, the user presses Ctrl+D and the plan + todos are returned.
+
+### Optional: Re-scout after planning
+
+If the spec or planner significantly changed scope (e.g. new subsystems, different approach than expected, areas the original scout didn't cover), spawn another scout targeting the new areas:
+
+```typescript
+subagent({
+  name: "🔍 Scout (updated scope)",
+  agent: "scout",
+  task: "The plan changed scope. Gather context for [new areas]. Read the plan at [plan path]. Focus on [specific files/modules the planner identified that weren't in the original scout].",
+});
+```
+
+Fold the new context into the worker tasks.
+
+---
+
+## Phase 5: Review Plan & Todos
+
+Once the planner closes, read the plan and todos:
+
+```typescript
+todo({ action: "list" });
+```
+
+Review with the user:
+
+> "Here's what the planner produced: [brief summary]. Ready to execute, or anything to adjust?"
+
+---
+
+## Phase 6: Execute Todos
+
+Spawn workers sequentially. Each worker gets the plan path and scout context:
+
+```typescript
+// Workers execute todos sequentially — one at a time
+subagent({
+  name: "🔨 Worker 1/N",
+  agent: "worker",
+  task: "Implement TODO-xxxx. Mark the todo as done. Plan: [plan path]\n\nScout context: [paste scout summary from Phase 2, plus any re-scout from Phase 4]",
+});
+
+// Check result, then next todo
+subagent({
+  name: "🔨 Worker 2/N",
+  agent: "worker",
+  task: "Implement TODO-yyyy. Mark the todo as done. Plan: [plan path]\n\nScout context: [paste scout summary]",
+});
+```
+
+**Always run workers sequentially in the same git repo** — parallel workers will conflict on commits.
+
+---
+
+## Phase 7: Review
+
+After all todos are complete:
+
+```typescript
+subagent({
+  name: "Reviewer",
+  agent: "reviewer",
+  interactive: false,
+  task: "Review the recent changes. Plan: [plan path]",
+});
+```
+
+Triage findings:
+
+- **P0** — Real bugs, security issues → fix now
+- **P1** — Genuine traps, maintenance dangers → fix before merging
+- **P2** — Minor issues → fix if quick, note otherwise
+- **P3** — Nits → skip
+
+Create todos for P0/P1, run workers to fix, re-review only if fixes were substantial.
+
+---
+
+## ⚠️ Completion Checklist
+
+Before reporting done:
+
+1. ✅ Scout ran before spec/planner?
+2. ✅ Scout context was passed to spec and planner?
+3. ✅ All worker todos closed?
+4. ✅ Every todo has a polished commit (using the `commit` skill)?
+5. ✅ Reviewer has run?
+6. ✅ Reviewer findings triaged and addressed?

package/node_modules/pi-interactive-subagents/pi-extension/subagents/session.ts

@@ -0,0 +1,124 @@
+import { readFileSync, appendFileSync, copyFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+
+export interface SessionEntry {
+  type: string;
+  id: string;
+  parentId?: string;
+  [key: string]: unknown;
+}
+
+export interface MessageEntry extends SessionEntry {
+  type: "message";
+  message: {
+    role: "user" | "assistant" | "toolResult";
+    content: Array<{ type: string; text?: string; [key: string]: unknown }>;
+  };
+}
+
+function readEntries(sessionFile: string): SessionEntry[] {
+  const raw = readFileSync(sessionFile, "utf8");
+  return raw
+    .split("\n")
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line) as SessionEntry);
+}
+
+/**
+ * Return the id of the last entry in the session file (current branch point / leaf).
+ */
+export function getLeafId(sessionFile: string): string | null {
+  const entries = readEntries(sessionFile);
+  return entries.length > 0 ? entries[entries.length - 1].id : null;
+}
+
+/**
+ * Return the number of non-empty lines (entries) in the session file.
+ */
+export function getEntryCount(sessionFile: string): number {
+  const raw = readFileSync(sessionFile, "utf8");
+  return raw.split("\n").filter((line) => line.trim()).length;
+}
+
+/**
+ * Return entries added after `afterLine` (1-indexed count of existing entries).
+ */
+export function getNewEntries(sessionFile: string, afterLine: number): SessionEntry[] {
+  const raw = readFileSync(sessionFile, "utf8");
+  const lines = raw.split("\n").filter((line) => line.trim());
+  return lines.slice(afterLine).map((line) => JSON.parse(line) as SessionEntry);
+}
+
+/**
+ * Find the last assistant message text in a list of entries.
+ */
+export function findLastAssistantMessage(entries: SessionEntry[]): string | null {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "message") continue;
+    const msg = entry as MessageEntry;
+    if (msg.message.role !== "assistant") continue;
+
+    const texts = msg.message.content
+      .filter(
+        (block) =>
+          block.type === "text" && typeof block.text === "string" && block.text.trim() !== "",
+      )
+      .map((block) => block.text as string);
+
+    if (texts.length > 0 && texts.join("").trim()) return texts.join("\n");
+  }
+  return null;
+}
+
+/**
+ * Append a branch_summary entry to the session file.
+ * Returns the new entry's id.
+ */
+export function appendBranchSummary(
+  sessionFile: string,
+  branchPointId: string,
+  fromId: string | null,
+  summary: string,
+): string {
+  const id = randomBytes(4).toString("hex");
+  const entry = {
+    type: "branch_summary",
+    id,
+    parentId: branchPointId,
+    timestamp: new Date().toISOString(),
+    fromId: fromId ?? branchPointId,
+    summary,
+  };
+  appendFileSync(sessionFile, JSON.stringify(entry) + "\n", "utf8");
+  return id;
+}
+
+/**
+ * Copy the session file to destDir for parallel worker isolation.
+ * Returns the path of the copy.
+ */
+export function copySessionFile(sessionFile: string, destDir: string): string {
+  const id = randomBytes(4).toString("hex");
+  const dest = join(destDir, `subagent-${id}.jsonl`);
+  copyFileSync(sessionFile, dest);
+  return dest;
+}
+
+/**
+ * Read new entries from sourceFile (after afterLine), append them to targetFile.
+ * Returns the appended entries.
+ */
+export function mergeNewEntries(
+  sourceFile: string,
+  targetFile: string,
+  afterLine: number,
+): SessionEntry[] {
+  const entries = getNewEntries(sourceFile, afterLine);
+  for (const entry of entries) {
+    appendFileSync(targetFile, JSON.stringify(entry) + "\n", "utf8");
+  }
+  return entries;
+}
+const unused = "hello";

package/node_modules/pi-interactive-subagents/pi-extension/subagents/subagent-done.ts

@@ -0,0 +1,166 @@
+/**
+ * Extension loaded into sub-agents.
+ * - Shows agent identity + available tools as a styled widget above the editor (toggle with Ctrl+J)
+ * - Provides a `subagent_done` tool for autonomous agents to self-terminate
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Box, Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+
+export function shouldMarkUserTookOver(agentStarted: boolean): boolean {
+  return agentStarted;
+}
+
+export function shouldAutoExitOnAgentEnd(
+  userTookOver: boolean,
+  messages: any[] | undefined,
+): boolean {
+  if (userTookOver) return false;
+
+  if (messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg?.role === "assistant") {
+        return msg.stopReason !== "aborted";
+      }
+    }
+  }
+
+  return true;
+}
+
+export default function (pi: ExtensionAPI) {
+  let toolNames: string[] = [];
+  let denied: string[] = [];
+  let expanded = false;
+
+  // Read subagent identity from env vars (set by parent orchestrator)
+  const subagentName = process.env.PI_SUBAGENT_NAME ?? "";
+  const subagentAgent = process.env.PI_SUBAGENT_AGENT ?? "";
+
+  function renderWidget(ctx: { ui: { setWidget: Function } }, _theme: any) {
+    ctx.ui.setWidget(
+      "subagent-tools",
+      (_tui: any, theme: any) => {
+        const box = new Box(1, 0, (text: string) => theme.bg("toolSuccessBg", text));
+
+        const label = subagentAgent || subagentName;
+        const agentTag = label ? theme.bold(theme.fg("accent", `[${label}]`)) : "";
+
+        if (expanded) {
+          // Expanded: full tool list + denied
+          const countInfo = theme.fg("dim", ` — ${toolNames.length} available`);
+          const hint = theme.fg("muted", "  (Ctrl+J to collapse)");
+
+          const toolList = toolNames
+            .map((name: string) => theme.fg("dim", name))
+            .join(theme.fg("muted", ", "));
+
+          let deniedLine = "";
+          if (denied.length > 0) {
+            const deniedList = denied
+              .map((name: string) => theme.fg("error", name))
+              .join(theme.fg("muted", ", "));
+            deniedLine = "\n" + theme.fg("muted", "denied: ") + deniedList;
+          }
+
+          const content = new Text(
+            `${agentTag}${countInfo}${hint}\n${toolList}${deniedLine}`,
+            0,
+            0,
+          );
+          box.addChild(content);
+        } else {
+          // Collapsed: one-line summary
+          const countInfo = theme.fg("dim", ` — ${toolNames.length} tools`);
+          const deniedInfo =
+            denied.length > 0
+              ? theme.fg("dim", " · ") + theme.fg("error", `${denied.length} denied`)
+              : "";
+          const hint = theme.fg("muted", "  (Ctrl+J to expand)");
+
+          const content = new Text(`${agentTag}${countInfo}${deniedInfo}${hint}`, 0, 0);
+          box.addChild(content);
+        }
+
+        return box;
+      },
+      { placement: "aboveEditor" },
+    );
+  }
+
+  const autoExit = process.env.PI_SUBAGENT_AUTO_EXIT === "1";
+
+  // Show widget + status bar on session start
+  pi.on("session_start", (_event, ctx) => {
+    const tools = pi.getAllTools();
+    toolNames = tools.map((t) => t.name).sort();
+    denied = (process.env.PI_DENY_TOOLS ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    renderWidget(ctx, null);
+  });
+
+  // Auto-exit: when the agent loop ends, shut down automatically.
+  // If the user interrupts (Escape) or sends any input, auto-exit is disabled
+  // for that cycle — the user wants to steer. Once they're done and the agent
+  // completes normally again, auto-exit re-engages.
+  // Enabled via `auto-exit: true` in agent frontmatter.
+  if (autoExit) {
+    let userTookOver = false;
+    let agentStarted = false;
+
+    pi.on("agent_start", () => {
+      agentStarted = true;
+    });
+
+    pi.on("input", () => {
+      // Ignore the initial task message that starts an autonomous subagent.
+      // Only inputs after the first agent run has started count as user takeover.
+      if (!shouldMarkUserTookOver(agentStarted)) return;
+      userTookOver = true;
+    });
+
+    pi.on("agent_end", (event, ctx) => {
+      const messages = (event as any).messages as any[] | undefined;
+      const shouldExit = shouldAutoExitOnAgentEnd(userTookOver, messages);
+      if (!shouldExit) {
+        // User sent input after the agent had started, or the run was interrupted
+        // with Escape. Reset takeover so auto-exit can re-engage on the next
+        // normal completion cycle.
+        userTookOver = false;
+        return;
+      }
+
+      ctx.shutdown();
+    });
+  }
+
+  // Toggle expand/collapse with Ctrl+J
+  pi.registerShortcut("ctrl+j", {
+    description: "Toggle subagent tools widget",
+    handler: (ctx) => {
+      expanded = !expanded;
+      renderWidget(ctx, null);
+    },
+  });
+
+  pi.registerTool({
+    name: "subagent_done",
+    label: "Subagent Done",
+    description:
+      "Call this tool when you have completed your task. " +
+      "It will close this session and return your results to the main session. " +
+      "Your LAST assistant message before calling this becomes the summary returned to the caller.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      ctx.shutdown();
+      return {
+        content: [{ type: "text", text: "Shutting down subagent session." }],
+        details: {},
+      };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@johnnygreco/pizza-pi",
+  "version": "0.1.1",
+  "description": "🍕 Pizza — Pi with toppings",
+  "type": "module",
+  "license": "Apache-2.0",
+  "keywords": [
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/johnnygreco/pizza.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "pi": {
+    "extensions": [
+      "extensions",
+      "node_modules/pi-interactive-subagents"
+    ],
+    "skills": [
+      "skills"
+    ],
+    "prompts": [
+      "prompts"
+    ]
+  },
+  "files": [
+    "extensions",
+    "skills",
+    "prompts"
+  ],
+  "bundledDependencies": [
+    "pi-interactive-subagents"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "scripts": {
+    "prepack": "rm -rf node_modules/pi-interactive-subagents/test",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "pi-interactive-subagents": "github:HazAT/pi-interactive-subagents#bf4fb961c14567c949e010dca5ec01590b08289a"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "~0.66.1",
+    "@mariozechner/pi-ai": "~0.66.1",
+    "@mariozechner/pi-tui": "~0.66.1",
+    "@sinclair/typebox": "~0.34.49"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "0.66.1",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}