@geekbeer/minion 2.67.1 → 2.68.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "2.67.1",
+  "version": "2.68.1",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/win/lib/process-manager.js

@@ -54,19 +54,114 @@ function detectProcessManager() {
  * @param {string} startCmd - Command/script block to start the agent
  * @returns {string} - Path to the generated update script (.ps1)
  */
-function buildUpdateScript(npmInstallCmd, stopCmd, startCmd, scriptName = 'update-agent') {
-  const dataDir = path.join(os.homedir(), '.minion')
-  const scriptPath = path.join(dataDir, `${scriptName}.ps1`)
-  const logPath = path.join(dataDir, `${scriptName}.log`)
+/**
+ * Generate a PowerShell snippet that requests graceful shutdown via the agent's
+ * HTTP API, then falls back to force-kill. This mirrors Linux's SIGTERM behavior:
+ * the agent runs shutdown() → sends offline heartbeat → exits cleanly.
+ *
+ * Windows has no SIGTERM for console processes, so we use HTTP instead.
+ *
+ * @param {number} agentPort - The agent's HTTP port (default 8080)
+ * @param {string} apiToken - The agent's API token for authentication
+ * @returns {string} PowerShell code block for graceful shutdown
+ */
+function buildGracefulStopBlock(agentPort, apiToken) {
+  return [
+    `  try {`,
+    `    Invoke-RestMethod -Uri 'http://localhost:${agentPort}/api/shutdown' -Method POST ` +
+         `-Headers @{ Authorization = 'Bearer ${apiToken}' } -TimeoutSec 5 | Out-Null`,
+    `    Log 'Graceful shutdown requested, waiting for offline heartbeat...'`,
+    `    Start-Sleep -Seconds 4`,
+    `  } catch {`,
+    `    Log "Graceful shutdown API failed: $_ (will force kill)"`,
+    `  }`,
+  ].join('\n')
+}
 
-  // PowerShell script content: stop → install → start, with logging
-  // The stopCmd kills all child processes of the agent. Since this script
-  // itself is a child of the agent (spawn from Node), we must exclude our
-  // own PID ($PID) to avoid the update script killing itself.
-  const safeStopCmd = stopCmd.replace(
+/**
+ * Apply self-PID exclusion to a stopCmd so that the detached script
+ * does not kill itself when enumerating child processes.
+ */
+function makeSafeStopCmd(stopCmd) {
+  return stopCmd.replace(
     /ForEach-Object\s*\{\s*Stop-Process/,
     'Where-Object { $_.ProcessId -ne $PID } | ForEach-Object { Stop-Process'
   )
+}
+
+/**
+ * Generate a temporary PowerShell restart script that:
+ * 1. Requests graceful shutdown via HTTP API (sends offline heartbeat)
+ * 2. Force-kills remaining processes (fallback)
+ * 3. Restarts the agent
+ *
+ * @param {string} stopCmd - Command/script block to force-stop the agent
+ * @param {string} startCmd - Command/script block to start the agent
+ * @param {number} agentPort - The agent's HTTP port
+ * @param {string} apiToken - The agent's API token
+ * @returns {string} - Path to the generated restart script (.ps1)
+ */
+function buildRestartScript(stopCmd, startCmd, agentPort, apiToken) {
+  const dataDir = path.join(os.homedir(), '.minion')
+  const scriptPath = path.join(dataDir, 'restart-agent.ps1')
+  const logPath = path.join(dataDir, 'restart-agent.log')
+
+  const safeStopCmd = makeSafeStopCmd(stopCmd)
+  const gracefulStop = buildGracefulStopBlock(agentPort, apiToken)
+
+  const ps1 = [
+    `$ErrorActionPreference = 'Stop'`,
+    `$logFile = '${logPath.replace(/\\/g, '\\\\')}'`,
+    `function Log($msg) { "$(Get-Date -Format o) $msg" | Out-File -Append $logFile }`,
+    `Log 'Restart started'`,
+    `try {`,
+    `  Log 'Requesting graceful shutdown...'`,
+    gracefulStop,
+    `  Log 'Force stopping remaining processes...'`,
+    `  ${safeStopCmd}`,
+    `  Start-Sleep -Seconds 2`,
+    `  Log 'Starting agent...'`,
+    `  ${startCmd}`,
+    `  Log 'Restart completed successfully'`,
+    `} catch {`,
+    `  Log "Restart failed: $_"`,
+    `  Log 'Attempting to start agent anyway...'`,
+    `  ${startCmd}`,
+    `}`,
+  ].join('\n')
+
+  try { fs.mkdirSync(dataDir, { recursive: true }) } catch { /* exists */ }
+  fs.writeFileSync(scriptPath, ps1, 'utf-8')
+
+  return scriptPath
+}
+
+/**
+ * Generate a temporary PowerShell script that:
+ * 1. Requests graceful shutdown via HTTP API (sends offline heartbeat)
+ * 2. Force-kills remaining processes (releases DLL file locks)
+ * 3. Runs npm install -g
+ * 4. Restarts the agent
+ *
+ * The force-kill after graceful shutdown is necessary because node-pty's
+ * conpty.node DLL is locked by the running process, causing EBUSY errors
+ * if npm tries to overwrite it in-place.
+ *
+ * @param {string} npmInstallCmd - The npm install command to run
+ * @param {string} stopCmd - Command/script block to stop the agent
+ * @param {string} startCmd - Command/script block to start the agent
+ * @param {string} scriptName - Base name for the .ps1 and .log files
+ * @param {number} agentPort - The agent's HTTP port
+ * @param {string} apiToken - The agent's API token
+ * @returns {string} - Path to the generated update script (.ps1)
+ */
+function buildUpdateScript(npmInstallCmd, stopCmd, startCmd, scriptName = 'update-agent', agentPort = 8080, apiToken = '') {
+  const dataDir = path.join(os.homedir(), '.minion')
+  const scriptPath = path.join(dataDir, `${scriptName}.ps1`)
+  const logPath = path.join(dataDir, `${scriptName}.log`)
+
+  const safeStopCmd = makeSafeStopCmd(stopCmd)
+  const gracefulStop = buildGracefulStopBlock(agentPort, apiToken)
 
   const ps1 = [
     `$ErrorActionPreference = 'Stop'`,
@@ -74,7 +169,9 @@ function buildUpdateScript(npmInstallCmd, stopCmd, startCmd, scriptName = 'updat
     `function Log($msg) { "$(Get-Date -Format o) $msg" | Out-File -Append $logFile }`,
     `Log 'Update started'`,
     `try {`,
-    `  Log 'Stopping agent...'`,
+    `  Log 'Requesting graceful shutdown...'`,
+    gracefulStop,
+    `  Log 'Force stopping remaining processes...'`,
     `  ${safeStopCmd}`,
     `  Start-Sleep -Seconds 3`,
     `  Log 'Installing package...'`,
@@ -103,22 +200,26 @@ function buildUpdateScript(npmInstallCmd, stopCmd, startCmd, scriptName = 'updat
 /**
  * Build allowed commands for the detected process manager.
  * @param {string} procMgr - Process manager type
+ * @param {{ AGENT_PORT?: number, API_TOKEN?: string }} [agentConfig] - Agent config for graceful shutdown
  * @returns {Record<string, { description: string; command: string; deferred?: boolean }>}
  */
-function buildAllowedCommands(procMgr) {
+function buildAllowedCommands(procMgr, agentConfig = {}) {
   const commands = {}
+  const agentPort = agentConfig.AGENT_PORT || 8080
+  const apiToken = agentConfig.API_TOKEN || ''
 
   if (procMgr === 'user-process') {
     const dataDir = path.join(os.homedir(), '.minion')
     const pidFile = path.join(dataDir, 'minion-agent.pid')
     const startScript = path.join(dataDir, 'start-agent.ps1')
 
-    const stopBlock = `$pid = Get-Content '${pidFile}' -ErrorAction SilentlyContinue; if ($pid) { Get-CimInstance Win32_Process -Filter \\"ParentProcessId = $pid\\" -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }; Stop-Process -Id $pid -Force -ErrorAction SilentlyContinue }`
-    const startBlock = `Start-Process powershell -ArgumentList '-ExecutionPolicy Bypass -WindowStyle Hidden -File \\"${startScript}\\"' -WindowStyle Hidden`
+    const stopBlock = `$agentPid = Get-Content '${pidFile}' -ErrorAction SilentlyContinue; if ($agentPid) { Get-CimInstance Win32_Process -Filter ('ParentProcessId = ' + $agentPid) -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }; Stop-Process -Id $agentPid -Force -ErrorAction SilentlyContinue }`
+    const startBlock = `Start-Process powershell -ArgumentList ('-ExecutionPolicy Bypass -WindowStyle Hidden -File \"' + '${startScript}' + '\"') -WindowStyle Hidden`
 
     commands['restart-agent'] = {
       description: 'Restart the minion agent process',
-      command: `powershell -Command "${stopBlock}; Start-Sleep -Seconds 2; ${startBlock}"`,
+      spawnArgs: ['powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File',
+        buildRestartScript(stopBlock, startBlock, agentPort, apiToken)]],
       deferred: true,
     }
     commands['update-agent'] = {
@@ -127,6 +228,9 @@ function buildAllowedCommands(procMgr) {
         'npm install -g @geekbeer/minion@latest',
         stopBlock,
         startBlock,
+        'update-agent',
+        agentPort,
+        apiToken,
       )]],
       deferred: true,
     }
@@ -137,14 +241,17 @@ function buildAllowedCommands(procMgr) {
         stopBlock,
         startBlock,
         'update-agent-dev',
+        agentPort,
+        apiToken,
       )]],
       deferred: true,
     }
     commands['status-services'] = {
       description: 'Show agent process info',
-      command: `powershell -Command "$pidFile = '${pidFile}'; if (Test-Path $pidFile) { $pid = (Get-Content $pidFile -Raw).Trim(); $proc = Get-Process -Id $pid -ErrorAction SilentlyContinue; if ($proc) { Write-Host 'minion-agent: running (PID:' $pid ')' } else { Write-Host 'minion-agent: not running (stale PID)' } } else { Write-Host 'minion-agent: not running' }"`,
+      command: `powershell -Command "$pidFile = '${pidFile}'; if (Test-Path $pidFile) { $agentPid = (Get-Content $pidFile -Raw).Trim(); $proc = Get-Process -Id $agentPid -ErrorAction SilentlyContinue; if ($proc) { Write-Host 'minion-agent: running (PID:' $agentPid ')' } else { Write-Host 'minion-agent: not running (stale PID)' } } else { Write-Host 'minion-agent: not running' }"`,
     }
   } else if (procMgr === 'nssm') {
+    // NSSM handles graceful stop via its own service control, so no HTTP API needed
     commands['restart-agent'] = {
       description: 'Restart the minion agent service',
       command: 'nssm restart minion-agent',
@@ -156,6 +263,9 @@ function buildAllowedCommands(procMgr) {
         'npm install -g @geekbeer/minion@latest',
         'nssm stop minion-agent',
         'nssm start minion-agent',
+        'update-agent',
+        agentPort,
+        apiToken,
       )]],
       deferred: true,
     }
@@ -166,6 +276,8 @@ function buildAllowedCommands(procMgr) {
         'nssm stop minion-agent',
         'nssm start minion-agent',
         'update-agent-dev',
+        agentPort,
+        apiToken,
       )]],
       deferred: true,
     }
@@ -178,6 +290,7 @@ function buildAllowedCommands(procMgr) {
       command: 'nssm status minion-agent & nssm status minion-websockify',
     }
   } else if (procMgr === 'sc') {
+    // sc.exe handles graceful stop via service control, so no HTTP API needed
     commands['restart-agent'] = {
       description: 'Restart the minion agent service',
       command: 'net stop minion-agent & net start minion-agent',
@@ -189,6 +302,9 @@ function buildAllowedCommands(procMgr) {
         'npm install -g @geekbeer/minion@latest',
         'net stop minion-agent',
         'net start minion-agent',
+        'update-agent',
+        agentPort,
+        apiToken,
       )]],
       deferred: true,
     }
@@ -199,6 +315,8 @@ function buildAllowedCommands(procMgr) {
         'net stop minion-agent',
         'net start minion-agent',
         'update-agent-dev',
+        agentPort,
+        apiToken,
       )]],
       deferred: true,
     }

package/win/minion-cli.ps1

@@ -196,10 +196,27 @@ function Stop-MinionProcess {
     $agentPid = (Get-Content $PidFile -Raw).Trim()
     $proc = Get-Process -Id $agentPid -ErrorAction SilentlyContinue
     if ($proc) {
-        # Also stop child processes (node, websockify, cloudflared)
+        # Graceful shutdown via HTTP API (sends offline heartbeat to HQ)
+        # This mirrors Linux's SIGTERM → shutdown() flow.
+        $token = ''
+        if (Test-Path $EnvFile) {
+            $envVars = Read-EnvFile $EnvFile
+            if ($envVars['API_TOKEN']) { $token = $envVars['API_TOKEN'] }
+        }
+        try {
+            $headers = @{}
+            if ($token) { $headers['Authorization'] = "Bearer $token" }
+            Invoke-RestMethod -Uri "$AgentUrl/api/shutdown" -Method POST -Headers $headers -TimeoutSec 5 | Out-Null
+            Write-Host "Graceful shutdown requested, waiting..."
+            Start-Sleep -Seconds 4
+        } catch {
+            Write-Host "Graceful shutdown failed, force stopping..."
+        }
+
+        # Force kill remaining processes (node, websockify, cloudflared)
         Get-CimInstance Win32_Process -Filter "ParentProcessId = $agentPid" -ErrorAction SilentlyContinue |
             ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
-        Stop-Process -Id $agentPid -Force
+        Stop-Process -Id $agentPid -Force -ErrorAction SilentlyContinue
         Write-Host "minion-agent stopped (PID: $agentPid)"
     } else {
         Write-Host "minion-agent was not running (stale PID file)"

package/win/routes/commands.js

@@ -9,10 +9,11 @@ const { promisify } = require('util')
 const execAsync = promisify(exec)
 
 const { verifyToken } = require('../../core/lib/auth')
+const { config } = require('../../core/config')
 const { detectProcessManager, buildAllowedCommands } = require('../lib/process-manager')
 
 const PROC_MGR = detectProcessManager()
-const ALLOWED_COMMANDS = buildAllowedCommands(PROC_MGR)
+const ALLOWED_COMMANDS = buildAllowedCommands(PROC_MGR, config)
 
 async function commandRoutes(fastify) {
   fastify.get('/api/commands', async (request, reply) => {

package/win/server.js

@@ -38,6 +38,7 @@ const revisionWatcher = require('../core/lib/revision-watcher')
 const reflectionScheduler = require('../core/lib/reflection-scheduler')
 const threadWatcher = require('../core/lib/thread-watcher')
 const { commandRoutes, getProcessManager, getAllowedCommands } = require('./routes/commands')
+const { verifyToken } = require('../core/lib/auth')
 const { terminalRoutes, cleanupSessions } = require('./routes/terminal')
 const { startTerminalServer, stopTerminalServer } = require('./terminal-server')
 const { fileRoutes } = require('./routes/files')
@@ -214,6 +215,19 @@ async function registerRoutes(app) {
   await app.register(helpThreadRoutes)
   await app.register(daemonRoutes, { heartbeatStatus: () => ({ running: !!heartbeatTimer, last_beat_at: lastBeatAt }) })
 
+  // Shutdown endpoint — allows detached restart/update scripts to trigger
+  // graceful shutdown (offline heartbeat) before force-killing the process.
+  // Windows has no SIGTERM equivalent for console processes, so this HTTP API
+  // serves the same role that SIGTERM plays on Linux.
+  app.post('/api/shutdown', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+    reply.send({ success: true })
+    setImmediate(() => shutdown('API'))
+  })
+
   // Windows-specific routes
   await app.register(commandRoutes)
   await app.register(terminalRoutes)