pi-maestro-flow 0.2.0

package/src/extension/index.ts

@@ -0,0 +1,222 @@
+/**
+ * Maestro Agent Extension Entry Point
+ *
+ * Registers three tools:
+ *   - maestro: Main tool with action-based dispatch (explore, delegate, moa)
+ *   - maestro-wait: Block until background maestro runs finish
+ *   - maestro-status: Inspect active/completed runs
+ *
+ * Also registers dynamic LLM providers from cli-tools.json at startup.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { Text } from "@earendil-works/pi-tui";
+import {
+  MaestroParams,
+  MaestroWaitParams,
+  MaestroStatusParams,
+} from "./schemas.ts";
+import { executeExplore, type ExploreParams } from "../tools/explore.ts";
+import { executeDelegate, type DelegateParams } from "../tools/delegate.ts";
+import { executeMoa, type MoaParams } from "../tools/moa.ts";
+import { executeMaestroWait } from "../tools/wait.ts";
+import { executeMaestroStatus } from "../tools/status.ts";
+import { registerMaestroProviders } from "../providers/provider-registry.ts";
+
+interface MaestroState {
+  baseCwd: string;
+  activeRuns: Map<
+    string,
+    {
+      action: string;
+      startedAt: number;
+      correlationId: string;
+    }
+  >;
+}
+
+export default function registerMaestroExtension(pi: ExtensionAPI): void {
+  const state: MaestroState = {
+    baseCwd: "",
+    activeRuns: new Map(),
+  };
+
+  // Register dynamic providers from cli-tools.json
+  try {
+    registerMaestroProviders(pi);
+  } catch (error) {
+    // Provider registration failures should not block extension load
+    console.error(
+      `[maestro] Provider registration warning: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  // === Main Tool: maestro ===
+  const maestroTool: ToolDefinition<typeof MaestroParams> = {
+    name: "maestro",
+    label: "Maestro",
+    description: `Maestro flow command tool with three actions:
+
+- **explore**: Parallel code search via teammate agents. Each prompt spawns an independent search agent.
+  { action: "explore", prompts: ["FIND: auth middleware\\nSCOPE: src/"], model: "..." }
+
+- **delegate**: Delegate a task to a specific model/provider for analysis or implementation.
+  { action: "delegate", prompt: "Analyze the auth flow", tool: "gemini", mode: "analysis" }
+
+- **moa**: Mixture-of-Agents — parallel reference analysis across models, then aggregator synthesis.
+  { action: "moa", prompts: ["Compare auth strategies"], preset: "deep" }`,
+
+    parameters: MaestroParams,
+
+    async execute(
+      id: string,
+      params: Record<string, unknown>,
+      signal: AbortSignal,
+      onUpdate:
+        | ((result: AgentToolResult) => void)
+        | undefined,
+      ctx: ExtensionContext,
+    ): Promise<AgentToolResult> {
+      const action = params.action as string;
+
+      // Track run
+      state.activeRuns.set(id, {
+        action,
+        startedAt: Date.now(),
+        correlationId: id,
+      });
+
+      try {
+        switch (action) {
+          case "explore":
+            return await executeExplore(
+              params as unknown as ExploreParams,
+              signal,
+              ctx,
+            );
+
+          case "delegate":
+            return await executeDelegate(
+              params as unknown as DelegateParams,
+              signal,
+              ctx,
+            );
+
+          case "moa":
+            return await executeMoa(
+              params as unknown as MoaParams,
+              signal,
+              ctx,
+            );
+
+          default:
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Unknown action "${action}". Valid actions: explore, delegate, moa`,
+                },
+              ],
+              isError: true,
+            };
+        }
+      } finally {
+        state.activeRuns.delete(id);
+      }
+    },
+
+    renderCall(args, theme) {
+      const action = (args.action as string) ?? "?";
+      const asyncLabel =
+        args.async === true ? theme.fg("warning", " [async]") : "";
+
+      let detail = "";
+      if (action === "explore") {
+        const prompts = args.prompts as string[] | undefined;
+        detail = prompts
+          ? ` (${prompts.length} prompt${prompts.length !== 1 ? "s" : ""})`
+          : "";
+      } else if (action === "delegate") {
+        const tool = (args.tool as string) ?? "";
+        detail = tool ? ` ${theme.fg("accent", tool)}` : "";
+      } else if (action === "moa") {
+        detail = "";
+      }
+
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("maestro "))}${action}${detail}${asyncLabel}`,
+        0,
+        0,
+      );
+    },
+  };
+
+  pi.registerTool(maestroTool);
+
+  // === Auxiliary Tool: maestro-wait ===
+  const waitTool: ToolDefinition<typeof MaestroWaitParams> = {
+    name: "maestro-wait",
+    label: "Maestro Wait",
+    description: `Block until background (async) maestro runs finish.
+
+- { } — wait for first active run to finish (default)
+- { all: true } — wait for all active runs to finish
+- { id: "..." } — wait for a specific run
+- { timeoutMs: 600000 } — timeout after N ms (runs continue regardless)`,
+
+    parameters: MaestroWaitParams,
+
+    async execute(
+      _id: string,
+      params: Record<string, unknown>,
+      signal: AbortSignal,
+    ): Promise<AgentToolResult> {
+      return executeMaestroWait(
+        params as { id?: string; all?: boolean; timeoutMs?: number },
+        signal,
+        state,
+      );
+    },
+  };
+
+  pi.registerTool(waitTool);
+
+  // === Auxiliary Tool: maestro-status ===
+  const statusTool: ToolDefinition<typeof MaestroStatusParams> = {
+    name: "maestro-status",
+    label: "Maestro Status",
+    description: `Inspect maestro run status.
+
+- { } — fleet overview of all active runs
+- { id: "..." } — details for a specific run
+- { view: "transcript" } — tail the latest run transcript`,
+
+    parameters: MaestroStatusParams,
+
+    async execute(
+      _id: string,
+      params: Record<string, unknown>,
+    ): Promise<AgentToolResult> {
+      return executeMaestroStatus(
+        params as { id?: string; view?: "fleet" | "transcript" },
+        state,
+      );
+    },
+  };
+
+  pi.registerTool(statusTool);
+
+  // Session lifecycle
+  pi.on("session_start", (_event, ctx) => {
+    state.baseCwd = ctx.cwd;
+  });
+
+  pi.on("session_shutdown", () => {
+    state.activeRuns.clear();
+  });
+}

package/src/extension/schemas.ts

@@ -0,0 +1,131 @@
+/**
+ * TypeBox schemas for the maestro tool with action-based dispatch.
+ *
+ * Main tool: maestro (action: explore | delegate | moa)
+ * Auxiliary tools: maestro-wait, maestro-status
+ */
+
+import { Type } from "typebox";
+
+function StringEnum<T extends string[]>(values: [...T]) {
+  return Type.Unsafe<T[number]>({
+    type: "string",
+    enum: values,
+  });
+}
+
+export const MaestroParams = Type.Object({
+  // === Action Dispatch ===
+  action: StringEnum(["explore", "delegate", "moa"]),
+
+  // === Explore Action Fields ===
+  prompts: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Search prompts for explore action (each prompt = one parallel agent)",
+    }),
+  ),
+  endpoint: Type.Optional(
+    Type.String({
+      description: "Specific model/endpoint for explore agents",
+    }),
+  ),
+  all: Type.Optional(
+    Type.Boolean({
+      description: "Fan out each prompt to all registered endpoints",
+    }),
+  ),
+  maxTurns: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Maximum agent turns per exploration job",
+    }),
+  ),
+  concurrency: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Maximum concurrent explore agents (default: 4)",
+    }),
+  ),
+
+  // === Delegate Action Fields ===
+  prompt: Type.Optional(
+    Type.String({
+      description: "Task prompt for delegate action",
+    }),
+  ),
+  tool: Type.Optional(
+    Type.String({
+      description:
+        "Target tool/provider for delegate (e.g., 'gemini', 'claude', 'codex')",
+    }),
+  ),
+  mode: Type.Optional(
+    StringEnum(["analysis", "write"]),
+  ),
+  model: Type.Optional(
+    Type.String({
+      description: "Model override for delegate or explore",
+    }),
+  ),
+  rule: Type.Optional(
+    Type.String({
+      description: "Protocol + prompt template for delegate",
+    }),
+  ),
+
+  // === MOA Action Fields ===
+  preset: Type.Optional(
+    Type.String({
+      description: "MOA preset configuration name",
+    }),
+  ),
+
+  // === Common Fields ===
+  cwd: Type.Optional(
+    Type.String({
+      description: "Working directory for the operation",
+    }),
+  ),
+  async: Type.Optional(
+    Type.Boolean({
+      description: "Run in background (default: false)",
+    }),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Timeout in milliseconds",
+    }),
+  ),
+});
+
+export const MaestroWaitParams = Type.Object({
+  id: Type.Optional(
+    Type.String({
+      description: "Specific run ID to wait for (omit to wait for any)",
+    }),
+  ),
+  all: Type.Optional(
+    Type.Boolean({
+      description: "Wait for all active runs (default: wait for first)",
+    }),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Timeout in milliseconds (default: 1800000 / 30 min)",
+    }),
+  ),
+});
+
+export const MaestroStatusParams = Type.Object({
+  id: Type.Optional(
+    Type.String({
+      description: "Specific run ID to inspect",
+    }),
+  ),
+  view: Type.Optional(
+    StringEnum(["fleet", "transcript"]),
+  ),
+});

package/src/providers/cli-tools-loader.ts

@@ -0,0 +1,74 @@
+/**
+ * Load and parse ~/.maestro/cli-tools.json configuration.
+ *
+ * Maps each enabled CLI tool to its provider configuration for
+ * dynamic pi provider registration.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface CliToolConfig {
+  enabled: boolean;
+  primaryModel: string;
+  tags: string[];
+  type: string;
+  settingsFile?: string;
+  reasoningEffort?: string;
+}
+
+export interface CliToolsConfig {
+  version: string;
+  tools: Record<string, CliToolConfig>;
+  roles: Record<string, unknown>;
+  proxy?: {
+    enabled: boolean;
+    httpProxy?: string;
+    noProxy?: string;
+  };
+}
+
+const CLI_TOOLS_PATH = path.join(os.homedir(), ".maestro", "cli-tools.json");
+
+/**
+ * Load cli-tools.json from the default location.
+ * Returns null if the file doesn't exist or can't be parsed.
+ */
+export function loadCliToolsConfig(
+  configPath?: string,
+): CliToolsConfig | null {
+  const filePath = configPath ?? CLI_TOOLS_PATH;
+
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(content) as unknown;
+
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+
+    const config = parsed as Record<string, unknown>;
+
+    // Validate basic structure
+    if (!config.tools || typeof config.tools !== "object") {
+      return null;
+    }
+
+    return parsed as CliToolsConfig;
+  } catch {
+    // File missing or invalid — not an error, providers are optional
+    return null;
+  }
+}
+
+/**
+ * Get all enabled tools from the config.
+ */
+export function getEnabledTools(
+  config: CliToolsConfig,
+): Array<{ name: string; config: CliToolConfig }> {
+  return Object.entries(config.tools)
+    .filter(([_, toolConfig]) => toolConfig.enabled)
+    .map(([name, toolConfig]) => ({ name, config: toolConfig }));
+}

package/src/providers/provider-registry.ts

@@ -0,0 +1,130 @@
+/**
+ * Dynamic LLM provider registration from cli-tools.json.
+ *
+ * At extension startup, reads cli-tools.json and registers each enabled
+ * tool as a pi provider via pi.registerProvider(). Uses pi CredentialStore
+ * for authentication ($API_KEY env var pattern).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  loadCliToolsConfig,
+  getEnabledTools,
+  type CliToolConfig,
+} from "./cli-tools-loader.ts";
+
+/**
+ * Map a CLI tool type to its pi provider configuration.
+ */
+function mapToolToProviderConfig(
+  name: string,
+  config: CliToolConfig,
+): {
+  apiType: string;
+  envVar: string;
+  baseUrl?: string;
+} {
+  // Map tool names/types to API configurations
+  switch (name) {
+    case "claude":
+      return {
+        apiType: "anthropic-messages",
+        envVar: "ANTHROPIC_API_KEY",
+      };
+
+    case "gemini":
+      return {
+        apiType: "google-genai",
+        envVar: "GOOGLE_API_KEY",
+      };
+
+    case "codex":
+      return {
+        apiType: "openai-completions",
+        envVar: "OPENAI_API_KEY",
+      };
+
+    case "opencode":
+      return {
+        apiType: "openai-compatible",
+        envVar: "OPENAI_API_KEY",
+        baseUrl: "https://api.openai.com/v1",
+      };
+
+    case "agy":
+      return {
+        apiType: "openai-compatible",
+        envVar: "AGY_API_KEY",
+      };
+
+    case "api-explore":
+      return {
+        apiType: "openai-compatible",
+        envVar: "API_EXPLORE_KEY",
+      };
+
+    default:
+      // Generic OpenAI-compatible fallback
+      return {
+        apiType: "openai-compatible",
+        envVar: `${name.toUpperCase()}_API_KEY`,
+      };
+  }
+}
+
+/**
+ * Register all enabled CLI tools as pi providers.
+ *
+ * Reads cli-tools.json, maps each enabled tool to a provider config,
+ * and calls pi.registerProvider() for each.
+ */
+export function registerMaestroProviders(pi: ExtensionAPI): void {
+  const cliConfig = loadCliToolsConfig();
+  if (!cliConfig) {
+    // No cli-tools.json — silently skip provider registration
+    return;
+  }
+
+  const enabledTools = getEnabledTools(cliConfig);
+
+  for (const { name, config: toolConfig } of enabledTools) {
+    if (!toolConfig.primaryModel) {
+      // Skip tools without a primary model (e.g., opencode with empty model)
+      continue;
+    }
+
+    const providerMapping = mapToolToProviderConfig(name, toolConfig);
+
+    try {
+      // Register the provider with pi
+      // Note: pi.registerProvider() is the ExtensionAPI method for adding
+      // LLM providers dynamically. The exact signature depends on the
+      // pi-agent-core version.
+      if (typeof pi.registerProvider === "function") {
+        pi.registerProvider(name, {
+          apiType: providerMapping.apiType,
+          apiKey: `$${providerMapping.envVar}`,
+          ...(providerMapping.baseUrl
+            ? { baseUrl: providerMapping.baseUrl }
+            : {}),
+          models: [
+            {
+              id: toolConfig.primaryModel,
+              name: toolConfig.primaryModel,
+              reasoning: false,
+              input: ["text"],
+            },
+          ],
+          ...(cliConfig.proxy?.enabled && cliConfig.proxy.httpProxy
+            ? { proxy: cliConfig.proxy.httpProxy }
+            : {}),
+        });
+      }
+    } catch (error) {
+      // Individual provider registration failures should not block others
+      console.error(
+        `[maestro] Failed to register provider "${name}": ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+}

package/src/tools/delegate.ts

@@ -0,0 +1,85 @@
+/**
+ * Delegate action — task delegation to a specific model/provider.
+ *
+ * Spawns a single teammate agent (delegate profile) with the specified
+ * model override from registered providers, passing the prompt as task
+ * with analysis or write mode.
+ */
+
+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";
+
+export interface DelegateParams {
+  prompt?: string;
+  tool?: string;
+  mode?: "analysis" | "write";
+  model?: string;
+  rule?: string;
+  cwd?: string;
+}
+
+/**
+ * Execute delegate action: spawn a teammate with specified model override.
+ */
+export async function executeDelegate(
+  params: DelegateParams,
+  signal: AbortSignal,
+  ctx: ExtensionContext,
+): Promise<AgentToolResult> {
+  if (!params.prompt) {
+    return {
+      content: [
+        { type: "text", text: "No prompt provided for delegate action." },
+      ],
+      isError: true,
+    };
+  }
+
+  // Build task with mode context
+  let task = params.prompt;
+  if (params.mode) {
+    task = `MODE: ${params.mode}\n\n${task}`;
+  }
+  if (params.rule) {
+    task = `RULE: ${params.rule}\n\n${task}`;
+  }
+
+  // Resolve model from tool name or explicit model
+  const model = params.model ?? params.tool;
+
+  try {
+    const result = await runTeammate(
+      {
+        agent: "delegate",
+        task,
+        model,
+        cwd: params.cwd,
+        reply_to: "caller",
+        lifecycle: "ephemeral",
+      },
+      {
+        baseCwd: ctx.cwd,
+        signal,
+      },
+    );
+
+    const lastMessage =
+      result.messages[result.messages.length - 1]?.content ?? "(no output)";
+
+    return {
+      content: [{ type: "text", text: lastMessage }],
+      isError: result.exitCode !== 0,
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Delegate failed: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}