anima-core 1.1.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 161b7dfde73fa61f7656427c0af3c5919e1a1cc50d6b1a2d201f5a45ce79c561
-  data.tar.gz: 880538d54fbc682b61bbeb6d63b38aa066e86327c778fefce8e60091c6ad816d
+  metadata.gz: 19dbc9d1eaa160cc21e98ad347f86968ad4ce5cb31f2bc3024844a1e0cd3c8e4
+  data.tar.gz: 280f6848271d0c97958dddc467543bb4b747c5a1e8a2e417f0c88e21b9612f4e
 SHA512:
-  metadata.gz: f0ee765c1a125e26b9f10b5cc97f41e857ec17562ef4ba116dd53bf97b9b26fb3781d9f292c6296c1c408089d155d9d8a24e4165d58f57ead64e72595f833ae8
-  data.tar.gz: 86c95c9f103cb0c6c4b37ef3452662274205da97ef04d3f846f7f2d041ff0c94f375208b60d245f454aa73abb2c144113f9d6691cc99a0124f43971fcfb62ae1
+  metadata.gz: 9c43ec74eabd07e8ce2be3f8961e67f16858f2de20e828730f10b00dafe9cf2e3e9f3e96ed018718283d2093ae20bd0933931ce9807c29959b95b1f8c2a9a17c
+  data.tar.gz: 6bcb6b84581afb310b98899a40d2aa04d87cbcbd7790970fa9053c817886580eab5fe73f39a37944c7421ef9c190e5be26ffd2abac28a0afd7306dae5e2f19da

data/.reek.yml

@@ -80,6 +80,10 @@ detectors:
   TooManyConstants:
     exclude:
       - "EventDecorator"
+  # encode_utf8 is descriptive — the digit triggers a false positive.
+  UncommunicativeMethodName:
+    exclude:
+      - "ToolDecorator#self.encode_utf8"
   # Abstract base class methods declare parameters for the subclass contract.
   UnusedParameters:
     exclude:

data/app/decorators/tool_decorator.rb

@@ -21,19 +21,74 @@ class ToolDecorator
     "web_get" => "WebGetToolDecorator"
   }.freeze
 
-  # Factory: dispatches to the tool-specific decorator or passes through.
+  # Factory: dispatches to the tool-specific decorator, then sanitizes
+  # the result for safe LLM consumption.
+  #
+  # Sanitization guarantees the final string is UTF-8 encoded, free of
+  # ANSI escape codes, and stripped of control characters that carry no
+  # meaning for an LLM. This is the single gate — no tool or decorator
+  # subclass needs to think about encoding or terminal noise.
   #
   # @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
+  # @return [String, Hash] sanitized 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
+    result = klass_name.constantize.new.call(result) if klass_name
+
+    sanitize_for_llm(result)
+  end
+
+  # Ensures a tool result string is safe for LLM consumption by
+  # composing {encode_utf8}, {strip_ansi}, and {strip_control_chars}.
+  #
+  # Non-string results pass through unchanged.
+  #
+  # @param result [String, Object] tool output to sanitize
+  # @return [String, Object] sanitized string or original object
+  def self.sanitize_for_llm(result)
+    return result unless result.is_a?(String)
+
+    strip_control_chars(strip_ansi(encode_utf8(result)))
+  end
+  private_class_method :sanitize_for_llm
 
-    klass_name.constantize.new.call(result)
+  # Force-encodes a string to UTF-8, replacing invalid or undefined
+  # bytes with the Unicode replacement character (U+FFFD).
+  #
+  # @param str [String] input in any encoding (commonly ASCII-8BIT from PTY)
+  # @return [String] valid UTF-8 string
+  def self.encode_utf8(str)
+    str.encode("UTF-8", invalid: :replace, undef: :replace, replace: "\uFFFD")
+  end
+  private_class_method :encode_utf8
+
+  # CSI (colors, cursor, DEC private modes), OSC (terminal title),
+  # charset designation, single-char commands
+  ANSI_ESCAPE = /\e\[[?>=<0-9;]*[A-Za-z]|\e\][^\a\e]*(?:\a|\e\\)|\e[()][0-9A-Za-z]|\e[>=<78NOMDEHcn]/
+  private_constant :ANSI_ESCAPE
+
+  # Strips ANSI escape sequences that are meaningless noise to an LLM
+  # but can dominate terminal output payloads.
+  #
+  # @param str [String] UTF-8 string possibly containing escape codes
+  # @return [String] cleaned string
+  def self.strip_ansi(str)
+    str.gsub(ANSI_ESCAPE, "")
+  end
+  private_class_method :strip_ansi
+
+  # Strips C0 control characters (NUL, BEL, BS, CR, etc.) that carry
+  # no meaning for an LLM. Preserves newline (\n) and tab (\t).
+  #
+  # @param str [String] UTF-8 string possibly containing control chars
+  # @return [String] cleaned string
+  def self.strip_control_chars(str)
+    str.gsub(/[\x00-\x08\x0B-\x0D\x0E-\x1F\x7F]/, "")
   end
+  private_class_method :strip_control_chars
 
   # Subclasses override to transform the raw tool result.
   #

data/lib/anima/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Anima
-  VERSION = "1.1.1"
+  VERSION = "1.1.2"
 end

data/lib/llm/client.rb

@@ -191,13 +191,7 @@ module LLM
         session_id: session_id
       ))
 
-      result = begin
-        registry.execute(name, input)
-      rescue => error
-        Rails.logger.error("Tool #{name} raised #{error.class}: #{error.message}")
-        {error: "#{error.class}: #{error.message}"}
-      end
-
+      result = registry.execute(name, input)
       result = ToolDecorator.call(name, result)
       result_content = format_tool_result(result)
       log(:debug, "tool_result: #{name} → #{result_content.to_s.truncate(200)}")
@@ -209,6 +203,23 @@ module LLM
       ))
 
       {type: "tool_result", tool_use_id: id, content: result_content}
+    rescue => error
+      error_detail = "#{error.class}: #{error.message}"
+      Rails.logger.error("Tool #{name} raised #{error_detail}")
+      error_content = format_tool_result(error: error_detail)
+
+      # Emission can fail (e.g. encoding errors in ActionCable/SQLite),
+      # but losing the tool_result would permanently corrupt the session.
+      begin
+        Events::Bus.emit(Events::ToolResponse.new(
+          content: error_content, tool_name: name, tool_use_id: id,
+          success: false, session_id: session_id
+        ))
+      rescue => emit_error
+        Rails.logger.error("ToolResponse emission failed: #{emit_error.class}: #{emit_error.message}")
+      end
+
+      {type: "tool_result", tool_use_id: id, content: error_content}
     end
 
     # Creates a synthetic "Stopped by user" result for a tool that was not

data/lib/shell_session.rb

@@ -390,10 +390,11 @@ class ShellSession
 
   def truncate(output)
     max_bytes = @max_output_bytes
+    output = output.dup.force_encoding("UTF-8").scrub
+
     return output if output.bytesize <= max_bytes
 
     output.byteslice(0, max_bytes)
-      .force_encoding("UTF-8")
       .scrub +
       "\n\n[Truncated: output exceeded #{max_bytes} bytes]"
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: anima-core
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.2
 platform: ruby
 authors:
 - Yevhenii Hurin