event-log.ts

/**
 * Phase 6 subtasks 6.1 + 6.2 — hook-events JSONL log.
 *
 * Writes to `<projectRoot>/.token-pilot/hook-events.jsonl` with the
 * schema specified in TP-c2a acceptance:
 *
 *   { ts, session_id, agent_type, agent_id, event, file, lines,
 *     estTokens, summaryTokens, savedTokens }
 *
 * Rotation: when the current file grows past `ROTATION_THRESHOLD_BYTES`
 * (10 MB), it is renamed to `hook-events.<unix-ms>.jsonl` and a new
 * empty file begins.
 *
 * Retention: `applyRetention` deletes rotated files older than
 * `RETENTION_MAX_AGE_DAYS` (30 days) and trims the directory down to
 * `RETENTION_MAX_TOTAL_BYTES` (100 MB) by removing the oldest archives
 * first. The current file is never deleted.
 *
 * Legacy coexistence: the old `.token-pilot/hook-denied.jsonl` is left
 * in place — this module writes only to the new file.
 */

import { promises as fs } from "node:fs";
import { join } from "node:path";

export const ROTATION_THRESHOLD_BYTES = 10_000_000;
export const RETENTION_MAX_AGE_DAYS = 30;
export const RETENTION_MAX_TOTAL_BYTES = 100_000_000;

const CURRENT_FILE = "hook-events.jsonl";
const ARCHIVE_RE = /^hook-events\.\d+\.jsonl$/;

export interface HookEvent {
  ts: number;
  session_id: string;
  /** null for top-level session; agent_type string inside a subagent. */
  agent_type: string | null;
  agent_id: string | null;
  /**
   * v0.34.0 — agent_id of the parent that dispatched this subagent.
   * Claude Code now ships `x-claude-code-parent-agent-id` headers
   * and exposes the value in PostToolUse:Task input. Capturing it
   * lets us reconstruct the full dispatch chain
   * (main → general-purpose → tp-* delegate, etc.) instead of seeing
   * only the leaf agent. Optional — older Claude Code versions
   * never populate it; events stay shape-compatible.
   */
  parent_agent_id?: string | null;
  /**
   * v0.45.0 — root/parent SESSION id (distinct from agent_id). Claude Code
   * exposes `parent_session_id` in subagent hook payloads (binary:
   * `if(D.parentSessionId) X.parent_session_id = D.parentSessionId`). A
   * subagent's MCP server is spawned with CLAUDE_CODE_SESSION_ID = the AGENT
   * session, so its tool-call and denial savings get tagged with that id and
   * the statusline's main-session filter drops them. Capturing the parent lets
   * the badge roll subagent savings up to the conversation that spawned them.
   * Optional — absent on the main thread and on older Claude Code.
   */
  parent_session_id?: string | null;
  /**
   * v0.38.0 — id of the token-pilot workflow this event belongs to,
   * when one is active (TOKEN_PILOT_WORKFLOW_ID set). Lets fleet-level
   * budget + telemetry slice a fan-out run out of the global log.
   * Optional — absent when no workflow is active.
   */
  workflow_id?: string;
  /**
   * Loom spine link — id of the Loom task this event belongs to, when the
   * session was launched by Loom (LOOM_TASK_ID set). Lets Loom attribute token
   * savings to a task exactly. Optional — absent outside Loom, so standalone
   * token-pilot events stay byte-identical to before.
   */
  task_id?: string;
  event:
    | "denied"
    | "allowed"
    | "bypass"
    | "pass-through"
    | "task"
    | "diagnostic"
    | string;
  file: string;
  lines: number;
  estTokens: number;
  /** Tokens delivered back to the agent as the summary; 0 for allow/bypass. */
  summaryTokens: number;
  /** estTokens - summaryTokens; 0 for allow/bypass. */
  savedTokens: number;

  // ─── diagnostic (v0.34.0) ────────────────────────────────────────
  // Populated only on `event: "diagnostic"` records — emitted by
  // hooks/handlers when an edge-case fires (matcher empty, WSL
  // path rejected, validation coerced, …). Every diagnostic gets a
  // stable `code` so frequencies are countable in stats.
  /** "info" | "warn" | "error" — severity of the diagnostic. */
  level?: "info" | "warn" | "error";
  /** Stable searchable identifier — e.g. `force_subagents_no_agents`. */
  code?: string;
  /** Optional small map of context — must be sanitised by caller. */
  detail?: Record<string, unknown>;

  // ─── timing (v0.34.0 Pack 3) ─────────────────────────────────────
  /**
   * Wall-clock duration of the hook handler that emitted this event,
   * milliseconds. Always optional — only the safe-runner wrapper sets
   * it, and only on the FINAL diagnostic record per hook invocation.
   */
  duration_ms?: number;

  // ─── task-specific (v0.31.0) ─────────────────────────────────────
  // These are populated only on `event: "task"` records emitted by
  // `processPostTask`. They are optional on the interface so the rest
  // of the pipeline (existing Read/Bash events) stays unchanged.
  /** The subagent_type Claude Code dispatched (`tp-*` or `general-purpose`…). */
  subagent_type?: string;
  /**
   * Heuristic match against `tp-*` agent frontmatter. Set only when
   * `subagent_type` is NOT already a tp-*. null when no match fires.
   */
  matched_tp_agent?: string | null;
  /** Confidence of the heuristic match (omitted when matched_tp_agent=null). */
  match_confidence?: "high" | "low";
  /** Response budget declared in the agent markdown body, or null. */
  budget?: number | null;
  /** actualTokens > budget × (1 + tolerance). */
  overBudget?: boolean;
}

export function eventLogDir(projectRoot: string): string {
  return join(projectRoot, ".token-pilot");
}

export function currentLogPath(projectRoot: string): string {
  return join(eventLogDir(projectRoot), CURRENT_FILE);
}

// ─── pure: rotation predicate ───────────────────────────────────────────────

/**
 * Decide whether the current log file has grown past the rotation
 * threshold and should be archived before the next append.
 */
export function shouldRotate(
  stat: { size: number },
  thresholdBytes: number = ROTATION_THRESHOLD_BYTES,
): boolean {
  return stat.size >= thresholdBytes;
}

// ─── pure: retention policy ─────────────────────────────────────────────────

/**
 * Given the full list of archive files with their mtime + size, return
 * the subset whose paths should be deleted to satisfy:
 *   (a) maxAgeDays — delete anything older
 *   (b) maxTotalBytes — delete oldest first until total fits
 *
 * `now` is passed in to keep the function deterministic for tests.
 */
export function retentionDeletions(
  files: Array<{ path: string; mtime: Date; size: number }>,
  now: Date,
  maxAgeDays: number = RETENTION_MAX_AGE_DAYS,
  maxTotalBytes: number = RETENTION_MAX_TOTAL_BYTES,
): string[] {
  const toDelete = new Set<string>();
  const maxAgeMs = maxAgeDays * 86_400_000;

  // (a) age-based
  const survivors: Array<{ path: string; mtime: Date; size: number }> = [];
  for (const f of files) {
    if (now.getTime() - f.mtime.getTime() > maxAgeMs) {
      toDelete.add(f.path);
    } else {
      survivors.push(f);
    }
  }

  // (b) size-based — delete oldest first from survivors until cap is met
  const totalSize = survivors.reduce((sum, f) => sum + f.size, 0);
  if (totalSize > maxTotalBytes) {
    const byOldest = [...survivors].sort(
      (a, b) => a.mtime.getTime() - b.mtime.getTime(),
    );
    let trimmed = totalSize;
    for (const f of byOldest) {
      if (trimmed <= maxTotalBytes) break;
      toDelete.add(f.path);
      trimmed -= f.size;
    }
  }

  return [...toDelete];
}

// ─── FS wrappers ────────────────────────────────────────────────────────────

async function ensureLogDir(projectRoot: string): Promise<void> {
  await fs.mkdir(eventLogDir(projectRoot), { recursive: true });
}

async function rotateIfNeeded(
  projectRoot: string,
  thresholdBytes: number = ROTATION_THRESHOLD_BYTES,
): Promise<void> {
  const current = currentLogPath(projectRoot);
  let stat: { size: number };
  try {
    const s = await fs.stat(current);
    stat = { size: s.size };
  } catch {
    return; // no current file → nothing to rotate
  }
  if (!shouldRotate(stat, thresholdBytes)) return;
  const archivePath = join(
    eventLogDir(projectRoot),
    `hook-events.${Date.now()}.jsonl`,
  );
  try {
    await fs.rename(current, archivePath);
  } catch {
    // Rename raced with another process; caller will just append onto
    // whichever file now exists.
  }
}

/**
 * Append one event to the current log file. Rotates first if the
 * current file has reached the threshold. Never throws — a failure
 * here must not break hook dispatch.
 */
export async function appendEvent(
  projectRoot: string,
  event: HookEvent,
): Promise<void> {
  try {
    // v0.38.0 — auto-tag with the active workflow id so every event
    // emitted inside a `token-pilot workflow` boundary is sliceable.
    // Read the env var directly here to keep call sites unchanged; an
    // explicit workflow_id on the event always wins.
    const wf =
      event.workflow_id ??
      process.env.TOKEN_PILOT_WORKFLOW_ID ??
      process.env.CLAUDE_CODE_WORKFLOW_ID ??
      process.env.LOOM_WORKFLOW_ID ??
      undefined;
    // Loom spine: tag the task id when the session was launched by Loom.
    // Env-driven so call sites stay unchanged; absent outside Loom → no field.
    const taskId = event.task_id ?? process.env.LOOM_TASK_ID ?? undefined;
    let tagged = event;
    if (wf) tagged = { ...tagged, workflow_id: wf };
    if (taskId) tagged = { ...tagged, task_id: taskId };
    await ensureLogDir(projectRoot);
    await rotateIfNeeded(projectRoot);
    const line = JSON.stringify(tagged) + "\n";
    await fs.appendFile(currentLogPath(projectRoot), line);
  } catch {
    /* silent — telemetry is best-effort */
  }
}

/**
 * v0.34.0 — convenience wrapper for emitting a `diagnostic` event.
 *
 * Diagnostics describe edge-case branches inside a normal handler
 * run (matcher returned no agents, WSL path rejected, MCP arg
 * coerced, etc.). They live in the project-local hook-events.jsonl
 * alongside the regular events so `stats --diagnostics` can count
 * them by code.
 *
 * If the projectRoot is not yet resolvable (the failure happened
 * before detection), prefer `appendError` from `core/error-log.ts`
 * — it falls back to a user-level path.
 *
 * Pure-ish: never throws. Same best-effort semantics as appendEvent.
 */
export async function appendDiagnostic(
  projectRoot: string,
  args: {
    code: string;
    level?: "info" | "warn" | "error";
    detail?: Record<string, unknown>;
    sessionId?: string;
    agentType?: string | null;
    agentId?: string | null;
    durationMs?: number;
  },
): Promise<void> {
  const rec: HookEvent = {
    ts: Date.now(),
    session_id: args.sessionId ?? "diagnostic",
    agent_type: args.agentType ?? null,
    agent_id: args.agentId ?? null,
    event: "diagnostic",
    file: "",
    lines: 0,
    estTokens: 0,
    summaryTokens: 0,
    savedTokens: 0,
    level: args.level ?? "info",
    code: args.code,
    detail: args.detail,
    duration_ms: args.durationMs,
  };
  await appendEvent(projectRoot, rec);
}

/**
 * Read all events from the current log file. Malformed JSONL lines are
 * skipped silently (a corrupted line should not poison the whole
 * dataset). Returns [] if the file is missing.
 */
export async function loadEvents(projectRoot: string): Promise<HookEvent[]> {
  let raw: string;
  try {
    raw = await fs.readFile(currentLogPath(projectRoot), "utf-8");
  } catch {
    return [];
  }
  const out: HookEvent[] = [];
  for (const line of raw.split("\n")) {
    if (!line.trim()) continue;
    try {
      out.push(JSON.parse(line) as HookEvent);
    } catch {
      // skip malformed
    }
  }
  return out;
}

/**
 * v0.33.0 (B5) — load events from EVERY `.token-pilot/hook-events.jsonl`
 * found at or below `repoRoot`. The hook writer resolves its own
 * project root from `process.cwd()` at the moment Claude Code spawns
 * us, which can land in a subdirectory of the actual repo (apps/admin,
 * apps/api, packages/prisma, …). Without this, `token-pilot stats`
 * sees only the top-level log and reports a fraction of the savings.
 *
 * Walks up to `maxDepth` levels and merges chronologically. Pure on
 * filesystem read errors — missing dirs are silently skipped.
 */
export async function loadEventsTree(
  repoRoot: string,
  maxDepth = 5,
): Promise<HookEvent[]> {
  const PRUNE = new Set([
    "node_modules",
    ".git",
    "dist",
    "build",
    ".next",
    ".turbo",
    ".cache",
    "coverage",
    ".vercel",
    ".vite",
  ]);
  const seen = new Set<string>();
  const all: HookEvent[] = [];

  async function visit(dir: string, depth: number): Promise<void> {
    if (depth > maxDepth) return;
    let entries: string[] = [];
    try {
      entries = await fs.readdir(dir);
    } catch {
      return;
    }
    if (entries.includes(".token-pilot")) {
      const logPath = join(dir, ".token-pilot", CURRENT_FILE);
      if (!seen.has(logPath)) {
        seen.add(logPath);
        try {
          const raw = await fs.readFile(logPath, "utf-8");
          for (const line of raw.split("\n")) {
            if (!line.trim()) continue;
            try {
              all.push(JSON.parse(line) as HookEvent);
            } catch {
              /* skip malformed */
            }
          }
        } catch {
          /* missing log */
        }
      }
    }
    for (const name of entries) {
      if (PRUNE.has(name)) continue;
      if (name.startsWith(".") && name !== ".claude") continue;
      const full = join(dir, name);
      try {
        const stat = await fs.stat(full);
        if (stat.isDirectory()) {
          await visit(full, depth + 1);
        }
      } catch {
        /* skip */
      }
    }
  }

  await visit(repoRoot, 0);
  // Sort chronologically so per-session aggregations stay correct.
  all.sort((a, b) => (a.ts || 0) - (b.ts || 0));
  return all;
}

/**
 * Enumerate all archive files (`hook-events.<ts>.jsonl`) with metadata
 * needed by `retentionDeletions`.
 */
async function listArchives(
  projectRoot: string,
): Promise<Array<{ path: string; mtime: Date; size: number }>> {
  const dir = eventLogDir(projectRoot);
  let entries: string[];
  try {
    entries = await fs.readdir(dir);
  } catch {
    return [];
  }
  const out: Array<{ path: string; mtime: Date; size: number }> = [];
  for (const name of entries) {
    if (!ARCHIVE_RE.test(name)) continue;
    const full = join(dir, name);
    try {
      const s = await fs.stat(full);
      out.push({ path: full, mtime: s.mtime, size: s.size });
    } catch {
      /* skip unreadable */
    }
  }
  return out;
}

/**
 * Apply age + size retention. Safe to call on startup; no-op when the
 * directory does not exist.
 */
export async function applyRetention(
  projectRoot: string,
  now: Date = new Date(),
): Promise<void> {
  const archives = await listArchives(projectRoot);
  const victims = retentionDeletions(archives, now);
  for (const p of victims) {
    try {
      await fs.unlink(p);
    } catch {
      /* ignore */
    }
  }
}