Module: Clacky::Agent::SessionSerializer

Included in:

Clacky::Agent

Defined in:

lib/clacky/agent/session_serializer.rb

Overview

Session serialization for saving and restoring agent state Handles session data serialization and deserialization

Instance Method Summary

• #_replay_single_message(msg, ui) ⇒ Object

  Render a single non-user message into the UI.

• #extract_image_files_from_content(content) ⇒ Object

  Extract images from a multipart content array and return them as file entries.

• #extract_images_from_content(content) ⇒ Array<String>

  Extract base64 data URLs from multipart content (image blocks).

• #extract_text_from_content(content) ⇒ String

  Extract text from message content (handles string and array formats).

• #get_recent_user_messages(limit: 5) ⇒ Array<String>

  Get recent user messages from conversation history.

• #inject_chunk_index_if_needed ⇒ Object

  Inject a chunk index card into the conversation when archived chunks exist.

• #refresh_system_prompt ⇒ Object

  Replace the system message in @messages with a freshly built system prompt.

• #replay_history(ui, limit: 20, before: nil) ⇒ Hash

  Replay conversation history by calling ui.show_* methods for each message.

• #restore_session(session_data) ⇒ Object

  Restore from a saved session.

• #to_session_data(status: :success, error_message: nil) ⇒ Hash

  Generate session data for saving.

Instance Method Details

#_replay_single_message(msg, ui) ⇒ Object

Render a single non-user message into the UI. Used by both the normal round-based replay and the compressed-session fallback.

# File 'lib/clacky/agent/session_serializer.rb', line 469

def _replay_single_message(msg, ui)
  return if msg[:system_injected]

  case msg[:role].to_s
  when "assistant"
    # Text content
    text = extract_text_from_content(msg[:content]).to_s.strip
    ui.show_assistant_message(text, files: []) unless text.empty?

    # Tool calls embedded in assistant message
    Array(msg[:tool_calls]).each do |tc|
      name     = tc[:name] || tc.dig(:function, :name) || ""
      args_raw = tc[:arguments] || tc.dig(:function, :arguments) || {}
      args     = args_raw.is_a?(String) ? (JSON.parse(args_raw) rescue args_raw) : args_raw

      # Special handling: request_user_feedback question is shown as an
      # assistant message (matching real-time behavior), not as a tool call.
      # Reconstruct the full formatted message including options (mirrors RequestUserFeedback#execute).
      if name == "request_user_feedback"
        question = args.is_a?(Hash) ? (args[:question] || args["question"]).to_s : ""
        context  = args.is_a?(Hash) ? (args[:context]  || args["context"]).to_s  : ""
        options  = args.is_a?(Hash) ? (args[:options]  || args["options"])        : nil

        unless question.empty?
          parts = []
          parts << "**Context:** #{context.strip}" << "" unless context.strip.empty?
          parts << "**Question:** #{question.strip}"
          # Guard: options must be an Array to iterate with each_with_index
          if options.is_a?(Array) && !options.empty?
            parts << "" << "**Options:**"
            options.each_with_index { |opt, i| parts << "  #{i + 1}. #{opt}" }
          end
          ui.show_assistant_message(parts.join("\n"), files: [])
        end
      else
        ui.show_tool_call(name, args)
      end
    end

    # Emit token usage stored on this message (for history replay display)
    ui.show_token_usage(msg[:token_usage]) if msg[:token_usage]

  when "user"
    # Anthropic-format tool results (role: user, content: array of tool_result blocks)
    return unless msg[:content].is_a?(Array)

    msg[:content].each do |blk|
      next unless blk.is_a?(Hash) && blk[:type] == "tool_result"

      ui.show_tool_result(blk[:content].to_s)
    end

  when "tool"
    # OpenAI-format tool result
    ui.show_tool_result(msg[:content].to_s)
  end
end

#extract_image_files_from_content(content) ⇒ Object

Extract images from a multipart content array and return them as file entries. Returns an array of { name:, mime_type:, data_url: } hashes — the same structure that the frontend sends via ‘files` in a message, and that show_user_message(files:) expects. Only includes inline data_url images (not remote URLs).

# File 'lib/clacky/agent/session_serializer.rb', line 593

def extract_image_files_from_content(content)
  return [] unless content.is_a?(Array)

  content.each_with_index.filter_map do |block, idx|
    next unless block.is_a?(Hash)
    # OpenAI-style: { type: "image_url", image_url: { url: "data:image/png;base64,..." } }
    next unless block[:type] == "image_url"

    url = block.dig(:image_url, :url)
    # image_path is stored at send-time so replay can reconstruct the image from tmp
    path = block[:image_path]

    next unless url&.start_with?("data:") || path

    mime_type = (url || "")[/\Adata:([^;]+);/, 1] || "image/jpeg"
    ext       = mime_type.split("/").last
    { name: "image_#{idx + 1}.#{ext}", mime_type: mime_type, data_url: url, path: path }
  end
end

#extract_images_from_content(content) ⇒ Array<String>

Extract base64 data URLs from multipart content (image blocks). Returns an empty array when there are no images or content is plain text.

Parameters:

• content (String, Array, Object) —

  Message content

Returns:

• (Array<String>) —

  Array of data URLs (e.g. “data:image/png;base64,…”)

# File 'lib/clacky/agent/session_serializer.rb', line 547

def extract_images_from_content(content)
  return [] unless content.is_a?(Array)

  content.filter_map do |block|
    next unless block.is_a?(Hash)

    case block[:type].to_s
    when "image_url"
      # OpenAI format: { type: "image_url", image_url: { url: "data:image/png;base64,..." } }
      block.dig(:image_url, :url)
    when "image"
      # Anthropic format: { type: "image", source: { type: "base64", media_type: "image/png", data: "..." } }
      source = block[:source]
      next unless source.is_a?(Hash) && source[:type].to_s == "base64"

      "data:#{source[:media_type]};base64,#{source[:data]}"
    when "document"
      # Anthropic PDF document block — return a sentinel string for frontend display
      source = block[:source]
      next unless source.is_a?(Hash) && source[:media_type].to_s == "application/pdf"

      # Return a special marker so the frontend can render a PDF badge instead of an <img>
      "pdf:#{source[:data]&.then { |d| d[0, 32] }}"  # prefix to identify without full payload
    end
  end
end

#extract_text_from_content(content) ⇒ String

Extract text from message content (handles string and array formats)

Parameters:

• content (String, Array, Object) —

  Message content

Returns:

• (String) —

  Extracted text

# File 'lib/clacky/agent/session_serializer.rb', line 577

def extract_text_from_content(content)
  if content.is_a?(String)
    content
  elsif content.is_a?(Array)
    # Extract text from content array (may contain text and images)
    text_parts = content.select { |c| c.is_a?(Hash) && c[:type] == "text" }
    text_parts.map { |c| c[:text] }.join("\n")
  else
    content.to_s
  end
end

#get_recent_user_messages(limit: 5) ⇒ Array<String>

Get recent user messages from conversation history

Parameters:

• limit (Integer) (defaults to: 5) —

  Number of recent user messages to retrieve (default: 5)

Returns:

• (Array<String>) —

  Array of recent user message contents

# File 'lib/clacky/agent/session_serializer.rb', line 146

def get_recent_user_messages(limit: 5)
  @history.real_user_messages.last(limit).map do |msg|
    extract_text_from_content(msg[:content])
  end
end

#inject_chunk_index_if_needed ⇒ Object

Inject a chunk index card into the conversation when archived chunks exist. Lists all chunk files (path + topics + turn count) so the AI knows where to look if it needs details from past conversations. The AI can load any chunk on demand using the existing file_reader tool — no new tools required.

Only re-injects when a new chunk has been added since the last injection, keeping the message list clean across multiple compressions.

Cache-safe: injected as a system_injected user message in the conversation turns, never touching the system prompt.

# File 'lib/clacky/agent/session_serializer.rb', line 623

def inject_chunk_index_if_needed
  # Collect all compressed_summary messages that carry a chunk_path
  chunk_msgs = @history.to_a.select { |m| m[:compressed_summary] && m[:chunk_path] }
  return if chunk_msgs.empty?

  # Skip if we already injected an index for this exact chunk count
  return if @history.last_injected_chunk_count == chunk_msgs.size

  # Remove any previously injected chunk index (stale — chunk count changed)
  @history.delete_where { |m| m[:chunk_index] }

  # Build index card lines
  lines = ["## Previous Session Archives (#{chunk_msgs.size} chunk#{"s" if chunk_msgs.size > 1} available)\n"]
  chunk_msgs.each_with_index do |msg, i|
    path   = msg[:chunk_path].to_s
    topics = read_chunk_topics(path)
    turns  = read_chunk_message_count(path)
    lines << "[CHUNK-#{i + 1}] #{path}"
    lines << "  Topics: #{topics}" if topics
    lines << "  Turns: #{turns}"   if turns
    lines << ""
  end
  lines << "Use file_reader to load a chunk file when you need original conversation details."

  @history.append({
    role: "user",
    content: lines.join("\n"),
    system_injected: true,
    chunk_index: true,
    chunk_count: chunk_msgs.size
  })
end

#refresh_system_prompt ⇒ Object

Replace the system message in @messages with a freshly built system prompt. Called after restore_session so newly installed skills and any other configuration changes since the session was saved take effect immediately. If no system message exists yet (shouldn’t happen in practice), a new one is prepended so the conversation stays well-formed.

# File 'lib/clacky/agent/session_serializer.rb', line 532

def refresh_system_prompt
  # Reload skills from disk to pick up anything installed since the session was saved
  @skill_loader.load_all

  fresh_prompt = build_system_prompt
  @history.replace_system_prompt(fresh_prompt)
rescue StandardError => e
  # Log and continue — a stale system prompt is better than a broken restore
  Clacky::Logger.warn("refresh_system_prompt failed during session restore: #{e.message}")
end

#replay_history(ui, limit: 20, before: nil) ⇒ Hash

Replay conversation history by calling ui.show_* methods for each message. Supports cursor-based pagination using created_at timestamps on user messages. Each “round” starts at a user message and includes all subsequent assistant/tool messages. Compressed chunks (chunk_path on assistant messages) are transparently expanded.

Parameters:

• ui (Object) —

  UI interface that responds to show_user_message, show_assistant_message, etc.

• limit (Integer) (defaults to: 20) —

  Maximum number of rounds (user turns) to replay

• before (Float, nil) (defaults to: nil) —

  Unix timestamp cursor — only replay rounds where the user message created_at < before. Pass nil to get the most recent rounds.

Returns:

• (Hash) —

  { has_more: Boolean } — whether older rounds exist beyond this page

# File 'lib/clacky/agent/session_serializer.rb', line 162

def replay_history(ui, limit: 20, before: nil)
  # Split @history into rounds, each starting at a real user message
  rounds = []
  current_round = nil

  @history.to_a.each do |msg|
    role = msg[:role].to_s

    # A real user message can have either a String content or an Array content
    # (Array = multipart: text + image blocks). Exclude system-injected messages
    # and synthetic [SYSTEM] text messages.
    is_real_user_msg = role == "user" && !msg[:system_injected] &&
      if msg[:content].is_a?(String)
        !msg[:content].start_with?("[SYSTEM]")
      elsif msg[:content].is_a?(Array)
        # Must contain at least one text or image block (not a tool_result array)
        msg[:content].any? { |b| b.is_a?(Hash) && %w[text image].include?(b[:type].to_s) }
      else
        false
      end

    if is_real_user_msg
      # Start a new round at each real user message
      current_round = { user_msg: msg, events: [] }
      rounds << current_round
    elsif current_round
      current_round[:events] << msg
    elsif msg[:compressed_summary] && msg[:chunk_path]
      # Compressed summary sitting before any user rounds — expand ALL chunk
      # MD files that belong to the same session (siblings of chunk_path),
      # in chunk-index ascending order.
      #
      # Under the current "single summary + previous_chunks index" scheme,
      # session.json only keeps the newest compressed_summary message (which
      # points at the newest chunk). Older chunks (chunk-1..chunk-N-1) are
      # referenced only as basenames inside the summary text. Expanding just
      # msg[:chunk_path] would therefore lose all prior chunks on replay.
      chunk_rounds = sibling_chunks_of(msg[:chunk_path]).flat_map { |p|
        parse_chunk_md_to_rounds(p)
      }
      rounds.concat(chunk_rounds)
      # After expanding, treat the last chunk round as the current round so that
      # any orphaned assistant/tool messages that follow in session.json (belonging
      # to the same task whose user message was compressed into the chunk) get
      # appended here instead of being silently discarded.
      current_round = rounds.last
    elsif rounds.last
      # Orphaned non-user message with no current_round yet (e.g. recent_messages
      # after compression started mid-task with no leading user message).
      # Attach to the last known round rather than drop silently.
      rounds.last[:events] << msg
    end
  end

  # Expand any compressed_summary assistant messages sitting inside a round's events.
  # These occur when compression happened mid-round (rare) — expand them in-place.
  rounds.each do |round|
    round[:events].select! { |ev| !ev[:compressed_summary] }
  end

  # Apply before-cursor filter: only rounds whose user message created_at < before
  if before
    rounds = rounds.select { |r| r[:user_msg][:created_at] && r[:user_msg][:created_at] < before }
  end

  # Fallback: when the conversation was compressed and no user messages remain in the
  # kept slice, render the surviving assistant/tool messages directly so the user can
  # still see the last visible state of the chat (e.g. compressed summary + recent work).
  if rounds.empty?
    visible = @history.to_a.reject { |m| m[:role].to_s == "system" || m[:system_injected] }
    visible.each { |msg| _replay_single_message(msg, ui) }
    return { has_more: false }
  end

  has_more = rounds.size > limit
  # Take the most recent `limit` rounds
  page = rounds.last(limit)

  page.each do |round|
    msg = round[:user_msg]
    raw_text    = extract_text_from_content(msg[:content])
    # Images: recovered from inline image_url blocks in content (carry data_url for <img> rendering)
    image_files = extract_image_files_from_content(msg[:content])
    # Disk files (PDF, doc, etc.): stored in display_files on the user message at send time
    disk_files  = Array(msg[:display_files]).map { |f|
      { name: f[:name] || f["name"], type: f[:type] || f["type"] || "file",
        preview_path: f[:preview_path] || f["preview_path"] }
    }
    all_files = image_files + disk_files
    ui.show_user_message(raw_text, created_at: msg[:created_at], files: all_files)

    round[:events].each do |ev|
      # Skip system-injected messages (e.g. synthetic skill content, memory prompts)
      # — they are internal scaffolding and must not be shown to the user.
      next if ev[:system_injected]

      _replay_single_message(ev, ui)
    end
  end

  { has_more: has_more }
end

#restore_session(session_data) ⇒ Object

Restore from a saved session

Parameters:

• session_data (Hash) —

  Saved session data

# File 'lib/clacky/agent/session_serializer.rb', line 10

def restore_session(session_data)
  @session_id = session_data[:session_id]
  @name = session_data[:name] || ""
  @pinned = session_data[:pinned] || false
  @history = MessageHistory.new(session_data[:messages] || [])
  @todos = session_data[:todos] || []  # Restore todos from session
  @iterations = session_data.dig(:stats, :total_iterations) || 0
  @total_cost = session_data.dig(:stats, :total_cost_usd) || 0.0
  @working_dir = session_data[:working_dir]
  @created_at = session_data[:created_at]
  @total_tasks = session_data.dig(:stats, :total_tasks) || 0
  # Restore cost_source so frontend knows if cost is reliable
  cost_src = session_data.dig(:stats, :cost_source)
  @cost_source = (cost_src && cost_src.to_sym) || :estimated
  @task_cost_source = :estimated
  # Restore source; fall back to :manual for sessions saved before this field existed
  @source = (session_data[:source] || "manual").to_sym

  # Restore cache statistics if available
  @cache_stats = session_data.dig(:stats, :cache_stats) || {
    cache_creation_input_tokens: 0,
    cache_read_input_tokens: 0,
    total_requests: 0,
    cache_hit_requests: 0
  }

  # Restore previous_total_tokens for accurate delta calculation across sessions
  @previous_total_tokens = session_data.dig(:stats, :previous_total_tokens) || 0

  # Recover the latest latency metric from the most recent assistant message
  # that carries a :latency field. This is the source of truth for the status-bar
  # signal — no separate session-level field is needed. Older sessions (pre-feature)
  # simply start with nil; the signal stays hidden until the next LLM call populates it.
  last_assistant_with_latency = @history.to_a.reverse.find do |m|
    m[:role].to_s == "assistant" && m[:latency]
  end
  @latest_latency = last_assistant_with_latency&.dig(:latency)

  # Restore Time Machine state
  @task_parents = session_data.dig(:time_machine, :task_parents) || {}
  @current_task_id = session_data.dig(:time_machine, :current_task_id) || 0
  @active_task_id = session_data.dig(:time_machine, :active_task_id) || 0

  # Check if the session ended with an error.
  # We record the rollback intent here but do NOT truncate history immediately —
  # truncating at restore time causes the history replay to return empty results,
  # leaving the chat panel blank on first open.
  # Instead, the rollback is deferred: history is trimmed lazily when the user
  # actually sends the next message (see run() / handle_user_message).
  last_status = session_data.dig(:stats, :last_status)
  last_error = session_data.dig(:stats, :last_error)

  if last_status == "error" && last_error
    @pending_error_rollback = true
  end

  # Restore the session's original model if it still exists in the current
  # config. This prevents all sessions from silently switching to the new
  # default model when the user changes it and restarts. Falls back to the
  # current default if the model was deleted/renamed since the session was
  # last saved.
  saved_model_name = session_data.dig(:config, :model_name)
  if saved_model_name
    saved_base_url = session_data.dig(:config, :model_base_url)
    model_entry = @config.find_model_by_name_and_url(saved_model_name, saved_base_url)
    if model_entry && model_entry["id"]
      switch_model_by_id(model_entry["id"])
    end
  end

  # Rebuild and refresh the system prompt so any newly installed skills
  # (or other configuration changes since the session was saved) are
  # reflected immediately — without requiring the user to create a new session.
  refresh_system_prompt
end

#to_session_data(status: :success, error_message: nil) ⇒ Hash

Generate session data for saving

Parameters:

• status (Symbol) (defaults to: :success) —

  Status of the last task: :success, :error, or :interrupted

• error_message (String) (defaults to: nil) —

  Error message if status is :error

Returns:

• (Hash) —

  Session data ready for serialization

# File 'lib/clacky/agent/session_serializer.rb', line 90

def to_session_data(status: :success, error_message: nil)
  stats_data = {
    total_tasks: @total_tasks,
    total_iterations: @iterations,
    total_cost_usd: @total_cost.round(4),
    cost_source: @cost_source.to_s,
    duration_seconds: @start_time ? (Time.now - @start_time).round(2) : 0,
    last_status: status.to_s,
    cache_stats: @cache_stats,
    debug_logs: @debug_logs,
    previous_total_tokens: @previous_total_tokens
  }

  # Add error message if status is error
  stats_data[:last_error] = error_message if status == :error && error_message

  {
    session_id: @session_id,
    name: @name,
    pinned: @pinned,
    created_at: @created_at,
    updated_at: Time.now.iso8601,
    working_dir: @working_dir,
    source: @source.to_s,                      # "manual" | "cron" | "channel" | "setup"
    agent_profile: @agent_profile&.name || "", # "general" | "coding" | custom
    todos: @todos,  # Include todos in session data
    time_machine: {  # Include Time Machine state
      task_parents: @task_parents || {},
      current_task_id: @current_task_id || 0,
      active_task_id: @active_task_id || 0
    },
    config: {
      # NOTE: api_key and other sensitive credentials are intentionally excluded
      # to prevent leaking secrets into session files on disk.
      # model_name is saved so the session can restore its original model on restart
      # (falling back to the current default if the model no longer exists).
      permission_mode: @config.permission_mode.to_s,
      enable_compression: @config.enable_compression,
      enable_prompt_caching: @config.enable_prompt_caching,
      max_tokens: @config.max_tokens,
      verbose: @config.verbose,
      # Persist the current model identity so the session can restore its
      # original model on restart. model_name + model_base_url form a
      # composite key to avoid matching a different provider's model of
      # the same name. Falls back to default if the model no longer exists.
      model_name: @config.current_model&.dig("model"),
      model_base_url: @config.current_model&.dig("base_url")
    },
    stats: stats_data,
    messages: @history.to_a
  }
end