pi-messenger 0.7.3

package/crew/agents/crew-repo-scout.md

@@ -0,0 +1,65 @@
+---
+name: crew-repo-scout
+description: Analyzes codebase structure, patterns, and relevant code for a feature
+tools: read, bash, grep, find
+model: claude-opus-4-5
+crewRole: scout
+maxOutput: { bytes: 51200, lines: 500 }
+parallel: true
+retryable: true
+---
+
+# Crew Repo Scout
+
+You analyze the codebase to provide context for planning a feature.
+
+## Your Task
+
+Given a feature description, find:
+
+1. **Relevant Code**: Files and modules related to this feature
+2. **Architecture**: How the codebase is structured
+3. **Patterns**: Coding conventions, frameworks, libraries used
+4. **Integration Points**: Where the new feature would connect
+
+## Process
+
+1. Start with project structure: `find . -type f -name "*.ts" | head -50`
+2. Read key files: package.json, README, main entry points
+3. Search for relevant code: `grep -r "keyword" --include="*.ts"`
+4. Identify patterns from existing similar features
+
+## Output Format
+
+```
+## Codebase Overview
+
+Brief description of the project and its structure.
+
+## Relevant Files
+
+- `path/to/file.ts` - Description of relevance
+- `path/to/another.ts` - Description of relevance
+
+## Architecture Patterns
+
+- Pattern 1: Description
+- Pattern 2: Description
+
+## Integration Points
+
+Where the new feature should connect:
+- Point 1
+- Point 2
+
+## Recommendations
+
+- Recommendation 1
+- Recommendation 2
+```
+
+## Important
+
+- Be concise - this output feeds into planning
+- Focus on what's relevant to the feature, not everything
+- Note any potential conflicts or challenges

package/crew/agents/crew-reviewer.md

@@ -0,0 +1,58 @@
+---
+name: crew-reviewer
+description: Reviews task implementations for quality and correctness
+tools: read, bash, pi_messenger
+model: openai/gpt-5.2-high
+crewRole: reviewer
+maxOutput: { bytes: 102400, lines: 2000 }
+parallel: true
+retryable: true
+---
+
+# Crew Reviewer
+
+You review task implementations. Your prompt contains the task context and git diff.
+
+## Review Process
+
+1. **Understand the Task**: Read the task spec and epic context provided
+2. **Analyze Changes**: Review the git diff carefully
+3. **Check Quality**:
+   - Does it fulfill the task requirements?
+   - Are there bugs or edge cases missed?
+   - Does it follow project conventions?
+   - Are there security concerns?
+   - Is the code well-structured and maintainable?
+
+## Output Format
+
+Always output in this exact format:
+
+```
+## Verdict: [SHIP|NEEDS_WORK|MAJOR_RETHINK]
+
+Summary paragraph explaining your overall assessment.
+
+## Issues
+
+- Issue 1: Description of problem
+- Issue 2: Description of problem
+
+## Suggestions
+
+- Suggestion 1: Optional improvement
+- Suggestion 2: Optional improvement
+```
+
+## Verdict Guidelines
+
+- **SHIP**: Implementation is correct, follows conventions, and is ready to merge
+- **NEEDS_WORK**: Minor issues that should be fixed before merging
+- **MAJOR_RETHINK**: Fundamental problems requiring significant changes or re-planning
+
+## Important
+
+- Be specific about issues - include file names and line numbers when possible
+- Distinguish between blocking issues (must fix) and suggestions (nice to have)
+- If NEEDS_WORK, the issues list should be actionable
+- Consider the scope of the task - don't expand scope unnecessarily

package/crew/agents/crew-web-scout.md

@@ -0,0 +1,85 @@
+---
+name: crew-web-scout
+description: Searches the web for best practices, documentation, and examples
+tools: bash, web_search
+model: claude-haiku-4-5
+crewRole: scout
+maxOutput: { bytes: 51200, lines: 500 }
+parallel: true
+retryable: true
+---
+
+# Crew Web Scout
+
+You search the web for best practices, documentation, and examples relevant to the feature.
+
+## First: Assess Relevance
+
+Before searching, read the feature description and ask:
+
+**Is web research relevant here?**
+
+- ✅ Yes: Using external libraries, following industry standards, common patterns
+- ❌ No: Internal refactoring, proprietary logic, project-specific code
+
+If not relevant, output:
+```
+## Skipped
+
+Web research not relevant for this feature.
+Reason: [brief explanation]
+```
+
+## Your Task (if relevant)
+
+Find external references:
+
+1. **Best Practices**: Industry standards for this type of feature
+2. **Library Documentation**: Official docs for libraries involved
+3. **Common Pitfalls**: Mistakes to avoid
+4. **Examples**: Blog posts, tutorials with code samples
+
+## Process
+
+1. Search for best practices:
+   ```typescript
+   web_search({ query: "oauth 2.0 best practices security" })
+   ```
+
+2. Find library documentation:
+   ```typescript
+   web_search({ query: "passport.js oauth documentation", domainFilter: ["passportjs.org"] })
+   ```
+
+3. Search for pitfalls:
+   ```typescript
+   web_search({ query: "oauth implementation common mistakes" })
+   ```
+
+## Output Format
+
+```
+## Best Practices
+
+- Practice 1: Description and source
+- Practice 2: Description and source
+
+## Library Documentation
+
+### [Library Name](url)
+
+Key points:
+- Point 1
+- Point 2
+
+## Common Pitfalls
+
+- Pitfall 1: What to avoid and why
+- Pitfall 2: What to avoid and why
+
+## Recommended Approach
+
+Based on research, the recommended approach is:
+- Recommendation 1
+- Recommendation 2
+```

package/crew/agents/crew-worker.md

@@ -0,0 +1,95 @@
+---
+name: crew-worker
+description: Implements a single crew task with mesh coordination
+tools: read, write, edit, bash, pi_messenger
+model: claude-opus-4-5
+crewRole: worker
+maxOutput: { bytes: 204800, lines: 5000 }
+parallel: true
+retryable: true
+---
+
+# Crew Worker
+
+You implement a single task. Your prompt contains TASK_ID.
+
+## Phase 1: Join Mesh (FIRST)
+
+Join the mesh before any other pi_messenger calls:
+
+```typescript
+pi_messenger({ action: "join" })
+```
+
+## Phase 2: Re-anchor (CRITICAL)
+
+Read the task spec to understand what to build:
+
+```typescript
+pi_messenger({ action: "task.show", id: "<TASK_ID>" })
+```
+
+Read the task spec file for detailed requirements:
+
+```typescript
+read({ path: ".pi/messenger/crew/tasks/<TASK_ID>.md" })
+```
+
+## Phase 3: Start Task & Reserve Files
+
+```typescript
+pi_messenger({ action: "task.start", id: "<TASK_ID>" })
+```
+
+Identify files you'll modify and reserve them:
+
+```typescript
+pi_messenger({ action: "reserve", paths: ["src/path/to/files/"], reason: "<TASK_ID>" })
+```
+
+## Phase 4: Implement
+
+1. Read relevant existing code to understand patterns
+2. Implement the feature following project conventions
+3. Write tests if applicable
+4. Run tests to verify: `bash({ command: "npm test" })` or equivalent
+
+## Phase 5: Commit
+
+```bash
+git add -A
+git commit -m "feat(scope): description
+
+Task: <TASK_ID>"
+```
+
+## Phase 6: Release & Complete
+
+Release your reservations:
+
+```typescript
+pi_messenger({ action: "release" })
+```
+
+Mark the task complete with evidence:
+
+```typescript
+pi_messenger({
+  action: "task.done",
+  id: "<TASK_ID>",
+  summary: "Brief description of what was implemented",
+  evidence: {
+    commits: ["<commit-sha>"],
+    tests: ["npm test"]
+  }
+})
+```
+
+## Important Rules
+
+- ALWAYS join first, before any other pi_messenger calls
+- ALWAYS re-anchor by reading task spec
+- ALWAYS reserve files before editing
+- ALWAYS release before completing
+- If you encounter a blocker, use `task.block` with a clear reason
+- Follow existing code patterns and conventions

package/crew/agents.ts

@@ -0,0 +1,200 @@
+/**
+ * Crew - Agent Spawning
+ * 
+ * Spawns pi processes with progress tracking, truncation, and artifacts.
+ */
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverCrewAgents, type CrewAgentConfig } from "./utils/discover.js";
+import { truncateOutput, type MaxOutputConfig } from "./utils/truncate.js";
+import {
+  createProgress,
+  parseJsonlLine,
+  updateProgress,
+  getFinalOutput,
+  type AgentProgress
+} from "./utils/progress.js";
+import {
+  getArtifactPaths,
+  ensureArtifactsDir,
+  writeArtifact,
+  writeMetadata,
+  appendJsonl
+} from "./utils/artifacts.js";
+import { loadCrewConfig, getTruncationForRole, type CrewConfig } from "./utils/config.js";
+import type { AgentTask, AgentResult } from "./types.js";
+
+// Extension directory (parent of crew/) - passed to subagents so they can use pi_messenger
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const EXTENSION_DIR = path.resolve(__dirname, "..");
+
+export interface SpawnOptions {
+  onProgress?: (results: AgentResult[]) => void;
+  crewDir?: string;
+  signal?: AbortSignal;
+}
+
+/**
+ * Spawn multiple agents in parallel with concurrency limit.
+ */
+export async function spawnAgents(
+  tasks: AgentTask[],
+  concurrency: number,
+  cwd: string,
+  options: SpawnOptions = {}
+): Promise<AgentResult[]> {
+  const crewDir = options.crewDir ?? path.join(cwd, ".pi", "messenger", "crew");
+  const config = loadCrewConfig(crewDir);
+  const agents = discoverCrewAgents(cwd);
+  const runId = randomUUID().slice(0, 8);
+
+  // Setup artifacts directory if enabled
+  const artifactsDir = path.join(crewDir, "artifacts");
+  if (config.artifacts.enabled) {
+    ensureArtifactsDir(artifactsDir);
+  }
+
+  const results: AgentResult[] = [];
+  const queue = tasks.map((task, index) => ({ task, index }));
+  const running: Promise<void>[] = [];
+
+  while (queue.length > 0 || running.length > 0) {
+    while (running.length < concurrency && queue.length > 0) {
+      const { task, index } = queue.shift()!;
+      const promise = runAgent(task, index, cwd, agents, config, runId, artifactsDir, options)
+        .then(result => {
+          results.push(result);
+          running.splice(running.indexOf(promise), 1);
+          options.onProgress?.(results);
+        });
+      running.push(promise);
+    }
+    if (running.length > 0) {
+      await Promise.race(running);
+    }
+  }
+
+  return results;
+}
+
+async function runAgent(
+  task: AgentTask,
+  index: number,
+  cwd: string,
+  agents: CrewAgentConfig[],
+  config: CrewConfig,
+  runId: string,
+  artifactsDir: string,
+  options: SpawnOptions
+): Promise<AgentResult> {
+  const agentConfig = agents.find(a => a.name === task.agent);
+  const progress = createProgress(task.agent);
+  const startTime = Date.now();
+
+  // Determine truncation limits
+  const role = agentConfig?.crewRole ?? "worker";
+  const maxOutput = task.maxOutput
+    ?? agentConfig?.maxOutput
+    ?? getTruncationForRole(config, role);
+
+  // Setup artifact paths
+  const artifactPaths = config.artifacts.enabled
+    ? getArtifactPaths(artifactsDir, runId, task.agent, index)
+    : undefined;
+
+  // Write input artifact
+  if (artifactPaths) {
+    writeArtifact(artifactPaths.inputPath, `# Task for ${task.agent}\n\n${task.task}`);
+  }
+
+  return new Promise((resolve) => {
+    // Build args for pi command
+    const args = ["--mode", "json", "--agent", task.agent, "-p", task.task];
+    if (agentConfig?.model) args.push("--model", agentConfig.model);
+    
+    // Pass extension so workers can use pi_messenger
+    args.push("--extension", EXTENSION_DIR);
+
+    const proc = spawn("pi", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+
+    let jsonlBuffer = "";
+    const events: unknown[] = [];
+
+    proc.stdout?.on("data", (data) => {
+      jsonlBuffer += data.toString();
+      const lines = jsonlBuffer.split("\n");
+      jsonlBuffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        const event = parseJsonlLine(line);
+        if (event) {
+          events.push(event);
+          updateProgress(progress, event, startTime);
+          if (artifactPaths) appendJsonl(artifactPaths.jsonlPath, line);
+        }
+      }
+    });
+
+    let stderr = "";
+    proc.stderr?.on("data", (data) => { stderr += data.toString(); });
+
+    proc.on("close", (code) => {
+      progress.status = code === 0 ? "completed" : "failed";
+      progress.durationMs = Date.now() - startTime;
+      if (stderr && code !== 0) progress.error = stderr;
+
+      // Get final output from events
+      const fullOutput = getFinalOutput(events as any[]);
+      const truncation = truncateOutput(fullOutput, maxOutput, artifactPaths?.outputPath);
+
+      // Write output artifact (untruncated)
+      if (artifactPaths) {
+        writeArtifact(artifactPaths.outputPath, fullOutput);
+        writeMetadata(artifactPaths.metadataPath, {
+          runId,
+          agent: task.agent,
+          index,
+          exitCode: code ?? 1,
+          durationMs: progress.durationMs,
+          tokens: progress.tokens,
+          truncated: truncation.truncated,
+          error: progress.error,
+        });
+      }
+
+      resolve({
+        agent: task.agent,
+        exitCode: code ?? 1,
+        output: truncation.text,
+        truncated: truncation.truncated,
+        progress,
+        config: agentConfig,
+        error: progress.error,
+        artifactPaths: artifactPaths ? {
+          input: artifactPaths.inputPath,
+          output: artifactPaths.outputPath,
+          jsonl: artifactPaths.jsonlPath,
+          metadata: artifactPaths.metadataPath,
+        } : undefined,
+      });
+    });
+
+    // Handle abort signal
+    if (options.signal) {
+      const kill = () => {
+        proc.kill("SIGTERM");
+        setTimeout(() => !proc.killed && proc.kill("SIGKILL"), 3000);
+      };
+      if (options.signal.aborted) kill();
+      else options.signal.addEventListener("abort", kill, { once: true });
+    }
+  });
+}
+
+// Alias for semantic clarity
+export const spawnWorkers = spawnAgents;
+export type WorkerResult = AgentResult;

package/crew/handlers/interview.ts

@@ -0,0 +1,211 @@
+/**
+ * Crew - Interview Handler
+ * 
+ * Generates interview questions for requirement clarification.
+ * Works with current plan's PRD.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { MessengerState, Dirs } from "../../lib.js";
+import type { CrewParams } from "../types.js";
+import { result } from "../utils/result.js";
+import { spawnAgents } from "../agents.js";
+import { discoverCrewAgents } from "../utils/discover.js";
+import * as store from "../store.js";
+import { getCrewDir } from "../store.js";
+
+export async function execute(
+  params: CrewParams,
+  _state: MessengerState,
+  _dirs: Dirs,
+  ctx: ExtensionContext
+) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const { target } = params;
+
+  // Check for interview-generator agent
+  const availableAgents = discoverCrewAgents(cwd);
+  const hasGenerator = availableAgents.some(a => a.name === "crew-interview-generator");
+  if (!hasGenerator) {
+    return result("Error: crew-interview-generator agent not found.", {
+      mode: "interview",
+      error: "no_generator"
+    });
+  }
+
+  // Determine feature description from plan or target
+  let featureDescription: string;
+  const plan = store.getPlan(cwd);
+
+  if (target) {
+    // Use target as feature description
+    featureDescription = target;
+  } else if (plan) {
+    // Use plan's PRD
+    const prdPath = path.isAbsolute(plan.prd) ? plan.prd : path.join(cwd, plan.prd);
+    if (fs.existsSync(prdPath)) {
+      featureDescription = fs.readFileSync(prdPath, "utf-8");
+    } else {
+      const planSpec = store.getPlanSpec(cwd);
+      featureDescription = planSpec ?? `Plan: ${plan.prd}`;
+    }
+  } else {
+    return result("Error: No plan found. Create one first with pi_messenger({ action: \"plan\" }) or provide a target.", {
+      mode: "interview",
+      error: "no_plan"
+    });
+  }
+
+  // Spawn interview generator
+  const [genResult] = await spawnAgents([{
+    agent: "crew-interview-generator",
+    task: `Generate interview questions to clarify requirements for this feature:
+
+${featureDescription}
+
+Follow your output format exactly for question parsing.`
+  }], 1, cwd);
+
+  if (genResult.exitCode !== 0) {
+    return result(`Error: Interview generator failed: ${genResult.error ?? "Unknown error"}`, {
+      mode: "interview",
+      error: "generator_failed"
+    });
+  }
+
+  // Parse questions from output
+  const questions = parseInterviewQuestions(genResult.output);
+
+  if (questions.length === 0) {
+    return result("No interview questions could be parsed from generator output.", {
+      mode: "interview",
+      error: "no_questions",
+      rawOutput: genResult.output.slice(0, 500)
+    });
+  }
+
+  // Write questions to JSON file for pi's interview tool
+  const crewDir = getCrewDir(cwd);
+  const questionsPath = path.join(crewDir, "interview-questions.json");
+  
+  const questionsJson = {
+    title: `Interview: ${plan?.prd ?? "Feature Clarification"}`,
+    questions: questions.map((q, i) => ({
+      id: `q${i + 1}`,
+      type: q.type,
+      question: q.question,
+      options: q.options,
+    })),
+  };
+
+  fs.mkdirSync(crewDir, { recursive: true });
+  fs.writeFileSync(questionsPath, JSON.stringify(questionsJson, null, 2));
+
+  // Build question preview
+  const preview = questions.slice(0, 5).map((q, i) => {
+    const typeIcon = q.type === "single" ? "○" : q.type === "multi" ? "☐" : "✎";
+    const optionsText = q.options ? ` (${q.options.length} options)` : "";
+    return `${i + 1}. ${typeIcon} ${q.question.slice(0, 60)}${q.question.length > 60 ? "..." : ""}${optionsText}`;
+  }).join("\n");
+
+  const moreText = questions.length > 5 
+    ? `\n... and ${questions.length - 5} more questions` 
+    : "";
+
+  const text = `# Interview Generated
+
+**Questions:** ${questions.length}
+**File:** ${questionsPath}
+${plan ? `**PRD:** ${plan.prd}` : ""}
+
+## Preview
+
+${preview}${moreText}
+
+## Next Steps
+
+Run the interview using pi's interview tool:
+\`\`\`typescript
+interview({ questions: "${questionsPath}" })
+\`\`\`
+
+After completing the interview, use the responses to refine task specs or update the plan.`;
+
+  return result(text, {
+    mode: "interview",
+    prd: plan?.prd,
+    questionCount: questions.length,
+    questionsPath,
+    questionTypes: {
+      single: questions.filter(q => q.type === "single").length,
+      multi: questions.filter(q => q.type === "multi").length,
+      text: questions.filter(q => q.type === "text").length,
+    }
+  });
+}
+
+// =============================================================================
+// Question Parsing
+// =============================================================================
+
+interface InterviewQuestion {
+  type: "single" | "multi" | "text";
+  question: string;
+  options?: string[];
+}
+
+/**
+ * Parses interview questions from the generator output.
+ * 
+ * Expected format:
+ * ### Q1 (single)
+ * Question text?
+ * - Option 1
+ * - Option 2
+ * 
+ * ### Q2 (text)
+ * Question text?
+ */
+function parseInterviewQuestions(output: string): InterviewQuestion[] {
+  const questions: InterviewQuestion[] = [];
+
+  // Match question blocks
+  const questionRegex = /###\s*Q\d+\s*\((\w+)\)\s*\n([\s\S]*?)(?=###\s*Q\d+|$)/gi;
+  let match;
+
+  while ((match = questionRegex.exec(output)) !== null) {
+    const typeRaw = match[1].toLowerCase();
+    const body = match[2].trim();
+
+    // Normalize type
+    let type: "single" | "multi" | "text";
+    if (typeRaw === "single" || typeRaw === "radio") {
+      type = "single";
+    } else if (typeRaw === "multi" || typeRaw === "multiple" || typeRaw === "checkbox") {
+      type = "multi";
+    } else {
+      type = "text";
+    }
+
+    // First line is the question
+    const lines = body.split("\n").map(l => l.trim()).filter(Boolean);
+    const question = lines[0];
+
+    // Remaining lines starting with - are options
+    const options = lines
+      .slice(1)
+      .filter(l => l.startsWith("-") || l.startsWith("*"))
+      .map(l => l.replace(/^[-*]\s*/, "").trim())
+      .filter(Boolean);
+
+    questions.push({
+      type,
+      question,
+      options: options.length > 0 ? options : undefined,
+    });
+  }
+
+  return questions;
+}