pi-maestro-flow 0.2.0

package/src/tools/explore.ts

@@ -0,0 +1,134 @@
+/**
+ * Explore action — parallel code search via teammate sub-agents.
+ *
+ * For each prompt, spawns a teammate agent (explorer profile) that
+ * searches the codebase using read/grep/find/ls tools.
+ * Results are collected and merged into a unified exploration output.
+ */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { runTeammate } from "@pi-maestro/teammate/src/runs/execution.ts";
+import type { SingleResult } from "@pi-maestro/teammate/src/shared/types.ts";
+
+export interface ExploreParams {
+  prompts?: string[];
+  endpoint?: string;
+  all?: boolean;
+  maxTurns?: number;
+  concurrency?: number;
+  model?: string;
+  cwd?: string;
+}
+
+export interface ExploreResult {
+  prompt: string;
+  agent: string;
+  model: string;
+  content: string;
+  exitCode: number;
+  durationMs: number;
+}
+
+/**
+ * Execute explore action: spawn parallel teammate agents for code search.
+ */
+export async function executeExplore(
+  params: ExploreParams,
+  signal: AbortSignal,
+  ctx: ExtensionContext,
+): Promise<AgentToolResult> {
+  const prompts = params.prompts ?? [];
+
+  if (prompts.length === 0) {
+    return {
+      content: [{ type: "text", text: "No prompts provided for explore action." }],
+      isError: true,
+    };
+  }
+
+  const concurrency = params.concurrency ?? 4;
+  const results: ExploreResult[] = [];
+  const errors: string[] = [];
+
+  // Process prompts with concurrency limit
+  const queue = [...prompts];
+  const running: Promise<void>[] = [];
+
+  const processPrompt = async (prompt: string): Promise<void> => {
+    if (signal.aborted) return;
+
+    try {
+      const result = await runTeammate(
+        {
+          agent: "explorer",
+          task: prompt,
+          model: params.model ?? params.endpoint,
+          cwd: params.cwd,
+          reply_to: "caller",
+          lifecycle: "ephemeral",
+        },
+        {
+          baseCwd: ctx.cwd,
+          signal,
+        },
+      );
+
+      const lastMessage =
+        result.messages[result.messages.length - 1]?.content ?? "(no output)";
+
+      results.push({
+        prompt,
+        agent: result.agent,
+        model: result.model,
+        content: lastMessage,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+      });
+    } catch (error) {
+      errors.push(
+        `Prompt "${prompt.slice(0, 50)}": ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  };
+
+  // Dispatch with concurrency control
+  for (const prompt of queue) {
+    if (signal.aborted) break;
+
+    const task = processPrompt(prompt);
+    running.push(task);
+
+    if (running.length >= concurrency) {
+      await Promise.race(running);
+      // Remove completed tasks
+      for (let i = running.length - 1; i >= 0; i--) {
+        const settled = await Promise.race([
+          running[i].then(() => true),
+          Promise.resolve(false),
+        ]);
+        if (settled) running.splice(i, 1);
+      }
+    }
+  }
+
+  // Wait for remaining
+  await Promise.allSettled(running);
+
+  // Build output
+  const outputParts: string[] = [];
+  for (const result of results) {
+    outputParts.push(
+      `## Prompt: ${result.prompt.slice(0, 80)}\n**Model**: ${result.model} | **Duration**: ${result.durationMs}ms\n\n${result.content}\n`,
+    );
+  }
+
+  if (errors.length > 0) {
+    outputParts.push(`## Errors\n${errors.map((e) => `- ${e}`).join("\n")}`);
+  }
+
+  return {
+    content: [{ type: "text", text: outputParts.join("\n---\n\n") }],
+    isError: results.length === 0 && errors.length > 0,
+  };
+}

package/src/tools/moa.ts

@@ -0,0 +1,213 @@
+/**
+ * MOA (Mixture-of-Agents) action — multi-model synthesis.
+ *
+ * Phase 1: Spawn parallel teammate agents (reference profile) across
+ *          different models/endpoints for independent analysis.
+ * Phase 2: Spawn aggregator teammate with all reference outputs as
+ *          context to synthesize a unified result.
+ */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { runTeammate } from "@pi-maestro/teammate/src/runs/execution.ts";
+import type { SingleResult } from "@pi-maestro/teammate/src/shared/types.ts";
+
+export interface MoaParams {
+  prompts?: string[];
+  preset?: string;
+  maxTurns?: number;
+  model?: string;
+  cwd?: string;
+}
+
+interface ReferenceOutput {
+  model: string;
+  content: string;
+  exitCode: number;
+  durationMs: number;
+}
+
+/**
+ * Get available models from registered providers.
+ * Falls back to a default set if provider registry is not available.
+ */
+function getAvailableModels(preset?: string): string[] {
+  // Default models for MOA — the provider registry will override these
+  // when fully connected. For now, use a reasonable default set.
+  return [
+    "anthropic/claude-sonnet-4",
+    "google/gemini-2.5-pro",
+    "openai/gpt-4.1",
+  ];
+}
+
+/**
+ * Execute MOA action: parallel reference analysis + aggregator synthesis.
+ */
+export async function executeMoa(
+  params: MoaParams,
+  signal: AbortSignal,
+  ctx: ExtensionContext,
+): Promise<AgentToolResult> {
+  const prompts = params.prompts ?? [];
+  const primaryPrompt = prompts[0];
+
+  if (!primaryPrompt) {
+    return {
+      content: [
+        { type: "text", text: "No prompts provided for MOA action." },
+      ],
+      isError: true,
+    };
+  }
+
+  const models = getAvailableModels(params.preset);
+
+  // Phase 1: Spawn parallel reference agents across different models
+  const referenceOutputs: ReferenceOutput[] = [];
+  const referencePromises: Promise<void>[] = [];
+
+  for (const model of models) {
+    if (signal.aborted) break;
+
+    const promise = (async () => {
+      try {
+        const result = await runTeammate(
+          {
+            agent: "reference",
+            task: primaryPrompt,
+            model,
+            cwd: params.cwd,
+            reply_to: "caller",
+            lifecycle: "ephemeral",
+          },
+          {
+            baseCwd: ctx.cwd,
+            signal,
+          },
+        );
+
+        const lastMessage =
+          result.messages[result.messages.length - 1]?.content ?? "(no output)";
+
+        referenceOutputs.push({
+          model: result.model,
+          content: lastMessage,
+          exitCode: result.exitCode,
+          durationMs: result.durationMs,
+        });
+      } catch (error) {
+        referenceOutputs.push({
+          model,
+          content: `Error: ${error instanceof Error ? error.message : String(error)}`,
+          exitCode: 1,
+          durationMs: 0,
+        });
+      }
+    })();
+
+    referencePromises.push(promise);
+  }
+
+  // Wait for all reference agents
+  await Promise.allSettled(referencePromises);
+
+  if (signal.aborted) {
+    return {
+      content: [{ type: "text", text: "MOA operation was aborted." }],
+      isError: true,
+    };
+  }
+
+  const successfulOutputs = referenceOutputs.filter((r) => r.exitCode === 0);
+
+  if (successfulOutputs.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `All reference agents failed.\n\n${referenceOutputs.map((r) => `${r.model}: ${r.content}`).join("\n\n")}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  // Phase 2: Aggregator synthesizes all reference outputs
+  const aggregationPrompt = buildAggregationPrompt(
+    primaryPrompt,
+    successfulOutputs,
+  );
+
+  try {
+    const aggregatorResult = await runTeammate(
+      {
+        agent: "aggregator",
+        task: aggregationPrompt,
+        model: params.model,
+        cwd: params.cwd,
+        reply_to: "caller",
+        lifecycle: "ephemeral",
+      },
+      {
+        baseCwd: ctx.cwd,
+        signal,
+      },
+    );
+
+    const lastMessage =
+      aggregatorResult.messages[aggregatorResult.messages.length - 1]
+        ?.content ?? "(no output)";
+
+    return {
+      content: [{ type: "text", text: lastMessage }],
+      isError: aggregatorResult.exitCode !== 0,
+    };
+  } catch (error) {
+    // Fallback: return raw reference outputs if aggregation fails
+    const fallbackOutput = successfulOutputs
+      .map((r) => `## ${r.model}\n\n${r.content}`)
+      .join("\n\n---\n\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Aggregation failed, returning raw reference outputs:\n\n${fallbackOutput}`,
+        },
+      ],
+      isError: false,
+    };
+  }
+}
+
+function buildAggregationPrompt(
+  originalPrompt: string,
+  referenceOutputs: ReferenceOutput[],
+): string {
+  const referenceSections = referenceOutputs
+    .map(
+      (r, i) =>
+        `### Reference ${i + 1} (${r.model})\n\n${r.content}`,
+    )
+    .join("\n\n---\n\n");
+
+  return `You are synthesizing multiple independent analyses into a unified, high-quality response.
+
+## Original Question/Task
+
+${originalPrompt}
+
+## Independent Reference Analyses
+
+${referenceSections}
+
+## Your Task
+
+Synthesize these reference analyses into a single, comprehensive response:
+1. Identify areas of consensus across references
+2. Note any conflicts or divergent perspectives
+3. Produce a unified analysis that incorporates the strongest points from each reference
+4. Where references disagree, evaluate the evidence and make a reasoned judgment
+5. Ensure the final output is coherent, well-structured, and directly addresses the original question`;
+}

package/src/tools/status.ts

@@ -0,0 +1,99 @@
+/**
+ * maestro-status auxiliary tool.
+ *
+ * Inspects active and completed maestro runs.
+ * Supports fleet view (overview) and transcript view (tail logs).
+ */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+
+interface MaestroState {
+  activeRuns: Map<
+    string,
+    {
+      action: string;
+      startedAt: number;
+      correlationId: string;
+    }
+  >;
+}
+
+interface StatusParams {
+  id?: string;
+  view?: "fleet" | "transcript";
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}m${remainingSeconds}s`;
+}
+
+/**
+ * Get status of maestro runs.
+ */
+export async function executeMaestroStatus(
+  params: StatusParams,
+  state: MaestroState,
+): Promise<AgentToolResult> {
+  const now = Date.now();
+
+  // Specific run by ID
+  if (params.id) {
+    const run = state.activeRuns.get(params.id);
+    if (!run) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Run "${params.id}" not found. It may have completed.`,
+          },
+        ],
+      };
+    }
+
+    const elapsed = formatDuration(now - run.startedAt);
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            `## Run: ${params.id}`,
+            `- **Action**: ${run.action}`,
+            `- **Status**: running`,
+            `- **Elapsed**: ${elapsed}`,
+            `- **Correlation ID**: ${run.correlationId}`,
+          ].join("\n"),
+        },
+      ],
+    };
+  }
+
+  // Fleet view (default)
+  if (state.activeRuns.size === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No active maestro runs.",
+        },
+      ],
+    };
+  }
+
+  const lines: string[] = ["## Maestro Fleet Status", ""];
+
+  for (const [id, run] of state.activeRuns) {
+    const elapsed = formatDuration(now - run.startedAt);
+    lines.push(`- **${id}**: ${run.action} (${elapsed})`);
+  }
+
+  lines.push("", `Total: ${state.activeRuns.size} active run(s)`);
+
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+  };
+}

package/src/tools/wait.ts

@@ -0,0 +1,166 @@
+/**
+ * maestro-wait auxiliary tool.
+ *
+ * Blocks until background maestro runs finish.
+ * Supports waiting for a specific run, the first to finish, or all runs.
+ */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+
+interface MaestroState {
+  activeRuns: Map<
+    string,
+    {
+      action: string;
+      startedAt: number;
+      correlationId: string;
+    }
+  >;
+}
+
+interface WaitParams {
+  id?: string;
+  all?: boolean;
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const POLL_INTERVAL_MS = 1000;
+
+/**
+ * Wait for active maestro runs to complete.
+ *
+ * Uses a poll-based approach to check run completion status.
+ * Resolves when the target run(s) finish or timeout is reached.
+ */
+export async function executeMaestroWait(
+  params: WaitParams,
+  signal: AbortSignal,
+  state: MaestroState,
+): Promise<AgentToolResult> {
+  const timeout = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const startTime = Date.now();
+
+  // No active runs
+  if (state.activeRuns.size === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No active maestro runs to wait for.",
+        },
+      ],
+    };
+  }
+
+  // If waiting for specific ID
+  if (params.id) {
+    const run = state.activeRuns.get(params.id);
+    if (!run) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Run "${params.id}" not found in active runs.`,
+          },
+        ],
+      };
+    }
+  }
+
+  // Poll until completion or timeout
+  return new Promise<AgentToolResult>((resolve) => {
+    const checkCompletion = () => {
+      // Check abort
+      if (signal.aborted) {
+        resolve({
+          content: [
+            {
+              type: "text",
+              text: "Wait was aborted.",
+            },
+          ],
+        });
+        return;
+      }
+
+      // Check timeout
+      if (Date.now() - startTime >= timeout) {
+        const remaining = Array.from(state.activeRuns.entries())
+          .map(([id, r]) => `  - ${id}: ${r.action} (running ${Math.floor((Date.now() - r.startedAt) / 1000)}s)`)
+          .join("\n");
+
+        resolve({
+          content: [
+            {
+              type: "text",
+              text: `Wait timed out after ${timeout}ms. Active runs:\n${remaining}`,
+            },
+          ],
+        });
+        return;
+      }
+
+      // Check if target run(s) finished
+      if (params.id) {
+        if (!state.activeRuns.has(params.id)) {
+          resolve({
+            content: [
+              {
+                type: "text",
+                text: `Run "${params.id}" completed.`,
+              },
+            ],
+          });
+          return;
+        }
+      } else if (params.all) {
+        if (state.activeRuns.size === 0) {
+          resolve({
+            content: [
+              {
+                type: "text",
+                text: "All maestro runs completed.",
+              },
+            ],
+          });
+          return;
+        }
+      } else {
+        // Wait for first — check if any have completed since we started
+        // (This simple implementation checks if the count decreased)
+        // A full implementation would use event subscriptions
+        if (state.activeRuns.size === 0) {
+          resolve({
+            content: [
+              {
+                type: "text",
+                text: "A maestro run completed.",
+              },
+            ],
+          });
+          return;
+        }
+      }
+
+      // Keep polling
+      setTimeout(checkCompletion, POLL_INTERVAL_MS);
+    };
+
+    // Start polling
+    checkCompletion();
+
+    // Handle abort signal
+    signal.addEventListener(
+      "abort",
+      () => {
+        resolve({
+          content: [
+            { type: "text", text: "Wait was aborted." },
+          ],
+        });
+      },
+      { once: true },
+    );
+  });
+}