@bugmole/cli 0.4.0

package/src/runtime/canonical-flow.test.ts

@@ -0,0 +1,52 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { canonicalFlows, emptyJourneyGraph, validateJourneyGraph } from "./journey-graph.js";
+
+test("only stable canonical flows project into the application graph", () => {
+  const graph = emptyJourneyGraph("demo");
+  graph.journeys = [
+    {
+      id: "draft-flow",
+      name: "Draft",
+      actor: "user",
+      nodeIds: [],
+      edgeIds: [],
+      revision: 1,
+      status: "draft",
+      sourceOfTruth: "canonical_flow",
+      stability: "stabilizing",
+      linkedToGraph: false,
+    },
+    {
+      id: "stable-flow",
+      name: "Stable",
+      actor: "user",
+      nodeIds: [],
+      edgeIds: [],
+      revision: 2,
+      status: "published",
+      sourceOfTruth: "canonical_flow",
+      stability: "stable",
+      linkedToGraph: true,
+    },
+  ];
+  assert.deepEqual(canonicalFlows(graph).map((journey) => journey.id), ["stable-flow"]);
+  assert.deepEqual(validateJourneyGraph(graph), { valid: true, errors: [] });
+});
+
+test("rejects a flow linked to the graph before stabilization", () => {
+  const graph = emptyJourneyGraph("demo");
+  graph.journeys = [{
+    id: "unstable-flow",
+    name: "Unstable",
+    actor: "user",
+    nodeIds: [],
+    edgeIds: [],
+    revision: 1,
+    status: "published",
+    sourceOfTruth: "canonical_flow",
+    stability: "stabilizing",
+    linkedToGraph: true,
+  }];
+  assert.equal(validateJourneyGraph(graph).valid, false);
+});

package/src/runtime/config-validate.ts

@@ -0,0 +1,185 @@
+/**
+ * Config validation against governor policy rules.
+ * Validates environment classification, watermark rules, and safety constraints.
+ */
+
+import { defaultTargets } from "./browser-matrix.js";
+
+type Environment = "SANDBOX" | "TEST" | "STAGING" | "PRODUCTION";
+
+interface Config {
+  runtime: {
+    env: string;
+    tenant: string;
+    artifacts_dir: string;
+    spec_dir: string;
+  };
+  llm: {
+    provider: string;
+    api_key: string;
+    model: string;
+    base_url?: string;
+  };
+  mcp?: {
+    enabled: boolean;
+    host: string;
+    port: number;
+  };
+  execution: {
+    driver?: string;
+    maestro?: {
+      command?: string;
+      timeout_ms?: number;
+    };
+    playwright: {
+      base_url: string;
+      headless: boolean;
+      browsers?: unknown;
+      devices?: unknown;
+      parallel?: unknown;
+    };
+    retries: {
+      step: number;
+      journey: number;
+    };
+  };
+  storage?: {
+    provider?: string;
+    [provider: string]: unknown;
+  };
+}
+
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  environment: Environment;
+}
+
+/**
+ * Classify environment from config string.
+ * Defaults to STAGING if uncertain (safest default).
+ */
+function classifyEnvironment(envStr?: string): Environment {
+  const upper = envStr?.toUpperCase() ?? "";
+  if (upper === "SANDBOX" || upper === "SANDBOX") return "SANDBOX";
+  if (upper === "TEST") return "TEST";
+  if (upper === "STAGING") return "STAGING";
+  if (upper === "PRODUCTION" || upper === "PROD") return "PRODUCTION";
+  // Default to STAGING for safety (per governor policy)
+  return "STAGING";
+}
+
+/**
+ * Validate config against governor policy rules.
+ * See docs/governor-policy.md for complete rules.
+ */
+export function validateConfig(cfg: Config): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const env = classifyEnvironment(cfg.runtime.env);
+
+  // Required fields
+  if (!cfg.runtime?.env) {
+    errors.push("runtime.env is required");
+  }
+  if (!cfg.runtime?.artifacts_dir) {
+    errors.push("runtime.artifacts_dir is required");
+  }
+  if (!cfg.runtime?.spec_dir) {
+    errors.push("runtime.spec_dir is required");
+  }
+  if (!cfg.llm?.provider) {
+    errors.push("llm.provider is required");
+  }
+  if (!cfg.llm?.api_key) {
+    errors.push("llm.api_key is required (set LLM_API_KEY in .env)");
+  }
+  const driver = cfg.execution?.driver || "maestro";
+  if (!["maestro", "playwright", "simulation"].includes(driver)) {
+    warnings.push(`Execution driver "${driver}" is not recognized; configure a registered driver adapter`);
+  }
+  if (driver === "maestro" && cfg.execution?.maestro?.timeout_ms !== undefined &&
+      cfg.execution.maestro.timeout_ms <= 0) {
+    errors.push("execution.maestro.timeout_ms must be greater than zero");
+  }
+  // Fail at startup, not mid-run, when the browser/device matrix has a typo.
+  try {
+    defaultTargets(cfg);
+  } catch (error) {
+    errors.push(`execution.playwright: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const parallel = cfg.execution?.playwright?.parallel;
+  if (parallel !== undefined && !(Number.isInteger(parallel) && (parallel as number) > 0)) {
+    errors.push("execution.playwright.parallel must be a positive integer");
+  }
+  const storageProvider = cfg.storage?.provider;
+  const storageDetails =
+    storageProvider && typeof cfg.storage?.[storageProvider] === "object"
+      ? (cfg.storage[storageProvider] as { bucket?: string; account_id?: string })
+      : undefined;
+  if (storageProvider && !["local", "gcs", "s3", "r2"].includes(storageProvider)) {
+    errors.push(`storage.provider "${storageProvider}" is unsupported`);
+  }
+  if (storageProvider && storageProvider !== "local" && !storageDetails?.bucket) {
+    errors.push(`storage.${storageProvider}.bucket is required`);
+  }
+  if (storageProvider === "r2" && !storageDetails?.account_id && !process.env.R2_ACCOUNT_ID) {
+    warnings.push("Cloudflare R2 account_id is not configured; provide R2_ACCOUNT_ID at runtime");
+  }
+
+  // Environment classification warnings
+  const envStr = cfg.runtime.env?.toUpperCase() ?? "";
+  if (!["SANDBOX", "TEST", "STAGING", "PRODUCTION", "PROD"].includes(envStr)) {
+    warnings.push(
+      `Environment "${cfg.runtime.env}" not recognized, defaulting to STAGING (safest)`,
+    );
+  }
+
+  // Production environment warnings
+  if (env === "PRODUCTION") {
+    warnings.push("PRODUCTION environment detected. Destructive actions will be blocked.");
+  }
+
+  // Retry budget validation (per governor policy defaults)
+  if (cfg.execution?.retries?.step !== undefined) {
+    const stepRetries = cfg.execution.retries.step;
+    if (stepRetries < 0 || stepRetries > 5) {
+      warnings.push(`Step retry count (${stepRetries}) is outside recommended range (0-5)`);
+    }
+  }
+  if (cfg.execution?.retries?.journey !== undefined) {
+    const journeyRetries = cfg.execution.retries.journey;
+    if (journeyRetries < 0 || journeyRetries > 3) {
+      warnings.push(`Journey retry count (${journeyRetries}) is outside recommended range (0-3)`);
+    }
+  }
+
+  // Artifacts directory must be writable (check will happen at runtime)
+  // Spec directory must exist and be readable
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    environment: env,
+  };
+}
+
+/**
+ * Validate and throw if invalid.
+ * Use this before starting any runtime operations.
+ */
+export function validateConfigOrThrow(cfg: Config): Environment {
+  const result = validateConfig(cfg);
+  if (!result.valid) {
+    throw new Error(
+      `Config validation failed:\n${result.errors.map((e) => `  - ${e}`).join("\n")}`,
+    );
+  }
+  if (result.warnings.length > 0) {
+    console.warn("[Bugmole MCP] Config warnings:");
+    result.warnings.forEach((w) => console.warn(`  ⚠ ${w}`));
+  }
+  return result.environment;
+}

package/src/runtime/continuous-execution.ts

@@ -0,0 +1,291 @@
+/**
+ * Continuous execution loop for LLM agents
+ *
+ * This module provides a continuous execution loop that:
+ * 1. Sends a task to the LLM
+ * 2. Waits for commit response
+ * 3. Checks for next_steps in the response
+ * 4. If next_steps exist, automatically continues with follow-up prompts
+ * 5. Repeats until task is complete (no more next_steps)
+ *
+ * Works with any LLM provider (OpenAI, Anthropic, Cursor, Ollama)
+ */
+
+import { llmStructured, type LLMOptions, type LLMResponse } from "./llm.js";
+import { cursorLLMStructured, type CursorLLMOptions } from "./cursor-llm.js";
+import type { CursorDriverResponse } from "./cursor-driver.js";
+
+/**
+ * Options for continuous execution
+ */
+export interface ContinuousExecutionOptions extends LLMOptions {
+  /**
+   * Maximum number of iterations (prevents infinite loops)
+   * @default 100
+   */
+  maxIterations?: number;
+
+  /**
+   * Delay between iterations in ms
+   * @default 2000
+   */
+  iterationDelay?: number;
+
+  /**
+   * Whether to use Cursor LLM (true) or standard LLM (false)
+   * @default true
+   */
+  useCursor?: boolean;
+}
+
+/**
+ * Result of continuous execution
+ */
+export interface ContinuousExecutionResult {
+  /**
+   * All responses from the execution loop
+   */
+  responses: Array<LLMResponse | CursorDriverResponse>;
+
+  /**
+   * Final response
+   */
+  finalResponse: LLMResponse | CursorDriverResponse;
+
+  /**
+   * Total iterations
+   */
+  iterations: number;
+
+  /**
+   * Whether execution completed successfully
+   */
+  success: boolean;
+
+  /**
+   * Error if execution failed
+   */
+  error?: string;
+}
+
+/**
+ * Extracts next steps from a response
+ */
+function extractNextSteps(response: LLMResponse | CursorDriverResponse): string[] | undefined {
+  if ("payload" in response && response.payload) {
+    // CursorDriverResponse
+    const cursorResponse = response as CursorDriverResponse;
+    return cursorResponse.payload?.next_steps;
+  } else {
+    // LLMResponse - check metadata
+    const llmResponse = response as LLMResponse;
+    return llmResponse.metadata?.next_steps as string[] | undefined;
+  }
+}
+
+/**
+ * Generates a follow-up prompt from next steps with enhanced state summarization
+ * This provides context about what was done previously so the agent can continue efficiently
+ */
+function generateFollowUpPrompt(
+  initialTask: string,
+  previousResponses: Array<LLMResponse | CursorDriverResponse>,
+  nextSteps: string[],
+): string {
+  // Build a concise summary of all previous work
+  const summaries: string[] = [];
+  const actions: string[] = [];
+  const artifacts: string[] = [];
+  let lastStatus = "ok";
+
+  previousResponses.forEach((response, index) => {
+    if ("payload" in response && response.payload) {
+      const cursorResponse = response as CursorDriverResponse;
+      const payload = cursorResponse.payload;
+      if (payload) {
+        summaries.push(`Iteration ${index + 1}: ${payload.summary}`);
+        lastStatus = payload.status || "ok";
+
+        // Collect key actions
+        if (payload.actions && payload.actions.length > 0) {
+          payload.actions.forEach((action) => {
+            actions.push(`- ${action.type}: ${action.target}`);
+          });
+        }
+
+        // Collect artifacts
+        if (payload.artifacts && payload.artifacts.length > 0) {
+          payload.artifacts.forEach((artifact) => {
+            artifacts.push(`- ${artifact.type}: ${artifact.content.substring(0, 100)}...`);
+          });
+        }
+      }
+    } else {
+      const llmResponse = response as LLMResponse;
+      summaries.push(`Iteration ${index + 1}: ${llmResponse.text.substring(0, 200)}...`);
+    }
+  });
+
+  // Build the prompt with concise context
+  let prompt = `# Continuing Task (Iteration ${previousResponses.length + 1})
+
+## Original Task
+${initialTask}
+
+## Previous Work Summary
+${summaries.length > 0 ? summaries.join("\n") : "No previous iterations"}
+
+`;
+
+  // Include actions if any
+  if (actions.length > 0) {
+    prompt += `## Actions Taken
+${actions.slice(-10).join("\n")}  // Showing last 10 actions
+
+`;
+  }
+
+  // Include artifacts if any
+  if (artifacts.length > 0) {
+    prompt += `## Artifacts Created
+${artifacts.slice(-5).join("\n")}  // Showing last 5 artifacts
+
+`;
+  }
+
+  // Include last status
+  if (lastStatus === "error") {
+    prompt += `⚠️ **Note:** Previous iteration had an error status. Please review and continue carefully.\n\n`;
+  }
+
+  prompt += `## Next Steps (Continue Here)
+${nextSteps.map((step, i) => `${i + 1}. ${step}`).join("\n")}
+
+## Instructions
+- Continue from where you left off - you have full context of previous work
+- Complete the next steps listed above
+- Use MCP tools as needed (bugmole_explore, bugmole_journey_next, bugmole_record_discovery, bugmole_plan, bugmole_run, bugmole_write_spec, etc.)
+- After every exploration or discovery action, call bugmole_journey_get and bugmole_journey_next for the selected flow.
+- If bugmole_journey_next returns an actionable task, perform it, record the resulting evidence, and continue the loop.
+- Stop the exploration loop only when bugmole_journey_next returns exhausted or an explicit blocked reason; do not replace an actionable flow task with a generic plan.
+- If there are more steps after completing these, include them in your \`next_steps\` field
+- If this is the final step, do NOT include \`next_steps\` in your response
+
+Continue with the next steps now.`;
+
+  return prompt;
+}
+
+/**
+ * Executes a task continuously, following next_steps until completion
+ *
+ * @param initialTask - The initial task to start with
+ * @param options - Execution options
+ * @returns All responses and final result
+ *
+ * @example
+ * ```typescript
+ * const result = await executeContinuously(
+ *   'Investigate the project and set up testing',
+ *   { useCursor: true, maxIterations: 5 }
+ * );
+ *
+ * console.log(`Completed in ${result.iterations} iterations`);
+ * console.log('Final response:', result.finalResponse);
+ * ```
+ */
+export async function executeContinuously(
+  initialTask: string,
+  options: ContinuousExecutionOptions = {},
+): Promise<ContinuousExecutionResult> {
+  const { maxIterations = 100, iterationDelay = 2000, useCursor = true, ...llmOptions } = options;
+
+  const responses: Array<LLMResponse | CursorDriverResponse> = [];
+  let currentTask = initialTask;
+  let iteration = 0;
+
+  console.log(`[Continuous Execution] Starting with max ${maxIterations} iterations\n`);
+
+  while (iteration < maxIterations) {
+    iteration++;
+    console.log(`[Continuous Execution] Iteration ${iteration}/${maxIterations}`);
+
+    try {
+      // Execute current task
+      let response: LLMResponse | CursorDriverResponse;
+
+      if (useCursor) {
+        const cursorResponse = await cursorLLMStructured(
+          currentTask,
+          llmOptions as CursorLLMOptions,
+        );
+        response = cursorResponse;
+      } else {
+        response = await llmStructured(currentTask, llmOptions);
+      }
+
+      responses.push(response);
+
+      // Check if successful
+      if ("success" in response && !response.success) {
+        return {
+          responses,
+          finalResponse: response,
+          iterations: iteration,
+          success: false,
+          error: response.error || "Execution failed",
+        };
+      }
+
+      // Check for next steps
+      let nextSteps = extractNextSteps(response);
+
+      // Debug: log what we extracted
+      if (nextSteps && nextSteps.length > 0) {
+        console.log(`[Continuous Execution] Found ${nextSteps.length} next step(s):`, nextSteps);
+      } else {
+        console.log(
+          `[Continuous Execution] No next steps found (value: ${JSON.stringify(nextSteps)})`,
+        );
+      }
+
+      if (!nextSteps || nextSteps.length === 0) {
+        // No more steps, we're done!
+        console.log(`[Continuous Execution] Task completed in ${iteration} iteration(s)\n`);
+        return {
+          responses,
+          finalResponse: response,
+          iterations: iteration,
+          success: true,
+        };
+      }
+
+      // Generate follow-up prompt
+      console.log(`[Continuous Execution] Found ${nextSteps.length} next step(s), continuing...\n`);
+      currentTask = generateFollowUpPrompt(initialTask, responses, nextSteps);
+
+      // Wait before next iteration
+      if (iteration < maxIterations) {
+        await new Promise((resolve) => setTimeout(resolve, iterationDelay));
+      }
+    } catch (error: any) {
+      return {
+        responses,
+        finalResponse: responses[responses.length - 1] || ({} as any),
+        iterations: iteration,
+        success: false,
+        error: error.message || "Execution error",
+      };
+    }
+  }
+
+  // Max iterations reached
+  console.log(`[Continuous Execution] Reached max iterations (${maxIterations})\n`);
+  return {
+    responses,
+    finalResponse: responses[responses.length - 1],
+    iterations: iteration,
+    success: false,
+    error: `Reached maximum iterations (${maxIterations})`,
+  };
+}