@kennykeni/agent-trace 0.1.0

package/src/install/claude.ts

@@ -0,0 +1,78 @@
+import { join } from "node:path";
+import type { ChangeSummary } from "./types";
+import { hookCommand, readJson, writeJson } from "./utils";
+
+function ensureClaudeCommandGroup(
+  hooks: Record<string, unknown>,
+  event: string,
+  command: string,
+  matcher?: string,
+): void {
+  const groups = Array.isArray(hooks[event])
+    ? [...(hooks[event] as unknown[])]
+    : [];
+  let target: Record<string, unknown> | undefined;
+
+  for (const group of groups) {
+    if (!group || typeof group !== "object") continue;
+    const candidate = group as Record<string, unknown>;
+    const candidateMatcher =
+      typeof candidate.matcher === "string" ? candidate.matcher : undefined;
+    if ((matcher ?? undefined) === candidateMatcher) {
+      target = candidate;
+      break;
+    }
+  }
+
+  if (!target) {
+    target = {};
+    if (matcher) target.matcher = matcher;
+    target.hooks = [];
+    groups.push(target);
+  }
+
+  const inner = Array.isArray(target.hooks)
+    ? [...(target.hooks as unknown[])]
+    : [];
+  const filtered = inner.filter(
+    (entry) =>
+      !(
+        entry &&
+        typeof entry === "object" &&
+        (entry as Record<string, unknown>).type === "command" &&
+        typeof (entry as Record<string, unknown>).command === "string" &&
+        ((entry as Record<string, unknown>).command as string).includes(
+          "agent-trace",
+        )
+      ),
+  );
+  filtered.push({ type: "command", command });
+  target.hooks = filtered;
+  hooks[event] = groups;
+}
+
+export function installClaude(
+  targetRoot: string,
+  dryRun: boolean,
+  pinVersion = true,
+): ChangeSummary {
+  const path = join(targetRoot, ".claude", "settings.json");
+  const command = hookCommand("claude", { pinVersion });
+
+  const config = readJson(path);
+  const hooks = (config.hooks ?? {}) as Record<string, unknown>;
+
+  ensureClaudeCommandGroup(hooks, "SessionStart", command);
+  ensureClaudeCommandGroup(hooks, "SessionEnd", command);
+  ensureClaudeCommandGroup(hooks, "UserPromptSubmit", command);
+  ensureClaudeCommandGroup(hooks, "PostToolUse", command, "Write|Edit");
+  ensureClaudeCommandGroup(hooks, "PostToolUse", command, "Bash");
+  ensureClaudeCommandGroup(
+    hooks,
+    "PostToolUseFailure",
+    command,
+    "Write|Edit|Bash",
+  );
+
+  return writeJson(path, { ...config, hooks }, dryRun);
+}

package/src/install/cursor.ts

@@ -0,0 +1,50 @@
+import { join } from "node:path";
+import type { ChangeSummary } from "./types";
+import { hookCommand, readJson, writeJson } from "./utils";
+
+export function installCursor(
+  targetRoot: string,
+  dryRun: boolean,
+  pinVersion = true,
+): ChangeSummary {
+  const path = join(targetRoot, ".cursor", "hooks.json");
+  const command = hookCommand("cursor", { pinVersion });
+
+  const config = readJson(path);
+  const hooks = (config.hooks ?? {}) as Record<string, unknown>;
+  const events = [
+    "sessionStart",
+    "sessionEnd",
+    "beforeSubmitPrompt",
+    "afterFileEdit",
+    "afterTabFileEdit",
+    "afterShellExecution",
+  ];
+
+  for (const event of events) {
+    const entries = Array.isArray(hooks[event])
+      ? [...(hooks[event] as unknown[])]
+      : [];
+    const filtered = entries.filter(
+      (entry) =>
+        !(
+          entry &&
+          typeof entry === "object" &&
+          typeof (entry as Record<string, unknown>).command === "string" &&
+          ((entry as Record<string, unknown>).command as string).includes(
+            "agent-trace",
+          )
+        ),
+    );
+    filtered.push({ command });
+    hooks[event] = filtered;
+  }
+
+  const next = {
+    ...config,
+    version: Number.isInteger(config.version) ? config.version : 1,
+    hooks,
+  };
+
+  return writeJson(path, next, dryRun);
+}

package/src/install/index.ts

@@ -0,0 +1,49 @@
+import { installClaude } from "./claude";
+import { installCursor } from "./cursor";
+import { installOpenCode } from "./opencode";
+import type { ChangeSummary, InstallOptions } from "./types";
+
+export { InstallError, parseArgs } from "./args";
+export type { ChangeSummary, InstallOptions } from "./types";
+
+export function install(options: InstallOptions): ChangeSummary[] {
+  const changes: ChangeSummary[] = [];
+
+  for (const targetRoot of options.targetRoots) {
+    if (options.providers.includes("cursor")) {
+      changes.push(
+        installCursor(targetRoot, options.dryRun, options.pinVersion),
+      );
+    }
+    if (options.providers.includes("claude")) {
+      changes.push(
+        installClaude(targetRoot, options.dryRun, options.pinVersion),
+      );
+    }
+    if (options.providers.includes("opencode")) {
+      changes.push(
+        installOpenCode(targetRoot, options.dryRun, options.pinVersion),
+      );
+    }
+  }
+
+  return changes;
+}
+
+export function printInstallSummary(
+  changes: ChangeSummary[],
+  targetRoots: string[],
+): void {
+  const summary = changes
+    .map((change) =>
+      change.note
+        ? `${change.status.toUpperCase()}: ${change.file} (${change.note})`
+        : `${change.status.toUpperCase()}: ${change.file}`,
+    )
+    .join("\n");
+
+  console.log(summary);
+  console.log("\nTargets:");
+  for (const target of targetRoots) console.log(`  ${target}`);
+  console.log("\nTrace output: .agent-trace/");
+}

package/src/install/opencode.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ChangeSummary } from "./types";
+import { getPackageName, getPackageVersion, writeTextFile } from "./utils";
+
+export function installOpenCode(
+  targetRoot: string,
+  dryRun: boolean,
+  pinVersion = true,
+): ChangeSummary {
+  const templatePath = join(import.meta.dir, "templates", "opencode-plugin.ts");
+  const raw = readFileSync(templatePath, "utf-8");
+  const name = getPackageName();
+  const pkg = pinVersion ? `${name}@${getPackageVersion()}` : name;
+  const content = raw.replace("__AGENT_TRACE_PKG__", pkg);
+  const path = join(targetRoot, ".opencode", "plugins", "agent-trace.ts");
+  return writeTextFile(path, content, dryRun);
+}

package/src/install/templates/opencode-plugin.ts

@@ -0,0 +1,207 @@
+import { spawn } from "node:child_process";
+
+async function emitToAgentTrace(root: string, payload: unknown): Promise<void> {
+  await new Promise<void>((resolve) => {
+    const child = spawn(
+      "bunx",
+      ["__AGENT_TRACE_PKG__", "hook", "--provider", "opencode"],
+      {
+        cwd: root,
+        stdio: ["pipe", "ignore", "ignore"],
+      },
+    );
+    child.on("error", () => resolve());
+    child.on("exit", () => resolve());
+    child.stdin.end(JSON.stringify(payload));
+  });
+}
+
+export const AgentTracePlugin = async ({
+  worktree,
+  directory,
+}: {
+  worktree?: string;
+  directory?: string;
+}) => {
+  const root = worktree || directory || process.cwd();
+  const pendingCommands = new Map<string, string>();
+  return {
+    event: async ({
+      event,
+    }: {
+      event: { type: string; properties: Record<string, unknown> };
+    }) => {
+      const props = event.properties ?? {};
+      const nested = (key: string) => {
+        const v = props[key];
+        return typeof v === "object" && v !== null
+          ? (v as Record<string, unknown>)
+          : undefined;
+      };
+      const info = nested("info");
+      const part = nested("part");
+
+      const str = (v: unknown): string | undefined =>
+        typeof v === "string" && v ? v : undefined;
+
+      const session =
+        str(props.sessionID) ??
+        str(info?.sessionID) ??
+        str(info?.id) ??
+        str(part?.sessionID);
+
+      const filterDiffs = (arr: unknown[]) =>
+        arr.filter((d: unknown) => {
+          if (!d || typeof d !== "object") return true;
+          const file = (d as Record<string, unknown>).file;
+          return typeof file !== "string" || !file.startsWith(".agent-trace/");
+        });
+
+      let filtered = props;
+      if (Array.isArray(props.diff)) {
+        filtered = { ...filtered, diff: filterDiffs(props.diff) };
+      }
+      if (info?.summary && typeof info.summary === "object") {
+        const summary = info.summary as Record<string, unknown>;
+        if (Array.isArray(summary.diffs)) {
+          filtered = {
+            ...filtered,
+            info: {
+              ...info,
+              summary: { ...summary, diffs: filterDiffs(summary.diffs) },
+            },
+          };
+        }
+      }
+
+      await emitToAgentTrace(root, {
+        hook_event_name: event.type ?? "event",
+        provider: "opencode",
+        session_id: session,
+        cwd: root,
+        event: filtered,
+      });
+    },
+
+    "chat.message": async (
+      input: {
+        sessionID: string;
+        agent?: string;
+        model?: { providerID: string; modelID: string };
+        messageID?: string;
+      },
+      output: {
+        parts?: Array<{ type?: string; text?: string; synthetic?: boolean }>;
+      },
+    ) => {
+      const parts = output?.parts ?? [];
+      const content = parts
+        .filter(
+          (p) =>
+            !p.synthetic && p.type === "text" && typeof p.text === "string",
+        )
+        .map((p) => p.text as string)
+        .join("\n");
+      if (!content) return;
+
+      const model =
+        input.model?.providerID && input.model?.modelID
+          ? `${input.model.providerID}/${input.model.modelID}`
+          : input.model?.modelID;
+
+      await emitToAgentTrace(root, {
+        hook_event_name: "hook:chat.message",
+        provider: "opencode",
+        session_id: input.sessionID,
+        cwd: root,
+        content,
+        role: "user",
+        model,
+        message_id: input.messageID,
+        agent: input.agent,
+      });
+    },
+
+    "tool.execute.before": async (
+      input: { tool: string; sessionID: string; callID: string },
+      output: { args: Record<string, unknown> },
+    ) => {
+      const shellTools = ["bash", "shell"];
+      if (
+        shellTools.includes(input.tool) &&
+        typeof output?.args?.command === "string"
+      ) {
+        pendingCommands.set(input.callID, output.args.command);
+      }
+    },
+
+    "tool.execute.after": async (
+      input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+      },
+      output: {
+        title?: string;
+        output?: string;
+        metadata?: {
+          files?: Array<{
+            filePath?: string;
+            before?: string;
+            after?: string;
+            additions?: number;
+            deletions?: number;
+          }>;
+        };
+      },
+    ) => {
+      const toolName = input?.tool ?? "";
+      const shellTools = ["bash", "shell"];
+
+      if (shellTools.includes(toolName)) {
+        const command = pendingCommands.get(input.callID);
+        pendingCommands.delete(input.callID);
+        await emitToAgentTrace(root, {
+          hook_event_name: "hook:tool.execute.after",
+          provider: "opencode",
+          session_id: input.sessionID,
+          cwd: root,
+          tool_name: toolName,
+          command,
+        });
+        return;
+      }
+
+      const editTools = ["edit", "apply_patch", "write", "patch"];
+      if (!editTools.includes(toolName)) return;
+
+      const metadata = output?.metadata;
+      const files: Array<{ file: string; before?: string; after?: string }> =
+        [];
+
+      if (metadata?.files) {
+        for (const f of metadata.files) {
+          const fp = f.filePath ?? "";
+          if (!fp || fp.startsWith(".agent-trace/")) continue;
+          files.push({
+            file: fp,
+            before: f.before,
+            after: f.after,
+          });
+        }
+      }
+
+      if (files.length === 0) return;
+
+      await emitToAgentTrace(root, {
+        hook_event_name: "hook:tool.execute.after",
+        provider: "opencode",
+        session_id: input.sessionID,
+        cwd: root,
+        tool_name: toolName,
+        call_id: input.callID,
+        files,
+      });
+    },
+  };
+};

package/src/install/types.ts

@@ -0,0 +1,14 @@
+import type { Provider } from "../providers/types";
+
+export interface ChangeSummary {
+  file: string;
+  status: "created" | "updated" | "unchanged" | "skipped";
+  note?: string;
+}
+
+export interface InstallOptions {
+  providers: Provider[];
+  dryRun: boolean;
+  pinVersion: boolean;
+  targetRoots: string[];
+}

package/src/install/utils.ts

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureDir } from "../core/utils";
+import type { ChangeSummary } from "./types";
+
+export function readJson(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf-8");
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    throw new Error(`Failed to parse JSON at ${path}`);
+  }
+}
+
+export function writeJson(
+  path: string,
+  value: unknown,
+  dryRun: boolean,
+): ChangeSummary {
+  const next = `${JSON.stringify(value, null, 2)}\n`;
+  return writeTextFile(path, next, dryRun);
+}
+
+export function writeTextFile(
+  path: string,
+  content: string,
+  dryRun: boolean,
+): ChangeSummary {
+  let previous = "";
+  if (existsSync(path)) previous = readFileSync(path, "utf-8");
+  const status: ChangeSummary["status"] = existsSync(path)
+    ? previous === content
+      ? "unchanged"
+      : "updated"
+    : "created";
+  if (!dryRun && status !== "unchanged") {
+    ensureDir(dirname(path));
+    writeFileSync(path, content, "utf-8");
+  }
+  return { file: path, status };
+}
+
+function findPackageRoot(startDir: string): string {
+  let dir = startDir;
+  while (true) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return startDir;
+}
+
+function readPkg(): { name: string; version: string } {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  const root = findPackageRoot(dir);
+  return JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+}
+
+export function getPackageName(): string {
+  return readPkg().name;
+}
+
+export function getPackageVersion(): string {
+  return readPkg().version;
+}
+
+export function hookCommand(
+  provider: string,
+  options?: { pinVersion?: boolean },
+): string {
+  const pkg = getPackageName();
+  const pinVersion = options?.pinVersion ?? true;
+  const target = pinVersion ? `${pkg}@${getPackageVersion()}` : pkg;
+  return `bunx ${target} hook --provider ${provider}`;
+}

package/src/providers/claude.ts

@@ -0,0 +1,130 @@
+import type { HookInput, TraceEvent } from "../core/types";
+import { textFromUnknown } from "../core/utils";
+import { normalizeModelId, sessionIdFor } from "./utils";
+
+export interface ClaudeHookInput extends HookInput {
+  tool_name?: string;
+  tool_input?: {
+    file_path?: string;
+    new_string?: string;
+    old_string?: string;
+    content?: string;
+    command?: string;
+  };
+  tool_response?: {
+    originalFile?: string;
+  };
+  tool_use_id?: string;
+  source?: string;
+  reason?: string;
+  prompt?: unknown;
+  message?: unknown;
+  content?: unknown;
+}
+
+export { sessionIdFor } from "./utils";
+
+export function adapt(input: HookInput): TraceEvent | TraceEvent[] | undefined {
+  const ci = input as ClaudeHookInput;
+  const sessionId = sessionIdFor(input);
+  const model = normalizeModelId(input.model);
+
+  switch (input.hook_event_name) {
+    case "PostToolUse": {
+      const toolName = ci.tool_name ?? "";
+      const isFileEdit = toolName === "Write" || toolName === "Edit";
+      const isBash = toolName === "Bash";
+      if (!isFileEdit && !isBash) return undefined;
+
+      if (isBash) {
+        return {
+          kind: "shell",
+          provider: "claude",
+          sessionId,
+          model,
+          transcript: input.transcript_path,
+          meta: {
+            session_id: input.session_id,
+            tool_name: toolName,
+            tool_use_id: ci.tool_use_id,
+            command: ci.tool_input?.command,
+          },
+        };
+      }
+
+      const file = ci.tool_input?.file_path ?? ".unknown";
+      const newContent = ci.tool_input?.new_string ?? ci.tool_input?.content;
+      const edits = newContent
+        ? [
+            {
+              old_string:
+                ci.tool_input?.old_string ??
+                ci.tool_response?.originalFile ??
+                "",
+              new_string: newContent,
+            },
+          ]
+        : [];
+      return {
+        kind: "file_edit",
+        provider: "claude",
+        sessionId,
+        filePath: file,
+        edits,
+        model,
+        readContent: !!ci.tool_input?.file_path,
+        transcript: input.transcript_path,
+        eventName: "PostToolUse",
+        meta: {
+          session_id: input.session_id,
+          tool_name: toolName,
+          tool_use_id: ci.tool_use_id,
+        },
+      };
+    }
+
+    case "UserPromptSubmit": {
+      const text = textFromUnknown(ci.prompt ?? ci.message ?? ci.content);
+      if (!text) return undefined;
+      return {
+        kind: "message",
+        provider: "claude",
+        sessionId,
+        role: "user",
+        content: text,
+        eventName: "UserPromptSubmit",
+        model,
+        meta: {},
+      };
+    }
+
+    case "SessionStart": {
+      return {
+        kind: "session_start",
+        provider: "claude",
+        sessionId,
+        model,
+        meta: {
+          session_id: input.session_id,
+          source: ci.source,
+        },
+      };
+    }
+
+    case "SessionEnd": {
+      return {
+        kind: "session_end",
+        provider: "claude",
+        sessionId,
+        model,
+        meta: {
+          session_id: input.session_id,
+          reason: ci.reason,
+        },
+      };
+    }
+
+    default:
+      return undefined;
+  }
+}