rubino-agent 0.3.0

data/lib/rubino/context/prompt_assembler.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Context
+    # Assembles the complete prompt from all context sources.
+    # Returns the message array (system + summary + history) for LLM submission.
+    class PromptAssembler
+      # Process-wide cache of the memory snapshot keyed by session id.
+      # Captured the first time build_system_prompt runs for a session and
+      # reused on every subsequent assembly in that session — even if the
+      # agent calls Tools::MemoryTool mid-session. Rationale: without
+      # freezing, an injected memory written this turn would land in the
+      # *next* prompt and effectively self-elevate. The agent must wait
+      # for the next session (or call reset_snapshot!) for new writes to
+      # appear in the system prompt.
+      @snapshots = {}
+      @snapshots_mutex = Mutex.new
+
+      class << self
+        # Returns the cached snapshot for a session, computing it via the
+        # supplied block on first access. The block receives no args and
+        # must return the memory-context hash to freeze.
+        def snapshot_for(session_id)
+          @snapshots_mutex.synchronize do
+            @snapshots[session_id] ||= yield
+          end
+        end
+
+        # Drops the cached snapshot for a session so the next assembly
+        # captures fresh memory state. Use this when a tool call must
+        # influence the very next turn (trade-off: the freeze stops
+        # protecting against same-turn poisoning).
+        def reset_snapshot!(session_id)
+          @snapshots_mutex.synchronize { @snapshots.delete(session_id) }
+        end
+
+        # Test/teardown hook. Not part of the public API.
+        def reset_all_snapshots!
+          @snapshots_mutex.synchronize { @snapshots.clear }
+        end
+      end
+
+      def initialize(session:, memory_context:, config:, agent_definition: nil,
+                     ignore_rules: false)
+        @session = session
+        @memory_context = memory_context
+        @config = config
+        @agent_definition = agent_definition
+        # --ignore-rules suppresses project-context discovery
+        # (AGENTS.md/CLAUDE.md/.rubino.md/.cursorrules). The flag is threaded
+        # from Lifecycle so the CLI option genuinely skips discovery (#47), not
+        # just the trust gate.
+        @ignore_rules = ignore_rules
+        @message_store = Session::Store.new
+      end
+
+      # Builds and returns the full message array for LLM submission
+      def build
+        messages = []
+
+        # System prompt (always first)
+        messages << { role: "system", content: build_system_prompt }
+
+        # Session summary (if compacted)
+        summary = load_summary
+        messages << { role: "system", content: "[Session Summary]\n#{summary}" } if summary
+
+        # Conversation history. Repair tool pairing across the FULL list before
+        # mapping to wire format — this is the defensive "net" that recovers
+        # sessions already corrupted by the historical metadata-dropping bug in
+        # compaction/fork (those rows exist in prod). Mirrors Claude Code's
+        # pre-call sanitization: never emit an orphan tool block that 400s a
+        # strict provider. Conservative by design — when in doubt, keep.
+        history = repair_tool_pairs(@message_store.for_session(@session[:id]))
+        history.each do |msg|
+          messages << msg.to_context
+        end
+
+        messages
+      end
+
+      private
+
+      # Final pairing repair over the full history (a list of Message objects).
+      # Two orphan shapes 400 strict providers; we fix both, conservatively:
+      #
+      #   1. tool RESULT with no matching assistant tool_call upstream → drop it.
+      #   2. assistant tool_call whose results are ENTIRELY absent downstream →
+      #      strip its tool_calls (keep the message if it still has content,
+      #      otherwise drop it). Partially-answered calls are LEFT ALONE: pruning
+      #      a still-referenced id would itself create an orphan.
+      #
+      # Reuses ToolPairSanitizer's id predicates so the matching logic lives in
+      # one place. Returns a list of Message objects safe to map via to_context.
+      def repair_tool_pairs(history)
+        sanitizer = ToolPairSanitizer.new
+
+        # All tool_call ids declared by assistant messages anywhere in history.
+        declared_ids = history
+                       .select { |m| sanitizer.assistant_tool_call?(m) }
+                       .flat_map { |m| sanitizer.tool_call_ids(m) }
+                       .to_set
+
+        # All ids actually answered by a tool result anywhere in history.
+        answered_ids = history
+                       .select { |m| m.role == "tool" && m.tool_call_id }
+                       .map(&:tool_call_id)
+                       .to_set
+
+        repaired = []
+        history.each do |msg|
+          if msg.role == "tool" && msg.tool_call_id
+            # Drop a result whose triggering assistant call is gone.
+            next unless declared_ids.include?(msg.tool_call_id)
+
+            repaired << msg
+          elsif sanitizer.assistant_tool_call?(msg)
+            ids = sanitizer.tool_call_ids(msg)
+            if ids.any? { |id| answered_ids.include?(id) }
+              # At least one result present → keep the call intact. Partial
+              # answers stay as-is (pruning would re-orphan the kept result).
+              repaired << msg
+            else
+              # No results at all → strip tool_calls so we don't emit a toolUse
+              # with no following toolResult. Keep the surrounding prose if any.
+              stripped = strip_tool_calls(msg)
+              repaired << stripped if stripped
+            end
+          else
+            repaired << msg
+          end
+        end
+
+        repaired
+      end
+
+      # Returns a copy of an assistant message with tool_calls removed, or nil
+      # when the message would be empty afterwards (nothing left to send).
+      def strip_tool_calls(msg)
+        return nil if msg.content.nil? || msg.content.to_s.strip.empty?
+
+        metadata = msg.metadata.is_a?(Hash) ? msg.metadata.dup : {}
+        metadata.delete(:tool_calls)
+        metadata.delete("tool_calls")
+
+        Session::Message.new(
+          id: msg.id,
+          session_id: msg.session_id,
+          role: msg.role,
+          content: msg.content,
+          tool_name: msg.tool_name,
+          tool_call_id: msg.tool_call_id,
+          token_count: msg.token_count,
+          metadata: metadata,
+          created_at: msg.created_at
+        )
+      end
+
+      # Assembles the system prompt as a stack of labelled blocks:
+      #   1. Identity        — role-specific built-in prompt (or override)
+      #   2. Product preamble— config.prompts.preamble, customer-side
+      #   3. Environment     — date/OS/cwd/git/runtimes/PATH utilities
+      #   4. User profile    — from memory
+      #   5. Relevant memories
+      #   6. Skills index   — "## Skills (mandatory)" catalogue (auto-trigger)
+      #   7. Project context — AGENTS.md / CLAUDE.md walk
+      # Each block is independent: if a section is empty/disabled it just
+      # drops out without leaving a stray header.
+      def build_system_prompt
+        # Memory snapshot is frozen for the lifetime of the session — see
+        # the class-level @snapshots cache for why. The first assembly in
+        # a session captures @memory_context; later assemblies reuse it
+        # even if Memory::Store has been mutated in the meantime.
+        snapshot = self.class.snapshot_for(@session[:id]) { @memory_context }
+
+        parts = []
+        parts << agent_identity
+        product = product_preamble
+        parts << "[Product]\n#{product}" if product
+        env = environment_block
+        parts << env if env
+
+        if snapshot[:user_profile] && !snapshot[:user_profile].empty?
+          parts << "[User Profile]\n#{snapshot[:user_profile]}"
+        end
+
+        if snapshot[:relevant_memories]&.any?
+          memories_text = snapshot[:relevant_memories].map { |m| "- #{m[:content]}" }.join("\n")
+          parts << "[Relevant Memories]\n#{memories_text}"
+        end
+
+        skills_index = skills_index_block
+        parts << skills_index if skills_index
+
+        # The user-PINNED active skill (the `/skills <name>` picker): force-load
+        # its full SKILL.md into the prompt EACH turn so the model actually uses
+        # it, not just shows a chip. Sits after the skills index so the pinned
+        # skill is the most concrete, last-read instruction in the skills region.
+        active_skill = active_skill_block
+        parts << active_skill if active_skill
+
+        project_ctx = load_project_context
+        parts << "[Project Context]\n#{project_ctx}" if project_ctx
+
+        parts.join("\n\n")
+      end
+
+      # The "## Skills (mandatory)" catalogue. This is the load-bearing trigger
+      # for skill auto-activation — surfacing skills in the system prompt (not
+      # just the `skill` tool description) is what makes the model proactively
+      # scan and load a relevant skill before replying.
+      #
+      # Gated, mirroring the reference (which gates on the skills
+      # toolset being present), on both holding:
+      #   - the skills feature is enabled (config skills.enabled), and
+      #   - the `skill` tool is actually available this turn.
+      # When either fails we inject nothing. When both hold we always inject the
+      # block, even with zero skills discovered: the catalogue half drops out but
+      # the proactive-creation nudge remains, so a fresh install still gets told
+      # to distill repeatable work into a skill (PromptIndex#render handles the
+      # empty-catalogue case and never returns nil).
+      def skills_index_block
+        return nil unless skills_feature_enabled?
+        return nil unless skill_tool_available?
+
+        Skills::PromptIndex.new(
+          registry: Skills::Registry.new(
+            config: @config,
+            include_project_local: project_local_trusted?
+          )
+        ).render
+      rescue StandardError
+        nil
+      end
+
+      # The user-PINNED active skill block. When the user has activated a skill
+      # via the `/skills <name>` picker (Rubino::ActiveSkill), we force-load its
+      # FULL SKILL.md content into the system prompt every turn and prepend a
+      # strong directive naming it — so the model treats it as active and follows
+      # it without having to discover/load it via the `skill` tool. This is the
+      # load-bearing half of the picker: the chip is cosmetic, THIS is what makes
+      # the skill actually take effect.
+      #
+      # Gated on the skills feature being enabled (same gate as the index). A
+      # pinned-but-now-missing/disabled skill (deleted on disk, or toggled off)
+      # silently drops out rather than injecting an empty block. Never raises —
+      # a load failure must not take down prompt assembly — but it LOGS, so a
+      # logic error here (e.g. a signature drift) is visible instead of the
+      # pinned skill silently vanishing from the prompt (#62).
+      def active_skill_block
+        return nil unless skills_feature_enabled?
+
+        name = Rubino::ActiveSkill.current
+        return nil unless name
+
+        registry = Skills::Registry.new(
+          config: @config,
+          include_project_local: project_local_trusted?
+        )
+        return nil unless registry.enabled?(name)
+
+        content = registry.load_skill(name)
+        return nil if content.nil? || content.to_s.strip.empty?
+
+        <<~PROMPT.strip
+          ## Active skill (pinned): #{name}
+          The user has PINNED the "#{name}" skill active for this session. You MUST follow its instructions for this and every subsequent turn until it is changed. Its full content is loaded below — treat it as authoritative; you do not need to load it again with the `skill` tool.
+
+          <active_skill name="#{name}">
+          #{content.to_s.strip}
+          </active_skill>
+        PROMPT
+      rescue StandardError => e
+        Rubino.logger.debug(event: "prompt.active_skill_block_failed",
+                            error: "#{e.class}: #{e.message}")
+        nil
+      end
+
+      def skills_feature_enabled?
+        value = @config.dig("skills", "enabled")
+        value.nil? || value == true
+      end
+
+      # True when the `skill` tool is exposed to the model this turn. Honors the
+      # agent definition's tool restrictions when present, else falls back to the
+      # globally enabled tools — the same source the loop uses to pick tools.
+      def skill_tool_available?
+        tools =
+          if @agent_definition
+            @agent_definition.resolved_tools
+          else
+            Tools::Registry.instance.enabled_tools
+          end
+        tools.any? { |t| t.respond_to?(:name) && t.name == "skill" }
+      rescue StandardError
+        false
+      end
+
+      def agent_identity
+        return @agent_definition.system_prompt if @agent_definition&.system_prompt
+
+        load_builtin_prompt("build") || <<~FALLBACK.strip
+          You are a helpful AI assistant powered by rubino.
+          You can use tools to help accomplish tasks.
+          Be concise and accurate in your responses.
+        FALLBACK
+      end
+
+      def product_preamble
+        return nil unless @config.respond_to?(:prompts_preamble)
+
+        @config.prompts_preamble
+      end
+
+      def environment_block
+        return nil unless environment_enabled?
+
+        EnvironmentInspector.new(
+          extra_utilities: environment_extra_utilities
+        ).render
+      rescue StandardError
+        # The env block is a convenience; never let a probe failure
+        # (read-only filesystem, missing `git`, weird PATH) take down the
+        # whole interaction.
+        nil
+      end
+
+      def environment_enabled?
+        return true unless @config.respond_to?(:prompts_environment_enabled?)
+
+        @config.prompts_environment_enabled?
+      end
+
+      def environment_extra_utilities
+        return [] unless @config.respond_to?(:prompts_environment_extra_utilities)
+
+        @config.prompts_environment_extra_utilities
+      end
+
+      def load_builtin_prompt(name)
+        path = File.expand_path("../agent/prompts/#{name}.txt", __dir__)
+        File.exist?(path) ? File.read(path).strip : nil
+      rescue StandardError
+        nil
+      end
+
+      def load_summary
+        Session::SummaryStore.new.latest_content(@session[:id])
+      rescue StandardError
+        nil
+      end
+
+      def load_project_context
+        return nil if @ignore_rules
+        return nil unless @config.dig("memory", "project_context_enabled")
+        return nil unless project_local_trusted?
+
+        # Discover from the PRIMARY workspace root (not just Dir.pwd) so project
+        # context tracks terminal.cwd and the dir the trust gate vouched for.
+        discovery = Context::FileDiscovery.new(base_path: Rubino::Workspace.primary_root)
+        discovery.load_project_context
+      rescue StandardError
+        nil
+      end
+
+      # Folder-trust gate (proportionate; see Rubino::Trust). The cwd's
+      # AGENTS.md/etc. and its .rubino/skills are auto-injected into the system
+      # prompt, so a hostile repo could STEER the agent the moment you start
+      # there. We withhold that project-local context until the primary root is
+      # trusted — the CLI prompts once at boot / on /add-dir and remembers the
+      # answer. An already-trusted dir (or one the user never gated, e.g. a bare
+      # scratch dir with no context files) loads normally.
+      def project_local_trusted?
+        Rubino::Trust.trusted?(Rubino::Workspace.primary_root)
+      rescue StandardError
+        # Never let the trust check itself drop context on a real error; the
+        # boot-time prompt is the authoritative gate, this is defence-in-depth.
+        true
+      end
+    end
+  end
+end

data/lib/rubino/context/summary_builder.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Context
+    # Builds structured summaries from compressible message segments.
+    # Uses the LLM to generate a comprehensive summary following the template.
+    class SummaryBuilder
+      SUMMARY_TEMPLATE = <<~TEMPLATE
+        ## Goal
+        Current user objective.
+
+        ## Constraints & Preferences
+        Technical constraints, preferences, conventions.
+
+        ## Progress
+
+        ### Done
+        Completed items.
+
+        ### In Progress
+        Work in progress.
+
+        ### Blocked
+        Open blockers or errors.
+
+        ## Key Decisions
+        Technical decisions made and their rationale.
+
+        ## Relevant Files
+        Files read, modified, or created.
+
+        ## Tool Results
+        Important tool execution results.
+
+        ## Current State
+        Current session state.
+
+        ## Next Steps
+        Planned next actions.
+
+        ## Critical Context
+        Information that must not be lost.
+      TEMPLATE
+
+      def initialize(session_id:, config: nil)
+        @session_id = session_id
+        @config = config || Rubino.configuration
+      end
+
+      # Builds a summary from messages, optionally incorporating a previous summary
+      def build(messages:, previous_summary: nil)
+        content = format_messages_for_summary(messages)
+
+        prompt = build_summary_prompt(content, previous_summary)
+        @config.compression_max_summary_tokens
+
+        # Use the auxiliary compression model if configured
+        model = compression_model
+        adapter = LLM::RubyLLMAdapter.new(model_id: model)
+
+        response = adapter.chat(messages: [
+                                  { role: "system", content: summary_system_prompt },
+                                  { role: "user", content: prompt }
+                                ])
+
+        response&.content || fallback_summary(messages, previous_summary)
+      rescue StandardError
+        # If LLM fails, produce a basic extractive summary
+        fallback_summary(messages, previous_summary)
+      end
+
+      # Builds and saves the summary to the database
+      def build_and_save!
+        message_store = Session::Store.new
+        messages = message_store.for_session(@session_id)
+        return if messages.size < 10
+
+        summary = build(messages: messages, previous_summary: load_previous_summary)
+        save!(summary)
+      end
+
+      private
+
+      def summary_system_prompt
+        <<~PROMPT
+          You are a context summarizer. Your job is to create a structured summary
+          of a conversation segment that preserves all important information.
+
+          Follow this template structure:
+          #{SUMMARY_TEMPLATE}
+
+          Be concise but comprehensive. Do not lose critical technical details,
+          file paths, decisions, or error states.
+        PROMPT
+      end
+
+      def build_summary_prompt(content, previous_summary)
+        parts = []
+
+        parts << "Previous summary to incorporate:\n#{previous_summary}\n\n---\n" if previous_summary
+
+        parts << "New conversation segment to summarize:\n#{content}"
+        parts.join("\n")
+      end
+
+      def format_messages_for_summary(messages)
+        messages.map do |msg|
+          role = msg.respond_to?(:role) ? msg.role : msg[:role]
+          content = msg.respond_to?(:content) ? msg.content : msg[:content]
+          "[#{role}] #{content}"
+        end.join("\n\n")
+      end
+
+      def compression_model
+        aux_config = @config.auxiliary_compression_config
+        model = aux_config["model"]
+
+        if model && !model.empty?
+          model
+        else
+          @config.model_default
+        end
+      end
+
+      def summary_store
+        @summary_store ||= Session::SummaryStore.new
+      end
+
+      def load_previous_summary
+        summary_store.latest_content(@session_id)
+      end
+
+      def save!(content)
+        summary_store.insert(session_id: @session_id, content: content)
+      end
+
+      def fallback_summary(messages, previous_summary)
+        parts = []
+        parts << "## Previous Context\n#{previous_summary}" if previous_summary
+
+        # Extract key information heuristically
+        parts << "## Conversation Summary"
+        parts << "Messages in segment: #{messages.size}"
+
+        # Get user messages as goal indicators
+        user_msgs = messages.select { |m| (m.respond_to?(:role) ? m.role : m[:role]) == "user" }
+        unless user_msgs.empty?
+          parts << "\n### User Requests"
+          user_msgs.last(3).each do |m|
+            content = m.respond_to?(:content) ? m.content : m[:content]
+            parts << "- #{content&.slice(0, 200)}"
+          end
+        end
+
+        parts.join("\n")
+      end
+    end
+  end
+end

data/lib/rubino/context/token_budget.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Context
+    # Manages token budget calculations and determines when compaction is needed.
+    class TokenBudget
+      CHARS_PER_TOKEN = 4 # Rough approximation
+      # Fallback when the user hasn't pinned `model.context_length` in config.
+      # Generous-but-safe; truncation kicks in via `needs_compaction?` long
+      # before the real provider limit would be hit.
+      DEFAULT_CONTEXT_WINDOW = 128_000
+
+      def initialize(model_id:, config:)
+        @model_id = model_id
+        @config = config
+        @context_window = determine_context_window
+      end
+
+      attr_reader :context_window
+
+      # Returns the max tokens available for conversation
+      def available_tokens
+        override = @config.dig("context", "max_tokens")
+        override || @context_window
+      end
+
+      # Estimates token count for a set of messages
+      def estimate_tokens(messages)
+        total_chars = messages.sum { |m| (m[:content] || "").length }
+        (total_chars.to_f / CHARS_PER_TOKEN).ceil
+      end
+
+      # Returns true if the messages exceed the compaction threshold
+      def needs_compaction?(messages)
+        return false unless @config.compression_enabled?
+
+        estimated = estimate_tokens(messages)
+        threshold = (available_tokens * @config.compression_threshold).to_i
+        estimated > threshold
+      end
+
+      # Returns true if critically close to context limit
+      def critical?(messages)
+        return false unless @config.compression_enabled?
+
+        estimated = estimate_tokens(messages)
+        gateway = (available_tokens * @config.compression_gateway_threshold).to_i
+        estimated > gateway
+      end
+
+      # Returns the target token count after compaction
+      def compaction_target
+        (available_tokens * @config.compression_target_ratio).to_i
+      end
+
+      private
+
+      # Single source of truth: the user's `model.context_length` config
+      # value if set, else the default. We deliberately do NOT maintain a
+      # per-model lookup table — `assume_model_exists: true` already lets
+      # any provider-compatible model id work; if its real window differs
+      # from the default, the user pins it in config.
+      def determine_context_window
+        @config.model_context_length || DEFAULT_CONTEXT_WINDOW
+      end
+    end
+  end
+end

data/lib/rubino/context/tool_pair_sanitizer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Context
+    # Ensures tool_call and tool_result pairs are not split during compaction.
+    # If a tool_call is in the compressible section, its result must be too (and
+    # vice versa).
+    #
+    # WIRE FORMAT: an assistant tool call lives in metadata[:tool_calls] (a list
+    # of { id:, name:, arguments: }), NOT in tool_call_id — tool_call_id is only
+    # set on role:"tool" RESULT rows. The original predicate keyed off
+    # `tool_call_id && role=="assistant"`, a contradiction that never matched, so
+    # the trailing-orphan trim was inert. The methods below read metadata, and
+    # are also reused by PromptAssembler's pre-send repair pass.
+    class ToolPairSanitizer
+      # Adjusts a slice to ensure tool pairs remain intact at its boundaries.
+      def sanitize(middle_messages)
+        adjusted = middle_messages.dup
+
+        # Leading orphan: a tool RESULT whose call lives in the head section.
+        adjusted.shift while adjusted.first&.role == "tool"
+
+        # Trailing orphan: an assistant tool call whose results are NOT all
+        # present after it in this slice (e.g. interrupted turn, or results
+        # landed in the tail section). A fully-PAIRED trailing call is kept.
+        adjusted.pop while adjusted.last && trailing_unanswered_tool_call?(adjusted)
+
+        adjusted
+      end
+
+      # True when the message is an assistant turn carrying tool calls.
+      def assistant_tool_call?(message)
+        message.role == "assistant" &&
+          message.respond_to?(:metadata) && message.metadata.is_a?(Hash) &&
+          !Array(message.metadata[:tool_calls]).empty?
+      end
+
+      # The tool_call ids declared by an assistant message. Handles both
+      # symbol and string keys — metadata is hydrated with symbolize_names but
+      # in-memory messages (pre-persist) may carry string keys.
+      def tool_call_ids(message)
+        Array(message.metadata[:tool_calls]).map { |tc| tc[:id] || tc["id"] }.compact
+      end
+
+      private
+
+      # The last message is an unanswered assistant tool call: it declares ids
+      # that are not all satisfied by role:"tool" results appearing after it.
+      def trailing_unanswered_tool_call?(messages)
+        last = messages.last
+        return false unless assistant_tool_call?(last)
+
+        ids = tool_call_ids(last)
+        return true if ids.empty? # malformed call with no id → cannot be paired
+
+        answered = answered_ids(messages, after_index: messages.length - 1)
+        !ids.all? { |id| answered.include?(id) }
+      end
+
+      # Set of tool_call_ids answered by role:"tool" messages positioned after
+      # the given index in the slice.
+      def answered_ids(messages, after_index:)
+        messages[(after_index + 1)..]
+          &.select { |m| m.role == "tool" && m.tool_call_id }
+          &.map(&:tool_call_id)
+          &.to_set || Set.new
+      end
+    end
+  end
+end