@caseyharalson/orrery 0.7.1

package/lib/orchestration/config.js

@@ -0,0 +1,213 @@
+/**
+ * Orchestrator Configuration
+ *
+ * This file configures the plan orchestrator including agent commands,
+ * concurrency settings, and directory paths.
+ */
+
+const { getFormatInstructions } = require("./report-format");
+const { detectInstalledAgents } = require("../utils/agent-detector");
+
+// Helper function to get agent priority from environment or default
+function getAgentPriority() {
+  const envPriority = process.env.ORRERY_AGENT_PRIORITY;
+  if (envPriority && envPriority.trim()) {
+    return envPriority
+      .trim()
+      .split(",")
+      .map((s) => s.trim());
+  }
+  return ["codex", "gemini", "claude"];
+}
+
+// Filter agent priority to only include agents that are installed (have config directories)
+function getInstalledAgentPriority() {
+  const requestedAgents = getAgentPriority();
+  const installedAgents = detectInstalledAgents();
+
+  const filteredAgents = requestedAgents.filter((agent) =>
+    installedAgents.includes(agent)
+  );
+
+  // Warn about agents in priority that aren't installed
+  const skippedAgents = requestedAgents.filter(
+    (agent) => !installedAgents.includes(agent)
+  );
+  if (skippedAgents.length > 0) {
+    const missingDirs = skippedAgents.map((a) => `~/.${a}`).join(", ");
+    console.warn(
+      `[config] Skipping unconfigured agents: ${skippedAgents.join(", ")} (missing: ${missingDirs})`
+    );
+  }
+
+  if (filteredAgents.length === 0) {
+    console.warn(
+      `[config] No configured agents found. Install an agent CLI and create its config directory (e.g., ~/.claude, ~/.codex, ~/.gemini)`
+    );
+  }
+
+  return filteredAgents;
+}
+
+// Shared prompt for all worker agents
+const WORKER_PROMPT = `You are a Worker Agent executing plan steps.
+
+Plan file: {planFile}
+Steps to execute: {stepIds}
+
+## Plan Format Note
+
+The plan file may be a condensed version containing only your assigned steps
+and their completed dependencies (indicated by \`condensed: true\` in metadata).
+All necessary context is included - do not reference the source plan.
+
+## Workflow
+
+For each step:
+
+1. Read the plan file to understand the step's requirements, criteria, and files
+2. Execute: Implement the changes following project conventions. Do NOT commit - the orchestrator handles commits.
+3. Verify: Run tests and confirm acceptance criteria are met. Fix issues before proceeding.
+4. Report: Output a JSON result for the step (see format below)
+
+Use /orrery-execute, /orrery-verify, and /orrery-report skills for detailed guidance on each phase.
+
+${getFormatInstructions()}
+
+## Exit Codes
+
+- Exit 0: All steps completed successfully
+- Exit 1: One or more steps blocked
+
+## Rules
+
+- The plan file is READ-ONLY—never modify it
+- Complete each step fully before starting the next
+- Output clean JSON to stdout—no extra text or markdown wrapping`;
+
+const REVIEW_PROMPT = `You are a Review Agent. Evaluate the changes for the completed plan step.
+
+## Context
+
+Step context:
+{stepContext}
+
+Modified files:
+{files}
+
+Diff:
+{diff}
+
+## Instructions
+
+- Identify bugs, regressions, missing edge cases, or unmet acceptance criteria.
+- If changes are acceptable, respond with approval.
+- If changes need edits, provide specific, actionable feedback.
+- Keep feedback concise and grounded in the diff.
+
+## Output Format (JSON, single line)
+
+{"status":"approved","summary":"..."}
+OR
+{"status":"changes_requested","summary":"...","comments":["...","..."]}`;
+
+module.exports = {
+  // Agent configurations (keyed by agent name)
+  agents: {
+    claude: {
+      command: "claude",
+      args: [
+        "--model",
+        "sonnet",
+        "--dangerously-skip-permissions",
+        "-p",
+        WORKER_PROMPT
+      ]
+    },
+    codex: {
+      command: "codex",
+      args: ["exec", "--yolo", WORKER_PROMPT],
+      // Codex writes progress to stderr and final result to stdout
+      stderrIsProgress: true
+    },
+    gemini: {
+      command: "gemini",
+      args: ["--yolo", "-p", WORKER_PROMPT],
+      // Gemini writes progress to stderr and final result to stdout
+      stderrIsProgress: true
+    }
+  },
+
+  // Default agent to use when failover is disabled
+  defaultAgent: "codex",
+
+  // Agent priority list for failover (tried in order, filtered to installed agents)
+  agentPriority: getInstalledAgentPriority(),
+
+  // Failover configuration
+  failover: {
+    // Enable/disable failover behavior
+    enabled: true,
+
+    // Timeout in milliseconds before trying next agent (15 minutes)
+    timeoutMs: 900000,
+
+    // Patterns to detect failover-triggering errors from stderr
+    errorPatterns: {
+      // API/connection errors
+      apiError: [
+        /API error/i,
+        /connection refused/i,
+        /ECONNRESET/i,
+        /ETIMEDOUT/i,
+        /network error/i,
+        /rate limit/i,
+        /429/,
+        /502/,
+        /503/
+      ],
+      // Token/context limit errors
+      tokenLimit: [
+        /token limit/i,
+        /context.*(limit|length|exceeded)/i,
+        /maximum.*tokens/i,
+        /too long/i
+      ]
+    }
+  },
+
+  // Concurrency control
+  concurrency: {
+    maxParallel: 1, // Parallel disabled - see TODO below
+    // TODO: To re-enable parallel execution:
+    // 1. Set maxParallel > 1
+    // 2. Bundle commits: after ALL parallel agents complete, commit once with combined messages
+    // 3. Update processPlan() to collect all parallel results before committing
+    pollInterval: 5000
+  },
+
+  // Retry policy for failed steps
+  retry: {
+    // Maximum retry attempts per step
+    maxAttempts: 1,
+    // Delay in ms before retrying
+    backoffMs: 5000
+  },
+
+  // Logging options
+  logging: {
+    // Show agent stdout in real-time
+    streamOutput: true,
+    // Prefix format for agent output ("[step-1]" or "[step-1,step-2]")
+    prefixFormat: "step"
+  },
+
+  // Review/edit loop configuration
+  review: {
+    enabled: false,
+    maxIterations: 3,
+    prompt: REVIEW_PROMPT
+  },
+
+  REVIEW_PROMPT
+};

package/lib/orchestration/dependency-resolver.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+/**
+ * Dependency resolution utilities for plan step execution ordering.
+ * Uses Kahn's algorithm for topological sorting.
+ */
+
+/**
+ * Get steps that are ready to execute (pending with all deps satisfied)
+ * @param {Object} plan - The plan object
+ * @returns {Array} - Array of step objects ready to execute
+ */
+function getReadySteps(plan) {
+  const completed = plan.getCompletedSteps();
+
+  return plan.steps.filter((step) => {
+    // Must be pending
+    if (step.status !== "pending") return false;
+
+    // All dependencies must be complete (not pending, not blocked, not in_progress)
+    const deps = step.deps || [];
+    return deps.every((depId) => completed.has(depId));
+  });
+}
+
+/**
+ * Group steps for parallel execution based on dependency levels.
+ * Uses Kahn's algorithm to find execution groups.
+ * @param {Array} steps - Array of step objects (with id, deps, parallel fields)
+ * @returns {Array<Array>} - Array of step groups, each group can run in parallel
+ */
+function resolveExecutionGroups(steps) {
+  const stepMap = new Map(steps.map((s) => [s.id, s]));
+  const remaining = new Set(steps.map((s) => s.id));
+  const groups = [];
+
+  while (remaining.size > 0) {
+    // Find all steps with no remaining dependencies
+    const ready = [...remaining].filter((id) => {
+      const step = stepMap.get(id);
+      const deps = step.deps || [];
+      return deps.every((dep) => !remaining.has(dep));
+    });
+
+    if (ready.length === 0 && remaining.size > 0) {
+      const cycleSteps = [...remaining].join(", ");
+      throw new Error(
+        `Circular dependency detected among steps: ${cycleSteps}`
+      );
+    }
+
+    // Separate parallel and serial steps
+    const parallelSteps = ready
+      .filter((id) => stepMap.get(id).parallel === true)
+      .map((id) => stepMap.get(id));
+
+    const serialSteps = ready
+      .filter((id) => stepMap.get(id).parallel !== true)
+      .map((id) => stepMap.get(id));
+
+    // Add parallel steps as a single group (can run together)
+    if (parallelSteps.length > 0) {
+      groups.push(parallelSteps);
+    }
+
+    // Add serial steps as individual groups (run one at a time)
+    for (const step of serialSteps) {
+      groups.push([step]);
+    }
+
+    // Remove processed steps from remaining
+    for (const id of ready) {
+      remaining.delete(id);
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * Check if a plan has any circular dependencies
+ * @param {Object} plan - The plan object
+ * @returns {{hasCycle: boolean, cycleSteps?: string[]}} - Result with cycle info
+ */
+function detectCycles(plan) {
+  try {
+    resolveExecutionGroups(plan.steps);
+    return { hasCycle: false };
+  } catch (error) {
+    if (error.message.includes("Circular dependency")) {
+      // Extract step IDs from error message
+      const match = error.message.match(/steps: (.+)$/);
+      const cycleSteps = match ? match[1].split(", ") : [];
+      return { hasCycle: true, cycleSteps };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get steps that are blocked due to a specific step being blocked
+ * (i.e., steps that depend on the blocked step directly or transitively)
+ * @param {Object} plan - The plan object
+ * @param {string} blockedStepId - ID of the blocked step
+ * @returns {string[]} - Array of step IDs that are blocked as a result
+ */
+function getBlockedDependents(plan, blockedStepId) {
+  const dependents = new Set();
+
+  function findDependents(stepId) {
+    for (const step of plan.steps) {
+      const deps = step.deps || [];
+      if (deps.includes(stepId) && !dependents.has(step.id)) {
+        dependents.add(step.id);
+        findDependents(step.id);
+      }
+    }
+  }
+
+  findDependents(blockedStepId);
+  return [...dependents];
+}
+
+/**
+ * Partition ready steps into groups respecting maxParallel limit
+ * @param {Array} readySteps - Steps ready to execute
+ * @param {number} maxParallel - Maximum concurrent steps
+ * @param {number} currentlyRunning - Number of steps currently in progress
+ * @returns {{parallel: Array, serial: Array}} - Steps grouped by execution type
+ */
+function partitionSteps(readySteps, maxParallel, currentlyRunning = 0) {
+  const availableSlots = Math.max(0, maxParallel - currentlyRunning);
+
+  const parallel = readySteps.filter((s) => s.parallel === true);
+  const serial = readySteps.filter((s) => s.parallel !== true);
+
+  return {
+    parallel: parallel.slice(0, availableSlots),
+    serial: serial.slice(0, Math.max(0, availableSlots - parallel.length))
+  };
+}
+
+module.exports = {
+  getReadySteps,
+  resolveExecutionGroups,
+  detectCycles,
+  getBlockedDependents,
+  partitionSteps
+};

package/lib/orchestration/edit-invoker.js

@@ -0,0 +1,115 @@
+const {
+  invokeAgentWithFailover,
+  parseAgentResults
+} = require("./agent-invoker");
+
+function getWorkerPromptTemplate(config) {
+  if (config && typeof config.WORKER_PROMPT === "string") {
+    return config.WORKER_PROMPT;
+  }
+
+  const agents = (config && config.agents) || {};
+  const preferredAgent =
+    (config && config.defaultAgent && agents[config.defaultAgent]) ||
+    Object.values(agents)[0];
+
+  if (preferredAgent && Array.isArray(preferredAgent.args)) {
+    const lastArg = preferredAgent.args[preferredAgent.args.length - 1];
+    if (typeof lastArg === "string") {
+      return lastArg;
+    }
+  }
+
+  return "";
+}
+
+function formatFeedbackList(feedback) {
+  if (!Array.isArray(feedback) || feedback.length === 0) {
+    return "No review feedback items provided.";
+  }
+
+  return feedback
+    .map((entry, index) => {
+      const item =
+        entry && typeof entry === "object" ? entry : { comment: String(entry) };
+      const file =
+        typeof item.file === "string" && item.file.trim()
+          ? item.file.trim()
+          : "(not specified)";
+      const line = Number.isFinite(item.line) ? ` line: ${item.line}` : "";
+      const severity =
+        typeof item.severity === "string" && item.severity.trim()
+          ? item.severity.trim()
+          : "suggestion";
+      const comment =
+        typeof item.comment === "string" && item.comment.trim()
+          ? item.comment.trim()
+          : "(no comment provided)";
+
+      return `${index + 1}. file: ${file}${line} severity: ${severity} comment: ${comment}`;
+    })
+    .join("\n");
+}
+
+function buildEditPrompt(template, planFile, stepIds, feedback) {
+  const stepIdsStr = Array.isArray(stepIds)
+    ? stepIds.join(",")
+    : String(stepIds);
+  const basePrompt = String(template || "")
+    .replace("{planFile}", planFile)
+    .replace("{stepIds}", stepIdsStr);
+
+  const feedbackSection = formatFeedbackList(feedback);
+
+  return `${basePrompt}\n\n## Review Feedback\n${feedbackSection}\n\n## Instructions\nAddress all review feedback items above before reporting the step as complete.`;
+}
+
+function buildEditConfig(config, prompt) {
+  const agents = {};
+
+  for (const [name, agentConfig] of Object.entries(config.agents || {})) {
+    const args = Array.isArray(agentConfig.args)
+      ? agentConfig.args.slice()
+      : [];
+    if (args.length > 0) {
+      args[args.length - 1] = prompt;
+    }
+    agents[name] = {
+      ...agentConfig,
+      args
+    };
+  }
+
+  return {
+    ...config,
+    agents
+  };
+}
+
+async function invokeEditAgent(
+  config,
+  planFile,
+  stepIds,
+  feedback,
+  repoRoot,
+  options = {}
+) {
+  const template = getWorkerPromptTemplate(config);
+  const prompt = buildEditPrompt(template, planFile, stepIds, feedback);
+  const editConfig = buildEditConfig(config, prompt);
+
+  const handle = invokeAgentWithFailover(
+    editConfig,
+    planFile,
+    stepIds,
+    repoRoot,
+    options
+  );
+
+  const result = await handle.completion;
+  return parseAgentResults(result.stdout || "");
+}
+
+module.exports = {
+  invokeEditAgent
+};