@geekbeer/minion 3.17.0 → 3.22.0

package/core/llm-plugins/lib/spawn-helper.js

@@ -0,0 +1,88 @@
+/**
+ * Shared helpers for plugin implementations that wrap a local LLM CLI.
+ *
+ * The key goal here is to NEVER pass the prompt through shell string
+ * interpolation. Prompts go through stdin or argv arrays — this avoids the
+ * entire class of quote-escaping bugs that plagued LLM_COMMAND.
+ */
+
+const { spawn } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+const { buildExtendedPath, IS_WINDOWS } = require('../../lib/platform')
+
+/**
+ * Resolve a binary name to an absolute path if installed in ~/.local/bin,
+ * otherwise return the bare name (PATH lookup).
+ */
+function resolveBinary(binaryName, homeDir) {
+  const candidate = path.join(homeDir, '.local', 'bin', binaryName)
+  if (!IS_WINDOWS && fs.existsSync(candidate)) return candidate
+  return binaryName
+}
+
+/**
+ * Spawn a CLI, pass the prompt via stdin, collect stdout/stderr, resolve with
+ * the full output. Never uses shell interpolation.
+ *
+ * @param {Object} opts
+ * @param {string} opts.binary
+ * @param {string[]} opts.args
+ * @param {string} opts.prompt
+ * @param {string} opts.homeDir
+ * @param {Object} [opts.env]
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<{ stdout: string, stderr: string, code: number, durationMs: number }>}
+ */
+function spawnWithStdin({ binary, args, prompt, homeDir, env = {}, timeoutMs = 30 * 60 * 1000 }) {
+  return new Promise((resolve, reject) => {
+    const started = Date.now()
+    const child = spawn(binary, args, {
+      cwd: homeDir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        HOME: homeDir,
+        ...(IS_WINDOWS && { USERPROFILE: homeDir }),
+        PATH: buildExtendedPath(homeDir),
+        ...env,
+      },
+    })
+
+    let stdout = ''
+    let stderr = ''
+    let timedOut = false
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill('SIGTERM')
+    }, timeoutMs)
+
+    child.stdout.on('data', d => { stdout += d.toString('utf-8') })
+    child.stderr.on('data', d => { stderr += d.toString('utf-8') })
+
+    child.on('error', err => {
+      clearTimeout(timer)
+      reject(err)
+    })
+
+    child.on('close', code => {
+      clearTimeout(timer)
+      if (timedOut) {
+        reject(new Error(`Plugin invocation timed out after ${timeoutMs}ms`))
+        return
+      }
+      resolve({ stdout, stderr, code: code ?? -1, durationMs: Date.now() - started })
+    })
+
+    try {
+      child.stdin.write(prompt)
+      child.stdin.end()
+    } catch (err) {
+      clearTimeout(timer)
+      reject(err)
+    }
+  })
+}
+
+module.exports = { resolveBinary, spawnWithStdin }

package/core/llm-plugins/registry.js

@@ -0,0 +1,168 @@
+/**
+ * LLM Plugin Registry
+ *
+ * Loads builtin plugins (claude, gemini, codex) and any user plugins installed
+ * under ~/minion/llm/plugins/<name>/index.js. Persists primary/enabled selection
+ * in ~/minion/llm/config.json, read from file on every access (no env var
+ * caching — avoids the supervisord quote-corruption class of bug).
+ *
+ * This module is intentionally isolated from the existing LLM_COMMAND code path.
+ * It is a no-op at runtime unless a plugin config.json exists with a `primary`
+ * field set.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { config } = require('../config')
+
+const BUILTIN_NAMES = ['claude', 'gemini', 'codex']
+
+/** Resolve the plugin root directory for this minion. */
+function getPluginRoot() {
+  return path.join(config.HOME_DIR, 'minion', 'llm')
+}
+
+/** Resolve the plugin config.json path. */
+function getConfigPath() {
+  return path.join(getPluginRoot(), 'config.json')
+}
+
+/** Resolve the user plugins directory. */
+function getUserPluginsDir() {
+  return path.join(getPluginRoot(), 'plugins')
+}
+
+/**
+ * Load the plugin system config.
+ * @returns {{ primary: string | null, enabled: string[] }}
+ */
+function readConfig() {
+  try {
+    const raw = fs.readFileSync(getConfigPath(), 'utf-8')
+    const parsed = JSON.parse(raw)
+    return {
+      primary: typeof parsed.primary === 'string' ? parsed.primary : null,
+      enabled: Array.isArray(parsed.enabled) ? parsed.enabled.filter(n => typeof n === 'string') : [],
+    }
+  } catch {
+    return { primary: null, enabled: [] }
+  }
+}
+
+/**
+ * Persist the plugin system config atomically.
+ * @param {{ primary: string | null, enabled: string[] }} cfg
+ */
+function writeConfig(cfg) {
+  const dir = getPluginRoot()
+  fs.mkdirSync(dir, { recursive: true })
+  const payload = {
+    primary: cfg.primary ?? null,
+    enabled: Array.isArray(cfg.enabled) ? cfg.enabled : [],
+  }
+  const target = getConfigPath()
+  const tmp = `${target}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf-8')
+  fs.renameSync(tmp, target)
+}
+
+/** @returns {import('./types').LlmPlugin | null} */
+function tryLoad(modulePath) {
+  try {
+    // Clear require cache so hot-added plugins are picked up on reload.
+    delete require.cache[require.resolve(modulePath)]
+    const mod = require(modulePath)
+    const plugin = mod && mod.plugin ? mod.plugin : mod
+    if (!plugin || typeof plugin.name !== 'string') return null
+    return plugin
+  } catch (err) {
+    console.error(`[LlmPlugin] Failed to load ${modulePath}: ${err.message}`)
+    return null
+  }
+}
+
+/**
+ * Discover and load all available plugins (builtins + user-installed).
+ * @returns {Map<string, import('./types').LlmPlugin>}
+ */
+function loadAllPlugins() {
+  const plugins = new Map()
+
+  for (const name of BUILTIN_NAMES) {
+    const p = tryLoad(path.join(__dirname, name))
+    if (p) plugins.set(p.name, p)
+  }
+
+  const userDir = getUserPluginsDir()
+  try {
+    const entries = fs.readdirSync(userDir, { withFileTypes: true })
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue
+      const p = tryLoad(path.join(userDir, ent.name))
+      if (p) plugins.set(p.name, p)
+    }
+  } catch {
+    // No user plugins directory — not an error
+  }
+
+  return plugins
+}
+
+/**
+ * Check whether the plugin system is enabled (opt-in).
+ * Returns false when no config.json exists or primary is unset.
+ */
+function isEnabled() {
+  const cfg = readConfig()
+  return !!cfg.primary
+}
+
+/**
+ * List all available plugins with runtime status.
+ */
+async function listPlugins() {
+  const cfg = readConfig()
+  const plugins = loadAllPlugins()
+  const out = []
+  for (const p of plugins.values()) {
+    let authenticated = false
+    try {
+      authenticated = await p.isAuthenticated()
+    } catch {
+      // Treat as not authenticated
+    }
+    out.push({
+      name: p.name,
+      displayName: p.displayName,
+      capabilities: p.capabilities,
+      authenticated,
+      builtin: BUILTIN_NAMES.includes(p.name),
+      enabled: cfg.enabled.includes(p.name),
+      primary: cfg.primary === p.name,
+    })
+  }
+  return out
+}
+
+/**
+ * Resolve a plugin by name.
+ * @param {string} name
+ * @returns {import('./types').LlmPlugin | null}
+ */
+function getPlugin(name) {
+  const plugins = loadAllPlugins()
+  return plugins.get(name) ?? null
+}
+
+module.exports = {
+  BUILTIN_NAMES,
+  getPluginRoot,
+  getConfigPath,
+  getUserPluginsDir,
+  readConfig,
+  writeConfig,
+  loadAllPlugins,
+  listPlugins,
+  getPlugin,
+  isEnabled,
+}

package/core/llm-plugins/types.js

@@ -0,0 +1,85 @@
+/**
+ * LLM Plugin System — Type definitions (JSDoc)
+ *
+ * Every LLM plugin must implement the LlmPlugin contract. Plugins can act as
+ * either the Primary (user-facing) session or as a Child (specialist) session
+ * dispatched from the Primary via the dispatch MCP server.
+ *
+ * See: packages/docs-internal/src/content/docs/design/llm-plugin-system.md
+ */
+
+/**
+ * @typedef {Object} LlmCapabilities
+ * @property {boolean} toolUse           Can act as Primary (dispatches to children)
+ * @property {boolean} streaming         Supports SSE-style streaming output
+ * @property {boolean} vision            Accepts image inputs
+ * @property {boolean} imageGeneration   Produces image outputs
+ * @property {boolean} sessionResume     Supports resuming an existing session
+ */
+
+/**
+ * @typedef {Object} LlmAttachment
+ * @property {string} path
+ * @property {string} mimeType
+ */
+
+/**
+ * @typedef {Object} LlmInput
+ * @property {string} prompt
+ * @property {string} [systemPrompt]
+ * @property {LlmAttachment[]} [attachments]
+ * @property {string} [model]
+ * @property {string[]} [mcpServers]       Primary only: MCP servers to wire up
+ * @property {number} [timeoutMs]
+ */
+
+/**
+ * @typedef {Object} LlmOutputFile
+ * @property {string} path                Absolute path on minion FS
+ * @property {string} mimeType
+ * @property {string} [purpose]           e.g. "hero_image", "component_source"
+ */
+
+/**
+ * @typedef {Object} LlmOutputMetadata
+ * @property {string} [sessionId]
+ * @property {number} durationMs
+ * @property {{ input: number, output: number }} [tokensUsed]
+ */
+
+/**
+ * @typedef {Object} LlmOutputError
+ * @property {string} code
+ * @property {string} message
+ */
+
+/**
+ * @typedef {Object} LlmOutput
+ * @property {string} text
+ * @property {LlmOutputFile[]} files
+ * @property {LlmOutputMetadata} metadata
+ * @property {LlmOutputError} [error]
+ */
+
+/**
+ * @typedef {Object} LlmEvent
+ * @property {string} type            "text" | "tool_use" | "tool_result" | "done" | "error"
+ * @property {string} [text]
+ * @property {*} [data]
+ */
+
+/**
+ * @typedef {Object} LlmPlugin
+ * @property {string} name                     Unique identifier (e.g. "claude")
+ * @property {string} displayName              Human-readable name
+ * @property {LlmCapabilities} capabilities
+ * @property {() => Promise<boolean>} isAuthenticated
+ * @property {(input: LlmInput) => Promise<LlmOutput>} invoke
+ * @property {(input: LlmInput, onEvent: (e: LlmEvent) => void, ctx?: any) => Promise<LlmOutput>} [stream]
+ * @property {(sessionId: string, input: LlmInput) => Promise<LlmOutput>} [resume]
+ * @property {(opts: { promptFile: string, model?: string }) => string} [buildShellInvocation]   Build a shell command that runs this LLM. The prompt is passed via file redirection to avoid shell quoting issues. Used by workflow/routine runners.
+ * @property {() => string} [getSkillsDir]     Absolute path to the skills directory for this plugin (e.g. ~/.claude/skills)
+ * @property {(skillName: string, args?: string[]) => string} [formatSkillInvocation]   Render a skill invocation in the syntax this plugin understands (e.g. "/skill-name" for Claude/Codex, natural language for Gemini)
+ */
+
+module.exports = {}

package/core/routes/llm.js

@@ -0,0 +1,89 @@
+/**
+ * LLM plugin management routes (shared between Linux and Windows)
+ *
+ *   GET  /api/llm/plugins   - List available plugins with capabilities & auth status
+ *   GET  /api/llm/config    - Get current primary/enabled selection
+ *   PUT  /api/llm/config    - Update primary/enabled selection
+ *
+ * All endpoints require Bearer token authentication.
+ *
+ * This system is opt-in: when no primary is set, the existing LLM_COMMAND
+ * code path continues to operate unchanged.
+ */
+
+const { verifyToken } = require('../lib/auth')
+const { listPlugins, readConfig, writeConfig, loadAllPlugins, getPlugin } = require('../llm-plugins/registry')
+const { registerDispatchServer, unregisterDispatchServerFromAll } = require('../llm-plugins/lib/mcp-registration')
+
+function llmRoutes(fastify, _opts, done) {
+  fastify.get('/api/llm/plugins', async (request, reply) => {
+    if (!verifyToken(request)) {
+      return reply.code(401).send({ error: 'Unauthorized' })
+    }
+    const plugins = await listPlugins()
+    return { success: true, plugins }
+  })
+
+  fastify.get('/api/llm/config', async (request, reply) => {
+    if (!verifyToken(request)) {
+      return reply.code(401).send({ error: 'Unauthorized' })
+    }
+    return { success: true, config: readConfig() }
+  })
+
+  fastify.put('/api/llm/config', async (request, reply) => {
+    if (!verifyToken(request)) {
+      return reply.code(401).send({ error: 'Unauthorized' })
+    }
+    const body = request.body || {}
+    const primary = body.primary === null ? null : (typeof body.primary === 'string' ? body.primary : undefined)
+    const enabled = Array.isArray(body.enabled) ? body.enabled.filter(n => typeof n === 'string') : undefined
+
+    if (primary === undefined && enabled === undefined) {
+      return reply.code(400).send({ error: 'primary or enabled is required' })
+    }
+
+    const current = readConfig()
+    const next = {
+      primary: primary === undefined ? current.primary : primary,
+      enabled: enabled === undefined ? current.enabled : enabled,
+    }
+
+    if (next.primary !== null) {
+      const plugins = loadAllPlugins()
+      if (!plugins.has(next.primary)) {
+        return reply.code(400).send({ error: `Unknown plugin: ${next.primary}` })
+      }
+    }
+
+    try {
+      writeConfig(next)
+
+      // Sync MCP dispatch server registration with the new primary.
+      try {
+        const allPlugins = [...loadAllPlugins().values()]
+        if (next.primary) {
+          const primaryPlugin = getPlugin(next.primary)
+          if (primaryPlugin) {
+            // Clear from non-primary plugins first so we don't leave stale entries.
+            unregisterDispatchServerFromAll(allPlugins.filter(p => p.name !== next.primary))
+            registerDispatchServer(primaryPlugin)
+          }
+        } else {
+          unregisterDispatchServerFromAll(allPlugins)
+        }
+      } catch (regErr) {
+        console.error('[LLM] MCP server registration failed:', regErr.message)
+        // Non-fatal — config is still saved
+      }
+
+      return { success: true, config: next }
+    } catch (err) {
+      return reply.code(500).send({ error: `Failed to write config: ${err.message}` })
+    }
+  })
+
+  done()
+}
+
+module.exports = { llmRoutes }

package/core/routes/skills.js

@@ -19,6 +19,8 @@ const api = require('../api')
 const { config, isHqConfigured } = require('../config')
 const executionStore = require('../stores/execution-store')
 const logManager = require('../lib/log-manager')
+const { reportDagNodeComplete } = require('../lib/dag-node-executor')
+const { getActiveSkillDirs, getPrimarySkillDir } = require('../llm-plugins/lib/skill-dirs')
 
 /**
  * Parse YAML frontmatter from SKILL.md content
@@ -40,8 +42,12 @@ function parseFrontmatter(content) {
 }
 
 /**
- * Write a skill to the local ~/.claude/skills/ directory.
- * Shared by deploy-skill and skills/fetch endpoints.
+ * Write a skill to the local skill directories of all enabled LLM plugins.
+ *
+ * Multi-plugin distribution: each LLM CLI loads skills from its own dir
+ * (e.g. ~/.claude/skills/, ~/.gemini/skills/). The same skill content is
+ * written to every enabled plugin's directory so switching Primary doesn't
+ * break skill availability.
  *
  * @param {string} name - Skill slug (e.g. "execution-report")
  * @param {object} opts
@@ -49,15 +55,9 @@ function parseFrontmatter(content) {
  * @param {string} [opts.description] - Skill description for frontmatter
  * @param {string} [opts.display_name] - Display name for frontmatter
  * @param {Array<{path: string, content?: string}>} [opts.files] - Skill files from HQ storage
- * @returns {Promise<{path: string, files_count: number}>}
+ * @returns {Promise<{path: string, paths: string[], files_count: number}>}
  */
 async function writeSkillToLocal(name, { content, description, display_name, type, files = [] }) {
-  const skillDir = path.join(config.HOME_DIR, '.claude', 'skills', name)
-  const filesDir = path.join(skillDir, 'files')
-
-  await fs.mkdir(skillDir, { recursive: true })
-  await fs.mkdir(filesDir, { recursive: true })
-
   // If content already has frontmatter, write as-is; otherwise build frontmatter
   const hasFrontmatter = content.startsWith('---\n')
   let fileContent
@@ -73,21 +73,30 @@ async function writeSkillToLocal(name, { content, description, display_name, typ
     fileContent = `---\n${frontmatterLines}\n---\n\n${content}`
   }
 
-  await fs.writeFile(
-    path.join(skillDir, 'SKILL.md'),
-    fileContent,
-    'utf-8'
-  )
-
-  // Write skill files
-  for (const file of files) {
-    if (file.path && file.content) {
-      const safeFilename = path.basename(file.path)
-      await fs.writeFile(path.join(filesDir, safeFilename), file.content, 'utf-8')
+  const targetRoots = getActiveSkillDirs()
+  const writtenPaths = []
+
+  for (const root of targetRoots) {
+    const skillDir = path.join(root, name)
+    const filesDir = path.join(skillDir, 'files')
+    await fs.mkdir(skillDir, { recursive: true })
+    await fs.mkdir(filesDir, { recursive: true })
+    await fs.writeFile(path.join(skillDir, 'SKILL.md'), fileContent, 'utf-8')
+
+    for (const file of files) {
+      if (file.path && file.content) {
+        const safeFilename = path.basename(file.path)
+        await fs.writeFile(path.join(filesDir, safeFilename), file.content, 'utf-8')
+      }
     }
+    writtenPaths.push(skillDir)
   }
 
-  return { path: skillDir, files_count: files.length }
+  return {
+    path: writtenPaths[0],
+    paths: writtenPaths,
+    files_count: files.length,
+  }
 }
 
 /**
@@ -99,8 +108,10 @@ async function writeSkillToLocal(name, { content, description, display_name, typ
  * @throws {Error} If skill not found locally or HQ rejects
  */
 async function pushSkillToHQ(name) {
-  const homeDir = config.HOME_DIR
-  const skillDir = path.join(homeDir, '.claude', 'skills', name)
+  // Use the Primary plugin's skill directory as the canonical read source.
+  // Skills are written identically to every enabled plugin dir, so reading
+  // from any one of them yields the same content.
+  const skillDir = path.join(getPrimarySkillDir(), name)
   const skillMdPath = path.join(skillDir, 'SKILL.md')
 
   const rawContent = await fs.readFile(skillMdPath, 'utf-8')
@@ -158,34 +169,29 @@ async function skillRoutes(fastify, opts) {
     console.log('[Skills] Listing deployed skills')
 
     try {
-      const homeDir = config.HOME_DIR
-      const skillsDir = path.join(homeDir, '.claude', 'skills')
-
-      // Check if skills directory exists
-      try {
-        await fs.access(skillsDir)
-      } catch {
-        // Directory doesn't exist, return empty list
-        console.log('[Skills] Skills directory does not exist, returning empty list')
-        return { success: true, skills: [] }
-      }
-
-      // Read directory contents
-      const entries = await fs.readdir(skillsDir, { withFileTypes: true })
-
-      // Filter to only directories that contain SKILL.md
-      const skills = []
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
+      // Union of skills across all active plugin skill dirs.
+      // Same skill name may exist in multiple dirs (multi-plugin distribution);
+      // dedupe via Set.
+      const skillsSet = new Set()
+      for (const skillsDir of getActiveSkillDirs()) {
+        try {
+          await fs.access(skillsDir)
+        } catch {
+          continue
+        }
+        const entries = await fs.readdir(skillsDir, { withFileTypes: true })
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue
           const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md')
           try {
             await fs.access(skillMdPath)
-            skills.push(entry.name)
+            skillsSet.add(entry.name)
           } catch {
-            // SKILL.md doesn't exist, skip this directory
+            // SKILL.md missing, skip
           }
         }
       }
+      const skills = [...skillsSet]
 
       console.log(`[Skills] Found ${skills.length} deployed skills: ${skills.join(', ') || '(none)'}`)
 
@@ -311,16 +317,23 @@ async function skillRoutes(fastify, opts) {
       return { success: false, error: 'Unauthorized' }
     }
 
-    const { skill_name, execution_id, step_index, workflow_name, role, revision_feedback } = request.body || {}
+    const {
+      skill_name,
+      execution_id,
+      step_index,
+      workflow_name,
+      role,
+      revision_feedback,
+      dag_node_execution_id,
+    } = request.body || {}
 
     if (!skill_name) {
       reply.code(400)
       return { success: false, error: 'skill_name is required' }
     }
 
-    // Verify skill exists locally
-    const homeDir = config.HOME_DIR
-    const skillMdPath = path.join(homeDir, '.claude', 'skills', skill_name, 'SKILL.md')
+    // Verify skill exists locally (any plugin's dir is sufficient)
+    const skillMdPath = path.join(getPrimarySkillDir(), skill_name, 'SKILL.md')
     try {
       await fs.access(skillMdPath)
     } catch {
@@ -419,6 +432,44 @@ async function skillRoutes(fastify, opts) {
             console.error(`[Skills] Failed to report step completion: ${hookErr.message}`)
           }
         }
+
+        // Post-execution hook: report DAG node completion to HQ
+        if (dag_node_execution_id) {
+          try {
+            let summary = null
+            let details = null
+            try {
+              const execRecord = await executionStore.getById(effectiveExecutionId)
+              if (execRecord) {
+                summary = execRecord.summary || null
+                details = execRecord.details || null
+              }
+            } catch (readErr) {
+              console.error(`[Skills] Failed to read execution report for DAG node: ${readErr.message}`)
+            }
+
+            await reportDagNodeComplete(
+              dag_node_execution_id,
+              success ? 'completed' : 'failed',
+              summary,
+              details
+            )
+            console.log(`[Skills] DAG node completion reported: ${dag_node_execution_id} → ${success ? 'completed' : 'failed'}`)
+          } catch (hookErr) {
+            console.error(`[Skills] Failed to report DAG node completion: ${hookErr.message}`)
+          }
+
+          // Clean up ephemeral transform skill directory (created by dag-step-poller)
+          if (skill_name.startsWith('_dag_transform_')) {
+            for (const root of getActiveSkillDirs()) {
+              try {
+                await fs.rm(path.join(root, skill_name), { recursive: true, force: true })
+              } catch {
+                // best-effort cleanup
+              }
+            }
+          }
+        }
       }
     })()
 
@@ -458,20 +509,24 @@ async function skillRoutes(fastify, opts) {
     console.log(`[Skills] Deleting skill: ${name}`)
 
     try {
-      const homeDir = config.HOME_DIR
-      const skillDir = path.join(homeDir, '.claude', 'skills', name)
+      // Delete from every active plugin's skill dir
+      let foundAny = false
+      for (const root of getActiveSkillDirs()) {
+        const skillDir = path.join(root, name)
+        try {
+          await fs.access(skillDir)
+          await fs.rm(skillDir, { recursive: true, force: true })
+          foundAny = true
+        } catch {
+          // not present in this dir
+        }
+      }
 
-      // Check if skill exists
-      try {
-        await fs.access(skillDir)
-      } catch {
+      if (!foundAny) {
         reply.code(404)
         return { success: false, error: 'Skill not found' }
       }
 
-      // Recursively delete the skill directory
-      await fs.rm(skillDir, { recursive: true, force: true })
-
       console.log(`[Skills] Skill deleted successfully: ${name}`)
 
       return {