avorelo 0.1.0

package/scripts/lib/unified-events.js

@@ -0,0 +1,396 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { nowIso } = require("./fsx");
+const { normalizeAttribution, inferValueUnit } = require("./attribution");
+const { numberOrNull } = require("./cost-evidence");
+
+const OUTBOX_REL = ".claude/cco/cloud/outbox/events.jsonl";
+const OUTCOME_EVENTS_REL = ".claude/cco/events/outcome-events.jsonl";
+const OUTCOME_EXPORTS_REL = ".claude/cco/exports";
+
+function ensureDirFor(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function parseJsonl(absPath) {
+  if (!fs.existsSync(absPath)) return [];
+  return fs
+    .readFileSync(absPath, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((ln) => {
+      try {
+        return JSON.parse(ln);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function appendJsonl(absPath, rows) {
+  ensureDirFor(absPath);
+  const lines = (rows || []).map((row) => JSON.stringify(row)).join("\n");
+  if (!lines) return;
+  fs.appendFileSync(absPath, lines + "\n", "utf8");
+}
+
+function confidenceFromReasonCodes(reasonCodes) {
+  const sec = (reasonCodes || []).filter((x) => String(x).startsWith("SEC_")).length;
+  if (sec >= 2) return "high";
+  if (sec === 1) return "medium";
+  return "low";
+}
+
+function confidenceScore(reasonCodes) {
+  const sec = (reasonCodes || []).filter((x) => String(x).startsWith("SEC_")).length;
+  if (sec >= 2) return 0.92;
+  if (sec === 1) return 0.75;
+  if ((reasonCodes || []).includes("LOOP_REPEATED_TOOL")) return 0.81;
+  if ((reasonCodes || []).includes("CTX_LARGE_OUTPUT")) return 0.72;
+  return 0.58;
+}
+
+function inferCategory(metric) {
+  const codes = metric.reasonCodes || [];
+  const event = String(metric.event || "");
+
+  if (codes.some((c) => String(c).startsWith("SEC_"))) return "risky_skill_flagged";
+  if (codes.includes("LOOP_REPEATED_TOOL") || codes.includes("FAIL_RETRY_GUARD")) return "loop_detected";
+  if (codes.includes("CTX_LARGE_OUTPUT") || codes.includes("CTX_SCAN_SKIPPED_UNCHANGED")) return "output_trimmed";
+  if (codes.includes("SEC_REMEDIATION_JOB_CREATED")) return "patch_suggested";
+  if (codes.includes("PERM_FATIGUE_CONSOLIDATED")) return "permission_consolidated";
+  if (codes.includes("SEC_TRUST_UNKNOWN_HIGH") || codes.includes("SEC_TRUST_AUDIT") || event === "WorktreeCreate" || event === "WorktreeRemove") {
+    return "trust_alert";
+  }
+  if (event === "CloudSync" || event === "SessionEnd" || event === "TaskCompleted") return "pricing_signal";
+  if (String(metric.event || "").toLowerCase().includes("intel")) return "intel_signal";
+  return "waste_prevented";
+}
+
+function measuredValue(metric, category) {
+  const meta = metric.meta || {};
+  if (typeof meta.measured_value === "number") return meta.measured_value;
+  if (category === "output_trimmed") {
+    const bytes = Number(meta.bytes || 0);
+    return Number.isFinite(bytes) && bytes > 0 ? bytes : null;
+  }
+  if (category === "loop_detected") return (metric.reasonCodes || []).includes("LOOP_REPEATED_TOOL") ? 1 : null;
+  if (category === "risky_skill_flagged") return (metric.reasonCodes || []).some((x) => String(x).startsWith("SEC_")) ? 1 : null;
+  if (category === "patch_suggested") return (metric.reasonCodes || []).includes("SEC_REMEDIATION_JOB_CREATED") ? 1 : null;
+  if (category === "pricing_signal") return Number(meta.syncedEvents || 0) || null;
+  return null;
+}
+
+function counterfactualValue(metric, category) {
+  const meta = metric.meta || {};
+  if (typeof meta.estimated_counterfactual_value === "number") return meta.estimated_counterfactual_value;
+  if (category === "loop_detected") {
+    if ((metric.reasonCodes || []).includes("LOOP_REPEATED_TOOL")) return 3;
+    if ((metric.reasonCodes || []).includes("FAIL_RETRY_GUARD")) return 2;
+  }
+  if (category === "output_trimmed") {
+    const bytes = Number(meta.bytes || 0);
+    return Number.isFinite(bytes) && bytes > 0 ? Math.round(bytes * 0.65) : null;
+  }
+  if (category === "risky_skill_flagged") return (metric.reasonCodes || []).some((x) => String(x).startsWith("SEC_")) ? 1 : null;
+  if (category === "patch_suggested") return (metric.reasonCodes || []).includes("SEC_REMEDIATION_JOB_CREATED") ? 1 : null;
+  return null;
+}
+
+function stableId(parts) {
+  const joined = parts.map((x) => String(x || "")).join("|");
+  const hex = crypto.createHash("sha256").update(joined).digest("hex");
+  return `evt_${hex.slice(0, 16)}`;
+}
+
+function buildOutcomeEvent(params) {
+  const metric = params?.metric || {};
+  const platform = params?.platform || "claude";
+  const projectId = params?.projectId || metric?.meta?.projectId || "unknown-project";
+  const userId = params?.userId || metric?.meta?.userId || process.env.CCO_USER_ID || "local-user";
+  const repoId = params?.repoId || metric?.meta?.repoId || projectId;
+  const category = inferCategory(metric);
+  const reasonCode = (metric.reasonCodes && metric.reasonCodes[0]) || "UNKNOWN_REASON";
+
+  const measured = measuredValue(metric, category);
+  const counterfactual = counterfactualValue(metric, category);
+  const attribution = normalizeAttribution(metric);
+  const valueUnit = inferValueUnit({ ...metric, category }, attribution, measured, counterfactual);
+
+  return {
+    event_id: stableId([metric.ts || nowIso(), metric.sessionId || "unknown", metric.event || "UnknownEvent", metric.tool || "", metric.action || "", reasonCode]),
+    session_id: metric.sessionId || "unknown",
+    repo_id: repoId,
+    project_id: projectId,
+    user_id: userId,
+    timestamp: metric.ts || nowIso(),
+    category,
+    reason_code: reasonCode,
+    measured_value: measured,
+    estimated_counterfactual_value: counterfactual,
+    confidence_score: confidenceScore(metric.reasonCodes || []),
+    platform,
+    event_name: metric.event || "UnknownEvent",
+    action: metric.action || null,
+    tool: metric.tool || null,
+    value_unit: valueUnit,
+    attribution,
+    metadata: metric.meta || {},
+  };
+}
+
+function appendOutcomeEvents(cwd, events) {
+  const abs = path.join(cwd, OUTCOME_EVENTS_REL);
+  appendJsonl(abs, events || []);
+  return abs;
+}
+
+function readOutcomeEvents(cwd) {
+  const abs = path.join(cwd, OUTCOME_EVENTS_REL);
+  return parseJsonl(abs);
+}
+
+function aggregateOutcomeEvents(events, options = {}) {
+  const list = Array.isArray(events) ? events : [];
+  const now = Date.now();
+  const days = Number(options.days || 7);
+  const cutoff = now - days * 24 * 60 * 60 * 1000;
+  const weekly = list.filter((e) => {
+    const ts = Date.parse(e.timestamp || 0);
+    return Number.isFinite(ts) && ts >= cutoff;
+  });
+
+  const byCategory = {
+    waste_prevented: 0,
+    loop_detected: 0,
+    output_trimmed: 0,
+    risky_skill_flagged: 0,
+    patch_suggested: 0,
+    permission_consolidated: 0,
+    trust_alert: 0,
+    pricing_signal: 0,
+    intel_signal: 0,
+    other: 0,
+  };
+
+  let measuredTotal = 0;
+  let counterfactualTotal = 0;
+  let measuredCostTotal = 0;
+  let estimatedCostCounterfactualTotal = 0;
+  let tokenUsageTotal = 0;
+  const reasonCounts = {};
+
+  weekly.forEach((e) => {
+    if (byCategory[e.category] === undefined) byCategory.other += 1;
+    else byCategory[e.category] += 1;
+
+    const m = Number(e.measured_value);
+    if (Number.isFinite(m)) measuredTotal += m;
+    const c = Number(e.estimated_counterfactual_value);
+    if (Number.isFinite(c)) counterfactualTotal += c;
+
+    const metadata = e.metadata || {};
+    const cost = numberOrNull(e.attribution?.cost ?? metadata.totalCost);
+    const tokens = numberOrNull(e.attribution?.tokenUsage ?? metadata.totalTokens);
+    const isCurrency = String(e.value_unit || "") === "currency" || (cost !== null && cost > 0);
+
+    if (isCurrency && cost !== null && cost > 0) {
+      measuredCostTotal += cost;
+      if (Number.isFinite(c)) estimatedCostCounterfactualTotal += c;
+    }
+
+    if (tokens !== null && tokens > 0) tokenUsageTotal += tokens;
+
+    reasonCounts[e.reason_code] = (reasonCounts[e.reason_code] || 0) + 1;
+  });
+
+  const topReasonCodes = Object.keys(reasonCounts)
+    .sort((a, b) => reasonCounts[b] - reasonCounts[a])
+    .slice(0, 5);
+
+  const firstSession = list[0]?.session_id || "unknown";
+  const repoId = list[0]?.repo_id || "unknown-project";
+
+  const loopsPrevented = byCategory.loop_detected;
+  const contextPressureReduction = byCategory.output_trimmed;
+  const riskEventsPrevented = byCategory.risky_skill_flagged + byCategory.trust_alert;
+
+  const confidenceLabel = weekly.length >= 20 ? "high" : weekly.length >= 8 ? "medium" : "low";
+
+  return {
+    sessionSummary: {
+      sessionId: firstSession,
+      events: list.filter((x) => x.session_id === firstSession).length,
+      measuredValueTotal: measuredTotal,
+      estimatedCounterfactualTotal: counterfactualTotal,
+      measuredCostTotal: Math.round(measuredCostTotal * 100) / 100,
+      estimatedCostCounterfactualTotal: Math.round(estimatedCostCounterfactualTotal * 100) / 100,
+      tokenUsageTotal: Math.round(tokenUsageTotal),
+      legacyMixedUnitTotals: {
+        measuredValueTotal: measuredTotal,
+        estimatedCounterfactualTotal: counterfactualTotal,
+      },
+      costAwareTotals: {
+        measuredCostTotal: Math.round(measuredCostTotal * 100) / 100,
+        estimatedCostCounterfactualTotal: Math.round(estimatedCostCounterfactualTotal * 100) / 100,
+        tokenUsageTotal: Math.round(tokenUsageTotal),
+      },
+      topReasonCodes,
+    },
+    weeklyRepoSummary: {
+      repoId,
+      days,
+      events: weekly.length,
+      measuredValueTotal: measuredTotal,
+      estimatedCounterfactualTotal: counterfactualTotal,
+      measuredCostTotal: Math.round(measuredCostTotal * 100) / 100,
+      estimatedCostCounterfactualTotal: Math.round(estimatedCostCounterfactualTotal * 100) / 100,
+      tokenUsageTotal: Math.round(tokenUsageTotal),
+      legacyMixedUnitTotals: {
+        measuredValueTotal: measuredTotal,
+        estimatedCounterfactualTotal: counterfactualTotal,
+      },
+      costAwareTotals: {
+        measuredCostTotal: Math.round(measuredCostTotal * 100) / 100,
+        estimatedCostCounterfactualTotal: Math.round(estimatedCostCounterfactualTotal * 100) / 100,
+        tokenUsageTotal: Math.round(tokenUsageTotal),
+      },
+      byCategory,
+    },
+    savingsSummary: {
+      minutesSavedEstimate: Math.max(0, loopsPrevented * 3),
+      contextPressureReduction,
+      loopsPrevented,
+      confidenceLabel,
+    },
+    riskSummary: {
+      riskEventsPrevented,
+      highRiskEvents: byCategory.risky_skill_flagged,
+      remediationSuggested: byCategory.patch_suggested,
+      confidenceLabel,
+    },
+  };
+}
+
+function csvEscape(v) {
+  const s = String(v == null ? "" : v);
+  if (/[",\n]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
+  return s;
+}
+
+function toCsv(events) {
+  const headers = [
+    "event_id",
+    "session_id",
+    "repo_id",
+    "project_id",
+    "user_id",
+    "timestamp",
+    "category",
+    "reason_code",
+    "measured_value",
+    "estimated_counterfactual_value",
+    "confidence_score",
+    "platform",
+    "event_name",
+    "action",
+    "tool",
+  ];
+  const lines = [headers.join(",")];
+  (events || []).forEach((e) => {
+    const row = headers.map((h) => csvEscape(e[h]));
+    lines.push(row.join(","));
+  });
+  return lines.join("\n") + "\n";
+}
+
+function exportOutcomeEvents(cwd, options = {}) {
+  const events = Array.isArray(options.events) ? options.events : readOutcomeEvents(cwd);
+  const ts = nowIso().replace(/[:.]/g, "-");
+  const jsonRel = path.posix.join(OUTCOME_EXPORTS_REL, `outcomes-${ts}.json`);
+  const csvRel = path.posix.join(OUTCOME_EXPORTS_REL, `outcomes-${ts}.csv`);
+
+  const jsonAbs = path.join(cwd, jsonRel);
+  const csvAbs = path.join(cwd, csvRel);
+  ensureDirFor(jsonAbs);
+  fs.writeFileSync(jsonAbs, JSON.stringify({
+    version: 2,
+    generatedAt: nowIso(),
+    count: events.length,
+    aggregation: aggregateOutcomeEvents(events, { days: Number(options.days || 7) }),
+    events,
+  }, null, 2), "utf8");
+
+  ensureDirFor(csvAbs);
+  fs.writeFileSync(csvAbs, toCsv(events), "utf8");
+
+  return { jsonRel, csvRel, count: events.length };
+}
+
+function buildUnifiedEventEnvelope(params) {
+  const metric = params?.metric || {};
+  const platform = params?.platform || "claude";
+  const projectId = params?.projectId || "unknown-project";
+
+  return {
+    version: 1,
+    platform,
+    eventName: metric.event || "UnknownEvent",
+    sessionId: metric.sessionId || "unknown",
+    repoId: projectId,
+    ts: metric.ts || nowIso(),
+    signals: {
+      tool: metric.tool || null,
+      action: metric.action || null,
+      meta: metric.meta || {},
+    },
+    reasonCodes: metric.reasonCodes || [],
+    confidence: confidenceFromReasonCodes(metric.reasonCodes || []),
+  };
+}
+
+function appendUnifiedEvents(cwd, envelopes) {
+  const abs = path.join(cwd, OUTBOX_REL);
+  appendJsonl(abs, envelopes || []);
+  return abs;
+}
+
+function buildUnifiedBenefitRecord(params) {
+  const weekly = params?.weekly || {};
+  const platform = params?.platform || "claude";
+  const savings = weekly.savingsFirstSummary || {};
+
+  return {
+    version: 1,
+    sourcePlatform: platform,
+    minutesSavedEstimate: Number(savings.estimatedMinutesSaved || 0),
+    riskEventsPrevented: Number(weekly.riskyIntercepts || 0),
+    contextPressureDelta: -1 * Number(savings.outputsTrimmed || weekly.largeOutputsStored || 0),
+    confidenceLabel: savings.confidenceLabel || (Number(weekly.sessions || 0) >= 5 ? "medium" : "low"),
+  };
+}
+
+function readOutbox(cwd) {
+  const abs = path.join(cwd, OUTBOX_REL);
+  return parseJsonl(abs);
+}
+
+module.exports = {
+  OUTBOX_REL,
+  OUTCOME_EVENTS_REL,
+  OUTCOME_EXPORTS_REL,
+  confidenceFromReasonCodes,
+  buildOutcomeEvent,
+  appendOutcomeEvents,
+  readOutcomeEvents,
+  aggregateOutcomeEvents,
+  exportOutcomeEvents,
+  buildUnifiedEventEnvelope,
+  buildUnifiedBenefitRecord,
+  appendUnifiedEvents,
+  readOutbox,
+};