anima-core 0.3.0 → 1.0.1

data/lib/tools/mcp_tool.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Tools
+  # Wraps a single MCP server tool for use with {Tools::Registry}.
+  # Registered as an instance (not a class) — the Registry calls
+  # +#execute+ directly without instantiation, since MCP tools
+  # carry their own client reference and are effectively stateless
+  # from the LLM's perspective.
+  #
+  # Implements the same duck-typed interface as {Tools::Base} subclasses:
+  # - +#tool_name+ — unique identifier
+  # - +#description+ — human-readable description
+  # - +#input_schema+ — JSON Schema for parameters
+  # - +#schema+ — Anthropic API tool definition
+  # - +#execute(input)+ — run the tool
+  #
+  # Tool names are namespaced as `<server_name>__<tool_name>` to prevent
+  # collisions between servers and with built-in tools.
+  #
+  # @example
+  #   wrapper = Tools::McpTool.new(
+  #     server_name: "mythonix",
+  #     mcp_client: client,
+  #     mcp_tool: client.tools.first
+  #   )
+  #   wrapper.tool_name  # => "mythonix__create_image"
+  #   wrapper.execute({"prompt" => "a red dragon"})
+  class McpTool
+    # Separator between server name and tool name in namespaced identifiers.
+    NAMESPACE_SEPARATOR = "__"
+
+    # @return [String] namespaced tool identifier (<server>__<tool>)
+    attr_reader :tool_name
+
+    # @param server_name [String] MCP server name from config
+    # @param mcp_client [MCP::Client] the client instance for this server
+    # @param mcp_tool [MCP::Client::Tool] tool metadata from the server
+    def initialize(server_name:, mcp_client:, mcp_tool:)
+      @tool_name = "#{server_name}#{NAMESPACE_SEPARATOR}#{mcp_tool.name}"
+      @mcp_client = mcp_client
+      @mcp_tool = mcp_tool
+    end
+
+    # @return [String] tool description from the MCP server
+    def description
+      @mcp_tool.description
+    end
+
+    # @return [Hash] JSON Schema for tool input parameters
+    def input_schema
+      @mcp_tool.input_schema
+    end
+
+    # Builds the schema hash expected by the Anthropic tools API.
+    # @return [Hash] with :name, :description, and :input_schema keys
+    def schema
+      {name: tool_name, description: description, input_schema: input_schema}
+    end
+
+    # Calls the MCP server tool and normalizes the response.
+    #
+    # @param input [Hash] tool input parameters from the LLM
+    # @return [String] normalized tool output
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      response = @mcp_client.call_tool(tool: @mcp_tool, arguments: input)
+      normalize_response(response)
+    rescue MCP::Client::RequestHandlerError => error
+      {error: "#{tool_name}: #{error.message}"}
+    end
+
+    private
+
+    # Extracts content from an MCP tool response (JSON-RPC envelope).
+    # Checks the `isError` flag and routes accordingly.
+    #
+    # @param response [Hash] full JSON-RPC response from MCP client
+    # @return [String] concatenated text content
+    # @return [Hash] with :error key if the response indicates an error
+    def normalize_response(response)
+      result = response["result"] || response
+      error = result["isError"]
+
+      text = extract_text(result)
+      error ? {error: "#{tool_name}: #{text}"} : text
+    end
+
+    # Extracts human-readable text from MCP content blocks.
+    # MCP responses contain an array of typed content blocks.
+    #
+    # @param result [Hash] MCP result containing "content" array
+    # @return [String] concatenated text from all content blocks
+    def extract_text(result)
+      content = result["content"]
+
+      return result.to_json unless content
+
+      case content
+      when Array
+        content.filter_map { |block|
+          case block["type"]
+          when "text" then block["text"]
+          when "image" then "[image: #{block["mimeType"]}]"
+          else block.to_json
+          end
+        }.join("\n")
+      when String
+        content
+      else
+        content.to_json
+      end
+    end
+  end
+end

data/lib/tools/read.rb

@@ -4,7 +4,7 @@ module Tools
   # Reads file contents with smart truncation and offset/limit paging.
   # Returns plain text without line numbers, normalized to LF line endings.
   #
-  # Truncation limits: `MAX_LINES` lines or `MAX_BYTES` bytes, whichever
+  # Truncation limits: `Anima::Settings.max_read_lines` lines or `Anima::Settings.max_read_bytes` bytes, whichever
   # hits first. When truncated, appends a continuation hint with the next
   # offset value so the agent can page through large files.
   #
@@ -16,9 +16,6 @@ module Tools
   #   tool.execute("path" => "large.log", "offset" => 2001, "limit" => 500)
   #   # => "line 2001 content\n..."
   class Read < Base
-    MAX_LINES = 2_000
-    MAX_BYTES = 50_000
-
     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."
@@ -29,7 +26,7 @@ module Tools
         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 number of lines to read (default: 2000, also limited by #{MAX_BYTES} byte cap)"}
+          limit: {type: "integer", description: "Maximum lines to read (subject to line and byte caps from config)"}
         },
         required: ["path"]
       }
@@ -61,7 +58,7 @@ module Tools
       path = input["path"].to_s.strip
       offset = [input["offset"].to_i, 1].max
       raw_limit = input["limit"]
-      limit = raw_limit ? [raw_limit.to_i, 1].max : MAX_LINES
+      limit = raw_limit ? [raw_limit.to_i, 1].max : Anima::Settings.max_read_lines
       [path, offset, limit]
     end
 
@@ -81,15 +78,15 @@ module Tools
 
     # Reads the file, normalizes line endings, and applies truncation limits.
     # Two limits are enforced as first-hit-wins: line count and byte size.
-    # A single line exceeding `MAX_BYTES` is rejected outright (likely minified).
-    # Files larger than `MAX_READ_SIZE` are rejected to avoid memory exhaustion.
-    MAX_READ_SIZE = 10 * 1024 * 1024 # 10 MB
+    # A single line exceeding `Anima::Settings.max_read_bytes` is rejected outright (likely minified).
+    # Files larger than max_file_size are rejected to avoid memory exhaustion.
 
     def read_file(path, offset, limit)
       file_size = File.size(path)
-      if file_size > MAX_READ_SIZE
+      max_size = Anima::Settings.max_file_size
+      if file_size > max_size
         return {error: "File is #{file_size} bytes (#{file_size / 1_048_576} MB). " \
-                       "Max readable size is #{MAX_READ_SIZE / 1_048_576} MB. " \
+                       "Max readable size is #{max_size / 1_048_576} MB. " \
                        "Use bash tool with: head -n #{offset + limit} #{path} | tail -n +#{offset}"}
       end
 
@@ -99,7 +96,7 @@ module Tools
       start_index = offset - 1
       return "[File has #{lines.size} lines. Offset #{offset} is beyond end of file.]" if start_index >= lines.size
 
-      window = lines[start_index, [limit, MAX_LINES].min]
+      window = lines[start_index, [limit, Anima::Settings.max_read_lines].min]
 
       error = check_oversized_lines(window, offset, path)
       return error if error
@@ -112,11 +109,12 @@ module Tools
     end
 
     def check_oversized_lines(window, offset, path)
-      index = window.index { |line| line.bytesize > MAX_BYTES }
+      max_bytes = Anima::Settings.max_read_bytes
+      index = window.index { |line| line.bytesize > max_bytes }
       return unless index
 
       line_num = offset + index
-      {error: "Line #{line_num} exceeds #{MAX_BYTES} bytes (likely minified). " \
+      {error: "Line #{line_num} exceeds #{max_bytes} bytes (likely minified). " \
               "Use bash tool with: sed -n '#{line_num}p' #{path}"}
     end
 
@@ -131,15 +129,16 @@ module Tools
       end
     end
 
-    # Accumulates lines until `MAX_BYTES` would be exceeded.
+    # Accumulates lines until the byte cap would be exceeded.
     # @return [Array(String, Integer)] accumulated text and number of lines included
     def accumulate_lines(window)
+      max_bytes = Anima::Settings.max_read_bytes
       output = +""
       bytes = 0
       count = 0
 
       window.each_with_index do |line, index|
-        break if bytes + line.bytesize > MAX_BYTES && index > 0
+        break if bytes + line.bytesize > max_bytes && index > 0
 
         output << line
         bytes += line.bytesize

data/lib/tools/registry.rb

@@ -4,16 +4,17 @@ module Tools
   class UnknownToolError < StandardError; end
 
   # Manages tool registration, schema export, and dispatch.
-  # Tools are registered by class and looked up by name at execution time.
-  # An optional context hash is passed to each tool's constructor, allowing
-  # shared dependencies (e.g. a {ShellSession}) to reach tools that need them.
+  # Accepts both tool classes (e.g. {Tools::Base} subclasses) and tool
+  # instances (e.g. {Tools::McpTool}) via duck typing. Classes are
+  # instantiated with the registry's context on each execution; instances
+  # are called directly since they carry their own state.
   #
   # @example
   #   registry = Tools::Registry.new(context: {shell_session: my_shell})
   #   registry.register(Tools::Bash)
   #   registry.execute("bash", {"command" => "ls"})
   class Registry
-    # @return [Hash{String => Class}] registered tool classes keyed by name
+    # @return [Hash{String => Class, Object}] registered tools keyed by name
     attr_reader :tools
 
     # @param context [Hash] keyword arguments forwarded to every tool constructor
@@ -22,11 +23,11 @@ module Tools
       @context = context
     end
 
-    # Register a tool class. The class must respond to .tool_name.
-    # @param tool_class [Class<Tools::Base>] the tool class to register
+    # Register a tool class or instance. Must respond to +tool_name+ and +schema+.
+    # @param tool [Class<Tools::Base>, #tool_name] tool class or duck-typed instance
     # @return [void]
-    def register(tool_class)
-      @tools[tool_class.tool_name] = tool_class
+    def register(tool)
+      @tools[tool.tool_name] = tool
     end
 
     # @return [Array<Hash>] schema array for the Anthropic tools API parameter
@@ -34,16 +35,17 @@ module Tools
       @tools.values.map(&:schema)
     end
 
-    # Instantiate and execute a tool by name. The registry's context is
-    # forwarded to the tool constructor as keyword arguments.
+    # Execute a tool by name. Classes are instantiated with the registry's
+    # context; instances are called directly.
     #
     # @param name [String] registered tool name
     # @param input [Hash] tool input parameters
     # @return [String, Hash] tool execution result
     # @raise [UnknownToolError] if no tool is registered with the given name
     def execute(name, input)
-      tool_class = @tools.fetch(name) { raise UnknownToolError, "Unknown tool: #{name}" }
-      tool_class.new(**@context).execute(input)
+      tool = @tools.fetch(name) { raise UnknownToolError, "Unknown tool: #{name}" }
+      instance = tool.is_a?(Class) ? tool.new(**@context) : tool
+      instance.execute(input)
     end
 
     # @param name [String] tool name to check

data/lib/tools/request_feature.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # 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
+    # @return [String] tool identifier used in the Anthropic API schema
+    def self.tool_name = "request_feature"
+
+    # @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 [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?"}
+        },
+        required: %w[title description]
+      }
+    end
+
+    # @param input [Hash<String, Object>] with +"title"+ and +"description"+ keys
+    # @return [String] formatted gh command output (stdout, stderr, and exit code if non-zero)
+    # @return [Hash{Symbol => String}] with +:error+ key on validation or repo resolution failure
+    def execute(input)
+      title = input["title"].to_s.strip
+      description = input["description"].to_s.strip
+      return {error: "Title cannot be blank"} if title.empty?
+      return {error: "Description cannot be blank"} if description.empty?
+
+      repo = resolve_repo
+      return repo if repo.is_a?(Hash)
+
+      run_gh(repo, title, description)
+    end
+
+    private
+
+    # Resolves the target repository: config.toml setting first, then git remote origin.
+    # @return [String] owner/repo identifier
+    # @return [Hash{Symbol => String}] error hash when no repository can be determined
+    def resolve_repo
+      repo = settings_repo || git_remote_repo
+      return {error: "Cannot determine repository. Set [github] repo in config.toml or ensure a git remote origin exists."} unless repo
+
+      repo
+    end
+
+    # @return [String, nil] repo from config.toml, nil when not configured
+    def settings_repo
+      value = Anima::Settings.github_repo
+      value unless value.to_s.strip.empty?
+    rescue Anima::Settings::MissingSettingError
+      nil
+    end
+
+    # @return [String, nil] owner/repo parsed from +git remote get-url origin+
+    def git_remote_repo
+      url, _status = Open3.capture2("git", "remote", "get-url", "origin")
+      parse_owner_repo(url.strip)
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # Extracts +owner/repo+ from common GitHub remote URL formats.
+    # @param url [String] SSH or HTTPS remote URL
+    # @return [String, nil] owner/repo or nil when the URL is not recognizable
+    def parse_owner_repo(url)
+      case url
+      when %r{github\.com[:/]([^/]+/[^/]+?)(?:\.git)?$}
+        Regexp.last_match(1)
+      end
+    end
+
+    # Invokes +gh issue create+ and returns the formatted output.
+    # @param repo [String] owner/repo identifier
+    # @param title [String] issue title
+    # @param description [String] issue body
+    # @return [String] formatted command output
+    def run_gh(repo, title, description)
+      stdout, stderr, status = Open3.capture3(
+        "gh", "issue", "create",
+        "--repo", repo,
+        "--label", Anima::Settings.github_label,
+        "--title", title,
+        "--body", description
+      )
+      format_result(stdout, stderr, status.exitstatus)
+    end
+
+    # Combines stdout, stderr, and exit code into a single string response.
+    # @param stdout [String] captured standard output
+    # @param stderr [String] captured standard error
+    # @param exit_code [Integer] process exit status
+    # @return [String] joined non-empty parts separated by blank lines
+    def format_result(stdout, stderr, exit_code)
+      out = stdout.strip
+      err = stderr.strip
+      parts = []
+      parts << out unless out.empty?
+      parts << err unless err.empty?
+      parts << "exit_code: #{exit_code}" unless exit_code.zero?
+      parts.join("\n\n")
+    end
+  end
+end

data/lib/tools/return_result.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Tools
+  # Sub-agent-only tool that delivers a completed result back to the
+  # parent session as a tool_call/tool_response pair. The parent agent
+  # sees it as if it called a tool itself — no custom event types needed.
+  #
+  # Never registered for main sessions — only sub-agents see this tool.
+  class ReturnResult < Base
+    def self.tool_name = "return_result"
+
+    def self.description = "Return your completed result to the parent agent. " \
+      "Call this when you have fulfilled the assigned task."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          result: {
+            type: "string",
+            description: "The completed deliverable to send back to the parent agent"
+          }
+        },
+        required: ["result"]
+      }
+    end
+
+    # @param session [Session] the sub-agent session returning a result
+    def initialize(session:, **)
+      @session = session
+    end
+
+    # Emits a tool_call/tool_response pair in the parent session so the
+    # parent agent sees the sub-agent result as a regular tool interaction.
+    #
+    # @param input [Hash<String, Object>] with "result" key
+    # @return [String, Hash] confirmation message, or Hash with :error key on failure
+    def execute(input)
+      result = input["result"].to_s.strip
+      return {error: "Result cannot be blank"} if result.empty?
+
+      parent = @session.parent_session
+      return {error: "No parent session — only sub-agents can return results"} unless parent
+
+      tool_use_id = "toolu_subagent_#{@session.id}"
+      task = extract_task
+      # Specialists are spawned with a name from the registry; generic sub-agents have nil name.
+      origin_tool = @session.name ? SpawnSpecialist.tool_name : SpawnSubagent.tool_name
+
+      Events::Bus.emit(Events::ToolCall.new(
+        content: "Sub-agent result (session #{@session.id})",
+        tool_name: origin_tool,
+        tool_input: {"task" => task, "session_id" => @session.id},
+        tool_use_id: tool_use_id,
+        session_id: parent.id
+      ))
+
+      Events::Bus.emit(Events::ToolResponse.new(
+        content: result,
+        tool_name: origin_tool,
+        tool_use_id: tool_use_id,
+        session_id: parent.id
+      ))
+
+      "Result delivered to parent session #{parent.id}."
+    end
+
+    private
+
+    # Extracts the original task from the sub-agent's first user message.
+    # @return [String]
+    def extract_task
+      @session.events
+        .where(event_type: "user_message")
+        .order(:id)
+        .pick(:payload)
+        &.dig("content")
+        .to_s
+    end
+  end
+end

data/lib/tools/spawn_specialist.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Tools
+  # Spawns a named specialist sub-agent from the agent registry.
+  # 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}.
+  #
+  # @see Agents::Registry
+  # @see Agents::Definition
+  class SpawnSpecialist < Base
+    include SubagentPrompts
+
+    def self.tool_name = "spawn_specialist"
+
+    # 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."
+
+      registry = Agents::Registry.instance
+      return base unless registry.any?
+
+      specialist_list = registry.catalog.map { |name, desc| "- #{name}: #{desc}" }.join("\n")
+      "#{base}\n\nAvailable specialists:\n#{specialist_list}"
+    end
+
+    # Builds input schema dynamically to include named agent enum.
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          name: name_property,
+          task: {
+            type: "string",
+            description: "What the specialist should do (emitted as its first user message)"
+          },
+          expected_output: {
+            type: "string",
+            description: "Description of the expected deliverable"
+          }
+        },
+        required: %w[name task expected_output]
+      }
+    end
+
+    # @return [Hash] JSON Schema property for the name parameter
+    def self.name_property
+      registry = Agents::Registry.instance
+      prop = {
+        type: "string",
+        description: "Named specialist agent to spawn from the registry."
+      }
+      prop[:enum] = registry.names if registry.any?
+      prop
+    end
+
+    private_class_method :name_property
+
+    # @param session [Session] the parent session spawning the specialist
+    # @param agent_registry [Agents::Registry, nil] injectable for testing
+    def initialize(session:, agent_registry: nil, **)
+      @session = session
+      @agent_registry = agent_registry || Agents::Registry.instance
+    end
+
+    # Creates a child session with the specialist's predefined prompt and tools,
+    # emits the task as a user message, and queues background processing.
+    #
+    # @param input [Hash<String, Object>] with "name", "task", and "expected_output"
+    # @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)
+      "Specialist '#{name}' spawned (session #{child.id}). Result will arrive as a tool response."
+    end
+
+    private
+
+    def spawn_child(definition, task, expected_output)
+      prompt = build_prompt(definition, expected_output)
+      child = Session.create!(
+        parent_session_id: @session.id,
+        prompt: prompt,
+        granted_tools: definition.tools,
+        name: definition.name
+      )
+      Events::Bus.emit(Events::UserMessage.new(content: task, session_id: child.id))
+      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}"
+    end
+  end
+end