anima-core 1.3.0 → 1.5.0

data/lib/mneme/tools/surface_memory.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Mneme
+  module Tools
+    # Surfaces a past message into Aoide's next turn as a `from_mneme`
+    # phantom tool pair. Called by Mneme's recall loop when a search hit
+    # or a viewed message clears her relevance bar.
+    #
+    # The persisted {PendingMessage} carries the original +message_id+ in
+    # its +source_name+ (and through promotion ends up inside
+    # +tool_input.message_id+ of the phantom pair), so the same memory
+    # isn't re-surfaced on later cycles — Mneme::Search already excludes
+    # Aoide's viewport, and once a recall promotes it lives there.
+    #
+    # The muse explains +why+ she's surfacing this memory. The reason is
+    # logged but not shown to Aoide — keeping the surfaced content itself
+    # clean of meta-commentary.
+    class SurfaceMemory < ::Tools::Base
+      def self.tool_name = "surface_memory"
+
+      def self.description = "Surface a memory into Aoide's next turn. Use when a specific past message is genuinely useful for what she's working on now. Pass the message_id and a short reason — one sentence explaining why she needs this *now*."
+
+      def self.input_schema
+        {
+          type: "object",
+          properties: {
+            message_id: {type: "integer"},
+            why: {type: "string", description: "One-sentence justification — kept for logs, not shown to Aoide."}
+          },
+          required: %w[message_id why]
+        }
+      end
+
+      # @param main_session [Session] the session receiving the recall
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      def execute(input)
+        message_id = input["message_id"].to_i
+        why = input["why"].to_s.strip
+
+        message = Message.find_by(id: message_id)
+        return {error: "Message #{message_id} not found"} unless message
+        return {error: "Reason cannot be blank"} if why.empty?
+
+        content = render_snippet(message)
+
+        @main_session.pending_messages.create!(
+          content: content,
+          source_type: "recall",
+          source_name: message_id.to_s,
+          message_type: "from_mneme"
+        )
+
+        Mneme.logger.info("session=#{@main_session.id} — surfaced message #{message_id}: #{why}")
+
+        "Surfaced message #{message_id}."
+      end
+
+      private
+
+      # Formats the message as the text Aoide will read when the phantom
+      # pair promotes. Headed with origin metadata, bounded by the recall
+      # snippet-token budget so long messages don't blow out her viewport.
+      #
+      # @param message [Message]
+      # @return [String]
+      def render_snippet(message)
+        origin = message.session&.name.presence || "session ##{message.session_id}"
+        raw = extract_content(message)
+        max_chars = Anima::Settings.recall_max_snippet_tokens * TokenEstimation::BYTES_PER_TOKEN
+        "message #{message.id} (#{origin}): #{raw.truncate(max_chars)}"
+      end
+
+      def extract_content(message)
+        payload = message.payload
+        case message.message_type
+        when "user_message", "agent_message", "system_message"
+          payload["content"].to_s
+        when "tool_call"
+          payload.dig("tool_input", "thoughts").to_s
+        else
+          payload["content"].to_s
+        end
+      end
+    end
+  end
+end

data/lib/mneme.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
-# Mneme — the memory department. Watches for viewport eviction and creates
-# summaries before context is lost. Named after the Greek Titaness of memory.
+# Mneme — the muse of memory. Watches for viewport eviction and creates
+# summaries before context is lost. One of the Three Muses: she remembers
+# while Melete prepares and Aoide performs.
 #
-# Mneme is the third event bus department alongside Nous (main agent) and
-# the Analytical Brain. It operates as a phantom LLM loop: observes the
-# main session, creates snapshots, but leaves no trace of its own reasoning.
+# Operates as a phantom LLM loop: observes the main session, creates
+# snapshots, but leaves no trace of her own reasoning.
 module Mneme
+  # Estimated token overhead for a synthetic +tool_use+/+tool_result+
+  # pair — the wrapper JSON that phantom promotions emit around their
+  # content (tool name, input hash, ids, framing). Added to the content's
+  # token estimate when sizing phantom pairs in the viewport.
+  TOOL_PAIR_OVERHEAD_TOKENS = 50
+
   # Dev-only logger that writes to log/mneme.log.
   # In non-development environments returns a null logger so
   # call sites don't need conditionals.

data/lib/providers/anthropic.rb

@@ -17,6 +17,34 @@ module Providers
     # subscription tokens on Sonnet/Opus. Without it, /v1/messages returns 400.
     OAUTH_PASSPHRASE = "You are Claude Code, Anthropic's official CLI for Claude."
 
+    # Rate limit header names for extraction
+    RATE_LIMIT_HEADERS = {
+      "5h_status" => "Anthropic-Ratelimit-Unified-5h-Status",
+      "5h_reset" => "Anthropic-Ratelimit-Unified-5h-Reset",
+      "5h_utilization" => "Anthropic-Ratelimit-Unified-5h-Utilization",
+      "7d_status" => "Anthropic-Ratelimit-Unified-7d-Status",
+      "7d_reset" => "Anthropic-Ratelimit-Unified-7d-Reset",
+      "7d_utilization" => "Anthropic-Ratelimit-Unified-7d-Utilization"
+    }.freeze
+
+    # Response wrapper containing both the parsed body and API metrics.
+    # Behaves like a Hash for backward compatibility (delegates to body).
+    #
+    # @!attribute [r] body
+    #   @return [Hash] parsed API response
+    # @!attribute [r] api_metrics
+    #   @return [Hash, nil] rate limits and usage data
+    ApiResponse = Data.define(:body, :api_metrics) do
+      # Delegate Hash methods to body for backward compatibility.
+      # Callers using response["content"] continue to work unchanged.
+      def [](key) = body[key]
+      def dig(...) = body.dig(...)
+      def fetch(...) = body.fetch(...)
+      def key?(key) = body.key?(key)
+      def to_h = body
+      def to_json(...) = body.to_json(...)
+    end
+
     class Error < StandardError; end
     class AuthenticationError < Error; end
     class TokenFormatError < Error; end
@@ -76,13 +104,17 @@ module Providers
     # @param model [String] Anthropic model identifier
     # @param messages [Array<Hash>] conversation messages
     # @param max_tokens [Integer] maximum tokens in the response
+    # @param include_metrics [Boolean] when true, returns an {ApiResponse}
+    #   wrapper with both body and api_metrics; when false (default),
+    #   returns just the parsed body Hash for backward compatibility
     # @param options [Hash] additional parameters (e.g. +system:+, +tools:+)
-    # @return [Hash] parsed API response
+    # @return [Hash, ApiResponse] parsed API response, or wrapper with metrics
     # @raise [TransientError] on network failures or server errors (retryable)
     # @raise [AuthenticationError] on 401/403 (permanent)
     # @raise [Error] on other API errors
-    def create_message(model:, messages:, max_tokens:, **options)
+    def create_message(model:, messages:, max_tokens:, include_metrics: false, **options)
       wrap_system_prompt!(options)
+      annotate_last_message_for_caching!(messages)
       body = {model: model, messages: messages, max_tokens: max_tokens}.merge(options)
 
       response = self.class.post(
@@ -92,7 +124,7 @@ module Providers
         timeout: Anima::Settings.api_timeout
       )
 
-      handle_response(response)
+      handle_response(response, include_metrics: include_metrics)
     rescue Errno::ECONNRESET, Net::ReadTimeout, Net::OpenTimeout, SocketError, EOFError => network_error
       raise TransientError, "#{network_error.class}: #{network_error.message}"
     end
@@ -106,7 +138,6 @@ module Providers
     # @return [Integer] estimated input token count
     # @raise [Error] on API errors
     def count_tokens(model:, messages:, **options)
-      wrap_system_prompt!(options)
       body = {model: model, messages: messages}.merge(options)
 
       response = self.class.post(
@@ -159,16 +190,56 @@ module Providers
     # Wraps the system parameter in the array-of-blocks format required by
     # Anthropic for OAuth tokens. The passphrase block is always present;
     # the caller's prompt (if any) is appended as the second block.
+    # The last block is annotated with +cache_control+ so the API caches
+    # the entire system prefix (tools are evaluated before system).
     #
     # @param options [Hash] mutable options hash (modified in place)
     # @return [void]
     def wrap_system_prompt!(options)
       prompt = options[:system]
       blocks = [{type: "text", text: OAUTH_PASSPHRASE}]
-      blocks << {type: "text", text: prompt} if prompt
+      blocks << {type: "text", text: prompt, cache_control: {type: "ephemeral"}}
       options[:system] = blocks
     end
 
+    # Annotates the last message's last content block with +cache_control+
+    # so every subsequent API call in a tool-use loop hits the prefix cache.
+    # String content is normalized to array-of-blocks format since bare
+    # strings cannot carry +cache_control+ metadata.
+    #
+    # Clears stale breakpoints from earlier messages to stay within the
+    # Anthropic 4-breakpoint limit (tools + system consume 2).
+    #
+    # @param messages [Array<Hash>] mutable messages array (modified in place)
+    # @return [void]
+    def annotate_last_message_for_caching!(messages)
+      return if messages.empty?
+
+      clear_stale_cache_breakpoints!(messages[0...-1])
+
+      last_msg = messages.last
+      content = last_msg[:content]
+
+      case content
+      when String
+        last_msg[:content] = [{type: "text", text: content, cache_control: {type: "ephemeral"}}]
+      when Array
+        last_block = content.last
+        last_block[:cache_control] = {type: "ephemeral"} if last_block
+      end
+    end
+
+    # Removes +cache_control+ from content blocks in the given messages.
+    # Called before re-annotating the last message to stay within the
+    # Anthropic 4-breakpoint limit across tool-loop rounds.
+    def clear_stale_cache_breakpoints!(messages)
+      messages.each do |msg|
+        content = msg[:content]
+        next unless content.is_a?(Array)
+        content.each { |block| block.delete(:cache_control) if block.is_a?(Hash) }
+      end
+    end
+
     def request_headers
       {
         "Authorization" => "Bearer #{token}",
@@ -178,10 +249,13 @@ module Providers
       }
     end
 
-    def handle_response(response)
+    def handle_response(response, include_metrics: false)
       case response.code
       when 200
-        response.parsed_response
+        body = response.parsed_response
+        return body unless include_metrics
+
+        ApiResponse.new(body: body, api_metrics: extract_api_metrics(response))
       when 400
         raise Error, "Bad request: #{error_message(response)}"
       when 401
@@ -199,6 +273,37 @@ module Providers
       end
     end
 
+    # Extracts rate limit headers and usage data from an HTTParty response.
+    #
+    # @param response [HTTParty::Response] raw API response
+    # @return [Hash] with "rate_limits" and "usage" string keys
+    def extract_api_metrics(response)
+      {
+        "rate_limits" => extract_rate_limits(response.headers),
+        "usage" => response.parsed_response&.dig("usage")
+      }
+    end
+
+    # Extracts rate limit values from response headers.
+    #
+    # @param headers [Hash] HTTParty headers (case-insensitive)
+    # @return [Hash] normalized rate limit data
+    def extract_rate_limits(headers)
+      return {} unless headers
+
+      RATE_LIMIT_HEADERS.transform_values do |header_name|
+        # HTTParty headers are strings; VCR replays them as arrays
+        raw = headers[header_name]
+        value = raw.is_a?(Array) ? raw.first : raw
+        # Parse numeric values (utilization, reset timestamps)
+        case value
+        when /\A\d+\z/ then value.to_i
+        when /\A\d+\.\d+\z/ then value.to_f
+        else value
+        end
+      end
+    end
+
     def error_message(response)
       response.parsed_response&.dig("error", "message") || response.message
     rescue JSON::ParserError, NoMethodError