anima-core 1.2.0 → 1.4.0

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

data/lib/shell_session.rb

@@ -1,9 +1,29 @@
 # frozen_string_literal: true
 
 require "io/console"
+require "open3"
+require "pathname"
 require "pty"
 require "securerandom"
 require "shellwords"
+require "uri"
+
+# Immutable snapshot of the shell's environment for change detection.
+# Compared between commands to produce natural-language summaries of what
+# changed — the agent discovers its environment through Bash tool responses.
+#
+# @!attribute [r] pwd
+#   @return [String, nil] current working directory
+# @!attribute [r] branch
+#   @return [String, nil] current git branch name
+# @!attribute [r] repo
+#   @return [String, nil] "owner/repo" extracted from git origin remote
+# @!attribute [r] project_files
+#   @return [Array<String>] sorted relative paths to project instruction files
+EnvironmentSnapshot = Data.define(:pwd, :branch, :repo, :project_files) do
+  # Sentinel for "never detected" — diffs against this produce a full snapshot.
+  def self.blank = new(pwd: nil, branch: nil, repo: nil, project_files: [])
+end
 
 # Persistent shell session backed by a PTY with FIFO-based stderr separation.
 # Commands share working directory, environment variables, and shell history
@@ -12,6 +32,11 @@ require "shellwords"
 # Auto-recovers from timeouts and crashes: if the shell dies, the next command
 # transparently respawns a fresh shell and restores the working directory.
 #
+# After each successful command, detects environment changes (CWD, git branch,
+# project files) and includes a natural-language summary in the result hash.
+# This replaces the old EnvironmentProbe system-prompt injection, keeping the
+# system prompt static for prompt caching.
+#
 # Uses IO.select-based deadlines instead of Timeout.timeout for all PTY reads.
 # Timeout.timeout is unsafe with PTY I/O — it uses Thread.raise which can
 # corrupt mutex state, leave resources inconsistent, and cause exceptions
@@ -35,6 +60,7 @@ class ShellSession
     @alive = false
     @finalized = false
     @pwd = nil
+    @env_snapshot = nil
     @read_buffer = +""
     self.class.cleanup_orphans
     start
@@ -47,13 +73,17 @@ class ShellSession
   # @param command [String] bash command to execute
   # @param timeout [Integer, nil] per-call timeout in seconds; overrides
   #   Settings.command_timeout when provided
+  # @param interrupt_check [Proc, nil] callable returning truthy when the
+  #   user has requested an interrupt. Polled every
+  #   {Anima::Settings.interrupt_check_interval} seconds during command execution.
   # @return [Hash] with :stdout, :stderr, :exit_code keys on success
+  # @return [Hash] with :interrupted, :stdout, :stderr keys on user interrupt
   # @return [Hash] with :error key on failure
-  def run(command, timeout: nil)
+  def run(command, timeout: nil, interrupt_check: nil)
     @mutex.synchronize do
       return {error: "Shell session is not running"} if @finalized
       restart unless @alive
-      execute_in_pty(command, timeout: timeout)
+      execute_in_pty(command, timeout: timeout, interrupt_check: interrupt_check)
     end
   rescue => error # rubocop:disable Lint/RescueException -- LLM must always get a result hash, never a stack trace
     {error: "#{error.class}: #{error.message}"}
@@ -133,6 +163,7 @@ class ShellSession
     start_stderr_reader
     init_shell
     update_pwd
+    seed_env_snapshot
     @alive = true
   end
 
@@ -229,7 +260,7 @@ class ShellSession
     end
   end
 
-  def execute_in_pty(command, timeout: nil)
+  def execute_in_pty(command, timeout: nil, interrupt_check: nil)
     clear_stderr
     marker = "__ANIMA_#{SecureRandom.hex(8)}__"
     timeout ||= Anima::Settings.command_timeout
@@ -237,10 +268,21 @@ class ShellSession
 
     @pty_stdin.puts "#{command}; __anima_ec=$?; echo; echo '#{marker}' $__anima_ec"
 
-    stdout, exit_code = read_until_marker(marker, deadline: deadline)
+    stdout, exit_code = read_until_marker(marker, deadline: deadline, interrupt_check: interrupt_check)
+
+    if exit_code == :interrupted
+      recover_shell
+      update_pwd
+      stderr = drain_stderr
+      return {
+        interrupted: true,
+        stdout: truncate(stdout),
+        stderr: truncate(stderr)
+      }
+    end
 
     if exit_code.nil?
-      recover_from_timeout
+      recover_shell
       stderr = drain_stderr
       parts = ["Command timed out after #{timeout} seconds."]
       parts << "Partial stdout:\n#{truncate(stdout)}" unless stdout.empty?
@@ -248,14 +290,16 @@ class ShellSession
       return {error: parts.join("\n\n")}
     end
 
-    update_pwd
+    env_summary = update_environment
     stderr = drain_stderr
 
-    {
+    result = {
       stdout: truncate(stdout),
       stderr: truncate(stderr),
       exit_code: exit_code
     }
+    result[:env_summary] = env_summary if env_summary
+    result
   rescue Errno::EIO, IOError
     @alive = false
     {error: "Shell session terminated unexpectedly"}
@@ -267,14 +311,23 @@ class ShellSession
   #
   # @param marker [String] unique marker to detect command completion
   # @param deadline [Float] monotonic clock deadline
+  # @param interrupt_check [Proc, nil] callable returning truthy on user interrupt
   # @return [Array(String, Integer)] stdout and exit code on success
+  # @return [Array(String, Symbol)] partial stdout and +:interrupted+ on user interrupt
   # @return [Array(String, nil)] partial stdout and nil exit code on timeout
-  def read_until_marker(marker, deadline:)
+  def read_until_marker(marker, deadline:, interrupt_check: nil)
     lines = []
     exit_code = nil
+    check_interval = interrupt_check ? [Anima::Settings.interrupt_check_interval, 0.5].max : nil
 
     loop do
-      line = gets_with_deadline(deadline)
+      line = gets_with_deadline(deadline, interrupt_check: interrupt_check, check_interval: check_interval)
+
+      if line == :interrupted
+        exit_code = :interrupted
+        break
+      end
+
       break if line.nil?
 
       line = line.chomp.delete("\r")
@@ -315,12 +368,21 @@ class ShellSession
   # Timeout.timeout (which uses Thread.raise that can corrupt mutex state
   # and leave resources inconsistent).
   #
+  # When +interrupt_check+ is provided, IO.select uses a shorter timeout
+  # (capped at {Anima::Settings.interrupt_check_interval}) and polls the
+  # callback between iterations. Returns +:interrupted+ when the callback
+  # fires, allowing the caller to send Ctrl+C and return partial output.
+  #
   # @param deadline [Float] monotonic clock deadline
+  # @param interrupt_check [Proc, nil] callable returning truthy on user interrupt
+  # @param check_interval [Float, nil] resolved interrupt check interval (seconds);
+  #   pre-computed by the caller to avoid re-reading Settings on every line
   # @return [String] line including trailing newline
+  # @return [:interrupted] when user interrupt detected
   # @return [nil] if deadline expired
   # @raise [Errno::EIO] when the PTY child process exits (Linux)
   # @raise [IOError] when the PTY file descriptor is closed
-  def gets_with_deadline(deadline)
+  def gets_with_deadline(deadline, interrupt_check: nil, check_interval: nil)
     loop do
       if (idx = @read_buffer.index("\n"))
         return @read_buffer.slice!(0..idx)
@@ -329,24 +391,29 @@ class ShellSession
       remaining = deadline - monotonic_now
       return nil if remaining <= 0
 
-      ready = IO.select([@pty_stdout], nil, nil, remaining)
-      return nil unless ready
+      select_timeout = check_interval ? [remaining, check_interval].min : remaining
 
-      begin
-        @read_buffer << @pty_stdout.read_nonblock(4096)
-      rescue IO::WaitReadable
-        # Spurious wakeup from IO.select — retry
+      ready = IO.select([@pty_stdout], nil, nil, select_timeout)
+
+      if ready
+        begin
+          @read_buffer << @pty_stdout.read_nonblock(4096)
+        rescue IO::WaitReadable
+          # Spurious wakeup from IO.select — retry
+        end
       end
+
+      return :interrupted if interrupt_check&.call
     end
   end
 
-  # Sends Ctrl+C to interrupt the running command and drains leftover output.
+  # Sends Ctrl+C and drains leftover output after a timeout or user interrupt.
   # If recovery fails, marks the session as dead (will be respawned on next run).
   #
   # @return [void]
   # @raise [Errno::EIO] when the PTY child process has exited
   # @raise [IOError] when the PTY file descriptor is closed
-  def recover_from_timeout
+  def recover_shell
     @pty_stdin.write("\x03")
     sleep 0.1
     marker = "__ANIMA_RECOVER_#{SecureRandom.hex(8)}__"
@@ -379,6 +446,33 @@ class ShellSession
     end
   end
 
+  # Captures the initial environment snapshot so the first real Bash call
+  # can diff against the actual shell state rather than a blank sentinel
+  # whose nil pwd would always trigger a "location changed" report.
+  #
+  # Sets {#env_snapshot} to a real snapshot of the current pwd, git branch,
+  # repo, and project files. Called within {#start} after {#update_pwd}
+  # and before the session is marked alive.
+  #
+  # @return [void]
+  def seed_env_snapshot
+    @env_snapshot = take_env_snapshot(EnvironmentSnapshot.blank)
+  end
+
+  # Snapshots the shell's environment and returns a natural-language summary
+  # of what changed since the last snapshot. The agent discovers its
+  # environment through these summaries in Bash tool responses.
+  #
+  # Each call only mentions what changed. Returns nil when nothing did.
+  #
+  # @return [String, nil] human-readable summary of environment changes
+  def update_environment
+    update_pwd
+    previous = @env_snapshot || EnvironmentSnapshot.blank
+    @env_snapshot = take_env_snapshot(previous)
+    describe_env_changes(previous, @env_snapshot)
+  end
+
   # Reads the shell's current working directory via the /proc filesystem.
   # @note Linux-only. Falls back silently on other platforms or if the
   #   process has exited.
@@ -388,6 +482,133 @@ class ShellSession
     # Process exited or no access — @pwd retains its previous value
   end
 
+  # Captures the current environment as an immutable snapshot.
+  # Re-detects git state on every call (branch can change without cd).
+  # Re-scans project files only when the working directory changed.
+  #
+  # @param previous [EnvironmentSnapshot] the last known snapshot
+  # @return [EnvironmentSnapshot]
+  def take_env_snapshot(previous)
+    branch, repo = detect_git
+    files = (@pwd != previous.pwd) ? scan_project_files : previous.project_files
+
+    EnvironmentSnapshot.new(pwd: @pwd, branch: branch, repo: repo, project_files: files)
+  end
+
+  # Detects git branch and repo name for the current working directory.
+  #
+  # @return [Array(String, String)] branch and repo name
+  # @return [Array(nil, nil)] when not inside a git repository
+  def detect_git
+    return [nil, nil] unless @pwd
+
+    _, status = Open3.capture2("git", "-C", @pwd, "rev-parse", "--is-inside-work-tree", err: File::NULL)
+    return [nil, nil] unless status.success?
+
+    branch = detect_git_branch
+    repo = detect_git_repo
+    [branch, repo]
+  rescue Errno::ENOENT
+    [nil, nil]
+  end
+
+  # @return [String, nil] current branch name
+  def detect_git_branch
+    output, = Open3.capture2("git", "-C", @pwd, "rev-parse", "--abbrev-ref", "HEAD", err: File::NULL)
+    output.strip.presence
+  end
+
+  # @return [String, nil] "owner/repo" extracted from the origin remote
+  def detect_git_repo
+    output, = Open3.capture2("git", "-C", @pwd, "remote", "get-url", "origin", err: File::NULL)
+    remote = output.strip
+    return unless remote.present?
+
+    extract_repo_name(remote)
+  end
+
+  # Scans for well-known project files in the current working directory.
+  #
+  # @return [Array<String>] sorted relative paths
+  def scan_project_files
+    return [] unless @pwd
+
+    base = Pathname.new(@pwd)
+    whitelist = Anima::Settings.project_files_whitelist
+    max_depth = Anima::Settings.project_files_max_depth
+
+    patterns = whitelist.product((0..max_depth).to_a).map do |filename, depth|
+      File.join(@pwd, Array.new(depth, "*"), filename)
+    end
+
+    patterns.flat_map { |pattern| Dir.glob(pattern) }
+      .map { |path| Pathname.new(path).relative_path_from(base).to_s }
+      .sort
+      .uniq
+  end
+
+  # Extracts owner/repo from a Git remote URL (SSH or HTTPS).
+  #
+  # @param remote_url [String] SSH or HTTPS remote URL
+  # @return [String] "owner/repo" path
+  def extract_repo_name(remote_url)
+    path = if remote_url.match?(%r{\A\w+://})
+      URI.parse(remote_url).path
+    else
+      remote_url.split(":").last
+    end
+    path.delete_prefix("/").delete_suffix(".git")
+  rescue URI::InvalidURIError
+    remote_url
+  end
+
+  # ─── Environment change description ──────────────────────────────
+
+  # Builds a natural-language summary describing what changed between two
+  # environment snapshots. Returns nil when nothing changed.
+  #
+  # @param old_snap [EnvironmentSnapshot]
+  # @param new_snap [EnvironmentSnapshot]
+  # @return [String, nil]
+  def describe_env_changes(old_snap, new_snap)
+    parts = []
+    parts << describe_location_change(old_snap, new_snap)
+    parts << describe_project_files(old_snap, new_snap)
+    parts.compact!
+    parts.empty? ? nil : parts.join("\n")
+  end
+
+  # @return [String, nil] location/branch change line
+  def describe_location_change(old_snap, new_snap)
+    if new_snap.pwd != old_snap.pwd
+      format_full_location(new_snap)
+    elsif new_snap.branch != old_snap.branch && new_snap.branch
+      "Branch changed to #{new_snap.branch}."
+    end
+  end
+
+  # @return [String, nil] project files line
+  def describe_project_files(old_snap, new_snap)
+    return unless new_snap.project_files.any?
+    return unless new_snap.pwd != old_snap.pwd || new_snap.project_files != old_snap.project_files
+
+    "Project has instructions in #{new_snap.project_files.join(", ")}."
+  end
+
+  # Formats the full location line for display in tool responses.
+  #
+  # @param snap [EnvironmentSnapshot]
+  # @return [String]
+  def format_full_location(snap)
+    parts = ["You are now in #{snap.pwd}"]
+    if snap.repo && snap.branch
+      parts << ", git repo #{snap.repo} on branch #{snap.branch}"
+    elsif snap.branch
+      parts << " on branch #{snap.branch}"
+    end
+    parts.join + "."
+  end
+
   def truncate(output)
     max_bytes = @max_output_bytes
     output = output.dup.force_encoding("UTF-8").scrub

data/lib/tools/base.rb

@@ -41,8 +41,30 @@ module Tools
       def schema
         {name: tool_name, description: description, input_schema: input_schema}
       end
+
+      # Per-tool character threshold for response truncation.
+      # Override in subclasses to use a custom limit, or return +nil+
+      # to skip truncation entirely (e.g. read_file tool has its own pagination).
+      #
+      # @return [Integer, nil] character threshold, or nil to skip truncation
+      def truncation_threshold
+        Anima::Settings.max_tool_response_chars
+      end
     end
 
+    # Subclasses whose schema depends on runtime context (e.g. session state,
+    # shell working directory) can implement +#dynamic_schema+. The registry
+    # calls it instead of the class-level {.schema} when present.
+    #
+    # @example
+    #   def dynamic_schema
+    #     schema = self.class.schema.deep_dup
+    #     schema[:description] = "Dynamic: #{@some_state}"
+    #     schema
+    #   end
+    #
+    # @see Think#dynamic_schema Budget-based maxLength
+
     # Accepts and discards context keywords so that the Registry can pass
     # shared dependencies (e.g. shell_session) to any tool uniformly.
     # Subclasses that need specific context should override with named kwargs.