@kennykeni/agent-trace 0.1.2 → 0.1.3

package/README.md

@@ -49,13 +49,16 @@ bunx @kennykeni/agent-trace status
 
 ## What `init` does
 
-Configures the target repo's provider settings:
+Creates `.agent-trace/config.json` with default settings and configures the target repo's provider hooks:
 
-| Provider   | Config written                            |
-| ---------- | ----------------------------------------- |
-| Cursor     | `.cursor/hooks.json`                      |
-| Claude Code| `.claude/settings.json`                   |
-| OpenCode   | `.opencode/plugins/agent-trace.ts`        |
+| File                                    | Purpose                          |
+| --------------------------------------- | -------------------------------- |
+| `.agent-trace/config.json`              | Extensions and ignore settings   |
+| `.cursor/hooks.json`                    | Cursor hook registration         |
+| `.claude/settings.json`                 | Claude Code hook registration    |
+| `.opencode/plugins/agent-trace.ts`      | OpenCode plugin registration     |
+
+Existing `config.json` files are never overwritten — only created when absent.
 
 ## How it works
 
@@ -72,20 +75,49 @@ Additional artifacts are written by extensions under `.agent-trace/`:
 - `diffs/<provider>/<session>.patch` -- diff artifacts when available (`diffs` extension)
 - `line-hashes/<provider>/<session>.jsonl` -- per-line content hashes (`line-hashes` extension)
 
-## Extensions
-
-Extensions are pluggable modules that run alongside the core trace pipeline. Four are built in: `raw-events`, `diffs`, `messages`, and `line-hashes`. All extensions are enabled by default.
+## Configuration
 
-To control which extensions run, create `.agent-trace/config.json` in your project root:
+`init` generates `.agent-trace/config.json` with these defaults:
 
 ```json
-{ "extensions": ["diffs", "messages"] }
+{
+  "extensions": ["diffs", "line-hashes", "raw-events", "messages"],
+  "useGitignore": true,
+  "useBuiltinSensitive": true,
+  "ignore": [],
+  "ignoreMode": "redact"
+}
 ```
 
-- **File absent** -- all registered extensions run (default)
+### Extensions
+
+Extensions are pluggable modules that run alongside the core trace pipeline. Four are built in: `raw-events`, `diffs`, `messages`, and `line-hashes`.
+
 - **`"extensions": ["diffs", "messages"]`** -- only listed extensions run
 - **`"extensions": []`** -- no extensions run (only `traces.jsonl` is written)
-- **Malformed JSON** -- warning logged, all extensions run
+
+### Sensitive file filtering
+
+By default, agent-trace filters sensitive files to prevent secrets from leaking into trace artifacts. Filtering applies to `traces.jsonl`, diffs, line-hashes, and raw events.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `useGitignore` | `true` | Respect `.gitignore` patterns via `git check-ignore` |
+| `useBuiltinSensitive` | `true` | Apply built-in sensitive file patterns |
+| `ignore` | `[]` | Additional glob patterns to filter |
+| `ignoreMode` | `"redact"` | `"redact"` keeps the trace entry with path but no content; `"skip"` drops the event entirely |
+
+Built-in sensitive patterns match at any depth:
+
+```
+.env  .env.*  *.pem  *.key  *.p12  *.pfx
+id_rsa  id_dsa  id_ecdsa  id_ed25519
+*.kubeconfig  credentials.*
+```
+
+When a file is **redacted**, the trace records the file path with empty ranges and `metadata.redacted: true`. Extensions see empty edits and produce no diff/hash artifacts. Raw events have sensitive fields (`old_string`, `new_string`, `content`, `before`, `after`, `originalFile`) replaced with `"[REDACTED]"`.
+
+When a file is **skipped**, no trace entry, diff, hash, or raw event is written.
 
 ## Trace format
 
@@ -105,7 +137,33 @@ Schema source: [`schemas.ts`](./src/core/schemas.ts)
 
 - **indexOf-based range attribution**: When the same text appears multiple times in a file, line-range attribution may point to the first occurrence rather than the actual edit location. Providers don't always supply line numbers, so `indexOf` is the best-effort fallback.
 - **Bun-only**: The hook runtime and CLI require Bun. Node.js is not supported.
-- **No VCS requirement**: Works without git. When git is available, traces include the current commit SHA. Without git, VCS info is omitted.
+- **No VCS requirement**: Works without git. When git is available, traces include the current commit SHA. Without git, VCS info is omitted. `useGitignore` silently becomes a no-op in non-git repos.
+- **Multi-file OpenCode events**: If any file in a `hook:tool.execute.after` payload is ignored, the entire raw event is redacted/skipped (conservative approach).
+- **`.env.*` matches broadly**: `**/.env.*` matches `.env.example` and `.env.template` intentionally — these files sometimes contain real values.
+
+## Provider quirks
+
+### Cursor
+
+- **Tab edits lack file content**: `afterTabFileEdit` events do not set `readContent`, so line-hashes for tab completions have no file context for position resolution.
+- **Duration field ambiguity**: Shell events accept both `duration` and `duration_ms`. When both are present, `duration_ms` takes precedence.
+
+### Claude Code
+
+- **Model tracking limited to session start**: Claude Code only includes the `model` field in `SessionStart` hook payloads. Switching models mid-session via `/model` does not fire a hook event, so traces after a switch may reflect the original model. This is a Claude Code hook API limitation.
+- **Only Write, Edit, and Bash traced**: Other tool uses (Read, Search, etc.) are not hooked and produce no trace events.
+- **Write tool fallback**: When the `Write` tool payload has no `new_string`, falls back to `content`. When neither is present, an empty-edits trace is recorded.
+
+### OpenCode
+
+- **Two file-edit code paths**: `file.edited` events carry no diff data (`edits: []`, `diffs: false`). Only `hook:tool.execute.after` events include before/after content for diffs and line-hashes.
+- **Flexible session ID extraction**: Session IDs can appear in five different payload locations depending on the event type. The adapter tries them all in priority order.
+
+### Codex
+
+- **Only `apply_patch` tool calls traced**: File changes from shell commands or other mechanisms are not detected. Same contract as other providers — only explicit tool-reported edits are traced.
+- **Patch format stability**: `parsePatchInput` depends on Codex's `*** <Action> File:` patch grammar. If Codex changes the format, parsing fails silently.
+- **`*** Move to:` (rename) blocks not parsed**: Rename operations in apply_patch are not traced. This is a rare edge case.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennykeni/agent-trace",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "bin": {
     "agent-trace": "src/cli.ts"
@@ -22,10 +22,12 @@
     "test": "bun test"
   },
   "dependencies": {
+    "diff": "^8.0.3",
     "zod": "^3.24.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.14",
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@types/diff": "^8.0.0"
   }
 }

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { runHook } from "./core/trace-hook";
 import "./extensions";
@@ -21,21 +22,27 @@ Usage:
   agent-trace <command> [options]
 
 Commands:
-  init       Initialize hooks for Cursor, Claude Code, and OpenCode in a project
+  init       Initialize hooks for Cursor, Claude Code, OpenCode, and Codex
   hook       Run the trace hook (reads JSON from stdin)
+  codex      Codex subcommands (notify, ingest, exec)
   status     Show installed hook status
   help       Show this help message
 
 Init options:
-  --providers <list>   Comma-separated providers (cursor,claude,opencode) [default: all]
+  --providers <list>   Comma-separated providers (cursor,claude,opencode,codex) [default: all]
   --target-root <dir>  Target project root [default: current directory]
   --dry-run            Preview changes without writing
   --latest             Use latest version instead of pinning to current
 
+Codex subcommands:
+  codex notify '<json>'   Handle Codex notify callback
+  codex ingest            Read Codex JSONL from stdin
+  codex exec [args...]    Wrap codex exec --json with tracing
+
 Examples:
   agent-trace init
   agent-trace init --providers cursor
-  agent-trace init --providers opencode
+  agent-trace init --providers codex
   agent-trace init --target-root ~/my-project
   agent-trace status`);
 }
@@ -53,6 +60,12 @@ function checkHookConfig(
   }
 }
 
+function codexConfigStatus(): "installed" | "not installed" {
+  const home = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+  const configPath = join(home, "config.toml");
+  return checkHookConfig(configPath, "agent-trace");
+}
+
 function status(): void {
   const root = getWorkspaceRoot();
 
@@ -69,6 +82,7 @@ function status(): void {
     "agent-trace hook --provider claude",
   );
   const opencodeStatus = checkHookConfig(opencodePath, "agent-trace");
+  const codexStatus = codexConfigStatus();
   const traceDir = join(root, ".agent-trace");
   const hasTraces = existsSync(join(traceDir, "traces.jsonl"));
 
@@ -76,6 +90,7 @@ function status(): void {
   console.log(`Cursor:     ${cursorStatus}`);
   console.log(`Claude:     ${claudeStatus}`);
   console.log(`OpenCode:   ${opencodeStatus}`);
+  console.log(`Codex:      ${codexStatus}`);
   console.log(`Traces:     ${hasTraces ? "present" : "none"}`);
 }
 
@@ -99,6 +114,12 @@ switch (command) {
   case "hook":
     await runHook();
     break;
+  case "codex": {
+    const { runCodexSubcommand } = await import("./codex");
+    const exitCode = await runCodexSubcommand(process.argv.slice(3));
+    process.exit(exitCode);
+    break;
+  }
   case "status":
     status();
     break;

package/src/codex/index.ts

@@ -0,0 +1,56 @@
+import "../extensions";
+import { CodexTraceIngestor } from "./ingestor";
+import { handleNotify } from "./notify";
+import { streamLines } from "./stream";
+
+async function ingestCodexJsonFromStdin(): Promise<number> {
+  const ingestor = new CodexTraceIngestor();
+
+  await streamLines(Bun.stdin.stream(), (line) => {
+    ingestor.processLine(line);
+  });
+
+  return 0;
+}
+
+async function runCodexExecWithTracing(args: string[]): Promise<number> {
+  const proc = Bun.spawn(["codex", "exec", "--json", ...args], {
+    stdin: "inherit",
+    stderr: "inherit",
+    stdout: "pipe",
+  });
+
+  const ingestor = new CodexTraceIngestor();
+
+  await streamLines(proc.stdout, (line) => {
+    process.stdout.write(`${line}\n`);
+    ingestor.processLine(line);
+  });
+
+  const exitCode = await proc.exited;
+  return exitCode;
+}
+
+export async function runCodexSubcommand(args: string[]): Promise<number> {
+  const sub = args[0];
+
+  switch (sub) {
+    case "notify":
+      if (!args[1]) {
+        console.error("Usage: agent-trace codex notify '<json>'");
+        return 1;
+      }
+      return handleNotify(args[1]);
+
+    case "ingest":
+      return ingestCodexJsonFromStdin();
+
+    case "exec":
+      return runCodexExecWithTracing(args.slice(1));
+
+    default:
+      console.error(`Unknown codex subcommand: ${sub ?? "(none)"}`);
+      console.error("Available: notify, ingest, exec");
+      return 1;
+  }
+}

package/src/codex/ingestor.ts

@@ -0,0 +1,427 @@
+import { join, resolve } from "node:path";
+import type { IgnoreConfig } from "../core/ignore";
+import { loadConfig } from "../core/ignore";
+import { activeExtensions, dispatchTraceEvent } from "../core/trace-hook";
+import { getWorkspaceRoot } from "../core/trace-store";
+import type { FileEdit, TraceEvent } from "../core/types";
+import { appendJsonl, sanitizeSessionId } from "../extensions/helpers";
+
+const TOOL = { name: "codex-cli" } as const;
+
+interface HunkLine {
+  type: "context" | "del" | "add";
+  text: string;
+}
+
+const CONTEXT_LINES = 3;
+const MERGE_GAP = 2 * CONTEXT_LINES;
+
+export function clusterHunkLines(lines: HunkLine[]): FileEdit[] {
+  const changeIndices: number[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line && line.type !== "context") changeIndices.push(i);
+  }
+  if (changeIndices.length === 0) return [];
+
+  const regions: { start: number; end: number }[] = [];
+  const first = changeIndices[0];
+  if (first === undefined) return [];
+  let rStart = first;
+  let rEnd = rStart;
+
+  for (let i = 1; i < changeIndices.length; i++) {
+    const idx = changeIndices[i];
+    if (idx === undefined) continue;
+    if (idx === rEnd + 1) {
+      rEnd = idx;
+    } else {
+      let allContext = true;
+      for (let j = rEnd + 1; j < idx; j++) {
+        const jLine = lines[j];
+        if (jLine && jLine.type !== "context") {
+          allContext = false;
+          break;
+        }
+      }
+      if (allContext) {
+        regions.push({ start: rStart, end: rEnd });
+        rStart = idx;
+        rEnd = idx;
+      } else {
+        rEnd = idx;
+      }
+    }
+  }
+  regions.push({ start: rStart, end: rEnd });
+
+  const firstRegion = regions[0];
+  if (!firstRegion) return [];
+  const merged: { start: number; end: number }[] = [firstRegion];
+  for (let i = 1; i < regions.length; i++) {
+    const prev = merged[merged.length - 1];
+    const curr = regions[i];
+    if (!prev || !curr) continue;
+    const gap = curr.start - prev.end - 1;
+    if (gap <= MERGE_GAP) {
+      prev.end = curr.end;
+    } else {
+      merged.push({ ...curr });
+    }
+  }
+
+  const edits: FileEdit[] = [];
+  for (const region of merged) {
+    const ctxStart = Math.max(0, region.start - CONTEXT_LINES);
+    const ctxEnd = Math.min(lines.length - 1, region.end + CONTEXT_LINES);
+
+    const oldParts: string[] = [];
+    const newParts: string[] = [];
+    for (let i = ctxStart; i <= ctxEnd; i++) {
+      const l = lines[i];
+      if (!l) continue;
+      if (l.type === "context") {
+        oldParts.push(l.text);
+        newParts.push(l.text);
+      } else if (l.type === "del") {
+        oldParts.push(l.text);
+      } else {
+        newParts.push(l.text);
+      }
+    }
+
+    edits.push({
+      old_string: oldParts.join("\n"),
+      new_string: newParts.join("\n"),
+    });
+  }
+
+  return edits;
+}
+
+export interface IngestorState {
+  sessionId: string | undefined;
+  modelId: string | undefined;
+  turnIndex: number;
+  sessionStarted: boolean;
+  sessionEnded: boolean;
+  pendingUserPrompt: string | undefined;
+  lastAgentMessage: string | undefined;
+}
+
+interface RolloutLine {
+  timestamp?: string;
+  type: string;
+  payload: Record<string, unknown>;
+}
+
+export function parsePatchInput(input: string): Map<string, FileEdit[]> {
+  const result = new Map<string, FileEdit[]>();
+  const filePattern = /^\*\*\*\s+(?:Update|Add|Delete)\s+File:\s+(.+)$/;
+  const lines = input.split("\n");
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    const fileMatch = filePattern.exec(line);
+    if (!fileMatch) {
+      i++;
+      continue;
+    }
+
+    const filePath = fileMatch[1]?.trim();
+    if (!filePath) {
+      i++;
+      continue;
+    }
+
+    i++;
+    const edits: FileEdit[] = [];
+
+    // Collect +lines between file header and first @@ (for Add File without hunk header)
+    const looseNewLines: string[] = [];
+
+    while (i < lines.length) {
+      const cur = lines[i] ?? "";
+      if (cur.startsWith("***")) break;
+
+      if (cur.startsWith("@@")) {
+        i++;
+        const hunkLines: HunkLine[] = [];
+
+        while (i < lines.length) {
+          const dl = lines[i] ?? "";
+          if (dl.startsWith("@@") || dl.startsWith("***")) break;
+          if (dl.startsWith("-")) {
+            hunkLines.push({ type: "del", text: dl.slice(1) });
+          } else if (dl.startsWith("+")) {
+            hunkLines.push({ type: "add", text: dl.slice(1) });
+          } else if (dl.startsWith(" ")) {
+            hunkLines.push({ type: "context", text: dl.slice(1) });
+          }
+          i++;
+        }
+
+        edits.push(...clusterHunkLines(hunkLines));
+        continue;
+      }
+
+      if (cur.startsWith("+")) {
+        looseNewLines.push(cur.slice(1));
+      }
+
+      i++;
+    }
+
+    if (looseNewLines.length > 0 && edits.length === 0) {
+      edits.push({
+        old_string: "",
+        new_string: looseNewLines.join("\n"),
+      });
+    }
+
+    const existing = result.get(filePath) ?? [];
+    result.set(filePath, [...existing, ...edits]);
+  }
+
+  return result;
+}
+
+export class CodexTraceIngestor {
+  sessionId: string | undefined;
+  modelId: string | undefined;
+  private transcriptPath: string | undefined;
+  private cachedIgnoreConfig: IgnoreConfig | undefined;
+  turnIndex = 0;
+  sessionStarted = false;
+  sessionEnded = false;
+  pendingUserPrompt: string | undefined;
+  lastAgentMessage: string | undefined;
+
+  constructor(transcriptPath?: string) {
+    this.transcriptPath = transcriptPath;
+  }
+
+  private getIgnoreConfig(): IgnoreConfig {
+    if (!this.cachedIgnoreConfig) {
+      this.cachedIgnoreConfig = loadConfig(getWorkspaceRoot()).ignore;
+    }
+    return this.cachedIgnoreConfig;
+  }
+
+  private emitTraceEvent(event: TraceEvent): void {
+    if (!this.sessionId) return;
+    const root = getWorkspaceRoot();
+    const config = loadConfig(root);
+    const extensions = activeExtensions(config.extensions);
+    dispatchTraceEvent(event, extensions, TOOL, this.getIgnoreConfig());
+  }
+
+  restoreState(state: IngestorState): void {
+    this.sessionId = state.sessionId;
+    this.modelId = state.modelId;
+    this.turnIndex = state.turnIndex;
+    this.sessionStarted = state.sessionStarted;
+    this.sessionEnded = state.sessionEnded;
+    this.pendingUserPrompt = state.pendingUserPrompt;
+    this.lastAgentMessage = state.lastAgentMessage;
+  }
+
+  snapshotState(): IngestorState {
+    return {
+      sessionId: this.sessionId,
+      modelId: this.modelId,
+      turnIndex: this.turnIndex,
+      sessionStarted: this.sessionStarted,
+      sessionEnded: this.sessionEnded,
+      pendingUserPrompt: this.pendingUserPrompt,
+      lastAgentMessage: this.lastAgentMessage,
+    };
+  }
+
+  processLine(line: string): void {
+    let parsed: RolloutLine;
+    try {
+      parsed = JSON.parse(line) as RolloutLine;
+    } catch {
+      return;
+    }
+
+    const outerType = parsed.type;
+    if (!outerType || !parsed.payload) return;
+
+    switch (outerType) {
+      case "session_meta":
+        this.onSessionMeta(parsed.payload);
+        break;
+      case "turn_context":
+        this.onTurnContext(parsed.payload);
+        break;
+      case "event_msg":
+        this.onEventMsg(parsed.payload);
+        break;
+      case "response_item":
+        this.onResponseItem(parsed.payload);
+        break;
+    }
+
+    this.appendRaw(parsed);
+  }
+
+  private appendRaw(event: RolloutLine): void {
+    if (!this.sessionId) return;
+    const root = getWorkspaceRoot();
+    const sid = sanitizeSessionId(this.sessionId);
+    const path = join(root, ".agent-trace", "raw", "codex", `${sid}.jsonl`);
+    appendJsonl(path, {
+      timestamp: new Date().toISOString(),
+      provider: "codex",
+      session_id: sid,
+      event,
+    });
+  }
+
+  private onSessionMeta(payload: Record<string, unknown>): void {
+    this.sessionId = (payload.id as string) ?? this.sessionId;
+    this.sessionStarted = true;
+
+    this.emitTraceEvent({
+      kind: "session_start",
+      provider: "codex",
+      sessionId: this.sessionId,
+      model: this.modelId,
+      meta: {
+        codex_session_id: this.sessionId,
+        cli_version: payload.cli_version,
+        model_provider: payload.model_provider,
+      },
+    });
+  }
+
+  private onTurnContext(payload: Record<string, unknown>): void {
+    const model = payload.model as string | undefined;
+    if (model) this.modelId = model;
+    this.turnIndex++;
+  }
+
+  private onEventMsg(payload: Record<string, unknown>): void {
+    const innerType = payload.type as string | undefined;
+    if (!innerType) return;
+
+    switch (innerType) {
+      case "user_message": {
+        const message = (payload.message as string) ?? undefined;
+        this.pendingUserPrompt = message;
+        if (message) {
+          this.emitTraceEvent({
+            kind: "message",
+            provider: "codex",
+            sessionId: this.sessionId,
+            role: "user",
+            content: message,
+            eventName: "user_message",
+            model: this.modelId,
+            meta: {
+              codex_session_id: this.sessionId,
+              turn_index: this.turnIndex,
+            },
+          });
+        }
+        break;
+      }
+      case "agent_message": {
+        const message = (payload.message as string) ?? undefined;
+        this.lastAgentMessage = message;
+        if (message) {
+          this.emitTraceEvent({
+            kind: "message",
+            provider: "codex",
+            sessionId: this.sessionId,
+            role: "assistant",
+            content: message,
+            eventName: "agent_message",
+            model: this.modelId,
+            meta: {
+              codex_session_id: this.sessionId,
+              turn_index: this.turnIndex,
+            },
+          });
+        }
+        break;
+      }
+    }
+  }
+
+  private onResponseItem(payload: Record<string, unknown>): void {
+    const itemType = payload.type as string | undefined;
+    if (!itemType) return;
+
+    switch (itemType) {
+      case "custom_tool_call":
+        this.onToolCall(payload);
+        break;
+      case "function_call":
+        this.onFunctionCall(payload);
+        break;
+    }
+  }
+
+  private onToolCall(payload: Record<string, unknown>): void {
+    const name = payload.name as string | undefined;
+    if (name !== "apply_patch") return;
+
+    const input = payload.input as string | undefined;
+    if (!input) return;
+
+    const parsed = parsePatchInput(input);
+    const root = getWorkspaceRoot();
+
+    for (const [filePath, edits] of parsed) {
+      this.emitTraceEvent({
+        kind: "file_edit",
+        provider: "codex",
+        sessionId: this.sessionId,
+        filePath: resolve(root, filePath),
+        edits,
+        model: this.modelId,
+        transcript: this.transcriptPath ?? undefined,
+        readContent: false,
+        eventName: "apply_patch",
+        meta: {
+          codex_session_id: this.sessionId,
+          turn_index: this.turnIndex,
+          source: "apply_patch",
+        },
+      });
+    }
+  }
+
+  private onFunctionCall(payload: Record<string, unknown>): void {
+    const name = payload.name as string | undefined;
+    if (name !== "exec_command") return;
+
+    let cmd: string | undefined;
+    const argsStr = payload.arguments as string | undefined;
+    if (argsStr) {
+      try {
+        const args = JSON.parse(argsStr) as Record<string, unknown>;
+        cmd = args.cmd as string | undefined;
+      } catch {
+        // ignore malformed arguments
+      }
+    }
+
+    this.emitTraceEvent({
+      kind: "shell",
+      provider: "codex",
+      sessionId: this.sessionId,
+      model: this.modelId,
+      transcript: this.transcriptPath ?? undefined,
+      meta: {
+        codex_session_id: this.sessionId,
+        turn_index: this.turnIndex,
+        command: cmd,
+      },
+    });
+  }
+}