anima-core 0.3.0 → 1.0.0

data/lib/tools/spawn_subagent.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+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}.
+  #
+  # 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"
+
+    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."
+    end
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          task: {
+            type: "string",
+            description: "What the sub-agent should do (emitted as its first user message)"
+          },
+          expected_output: {
+            type: "string",
+            description: "Description of the expected deliverable"
+          },
+          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). " \
+              "Valid tools: #{AgentLoop::STANDARD_TOOLS_BY_NAME.keys.join(", ")}"
+          }
+        },
+        required: %w[task expected_output]
+      }
+    end
+
+    # @param session [Session] the parent session spawning the sub-agent
+    def initialize(session:, **)
+      @session = session
+    end
+
+    # Creates a child session, emits the task as a user message, and
+    # queues background processing. Returns immediately (non-blocking).
+    #
+    # @param input [Hash<String, Object>] with "task", "expected_output", and optional "tools"
+    # @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
+
+      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)
+      "Sub-agent spawned (session #{child.id}). Result will arrive as a tool response."
+    end
+
+    private
+
+    def spawn_child(task, expected_output, granted_tools)
+      child = Session.create!(
+        parent_session_id: @session.id,
+        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))
+      AgentRequestJob.perform_later(child.id)
+      child
+    end
+
+    # Normalizes tool names to lowercase and removes duplicates.
+    # Returns non-array values unchanged for {#validate_tools} to catch.
+    #
+    # @param tools [Array, nil, Object] raw tools parameter from LLM
+    # @return [Array<String>, nil, Object] normalized tools
+    def normalize_tools(tools)
+      return nil unless tools
+      return tools unless tools.is_a?(Array)
+
+      tools.map { |tool| tool.to_s.downcase }.uniq
+    end
+
+    # @param tools [Array<String>, nil, Object] normalized tools parameter
+    # @return [Hash{Symbol => String}, nil] error hash if invalid, nil if valid
+    def validate_tools(tools)
+      return nil unless tools
+      return {error: "tools must be an array"} unless tools.is_a?(Array)
+
+      unknown = tools - AgentLoop::STANDARD_TOOLS_BY_NAME.keys
+      return {error: "Unknown tool: #{unknown.first}"} if unknown.any?
+
+      nil
+    end
+  end
+end

data/lib/tools/subagent_prompts.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Tools
+  # Shared prompt fragments 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."
+
+    EXPECTED_DELIVERABLE_PREFIX = "Expected deliverable: "
+  end
+end

data/lib/tools/web_get.rb

@@ -4,13 +4,10 @@ require "httparty"
 
 module Tools
   # Fetches content from a URL via HTTP GET. Returns the response body
-  # as plain text, truncated to {MAX_RESPONSE_BYTES} to prevent memory issues.
+  # as plain text, truncated to {Anima::Settings.max_web_response_bytes} to prevent memory issues.
   #
   # Only http and https schemes are allowed.
   class WebGet < Base
-    MAX_RESPONSE_BYTES = 100_000
-    REQUEST_TIMEOUT = 10
-
     def self.tool_name = "web_get"
 
     def self.description = "Fetch content from a URL via HTTP GET and return the response body"
@@ -35,17 +32,18 @@ module Tools
     private
 
     def validate_and_fetch(url)
+      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: REQUEST_TIMEOUT, follow_redirects: false).body.to_s)
+      truncate_body(HTTParty.get(url, timeout: timeout, follow_redirects: false).body.to_s)
     rescue URI::InvalidURIError => error
       {error: "Invalid URL: #{error.message}"}
     rescue Net::OpenTimeout, Net::ReadTimeout
-      {error: "Request timed out after #{REQUEST_TIMEOUT} seconds"}
+      {error: "Request timed out after #{timeout} seconds"}
     rescue Errno::ECONNREFUSED
       {error: "Connection refused: #{url}"}
     rescue => error
@@ -53,10 +51,11 @@ module Tools
     end
 
     def truncate_body(body)
-      return body if body.bytesize <= MAX_RESPONSE_BYTES
+      max_bytes = Anima::Settings.max_web_response_bytes
+      return body if body.bytesize <= max_bytes
 
-      body.byteslice(0, MAX_RESPONSE_BYTES) +
-        "\n\n[Truncated: response exceeded #{MAX_RESPONSE_BYTES} bytes]"
+      body.byteslice(0, max_bytes) +
+        "\n\n[Truncated: response exceeded #{max_bytes} bytes]"
     end
   end
 end