@kennykeni/agent-trace 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# agent-trace
+
+A TypeScript implementation of the [Agent Trace specification](https://agent-trace.org) ([GitHub](https://github.com/cursor/agent-trace)) for capturing AI code contributions from local coding tools.
+
+## Overview
+
+agent-trace hooks into AI coding tools and records trace data as they edit files. Each trace captures what was changed, which model was used, and links back to the conversation that produced the code. Traces are written as JSONL to `.agent-trace/traces.jsonl` in the project root.
+
+Supported providers:
+
+- Cursor
+- Claude Code
+- OpenCode
+
+## Setup
+
+Requires [Bun](https://bun.sh).
+
+Install hooks in the current git repository:
+
+```bash
+bunx @kennykeni/agent-trace init
+```
+
+Install for specific providers:
+
+```bash
+bunx @kennykeni/agent-trace init --providers cursor
+bunx @kennykeni/agent-trace init --providers claude,opencode
+```
+
+Install for a specific project:
+
+```bash
+bunx @kennykeni/agent-trace init --target-root ~/my-project
+```
+
+Preview what would be written:
+
+```bash
+bunx @kennykeni/agent-trace init --dry-run
+```
+
+Check installation status:
+
+```bash
+bunx @kennykeni/agent-trace status
+```
+
+## What `init` does
+
+Configures the target repo's provider settings:
+
+| Provider   | Config written                            |
+| ---------- | ----------------------------------------- |
+| Cursor     | `.cursor/hooks.json`                      |
+| Claude Code| `.claude/settings.json`                   |
+| OpenCode   | `.opencode/plugins/agent-trace.ts`        |
+
+## How it works
+
+1. Provider hooks fire on tool events (file edits, shell commands, session lifecycle).
+2. The hook receives event JSON on stdin and routes it through a provider adapter.
+3. The adapter normalizes provider-specific payloads into internal trace events.
+4. The trace pipeline converts events into spec-compliant trace records.
+5. Records are appended to `.agent-trace/traces.jsonl`.
+
+Additional artifacts are written by extensions under `.agent-trace/`:
+
+- `raw/<provider>/<session>.jsonl` -- raw hook events (`raw-events` extension)
+- `messages/<provider>/<session>.jsonl` -- captured chat messages (`messages` extension)
+- `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.
+
+To control which extensions run, create `.agent-trace/config.json` in your project root:
+
+```json
+{ "extensions": ["diffs", "messages"] }
+```
+
+- **File absent** -- all registered extensions run (default)
+- **`"extensions": ["diffs", "messages"]`** -- only listed extensions run
+- **`"extensions": []`** -- no extensions run (only `traces.jsonl` is written)
+- **Malformed JSON** -- warning logged, all extensions run
+
+## Trace format
+
+Traces follow the [Agent Trace spec](https://agent-trace.org). Each JSONL line contains:
+
+- `version` -- spec version
+- `id` -- unique trace ID (UUID)
+- `timestamp` -- ISO 8601
+- `vcs` -- version control info (type, revision)
+- `tool` -- tool name and version
+- `files[]` -- files with conversation and range attribution
+- `metadata` -- optional implementation-specific data
+
+Schema source: [`schemas.ts`](./src/core/schemas.ts)
+
+## Known limitations
+
+- **Path normalization edge cases**: Relative path conversion is string-prefix based today; some sibling-path cases can produce `..` segments.
+- **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.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run check
+```
+
+## Spec reference
+
+This project implements the [Agent Trace specification](https://agent-trace.org) authored by [Cursor](https://github.com/cursor/agent-trace). The spec defines a vendor-neutral format for recording AI contributions alongside human authorship in version-controlled codebases.
+
+## License
+
+See the [Agent Trace spec](https://github.com/cursor/agent-trace) for specification licensing (CC BY 4.0).

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kennykeni/agent-trace",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "agent-trace": "src/cli.ts"
+  },
+  "files": [
+    "src/",
+    "!src/**/__tests__/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KennyKeni/agent-trace.git"
+  },
+  "scripts": {
+    "build": "bun run index.ts",
+    "dev": "bun run index.ts --dev",
+    "check": "tsc --noEmit && biome check .",
+    "check:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/bun": "latest",
+    "marked": "^15.0.0",
+    "marked-shiki": "^1.2.0",
+    "shiki": "^3.0.0",
+    "zod-to-json-schema": "^3.24.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env bun
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runHook } from "./core/trace-hook";
+import "./extensions";
+import "./providers";
+import { getWorkspaceRoot } from "./core/trace-store";
+import {
+  InstallError,
+  install,
+  parseArgs,
+  printInstallSummary,
+} from "./install";
+import { getPackageVersion } from "./install/utils";
+
+function printHelp(): void {
+  console.log(`agent-trace - AI code attribution tracker
+
+Usage:
+  agent-trace <command> [options]
+
+Commands:
+  init       Initialize hooks for Cursor, Claude Code, and OpenCode in a project
+  hook       Run the trace hook (reads JSON from stdin)
+  status     Show installed hook status
+  help       Show this help message
+
+Init options:
+  --providers <list>   Comma-separated providers (cursor,claude,opencode) [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
+
+Examples:
+  agent-trace init
+  agent-trace init --providers cursor
+  agent-trace init --providers opencode
+  agent-trace init --target-root ~/my-project
+  agent-trace status`);
+}
+
+function checkHookConfig(
+  path: string,
+  searchString: string,
+): "installed" | "not installed" {
+  if (!existsSync(path)) return "not installed";
+  try {
+    const content = readFileSync(path, "utf-8");
+    return content.includes(searchString) ? "installed" : "not installed";
+  } catch {
+    return "not installed";
+  }
+}
+
+function status(): void {
+  const root = getWorkspaceRoot();
+
+  const cursorPath = join(root, ".cursor", "hooks.json");
+  const claudePath = join(root, ".claude", "settings.json");
+  const opencodePath = join(root, ".opencode", "plugins", "agent-trace.ts");
+
+  const cursorStatus = checkHookConfig(
+    cursorPath,
+    "agent-trace hook --provider cursor",
+  );
+  const claudeStatus = checkHookConfig(
+    claudePath,
+    "agent-trace hook --provider claude",
+  );
+  const opencodeStatus = checkHookConfig(opencodePath, "agent-trace");
+  const traceDir = join(root, ".agent-trace");
+  const hasTraces = existsSync(join(traceDir, "traces.jsonl"));
+
+  console.log(`Workspace: ${root}\n`);
+  console.log(`Cursor:     ${cursorStatus}`);
+  console.log(`Claude:     ${claudeStatus}`);
+  console.log(`OpenCode:   ${opencodeStatus}`);
+  console.log(`Traces:     ${hasTraces ? "present" : "none"}`);
+}
+
+const command = process.argv[2];
+
+switch (command) {
+  case "init": {
+    try {
+      const options = parseArgs(process.argv.slice(3));
+      const changes = install(options);
+      printInstallSummary(changes, options.targetRoots);
+    } catch (e) {
+      if (e instanceof InstallError) {
+        console.error(e.message);
+        process.exit(1);
+      }
+      throw e;
+    }
+    break;
+  }
+  case "hook":
+    await runHook();
+    break;
+  case "status":
+    status();
+    break;
+  case "--version":
+  case "-v":
+    console.log(getPackageVersion());
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+  case undefined:
+    printHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}

package/src/core/schemas.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+export const SPEC_VERSION = "0.1.0";
+
+const SCHEMA_BASE_URL = "https://agent-trace.dev/schemas/v1";
+
+export const ContributorTypeSchema = z.enum([
+  "human",
+  "ai",
+  "mixed",
+  "unknown",
+]);
+
+export const ToolSchema = z.object({
+  name: z
+    .string()
+    .optional()
+    .describe("Name of the tool that produced the code"),
+  version: z.string().optional().describe("Version of the tool"),
+});
+
+export const ContributorSchema = z.object({
+  type: ContributorTypeSchema.describe("The type of contributor"),
+  model_id: z
+    .string()
+    .max(250)
+    .optional()
+    .describe(
+      "The model's unique identifier following models.dev convention (e.g., 'anthropic/claude-opus-4-5-20251101')",
+    ),
+});
+
+export const RelatedResourceSchema = z.object({
+  type: z.string().describe("Type of related resource"),
+  url: z.string().url().describe("URL to the related resource"),
+});
+
+export const RangeSchema = z.object({
+  start_line: z.number().int().min(1).describe("1-indexed start line number"),
+  end_line: z.number().int().min(1).describe("1-indexed end line number"),
+  content_hash: z
+    .string()
+    .optional()
+    .describe("Hash of attributed content for position-independent tracking"),
+  contributor: ContributorSchema.optional().describe(
+    "Override contributor for this specific range (e.g., for agent handoffs)",
+  ),
+});
+
+export const ConversationSchema = z.object({
+  url: z
+    .string()
+    .url()
+    .optional()
+    .describe("URL to look up the conversation that produced this code"),
+  contributor: ContributorSchema.optional().describe(
+    "The contributor for ranges in this conversation (can be overridden per-range)",
+  ),
+  ranges: z
+    .array(RangeSchema)
+    .describe("Array of line ranges produced by this conversation"),
+  related: z
+    .array(RelatedResourceSchema)
+    .optional()
+    .describe("Other related resources"),
+});
+
+export const FileSchema = z.object({
+  path: z.string().describe("Relative file path from repository root"),
+  conversations: z
+    .array(ConversationSchema)
+    .describe("Array of conversations that contributed to this file"),
+});
+
+export const VcsTypeSchema = z.enum(["git", "jj", "hg", "svn"]);
+
+export const VcsSchema = z.object({
+  type: VcsTypeSchema.describe(
+    "Version control system type (e.g., 'git', 'jj', 'hg')",
+  ),
+  revision: z
+    .string()
+    .describe(
+      "Revision identifier (e.g., git commit SHA, jj change ID, hg changeset)",
+    ),
+});
+
+export const TraceRecordSchema = z.object({
+  version: z
+    .string()
+    .regex(/^[0-9]+\.[0-9]+\.[0-9]+$/)
+    .describe("Agent Trace specification version (e.g., '0.1.0')"),
+  id: z.string().uuid().describe("Unique identifier for this trace record"),
+  timestamp: z
+    .string()
+    .datetime({ offset: true })
+    .describe("RFC 3339 timestamp when trace was recorded"),
+  vcs: VcsSchema.optional().describe(
+    "Version control system information for this trace",
+  ),
+  tool: ToolSchema.optional().describe("The tool that generated this trace"),
+  files: z.array(FileSchema).describe("Array of files with attributed ranges"),
+  metadata: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe(
+      "Additional metadata for implementation-specific or vendor-specific data",
+    ),
+});
+
+export function generateJsonSchemas(): Record<string, object> {
+  const schemas: Record<string, object> = {};
+
+  // Trace Record Schema
+  schemas["trace-record.json"] = {
+    ...zodToJsonSchema(TraceRecordSchema, {
+      name: "TraceRecord",
+      $refStrategy: "none",
+    }),
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: `${SCHEMA_BASE_URL}/trace-record.json`,
+    title: "Agent Trace Record",
+  };
+
+  return schemas;
+}
+
+export type ContributorType = z.infer<typeof ContributorTypeSchema>;
+export type VcsType = z.infer<typeof VcsTypeSchema>;
+export type Vcs = z.infer<typeof VcsSchema>;
+export type Tool = z.infer<typeof ToolSchema>;
+export type Contributor = z.infer<typeof ContributorSchema>;
+export type Range = z.infer<typeof RangeSchema>;
+export type Conversation = z.infer<typeof ConversationSchema>;
+export type File = z.infer<typeof FileSchema>;
+export type RelatedResource = z.infer<typeof RelatedResourceSchema>;
+export type TraceRecord = z.infer<typeof TraceRecordSchema>;

package/src/core/trace-hook.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env bun
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  appendTrace,
+  computeRangePositions,
+  createTrace,
+  getWorkspaceRoot,
+  tryReadFile,
+} from "./trace-store";
+import type {
+  Extension,
+  HookInput,
+  ProviderAdapter,
+  TraceEvent,
+} from "./types";
+
+export type { HookInput } from "./types";
+
+const providerRegistry = new Map<string, ProviderAdapter>();
+
+export function registerProvider(name: string, adapter: ProviderAdapter): void {
+  providerRegistry.set(name, adapter);
+}
+
+const extensionRegistry = new Map<string, Extension>();
+
+export function registerExtension(ext: Extension): void {
+  extensionRegistry.set(ext.name, ext);
+}
+
+function parseProvider(argv: string[]): string | undefined {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--provider") {
+      return argv[i + 1] ?? undefined;
+    }
+    if (arg?.startsWith("--provider=")) {
+      return arg.slice("--provider=".length) || undefined;
+    }
+  }
+  return undefined;
+}
+
+function loadExtensionConfig(root: string): string[] | null {
+  const configPath = join(root, ".agent-trace", "config.json");
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, "utf-8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      Array.isArray(parsed.extensions)
+    ) {
+      return parsed.extensions.filter(
+        (e: unknown): e is string => typeof e === "string",
+      );
+    }
+    console.error(
+      "agent-trace: config.json missing 'extensions' array, running all extensions",
+    );
+    return null;
+  } catch {
+    console.error("agent-trace: malformed config.json, running all extensions");
+    return null;
+  }
+}
+
+function activeExtensions(root: string): Extension[] {
+  const allowlist = loadExtensionConfig(root);
+  if (allowlist === null) return [...extensionRegistry.values()];
+
+  const active: Extension[] = [];
+  for (const name of allowlist) {
+    const ext = extensionRegistry.get(name);
+    if (ext) {
+      active.push(ext);
+    } else {
+      console.error(`agent-trace: unknown extension "${name}", skipping`);
+    }
+  }
+  return active;
+}
+
+function writeTrace(event: TraceEvent): void {
+  const appendIfTrace = (trace: ReturnType<typeof createTrace>): void => {
+    if (trace) appendTrace(trace);
+  };
+
+  switch (event.kind) {
+    case "file_edit": {
+      const edits = event.edits;
+      const fileContent = event.readContent
+        ? tryReadFile(event.filePath)
+        : undefined;
+      const rangePositions = edits.length
+        ? computeRangePositions(edits, fileContent)
+        : undefined;
+
+      appendIfTrace(
+        createTrace("ai", event.filePath, {
+          model: event.model,
+          rangePositions,
+          transcript: event.transcript,
+          tool: event.tool,
+          metadata: event.meta,
+        }),
+      );
+      break;
+    }
+    case "shell": {
+      appendIfTrace(
+        createTrace("ai", ".shell-history", {
+          model: event.model,
+          transcript: event.transcript,
+          tool: event.tool,
+          metadata: event.meta,
+        }),
+      );
+      break;
+    }
+    case "session_start": {
+      appendIfTrace(
+        createTrace("ai", ".sessions", {
+          model: event.model,
+          tool: event.tool,
+          metadata: { event: "session_start", ...event.meta },
+        }),
+      );
+      break;
+    }
+    case "session_end": {
+      appendIfTrace(
+        createTrace("ai", ".sessions", {
+          model: event.model,
+          tool: event.tool,
+          metadata: { event: "session_end", ...event.meta },
+        }),
+      );
+      break;
+    }
+    case "message":
+      break;
+  }
+}
+
+export async function runHook() {
+  if (providerRegistry.size === 0) {
+    console.error(
+      'No providers registered. Import provider registrations before calling runHook() (e.g. import "./providers").',
+    );
+    process.exit(1);
+  }
+
+  const chunks: Buffer[] = [];
+  for await (const chunk of Bun.stdin.stream()) {
+    chunks.push(Buffer.from(chunk));
+  }
+
+  const json = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!json) process.exit(0);
+
+  try {
+    const providerName = parseProvider(process.argv.slice(2));
+    if (!providerName) {
+      const registered = [...providerRegistry.keys()].join(", ");
+      console.error(
+        `Missing --provider flag. Registered providers: ${registered}`,
+      );
+      process.exit(1);
+    }
+
+    const adapter = providerRegistry.get(providerName);
+    if (!adapter) {
+      const registered = [...providerRegistry.keys()].join(", ");
+      console.error(
+        `Unknown provider "${providerName}". Registered providers: ${registered}`,
+      );
+      process.exit(1);
+    }
+
+    const input = JSON.parse(json) as HookInput;
+
+    process.env.AGENT_TRACE_PROVIDER = providerName;
+
+    const sessionId = adapter.sessionIdFor(input);
+    const extensions = activeExtensions(getWorkspaceRoot());
+
+    for (const ext of extensions) {
+      if (ext.onRawInput) {
+        try {
+          ext.onRawInput(providerName, sessionId, input);
+        } catch (e) {
+          console.error(`Extension error (${ext.name}/onRawInput):`, e);
+        }
+      }
+    }
+
+    const toolInfo = adapter.toolInfo?.();
+
+    const result = adapter.adapt(input);
+    if (result) {
+      const events = Array.isArray(result) ? result : [result];
+      for (const raw of events) {
+        const event = toolInfo ? { ...raw, tool: toolInfo } : raw;
+        writeTrace(event);
+        for (const ext of extensions) {
+          if (ext.onTraceEvent) {
+            try {
+              ext.onTraceEvent(event);
+            } catch (e) {
+              console.error(`Extension error (${ext.name}/onTraceEvent):`, e);
+            }
+          }
+        }
+      }
+    }
+  } catch (e) {
+    console.error("Hook error:", e);
+    process.exit(1);
+  }
+}
+
+if (import.meta.main) void runHook();