@arcreflex/agent-transcripts 0.1.9 → 0.1.11

package/src/adapters/claude-code.ts

@@ -17,45 +17,279 @@ 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[];
   };
+  /** 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 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;
-  subtype?: string;
-  cwd?: string;
 }
 
-interface ContentBlock {
-  type: string;
-  text?: string;
-  thinking?: string;
-  id?: string;
-  name?: string;
-  input?: Record<string, unknown>;
-  tool_use_id?: string;
-  content?: unknown; // Can be string, array, or other structure
+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;
 }
 
 /**
@@ -87,13 +321,16 @@ 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, ClaudeRecord>,
+  allByUuid: Map<string, TraversableRecord>,
   messageUuids: Set<string>,
 ): string | undefined {
   const visited = new Set<string>();
@@ -112,8 +349,12 @@ function findMessageAncestor(
   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: ClaudeRecord[][];
+  conversations: ConversationRecord[][];
   /** Map from message UUID to its resolved parent (nearest message ancestor) */
   resolvedParents: Map<string, string | undefined>;
 }
@@ -123,40 +364,36 @@ interface SplitResult {
  * Returns conversations and a map of resolved parent references.
  */
 function splitConversations(records: ClaudeRecord[]): SplitResult {
-  // Filter to only message records (user, assistant, system with uuid)
+  // 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 { conversations: [], resolvedParents: new Map() };
   }
 
-  // Build UUID lookup for ALL records to track parent chains through non-messages
-  const allByUuid = new Map<string, ClaudeRecord>();
+  // 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 (rec.uuid) {
+    if (isMessageRecord(rec)) {
       allByUuid.set(rec.uuid, rec);
     }
   }
 
   // Set of message UUIDs for quick lookup
-  const messageUuids = new Set<string>();
-  for (const rec of messageRecords) {
-    if (rec.uuid) messageUuids.add(rec.uuid);
-  }
+  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, ClaudeRecord>();
+  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.uuid) continue;
     byUuid.set(rec.uuid, rec);
 
     // Find nearest message ancestor (walking through non-message records)
@@ -181,12 +418,12 @@ function splitConversations(records: ClaudeRecord[]): SplitResult {
 
   // 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) {
@@ -210,8 +447,8 @@ function splitConversations(records: ClaudeRecord[]): SplitResult {
 
   // 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;
   });
 
@@ -342,7 +579,7 @@ function resolveParent(
  * Transform a conversation into our intermediate format.
  */
 function transformConversation(
-  records: ClaudeRecord[],
+  records: ConversationRecord[],
   sourcePath: string,
   warnings: Warning[],
   resolvedParents: Map<string, string | undefined>,
@@ -354,7 +591,7 @@ function transformConversation(
   // 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) {
+    if (rec.type === "user") {
       const results = extractToolResults(rec.message.content);
       for (const [id, content] of results) {
         allToolResults.set(id, content);
@@ -366,23 +603,21 @@ function transformConversation(
 
   // 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) {
+    if (!cwd) {
       cwd = rec.cwd;
     }
 
-    if (rec.type === "user" && rec.message) {
+    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, allToolResults);
@@ -403,16 +638,17 @@ function transformConversation(
 
   // 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 sourceRef = rec.uuid;
+    const timestamp = rec.timestamp;
     // 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 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;
 
@@ -427,7 +663,7 @@ function transformConversation(
           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, allToolResults);
@@ -535,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
@@ -578,6 +815,7 @@ async function discoverByGlob(source: string): Promise<DiscoveredSession[]> {
 
 export const claudeCodeAdapter: Adapter = {
   name: "claude-code",
+  version: "claude-code:1",
 
   async discover(source: string): Promise<DiscoveredSession[]> {
     // Try index-based discovery first, fall back to glob

package/src/adapters/index.ts

@@ -30,16 +30,10 @@ export function detectAdapter(filePath: string): string | undefined {
   return undefined;
 }
 
-/**
- * Get adapter by name.
- */
 export function getAdapter(name: string): Adapter | undefined {
   return adapters[name];
 }
 
-/**
- * List available adapter names.
- */
 export function listAdapters(): string[] {
   return Object.keys(adapters);
 }