anima-core 1.1.3 → 1.2.0

data/lib/tools/{request_feature.rb → open_issue.rb}

@@ -3,32 +3,29 @@
 require "open3"
 
 module Tools
-  # Creates a GitHub issue via the +gh+ CLI, letting the agent request
-  # capabilities it discovers are missing during real work. Every issue
-  # is tagged with the label from +[github] label+ in +config.toml+ so
-  # the developer can filter agent-originated requests from human ones.
+  # Opens a GitHub issue on Anima's repository via the +gh+ CLI,
+  # giving the agent a voice to report bugs, pain points, or ideas.
+  # Every issue is tagged with the label from +[github] label+ in
+  # +config.toml+ so maintainers can filter agent-originated issues.
   #
   # The repository is read from +[github] repo+ in +config.toml+; when
   # unset, the tool falls back to parsing the +origin+ remote URL.
   #
   # @see https://github.com/hoblin/anima/issues/103
-  class RequestFeature < Base
+  class OpenIssue < Base
     # @return [String] tool identifier used in the Anthropic API schema
-    def self.tool_name = "request_feature"
+    def self.tool_name = "open_issue"
 
-    # @return [String] motivational description shown to the LLM
-    def self.description
-      "Don't have the right tool for this task? Request it! " \
-        "Creates a GitHub issue so the developer knows what you need."
-    end
+    # @return [String] description shown to the LLM
+    def self.description = "Something broken, missing, or could be better in Anima? Say it here."
 
     # @return [Hash] JSON Schema for the tool's input parameters
     def self.input_schema
       {
         type: "object",
         properties: {
-          title: {type: "string", description: "Short, descriptive title for the feature request"},
-          description: {type: "string", description: "What you need and why — what were you trying to do, and what's missing?"}
+          title: {type: "string"},
+          description: {type: "string", description: "Use gh-issue skill for guidance."}
         },
         required: %w[title description]
       }

data/lib/tools/read.rb

@@ -18,15 +18,15 @@ module Tools
   class Read < Base
     def self.tool_name = "read"
 
-    def self.description = "Read file contents. Returns plain text with smart truncation. Use offset/limit to page through large files."
+    def self.description = "Read file. Relative paths resolve against working directory."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
-          offset: {type: "integer", description: "1-indexed line number to start from (default: 1)"},
-          limit: {type: "integer", description: "Maximum lines to read (subject to line and byte caps from config)"}
+          path: {type: "string"},
+          offset: {type: "integer", description: "1-indexed line number (default: 1)."},
+          limit: {type: "integer", description: "Max lines to return."}
         },
         required: ["path"]
       }

data/lib/tools/registry.rb

@@ -73,7 +73,7 @@ module Tools
       s[:input_schema][:properties] ||= {}
       s[:input_schema][:properties]["timeout"] = {
         type: "integer",
-        description: "Max execution seconds (default: #{default}). Increase for long-running operations."
+        description: "Seconds (default: #{default})."
       }
       s
     end

data/lib/tools/remember.rb

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
 module Tools
-  # Fractal-resolution zoom into event history. Returns a window centered
-  # on a target event with full detail at the center and compressed context
+  # Fractal-resolution zoom into message history. Returns a window centered
+  # on a target message with full detail at the center and compressed context
   # at the edges — sharp fovea, blurry periphery.
   #
   # Output structure:
   #   [Previous snapshots — compressed context before]
-  #   [Events N-M — full detail, tool_responses compressed to checkmarks]
+  #   [Messages N-M — full detail, tool_responses compressed to checkmarks]
   #   [Following snapshots — compressed context after]
   #
-  # The agent discovers target events via FTS5 search results embedded in
+  # The agent discovers target messages via FTS5 search results embedded in
   # viewport recall snippets. This tool drills down into the full context.
   #
   # @example
-  #   remember(event_id: 42)
+  #   remember(message_id: 42)
   class Remember < Base
-    # Events around the target to include at full resolution.
-    # ±10 events provides sharp foveal detail while keeping output readable.
+    # Messages around the target to include at full resolution.
+    # ±10 messages provides sharp foveal detail while keeping output readable.
     CONTEXT_WINDOW = 20
 
     ROLE_LABELS = {
@@ -28,24 +28,15 @@ module Tools
 
     def self.tool_name = "remember"
 
-    def self.description
-      "Recall the full context around a past event. " \
-        "Returns a fractal-resolution window: high detail at the center " \
-        "(the target event and its neighbors), compressed context at the edges " \
-        "(snapshots before and after). Use this when search results surface " \
-        "a relevant event and you need the surrounding conversation."
-    end
+    def self.description = "Recall the full conversation around a past message."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          event_id: {
-            type: "integer",
-            description: "The event ID to zoom into (from search results or recall snippets)"
-          }
+          message_id: {type: "integer"}
         },
-        required: ["event_id"]
+        required: ["message_id"]
       }
     end
 
@@ -53,12 +44,12 @@ module Tools
       @session = session
     end
 
-    # @param input [Hash] with "event_id"
-    # @return [String] fractal-resolution window around the target event
+    # @param input [Hash] with "message_id"
+    # @return [String] fractal-resolution window around the target message
     def execute(input)
-      event_id = input["event_id"].to_i
-      target = Event.find_by(id: event_id)
-      return {error: "Event #{event_id} not found"} unless target
+      message_id = input["message_id"].to_i
+      target = Message.find_by(id: message_id)
+      return {error: "Message #{message_id} not found"} unless target
 
       build_fractal_window(target)
     end
@@ -67,17 +58,17 @@ module Tools
 
     # Assembles the three-zone fractal window.
     #
-    # @param target [Event] the center event
+    # @param target [Message] the center message
     # @return [String] formatted fractal window
     def build_fractal_window(target)
       target_session = target.session
-      center_events = fetch_center_events(target, target_session)
-      first_center_id = center_events.first&.id
-      last_center_id = center_events.last&.id
+      center_messages = fetch_center_messages(target, target_session)
+      first_center_id = center_messages.first&.id
+      last_center_id = center_messages.last&.id
 
       sections = build_sections(
         target_session: target_session,
-        center_events: center_events,
+        center_messages: center_messages,
         target_id: target.id,
         first_center_id: first_center_id,
         last_center_id: last_center_id
@@ -86,18 +77,18 @@ module Tools
     end
 
     # Builds ordered sections: header, before snapshots, center, after snapshots.
-    def build_sections(target_session:, center_events:, target_id:, first_center_id:, last_center_id:)
+    def build_sections(target_session:, center_messages:, target_id:, first_center_id:, last_center_id:)
       sections = [session_header(target_session)]
 
       append_snapshot_sections(sections, target_session.snapshots
-        .where("to_event_id < ?", first_center_id)
+        .where("to_message_id < ?", first_center_id)
         .chronological.last(3), label: "PREVIOUS CONTEXT")
 
-      sections << "── FULL CONTEXT (events #{first_center_id}..#{last_center_id}) ──"
-      center_events.each { |event| sections << render_center_event(event, target_id) }
+      sections << "── FULL CONTEXT (messages #{first_center_id}..#{last_center_id}) ──"
+      center_messages.each { |msg| sections << render_center_message(msg, target_id) }
 
       append_snapshot_sections(sections, target_session.snapshots
-        .where("from_event_id > ?", last_center_id)
+        .where("from_message_id > ?", last_center_id)
         .chronological.first(3), label: "FOLLOWING CONTEXT")
 
       sections
@@ -116,12 +107,12 @@ module Tools
       snapshots.each { |snapshot| sections << format_snapshot(snapshot) }
     end
 
-    # Fetches conversation events around the target within a fixed window.
+    # Fetches conversation messages around the target within a fixed window.
     #
-    # @return [Array<Event>] chronologically ordered
-    def fetch_center_events(target, target_session)
+    # @return [Array<Message>] chronologically ordered
+    def fetch_center_messages(target, target_session)
       half = CONTEXT_WINDOW / 2
-      scope = target_session.events.context_events.deliverable
+      scope = target_session.messages.context_messages.deliverable
       target_id = target.id
 
       before = scope.where("id <= ?", target_id).reorder(id: :desc).limit(half + 1).to_a.reverse
@@ -130,37 +121,37 @@ module Tools
       before + after
     end
 
-    # Renders a center event at full resolution.
-    # Conversation events show full content. Tool calls show name + input.
+    # Renders a center message at full resolution.
+    # Conversation messages show full content. Tool calls show name + input.
     # Tool responses compressed to status indicator.
     #
-    # @param event [Event]
-    # @param target_id [Integer] the event being zoomed into (marked with arrow)
+    # @param message [Message]
+    # @param target_id [Integer] the message being zoomed into (marked with arrow)
     # @return [String]
-    def render_center_event(event, target_id)
-      marker = (event.id == target_id) ? "→" : " "
-      prefix = "#{marker} event #{event.id}"
+    def render_center_message(message, target_id)
+      marker = (message.id == target_id) ? "→" : " "
+      prefix = "#{marker} message #{message.id}"
 
-      "#{prefix} #{format_event_content(event)}"
+      "#{prefix} #{format_message_content(message)}"
     end
 
-    # Formats event content based on type.
-    def format_event_content(event)
-      data = event.payload
+    # Formats message content based on type.
+    def format_message_content(message)
+      data = message.payload
       content = data["content"]
 
-      if ROLE_LABELS.key?(event.event_type)
-        "#{ROLE_LABELS[event.event_type]}: #{content}"
-      elsif event.event_type == "tool_call"
+      if ROLE_LABELS.key?(message.message_type)
+        "#{ROLE_LABELS[message.message_type]}: #{content}"
+      elsif message.message_type == "tool_call"
         format_tool_call(data)
-      elsif event.event_type == "tool_response"
+      elsif message.message_type == "tool_response"
         status = content.to_s.start_with?("Error") ? "error" : "ok"
         "ToolResult: [#{status}] #{data["tool_use_id"]}"
       end
     end
 
     def format_tool_call(data)
-      if data["tool_name"] == Event::THINK_TOOL
+      if data["tool_name"] == Message::THINK_TOOL
         "Think: #{data.dig("tool_input", "thoughts")}"
       else
         "Tool: #{data["tool_name"]}(#{data["tool_input"].to_json.truncate(200)})"
@@ -173,7 +164,7 @@ module Tools
     # @return [String]
     def format_snapshot(snapshot)
       level = (snapshot.level == 2) ? "L2" : "L1"
-      "[#{level} snapshot, events #{snapshot.from_event_id}..#{snapshot.to_event_id}]\n#{snapshot.text}"
+      "[#{level} snapshot, messages #{snapshot.from_message_id}..#{snapshot.to_message_id}]\n#{snapshot.text}"
     end
   end
 end

data/lib/tools/spawn_specialist.rb

@@ -21,9 +21,8 @@ module Tools
 
     # Builds description dynamically to include available specialists.
     def self.description
-      base = "Spawn a named specialist sub-agent to work on a task autonomously. " \
-        "The specialist has a predefined role, system prompt, and tool set. " \
-        "Its text messages are forwarded to you automatically. " \
+      base = "Spawn a specialist to work on a task. " \
+        "Its messages are forwarded to you. " \
         "Address it via @name to send follow-up instructions."
 
       registry = Agents::Registry.instance
@@ -39,16 +38,9 @@ module Tools
         type: "object",
         properties: {
           name: name_property,
-          task: {
-            type: "string",
-            description: "What the specialist should do (persisted as its first user message)"
-          },
-          expected_output: {
-            type: "string",
-            description: "Description of the expected deliverable"
-          }
+          task: {type: "string", description: "State the goal — the specialist knows its method."}
         },
-        required: %w[name task expected_output]
+        required: %w[name task]
       }
     end
 
@@ -57,7 +49,7 @@ module Tools
       registry = Agents::Registry.instance
       prop = {
         type: "string",
-        description: "Named specialist agent to spawn from the registry."
+        description: "Specialist to spawn."
       }
       prop[:enum] = registry.names if registry.any?
       prop
@@ -76,22 +68,20 @@ module Tools
     # persists the task as a user message, and queues background processing.
     # Returns immediately (non-blocking).
     #
-    # @param input [Hash<String, Object>] with "name", "task", and "expected_output"
+    # @param input [Hash<String, Object>] with "name" and "task"
     # @return [String] confirmation with child session ID
     # @return [Hash{Symbol => String}] with :error key on validation failure
     def execute(input)
       task = input["task"].to_s.strip
-      expected_output = input["expected_output"].to_s.strip
       name = input["name"].to_s.strip
 
       return {error: "Name cannot be blank"} if name.empty?
       return {error: "Task cannot be blank"} if task.empty?
-      return {error: "Expected output cannot be blank"} if expected_output.empty?
 
       definition = @agent_registry.get(name)
       return {error: "Unknown agent: #{name}"} unless definition
 
-      child = spawn_child(definition, task, expected_output)
+      child = spawn_child(definition, task)
       nickname = child.name
       "Specialist @#{nickname} spawned (session #{child.id}). " \
         "Its messages will appear in your conversation. " \
@@ -100,22 +90,21 @@ module Tools
 
     private
 
-    def spawn_child(definition, task, expected_output)
-      prompt = build_prompt(definition, expected_output)
+    def spawn_child(definition, task)
       child = Session.create!(
         parent_session_id: @session.id,
-        prompt: prompt,
+        prompt: build_prompt(definition),
         granted_tools: definition.tools
       )
-      child.create_user_event(task)
+      child.create_user_message(task)
       assign_nickname_via_brain(child)
       child.broadcast_children_update_to_parent
       AgentRequestJob.perform_later(child.id)
       child
     end
 
-    def build_prompt(definition, expected_output)
-      "#{definition.prompt}\n\n#{COMMUNICATION_INSTRUCTION}\n\n#{EXPECTED_DELIVERABLE_PREFIX}#{expected_output}"
+    def build_prompt(definition)
+      "#{definition.prompt}\n\n#{COMMUNICATION_INSTRUCTION}"
     end
   end
 end

data/lib/tools/spawn_subagent.rb

@@ -19,9 +19,8 @@ module Tools
     def self.tool_name = "spawn_subagent"
 
     def self.description
-      "Spawn a generic sub-agent to work on a task autonomously. " \
-        "The sub-agent inherits your conversation context, works independently, " \
-        "and its text messages are forwarded to you automatically. " \
+      "Spawn a sub-agent to work on a task. " \
+        "It inherits your conversation context and its messages are forwarded to you. " \
         "Address it via @nickname to send follow-up instructions."
     end
 
@@ -29,14 +28,7 @@ module Tools
       {
         type: "object",
         properties: {
-          task: {
-            type: "string",
-            description: "What the sub-agent should do (persisted as its first user message)"
-          },
-          expected_output: {
-            type: "string",
-            description: "Description of the expected deliverable"
-          },
+          task: {type: "string"},
           tools: {
             type: "array",
             items: {type: "string"},
@@ -45,7 +37,7 @@ module Tools
               "Valid tools: #{AgentLoop::STANDARD_TOOLS_BY_NAME.keys.join(", ")}"
           }
         },
-        required: %w[task expected_output]
+        required: %w[task]
       }
     end
 
@@ -58,22 +50,20 @@ module Tools
     # persists the task as a user message, and queues background processing.
     # Returns immediately after brain completes (blocking for ~200ms).
     #
-    # @param input [Hash<String, Object>] with "task", "expected_output", and optional "tools"
+    # @param input [Hash<String, Object>] with "task" and optional "tools"
     # @return [String] confirmation with child session ID and @nickname
     # @return [Hash{Symbol => String}] with :error key on validation failure
     def execute(input)
       task = input["task"].to_s.strip
-      expected_output = input["expected_output"].to_s.strip
 
       return {error: "Task cannot be blank"} if task.empty?
-      return {error: "Expected output cannot be blank"} if expected_output.empty?
 
       tools = normalize_tools(input["tools"])
 
       error = validate_tools(tools)
       return error if error
 
-      child = spawn_child(task, expected_output, tools)
+      child = spawn_child(task, tools)
       nickname = child.name
       "Sub-agent @#{nickname} spawned (session #{child.id}). " \
         "Its messages will appear in your conversation. " \
@@ -82,13 +72,13 @@ module Tools
 
     private
 
-    def spawn_child(task, expected_output, granted_tools)
+    def spawn_child(task, granted_tools)
       child = Session.create!(
         parent_session_id: @session.id,
-        prompt: "#{GENERIC_PROMPT}\n#{EXPECTED_DELIVERABLE_PREFIX}#{expected_output}",
+        prompt: GENERIC_PROMPT,
         granted_tools: granted_tools
       )
-      child.create_user_event(task)
+      child.create_user_message(task)
       assign_nickname_via_brain(child)
       child.broadcast_children_update_to_parent
       AgentRequestJob.perform_later(child.id)

data/lib/tools/subagent_prompts.rb

@@ -8,8 +8,6 @@ module Tools
       "When you finish, write your final summary and stop — no special tool needed. " \
       "If you need clarification, just ask — the parent can reply."
 
-    EXPECTED_DELIVERABLE_PREFIX = "Expected deliverable: "
-
     private
 
     # Runs the analytical brain synchronously to assign a nickname.

data/lib/tools/think.rb

@@ -21,24 +21,17 @@ module Tools
   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.description = "Think out loud or silently."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          thoughts: {
-            type: "string",
-            description: "Your reasoning, analysis, or internal monologue"
-          },
+          thoughts: {type: "string"},
           visibility: {
             type: "string",
             enum: ["inner", "aloud"],
-            description: "\"inner\" (default) for silent reasoning; \"aloud\" to narrate for the user"
+            description: "inner (default) is silent. aloud is shown to the user."
           }
         },
         required: ["thoughts"]

data/lib/tools/web_get.rb

@@ -15,13 +15,13 @@ module Tools
   class WebGet < Base
     def self.tool_name = "web_get"
 
-    def self.description = "Fetch content from a URL via HTTP GET and return the response body"
+    def self.description = "Fetch a URL."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          url: {type: "string", description: "The URL to fetch (http or https)"}
+          url: {type: "string"}
         },
         required: ["url"]
       }
@@ -47,10 +47,11 @@ module Tools
       end
 
       response = HTTParty.get(url, timeout: timeout, follow_redirects: false, ssl_ca_file: Certifi.where)
-      body = truncate_body(response.body.to_s)
       content_type = response.content_type || "text/plain"
+      body = response.body.to_s
+      body = strip_html_noise(body) if content_type.include?("text/html")
 
-      {body: body, content_type: content_type}
+      {body: truncate_body(body), content_type: content_type}
     rescue URI::InvalidURIError => error
       {error: "Invalid URL: #{error.message}"}
     rescue Net::OpenTimeout, Net::ReadTimeout
@@ -68,5 +69,23 @@ module Tools
       body.byteslice(0, max_bytes).scrub +
         "\n\n[Truncated: response exceeded #{max_bytes} bytes]"
     end
+
+    # First-stage noise stripping — runs before truncation so that the
+    # byte budget is spent on content, not on scripts/SVGs/metadata.
+    # Each pattern targets one tag type for easy maintenance.
+    # The decorator applies a second, structure-aware pass via Nokogiri.
+    HTML_NOISE_PATTERNS = [
+      %r{<head\b[^>]*>.*?</head>}mi,       # metadata, link/meta tags
+      %r{<script\b[^>]*>.*?</script>}mi,   # JavaScript
+      %r{<style\b[^>]*>.*?</style>}mi,      # CSS
+      %r{<svg\b[^>]*>.*?</svg>}mi,          # inline graphics
+      %r{<template\b[^>]*>.*?</template>}mi, # deferred markup
+      %r{<noscript\b[^>]*>.*?</noscript>}mi  # JS-disabled fallbacks
+    ].freeze
+    private_constant :HTML_NOISE_PATTERNS
+
+    def strip_html_noise(html)
+      HTML_NOISE_PATTERNS.reduce(html) { |text, pattern| text.gsub(pattern, "") }
+    end
   end
 end

data/lib/tools/write.rb

@@ -17,14 +17,14 @@ module Tools
   class Write < Base
     def self.tool_name = "write"
 
-    def self.description = "Create or overwrite a file. Creates intermediate directories automatically. Use for new files or full replacement."
+    def self.description = "Write file."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
-          content: {type: "string", description: "Full file content to write"}
+          path: {type: "string", description: "Relative paths resolve against working directory. Creates intermediate directories."},
+          content: {type: "string"}
         },
         required: %w[path content]
       }

data/lib/tui/cable_client.rb

@@ -129,9 +129,9 @@ module TUI
     # Requests the brain to recall (delete) a pending message so the user
     # can edit it before the LLM sees it.
     #
-    # @param event_id [Integer] database ID of the pending user_message event
-    def recall_pending(event_id)
-      send_action("recall_pending", {"event_id" => event_id})
+    # @param message_id [Integer] database ID of the pending user_message
+    def recall_pending(message_id)
+      send_action("recall_pending", {"message_id" => message_id})
     end
 
     # Requests interruption of the current tool execution. The server sets