@geekbeer/minion 2.33.4 → 2.42.5

package/core/lib/workflow-orchestrator.js

@@ -0,0 +1,382 @@
+/**
+ * Workflow Orchestrator
+ *
+ * Deterministic orchestration engine for multi-minion workflow execution.
+ * Replaces the previous LLM-based orchestration skill with code-driven
+ * step dispatch, status polling, and review gate handling.
+ *
+ * The only LLM call is for revision routing: when a reviewer requests
+ * changes, the orchestrator asks an LLM to decide which pipeline step
+ * to roll back to based on the review comment and pipeline structure.
+ */
+
+const { config } = require('../config')
+const api = require('../api')
+
+// Polling configuration
+const POLL_INTERVAL_MS = 30_000 // 30 seconds
+const STEP_TIMEOUT_MS = 30 * 60 * 1000 // 30 minutes per step
+const MAX_REVISIONS_PER_STEP = 3
+
+/**
+ * Sleep for specified milliseconds
+ * @param {number} ms
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Run the orchestration loop for a workflow execution.
+ * Dispatches steps sequentially, polls for completion, and handles review gates.
+ *
+ * @param {object} params
+ * @param {string} params.executionId - Workflow execution UUID
+ * @param {Array<{step_index: number, step_execution_id: string, skill_version_id: string, skill_name: string, assigned_role: string, requires_review: boolean}>} params.steps
+ * @param {string} params.hqUrl - HQ server URL
+ * @param {string} [params.revisionPolicy] - Optional PM revision policy text
+ * @returns {Promise<{success: boolean, error?: string}>}
+ */
+async function orchestrate({ executionId, steps, hqUrl, revisionPolicy }) {
+  // Always use the minion's own HQ_URL — it is guaranteed reachable from this
+  // network context.  The hqUrl passed from the trigger route may be a
+  // public URL that is not resolvable from inside a container.
+  const effectiveHqUrl = config.HQ_URL || hqUrl
+  if (!effectiveHqUrl) {
+    console.error('[Orchestrator] No HQ URL available (config.HQ_URL and hqUrl are both empty)')
+    return { success: false, error: 'No HQ URL configured' }
+  }
+
+  const apiToken = config.API_TOKEN
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${apiToken}`,
+  }
+
+  console.log(`[Orchestrator] Starting execution ${executionId} with ${steps.length} steps`)
+
+  let currentStepIdx = 0
+
+  while (currentStepIdx < steps.length) {
+    const step = steps[currentStepIdx]
+    console.log(`[Orchestrator] Dispatching step ${step.step_index}: ${step.skill_name} (role: ${step.assigned_role})`)
+
+    // 1. Dispatch step
+    const dispatchResult = await dispatchStep(effectiveHqUrl, headers, executionId, step.step_index)
+    if (!dispatchResult.success) {
+      console.error(`[Orchestrator] Failed to dispatch step ${step.step_index}: ${dispatchResult.error}`)
+      return { success: false, error: `Dispatch failed at step ${step.step_index}: ${dispatchResult.error}` }
+    }
+
+    console.log(`[Orchestrator] Step ${step.step_index} dispatched to ${dispatchResult.minion_name || 'unknown'}`)
+
+    // 2. Poll until step completes
+    const pollResult = await pollStepCompletion(effectiveHqUrl, headers, executionId, step.step_index)
+    if (!pollResult.success) {
+      console.error(`[Orchestrator] Step ${step.step_index} failed: ${pollResult.error}`)
+      return { success: false, error: `Step ${step.step_index} failed: ${pollResult.error}` }
+    }
+
+    console.log(`[Orchestrator] Step ${step.step_index} completed (status: ${pollResult.status})`)
+
+    // 3. Handle review gate if required
+    if (step.requires_review) {
+      const reviewResult = await handleReviewGate(effectiveHqUrl, headers, executionId, step, steps, revisionPolicy)
+
+      if (reviewResult.action === 'continue') {
+        // Approved — proceed to next step
+        console.log(`[Orchestrator] Step ${step.step_index} approved, continuing`)
+      } else if (reviewResult.action === 'abort') {
+        console.log(`[Orchestrator] Step ${step.step_index} rejected, aborting workflow`)
+        return { success: false, error: `Workflow aborted: step ${step.step_index} rejected by reviewer` }
+      } else if (reviewResult.action === 'retry_from') {
+        // Revision requested — jump back to target step
+        console.log(`[Orchestrator] Revision requested, restarting from step ${reviewResult.targetStepIndex}`)
+        currentStepIdx = reviewResult.targetStepIndex
+        continue
+      } else if (reviewResult.action === 'error') {
+        return { success: false, error: reviewResult.error }
+      }
+    }
+
+    currentStepIdx++
+  }
+
+  console.log(`[Orchestrator] Execution ${executionId} completed successfully`)
+  return { success: true }
+}
+
+/**
+ * Dispatch a single step via HQ API.
+ */
+async function dispatchStep(hqUrl, headers, executionId, stepIndex) {
+  try {
+    const resp = await fetch(`${hqUrl}/api/minion/dispatch-step`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ execution_id: executionId, step_index: stepIndex }),
+    })
+
+    const data = await resp.json()
+    if (!resp.ok) {
+      return { success: false, error: data.error || `HTTP ${resp.status}` }
+    }
+    return { success: true, minion_name: data.minion_name }
+  } catch (err) {
+    return { success: false, error: err.message }
+  }
+}
+
+/**
+ * Poll HQ for step completion. Returns when the step reaches a terminal state.
+ */
+async function pollStepCompletion(hqUrl, headers, executionId, stepIndex) {
+  const startTime = Date.now()
+
+  while (Date.now() - startTime < STEP_TIMEOUT_MS) {
+    try {
+      const resp = await fetch(`${hqUrl}/api/minion/execution/${executionId}/status`, {
+        headers,
+      })
+
+      if (!resp.ok) {
+        console.error(`[Orchestrator] Status poll failed: HTTP ${resp.status}`)
+        await sleep(POLL_INTERVAL_MS)
+        continue
+      }
+
+      const data = await resp.json()
+      const stepData = data.steps?.find((s) => s.step_index === stepIndex)
+
+      if (!stepData) {
+        console.error(`[Orchestrator] Step ${stepIndex} not found in status response`)
+        await sleep(POLL_INTERVAL_MS)
+        continue
+      }
+
+      if (stepData.status === 'completed') {
+        return { success: true, status: 'completed' }
+      }
+
+      if (stepData.status === 'failed') {
+        return { success: false, error: 'Step execution failed' }
+      }
+
+      // Still running or pending
+      await sleep(POLL_INTERVAL_MS)
+    } catch (err) {
+      console.error(`[Orchestrator] Poll error: ${err.message}`)
+      await sleep(POLL_INTERVAL_MS)
+    }
+  }
+
+  return { success: false, error: `Step ${stepIndex} timed out after ${STEP_TIMEOUT_MS / 60000} minutes` }
+}
+
+/**
+ * Handle review gate: poll for review decision and act accordingly.
+ * Reviewer can approve, reject, or request revisions.
+ *
+ * @returns {{ action: 'continue' | 'abort' | 'retry_from' | 'error', targetStepIndex?: number, error?: string }}
+ */
+async function handleReviewGate(hqUrl, headers, executionId, currentStep, allSteps, revisionPolicy) {
+  console.log(`[Orchestrator] Waiting for review on step ${currentStep.step_index}...`)
+
+  // Poll for review decision (no timeout — waits indefinitely for human input)
+  // In practice, the orchestrate caller or HQ can cancel the execution externally.
+  while (true) {
+    try {
+      const resp = await fetch(`${hqUrl}/api/minion/execution/${executionId}/status`, {
+        headers,
+      })
+
+      if (!resp.ok) {
+        await sleep(POLL_INTERVAL_MS)
+        continue
+      }
+
+      const data = await resp.json()
+      const stepData = data.steps?.find((s) => s.step_index === currentStep.step_index)
+
+      if (!stepData || !stepData.review_status) {
+        await sleep(POLL_INTERVAL_MS)
+        continue
+      }
+
+      if (stepData.review_status === 'approved') {
+        return { action: 'continue' }
+      }
+
+      if (stepData.review_status === 'rejected') {
+        return { action: 'abort' }
+      }
+
+      if (stepData.review_status === 'revision_requested') {
+        const reviewComment = stepData.review_comment || ''
+        console.log(`[Orchestrator] Revision requested: "${reviewComment}"`)
+
+        // Decide which step to roll back to
+        const targetStepIndex = await decideRevisionTarget(
+          allSteps,
+          reviewComment,
+          currentStep.step_index,
+          revisionPolicy
+        )
+
+        // Call revision-reset API
+        const resetResult = await resetForRevision(
+          hqUrl, headers, executionId,
+          targetStepIndex, currentStep.step_index, reviewComment
+        )
+
+        if (!resetResult.success) {
+          return { action: 'error', error: `Revision reset failed: ${resetResult.error}` }
+        }
+
+        return { action: 'retry_from', targetStepIndex }
+      }
+
+      await sleep(POLL_INTERVAL_MS)
+    } catch (err) {
+      console.error(`[Orchestrator] Review poll error: ${err.message}`)
+      await sleep(POLL_INTERVAL_MS)
+    }
+  }
+}
+
+/**
+ * Decide which step to roll back to when a reviewer requests revisions.
+ *
+ * Uses LLM to analyze the review comment and pipeline structure.
+ * Falls back to current step index if LLM call fails or returns invalid data.
+ *
+ * @param {Array} steps - All pipeline steps
+ * @param {string} reviewComment - Reviewer's feedback
+ * @param {number} currentStepIndex - The step that was reviewed
+ * @param {string} [revisionPolicy] - Optional PM-specific revision policy
+ * @returns {Promise<number>} Target step index to roll back to
+ */
+async function decideRevisionTarget(steps, reviewComment, currentStepIndex, revisionPolicy) {
+  // If only one step or current is first, no choice needed
+  if (currentStepIndex === 0 || steps.length <= 1) {
+    return currentStepIndex
+  }
+
+  // Build pipeline description for the LLM
+  const pipelineDesc = steps
+    .filter((s) => s.step_index <= currentStepIndex)
+    .map((s) => `Step ${s.step_index}: ${s.skill_name} (role: ${s.assigned_role})`)
+    .join('\n')
+
+  const systemPrompt = `You are analyzing a workflow pipeline to decide which step to roll back to after a reviewer requested changes.
+
+Given the pipeline steps and the reviewer's feedback, determine which step is the root cause that needs to be re-executed.
+- If the feedback targets the current step's output only, return the current step index.
+- If the feedback suggests an earlier step produced incorrect input, return that earlier step's index.
+- Always return the EARLIEST step that needs re-execution.
+
+Respond with ONLY a JSON object: {"target_step_index": <number>}
+Do not include any other text.`
+
+  const userPrompt = `## Pipeline (steps 0 through ${currentStepIndex})
+${pipelineDesc}
+
+## Reviewer Feedback
+${reviewComment}
+
+## Current Step (reviewed)
+Step ${currentStepIndex}
+${revisionPolicy ? `\n## PM Revision Policy\n${revisionPolicy}` : ''}`
+
+  try {
+    const result = await callLlmForJson(systemPrompt, userPrompt)
+
+    if (
+      result &&
+      typeof result.target_step_index === 'number' &&
+      Number.isInteger(result.target_step_index) &&
+      result.target_step_index >= 0 &&
+      result.target_step_index <= currentStepIndex
+    ) {
+      console.log(`[Orchestrator] LLM decided revision target: step ${result.target_step_index}`)
+      return result.target_step_index
+    }
+
+    console.warn(`[Orchestrator] LLM returned invalid target, falling back to current step ${currentStepIndex}`)
+    return currentStepIndex
+  } catch (err) {
+    console.error(`[Orchestrator] LLM call failed, falling back to current step: ${err.message}`)
+    return currentStepIndex
+  }
+}
+
+/**
+ * Call an LLM API to get a JSON response.
+ * Uses the Anthropic Messages API with ANTHROPIC_API_KEY from environment.
+ *
+ * @param {string} systemPrompt
+ * @param {string} userPrompt
+ * @returns {Promise<object>} Parsed JSON response
+ */
+async function callLlmForJson(systemPrompt, userPrompt) {
+  const apiKey = process.env.ANTHROPIC_API_KEY
+  if (!apiKey) {
+    throw new Error('ANTHROPIC_API_KEY not set — cannot make LLM call for revision routing')
+  }
+
+  const resp = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: 'claude-haiku-4-5-20251001',
+      max_tokens: 256,
+      system: systemPrompt,
+      messages: [{ role: 'user', content: userPrompt }],
+    }),
+  })
+
+  if (!resp.ok) {
+    const text = await resp.text()
+    throw new Error(`Anthropic API error: ${resp.status} ${text}`)
+  }
+
+  const data = await resp.json()
+  const content = data.content?.[0]?.text
+  if (!content) {
+    throw new Error('Empty response from Anthropic API')
+  }
+
+  return JSON.parse(content)
+}
+
+/**
+ * Call the revision-reset API on HQ to reset steps for re-execution.
+ */
+async function resetForRevision(hqUrl, headers, executionId, targetStepIndex, revisionStepIndex, revisionFeedback) {
+  try {
+    const resp = await fetch(`${hqUrl}/api/minion/revision-reset`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        execution_id: executionId,
+        target_step_index: targetStepIndex,
+        revision_step_index: revisionStepIndex,
+        revision_feedback: revisionFeedback,
+      }),
+    })
+
+    const data = await resp.json()
+    if (!resp.ok) {
+      return { success: false, error: data.error || `HTTP ${resp.status}` }
+    }
+    return { success: true }
+  } catch (err) {
+    return { success: false, error: err.message }
+  }
+}
+
+module.exports = { orchestrate }

package/core/routes/diagnose.js

@@ -0,0 +1,296 @@
+/**
+ * Diagnostic endpoint for checking all essential services
+ *
+ * Endpoints:
+ * - GET /api/diagnose - Run full diagnostic check
+ *
+ * Checks:
+ * - Minion Server (Fastify) status
+ * - HQ connectivity (heartbeat reachability)
+ * - Cloudflare Tunnel process
+ * - VNC / websockify (display server)
+ * - Terminal proxy (ttyd / terminal-server)
+ * - LLM CLI availability (Claude, Gemini, Codex)
+ * - Environment variable configuration
+ */
+
+const { execSync } = require('child_process')
+const { config, isHqConfigured } = require('../config')
+const { version } = require('../../package.json')
+const { getLlmServices, isLlmCommandConfigured } = require('../lib/llm-checker')
+const { IS_WINDOWS } = require('../lib/platform')
+const { getStatus } = require('./health')
+
+/**
+ * Check if a process is running by name.
+ * @param {string} name - Process name to search for
+ * @returns {boolean}
+ */
+function isProcessRunning(name) {
+  try {
+    if (IS_WINDOWS) {
+      const out = execSync(`tasklist /FI "IMAGENAME eq ${name}" /NH`, {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: 'pipe',
+      })
+      return out.toLowerCase().includes(name.toLowerCase())
+    } else {
+      execSync(`pgrep -f "${name}"`, {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: 'pipe',
+      })
+      return true
+    }
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if a local TCP port is listening.
+ * @param {number} port
+ * @returns {boolean}
+ */
+function isPortListening(port) {
+  try {
+    if (IS_WINDOWS) {
+      const out = execSync(`netstat -an | findstr ":${port} "`, {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: 'pipe',
+      })
+      return out.includes('LISTENING')
+    } else {
+      const out = execSync(`ss -tlnp 2>/dev/null | grep ":${port} " || netstat -tlnp 2>/dev/null | grep ":${port} "`, {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: 'pipe',
+      })
+      return out.trim().length > 0
+    }
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check HQ connectivity by sending a test heartbeat.
+ * @returns {Promise<{ ok: boolean, latency_ms?: number, error?: string }>}
+ */
+async function checkHqConnectivity() {
+  if (!isHqConfigured()) {
+    return { ok: false, error: 'HQ not configured (standalone mode)' }
+  }
+
+  const url = `${config.HQ_URL}/api/minion/heartbeat`
+  const { currentStatus, currentTask } = getStatus()
+  const start = Date.now()
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${config.API_TOKEN}`,
+      },
+      body: JSON.stringify({ status: currentStatus, current_task: currentTask, version }),
+      signal: AbortSignal.timeout(10000),
+    })
+    const latency = Date.now() - start
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}))
+      return { ok: false, latency_ms: latency, error: `HTTP ${response.status}: ${data.error || response.statusText}` }
+    }
+
+    return { ok: true, latency_ms: latency }
+  } catch (err) {
+    const latency = Date.now() - start
+    return { ok: false, latency_ms: latency, error: err.message }
+  }
+}
+
+/**
+ * Check Cloudflare Tunnel status.
+ * @returns {{ running: boolean, details?: string }}
+ */
+function checkTunnel() {
+  if (IS_WINDOWS) {
+    const running = isProcessRunning('cloudflared.exe')
+    return { running, details: running ? 'cloudflared.exe process found' : 'cloudflared.exe not running' }
+  }
+
+  // Linux: check for cloudflared process
+  const running = isProcessRunning('cloudflared')
+  if (!running) {
+    return { running: false, details: 'cloudflared not running' }
+  }
+
+  // Check if it's a tunnel connector (not just any cloudflared)
+  try {
+    const out = execSync('pgrep -af "cloudflared.*tunnel"', {
+      encoding: 'utf-8',
+      timeout: 5000,
+      stdio: 'pipe',
+    }).trim()
+    return { running: true, details: out.split('\n')[0] || 'cloudflared tunnel running' }
+  } catch {
+    return { running: true, details: 'cloudflared running (tunnel mode unconfirmed)' }
+  }
+}
+
+/**
+ * Check VNC / display server status.
+ * @returns {{ running: boolean, port?: number, details?: string }}
+ */
+function checkVnc() {
+  if (IS_WINDOWS) {
+    // TightVNC on Windows
+    const running = isProcessRunning('tvnserver.exe')
+    const websockify = isPortListening(6080)
+    return {
+      running: running && websockify,
+      details: [
+        `TightVNC: ${running ? 'running' : 'not running'}`,
+        `websockify (:6080): ${websockify ? 'listening' : 'not listening'}`,
+      ].join(', '),
+    }
+  }
+
+  // Linux: Xvfb + x11vnc + websockify (noVNC)
+  const xvfb = isProcessRunning('Xvfb')
+  const vnc = isProcessRunning('x11vnc')
+  const websockify = isPortListening(6080)
+  return {
+    running: xvfb && websockify,
+    details: [
+      `Xvfb: ${xvfb ? 'running' : 'not running'}`,
+      `x11vnc: ${vnc ? 'running' : 'not running'}`,
+      `websockify (:6080): ${websockify ? 'listening' : 'not listening'}`,
+    ].join(', '),
+  }
+}
+
+/**
+ * Check terminal proxy status.
+ * @returns {{ running: boolean, port?: number, details?: string }}
+ */
+function checkTerminal() {
+  if (IS_WINDOWS) {
+    // Windows terminal server runs on port 7681
+    const listening = isPortListening(7681)
+    return {
+      running: listening,
+      details: `terminal-server (:7681): ${listening ? 'listening' : 'not listening'}`,
+    }
+  }
+
+  // Linux: ttyd on port 7681
+  const ttyd = isProcessRunning('ttyd')
+  const listening = isPortListening(7681)
+  return {
+    running: ttyd || listening,
+    details: [
+      `ttyd: ${ttyd ? 'running' : 'not running'}`,
+      `port 7681: ${listening ? 'listening' : 'not listening'}`,
+    ].join(', '),
+  }
+}
+
+/**
+ * Check LLM service availability.
+ * @returns {{ services: object[], llm_command: { configured: boolean, value: string } }}
+ */
+function checkLlm() {
+  return {
+    services: getLlmServices(),
+    llm_command: {
+      configured: isLlmCommandConfigured(),
+      value: config.LLM_COMMAND || '(not set)',
+    },
+  }
+}
+
+/**
+ * Check environment variable configuration.
+ * @returns {{ configured: string[], missing: string[] }}
+ */
+function checkEnv() {
+  const required = ['HQ_URL', 'API_TOKEN', 'MINION_ID']
+  const optional = ['AGENT_PORT', 'LLM_COMMAND', 'HEARTBEAT_INTERVAL', 'MINION_USER']
+
+  const configured = []
+  const missing = []
+
+  for (const key of required) {
+    if (config[key] || process.env[key]) {
+      configured.push(key)
+    } else {
+      missing.push(key)
+    }
+  }
+  for (const key of optional) {
+    if (config[key] || process.env[key]) {
+      configured.push(key)
+    }
+  }
+
+  return { configured, missing }
+}
+
+/**
+ * Register diagnose routes as Fastify plugin
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+async function diagnoseRoutes(fastify) {
+  fastify.get('/api/diagnose', async () => {
+    const { currentStatus, currentTask } = getStatus()
+
+    // Run HQ check (async) in parallel with sync checks
+    const [hq, tunnel, vnc, terminal, llm, env] = await Promise.all([
+      checkHqConnectivity(),
+      Promise.resolve(checkTunnel()),
+      Promise.resolve(checkVnc()),
+      Promise.resolve(checkTerminal()),
+      Promise.resolve(checkLlm()),
+      Promise.resolve(checkEnv()),
+    ])
+
+    // Build summary: count ok/warn/fail
+    const checks = {
+      agent: { ok: true, details: `status=${currentStatus}, uptime=${Math.floor(process.uptime())}s` },
+      hq: { ok: hq.ok, details: hq.error || `latency=${hq.latency_ms}ms` },
+      tunnel: { ok: tunnel.running, details: tunnel.details },
+      vnc: { ok: vnc.running, details: vnc.details },
+      terminal: { ok: terminal.running, details: terminal.details },
+      llm: {
+        ok: llm.services.some(s => s.authenticated) && llm.llm_command.configured,
+        details: llm.services.map(s => `${s.name}:${s.authenticated ? 'ok' : 'ng'}`).join(', ')
+          + ` | llm_command:${llm.llm_command.configured ? 'ok' : 'ng'}`,
+      },
+      env: {
+        ok: env.missing.length === 0,
+        details: env.missing.length === 0
+          ? `all configured (${env.configured.join(', ')})`
+          : `missing: ${env.missing.join(', ')}`,
+      },
+    }
+
+    const okCount = Object.values(checks).filter(c => c.ok).length
+    const totalCount = Object.keys(checks).length
+    const allOk = okCount === totalCount
+
+    return {
+      summary: allOk ? 'ALL OK' : `${okCount}/${totalCount} checks passed`,
+      version,
+      platform: IS_WINDOWS ? 'windows' : 'linux',
+      timestamp: new Date().toISOString(),
+      current_task: currentTask,
+      checks,
+    }
+  })
+}
+
+module.exports = { diagnoseRoutes }