anima-core 1.0.1 → 1.0.2

data/lib/llm/client.rb

@@ -15,6 +15,9 @@ module LLM
   #   registry.register(Tools::WebGet)
   #   client.chat_with_tools(messages, registry: registry, session_id: session.id)
   class Client
+    # Synthetic tool_result message when a tool is skipped due to user interrupt.
+    INTERRUPT_MESSAGE = "Stopped by user"
+
     # @return [Providers::Anthropic] the underlying API provider
     attr_reader :provider
 
@@ -61,11 +64,14 @@ module LLM
     # Emits {Events::ToolCall} and {Events::ToolResponse} events for each
     # tool interaction so they're persisted and visible in the event stream.
     #
+    # When the user interrupts via Escape, remaining tools receive synthetic
+    # "Stopped by user" results and the loop exits without another LLM call.
+    #
     # @param messages [Array<Hash>] conversation messages in Anthropic format
     # @param registry [Tools::Registry] registered tools to make available
     # @param session_id [Integer, String] session ID for emitted events
     # @param options [Hash] additional API parameters (e.g. +system:+)
-    # @return [String] the assistant's final text response
+    # @return [String, nil] the assistant's final text response, or nil when interrupted
     # @raise [Providers::Anthropic::Error] on API errors
     def chat_with_tools(messages, registry:, session_id:, **options)
       messages = messages.dup
@@ -95,6 +101,11 @@ module LLM
             {role: "assistant", content: response["content"]},
             {role: "user", content: tool_results}
           ]
+
+          if interrupted?(session_id)
+            clear_interrupt!(session_id)
+            return nil
+          end
         else
           return extract_text(response)
         end
@@ -122,20 +133,43 @@ module LLM
     end
 
     # Executes all tool_use blocks from a response, emitting events for each.
+    # Checks for user interrupt between tools — remaining tools receive
+    # synthetic results to satisfy the Anthropic API's tool_use/tool_result
+    # pairing requirement (a missing result permanently breaks the conversation).
     #
     # @param response [Hash] Anthropic API response with tool_use content blocks
     # @param registry [Tools::Registry] tool registry for dispatch
     # @param session_id [Integer, String] session ID for events
     # @return [Array<Hash>] tool_result content blocks for the next API call
     def execute_tools(response, registry, session_id)
-      extract_tool_uses(response).map do |tool_use|
-        execute_single_tool(tool_use, registry, session_id)
+      tool_uses = extract_tool_uses(response)
+      results = []
+
+      tool_uses.each_with_index do |tool_use, index|
+        if interrupted?(session_id)
+          remaining = tool_uses[index..]
+          results.concat(interrupt_remaining_tools(remaining, session_id)) if remaining&.any?
+          break
+        end
+        results << execute_single_tool(tool_use, registry, session_id)
       end
+
+      results
+    end
+
+    # Creates synthetic "Stopped by user" results for all tools in the list.
+    #
+    # @param tool_uses [Array<Hash>] remaining tool_use content blocks
+    # @param session_id [Integer, String] session ID for events
+    # @return [Array<Hash>] tool_result content blocks
+    def interrupt_remaining_tools(tool_uses, session_id)
+      tool_uses.map { |tool_use| interrupt_tool(tool_use, session_id) }
     end
 
-    # Executes a single tool and always returns a tool_result — even if
-    # the tool raises. The LLM requires every tool_use to have a matching
-    # tool_result; a missing result breaks the conversation permanently.
+    # Executes a single tool and always returns a tool_result — even if the
+    # tool raises. Per the Anthropic tool-use protocol, every tool_use must
+    # have a matching tool_result; a missing result permanently corrupts the
+    # conversation history and breaks the session.
     def execute_single_tool(tool_use, registry, session_id)
       name = tool_use["name"]
       id = tool_use["id"]
@@ -167,6 +201,49 @@ module LLM
       {type: "tool_result", tool_use_id: id, content: result_content}
     end
 
+    # Creates a synthetic "Stopped by user" result for a tool that was not
+    # executed due to user interrupt. Emits both ToolCall and ToolResponse
+    # events so the TUI shows the interrupted tool in the event stream.
+    #
+    # @param tool_use [Hash] Anthropic tool_use content block
+    # @param session_id [Integer, String] session ID for events
+    # @return [Hash] tool_result content block
+    def interrupt_tool(tool_use, session_id)
+      name = tool_use["name"]
+      id = tool_use["id"]
+      input = tool_use["input"] || {}
+
+      Events::Bus.emit(Events::ToolCall.new(
+        content: "Skipped #{name} (interrupted)", tool_name: name,
+        tool_input: input, tool_use_id: id, session_id: session_id
+      ))
+
+      Events::Bus.emit(Events::ToolResponse.new(
+        content: INTERRUPT_MESSAGE, tool_name: name, tool_use_id: id,
+        success: false, session_id: session_id
+      ))
+
+      {type: "tool_result", tool_use_id: id, content: INTERRUPT_MESSAGE}
+    end
+
+    # Checks the database for a pending interrupt flag on the session.
+    #
+    # @param session_id [Integer, String] session to check
+    # @return [Boolean] whether the session has a pending interrupt request
+    def interrupted?(session_id)
+      Session.where(id: session_id, interrupt_requested: true).exists?
+    end
+
+    # Clears the interrupt flag so the agent loop can continue with pending
+    # messages. Also cleared by {AgentRequestJob#clear_interrupt} as a safety
+    # net for unexpected exits.
+    #
+    # @param session_id [Integer, String] session to clear
+    # @return [void]
+    def clear_interrupt!(session_id)
+      Session.where(id: session_id).update_all(interrupt_requested: false)
+    end
+
     def log(level, message)
       return unless @logger
 

data/lib/tools/think.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Tools
+  # A deliberate reasoning space for the agent's inner voice. Creates a
+  # pause between tool calls where the agent can organize thoughts, plan
+  # next steps, or make decisions without interrupting the user.
+  #
+  # Think events bridge the gap between the analytical brain (subconscious
+  # background processing) and speech (user-facing messages). Without this
+  # tool, reasoning leaks into tool arguments as comments.
+  #
+  # Two visibility modes control how thoughts appear in the TUI:
+  # - **inner** (default) — silent reasoning, visible only in verbose/debug
+  # - **aloud** — narration shown in all view modes with a thought bubble
+  #
+  # @example Silent planning between tool calls
+  #   think(thoughts: "Three auth failures — likely a config issue, not individual tests.")
+  #
+  # @example Narrating approach for the user
+  #   think(thoughts: "Checking the OAuth config first.", visibility: "aloud")
+  class Think < Base
+    def self.tool_name = "think"
+
+    def self.description
+      "Express your internal reasoning between tool calls. " \
+        "Use this to analyze intermediate results, plan next steps, or make decisions before continuing. " \
+        "Set visibility to \"aloud\" when you want the user to see your thought process."
+    end
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          thoughts: {
+            type: "string",
+            description: "Your reasoning, analysis, or internal monologue"
+          },
+          visibility: {
+            type: "string",
+            enum: ["inner", "aloud"],
+            description: "\"inner\" (default) for silent reasoning; \"aloud\" to narrate for the user"
+          }
+        },
+        required: ["thoughts"]
+      }
+    end
+
+    # @param input [Hash] with "thoughts" and optional "visibility"
+    # @return [String] acknowledgement — the value is in the call, not the result
+    def execute(input)
+      thoughts = input["thoughts"].to_s
+      return {error: "Thoughts cannot be blank"} if thoughts.strip.empty?
+
+      "OK"
+    end
+  end
+end

data/lib/tui/app.rb

@@ -391,9 +391,15 @@ module TUI
         return nil
       end
 
+      # Escape key priority: unfocus chat > interrupt tools > clear input > parent session
       if event.esc?
-        if @screens[:chat].chat_focused
-          @screens[:chat].unfocus_chat
+        chat = @screens[:chat]
+        if chat.chat_focused
+          chat.unfocus_chat
+        elsif chat.loading? && chat.input.empty?
+          chat.interrupt_execution
+        elsif !chat.input.empty?
+          chat.clear_input
         else
           return_to_parent_session
         end

data/lib/tui/cable_client.rb

@@ -134,6 +134,14 @@ module TUI
       send_action("recall_pending", {"event_id" => event_id})
     end
 
+    # Requests interruption of the current tool execution. The server sets
+    # an interrupt flag that the LLM client checks between tool calls.
+    #
+    # @return [void]
+    def interrupt
+      send_action("interrupt_execution", {})
+    end
+
     # Sends an Anthropic subscription token to the brain for validation and storage.
     # The token flows directly from TUI input to encrypted credentials — never
     # enters the LLM context window.

data/lib/tui/screens/chat.rb

@@ -21,6 +21,8 @@ module TUI
       RETURN_ARROW = "\u21A9"
       ERROR_ICON = "\u274C"
 
+      THOUGHT_BUBBLE = "\u{1F4AD}"
+
       ROLE_COLORS = {"user" => "green", "assistant" => "cyan"}.freeze
 
       # Intentionally duplicated from Session::VIEW_MODES to keep the TUI
@@ -165,6 +167,21 @@ module TUI
         @cable_client.change_view_mode(mode)
       end
 
+      # Sends an interrupt request to the server to stop the current tool chain.
+      # Called when Escape is pressed with empty input during active processing.
+      #
+      # @return [void]
+      def interrupt_execution
+        @cable_client.interrupt
+      end
+
+      # Clears the input buffer. Used when Escape is pressed with non-empty input.
+      #
+      # @return [void]
+      def clear_input
+        @input_buffer.clear
+      end
+
       # Clears the authentication_required flag after the App has consumed it.
       # @return [void]
       def clear_authentication_required
@@ -449,6 +466,8 @@ module TUI
           render_tool_call_entry(tui, data)
         when "tool_response"
           render_tool_response_entry(tui, data)
+        when "think"
+          render_think_entry(tui, data)
         when "system"
           render_system_entry(tui, data)
         when "system_prompt"
@@ -557,6 +576,27 @@ module TUI
         lines
       end
 
+      # Renders a think event — the agent's inner reasoning between tool calls.
+      # "aloud" thoughts use yellow (narration for the user), "inner" thoughts
+      # use dark_gray (visible only in verbose/debug, dimmed to signal internality).
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @param data [Hash] structured data with "content", "visibility", optional "timestamp", "tool_use_id"
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_think_entry(tui, data)
+        aloud = data["visibility"] == "aloud"
+        color = aloud ? "yellow" : "dark_gray"
+        style = tui.style(fg: color)
+
+        meta = []
+        meta << "[#{format_ns_timestamp(data["timestamp"])}]" if data["timestamp"]
+        header = meta.empty? ? THOUGHT_BUBBLE : "#{meta.join(" ")} #{THOUGHT_BUBBLE}"
+
+        content_lines = data["content"].to_s.split("\n", -1)
+        lines = [tui.line(spans: [tui.span(content: "#{header} #{content_lines.first}", style: style)])]
+        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: "  #{line}", style: style)]) }
+        lines
+      end
+
       # Formats a token count for display, with tilde prefix for estimates.
       # @param tokens [Integer, nil] token count
       # @param estimated [Boolean] whether the count is an estimate

data/templates/config.toml

@@ -0,0 +1,116 @@
+# Anima Configuration
+#
+# Edit settings below to customize Anima's behavior.
+# Changes take effect immediately — no restart needed.
+
+# ─── LLM ───────────────────────────────────────────────────────
+
+[llm]
+
+# Primary model for conversations.
+model = "claude-opus-4-6"
+
+# Lightweight model for fast tasks (e.g. session naming).
+fast_model = "claude-haiku-4-5"
+
+# Maximum tokens per LLM response.
+max_tokens = 8192
+
+# Maximum consecutive tool execution rounds per request.
+max_tool_rounds = 500
+
+# Context window budget — tokens reserved for conversation history.
+# Set this based on your model's context window minus system prompt.
+token_budget = 190_000
+
+# ─── Timeouts (seconds) ─────────────────────────────────────────
+
+[timeouts]
+
+# LLM API request timeout.
+api = 300
+
+# Shell command execution timeout.
+command = 30
+
+# MCP server response timeout.
+mcp_response = 60
+
+# Web fetch request timeout.
+web_request = 10
+
+# ─── Shell ──────────────────────────────────────────────────────
+
+[shell]
+
+# Maximum bytes of command output before truncation.
+max_output_bytes = 100_000
+
+# ─── Tools ──────────────────────────────────────────────────────
+
+[tools]
+
+# Maximum file size for read/edit operations (bytes).
+max_file_size = 10_485_760
+
+# Maximum lines returned by the read tool.
+max_read_lines = 2_000
+
+# Maximum bytes returned by the read tool.
+max_read_bytes = 50_000
+
+# Maximum bytes from web GET responses.
+max_web_response_bytes = 100_000
+
+# ─── Environment ──────────────────────────────────────────────
+
+[environment]
+
+# Files to scan for in the working directory (at root and up to project_files_max_depth subdirectories deep).
+project_files = ["CLAUDE.md", "AGENTS.md", "README.md", "CONTRIBUTING.md"]
+
+# Maximum directory depth for project file scanning.
+project_files_max_depth = 3
+
+# ─── GitHub ─────────────────────────────────────────────────────
+
+[github]
+
+# Repository for agent feature requests (owner/repo format).
+# Falls back to parsing git remote origin when unset.
+repo = "hoblin/anima"
+
+# Label applied to agent-created feature request issues.
+label = "anima-wants"
+
+# ─── Paths ─────────────────────────────────────────────────────
+
+[paths]
+
+# The agent's self-authored identity file.
+soul = "{{ANIMA_HOME}}/soul.md"
+
+# ─── Session ────────────────────────────────────────────────────
+
+[session]
+
+# Regenerate session name every N messages.
+name_generation_interval = 30
+
+# ─── Analytical Brain ─────────────────────────────────────────
+
+[analytical_brain]
+
+# Maximum tokens per analytical brain response.
+# Must accommodate multiple tool calls (rename + goals + skills + ready).
+max_tokens = 4096
+
+# Run the analytical brain synchronously before the main agent on user messages.
+# Ensures activated skills are available for the current response.
+blocking_on_user_message = true
+
+# Run the analytical brain asynchronously after the main agent completes.
+blocking_on_agent_message = false
+
+# Number of recent events to include in the analytical brain's context window.
+event_window = 20

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: anima-core
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Yevhenii Hurin
@@ -269,6 +269,7 @@ files:
 - db/migrate/20260315140843_create_goals.rb
 - db/migrate/20260315144837_add_completed_at_to_goals.rb
 - db/migrate/20260315191105_add_active_workflow_to_sessions.rb
+- db/migrate/20260316094817_add_interrupt_requested_to_sessions.rb
 - db/queue_schema.rb
 - db/seeds.rb
 - exe/anima
@@ -290,6 +291,7 @@ files:
 - lib/anima/cli.rb
 - lib/anima/cli/mcp.rb
 - lib/anima/cli/mcp/secrets.rb
+- lib/anima/config_migrator.rb
 - lib/anima/installer.rb
 - lib/anima/settings.rb
 - lib/anima/version.rb
@@ -326,6 +328,7 @@ files:
 - lib/tools/spawn_specialist.rb
 - lib/tools/spawn_subagent.rb
 - lib/tools/subagent_prompts.rb
+- lib/tools/think.rb
 - lib/tools/web_get.rb
 - lib/tools/write.rb
 - lib/tui/app.rb
@@ -514,6 +517,7 @@ files:
 - skills/rspec/references/matchers.md
 - skills/rspec/references/mocks.md
 - skills/rspec/references/rails.md
+- templates/config.toml
 - templates/soul.md
 - workflows/commit.md
 - workflows/create_handoff.md