@arcreflex/agent-transcripts 0.1.8 → 0.1.10

package/src/adapters/claude-code.ts

@@ -17,46 +17,281 @@ import type {
 } from "../types.ts";
 import { extractToolSummary } from "../utils/summary.ts";
 
+// ============================================================================
+// sessions-index.json types
+// ============================================================================
+
 /**
- * Claude Code sessions-index.json structure.
+ * Root structure of sessions-index.json file.
+ * Contains metadata about all Claude Code sessions for a project.
  */
 interface SessionsIndex {
+  /** Schema version for the index file format */
   version: number;
+  /** Array of session metadata entries */
   entries: SessionIndexEntry[];
+  /**
+   * Original project path (workspace path).
+   * This is the actual project directory being worked on.
+   */
+  originalPath: string;
 }
 
+/**
+ * Metadata for a single Claude Code session.
+ * Each entry corresponds to one .jsonl session file.
+ */
 interface SessionIndexEntry {
+  /** Unique session identifier (UUID format) */
   sessionId: string;
+  /**
+   * Absolute path to the session .jsonl file.
+   * Typically in ~/.claude/projects/<project-name>/<sessionId>.jsonl
+   */
   fullPath: string;
+  /**
+   * File modification time in Unix epoch milliseconds.
+   * Used to detect file changes and for sorting.
+   */
   fileMtime: number;
+  /**
+   * First user prompt in the session (may be truncated with "…").
+   * Will be "No prompt" for empty sessions or "[Request interrupted by user]"
+   * for sessions that were interrupted before completion.
+   */
+  firstPrompt: string;
+  /**
+   * Human-readable summary of the session.
+   * Generated by Claude Code, describes what the session accomplished.
+   * Common patterns:
+   * - "Conversation Cleared" / "Empty Conversation - Clear Command Only" for cleared sessions
+   * - Action-oriented descriptions for active sessions
+   */
+  summary: string;
+  /** Total number of messages in the session */
+  messageCount: number;
+  /** ISO 8601 timestamp when the session was created */
+  created: string;
+  /** ISO 8601 timestamp when the session was last modified */
+  modified: string;
+  /**
+   * Git branch that was active when the session was created/active.
+   * Useful for correlating sessions with code changes.
+   */
+  gitBranch: string;
+  /**
+   * Project workspace path.
+   * This is the working directory for the session.
+   */
+  projectPath: string;
+  /**
+   * Whether this session is a "sidechain" (subagent) session.
+   * Subagent sessions are spawned by parent sessions for specialized tasks.
+   * Main sessions have isSidechain: false.
+   */
+  isSidechain: boolean;
+}
+
+// ============================================================================
+// JSONL record types
+// ============================================================================
+
+/**
+ * Top-level JSONL record type discriminated by `type` field.
+ * Each line in a Claude Code session .jsonl file is one of these record types.
+ */
+type ClaudeRecord =
+  | FileHistorySnapshot
+  | UserRecord
+  | AssistantRecord
+  | SystemRecord
+  | ProgressRecord
+  | SummaryRecord;
+
+/**
+ * Records that participate in the message tree (have uuid, parentUuid, timestamp).
+ * These are the record types that the parsing code processes for transcript generation.
+ */
+type MessageRecord =
+  | UserRecord
+  | AssistantRecord
+  | SystemRecord
+  | ProgressRecord;
+
+/** Type guard for message records */
+function isMessageRecord(rec: ClaudeRecord): rec is MessageRecord {
+  return (
+    rec.type === "user" ||
+    rec.type === "assistant" ||
+    rec.type === "system" ||
+    rec.type === "progress"
+  );
+}
+
+/** Common fields shared by most record types */
+interface BaseRecord {
+  uuid: string;
+  parentUuid: string | null;
+  timestamp: string;
   isSidechain: boolean;
+  userType: "external";
+  cwd: string;
+  sessionId: string;
+  version: string;
+  gitBranch: string;
+  slug?: string;
+}
+
+interface FileHistorySnapshot {
+  type: "file-history-snapshot";
+  messageId: string;
+  snapshot: {
+    messageId: string;
+    trackedFileBackups: Record<
+      string,
+      {
+        backupFileName: string;
+        version: number;
+        backupTime: string;
+      }
+    >;
+    timestamp: string;
+  };
+  isSnapshotUpdate: boolean;
 }
 
-// Claude Code JSONL record types
-interface ClaudeRecord {
-  type: string;
-  uuid?: string;
-  parentUuid?: string | null;
-  timestamp?: string;
-  message?: {
-    role: string;
+interface UserRecord extends BaseRecord {
+  type: "user";
+  message: {
+    role: "user";
     content: string | ContentBlock[];
   };
-  content?: string;
-  subtype?: string;
+  /** Present when message is metadata (e.g., command caveats) */
+  isMeta?: boolean;
+  /** Present when message is a tool result */
+  toolUseResult?: {
+    task?: {
+      id: string;
+      subject: string;
+    };
+    [key: string]: unknown;
+  };
+  /** UUID of the assistant message that triggered this tool use */
+  sourceToolAssistantUUID?: string;
+}
+
+interface AssistantRecord extends BaseRecord {
+  type: "assistant";
+  message: {
+    model: string;
+    id: string;
+    type: "message";
+    role: "assistant";
+    content: ContentBlock[];
+    stop_reason: string | null;
+    stop_sequence: string | null;
+    usage: {
+      input_tokens: number;
+      cache_creation_input_tokens?: number;
+      cache_read_input_tokens?: number;
+      cache_creation?: {
+        ephemeral_5m_input_tokens: number;
+        ephemeral_1h_input_tokens: number;
+      };
+      output_tokens: number;
+      service_tier?: string;
+    };
+  };
+  requestId: string;
 }
 
-interface ContentBlock {
-  type: string;
-  text?: string;
-  thinking?: string;
-  id?: string;
-  name?: string;
-  input?: Record<string, unknown>;
-  tool_use_id?: string;
+interface SystemRecord extends BaseRecord {
+  type: "system";
+  /** Subtypes: "turn_duration", etc. */
+  subtype: string;
+  isMeta: boolean;
+  /** Present for turn_duration subtype */
+  durationMs?: number;
+  /** Text content (if any) - some system messages may include display text */
   content?: string;
 }
 
+interface ProgressRecord extends BaseRecord {
+  type: "progress";
+  data: AgentProgressData | HookProgressData;
+  /** Tool use ID that triggered this progress */
+  toolUseID?: string;
+  /** Parent tool use ID (for nested tool calls) */
+  parentToolUseID?: string;
+}
+
+interface AgentProgressData {
+  type: "agent_progress";
+  message: {
+    type: "user";
+    message: {
+      role: "user";
+      content: ContentBlock[];
+    };
+    uuid: string;
+    timestamp: string;
+  };
+  normalizedMessages: unknown[];
+  /** The prompt text sent to the agent */
+  prompt: string;
+  /** Agent identifier */
+  agentId: string;
+}
+
+interface HookProgressData {
+  type: "hook_progress";
+  hookEvent: string;
+  hookName: string;
+  command: string;
+}
+
+interface SummaryRecord {
+  type: "summary";
+  /** Human-readable summary text */
+  summary: string;
+  /** UUID of the leaf message in the conversation tree */
+  leafUuid: string;
+}
+
+// ============================================================================
+// Content block types
+// ============================================================================
+
+/**
+ * Content blocks appear in message.content arrays for both user and assistant messages.
+ */
+type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock;
+
+interface TextBlock {
+  type: "text";
+  text: string;
+}
+
+interface ThinkingBlock {
+  type: "thinking";
+  thinking: string;
+}
+
+interface ToolUseBlock {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+interface ToolResultBlock {
+  type: "tool_result";
+  tool_use_id: string;
+  content: string | ContentBlock[];
+  /** Present when tool result indicates an error */
+  is_error?: boolean;
+}
+
 /**
  * Parse JSONL content with best-effort error recovery.
  */
@@ -86,52 +321,109 @@ function parseJsonl(content: string): {
   return { records, warnings };
 }
 
+/** Any record that can participate in parent-child relationships */
+type TraversableRecord = { uuid: string; parentUuid: string | null };
+
+/**
+ * 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, TraversableRecord>,
+  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;
+}
+
+/** Message record types that appear in conversation trees */
+type ConversationRecord = UserRecord | AssistantRecord | SystemRecord;
+
+/** Result of splitting records into conversation trees */
+interface SplitResult {
+  conversations: ConversationRecord[][];
+  /** 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[][] {
-  // Filter to only message records (user, assistant, system with uuid)
+function splitConversations(records: ClaudeRecord[]): SplitResult {
+  // Filter to only message records (user, assistant, system - records with uuid)
   const messageRecords = records.filter(
-    (r) =>
-      r.uuid &&
-      (r.type === "user" || r.type === "assistant" || r.type === "system"),
+    (r): r is UserRecord | AssistantRecord | SystemRecord =>
+      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) {
-    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);
-      }
+  // Build UUID lookup for ALL records with uuid/parentUuid to enable
+  // traversing through non-message records (e.g., progress) when resolving parents
+  const allByUuid = new Map<string, TraversableRecord>();
+  for (const rec of records) {
+    if (isMessageRecord(rec)) {
+      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>(messageRecords.map((r) => r.uuid));
+
+  // Build parent → children map, resolving through non-message records
+  // Also track resolved parents for use in transformation
+  const byUuid = new Map<string, ConversationRecord>();
+  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);
+    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);
     }
   }
 
   // BFS from each root to collect conversation
   const visited = new Set<string>();
-  const conversations: ClaudeRecord[][] = [];
+  const conversations: ConversationRecord[][] = [];
 
   for (const root of roots) {
     if (visited.has(root)) continue;
 
-    const conversation: ClaudeRecord[] = [];
+    const conversation: ConversationRecord[] = [];
     const queue = [root];
 
     while (queue.length > 0) {
@@ -155,12 +447,12 @@ function splitConversations(records: ClaudeRecord[]): ClaudeRecord[][] {
 
   // Sort conversations by their first message timestamp
   conversations.sort((a, b) => {
-    const ta = a[0]?.timestamp ? new Date(a[0].timestamp).getTime() : 0;
-    const tb = b[0]?.timestamp ? new Date(b[0].timestamp).getTime() : 0;
+    const ta = new Date(a[0].timestamp).getTime();
+    const tb = new Date(b[0].timestamp).getTime();
     return ta - tb;
   });
 
-  return conversations;
+  return { conversations, resolvedParents };
 }
 
 /**
@@ -189,16 +481,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,
         },
       ];
     }
@@ -206,6 +505,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).
  */
@@ -230,8 +562,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);
   }
 
@@ -242,31 +579,48 @@ function resolveParent(
  * Transform a conversation into our intermediate format.
  */
 function transformConversation(
-  records: ClaudeRecord[],
+  records: ConversationRecord[],
   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>();
 
-  // First pass: identify which messages will be skipped
+  // Collect all tool results from user messages (tool_use_id → result)
+  const allToolResults = new Map<string, string>();
   for (const rec of records) {
-    if (!rec.uuid) continue;
+    if (rec.type === "user") {
+      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) {
     let willSkip = false;
 
-    if (rec.type === "user" && rec.message) {
+    // Take the first cwd we find.
+    if (!cwd) {
+      cwd = rec.cwd;
+    }
+
+    if (rec.type === "user") {
       if (isToolResultOnly(rec.message.content)) {
         willSkip = true;
       } else {
         const text = extractText(rec.message.content);
         if (!text.trim()) willSkip = true;
       }
-    } else if (rec.type === "assistant" && rec.message) {
+    } else if (rec.type === "assistant") {
       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;
@@ -277,17 +631,24 @@ 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));
     }
   }
 
   // Second pass: build messages with corrected parent references
   for (const rec of records) {
-    const sourceRef = rec.uuid || "";
-    const timestamp = rec.timestamp || new Date().toISOString();
-    const parentMessageRef = resolveParent(rec.parentUuid, skippedParents);
+    const sourceRef = rec.uuid;
+    const timestamp = rec.timestamp;
+    // Start with the resolved parent (through non-message records),
+    // then walk through any skipped messages
+    const parentMessageRef = resolveParent(
+      resolvedParents.get(rec.uuid),
+      skippedParents,
+    );
+    const rawJson = JSON.stringify(rec);
 
-    if (rec.type === "user" && rec.message) {
+    if (rec.type === "user") {
       // Skip tool-result-only user messages (they're just tool responses)
       if (isToolResultOnly(rec.message.content)) continue;
 
@@ -298,13 +659,14 @@ function transformConversation(
           sourceRef,
           timestamp,
           parentMessageRef,
+          rawJson,
           content: text,
         });
       }
-    } else if (rec.type === "assistant" && rec.message) {
+    } else if (rec.type === "assistant") {
       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) {
@@ -313,6 +675,7 @@ function transformConversation(
           sourceRef,
           timestamp,
           parentMessageRef,
+          rawJson,
           content: text,
           thinking,
         });
@@ -325,6 +688,7 @@ function transformConversation(
           sourceRef,
           timestamp,
           parentMessageRef,
+          rawJson,
           calls: toolCalls,
         });
       }
@@ -336,18 +700,42 @@ 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,
   };
 }
@@ -383,6 +771,7 @@ async function discoverFromIndex(
           relativePath:
             relative(source, entry.fullPath) || basename(entry.fullPath),
           mtime: fileStat.mtime.getTime(),
+          summary: entry.summary,
         });
       } catch {
         // Skip files that no longer exist
@@ -435,14 +824,21 @@ export const claudeCodeAdapter: Adapter = {
 
   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: [],
         },
       ];
@@ -450,12 +846,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,
+      ),
     );
   },
 };