anima-core 1.0.1 → 1.1.0

data/anima-core.gemspec

@@ -21,13 +21,14 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
     ls.readlines("\x0", chomp: true).reject do |f|
-      f.start_with?(*%w[bin/console bin/dev bin/setup .gitignore .rspec spec/ .github/ .standard.yml thoughts/ CLAUDE.md .mise.toml])
+      f.start_with?(*%w[bin/console bin/dev bin/setup Gemfile .gitignore .rspec spec/ .github/ .standard.yml thoughts/ CLAUDE.md .mise.toml])
     end
   end
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "certifi"
   spec.add_dependency "draper", "~> 4.0"
   spec.add_dependency "faraday", "~> 2.0"
   spec.add_dependency "foreman", "~> 0.88"
@@ -36,9 +37,11 @@ Gem::Specification.new do |spec|
   spec.add_dependency "puma", "~> 6.0"
   spec.add_dependency "rails", "~> 8.1"
   spec.add_dependency "ratatui_ruby", "~> 1.4"
+  spec.add_dependency "reverse_markdown", "~> 3.0"
   spec.add_dependency "solid_cable", "~> 3.0"
   spec.add_dependency "solid_queue", "~> 1.1"
   spec.add_dependency "sqlite3", "~> 2.0"
   spec.add_dependency "toml-rb", "~> 4.0"
+  spec.add_dependency "toon-ruby", "~> 0.1"
   spec.add_dependency "websocket-client-simple", "~> 0.8"
 end

data/app/channels/session_channel.rb

@@ -42,9 +42,14 @@ class SessionChannel < ApplicationCable::Channel
     ActionCable.server.broadcast(stream_name, data)
   end
 
-  # Processes user input: persists the message and enqueues LLM processing.
-  # When the session is actively processing an agent request, the message
-  # is queued as "pending" and picked up after the current loop completes.
+  # Processes user input by emitting a {Events::UserMessage} on the event bus.
+  #
+  # When the session is idle, the emission triggers {Events::Subscribers::AgentDispatcher}
+  # which schedules {AgentRequestJob} to persist the event and deliver it to the LLM
+  # inside a transaction (Bounce Back, #236).
+  #
+  # When the session is already processing, the message is queued as "pending"
+  # and picked up after the current agent loop completes.
   #
   # @param data [Hash] must include "content" with the user's message text
   def speak(data)
@@ -58,7 +63,6 @@ class SessionChannel < ApplicationCable::Channel
       Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id, status: Event::PENDING_STATUS))
     else
       Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id))
-      AgentRequestJob.perform_later(@current_session_id)
     end
   end
 
@@ -82,6 +86,21 @@ class SessionChannel < ApplicationCable::Channel
     ActionCable.server.broadcast(stream_name, {"action" => "user_message_recalled", "event_id" => event_id})
   end
 
+  # Requests interruption of the current tool execution. Sets a flag on the
+  # session that the LLM client checks between tool calls. Remaining tools
+  # receive synthetic "Stopped by user" results to satisfy the API's
+  # tool_use/tool_result pairing requirement.
+  #
+  # Atomic: a single UPDATE with WHERE avoids the read-then-write race where
+  # the session could finish processing between the SELECT and UPDATE.
+  # No-op if the session isn't currently processing.
+  #
+  # @param _data [Hash] unused
+  def interrupt_execution(_data)
+    Session.where(id: @current_session_id, processing: true)
+      .update_all(interrupt_requested: true)
+  end
+
   # Returns recent root sessions with nested child metadata for session picker UI.
   # Filters to root sessions only (no parent_session_id). Child sessions are
   # nested under their parent with name and status information.
@@ -126,10 +145,18 @@ class SessionChannel < ApplicationCable::Channel
     token = data["token"].to_s.strip
 
     Providers::Anthropic.validate_token_format!(token)
-    Providers::Anthropic.validate_token_api!(token)
-    write_anthropic_token(token)
 
-    transmit({"action" => "token_saved"})
+    warning = begin
+      Providers::Anthropic.validate_token_api!(token)
+      nil
+    rescue Providers::Anthropic::TransientError => transient
+      # Token format is valid but API is temporarily unavailable (500, timeout, etc.).
+      # Save the token to break the prompt loop — it will work once the API recovers.
+      "Token saved but could not be verified — #{transient.message}"
+    end
+
+    write_anthropic_token(token)
+    transmit({"action" => "token_saved", "warning" => warning}.compact)
   rescue Providers::Anthropic::TokenFormatError, Providers::Anthropic::AuthenticationError => error
     transmit({"action" => "token_error", "message" => error.message})
   end
@@ -174,12 +201,12 @@ class SessionChannel < ApplicationCable::Channel
   # client can handle both paths with a single code path.
   #
   # Payload: session_id, name, parent_session_id, message_count,
-  # view_mode, active_skills, goals.
+  # view_mode, active_skills, goals, children (when present).
   #
   # @param session [Session] the session to announce
   # @return [void]
   def transmit_session_changed(session)
-    transmit({
+    payload = {
       "action" => "session_changed",
       "session_id" => session.id,
       "name" => session.name,
@@ -189,7 +216,14 @@ class SessionChannel < ApplicationCable::Channel
       "active_skills" => session.active_skills,
       "active_workflow" => session.active_workflow,
       "goals" => session.goals_summary
-    })
+    }
+
+    children = session.child_sessions.order(:created_at).select(:id, :name, :processing)
+    if children.any?
+      payload["children"] = children.map { |child| {"id" => child.id, "name" => child.name, "processing" => child.processing?} }
+    end
+
+    transmit(payload)
   end
 
   # Switches the channel to a different session: stops current stream,

data/app/decorators/agent_message_decorator.rb

@@ -21,4 +21,10 @@ class AgentMessageDecorator < EventDecorator
   def render_debug
     render_verbose.merge(token_info)
   end
+
+  # @return [String] agent message for the analytical brain, middle-truncated
+  #   if very long (preserves opening context and final conclusion)
+  def render_brain
+    "Assistant: #{truncate_middle(content)}"
+  end
 end

data/app/decorators/event_decorator.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
 # Base decorator for {Event} records, providing multi-resolution rendering
-# for the TUI. Each event type has a dedicated subclass that implements
-# rendering methods for each view mode (basic, verbose, debug).
+# for the TUI and analytical brain. Each event type has a dedicated subclass
+# that implements rendering methods for each view mode:
 #
-# Decorators return structured hashes (not pre-formatted strings) so that
+# - **basic** / **verbose** / **debug** — TUI display modes returning structured hashes
+# - **brain** — analytical brain transcript returning plain strings (or nil to skip)
+#
+# TUI decorators return structured hashes (not pre-formatted strings) so that
 # the TUI can style and lay out content based on semantic role, without
 # fragile regex parsing. The TUI receives structured data via ActionCable
 # and formats it for display.
 #
-# Subclasses must override {#render_basic}. Verbose and debug modes
+# Brain mode returns condensed single-line strings for the analytical brain's
+# event transcript. Returns nil to exclude an event from the brain's view.
+#
+# Subclasses must override {#render_basic}. Verbose, debug, and brain modes
 # delegate to basic until subclasses provide their own implementations.
 #
 # @example Decorate an Event AR model
@@ -29,6 +35,7 @@ class EventDecorator < ApplicationDecorator
   TOOL_ICON = "\u{1F527}"
   RETURN_ARROW = "\u21A9"
   ERROR_ICON = "\u274C"
+  MIDDLE_TRUNCATION_MARKER = "\n[...truncated...]\n"
 
   DECORATOR_MAP = {
     "user_message" => "UserMessageDecorator",
@@ -77,14 +84,16 @@ class EventDecorator < ApplicationDecorator
   RENDER_DISPATCH = {
     "basic" => :render_basic,
     "verbose" => :render_verbose,
-    "debug" => :render_debug
+    "debug" => :render_debug,
+    "brain" => :render_brain
   }.freeze
   private_constant :RENDER_DISPATCH
 
   # Dispatches to the render method for the given view mode.
   #
-  # @param mode [String] one of "basic", "verbose", "debug"
-  # @return [Hash, nil] structured event data, or nil to hide the event
+  # @param mode [String] one of "basic", "verbose", "debug", "brain"
+  # @return [Hash, String, nil] structured event data (basic/verbose/debug),
+  #   plain string (brain), or nil to hide the event
   # @raise [ArgumentError] if the mode is not a valid view mode
   def render(mode)
     method = RENDER_DISPATCH[mode]
@@ -113,6 +122,14 @@ class EventDecorator < ApplicationDecorator
     render_basic
   end
 
+  # Analytical brain view — condensed single-line string for the brain's
+  # event transcript. Returns nil to exclude from the brain's context.
+  # Subclasses override to provide event-type-specific formatting.
+  # @return [String, nil] formatted transcript line, or nil to skip
+  def render_brain
+    nil
+  end
+
   private
 
   # Token count for display: exact count from {CountEventTokensJob} when
@@ -155,6 +172,23 @@ class EventDecorator < ApplicationDecorator
     lines.first(max_lines).push("...").join("\n")
   end
 
+  # Truncates long text by cutting the middle, preserving the start and end
+  # so context and conclusions aren't lost. Used for brain transcripts where
+  # both the opening (intent) and closing (result) matter.
+  #
+  # @param text [String, nil] text to truncate
+  # @param max_chars [Integer] maximum character length before truncation
+  # @return [String] original text or start + marker + end
+  def truncate_middle(text, max_chars: 500)
+    str = text.to_s
+    return str if str.length <= max_chars
+
+    keep = max_chars - MIDDLE_TRUNCATION_MARKER.length
+    head = keep / 2
+    tail = keep - head
+    "#{str[0, head]}#{MIDDLE_TRUNCATION_MARKER}#{str[-tail, tail]}"
+  end
+
   # Normalizes input to something Draper can wrap.
   # Event AR models pass through; hashes become EventPayload structs
   # with string-normalized keys.

data/app/decorators/tool_call_decorator.rb

@@ -1,36 +1,95 @@
 # frozen_string_literal: true
 
+require "toon"
+
 # Decorates tool_call events for display in the TUI.
 # Hidden in basic mode — tool activity is represented by the
 # aggregated tool counter instead. Verbose mode returns tool name
 # and a formatted preview of the input arguments. Debug mode shows
-# full untruncated input as pretty-printed JSON with tool_use_id.
+# full untruncated input in TOON format with tool_use_id.
+#
+# Think tool calls are special: "aloud" thoughts are shown in all
+# view modes (with a thought bubble), while "inner" thoughts are
+# visible only in verbose and debug modes.
 class ToolCallDecorator < EventDecorator
-  # @return [nil] tool calls are hidden in basic mode
+  THINK_TOOL = "think"
+
+  # In basic mode, only "aloud" think calls are visible.
+  # All other tool calls are hidden (represented by the tool counter).
+  #
+  # @return [Hash, nil] structured think data for aloud thoughts, nil otherwise
   def render_basic
-    nil
+    return unless think?
+    return unless aloud?
+
+    {role: :think, content: thoughts, visibility: "aloud"}
   end
 
   # @return [Hash] structured tool call data
   #   `{role: :tool_call, tool: String, input: String, timestamp: Integer|nil}`
   def render_verbose
+    return render_think_verbose if think?
+
     {role: :tool_call, tool: payload["tool_name"], input: format_input, timestamp: timestamp}
   end
 
   # @return [Hash] full tool call data with untruncated input and tool_use_id
   #   `{role: :tool_call, tool: String, input: String, tool_use_id: String|nil, timestamp: Integer|nil}`
   def render_debug
+    return render_think_debug if think?
+
     {
       role: :tool_call,
       tool: payload["tool_name"],
-      input: JSON.pretty_generate(payload["tool_input"] || {}),
+      input: Toon.encode(payload["tool_input"] || {}),
       tool_use_id: payload["tool_use_id"],
       timestamp: timestamp
     }
   end
 
+  # Think calls get full text — the agent's reasoning IS the signal.
+  # Other tool calls show tool name + params (compact JSON).
+  # @return [String] transcript line for the analytical brain
+  def render_brain
+    if think?
+      "Think: #{thoughts}"
+    else
+      "Tool call: #{payload["tool_name"]}(#{tool_input.to_json})"
+    end
+  end
+
   private
 
+  def think?
+    payload["tool_name"] == THINK_TOOL
+  end
+
+  def aloud?
+    tool_input.dig("visibility") == "aloud"
+  end
+
+  def thoughts
+    tool_input.dig("thoughts").to_s
+  end
+
+  def tool_input
+    payload["tool_input"] || {}
+  end
+
+  def visibility
+    tool_input.dig("visibility") || "inner"
+  end
+
+  # @return [Hash] think event for verbose mode — both inner and aloud visible
+  def render_think_verbose
+    {role: :think, content: thoughts, visibility: visibility, timestamp: timestamp}
+  end
+
+  # @return [Hash] think event for debug mode — full metadata
+  def render_think_debug
+    {role: :think, content: thoughts, visibility: visibility, tool_use_id: payload["tool_use_id"], timestamp: timestamp}
+  end
+
   # Formats tool input for display, with tool-specific formatting for
   # known tools and generic JSON fallback for others.
   # @return [String] formatted input preview
@@ -41,8 +100,10 @@ class ToolCallDecorator < EventDecorator
       "$ #{input&.dig("command")}"
     when "web_get"
       "GET #{input&.dig("url")}"
+    when "read", "edit", "write"
+      input&.dig("file_path").to_s
     else
-      truncate_lines(input.to_json, max_lines: 2)
+      truncate_lines(Toon.encode(input), max_lines: 2)
     end
   end
 end

data/app/decorators/tool_decorator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Base class for server-side tool response decoration. Transforms raw tool
+# results into LLM-optimized formats before they enter the event stream.
+#
+# This is a separate decorator type from {EventDecorator}: EventDecorator
+# formats events for clients (TUI/web), while ToolDecorator formats tool
+# responses for the LLM. They sit at different points in the pipeline:
+#
+#   Tool executes → ToolDecorator transforms → event stream → EventDecorator renders
+#
+# Subclasses implement {#call} to transform a tool's raw result into an
+# LLM-friendly string. Each tool can have its own ToolDecorator subclass
+# (e.g. {WebGetToolDecorator}) registered in {DECORATOR_MAP}.
+#
+# @example Decorating a tool result
+#   ToolDecorator.call("web_get", {body: html, content_type: "text/html"})
+#   #=> "[Converted: HTML → Markdown]\n\n# Page Title\n..."
+class ToolDecorator
+  DECORATOR_MAP = {
+    "web_get" => "WebGetToolDecorator"
+  }.freeze
+
+  # Factory: dispatches to the tool-specific decorator or passes through.
+  #
+  # @param tool_name [String] registered tool name
+  # @param result [String, Hash] raw tool execution result
+  # @return [String, Hash] decorated result (String) or original error Hash
+  def self.call(tool_name, result)
+    return result if result.is_a?(Hash) && result.key?(:error)
+
+    klass_name = DECORATOR_MAP[tool_name]
+    return result unless klass_name
+
+    klass_name.constantize.new.call(result)
+  end
+
+  # Subclasses override to transform the raw tool result.
+  #
+  # @param result [String, Hash] raw tool execution result
+  # @return [String] LLM-optimized content
+  def call(result)
+    raise NotImplementedError, "#{self.class} must implement #call"
+  end
+
+  private
+
+  # Combines decorated text with an optional metadata tag so the LLM
+  # knows the content was transformed.
+  #
+  # @param text [String] the transformed content
+  # @param meta [String, nil] conversion tag (e.g. "[Converted: HTML → Markdown]")
+  # @return [String]
+  def assemble(text:, meta:)
+    meta ? "#{meta}\n\n#{text}" : text
+  end
+end

data/app/decorators/tool_response_decorator.rb

@@ -3,19 +3,29 @@
 # Decorates tool_response events for display in the TUI.
 # Hidden in basic mode — tool activity is represented by the
 # aggregated tool counter instead. Verbose mode returns truncated
-# output with a success/failure indicator. Debug mode shows full
-# untruncated output with tool_use_id and estimated token count.
+# output with a success/failure indicator and tool name for per-tool
+# client-side rendering. Debug mode shows full untruncated output
+# with tool_use_id and estimated token count.
+#
+# Think tool responses ("OK") are hidden in basic and verbose modes
+# because the value is in the tool_call (the thoughts), not the response.
 class ToolResponseDecorator < EventDecorator
+  THINK_TOOL = "think"
+
   # @return [nil] tool responses are hidden in basic mode
   def render_basic
     nil
   end
 
-  # @return [Hash] structured tool response data
-  #   `{role: :tool_response, content: String, success: Boolean, timestamp: Integer|nil}`
+  # Think responses are hidden in verbose mode — the "OK" adds no information.
+  # @return [Hash, nil] structured tool response data, nil for think responses
+  #   `{role: :tool_response, tool: String, content: String, success: Boolean, timestamp: Integer|nil}`
   def render_verbose
+    return if think?
+
     {
       role: :tool_response,
+      tool: tool_name,
       content: truncate_lines(content, max_lines: 3),
       success: payload["success"] != false,
       timestamp: timestamp
@@ -23,15 +33,35 @@ class ToolResponseDecorator < EventDecorator
   end
 
   # @return [Hash] full tool response data with untruncated content, tool_use_id, and token estimate
-  #   `{role: :tool_response, content: String, success: Boolean, tool_use_id: String|nil,
+  #   `{role: :tool_response, tool: String, content: String, success: Boolean, tool_use_id: String|nil,
   #     timestamp: Integer|nil, tokens: Integer, estimated: Boolean}`
   def render_debug
     {
       role: :tool_response,
+      tool: tool_name,
       content: content,
       success: payload["success"] != false,
       tool_use_id: payload["tool_use_id"],
       timestamp: timestamp
     }.merge(token_info)
   end
+
+  # Think responses ("OK") are noise — excluded from the brain's transcript.
+  # Other tool responses are compressed to success/failure indicators only.
+  # @return [String, nil] ✅ or ❌ indicator, nil for think responses
+  def render_brain
+    return if think?
+
+    (payload["success"] != false) ? "\u2705" : "\u274C"
+  end
+
+  private
+
+  def tool_name
+    payload["tool_name"]
+  end
+
+  def think?
+    tool_name == THINK_TOOL
+  end
 end

data/app/decorators/user_message_decorator.rb

@@ -26,6 +26,12 @@ class UserMessageDecorator < EventDecorator
     render_verbose.merge(token_info)
   end
 
+  # @return [String] user message for the analytical brain, middle-truncated
+  #   if very long (preserves intent at start and conclusion at end)
+  def render_brain
+    "User: #{truncate_middle(content)}"
+  end
+
   private
 
   # @return [Boolean] true when this message is queued but not yet sent to LLM

data/app/decorators/web_get_tool_decorator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "reverse_markdown"
+require "toon"
+
+# Transforms {Tools::WebGet} responses for LLM consumption by detecting
+# the Content-Type header and applying format-specific conversion.
+#
+# Content-Type maps to a method name via simple string normalization:
+#   "application/json" → {#application_json}
+#   "text/html"        → {#text_html}
+#   "text/plain"       → method_missing → passthrough
+#
+# Adding a new format = adding one method. Unknown types fall through
+# {#method_missing} and pass through unchanged.
+#
+# @example
+#   decorator = WebGetToolDecorator.new
+#   decorator.call(body: "<h1>Hi</h1>", content_type: "text/html")
+#   #=> "[Converted: HTML → Markdown]\n\n# Hi"
+class WebGetToolDecorator < ToolDecorator
+  # HTML elements that carry no useful content for an LLM.
+  NOISE_TAGS = %w[script style nav footer aside form noscript iframe
+    svg header menu menuitem].freeze
+
+  # @param result [Hash] `{body: String, content_type: String}`
+  # @return [String] LLM-optimized content with conversion metadata tag
+  def call(result)
+    return result.to_s unless result.is_a?(Hash) && result.key?(:body)
+
+    body = result[:body].to_s
+    content_type = result[:content_type] || "text/plain"
+    decorated = decorate(body, content_type: content_type)
+
+    assemble(**decorated)
+  end
+
+  # Dispatches to the format-specific method derived from Content-Type.
+  #
+  # @param body [String] raw response body
+  # @param content_type [String] HTTP Content-Type header value
+  # @return [Hash] `{text: String, meta: String|nil}`
+  def decorate(body, content_type:)
+    method_name = content_type.split(";").first.strip.tr("/", "_").tr("-", "_")
+    public_send(method_name, body)
+  end
+
+  # Compresses JSON using TOON (Token-Optimized Object Notation) for
+  # ~40% token savings on typical JSON arrays.
+  #
+  # @param body [String] JSON response body
+  # @return [Hash] `{text: String, meta: String}`
+  def application_json(body)
+    parsed = JSON.parse(body)
+    {text: Toon.encode(parsed), meta: "[Converted: JSON → TOON]"}
+  rescue JSON::ParserError
+    {text: body, meta: nil}
+  end
+
+  # Strips noise elements (scripts, styles, nav, ads) and converts
+  # semantic HTML to Markdown for clean LLM consumption.
+  #
+  # @param body [String] HTML response body
+  # @return [Hash] `{text: String, meta: String}`
+  def text_html(body)
+    markdown = html_to_markdown(body)
+    {text: markdown, meta: "[Converted: HTML → Markdown]"}
+  end
+
+  # Passthrough for unregistered content types.
+  #
+  # @return [Hash] `{text: String, meta: nil}`
+  def method_missing(_method_name, body, *)
+    {text: body, meta: nil}
+  end
+
+  def respond_to_missing?(*, **)
+    true
+  end
+
+  private
+
+  # Strips noise HTML elements then converts to Markdown.
+  #
+  # @param html [String] raw HTML
+  # @return [String] clean Markdown
+  def html_to_markdown(html)
+    doc = Nokogiri::HTML(html)
+    doc.css(NOISE_TAGS.join(", ")).remove
+    clean_html = doc.at("body")&.inner_html || doc.to_html
+    markdown = ReverseMarkdown.convert(clean_html, unknown_tags: :bypass, github_flavored: true)
+    collapse_whitespace(markdown)
+  end
+
+  # Collapses excessive blank lines down to a single blank line.
+  #
+  # @param text [String]
+  # @return [String]
+  def collapse_whitespace(text)
+    text.gsub(/\n{3,}/, "\n\n").strip
+  end
+end