@geekbeer/minion 2.33.4 → 2.42.5

package/.env.example

@@ -17,6 +17,3 @@ MINION_ID=
 
 # Agent port (optional, default: 8080)
 AGENT_PORT=8080
-
-# Heartbeat interval in seconds (optional, default: 30)
-HEARTBEAT_INTERVAL=30

package/README.md

@@ -58,7 +58,6 @@ await reportIssue({
 | `API_TOKEN` | Authentication token | - |
 | `MINION_ID` | Minion UUID | - |
 | `AGENT_PORT` | Agent API listen port | `8080` |
-| `HEARTBEAT_INTERVAL` | Heartbeat interval (ms) | `30000` |
 
 ## License
 

package/core/api.js

@@ -74,9 +74,22 @@ async function reportIssue(data) {
   })
 }
 
+/**
+ * Send heartbeat to HQ to report current status.
+ * Called periodically, on startup, on shutdown, and on status change.
+ * @param {object} data - { status: 'online' | 'offline' | 'busy', current_task?: string | null, version?: string }
+ */
+async function sendHeartbeat(data) {
+  return request('/heartbeat', {
+    method: 'POST',
+    body: JSON.stringify(data),
+  })
+}
+
 module.exports = {
   request,
   reportExecution,
   reportStepComplete,
   reportIssue,
+  sendHeartbeat,
 }

package/core/config.js

@@ -15,8 +15,40 @@
  */
 
 const os = require('os')
+const fs = require('fs')
 const { execSync } = require('child_process')
 
+/**
+ * Load .env file into process.env (without overwriting existing values).
+ * This ensures values written to the .env file at runtime (e.g. LLM_COMMAND
+ * set via the config API) are picked up on process restart, even when the
+ * process manager (supervisord) does not include them in its environment line.
+ */
+function loadEnvFile() {
+  const { resolveEnvFilePath } = require('./lib/platform')
+  // resolveHomeDir is not available yet, use a lightweight fallback
+  const home = process.env.HOME || os.homedir()
+  const envPath = resolveEnvFilePath(home)
+  try {
+    const content = fs.readFileSync(envPath, 'utf-8')
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('=')) continue
+      const eqIdx = trimmed.indexOf('=')
+      const key = trimmed.slice(0, eqIdx).trim()
+      const value = trimmed.slice(eqIdx + 1).trim()
+      // Do not overwrite values already set by the process manager
+      if (!(key in process.env)) {
+        process.env[key] = value
+      }
+    }
+  } catch {
+    // .env file doesn't exist or can't be read — not an error
+  }
+}
+
+loadEnvFile()
+
 /**
  * Resolve the correct home directory for the minion user.
  * On Linux, supervisord environments may set HOME=/root incorrectly.
@@ -82,4 +114,17 @@ function isLlmConfigured() {
   return !!config.LLM_COMMAND
 }
 
-module.exports = { config, validate, isHqConfigured, isLlmConfigured }
+/**
+ * Update a config value at runtime (e.g. after .env file write).
+ * Also syncs to process.env so child processes inherit the change.
+ * @param {string} key
+ * @param {string} value
+ */
+function updateConfig(key, value) {
+  if (key in config) {
+    config[key] = value
+    process.env[key] = value
+  }
+}
+
+module.exports = { config, validate, isHqConfigured, isLlmConfigured, updateConfig }

package/core/lib/log-manager.js

@@ -7,6 +7,7 @@
 const fs = require('fs').promises
 const path = require('path')
 const platform = require('./platform')
+const { stripAnsi } = require('./strip-ansi')
 
 // Log storage configuration (platform-aware via platform.js)
 const LOG_DIR = platform.LOG_DIR
@@ -59,7 +60,9 @@ async function readLog(executionId, options = {}) {
 
   try {
     const stats = await fs.stat(logPath)
-    const content = await fs.readFile(logPath, 'utf-8')
+    const rawContent = await fs.readFile(logPath, 'utf-8')
+    // Strip ANSI/TTY escape sequences from tmux pipe-pane output
+    const content = stripAnsi(rawContent)
     const allLines = content.split('\n')
 
     let resultContent = content

package/core/lib/platform.js

@@ -16,22 +16,15 @@ const TEMP_DIR = os.tmpdir()
 
 /**
  * Resolve the data directory for minion agent persistent files.
- * Windows: %PROGRAMDATA%\minion-agent (or fallback to %USERPROFILE%\.minion-agent)
+ * Windows: %USERPROFILE%\.minion (matches minion-cli.ps1 / start-agent.ps1)
  * Linux:   /opt/minion-agent (existing behavior)
  */
 function resolveDataDir() {
   if (IS_WINDOWS) {
-    const programData = process.env.PROGRAMDATA || process.env.ALLUSERSPROFILE
-    if (programData) {
-      const dir = path.join(programData, 'minion-agent')
-      try {
-        fs.mkdirSync(dir, { recursive: true })
-        return dir
-      } catch {
-        // Fall through to home-based path
-      }
-    }
-    return path.join(os.homedir(), '.minion-agent')
+    // Use ~/.minion to match minion-cli.ps1 and start-agent.ps1.
+    // All Windows-specific code (CLI, process-manager, server.js) uses ~/.minion
+    // as the canonical data directory, so core modules must align with it.
+    return path.join(os.homedir(), '.minion')
   }
   return '/opt/minion-agent'
 }
@@ -89,7 +82,9 @@ function getDefaultShell() {
 
 /**
  * Resolve .env file path.
- * Prefers DATA_DIR/.env, falls back to ~/minion.env.
+ * Returns DATA_DIR/.env (which is ~/.minion/.env on Windows,
+ * /opt/minion-agent/.env on Linux).
+ * Falls back to ~/minion.env if DATA_DIR is not writable.
  * @param {string} homeDir - User home directory
  * @returns {string} Path to .env file
  */

package/core/lib/revision-watcher.js

@@ -0,0 +1,252 @@
+/**
+ * Revision Watcher
+ *
+ * PM-only polling daemon that detects steps with revision_requested
+ * review status and handles revision routing.
+ *
+ * When a reviewer requests changes on a completed step:
+ * 1. This watcher detects the revision_requested status
+ * 2. Uses LLM to decide which step to roll back to
+ * 3. Calls HQ's /api/minion/revision-reset to reset affected steps
+ * 4. The step-poller on the target minion picks up the re-pending step
+ *
+ * Only runs on minions that have PM role in at least one project.
+ */
+
+const { config, isHqConfigured } = require('../config')
+const api = require('../api')
+
+// Poll every 30 seconds (same frequency as step-poller)
+const POLL_INTERVAL_MS = 30_000
+
+let polling = false
+let pollTimer = null
+
+// Track revisions being processed to avoid duplicate handling
+const processingRevisions = new Set()
+
+/**
+ * Poll HQ for pending revisions and handle them.
+ */
+async function pollOnce() {
+  if (!isHqConfigured()) return
+  if (polling) return
+
+  polling = true
+  try {
+    const data = await api.request('/pending-revisions')
+
+    if (!data.revisions || data.revisions.length === 0) {
+      return
+    }
+
+    console.log(`[RevisionWatcher] Found ${data.revisions.length} pending revision(s)`)
+
+    for (const revision of data.revisions) {
+      const key = `${revision.execution_id}-${revision.revision_step_index}`
+      if (processingRevisions.has(key)) {
+        continue
+      }
+
+      processingRevisions.add(key)
+      try {
+        await handleRevision(revision)
+      } finally {
+        processingRevisions.delete(key)
+      }
+    }
+  } catch (err) {
+    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+      console.log(`[RevisionWatcher] HQ unreachable, will retry next cycle`)
+    } else {
+      console.error(`[RevisionWatcher] Poll error: ${err.message}`)
+    }
+  } finally {
+    polling = false
+  }
+}
+
+/**
+ * Handle a single revision request:
+ * 1. Decide which step to roll back to (LLM or simple heuristic)
+ * 2. Call revision-reset API
+ *
+ * @param {object} revision
+ * @param {string} revision.execution_id
+ * @param {string} revision.workflow_name
+ * @param {number} revision.revision_step_index
+ * @param {string} revision.review_comment
+ * @param {Array<{step_index: number, skill_name: string|null, assigned_role: string}>} revision.pipeline
+ */
+async function handleRevision(revision) {
+  const { execution_id, workflow_name, revision_step_index, review_comment, pipeline } = revision
+
+  console.log(
+    `[RevisionWatcher] Handling revision for "${workflow_name}" step ${revision_step_index}: "${review_comment}"`
+  )
+
+  // Decide target step for rollback
+  const targetStepIndex = await decideRevisionTarget(pipeline, review_comment, revision_step_index)
+
+  console.log(`[RevisionWatcher] Rolling back to step ${targetStepIndex}`)
+
+  // Call revision-reset API on HQ
+  try {
+    await api.request('/revision-reset', {
+      method: 'POST',
+      body: JSON.stringify({
+        execution_id,
+        target_step_index: targetStepIndex,
+        revision_step_index: revision_step_index,
+        revision_feedback: review_comment,
+      }),
+    })
+
+    console.log(
+      `[RevisionWatcher] Revision reset complete: steps ${targetStepIndex}-${revision_step_index} ` +
+      `of execution ${execution_id} reset to pending`
+    )
+  } catch (err) {
+    console.error(`[RevisionWatcher] Revision reset failed: ${err.message}`)
+  }
+}
+
+/**
+ * Decide which step to roll back to.
+ * Uses LLM when multiple steps are involved, otherwise defaults to the reviewed step.
+ */
+async function decideRevisionTarget(pipeline, reviewComment, currentStepIndex) {
+  // If only one step or reviewing the first step, no choice needed
+  if (currentStepIndex === 0 || pipeline.length <= 1) {
+    return currentStepIndex
+  }
+
+  // Build pipeline description for LLM
+  const pipelineDesc = pipeline
+    .map(s => `Step ${s.step_index}: ${s.skill_name || 'unknown'} (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}`
+
+  // Load optional PM revision policy
+  let revisionPolicy = ''
+  try {
+    const fs = require('fs').promises
+    const path = require('path')
+    const policyPath = path.join(config.HOME_DIR, '.minion', 'revision-policy.md')
+    revisionPolicy = await fs.readFile(policyPath, 'utf-8')
+  } catch {
+    // No custom policy
+  }
+
+  if (revisionPolicy) {
+    // Append policy to user prompt (same as orchestrator did)
+  }
+
+  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(`[RevisionWatcher] LLM decided revision target: step ${result.target_step_index}`)
+      return result.target_step_index
+    }
+
+    console.warn(`[RevisionWatcher] LLM returned invalid target, falling back to step ${currentStepIndex}`)
+    return currentStepIndex
+  } catch (err) {
+    console.error(`[RevisionWatcher] LLM call failed, falling back to step ${currentStepIndex}: ${err.message}`)
+    return currentStepIndex
+  }
+}
+
+/**
+ * Call LLM API for JSON response.
+ * Reuses the same Anthropic Messages API pattern as workflow-orchestrator.
+ */
+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)
+}
+
+/**
+ * Start the revision watcher daemon.
+ */
+function start() {
+  if (!isHqConfigured()) {
+    console.log('[RevisionWatcher] HQ not configured, revision watcher disabled')
+    return
+  }
+
+  // Initial poll after a short delay
+  setTimeout(() => pollOnce(), 8000)
+
+  // Periodic polling
+  pollTimer = setInterval(() => pollOnce(), POLL_INTERVAL_MS)
+  console.log(`[RevisionWatcher] Started (polling every ${POLL_INTERVAL_MS / 1000}s)`)
+}
+
+/**
+ * Stop the revision watcher daemon.
+ */
+function stop() {
+  if (pollTimer) {
+    clearInterval(pollTimer)
+    pollTimer = null
+    console.log('[RevisionWatcher] Stopped')
+  }
+}
+
+module.exports = { start, stop, pollOnce }

package/core/lib/step-poller.js

@@ -0,0 +1,222 @@
+/**
+ * Step Poller
+ *
+ * Polling daemon that runs on every minion (including PM).
+ * Periodically checks HQ for pending workflow steps assigned to this
+ * minion's role, then fetches the skill and executes it.
+ *
+ * This enables the Pull model: minions autonomously pick up work
+ * when their turn comes, without needing a PM to push-dispatch.
+ * Handles minion absence gracefully — when a minion comes online,
+ * it simply picks up any pending steps waiting for its role.
+ *
+ * Flow per poll cycle:
+ * 1. GET /api/minion/pending-steps → list of actionable steps
+ * 2. For each step (one at a time):
+ *    a. POST /api/skills/fetch/:name → deploy skill locally
+ *    b. POST /api/skills/run → execute in tmux session
+ *    c. (step-complete is reported by the /api/skills/run post-execution hook)
+ */
+
+const { config, isHqConfigured } = require('../config')
+const api = require('../api')
+
+// Polling interval: 30 seconds (matches heartbeat frequency)
+const POLL_INTERVAL_MS = 30_000
+
+// Prevent concurrent poll cycles from overlapping
+let polling = false
+
+// Timer reference for cleanup
+let pollTimer = null
+
+// Track currently executing step to avoid double-dispatch
+let activeStepExecutionId = null
+
+/**
+ * Poll HQ for pending steps and execute them.
+ */
+async function pollOnce() {
+  if (!isHqConfigured()) return
+  if (polling) return
+
+  polling = true
+  try {
+    // 1. Fetch pending steps from HQ
+    const data = await api.request('/pending-steps')
+
+    if (!data.steps || data.steps.length === 0) {
+      return
+    }
+
+    console.log(`[StepPoller] Found ${data.steps.length} pending step(s)`)
+
+    // 2. Process steps one at a time (sequential execution)
+    for (const step of data.steps) {
+      // Skip if we're already executing this step
+      if (activeStepExecutionId === step.step_execution_id) {
+        console.log(`[StepPoller] Step ${step.step_execution_id} already in progress, skipping`)
+        continue
+      }
+
+      await executeStep(step)
+
+      // Only execute one step per poll cycle to avoid overloading
+      break
+    }
+  } catch (err) {
+    // Don't log network errors at error level — they're expected when HQ is temporarily unreachable
+    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+      console.log(`[StepPoller] HQ unreachable, will retry next cycle`)
+    } else {
+      console.error(`[StepPoller] Poll error: ${err.message}`)
+    }
+  } finally {
+    polling = false
+  }
+}
+
+/**
+ * Execute a single pending step:
+ * 1. Claim the step by calling dispatch-self endpoint
+ * 2. Fetch the skill from HQ
+ * 3. Run the skill locally
+ *
+ * @param {object} step - Step info from pending-steps response
+ */
+async function executeStep(step) {
+  const {
+    step_execution_id,
+    execution_id,
+    workflow_name,
+    step_index,
+    skill_version_id,
+    assigned_role,
+    skill_name,
+    revision_feedback,
+  } = step
+
+  console.log(
+    `[StepPoller] Executing step ${step_index} of "${workflow_name}" ` +
+    `(skill: ${skill_name || skill_version_id}, role: ${assigned_role})`
+  )
+
+  activeStepExecutionId = step_execution_id
+
+  try {
+    // 1. Claim the step — tell HQ we're taking it
+    //    This sets status to 'running' and prevents other minions from picking it up
+    try {
+      await api.request('/claim-step', {
+        method: 'POST',
+        body: JSON.stringify({
+          execution_id,
+          step_index,
+        }),
+      })
+    } catch (claimErr) {
+      // 409 means step is no longer pending (already claimed or completed)
+      if (claimErr.statusCode === 409) {
+        console.log(`[StepPoller] Step ${step_index} already claimed, skipping`)
+        return
+      }
+      throw claimErr
+    }
+
+    // 2. Fetch the skill from HQ to ensure it's deployed locally
+    if (skill_name) {
+      try {
+        const fetchUrl = `http://localhost:${config.AGENT_PORT || 8080}/api/skills/fetch/${encodeURIComponent(skill_name)}`
+        const fetchResp = await fetch(fetchUrl, {
+          method: 'POST',
+          headers: { 'Authorization': `Bearer ${config.API_TOKEN}` },
+        })
+        if (!fetchResp.ok) {
+          console.error(`[StepPoller] Skill fetch failed: ${await fetchResp.text()}`)
+        }
+      } catch (fetchErr) {
+        console.error(`[StepPoller] Skill fetch error: ${fetchErr.message}`)
+        // Continue — skill may already be deployed locally
+      }
+    }
+
+    // 3. Run the skill via local API
+    const runPayload = {
+      skill_name,
+      execution_id,
+      step_index,
+      workflow_name,
+      role: assigned_role,
+    }
+    if (revision_feedback) {
+      runPayload.revision_feedback = revision_feedback
+    }
+
+    const runUrl = `http://localhost:${config.AGENT_PORT || 8080}/api/skills/run`
+    const runResp = await fetch(runUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${config.API_TOKEN}`,
+      },
+      body: JSON.stringify(runPayload),
+    })
+
+    if (!runResp.ok) {
+      const errData = await runResp.json().catch(() => ({}))
+      console.error(`[StepPoller] Skill run failed: ${errData.error || runResp.status}`)
+      // Report failure to HQ
+      try {
+        await api.reportStepComplete({
+          workflow_execution_id: execution_id,
+          step_index,
+          status: 'failed',
+          output_summary: `Step poller failed to start skill: ${errData.error || 'unknown error'}`,
+        })
+      } catch (reportErr) {
+        console.error(`[StepPoller] Failed to report step failure: ${reportErr.message}`)
+      }
+      return
+    }
+
+    const runData = await runResp.json()
+    console.log(
+      `[StepPoller] Skill "${skill_name}" started (session: ${runData.session_name}). ` +
+      `Step completion will be reported by the post-execution hook.`
+    )
+  } catch (err) {
+    console.error(`[StepPoller] Failed to execute step ${step_index}: ${err.message}`)
+  } finally {
+    activeStepExecutionId = null
+  }
+}
+
+/**
+ * Start the polling daemon.
+ */
+function start() {
+  if (!isHqConfigured()) {
+    console.log('[StepPoller] HQ not configured, step poller disabled')
+    return
+  }
+
+  // Initial poll after a short delay (let server fully start)
+  setTimeout(() => pollOnce(), 5000)
+
+  // Periodic polling
+  pollTimer = setInterval(() => pollOnce(), POLL_INTERVAL_MS)
+  console.log(`[StepPoller] Started (polling every ${POLL_INTERVAL_MS / 1000}s)`)
+}
+
+/**
+ * Stop the polling daemon.
+ */
+function stop() {
+  if (pollTimer) {
+    clearInterval(pollTimer)
+    pollTimer = null
+    console.log('[StepPoller] Stopped')
+  }
+}
+
+module.exports = { start, stop, pollOnce }

package/core/lib/strip-ansi.js

@@ -0,0 +1,18 @@
+/**
+ * Strip ANSI escape sequences from a string.
+ * Handles CSI sequences, OSC sequences, and other control codes
+ * that terminal emulators (node-pty) produce.
+ */
+
+// Match ANSI escape sequences:
+// - CSI: ESC[ ... (params including <>=:;?) ... (final byte)
+// - OSC: ESC] ... ST (string terminator: ESC\ or BEL, or next ESC)
+// - Other ESC sequences: ESC followed by a character
+// - Standalone control characters (except newline, carriage return, tab)
+const ANSI_REGEX = /(?:\x1B\[[0-9;?<>=:]*[A-Za-z~]|\x1B\][^\x07\x1B]*(?:\x07|\x1B\\|\x1B(?=\[|\]))|\x1B[^[\]()][A-Za-z]?|[\x00-\x08\x0B\x0C\x0E-\x1F\x7F])/g
+
+function stripAnsi(str) {
+  return str.replace(ANSI_REGEX, '')
+}
+
+module.exports = { stripAnsi }