autoctxd 0.4.1

package/src/util/metrics.ts

@@ -0,0 +1,236 @@
+// Token accounting: tracks real metrics about context value
+// - exploration calls before first edit
+// - time to first substantive action
+// - context hit rate (explored file was in injected context)
+
+import { getDb } from "../db/sqlite/schema";
+
+// Rough GPT-style estimate: ~4 chars per token for English code/prose
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Record the context injection at session start.
+ * Stores token count + list of files/topics mentioned in the injected context.
+ */
+export function recordInjection(
+  sessionId: string,
+  contextBlock: string,
+  projectPath: string,
+  injectedFiles?: string[],
+): void {
+  const db = getDb();
+  const tokens = estimateTokens(contextBlock);
+  const filesJson = injectedFiles && injectedFiles.length > 0
+    ? JSON.stringify(injectedFiles.map(f => normalizePath(f)))
+    : null;
+  try {
+    db.prepare(`
+      INSERT INTO token_metrics (session_id, tokens_injected, injected_files)
+      VALUES (?, ?, ?)
+    `).run(sessionId, tokens, filesJson);
+    db.prepare(`
+      UPDATE sessions SET tokens_injected = ? WHERE session_id = ?
+    `).run(tokens, sessionId);
+  } catch {
+    // Metrics must never block the hook
+  }
+}
+
+/**
+ * Record an exploration call (Read/Glob/Grep).
+ * Checks if the explored file was already covered by injected context (hit vs miss).
+ * Only counts calls before the first edit.
+ */
+export function recordExplorationCall(sessionId: string, exploredPath: string): void {
+  const db = getDb();
+  try {
+    const row = db.prepare(
+      "SELECT injected_files, first_edit_recorded FROM token_metrics WHERE session_id = ?"
+    ).get(sessionId) as { injected_files: string | null; first_edit_recorded: number } | undefined;
+
+    if (!row) return;
+
+    // Only count exploration before first edit
+    if (row.first_edit_recorded) return;
+
+    const normalized = normalizePath(exploredPath);
+    let isHit = false;
+
+    if (row.injected_files) {
+      try {
+        const files: string[] = JSON.parse(row.injected_files);
+        isHit = files.some(f => normalized.includes(f) || f.includes(normalized));
+      } catch {
+        // Bad JSON, treat as miss
+      }
+    }
+
+    if (isHit) {
+      db.prepare(`
+        UPDATE token_metrics
+        SET context_hit_count = context_hit_count + 1,
+            exploration_calls_before_edit = exploration_calls_before_edit + 1
+        WHERE session_id = ?
+      `).run(sessionId);
+    } else {
+      db.prepare(`
+        UPDATE token_metrics
+        SET context_miss_count = context_miss_count + 1,
+            exploration_calls_before_edit = exploration_calls_before_edit + 1
+        WHERE session_id = ?
+      `).run(sessionId);
+    }
+  } catch {
+    // Silent
+  }
+}
+
+/**
+ * Record the first substantive action (Edit/Write/Bash).
+ * Calculates time_to_first_edit_sec from session start.
+ */
+export function recordFirstEdit(sessionId: string): void {
+  const db = getDb();
+  try {
+    const row = db.prepare(
+      "SELECT first_edit_recorded FROM token_metrics WHERE session_id = ?"
+    ).get(sessionId) as { first_edit_recorded: number } | undefined;
+
+    if (!row || row.first_edit_recorded) return;
+
+    // Get session start time
+    const session = db.prepare(
+      "SELECT started_at FROM sessions WHERE session_id = ?"
+    ).get(sessionId) as { started_at: string } | undefined;
+
+    if (!session) return;
+
+    const startedAt = new Date(session.started_at + "Z").getTime();
+    const now = Date.now();
+    const elapsedSec = Math.round((now - startedAt) / 1000 * 10) / 10;
+
+    db.prepare(`
+      UPDATE token_metrics
+      SET time_to_first_edit_sec = ?, first_edit_recorded = 1
+      WHERE session_id = ?
+    `).run(elapsedSec, sessionId);
+  } catch {
+    // Silent
+  }
+}
+
+/**
+ * Calculate estimated tokens saved based on real data.
+ * Called at session end (Stop hook).
+ *
+ * Heuristics (conservative):
+ * - Each context hit = ~80 tokens saved (a Read call that was informed by context)
+ * - Baseline: sessions without context average N exploration calls;
+ *   each call below baseline = ~50 tokens saved
+ */
+export function recordSavings(sessionId: string, observations: Array<{ summary: string }>): void {
+  const db = getDb();
+  try {
+    const row = db.prepare(`
+      SELECT tokens_injected, context_hit_count, context_miss_count,
+             exploration_calls_before_edit
+      FROM token_metrics WHERE session_id = ?
+    `).get(sessionId) as {
+      tokens_injected: number;
+      context_hit_count: number;
+      context_miss_count: number;
+      exploration_calls_before_edit: number;
+    } | undefined;
+
+    if (!row || row.tokens_injected === 0) return;
+
+    // Calculate baseline: avg exploration calls in sessions WITHOUT context
+    const baseline = db.prepare(`
+      SELECT AVG(tm.exploration_calls_before_edit) as avg_calls
+      FROM token_metrics tm
+      WHERE tm.tokens_injected = 0 AND tm.exploration_calls_before_edit > 0
+    `).get() as { avg_calls: number | null } | undefined;
+
+    const TOKENS_PER_HIT = 80;
+    const TOKENS_PER_AVOIDED_CALL = 50;
+
+    let saved = 0;
+
+    // Value from context hits
+    saved += row.context_hit_count * TOKENS_PER_HIT;
+
+    // Value from avoided exploration (if we have baseline data)
+    if (baseline?.avg_calls && baseline.avg_calls > row.exploration_calls_before_edit) {
+      const avoidedCalls = Math.round(baseline.avg_calls - row.exploration_calls_before_edit);
+      saved += avoidedCalls * TOKENS_PER_AVOIDED_CALL;
+    }
+
+    // Calculate relevance score: hit rate as 0-1
+    const totalExploration = row.context_hit_count + row.context_miss_count;
+    const relevanceScore = totalExploration > 0
+      ? row.context_hit_count / totalExploration
+      : 0;
+
+    db.prepare(`
+      UPDATE token_metrics
+      SET estimated_tokens_saved = ?, context_relevance_score = ?
+      WHERE session_id = ?
+    `).run(saved, Math.round(relevanceScore * 100) / 100, sessionId);
+  } catch {
+    // Silent
+  }
+}
+
+export interface GlobalMetrics {
+  totalInjected: number;
+  totalSaved: number;
+  sessionsWithContext: number;
+  avgInjectedPerSession: number;
+  avgExplorationBeforeEdit: number;
+  avgTimeToFirstEditSec: number | null;
+  contextHitRate: number;
+  totalHits: number;
+  totalMisses: number;
+}
+
+export function getGlobalMetrics(): GlobalMetrics {
+  const db = getDb();
+  const row = db.prepare(`
+    SELECT
+      COALESCE(SUM(tokens_injected), 0) as totalInjected,
+      COALESCE(SUM(estimated_tokens_saved), 0) as totalSaved,
+      COUNT(*) as sessionsWithContext,
+      COALESCE(AVG(exploration_calls_before_edit), 0) as avgExploration,
+      AVG(CASE WHEN time_to_first_edit_sec IS NOT NULL THEN time_to_first_edit_sec END) as avgTimeToEdit,
+      COALESCE(SUM(context_hit_count), 0) as totalHits,
+      COALESCE(SUM(context_miss_count), 0) as totalMisses
+    FROM token_metrics WHERE tokens_injected > 0
+  `).get() as any;
+
+  const totalExploration = row.totalHits + row.totalMisses;
+
+  return {
+    totalInjected: row.totalInjected,
+    totalSaved: row.totalSaved,
+    sessionsWithContext: row.sessionsWithContext,
+    avgInjectedPerSession: row.sessionsWithContext > 0
+      ? Math.round(row.totalInjected / row.sessionsWithContext)
+      : 0,
+    avgExplorationBeforeEdit: Math.round(row.avgExploration * 10) / 10,
+    avgTimeToFirstEditSec: row.avgTimeToEdit !== null
+      ? Math.round(row.avgTimeToEdit * 10) / 10
+      : null,
+    contextHitRate: totalExploration > 0
+      ? Math.round((row.totalHits / totalExploration) * 100)
+      : 0,
+    totalHits: row.totalHits,
+    totalMisses: row.totalMisses,
+  };
+}
+
+/** Normalize file path for comparison — extract basename for fuzzy matching */
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, "/").split("/").pop() || filePath;
+}

package/src/util/path.ts

@@ -0,0 +1,57 @@
+// Canonicalize file paths so the same file produces the same string across
+// Windows ("C:\\Users\\..."), Git Bash/MSYS ("/c/Users/..."), Cygwin
+// ("/cygdrive/c/Users/..."), and forward-slash POSIX. Without this, the same
+// file gets counted as multiple entries in hot files / pattern detection.
+//
+// Output format: lowercase drive + forward slashes ("c:/Users/Eliel/...").
+
+const WINDOWS_ABS = /^([a-zA-Z]):[\\/]/;
+const MSYS_ABS = /^\/([a-zA-Z])\/(.*)$/;
+const CYGWIN_ABS = /^\/cygdrive\/([a-zA-Z])\/(.*)$/;
+
+export function normalizePath(input: string): string {
+  if (!input) return input;
+  let p = input.trim();
+  if (!p) return p;
+
+  // Strip surrounding quotes
+  if ((p.startsWith('"') && p.endsWith('"')) || (p.startsWith("'") && p.endsWith("'"))) {
+    p = p.slice(1, -1);
+  }
+
+  // /cygdrive/c/Users/... -> c:/Users/...
+  const cyg = p.match(CYGWIN_ABS);
+  if (cyg) {
+    return `${cyg[1].toLowerCase()}:/${cyg[2].replace(/\\/g, "/")}`;
+  }
+
+  // /c/Users/... -> c:/Users/...  (only when first segment is a single letter)
+  const msys = p.match(MSYS_ABS);
+  if (msys) {
+    return `${msys[1].toLowerCase()}:/${msys[2].replace(/\\/g, "/")}`;
+  }
+
+  // C:\Users\... or C:/Users/... -> c:/Users/...
+  const win = p.match(WINDOWS_ABS);
+  if (win) {
+    const drive = win[1].toLowerCase();
+    const rest = p.slice(2).replace(/\\/g, "/").replace(/^\/+/, "");
+    return `${drive}:/${rest}`;
+  }
+
+  // POSIX absolute or relative — just normalize separators
+  return p.replace(/\\/g, "/");
+}
+
+export function normalizePaths(paths: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const p of paths) {
+    const n = normalizePath(p);
+    if (n && !seen.has(n)) {
+      seen.add(n);
+      out.push(n);
+    }
+  }
+  return out;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}