@arcreflex/agent-transcripts 0.1.8 → 0.1.9

package/src/title.ts

@@ -0,0 +1,172 @@
+/**
+ * Title generation command.
+ *
+ * Adds LLM-generated titles to transcripts.json entries that don't have them.
+ * Can be run standalone or called from sync.
+ */
+
+import { join } from "path";
+import { loadIndex, saveIndex } from "./utils/provenance.ts";
+import { getAdapters } from "./adapters/index.ts";
+import { renderTranscript } from "./render.ts";
+import { renderTranscriptHtml } from "./render-html.ts";
+import { generateTitle } from "./utils/openrouter.ts";
+import {
+  computeContentHash,
+  loadCache,
+  saveCache,
+  getCachedTitle,
+  type CacheEntry,
+} from "./cache.ts";
+
+export interface TitleOptions {
+  outputDir: string;
+  force?: boolean; // regenerate all titles, not just missing ones
+  quiet?: boolean;
+}
+
+export interface TitleResult {
+  generated: number;
+  skipped: number;
+  errors: number;
+}
+
+/**
+ * Generate titles for transcripts.json entries that don't have them.
+ */
+export async function generateTitles(
+  options: TitleOptions,
+): Promise<TitleResult> {
+  const { outputDir, force = false, quiet = false } = options;
+
+  const result: TitleResult = { generated: 0, skipped: 0, errors: 0 };
+
+  if (!process.env.OPENROUTER_API_KEY) {
+    if (!quiet) {
+      console.error("OPENROUTER_API_KEY not set, skipping title generation");
+    }
+    return result;
+  }
+
+  const index = await loadIndex(outputDir);
+  const entries = Object.entries(index.entries);
+
+  if (entries.length === 0) {
+    if (!quiet) {
+      console.error("No entries in transcripts.json");
+    }
+    return result;
+  }
+
+  const adapters = getAdapters();
+  const adapterMap = new Map(adapters.map((a) => [a.name, a]));
+
+  // Process entries that need titles
+  for (const [filename, entry] of entries) {
+    // Skip if already has title (unless force)
+    if (entry.title && !force) {
+      result.skipped++;
+      continue;
+    }
+
+    try {
+      // Read source and compute content hash
+      const content = await Bun.file(entry.source).text();
+      const contentHash = computeContentHash(content);
+
+      // Check cache for existing title
+      const cached = await loadCache(entry.source);
+      const segmentIndex = entry.segmentIndex ? entry.segmentIndex - 1 : 0;
+      const cachedTitle = getCachedTitle(cached, contentHash, segmentIndex);
+
+      if (cachedTitle && !force) {
+        entry.title = cachedTitle;
+        result.skipped++;
+        continue;
+      }
+
+      // Determine adapter from filename pattern (HTML files were synced with an adapter)
+      // We need to find which adapter was used - check the source path
+      let adapter = adapterMap.get("claude-code"); // default
+      for (const a of adapters) {
+        if (entry.source.includes(".claude/")) {
+          adapter = a;
+          break;
+        }
+      }
+
+      if (!adapter) {
+        console.error(`Warning: No adapter found for ${entry.source}`);
+        result.errors++;
+        continue;
+      }
+
+      const transcripts = adapter.parse(content, entry.source);
+
+      // Find the right transcript (by segment index if applicable)
+      const transcript = transcripts[segmentIndex];
+
+      if (!transcript) {
+        console.error(`Warning: Transcript not found for ${filename}`);
+        result.errors++;
+        continue;
+      }
+
+      const markdown = renderTranscript(transcript);
+      const title = await generateTitle(markdown);
+
+      if (title) {
+        entry.title = title;
+        result.generated++;
+        if (!quiet) {
+          console.error(`Title: ${filename} → ${title}`);
+        }
+
+        // Update cache with new title
+        // Start fresh if content changed to avoid stale md/html
+        // Deep copy segments to avoid mutating cached object
+        const newCache: CacheEntry = {
+          contentHash,
+          segments:
+            cached?.contentHash === contentHash
+              ? cached.segments.map((s) => ({ ...s }))
+              : [],
+        };
+        // Ensure segment array is long enough
+        while (newCache.segments.length <= segmentIndex) {
+          newCache.segments.push({});
+        }
+        newCache.segments[segmentIndex].title = title;
+
+        // Re-render HTML with title if this is an HTML file
+        if (filename.endsWith(".html")) {
+          const html = await renderTranscriptHtml(transcript, { title });
+          const outputPath = join(outputDir, filename);
+          await Bun.write(outputPath, html);
+          newCache.segments[segmentIndex].html = html;
+        }
+
+        await saveCache(entry.source, newCache);
+      } else {
+        result.skipped++;
+        if (!quiet) {
+          console.error(`Skip (no title generated): ${filename}`);
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Error: ${filename}: ${message}`);
+      result.errors++;
+    }
+  }
+
+  await saveIndex(outputDir, index);
+
+  if (!quiet) {
+    console.error(
+      `\nTitle generation complete: ${result.generated} generated, ${result.skipped} skipped, ${result.errors} errors`,
+    );
+  }
+
+  return result;
+}

package/src/types.ts

@@ -10,6 +10,10 @@ export interface Transcript {
   };
   metadata: {
     warnings: Warning[];
+    messageCount: number;
+    startTime: string; // ISO timestamp of first message
+    endTime: string; // ISO timestamp of last message
+    cwd?: string; // Working directory (if known)
   };
   messages: Message[];
 }
@@ -31,6 +35,7 @@ interface BaseMessage {
   sourceRef: string;
   timestamp: string;
   parentMessageRef?: string; // UUID of parent message (for tree reconstruction)
+  rawJson?: string; // Original JSON for raw view toggle
 }
 
 export interface UserMessage extends BaseMessage {
@@ -57,6 +62,8 @@ export interface ToolCallGroup extends BaseMessage {
 export interface ToolCall {
   name: string;
   summary: string;
+  input?: Record<string, unknown>;
+  result?: string;
   error?: string;
 }
 

package/src/utils/html.ts

@@ -0,0 +1,12 @@
+/**
+ * HTML rendering utilities.
+ */
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}

package/src/utils/openrouter.ts

@@ -0,0 +1,116 @@
+/**
+ * OpenRouter API client for LLM-based title generation.
+ *
+ * Uses Gemini 2.5 Flash for fast, cheap title generation.
+ * Gracefully handles missing API key or API failures.
+ */
+
+const OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions";
+const MODEL = "google/gemini-2.5-flash";
+
+// Approximate token limit for context (conservative estimate)
+// Gemini Flash has 1M context, but we don't need anywhere near that
+const MAX_CHARS = 32000; // ~8k tokens
+
+/**
+ * Truncate content with middle-cut strategy.
+ * Keeps beginning and end, removes middle if over limit.
+ */
+function truncateMiddle(content: string, maxChars: number): string {
+  if (content.length <= maxChars) return content;
+
+  const halfLimit = Math.floor(maxChars / 2);
+  const start = content.slice(0, halfLimit);
+  const end = content.slice(-halfLimit);
+
+  return `${start}\n\n[... middle truncated ...]\n\n${end}`;
+}
+
+interface OpenRouterResponse {
+  choices?: Array<{
+    message?: {
+      content?: string;
+    };
+  }>;
+  error?: {
+    message?: string;
+  };
+}
+
+/**
+ * Generate a title for a transcript using OpenRouter.
+ *
+ * @param markdownContent - The full markdown transcript
+ * @returns Generated title, or undefined if generation fails/skipped
+ */
+export async function generateTitle(
+  markdownContent: string,
+): Promise<string | undefined> {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+
+  if (!apiKey) {
+    // Silently skip - no API key means user doesn't want title generation
+    return undefined;
+  }
+
+  const truncated = truncateMiddle(markdownContent, MAX_CHARS);
+
+  const prompt = `Generate a concise title (5-10 words) for this AI coding session transcript. The title should capture the main task or topic discussed.
+
+Reply with just the title, no quotes, no punctuation at the end, no explanation.
+
+Transcript:
+${truncated}`;
+
+  try {
+    const response = await fetch(OPENROUTER_API_URL, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        "HTTP-Referer": "https://github.com/arcreflex/agent-transcripts",
+        "X-Title": "agent-transcripts",
+      },
+      body: JSON.stringify({
+        model: MODEL,
+        messages: [{ role: "user", content: prompt }],
+        max_tokens: 50,
+        temperature: 0.3,
+      }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      console.error(
+        `Warning: OpenRouter API error (${response.status}): ${text.slice(0, 200)}`,
+      );
+      return undefined;
+    }
+
+    const data = (await response.json()) as OpenRouterResponse;
+
+    if (data.error) {
+      console.error(
+        `Warning: OpenRouter error: ${data.error.message || "Unknown error"}`,
+      );
+      return undefined;
+    }
+
+    const title = data.choices?.[0]?.message?.content?.trim();
+
+    if (!title) {
+      console.error("Warning: OpenRouter returned empty title");
+      return undefined;
+    }
+
+    // Clean up: remove quotes if present, trim trailing punctuation
+    return title
+      .replace(/^["']|["']$/g, "")
+      .replace(/[.!?]+$/, "")
+      .trim();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Warning: OpenRouter request failed: ${message}`);
+    return undefined;
+  }
+}

package/src/utils/provenance.ts

@@ -6,7 +6,6 @@
  */
 
 import { join, resolve } from "path";
-import { existsSync } from "fs";
 import { rename, unlink } from "fs/promises";
 
 const INDEX_FILENAME = "transcripts.json";
@@ -17,10 +16,15 @@ const INDEX_FILENAME = "transcripts.json";
 
 export interface TranscriptEntry {
   source: string; // absolute path to source
-  sourceMtime: number; // ms since epoch
   sessionId: string; // full session ID from source filename
   segmentIndex?: number; // for multi-transcript sources (1-indexed)
   syncedAt: string; // ISO timestamp
+  firstUserMessage: string; // first user message content (for display)
+  title?: string; // copied from cache for index.html convenience
+  messageCount: number;
+  startTime: string; // ISO timestamp
+  endTime: string; // ISO timestamp
+  cwd?: string;
 }
 
 export interface TranscriptsIndex {
@@ -120,45 +124,6 @@ export function getOutputsForSource(
   return outputs;
 }
 
-/**
- * Check if outputs for a source are stale.
- * Returns true if:
- * - No outputs exist for this source
- * - Output count doesn't match expected
- * - Any output file is missing from disk
- * - Source mtime is newer than recorded mtime
- */
-export function isStale(
-  index: TranscriptsIndex,
-  sourcePath: string,
-  sourceMtime: number,
-  expectedCount: number,
-  outputDir: string,
-): boolean {
-  const outputs = getOutputsForSource(index, sourcePath);
-
-  if (outputs.length !== expectedCount) {
-    return true;
-  }
-
-  // Check if outputs actually exist on disk
-  for (const filename of outputs) {
-    if (!existsSync(join(outputDir, filename))) {
-      return true;
-    }
-  }
-
-  // Check if source has been modified since last sync
-  for (const filename of outputs) {
-    const entry = index.entries[filename];
-    if (entry && entry.sourceMtime < sourceMtime) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
 /**
  * Set or update an entry in the index.
  * outputPath should be relative to the output directory.
@@ -226,3 +191,22 @@ export async function deleteOutputFiles(
     }
   }
 }
+
+// ============================================================================
+// Transcript Metadata Extraction
+// ============================================================================
+
+import type { Transcript } from "../types.ts";
+
+/**
+ * Extract the first user message from a transcript.
+ * Returns empty string if no user message found.
+ */
+export function extractFirstUserMessage(transcript: Transcript): string {
+  for (const msg of transcript.messages) {
+    if (msg.type === "user") {
+      return msg.content;
+    }
+  }
+  return "";
+}

package/src/utils/tree.ts

@@ -0,0 +1,116 @@
+/**
+ * Tree/branch navigation utilities for transcript messages.
+ */
+
+import type { Message } from "../types.ts";
+
+export interface MessageTree {
+  bySourceRef: Map<string, Message[]>;
+  children: Map<string, Set<string>>;
+  parents: Map<string, string>;
+  roots: string[];
+}
+
+/**
+ * Build tree structure from messages.
+ * Returns maps for navigation and the messages grouped by sourceRef.
+ */
+export function buildTree(messages: Message[]): MessageTree {
+  const bySourceRef = new Map<string, Message[]>();
+  for (const msg of messages) {
+    const existing = bySourceRef.get(msg.sourceRef) || [];
+    existing.push(msg);
+    bySourceRef.set(msg.sourceRef, existing);
+  }
+
+  const children = new Map<string, Set<string>>();
+  const parents = new Map<string, string>();
+
+  for (const msg of messages) {
+    if (msg.parentMessageRef && bySourceRef.has(msg.parentMessageRef)) {
+      parents.set(msg.sourceRef, msg.parentMessageRef);
+      const existing = children.get(msg.parentMessageRef) || new Set();
+      existing.add(msg.sourceRef);
+      children.set(msg.parentMessageRef, existing);
+    }
+  }
+
+  const roots: string[] = [];
+  for (const sourceRef of bySourceRef.keys()) {
+    if (!parents.has(sourceRef)) {
+      roots.push(sourceRef);
+    }
+  }
+
+  return { bySourceRef, children, parents, roots };
+}
+
+/**
+ * Find the latest leaf in the tree (for primary branch).
+ */
+export function findLatestLeaf(
+  bySourceRef: Map<string, Message[]>,
+  children: Map<string, Set<string>>,
+): string | undefined {
+  let latestLeaf: string | undefined;
+  let latestTime = 0;
+
+  for (const sourceRef of bySourceRef.keys()) {
+    const childSet = children.get(sourceRef);
+    if (!childSet || childSet.size === 0) {
+      const msgs = bySourceRef.get(sourceRef);
+      if (msgs && msgs.length > 0) {
+        const time = new Date(msgs[0].timestamp).getTime();
+        if (time > latestTime) {
+          latestTime = time;
+          latestLeaf = sourceRef;
+        }
+      }
+    }
+  }
+
+  return latestLeaf;
+}
+
+/**
+ * Trace path from root to target.
+ */
+export function tracePath(
+  target: string,
+  parents: Map<string, string>,
+): string[] {
+  const path: string[] = [];
+  let current: string | undefined = target;
+
+  while (current) {
+    path.unshift(current);
+    current = parents.get(current);
+  }
+
+  return path;
+}
+
+/**
+ * Get first line of message content for branch reference display.
+ */
+export function getFirstLine(msg: Message): string {
+  let text: string;
+  switch (msg.type) {
+    case "user":
+    case "assistant":
+    case "system":
+    case "error":
+      text = msg.content;
+      break;
+    case "tool_calls":
+      text = msg.calls.map((c) => c.name).join(", ");
+      break;
+    default:
+      text = "";
+  }
+  const firstLine = text.split("\n")[0].trim();
+  const maxLen = 60;
+  return firstLine.length > maxLen
+    ? firstLine.slice(0, maxLen) + "..."
+    : firstLine;
+}

package/test/fixtures/claude/non-message-parents.input.jsonl

@@ -0,0 +1,9 @@
+{"type": "user", "uuid": "msg-1", "message": {"role": "user", "content": "First message"}, "timestamp": "2024-01-15T10:00:00Z"}
+{"type": "assistant", "uuid": "msg-2", "parentUuid": "msg-1", "message": {"role": "assistant", "content": [{"type": "text", "text": "First response"}]}, "timestamp": "2024-01-15T10:00:05Z"}
+{"type": "progress", "uuid": "progress-1", "parentUuid": "msg-2", "content": "Processing...", "timestamp": "2024-01-15T10:00:10Z"}
+{"type": "user", "uuid": "msg-3", "parentUuid": "progress-1", "message": {"role": "user", "content": "Second message (parent is progress record)"}, "timestamp": "2024-01-15T10:00:15Z"}
+{"type": "assistant", "uuid": "msg-4", "parentUuid": "msg-3", "message": {"role": "assistant", "content": [{"type": "text", "text": "Second response"}]}, "timestamp": "2024-01-15T10:00:20Z"}
+{"type": "progress", "uuid": "progress-2", "parentUuid": "msg-4", "content": "More processing...", "timestamp": "2024-01-15T10:00:25Z"}
+{"type": "progress", "uuid": "progress-3", "parentUuid": "progress-2", "content": "Nested progress...", "timestamp": "2024-01-15T10:00:26Z"}
+{"type": "user", "uuid": "msg-5", "parentUuid": "progress-3", "message": {"role": "user", "content": "Third message (parent is nested progress)"}, "timestamp": "2024-01-15T10:00:30Z"}
+{"type": "assistant", "uuid": "msg-6", "parentUuid": "msg-5", "message": {"role": "assistant", "content": [{"type": "text", "text": "Third response"}]}, "timestamp": "2024-01-15T10:00:35Z"}

package/test/fixtures/claude/non-message-parents.output.md

@@ -0,0 +1,30 @@
+# Transcript
+
+**Source**: `test/fixtures/claude/non-message-parents.input.jsonl`
+**Adapter**: claude-code
+
+---
+
+## User
+
+First message
+
+## Assistant
+
+First response
+
+## User
+
+Second message (parent is progress record)
+
+## Assistant
+
+Second response
+
+## User
+
+Third message (parent is nested progress)
+
+## Assistant
+
+Third response