@arcreflex/agent-transcripts 0.1.5 → 0.1.9

package/src/adapters/claude-code.ts

@@ -4,8 +4,12 @@
  * Parses session files from ~/.claude/projects/{project}/sessions/{session}.jsonl
  */
 
+import { Glob } from "bun";
+import { basename, join, relative } from "path";
+import { stat } from "fs/promises";
 import type {
   Adapter,
+  DiscoveredSession,
   Transcript,
   Message,
   Warning,
@@ -13,6 +17,21 @@ import type {
 } from "../types.ts";
 import { extractToolSummary } from "../utils/summary.ts";
 
+/**
+ * Claude Code sessions-index.json structure.
+ */
+interface SessionsIndex {
+  version: number;
+  entries: SessionIndexEntry[];
+}
+
+interface SessionIndexEntry {
+  sessionId: string;
+  fullPath: string;
+  fileMtime: number;
+  isSidechain: boolean;
+}
+
 // Claude Code JSONL record types
 interface ClaudeRecord {
   type: string;
@@ -25,6 +44,7 @@ interface ClaudeRecord {
   };
   content?: string;
   subtype?: string;
+  cwd?: string;
 }
 
 interface ContentBlock {
@@ -35,7 +55,7 @@ interface ContentBlock {
   name?: string;
   input?: Record<string, unknown>;
   tool_use_id?: string;
-  content?: string;
+  content?: unknown; // Can be string, array, or other structure
 }
 
 /**
@@ -67,11 +87,42 @@ function parseJsonl(content: string): {
   return { records, warnings };
 }
 
+/**
+ * Find the nearest message ancestor by walking up the parent chain.
+ * Returns undefined if no message ancestor exists.
+ */
+function findMessageAncestor(
+  parentUuid: string | null | undefined,
+  allByUuid: Map<string, ClaudeRecord>,
+  messageUuids: Set<string>,
+): string | undefined {
+  const visited = new Set<string>();
+  let current = parentUuid;
+  while (current) {
+    if (visited.has(current)) {
+      return undefined; // Cycle detected
+    }
+    visited.add(current);
+    if (messageUuids.has(current)) {
+      return current;
+    }
+    const rec = allByUuid.get(current);
+    current = rec?.parentUuid ?? null;
+  }
+  return undefined;
+}
+
+interface SplitResult {
+  conversations: ClaudeRecord[][];
+  /** Map from message UUID to its resolved parent (nearest message ancestor) */
+  resolvedParents: Map<string, string | undefined>;
+}
+
 /**
  * Build message graph and find conversation boundaries.
- * Returns array of conversation groups (each is array of records in order).
+ * Returns conversations and a map of resolved parent references.
  */
-function splitConversations(records: ClaudeRecord[]): ClaudeRecord[][] {
+function splitConversations(records: ClaudeRecord[]): SplitResult {
   // Filter to only message records (user, assistant, system with uuid)
   const messageRecords = records.filter(
     (r) =>
@@ -79,29 +130,52 @@ function splitConversations(records: ClaudeRecord[]): ClaudeRecord[][] {
       (r.type === "user" || r.type === "assistant" || r.type === "system"),
   );
 
-  if (messageRecords.length === 0) return [];
-
-  // Build parent → children map
-  const byUuid = new Map<string, ClaudeRecord>();
-  const children = new Map<string, string[]>();
+  if (messageRecords.length === 0) {
+    return { conversations: [], resolvedParents: new Map() };
+  }
 
-  for (const rec of messageRecords) {
+  // Build UUID lookup for ALL records to track parent chains through non-messages
+  const allByUuid = new Map<string, ClaudeRecord>();
+  for (const rec of records) {
     if (rec.uuid) {
-      byUuid.set(rec.uuid, rec);
-      const parent = rec.parentUuid;
-      if (parent) {
-        const existing = children.get(parent) || [];
-        existing.push(rec.uuid);
-        children.set(parent, existing);
-      }
+      allByUuid.set(rec.uuid, rec);
     }
   }
 
-  // Find roots (no parent or parent not in our set)
+  // Set of message UUIDs for quick lookup
+  const messageUuids = new Set<string>();
+  for (const rec of messageRecords) {
+    if (rec.uuid) messageUuids.add(rec.uuid);
+  }
+
+  // Build parent → children map, resolving through non-message records
+  // Also track resolved parents for use in transformation
+  const byUuid = new Map<string, ClaudeRecord>();
+  const children = new Map<string, string[]>();
+  const resolvedParents = new Map<string, string | undefined>();
   const roots: string[] = [];
+
   for (const rec of messageRecords) {
-    if (!rec.parentUuid || !byUuid.has(rec.parentUuid)) {
-      if (rec.uuid) roots.push(rec.uuid);
+    if (!rec.uuid) continue;
+    byUuid.set(rec.uuid, rec);
+
+    // Find nearest message ancestor (walking through non-message records)
+    const ancestor = findMessageAncestor(
+      rec.parentUuid,
+      allByUuid,
+      messageUuids,
+    );
+
+    // Store resolved parent for this message
+    resolvedParents.set(rec.uuid, ancestor);
+
+    if (ancestor) {
+      const existing = children.get(ancestor) || [];
+      existing.push(rec.uuid);
+      children.set(ancestor, existing);
+    } else {
+      // No message ancestor - this is a root
+      roots.push(rec.uuid);
     }
   }
 
@@ -141,7 +215,7 @@ function splitConversations(records: ClaudeRecord[]): ClaudeRecord[][] {
     return ta - tb;
   });
 
-  return conversations;
+  return { conversations, resolvedParents };
 }
 
 /**
@@ -170,16 +244,23 @@ function extractThinking(content: string | ContentBlock[]): string | undefined {
 
 /**
  * Extract tool calls from content blocks.
+ * Matches with results from the toolResults map.
  */
-function extractToolCalls(content: string | ContentBlock[]): ToolCall[] {
+function extractToolCalls(
+  content: string | ContentBlock[],
+  toolResults: Map<string, string>,
+): ToolCall[] {
   if (typeof content === "string") return [];
 
   return content.flatMap((b) => {
-    if (b.type === "tool_use" && b.name) {
+    if (b.type === "tool_use" && b.name && b.id) {
+      const result = toolResults.get(b.id);
       return [
         {
           name: b.name,
           summary: extractToolSummary(b.name, b.input || {}),
+          input: b.input,
+          result,
         },
       ];
     }
@@ -187,6 +268,39 @@ function extractToolCalls(content: string | ContentBlock[]): ToolCall[] {
   });
 }
 
+/**
+ * Safely convert tool result content to string.
+ * Content can be a string, array, or other structure.
+ */
+function stringifyToolResult(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (content === null || content === undefined) return "";
+  // For arrays or objects, JSON stringify for display
+  try {
+    return JSON.stringify(content, null, 2);
+  } catch {
+    return String(content);
+  }
+}
+
+/**
+ * Extract tool results from content blocks.
+ * Returns a map of tool_use_id → result content.
+ */
+function extractToolResults(
+  content: string | ContentBlock[],
+): Map<string, string> {
+  const results = new Map<string, string>();
+  if (typeof content === "string") return results;
+
+  for (const b of content) {
+    if (b.type === "tool_result" && b.tool_use_id && b.content !== undefined) {
+      results.set(b.tool_use_id, stringifyToolResult(b.content));
+    }
+  }
+  return results;
+}
+
 /**
  * Check if a user message contains only tool results (no actual user text).
  */
@@ -211,8 +325,13 @@ function resolveParent(
   if (!parentUuid) return undefined;
 
   // Follow the chain through any skipped messages
+  const visited = new Set<string>();
   let current: string | undefined = parentUuid;
   while (current && skippedParents.has(current)) {
+    if (visited.has(current)) {
+      return undefined; // Cycle detected
+    }
+    visited.add(current);
     current = skippedParents.get(current);
   }
 
@@ -226,17 +345,36 @@ function transformConversation(
   records: ClaudeRecord[],
   sourcePath: string,
   warnings: Warning[],
+  resolvedParents: Map<string, string | undefined>,
 ): Transcript {
   const messages: Message[] = [];
-  // Track skipped message UUIDs → their parent UUIDs for chain repair
+  // Track skipped message UUIDs → their resolved parent UUIDs for chain repair
   const skippedParents = new Map<string, string | undefined>();
 
+  // Collect all tool results from user messages (tool_use_id → result)
+  const allToolResults = new Map<string, string>();
+  for (const rec of records) {
+    if (rec.type === "user" && rec.message) {
+      const results = extractToolResults(rec.message.content);
+      for (const [id, content] of results) {
+        allToolResults.set(id, content);
+      }
+    }
+  }
+
+  let cwd: string | undefined;
+
   // First pass: identify which messages will be skipped
   for (const rec of records) {
     if (!rec.uuid) continue;
 
     let willSkip = false;
 
+    // Take the first cwd we find.
+    if (!cwd && rec.cwd) {
+      cwd = rec.cwd;
+    }
+
     if (rec.type === "user" && rec.message) {
       if (isToolResultOnly(rec.message.content)) {
         willSkip = true;
@@ -247,7 +385,7 @@ function transformConversation(
     } else if (rec.type === "assistant" && rec.message) {
       const text = extractText(rec.message.content);
       const thinking = extractThinking(rec.message.content);
-      const toolCalls = extractToolCalls(rec.message.content);
+      const toolCalls = extractToolCalls(rec.message.content, allToolResults);
       // Only skip if no text, no thinking, AND no tool calls
       if (!text.trim() && !thinking && toolCalls.length === 0) {
         willSkip = true;
@@ -258,7 +396,8 @@ function transformConversation(
     }
 
     if (willSkip) {
-      skippedParents.set(rec.uuid, rec.parentUuid || undefined);
+      // Use the resolved parent (already walked through non-message records)
+      skippedParents.set(rec.uuid, resolvedParents.get(rec.uuid));
     }
   }
 
@@ -266,7 +405,12 @@ function transformConversation(
   for (const rec of records) {
     const sourceRef = rec.uuid || "";
     const timestamp = rec.timestamp || new Date().toISOString();
-    const parentMessageRef = resolveParent(rec.parentUuid, skippedParents);
+    // Start with the resolved parent (through non-message records),
+    // then walk through any skipped messages
+    const parentMessageRef = rec.uuid
+      ? resolveParent(resolvedParents.get(rec.uuid), skippedParents)
+      : undefined;
+    const rawJson = JSON.stringify(rec);
 
     if (rec.type === "user" && rec.message) {
       // Skip tool-result-only user messages (they're just tool responses)
@@ -279,13 +423,14 @@ function transformConversation(
           sourceRef,
           timestamp,
           parentMessageRef,
+          rawJson,
           content: text,
         });
       }
     } else if (rec.type === "assistant" && rec.message) {
       const text = extractText(rec.message.content);
       const thinking = extractThinking(rec.message.content);
-      const toolCalls = extractToolCalls(rec.message.content);
+      const toolCalls = extractToolCalls(rec.message.content, allToolResults);
 
       // Add assistant message if there's text or thinking
       if (text.trim() || thinking) {
@@ -294,6 +439,7 @@ function transformConversation(
           sourceRef,
           timestamp,
           parentMessageRef,
+          rawJson,
           content: text,
           thinking,
         });
@@ -306,6 +452,7 @@ function transformConversation(
           sourceRef,
           timestamp,
           parentMessageRef,
+          rawJson,
           calls: toolCalls,
         });
       }
@@ -317,36 +464,144 @@ function transformConversation(
           sourceRef,
           timestamp,
           parentMessageRef,
+          rawJson,
           content: text,
         });
       }
     }
   }
 
+  // Compute time bounds from min/max across all messages (not array order,
+  // which is BFS traversal order and may not be chronological for branches)
+  let minTime = Infinity;
+  let maxTime = -Infinity;
+  for (const msg of messages) {
+    const t = new Date(msg.timestamp).getTime();
+    if (t < minTime) minTime = t;
+    if (t > maxTime) maxTime = t;
+  }
+  const now = new Date().toISOString();
+  const startTime = Number.isFinite(minTime)
+    ? new Date(minTime).toISOString()
+    : now;
+  const endTime = Number.isFinite(maxTime)
+    ? new Date(maxTime).toISOString()
+    : startTime;
+
   return {
     source: {
       file: sourcePath,
       adapter: "claude-code",
     },
-    metadata: { warnings },
+    metadata: {
+      warnings,
+      messageCount: messages.length,
+      startTime,
+      endTime,
+      cwd,
+    },
     messages,
   };
 }
 
+/**
+ * Discover sessions from sessions-index.json.
+ * Returns undefined if index doesn't exist or is invalid.
+ */
+async function discoverFromIndex(
+  source: string,
+): Promise<DiscoveredSession[] | undefined> {
+  const indexPath = join(source, "sessions-index.json");
+
+  try {
+    const content = await Bun.file(indexPath).text();
+    const index: SessionsIndex = JSON.parse(content);
+
+    if (index.version !== 1 || !Array.isArray(index.entries)) {
+      return undefined;
+    }
+
+    const sessions: DiscoveredSession[] = [];
+
+    for (const entry of index.entries) {
+      // Skip sidechains (subagents)
+      if (entry.isSidechain) continue;
+
+      // Verify the file exists and get current mtime
+      try {
+        const fileStat = await stat(entry.fullPath);
+        sessions.push({
+          path: entry.fullPath,
+          relativePath:
+            relative(source, entry.fullPath) || basename(entry.fullPath),
+          mtime: fileStat.mtime.getTime(),
+        });
+      } catch {
+        // Skip files that no longer exist
+      }
+    }
+
+    return sessions;
+  } catch {
+    // Index doesn't exist or is invalid
+    return undefined;
+  }
+}
+
+/**
+ * Discover sessions via glob pattern fallback.
+ */
+async function discoverByGlob(source: string): Promise<DiscoveredSession[]> {
+  const sessions: DiscoveredSession[] = [];
+  const glob = new Glob("**/*.jsonl");
+
+  for await (const file of glob.scan({ cwd: source, absolute: false })) {
+    // Skip files in subagents directories
+    if (file.includes("/subagents/")) continue;
+
+    const fullPath = join(source, file);
+
+    try {
+      const fileStat = await stat(fullPath);
+      sessions.push({
+        path: fullPath,
+        relativePath: file,
+        mtime: fileStat.mtime.getTime(),
+      });
+    } catch {
+      // Skip files we can't stat
+    }
+  }
+
+  return sessions;
+}
+
 export const claudeCodeAdapter: Adapter = {
   name: "claude-code",
-  filePatterns: ["*.jsonl"],
+
+  async discover(source: string): Promise<DiscoveredSession[]> {
+    // Try index-based discovery first, fall back to glob
+    const fromIndex = await discoverFromIndex(source);
+    return fromIndex ?? (await discoverByGlob(source));
+  },
 
   parse(content: string, sourcePath: string): Transcript[] {
     const { records, warnings } = parseJsonl(content);
-    const conversations = splitConversations(records);
+    const { conversations, resolvedParents } = splitConversations(records);
 
     if (conversations.length === 0) {
       // Return single empty transcript with warnings
+      const now = new Date().toISOString();
       return [
         {
           source: { file: sourcePath, adapter: "claude-code" },
-          metadata: { warnings },
+          metadata: {
+            warnings,
+            messageCount: 0,
+            startTime: now,
+            endTime: now,
+            cwd: undefined,
+          },
           messages: [],
         },
       ];
@@ -354,12 +609,24 @@ export const claudeCodeAdapter: Adapter = {
 
     // For single conversation, include all warnings
     if (conversations.length === 1) {
-      return [transformConversation(conversations[0], sourcePath, warnings)];
+      return [
+        transformConversation(
+          conversations[0],
+          sourcePath,
+          warnings,
+          resolvedParents,
+        ),
+      ];
     }
 
     // For multiple conversations, only first gets warnings
     return conversations.map((conv, i) =>
-      transformConversation(conv, sourcePath, i === 0 ? warnings : []),
+      transformConversation(
+        conv,
+        sourcePath,
+        i === 0 ? warnings : [],
+        resolvedParents,
+      ),
     );
   },
 };

package/src/cache.ts

@@ -0,0 +1,129 @@
+/**
+ * Cache module for agent-transcripts.
+ *
+ * Stores derived content (rendered outputs, titles) keyed by source path,
+ * invalidated by content hash. Cache lives at ~/.cache/agent-transcripts/.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { mkdir, rename, unlink } from "fs/promises";
+
+const CACHE_DIR = join(homedir(), ".cache", "agent-transcripts");
+
+export interface SegmentCache {
+  title?: string;
+  html?: string;
+  md?: string;
+}
+
+export interface CacheEntry {
+  contentHash: string;
+  segments: SegmentCache[];
+}
+
+/**
+ * Compute a hash of file content for cache invalidation.
+ */
+export function computeContentHash(content: string): string {
+  return Bun.hash(content).toString(16);
+}
+
+/**
+ * Get the cache file path for a source file.
+ * Uses hash of source path to avoid filesystem issues with special chars.
+ */
+function getCachePath(sourcePath: string): string {
+  const pathHash = Bun.hash(sourcePath).toString(16);
+  return join(CACHE_DIR, `${pathHash}.json`);
+}
+
+/**
+ * Ensure cache directory exists.
+ */
+async function ensureCacheDir(): Promise<void> {
+  await mkdir(CACHE_DIR, { recursive: true, mode: 0o755 });
+}
+
+/**
+ * Load cache entry for a source file.
+ * Returns undefined if no cache exists or cache is corrupt.
+ */
+export async function loadCache(
+  sourcePath: string,
+): Promise<CacheEntry | undefined> {
+  const cachePath = getCachePath(sourcePath);
+  try {
+    const content = await Bun.file(cachePath).text();
+    return JSON.parse(content) as CacheEntry;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Save cache entry for a source file.
+ * Uses atomic write (temp file + rename) to prevent corruption.
+ */
+export async function saveCache(
+  sourcePath: string,
+  entry: CacheEntry,
+): Promise<void> {
+  await ensureCacheDir();
+
+  const cachePath = getCachePath(sourcePath);
+  const tmpPath = `${cachePath}.${process.pid}.${Date.now()}.tmp`;
+
+  const content = JSON.stringify(entry, null, 2) + "\n";
+  await Bun.write(tmpPath, content);
+
+  try {
+    await rename(tmpPath, cachePath);
+  } catch (err) {
+    try {
+      await unlink(tmpPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw err;
+  }
+}
+
+/**
+ * Check if cache is valid for the given content hash and format.
+ * Returns the cached segments if valid, undefined otherwise.
+ */
+export function getCachedSegments(
+  cached: CacheEntry | undefined,
+  contentHash: string,
+  format: "html" | "md",
+): SegmentCache[] | undefined {
+  if (!cached || cached.contentHash !== contentHash) {
+    return undefined;
+  }
+  // Check that all segments have the requested format
+  if (cached.segments.length === 0) {
+    return undefined;
+  }
+  for (const seg of cached.segments) {
+    if (!seg[format]) {
+      return undefined;
+    }
+  }
+  return cached.segments;
+}
+
+/**
+ * Get cached title for a specific segment.
+ * Returns undefined if cache is invalid or title not present.
+ */
+export function getCachedTitle(
+  cached: CacheEntry | undefined,
+  contentHash: string,
+  segmentIndex: number,
+): string | undefined {
+  if (!cached || cached.contentHash !== contentHash) {
+    return undefined;
+  }
+  return cached.segments[segmentIndex]?.title;
+}