agentf 0.4.6 → 0.5.0

data/lib/agentf/mcp/server.rb

@@ -3,9 +3,9 @@
 begin
   require "mcp"
 rescue LoadError
-  require_relative "stub"
 end
 require "json"
+require "set"
 
 module Agentf
   module MCP
@@ -20,6 +20,161 @@ module Agentf
     #   AGENTF_MCP_ALLOW_WRITES   - true/false, controls memory write tools
     #   AGENTF_MCP_MAX_ARG_LENGTH - max length per string argument
     class Server
+      ToolDefinition = Struct.new(:name, :description, :arguments, :handler, keyword_init: true)
+
+      class ToolBuilder
+        attr_reader :arguments, :handler
+
+        def initialize(name)
+          @name = name
+          @arguments = {}
+        end
+
+        def description(value = nil)
+          @description = value unless value.nil?
+          @description
+        end
+
+        def argument(name, type, required: false, description:, items: nil, **_opts)
+          @arguments[name] = {
+            type: type,
+            items: items,
+            required: required,
+            schema: {
+              type: schema_type(type),
+              description: description
+            }.tap do |schema|
+              schema[:items] = { type: schema_type(items) } if type == Array && items
+            end
+          }
+        end
+
+        def call(&block)
+          @handler = block
+        end
+
+        private
+
+        def schema_type(type)
+          case type&.name
+          when "String" then "string"
+          when "Integer" then "integer"
+          when "Float" then "number"
+          when "TrueClass", "FalseClass" then "boolean"
+          when "Array" then "array"
+          when "Hash" then "object"
+          else
+            "string"
+          end
+        end
+      end
+
+      class RegistryAdapter
+        def initialize(name:, version:)
+          @name = name
+          @version = version
+          @tools = {}
+        end
+
+        def tool(name, &block)
+          builder = ToolBuilder.new(name)
+          builder.instance_eval(&block)
+          @tools[name] = ToolDefinition.new(
+            name: name,
+            description: builder.description,
+            arguments: builder.arguments,
+            handler: builder.handler
+          )
+        end
+
+        def list_tools
+          @tools.values.map do |tool|
+            {
+              name: tool.name,
+              description: tool.description.to_s,
+              inputSchema: {
+                type: "object",
+                properties: tool.arguments.transform_values { |arg| arg[:schema] },
+                required: tool.arguments.select { |_k, arg| arg[:required] }.keys.map(&:to_s)
+              }
+            }
+          end
+        end
+
+        def call_tool(name, **args)
+          tool = @tools[name]
+          raise "Unknown tool: #{name}" unless tool
+
+          tool.handler.call(args)
+        rescue StandardError => e
+          e.message
+        end
+
+        def run
+          runtime_server = build_runtime_server
+          transport = ::MCP::Server::Transports::StdioTransport.new(runtime_server)
+          runtime_server.transport = transport if runtime_server.respond_to?(:transport=)
+          transport.open
+        end
+
+        private
+
+        def build_runtime_server
+          ensure_runtime_support!
+
+          runtime_server = ::MCP::Server.new(name: @name, version: @version)
+          adapter = self
+          @tools.each_value do |tool|
+            runtime_server.define_tool(
+              name: tool.name,
+              description: tool.description,
+              input_schema: runtime_input_schema(tool.arguments)
+            ) do |**kwargs|
+              result = tool.handler.call(kwargs)
+              adapter.send(:build_response, result)
+            rescue StandardError => e
+              ::MCP::Tool::Response.new([::MCP::Content::Text.new(e.message).to_h], error: true)
+            end
+          end
+          runtime_server
+        end
+
+        def ensure_runtime_support!
+          return if defined?(::MCP::Server::Transports::StdioTransport) && defined?(::MCP::Tool::Response) && defined?(::MCP::Content::Text)
+
+          raise "Installed MCP runtime does not support stdio server transport"
+        end
+
+        def runtime_input_schema(arguments)
+          schema = {
+            type: "object",
+            properties: arguments.transform_keys(&:to_s).transform_values { |arg| arg[:schema].transform_keys(&:to_s) }
+          }
+
+          required = arguments.select { |_k, arg| arg[:required] }.keys.map(&:to_s)
+          schema[:required] = required unless required.empty?
+          schema
+        end
+
+        def build_response(result)
+          return result if result.is_a?(::MCP::Tool::Response)
+
+          text = result.is_a?(String) ? result : JSON.generate(result)
+          structured = parse_structured_content(result)
+          ::MCP::Tool::Response.new([::MCP::Content::Text.new(text).to_h], structured_content: structured)
+        end
+
+        def parse_structured_content(result)
+          return result if result.is_a?(Hash)
+          return JSON.parse(result) if result.is_a?(String)
+          return result.as_json if result.respond_to?(:as_json)
+
+          nil
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
       KNOWN_TOOLS = %w[
         agentf-code-glob
         agentf-code-grep
@@ -66,6 +221,25 @@ module Agentf
         @server = build_server
       end
 
+      # Helper to centralize confirmation handling for MCP server write tools.
+      # Yields the block that performs the memory write and returns either the
+      # block result or the normalized confirmation hash produced by
+      # Agentf::Agents::Base#safe_memory_write.
+      def safe_mcp_memory_write(memory, attempted: {})
+        begin
+          yield
+          nil
+        rescue Agentf::Memory::RedisMemory::ConfirmationRequired => e
+          {
+            "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, call the same tool again after confirmation. If they decline, do not retry."
+          }
+        end
+      end
+
       # Start the stdio read loop (blocks until stdin closes).
       def run
         @server.run
@@ -139,7 +313,7 @@ module Agentf
       # ── Server construction ─────────────────────────────────────
 
       def build_server
-        s = ::MCP::Server.new(name: "agentf", version: Agentf::VERSION)
+        s = RegistryAdapter.new(name: "agentf", version: Agentf::VERSION)
         register_code_tools(s)
         register_memory_tools(s)
         register_architecture_tools(s)
@@ -349,14 +523,24 @@ module Agentf
           argument :priority, Integer, required: false, description: "Priority"
           call do |args|
             mcp_server.send(:guard!, "agentf-memory-add-business-intent", **args)
-            id = memory.store_business_intent(
-              title: args[:title],
-              description: args[:description],
-              tags: args[:tags] || [],
-              constraints: args[:constraints] || [],
-              priority: args[:priority] || 1
-            )
-            JSON.generate(id: id, type: "business_intent", status: "stored")
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-business-intent", args: args }) do
+                  id = memory.store_business_intent(
+                    title: args[:title],
+                    description: args[:description],
+                    tags: args[:tags] || [],
+                    constraints: args[:constraints] || [],
+                    priority: args[:priority] || 1
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(confirmation_required: true, confirmation_details: res["confirmation_details"], attempted: res["attempted"])
+                else
+                  JSON.generate(id: id, type: "business_intent", status: "stored")
+                end
+              end
           end
         end
 
@@ -370,15 +554,25 @@ module Agentf
           argument :related_task_id, String, required: false, description: "Related task id"
           call do |args|
             mcp_server.send(:guard!, "agentf-memory-add-feature-intent", **args)
-            id = memory.store_feature_intent(
-              title: args[:title],
-              description: args[:description],
-              tags: args[:tags] || [],
-              acceptance_criteria: args[:acceptance] || [],
-              non_goals: args[:non_goals] || [],
-              related_task_id: args[:related_task_id]
-            )
-            JSON.generate(id: id, type: "feature_intent", status: "stored")
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-feature-intent", args: args }) do
+                  id = memory.store_feature_intent(
+                    title: args[:title],
+                    description: args[:description],
+                    tags: args[:tags] || [],
+                    acceptance_criteria: args[:acceptance] || [],
+                    non_goals: args[:non_goals] || [],
+                    related_task_id: args[:related_task_id]
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(confirmation_required: true, confirmation_details: res["confirmation_details"], attempted: res["attempted"])
+                else
+                  JSON.generate(id: id, type: "feature_intent", status: "stored")
+                end
+              end
           end
         end
 
@@ -427,16 +621,32 @@ module Agentf
           argument :context, String, required: false, description: "Context"
           call do |args|
             mcp_server.send(:guard!, "agentf-memory-add-lesson", **args)
-            id = memory.store_episode(
-              type: "lesson",
-              title: args[:title],
-              description: args[:description],
-              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
-              tags: args[:tags] || [],
-              context: args[:context].to_s,
-              code_snippet: ""
-            )
-            JSON.generate(id: id, type: "lesson", status: "stored")
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-lesson", args: args }) do
+                  id = memory.store_episode(
+                    type: "lesson",
+                    title: args[:title],
+                    description: args[:description],
+                    agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
+                    tags: args[:tags] || [],
+                    context: args[:context].to_s,
+                    code_snippet: ""
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(
+                    confirmation_required: true,
+                    confirmation_details: res["confirmation_details"],
+                    attempted: res["attempted"],
+                    confirmed_write_token: res["confirmed_write_token"],
+                    confirmation_prompt: res["confirmation_prompt"]
+                  )
+                else
+                  JSON.generate(id: id, type: "lesson", status: "stored")
+                end
+              end
           end
         end
 
@@ -449,16 +659,32 @@ module Agentf
           argument :context, String, required: false, description: "Context"
           call do |args|
             mcp_server.send(:guard!, "agentf-memory-add-success", **args)
-            id = memory.store_episode(
-              type: "success",
-              title: args[:title],
-              description: args[:description],
-              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
-              tags: args[:tags] || [],
-              context: args[:context].to_s,
-              code_snippet: ""
-            )
-            JSON.generate(id: id, type: "success", status: "stored")
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-success", args: args }) do
+                  id = memory.store_episode(
+                    type: "success",
+                    title: args[:title],
+                    description: args[:description],
+                    agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
+                    tags: args[:tags] || [],
+                    context: args[:context].to_s,
+                    code_snippet: ""
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(
+                    confirmation_required: true,
+                    confirmation_details: res["confirmation_details"],
+                    attempted: res["attempted"],
+                    confirmed_write_token: res["confirmed_write_token"],
+                    confirmation_prompt: res["confirmation_prompt"]
+                  )
+                else
+                  JSON.generate(id: id, type: "success", status: "stored")
+                end
+              end
           end
         end
 
@@ -471,16 +697,32 @@ module Agentf
           argument :context, String, required: false, description: "Context"
           call do |args|
             mcp_server.send(:guard!, "agentf-memory-add-pitfall", **args)
-            id = memory.store_episode(
-              type: "pitfall",
-              title: args[:title],
-              description: args[:description],
-              agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
-              tags: args[:tags] || [],
-              context: args[:context].to_s,
-              code_snippet: ""
-            )
-            JSON.generate(id: id, type: "pitfall", status: "stored")
+              begin
+                id = nil
+                res = mcp_server.send(:safe_mcp_memory_write, memory, attempted: { tool: "agentf-memory-add-pitfall", args: args }) do
+                  id = memory.store_episode(
+                    type: "pitfall",
+                    title: args[:title],
+                    description: args[:description],
+                    agent: args[:agent] || Agentf::AgentRoles::ENGINEER,
+                    tags: args[:tags] || [],
+                    context: args[:context].to_s,
+                    code_snippet: ""
+                  )
+                end
+
+                if res.is_a?(Hash) && res["confirmation_required"]
+                  JSON.generate(
+                    confirmation_required: true,
+                    confirmation_details: res["confirmation_details"],
+                    attempted: res["attempted"],
+                    confirmed_write_token: res["confirmed_write_token"],
+                    confirmation_prompt: res["confirmation_prompt"]
+                  )
+                else
+                  JSON.generate(id: id, type: "pitfall", status: "stored")
+                end
+              end
           end
         end
       end

data/lib/agentf/memory.rb

@@ -23,6 +23,16 @@ module Agentf
         ensure_indexes if @search_supported
       end
 
+      # Raised when a write requires explicit user confirmation (ask_first).
+      class ConfirmationRequired < StandardError
+        attr_reader :details
+
+        def initialize(message = "confirmation required to persist memory", details = {})
+          super(message)
+          @details = details
+        end
+      end
+
       def store_task(content:, embedding: [], language: nil, task_type: nil, success: true, agent: Agentf::AgentRoles::PLANNER)
         task_id = "task_#{SecureRandom.hex(4)}"
 
@@ -44,8 +54,34 @@ module Agentf
         task_id
       end
 
-      def store_episode(type:, title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ENGINEER,
-                        related_task_id: nil, metadata: {}, entity_ids: [], relationships: [], parent_episode_id: nil, causal_from: nil)
+      def store_episode(type:, title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR,
+                        related_task_id: nil, metadata: {}, entity_ids: [], relationships: [], parent_episode_id: nil, causal_from: nil, confirm: nil)
+        # Determine persistence preference from the agent's policy boundaries.
+        # Precedence: never > ask_first > always > none.
+        # For local/dev testing we may bypass interactive confirmation when
+        # AGENTF_AUTO_CONFIRM_MEMORIES=true. Otherwise, when an agent declares
+        # an "ask_first" persistence preference we raise ConfirmationRequired
+        # so higher-level code (MCP server / workflow engine / CLI) can prompt
+        # the user and retry the write with confirm: true.
+        auto_confirm = ENV['AGENTF_AUTO_CONFIRM_MEMORIES'] == 'true'
+        pref = persistence_preference_for(agent)
+
+        case pref
+        when :never
+          begin
+            puts "[MEMORY] Skipping persistence for #{agent}: policy forbids persisting memories"
+          rescue StandardError
+          end
+          return nil
+        when :ask_first
+          # If the agent's policy requires asking first, and we do not have
+          # an explicit confirmation (confirm: true) and auto_confirm is not
+          # enabled, raise ConfirmationRequired so callers can handle prompting.
+          unless auto_confirm || confirm == true
+            details = { "reason" => "ask_first", "agent" => agent.to_s, "attempted" => { "type" => type, "title" => title } }
+            raise ConfirmationRequired.new("confirm", details)
+          end
+        end
         episode_id = "episode_#{SecureRandom.hex(4)}"
         normalized_metadata = enrich_metadata(
           metadata: metadata,
@@ -107,52 +143,56 @@ module Agentf
         episode_id
       end
 
-      def store_success(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ENGINEER)
-        store_episode(
+       def store_success(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR, confirm: nil)
+         store_episode(
           type: "success",
           title: title,
           description: description,
           context: context,
           code_snippet: code_snippet,
           tags: tags,
-          agent: agent
+           agent: agent,
+           confirm: confirm
         )
       end
 
-      def store_pitfall(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ENGINEER)
-        store_episode(
+       def store_pitfall(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR, confirm: nil)
+         store_episode(
           type: "pitfall",
           title: title,
           description: description,
           context: context,
           code_snippet: code_snippet,
           tags: tags,
-          agent: agent
+           agent: agent,
+           confirm: confirm
         )
       end
 
-      def store_lesson(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ENGINEER)
-        store_episode(
+       def store_lesson(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR, confirm: nil)
+         store_episode(
           type: "lesson",
           title: title,
           description: description,
           context: context,
           code_snippet: code_snippet,
           tags: tags,
-          agent: agent
+           agent: agent,
+           confirm: confirm
         )
       end
 
-      def store_business_intent(title:, description:, constraints: [], tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR, priority: 1)
+      def store_business_intent(title:, description:, constraints: [], tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR, priority: 1, confirm: nil)
         context = constraints.any? ? "Constraints: #{constraints.join('; ')}" : ""
 
-        store_episode(
+         store_episode(
           type: "business_intent",
           title: title,
           description: description,
           context: context,
           tags: tags,
-          agent: agent,
+           agent: agent,
+           confirm: confirm,
           metadata: {
             "intent_kind" => "business",
             "constraints" => constraints,
@@ -162,18 +202,19 @@ module Agentf
       end
 
       def store_feature_intent(title:, description:, acceptance_criteria: [], non_goals: [], tags: [], agent: Agentf::AgentRoles::PLANNER,
-                               related_task_id: nil)
+                                related_task_id: nil, confirm: nil)
         context_parts = []
         context_parts << "Acceptance: #{acceptance_criteria.join('; ')}" if acceptance_criteria.any?
         context_parts << "Non-goals: #{non_goals.join('; ')}" if non_goals.any?
 
-        store_episode(
+         store_episode(
           type: "feature_intent",
           title: title,
           description: description,
           context: context_parts.join(" | "),
           tags: tags,
           agent: agent,
+           confirm: confirm,
           related_task_id: related_task_id,
           metadata: {
             "intent_kind" => "feature",
@@ -184,7 +225,7 @@ module Agentf
       end
 
       def store_incident(title:, description:, root_cause: "", resolution: "", tags: [], agent: Agentf::AgentRoles::INCIDENT_RESPONDER,
-                         business_capability: nil)
+                         business_capability: nil, confirm: nil)
         store_episode(
           type: "incident",
           title: title,
@@ -192,6 +233,7 @@ module Agentf
           context: ["Root cause: #{root_cause}", "Resolution: #{resolution}"].reject { |entry| entry.end_with?(": ") }.join(" | "),
           tags: tags,
           agent: agent,
+          confirm: confirm,
           metadata: {
             "root_cause" => root_cause,
             "resolution" => resolution,
@@ -201,7 +243,7 @@ module Agentf
         )
       end
 
-      def store_playbook(title:, description:, steps: [], tags: [], agent: Agentf::AgentRoles::PLANNER, feature_area: nil)
+      def store_playbook(title:, description:, steps: [], tags: [], agent: Agentf::AgentRoles::PLANNER, feature_area: nil, confirm: nil)
         store_episode(
           type: "playbook",
           title: title,
@@ -209,6 +251,7 @@ module Agentf
           context: steps.any? ? "Steps: #{steps.join('; ')}" : "",
           tags: tags,
           agent: agent,
+          confirm: confirm,
           metadata: {
             "steps" => steps,
             "feature_area" => feature_area,
@@ -580,7 +623,7 @@ module Agentf
           cursor, batch = @client.scan(cursor, match: "episodic:*", count: 100)
           batch.each do |key|
             memory = load_episode(key)
-            memories << memory if memory
+            memories << memory if memory && memory["project"].to_s == @project.to_s
           end
           break if cursor == "0"
         end
@@ -858,6 +901,41 @@ module Agentf
         base
       end
 
+      # NOTE: previous implementations exposed an `agent_requires_confirmation?`
+      # helper here. That functionality is superseded by
+      # `persistence_preference_for(agent)` which returns explicit preferences
+      # (:always, :ask_first, :never) and is used by callers to decide whether
+      # interactive confirmation is required. Keep this file lean and avoid
+      # duplicate helpers.
+
+      # Inspect loaded agent classes for explicit persistence preference.
+      # Returns one of: :always, :ask_first, :never, or nil when unknown.
+      def persistence_preference_for(agent)
+        begin
+          candidate = Agentf::Agents.constants
+                      .map { |c| Agentf::Agents.const_get(c) }
+                      .find do |klass|
+                        klass.is_a?(Class) && klass.respond_to?(:policy_boundaries) && klass.typed_name == agent
+                      end
+
+          return nil unless candidate
+
+          boundaries = candidate.policy_boundaries
+          persist_pattern = /persist|store|save/i
+
+          never_matches = Array(boundaries["never"]).select { |s| s =~ persist_pattern }
+          ask_matches = Array(boundaries["ask_first"]).select { |s| s =~ persist_pattern }
+          always_matches = Array(boundaries["always"]).select { |s| s =~ persist_pattern }
+
+          return :never if never_matches.any?
+          return :ask_first if ask_matches.any?
+          return :always if always_matches.any? && ask_matches.empty?
+          nil
+        rescue StandardError
+          nil
+        end
+      end
+
       def infer_division(agent)
         case agent
         when Agentf::AgentRoles::PLANNER, Agentf::AgentRoles::ORCHESTRATOR, Agentf::AgentRoles::KNOWLEDGE_MANAGER