@arcreflex/agent-transcripts 0.1.9 → 0.1.10

package/README.md

@@ -122,12 +122,24 @@ interface TranscriptsIndex {
 - `Message`: union of UserMessage | AssistantMessage | SystemMessage | ToolCallGroup | ErrorMessage
 - `Adapter`: name, discover function, parse function
 
+### Titles
+
+Transcripts get titles from (in priority order):
+
+1. Harness-provided summary (e.g., Claude Code's sessions-index.json `summary` field)
+2. Cached title from previous sync
+3. LLM-generated title via OpenRouter (requires `OPENROUTER_API_KEY`)
+
 ## Adding an Adapter
 
 1. Create `src/adapters/<name>.ts` implementing `Adapter`
 2. Register in `src/adapters/index.ts` (adapters map + detection rules)
 3. Add test fixtures in `test/fixtures/<name>/`
 
+## Development Scripts
+
+- `scripts/infer-cc-types.prose`: open-prose program to infer types from real CC session data
+
 ## Tests
 
 Snapshot-based: `*.input.jsonl` → parse → render → compare against `*.output.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcreflex/agent-transcripts",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Transform AI coding agent session files into readable transcripts",
   "type": "module",
   "repository": {

package/scripts/infer-cc-types.prose

@@ -0,0 +1,87 @@
+# Infer TypeScript types from Claude Code session data
+#
+# Usage: prose run scripts/infer-cc-types.prose
+#
+# Examines real CC session directories and updates the type definitions
+# in src/adapters/claude-code.ts to match the current data format.
+
+# Agent that synthesizes TypeScript types from JSON examples
+agent type-inferrer:
+  model: sonnet
+  prompt: """
+    You analyze JSON data samples and synthesize TypeScript type definitions.
+
+    Your output should be:
+    - Clean, minimal TypeScript interfaces
+    - JSDoc comments explaining non-obvious fields
+    - Optional fields marked with ?
+    - Union types where the data shows multiple shapes
+    - `unknown` (never `any`) for truly dynamic data
+
+    When you see multiple examples, infer which fields are always present
+    (required) vs sometimes present (optional).
+  """
+
+# Discover CC session data locations (once)
+let discovery = session "Find CC session data"
+  model: sonnet
+  prompt: """
+    Find Claude Code session data on this system.
+
+    1. Search for sessions-index.json files under ~/.claude
+    2. For each, note the directory path and count of .jsonl files
+
+    Return a structured list of what you found.
+    If nothing found, say so clearly.
+  """
+
+# Iterate: infer types → implement → check → repeat if needed
+let feedback = "(no feedback)"
+
+loop until **feedback indicates success** (max: 5):
+  # Parallel type inference
+  parallel:
+    index_types = session: type-inferrer
+      prompt: """
+        Analyze the sessions-index.json files from the discovered locations.
+
+        Generate TypeScript interfaces for:
+        - SessionsIndex (the root object)
+        - SessionIndexEntry (each entry in the entries array)
+      """
+      context: { discovery, feedback }
+
+    record_types = session: type-inferrer
+      prompt: """
+        Analyze Claude Code session .jsonl files (sample 20-30 lines from a few files).
+
+        Generate TypeScript types describing JSONL records.
+        - ClaudeRecord (the JSONL line structure)
+        - ContentBlock (the message.content array elements)
+      """
+      context: { discovery, feedback }
+
+  # Implement and verify
+  feedback = session "Update adapter types"
+    model: opus
+    prompt: """
+      Update the type definitions in src/adapters/claude-code.ts to match these inferred types.
+
+      ## Inferred from sessions-index.json
+      {index_types}
+
+      ## Inferred from JSONL records
+      {record_types}
+
+      ## Task
+
+      1. Read the current types in src/adapters/claude-code.ts
+      2. Edit to match the inferred types (add new fields, fix types, etc.)
+      3. Run: bun run typecheck
+
+      If typecheck succeeds and you're happy with the types, output a message indicating success.
+      If typecheck fails, assess whether the failures reflect a real need to change the code or a flaw in the type design.
+        If yes, and you're happy with the types, make the changes and output a message indicating success.
+      Otherwise: output feedback requesting revisions to the type design.
+    """
+    context: { index_types, record_types }

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

package/src/sync.ts

@@ -198,22 +198,23 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           // Ensure output directory exists
           await mkdir(dirname(outputPath), { recursive: true });
 
-          // Preserve title from cache if content unchanged
-          const cachedTitle =
-            cached?.contentHash === contentHash
+          // Use title from: (1) harness-provided summary, (2) cache, (3) LLM later
+          const title =
+            session.summary ||
+            (cached?.contentHash === contentHash
               ? cached.segments[i]?.title
-              : undefined;
+              : undefined);
 
           // Render and write
           const rendered = await renderToFormat(transcript, format, {
             sourcePath,
-            title: cachedTitle,
+            title,
           });
           await Bun.write(outputPath, rendered);
           newOutputs.push(relativePath);
 
           // Build segment cache
-          const segmentCache: SegmentCache = { title: cachedTitle };
+          const segmentCache: SegmentCache = { title };
           segmentCache[format] = rendered;
           newCache.segments.push(segmentCache);
 
@@ -224,7 +225,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
             segmentIndex,
             syncedAt: new Date().toISOString(),
             firstUserMessage,
-            title: cachedTitle,
+            title,
             messageCount: transcript.metadata.messageCount,
             startTime: transcript.metadata.startTime,
             endTime: transcript.metadata.endTime,

package/src/types.ts

@@ -79,6 +79,8 @@ export interface DiscoveredSession {
   path: string;
   relativePath: string;
   mtime: number;
+  /** Summary/title from the source harness, if available */
+  summary?: string;
 }
 
 /**