avorelo 0.1.0

package/scripts/lib/carry-forward-surfacing.js

@@ -0,0 +1,194 @@
+// Thin carry-forward surfacing utilities for wrappers
+// Local-first, deterministic, bounded
+const path = require("path");
+const fs = require("fs");
+
+const CARRY_FORWARD_PATH = ".claude/cco/state/reentry-carry-forward.json";
+const CARRY_FORWARD_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const MAX_HISTORY_DEPTH = 3; // Last 3 tool calls
+
+/**
+ * Capture bounded carry-forward state at session_end
+ * Minimal JavaScript implementation for sessionend.js
+ */
+function captureCarryForward(cwd, sessionId, toolHistory) {
+  try {
+    // Build state object
+    const state = {
+      capturedAt: new Date().toISOString(),
+      sessionId,
+      ttlMs: CARRY_FORWARD_TTL_MS,
+    };
+
+    // Store bounded tool history if provided
+    if (toolHistory && toolHistory.length > 0) {
+      state.toolHistory = {
+        toolNames: toolHistory.slice(-MAX_HISTORY_DEPTH),
+        lastRunAt: new Date().toISOString(),
+      };
+    }
+
+    // Persist to disk
+    const fullPath = path.join(cwd, CARRY_FORWARD_PATH);
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(fullPath, JSON.stringify(state, null, 2));
+
+    return state;
+  } catch (err) {
+    // Fail open - log error but don't break session end
+    console.error(`[carry-forward] Failed to capture: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Load carry-forward state from disk if it exists and is valid (within TTL)
+ * Returns null if no valid state, preserving fail-open contract
+ */
+function loadCarryForward(cwd) {
+  try {
+    const fullPath = path.join(cwd, ".claude", "cco", "state", "reentry-carry-forward.json");
+    const fs = require("fs");
+    if (!fs.existsSync(fullPath)) {
+      return null;
+    }
+    const state = JSON.parse(fs.readFileSync(fullPath, "utf8"));
+
+    // Simple TTL check: if TTL expired (10 minutes), return null
+    const capturedAt = new Date(state.capturedAt).getTime();
+    const age = Date.now() - capturedAt;
+    const TTL = state.ttlMs || (10 * 60 * 1000); // 10 minutes default
+    if (age > TTL) {
+      // Expired: clear and return null
+      try {
+        fs.unlinkSync(fullPath);
+      } catch {}
+      return null;
+    }
+    return state;
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Build human-readable continuity message from carry-forward state
+ * Bounded, explicit, non-magical
+ *
+ * @returns {string} message suitable for console or UI
+ */
+function buildContinuityMessage(state, opts = {}) {
+  const compact = opts.compact || false;
+
+  if (!state) {
+    return compact ? "" : "Fresh start";
+  }
+
+  // Calculate simple human-friendly time (e.g., "3 minutes ago")
+  const capturedAt = new Date(state.capturedAt).getTime();
+  const age = Date.now() - capturedAt;
+  const ageMinutes = Math.floor(age / (1000 * 60));
+  const ageText = ageMinutes <= 0 ? "just now" : `${ageMinutes} min ago`;
+
+  // If tool history available
+  if (state.toolHistory && state.toolHistory.toolNames && state.toolHistory.toolNames.length > 0) {
+    const lastTool = state.toolHistory.toolNames[state.toolHistory.toolNames.length - 1];
+    const count = state.toolHistory.toolNames.length;
+    if (compact) {
+      return `[resume: ${lastTool}, ${ageText}]`;
+    }
+    return `Resume context available (${ageText}). Last: ${lastTool} (${count} tool${count > 1 ? "s" : ""})`;
+  }
+
+  // Fallback if only loop summary
+  if (compact) {
+    return "[resume available]";
+  }
+  return `Resume context available (${ageText})`;
+}
+
+/**
+ * Build structured output for wrappers to use
+ *
+ * Input example: { cwd, sessionId }
+ * Output shape:
+ * {
+ *   reentryStatus: "fresh_start" | "resume_available",
+ *   continuityMessage: string (human-facing),
+ *   carryForward?: object (for wrappers with more complex needs)
+ * }
+ */
+function buildReentryOutput(input) {
+  const state = loadCarryForward(input.cwd);
+
+  if (!state) {
+    return {
+      reentryStatus: "fresh_start",
+      continuityMessage: "Fresh start",
+      carryForward: null,
+    };
+  }
+
+  return {
+    reentryStatus: "resume_available",
+    continuityMessage: buildContinuityMessage(state),
+    carryForward: state,
+  };
+}
+
+/**
+ * Validates consistency between carry-forward and continuity.json
+ * Ensures they don't give conflicting resume signals
+ * Returns any inconsistencies found (empty array if consistent)
+ */
+function validateCarryForwardContinuityConsistency(cwd) {
+  const inconsistencies = [];
+
+  try {
+    // Check continuity state
+    const continuityPath = path.join(cwd, ".claude", "cco", "state", "continuity.json");
+    let hasContinuity = false;
+    let continuityState = null;
+
+    if (fs.existsSync(continuityPath)) {
+      try {
+        continuityState = JSON.parse(fs.readFileSync(continuityPath, "utf8"));
+        hasContinuity = continuityState.sessionId && continuityState.reEntryCount > 0;
+      } catch {
+        // Invalid continuity.json - ignore for consistency check
+      }
+    }
+
+    // Check carry-forward state
+    const carryForward = loadCarryForward(cwd);
+    const hasValidCarryForward = carryForward !== null;
+
+    // Consistency rule: If carry-forward is available, consistency state should be re-entry
+    if (hasValidCarryForward && !hasContinuity) {
+      // Edge case: carry-forward exists but continuity doesn't (first session with carry-forward)
+      // This can happen on first session after carry-forward capture
+      // Not technically inconsistent, but good to know about
+      console.error("[consistency] Note: carry-forward exists but no continuity state");
+    }
+
+    // If continuity says re-entry but carry-forward is expired, that's consistent
+    // (we prefer carry-forward over continuity due to more specific context)
+
+  } catch (err) {
+    // Failed to check consistency - log but don't fail
+    console.error(`[consistency] Failed to validate consistency: ${err.message}`);
+  }
+
+  return inconsistencies;
+}
+
+module.exports = {
+  captureCarryForward,
+  loadCarryForward,
+  buildContinuityMessage,
+  buildReentryOutput,
+  validateCarryForwardContinuityConsistency
+};

package/scripts/lib/ccusage-adapter.js

@@ -0,0 +1,188 @@
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const { nowIso, safeWriteJson, safeReadJson } = require("./fsx");
+const { buildOutcomeEvent, appendOutcomeEvents } = require("./unified-events");
+
+function run(command, args, cwd) {
+  return spawnSync(command, args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 30000,
+  });
+}
+
+function parseJsonMaybe(text) {
+  try {
+    return JSON.parse(text || "{}");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeCcusageRows(payload) {
+  if (!payload) return [];
+  if (Array.isArray(payload)) return payload;
+  if (Array.isArray(payload.data)) return payload.data;
+  if (Array.isArray(payload.rows)) return payload.rows;
+  if (Array.isArray(payload.daily)) return payload.daily;
+  if (Array.isArray(payload.result)) return payload.result;
+  return [];
+}
+
+function numeric(row, keys) {
+  for (const k of keys) {
+    const v = Number(row?.[k]);
+    if (Number.isFinite(v)) return v;
+  }
+  return 0;
+}
+
+function rowToMetric(row, sessionId) {
+  const date = String(row.date || row.day || row.bucket || nowIso().slice(0, 10));
+  const totalCost = numeric(row, ["cost", "totalCost", "total_cost", "usd", "costUsd"]);
+  const totalTokens = numeric(row, ["tokens", "totalTokens", "total_tokens", "inputTokens", "outputTokens"]);
+
+  return {
+    ts: `${date}T00:00:00.000Z`,
+    sessionId,
+    event: "CcusageImport",
+    tool: "ccusage",
+    action: "import",
+    reasonCodes: ["CCUSAGE_IMPORT"],
+    meta: {
+      measured_value: totalCost > 0 ? totalCost : totalTokens,
+      estimated_counterfactual_value: totalCost > 0 ? Math.round(totalCost * 0.12 * 100) / 100 : Math.round(totalTokens * 0.08),
+      date,
+      totalCost,
+      totalTokens,
+      provider: row.provider || null,
+      model: row.model || null,
+    },
+  };
+}
+
+function buildImportSummary(rows) {
+  const totalCost = rows.reduce((acc, row) => acc + numeric(row, ["cost", "totalCost", "total_cost", "usd", "costUsd"]), 0);
+  const totalTokens = rows.reduce((acc, row) => acc + numeric(row, ["tokens", "totalTokens", "total_tokens", "inputTokens", "outputTokens"]), 0);
+  return {
+    rows: rows.length,
+    totalCost: Math.round(totalCost * 100) / 100,
+    totalTokens: Math.round(totalTokens),
+  };
+}
+
+function fixtureRows() {
+  const now = new Date();
+  const day1 = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+  const day2 = new Date(now.getTime() - 1 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+  return [
+    { date: day1, cost: 4.25, tokens: 125000, provider: "claude", model: "sonnet" },
+    { date: day2, cost: 2.75, tokens: 93000, provider: "claude", model: "haiku" },
+  ];
+}
+
+function runCcusageCommand(cwd, flavor) {
+  const cmd = "npx";
+  const pkg = flavor === "codex" ? "@ccusage/codex@latest" : "ccusage@latest";
+  const args = ["--yes", pkg, "daily", "--json"];
+  return run(cmd, args, cwd);
+}
+
+function importCcusageSignals(cwd, options = {}) {
+  const flavor = options.flavor || "claude";
+  const projectId = options.projectId || path.basename(cwd).toLowerCase();
+  const userId = options.userId || process.env.CCO_USER_ID || "local-user";
+  const sessionId = `ccusage-${Date.now()}`;
+
+  if (options?.fixture || process.env.CCO_CCUSAGE_FIXTURE === "1") {
+    const rows = fixtureRows();
+    const summary = buildImportSummary(rows);
+    const metrics = rows.map((row) => rowToMetric(row, sessionId));
+    const outcomes = metrics.map((metric) =>
+      buildOutcomeEvent({
+        metric,
+        platform: flavor === "codex" ? "codex" : "claude",
+        projectId,
+        repoId: projectId,
+        userId,
+      })
+    );
+    appendOutcomeEvents(cwd, outcomes);
+    const ts = nowIso().replace(/[:.]/g, "-");
+    const rel = `.claude/cco/events/ccusage-import-${flavor}-${ts}.json`;
+    safeWriteJson(cwd, rel, { importedAt: nowIso(), flavor, summary, rows, outcomes, fixture: true });
+    safeWriteJson(cwd, ".claude/cco/events/ccusage-latest.json", { importedAt: nowIso(), flavor, summary, artifact: rel, fixture: true });
+    return { ok: true, flavor, summary, artifact: rel, eventsWritten: outcomes.length, fixture: true };
+  }
+
+  const proc = runCcusageCommand(cwd, flavor);
+  if (proc.status !== 0) {
+    return {
+      ok: false,
+      reason: "ccusage-unavailable",
+      stderr: String(proc.stderr || "").slice(0, 1000),
+      stdout: String(proc.stdout || "").slice(0, 1000),
+    };
+  }
+
+  const payload = parseJsonMaybe(proc.stdout);
+  if (!payload) {
+    return {
+      ok: false,
+      reason: "ccusage-invalid-json",
+      stdout: String(proc.stdout || "").slice(0, 1000),
+    };
+  }
+
+  const rows = normalizeCcusageRows(payload);
+  const summary = buildImportSummary(rows);
+
+  const metrics = rows.map((row) => rowToMetric(row, sessionId));
+  const outcomes = metrics.map((metric) =>
+    buildOutcomeEvent({
+      metric,
+      platform: flavor === "codex" ? "codex" : "claude",
+      projectId,
+      repoId: projectId,
+      userId,
+    })
+  );
+  appendOutcomeEvents(cwd, outcomes);
+
+  const ts = nowIso().replace(/[:.]/g, "-");
+  const rel = `.claude/cco/events/ccusage-import-${flavor}-${ts}.json`;
+  safeWriteJson(cwd, rel, {
+    importedAt: nowIso(),
+    flavor,
+    summary,
+    rows,
+    outcomes,
+  });
+
+  safeWriteJson(cwd, ".claude/cco/events/ccusage-latest.json", {
+    importedAt: nowIso(),
+    flavor,
+    summary,
+    artifact: rel,
+  });
+
+  return {
+    ok: true,
+    flavor,
+    summary,
+    artifact: rel,
+    eventsWritten: outcomes.length,
+  };
+}
+
+function readLatestCcusageImport(cwd) {
+  return safeReadJson(cwd, ".claude/cco/events/ccusage-latest.json", null);
+}
+
+module.exports = {
+  importCcusageSignals,
+  readLatestCcusageImport,
+  normalizeCcusageRows,
+};