agentboss 0.1.0

package/server/analysis/text-signals.js

@@ -0,0 +1,179 @@
+/**
+ * Text-signal extraction utilities.
+ *
+ * Shared by H1/H2/H3 (and the rule fallbacks in E1/O1).  We deliberately
+ * keep this in one file so the keyword vocabulary is reviewed in one
+ * place — the spec doc is the source of truth, this file just encodes it.
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+const { queryAll } = require('../db/queries');
+
+// ---------------------------------------------------------------------------
+//  Keyword vocabularies
+// ---------------------------------------------------------------------------
+
+/** User saying "change direction" / "redo" / "start over". */
+const DRIFT_PATTERNS = [
+  /换(一种|一个|个)/, /算了/, /改成/, /重新来/, /不(对|是)[,，]?\s*(应该|是)/, /推翻/, /换思路/,
+  /forget (it|that)/i, /let'?s restart/i, /never mind/i, /actually,? (let'?s|use|do)/i,
+];
+
+/** User explicitly reframing or planning. */
+const REFRAME_PATTERNS = [
+  /^我先/, /先理清/, /先?分?(两|三|四|多)步/, /我希望(先|你)/, /先?规划/, /先?设计/, /先?列(出)?/,
+  /step (one|1)/i, /^let'?s first/i, /first,? let'?s/i, /^plan:/i, /^step 1/i,
+];
+
+/** User pushing back / questioning AI output. */
+const CHALLENGE_PATTERNS = [
+  /为什么/, /不对/, /再确认/, /你刚说/, /真的吗/, /再想想/, /有(没有)?更好/, /有问题/, /(我)?不(同意|认可)/,
+  /为何/, /哪里/,
+  /why\b/i, /that'?s wrong/i, /are you sure/i, /reconsider/i, /(i )?disagree/i,
+  /that doesn'?t/i, /that won'?t/i,
+];
+
+/** User overriding AI's choice. */
+const OVERRIDE_PATTERNS = [
+  /用别的/, /换/, /(应)?该用/, /不要(用)?/, /(必须|得)用/, /改用/, /(放|去)弃/,
+  /use\s+\w+ instead/i, /don'?t use/i, /switch to/i,
+];
+
+/** User saying "thanks / great / continue" without correction. */
+const ACCEPT_PATTERNS = [
+  /^好的?[!.。!]*$/, /^可以[。.]?$/, /^继续[。.]?$/, /^没问题[。.]?$/, /^谢谢?[!.。!]*$/, /^完美/, /^很好/, /^赞/,
+  /^ok\b/i, /^thanks?\b/i, /^great\b/i, /^perfect\b/i, /^lgtm\b/i, /^continue\b/i,
+];
+
+/** User pointing out a deprecated/missing/wrong API. */
+const STALENESS_PATTERNS = [
+  /已?废弃/, /已?(被)?移除/, /已不支持/, /不存在(这个|该)/, /用错了/, /(应)?该是/,
+  /deprecated/i, /removed/i, /no longer/i, /that (api|method|function) doesn'?t exist/i,
+];
+
+/** Abstraction / system-design vocabulary. */
+const ABSTRACTION_TERMS = [
+  '架构', '模块', '接口', '抽象', '复用', '约束', '规范', '协议', '范式', '策略', '契约',
+  '边界', '解耦', '依赖倒置', '泛化', '模板',
+  'architecture', 'module', 'interface', 'abstraction', 'protocol', 'contract',
+  'boundary', 'decouple', 'generalise', 'template',
+];
+
+/** Active-refactoring vocabulary (H3). */
+const REFACTOR_PATTERNS = [
+  /重构/, /统一/, /沉淀/, /抽象成/, /模板化/, /标准化/, /整合/, /合并/,
+  /refactor/i, /consolidate/i, /unify/i, /standard[ie]se/i, /extract\s+to/i,
+];
+
+// ---------------------------------------------------------------------------
+//  Matchers
+// ---------------------------------------------------------------------------
+
+function matchesAny(text, patterns) {
+  if (!text) return false;
+  for (const p of patterns) if (p.test(text)) return true;
+  return false;
+}
+
+function countMatches(text, patterns) {
+  if (!text) return 0;
+  let n = 0;
+  for (const p of patterns) {
+    const m = text.match(new RegExp(p.source, p.flags.includes('g') ? p.flags : p.flags + 'g'));
+    if (m) n += m.length;
+  }
+  return n;
+}
+
+function termOccurrences(text, terms) {
+  if (!text) return 0;
+  const lower = text.toLowerCase();
+  let n = 0;
+  for (const t of terms) {
+    // very lightweight token count
+    const re = new RegExp(t.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g');
+    const m = lower.match(re);
+    if (m) n += m.length;
+  }
+  return n;
+}
+
+// ---------------------------------------------------------------------------
+//  Per-session text fetcher
+//
+//  Returns the user/assistant message stream for a session as a chronological
+//  list of { role, text, ts }.  We currently only have `content_length` and
+//  `is_error` on unified_message — the actual text is in unified_part rows
+//  with type='text'.  To keep this drop-in we read part.data when available
+//  and fall back to title/length-only stats.
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch every text fragment for a session, joined per parent message,
+ * tagged with role + timestamp.
+ *
+ * @param {object} db
+ * @param {string} sessionId
+ * @returns {Array<{ id: string, role: string, text: string, ts: string }>}
+ */
+function fetchMessages(db, sessionId) {
+  // The v2 ETL writes the text payload into unified_message.text (capped
+  // at ~4 KB per row).  Legacy rows from before the migration still have
+  // NULL there — callers should treat empty text as "signal unknown" and
+  // either skip the indicator or fall back to length-only signals.
+
+  const rows = queryAll(
+    db,
+    `SELECT id, role, timestamp, content_length, is_error, text
+       FROM unified_message
+      WHERE session_id = ?
+      ORDER BY timestamp ASC`,
+    [sessionId]
+  );
+
+  return rows.map((r) => ({
+    id: r.id,
+    role: r.role,
+    text: r.text || '',
+    contentLength: r.content_length || 0,
+    isError: !!r.is_error,
+    ts: r.timestamp,
+  }));
+}
+
+/**
+ * Convenience: list user messages only.
+ */
+function userMessages(messages) {
+  return messages.filter((m) => m.role === 'user');
+}
+
+/**
+ * Convenience: list assistant messages only.
+ */
+function assistantMessages(messages) {
+  return messages.filter((m) => m.role === 'assistant');
+}
+
+module.exports = {
+  // patterns
+  DRIFT_PATTERNS,
+  REFRAME_PATTERNS,
+  CHALLENGE_PATTERNS,
+  OVERRIDE_PATTERNS,
+  ACCEPT_PATTERNS,
+  STALENESS_PATTERNS,
+  ABSTRACTION_TERMS,
+  REFACTOR_PATTERNS,
+  // matchers
+  matchesAny,
+  countMatches,
+  termOccurrences,
+  // data fetchers
+  fetchMessages,
+  userMessages,
+  assistantMessages,
+};

package/server/analysis/thresholds-v2.js

@@ -0,0 +1,358 @@
+/**
+ * v2 capability thresholds — single source of truth.
+ *
+ * Each sub-indicator declares:
+ *   • how its raw value should be interpreted (higher / lower / band-better)
+ *   • the L1-L4 boundaries, possibly per difficulty bucket
+ *
+ * The shape is deliberately flat data so it can be tweaked without code
+ * changes and (eventually) edited from the Settings UI.
+ *
+ * Source of truth: docs/superpowers/specs/2026-06-13-capability-model-v2.md §4
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+// ---------------------------------------------------------------------------
+//  Helpers
+// ---------------------------------------------------------------------------
+
+/** Map L1..L4 to a centred numeric score the rollup can average. */
+const LEVEL_SCORE = { 1: 25, 2: 55, 3: 80, 4: 95 };
+
+/** Map a numeric score back to a level (matches §5 rules). */
+function scoreToLevel(score) {
+  if (score == null || Number.isNaN(score)) return null;
+  if (score >= 85) return 4;
+  if (score >= 65) return 3;
+  if (score >= 40) return 2;
+  return 1;
+}
+
+// ---------------------------------------------------------------------------
+//  Threshold tables
+//  Each row reads "if value satisfies the cell for level L at difficulty D,
+//  return L".  Difficulty buckets: 1 trivial · 2 routine · 3 complex · 4 heavy.
+//
+//  direction: 'lower' = lower is better
+//             'higher' = higher is better
+//             'band'   = ideal range, anything else penalised
+// ---------------------------------------------------------------------------
+
+/* ----- H1 — Problem Definition ------------------------------------- */
+
+const H1 = {
+  /** AI proactive-question count (HEAD 30% of the session). */
+  clarity: {
+    direction: 'lower',
+    // bucket = difficulty.  cell = inclusive upper bound for that level.
+    table: {
+      1: { L4: 0, L3: 1, L2: 3 },
+      2: { L4: 1, L3: 2, L2: 5 },
+      3: { L4: 2, L3: 4, L2: 8 },
+      4: { L4: 3, L3: 6, L2: 12 },
+    },
+  },
+  /** User-message rounds needed to converge. */
+  converge: {
+    direction: 'lower',
+    table: {
+      1: { L4: 3,  L3: 5,  L2: 8 },
+      2: { L4: 5,  L3: 8,  L2: 15 },
+      3: { L4: 8,  L3: 15, L2: 25 },
+      4: { L4: 15, L3: 30, L2: 50 },
+    },
+  },
+  /** Direction-change events. */
+  drift: {
+    direction: 'lower',
+    table: {
+      1: { L4: 0, L3: 1, L2: 2 },
+      2: { L4: 0, L3: 1, L2: 2 },
+      3: { L4: 1, L3: 2, L2: 4 },
+      4: { L4: 1, L3: 3, L2: 6 },
+    },
+  },
+};
+
+/* ----- H2 — Judgement ---------------------------------------------- */
+
+const H2 = {
+  challenge: {
+    direction: 'higher',
+    table: {
+      1: { L4: 0.20, L3: 0.10, L2: 0.03 },
+      2: { L4: 0.30, L3: 0.18, L2: 0.08 },
+      3: { L4: 0.35, L3: 0.25, L2: 0.15 },
+      4: { L4: 0.40, L3: 0.30, L2: 0.20 },
+    },
+  },
+  /**
+   * Override rate — band metric: too low = rubber-stamping, too high =
+   * thrashing.  Encoded as { ideal: [lo, hi], tolerance: [[L3 lo, L3 hi], …] }
+   */
+  override: {
+    direction: 'band',
+    bands: {
+      1: { L4: [0, 0.10],   L3: [0, 0.20],   L2: [0, 0.35] },
+      2: { L4: [0.05, 0.15],L3: [0, 0.25],   L2: [0, 0.40] },
+      3: { L4: [0.10, 0.20],L3: [0, 0.30],   L2: [0, 0.45] },
+      4: { L4: [0.10, 0.25],L3: [0, 0.35],   L2: [0, 0.50] },
+    },
+  },
+  /** Compliant-without-comment rate — ideal band 60-85% (difficulty-agnostic). */
+  accept_rate: {
+    direction: 'band',
+    bands: {
+      1: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
+      2: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
+      3: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
+      4: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
+    },
+  },
+};
+
+/* ----- H3 — System Thinking (rolling) ------------------------------ */
+
+const H3 = {
+  consistency: {
+    direction: 'higher',
+    table: { all: { L4: 0.80, L3: 0.60, L2: 0.40 } },
+  },
+  dedup: {
+    direction: 'lower',
+    table: { all: { L4: 0.05, L3: 0.15, L2: 0.30 } },
+  },
+  refactor: {  // per 100 sessions
+    direction: 'higher',
+    table: { all: { L4: 6, L3: 3, L2: 1 } },
+  },
+  abstraction: {
+    direction: 'higher',
+    table: { all: { L4: 0.20, L3: 0.10, L2: 0.05 } },
+  },
+};
+
+/* ----- E1 — Knowledge Coverage ------------------------------------- */
+
+const E1 = {
+  domain_errors: {
+    direction: 'lower',
+    table: { all: { L4: 0.03, L3: 0.08, L2: 0.15 } },
+  },
+  staleness: {
+    direction: 'lower',
+    table: { all: { L4: 0, L3: 1, L2: 3 } },
+  },
+  best_practice: {
+    direction: 'higher',
+    table: { all: { L4: 0.85, L3: 0.65, L2: 0.45 } },
+  },
+};
+
+/* ----- E2 — Tool Coverage ------------------------------------------ */
+
+const E2 = {
+  tool_pick: {
+    direction: 'higher',
+    table: {
+      1: { L4: 0.95, L3: 0.85, L2: 0.70 },
+      2: { L4: 0.90, L3: 0.80, L2: 0.65 },
+      3: { L4: 0.85, L3: 0.75, L2: 0.60 },
+      4: { L4: 0.80, L3: 0.70, L2: 0.55 },
+    },
+  },
+  /** calls-per-intent ratio vs baseline 1.0 (LOWER better) */
+  chain_eff: {
+    direction: 'lower',
+    table: { all: { L4: 1.1, L3: 1.4, L2: 1.8 } },
+  },
+  self_heal: {
+    direction: 'higher',
+    table: { all: { L4: 0.85, L3: 0.65, L2: 0.40 } },
+  },
+};
+
+/* ----- O1 — Output Quality ----------------------------------------- */
+
+const O1 = {
+  first_take: {
+    direction: 'higher',
+    table: {
+      1: { L4: 0.80, L3: 0.60, L2: 0.40 },
+      2: { L4: 0.70, L3: 0.55, L2: 0.40 },
+      3: { L4: 0.60, L3: 0.45, L2: 0.30 },
+      4: { L4: 0.50, L3: 0.35, L2: 0.25 },
+    },
+  },
+  code_style: {
+    direction: 'higher',
+    table: { all: { L4: 0.85, L3: 0.65, L2: 0.45 } },
+  },
+  completeness: {
+    direction: 'higher',
+    table: { all: { L4: 0.80, L3: 0.60, L2: 0.40 } },
+  },
+};
+
+const ALL = { H1, H2, H3, E1, E2, O1 };
+
+// ---------------------------------------------------------------------------
+//  Roll-up weights — see spec §5
+// ---------------------------------------------------------------------------
+
+const WEIGHTS = {
+  H1: { clarity: 0.45, converge: 0.35, drift: 0.20 },
+  H2: { challenge: 0.40, override: 0.35, accept_rate: 0.25 },
+  H3: { consistency: 0.30, dedup: 0.25, refactor: 0.20, abstraction: 0.25 },
+  E1: { domain_errors: 0.40, staleness: 0.25, best_practice: 0.35 },
+  E2: { tool_pick: 0.40, chain_eff: 0.30, self_heal: 0.30 },
+  O1: { first_take: 0.45, code_style: 0.25, completeness: 0.30 },
+};
+
+// ---------------------------------------------------------------------------
+//  Level evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a numeric value to L1..L4 against an indicator spec.
+ *
+ * @param {Object} indicator   one of H1.clarity, H2.override, etc.
+ * @param {number|null} value  the raw measurement
+ * @param {number} difficulty  1-4 (ignored if the spec table is keyed by 'all')
+ * @returns {1|2|3|4|null}
+ */
+function evalLevel(indicator, value, difficulty = 2) {
+  if (!indicator || value == null || Number.isNaN(value)) return null;
+
+  const key = pickTableKey(indicator, difficulty);
+
+  if (indicator.direction === 'band') {
+    const bands = indicator.bands[key];
+    if (!bands) return null;
+    if (inBand(value, bands.L4)) return 4;
+    if (inBand(value, bands.L3)) return 3;
+    if (inBand(value, bands.L2)) return 2;
+    return 1;
+  }
+
+  const cells = indicator.table[key];
+  if (!cells) return null;
+
+  if (indicator.direction === 'lower') {
+    if (value <= cells.L4) return 4;
+    if (value <= cells.L3) return 3;
+    if (value <= cells.L2) return 2;
+    return 1;
+  }
+  // 'higher'
+  if (value >= cells.L4) return 4;
+  if (value >= cells.L3) return 3;
+  if (value >= cells.L2) return 2;
+  return 1;
+}
+
+function pickTableKey(indicator, difficulty) {
+  const t = indicator.table || indicator.bands || {};
+  if (t.all) return 'all';
+  if (t[difficulty] != null) return difficulty;
+  // fall back to the closest available bucket
+  const keys = Object.keys(t).map(Number).filter(Number.isFinite).sort((a, b) => a - b);
+  if (!keys.length) return null;
+  return keys.reduce((acc, k) => (Math.abs(k - difficulty) < Math.abs(acc - difficulty) ? k : acc), keys[0]);
+}
+
+function inBand(value, range) {
+  return Array.isArray(range) && value >= range[0] && value <= range[1];
+}
+
+/**
+ * Convenience: given a raw measurement, return both the level and a
+ * centred numeric score useful for averaging into the dimension score.
+ *
+ * @param {Object} indicator
+ * @param {number} value
+ * @param {number} difficulty
+ * @returns {{ level: number|null, score: number|null }}
+ */
+function evalIndicator(indicator, value, difficulty = 2) {
+  const lvl = evalLevel(indicator, value, difficulty);
+  return { level: lvl, score: lvl == null ? null : LEVEL_SCORE[lvl] };
+}
+
+/**
+ * Like evalIndicator but also returns a structured "why" payload the UI
+ * can render in a tooltip without re-implementing the threshold tables.
+ *
+ *   { level, score, bounds, direction, table }
+ *     - bounds.l4, l3, l2  : the inclusive boundaries used for this
+ *                            difficulty bucket (numbers or [lo, hi] for bands)
+ *     - direction          : 'lower' | 'higher' | 'band'
+ *     - bucketKey          : 'all' or 1-4 (which row of the table was used)
+ *
+ * @param {Object} indicator
+ * @param {number|null} value
+ * @param {number} difficulty
+ */
+function explainIndicator(indicator, value, difficulty = 2) {
+  const base = evalIndicator(indicator, value, difficulty);
+  if (!indicator) return { ...base, value, direction: null, bounds: null, bucketKey: null };
+
+  const bucketKey = pickTableKey(indicator, difficulty);
+  let bounds = null;
+  if (indicator.direction === 'band' && indicator.bands?.[bucketKey]) {
+    const b = indicator.bands[bucketKey];
+    bounds = { L4: b.L4 || null, L3: b.L3 || null, L2: b.L2 || null };
+  } else if (indicator.table?.[bucketKey]) {
+    const t = indicator.table[bucketKey];
+    bounds = { L4: t.L4 ?? null, L3: t.L3 ?? null, L2: t.L2 ?? null };
+  }
+
+  return {
+    ...base,
+    value,
+    direction: indicator.direction,
+    bounds,
+    bucketKey,
+  };
+}
+
+/**
+ * Roll up a set of sub-scores into one dimension score using the
+ * declared weights.  Missing sub-scores are skipped and the remaining
+ * weights are re-normalised so a partial measurement still produces a
+ * sensible number.
+ *
+ * @param {string} dimensionKey  'H1' | 'H2' | … | 'O1'
+ * @param {Object} subScores     { clarity: 80, converge: 55, … }
+ * @returns {number|null}
+ */
+function rollupDimension(dimensionKey, subScores) {
+  const w = WEIGHTS[dimensionKey];
+  if (!w) return null;
+
+  let total = 0;
+  let weightSum = 0;
+  for (const key of Object.keys(w)) {
+    const v = subScores ? subScores[key] : null;
+    if (v == null || Number.isNaN(v)) continue;
+    total += v * w[key];
+    weightSum += w[key];
+  }
+
+  if (weightSum === 0) return null;
+  return Math.round(total / weightSum);
+}
+
+module.exports = {
+  H1, H2, H3, E1, E2, O1, ALL,
+  WEIGHTS,
+  LEVEL_SCORE,
+  scoreToLevel,
+  evalLevel,
+  evalIndicator,
+  explainIndicator,
+  rollupDimension,
+};

package/server/api/advice.js

@@ -0,0 +1,124 @@
+/**
+ * Per-session AI advice API.
+ *
+ * POST /api/advice/session/:id   body: { force?: boolean }   trigger generation
+ * GET  /api/advice/session/:id                                read cached payload
+ *
+ * Failure reasons from server/llm/advice.js are mapped to HTTP codes:
+ *   no-session     → 404
+ *   llm-disabled   → 409
+ *   no-cli         → 409
+ *   timeout        → 504
+ *   bad-json       → 502
+ *   spawn-error    → 500
+ *   exit-non-zero  → 500
+ *   internal / any → 500
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+const router = require('express').Router();
+
+const { generateAdvice, loadAdvice } = require('../llm/advice');
+const { getSessionById } = require('../db/queries');
+
+// ---------------------------------------------------------------------------
+//  Helpers
+// ---------------------------------------------------------------------------
+
+const REASON_TO_STATUS = {
+  'no-session':    404,
+  'llm-disabled':  409,
+  'no-cli':        409,
+  'timeout':       504,
+  'bad-json':      502,
+  'spawn-error':   500,
+  'exit-non-zero': 500,
+  'no-prompt':     500,
+  'internal':      500,
+};
+
+const REASON_TO_MESSAGE = {
+  'no-session':    'Session not found',
+  'llm-disabled':  'LLM judging is disabled in settings',
+  'no-cli':        'No opencode/claude CLI detected on PATH',
+  'timeout':       'LLM call timed out after 90s',
+  'bad-json':      'LLM returned non-JSON output',
+  'spawn-error':   'Failed to spawn LLM CLI',
+  'exit-non-zero': 'LLM CLI exited with a non-zero status',
+  'no-prompt':     'Internal: empty prompt assembled',
+  'internal':      'Internal advice generation error',
+};
+
+function failure(res, reason, extra) {
+  const status = REASON_TO_STATUS[reason] || 500;
+  const message = (extra && extra.error) || REASON_TO_MESSAGE[reason] || reason;
+  return res.status(status).json({
+    ok: false,
+    error: { code: reason.toUpperCase().replace(/-/g, '_'), message },
+  });
+}
+
+// ---------------------------------------------------------------------------
+//  Routes
+// ---------------------------------------------------------------------------
+
+module.exports = function (db) {
+  // POST /api/advice/session/:id  body { force?: boolean }
+  router.post('/session/:id', async (req, res) => {
+    const sessionId = req.params.id;
+    const force = req.body?.force === true || req.body?.force === '1';
+
+    // Cheap pre-check so a bad URL fails fast without spinning up the LLM
+    // path or scanning cache.  The advice layer also catches no-session,
+    // but this gives clients a 404 in the obvious case.
+    if (!getSessionById(db, sessionId)) {
+      return failure(res, 'no-session');
+    }
+
+    try {
+      const result = await generateAdvice(db, sessionId, { force });
+      if (!result.ok) return failure(res, result.reason, result);
+
+      return res.json({
+        ok: true,
+        data: {
+          advice: result.data,
+          fromCache: !!result.fromCache,
+          generatedAt: result.data.cachedAt,
+          cli: result.data.cli,
+        },
+        meta: { generated_at: new Date().toISOString() },
+      });
+    } catch (err) {
+      // Should not happen — generateAdvice catches its own errors — but
+      // belt-and-braces so the API never throws an uncaught.
+      return failure(res, 'internal', { error: err && err.message });
+    }
+  });
+
+  // GET /api/advice/session/:id   read-only cache fetch (never spawns CLI)
+  router.get('/session/:id', (req, res) => {
+    const sessionId = req.params.id;
+    if (!getSessionById(db, sessionId)) {
+      return failure(res, 'no-session');
+    }
+    const cached = loadAdvice(db, sessionId);
+    return res.json({
+      ok: true,
+      data: cached
+        ? {
+            advice: cached,
+            fromCache: true,
+            generatedAt: cached.cachedAt || null,
+            cli: cached.cli || null,
+          }
+        : { advice: null, fromCache: false, generatedAt: null, cli: null },
+      meta: { generated_at: new Date().toISOString() },
+    });
+  });
+
+  return router;
+};