@arcreflex/agent-transcripts 0.1.1

package/src/adapters/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Adapter registry with path-based detection.
+ */
+
+import type { Adapter } from "../types.ts";
+import { claudeCodeAdapter } from "./claude-code.ts";
+
+const adapters: Record<string, Adapter> = {
+  "claude-code": claudeCodeAdapter,
+};
+
+/**
+ * Detection rules: path pattern → adapter name
+ */
+const detectionRules: Array<{ pattern: RegExp; adapter: string }> = [
+  // Match .claude/ or /claude/ in path
+  { pattern: /[./]claude[/\\]/, adapter: "claude-code" },
+];
+
+/**
+ * Detect adapter from file path.
+ * Returns adapter name if detected, undefined if not.
+ */
+export function detectAdapter(filePath: string): string | undefined {
+  for (const rule of detectionRules) {
+    if (rule.pattern.test(filePath)) {
+      return rule.adapter;
+    }
+  }
+  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);
+}

package/src/cli.ts

@@ -0,0 +1,114 @@
+/**
+ * CLI entry point using cmd-ts.
+ */
+
+import {
+  command,
+  subcommands,
+  run,
+  string,
+  option,
+  optional,
+  positional,
+} from "cmd-ts";
+import { parse } from "./parse.ts";
+import { render } from "./render.ts";
+
+// Shared options
+const inputArg = positional({
+  type: optional(string),
+  displayName: "file",
+  description: "Input file (reads from stdin if not provided)",
+});
+
+const outputOpt = option({
+  type: optional(string),
+  long: "output",
+  short: "o",
+  description: "Output path (defaults to current directory)",
+});
+
+const adapterOpt = option({
+  type: optional(string),
+  long: "adapter",
+  description:
+    "Source format adapter (auto-detected from path if not specified)",
+});
+
+const headOpt = option({
+  type: optional(string),
+  long: "head",
+  description: "Render branch ending at this message ID (default: latest)",
+});
+
+// Parse subcommand
+const parseCmd = command({
+  name: "parse",
+  description: "Parse source format to intermediate JSON",
+  args: {
+    input: inputArg,
+    output: outputOpt,
+    adapter: adapterOpt,
+  },
+  async handler({ input, output, adapter }) {
+    await parse({ input, output, adapter });
+  },
+});
+
+// Render subcommand
+const renderCmd = command({
+  name: "render",
+  description: "Render intermediate JSON to markdown",
+  args: {
+    input: inputArg,
+    output: outputOpt,
+    head: headOpt,
+  },
+  async handler({ input, output, head }) {
+    await render({ input, output, head });
+  },
+});
+
+// Default command: full pipeline (parse → render)
+const defaultCmd = command({
+  name: "agent-transcripts",
+  description: "Transform agent session files to readable transcripts",
+  args: {
+    input: inputArg,
+    output: outputOpt,
+    adapter: adapterOpt,
+    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 });
+
+    // 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 });
+    }
+  },
+});
+
+// Main CLI with subcommands
+const cli = subcommands({
+  name: "agent-transcripts",
+  description: "Transform agent session files to readable transcripts",
+  cmds: {
+    parse: parseCmd,
+    render: renderCmd,
+  },
+  // Default command when no subcommand is specified
+});
+
+// Run CLI
+const args = process.argv.slice(2);
+
+// Check if first arg is a subcommand
+if (args[0] === "parse" || args[0] === "render") {
+  run(cli, args);
+} else {
+  // Run default command for full pipeline
+  run(defaultCmd, args);
+}

package/src/parse.ts

@@ -0,0 +1,127 @@
+/**
+ * Parse command: source format → intermediate JSON
+ */
+
+import { basename, dirname, join } from "path";
+import { mkdir } from "fs/promises";
+import type { Transcript } from "./types.ts";
+import { detectAdapter, getAdapter, listAdapters } from "./adapters/index.ts";
+
+export interface ParseOptions {
+  input?: string; // file path, undefined for stdin
+  output?: string; // output path/dir
+  adapter?: string; // explicit adapter name
+}
+
+/**
+ * Read input content from file or stdin.
+ */
+async function readInput(
+  input?: string,
+): Promise<{ content: string; path: string }> {
+  if (input) {
+    const content = await Bun.file(input).text();
+    return { content, path: input };
+  }
+
+  // Read from stdin
+  const chunks: string[] = [];
+  const reader = Bun.stdin.stream().getReader();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(new TextDecoder().decode(value));
+  }
+
+  return { content: chunks.join(""), path: "<stdin>" };
+}
+
+/**
+ * Determine output file paths for transcripts.
+ */
+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?$/, "");
+  }
+
+  // Determine output directory
+  let outputDir: string;
+  if (outputOption) {
+    // If output looks like a file (has extension), use its directory
+    if (outputOption.match(/\.\w+$/)) {
+      outputDir = dirname(outputOption);
+      baseName = basename(outputOption).replace(/\.\w+$/, "");
+    } else {
+      outputDir = outputOption;
+    }
+  } else {
+    outputDir = process.cwd();
+  }
+
+  // Generate paths
+  if (transcripts.length === 1) {
+    return [join(outputDir, `${baseName}.json`)];
+  }
+
+  return transcripts.map((_, i) =>
+    join(outputDir, `${baseName}_${i + 1}.json`),
+  );
+}
+
+export interface ParseResult {
+  transcripts: Transcript[];
+  outputPaths: string[];
+}
+
+/**
+ * Parse source file(s) to intermediate JSON.
+ */
+export async function parse(options: ParseOptions): Promise<ParseResult> {
+  const { content, path: inputPath } = await readInput(options.input);
+
+  // Determine adapter
+  let adapterName = options.adapter;
+  if (!adapterName && options.input) {
+    adapterName = detectAdapter(options.input);
+  }
+
+  if (!adapterName) {
+    throw new Error(
+      `Could not detect adapter for input. Use --adapter to specify. Available: ${listAdapters().join(", ")}`,
+    );
+  }
+
+  const adapter = getAdapter(adapterName);
+  if (!adapter) {
+    throw new Error(
+      `Unknown adapter: ${adapterName}. Available: ${listAdapters().join(", ")}`,
+    );
+  }
+
+  // Parse
+  const transcripts = adapter.parse(content, inputPath);
+
+  // Write output files
+  const outputPaths = getOutputPaths(transcripts, inputPath, options.output);
+
+  for (let i = 0; i < transcripts.length; i++) {
+    const json = JSON.stringify(transcripts[i], null, 2);
+    // Ensure directory exists
+    const dir = dirname(outputPaths[i]);
+    await mkdir(dir, { recursive: true });
+    await Bun.write(outputPaths[i], json);
+    console.error(`Wrote: ${outputPaths[i]}`);
+  }
+
+  return { transcripts, outputPaths };
+}

package/src/render.ts

@@ -0,0 +1,354 @@
+/**
+ * Render command: intermediate JSON → markdown
+ */
+
+import { basename, dirname, join } from "path";
+import { mkdir } from "fs/promises";
+import type { Transcript, Message, ToolCall } from "./types.ts";
+
+export interface RenderOptions {
+  input?: string; // file path, undefined for stdin
+  output?: string; // output path
+  head?: string; // render branch ending at this message ID
+}
+
+/**
+ * Read transcript from file or stdin.
+ */
+async function readTranscript(
+  input?: string,
+): Promise<{ transcript: Transcript; path: string }> {
+  let content: string;
+  let path: string;
+
+  if (input) {
+    content = await Bun.file(input).text();
+    path = input;
+  } else {
+    const chunks: string[] = [];
+    const reader = Bun.stdin.stream().getReader();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(new TextDecoder().decode(value));
+    }
+
+    content = chunks.join("");
+    path = "<stdin>";
+  }
+
+  const transcript = JSON.parse(content) as Transcript;
+  return { transcript, path };
+}
+
+/**
+ * Format a single tool call.
+ */
+function formatToolCall(call: ToolCall): string {
+  if (call.summary) {
+    return `${call.name} \`${call.summary}\``;
+  }
+  return call.name;
+}
+
+/**
+ * Format tool calls group.
+ */
+function formatToolCalls(calls: ToolCall[]): string {
+  if (calls.length === 1) {
+    return `**Tool**: ${formatToolCall(calls[0])}`;
+  }
+  return `**Tools**:\n${calls.map((c) => `- ${formatToolCall(c)}`).join("\n")}`;
+}
+
+/**
+ * Render a message to markdown.
+ */
+function renderMessage(msg: Message): string {
+  switch (msg.type) {
+    case "user":
+      return `## User\n\n${msg.content}`;
+
+    case "assistant": {
+      const parts: string[] = ["## Assistant"];
+
+      if (msg.thinking) {
+        parts.push(`
+<details>
+<summary>Thinking...</summary>
+
+${msg.thinking}
+</details>`);
+      }
+
+      if (msg.content.trim()) {
+        parts.push(msg.content);
+      }
+
+      return parts.join("\n\n");
+    }
+
+    case "system":
+      return `## System\n\n\`\`\`\n${msg.content}\n\`\`\``;
+
+    case "tool_calls":
+      return formatToolCalls(msg.calls);
+
+    case "error":
+      return `## Error\n\n\`\`\`\n${msg.content}\n\`\`\``;
+
+    default:
+      return "";
+  }
+}
+
+/**
+ * Get first line of message content for branch reference.
+ */
+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;
+}
+
+/**
+ * Build tree structure from messages.
+ * Returns maps for navigation and the messages grouped by sourceRef.
+ */
+function buildTree(messages: Message[]): {
+  bySourceRef: Map<string, Message[]>;
+  children: Map<string, Set<string>>;
+  parents: Map<string, string>;
+  roots: string[];
+} {
+  // Group messages by sourceRef
+  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);
+  }
+
+  // Build parent → children map (at sourceRef level)
+  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);
+    }
+  }
+
+  // Find roots (no parent in our set)
+  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).
+ */
+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) {
+      // It's a leaf
+      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.
+ */
+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;
+}
+
+/**
+ * Render transcript to markdown with branch awareness.
+ */
+function renderTranscript(transcript: Transcript, head?: string): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push("# Transcript");
+  lines.push("");
+  lines.push(`**Source**: \`${transcript.source.file}\``);
+  lines.push(`**Adapter**: ${transcript.source.adapter}`);
+
+  // Warnings
+  if (transcript.metadata.warnings.length > 0) {
+    lines.push("");
+    lines.push("**Warnings**:");
+    for (const w of transcript.metadata.warnings) {
+      lines.push(`- ${w.type}: ${w.detail}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("---");
+
+  // Handle empty transcripts
+  if (transcript.messages.length === 0) {
+    return lines.join("\n");
+  }
+
+  // Build tree
+  const { bySourceRef, children, parents, roots } = buildTree(
+    transcript.messages,
+  );
+
+  // Determine target (head or latest leaf)
+  let target: string | undefined;
+  if (head) {
+    if (!bySourceRef.has(head)) {
+      lines.push("");
+      lines.push(`**Error**: Message ID \`${head}\` not found`);
+      return lines.join("\n");
+    }
+    target = head;
+  } else {
+    target = findLatestLeaf(bySourceRef, children);
+  }
+
+  if (!target) {
+    // Fallback: just render all messages in order (shouldn't happen normally)
+    for (const msg of transcript.messages) {
+      const rendered = renderMessage(msg);
+      if (rendered) {
+        lines.push("");
+        lines.push(rendered);
+      }
+    }
+    return lines.join("\n");
+  }
+
+  // Trace path from root to target
+  const path = tracePath(target, parents);
+  const pathSet = new Set(path);
+
+  // Render messages along the path
+  for (const sourceRef of path) {
+    const msgs = bySourceRef.get(sourceRef);
+    if (!msgs) continue;
+
+    // Render all messages from this source
+    for (const msg of msgs) {
+      const rendered = renderMessage(msg);
+      if (rendered) {
+        lines.push("");
+        lines.push(rendered);
+      }
+    }
+
+    // Check for other branches at this point (only if not using explicit --head)
+    if (!head) {
+      const childSet = children.get(sourceRef);
+      if (childSet && childSet.size > 1) {
+        const otherBranches = [...childSet].filter((c) => !pathSet.has(c));
+        if (otherBranches.length > 0) {
+          lines.push("");
+          lines.push("> **Other branches**:");
+          for (const branchRef of otherBranches) {
+            const branchMsgs = bySourceRef.get(branchRef);
+            if (branchMsgs && branchMsgs.length > 0) {
+              const firstLine = getFirstLine(branchMsgs[0]);
+              lines.push(`> - \`${branchRef}\` "${firstLine}"`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Determine output path for markdown.
+ */
+function getOutputPath(inputPath: string, outputOption?: string): string {
+  if (outputOption) {
+    // If it has an extension, use as-is
+    if (outputOption.match(/\.\w+$/)) {
+      return outputOption;
+    }
+    // Treat as directory
+    const base =
+      inputPath === "<stdin>"
+        ? "transcript"
+        : basename(inputPath).replace(/\.json$/, "");
+    return join(outputOption, `${base}.md`);
+  }
+
+  // Default: same name in cwd
+  const base =
+    inputPath === "<stdin>"
+      ? "transcript"
+      : basename(inputPath).replace(/\.json$/, "");
+  return join(process.cwd(), `${base}.md`);
+}
+
+/**
+ * Render intermediate JSON to markdown.
+ */
+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}`);
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Intermediate transcript format for agent-transcripts.
+ * Designed to be adapter-agnostic - any agent harness can produce this format.
+ */
+
+export interface Transcript {
+  source: {
+    file: string;
+    adapter: string;
+  };
+  metadata: {
+    warnings: Warning[];
+  };
+  messages: Message[];
+}
+
+export interface Warning {
+  type: string;
+  detail: string;
+  sourceRef?: string;
+}
+
+export type Message =
+  | UserMessage
+  | AssistantMessage
+  | SystemMessage
+  | ToolCallGroup
+  | ErrorMessage;
+
+interface BaseMessage {
+  sourceRef: string;
+  timestamp: string;
+  parentMessageRef?: string; // UUID of parent message (for tree reconstruction)
+}
+
+export interface UserMessage extends BaseMessage {
+  type: "user";
+  content: string;
+}
+
+export interface AssistantMessage extends BaseMessage {
+  type: "assistant";
+  content: string;
+  thinking?: string;
+}
+
+export interface SystemMessage extends BaseMessage {
+  type: "system";
+  content: string;
+}
+
+export interface ToolCallGroup extends BaseMessage {
+  type: "tool_calls";
+  calls: ToolCall[];
+}
+
+export interface ToolCall {
+  name: string;
+  summary: string;
+  error?: string;
+}
+
+export interface ErrorMessage extends BaseMessage {
+  type: "error";
+  content: string;
+}
+
+/**
+ * Adapter interface - each source format implements this.
+ */
+export interface Adapter {
+  name: string;
+  /** Parse source content into one or more transcripts (split by conversation) */
+  parse(content: string, sourcePath: string): Transcript[];
+}