@tracemarketplace/shared 0.0.1

package/src/extractors/codex.ts

@@ -0,0 +1,208 @@
+import { randomUUID } from "crypto";
+import { hashString, computeContentHash } from "../hash.js";
+import type {
+  NormalizedTrace,
+  Turn,
+  ContentBlock,
+} from "../types.js";
+
+export async function extractCodex(
+  rolloutFileBuffer: Buffer,
+  submittedBy = "unknown"
+): Promise<NormalizedTrace> {
+  const events: Record<string, unknown>[] = [];
+  for (const line of rolloutFileBuffer.toString("utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try { events.push(JSON.parse(line) as Record<string, unknown>); } catch {}
+  }
+
+  const sessionMetaPayload = (events.find(e => e["type"] === "session_meta")?.["payload"] ?? {}) as Record<string, unknown>;
+  const sessionId = (sessionMetaPayload["id"] as string | undefined) ?? randomUUID();
+  const cwd = (sessionMetaPayload["cwd"] as string | undefined) ?? null;
+  const cliVersion = (sessionMetaPayload["cli_version"] as string | undefined) ?? null;
+
+  const turns: Turn[] = [];
+
+  let inTask = false;
+  let currentTurnId: string | null = null;
+  let currentUserMessage: string | null = null;
+  let currentBlocks: ContentBlock[] = [];
+  let taskTimestamp: string | null = null;
+  let currentModel: string | null = null;
+
+  for (const event of events) {
+    const type = event["type"] as string;
+    const payload = (event["payload"] ?? {}) as Record<string, unknown>;
+    const timestamp = (event["timestamp"] as string | undefined) ?? null;
+
+    if (type === "event_msg" && payload["type"] === "task_started") {
+      inTask = true;
+      currentTurnId = (payload["turn_id"] as string | undefined) ?? randomUUID();
+      currentUserMessage = null;
+      currentBlocks = [];
+      taskTimestamp = timestamp;
+      continue;
+    }
+
+    if (type === "event_msg" && payload["type"] === "task_complete") {
+      if (inTask) {
+        if (currentUserMessage) {
+          turns.push({
+            turn_id: "user_" + currentTurnId,
+            parent_turn_id: null,
+            role: "user",
+            timestamp: taskTimestamp,
+            content: [{ type: "text", text: currentUserMessage }],
+            model: null,
+            usage: null,
+            source_metadata: { turn_id: currentTurnId },
+          });
+        }
+
+        const lastMsg = payload["last_agent_message"] as string | undefined;
+        if (lastMsg) {
+          const alreadyCaptured = currentBlocks.some(
+            b => b.type === "text" && (b as { type: "text"; text: string }).text === lastMsg
+          );
+          if (!alreadyCaptured) currentBlocks.push({ type: "text", text: lastMsg });
+        }
+
+        if (currentBlocks.length > 0) {
+          turns.push({
+            turn_id: currentTurnId ?? randomUUID(),
+            parent_turn_id: currentUserMessage ? "user_" + currentTurnId : null,
+            role: "assistant",
+            timestamp: taskTimestamp,
+            content: currentBlocks,
+            model: currentModel,
+            usage: null,
+            source_metadata: { turn_id: currentTurnId },
+          });
+        }
+      }
+      inTask = false;
+      currentTurnId = null;
+      currentUserMessage = null;
+      currentBlocks = [];
+      taskTimestamp = null;
+      currentModel = null;
+      continue;
+    }
+
+    if (!inTask) continue;
+
+    if (type === "turn_context") {
+      currentModel = (payload["model"] as string | undefined) ?? null;
+      continue;
+    }
+
+    if (type === "event_msg") {
+      switch (payload["type"] as string) {
+        case "user_message":
+          currentUserMessage = (payload["message"] as string | undefined) ?? "";
+          break;
+        case "agent_reasoning":
+          if (payload["text"]) currentBlocks.push({ type: "thinking", text: payload["text"] as string });
+          break;
+        case "agent_message":
+          if (payload["message"]) currentBlocks.push({ type: "text", text: payload["message"] as string });
+          break;
+      }
+    } else if (type === "response_item") {
+      switch (payload["type"] as string) {
+        case "function_call": {
+          const callId = (payload["call_id"] as string | undefined) ?? randomUUID();
+          let toolInput: Record<string, unknown> = {};
+          try { toolInput = JSON.parse(payload["arguments"] as string ?? "{}"); } catch {
+            toolInput = { raw: payload["arguments"] };
+          }
+          currentBlocks.push({
+            type: "tool_use",
+            tool_call_id: callId,
+            tool_name: (payload["name"] as string | undefined) ?? "unknown",
+            tool_input: toolInput,
+          });
+          break;
+        }
+        case "function_call_output": {
+          const output = payload["output"] as string | undefined;
+          const isError = typeof output === "string"
+            && output.includes("Process exited with code")
+            && !output.includes("code 0");
+          currentBlocks.push({
+            type: "tool_result",
+            tool_call_id: (payload["call_id"] as string | undefined) ?? "",
+            is_error: isError,
+            result_content: output ?? null,
+            exit_code: null,
+          });
+          break;
+        }
+        case "web_search_call": {
+          const action = payload["action"] as Record<string, unknown> | undefined;
+          currentBlocks.push({
+            type: "tool_use",
+            tool_call_id: randomUUID(),
+            tool_name: "web_search",
+            tool_input: { query: action?.["query"] ?? "", queries: action?.["queries"] ?? [] },
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  const allBlocks = turns.flatMap(t => t.content);
+  const toolCallCount = allBlocks.filter(b => b.type === "tool_use").length;
+  const hasFileChanges = allBlocks.some(
+    b => b.type === "tool_use" && ["write_file", "file_change", "create_file"].includes((b as { type: "tool_use"; tool_name: string }).tool_name)
+  );
+  const hasShellCommands = allBlocks.some(
+    b => b.type === "tool_use" && ["exec_command", "bash", "shell"].includes((b as { type: "tool_use"; tool_name: string }).tool_name)
+  );
+  const hasThinking = allBlocks.some(b => b.type === "thinking");
+  const startedAt = (sessionMetaPayload["timestamp"] as string | undefined) ?? events[0]?.["timestamp"] as string ?? new Date().toISOString();
+  const endedAt = events[events.length - 1]?.["timestamp"] as string ?? new Date().toISOString();
+
+  const partialTrace: Omit<NormalizedTrace, "trace_id"> = {
+    schema_version: "1.0",
+    source_tool: "codex_cli",
+    source_session_id: sessionId,
+    source_version: cliVersion,
+    submitted_by: submittedBy,
+    submitted_at: new Date().toISOString(),
+    extracted_at: new Date().toISOString(),
+    git_branch: null,
+    cwd_hash: cwd ? hashString(cwd) : null,
+    working_language: null,
+    started_at: startedAt,
+    ended_at: endedAt,
+    turns,
+    turn_count: turns.length,
+    tool_call_count: toolCallCount,
+    has_tool_calls: toolCallCount > 0,
+    has_thinking_blocks: hasThinking,
+    has_file_changes: hasFileChanges,
+    has_shell_commands: hasShellCommands,
+    total_input_tokens: null,
+    total_output_tokens: null,
+    total_cache_read_tokens: null,
+    content_fidelity: "full",
+    env_state: {
+      git_branch: null,
+      inferred_file_tree: null,
+      inferred_changed_files: null,
+      inferred_error_files: null,
+      shell_exit_codes: null,
+      open_files_in_editor: null,
+      extraction_method: "passive",
+    },
+    score: null,
+    raw_r2_key: "",
+    normalized_r2_key: "",
+  };
+
+  const contentHash = computeContentHash(partialTrace as NormalizedTrace);
+  const traceId = hashString("codex_cli" + sessionId + contentHash);
+  return { ...partialTrace, trace_id: traceId };
+}

package/src/extractors/cursor.ts

@@ -0,0 +1,118 @@
+import { randomUUID } from "crypto";
+import { hashString, computeContentHash } from "../hash.js";
+import type { NormalizedTrace, Turn, TokenUsage } from "../types.js";
+
+export async function extractCursor(
+  dbPath: string,
+  sessionId: string,
+  submittedBy = "unknown"
+): Promise<NormalizedTrace> {
+  const Database = (await import("better-sqlite3")).default;
+  const db = new Database(dbPath, { readonly: true });
+
+  try {
+    const composerRow = db
+      .prepare("SELECT value FROM cursorDiskKV WHERE key = ?")
+      .get(`composerData:${sessionId}`) as { value: string } | undefined;
+    if (!composerRow) throw new Error(`Session ${sessionId} not found in cursor DB`);
+
+    const composerData = JSON.parse(composerRow.value);
+    const headers: any[] = composerData.fullConversationHeadersOnly ?? [];
+
+    const turns: Turn[] = [];
+    const openFiles: string[] = [];
+
+    for (const header of headers) {
+      const bubbleId = header.bubbleId ?? header.id;
+      if (!bubbleId) continue;
+
+      const blobRow = db
+        .prepare("SELECT value FROM cursorDiskKV WHERE key = ?")
+        .get(`agentKv:blob:${bubbleId}`) as { value: string } | undefined;
+      if (!blobRow) continue;
+
+      const blob = JSON.parse(blobRow.value);
+      const role: "user" | "assistant" =
+        blob.type === "user" || blob.role === "user" ? "user" : "assistant";
+      const text: string = blob.text ?? blob.content ?? blob.message ?? "";
+
+      if (blob.context?.openFiles) {
+        openFiles.push(
+          ...blob.context.openFiles.map((f: any) => (typeof f === "string" ? f : f.path ?? ""))
+        );
+      }
+
+      const tokenUsage: TokenUsage | null = blob.usage
+        ? {
+            input_tokens: blob.usage.promptTokens ?? 0,
+            output_tokens: blob.usage.completionTokens ?? 0,
+            cache_read_input_tokens: null,
+            cache_creation_input_tokens: null,
+            reasoning_tokens: null,
+          }
+        : null;
+
+      turns.push({
+        turn_id: bubbleId,
+        parent_turn_id: null,
+        role,
+        timestamp: blob.createdAt ?? header.createdAt ?? null,
+        content: [{ type: "text", text }],
+        model: blob.model ?? null,
+        usage: tokenUsage,
+        source_metadata: { bubbleId, type: blob.type },
+      });
+    }
+
+    db.close();
+
+    const startedAt = turns[0]?.timestamp ?? new Date().toISOString();
+    const endedAt = turns[turns.length - 1]?.timestamp ?? new Date().toISOString();
+
+    const partialTrace: Omit<NormalizedTrace, "trace_id"> = {
+      schema_version: "1.0",
+      source_tool: "cursor",
+      source_session_id: sessionId,
+      source_version: null,
+      submitted_by: submittedBy,
+      submitted_at: new Date().toISOString(),
+      extracted_at: new Date().toISOString(),
+      git_branch: null,
+      cwd_hash: null,
+      working_language: null,
+      started_at: startedAt,
+      ended_at: endedAt,
+      turns,
+      turn_count: turns.length,
+      tool_call_count: 0,
+      has_tool_calls: false,
+      has_thinking_blocks: false,
+      has_file_changes: false,
+      has_shell_commands: false,
+      total_input_tokens: null,
+      total_output_tokens: null,
+      total_cache_read_tokens: null,
+      content_fidelity: "chat_only",
+      env_state: {
+        git_branch: null,
+        inferred_file_tree: null,
+        inferred_changed_files: null,
+        inferred_error_files: null,
+        shell_exit_codes: null,
+        open_files_in_editor: openFiles.length > 0 ? openFiles : null,
+        extraction_method: "passive",
+      },
+      score: null,
+      raw_r2_key: "",
+      normalized_r2_key: "",
+    };
+
+    const contentHash = computeContentHash(partialTrace as NormalizedTrace);
+    const traceId = hashString("cursor" + sessionId + contentHash);
+
+    return { ...partialTrace, trace_id: traceId };
+  } catch (err) {
+    db.close();
+    throw err;
+  }
+}

package/src/hash.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { computeContentHash } from "./hash.js";
+import type { NormalizedTrace } from "./types.js";
+
+function makeTrace(overrides: Partial<NormalizedTrace> = {}): NormalizedTrace {
+  return {
+    trace_id: "test-id",
+    schema_version: "1.0",
+    source_tool: "claude_code",
+    source_session_id: "session-abc",
+    source_version: null,
+    submitted_by: "user1",
+    submitted_at: "2024-01-01T00:00:00Z",
+    extracted_at: "2024-01-01T00:00:00Z",
+    git_branch: null,
+    cwd_hash: null,
+    working_language: null,
+    started_at: "2024-01-01T00:00:00Z",
+    ended_at: "2024-01-01T00:01:00Z",
+    turns: [],
+    turn_count: 0,
+    tool_call_count: 0,
+    has_tool_calls: false,
+    has_thinking_blocks: false,
+    has_file_changes: false,
+    has_shell_commands: false,
+    total_input_tokens: null,
+    total_output_tokens: null,
+    total_cache_read_tokens: null,
+    content_fidelity: "full",
+    env_state: null,
+    score: null,
+    raw_r2_key: "",
+    normalized_r2_key: "",
+    ...overrides,
+  };
+}
+
+describe("computeContentHash", () => {
+  it("returns the same hash for identical input", () => {
+    const trace = makeTrace();
+    expect(computeContentHash(trace)).toBe(computeContentHash(trace));
+  });
+
+  it("returns different hashes for different session_ids", () => {
+    const a = makeTrace({ source_session_id: "session-aaa" });
+    const b = makeTrace({ source_session_id: "session-bbb" });
+    expect(computeContentHash(a)).not.toBe(computeContentHash(b));
+  });
+
+  it("returns different hashes for different turns", () => {
+    const a = makeTrace({ turns: [] });
+    const b = makeTrace({
+      turns: [{
+        turn_id: "t1",
+        parent_turn_id: null,
+        role: "user",
+        timestamp: null,
+        content: [{ type: "text", text: "hello" }],
+        model: null,
+        usage: null,
+        source_metadata: {},
+      }],
+    });
+    expect(computeContentHash(a)).not.toBe(computeContentHash(b));
+  });
+
+  it("output is a 64-char hex string", () => {
+    const hash = computeContentHash(makeTrace());
+    expect(hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+});

package/src/hash.ts

@@ -0,0 +1,15 @@
+import { createHash } from "crypto";
+import type { NormalizedTrace } from "./types.js";
+
+export function computeContentHash(trace: NormalizedTrace): string {
+  const content = JSON.stringify({
+    source_tool: trace.source_tool,
+    source_session_id: trace.source_session_id,
+    turns: trace.turns,
+  });
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export function hashString(s: string): string {
+  return createHash("sha256").update(s).digest("hex");
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./hash.js";
+export * from "./scoring.js";
+export * from "./utils.js";
+export * from "./validators.js";
+export { extractClaudeCode } from "./extractors/claude-code.js";
+export { extractCodex } from "./extractors/codex.js";
+export { extractCursor } from "./extractors/cursor.js";

package/src/scoring.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from "vitest";
+import { detectFailureModes, checkCompleteness, scoreTrace } from "./scoring.js";
+import type { NormalizedTrace, Turn, ContentBlock } from "./types.js";
+
+function makeTrace(overrides: Partial<NormalizedTrace> = {}): NormalizedTrace {
+  return {
+    trace_id: "test-id",
+    schema_version: "1.0",
+    source_tool: "claude_code",
+    source_session_id: "session-abc",
+    source_version: null,
+    submitted_by: "user1",
+    submitted_at: "2024-01-01T00:00:00Z",
+    extracted_at: "2024-01-01T00:00:00Z",
+    git_branch: null,
+    cwd_hash: null,
+    working_language: null,
+    started_at: "2024-01-01T00:00:00Z",
+    ended_at: "2024-01-01T00:01:00Z",
+    turns: [],
+    turn_count: 0,
+    tool_call_count: 0,
+    has_tool_calls: false,
+    has_thinking_blocks: false,
+    has_file_changes: false,
+    has_shell_commands: false,
+    total_input_tokens: null,
+    total_output_tokens: null,
+    total_cache_read_tokens: null,
+    content_fidelity: "full",
+    env_state: null,
+    score: null,
+    raw_r2_key: "",
+    normalized_r2_key: "",
+    ...overrides,
+  };
+}
+
+function makeTurn(role: "user" | "assistant", content: ContentBlock[]): Turn {
+  return {
+    turn_id: Math.random().toString(36).slice(2),
+    parent_turn_id: null,
+    role,
+    timestamp: null,
+    content,
+    model: null,
+    usage: null,
+    source_metadata: {},
+  };
+}
+
+describe("detectFailureModes", () => {
+  it("empty turns → no_failure", () => {
+    const result = detectFailureModes(makeTrace({ turns: [] }));
+    expect(result).toEqual(["no_failure"]);
+  });
+
+  it("tool_result with is_error → tool_call_failure", () => {
+    const turns = [
+      makeTurn("user", [{ type: "tool_result", tool_call_id: "t1", is_error: true, result_content: "err", exit_code: 1 }]),
+    ];
+    const result = detectFailureModes(makeTrace({ turns }));
+    expect(result).toContain("tool_call_failure");
+  });
+
+  it("same tool 3× consecutive → repeated_tool_calls", () => {
+    const toolUse = (n: number): ContentBlock => ({
+      type: "tool_use",
+      tool_call_id: `t${n}`,
+      tool_name: "bash",
+      tool_input: {},
+    });
+    const turns = [
+      makeTurn("assistant", [toolUse(1), toolUse(2), toolUse(3)]),
+    ];
+    const result = detectFailureModes(makeTrace({ turns }));
+    expect(result).toContain("repeated_tool_calls");
+  });
+
+  it("context window text → context_limit_approached", () => {
+    const turns = [
+      makeTurn("assistant", [{ type: "text", text: "You have reached the context limit of this session." }]),
+    ];
+    const result = detectFailureModes(makeTrace({ turns }));
+    expect(result).toContain("context_limit_approached");
+  });
+
+  it("final turns all errors → catastrophic_failure", () => {
+    const errResult: ContentBlock = { type: "tool_result", tool_call_id: "t1", is_error: true, result_content: "fail", exit_code: 1 };
+    const turns = [
+      makeTurn("user", [errResult]),
+      makeTurn("user", [errResult]),
+    ];
+    const result = detectFailureModes(makeTrace({ turns }));
+    expect(result).toContain("catastrophic_failure");
+  });
+
+  it("tool errors + later recovery text → graceful_recovery", () => {
+    const errResult: ContentBlock = { type: "tool_result", tool_call_id: "t1", is_error: true, result_content: "fail", exit_code: 1 };
+    const turns = [
+      makeTurn("user", [errResult]),
+      makeTurn("assistant", [{ type: "text", text: "Let me try a different approach instead." }]),
+    ];
+    const result = detectFailureModes(makeTrace({ turns }));
+    expect(result).toContain("graceful_recovery");
+  });
+});
+
+describe("checkCompleteness", () => {
+  it("no turns → malformed", () => {
+    expect(checkCompleteness(makeTrace({ turns: [] }))).toBe("malformed");
+  });
+
+  it("turn with empty content → malformed", () => {
+    const turns = [makeTurn("assistant", [])];
+    expect(checkCompleteness(makeTrace({ turns }))).toBe("malformed");
+  });
+
+  it("1 user turn → incomplete", () => {
+    const turns = [makeTurn("user", [{ type: "text", text: "hello" }])];
+    expect(checkCompleteness(makeTrace({ turns }))).toBe("incomplete");
+  });
+
+  it("2+ turns ending with assistant text → complete", () => {
+    const turns = [
+      makeTurn("user", [{ type: "text", text: "hello" }]),
+      makeTurn("assistant", [{ type: "text", text: "world" }]),
+    ];
+    expect(checkCompleteness(makeTrace({ turns }))).toBe("complete");
+  });
+});
+
+describe("scoreTrace", () => {
+  it("malformed trace → near-zero payout", () => {
+    const score = scoreTrace(makeTrace({ turns: [], content_fidelity: "chat_only" }));
+    expect(score.completeness).toBe("malformed");
+    expect(score.payout_cents).toBeLessThan(100);
+  });
+
+  it("graceful_recovery + tool_call_failure → bonuses stack", () => {
+    const baseScore = scoreTrace(makeTrace({ turns: [], content_fidelity: "full" }));
+    const errResult: ContentBlock = { type: "tool_result", tool_call_id: "t1", is_error: true, result_content: "fail", exit_code: 1 };
+    const turns = [
+      makeTurn("user", [errResult]),
+      makeTurn("assistant", [{ type: "text", text: "Let me try a different approach instead." }]),
+    ];
+    const bonusScore = scoreTrace(makeTrace({ turns, content_fidelity: "full" }));
+    expect(bonusScore.payout_cents).toBeGreaterThan(baseScore.payout_cents);
+    expect(bonusScore.failure_modes).toContain("graceful_recovery");
+    expect(bonusScore.failure_modes).toContain("tool_call_failure");
+  });
+
+  it("total clamps to [0, 1]", () => {
+    const errResult: ContentBlock = { type: "tool_result", tool_call_id: "t1", is_error: true, result_content: "fail", exit_code: 1 };
+    const turns = [
+      makeTurn("user", [errResult]),
+      makeTurn("assistant", [{ type: "text", text: "Let me try a different approach instead." }]),
+    ];
+    const score = scoreTrace(makeTrace({ turns, content_fidelity: "full", total_input_tokens: 1000000, total_output_tokens: 1000000 }));
+    expect(score.total).toBeGreaterThanOrEqual(0);
+    expect(score.total).toBeLessThanOrEqual(1);
+  });
+
+  it("payout_cents = round(total * 500) clamped to 500", () => {
+    const turns = [
+      makeTurn("user", [{ type: "text", text: "hello" }]),
+      makeTurn("assistant", [{ type: "text", text: "world" }]),
+    ];
+    const score = scoreTrace(makeTrace({ turns, content_fidelity: "full" }));
+    const expected = Math.min(500, Math.round(score.total * 500));
+    expect(score.payout_cents).toBe(expected);
+  });
+});