protege 0.1.0.alpha.1

data/app/resolvers/README.md

@@ -0,0 +1,255 @@
+# Resolvers (engine-internal reference)
+
+> Engineering reference for the engine's built-in resolvers and the exact payload they produce.
+> User-facing docs live in `site/developer-experience/extensions/resolvers.md`; this file is the
+> precise contract for contributors working in the engine.
+
+A **resolver** assembles the context the LLM sees *before* an inference run. Each persona declares an
+ordered chain of resolvers (`message_resolvers` for replies, `responsibility_resolvers` for scheduled
+runs); the harness runs the chain, concatenates every resolver's output, and hands the result to the
+provider as the opening messages of the request.
+
+Resolvers are **not** auto-discovered — they are added to a chain explicitly, and **order matters**
+(the chain's output is concatenated in declaration order). Built-in resolvers live in
+`protege/resolvers/` under this directory and subclass `Protege::Resolver`
+(`engine/lib/protege/resolver_base.rb`).
+
+---
+
+## The contract
+
+Every resolver implements one method:
+
+```ruby
+def resolve(context:) # => ModelMessage | Array<ModelMessage> | nil
+```
+
+- **Input:** a `Protege::Orchestrator::Context` (see [Context](#the-context)).
+- **Output (this is the whole spec):** one **`ModelMessage`**, an **`Array`** of them, or **`nil`**
+  to contribute nothing — the chain coerces all three shapes. Build messages with the `message` helper
+  (`message(role:, content:, tool_call_id: nil, tool_calls: nil)`) rather than the raw constructor.
+
+There is no other return type. Anything a resolver wants to put in front of the model — a system
+prompt, prior conversation, retrieved records, tool history — is expressed as one or more
+`ModelMessage` objects. That single object type is the payload every resolver produces and the
+common currency the chain concatenates.
+
+---
+
+## The payload: `ModelMessage`
+
+Defined in `engine/lib/protege/inference/provider/message.rb`. It is the *same* value object used
+throughout the inference layer (requests and responses), so what a resolver emits is exactly what the
+provider serializes onto the wire.
+
+```ruby
+Message = Data.define(:role, :content, :tool_call_id, :tool_calls)
+# initialize(role:, content:, tool_call_id: nil, tool_calls: nil)
+```
+
+| Field          | Type                              | Required | Meaning |
+|----------------|-----------------------------------|----------|---------|
+| `role`         | `Symbol`                          | yes      | One of `:system`, `:user`, `:assistant`, `:tool`. |
+| `content`      | `String` **or** `Array<Part>`     | yes      | Text, or an array of typed parts (multimodal). May be `""`. |
+| `tool_call_id` | `String`                          | no       | **Only** meaningful when `role: :tool` — correlates a tool result to its call. |
+| `tool_calls`   | `Array<ToolCall>`                 | no       | **Only** meaningful when `role: :assistant` — tool calls the model is requesting. |
+
+### `content` normalization
+
+`Message#parts` normalizes `content` to an array of parts:
+
+```ruby
+def parts
+  content.is_a?(Array) ? content : [TextPart.new(text: content)]
+end
+```
+
+So a `String` is the text-only shorthand for `[TextPart.new(text: content)]`. Pass an `Array<Part>`
+directly for multimodal content.
+
+### Part value objects
+
+Under `engine/lib/protege/inference/provider/`:
+
+| Part           | Definition                                  | Notes |
+|----------------|---------------------------------------------|-------|
+| `TextPart`     | `Data.define(:text)`                        | Plain text. |
+| `ImagePart`    | `Data.define(:media_type, :data)`           | `data` is **Base64** bytes; `media_type` e.g. `"image/png"`. Vision models read it. |
+| `DocumentPart` | `Data.define(:filename, :media_type, :data)`| `data` is **Base64** bytes; used for PDFs. |
+
+### `ToolCall` (for `role: :assistant` messages)
+
+`engine/lib/protege/inference/provider/tool_call.rb`:
+
+```ruby
+ToolCall = Data.define(:id, :name, :input)
+# id:    String  — provider-assigned, correlates the eventual :tool result
+# name:  String  — snake_case tool name
+# input: Hash    — parsed arguments matching the tool's input schema
+```
+
+### Which shape goes with which role
+
+| `role`       | Typical `content`        | `tool_calls` | `tool_call_id` | Emitted by |
+|--------------|--------------------------|--------------|----------------|------------|
+| `:system`    | `String` (instructions)  | —            | —              | `LoadFileResolver`, `LoadTextResolver`, `LoadRecordResolver` (default) |
+| `:user`      | `String` or `Array<Part>`| —            | —              | `ThreadHistoryResolver` (inbound turns); any loader with `role: :user` |
+| `:assistant` | `String` (may be `""`)   | `Array<ToolCall>` when replaying a tool round | — | `ThreadHistoryResolver` (outbound turns, and the tool-call turns) |
+| `:tool`      | `String` (result JSON)   | —            | `String` (the call id) | `ThreadHistoryResolver` (replayed tool results) |
+
+> Every `:tool` message must be preceded by an `:assistant` message whose `tool_calls` include a
+> matching `id`. `ThreadHistoryResolver` reconstructs these as a paired block, and the resolver chain
+> preserves order — never interleave a lone `:tool` message.
+
+---
+
+## How the chain assembles the final payload
+
+`Protege::Orchestrator::ResolverChain#run` (`engine/lib/protege/orchestrator/resolver_chain.rb`):
+
+```ruby
+def run(context)
+  @entries.flat_map do |klass, args, kwargs, block|
+    Array(klass.new(*args, **kwargs, &block).resolve(context:))
+  end
+end
+```
+
+- Each resolver is instantiated fresh per run and `resolve(context:)` is called.
+- Its return is wrapped in `Array(...)`: **`nil` → `[]`**, a single message → `[message]`, an array →
+  unchanged.
+- `flat_map` concatenates every resolver's contribution into **one flat, ordered
+  `Array<ModelMessage>`** — in chain declaration order.
+
+That array becomes `context_messages` in `Inference.build_request`
+(`engine/lib/protege/inference.rb`):
+
+```ruby
+def build_request(user_content: nil, tools: [], context_messages: [])
+  messages  = Array(context_messages)
+  messages += [ModelMessage.new(role: :user, content: user_content)] unless user_content.nil?
+
+  Provider::Request.new(messages:, tools:)
+end
+```
+
+So the request's message list is, in order:
+
+```
+[ …every resolver's messages, concatenated in chain order… ] + [ optional trailing :user turn ]
+```
+
+- **Reply runs** pass the inbound email body (a `String`, or `Array<Part>` when it has attachments) as
+  `user_content`, appended as the closing `:user` message.
+- **Scheduled (responsibility) runs** pass `user_content: nil` — the resolver chain assembles the
+  *entire* message list itself (including the responsibility's instructions, typically via
+  `LoadTextResolver`).
+
+**The complete payload the resolvers produce together = the flat, ordered array of `ModelMessage`
+objects above.** Nothing else. Get the roles, order, and (for tool turns) the assistant/tool pairing
+right, and the request is well-formed.
+
+---
+
+## The context
+
+`resolve(context:)` receives a `Protege::Orchestrator::Context`. Attributes available:
+
+| Attribute        | Type                          | Reply run           | Scheduled run |
+|------------------|-------------------------------|---------------------|---------------|
+| `persona`        | `Protege::Persona`            | present             | present |
+| `config`         | `Protege::Configuration`      | present (frozen)    | present (frozen) |
+| `logger`         | `Logger`                      | present             | present |
+| `correlation_id` | `String, nil`                 | present             | present |
+| `message`        | `Protege::Message`            | **present**         | `nil` |
+| `responsibility` | `Protege::Responsibility`     | `nil`               | **present** |
+
+A resolver used in both chains must treat the field it doesn't expect as `nil` (e.g. guard
+`context.message` before reading `.email_thread`). The context is frozen, so resolvers read from it —
+they never mutate it.
+
+---
+
+## Built-in resolvers
+
+All live in `app/resolvers/protege/` as flat `Protege::<Name>` constants (e.g.
+`Protege::ThreadHistoryResolver`); a persona names one by that constant. Each returns a `ModelMessage`,
+an array of them, or `nil`.
+
+### `ThreadHistoryResolver`
+
+Replays a thread's prior conversation **and the agent's tool use between turns**, so the agent has
+memory across exchanges.
+
+- **Constructor:** `initialize(limit: 50, include_tool_calls: true)`
+  - `limit` — most-recent-N prior messages (chronological); `nil` for all.
+  - `include_tool_calls` — weave recorded `ToolUse` rows back in (default `true`).
+- **Returns:** `nil` when the thread has no prior content; otherwise an ordered array of:
+  - one message per prior message — `role: :user` (inbound) or `:assistant` (outbound), `content:`
+    the readable body (plain text, falling back to stripped HTML) plus an attachment note when present;
+    the *current* inbound message is excluded (it arrives as the trailing `:user` turn).
+  - for each prior turn's tool use (when `include_tool_calls`): one `:assistant` message with
+    `content: ''` and `tool_calls: Array<ToolCall>`, followed by one `:tool` message per result
+    (`tool_call_id:` set, `content:` the result JSON truncated to `REPLAY_RESULT_LIMIT = 4_000` chars).
+- **Reads:** `context.message.email_thread` (returns `nil` if there is no thread/message).
+
+### `LoadFileResolver`
+
+Reads a file and contributes it as one message. General-purpose (system prompt, knowledge, examples).
+
+- **Constructor:** `initialize(path = nil, role: :system, &block)` — supply **exactly one** of `path`
+  or a block returning a path (per delivery). Relative paths resolve against `Rails.root`; absolute
+  paths are used verbatim.
+- **Returns:** `nil` when the file is blank; otherwise one `ModelMessage` (role:, content: <file>).
+- **Raises:** `Protege::ResolverFileNotFoundError` when the file is missing (a missing
+  prompt is a misconfiguration — fail loud). Developer-wired; never agent input.
+
+### `LoadRecordResolver`
+
+Loads ActiveRecord record(s) and contributes them as one message — the DB counterpart to `LoadFile`.
+
+- **Constructor:** `initialize(role: :system, serialize: nil, &loader)` — the **required** `loader`
+  block receives the context and returns record(s) (`ActiveRecord::Base`, a `Relation`, an `Array`, or
+  `nil`). `serialize` is a `Symbol` (a method on each record returning text), a `Proc` (called with each
+  record), or `nil` for pretty-printed JSON (`JSON.pretty_generate(record.as_json)`).
+- **Returns:** `nil` when the loader yields nothing (empty is a normal runtime state); otherwise one
+  `ModelMessage` (role:, content: <records joined by "\n\n">).
+
+### `LoadTextResolver`
+
+The computed-text primitive: a block returns a `String`, contributed as one message. The clean way to
+inject a persona's DB-column system prompt.
+
+- **Constructor:** `initialize(role: :system, &block)` — the **required** block receives the context and
+  returns the text.
+- **Returns:** `nil` when the block returns blank/`nil` (so an unset column adds nothing); otherwise one
+  `ModelMessage` (role:, content: <stripped text>).
+
+---
+
+## Writing a resolver
+
+Subclass `Protege::Resolver`, implement `resolve(context:)`, and build messages with the `message`
+helper — the resolver counterpart of `Tool`'s `success`/`failure`, so you never construct `ModelMessage`
+by hand. Return one message, an array of them, or `nil`:
+
+```ruby
+class CustomerContextResolver < Protege::Resolver
+  def resolve(context:)
+    customer = Customer.find_by(email: context.message&.from_address)
+    return nil unless customer
+
+    message(role: :system, content: "You are speaking with #{customer.name} (plan: #{customer.plan}).")
+  end
+end
+```
+
+`message(role:, content:, tool_call_id: nil, tool_calls: nil)` returns one
+`ModelMessage`; the chain coerces a lone message, an array, or `nil`.
+
+Rules of thumb:
+- Return `nil` (not `[]` — both work, but `nil` is the idiom) when there's nothing to contribute.
+- Pick the `role` deliberately; default to `:system` for injected knowledge.
+- Only emit `:assistant`-with-`tool_calls` + paired `:tool` messages if you're replaying a real tool
+  exchange; keep them adjacent and correctly `tool_call_id`-matched.
+- Read the context; never mutate it (it's frozen).

data/app/resolvers/protege/load_file_resolver.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Protege
+  # General-purpose resolver that reads a file and contributes its contents as one context message.
+  # It is deliberately *not* named for a use case: the developer decides what the file is — a system
+  # prompt, a knowledge document, few-shot examples — by choosing the +role+ of the emitted message.
+  #
+  # The path is given either statically or as a block that receives the resolver context, so it can
+  # be derived from the inbound message or persona (e.g. a per-persona prompt file). Path resolution
+  # mirrors ordinary shell intuition, so the same resolver works in development and in any production
+  # deployment:
+  # - a relative path (+config/personas/agent.md+, +./agent.md+) resolves against the host app root
+  #   (+Rails.root+) — i.e. a file deployed with the app, which is reliably readable everywhere.
+  # - an absolute path (+/data/prompts/agent.md+) is used as-is, so an attached volume or mounted
+  #   secret just needs its fully-qualified path.
+  #
+  # LoadFileResolver is a *developer-wired* resolver, never a model-callable tool — the path is author-trusted
+  # code, so even absolute reads carry the same trust as any code in the persona. A missing file is a
+  # misconfiguration and raises +Protege::ResolverFileNotFoundError+; a blank file contributes
+  # nothing (returns +nil+).
+  #
+  #   resolvers do |chain|
+  #     chain.use Protege::LoadFileResolver, 'config/personas/agent.md'
+  #     chain.use(Protege::LoadFileResolver) { |ctx| "config/personas/#{ctx.persona.name.parameterize}.md" }
+  #   end
+  class LoadFileResolver < Protege::Resolver
+    # @param path [String, nil] file to read; relative paths resolve against +Rails.root+, absolute
+    #   paths are used verbatim. Omit when supplying a block instead.
+    # @param role [Symbol] role for the emitted message (+:system+ for a prompt, +:user+/+:assistant+
+    #   to seed conversation); defaults to +:system+
+    # @yieldparam context [Protege::Orchestrator::Context] the per-delivery context
+    # @yieldreturn [String] the path to read, computed per delivery
+    # @raise [ArgumentError] unless exactly one of +path+ or a block is given
+    def initialize(path = nil, role: :system, &block)
+      super()
+      raise ArgumentError, 'LoadFileResolver requires exactly one of a path or a block' unless path.nil? ^ block.nil?
+
+      @path  = path
+      @role  = role
+      @block = block
+    end
+
+    # Read the file and emit its contents as a single message, or +nil+ when the file is blank.
+    #
+    # @param context [Protege::Orchestrator::Context] the per-delivery context
+    # @return [Protege::ModelMessage, nil] one message, or +nil+ when blank
+    # @raise [Protege::ResolverFileNotFoundError] when the path does not exist
+    def resolve(context:)
+      content = read(path_for(context))
+      return nil if content.blank?
+
+      message(role: @role, content:)
+    end
+
+    private
+
+    # The path for this delivery: the block's return value when given a block, else the static path.
+    #
+    # @param context [Protege::Orchestrator::Context] the per-delivery context
+    # @return [String] the (unexpanded) path to read
+    def path_for(context)
+      @block ? @block.call(context) : @path
+    end
+
+    # Read the resolved path, translating a missing file into a domain error.
+    #
+    # @param path [String] the (unexpanded) path to read
+    # @return [String] the file contents
+    # @raise [Protege::ResolverFileNotFoundError] when the path does not exist
+    def read(path)
+      absolute = resolved_path(path)
+      File.read(absolute)
+    rescue Errno::ENOENT
+      raise Protege::ResolverFileNotFoundError.new(path:, absolute:)
+    end
+
+    # Expand a path: absolute paths pass through, relative paths anchor to +Rails.root+.
+    #
+    # @param path [String] the (unexpanded) path
+    # @return [String] the absolute filesystem path to read
+    def resolved_path(path)
+      str = path.to_s
+      str.start_with?('/') ? str : Rails.root.join(str).to_s
+    end
+  end
+end

data/app/resolvers/protege/load_record_resolver.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Protege
+  # General-purpose resolver that loads ActiveRecord record(s) and contributes them as one context
+  # message — the database counterpart to LoadFileResolver. Like LoadFileResolver, it is deliberately not named for a
+  # use case: the developer decides what the records mean (account state, open invoices, reference
+  # data) and what message +role+ carries them.
+  #
+  # The single primitive is a **loader block** that returns record(s). It receives the resolver
+  # context, so loading can key off the inbound message — e.g. find the account that emailed in. A
+  # static query is just a block that ignores the context. We intentionally do not offer a
+  # +model:+/+where:+ DSL: it would be strictly less capable than the block (no scopes, joins, or
+  # +find+ vs +where+) and would collide column names with resolver options.
+  #
+  # Serialization is per-record and always produces text. By default each record is rendered as
+  # pretty-printed JSON; +serialize:+ overrides that with a Symbol (a method on the record returning
+  # text) or a +Proc+ (called with the record, returning text). The rendered records are joined into
+  # one message. A +nil+ or empty result contributes nothing (returns +nil+), since "no matching
+  # rows" is a normal runtime state — unlike LoadFileResolver's missing-file misconfiguration.
+  #
+  #   resolvers do |chain|
+  #     chain.use(Protege::LoadRecordResolver) { |ctx| Account.find_by(email: ctx.message.from_address) }
+  #     chain.use(Protege::LoadRecordResolver, serialize: :to_llm_markdown) { Setting.active }
+  #   end
+  class LoadRecordResolver < Protege::Resolver
+    # Separator between each record's text rendering when more than one is loaded.
+    RECORD_SEPARATOR = "\n\n"
+
+    # @param role [Symbol] role for the emitted message; defaults to +:system+
+    # @param serialize [Symbol, Proc, nil] per-record serializer returning text — a method name to
+    #   call on each record, or a +Proc+ receiving each record; defaults to pretty-printed JSON
+    # @yieldparam context [Protege::Orchestrator::Context] the per-delivery context
+    # @yieldreturn [ActiveRecord::Base, ActiveRecord::Relation, Array, nil] the record(s) to load
+    # @raise [ArgumentError] when no loader block is given
+    def initialize(role: :system, serialize: nil, &loader)
+      super()
+      raise ArgumentError, 'LoadRecordResolver requires a block returning record(s)' unless loader
+
+      @role      = role
+      @serialize = serialize
+      @loader    = loader
+    end
+
+    # Run the loader and emit its record(s) as one message, or +nil+ when nothing is loaded.
+    #
+    # @param context [Protege::Orchestrator::Context] the per-delivery context
+    # @return [Protege::ModelMessage, nil] one message, or +nil+ when empty
+    def resolve(context:)
+      records = Array(@loader.call(context))
+      return nil if records.empty?
+
+      content = render(records)
+      message(role: @role, content:)
+    end
+
+    private
+
+    # Render the records into the message string: serialize each to text, then join. Every
+    # serializer returns text (that is the contract), so no per-value coercion is needed.
+    #
+    # @param records [Array] the loaded records
+    # @return [String] the message content
+    def render(records)
+      records.map { serialize_record(_1) }.join(RECORD_SEPARATOR)
+    end
+
+    # Serialize one record to text. A serializer always returns a String: a Symbol names a method on
+    # the record, a +Proc+ is called with the record, and the default is pretty-printed JSON.
+    #
+    # @param record [Object] the record to serialize
+    # @return [String] the record's text representation
+    def serialize_record(record)
+      case @serialize
+      when Symbol then record.public_send(@serialize)
+      when Proc   then @serialize.call(record)
+      else             JSON.pretty_generate(record.as_json)
+      end
+    end
+  end
+end

data/app/resolvers/protege/load_text_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Protege
+  # General-purpose resolver that runs a block and contributes its returned String as one context
+  # message — the computed-text sibling of +LoadFileResolver+ (text from a file) and +LoadRecordResolver+ (text from
+  # records). The block receives the resolver context, so the text can be derived from the persona or
+  # the inbound message. The canonical use is a persona's system prompt held in a column:
+  #
+  #   resolvers do |chain|
+  #     chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.persona.instructions }
+  #   end
+  #
+  # +role+ chooses how the text enters the conversation (+:system+ for a prompt, +:user+/+:assistant+
+  # to seed turns) and defaults to +:system+. A +nil+ or blank result contributes nothing (returns
+  # +nil+), so an unset column simply adds no message.
+  class LoadTextResolver < Protege::Resolver
+    # @param role [Symbol] role for the emitted message; defaults to +:system+
+    # @yieldparam context [Protege::Orchestrator::Context] the per-delivery context
+    # @yieldreturn [String, nil] the text to contribute
+    # @raise [ArgumentError] when no block is given
+    def initialize(role: :system, &block)
+      super()
+      raise ArgumentError, 'LoadTextResolver requires a block returning text' unless block
+
+      @role  = role
+      @block = block
+    end
+
+    # Run the block and emit its text as a single message, or +nil+ when the result is blank.
+    #
+    # @param context [Protege::Orchestrator::Context] the per-delivery context
+    # @return [Protege::ModelMessage, nil] one message, or +nil+ when blank
+    def resolve(context:)
+      content = @block.call(context).to_s.strip
+      return nil if content.empty?
+
+      message(role: @role, content:)
+    end
+  end
+end

data/app/resolvers/protege/thread_history_resolver.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Protege
+  # Built-in resolver that replays a thread's prior messages so the agent has conversational
+  # memory across exchanges. For each persisted message in the current message's thread it
+  # contributes an ordered +ModelMessage+ — inbound mapped to +:user+, outbound to
+  # +:assistant+ — with the current inbound message excluded (it arrives as the final +:user+
+  # message through the normal harness flow).
+  #
+  # Each turn is the message's +Protege::Message#to_llm_text+: a standard header block (From / To / Cc /
+  # Date / Subject, always rendered) followed by the body — plain text, or the tag-stripped HTML
+  # fallback — and, when the message carries attachments, the note the app builds listing each (filename,
+  # content type, size, and the attachment id the +read_attachment+ / +send_email+ tools accept). So the
+  # agent knows who wrote each turn and when, not just what was said, and an attachment-only message
+  # still contributes. A message with neither a body nor attachments is skipped.
+  #
+  # It also replays the agent's **tool use** between turns: the +ToolUse+ rows recorded during each
+  # prior run are woven back in right after the inbound message that triggered them, as the same
+  # structured messages a live run builds — one +:assistant+ message carrying the round's +tool_calls+,
+  # followed by one +:tool+ message per result. Without this the agent would forget, on the next turn,
+  # what it searched, fetched, or read earlier. Each replayed result is truncated to
+  # +REPLAY_RESULT_LIMIT+ so past tool output can't dominate the context. Pass +include_tool_calls:
+  # false+ to replay only the plain message turns.
+  #
+  # Returns +nil+ when the thread has no prior content.
+  #
+  # By default it replays only the most recent +DEFAULT_LIMIT+ prior messages (still in chronological
+  # order) — a bounded verbatim window that pairs well with a running summary recapping everything
+  # older, and a guard against unbounded context on long threads. Pass +limit:+ to change the window, or
+  # +limit: nil+ to replay the entire thread.
+  #
+  #   resolvers { |chain| chain.use Protege::ThreadHistoryResolver }            # most recent DEFAULT_LIMIT
+  #   resolvers { |chain| chain.use Protege::ThreadHistoryResolver, limit: 10 } # most recent 10
+  #   resolvers { |chain| chain.use Protege::ThreadHistoryResolver, limit: nil } # the entire thread
+  class ThreadHistoryResolver < Protege::Resolver
+    # Most-recent prior messages replayed when no +limit:+ is given.
+    DEFAULT_LIMIT = 50
+
+    # Maximum characters of each prior tool result replayed into history.
+    REPLAY_RESULT_LIMIT = 4_000
+
+    # @param limit [Integer, nil] keep only the most recent N prior messages; +nil+ keeps all
+    # @param include_tool_calls [Boolean] weave prior tool calls/results back into the history
+    def initialize(limit: DEFAULT_LIMIT, include_tool_calls: true)
+      super()
+      @limit              = limit
+      @include_tool_calls = include_tool_calls
+    end
+
+    # Build the thread's prior messages — and the tool use between them — as ordered provider messages.
+    #
+    # @param context [Protege::Orchestrator::Context] exposes the current +message+
+    # @return [Array<Protege::ModelMessage>, nil] ordered history, or +nil+ when empty
+    def resolve(context:)
+      thread = context.message.email_thread
+      return nil unless thread
+
+      prior = thread.messages
+                    .with_attached_attachments
+                    .where.not(message_id: context.message.message_id)
+                    .order(:sent_at)
+      prior = prior.includes(:tool_uses) if @include_tool_calls # eager-load each turn's tool history
+      prior = prior.last(@limit) if @limit # most recent N, still ascending by sent_at
+
+      prior.flat_map { |message| [history_message(message), *tool_turns(message)] }
+           .compact.presence
+    end
+
+    private
+
+    # Rebuild a message's tool activity as structured provider messages: per tool-calling round, one
+    # +:assistant+ message carrying the round's calls, then one +:tool+ message per (truncated) result.
+    # Reads the eager-loaded +tool_uses+ association and orders it in memory, so no extra query runs.
+    #
+    # @param message [Protege::Message] the message whose recorded tool use is replayed
+    # @return [Array<Protege::ModelMessage>] the reconstructed turns (empty when none)
+    def tool_turns(message)
+      return [] unless @include_tool_calls
+
+      message.tool_uses
+             .sort_by { |use| [use.run_id.to_s, use.turn_index, use.position] }
+             .group_by { |use| [use.run_id, use.turn_index] }
+             .flat_map { |_round, rows| round_messages(rows) }
+    end
+
+    # Rebuild one tool-calling round: the +:assistant+ message carrying its calls, then one +:tool+
+    # message per (truncated) result.
+    #
+    # @param rows [Array<Protege::ToolUse>] the round's tool uses, in call order
+    # @return [Array<Protege::ModelMessage>] the assistant turn followed by its results
+    def round_messages(rows)
+      assistant = message(role: :assistant, content: '', tool_calls: rows.map(&:to_provider_tool_call))
+      
+      results   = rows.map do |row|
+        message(role: :tool, tool_call_id: row.tool_call_id, content: row.replay_result(limit: REPLAY_RESULT_LIMIT))
+      end
+
+      [assistant, *results]
+    end
+
+    # Map one stored message to a provider message, or +nil+ when it carries no usable content.
+    #
+    # The turn's content is the message's {Protege::Message#to_llm_text} — the standard header
+    # (sender/recipients/subject/timestamp) plus body and any attachment note — so a replayed turn is
+    # self-describing. Skips a message with neither a body nor attachments (nothing worth replaying);
+    # an attachment-only turn still contributes.
+    #
+    # @param record [Protege::Message] the stored message
+    # @return [Protege::ModelMessage, nil]
+    def history_message(record)
+      return nil if record.readable_body.blank? && !record.attachments.attached?
+
+      message(role: record.inbound? ? :user : :assistant, content: record.to_llm_text)
+    end
+  end
+end