transcript-viewer 0.1.0

data/lib/transcript_viewer/templates/tree_content.html.erb

@@ -0,0 +1,2 @@
+<% case entry[:type]
+when "toolPair" %><span class="tree-role-tool"><%= h(tool_pair_text(entry)) %></span><% when "message" %><%= render_message_tree_content(entry[:message]) %><% when "reasoningChange" %><span class="tree-muted">[reasoning: <%= h(presence(entry[:reasoning]) || "unknown") %>]</span><% when "modelChange" %><span class="tree-muted">[model: <%= h(presence(entry[:modelId]) || "unknown") %>]</span><% when "compaction" %><span class="tree-compaction">[compaction: <%= (entry[:tokensBefore].to_i / 1000.0).round %>k tokens]</span> <%= h(truncate_tree_text(entry[:summary])) %><% when "forkBoundary" %><span class="tree-fork-boundary">[fork: new session starts here]</span><% else %><span class="tree-muted">[<%= h(entry[:type]) %>]</span><% end %>

data/lib/transcript_viewer/templates/tree_node.html.erb

@@ -0,0 +1,4 @@
+<%
+classes = ["tree-node"]
+classes << "active" if entry[:id] == @view[:leaf_id]
+%><a class="<%= h(classes.join(" ")) %>" href="#<%= h(entry[:targetId] || entry[:id]) %>"><span class="tree-prefix"></span><span class="tree-marker">•</span><span class="tree-content"><%= render_tree_content(entry) %></span></a>

data/lib/transcript_viewer/tool_execution.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TranscriptViewer
+  class ToolExecution
+    attr_reader :call, :result_entry
+
+    def initialize(call:, result_entry: nil)
+      @call = call
+      @result_entry = result_entry
+    end
+
+    def id
+      call[:id]
+    end
+
+    def name
+      call[:name].to_s
+    end
+
+    def input
+      call[:arguments] || {}
+    end
+    alias arguments input
+
+    def result
+      result_entry&.dig(:message)
+    end
+
+    def result_content
+      Array(result&.dig(:content))
+    end
+
+    def result_text
+      result_content.filter_map { |block| block[:text] if block[:type] == "text" }.join("\n")
+    end
+
+    def result_json
+      JSON.parse(result_text)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def images
+      result_content.select { |block| block[:type] == "image" && present_value?(block[:data]) }
+    end
+
+    def pending?
+      result_entry.nil?
+    end
+
+    def error?
+      !pending? && !!result&.dig(:isError)
+    end
+
+    def success?
+      !pending? && !error?
+    end
+
+    def status
+      return :pending if pending?
+      return :error if error?
+
+      :success
+    end
+
+    private
+
+    def present_value?(value)
+      !value.nil? && (!value.respond_to?(:empty?) || !value.empty?)
+    end
+  end
+end

data/lib/transcript_viewer/tool_template_registry.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module TranscriptViewer
+  class ToolTemplateRegistry
+    include Enumerable
+
+    def initialize(templates = nil)
+      @templates = {}
+      merge!(templates) if templates
+    end
+
+    def register(tool_name, template_path)
+      name = normalize_name(tool_name)
+      path = File.expand_path(template_path.to_s)
+
+      raise ArgumentError, "Tool template does not exist: #{path}" unless File.file?(path)
+
+      @templates[name] = path
+      self
+    end
+
+    def unregister(tool_name)
+      @templates.delete(tool_name.to_s)
+      self
+    end
+
+    def resolve(tool_name)
+      @templates[tool_name.to_s]
+    end
+
+    def each(&block)
+      @templates.each(&block)
+    end
+
+    def merge(other)
+      self.class.new(self).merge!(other)
+    end
+
+    def merge!(other)
+      return self unless other
+
+      registrations = if other.is_a?(self.class)
+        other
+      elsif other.respond_to?(:each_pair)
+        other.each_pair
+      else
+        raise ArgumentError, "Tool templates must be a ToolTemplateRegistry or hash"
+      end
+
+      registrations.each { |tool_name, template_path| register(tool_name, template_path) }
+      self
+    end
+
+    def to_h
+      @templates.dup
+    end
+
+    private
+
+    def normalize_name(tool_name)
+      name = tool_name.to_s
+      raise ArgumentError, "Tool name cannot be empty" if name.empty?
+
+      name
+    end
+  end
+end

data/lib/transcript_viewer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TranscriptViewer
+  VERSION = "0.1.0"
+end

data/lib/transcript_viewer/view.rb

@@ -0,0 +1,475 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+require "time"
+
+require_relative "support"
+
+module TranscriptViewer
+  class View
+    DEFAULT_ASSET_DIR = File.expand_path("../../assets", __dir__)
+
+    def initialize(session_id:, events:, forked_transcript: false, ancestor_lookup: nil, export_href: nil, forked_transcript_href: nil, hide_forked_transcript_href: nil, asset_dir: nil)
+      @session_id = session_id
+      @events = events
+      @forked_transcript = !!forked_transcript
+      @ancestor_lookup = ancestor_lookup
+      @export_href = export_href
+      @forked_transcript_href = forked_transcript_href
+      @hide_forked_transcript_href = hide_forked_transcript_href
+      @asset_dir = asset_dir || DEFAULT_ASSET_DIR
+    end
+
+    def to_h
+      session_entries = load_session_entries
+      fork_parent_id = session_entries.first&.dig(:parent_id)
+      ancestor_entries = forked_transcript ? load_ancestor_entries(fork_parent_id) : []
+      raw_entries = ancestor_entries + session_entries
+      tool_name_by_call_id = build_tool_call_name_map(raw_entries)
+      ancestor_count = ancestor_entries.map { |entry| map_entry(entry, tool_name_by_call_id) }.compact.length
+      entries = normalize_parent_links(
+        raw_entries.map { |entry| map_entry(entry, tool_name_by_call_id) }.compact,
+        raw_entries,
+      )
+      leaf_id = entries.last&.dig(:id)
+
+      {
+        css: stylesheet,
+        header: build_header(entries),
+        entries: entries,
+        sidebar_entries: build_sidebar_entries(entries, ancestor_count: ancestor_count),
+        leaf_id: leaf_id,
+        path_entries: path_to_entry(entries, leaf_id),
+        stats: compute_stats(entries),
+        forked_transcript_available: Support.present?(fork_parent_id),
+        forked_transcript_enabled: forked_transcript,
+        forked_ancestor_count: ancestor_count,
+        export_href: export_href,
+        forked_transcript_href: forked_transcript_href || "?forked_transcript=1",
+        hide_forked_transcript_href: hide_forked_transcript_href || "?forked_transcript=0",
+      }
+    end
+
+    private
+
+    attr_reader :session_id, :events, :forked_transcript, :ancestor_lookup, :export_href, :forked_transcript_href, :hide_forked_transcript_href, :asset_dir
+
+    def load_session_entries
+      raw_entries = Array(events).map { |event| normalize_raw_event(event) }
+      raise EmptyTranscriptError, "Agent session has no events: #{session_id}" if raw_entries.empty?
+
+      raw_entries
+    end
+
+    def load_ancestor_entries(parent_id)
+      return [] unless ancestor_lookup
+
+      ancestors = []
+      seen_ids = Set.new
+      cursor_id = parent_id
+
+      while Support.present?(cursor_id) && !seen_ids.include?(cursor_id)
+        seen_ids << cursor_id
+        event = ancestor_lookup.call(cursor_id)
+        break unless event
+
+        normalized = normalize_raw_event(event)
+        ancestors.unshift(normalized)
+        cursor_id = normalized[:parent_id]
+      end
+
+      ancestors
+    end
+
+    def normalize_raw_event(event)
+      event = object_to_hash(event)
+      event = Support.symbolize(event)
+
+      {
+        id: event[:id] || event[:event_id],
+        parent_id: event[:parent_id] || event[:parentId],
+        timestamp: normalize_timestamp(event[:timestamp]),
+        type: event[:type] || event[:event_type],
+        usage: Support.symbolize(event[:usage] || event[:usage_json]),
+        data: Support.symbolize(event[:data] || event[:data_json] || {}),
+      }
+    end
+
+    def object_to_hash(event)
+      return event if event.is_a?(Hash)
+
+      {
+        id: value_from(event, :id) || value_from(event, :event_id),
+        parent_id: value_from(event, :parent_id),
+        timestamp: value_from(event, :timestamp),
+        type: value_from(event, :type) || value_from(event, :event_type),
+        usage: value_from(event, :usage) || value_from(event, :usage_json),
+        data: value_from(event, :data) || value_from(event, :data_json),
+      }
+    end
+
+    def value_from(object, name)
+      object.public_send(name) if object.respond_to?(name)
+    end
+
+    def normalize_timestamp(timestamp)
+      return timestamp.iso8601 if timestamp.respond_to?(:iso8601)
+
+      timestamp&.to_s
+    end
+
+    def stylesheet
+      read_asset_file("template.css")
+        .gsub("{{THEME_VARS}}", dark_theme_vars)
+        .gsub("{{BODY_BG}}", "#18181e")
+        .gsub("{{CONTAINER_BG}}", "#1e1e24")
+        .gsub("{{INFO_BG}}", "#3c3728")
+    end
+
+    def build_tool_call_name_map(raw_entries)
+      raw_entries.each_with_object({}) do |entry, map|
+        next unless entry[:type] == "message"
+
+        data = entry[:data]
+        next unless data[:role] == "assistant"
+        next unless data[:content].is_a?(Array)
+
+        data[:content].each do |block|
+          map[block[:id]] = block[:name] if block[:type] == "tool_use"
+        end
+      end
+    end
+
+    def normalize_parent_links(entries, raw_entries)
+      mapped_ids = entries.map { |entry| entry[:id] }.to_set
+      raw_parent_by_id = raw_entries.each_with_object({}) { |entry, hash| hash[entry[:id]] = entry[:parent_id] }
+
+      entries.map do |entry|
+        normalized = entry.dup
+        normalized[:parentId] = nearest_mapped_parent_id(entry[:parentId], mapped_ids, raw_parent_by_id)
+        normalized
+      end
+    end
+
+    def nearest_mapped_parent_id(parent_id, mapped_ids, raw_parent_by_id)
+      seen_ids = Set.new
+      cursor_id = parent_id
+
+      while Support.present?(cursor_id) && !seen_ids.include?(cursor_id)
+        return cursor_id if mapped_ids.include?(cursor_id)
+
+        seen_ids << cursor_id
+        cursor_id = raw_parent_by_id[cursor_id]
+      end
+
+      nil
+    end
+
+    def map_entry(entry, tool_name_by_call_id)
+      case entry[:type]
+      when "message"
+        map_message_entry(entry, tool_name_by_call_id)
+      when "reasoning_change"
+        {
+          id: entry[:id],
+          parentId: entry[:parent_id],
+          timestamp: entry[:timestamp],
+          type: "reasoningChange",
+          reasoning: entry.dig(:data, :reasoning).to_s,
+        }
+      when "model_change"
+        {
+          id: entry[:id],
+          parentId: entry[:parent_id],
+          timestamp: entry[:timestamp],
+          type: "modelChange",
+          modelId: entry.dig(:data, :model_id).to_s,
+        }
+      when "compaction"
+        {
+          id: entry[:id],
+          parentId: entry[:parent_id],
+          timestamp: entry[:timestamp],
+          type: "compaction",
+          summary: compaction_summary(entry),
+          tokensBefore: compaction_tokens_before(entry),
+        }
+      end
+    end
+
+    def map_message_entry(entry, tool_name_by_call_id)
+      data = entry[:data]
+
+      mapped = {
+        id: entry[:id],
+        parentId: entry[:parent_id],
+        timestamp: entry[:timestamp],
+        type: "message",
+        message: nil,
+      }
+
+      if data[:role] == "user" && tool_result_message?(data)
+        tool_result_block = data[:content].find { |block| block[:type] == "tool_result" }
+        mapped[:message] = {
+          role: "toolResult",
+          toolCallId: tool_result_block[:tool_use_id],
+          toolName: tool_name_by_call_id[tool_result_block[:tool_use_id]],
+          content: normalize_tool_result_content(tool_result_block[:content]),
+          isError: false,
+          details: nil,
+        }
+        return mapped
+      end
+
+      mapped[:message] = {
+        role: data[:role],
+        content: normalize_message_content(data[:content]),
+        stopReason: normalize_stop_reason(data[:stop_reason]),
+        errorMessage: data[:error_message],
+        provider: data[:provider],
+        model: data[:model],
+        usage: normalize_usage(entry[:usage] || data[:usage]),
+      }
+
+      mapped
+    end
+
+    def tool_result_message?(data)
+      data[:content].is_a?(Array) && data[:content].any? && data[:content].all? { |block| block[:type] == "tool_result" }
+    end
+
+    def normalize_stop_reason(stop_reason)
+      stop_reason == "tool_use" ? "toolUse" : stop_reason
+    end
+
+    def normalize_usage(usage)
+      return if Support.blank?(usage)
+
+      input_details = usage[:input_token_details] || usage[:input_tokens_details] || {}
+      output_details = usage[:output_token_details] || usage[:output_tokens_details] || {}
+
+      {
+        input: usage[:total_input_tokens] || usage[:input] || usage[:input_tokens] || input_details[:input_tokens] || 0,
+        output: usage[:total_output_tokens] || usage[:output] || usage[:output_tokens] || output_details[:output_tokens] || 0,
+        cacheRead: usage[:cache_read] || input_details[:cache_read_input_tokens] || input_details[:cached_tokens] || 0,
+        cacheWrite: usage[:cache_write] || input_details[:cache_creation_input_tokens] || 0,
+      }
+    end
+
+    def compaction_summary(entry)
+      direct_summary = entry.dig(:data, :summary)
+      return direct_summary.to_s if Support.present?(direct_summary)
+
+      content = entry.dig(:data, :content)
+      return "" unless content.is_a?(Array)
+
+      content.filter_map do |block|
+        block = Support.symbolize(block)
+        case block[:type]
+        when "text", "input_text", "output_text"
+          block[:text]
+        when "reasoning"
+          block[:reasoning]
+        when "thinking"
+          block[:thinking]
+        end
+      end.join("\n\n")
+    end
+
+    def compaction_tokens_before(entry)
+      usage = entry[:usage] || entry.dig(:data, :usage) || {}
+      entry.dig(:data, :tokens_before) || entry.dig(:data, :tokensBefore) ||
+        usage[:total_input_tokens] || usage[:input_tokens] || usage[:input] || 0
+    end
+
+    def normalize_message_content(content)
+      return [] unless content.is_a?(Array)
+
+      content.filter_map do |block|
+        case block[:type]
+        when "text", "input_text", "output_text"
+          { type: "text", text: block[:text].to_s }
+        when "thinking"
+          { type: "thinking", thinking: block[:thinking].to_s }
+        when "reasoning"
+          { type: "thinking", thinking: block[:reasoning].to_s }
+        when "tool_use"
+          {
+            type: "toolCall",
+            id: block[:id],
+            name: block[:name],
+            arguments: block[:input] || {},
+          }
+        when "server_tool_use"
+          {
+            type: "serverToolUse",
+            id: block[:id],
+            name: block[:name],
+            input: block[:input] || {},
+          }
+        when "server_tool_result"
+          {
+            type: "serverToolResult",
+            toolUseId: block[:tool_use_id],
+            content: block[:content] || {},
+          }
+        end
+      end
+    end
+
+    def normalize_tool_result_content(content)
+      if content.is_a?(Array)
+        content.map { |item| normalize_tool_result_item(item) }
+      else
+        [{ type: "text", text: content.to_s }]
+      end
+    end
+
+    def normalize_tool_result_item(item)
+      if item.is_a?(String)
+        { type: "text", text: item }
+      elsif item.is_a?(Hash)
+        item = Support.symbolize(item)
+        case item[:type]
+        when "text"
+          { type: "text", text: item[:text].to_s }
+        when "image"
+          { type: "image", data: item[:data], mimeType: item[:media_type] || item[:mime_type] || item[:mimeType] }
+        else
+          { type: "text", text: JSON.pretty_generate(item) }
+        end
+      else
+        { type: "text", text: item.to_s }
+      end
+    end
+
+    def build_header(entries)
+      {
+        id: session_id,
+        timestamp: entries.first&.dig(:timestamp),
+      }
+    end
+
+    def path_to_entry(entries, leaf_id)
+      by_id = entries.each_with_object({}) { |entry, hash| hash[entry[:id]] = entry }
+      path = []
+      cursor = by_id[leaf_id]
+      while cursor
+        path.unshift(cursor)
+        cursor = by_id[cursor[:parentId]]
+      end
+      return entries if path.length <= 1 && entries.length > 1 && entries.none? { |entry| Support.present?(entry[:parentId]) }
+
+      path.empty? ? entries : path
+    end
+
+    def build_sidebar_entries(entries, ancestor_count: 0)
+      sidebar_entries = entries.flat_map do |entry|
+        next tool_pair_sidebar_entries(entry, entries) if entry.dig(:message, :role) == "toolResult"
+
+        [entry, *tool_pair_sidebar_entries(entry, entries)]
+      end
+
+      insert_fork_boundary(sidebar_entries, entries, ancestor_count)
+    end
+
+    def insert_fork_boundary(sidebar_entries, entries, ancestor_count)
+      return sidebar_entries unless forked_transcript && ancestor_count.positive?
+
+      first_session_id = entries[ancestor_count]&.dig(:id)
+      boundary_parent_id = entries[ancestor_count - 1]&.dig(:id)
+      insert_index = sidebar_entries.index { |entry| entry[:id] == first_session_id || entry[:targetId] == first_session_id } || sidebar_entries.length
+      sidebar_entries.insert(insert_index, fork_boundary_entry(boundary_parent_id))
+      sidebar_entries
+    end
+
+    def fork_boundary_entry(parent_id)
+      {
+        id: "fork-boundary",
+        parentId: parent_id,
+        targetId: "fork-boundary",
+        type: "forkBoundary",
+      }
+    end
+
+    def tool_pair_sidebar_entries(entry, entries)
+      return [] unless entry[:type] == "message"
+
+      msg = entry[:message]
+      return [] unless msg[:role] == "assistant"
+
+      tool_result_by_call_id = entries
+        .select { |candidate| candidate.dig(:message, :role) == "toolResult" }
+        .each_with_object({}) { |candidate, hash| hash[candidate.dig(:message, :toolCallId)] = candidate }
+
+      msg[:content].filter_map.with_index do |block, index|
+        case block[:type]
+        when "toolCall"
+          result = tool_result_by_call_id[block[:id]]
+          build_tool_pair_entry(parent_entry: entry, tool_id: block[:id], tool_name: block[:name], input: block[:arguments], result_content: result&.dig(:message, :content), target_id: result&.dig(:id))
+        when "serverToolUse"
+          result_block = msg[:content][(index + 1)..]&.find { |candidate| candidate[:type] == "serverToolResult" && candidate[:toolUseId] == block[:id] }
+          build_tool_pair_entry(parent_entry: entry, tool_id: block[:id], tool_name: block[:name], input: block[:input], result_content: result_block&.dig(:content), target_id: entry[:id])
+        end
+      end
+    end
+
+    def build_tool_pair_entry(parent_entry:, tool_id:, tool_name:, input:, result_content:, target_id:)
+      {
+        id: "#{parent_entry[:id]}:tool:#{tool_id}",
+        parentId: parent_entry[:id],
+        targetId: target_id || parent_entry[:id],
+        timestamp: parent_entry[:timestamp],
+        type: "toolPair",
+        toolName: tool_name,
+        input: input || {},
+        resultContent: result_content,
+      }
+    end
+
+    def compute_stats(entries)
+      stats = { developer: 0, user: 0, assistant: 0, tool_results: 0, compactions: 0, tool_calls: 0, tokens: Hash.new(0), models: Set.new }
+      entries.each do |entry|
+        if entry[:type] == "compaction"
+          stats[:compactions] += 1
+          next
+        end
+        next unless entry[:type] == "message"
+
+        msg = entry[:message]
+        stats[:developer] += 1 if msg[:role] == "developer"
+        stats[:user] += 1 if msg[:role] == "user"
+        stats[:tool_results] += 1 if msg[:role] == "toolResult"
+        next unless msg[:role] == "assistant"
+
+        stats[:assistant] += 1
+        stats[:models] << [msg[:provider], msg[:model]].compact.join("/") if msg[:model]
+        stats[:tool_calls] += msg[:content].count { |block| block[:type] == "toolCall" }
+        [:input, :output, :cacheRead, :cacheWrite].each { |key| stats[:tokens][key] += msg[:usage][key].to_i } if msg[:usage]
+      end
+      stats
+    end
+
+    def dark_theme_vars
+      theme = JSON.parse(read_asset_file("dark.json"))
+      vars = theme["vars"] || {}
+      colors = theme["colors"] || {}
+
+      colors.map do |key, value|
+        resolved = if value.nil? || value == ""
+          "#e5e5e7"
+        elsif vars.key?(value)
+          vars[value]
+        else
+          value
+        end
+        "--#{key}: #{resolved};"
+      end.join("\n      ")
+    end
+
+    def read_asset_file(relative_path)
+      File.read(File.join(asset_dir, relative_path))
+    end
+  end
+end

data/lib/transcript_viewer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "transcript_viewer/version"
+require_relative "transcript_viewer/configuration"
+require_relative "transcript_viewer/tool_execution"
+require_relative "transcript_viewer/view"
+require_relative "transcript_viewer/renderer"
+require_relative "transcript_viewer/page"
+
+module TranscriptViewer
+  class Error < StandardError; end
+  class EmptyTranscriptError < Error; end
+  class TemplateNotFoundError < Error; end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.register_tool_template(tool_name, template_path)
+    configuration.register_tool_template(tool_name, template_path)
+  end
+
+  def self.page(session_id:, events:, forked_transcript: false, ancestor_lookup: nil, export_href: nil, forked_transcript_href: nil, hide_forked_transcript_href: nil, asset_dir: nil, template_dir: nil, tool_templates: nil, before_html: nil, after_html: nil)
+    Page.new(
+      session_id: session_id,
+      events: events,
+      forked_transcript: forked_transcript,
+      ancestor_lookup: ancestor_lookup,
+      export_href: export_href,
+      forked_transcript_href: forked_transcript_href,
+      hide_forked_transcript_href: hide_forked_transcript_href,
+      asset_dir: asset_dir,
+      template_dir: template_dir,
+      tool_templates: tool_templates,
+      before_html: before_html,
+      after_html: after_html,
+    )
+  end
+
+  def self.render(**options)
+    page(**options).render
+  end
+end