@kienntpixon/dieu-phoi 0.0.0-stage → 0.1.0

package/lib/aggregate.cjs

@@ -0,0 +1,337 @@
+'use strict';
+/*
+ * Canonical stats (CONTRACT "Thước đo"). The sink implements the same rules; a parity test
+ * compares both against fixtures/parity-expected.json.
+ */
+
+const core = require('../hook.cjs');
+
+const MIN_N = 5;
+const FAIL_OUTCOMES = new Set(['fail', 'timeout']);
+const HEAVY_STEERS = new Set(['plan', 'redirect']);
+
+function tsOf(ev) {
+  const t = Date.parse(ev && ev.ts);
+  return isNaN(t) ? 0 : t;
+}
+
+function sumOrNull(values) {
+  if (!values.length) return null;
+  let s = 0;
+  for (const v of values) {
+    if (typeof v !== 'number' || !isFinite(v)) return null;
+    s += v;
+  }
+  return s;
+}
+
+function mean(values) {
+  const v = values.filter((x) => typeof x === 'number' && isFinite(x));
+  if (!v.length) return null;
+  return v.reduce((a, b) => a + b, 0) / v.length;
+}
+
+/** Linear interpolation between closest ranks (same as numpy default / Sheets PERCENTILE). */
+function percentile(values, q) {
+  const v = values.filter((x) => typeof x === 'number' && isFinite(x)).sort((a, b) => a - b);
+  if (!v.length) return null;
+  const pos = (v.length - 1) * q;
+  const lo = Math.floor(pos);
+  const hi = Math.ceil(pos);
+  return v[lo] + (v[hi] - v[lo]) * (pos - lo);
+}
+
+function round6(v) {
+  return v === null || v === undefined ? null : Math.round(v * 1e6) / 1e6;
+}
+
+/**
+ * Normalize a verdict to the two-layer model. Legacy `rework` (no `by`) = user reject/quality;
+ * missing `by` otherwise = agent layer.
+ */
+function normalizeVerdict(ev) {
+  if (ev.outcome === 'rework' && !ev.by) {
+    return { by: 'user', outcome: 'reject', cause: 'quality', round: Number(ev.round) || null };
+  }
+  const by = ev.by === 'user' ? 'user' : 'agent';
+  let cause = ev.cause || null;
+  if (by === 'user' && ev.outcome === 'reject' && cause !== 'scope') cause = 'quality';
+  return { by, outcome: ev.outcome, cause, round: Number(ev.round) || null };
+}
+
+function steerIdOf(ev) {
+  return typeof ev.steer_id === 'string' && ev.steer_id ? ev.steer_id : `${ev.agent_id}|${ev.ts}`;
+}
+
+/**
+ * Join events. Returns agents (one per real agent), userVerdicts (task layer), overrides, steers.
+ */
+function buildAgents(events) {
+  const map = new Map();
+  const userVerdicts = [];
+  const overrides = [];
+  const steers = [];
+  const get = (id) => {
+    if (!map.has(id)) map.set(id, { agent_id: id, dispatch: null, completes: [], verdicts: [], steers: [] });
+    return map.get(id);
+  };
+  events.forEach((ev, idx) => {
+    if (!ev || typeof ev !== 'object') return;
+    const e = Object.assign({ _idx: idx }, ev);
+    if (ev.kind === 'override') { overrides.push(e); return; }
+    if (ev.kind === 'verdict') {
+      const v = Object.assign(e, normalizeVerdict(ev));
+      if (v.by === 'user') { userVerdicts.push(v); return; }
+    }
+    if (ev.kind === 'steer') steers.push(e);
+    if (typeof ev.agent_id !== 'string' || !ev.agent_id) return;
+    const a = get(ev.agent_id);
+    if (ev.kind === 'dispatch') { if (!a.dispatch) a.dispatch = e; } else if (ev.kind === 'complete') a.completes.push(e);
+    else if (ev.kind === 'verdict') a.verdicts.push(e);
+    else if (ev.kind === 'steer') a.steers.push(e);
+  });
+  const agents = [];
+  for (const a of map.values()) {
+    if (!a.dispatch && !a.completes.length && !a.verdicts.length) continue; // task-level steer ids etc.
+    const d = a.dispatch || {};
+    const c0 = a.completes[0] || {};
+    const cl = a.completes[a.completes.length - 1] || {};
+    const v = a.verdicts.slice().sort((x, y) => tsOf(x) - tsOf(y) || x._idx - y._idx);
+    const verdict = v.length ? v[v.length - 1] : null;
+    const firstVerdictTs = v.length ? tsOf(v[0]) : Infinity;
+    const pick = (k) => (d[k] !== undefined && d[k] !== null ? d[k] : (c0[k] !== undefined && c0[k] !== null ? c0[k] : null));
+    const taskType = (d.task_type && d.task_type !== 'untagged' ? d.task_type : null)
+      || (c0.task_type && c0.task_type !== 'untagged' ? c0.task_type : null) || 'untagged';
+    // A heavy steer only removes the attempt if it came before the attempt's first agent verdict:
+    // steers never erase an already-recorded fail.
+    const heavy = a.steers.some((s) => HEAVY_STEERS.has(s.steer_kind) && tsOf(s) < firstVerdictTs);
+    agents.push({
+      agent_id: a.agent_id,
+      task_type: taskType,
+      task_id: pick('task_id') || (verdict && verdict.task_id) || (a.steers[0] && a.steers[0].task_id) || null,
+      try: Number(pick('try')) || 1,
+      role: pick('role') || 'exec',
+      score: d.score !== undefined ? d.score : null,
+      urgency: d.urgency || null,
+      model: core.normalizeModel(cl.model) || core.normalizeModel(d.model) || null,
+      effort: d.effort || c0.effort || null,
+      dispatched: !!a.dispatch,
+      completed: a.completes.length > 0,
+      cost_usd: a.completes.length ? sumOrNull(a.completes.map((x) => x.cost_usd)) : null,
+      duration_s: a.completes.length ? sumOrNull(a.completes.map((x) => x.duration_s)) : null,
+      tool_uses: a.completes.length ? sumOrNull(a.completes.map((x) => x.tool_uses)) : null,
+      outcome: verdict ? verdict.outcome : null,
+      first_outcome: v.length ? v[0].outcome : null,
+      verify: verdict ? verdict.verify : null,
+      reason_code: verdict ? verdict.reason_code : null,
+      steers: a.steers.map((s) => s.steer_kind).filter(Boolean),
+      steered: heavy,
+      ts: tsOf(a.dispatch || a.completes[0] || verdict || {}),
+      _idx: (a.dispatch || a.completes[0] || verdict || { _idx: 0 })._idx,
+      last_complete_ts: a.completes.length ? Math.max(...a.completes.map(tsOf)) : 0,
+    });
+  }
+  return { agents, userVerdicts, overrides, steers };
+}
+
+/** Group agents into tasks (sample unit = task_id; agents without task_id are their own task). */
+function buildTasks(agents, userVerdicts) {
+  const map = new Map();
+  const byAgent = new Map();
+  for (const a of agents) {
+    const key = a.task_id ? `task:${a.task_id}` : `agent:${a.agent_id}`;
+    if (!map.has(key)) map.set(key, { key, task_id: a.task_id, agents: [], user: [] });
+    map.get(key).agents.push(a);
+    byAgent.set(a.agent_id, key);
+  }
+  for (const v of userVerdicts || []) {
+    let key = v.task_id ? `task:${v.task_id}` : null;
+    if (!key && v.agent_id) key = byAgent.get(v.agent_id) || null; // legacy rework without task_id
+    if (!key) continue;
+    if (!map.has(key)) map.set(key, { key, task_id: v.task_id, agents: [], user: [] });
+    map.get(key).user.push(v);
+  }
+  const tasks = [];
+  for (const t of map.values()) {
+    const byTry = (x, y) => (x.try - y.try) || (x.ts - y.ts) || (x._idx - y._idx);
+    const attempts = t.agents.filter((a) => a.role !== 'verify').sort(byTry);
+    const verifies = t.agents.filter((a) => a.role === 'verify');
+    // First exec attempt: lowest try among role=exec (ties: earliest). No exec attempt -> no sample.
+    const first = t.agents.filter((a) => a.role === 'exec').sort(byTry)[0] || null;
+    const user = t.user.slice().sort((x, y) => ((x.round || 0) - (y.round || 0)) || (tsOf(x) - tsOf(y)) || (x._idx - y._idx));
+
+    // Effective per-attempt outcome for escalation: agent verdict, overridden by a user verdict
+    // landing on the latest attempt dispatched before it (reject/quality = fail, accept = pass).
+    for (const a of attempts) a.eff_outcome = a.outcome === 'pass' ? 'pass' : (FAIL_OUTCOMES.has(a.outcome) ? 'fail' : null);
+    for (const v of user) {
+      if (v.cause === 'scope') continue;
+      const vt = tsOf(v);
+      let target = null;
+      for (const a of attempts) if (a.ts <= vt && (!target || a.ts >= target.ts)) target = a;
+      if (!target) target = attempts[attempts.length - 1] || null;
+      if (target) target.eff_outcome = v.outcome === 'accept' ? 'pass' : 'fail';
+    }
+
+    const firstUser = user[0] || null;
+    let userOutcome = null;
+    if (firstUser) {
+      if (firstUser.outcome === 'accept') userOutcome = 'accept';
+      else userOutcome = firstUser.cause === 'scope' ? 'reject_scope' : 'reject_quality';
+    }
+    // Agent layer of the first exec attempt: its first agent verdict.
+    const agentFirst = first && first.first_outcome && (first.first_outcome === 'pass' || FAIL_OUTCOMES.has(first.first_outcome))
+      ? first.first_outcome === 'pass' : null;
+    let success = null;
+    let source = null;
+    if (userOutcome === 'accept') { success = true; source = 'user'; } else if (userOutcome === 'reject_quality') { success = false; source = 'user'; } else if (!userOutcome && agentFirst !== null) {
+      success = agentFirst; source = 'agent';
+    }
+    const lastUser = user[user.length - 1] || null;
+    const accepted = lastUser ? lastUser.outcome === 'accept' : attempts.some((a) => a.outcome === 'pass');
+    const costed = t.agents.filter((a) => a.completed || a.outcome);
+    tasks.push({
+      key: t.key,
+      task_id: t.task_id,
+      task_type: first ? first.task_type : (t.agents[0] && t.agents[0].task_type) || 'untagged',
+      first,
+      attempts,
+      verifies,
+      user_verdicts: user,
+      user_outcome: userOutcome,
+      success,
+      success_source: source,
+      excluded: !!(first && first.steered) || userOutcome === 'reject_scope',
+      accepted,
+      agent_first_pass: agentFirst,
+      // agents with a verdict but no complete event (hook missed) make cost/time unknown (null)
+      total_cost: sumOrNull(costed.map((a) => a.cost_usd)),
+      total_time_s: sumOrNull(costed.map((a) => a.duration_s)),
+    });
+  }
+  return tasks;
+}
+
+function cellKey(type, model, effort) {
+  return `${type}|${model || '?'}|${effort || '?'}`;
+}
+
+/**
+ * Cells task_type x model x effort (tier of the first exec attempt). Canonical fields:
+ * n, n_excluded, accept_rate, agent_pass_rate, cost_{mean,p50,p75}_usd, time_{mean,p50,p75}_min.
+ * CLI-only extras (not part of the parity contract): dispatched, passes, fails, attempt_*, score, enough, note.
+ */
+function buildCells(tasks, opts) {
+  const o = opts || {};
+  const lambda = typeof o.lambda === 'number' ? o.lambda : 0.1;
+  const cells = new Map();
+  for (const t of tasks) {
+    const f = t.first;
+    if (!f) continue;
+    const key = cellKey(t.task_type, f.model, f.effort);
+    if (!cells.has(key)) {
+      cells.set(key, { task_type: t.task_type, model: f.model, effort: f.effort, dispatched: 0, excluded: 0, tasks: [], agentTasks: [] });
+    }
+    const c = cells.get(key);
+    c.dispatched++;
+    if (t.excluded) { c.excluded++; continue; }
+    if (t.success !== null) c.tasks.push(t);
+    if (t.agent_first_pass !== null) c.agentTasks.push(t);
+  }
+  const out = [];
+  for (const c of cells.values()) {
+    const n = c.tasks.length;
+    const passes = c.tasks.filter((t) => t.success).length;
+    const costs = c.tasks.map((t) => t.total_cost);
+    const timesMin = c.tasks.map((t) => (t.total_time_s === null ? null : t.total_time_s / 60));
+    const attemptTimes = c.tasks.map((t) => (t.first.duration_s === null ? null : t.first.duration_s / 60));
+    const attemptCosts = c.tasks.map((t) => t.first.cost_usd);
+    const costMean = mean(costs);
+    const timeMean = mean(timesMin);
+    out.push({
+      task_type: c.task_type,
+      model: c.model,
+      effort: c.effort,
+      n,
+      n_excluded: c.excluded,
+      accept_rate: n ? round6(passes / n) : null,
+      agent_pass_rate: c.agentTasks.length
+        ? round6(c.agentTasks.filter((t) => t.agent_first_pass).length / c.agentTasks.length) : null,
+      cost_mean_usd: round6(costMean),
+      cost_p50_usd: round6(percentile(costs, 0.5)),
+      cost_p75_usd: round6(percentile(costs, 0.75)),
+      time_mean_min: round6(timeMean),
+      time_p50_min: round6(percentile(timesMin, 0.5)),
+      time_p75_min: round6(percentile(timesMin, 0.75)),
+      // CLI-only extras
+      dispatched: c.dispatched,
+      passes,
+      fails: n - passes,
+      n_user: c.tasks.filter((t) => t.success_source === 'user').length,
+      n_agent: c.agentTasks.length,
+      attempt_cost_usd: mean(attemptCosts),
+      attempt_cost_p50: percentile(attemptCosts, 0.5),
+      attempt_time_min: mean(attemptTimes),
+      attempt_p50_min: percentile(attemptTimes, 0.5),
+      attempt_p75_min: percentile(attemptTimes, 0.75),
+      score: costMean === null && timeMean === null ? null : round6((costMean || 0) + lambda * (timeMean || 0)),
+      enough: n >= MIN_N,
+      note: n >= MIN_N ? '' : 'chưa đủ dữ liệu',
+    });
+  }
+  out.sort((a, b) => a.task_type.localeCompare(b.task_type)
+    || String(a.model).localeCompare(String(b.model)) || String(a.effort).localeCompare(String(b.effort)));
+  return out;
+}
+
+const CANONICAL_CELL_FIELDS = [
+  'task_type', 'model', 'effort', 'n', 'n_excluded', 'accept_rate', 'agent_pass_rate',
+  'cost_mean_usd', 'cost_p50_usd', 'cost_p75_usd', 'time_mean_min', 'time_p50_min', 'time_p75_min',
+];
+
+function canonicalCells(cells) {
+  return cells.map((c) => Object.fromEntries(CANONICAL_CELL_FIELDS.map((k) => [k, c[k] === undefined ? null : c[k]])));
+}
+
+/** Steering per task_type, counted in distinct user actions (steer_id), not events. */
+function buildSteers(tasks, steers, agents) {
+  const typeOfTask = new Map(tasks.map((t) => [t.task_id, t.task_type]));
+  const agentById = new Map(agents.map((a) => [a.agent_id, a]));
+  const by = {};
+  const row = (type) => by[type] || (by[type] = {
+    task_type: type, tasks: 0, steered_tasks: 0, actions: 0, minor: 0, plan: 0, redirect: 0, _tasks: new Set(), _ids: new Set(),
+  });
+  for (const t of tasks) if (t.first) row(t.task_type).tasks++;
+  for (const s of steers) {
+    const a = agentById.get(s.agent_id);
+    const taskId = s.task_id || (a && a.task_id) || null;
+    const type = (taskId && typeOfTask.get(taskId)) || s.task_type || (a && a.task_type) || 'untagged';
+    const r = row(type);
+    const id = steerIdOf(s);
+    if (r._ids.has(id)) continue;
+    r._ids.add(id);
+    r.actions++;
+    if (r[s.steer_kind] !== undefined) r[s.steer_kind]++;
+    r._tasks.add(taskId || `agent:${s.agent_id}`);
+  }
+  return Object.values(by).map((r) => {
+    const steered = r._tasks.size;
+    const outRow = {
+      task_type: r.task_type, tasks: r.tasks, steered_tasks: steered, actions: r.actions,
+      minor: r.minor, plan: r.plan, redirect: r.redirect,
+      steer_rate: r.tasks ? round6(Math.min(1, steered / r.tasks)) : 0,
+    };
+    return outRow;
+  }).sort((a, b) => b.steer_rate - a.steer_rate || a.task_type.localeCompare(b.task_type));
+}
+
+function analyze(events, opts) {
+  const { agents, userVerdicts, overrides, steers } = buildAgents(events);
+  const tasks = buildTasks(agents, userVerdicts);
+  const cells = buildCells(tasks, opts);
+  return { agents, tasks, cells, overrides, userVerdicts, steerEvents: steers, steers: buildSteers(tasks, steers, agents) };
+}
+
+module.exports = {
+  MIN_N, FAIL_OUTCOMES, HEAVY_STEERS, CANONICAL_CELL_FIELDS, normalizeVerdict, buildAgents, buildTasks,
+  buildCells, buildSteers, canonicalCells, analyze, cellKey, mean, percentile, tsOf, steerIdOf,
+};

package/lib/args.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+const path = require('path');
+const core = require('../hook.cjs');
+
+const BOOLEAN_FLAGS = new Set(['json', 'help', 'h', 'purge', 'version', 'v', 'dry-run', 'no-sync']);
+
+/** Minimal argv parser: positionals, --k v, --k=v, boolean flags. */
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { out._.push(...argv.slice(i + 1)); break; }
+    if (a.startsWith('--') || (a.length === 2 && a[0] === '-' && a !== '-')) {
+      let key = a.replace(/^--?/, '');
+      let val;
+      const eq = key.indexOf('=');
+      if (eq >= 0) { val = key.slice(eq + 1); key = key.slice(0, eq); }
+      if (val === undefined) {
+        if (BOOLEAN_FLAGS.has(key)) val = true;
+        else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) val = argv[++i];
+        else val = true;
+      }
+      out[key] = val;
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function claudeDirOf(opts) {
+  if (opts && typeof opts['claude-dir'] === 'string') return path.resolve(opts['claude-dir']);
+  if (process.env.DIEU_PHOI_CLAUDE_DIR) return path.resolve(process.env.DIEU_PHOI_CLAUDE_DIR);
+  return core.defaultClaudeDir();
+}
+
+/** Context (home/paths/config) for CLI commands. */
+function ctxOf(opts) {
+  const explicit = opts && typeof opts['claude-dir'] === 'string'
+    ? path.join(path.resolve(opts['claude-dir']), 'dieu-phoi')
+    : (process.env.DIEU_PHOI_HOME || process.env.DIEU_PHOI_CLAUDE_DIR ? null
+      : path.join(core.defaultClaudeDir(), 'dieu-phoi'));
+  return core.makeCtx(explicit || undefined);
+}
+
+function yesNo(v, dflt) {
+  if (v === undefined || v === null || v === true) return v === true ? true : dflt;
+  const s = String(v).toLowerCase();
+  if (['y', 'yes', 'true', '1', 'c', 'co', 'có'].includes(s)) return true;
+  if (['n', 'no', 'false', '0', 'k', 'khong', 'không'].includes(s)) return false;
+  throw new Error(`Giá trị y/n không hợp lệ: ${v}`);
+}
+
+module.exports = { parseArgs, claudeDirOf, ctxOf, yesNo };