anima-core 0.2.1 → 1.0.0

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

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

data/lib/tools/write.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Tools
+  # Creates or overwrites files with automatic intermediate directory creation.
+  # Writes content exactly as given — no line ending normalization, no BOM
+  # handling. Full replacement only; no append or merge.
+  #
+  # @example Creating a new file
+  #   tool.execute("path" => "config/new.yml", "content" => "key: value\n")
+  #   # => "Wrote 11 bytes to /home/user/project/config/new.yml"
+  #
+  # @example Overwriting an existing file
+  #   tool.execute("path" => "README.md", "content" => "# Title\n")
+  #   # => "Wrote 9 bytes to /home/user/project/README.md"
+  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.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"}
+        },
+        required: %w[path content]
+      }
+    end
+
+    # @param shell_session [ShellSession, nil] provides working directory for resolving relative paths
+    def initialize(shell_session: nil, **)
+      @working_directory = shell_session&.pwd
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] confirmation with bytes written and resolved path
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      path, content = extract_params(input)
+      return {error: "Path cannot be blank"} if path.empty?
+
+      path = resolve_path(path)
+
+      error = validate_target(path)
+      return error if error
+
+      write_file(path, content)
+    end
+
+    private
+
+    def extract_params(input)
+      path = input["path"].to_s.strip
+      content = input["content"].to_s
+      [path, content]
+    end
+
+    def resolve_path(path)
+      if @working_directory
+        File.expand_path(path, @working_directory)
+      else
+        File.expand_path(path)
+      end
+    end
+
+    def validate_target(path)
+      return {error: "Is a directory: #{path}"} if File.directory?(path)
+      {error: "Not writable: #{path}"} if File.exist?(path) && !File.writable?(path)
+    end
+
+    def write_file(path, content)
+      FileUtils.mkdir_p(File.dirname(path))
+      bytes = File.write(path, content)
+      "Wrote #{bytes} bytes to #{path}"
+    rescue Errno::EACCES
+      {error: "Permission denied: #{path}"}
+    rescue Errno::ENOSPC
+      {error: "No space left on device: #{path}"}
+    rescue Errno::EROFS
+      {error: "Read-only file system: #{path}"}
+    end
+  end
+end