@arcreflex/agent-transcripts 0.1.1 → 0.1.3

package/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - run: bun install
+
+      - run: bun run check
+
+      - run: bun test
+
+      - run: npm publish --provenance --access public

package/package.json

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

package/src/adapters/claude-code.ts

@@ -199,6 +199,26 @@ function isToolResultOnly(content: string | ContentBlock[]): boolean {
   return hasToolResult && !hasText;
 }
 
+/**
+ * Resolve a parent reference through any skipped messages.
+ * When messages are skipped (e.g., tool-result-only user messages),
+ * we redirect parent references to the skipped message's parent.
+ */
+function resolveParent(
+  parentUuid: string | null | undefined,
+  skippedParents: Map<string, string | undefined>,
+): string | undefined {
+  if (!parentUuid) return undefined;
+
+  // Follow the chain through any skipped messages
+  let current: string | undefined = parentUuid;
+  while (current && skippedParents.has(current)) {
+    current = skippedParents.get(current);
+  }
+
+  return current;
+}
+
 /**
  * Transform a conversation into our intermediate format.
  */
@@ -208,11 +228,45 @@ function transformConversation(
   warnings: Warning[],
 ): Transcript {
   const messages: Message[] = [];
+  // Track skipped message UUIDs → their parent UUIDs for chain repair
+  const skippedParents = new Map<string, string | undefined>();
+
+  // First pass: identify which messages will be skipped
+  for (const rec of records) {
+    if (!rec.uuid) continue;
+
+    let willSkip = false;
+
+    if (rec.type === "user" && rec.message) {
+      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) {
+      const text = extractText(rec.message.content);
+      const thinking = extractThinking(rec.message.content);
+      const toolCalls = extractToolCalls(rec.message.content);
+      // Only skip if no text, no thinking, AND no tool calls
+      if (!text.trim() && !thinking && toolCalls.length === 0) {
+        willSkip = true;
+      }
+    } else if (rec.type === "system") {
+      const text = rec.content || "";
+      if (!text.trim()) willSkip = true;
+    }
+
+    if (willSkip) {
+      skippedParents.set(rec.uuid, rec.parentUuid || undefined);
+    }
+  }
 
+  // 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 = rec.parentUuid || undefined;
+    const parentMessageRef = resolveParent(rec.parentUuid, skippedParents);
 
     if (rec.type === "user" && rec.message) {
       // Skip tool-result-only user messages (they're just tool responses)

package/src/cli.ts

@@ -11,8 +11,11 @@ import {
   optional,
   positional,
 } from "cmd-ts";
-import { parse } from "./parse.ts";
-import { render } from "./render.ts";
+import { parse, parseToTranscripts } from "./parse.ts";
+import { render, renderTranscript } from "./render.ts";
+
+// Read OpenRouter API key from environment for LLM-based slug generation
+const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
 
 // Shared options
 const inputArg = positional({
@@ -25,7 +28,7 @@ const outputOpt = option({
   type: optional(string),
   long: "output",
   short: "o",
-  description: "Output path (defaults to current directory)",
+  description: "Output path (prints to stdout if not specified)",
 });
 
 const adapterOpt = option({
@@ -51,7 +54,19 @@ const parseCmd = command({
     adapter: adapterOpt,
   },
   async handler({ input, output, adapter }) {
-    await parse({ input, output, adapter });
+    const naming = OPENROUTER_API_KEY
+      ? { apiKey: OPENROUTER_API_KEY }
+      : undefined;
+
+    if (output) {
+      await parse({ input, output, adapter, naming });
+    } else {
+      // Print JSONL to stdout (one transcript per line)
+      const { transcripts } = await parseToTranscripts({ input, adapter });
+      for (const transcript of transcripts) {
+        console.log(JSON.stringify(transcript));
+      }
+    }
   },
 });
 
@@ -80,13 +95,24 @@ const defaultCmd = command({
     head: headOpt,
   },
   async handler({ input, output, adapter, head }) {
-    // Parse to JSON - parse() determines output paths and returns them
-    const { outputPaths } = await parse({ input, output, adapter });
+    const naming = OPENROUTER_API_KEY
+      ? { apiKey: OPENROUTER_API_KEY }
+      : undefined;
 
-    // Render each transcript (JSON path → markdown path)
-    for (const jsonPath of outputPaths) {
-      const mdPath = jsonPath.replace(/\.json$/, ".md");
-      await render({ input: jsonPath, output: mdPath, head });
+    if (output) {
+      // Write intermediate JSON and markdown files
+      const { outputPaths } = await parse({ input, output, adapter, naming });
+      for (const jsonPath of outputPaths) {
+        const mdPath = jsonPath.replace(/\.json$/, ".md");
+        await render({ input: jsonPath, output: mdPath, head });
+      }
+    } else {
+      // Stream to stdout - no intermediate files
+      const { transcripts } = await parseToTranscripts({ input, adapter });
+      for (let i = 0; i < transcripts.length; i++) {
+        if (i > 0) console.log(); // blank line between transcripts
+        console.log(renderTranscript(transcripts[i], head));
+      }
     }
   },
 });

package/src/parse.ts

@@ -2,15 +2,17 @@
  * Parse command: source format → intermediate JSON
  */
 
-import { basename, dirname, join } from "path";
+import { dirname, join } from "path";
 import { mkdir } from "fs/promises";
 import type { Transcript } from "./types.ts";
 import { detectAdapter, getAdapter, listAdapters } from "./adapters/index.ts";
+import { generateOutputName, type NamingOptions } from "./utils/naming.ts";
 
 export interface ParseOptions {
   input?: string; // file path, undefined for stdin
   output?: string; // output path/dir
   adapter?: string; // explicit adapter name
+  naming?: NamingOptions; // options for output file naming
 }
 
 /**
@@ -40,27 +42,24 @@ async function readInput(
 /**
  * Determine output file paths for transcripts.
  */
-function getOutputPaths(
+async function getOutputPaths(
   transcripts: Transcript[],
   inputPath: string,
   outputOption?: string,
-): string[] {
-  // Determine base name
-  let baseName: string;
-  if (inputPath === "<stdin>") {
-    baseName = "transcript";
-  } else {
-    const name = basename(inputPath);
-    baseName = name.replace(/\.jsonl?$/, "");
-  }
-
+  namingOptions?: NamingOptions,
+): Promise<string[]> {
   // Determine output directory
   let outputDir: string;
+  let explicitBaseName: string | undefined;
+
   if (outputOption) {
-    // If output looks like a file (has extension), use its directory
+    // If output looks like a file (has extension), use its directory and name
     if (outputOption.match(/\.\w+$/)) {
       outputDir = dirname(outputOption);
-      baseName = basename(outputOption).replace(/\.\w+$/, "");
+      explicitBaseName = outputOption
+        .split("/")
+        .pop()!
+        .replace(/\.\w+$/, "");
     } else {
       outputDir = outputOption;
     }
@@ -68,25 +67,50 @@ function getOutputPaths(
     outputDir = process.cwd();
   }
 
-  // Generate paths
-  if (transcripts.length === 1) {
-    return [join(outputDir, `${baseName}.json`)];
+  // Generate paths with descriptive names
+  const paths: string[] = [];
+
+  for (let i = 0; i < transcripts.length; i++) {
+    let baseName: string;
+
+    if (explicitBaseName) {
+      // User provided explicit filename
+      baseName = explicitBaseName;
+    } else {
+      // Generate descriptive name
+      baseName = await generateOutputName(
+        transcripts[i],
+        inputPath,
+        namingOptions || {},
+      );
+    }
+
+    // Add suffix for multiple transcripts
+    if (transcripts.length > 1) {
+      baseName = `${baseName}_${i + 1}`;
+    }
+
+    paths.push(join(outputDir, `${baseName}.json`));
   }
 
-  return transcripts.map((_, i) =>
-    join(outputDir, `${baseName}_${i + 1}.json`),
-  );
+  return paths;
 }
 
 export interface ParseResult {
   transcripts: Transcript[];
+  inputPath: string;
+}
+
+export interface ParseAndWriteResult extends ParseResult {
   outputPaths: string[];
 }
 
 /**
- * Parse source file(s) to intermediate JSON.
+ * Parse source file(s) to transcripts (no file I/O beyond reading input).
  */
-export async function parse(options: ParseOptions): Promise<ParseResult> {
+export async function parseToTranscripts(
+  options: ParseOptions,
+): Promise<ParseResult> {
   const { content, path: inputPath } = await readInput(options.input);
 
   // Determine adapter
@@ -108,11 +132,25 @@ export async function parse(options: ParseOptions): Promise<ParseResult> {
     );
   }
 
-  // Parse
   const transcripts = adapter.parse(content, inputPath);
+  return { transcripts, inputPath };
+}
+
+/**
+ * Parse source file(s) to intermediate JSON and write to files.
+ */
+export async function parse(
+  options: ParseOptions,
+): Promise<ParseAndWriteResult> {
+  const { transcripts, inputPath } = await parseToTranscripts(options);
 
   // Write output files
-  const outputPaths = getOutputPaths(transcripts, inputPath, options.output);
+  const outputPaths = await getOutputPaths(
+    transcripts,
+    inputPath,
+    options.output,
+    options.naming,
+  );
 
   for (let i = 0; i < transcripts.length; i++) {
     const json = JSON.stringify(transcripts[i], null, 2);
@@ -123,5 +161,5 @@ export async function parse(options: ParseOptions): Promise<ParseResult> {
     console.error(`Wrote: ${outputPaths[i]}`);
   }
 
-  return { transcripts, outputPaths };
+  return { transcripts, inputPath, outputPaths };
 }

package/src/render.ts

@@ -216,7 +216,10 @@ function tracePath(target: string, parents: Map<string, string>): string[] {
 /**
  * Render transcript to markdown with branch awareness.
  */
-function renderTranscript(transcript: Transcript, head?: string): string {
+export function renderTranscript(
+  transcript: Transcript,
+  head?: string,
+): string {
   const lines: string[] = [];
 
   // Header
@@ -345,10 +348,15 @@ export async function render(options: RenderOptions): Promise<void> {
   const { transcript, path: inputPath } = await readTranscript(options.input);
 
   const markdown = renderTranscript(transcript, options.head);
-  const outputPath = getOutputPath(inputPath, options.output);
 
-  // Ensure directory exists
-  await mkdir(dirname(outputPath), { recursive: true });
-  await Bun.write(outputPath, markdown);
-  console.error(`Wrote: ${outputPath}`);
+  if (options.output) {
+    const outputPath = getOutputPath(inputPath, options.output);
+    // Ensure directory exists
+    await mkdir(dirname(outputPath), { recursive: true });
+    await Bun.write(outputPath, markdown);
+    console.error(`Wrote: ${outputPath}`);
+  } else {
+    // Default: print to stdout
+    console.log(markdown);
+  }
 }

package/src/utils/naming.ts

@@ -0,0 +1,173 @@
+/**
+ * Output file naming utilities.
+ *
+ * Generates descriptive filenames for transcripts:
+ * - With OpenRouter API key: yyyy-mm-dd-{llm-generated-slug}.{ext}
+ * - Without: yyyy-mm-dd-{input-filename-prefix}.{ext}
+ */
+
+import type { Transcript, UserMessage } from "../types.ts";
+import { basename } from "path";
+
+export interface NamingOptions {
+  apiKey?: string; // OpenRouter API key
+  model?: string; // Default: google/gemini-2.0-flash-001
+}
+
+const DEFAULT_MODEL = "google/gemini-2.0-flash-001";
+const SLUG_MAX_LENGTH = 40;
+
+/**
+ * Extract date from transcript's first message timestamp.
+ */
+function extractDate(transcript: Transcript): string {
+  const firstMessage = transcript.messages[0];
+  if (firstMessage?.timestamp) {
+    const date = new Date(firstMessage.timestamp);
+    if (!isNaN(date.getTime())) {
+      return date.toISOString().slice(0, 10); // yyyy-mm-dd
+    }
+  }
+  // Fallback to current date
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Extract context from transcript for LLM summarization.
+ * Uses first few user messages, truncated.
+ */
+function extractContext(transcript: Transcript): string {
+  const userMessages = transcript.messages.filter(
+    (m): m is UserMessage => m.type === "user",
+  );
+
+  const chunks: string[] = [];
+  let totalLength = 0;
+  const maxLength = 500;
+
+  for (const msg of userMessages.slice(0, 3)) {
+    const content = msg.content.slice(0, 200);
+    if (totalLength + content.length > maxLength) break;
+    chunks.push(content);
+    totalLength += content.length;
+  }
+
+  return chunks.join("\n\n");
+}
+
+/**
+ * Sanitize a string into a valid URL slug.
+ */
+function sanitizeSlug(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "") // remove special chars
+    .replace(/\s+/g, "-") // spaces to hyphens
+    .replace(/-+/g, "-") // collapse multiple hyphens
+    .replace(/^-|-$/g, "") // trim leading/trailing hyphens
+    .slice(0, SLUG_MAX_LENGTH);
+}
+
+/**
+ * Generate slug via OpenRouter API.
+ */
+async function generateSlugViaLLM(
+  context: string,
+  options: NamingOptions,
+): Promise<string | null> {
+  const { apiKey, model = DEFAULT_MODEL } = options;
+  if (!apiKey || !context.trim()) return null;
+
+  try {
+    const response = await fetch(
+      "https://openrouter.ai/api/v1/chat/completions",
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model,
+          messages: [
+            {
+              role: "user",
+              content: `Generate a 2-4 word URL slug (lowercase, hyphenated) summarizing this conversation topic. Reply with ONLY the slug, nothing else.\n\n${context}`,
+            },
+          ],
+          max_tokens: 20,
+        }),
+      },
+    );
+
+    if (!response.ok) {
+      console.error(
+        `OpenRouter API error: ${response.status} ${response.statusText}`,
+      );
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      choices?: Array<{ message?: { content?: string } }>;
+    };
+    const content = data.choices?.[0]?.message?.content?.trim();
+
+    if (!content) return null;
+
+    const slug = sanitizeSlug(content);
+    return slug || null;
+  } catch (error) {
+    console.error(
+      `OpenRouter API call failed: ${error instanceof Error ? error.message : error}`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Generate fallback slug from input filename.
+ */
+function generateFallbackSlug(inputPath: string): string {
+  return extractFileId(inputPath, 8) || "transcript";
+}
+
+/**
+ * Extract a short identifier from the input filename.
+ * Used as a suffix for traceability back to source.
+ */
+function extractFileId(inputPath: string, length = 6): string {
+  if (inputPath === "<stdin>") {
+    return "";
+  }
+
+  const name = basename(inputPath);
+  const base = name.replace(/\.jsonl?$/, "");
+  // Take first N chars, sanitize, and clean up any trailing hyphens
+  return sanitizeSlug(base.slice(0, length)).replace(/-+$/, "");
+}
+
+/**
+ * Generate output base name for a transcript.
+ * Returns string like "2024-01-15-implement-auth-flow-abc123"
+ */
+export async function generateOutputName(
+  transcript: Transcript,
+  inputPath: string,
+  options: NamingOptions = {},
+): Promise<string> {
+  const date = extractDate(transcript);
+  const fileId = extractFileId(inputPath);
+
+  // Try LLM-generated slug if API key available
+  if (options.apiKey) {
+    const context = extractContext(transcript);
+    const slug = await generateSlugViaLLM(context, options);
+    if (slug) {
+      return fileId ? `${date}-${slug}-${fileId}` : `${date}-${slug}`;
+    }
+  }
+
+  // Fallback to input filename prefix (no need for fileId suffix, it's already the slug)
+  const slug = generateFallbackSlug(inputPath);
+  return `${date}-${slug}`;
+}

package/test/fixtures/claude/skipped-message-chain.input.jsonl

@@ -0,0 +1,6 @@
+{"type": "user", "uuid": "msg-1", "message": {"role": "user", "content": "Read the config file"}, "timestamp": "2024-01-15T10:00:00Z"}
+{"type": "assistant", "uuid": "msg-2", "parentUuid": "msg-1", "message": {"role": "assistant", "content": [{"type": "text", "text": "I'll read the config file for you."}, {"type": "tool_use", "id": "tool-1", "name": "Read", "input": {"file_path": "/project/config.json"}}]}, "timestamp": "2024-01-15T10:00:02Z"}
+{"type": "user", "uuid": "msg-3", "parentUuid": "msg-2", "message": {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "tool-1", "content": "config contents here"}]}, "timestamp": "2024-01-15T10:00:03Z"}
+{"type": "assistant", "uuid": "msg-4", "parentUuid": "msg-3", "message": {"role": "assistant", "content": [{"type": "text", "text": "The config file contains your settings."}]}, "timestamp": "2024-01-15T10:00:05Z"}
+{"type": "user", "uuid": "msg-5", "parentUuid": "msg-4", "message": {"role": "user", "content": "Thanks!"}, "timestamp": "2024-01-15T10:00:10Z"}
+{"type": "assistant", "uuid": "msg-6", "parentUuid": "msg-5", "message": {"role": "assistant", "content": [{"type": "text", "text": "You're welcome!"}]}, "timestamp": "2024-01-15T10:00:12Z"}

package/test/fixtures/claude/skipped-message-chain.output.md

@@ -0,0 +1,28 @@
+# Transcript
+
+**Source**: `test/fixtures/claude/skipped-message-chain.input.jsonl`
+**Adapter**: claude-code
+
+---
+
+## User
+
+Read the config file
+
+## Assistant
+
+I'll read the config file for you.
+
+**Tool**: Read `/project/config.json`
+
+## Assistant
+
+The config file contains your settings.
+
+## User
+
+Thanks!
+
+## Assistant
+
+You're welcome!