@geekbeer/minion 2.11.1 → 2.16.0

package/bin/hq

@@ -0,0 +1,108 @@
+#!/bin/bash
+# HQ API helper for minion chat context
+#
+# Fetches resource details from the HQ server API.
+# Used by Claude CLI during chat to retrieve information about
+# skills, workflows, and projects that the user is viewing on the dashboard.
+#
+# Environment variables (inherited from minion server):
+#   HQ_URL    - HQ server URL (e.g., https://minion-agent.com)
+#   API_TOKEN - Minion API token for authentication
+#
+# Usage:
+#   hq fetch skill <name>            - Get skill details (content, description, files)
+#   hq fetch workflow <name>         - Get workflow details (pipeline, cron, etc.)
+#   hq fetch project <id>            - Get project info (name, description, role)
+#   hq fetch project-context <id>    - Get project context (shared Markdown document)
+
+set -euo pipefail
+
+# Validate required environment variables
+if [ -z "${HQ_URL:-}" ]; then
+  echo "Error: HQ_URL is not set" >&2
+  exit 1
+fi
+
+if [ -z "${API_TOKEN:-}" ]; then
+  echo "Error: API_TOKEN is not set" >&2
+  exit 1
+fi
+
+BASE_URL="${HQ_URL}/api/minion"
+
+# Pretty-print JSON if jq is available, otherwise output raw
+format_json() {
+  if command -v jq &>/dev/null; then
+    jq .
+  else
+    cat
+  fi
+}
+
+fetch_resource() {
+  local url="$1"
+  local response
+  local http_code
+
+  # Fetch with HTTP status code
+  response=$(curl -s -w "\n%{http_code}" -H "Authorization: Bearer $API_TOKEN" "$url")
+  http_code=$(echo "$response" | tail -1)
+  body=$(echo "$response" | sed '$d')
+
+  if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+    echo "$body" | format_json
+  else
+    echo "Error: HQ API returned HTTP $http_code" >&2
+    echo "$body" >&2
+    exit 1
+  fi
+}
+
+# Main command dispatch
+case "${1:-}" in
+  fetch)
+    resource="${2:-}"
+    identifier="${3:-}"
+
+    if [ -z "$resource" ] || [ -z "$identifier" ]; then
+      echo "Usage: hq fetch {skill|workflow|project|project-context} <identifier>" >&2
+      exit 1
+    fi
+
+    case "$resource" in
+      skill)
+        fetch_resource "$BASE_URL/skills/$identifier"
+        ;;
+      workflow)
+        fetch_resource "$BASE_URL/workflows/$identifier"
+        ;;
+      project)
+        # Fetch all projects and filter by ID
+        response=$(curl -s -H "Authorization: Bearer $API_TOKEN" "$BASE_URL/me/projects")
+        if command -v jq &>/dev/null; then
+          echo "$response" | jq --arg id "$identifier" '.projects[] | select(.id == $id)'
+        else
+          echo "$response" | format_json
+        fi
+        ;;
+      project-context)
+        fetch_resource "$BASE_URL/me/project/$identifier/context"
+        ;;
+      *)
+        echo "Unknown resource: $resource" >&2
+        echo "Usage: hq fetch {skill|workflow|project|project-context} <identifier>" >&2
+        exit 1
+        ;;
+    esac
+    ;;
+  *)
+    echo "HQ API helper for minion chat" >&2
+    echo "" >&2
+    echo "Usage:" >&2
+    echo "  hq fetch skill <name>            - Get skill details" >&2
+    echo "  hq fetch workflow <name>          - Get workflow details" >&2
+    echo "  hq fetch project <id>             - Get project info" >&2
+    echo "  hq fetch project-context <id>     - Get project context" >&2
+    exit 1
+    ;;
+esac

package/chat-store.js

@@ -0,0 +1,106 @@
+/**
+ * Chat Session Store
+ * Persists the active chat session (session_id + messages) to local JSON file.
+ * One active session per minion. Claude CLI manages conversation context via --resume.
+ */
+
+const fs = require('fs').promises
+const path = require('path')
+
+const { config } = require('./config')
+
+const MAX_MESSAGES = 100
+
+/**
+ * Get chat session file path
+ * Uses /opt/minion-agent/ if available, otherwise home dir
+ */
+function getFilePath() {
+  const optPath = '/opt/minion-agent/chat-session.json'
+  try {
+    require('fs').accessSync(path.dirname(optPath))
+    return optPath
+  } catch {
+    return path.join(config.HOME_DIR, 'chat-session.json')
+  }
+}
+
+const SESSION_FILE = getFilePath()
+
+/**
+ * Load the active chat session
+ * @returns {Promise<object|null>} Session object or null if none exists
+ */
+async function load() {
+  try {
+    const data = await fs.readFile(SESSION_FILE, 'utf-8')
+    return JSON.parse(data)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return null
+    }
+    console.error(`[ChatStore] Failed to load session: ${err.message}`)
+    return null
+  }
+}
+
+/**
+ * Save the active chat session
+ * @param {object} session - Session object
+ */
+async function save(session) {
+  try {
+    await fs.writeFile(SESSION_FILE, JSON.stringify(session, null, 2), 'utf-8')
+  } catch (err) {
+    console.error(`[ChatStore] Failed to save session: ${err.message}`)
+  }
+}
+
+/**
+ * Add a message to the active session
+ * Creates a new session if none exists
+ * @param {string} sessionId - Claude CLI session ID
+ * @param {{ role: string, content: string }} msg - Message to add
+ */
+async function addMessage(sessionId, msg) {
+  let session = await load()
+
+  // If session_id changed, start a new session
+  if (!session || session.session_id !== sessionId) {
+    session = {
+      session_id: sessionId,
+      messages: [],
+      created_at: Date.now(),
+      updated_at: Date.now(),
+    }
+  }
+
+  session.messages.push({
+    role: msg.role,
+    content: msg.content,
+    timestamp: Date.now(),
+  })
+  session.updated_at = Date.now()
+
+  // Prune old messages
+  if (session.messages.length > MAX_MESSAGES) {
+    session.messages = session.messages.slice(-MAX_MESSAGES)
+  }
+
+  await save(session)
+}
+
+/**
+ * Clear the active session
+ */
+async function clear() {
+  try {
+    await fs.unlink(SESSION_FILE)
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      console.error(`[ChatStore] Failed to clear session: ${err.message}`)
+    }
+  }
+}
+
+module.exports = { load, save, addMessage, clear }

package/lib/llm-checker.js

@@ -111,4 +111,10 @@ function getLlmServices() {
   return services
 }
 
-module.exports = { getLlmServices }
+/** Clear the cached LLM service status */
+function clearLlmCache() {
+  cachedResult = null
+  cachedAt = 0
+}
+
+module.exports = { getLlmServices, clearLlmCache }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@geekbeer/minion",
-  "version": "2.11.1",
+  "version": "2.16.0",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "server.js",
   "bin": {
-    "minion-cli": "./minion-cli.sh"
+    "minion-cli": "./minion-cli.sh",
+    "hq": "./bin/hq"
   },
   "files": [
     "server.js",
@@ -16,6 +17,7 @@
     "routine-runner.js",
     "routine-store.js",
     "execution-store.js",
+    "chat-store.js",
     "lib/",
     "routes/",
     "skills/",
@@ -23,6 +25,7 @@
     "roles/",
     "docs/",
     "settings/",
+    "bin/",
     "minion-cli.sh",
     ".env.example"
   ],

package/routes/auth.js

@@ -0,0 +1,356 @@
+/**
+ * Authentication management endpoints
+ *
+ * Provides guided LLM authentication flow for non-engineer users.
+ * Uses tmux to run `claude auth login` in a named session that can be:
+ *   - Observed from the terminal: `tmux attach -t claude-auth`
+ *   - Controlled via `tmux send-keys` for reliable key input
+ *   - Read via `tmux capture-pane` for output extraction
+ *
+ * Flow:
+ * 1. POST /api/auth/start  - Start tmux session, navigate menus, extract OAuth URL
+ * 2. User opens URL in their browser, authenticates, receives a code
+ * 3. POST /api/auth/code   - Submit the code to the tmux session
+ * 4. GET  /api/auth/status  - Poll for authentication completion
+ */
+
+const { execSync, exec } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+const { verifyToken } = require('../lib/auth')
+const { getLlmServices, clearLlmCache } = require('../lib/llm-checker')
+const { config } = require('../config')
+
+const TMUX_SESSION = 'claude-auth'
+
+let authInProgress = false
+let authLockTimer = null
+
+/**
+ * Release the auth lock and clean up
+ */
+function releaseAuthLock() {
+  authInProgress = false
+  if (authLockTimer) {
+    clearTimeout(authLockTimer)
+    authLockTimer = null
+  }
+  // Kill tmux session if still running
+  try { execSync(`tmux kill-session -t ${TMUX_SESSION} 2>/dev/null`) } catch {}
+}
+
+/** Strip ANSI escape sequences for readable logging */
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07|\x1b\[\?[0-9;]*[a-zA-Z]/g, '')
+}
+
+/**
+ * Capture the current tmux pane content
+ */
+function captureTmuxPane() {
+  try {
+    return execSync(
+      `tmux capture-pane -t ${TMUX_SESSION} -p -J -S -50`,
+      { encoding: 'utf-8', timeout: 5000 }
+    )
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Check if the tmux session exists
+ */
+function tmuxSessionExists() {
+  try {
+    execSync(`tmux has-session -t ${TMUX_SESSION} 2>/dev/null`)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Extract OAuth URL from tmux pane content
+ */
+function extractUrlFromPane(content) {
+  const urlMatch = content.match(/(https:\/\/[^\s]+)/)
+  return urlMatch ? urlMatch[1] : null
+}
+
+/**
+ * Start Claude Code login in a tmux session.
+ *
+ * Interactive flow:
+ *   1. Theme selection  → send Enter (accept default)
+ *   2. Login method     → send Enter (accept default = Subscription)
+ *   3. OAuth URL output → capture and return
+ *
+ * Uses content-based polling instead of fixed timers so that first-run
+ * CLI initialization delays don't cause Enter keys to be lost.
+ *
+ * Returns a promise that resolves with the OAuth URL.
+ * The tmux session stays alive for code submission.
+ */
+function startClaudeAuth() {
+  return new Promise((resolve, reject) => {
+    // Kill any leftover session
+    try { execSync(`tmux kill-session -t ${TMUX_SESSION} 2>/dev/null`) } catch {}
+
+    console.log('[Auth] Creating tmux session for claude auth login')
+
+    try {
+      // Start claude auth login in a new tmux session
+      // CLAUDECODE='' prevents the nesting check
+      execSync(
+        `tmux new-session -d -s ${TMUX_SESSION} -x 500 -y 40 'CLAUDECODE="" claude auth login'`,
+        { timeout: 5000 }
+      )
+    } catch (err) {
+      reject(new Error(`Failed to create tmux session: ${err.message}`))
+      return
+    }
+
+    console.log('[Auth] tmux session created, polling for menus...')
+
+    // State machine for menu navigation
+    // 'wait_theme'  → waiting for theme selection menu to appear
+    // 'wait_login'  → Enter sent for theme, waiting for login method menu
+    // 'wait_url'    → Enter sent for login method, waiting for OAuth URL
+    let stage = 'wait_theme'
+    let resolved = false
+    let lastContent = ''
+
+    const pollInterval = setInterval(() => {
+      if (resolved) return
+
+      if (!tmuxSessionExists()) {
+        resolved = true
+        clearInterval(pollInterval)
+        reject(new Error('Auth session ended unexpectedly'))
+        return
+      }
+
+      const content = captureTmuxPane()
+      const clean = stripAnsi(content)
+
+      // Check for URL at any stage
+      const url = extractUrlFromPane(content)
+      if (url) {
+        resolved = true
+        clearInterval(pollInterval)
+        console.log(`[Auth] URL found: ${url}`)
+        resolve(url)
+        return
+      }
+
+      if (stage === 'wait_theme') {
+        // Detect theme selection menu: look for "text style" or menu indicators
+        if (clean.match(/text\s*style|theme|dark|light/i) && clean.length > 20) {
+          console.log('[Auth] Theme menu detected, sending Enter #1')
+          try { execSync(`tmux send-keys -t ${TMUX_SESSION} Enter`) } catch {}
+          stage = 'wait_login'
+          lastContent = clean
+        }
+      } else if (stage === 'wait_login') {
+        // Detect login method menu: look for "login" or "subscription" or content change
+        if (clean !== lastContent && (
+          clean.match(/login\s*method|subscription|account|how.*login/i) ||
+          clean.match(/anthropic|console|api\s*key/i) ||
+          // Content changed significantly after Enter — likely new menu
+          clean.length > lastContent.length + 10
+        )) {
+          console.log('[Auth] Login method menu detected, sending Enter #2')
+          try { execSync(`tmux send-keys -t ${TMUX_SESSION} Enter`) } catch {}
+          stage = 'wait_url'
+        }
+      }
+      // stage === 'wait_url': just keep polling for URL (handled above)
+
+    }, 1000)
+
+    // Timeout after 60 seconds (longer for first-run initialization)
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true
+        clearInterval(pollInterval)
+        const content = captureTmuxPane()
+        const clean = stripAnsi(content).trim()
+        console.error(`[Auth] Timed out at stage=${stage}. Pane content: ${clean.slice(0, 500)}`)
+        reject(new Error(
+          `Timed out waiting for auth URL (stage: ${stage}). Output: ${clean.slice(0, 300) || '(none)'}`
+        ))
+      }
+    }, 60000)
+  })
+}
+
+/**
+ * Submit an auth code to the running tmux session.
+ * Types the code and presses Enter.
+ */
+function submitAuthCode(code) {
+  if (!tmuxSessionExists()) {
+    return { success: false, error: 'No auth session running' }
+  }
+
+  try {
+    console.log('[Auth] Submitting auth code to tmux session')
+    // Use send-keys with -l (literal) to avoid interpreting special chars
+    execSync(`tmux send-keys -t ${TMUX_SESSION} -l '${code.replace(/'/g, "'\\''")}'`)
+    execSync(`tmux send-keys -t ${TMUX_SESSION} Enter`)
+    return { success: true }
+  } catch (err) {
+    console.error(`[Auth] Failed to send code: ${err.message}`)
+    return { success: false, error: 'Failed to submit code to auth session' }
+  }
+}
+
+/**
+ * Register auth routes as Fastify plugin
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+async function authRoutes(fastify) {
+
+  // Start LLM authentication flow
+  fastify.post('/api/auth/start', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const { service } = request.body || {}
+    const targetService = service || 'claude'
+
+    if (targetService !== 'claude') {
+      reply.code(400)
+      return { success: false, error: `Unsupported service: ${targetService}` }
+    }
+
+    // Check if already authenticated
+    const services = getLlmServices()
+    const claude = services.find(s => s.name === 'claude')
+    if (claude && claude.authenticated) {
+      return { success: true, already_authenticated: true }
+    }
+
+    // Clean up any previous auth session and start fresh
+    if (authInProgress) {
+      console.log('[Auth] Cleaning up previous auth session')
+      releaseAuthLock()
+    }
+
+    authInProgress = true
+    // Safety timeout — release lock after 5 minutes
+    authLockTimer = setTimeout(releaseAuthLock, 300000)
+
+    console.log('[Auth] Starting Claude Code authentication flow')
+
+    try {
+      const authUrl = await startClaudeAuth()
+      console.log('[Auth] Auth URL obtained successfully')
+      return { success: true, auth_url: authUrl }
+    } catch (err) {
+      console.error(`[Auth] Failed: ${err.message}`)
+      releaseAuthLock()
+      return {
+        success: false,
+        error: err.message,
+        fallback: 'Open Terminal and run: claude auth login',
+      }
+    }
+  })
+
+  // Submit auth code to running session
+  fastify.post('/api/auth/code', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const { code } = request.body || {}
+    if (!code || typeof code !== 'string') {
+      reply.code(400)
+      return { success: false, error: 'Missing auth code' }
+    }
+
+    const result = submitAuthCode(code.trim())
+    if (!result.success) {
+      reply.code(409)
+    }
+    return result
+  })
+
+  // Logout from LLM service
+  fastify.post('/api/auth/logout', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const { service } = request.body || {}
+    const targetService = service || 'claude'
+
+    if (targetService !== 'claude') {
+      reply.code(400)
+      return { success: false, error: `Unsupported service: ${targetService}` }
+    }
+
+    // Delete credential files directly (more reliable than CLI which may be interactive)
+    const credPaths = [
+      path.join(config.HOME_DIR, '.claude', '.credentials.json'),
+      path.join(config.HOME_DIR, '.claude', 'credentials.json'),
+    ]
+
+    let deleted = 0
+    for (const p of credPaths) {
+      try {
+        if (fs.existsSync(p)) {
+          fs.unlinkSync(p)
+          console.log(`[Auth] Deleted: ${p}`)
+          deleted++
+        }
+      } catch (err) {
+        console.error(`[Auth] Failed to delete ${p}: ${err.message}`)
+      }
+    }
+
+    // Clear cached LLM status so next check reflects the change
+    clearLlmCache()
+
+    console.log(`[Auth] Logout completed (${deleted} credential files removed)`)
+    return { success: true }
+  })
+
+  // Get current LLM authentication status (for polling)
+  fastify.get('/api/auth/status', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    // During active auth flow, bypass cache so credential changes are detected immediately
+    if (authInProgress) {
+      clearLlmCache()
+    }
+
+    const services = getLlmServices()
+
+    // Auto-release auth lock when Claude is now authenticated
+    if (authInProgress) {
+      const claude = services.find(s => s.name === 'claude')
+      if (claude && claude.authenticated) {
+        console.log('[Auth] Authentication detected, releasing auth lock')
+        releaseAuthLock()
+      }
+    }
+
+    return {
+      success: true,
+      services,
+      auth_in_progress: authInProgress,
+    }
+  })
+}
+
+module.exports = { authRoutes }

package/routes/chat.js

@@ -0,0 +1,328 @@
+/**
+ * Chat endpoints
+ *
+ * Provides streaming chat with Claude Code CLI using `--resume` sessions.
+ * Messages are sent via POST with SSE response for real-time streaming.
+ * Session state is persisted to local JSON via chat-store.js.
+ *
+ * Endpoints:
+ *   POST   /api/chat          - Send message, get SSE stream
+ *   GET    /api/chat/session   - Get active session (messages + session_id)
+ *   POST   /api/chat/clear     - Clear session and start fresh
+ */
+
+const { spawn } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+const { verifyToken } = require('../lib/auth')
+const { config } = require('../config')
+const chatStore = require('../chat-store')
+
+/**
+ * Register chat routes as Fastify plugin
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+async function chatRoutes(fastify) {
+
+  // POST /api/chat - Send a message and get streaming response
+  fastify.post('/api/chat', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const { message, session_id, context } = request.body || {}
+
+    if (!message || typeof message !== 'string') {
+      reply.code(400)
+      return { success: false, error: 'message is required' }
+    }
+
+    // Build prompt — add context prefix when context is available (new or resumed)
+    const prompt = context
+      ? buildContextPrefix(message, context)
+      : message
+
+    // Store user message
+    const currentSessionId = session_id || null
+    if (currentSessionId) {
+      await chatStore.addMessage(currentSessionId, { role: 'user', content: message })
+    }
+
+    // Take over response handling from Fastify for SSE streaming
+    reply.hijack()
+
+    reply.raw.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+    })
+    reply.raw.flushHeaders()
+
+    try {
+      await streamClaudeResponse(reply.raw, prompt, currentSessionId)
+    } catch (err) {
+      console.error('[Chat] stream error:', err.message)
+      const errorEvent = JSON.stringify({ type: 'error', error: err.message })
+      reply.raw.write(`data: ${errorEvent}\n\n`)
+    }
+
+    reply.raw.end()
+  })
+
+  // GET /api/chat/session - Get active chat session
+  fastify.get('/api/chat/session', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const session = await chatStore.load()
+    if (!session) {
+      return { success: true, session: null }
+    }
+
+    return {
+      success: true,
+      session: {
+        session_id: session.session_id,
+        messages: session.messages,
+        created_at: session.created_at,
+        updated_at: session.updated_at,
+      },
+    }
+  })
+
+  // POST /api/chat/clear - Clear the active session
+  fastify.post('/api/chat/clear', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    await chatStore.clear()
+    return { success: true }
+  })
+}
+
+/**
+ * Build context prefix that tells Claude CLI where the user is on the HQ dashboard
+ * and how to fetch details via the `hq` helper command.
+ * No conversation history injection — Claude CLI handles that via --resume.
+ */
+function buildContextPrefix(message, context) {
+  const parts = []
+
+  if (context) {
+    switch (context.type) {
+      case 'skill':
+        if (context.skillName) {
+          parts.push(
+            `ユーザーはHQダッシュボードでスキル「${context.skillName}」を閲覧しています。`,
+            `スキルの詳細を取得するには以下を実行してください:`,
+            `  hq fetch skill ${context.skillName}`,
+            `取得した内容をもとに回答してください。ローカルファイルを検索する必要はありません。`
+          )
+        }
+        break
+      case 'project':
+        if (context.projectId) {
+          const label = context.projectName
+            ? `プロジェクト「${context.projectName}」(ID: ${context.projectId})`
+            : `プロジェクト (ID: ${context.projectId})`
+          parts.push(
+            `ユーザーはHQダッシュボードで${label}を閲覧しています。`,
+            `プロジェクト情報を取得するには以下を実行してください:`,
+            `  hq fetch project ${context.projectId}`,
+            `  hq fetch project-context ${context.projectId}`,
+            `取得した内容をもとに回答してください。`
+          )
+        }
+        break
+      case 'workflow':
+        if (context.projectId) {
+          const label = context.workflowName
+            ? `ワークフロー「${context.workflowName}」`
+            : 'ワークフロー'
+          parts.push(
+            `ユーザーはHQダッシュボードで${label}を閲覧しています。`,
+            `ワークフロー情報を取得するには以下を実行してください:`,
+            `  hq fetch workflow ${context.workflowName || context.workflowId}`,
+            `プロジェクトコンテキスト:`,
+            `  hq fetch project-context ${context.projectId}`,
+            `取得した内容をもとに回答してください。`
+          )
+        }
+        break
+    }
+  }
+
+  if (parts.length > 0) {
+    return `${parts.join('\n')}\n\n${message}`
+  }
+
+  return message
+}
+
+/**
+ * Stream Claude Code CLI output as SSE events.
+ * Uses --resume to continue existing sessions.
+ */
+function streamClaudeResponse(res, prompt, sessionId) {
+  return new Promise((resolve, reject) => {
+    const claudePath = path.join(config.HOME_DIR, '.local', 'bin', 'claude')
+    const claudeBin = fs.existsSync(claudePath) ? claudePath : 'claude'
+
+    const extendedPath = [
+      `${config.HOME_DIR}/bin`,
+      `${config.HOME_DIR}/.npm-global/bin`,
+      `${config.HOME_DIR}/.local/bin`,
+      `${config.HOME_DIR}/.claude/bin`,
+      '/usr/local/bin',
+      '/usr/bin',
+      '/bin',
+    ].join(':')
+
+    // Build CLI args
+    const args = [
+      '-p',
+      '--verbose',
+      '--output-format', 'stream-json',
+      '--max-turns', '10',
+    ]
+
+    // Resume existing session
+    if (sessionId) {
+      args.push('--resume', sessionId)
+    }
+
+    args.push(prompt)
+
+    console.log(`[Chat] spawning: ${claudeBin} ${sessionId ? `--resume ${sessionId}` : '(new session)'} (cwd: ${config.HOME_DIR})`)
+
+    const child = spawn(claudeBin, args, {
+      cwd: config.HOME_DIR,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 300000, // 5 min
+      env: {
+        ...process.env,
+        HOME: config.HOME_DIR,
+        PATH: extendedPath,
+        DISPLAY: ':99',
+      },
+    })
+
+    // Close stdin immediately so CLI doesn't wait for input
+    child.stdin.end()
+
+    console.log(`[Chat] child PID: ${child.pid}`)
+
+    let fullResponse = ''
+    let stderrBuffer = ''
+    let lineBuffer = ''
+    let resolvedSessionId = sessionId || null
+
+    child.stdout.on('data', (data) => {
+      lineBuffer += data.toString()
+      const parts = lineBuffer.split('\n')
+      // Keep the last (potentially incomplete) line in the buffer
+      lineBuffer = parts.pop() || ''
+
+      for (const line of parts) {
+        if (!line.trim()) continue
+        try {
+          const parsed = JSON.parse(line)
+
+          // system init event — capture session_id
+          if (parsed.type === 'system' && parsed.session_id) {
+            resolvedSessionId = parsed.session_id
+            console.log(`[Chat] session_id: ${resolvedSessionId}`)
+          }
+
+          // assistant message content blocks
+          if (parsed.type === 'assistant' && parsed.message) {
+            for (const block of (parsed.message.content || [])) {
+              if (block.type === 'text') {
+                fullResponse += block.text
+                const event = JSON.stringify({ type: 'text', content: block.text })
+                res.write(`data: ${event}\n\n`)
+              }
+            }
+          } else if (parsed.type === 'content_block_delta') {
+            const delta = parsed.delta?.text || ''
+            if (delta) {
+              fullResponse += delta
+              const event = JSON.stringify({ type: 'delta', content: delta })
+              res.write(`data: ${event}\n\n`)
+            }
+          } else if (parsed.type === 'result') {
+            // result event — send as 'result' type for frontend to use as final text
+            const resultText = parsed.result || ''
+            if (resultText) {
+              const event = JSON.stringify({ type: 'result', content: resultText })
+              res.write(`data: ${event}\n\n`)
+              fullResponse = resultText
+            }
+            // If max turns was reached, notify frontend
+            if (parsed.subtype === 'error_max_turns' && !resultText) {
+              const event = JSON.stringify({ type: 'error', error: 'Max turns reached — response may be incomplete' })
+              res.write(`data: ${event}\n\n`)
+            }
+          }
+        } catch {
+          // Non-JSON line — ignore
+          console.warn(`[Chat] ignoring non-JSON line: ${line.substring(0, 80)}`)
+        }
+      }
+    })
+
+    child.stderr.on('data', (data) => {
+      const text = data.toString()
+      stderrBuffer += text
+      console.error(`[Chat] stderr: ${text}`)
+    })
+
+    child.on('close', async (code) => {
+      // Store messages in chat-store
+      if (resolvedSessionId) {
+        // If this was a new session, also store the user message now
+        if (!sessionId) {
+          await chatStore.addMessage(resolvedSessionId, { role: 'user', content: prompt })
+        }
+        // Store assistant response
+        if (fullResponse) {
+          await chatStore.addMessage(resolvedSessionId, { role: 'assistant', content: fullResponse })
+        }
+      }
+
+      // If exit code is non-zero and no response was generated, send error
+      if (code !== 0 && !fullResponse) {
+        const errorMsg = stderrBuffer.trim() || `Claude CLI exited with code ${code}`
+        console.error(`[Chat] CLI failed (exit ${code}): ${errorMsg}`)
+        const errorEvent = JSON.stringify({ type: 'error', error: errorMsg })
+        res.write(`data: ${errorEvent}\n\n`)
+      }
+
+      const doneEvent = JSON.stringify({
+        type: 'done',
+        session_id: resolvedSessionId,
+      })
+      res.write(`data: ${doneEvent}\n\n`)
+      resolve()
+    })
+
+    child.on('error', (err) => {
+      console.error(`[Chat] spawn error: ${err.message}`)
+      const errorEvent = JSON.stringify({ type: 'error', error: `Failed to start Claude CLI: ${err.message}` })
+      res.write(`data: ${errorEvent}\n\n`)
+      reject(err)
+    })
+
+    // Handle client disconnect
+    res.on('close', () => {
+      child.kill('SIGTERM')
+    })
+  })
+}
+
+module.exports = { chatRoutes }

package/routes/index.js

@@ -51,6 +51,15 @@
  *
  * Directives (routes/directives.js)
  *   POST /api/directive             - Receive and execute a temp skill directive (auth required)
+ *
+ * Auth (routes/auth.js)
+ *   POST /api/auth/start            - Start LLM authentication flow (auth required)
+ *   GET  /api/auth/status           - Get LLM authentication status (auth required)
+ *
+ * Chat (routes/chat.js)
+ *   POST   /api/chat                  - Send message, get SSE stream (auth required)
+ *   GET    /api/chat/session           - Get active session (auth required)
+ *   POST   /api/chat/clear             - Clear session (auth required)
  * ─────────────────────────────────────────────────────────────────────────────
  */
 
@@ -62,6 +71,8 @@ const { routineRoutes } = require('./routines')
 const { terminalRoutes } = require('./terminal')
 const { fileRoutes } = require('./files')
 const { directiveRoutes } = require('./directives')
+const { authRoutes } = require('./auth')
+const { chatRoutes } = require('./chat')
 
 /**
  * Register all routes with Fastify instance
@@ -76,6 +87,8 @@ async function registerRoutes(fastify) {
   await fastify.register(terminalRoutes)
   await fastify.register(fileRoutes)
   await fastify.register(directiveRoutes)
+  await fastify.register(authRoutes)
+  await fastify.register(chatRoutes)
 }
 
 module.exports = {