anima-core 1.0.2 → 1.1.1

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
@@ -22,24 +27,30 @@ 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
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API.
+    #   Supports optional "timeout" key (seconds) to override the global
+    #   web_request_timeout setting.
+    # @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)
+      validate_and_fetch(input["url"].to_s, timeout: input["timeout"])
     end
 
     private
 
-    def validate_and_fetch(url)
-      timeout = Anima::Settings.web_request_timeout
+    def validate_and_fetch(url, timeout: nil)
+      timeout ||= Anima::Settings.web_request_timeout
       scheme = URI.parse(url).scheme
 
       unless %w[http https].include?(scheme)
         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 +65,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