@geekbeer/minion 3.16.1 → 3.22.0

package/core/llm-plugins/lib/mcp-registration.js

@@ -0,0 +1,132 @@
+/**
+ * MCP server registration helpers.
+ *
+ * Each LLM CLI stores MCP server configuration in a different file with a
+ * different format. This module hides that variation: callers ask a plugin to
+ * register a server, and the plugin (or a fallback here) writes to the
+ * appropriate location.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { config } = require('../../config')
+
+const DISPATCH_SERVER_NAME = 'minion-llm-dispatch'
+
+/**
+ * Build the spec for the dispatch MCP server used by Primary to reach children.
+ * Plugins register this via {@link registerDispatchServer}.
+ */
+function buildDispatchServerSpec() {
+  const serverScript = path.join(__dirname, '..', '..', 'llm-dispatch', 'mcp-server.js')
+  return {
+    command: 'node',
+    args: [serverScript],
+  }
+}
+
+/**
+ * JSON-config MCP registration (used by Claude Code, Gemini CLI).
+ * Reads the target file, merges in the server entry under `mcpServers`,
+ * and writes back atomically.
+ *
+ * @param {string} configPath
+ * @param {string} serverName
+ * @param {{ command: string, args: string[] }} spec
+ */
+function writeJsonMcpEntry(configPath, serverName, spec) {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true })
+  let current = {}
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8')
+    current = JSON.parse(raw)
+  } catch {
+    // New file or unparseable — start fresh
+  }
+  if (!current.mcpServers || typeof current.mcpServers !== 'object') {
+    current.mcpServers = {}
+  }
+  current.mcpServers[serverName] = spec
+  const tmp = `${configPath}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(current, null, 2), 'utf-8')
+  fs.renameSync(tmp, configPath)
+}
+
+/**
+ * Remove a server entry from a JSON MCP config.
+ */
+function removeJsonMcpEntry(configPath, serverName) {
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8')
+    const current = JSON.parse(raw)
+    if (current?.mcpServers && current.mcpServers[serverName]) {
+      delete current.mcpServers[serverName]
+      const tmp = `${configPath}.tmp`
+      fs.writeFileSync(tmp, JSON.stringify(current, null, 2), 'utf-8')
+      fs.renameSync(tmp, configPath)
+    }
+  } catch {
+    // File missing or unparseable — nothing to remove
+  }
+}
+
+/**
+ * Register the dispatch MCP server with the given Primary plugin.
+ * No-op if the plugin does not implement addMcpServer() or when we don't
+ * know its MCP config location.
+ *
+ * @param {import('../types').LlmPlugin} plugin
+ */
+function registerDispatchServer(plugin) {
+  const spec = buildDispatchServerSpec()
+  if (typeof plugin.addMcpServer === 'function') {
+    plugin.addMcpServer(DISPATCH_SERVER_NAME, spec)
+    return { registered: true, method: 'plugin' }
+  }
+  // Fallback: well-known locations by plugin name
+  const fallbackPath = defaultMcpConfigPath(plugin.name)
+  if (fallbackPath) {
+    writeJsonMcpEntry(fallbackPath, DISPATCH_SERVER_NAME, spec)
+    return { registered: true, method: 'fallback', path: fallbackPath }
+  }
+  return { registered: false }
+}
+
+/**
+ * Unregister the dispatch MCP server from all known plugin MCP configs.
+ * Used when Primary is cleared.
+ */
+function unregisterDispatchServerFromAll(plugins) {
+  for (const p of plugins) {
+    if (typeof p.removeMcpServer === 'function') {
+      try { p.removeMcpServer(DISPATCH_SERVER_NAME) } catch { /* ignore */ }
+      continue
+    }
+    const fallbackPath = defaultMcpConfigPath(p.name)
+    if (fallbackPath) removeJsonMcpEntry(fallbackPath, DISPATCH_SERVER_NAME)
+  }
+}
+
+/** Best-known MCP config path for a given plugin name. Returns null if unknown. */
+function defaultMcpConfigPath(pluginName) {
+  switch (pluginName) {
+    case 'claude':
+      // Claude Code reads ~/.mcp.json (global) and project-local .mcp.json
+      return path.join(config.HOME_DIR, '.mcp.json')
+    case 'gemini':
+      // Gemini CLI settings include mcpServers field
+      return path.join(config.HOME_DIR, '.gemini', 'settings.json')
+    default:
+      return null
+  }
+}
+
+module.exports = {
+  DISPATCH_SERVER_NAME,
+  buildDispatchServerSpec,
+  writeJsonMcpEntry,
+  removeJsonMcpEntry,
+  registerDispatchServer,
+  unregisterDispatchServerFromAll,
+  defaultMcpConfigPath,
+}

package/core/llm-plugins/lib/skill-dirs.js

@@ -0,0 +1,67 @@
+/**
+ * Resolve skill directory paths across enabled LLM plugins.
+ *
+ * Each LLM CLI loads skills from its own directory:
+ *   Claude → ~/.claude/skills/
+ *   Gemini → ~/.gemini/skills/
+ *   Codex  → ~/.codex/skills/
+ *
+ * To make skill deployment LLM-agnostic, we write each skill to all enabled
+ * plugins' skill directories. Reads/deletes operate on the union.
+ */
+
+const path = require('path')
+const { config } = require('../../config')
+const { readConfig, loadAllPlugins } = require('../registry')
+
+/**
+ * Return the canonical skill directory paths for all enabled plugins.
+ * Falls back to ~/.claude/skills/ when the plugin system is not configured
+ * (preserves backward compatibility with the LLM_COMMAND era).
+ *
+ * @returns {string[]} Absolute directory paths
+ */
+function getActiveSkillDirs() {
+  const cfg = readConfig()
+  const enabled = new Set(cfg.enabled)
+
+  if (enabled.size === 0) {
+    return [path.join(config.HOME_DIR, '.claude', 'skills')]
+  }
+
+  const plugins = loadAllPlugins()
+  const dirs = []
+  for (const name of enabled) {
+    const plugin = plugins.get(name)
+    if (plugin && typeof plugin.getSkillsDir === 'function') {
+      dirs.push(plugin.getSkillsDir())
+    }
+  }
+  // Safety: if no enabled plugin reported a dir, default to claude
+  if (dirs.length === 0) {
+    dirs.push(path.join(config.HOME_DIR, '.claude', 'skills'))
+  }
+  return dirs
+}
+
+/**
+ * Get the primary plugin's skill directory (used as the canonical
+ * read source when listing or pushing skills back to HQ).
+ *
+ * @returns {string} Absolute directory path
+ */
+function getPrimarySkillDir() {
+  const cfg = readConfig()
+  if (cfg.primary) {
+    const plugins = loadAllPlugins()
+    const plugin = plugins.get(cfg.primary)
+    if (plugin && typeof plugin.getSkillsDir === 'function') {
+      return plugin.getSkillsDir()
+    }
+  }
+  // Fallback: first enabled plugin's dir, else claude
+  const dirs = getActiveSkillDirs()
+  return dirs[0]
+}
+
+module.exports = { getActiveSkillDirs, getPrimarySkillDir }

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 }