agentf 0.4.0 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31fbac11988e521fb26969fc26f2da9c434541fb0ada47c1b681a6717c4ee018
-  data.tar.gz: 761c50541fc3b7207089b22ac710f07b3fd004ae984a1d46b548e92277290196
+  metadata.gz: 3518ac253ce03fcc05439cf5b749bd91e07aea398b15b7870072b3bfe58b0d24
+  data.tar.gz: f95d3efeee0551c59ed2e8d575a4598ac889872f37bf73987c710064d0ff5ee8
 SHA512:
-  metadata.gz: 348d7d27eae2dddac25859f79c3b8fd99b5be0ebbd7d1447308c146155bb70908519e5ece270fd67255aaa2c313d5f689ce2b1ca46442789c6c229fc8ef47561
-  data.tar.gz: 3064ce1fc1f05c85b4d88e3f415202193427dcf21ad57827571eeda79a7975555390a6c506eca05ed36fce9c00d10fda3d9b357ab97930243f83b9934d1dca15
+  metadata.gz: 04703b74db04fac1840b7307100187b40bc33c3873d36ca2b34a92ee389551aa6292702bd494d9d62f4ceb27767e0873a3e8c56e40e75dd5f004cff2cf7d0bfb
+  data.tar.gz: a4bca497545c5ec43c63b192a2687378328cbd1aa940c99b761d2f30286cb5be2f0e1a4a98e6c1949b0e8ec5960c66fe84c15fa56dcfaa52c12d59243a5e147a

data/lib/agentf/agent_execution_contract.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Agentf
+  class AgentContractViolation < Agentf::Error
+    attr_reader :agent_name, :violations
+
+    def initialize(agent_name:, violations:)
+      @agent_name = agent_name
+      @violations = violations
+      super("Agent contract violated for #{agent_name}: #{violations.map { |v| v['code'] }.join(', ')}")
+    end
+  end
+
+  class AgentExecutionContract
+    def initialize(enabled:, mode:, policy: Agentf::AgentPolicy.new)
+      @enabled = enabled
+      @mode = normalize_mode(mode)
+      @policy = policy
+    end
+
+    def enabled?
+      @enabled && @mode != "off"
+    end
+
+    def enforcing?
+      enabled? && @mode == "enforcing"
+    end
+
+    def before!(agent_name:, boundaries:, context: {})
+      violations = @policy.validate(
+        agent_name: agent_name,
+        boundaries: boundaries,
+        context: context,
+        result: nil,
+        phase: :before
+      )
+      handle!(agent_name: agent_name, violations: violations)
+    end
+
+    def after!(agent_name:, boundaries:, context: {}, result:)
+      violations = @policy.validate(
+        agent_name: agent_name,
+        boundaries: boundaries,
+        context: context,
+        result: result,
+        phase: :after
+      ) + coding_execution_violations(agent_name: agent_name, result: result) + tdd_violations(agent_name: agent_name, context: context)
+      handle!(agent_name: agent_name, violations: violations)
+    end
+
+    private
+
+    def normalize_mode(value)
+      mode = value.to_s.strip.downcase
+      return mode if %w[advisory enforcing off].include?(mode)
+
+      "enforcing"
+    end
+
+    def handle!(agent_name:, violations:)
+      return if violations.empty? || !enabled?
+
+      raise Agentf::AgentContractViolation.new(agent_name: agent_name, violations: violations) if enforcing?
+    end
+
+    def tdd_violations(agent_name:, context:)
+      return [] unless [Agentf::AgentRoles::ENGINEER, Agentf::AgentRoles::UI_ENGINEER].include?(agent_name)
+
+      tdd_required = context["tdd_required"] == true || context.key?("tdd_phase")
+      return [] unless tdd_required
+
+      phase = context["tdd_phase"].to_s.strip
+      violations = []
+      if phase.empty?
+        violations << {
+          "code" => "missing_tdd_phase",
+          "severity" => "error",
+          "message" => "#{agent_name} requires explicit tdd_phase when TDD is enabled",
+          "agent" => agent_name,
+          "type" => "agent_contract"
+        }
+      end
+
+      if phase == "green" && context["expected_test_fix"].to_s.strip.empty?
+        violations << {
+          "code" => "missing_expected_test_fix",
+          "severity" => "error",
+          "message" => "#{agent_name} green phase requires expected_test_fix from failing test",
+          "agent" => agent_name,
+          "type" => "agent_contract"
+        }
+      end
+
+      violations
+    end
+
+    def coding_execution_violations(agent_name:, result:)
+      coding_agents = [Agentf::AgentRoles::ENGINEER, Agentf::AgentRoles::UI_ENGINEER, Agentf::AgentRoles::INCIDENT_RESPONDER]
+      return [] unless coding_agents.include?(agent_name)
+
+      unless result.is_a?(Hash) && [true, false].include?(result["success"])
+        return [
+          {
+            "code" => "invalid_success_flag",
+            "severity" => "error",
+            "message" => "#{agent_name} must return boolean success",
+            "agent" => agent_name,
+            "type" => "agent_contract"
+          }
+        ]
+      end
+
+      []
+    end
+  end
+end

data/lib/agentf/agent_policy.rb

@@ -4,19 +4,34 @@ module Agentf
   class AgentPolicy
     REQUIRED_KEYS = %w[always ask_first never].freeze
 
-    def validate(agent_name:, boundaries:, context: {}, result: nil)
+    def validate(agent_name:, boundaries:, context: {}, result: nil, phase: :any)
       errors = []
       boundaries = normalize(boundaries)
 
-      required_inputs = Array(boundaries["required_inputs"])
-      missing_inputs = required_inputs.reject { |key| context.key?(key) }
-      unless missing_inputs.empty?
-        errors << violation(
-          code: "missing_required_inputs",
-          severity: "error",
-          message: "#{agent_name} missing required inputs: #{missing_inputs.join(', ')}",
-          agent: agent_name
-        )
+      if %i[any before].include?(phase)
+        required_inputs = Array(boundaries["required_inputs"])
+        missing_inputs = required_inputs.reject { |key| context.key?(key) }
+        unless missing_inputs.empty?
+          errors << violation(
+            code: "missing_required_inputs",
+            severity: "error",
+            message: "#{agent_name} missing required inputs: #{missing_inputs.join(', ')}",
+            agent: agent_name
+          )
+        end
+      end
+
+      if %i[any after].include?(phase)
+        required_outputs = Array(boundaries["required_outputs"])
+        missing_outputs = required_outputs.reject { |key| output_present?(result, key) }
+        unless missing_outputs.empty?
+          errors << violation(
+            code: "missing_required_outputs",
+            severity: "error",
+            message: "#{agent_name} missing required outputs: #{missing_outputs.join(', ')}",
+            agent: agent_name
+          )
+        end
       end
 
       if result.is_a?(Hash) && result["error"]
@@ -41,6 +56,14 @@ module Agentf
 
     private
 
+    def output_present?(result, key)
+      return false unless result.is_a?(Hash)
+      return false unless result.key?(key)
+
+      value = result[key]
+      !value.nil?
+    end
+
     def violation(code:, severity:, message:, agent:)
       {
         "code" => code,

data/lib/agentf/agents/base.rb

@@ -55,11 +55,36 @@ module Agentf
       def initialize(memory)
         @memory = memory
         @name = self.class.typed_name
+        @execution_contract = Agentf::AgentExecutionContract.new(
+          enabled: Agentf.config.agent_contract_enabled,
+          mode: Agentf.config.agent_contract_mode
+        )
       end
 
       def log(message)
         puts "\n[#{@name}] #{message}"
       end
+
+      private
+
+      def execute_with_contract(context: {})
+        @execution_contract.before!(
+          agent_name: name,
+          boundaries: self.class.policy_boundaries,
+          context: context
+        )
+
+        result = yield
+
+        @execution_contract.after!(
+          agent_name: name,
+          boundaries: self.class.policy_boundaries,
+          context: context,
+          result: result
+        )
+
+        result
+      end
     end
   end
 end

data/lib/agentf/agents/debugger.rb

@@ -48,8 +48,8 @@ module Agentf
           "always" => ["Return analysis with root causes and suggested fix", "Persist debugging lesson"],
           "ask_first" => ["Applying speculative fixes without reproducible error"],
           "never" => ["Discard stack trace context when available"],
-          "required_inputs" => [],
-          "required_outputs" => ["analysis"]
+          "required_inputs" => ["error_text"],
+          "required_outputs" => ["analysis", "success"]
         }
       end
 
@@ -59,32 +59,35 @@ module Agentf
       end
 
       def diagnose(error, context: nil)
-        log "Diagnosing error"
-        log "  Error: #{error[0..100]}..."
-
-        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
-        )
-
-        log "Root cause: #{analysis.possible_causes.first}"
-        log "Suggested fix: #{analysis.suggested_fix}"
-
-        {
-          "error" => error,
-          "analysis" => {
-            "error_type" => analysis.error_type,
-            "possible_causes" => analysis.possible_causes,
-            "suggested_fix" => analysis.suggested_fix,
-            "stack_trace" => analysis.stack_trace
+        payload = { "error_text" => error, "context" => context }
+        execute_with_contract(context: payload) do
+          log "Diagnosing error"
+          log "  Error: #{error[0..100]}..."
+
+          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
+          )
+
+          log "Root cause: #{analysis.possible_causes.first}"
+          log "Suggested fix: #{analysis.suggested_fix}"
+
+          {
+            "success" => true,
+            "analysis" => {
+              "error_type" => analysis.error_type,
+              "possible_causes" => analysis.possible_causes,
+              "suggested_fix" => analysis.suggested_fix,
+              "stack_trace" => analysis.stack_trace
+            }
           }
-        }
+        end
       end
     end
   end

data/lib/agentf/agents/designer.rb

@@ -48,8 +48,8 @@ module Agentf
           "always" => ["Return generated component details", "Persist successful implementation pattern"],
           "ask_first" => ["Changing primary UI framework"],
           "never" => ["Return empty generated code for successful design task"],
-          "required_inputs" => [],
-          "required_outputs" => ["component", "generated_code"]
+          "required_inputs" => ["design_spec"],
+          "required_outputs" => ["component", "generated_code", "success"]
         }
       end
 
@@ -59,26 +59,29 @@ module Agentf
       end
 
       def implement_design(design_spec, framework: "react")
-        log "Implementing design: #{design_spec}"
-
-        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
-        )
-
-        log "Created component: #{spec.name}"
-
-        {
-          "design_spec" => design_spec,
-          "component" => spec.name,
-          "framework" => framework,
-          "generated_code" => spec.code
-        }
+        execute_with_contract(context: { "design_spec" => design_spec, "framework" => framework }) do
+          log "Implementing design: #{design_spec}"
+
+          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
+          )
+
+          log "Created component: #{spec.name}"
+
+          {
+            "design_spec" => design_spec,
+            "component" => spec.name,
+            "framework" => framework,
+            "generated_code" => spec.code,
+            "success" => true
+          }
+        end
       end
     end
   end

data/lib/agentf/agents/reviewer.rb

@@ -47,33 +47,35 @@ module Agentf
           "always" => ["Report approval decision", "Highlight known pitfalls in review findings"],
           "ask_first" => ["Approving with unresolved critical security issues"],
           "never" => ["Approve without any review evidence"],
-          "required_inputs" => [],
+          "required_inputs" => ["execution"],
           "required_outputs" => ["approved", "issues"]
         }
       end
 
       def review(subtask_result)
-        log "Reviewing subtask #{subtask_result['subtask_id']}"
+        execute_with_contract(context: { "execution" => subtask_result }) do
+          log "Reviewing subtask #{subtask_result['subtask_id']}"
 
-        pitfalls = memory.get_pitfalls(limit: 5)
-        memories = memory.get_recent_memories(limit: 5)
+          pitfalls = memory.get_pitfalls(limit: 5)
+          memories = memory.get_recent_memories(limit: 5)
 
-        issues = []
+          issues = []
 
-        pitfalls.each do |pitfall|
-          issues << "Warning: Known pitfall - #{pitfall['title']}" if pitfall["type"] == "pitfall"
-        end
+          pitfalls.each do |pitfall|
+            issues << "Warning: Known pitfall - #{pitfall['title']}" if pitfall["type"] == "pitfall"
+          end
 
-        approved = issues.empty?
+          approved = issues.empty?
 
-        if approved
-          log "Approved (no issues found)"
-        else
-          log "Issues found: #{issues.size}"
-          issues.each { |issue| log "  - #{issue}" }
-        end
+          if approved
+            log "Approved (no issues found)"
+          else
+            log "Issues found: #{issues.size}"
+            issues.each { |issue| log "  - #{issue}" }
+          end
 
-        { "approved" => approved, "issues" => issues }
+          { "approved" => approved, "issues" => issues }
+        end
       end
     end
   end

data/lib/agentf/agents/security.rb

@@ -48,7 +48,7 @@ module Agentf
           "always" => ["Return issue list and best practices", "Persist outcome as success or pitfall"],
           "ask_first" => ["Allowing known secret patterns in context"],
           "never" => ["Echo raw secrets in output"],
-          "required_inputs" => [],
+          "required_inputs" => ["task"],
           "required_outputs" => ["issues", "best_practices"]
         }
       end
@@ -59,30 +59,32 @@ module Agentf
       end
 
       def assess(task:, context: {})
-        log "Running security assessment"
-
-        findings = @commands.scan(task: task, context: context)
-        summary = summarize_findings(findings)
-
-        if findings["issues"].empty?
-          memory.store_success(
-            title: "Security review passed",
-            description: summary,
-            context: task,
-            tags: ["security", "pass"],
-            agent: name
-          )
-        else
-          memory.store_pitfall(
-            title: "Security findings detected",
-            description: summary,
-            context: task,
-            tags: ["security", "warning"],
-            agent: name
-          )
+        execute_with_contract(context: context.merge("task" => task)) do
+          log "Running security assessment"
+
+          findings = @commands.scan(task: task, context: context)
+          summary = summarize_findings(findings)
+
+          if findings["issues"].empty?
+            memory.store_success(
+              title: "Security review passed",
+              description: summary,
+              context: task,
+              tags: ["security", "pass"],
+              agent: name
+            )
+          else
+            memory.store_pitfall(
+              title: "Security findings detected",
+              description: summary,
+              context: task,
+              tags: ["security", "warning"],
+              agent: name
+            )
+          end
+
+          findings.merge("best_practices" => @commands.best_practices)
         end
-
-        findings.merge("best_practices" => @commands.best_practices)
       end
 
       private

data/lib/agentf/agents/specialist.rb

@@ -47,37 +47,44 @@ module Agentf
           "always" => ["Persist execution outcome", "Return deterministic success boolean"],
           "ask_first" => ["Applying architecture style changes across unrelated modules"],
           "never" => ["Claim implementation complete without execution result"],
-          "required_inputs" => [],
+          "required_inputs" => ["description"],
           "required_outputs" => ["subtask_id", "success"]
         }
       end
 
       def execute(subtask)
-        log "Executing: #{subtask['description']}"
+        normalized_subtask = subtask.merge(
+          "id" => subtask["id"] || "ad-hoc",
+          "description" => subtask["description"] || "Execute implementation step"
+        )
 
-        success = subtask.fetch("success", true)
+        execute_with_contract(context: normalized_subtask) do
+          log "Executing: #{normalized_subtask['description']}"
 
-        if success
-          memory.store_success(
-            title: "Completed: #{subtask['description']}",
-            description: "Successfully executed subtask #{subtask['id']}",
-            context: "Working on #{subtask.fetch('task', 'unknown task')}",
-            tags: ["implementation", subtask.fetch("language", "general")],
-            agent: name
-          )
-          log "Stored success memory"
-        else
-          memory.store_pitfall(
-            title: "Failed: #{subtask['description']}",
-            description: "Subtask #{subtask['id']} failed",
-            context: "Working on #{subtask.fetch('task', 'unknown task')}",
-            tags: ["failure", "implementation"],
-            agent: name
-          )
-          log "Stored pitfall memory"
-        end
+          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"
+          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"
+          end
 
-        { "subtask_id" => subtask["id"], "success" => success, "result" => "Code executed" }
+          { "subtask_id" => normalized_subtask["id"], "success" => success, "result" => "Code executed" }
+        end
       end
     end
   end

data/lib/agentf/cli/memory.rb

@@ -54,6 +54,8 @@ module Agentf
           list_tags
         when "search"
           search_memories(args)
+        when "delete"
+          delete_memories(args)
         when "neighbors"
           neighbors(args)
         when "subgraph"
@@ -315,6 +317,65 @@ module Agentf
         output_graph(result)
       end
 
+      def delete_memories(args)
+        mode = args.shift.to_s
+        case mode
+        when "id"
+          delete_by_id(args)
+        when "last"
+          delete_last(args)
+        when "all"
+          delete_all(args)
+        else
+          $stderr.puts "Error: delete requires one of: id|last|all"
+          exit 1
+        end
+      end
+
+      def delete_by_id(args)
+        id = args.shift.to_s
+        if id.empty?
+          $stderr.puts "Error: delete id requires a memory id"
+          exit 1
+        end
+
+        scope = parse_scope_option(args)
+        dry_run = parse_boolean_flag(args, "--dry-run")
+        result = @memory.delete_memory_by_id(id: id, scope: scope, dry_run: dry_run)
+        output_delete(result)
+      end
+
+      def delete_last(args)
+        limit = extract_limit(args)
+        if limit <= 0
+          $stderr.puts "Error: delete last requires -n with value > 0"
+          exit 1
+        end
+
+        scope = parse_scope_option(args)
+        type = parse_single_option(args, "--type=")
+        agent = parse_single_option(args, "--agent=")
+        dry_run = parse_boolean_flag(args, "--dry-run")
+        result = @memory.delete_recent(limit: limit, scope: scope, type: type, agent: agent, dry_run: dry_run)
+        output_delete(result)
+      end
+
+      def delete_all(args)
+        scope = parse_scope_option(args)
+        type = parse_single_option(args, "--type=")
+        agent = parse_single_option(args, "--agent=")
+        dry_run = parse_boolean_flag(args, "--dry-run")
+        confirmed = parse_boolean_flag(args, "--yes")
+
+        if !dry_run && !confirmed
+          $stderr.puts "Error: delete all requires --yes (or use --dry-run)"
+          exit 1
+        end
+
+        result = @memory.delete_all(scope: scope, type: type, agent: agent, dry_run: dry_run)
+        output_delete(result)
+      end
+
       def subgraph(args)
         seeds = args.shift.to_s.split(",").map(&:strip).reject(&:empty?)
         if seeds.empty?
@@ -363,6 +424,43 @@ module Agentf
         end
       end
 
+      def output_delete(result)
+        if result["error"]
+          if @json_output
+            puts JSON.generate({ "error" => result["error"] })
+          else
+            $stderr.puts "Error: #{result['error']}"
+          end
+          exit 1
+        end
+
+        if @json_output
+          puts JSON.generate(result)
+          return
+        end
+
+        action = result["dry_run"] ? "Planned" : "Deleted"
+        puts "#{action} #{result['deleted_count']} keys (candidates: #{result['candidate_count']})"
+        puts "Mode: #{result['mode']} | Scope: #{result['scope']}"
+        filters = result["filters"] || {}
+        puts "Filters: type=#{filters['type'] || 'any'}, agent=#{filters['agent'] || 'any'}"
+        ids = Array(result["deleted_ids"])
+        puts "Memory ids: #{ids.join(', ')}" unless ids.empty?
+      end
+
+      def parse_scope_option(args)
+        scope = parse_single_option(args, "--scope=") || "project"
+        unless %w[project all].include?(scope)
+          $stderr.puts "Error: --scope must be project or all"
+          exit 1
+        end
+        scope
+      end
+
+      def parse_boolean_flag(args, flag)
+        !args.delete(flag).nil?
+      end
+
       def output_graph(result)
         if result["error"]
           if @json_output
@@ -420,6 +518,9 @@ module Agentf
             add-pitfall               Store pitfall memory
             tags                      List all unique tags
             search <query>            Search memories by keyword
+            delete id <memory_id>     Delete one memory and related edges
+            delete last -n <count>    Delete most recent memories
+            delete all                Delete memories and graph/task keys
             neighbors <id>            Traverse graph edges from a memory id
             subgraph <ids>            Build graph from comma-separated seed ids
             summary, stats            Show summary statistics
@@ -440,6 +541,9 @@ module Agentf
             agentf memory add-lesson "Refactor strategy" "Extracted adapter seam" --agent=PLANNER --tags=architecture
             agentf memory add-success "Provider install works" "Installed copilot + opencode manifests" --agent=ENGINEER
             agentf memory search "react"
+            agentf memory delete id episode_abcd
+            agentf memory delete last -n 10 --scope=project
+            agentf memory delete all --scope=all --yes
             agentf memory neighbors episode_abcd --depth=2
             agentf memory by-tag "performance"
             agentf memory summary

data/lib/agentf/cli/router.rb

@@ -85,6 +85,8 @@ module Agentf
             AGENTF_METRICS_ENABLED=true|false   Enable/disable workflow metrics capture and CLI
             AGENTF_WORKFLOW_CONTRACT_ENABLED=true|false   Enable/disable workflow contract checks
             AGENTF_WORKFLOW_CONTRACT_MODE=advisory|enforcing|off   Contract behavior mode
+            AGENTF_AGENT_CONTRACT_ENABLED=true|false   Enable/disable per-agent contract checks
+            AGENTF_AGENT_CONTRACT_MODE=advisory|enforcing|off   Per-agent contract behavior mode
             AGENTF_DEFAULT_PACK=generic|rails_standard|rails_37signals|rails_feature_spec
             AGENTF_GEM_PATH=/path/to/gem   Path to agentf gem (for OpenCode plugin binary resolution)
 

data/lib/agentf/installer.rb

@@ -362,44 +362,127 @@ module Agentf
 
         const execFileAsync = promisify(execFile);
 
-        async function resolveAgentfBinary(directory: string): Promise<string> {
+        type AgentfBinaryResolution = {
+          binaryPath: string;
+          source: string;
+          attempts: string[];
+        };
+
+        type PreflightCache = {
+          workspaceRoot: string;
+          binaryPath: string;
+        };
+
+        let preflightCache: PreflightCache | null = null;
+
+        function buildPreflightError(attempts: string[], extraDetails?: string): Error {
+          const lines = [
+            "Agentf plugin preflight failed: unable to run a compatible agentf binary.",
+            "",
+            "Resolution attempts:",
+            ...attempts.map((attempt) => `- ${attempt}`),
+            "",
+            "Remediation:",
+            "- Set AGENTF_GEM_PATH to your installed agentf gem path (contains bin/agentf).",
+            "- Ensure your Ruby version manager shims are on PATH (rbenv/asdf/mise), then retry.",
+            "- Verify with: agentf version",
+          ];
+
+          if (extraDetails) {
+            lines.push("", "Details:", extraDetails);
+          }
+
+          return new Error(lines.join("\n"));
+        }
+
+        function formatExecFailure(error: unknown): string {
+          const failure = error as {
+            message?: string;
+            stdout?: Buffer | string;
+            stderr?: Buffer | string;
+          };
+
+          const stdout = failure.stdout?.toString().trim();
+          const stderr = failure.stderr?.toString().trim();
+          const message = failure.message?.trim();
+          const parts = [
+            message ? `message: ${message}` : null,
+            stderr ? `stderr: ${stderr}` : null,
+            stdout ? `stdout: ${stdout}` : null,
+          ].filter(Boolean);
+
+          return parts.length > 0 ? parts.join("\n") : "No additional process output.";
+        }
+
+        async function resolveAgentfBinary(directory: string): Promise<AgentfBinaryResolution> {
+          const attempts: string[] = [];
           const gemPath = process.env.AGENTF_GEM_PATH;
           if (gemPath) {
             const binaryPath = path.join(gemPath, "bin", "agentf");
             if (fs.existsSync(binaryPath)) {
-              return binaryPath;
+              attempts.push(`AGENTF_GEM_PATH succeeded: ${binaryPath}`);
+              return { binaryPath, source: "AGENTF_GEM_PATH", attempts };
             }
+            attempts.push(`AGENTF_GEM_PATH set but missing executable: ${binaryPath}`);
+          } else {
+            attempts.push("AGENTF_GEM_PATH is not set");
           }
 
           const projectRoot = path.resolve(directory);
           const projectBinary = path.join(projectRoot, "bin", "agentf");
           if (fs.existsSync(projectBinary)) {
-            return projectBinary;
+            attempts.push(`Project bin fallback succeeded: ${projectBinary}`);
+            return { binaryPath: projectBinary, source: "project-bin", attempts };
           }
+          attempts.push(`Project bin fallback missing: ${projectBinary}`);
 
           try {
             const { stdout } = await execFileAsync("command", ["-v", "agentf"], { shell: true });
             const whichPath = stdout.toString().trim();
             if (whichPath && fs.existsSync(whichPath)) {
-              return whichPath;
+              attempts.push(`PATH fallback succeeded: ${whichPath}`);
+              return { binaryPath: whichPath, source: "PATH", attempts };
             }
+            attempts.push("PATH fallback returned empty or non-existent path");
           } catch {
-            // command -v failed
+            attempts.push("PATH fallback failed: command -v agentf did not resolve");
           }
 
-          throw new Error(
-            "agentf binary not found. Set AGENTF_GEM_PATH environment variable to the path where agentf gem is installed, " +
-            "or ensure bin/agentf exists in your project root. " +
-            "Example: AGENTF_GEM_PATH=$(bundle show agentf) opencode run \"your task\""
-          );
+          throw buildPreflightError(attempts);
+        }
+
+        async function ensureAgentfPreflight(directory: string): Promise<string> {
+          const workspaceRoot = path.resolve(directory);
+          if (preflightCache && preflightCache.workspaceRoot === workspaceRoot) {
+            return preflightCache.binaryPath;
+          }
+
+          const resolution = await resolveAgentfBinary(workspaceRoot);
+
+          try {
+            await execFileAsync(resolution.binaryPath, ["version"], {
+              cwd: workspaceRoot,
+              env: process.env,
+              maxBuffer: 1024 * 1024,
+            });
+          } catch (error) {
+            throw buildPreflightError(
+              resolution.attempts,
+              [`Resolved via ${resolution.source}: ${resolution.binaryPath}`, formatExecFailure(error)].join("\n")
+            );
+          }
+
+          preflightCache = { workspaceRoot, binaryPath: resolution.binaryPath };
+          return resolution.binaryPath;
         }
 
         async function runAgentfCli(directory: string, subcommand: string, command: string, args: string[]) {
-          const binaryPath = await resolveAgentfBinary(directory);
-          const commandArgs = ["exec", "ruby", binaryPath, subcommand, command, ...args, "--json"];
+          const workspaceRoot = path.resolve(directory);
+          const binaryPath = await ensureAgentfPreflight(workspaceRoot);
+          const commandArgs = [subcommand, command, ...args, "--json"];
 
-          const { stdout } = await execFileAsync("bundle", commandArgs, {
-            cwd: path.resolve(directory),
+          const { stdout } = await execFileAsync(binaryPath, commandArgs, {
+            cwd: workspaceRoot,
             env: process.env,
             maxBuffer: 1024 * 1024 * 5,
           });
@@ -409,6 +492,8 @@ module Agentf
         }
 
         export const agentfPlugin: Plugin = async () => {
+          await ensureAgentfPreflight(process.env.PWD || process.cwd());
+
           return {
             tools: {
               "agentf-code-glob": tool({

data/lib/agentf/memory.rb

@@ -312,6 +312,68 @@ module Agentf
         all_tags.to_a
       end
 
+      def delete_memory_by_id(id:, scope: "project", dry_run: false)
+        normalized_scope = normalize_scope(scope)
+        episode_id = normalize_episode_id(id)
+        episode_key = "episodic:#{episode_id}"
+        memory = load_episode(episode_key)
+
+        return delete_result(mode: "id", scope: normalized_scope, dry_run: dry_run, error: "Memory not found: #{id}") unless memory
+        if normalized_scope == "project" && memory["project"].to_s != @project.to_s
+          return delete_result(mode: "id", scope: normalized_scope, dry_run: dry_run, error: "Memory not in current project")
+        end
+
+        keys = [episode_key]
+        keys.concat(collect_related_edge_keys(episode_ids: [episode_id], scope: normalized_scope))
+        result = delete_keys(keys.uniq, dry_run: dry_run)
+        result.merge(
+          "mode" => "id",
+          "scope" => normalized_scope,
+          "deleted_ids" => [episode_id],
+          "filters" => {}
+        )
+      end
+
+      def delete_recent(limit: 10, scope: "project", type: nil, agent: nil, dry_run: false)
+        normalized_scope = normalize_scope(scope)
+        count = [limit.to_i, 0].max
+        return delete_result(mode: "last", scope: normalized_scope, dry_run: dry_run, deleted_ids: [], filters: { "type" => type, "agent" => agent }) if count.zero?
+
+        episodes = collect_episode_records(scope: normalized_scope, type: type, agent: agent)
+        selected = episodes.sort_by { |mem| -(mem["created_at"] || 0) }.first(count)
+        episode_ids = selected.map { |mem| mem["id"].to_s }
+        keys = selected.map { |mem| "episodic:#{mem['id']}" }
+        keys.concat(collect_related_edge_keys(episode_ids: episode_ids, scope: normalized_scope))
+        result = delete_keys(keys.uniq, dry_run: dry_run)
+        result.merge(
+          "mode" => "last",
+          "scope" => normalized_scope,
+          "deleted_ids" => episode_ids,
+          "filters" => { "type" => type, "agent" => agent }
+        )
+      end
+
+      def delete_all(scope: "project", type: nil, agent: nil, dry_run: false)
+        normalized_scope = normalize_scope(scope)
+        episodic_records = collect_episode_records(scope: normalized_scope, type: type, agent: agent)
+        episode_ids = episodic_records.map { |mem| mem["id"].to_s }
+        keys = episodic_records.map { |mem| "episodic:#{mem['id']}" }
+        keys.concat(collect_related_edge_keys(episode_ids: episode_ids, scope: normalized_scope))
+
+        if type.to_s.empty? && agent.to_s.empty?
+          keys.concat(collect_edge_keys(scope: normalized_scope))
+          keys.concat(collect_semantic_keys(scope: normalized_scope))
+        end
+
+        result = delete_keys(keys.uniq, dry_run: dry_run)
+        result.merge(
+          "mode" => "all",
+          "scope" => normalized_scope,
+          "deleted_ids" => episode_ids,
+          "filters" => { "type" => type, "agent" => agent }
+        )
+      end
+
       def store_edge(source_id:, target_id:, relation:, weight: 1.0, tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR, metadata: {})
         edge_id = "edge_#{SecureRandom.hex(5)}"
         data = {
@@ -617,6 +679,134 @@ module Agentf
         { url: @redis_url }
       end
 
+      def normalize_scope(scope)
+        value = scope.to_s.strip.downcase
+        return "all" if value == "all"
+
+        "project"
+      end
+
+      def normalize_episode_id(id)
+        value = id.to_s.strip
+        value = value.sub("episodic:", "") if value.start_with?("episodic:")
+        value
+      end
+
+      def collect_episode_records(scope:, type: nil, agent: nil)
+        memories = []
+        cursor = "0"
+        loop do
+          cursor, batch = @client.scan(cursor, match: "episodic:*", count: 100)
+          batch.each do |key|
+            mem = load_episode(key)
+            next unless mem.is_a?(Hash)
+            next if scope == "project" && mem["project"].to_s != @project.to_s
+            next unless type.to_s.empty? || mem["type"].to_s == type.to_s
+            next unless agent.to_s.empty? || mem["agent"].to_s == agent.to_s
+
+            memories << mem
+          end
+          break if cursor == "0"
+        end
+        memories
+      end
+
+      def collect_related_edge_keys(episode_ids:, scope:)
+        ids = episode_ids.map(&:to_s).reject(&:empty?).to_set
+        return [] if ids.empty?
+
+        keys = []
+        cursor = "0"
+        loop do
+          cursor, batch = @client.scan(cursor, match: "edge:*", count: 100)
+          batch.each do |key|
+            edge = load_episode(key)
+            next unless edge.is_a?(Hash)
+            next if scope == "project" && edge["project"].to_s != @project.to_s
+
+            source = edge["source_id"].to_s
+            target = edge["target_id"].to_s
+            keys << key if ids.include?(source) || ids.include?(target)
+          end
+          break if cursor == "0"
+        end
+        keys
+      end
+
+      def collect_edge_keys(scope:)
+        keys = []
+        cursor = "0"
+        loop do
+          cursor, batch = @client.scan(cursor, match: "edge:*", count: 100)
+          batch.each do |key|
+            if scope == "all"
+              keys << key
+              next
+            end
+
+            edge = load_episode(key)
+            keys << key if edge.is_a?(Hash) && edge["project"].to_s == @project.to_s
+          end
+          break if cursor == "0"
+        end
+        keys
+      end
+
+      def collect_semantic_keys(scope:)
+        keys = []
+        cursor = "0"
+        loop do
+          cursor, batch = @client.scan(cursor, match: "semantic:*", count: 100)
+          batch.each do |key|
+            if scope == "all"
+              keys << key
+              next
+            end
+
+            task = @client.hgetall(key)
+            keys << key if task.is_a?(Hash) && task["project"].to_s == @project.to_s
+          end
+          break if cursor == "0"
+        end
+        keys
+      end
+
+      def delete_keys(keys, dry_run:)
+        if dry_run
+          {
+            "dry_run" => true,
+            "candidate_count" => keys.length,
+            "deleted_count" => 0,
+            "deleted_keys" => [],
+            "planned_keys" => keys
+          }
+        else
+          deleted = keys.empty? ? 0 : @client.del(*keys)
+          {
+            "dry_run" => false,
+            "candidate_count" => keys.length,
+            "deleted_count" => deleted,
+            "deleted_keys" => keys,
+            "planned_keys" => []
+          }
+        end
+      end
+
+      def delete_result(mode:, scope:, dry_run:, deleted_ids: [], filters: {}, error: nil)
+        {
+          "mode" => mode,
+          "scope" => scope,
+          "dry_run" => dry_run,
+          "candidate_count" => 0,
+          "deleted_count" => 0,
+          "deleted_keys" => [],
+          "planned_keys" => [],
+          "deleted_ids" => deleted_ids,
+          "filters" => filters,
+          "error" => error
+        }
+      end
+
       def persist_relationship_edges(episode_id:, related_task_id:, relationships:, metadata:, tags:, agent:)
         if related_task_id && !related_task_id.to_s.strip.empty?
           store_edge(source_id: episode_id, target_id: related_task_id, relation: "relates_to", tags: tags, agent: agent)

data/lib/agentf/service/providers.rb

@@ -125,6 +125,8 @@ module Agentf
           logger&.call("→ #{agent_name} Complete")
           result
         rescue StandardError => e
+          raise if e.is_a?(Agentf::AgentContractViolation)
+
           logger&.call("→ #{agent_name} Error: #{e.message}")
           { "error" => e.message, "agent" => agent_name }
         end

data/lib/agentf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agentf
-  VERSION = "0.4.0"
+  VERSION = "0.4.3"
 end

data/lib/agentf/workflow_engine.rb

@@ -166,6 +166,10 @@ module Agentf
         enriched_context["expected_test_fix"] = @workflow_state.dig("tdd", "failure_signature")
       end
 
+      if agent_name == Agentf::AgentRoles::REVIEWER
+        enriched_context["execution"] = @workflow_state["results"].last&.fetch("result", {}) || {}
+      end
+
       result = @provider.execute_agent(
         agent_name: agent_name,
         task: @workflow_state["task"],
@@ -179,7 +183,8 @@ module Agentf
         agent_name: agent_name,
         boundaries: @agents.fetch(agent_name).class.policy_boundaries,
         context: enriched_context,
-        result: result
+        result: result,
+        phase: :after
       )
       append_policy_violations(policy_violations)
 

data/lib/agentf.rb

@@ -15,7 +15,8 @@ module Agentf
   class Config
     attr_reader :redis_url
     attr_accessor :project_name, :base_path, :metrics_enabled, :workflow_contract_enabled,
-                  :workflow_contract_mode, :default_pack, :gem_path
+                  :workflow_contract_mode, :agent_contract_enabled, :agent_contract_mode,
+                  :default_pack, :gem_path
 
     def initialize
       @redis_url = normalize_redis_url(ENV.fetch("REDIS_URL", "redis://localhost:6379"))
@@ -29,6 +30,13 @@ module Agentf
       @workflow_contract_mode = normalize_contract_mode(
         ENV.fetch("AGENTF_WORKFLOW_CONTRACT_MODE", "advisory")
       )
+      @agent_contract_enabled = parse_boolean(
+        ENV.fetch("AGENTF_AGENT_CONTRACT_ENABLED", "true"),
+        default: true
+      )
+      @agent_contract_mode = normalize_contract_mode(
+        ENV.fetch("AGENTF_AGENT_CONTRACT_MODE", "enforcing")
+      )
       @default_pack = ENV.fetch("AGENTF_DEFAULT_PACK", "generic").to_s.strip.downcase
       @gem_path = ENV.fetch("AGENTF_GEM_PATH", nil)
     end
@@ -81,6 +89,7 @@ require_relative "agentf/service/providers"
 require_relative "agentf/context_builder"
 require_relative "agentf/packs"
 require_relative "agentf/agent_policy"
+require_relative "agentf/agent_execution_contract"
 require_relative "agentf/workflow_contract"
 require_relative "agentf/workflow_engine"
 require_relative "agentf/installer"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agentf
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.3
 platform: ruby
 authors:
 - Neal Deters
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-08 00:00:00.000000000 Z
+date: 2026-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -94,6 +94,7 @@ extra_rdoc_files: []
 files:
 - bin/agentf
 - lib/agentf.rb
+- lib/agentf/agent_execution_contract.rb
 - lib/agentf/agent_policy.rb
 - lib/agentf/agent_roles.rb
 - lib/agentf/agents.rb