@bli-cockpit/cli 0.1.6 → 0.1.8

package/dist/adapters/attribution-core.js

@@ -0,0 +1,172 @@
+import crypto from "node:crypto";
+import path from "node:path";
+/**
+ * Shared deterministic attribution core for agent session transcripts (Codex
+ * and Claude Code). Both adapters extract source-shaped signals, normalize them
+ * into an {@link AttributionSignalSet}, and score them here against the same
+ * candidate worktrees with the same weights, threshold, and margin. Keeping one
+ * scorer means cross-source comparison is honest: a session attributes the same
+ * way no matter which agent produced it.
+ *
+ * A session is attributed only when exactly one worktree clearly wins (best
+ * score ≥ threshold AND beats the runner-up by the margin). Close calls stay
+ * ambiguous instead of being duplicated across repos or guessed.
+ */
+export const SCORE_CWD_MATCH = 0.5;
+export const SCORE_WORKSPACE_ROOT_MATCH = 0.1;
+export const SCORE_ORIGIN_MATCH = 0.3;
+export const SCORE_BRANCH_MATCH = 0.15;
+export const SCORE_HEAD_SHA_MATCH = 0.05;
+export const ATTRIBUTION_MIN_SCORE = 0.4;
+export const ATTRIBUTION_MIN_MARGIN = 0.15;
+export const SESSION_FILE_UUID_PATTERN = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+export function scoreSignalsAgainstWorktrees(signals, worktrees, options = {}) {
+    const originLabel = options.originLabel ?? "origin_url_match";
+    const hasAnySignal = signals.cwds.length > 0 ||
+        signals.workspaceRoots.length > 0 ||
+        signals.originUrls.length > 0 ||
+        signals.branches.length > 0 ||
+        signals.headShas.length > 0;
+    if (!hasAnySignal) {
+        return unattributed("no_repo_signals");
+    }
+    // D6 deepest-root tie-break: a path signal can sit inside several candidate
+    // roots when one root is nested inside another (e.g. Claude's
+    // `<repo>/.claude/worktrees/<name>` linked worktrees, or any monorepo with a
+    // nested package that is itself a worktree). Crediting every containing root
+    // leaves the session ambiguous forever. Instead, only the DEEPEST containing
+    // root earns the path score, which is also the most specific (correct) match.
+    const cwdWinners = deepestContainers(signals.cwds, worktrees);
+    const workspaceRootWinners = deepestContainers(signals.workspaceRoots, worktrees);
+    const scored = worktrees.map((worktree) => {
+        const matched = [];
+        let score = 0;
+        let pathScore = 0;
+        if (cwdWinners.has(worktree.worktree_fingerprint)) {
+            score += SCORE_CWD_MATCH;
+            pathScore += SCORE_CWD_MATCH;
+            matched.push("cwd_match");
+        }
+        if (workspaceRootWinners.has(worktree.worktree_fingerprint)) {
+            score += SCORE_WORKSPACE_ROOT_MATCH;
+            pathScore += SCORE_WORKSPACE_ROOT_MATCH;
+            matched.push("workspace_root_match");
+        }
+        if (worktree.repo_origin_url &&
+            signals.originUrls.includes(worktree.repo_origin_url)) {
+            score += SCORE_ORIGIN_MATCH;
+            matched.push(originLabel);
+        }
+        if (signals.branches.includes(worktree.branch)) {
+            score += SCORE_BRANCH_MATCH;
+            matched.push("branch_match");
+        }
+        if (worktree.head_sha && signals.headShas.includes(worktree.head_sha)) {
+            score += SCORE_HEAD_SHA_MATCH;
+            matched.push("head_sha_match");
+        }
+        return { worktree, score, pathScore, matched };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    const best = scored[0];
+    const secondBestScore = scored[1]?.score ?? 0;
+    if (!best || best.score === 0) {
+        const reason = signals.cwds.length > 0 || signals.workspaceRoots.length > 0
+            ? "cwd_outside_scanned_worktrees"
+            : "no_matching_worktree_signals";
+        return unattributed(reason);
+    }
+    const score = clampScore(best.score);
+    const pathScore = clampScore(best.pathScore);
+    if (best.score >= ATTRIBUTION_MIN_SCORE &&
+        best.score - secondBestScore >= ATTRIBUTION_MIN_MARGIN) {
+        return {
+            state: "attributed",
+            reason: "deterministic_signal_match",
+            signals: best.matched,
+            attribution_score: score,
+            path_score: pathScore,
+            worktree: best.worktree,
+        };
+    }
+    return {
+        state: "ambiguous",
+        reason: best.score - secondBestScore < ATTRIBUTION_MIN_MARGIN
+            ? "multiple_worktrees_close_scores"
+            : "signal_score_below_threshold",
+        signals: best.matched,
+        attribution_score: score,
+        path_score: pathScore,
+        worktree: null,
+    };
+}
+function unattributed(reason) {
+    return {
+        state: "unattributed",
+        reason,
+        signals: [],
+        attribution_score: 0,
+        path_score: 0,
+        worktree: null,
+    };
+}
+/**
+ * For each path signal, the single worktree whose root most specifically
+ * contains it (the longest containing root). Returns the set of worktree
+ * fingerprints that win at least one path signal — these are the only roots
+ * credited with the path score (D6).
+ */
+function deepestContainers(signalValues, worktrees) {
+    const winners = new Set();
+    for (const value of signalValues) {
+        let best = null;
+        let bestRootLength = -1;
+        for (const worktree of worktrees) {
+            if (!isPathWithin(value, worktree.repo_root))
+                continue;
+            const rootLength = path.resolve(worktree.repo_root).length;
+            if (rootLength > bestRootLength) {
+                best = worktree;
+                bestRootLength = rootLength;
+            }
+        }
+        if (best)
+            winners.add(best.worktree_fingerprint);
+    }
+    return winners;
+}
+export function isPathWithin(candidate, root) {
+    const normalizedCandidate = path.resolve(candidate);
+    const normalizedRoot = path.resolve(root);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + path.sep));
+}
+export function clampScore(value) {
+    return Math.min(1, Math.max(0, Number(value.toFixed(4))));
+}
+export function sessionIdFromFileName(fileName) {
+    const match = fileName.match(SESSION_FILE_UUID_PATTERN);
+    return match?.[1]?.toLowerCase() ?? null;
+}
+/**
+ * Session ids come from file content and end up inside remote object keys, so
+ * anything outside the safe charset falls back to a hash of the raw value
+ * instead of poisoning every begin request in the batch.
+ */
+export function sanitizeSessionId(value) {
+    if (!value)
+        return null;
+    if (/^[A-Za-z0-9._-]{4,80}$/.test(value))
+        return value;
+    return shortHash(value);
+}
+export function shortHash(value) {
+    return crypto
+        .createHash("sha256")
+        .update(value, "utf8")
+        .digest("hex")
+        .slice(0, 16);
+}
+export function sha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}