agentboss 0.1.0

package/server/execution/job.js

@@ -0,0 +1,662 @@
+/**
+ * Execution job orchestration.
+ *
+ * Coordinates the lifecycle of an advice-execution run:
+ *   • parses advice_key into the right AdviceItem
+ *   • enforces project-path validity + whitelist
+ *   • enforces a single global running job
+ *   • spawns the runner asynchronously and writes results back to
+ *     execution_run row
+ *   • exposes read / cancel / orphan-cleanup helpers for the API + boot path
+ *
+ * Spec: docs/superpowers/specs/2026-06-13-advice-execution-design.md §8
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const {
+  queryAll,
+  queryOne,
+  getSessionById,
+  getMessagesBySession,
+  getSetting,
+  setSetting,
+} = require('../db/queries');
+const { loadAdvice } = require('../llm/advice');
+const { loadProjectAdvice } = require('../llm/project-advice');
+const { saveDb } = require('../db/connection');
+const { runExecutor, canSpawn } = require('./runner');
+const {
+  buildExecutionPrompt,
+  buildProjectExecutionPrompt,
+} = require('./prompt');
+const { canonicalProject } = require('../utils/project');
+
+// ---------------------------------------------------------------------------
+//  In-process global lock
+// ---------------------------------------------------------------------------
+
+/**
+ * The currently-running execution.  null when idle.
+ *
+ * Shape:
+ *   { runId, scope, scopeId, cancel: ()=>void, sessionId? }
+ *
+ * `sessionId` is kept on session-scope runs for backwards-compat with
+ * the API response shape; project-scope runs leave it null.
+ */
+let _current = null;
+
+function isBusy() { return _current !== null; }
+
+// ---------------------------------------------------------------------------
+//  Whitelist (stored in user_settings.execution_allowed_paths)
+// ---------------------------------------------------------------------------
+
+const WHITELIST_KEY = 'execution_allowed_paths';
+
+function normalisePath(p) {
+  if (typeof p !== 'string' || !p.trim()) return null;
+  try { return path.resolve(p.trim()); } catch { return null; }
+}
+
+function getWhitelist(db) {
+  const raw = getSetting(db, WHITELIST_KEY);
+  if (!raw) return [];
+  return raw.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+function setWhitelist(db, paths) {
+  const uniq = Array.from(new Set(paths.map(normalisePath).filter(Boolean)));
+  setSetting(db, WHITELIST_KEY, uniq.join('\n'));
+  return uniq;
+}
+
+function addToWhitelist(db, p) {
+  const np = normalisePath(p);
+  if (!np) return getWhitelist(db);
+  const cur = getWhitelist(db);
+  if (cur.some((x) => normalisePath(x) === np)) return cur;
+  cur.push(np);
+  return setWhitelist(db, cur);
+}
+
+function removeFromWhitelist(db, p) {
+  const np = normalisePath(p);
+  if (!np) return getWhitelist(db);
+  const cur = getWhitelist(db).filter((x) => normalisePath(x) !== np);
+  setWhitelist(db, cur);
+  return cur;
+}
+
+function isWhitelisted(db, p) {
+  const np = normalisePath(p);
+  if (!np) return false;
+  return getWhitelist(db).some((x) => normalisePath(x) === np);
+}
+
+// ---------------------------------------------------------------------------
+//  Path validation
+// ---------------------------------------------------------------------------
+
+function isValidProjectPath(p) {
+  if (typeof p !== 'string' || !p) return false;
+  try {
+    const st = fs.statSync(p);
+    return st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Advice item resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse 'category.index' → { category, index } or null.
+ */
+function parseAdviceKey(adviceKey) {
+  if (typeof adviceKey !== 'string') return null;
+  const m = adviceKey.match(/^([a-z_]+)\.(\d+)$/);
+  if (!m) return null;
+  return { category: m[1], index: Number(m[2]) };
+}
+
+/**
+ * Locate the AdviceItem inside the cached advice payload.  Returns the
+ * item with .category attached for convenience, or null.
+ *
+ * Works for both session advice (`session_analysis.llm_advice`) and
+ * project advice (`project_advice.llm_advice`) — both wrap items inside
+ * `{ categories: { [cat]: [items] } }` with identical AdviceItem shape.
+ */
+function findAdviceItem(advice, adviceKey) {
+  const parsed = parseAdviceKey(adviceKey);
+  if (!parsed) return null;
+  if (!advice || !advice.categories) return null;
+  const arr = advice.categories[parsed.category];
+  if (!Array.isArray(arr)) return null;
+  const it = arr[parsed.index];
+  if (!it) return null;
+  return { ...it, category: parsed.category };
+}
+
+// ---------------------------------------------------------------------------
+//  Recent user messages (context for executor)
+// ---------------------------------------------------------------------------
+
+function fetchRecentUserMessages(db, sessionId, limit = 5) {
+  const all = getMessagesBySession(db, sessionId);
+  const users = all.filter((m) => m.role === 'user' && m.text);
+  return users.slice(-limit).map((m) => ({ role: 'user', text: m.text || '' }));
+}
+
+// ---------------------------------------------------------------------------
+//  DB writes
+// ---------------------------------------------------------------------------
+
+function insertRun(db, row) {
+  db.run(
+    `INSERT INTO execution_run
+      (id, session_id, advice_key, advice_snapshot, project, executor,
+       status, started_at, ended_at, exit_code, stdout, stderr, error, duration_ms,
+       scope, scope_id, scope_meta)
+     VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+    [
+      row.id,
+      row.session_id || '',         // NOT NULL column — '' for project-scope rows
+      row.advice_key,
+      row.advice_snapshot,
+      row.project,
+      row.executor,
+      row.status,
+      row.started_at || null,
+      row.ended_at || null,
+      row.exit_code ?? null,
+      row.stdout || null,
+      row.stderr || null,
+      row.error || null,
+      row.duration_ms ?? null,
+      row.scope || 'session',
+      row.scope_id || row.session_id || '',
+      row.scope_meta || null,
+    ]
+  );
+}
+
+function updateRun(db, runId, patch) {
+  const fields = [];
+  const values = [];
+  for (const [k, v] of Object.entries(patch)) {
+    fields.push(`${k} = ?`);
+    values.push(v ?? null);
+  }
+  values.push(runId);
+  db.run(
+    `UPDATE execution_run SET ${fields.join(', ')} WHERE id = ?`,
+    values
+  );
+  try { saveDb(); } catch { /* auto-save will catch up */ }
+}
+
+function getRun(db, runId) {
+  return queryOne(db, 'SELECT * FROM execution_run WHERE id = ?', [runId]);
+}
+
+function listRunsForAdvice(db, sessionId) {
+  // Session-scope runs only.  Older rows (pre-scope migration) have
+  // scope = NULL but a valid session_id, so we treat NULL as 'session'.
+  const rows = queryAll(
+    db,
+    `SELECT * FROM execution_run
+       WHERE session_id = ?
+         AND (scope IS NULL OR scope = 'session')
+       ORDER BY advice_key, started_at DESC, id DESC`,
+    [sessionId]
+  );
+  const out = {};
+  for (const r of rows) {
+    (out[r.advice_key] || (out[r.advice_key] = [])).push(r);
+  }
+  return out;
+}
+
+/**
+ * Project-scope counterpart of listRunsForAdvice.  Looks up all runs
+ * triggered from a given project advice (project + scope + window).
+ *
+ * @param {object} db
+ * @param {string} projectKey  canonical project path
+ * @param {string} scope       'daily' | 'weekly' | 'all'
+ * @param {string} windowFrom
+ * @param {string} windowTo
+ * @returns {Object<string, Object[]>}  { 'cost.0': [run, ...], ... }
+ */
+function listRunsForProjectAdvice(db, projectKey, scope, windowFrom, windowTo) {
+  const project = canonicalProject(projectKey);
+  const scopeId = makeProjectScopeId(project, scope, windowFrom, windowTo);
+  const rows = queryAll(
+    db,
+    `SELECT * FROM execution_run
+       WHERE scope = 'project' AND scope_id = ?
+       ORDER BY advice_key, started_at DESC, id DESC`,
+    [scopeId]
+  );
+  const out = {};
+  for (const r of rows) {
+    (out[r.advice_key] || (out[r.advice_key] = [])).push(r);
+  }
+  return out;
+}
+
+/**
+ * Synthetic scope_id for project runs.  Encodes everything that
+ * identifies the source project_advice row, so two different windows of
+ * the same project don't share their run history.
+ */
+function makeProjectScopeId(project, scope, windowFrom, windowTo) {
+  return `project::${project}::${scope}::${windowFrom || ''}::${windowTo || ''}`;
+}
+
+function getCurrentRunning(db) {
+  return queryOne(
+    db,
+    `SELECT * FROM execution_run
+       WHERE status IN ('pending','running')
+       ORDER BY started_at DESC LIMIT 1`
+  );
+}
+
+// ---------------------------------------------------------------------------
+//  Orphan cleanup — called at server boot
+// ---------------------------------------------------------------------------
+
+function cleanupOrphans(db) {
+  const orphans = queryAll(
+    db,
+    `SELECT id FROM execution_run WHERE status IN ('pending','running')`
+  );
+  if (!orphans.length) return 0;
+  const now = new Date().toISOString();
+  for (const o of orphans) {
+    db.run(
+      `UPDATE execution_run
+          SET status='failed', error='aboss-restarted', ended_at=?
+        WHERE id=?`,
+      [now, o.id]
+    );
+  }
+  try { saveDb(); } catch { /* noop */ }
+  return orphans.length;
+}
+
+// ---------------------------------------------------------------------------
+//  Public: startExecution
+// ---------------------------------------------------------------------------
+
+/**
+ * Start a new execution run for the given advice item.
+ *
+ * @param {object}  db
+ * @param {object}  opts
+ * @param {string}  opts.sessionId
+ * @param {string}  opts.adviceKey      'category.index'
+ * @param {string}  [opts.executor]     override the item's preferred executor
+ * @param {boolean} [opts.ephemeral=false] true → don't add project to whitelist
+ *
+ * @returns {Promise<
+ *   { ok:true, runId, run: row }
+ * | { ok:false, reason:'already-running'|'no-session'|'no-advice'|'no-advice-item'
+ *                       |'not-actionable'|'invalid-project-path'|'not-whitelisted'
+ *                       |'no-cli'|'internal',
+ *     extra?: any, error?: string }
+ * >}
+ */
+async function startExecution(db, opts) {
+  const { sessionId, adviceKey, executor: executorOpt, ephemeral = false } = opts || {};
+  try {
+    // 1. Global lock (in-process is authoritative; DB query is a backup
+    //    for the race where _current was reset but a crashed run wasn't
+    //    cleaned up.  cleanupOrphans on boot makes this rare.)
+    const busy = checkBusy(db);
+    if (busy) return busy;
+
+    // 2. Session must exist.
+    const session = getSessionById(db, sessionId);
+    if (!session) return { ok: false, reason: 'no-session' };
+
+    // 3. Advice cache must exist + item must be findable.
+    const advice = loadAdvice(db, sessionId);
+    if (!advice) return { ok: false, reason: 'no-advice' };
+    const item = findAdviceItem(advice, adviceKey);
+    if (!item) return { ok: false, reason: 'no-advice-item' };
+
+    // 4. Item must be actionable.
+    if (item.actionable !== true) {
+      return { ok: false, reason: 'not-actionable' };
+    }
+
+    // 5. Project path validity.
+    const project = session.project;
+    if (!isValidProjectPath(project)) {
+      return { ok: false, reason: 'invalid-project-path', extra: { project } };
+    }
+
+    // 6. Whitelist (with optional ephemeral bypass).
+    if (!ephemeral && !isWhitelisted(db, project)) {
+      return { ok: false, reason: 'not-whitelisted', extra: { project } };
+    }
+
+    // 7. Executor choice & availability.
+    const executor = executorOpt || item.executor || 'opencode';
+    if (executor !== 'opencode' && executor !== 'claude') {
+      return { ok: false, reason: 'no-cli', extra: { executor } };
+    }
+    const cliOk = await canSpawn(executor);
+    if (!cliOk) return { ok: false, reason: 'no-cli', extra: { executor } };
+
+    // 8. Insert the row in 'pending' state.
+    const runId = crypto.randomUUID();
+    insertRun(db, {
+      id: runId,
+      session_id: sessionId,
+      advice_key: adviceKey,
+      advice_snapshot: JSON.stringify(item),
+      project,
+      executor,
+      status: 'pending',
+      scope: 'session',
+      scope_id: sessionId,
+      scope_meta: null,
+    });
+    try { saveDb(); } catch {}
+
+    // 9. Fire-and-forget the run.  Resolves the promise with runId NOW.
+    const recentUserMessages = fetchRecentUserMessages(db, sessionId);
+    _current = { runId, scope: 'session', scopeId: sessionId, sessionId, cancel: null };
+
+    const promptBuilder = () => buildExecutionPrompt({
+      advice: item,
+      session: {
+        project: session.project,
+        title: session.title,
+        model: session.model,
+        durationMinutes: session.duration_minutes,
+        messageCount: session.message_count,
+      },
+      recentUserMessages,
+    });
+
+    spawnRunAsync(db, { runId, executor, cwd: project, promptBuilder });
+
+    const row = getRun(db, runId);
+    return { ok: true, runId, run: row };
+  } catch (err) {
+    return { ok: false, reason: 'internal', error: err && err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Public: startProjectExecution
+// ---------------------------------------------------------------------------
+
+/**
+ * Start a new execution run for an item in a project-level advice payload.
+ *
+ * Mirrors startExecution but resolves the AdviceItem from project_advice
+ * rather than session_analysis.llm_advice, and spawns the executor in
+ * the project root (the same place session-scope runs target).
+ *
+ * Shares the global busy lock with session-scope runs (per design — only
+ * one opencode/claude subprocess at a time touching the user's files).
+ *
+ * @param {object}  db
+ * @param {object}  opts
+ * @param {string}  opts.project          raw or canonical project path
+ * @param {string}  opts.scope            'daily' | 'weekly' | 'all'
+ * @param {string}  [opts.windowFrom]
+ * @param {string}  [opts.windowTo]
+ * @param {string}  opts.adviceKey        'category.index'
+ * @param {string}  [opts.executor]
+ * @param {boolean} [opts.ephemeral=false]
+ *
+ * @returns {Promise<
+ *   { ok:true, runId, run: row }
+ * | { ok:false, reason: string, extra?: any, error?: string }
+ * >}
+ */
+async function startProjectExecution(db, opts) {
+  const {
+    project: projectRaw, scope, windowFrom = '', windowTo = '',
+    adviceKey, executor: executorOpt, ephemeral = false,
+  } = opts || {};
+  try {
+    const project = canonicalProject(projectRaw || '');
+    if (!project) return { ok: false, reason: 'no-project' };
+    if (!scope || (scope !== 'all' && (!windowFrom || !windowTo))) {
+      return { ok: false, reason: 'no-window' };
+    }
+
+    // 1. Global lock — shared with session-scope runs.
+    const busy = checkBusy(db);
+    if (busy) return busy;
+
+    // 2. Project advice cache must exist (per spec: meta-analysis is
+    //    user-triggered, so the absence means "go generate it first").
+    const cached = loadProjectAdvice(
+      db, project, scope,
+      scope === 'all' ? '' : windowFrom,
+      scope === 'all' ? '' : windowTo
+    );
+    if (!cached || !cached.payload) {
+      return { ok: false, reason: 'no-advice' };
+    }
+    const item = findAdviceItem(cached.payload, adviceKey);
+    if (!item) return { ok: false, reason: 'no-advice-item' };
+
+    // 3. Actionable check.
+    if (item.actionable !== true) {
+      return { ok: false, reason: 'not-actionable' };
+    }
+
+    // 4. Project path validity (the canonical path must actually be a dir
+    //    on disk — guards against deleted / renamed projects).
+    if (!isValidProjectPath(project)) {
+      return { ok: false, reason: 'invalid-project-path', extra: { project } };
+    }
+
+    // 5. Whitelist.
+    if (!ephemeral && !isWhitelisted(db, project)) {
+      return { ok: false, reason: 'not-whitelisted', extra: { project } };
+    }
+
+    // 6. Executor.
+    const executor = executorOpt || item.executor || 'opencode';
+    if (executor !== 'opencode' && executor !== 'claude') {
+      return { ok: false, reason: 'no-cli', extra: { executor } };
+    }
+    const cliOk = await canSpawn(executor);
+    if (!cliOk) return { ok: false, reason: 'no-cli', extra: { executor } };
+
+    // 7. Insert pending row.
+    const runId = crypto.randomUUID();
+    const scopeId = makeProjectScopeId(project, scope, windowFrom, windowTo);
+    const scopeMeta = JSON.stringify({ scope, windowFrom, windowTo, project });
+    insertRun(db, {
+      id: runId,
+      session_id: '',
+      advice_key: adviceKey,
+      advice_snapshot: JSON.stringify(item),
+      project,
+      executor,
+      status: 'pending',
+      scope: 'project',
+      scope_id: scopeId,
+      scope_meta: scopeMeta,
+    });
+    try { saveDb(); } catch {}
+
+    // 8. Mark current + spawn.
+    _current = { runId, scope: 'project', scopeId, sessionId: null, cancel: null };
+    const promptBuilder = () => buildProjectExecutionPrompt({
+      advice: item,
+      project: {
+        path: project,
+        scope,
+        windowFrom: scope === 'all' ? '' : windowFrom,
+        windowTo:   scope === 'all' ? '' : windowTo,
+        sessionCount: cached.sessionCount,
+      },
+      crossSessionPatterns: Array.isArray(cached.payload.crossSessionPatterns)
+        ? cached.payload.crossSessionPatterns
+        : [],
+    });
+
+    spawnRunAsync(db, { runId, executor, cwd: project, promptBuilder });
+
+    const row = getRun(db, runId);
+    return { ok: true, runId, run: row };
+  } catch (err) {
+    return { ok: false, reason: 'internal', error: err && err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Shared spawn / busy helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a failure result if anything is busy, otherwise null.
+ * Both in-process lock (authoritative) and DB row (belt + braces).
+ */
+function checkBusy(db) {
+  if (isBusy()) {
+    return {
+      ok: false, reason: 'already-running',
+      extra: {
+        runId: _current.runId,
+        scope: _current.scope,
+        scopeId: _current.scopeId,
+        sessionId: _current.sessionId,
+      },
+    };
+  }
+  const dbRunning = getCurrentRunning(db);
+  if (dbRunning) {
+    return {
+      ok: false, reason: 'already-running',
+      extra: {
+        runId: dbRunning.id,
+        scope: dbRunning.scope || 'session',
+        scopeId: dbRunning.scope_id || dbRunning.session_id,
+        sessionId: dbRunning.session_id || null,
+      },
+    };
+  }
+  return null;
+}
+
+/**
+ * Run the executor asynchronously (fire-and-forget) and write the final
+ * row state back to the DB.  Used by both session and project start
+ * paths so the success/failure handling stays identical.
+ */
+function spawnRunAsync(db, { runId, executor, cwd, promptBuilder }) {
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  (async () => {
+    try {
+      updateRun(db, runId, { status: 'running', started_at: new Date().toISOString() });
+
+      const prompt = promptBuilder();
+
+      const result = await runExecutor({
+        executor,
+        prompt,
+        cwd,
+        onSpawn: (cancel) => {
+          if (_current && _current.runId === runId) {
+            _current.cancel = cancel;
+          }
+        },
+      });
+
+      const ended = new Date().toISOString();
+      if (result.ok) {
+        updateRun(db, runId, {
+          status: 'success',
+          ended_at: ended,
+          exit_code: result.exitCode,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          duration_ms: result.durationMs,
+          error: null,
+        });
+      } else {
+        const status = result.reason === 'cancelled' ? 'cancelled' : 'failed';
+        updateRun(db, runId, {
+          status,
+          ended_at: ended,
+          exit_code: result.exitCode,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          duration_ms: result.durationMs,
+          error: result.reason,
+        });
+      }
+    } catch (err) {
+      // runner never throws — belt-and-braces.
+      updateRun(db, runId, {
+        status: 'failed',
+        ended_at: new Date().toISOString(),
+        error: 'internal',
+        stderr: (err && err.message) || String(err),
+      });
+    } finally {
+      _current = null;
+    }
+  })();
+}
+
+/**
+ * Cancel the run if it's the current in-flight one.  Returns
+ * `{ ok:false, reason:'not-running' }` otherwise.
+ */
+async function cancelRun(db, runId) {
+  if (!_current || _current.runId !== runId) {
+    return { ok: false, reason: 'not-running' };
+  }
+  if (typeof _current.cancel !== 'function') {
+    return { ok: false, reason: 'not-running' };
+  }
+  _current.cancel();
+  // Don't await — runner's exit handler will write the row with status=cancelled.
+  return { ok: true };
+}
+
+module.exports = {
+  startExecution,
+  startProjectExecution,
+  cancelRun,
+  getRun,
+  listRunsForAdvice,
+  listRunsForProjectAdvice,
+  getCurrentRunning,
+  cleanupOrphans,
+  // whitelist
+  getWhitelist,
+  addToWhitelist,
+  removeFromWhitelist,
+  isWhitelisted,
+  // helpers exported for tests / api
+  parseAdviceKey,
+  findAdviceItem,
+  isValidProjectPath,
+  makeProjectScopeId,
+};