anima-core 1.0.2 → 1.1.0

data/lib/tools/remember.rb

@@ -0,0 +1,179 @@
+# 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
+  # at the edges — sharp fovea, blurry periphery.
+  #
+  # Output structure:
+  #   [Previous snapshots — compressed context before]
+  #   [Events 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
+  # viewport recall snippets. This tool drills down into the full context.
+  #
+  # @example
+  #   remember(event_id: 42)
+  class Remember < Base
+    # Events around the target to include at full resolution.
+    # ±10 events provides sharp foveal detail while keeping output readable.
+    CONTEXT_WINDOW = 20
+
+    ROLE_LABELS = {
+      "user_message" => "User",
+      "agent_message" => "Assistant",
+      "system_message" => "System"
+    }.freeze
+
+    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.input_schema
+      {
+        type: "object",
+        properties: {
+          event_id: {
+            type: "integer",
+            description: "The event ID to zoom into (from search results or recall snippets)"
+          }
+        },
+        required: ["event_id"]
+      }
+    end
+
+    def initialize(session:, **)
+      @session = session
+    end
+
+    # @param input [Hash] with "event_id"
+    # @return [String] fractal-resolution window around the target event
+    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
+
+      build_fractal_window(target)
+    end
+
+    private
+
+    # Assembles the three-zone fractal window.
+    #
+    # @param target [Event] the center event
+    # @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
+
+      sections = build_sections(
+        target_session: target_session,
+        center_events: center_events,
+        target_id: target.id,
+        first_center_id: first_center_id,
+        last_center_id: last_center_id
+      )
+      sections.join("\n")
+    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:)
+      sections = [session_header(target_session)]
+
+      append_snapshot_sections(sections, target_session.snapshots
+        .where("to_event_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) }
+
+      append_snapshot_sections(sections, target_session.snapshots
+        .where("from_event_id > ?", last_center_id)
+        .chronological.first(3), label: "FOLLOWING CONTEXT")
+
+      sections
+    end
+
+    def session_header(target_session)
+      label = target_session.name || "Session ##{target_session.id}"
+      "── recalled from: #{label} ──"
+    end
+
+    # Appends snapshot sections if any exist.
+    def append_snapshot_sections(sections, snapshots, label:)
+      return if snapshots.empty?
+
+      sections << "── #{label} (compressed) ──"
+      snapshots.each { |snapshot| sections << format_snapshot(snapshot) }
+    end
+
+    # Fetches conversation events around the target within a fixed window.
+    #
+    # @return [Array<Event>] chronologically ordered
+    def fetch_center_events(target, target_session)
+      half = CONTEXT_WINDOW / 2
+      scope = target_session.events.context_events.deliverable
+      target_id = target.id
+
+      before = scope.where("id <= ?", target_id).reorder(id: :desc).limit(half + 1).to_a.reverse
+      after = scope.where("id > ?", target_id).reorder(id: :asc).limit(half).to_a
+
+      before + after
+    end
+
+    # Renders a center event at full resolution.
+    # Conversation events 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)
+    # @return [String]
+    def render_center_event(event, target_id)
+      marker = (event.id == target_id) ? "→" : " "
+      prefix = "#{marker} event #{event.id}"
+
+      "#{prefix} #{format_event_content(event)}"
+    end
+
+    # Formats event content based on type.
+    def format_event_content(event)
+      data = event.payload
+      content = data["content"]
+
+      if ROLE_LABELS.key?(event.event_type)
+        "#{ROLE_LABELS[event.event_type]}: #{content}"
+      elsif event.event_type == "tool_call"
+        format_tool_call(data)
+      elsif event.event_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
+        "Think: #{data.dig("tool_input", "thoughts")}"
+      else
+        "Tool: #{data["tool_name"]}(#{data["tool_input"].to_json.truncate(200)})"
+      end
+    end
+
+    # Formats a snapshot as compressed context.
+    #
+    # @param snapshot [Snapshot]
+    # @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}"
+    end
+  end
+end

data/lib/tools/spawn_specialist.rb

@@ -5,7 +5,12 @@ module Tools
   # The specialist has a predefined system prompt and tool set defined
   # in its Markdown definition file under agents/.
   #
-  # Results are delivered back through {Tools::ReturnResult}.
+  # Nickname assignment is handled by the {AnalyticalBrain::Runner} which
+  # runs synchronously at spawn time, generating a unique nickname based
+  # on the task — same as generic sub-agents.
+  #
+  # Results are delivered through natural text messages routed by
+  # {Events::Subscribers::SubagentMessageRouter}.
   #
   # @see Agents::Registry
   # @see Agents::Definition
@@ -17,7 +22,9 @@ 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."
+        "The specialist has a predefined role, system prompt, and tool set. " \
+        "Its text messages are forwarded to you automatically. " \
+        "Address it via @name to send follow-up instructions."
 
       registry = Agents::Registry.instance
       return base unless registry.any?
@@ -34,7 +41,7 @@ module Tools
           name: name_property,
           task: {
             type: "string",
-            description: "What the specialist should do (emitted as its first user message)"
+            description: "What the specialist should do (persisted as its first user message)"
           },
           expected_output: {
             type: "string",
@@ -66,7 +73,8 @@ module Tools
     end
 
     # Creates a child session with the specialist's predefined prompt and tools,
-    # emits the task as a user message, and queues background processing.
+    # 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"
     # @return [String] confirmation with child session ID
@@ -84,7 +92,10 @@ module Tools
       return {error: "Unknown agent: #{name}"} unless definition
 
       child = spawn_child(definition, task, expected_output)
-      "Specialist '#{name}' spawned (session #{child.id}). Result will arrive as a tool response."
+      nickname = child.name
+      "Specialist @#{nickname} spawned (session #{child.id}). " \
+        "Its messages will appear in your conversation. " \
+        "Reply with @#{nickname} to send it instructions."
     end
 
     private
@@ -94,16 +105,17 @@ module Tools
       child = Session.create!(
         parent_session_id: @session.id,
         prompt: prompt,
-        granted_tools: definition.tools,
-        name: definition.name
+        granted_tools: definition.tools
       )
-      Events::Bus.emit(Events::UserMessage.new(content: task, session_id: child.id))
+      child.create_user_event(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#{RETURN_INSTRUCTION}\n\n#{EXPECTED_DELIVERABLE_PREFIX}#{expected_output}"
+      "#{definition.prompt}\n\n#{COMMUNICATION_INSTRUCTION}\n\n#{EXPECTED_DELIVERABLE_PREFIX}#{expected_output}"
     end
   end
 end

data/lib/tools/spawn_subagent.rb

@@ -3,21 +3,26 @@
 module Tools
   # Spawns a generic child session that works on a task autonomously.
   # The sub-agent inherits the parent's viewport context at fork time,
-  # runs via {AgentRequestJob}, and delivers results back
-  # through {Tools::ReturnResult}.
+  # runs via {AgentRequestJob}, and communicates with the parent through
+  # natural text messages routed by {Events::Subscribers::SubagentMessageRouter}.
+  #
+  # Nickname assignment is handled by the {AnalyticalBrain::Runner} which
+  # runs synchronously at spawn time — the same brain that manages skills,
+  # goals, and workflows for the main session.
   #
   # For named specialists with predefined prompts and tools, see {SpawnSpecialist}.
   class SpawnSubagent < Base
     include SubagentPrompts
 
-    GENERIC_PROMPT = "You are a focused sub-agent. #{RETURN_INSTRUCTION}\n"
+    GENERIC_PROMPT = "You are a focused sub-agent. #{COMMUNICATION_INSTRUCTION}\n"
 
     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 returns results as a tool response when done."
+        "and its text messages are forwarded to you automatically. " \
+        "Address it via @nickname to send follow-up instructions."
     end
 
     def self.input_schema
@@ -26,7 +31,7 @@ module Tools
         properties: {
           task: {
             type: "string",
-            description: "What the sub-agent should do (emitted as its first user message)"
+            description: "What the sub-agent should do (persisted as its first user message)"
           },
           expected_output: {
             type: "string",
@@ -36,7 +41,7 @@ module Tools
             type: "array",
             items: {type: "string"},
             description: "Tool names to grant the sub-agent. " \
-              "Omit for all standard tools. Empty array for pure reasoning (return_result only). " \
+              "Omit for all standard tools. Empty array for pure reasoning. " \
               "Valid tools: #{AgentLoop::STANDARD_TOOLS_BY_NAME.keys.join(", ")}"
           }
         },
@@ -49,11 +54,12 @@ module Tools
       @session = session
     end
 
-    # Creates a child session, emits the task as a user message, and
-    # queues background processing. Returns immediately (non-blocking).
+    # Creates a child session, runs the analytical brain to assign a nickname,
+    # 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"
-    # @return [String] confirmation with child session ID
+    # @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
@@ -68,7 +74,10 @@ module Tools
       return error if error
 
       child = spawn_child(task, expected_output, tools)
-      "Sub-agent spawned (session #{child.id}). Result will arrive as a tool response."
+      nickname = child.name
+      "Sub-agent @#{nickname} spawned (session #{child.id}). " \
+        "Its messages will appear in your conversation. " \
+        "Reply with @#{nickname} to send it instructions."
     end
 
     private
@@ -79,7 +88,9 @@ module Tools
         prompt: "#{GENERIC_PROMPT}\n#{EXPECTED_DELIVERABLE_PREFIX}#{expected_output}",
         granted_tools: granted_tools
       )
-      Events::Bus.emit(Events::UserMessage.new(content: task, session_id: child.id))
+      child.create_user_event(task)
+      assign_nickname_via_brain(child)
+      child.broadcast_children_update_to_parent
       AgentRequestJob.perform_later(child.id)
       child
     end

data/lib/tools/subagent_prompts.rb

@@ -1,12 +1,29 @@
 # frozen_string_literal: true
 
 module Tools
-  # Shared prompt fragments for tools that spawn sub-agent sessions.
+  # Shared prompt fragments and nickname logic for tools that spawn sub-agent sessions.
   # Included by {SpawnSubagent} and {SpawnSpecialist} to avoid duplication.
   module SubagentPrompts
-    RETURN_INSTRUCTION = "Complete the assigned task, then call the return_result tool with your deliverable. " \
-      "Do not ask follow-up questions — work with the context you have."
+    COMMUNICATION_INSTRUCTION = "Your text messages are automatically forwarded to the parent agent. " \
+      "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.
+    # Falls back to a sequential "agent-N" name on any failure.
+    def assign_nickname_via_brain(child)
+      AnalyticalBrain::Runner.new(child).call
+      child.reload
+    rescue => error
+      Rails.logger.warn("Sub-agent nickname assignment failed: #{error.message}")
+      child.update!(name: fallback_nickname)
+    end
+
+    def fallback_nickname
+      "agent-#{@session.child_sessions.count}"
+    end
   end
 end

data/lib/tools/web_get.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
+require "certifi"
 require "httparty"
 
 module Tools
-  # Fetches content from a URL via HTTP GET. Returns the response body
-  # as plain text, truncated to {Anima::Settings.max_web_response_bytes} to prevent memory issues.
+  # Fetches content from a URL via HTTP GET. Returns a structured result with
+  # the response body and Content-Type header so that {ToolDecorator} can apply
+  # format-specific conversion (HTML → Markdown, JSON → TOON, etc.).
+  #
+  # The body is truncated to {Anima::Settings.max_web_response_bytes} before
+  # decoration to cap memory usage on large responses.
   #
   # Only http and https schemes are allowed.
   class WebGet < Base
@@ -23,8 +28,8 @@ module Tools
     end
 
     # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
-    # @return [String] response body (possibly truncated)
-    # @return [Hash] with :error key on failure
+    # @return [Hash] `{body: String, content_type: String}` on success
+    # @return [Hash] `{error: String}` on failure
     def execute(input)
       validate_and_fetch(input["url"].to_s)
     end
@@ -39,7 +44,11 @@ module Tools
         return {error: "Only http and https URLs are supported, got: #{scheme.inspect}"}
       end
 
-      truncate_body(HTTParty.get(url, timeout: timeout, follow_redirects: false).body.to_s)
+      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: body, content_type: content_type}
     rescue URI::InvalidURIError => error
       {error: "Invalid URL: #{error.message}"}
     rescue Net::OpenTimeout, Net::ReadTimeout
@@ -54,7 +63,7 @@ module Tools
       max_bytes = Anima::Settings.max_web_response_bytes
       return body if body.bytesize <= max_bytes
 
-      body.byteslice(0, max_bytes) +
+      body.byteslice(0, max_bytes).scrub +
         "\n\n[Truncated: response exceeded #{max_bytes} bytes]"
     end
   end