agentf 0.4.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a6b455ea4e8d08419665c731414589a39173932f0bdf70788b76cfbcc7c0380
-  data.tar.gz: 4552007bea3fbb27e4940f09542f76e557bdac18f06391dfcb7db6914adc9017
+  metadata.gz: 6072a9a176fba8e2376b10cc125d78d450057c90c4aa5d95158797429504d1f5
+  data.tar.gz: f66dc58d0030e1ba289d3f7046811190b9ae818aca61021729c9da12d19e710c
 SHA512:
-  metadata.gz: 37efe8cb9847156d5d0e93ee981c108fddab0940eab62fe60bb609e6fc68f799c14fd84f08214263ec4e98d05b617b5be7cd8d035d8a9352d7c639b4737947bb
-  data.tar.gz: c26f29b7059e1997f62b1a9b25c628c6ff25832309e8766ba2d076ebdf8333ca7ac3206145ae4e05f623c84aa6771c316970b5377e0b48de2980dff3e5c077df
+  metadata.gz: '0397d2603cc060239303773b370f14cc9585b94b4ba5109207ac7f705b18aec244f83443478c15c1ed40be4650c20f9f13d669f224dfc916374e924da4ab6cb1'
+  data.tar.gz: a8f7562d3bc1f8bd43897b4692c18a4096509d2c4ce413eaa1c992c61c2a7fada7c0c52228c543d62387c9a56c37672819f1becfd39240bc83066491947678f8

data/lib/agentf/agents/architect.rb

@@ -78,6 +78,10 @@ module Agentf
 
         { "subtasks" => subtasks, "context" => context }
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        plan_task(task)
+      end
     end
   end
 end

data/lib/agentf/agents/base.rb

@@ -61,7 +61,15 @@ module Agentf
         )
       end
 
+      # Unified execution entrypoint for all agents. Concrete agents must
+      # implement `execute(task:, context:, agents:, commands:, logger:)`.
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
       def log(message)
+        return if ENV["AGENTF_SUPPRESS_AGENT_LOGS"] == "true"
+
         puts "\n[#{@name}] #{message}"
       end
 
@@ -83,8 +91,28 @@ module Agentf
           result: result
         )
 
-        result
+      result
+    end
+
+    # Helper to centralize memory write confirmation handling.
+    # Yields a block that performs the memory write. If the memory layer
+    # requires confirmation (ask_first policy) a structured hash is
+    # returned with confirmation details so agents can merge that into
+    # their own return payloads or let the orchestrator handle prompting.
+    def safe_memory_write(attempted: {})
+      begin
+        yield
+      rescue Agentf::Memory::RedisMemory::ConfirmationRequired => e
+        log "[MEMORY] Confirmation required: #{e.message} -- details=#{e.details.inspect}"
+        {
+          "confirmation_required" => true,
+          "confirmation_details" => e.details,
+          "attempted" => attempted,
+          "confirmed_write_token" => "confirmed",
+          "confirmation_prompt" => "Ask the user whether to save this memory. If they approve, rerun the same tool with confirmedWrite=confirmed. If they decline, do not retry."
+        }
       end
     end
+    end
   end
 end

data/lib/agentf/agents/debugger.rb

@@ -45,8 +45,8 @@ module Agentf
 
       def self.policy_boundaries
         {
-          "always" => ["Return analysis with root causes and suggested fix", "Persist debugging lesson"],
-          "ask_first" => ["Applying speculative fixes without reproducible error"],
+          "always" => ["Return analysis with root causes and suggested fix"],
+          "ask_first" => ["Applying speculative fixes without reproducible error", "Persisting debugging lessons to memory"],
           "never" => ["Discard stack trace context when available"],
           "required_inputs" => ["error_text"],
           "required_outputs" => ["analysis", "success"]
@@ -66,14 +66,32 @@ module Agentf
 
           analysis = @commands.parse_error(error)
 
-          memory.store_episode(
-            type: "lesson",
-            title: "Debugged: #{error[0..50]}...",
-            description: "Root cause: #{analysis.possible_causes.first}. Fix: #{analysis.suggested_fix}",
-            context: context.to_s,
-            tags: ["debugging", "error", "fix"],
-            agent: name
-          )
+          res = safe_memory_write(attempted: { action: "store_lesson", title: "Debugged: #{error[0..50]}...", tags: ["debugging", "error", "fix"], agent: name }) do
+            memory.store_episode(
+              type: "lesson",
+              title: "Debugged: #{error[0..50]}...",
+              description: "Root cause: #{analysis.possible_causes.first}. Fix: #{analysis.suggested_fix}",
+              context: context.to_s,
+              tags: ["debugging", "error", "fix"],
+              agent: name
+            )
+          end
+
+          if res.is_a?(Hash) && res["confirmation_required"]
+            log "Root cause: #{analysis.possible_causes.first}"
+            log "Suggested fix: #{analysis.suggested_fix}"
+            return {
+              "success" => false,
+              "confirmation_required" => true,
+              "confirmation_details" => res["confirmation_details"],
+              "analysis" => {
+                "error_type" => analysis.error_type,
+                "possible_causes" => analysis.possible_causes,
+                "suggested_fix" => analysis.suggested_fix,
+                "stack_trace" => analysis.stack_trace
+              }
+            }
+          end
 
           log "Root cause: #{analysis.possible_causes.first}"
           log "Suggested fix: #{analysis.suggested_fix}"
@@ -90,6 +108,11 @@ module Agentf
           }
         end
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        error_text = task.is_a?(String) ? task : context["error"]
+        diagnose(error_text, context: context)
+      end
     end
   end
 end

data/lib/agentf/agents/designer.rb

@@ -46,7 +46,7 @@ module Agentf
       def self.policy_boundaries
         {
           "always" => ["Return generated component details", "Persist successful implementation pattern"],
-          "ask_first" => ["Changing primary UI framework"],
+          "ask_first" => ["Changing primary UI framework", "Persisting successful implementation patterns to memory"],
           "never" => ["Return empty generated code for successful design task"],
           "required_inputs" => ["design_spec"],
           "required_outputs" => ["component", "generated_code", "success"]
@@ -64,13 +64,19 @@ module Agentf
 
           spec = @commands.generate_component("GeneratedComponent", design_spec)
 
-          memory.store_success(
-            title: "Implemented design: #{design_spec}",
-            description: "Created #{spec.name} in #{spec.framework}",
-            context: "Framework: #{framework}",
-            tags: ["design", "ui", framework],
-            agent: name
-          )
+          res = safe_memory_write(attempted: { action: "store_success", title: "Implemented design: #{design_spec}", tags: ["design", "ui", framework], agent: name }) do
+            memory.store_success(
+              title: "Implemented design: #{design_spec}",
+              description: "Created #{spec.name} in #{spec.framework}",
+              context: "Framework: #{framework}",
+              tags: ["design", "ui", framework],
+              agent: name
+            )
+          end
+
+          if res.is_a?(Hash) && res["confirmation_required"]
+            return { "design_spec" => design_spec, "component" => spec.name, "framework" => framework, "generated_code" => spec.code, "success" => true }.merge(res)
+          end
 
           log "Created component: #{spec.name}"
 
@@ -83,6 +89,11 @@ module Agentf
           }
         end
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        spec = task.is_a?(String) ? task : context["design_spec"]
+        implement_design(spec, framework: context["framework"] || "react")
+      end
     end
   end
 end

data/lib/agentf/agents/documenter.rb

@@ -69,6 +69,12 @@ module Agentf
           "total_memories" => memories.size
         }
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        project = task.is_a?(String) ? task : (context["project_name"] || "project")
+        sync_docs(project)
+      end
+
     end
   end
 end

data/lib/agentf/agents/explorer.rb

@@ -11,8 +11,8 @@ module Agentf
       COMMANDS = %w[glob grep read_file].freeze
       MEMORY_CONCEPTS = {
         "reads" => [],
-        "writes" => ["store_episode"],
-        "policy" => "Store exploration breadcrumbs as episodic memories."
+        "writes" => ["store_lesson"],
+        "policy" => "Store research findings as lessons after user confirmation."
       }.freeze
 
       def self.description
@@ -45,8 +45,8 @@ module Agentf
 
       def self.policy_boundaries
         {
-          "always" => ["Return concrete file evidence", "Persist exploration breadcrumbs"],
-          "ask_first" => ["Scanning outside configured base path"],
+          "always" => ["Return concrete file evidence"],
+          "ask_first" => ["Scanning outside configured base path", "Persisting research lessons to memory"],
           "never" => ["Mutate project files during exploration"],
           "required_inputs" => [],
           "required_outputs" => ["files", "context_gathered"]
@@ -63,19 +63,38 @@ module Agentf
 
         files = @commands.glob(query, file_types: nil)
 
-        memory.store_episode(
-          type: "exploration",
-          title: "Explored: #{query}",
-          description: "Found #{files.size} relevant files",
-          context: "Search pattern: #{file_pattern || 'all files'}",
-          tags: ["exploration", "context"],
-          agent: name
-        )
+        res = safe_memory_write(attempted: { action: "store_lesson", title: "Research finding: #{query}", tags: ["research", "exploration"], agent: name }) do
+          memory.store_lesson(
+            title: "Research finding: #{query}",
+            description: "Found #{files.size} relevant files during exploration",
+            context: "Search pattern: #{file_pattern || 'all files'}",
+            tags: ["research", "exploration"],
+            agent: name
+          )
+        end
+
+        if res.is_a?(Hash) && res["confirmation_required"]
+          log "Memory confirmation required during exploration: #{res['confirmation_details'].inspect}"
+          return {
+            "files" => files,
+            "context_gathered" => true,
+            "confirmation_required" => true,
+            "confirmation_details" => res["confirmation_details"],
+            "attempted" => res["attempted"],
+            "confirmed_write_token" => res["confirmed_write_token"],
+            "confirmation_prompt" => res["confirmation_prompt"]
+          }
+        end
 
         log "Found #{files.size} files"
 
         { "query" => query, "files" => files, "context_gathered" => true }
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        query = context["explore_query"] || task || "*.rb"
+        explore(query, file_pattern: context["file_pattern"])
+      end
     end
   end
 end

data/lib/agentf/agents/reviewer.rb

@@ -77,6 +77,11 @@ module Agentf
           { "approved" => approved, "issues" => issues }
         end
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        subtask = task.is_a?(Hash) ? task : context["execution"] || {}
+        review(subtask)
+      end
     end
   end
 end

data/lib/agentf/agents/security.rb

@@ -45,8 +45,8 @@ module Agentf
 
       def self.policy_boundaries
         {
-          "always" => ["Return issue list and best practices", "Persist outcome as success or pitfall"],
-          "ask_first" => ["Allowing known secret patterns in context"],
+          "always" => ["Return issue list and best practices"],
+          "ask_first" => ["Allowing known secret patterns in context", "Persisting security scan findings to memory"],
           "never" => ["Echo raw secrets in output"],
           "required_inputs" => ["task"],
           "required_outputs" => ["issues", "best_practices"]
@@ -66,27 +66,37 @@ module Agentf
           summary = summarize_findings(findings)
 
           if findings["issues"].empty?
-            memory.store_success(
-              title: "Security review passed",
-              description: summary,
-              context: task,
-              tags: ["security", "pass"],
-              agent: name
-            )
+            res = safe_memory_write(attempted: { action: "store_success", title: "Security review passed", tags: ["security", "pass"], agent: name }) do
+              memory.store_success(
+                title: "Security review passed",
+                description: summary,
+                context: task,
+                tags: ["security", "pass"],
+                agent: name
+              )
+            end
+            return findings.merge(res) if res.is_a?(Hash) && res["confirmation_required"]
           else
-            memory.store_pitfall(
-              title: "Security findings detected",
-              description: summary,
-              context: task,
-              tags: ["security", "warning"],
-              agent: name
-            )
+            res = safe_memory_write(attempted: { action: "store_pitfall", title: "Security findings detected", tags: ["security", "warning"], agent: name }) do
+              memory.store_pitfall(
+                title: "Security findings detected",
+                description: summary,
+                context: task,
+                tags: ["security", "warning"],
+                agent: name
+              )
+            end
+            return findings.merge(res) if res.is_a?(Hash) && res["confirmation_required"]
           end
 
           findings.merge("best_practices" => @commands.best_practices)
         end
       end
 
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        assess(task: task, context: context)
+      end
+
       private
 
       def summarize_findings(findings)

data/lib/agentf/agents/specialist.rb

@@ -45,14 +45,16 @@ module Agentf
       def self.policy_boundaries
         {
           "always" => ["Persist execution outcome", "Return deterministic success boolean"],
-          "ask_first" => ["Applying architecture style changes across unrelated modules"],
+          "ask_first" => ["Applying architecture style changes across unrelated modules", "Persisting execution outcomes to memory (success/pitfall)"] ,
           "never" => ["Claim implementation complete without execution result"],
           "required_inputs" => ["description"],
           "required_outputs" => ["subtask_id", "success"]
         }
       end
 
-      def execute(subtask)
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+        subtask = task.is_a?(Hash) ? task : (context["current_subtask"] || { "description" => task })
+
         normalized_subtask = subtask.merge(
           "id" => subtask["id"] || "ad-hoc",
           "description" => subtask["description"] || "Execute implementation step"
@@ -64,23 +66,35 @@ module Agentf
           success = normalized_subtask.fetch("success", true)
 
           if success
-            memory.store_success(
-              title: "Completed: #{normalized_subtask['description']}",
-              description: "Successfully executed subtask #{normalized_subtask['id']}",
-              context: "Working on #{normalized_subtask.fetch('task', 'unknown task')}",
-              tags: ["implementation", normalized_subtask.fetch("language", "general")],
-              agent: name
-            )
-            log "Stored success memory"
+            res = safe_memory_write(attempted: { action: "store_success", title: "Completed: #{normalized_subtask['description']}", tags: ["implementation", normalized_subtask.fetch("language", "general")], agent: name }) do
+              memory.store_success(
+                title: "Completed: #{normalized_subtask['description']}",
+                description: "Successfully executed subtask #{normalized_subtask['id']}",
+                context: "Working on #{normalized_subtask.fetch('task', 'unknown task')}",
+                tags: ["implementation", normalized_subtask.fetch("language", "general")],
+                agent: name
+              )
+            end
+
+            if res.is_a?(Hash) && res["confirmation_required"]
+              log "Memory confirmation required when storing success: #{res['confirmation_details'].inspect}"
+              return { "subtask_id" => normalized_subtask["id"], "success" => success, "result" => "Code executed", "confirmation_required" => true, "confirmation_details" => res["confirmation_details"], "attempted" => res["attempted"] }
+            end
           else
-            memory.store_pitfall(
-              title: "Failed: #{normalized_subtask['description']}",
-              description: "Subtask #{normalized_subtask['id']} failed",
-              context: "Working on #{normalized_subtask.fetch('task', 'unknown task')}",
-              tags: ["failure", "implementation"],
-              agent: name
-            )
-            log "Stored pitfall memory"
+            res = safe_memory_write(attempted: { action: "store_pitfall", title: "Failed: #{normalized_subtask['description']}", tags: ["failure", "implementation"], agent: name }) do
+              memory.store_pitfall(
+                title: "Failed: #{normalized_subtask['description']}",
+                description: "Subtask #{normalized_subtask['id']} failed",
+                context: "Working on #{normalized_subtask.fetch('task', 'unknown task')}",
+                tags: ["failure", "implementation"],
+                agent: name
+              )
+            end
+
+            if res.is_a?(Hash) && res["confirmation_required"]
+              log "Memory confirmation required when storing pitfall: #{res['confirmation_details'].inspect}"
+              return { "subtask_id" => normalized_subtask["id"], "success" => success, "result" => "Code executed", "confirmation_required" => true, "confirmation_details" => res["confirmation_details"], "attempted" => res["attempted"] }
+            end
           end
 
           { "subtask_id" => normalized_subtask["id"], "success" => success, "result" => "Code executed" }

data/lib/agentf/agents/tester.rb

@@ -46,7 +46,7 @@ module Agentf
       def self.policy_boundaries
         {
           "always" => ["Produce framework-aware tests", "Verify red/green state when TDD enabled"],
-          "ask_first" => ["Changing test framework conventions"],
+          "ask_first" => ["Changing test framework conventions", "Persisting test-generation outcomes to memory"],
           "never" => ["Mark passing when command output is uncertain"],
           "required_inputs" => [],
           "required_outputs" => ["test_file"]
@@ -63,13 +63,20 @@ module Agentf
 
         template = @commands.generate_unit_tests(code_file)
 
-        memory.store_success(
-          title: "Generated #{test_type} tests for #{code_file}",
-          description: "Created #{template.test_file} with #{test_type} tests",
-          context: "Test framework: #{template.framework}",
-          tags: ["testing", test_type, code_file.split(".").last],
-          agent: name
-        )
+        res = safe_memory_write(attempted: { action: "store_success", title: "Generated #{test_type} tests for #{code_file}", tags: ["testing", test_type, code_file.split(".").last], agent: name }) do
+          memory.store_success(
+            title: "Generated #{test_type} tests for #{code_file}",
+            description: "Created #{template.test_file} with #{test_type} tests",
+            context: "Test framework: #{template.framework}",
+            tags: ["testing", test_type, code_file.split(".").last],
+            agent: name
+          )
+        end
+
+        if res.is_a?(Hash) && res["confirmation_required"]
+          log "Memory confirmation required when storing generated tests: #{res['confirmation_details'].inspect}"
+          return { "test_file" => template.test_file, "test_type" => test_type, "generated_code" => template.test_code, "confirmation_required" => true, "confirmation_details" => res["confirmation_details"], "attempted" => res["attempted"] }
+        end
 
         log "Created: #{template.test_file}"
 
@@ -90,6 +97,38 @@ module Agentf
 
         { "test_file" => test_file, "passed" => result["passed"] }
       end
+
+      def execute(task:, context: {}, agents: {}, commands: {}, logger: nil)
+         # Support provider-driven TDD red-phase: when context signals a red phase,
+         # generate tests via the tester commands (if provided) and return a
+         # simulated failing test signature so orchestrator flows can short-circuit.
+         if context.to_h["tdd_phase"] == "red"
+           tester_commands = if commands.respond_to?(:fetch)
+                               commands.fetch("tester", nil)
+                             else
+                               commands["tester"]
+                             end
+
+           begin
+             tester_commands&.generate_unit_tests(context.to_h["source_file"]) if tester_commands&.respond_to?(:generate_unit_tests)
+           rescue StandardError
+             # ignore command errors for the simulated red phase
+           end
+
+           return { "tdd_phase" => "red", "passed" => false, "failure_signature" => "expected-failure-#{context.to_h["source_file"] || 'unspecified'}" }
+         end
+
+         action = context["action"] || (task.is_a?(String) ? "generate_tests" : context["action"])
+        case action
+        when "generate_tests"
+          code_file = task.is_a?(String) ? task : context["code_file"]
+          generate_tests(code_file, test_type: context["test_type"] || "unit")
+        when "run_tests"
+          run_tests(context["test_file"] || task)
+        else
+          { "error" => "Unknown action for Tester: #{action}" }
+        end
+      end
     end
   end
 end

data/lib/agentf/cli/agent.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "arg_parser"
+require_relative "../commands/registry"
+require_relative "../commands"
+require_relative "../agents"
+require_relative "../memory"
+
+module Agentf
+  module CLI
+    # CLI entry for running a single agent and returning JSON output.
+    class Agent
+      include ArgParser
+
+      def initialize
+        @memory = Agentf::Memory::RedisMemory.new
+      end
+
+      def run(args)
+        if args.empty? || args.include?("--help") || args.include?("help")
+          show_help
+          return
+        end
+
+        # Allow callers (like the TypeScript plugin) to append `--json` to
+        # request machine-readable output. Strip it here so it's not treated as
+        # part of the agent payload.
+        args = args.dup
+        json_output = !args.delete("--json").nil?
+        confirmed_write = parse_single_option(args, "--confirmed-write=")
+
+        agent_name = args.shift
+        payload = args.join(" ")
+
+        # Build command registry with default implementations
+        registry = Agentf::Commands::Registry.new
+        # Register known command providers
+        registry.register("explorer", Agentf::Commands::Explorer.new)
+        registry.register("tester", Agentf::Commands::Tester.new)
+        registry.register("debugger", Agentf::Commands::Debugger.new)
+        registry.register("designer", Agentf::Commands::Designer.new)
+        registry.register("security", Agentf::Commands::SecurityScanner.new)
+        registry.register("architecture", Agentf::Commands::Architecture.new)
+
+        # Load agents (classes already required via lib/agentf)
+        agents = {}
+        Agentf::Agents.constants.each do |const|
+          klass = Agentf::Agents.const_get(const)
+          next unless klass.is_a?(Class) && klass < Agentf::Agents::Base
+          agents[klass.typed_name] = klass.new(@memory)
+        end
+
+        agent = agents[agent_name.upcase]
+        unless agent
+          $stderr.puts JSON.generate({ ok: false, error: "Agent not found: #{agent_name}" })
+          exit 1
+        end
+
+        # Parse possible JSON payload
+        parsed = nil
+        begin
+          parsed = JSON.parse(payload) unless payload.strip.empty?
+        rescue StandardError
+          parsed = payload
+        end
+
+        previous = ENV["AGENTF_SUPPRESS_AGENT_LOGS"]
+        previous_auto_confirm = ENV["AGENTF_AUTO_CONFIRM_MEMORIES"]
+        ENV["AGENTF_SUPPRESS_AGENT_LOGS"] = "true" if json_output
+        ENV["AGENTF_AUTO_CONFIRM_MEMORIES"] = "true" unless confirmed_write.to_s.empty?
+
+        result = agent.execute(
+          task: parsed || payload,
+          context: { "confirmed_write" => confirmed_write },
+          agents: agents,
+          commands: registry,
+          logger: json_output ? nil : method(:puts)
+        )
+
+        puts JSON.generate(result)
+      ensure
+        ENV["AGENTF_SUPPRESS_AGENT_LOGS"] = previous if json_output
+        ENV["AGENTF_AUTO_CONFIRM_MEMORIES"] = previous_auto_confirm unless confirmed_write.to_s.empty?
+      end
+
+      def show_help
+        puts <<~HELP
+          Usage: agentf agent <AGENT_NAME> [payload] [--json] [--confirmed-write=<token>]
+
+          Runs a single agent and prints JSON result.
+        HELP
+      end
+    end
+  end
+end