octo-agent 0.11.2

data/lib/octo/agent/memory_updater.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Octo
+  class Agent
+    # Long-term memory update functionality.
+    #
+    # Runs at the end of a qualifying task to persist important knowledge
+    # into ~/.octo/memories/. The LLM decides:
+    #   - Which topics were discussed
+    #   - Which memory files to update or create
+    #   - How to merge new info with existing content
+    #   - What to drop to stay within the per-file token limit
+    #
+    # Architecture:
+    #   Memory update runs as a **forked subagent**, NOT inline in the
+    #   main agent's loop. The subagent inherits the main agent's history
+    #   (so it can see what happened) via +fork_subagent+'s standard
+    #   deep-clone, and inherits the same model/tools so prompt-cache is
+    #   reused maximally. The subagent runs synchronously; when it returns,
+    #   the main agent prints +show_complete+.
+    #
+    #   This gives us, structurally:
+    #     - Clean main-agent history (no memory_update messages to clean up)
+    #     - Correct visual ordering ([OK] Task Complete is the LAST thing
+    #       printed — the memory-update progress finishes before it)
+    #     - Independent cost accounting (task cost vs. memory update cost)
+    #     - Natural recursion guard (+@is_subagent+ blocks re-entry)
+    #
+    # Trigger condition:
+    #   - Iteration count >= MEMORY_UPDATE_MIN_ITERATIONS (skip trivial tasks)
+    #   - Not already a subagent (no recursion)
+    #   - Memory update is enabled in config
+    module MemoryUpdater
+      # Minimum LLM iterations for this task before triggering memory update.
+      # Set high enough to skip short utility tasks (commit, deploy, etc.)
+      MEMORY_UPDATE_MIN_ITERATIONS = 10
+
+      MEMORIES_DIR = File.expand_path("~/.octo/memories")
+
+      # Check if memory update should be triggered for this task.
+      # Only triggers when the task had enough LLM iterations,
+      # skipping short utility tasks (e.g. commit, deploy).
+      # @return [Boolean]
+      def should_update_memory?
+        return false unless memory_update_enabled?
+        return false if @is_subagent  # Subagents never update memory
+
+        task_iterations = @iterations - (@task_start_iterations || 0)
+        task_iterations >= MEMORY_UPDATE_MIN_ITERATIONS
+      end
+
+      # Run memory update as a forked subagent.
+      #
+      # This is called by +Agent#run+ on the success path, AFTER the main
+      # loop exits and BEFORE +show_complete+ is printed. It blocks until
+      # the subagent finishes, so the visual order is structurally correct:
+      #
+      #   ... task output ...
+      #   [progress] Updating long-term memory… (spinner)
+      #   [progress finishes]
+      #   [OK] Task Complete
+      #
+      # Safe to call unconditionally; returns early if preconditions fail.
+      # Never raises for "no update needed" — only propagates genuine errors
+      # (+Octo::AgentInterrupted+ for Ctrl+C, other exceptions are caught
+      # and logged so memory-update failures never mask the parent task's
+      # result).
+      def run_memory_update_subagent
+        return unless should_update_memory?
+
+        handle = @ui&.start_progress(message: "Updating long-term memory…", style: :primary)
+
+        # Fork subagent inheriting main agent's model, tools, and history.
+        # Maximizes prompt-cache reuse: same model, same tool set, same
+        # cloned history — only the +system_prompt_suffix+ (the memory
+        # update instructions) and the final "Please proceed." user turn
+        # are new, landing on top of a warm cache.
+        subagent = fork_subagent(system_prompt_suffix: build_memory_update_prompt)
+
+        # Memory update is a background consolidation task — never prompt
+        # the user for confirmation on memory file writes. The subagent
+        # has its own config copy (fork_subagent does deep_copy), so this
+        # doesn't affect the parent.
+        sub_config = subagent.instance_variable_get(:@config)
+        sub_config.permission_mode = :auto_approve if sub_config.respond_to?(:permission_mode=)
+
+        begin
+          result = subagent.run("Please proceed.")
+        rescue Octo::AgentInterrupted
+          # User pressed Ctrl+C during memory update. Propagate so the
+          # parent agent's interrupt handler runs.
+          raise
+        rescue StandardError => e
+          # Memory update failures are NEVER fatal to the parent task.
+          # Log and move on — the user's actual work is already done.
+          @debug_logs << {
+            timestamp: Time.now.iso8601,
+            event: "memory_update_error",
+            error_class: e.class.name,
+            error_message: e.message,
+            backtrace: e.backtrace&.first(10)
+          }
+          Octo::Logger.error("memory_update_error", error: e)
+          return
+        ensure
+          handle&.finish
+        end
+
+        return unless result
+
+        # Only surface a completion info line if the subagent actually
+        # wrote something to memory. The common "No memory updates needed."
+        # path stays silent to avoid visual noise.
+        if subagent_wrote_memory?(subagent)
+          @ui&.show_info("Memory updated: #{result[:iterations]} iterations")
+        end
+      end
+
+      private def memory_update_enabled?
+        # Check config flag; default to true if not set
+        return true unless @config.respond_to?(:memory_update_enabled)
+
+        @config.memory_update_enabled != false
+      end
+
+      # Inspect the subagent's history for a successful write/edit tool
+      # call targeting a memory file. Used to decide whether to surface a
+      # "Memory updated" info line (option C — silent when nothing changed).
+      # @param subagent [Octo::Agent]
+      # @return [Boolean]
+      private def subagent_wrote_memory?(subagent)
+        return false unless subagent.respond_to?(:history) && subagent.history
+
+        subagent.history.to_a.any? do |msg|
+          next false unless msg.is_a?(Hash)
+
+          # Match OpenAI-style tool_calls on assistant messages …
+          tool_calls = msg[:tool_calls] || msg["tool_calls"]
+          if tool_calls.is_a?(Array) && tool_calls.any?
+            next true if tool_calls.any? do |tc|
+              name = tc.dig(:function, :name) || tc.dig("function", "name") || tc[:name] || tc["name"]
+              %w[write edit].include?(name.to_s)
+            end
+          end
+
+          # … and Anthropic-style content blocks with type=tool_use.
+          content = msg[:content] || msg["content"]
+          if content.is_a?(Array)
+            next true if content.any? do |block|
+              block.is_a?(Hash) &&
+                (block[:type] == "tool_use" || block["type"] == "tool_use") &&
+                %w[write edit].include?((block[:name] || block["name"]).to_s)
+            end
+          end
+
+          false
+        end
+      rescue StandardError
+        # Defensive: never let introspection errors break memory update.
+        false
+      end
+
+      # Build the memory update prompt for the forked subagent.
+      #
+      # Architecture:
+      #   - Decision (whitelist) lives HERE — MemoryUpdater is the trigger
+      #     and decides whether/what to persist.
+      #   - Execution (file naming, merging, frontmatter, size limits) lives
+      #     in the persist-memory skill — MemoryUpdater loads SKILL.md
+      #     directly via SkillManager and embeds it as the executor manual.
+      #
+      #   We do NOT call invoke_skill here (that would fork a second
+      #   subagent — the persist-memory skill is fork_agent:true). Instead
+      #   the subagent we already forked plays both roles: it reads the
+      #   whitelist, decides what (if anything) to persist, and follows
+      #   the embedded SKILL.md rules to write the files.
+      #
+      # @return [String]
+      private def build_memory_update_prompt
+        executor_manual = load_persist_memory_skill_body
+
+        <<~PROMPT
+          ═══════════════════════════════════════════════════════════════
+          MEMORY UPDATE MODE
+          ═══════════════════════════════════════════════════════════════
+          The conversation above has ended. You are now in MEMORY UPDATE MODE.
+
+          ## Default: Do NOT write anything.
+
+          Memory writes are expensive. Only write if the session contains at least one of the
+          following high-value signals. If NONE apply, respond immediately with:
+          "No memory updates needed." and STOP — do not use any tools.
+
+          ## Whitelist: Write ONLY if at least one condition is met
+
+          1. **Explicit decision** — The user made a clear technical, product, or process decision
+             that will affect future work (e.g. "we'll use X instead of Y going forward").
+          2. **New persistent context** — The user introduced project background, constraints, or
+             goals that are not already obvious from the code (e.g. a new feature direction,
+             a deployment target, a team convention).
+          3. **Correction of prior knowledge** — The user corrected a previous misunderstanding
+             or the agent discovered that an existing memory is wrong or outdated.
+          4. **Stated preference** — The user expressed a clear personal or team preference about
+             how they want the agent to behave, communicate, or write code.
+
+          ## What does NOT qualify (skip these entirely)
+
+          - Running tests, fixing lint, formatting code
+          - Committing, deploying, or releasing
+          - Answering a one-off question or explaining a concept
+          - Any task that produced no lasting decisions or preferences
+          - Repeating or slightly rephrasing what is already in memory
+
+          ═══════════════════════════════════════════════════════════════
+          EXECUTOR MANUAL (from persist-memory skill)
+          ═══════════════════════════════════════════════════════════════
+          If — and ONLY if — the whitelist matched, follow the manual below
+          to actually write the files. The manual owns file naming, merging,
+          frontmatter, and size limits. Treat it as authoritative for
+          execution; ignore any "should I write?" framing inside it (that
+          decision has already been made above).
+
+          #{executor_manual}
+
+          ───────────────────────────────────────────────────────────────
+          Begin by checking the whitelist. If no condition is met, stop immediately.
+        PROMPT
+      end
+
+      # Load the persist-memory skill's expanded body (frontmatter stripped,
+      # template variables like <%= memories_meta %> resolved).
+      #
+      # The persist-memory skill is a built-in default skill — it is always
+      # present. If it isn't, that's a build/install bug and we want it to
+      # surface loudly rather than silently degrade.
+      #
+      # @return [String]
+      private def load_persist_memory_skill_body
+        skill = @skill_loader.find_by_name("persist-memory")
+        raise "persist-memory skill not found — built-in skill is missing" unless skill
+
+        skill.process_content(template_context: build_template_context)
+      end
+    end
+  end
+end

data/lib/octo/agent/message_compressor.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Octo
+  # Message compressor using Insert-then-Compress strategy
+  #
+  # New Strategy: Instead of creating a separate API call for compression,
+  # we insert a compression instruction into the current conversation flow.
+  # This allows us to reuse the existing cache (system prompt + tools) and
+  # only pay for processing the new compression instruction.
+  #
+  # Flow:
+  # 1. Agent detects compression threshold is reached
+  # 2. Compressor builds a compression instruction message
+  # 3. Agent inserts this message and calls LLM (with cache reuse!)
+  # 4. LLM returns compressed summary
+  # 5. Compressor rebuilds message list: system + summary + recent messages
+  # 6. Agent continues with new message list (cache will rebuild from here)
+  #
+  # Benefits:
+  # - Compression call reuses existing cache (huge token savings)
+  # - Only one cache rebuild after compression (vs two with old approach)
+  #
+  class MessageCompressor
+    COMPRESSION_PROMPT = <<~PROMPT.freeze
+      ═══════════════════════════════════════════════════════════════
+      CRITICAL: TASK CHANGE - MEMORY COMPRESSION MODE
+      ═══════════════════════════════════════════════════════════════
+      The conversation above has ENDED. You are now in MEMORY COMPRESSION MODE.
+
+      CRITICAL INSTRUCTIONS - READ CAREFULLY:
+
+      1. This is NOT a continuation of the conversation
+      2. DO NOT respond to any requests in the conversation above
+      3. DO NOT call ANY tools or functions
+      4. DO NOT use tool_calls in your response
+      5. Your response MUST be PURE TEXT ONLY
+
+      YOUR ONLY TASK: Create a comprehensive summary of the conversation above.
+
+      REQUIRED RESPONSE FORMAT:
+      First output a <topics> line listing 3-6 key topic phrases (comma-separated, concise).
+      Then output the full summary wrapped in <summary> tags.
+
+      Example format:
+      <topics>Rails setup, database config, deploy pipeline, Tailwind CSS</topics>
+      <summary>
+      ...full summary text...
+      </summary>
+
+      Focus on:
+      - User's explicit requests and intents
+      - Key technical concepts and code changes
+      - Files examined and modified
+      - Errors encountered and fixes applied
+      - Current work status and pending tasks
+
+      Begin your response NOW. Remember: PURE TEXT only, starting with <topics> then <summary>.
+    PROMPT
+
+    def initialize(client, model: nil)
+      @client = client
+      @model = model
+    end
+
+    # Generate compression instruction message to be inserted into conversation
+    # This enables cache reuse by using the same API call with tools
+    # 
+    # SIMPLIFIED APPROACH:
+    # - Don't duplicate conversation history in the compression message
+    # - LLM can already see all messages, just ask it to compress
+    # - Keep the instruction small for better cache efficiency
+    #
+    # @param messages [Array<Hash>] Original conversation messages
+    # @param recent_messages [Array<Hash>] Recent messages to keep uncompressed (optional)
+    # @return [Hash] Compression instruction message to insert, or nil if nothing to compress
+    def build_compression_message(messages, recent_messages: [])
+      # Get messages to compress (exclude system message and recent messages)
+      messages_to_compress = messages.reject { |m| m[:role] == "system" || recent_messages.include?(m) }
+
+      # If nothing to compress, return nil
+      return nil if messages_to_compress.empty?
+
+      # Simple compression instruction - LLM can see the history already
+      { 
+        role: "user", 
+        content: COMPRESSION_PROMPT,
+        system_injected: true
+      }
+    end
+
+    # Parse LLM response and rebuild message list with compression
+    # @param compressed_content [String] The compressed summary from LLM
+    # @param original_messages [Array<Hash>] Original messages before compression
+    # @param recent_messages [Array<Hash>] Recent messages to preserve
+    # @param chunk_path [String, nil] Path to the archived chunk MD file (if saved)
+    # @param pulled_back_messages [Array<Hash>] Messages temporarily popped from the
+    #   tail of @history before the compression LLM call (to free up token budget so
+    #   the compression call itself doesn't overflow context). These are NOT discarded —
+    #   they are reattached to the tail of the rebuilt history so recent task progress
+    #   is preserved. Default: [] (normal compression path doesn't need this).
+    # @return [Array<Hash>] Rebuilt message list: system + compressed + recent + pulled_back
+    def rebuild_with_compression(compressed_content, original_messages:, recent_messages:, chunk_path: nil, topics: nil, previous_chunks: [], pulled_back_messages: [])
+      # Find and preserve system message
+      system_msg = original_messages.find { |m| m[:role] == "system" }
+
+      # Parse the compressed result, embedding previous chunk references so the
+      # new summary carries a complete index of all older archives. This avoids
+      # keeping all prior compressed_summary messages in active history while
+      # still giving the AI a path to find old conversations via file_reader.
+      parsed_messages = parse_compressed_result(compressed_content,
+                                                chunk_path: chunk_path,
+                                                topics: topics,
+                                                previous_chunks: previous_chunks)
+
+      # If parsing fails or returns empty, raise error
+      if parsed_messages.nil? || parsed_messages.empty?
+        raise "LLM compression failed: unable to parse compressed messages"
+      end
+
+      # Return system message + compressed messages + recent messages + pulled_back messages.
+      # Strip any system messages from recent_messages as a safety net —
+      # get_recent_messages_with_tool_pairs already excludes them, but this
+      # guard ensures we never end up with duplicate system prompts even if
+      # the caller passes an unfiltered list.
+      #
+      # pulled_back_messages: messages that were temporarily popped from the tail
+      # of @history before the compression LLM call (to free up token budget so
+      # the compression call itself doesn't overflow context). They are reattached
+      # here to preserve recent task progress.
+      safe_recent = recent_messages.reject { |m| m[:role] == "system" }
+      safe_pulled_back = pulled_back_messages.reject { |m| m[:role] == "system" }
+      [system_msg, *parsed_messages, *safe_recent, *safe_pulled_back].compact
+    end
+
+
+    # Parse topics tag from compressed content.
+    # Returns the topics string if found, nil otherwise.
+    # e.g. "<topics>Rails setup, database config</topics>" → "Rails setup, database config"
+    def parse_topics(content)
+      m = content.match(/<topics>(.*?)<\/topics>/m)
+      m ? m[1].strip : nil
+    end
+
+    def parse_compressed_result(result, chunk_path: nil, topics: nil, previous_chunks: [])
+      # Return the compressed result as a single user message (role: "user").
+      #
+      # Why role:"user" instead of "assistant":
+      #   When all original user messages get archived into the chunk during compression
+      #   (e.g. a long single-turn `/slash` task), the rebuilt history can end up as
+      #   `system → assistant(summary) → assistant(tool_calls) → tool → …` with NO user
+      #   message anywhere. Strict providers (notably DeepSeek V4 thinking mode) reject
+      #   this as a malformed turn structure with a misleading
+      #   "reasoning_content must be passed back" 400 error.
+      #
+      # Marking it as a user message gives the conversation a valid turn boundary.
+      # `system_injected: true` ensures the UI's replay_history still hides it from
+      # the chat panel (the real-user filter excludes system_injected messages), while
+      # INTERNAL_FIELDS in MessageHistory strips the marker before the API payload is
+      # built — so DeepSeek/OpenAI/Anthropic only see a plain `{role:"user", content:…}`.
+      #
+      # The `compressed_summary: true` flag is preserved so that replay_history still
+      # routes this message through the chunk-expansion path (which keys off that flag,
+      # not the role).
+      #
+      # @param topics [String, nil] Short topic description extracted from <topics> tag
+      # @param previous_chunks [Array<Hash>] Info about older chunk files
+      #   Each hash: { basename:, path:, topics: }
+      content = result.to_s.strip
+
+      if content.empty?
+        []
+      else
+        # Strip out the <topics> block — it's metadata for the chunk file, not for AI context
+        content_without_topics = content.gsub(/<topics>.*?<\/topics>\n*/m, "").strip
+
+        # Build previous chunks index section — links to older chunk files so the AI
+        # can find earlier conversations without keeping all prior compressed_summary
+        # messages in the active history. Shows newest chunks first (reverse order),
+        # capped at 10 to keep the message size bounded.
+        previous_chunks_section = ""
+        if previous_chunks.any?
+          max_visible = 10
+          visible = previous_chunks.last(max_visible).reverse
+          older_count = previous_chunks.size - visible.size
+
+          previous_chunks_section = "\n\n---\n📁 **Previous chunks (newest first):**\n"
+          visible.each do |pc|
+            topic_str = pc[:topics] ? " — #{pc[:topics]}" : ""
+            previous_chunks_section += "- `#{pc[:basename]}`#{topic_str}\n"
+          end
+
+          if older_count > 0
+            oldest = previous_chunks.first
+            previous_chunks_section += "- ... and #{older_count} older chunks back to `#{oldest[:basename]}`\n"
+          end
+
+          previous_chunks_section += "_Use `file_reader` to recall details from these chunks._"
+        end
+
+        # Inject chunk anchor so AI knows where to find original conversation for THIS chunk
+        anchor = ""
+        if chunk_path
+          anchor = "\n\n---\n📁 **Current chunk archived at:** `#{chunk_path}`\n" \
+                   "_Use `file_reader` tool to recall details from this chunk._"
+        end
+
+        # Prefix lets the model recognise this is injected context, not a user utterance.
+        # Order: summary → previous chunks → current anchor (chronological)
+        framed_content = "[Compressed conversation summary — previous turns archived]\n\n" \
+                         "#{content_without_topics}" \
+                         "#{previous_chunks_section}" \
+                         "#{anchor}"
+
+        [{
+          role: "user",
+          content: framed_content,
+          compressed_summary: true,
+          chunk_path: chunk_path,
+          topics: topics,
+          system_injected: true
+        }]
+      end
+    end
+  end
+end