@kennykeni/agent-trace 0.1.0

package/src/core/trace-store.ts

@@ -0,0 +1,170 @@
+import { execFileSync } from "node:child_process";
+import { appendFileSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import type {
+  ContributorType,
+  Conversation,
+  Range,
+  TraceRecord,
+  Vcs,
+} from "./schemas";
+import { SPEC_VERSION } from "./schemas";
+import type { FileEdit, RangePosition } from "./types";
+import { ensureDir, normalizeNewlines, resolvePosition } from "./utils";
+
+export type {
+  ContributorType,
+  Conversation,
+  Range,
+  TraceRecord,
+  Vcs,
+  VcsType,
+} from "./schemas";
+
+export type { FileEdit, RangePosition } from "./types";
+
+function contentHash(text: string): string {
+  const h = Bun.hash.murmur32v3(text, 0) >>> 0;
+  return `murmur3:${h.toString(16).padStart(8, "0")}`;
+}
+
+const TRACE_PATH = ".agent-trace/traces.jsonl";
+
+let cachedRoot: string | undefined;
+
+export function getWorkspaceRoot(): string {
+  if (cachedRoot) return cachedRoot;
+  if (process.env.AGENT_TRACE_WORKSPACE_ROOT) {
+    cachedRoot = process.env.AGENT_TRACE_WORKSPACE_ROOT;
+    return cachedRoot;
+  }
+  if (process.env.CURSOR_PROJECT_DIR) {
+    cachedRoot = process.env.CURSOR_PROJECT_DIR;
+    return cachedRoot;
+  }
+  if (process.env.CLAUDE_PROJECT_DIR) {
+    cachedRoot = process.env.CLAUDE_PROJECT_DIR;
+    return cachedRoot;
+  }
+  try {
+    cachedRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    cachedRoot = process.cwd();
+  }
+  return cachedRoot;
+}
+
+export function getVcsInfo(cwd: string): Vcs | undefined {
+  try {
+    const revision = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+    return { type: "git", revision };
+  } catch {
+    return undefined;
+  }
+}
+
+export function toRelativePath(
+  filePath: string,
+  root: string,
+): string | undefined {
+  if (!isAbsolute(filePath)) {
+    const resolved = resolve(root, filePath);
+    const rel = relative(resolve(root), resolved);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel) || rel === "")
+      return undefined;
+    return rel;
+  }
+
+  const rootResolved = resolve(root);
+  const fileResolved = resolve(filePath);
+  const rel = relative(rootResolved, fileResolved);
+
+  // Outside-root paths are not repo-relative and should not be traced.
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    return undefined;
+  }
+
+  // A file path equal to root is not a valid file entry.
+  if (rel === "") return undefined;
+
+  return rel;
+}
+
+export function computeRangePositions(
+  edits: FileEdit[],
+  fileContent?: string,
+): RangePosition[] {
+  return edits
+    .filter((e) => e.new_string)
+    .map((edit) => {
+      const pos = resolvePosition(edit, fileContent);
+      return { ...pos, content_hash: contentHash(edit.new_string) };
+    });
+}
+
+export function createTrace(
+  type: ContributorType,
+  filePath: string,
+  opts: {
+    model?: string;
+    rangePositions?: RangePosition[];
+    transcript?: string | null;
+    tool?: { name: string; version?: string };
+    metadata?: Record<string, unknown>;
+  } = {},
+): TraceRecord | undefined {
+  const root = getWorkspaceRoot();
+  const relativePath = toRelativePath(filePath, root);
+  if (!relativePath) return undefined;
+  const conversationUrl = opts.transcript
+    ? `file://${opts.transcript}`
+    : undefined;
+
+  const ranges: Range[] = opts.rangePositions?.length
+    ? opts.rangePositions.map((pos) => ({ ...pos }))
+    : [];
+
+  const conversation: Conversation = {
+    url: conversationUrl,
+    contributor: { type, model_id: opts.model },
+    ranges,
+  };
+
+  return {
+    version: SPEC_VERSION,
+    id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    vcs: getVcsInfo(root),
+    tool: opts.tool,
+    files: [
+      {
+        path: relativePath,
+        conversations: [conversation],
+      },
+    ],
+    metadata: opts.metadata,
+  };
+}
+
+export function appendTrace(trace: TraceRecord): void {
+  const root = getWorkspaceRoot();
+  const filePath = join(root, TRACE_PATH);
+  const dir = join(root, ".agent-trace");
+  ensureDir(dir);
+  appendFileSync(filePath, `${JSON.stringify(trace)}\n`, "utf-8");
+}
+
+export function tryReadFile(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return undefined;
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,93 @@
+export interface FileEdit {
+  old_string: string;
+  new_string: string;
+  range?: {
+    start_line_number: number;
+    end_line_number: number;
+    start_column: number;
+    end_column: number;
+  };
+}
+
+export interface RangePosition {
+  start_line: number;
+  end_line: number;
+  content_hash?: string;
+}
+
+export interface HookInput {
+  hook_event_name: string;
+  model?: string;
+  session_id?: string;
+  conversation_id?: string;
+  generation_id?: string;
+  transcript_path?: string | null;
+}
+
+export type TraceEvent =
+  | {
+      kind: "file_edit";
+      provider: string;
+      sessionId?: string;
+      filePath: string;
+      edits: FileEdit[];
+      model?: string;
+      transcript?: string | null;
+      readContent?: boolean;
+      diffs?: boolean;
+      eventName: string;
+      tool?: { name: string; version?: string };
+      meta: Record<string, unknown>;
+    }
+  | {
+      kind: "shell";
+      provider: string;
+      sessionId?: string;
+      model?: string;
+      transcript?: string | null;
+      tool?: { name: string; version?: string };
+      meta: Record<string, unknown>;
+    }
+  | {
+      kind: "session_start";
+      provider: string;
+      sessionId?: string;
+      model?: string;
+      tool?: { name: string; version?: string };
+      meta: Record<string, unknown>;
+    }
+  | {
+      kind: "session_end";
+      provider: string;
+      sessionId?: string;
+      model?: string;
+      tool?: { name: string; version?: string };
+      meta: Record<string, unknown>;
+    }
+  | {
+      kind: "message";
+      provider: string;
+      sessionId?: string;
+      role: "user" | "assistant" | "system";
+      content: string;
+      eventName: string;
+      model?: string;
+      tool?: { name: string; version?: string };
+      meta: Record<string, unknown>;
+    };
+
+export interface ProviderAdapter {
+  adapt(input: HookInput): TraceEvent | TraceEvent[] | undefined;
+  sessionIdFor(input: HookInput): string | undefined;
+  toolInfo?(): { name: string; version?: string };
+}
+
+export interface Extension {
+  name: string;
+  onRawInput?(
+    provider: string,
+    sessionId: string | undefined,
+    input: HookInput,
+  ): void;
+  onTraceEvent?(event: TraceEvent): void;
+}

package/src/core/utils.ts

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { FileEdit } from "./types";
+
+export function ensureDir(path: string): void {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+}
+
+export function ensureParent(path: string): void {
+  ensureDir(dirname(path));
+}
+
+export function normalizeNewlines(s: string): string {
+  return s.replace(/\r\n/g, "\n");
+}
+
+export function resolvePosition(
+  edit: FileEdit,
+  fileContent?: string,
+): { start_line: number; end_line: number } {
+  const lineCount = normalizeNewlines(edit.new_string).split("\n").length;
+
+  if (edit.range) {
+    return {
+      start_line: edit.range.start_line_number,
+      end_line: edit.range.end_line_number,
+    };
+  }
+
+  if (fileContent) {
+    const idx = fileContent.indexOf(edit.new_string);
+    if (idx !== -1) {
+      const startLine = fileContent.substring(0, idx).split("\n").length;
+      return { start_line: startLine, end_line: startLine + lineCount - 1 };
+    }
+  }
+
+  return { start_line: 1, end_line: lineCount };
+}
+
+export function textFromUnknown(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    const texts = value
+      .map((part) => textFromUnknown(part))
+      .filter((part): part is string => Boolean(part));
+    if (texts.length > 0) return texts.join("\n");
+    return undefined;
+  }
+  if (value && typeof value === "object") {
+    return stringFromObjectContent(value as Record<string, unknown>);
+  }
+  return undefined;
+}
+
+function stringFromObjectContent(
+  value: Record<string, unknown>,
+): string | undefined {
+  const direct = value.text;
+  if (typeof direct === "string" && direct.trim()) return direct;
+
+  const content = value.content;
+  if (typeof content === "string" && content.trim()) return content;
+
+  if (Array.isArray(content)) {
+    const texts = content
+      .map((part) => textFromUnknown(part))
+      .filter((part): part is string => Boolean(part));
+    if (texts.length > 0) return texts.join("\n");
+  }
+
+  return undefined;
+}
+
+export function maybeString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+export function safeRecord(
+  value: unknown,
+): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return undefined;
+  return value as Record<string, unknown>;
+}

package/src/extensions/diffs.ts

@@ -0,0 +1,89 @@
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { registerExtension } from "../core/trace-hook";
+import { getWorkspaceRoot } from "../core/trace-store";
+import { normalizeNewlines } from "../core/utils";
+import { ensureParent, nowIso, sanitizeSessionId } from "./helpers";
+
+const TRACE_ROOT_DIR = ".agent-trace";
+
+function normalizeLines(input: string): string[] {
+  if (!input) return [];
+  return normalizeNewlines(input).split("\n");
+}
+
+export function createPatchFromStrings(
+  filePath: string,
+  oldText: string | undefined,
+  newText: string | undefined,
+): string | undefined {
+  if ((oldText ?? "") === (newText ?? "")) return undefined;
+
+  const oldExists = oldText !== undefined;
+  const newExists = newText !== undefined;
+  const oldNorm = oldText ?? "";
+  const newNorm = newText ?? "";
+  const oldLines = normalizeLines(oldNorm);
+  const newLines = normalizeLines(newNorm);
+
+  const fromFile = oldExists ? `a/${filePath}` : "/dev/null";
+  const toFile = newExists ? `b/${filePath}` : "/dev/null";
+  const oldStart = oldLines.length === 0 ? 0 : 1;
+  const newStart = newLines.length === 0 ? 0 : 1;
+
+  const lines: string[] = [
+    `diff --git a/${filePath} b/${filePath}`,
+    `--- ${fromFile}`,
+    `+++ ${toFile}`,
+    `@@ -${oldStart},${oldLines.length} +${newStart},${newLines.length} @@`,
+  ];
+
+  for (const line of oldLines) lines.push(`-${line}`);
+  for (const line of newLines) lines.push(`+${line}`);
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function appendDiffArtifact(
+  provider: string,
+  sessionId: string | undefined,
+  filePath: string,
+  eventName: string,
+  diff: string,
+  root = getWorkspaceRoot(),
+): string {
+  const sid = sanitizeSessionId(sessionId);
+  const path = join(root, TRACE_ROOT_DIR, "diffs", provider, `${sid}.patch`);
+  ensureParent(path);
+  const section = [
+    `# event=${eventName} file=${filePath} timestamp=${nowIso()}`,
+    diff.trimEnd(),
+    "",
+  ].join("\n");
+  appendFileSync(path, section, "utf-8");
+  return `file://${path}`;
+}
+
+registerExtension({
+  name: "diffs",
+  onTraceEvent(event) {
+    if (event.kind !== "file_edit") return;
+    if (event.diffs === false) return;
+    for (const edit of event.edits) {
+      const diff = createPatchFromStrings(
+        event.filePath,
+        edit.old_string,
+        edit.new_string,
+      );
+      if (diff) {
+        appendDiffArtifact(
+          event.provider,
+          event.sessionId,
+          event.filePath,
+          event.eventName,
+          diff,
+        );
+      }
+    }
+  },
+});

package/src/extensions/helpers.ts

@@ -0,0 +1,19 @@
+import { appendFileSync } from "node:fs";
+import { ensureParent } from "../core/utils";
+
+export { ensureDir, ensureParent } from "../core/utils";
+
+export function appendJsonl(path: string, value: unknown): void {
+  ensureParent(path);
+  appendFileSync(path, `${JSON.stringify(value)}\n`, "utf-8");
+}
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function sanitizeSessionId(sessionId?: string | null): string {
+  const raw = (sessionId ?? "unknown").trim();
+  if (!raw) return "unknown";
+  return raw.replace(/[^a-zA-Z0-9._-]/g, "_");
+}

package/src/extensions/index.ts

@@ -0,0 +1,16 @@
+import "./raw-events";
+import "./diffs";
+import "./messages";
+import "./line-hashes";
+
+export { appendDiffArtifact, createPatchFromStrings } from "./diffs";
+export {
+  appendJsonl,
+  ensureDir,
+  ensureParent,
+  nowIso,
+  sanitizeSessionId,
+} from "./helpers";
+export { appendLineHashes } from "./line-hashes";
+export { appendMessage, type MessageRecord } from "./messages";
+export { appendRawEvent } from "./raw-events";

package/src/extensions/line-hashes.ts

@@ -0,0 +1,67 @@
+import { join } from "node:path";
+import { registerExtension } from "../core/trace-hook";
+import { getWorkspaceRoot, tryReadFile } from "../core/trace-store";
+import type { FileEdit } from "../core/types";
+import { normalizeNewlines, resolvePosition } from "../core/utils";
+import { appendJsonl, nowIso, sanitizeSessionId } from "./helpers";
+
+const TRACE_ROOT_DIR = ".agent-trace";
+
+function lineHash(line: string): string {
+  const h = Bun.hash.murmur32v3(line, 0) >>> 0;
+  return `murmur3:${h.toString(16).padStart(8, "0")}`;
+}
+
+export function appendLineHashes(
+  provider: string,
+  sessionId: string | undefined,
+  filePath: string,
+  eventName: string,
+  edits: FileEdit[],
+  fileContent?: string,
+  root = getWorkspaceRoot(),
+): void {
+  const sid = sanitizeSessionId(sessionId);
+  const path = join(
+    root,
+    TRACE_ROOT_DIR,
+    "line-hashes",
+    provider,
+    `${sid}.jsonl`,
+  );
+
+  for (const edit of edits) {
+    if (!edit.new_string) continue;
+
+    const lines = normalizeNewlines(edit.new_string).split("\n");
+    const hashes = lines.map(lineHash);
+    const pos = resolvePosition(edit, fileContent);
+
+    appendJsonl(path, {
+      timestamp: nowIso(),
+      file: filePath,
+      event: eventName,
+      start_line: pos.start_line,
+      end_line: pos.end_line,
+      hashes,
+    });
+  }
+}
+
+registerExtension({
+  name: "line-hashes",
+  onTraceEvent(event) {
+    if (event.kind !== "file_edit") return;
+    const fileContent = event.readContent
+      ? tryReadFile(event.filePath)
+      : undefined;
+    appendLineHashes(
+      event.provider,
+      event.sessionId,
+      event.filePath,
+      event.eventName,
+      event.edits,
+      fileContent,
+    );
+  },
+});

package/src/extensions/messages.ts

@@ -0,0 +1,48 @@
+import { join } from "node:path";
+import { registerExtension } from "../core/trace-hook";
+import { getWorkspaceRoot } from "../core/trace-store";
+import { appendJsonl, nowIso, sanitizeSessionId } from "./helpers";
+
+const TRACE_ROOT_DIR = ".agent-trace";
+
+export interface MessageRecord {
+  role: "user" | "assistant" | "system";
+  content: string;
+  event: string;
+  model_id?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export function appendMessage(
+  provider: string,
+  sessionId: string | undefined,
+  message: MessageRecord,
+  root = getWorkspaceRoot(),
+): string {
+  const sid = sanitizeSessionId(sessionId);
+  const path = join(root, TRACE_ROOT_DIR, "messages", provider, `${sid}.jsonl`);
+  appendJsonl(path, {
+    id: crypto.randomUUID(),
+    timestamp: nowIso(),
+    provider,
+    session_id: sid,
+    ...message,
+  });
+  return path;
+}
+
+registerExtension({
+  name: "messages",
+  onTraceEvent(event) {
+    if (event.kind !== "message") return;
+    const metadata =
+      Object.keys(event.meta).length > 0 ? event.meta : undefined;
+    appendMessage(event.provider, event.sessionId, {
+      role: event.role,
+      content: event.content,
+      event: event.eventName,
+      model_id: event.model,
+      metadata,
+    });
+  },
+});

package/src/extensions/raw-events.ts

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+import { registerExtension } from "../core/trace-hook";
+import { getWorkspaceRoot } from "../core/trace-store";
+import { appendJsonl, nowIso, sanitizeSessionId } from "./helpers";
+
+const TRACE_ROOT_DIR = ".agent-trace";
+
+export function appendRawEvent(
+  provider: string,
+  sessionId: string | undefined,
+  event: unknown,
+  root = getWorkspaceRoot(),
+): string {
+  const sid = sanitizeSessionId(sessionId);
+  const path = join(root, TRACE_ROOT_DIR, "raw", provider, `${sid}.jsonl`);
+  appendJsonl(path, {
+    timestamp: nowIso(),
+    provider,
+    session_id: sid,
+    event,
+  });
+  return path;
+}
+
+registerExtension({
+  name: "raw-events",
+  onRawInput(provider, sessionId, input) {
+    appendRawEvent(provider, sessionId, input);
+  },
+});

package/src/install/args.ts

@@ -0,0 +1,71 @@
+import { resolve } from "node:path";
+import { parseArgs as nodeParseArgs } from "node:util";
+import { getWorkspaceRoot } from "../core/trace-store";
+import { isProvider, PROVIDERS, type Provider } from "../providers/types";
+import type { InstallOptions } from "./types";
+
+export class InstallError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InstallError";
+  }
+}
+
+function normalizePath(path: string): string {
+  return resolve(path);
+}
+
+function parseProviders(raw?: string): Provider[] {
+  if (!raw) return [...PROVIDERS];
+  const values = raw
+    .split(",")
+    .map((x) => x.trim().toLowerCase())
+    .filter(Boolean);
+  const invalid = values.filter((value) => !isProvider(value));
+  if (invalid.length > 0) {
+    throw new InstallError(
+      `Invalid providers: ${invalid.join(", ")}. Valid values: ${PROVIDERS.join(", ")}`,
+    );
+  }
+  return values as Provider[];
+}
+
+export function parseArgs(argv: string[]): InstallOptions {
+  let values: {
+    providers?: string;
+    "target-root"?: string[];
+    "dry-run"?: boolean;
+    latest?: boolean;
+  };
+
+  try {
+    ({ values } = nodeParseArgs({
+      args: argv,
+      options: {
+        providers: { type: "string" },
+        "target-root": { type: "string", multiple: true },
+        "dry-run": { type: "boolean" },
+        latest: { type: "boolean" },
+      },
+      strict: true,
+    }));
+  } catch (err) {
+    if (err instanceof TypeError) {
+      throw new InstallError(err.message);
+    }
+    throw err;
+  }
+
+  const providers = parseProviders(values.providers);
+  const dryRun = values["dry-run"] ?? false;
+  const pinVersion = !(values.latest ?? false);
+
+  const targetRoots = values["target-root"]?.map(normalizePath) ?? [];
+  if (targetRoots.length === 0) {
+    targetRoots.push(getWorkspaceRoot());
+  }
+
+  const dedupedTargets = [...new Set(targetRoots.map(normalizePath))];
+
+  return { providers, dryRun, pinVersion, targetRoots: dedupedTargets };
+}