protege 0.1.0.alpha.1

data/lib/protege/orchestrator/harness.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Protege
+  module Orchestrator
+    # Multi-turn inference runner — the heart of the LOGI Orchestrator. Generates against the
+    # configured provider and dispatches tool calls until the model returns a tool-free response or
+    # +max_tool_turns+ is reached.
+    #
+    # This is the **abstract base** that owns the shared algorithm (event-wrapped tool loop, provider
+    # generation, tool dispatch, attachment review). What *drives* a run is left to subclasses, which
+    # each define one clean path: +ReplyHarness+ for a reactive run (an inbound email) and
+    # +ResponsibilityHarness+ for a proactive one (a scheduled Loop responsibility). The branch between
+    # them lives at the job boundary — the caller picks the subclass — so there are no run-kind
+    # conditionals in this loop. Subclasses fill the hooks: +#resolvers+, +#user_content+, +#context+,
+    # and (reply only) +#message+ / +#streaming?+.
+    #
+    # +Protege::Current.correlation_id+ must be set before calling so that emitted events carry the id
+    # automatically. Collaborates with +Inference+ (request building and generation), +Tool+ (dispatch
+    # and registry), the persona's +ResolverChain+ (context assembly), and the +Protege::*Event+ classes
+    # (observability).
+    #
+    # @example
+    #   ReplyHarness.run(persona:, message:)
+    #   ResponsibilityHarness.run(persona:, responsibility:)
+    #
+    # == Lifecycle
+    #
+    # 1. Emit +inference_started+ event.
+    # 2. Build the initial +Provider::Request+ from the opening user turn, registered tools, and
+    #    resolver-contributed context messages.
+    # 3. Enter the tool loop — generate, dispatch any tool calls, extend the request with results,
+    #    repeat until the model returns no tool calls or +max_tool_turns+ is exhausted.
+    # 4. Emit +inference_completed+ event and return the final response.
+    class Harness
+      class << self
+        # Instantiate the concrete harness and run it in one call. Keyword arguments are forwarded to
+        # the subclass initializer (e.g. +message:+ for +ReplyHarness+, +responsibility:+ for
+        # +ResponsibilityHarness+).
+        #
+        # @return [Object] the final +Provider::Response+
+        def run(**)
+          new(**).run
+        end
+      end
+
+      # @param persona [Protege::Persona] the persona handling the run
+      # @return [void]
+      def initialize(persona:)
+        @persona = persona
+      end
+
+      # Entry point. Emit lifecycle events around the tool loop.
+      #
+      # Always emits a terminal event — +inference_completed+ on success or +inference_failed+ when the
+      # loop raises — so subscribers (and stateful hooks keyed by correlation id) are never left
+      # waiting on a completion that never comes. The error is re-raised so the job's retry/discard
+      # policy still applies.
+      #
+      # @return [Object] the final +Provider::Response+
+      # @raise [StandardError] re-raised after +inference_failed+ is emitted
+      def run
+        InferenceStartedEvent.emit(persona:, message:)
+
+        result = run_tool_loop
+
+        InferenceCompletedEvent.emit(persona:, message:, result:)
+
+        result
+      rescue StandardError => e
+        InferenceFailedEvent.emit(persona:, message:, error: e)
+        raise
+      end
+
+      private
+
+      # @return [Protege::Persona] the persona handling the run
+      attr_reader :persona
+
+      # ── Kind-specific hooks (subclasses override) ─────────────────────────────
+
+      # The resolver chain that assembles this run's context messages.
+      # @return [Orchestrator::ResolverChain]
+      def resolvers
+        raise NotImplementedError, "#{self.class} must implement #resolvers"
+      end
+
+      # The per-run context shared by every tool and resolver invocation.
+      # @return [Orchestrator::Context]
+      def context
+        raise NotImplementedError, "#{self.class} must implement #context"
+      end
+
+      # An opening user turn for the harness to append, when a run carries a *live* trigger that isn't
+      # a stored record — the inbound email body for a reply. Defaults to none: assembling context
+      # (system prompts, history, and a scheduled run's instructions) is the resolver chain's job, not
+      # the harness's, so a subclass overrides this only for a live trigger it must inject itself.
+      #
+      # @return [String, Array<Object>, nil] the user-turn content, or nil to add nothing
+      def user_content
+        nil
+      end
+
+      # The inbound message, when this run answers one. Reactive runs override it; for scheduled runs
+      # it stays nil (events carry a nil message, and there is nothing to stream).
+      # @return [Object, nil]
+      def message
+        nil
+      end
+
+      # Whether to stream tokens to a connected console. Only the reactive console path streams.
+      # @return [Boolean]
+      def streaming?
+        false
+      end
+
+      # ── Shared loop ───────────────────────────────────────────────────────────
+
+      # Run the core generate → dispatch → extend loop.
+      #
+      # Runs up to +max_loop_iterations+ turns. Returns early when the model signals completion (no
+      # tool calls). On the final allowed turn, emits +max_turns_reached+ and breaks, returning
+      # whatever response the model last produced.
+      #
+      # @return [Object] the final +Provider::Response+
+      def run_tool_loop
+        final    = nil
+        extended = build_initial_request
+
+        max_loop_iterations.times do |turn|
+          final = capture(turn:, request: extended) { run_generation(extended) }
+
+          return final if final.tool_calls.blank?
+
+          if turn >= (max_loop_iterations - 1)
+            InferenceMaxTurnsReachedEvent.emit(persona:, turn:, tool_calls: final.tool_calls)
+            break
+          end
+
+          ToolCallsReceivedEvent.emit(persona:, tool_calls: final.tool_calls)
+
+          tool_results = final.tool_calls.map { invoke_tool(_1) }
+          record_tool_round(turn:, response: final, tool_results:)
+          extended     = Inference.extend_request(
+            previous:     extended,
+            response:     final,
+            tool_results:,
+            review_parts: review_parts_for(tool_results)
+          )
+        end
+
+        final
+      end
+
+      # Wrap one turn's generation for tracing. When tracing is off (the default) this is a bare
+      # pass-through — it yields and returns the response with zero overhead, publishing nothing. When
+      # tracing is on, it emits +InferenceGeneratedEvent+ (the seam the tracing subscriber snapshots).
+      # Gating the *emission* here — rather than always emitting and letting the subscriber decide —
+      # means the (potentially large) request payload is never assembled into an event unless a host
+      # opted in.
+      #
+      # @param turn [Integer] this generation's turn index within the run
+      # @param request [Object] the provider request being generated against
+      # @yieldreturn [Object] the provider response
+      # @return [Object] the provider response
+      def capture(turn:, request:)
+        return yield unless Protege.configuration.tracing[:enabled]
+
+        response = yield
+        emit_generated(turn:, request:, response:)
+        response
+      end
+
+      # Emit the per-turn trace event: the wire request (+Request#to_wire+ — the very serialization the
+      # API call uses, so the snapshot is exact), the response, and the inference settings that shaped it
+      # (+model+ + +settings+, pulled from the provider the harness resolves — not global config — so a
+      # future persona-level override is captured). Best-effort: any failure is logged and swallowed, so
+      # building or publishing the event can never abort a run whose side effects may already have run.
+      #
+      # @param turn [Integer] this generation's turn index
+      # @param request [Object] the provider request that was sent
+      # @param response [Object] the provider response it produced
+      # @return [void]
+      def emit_generated(turn:, request:, response:)
+        provider = Inference.provider
+
+        InferenceGeneratedEvent.emit(
+          turn:,
+          request:  request.to_wire,
+          response: response.to_wire,
+          model:    provider.model,
+          settings: provider.settings
+        )
+      rescue StandardError => e
+        Protege.configuration.logger.error(
+          "[Protege] failed to emit trace event (turn #{turn}): #{e.class}: #{e.message}"
+        )
+      end
+
+      # Run a single generation, streaming chunks to the browser when this run streams (console only).
+      #
+      # @param request [Object] the provider request to generate against
+      # @return [Object] the provider response
+      def run_generation(request)
+        if streaming?
+          Inference.generate_stream(request) do |chunk|
+            InferenceChunkEvent.emit(persona:, thread: message.email_thread, chunk:)
+          end
+        else
+          Inference.generate(request)
+        end
+      end
+
+      # Compute the loop bound. +max_tool_turns+ is how many tool-calling rounds to allow; the loop
+      # needs one extra iteration for the final tool-free generation.
+      #
+      # @return [Integer] the maximum number of loop iterations
+      def max_loop_iterations
+        Protege.configuration.max_tool_turns + 1
+      end
+
+      # Record one completed tool-calling round to the run's durable tool history.
+      #
+      # Recording is **best-effort**: it is an audit/memory side effect, not the run's mission, so any
+      # failure here is logged and swallowed. It must never abort the tool loop — the tools have already
+      # executed (a reply may have already been sent), and letting a persistence hiccup raise would kill
+      # the run and, under retry, re-execute those side effects. The actual write is delegated to
+      # +#persist_tool_round+, which subclasses override.
+      #
+      # @param turn [Integer] the tool-calling round index within this run
+      # @param response [Object] the assistant response carrying this round's tool calls
+      # @param tool_results [Array<Protege::ToolResult>] the paired results
+      # @return [void]
+      def record_tool_round(turn:, response:, tool_results:)
+        persist_tool_round(turn:, response:, tool_results:)
+      rescue StandardError => e
+        Protege.configuration.logger.error(
+          "[Protege] failed to record tool use (turn #{turn}): #{e.class}: #{e.message}"
+        )
+      end
+
+      # Persist this round's tool uses. Subclass hook — the base records nothing (a plain run keeps no
+      # tool history). +ReplyHarness+ and +ResponsibilityHarness+ override it.
+      #
+      # @param turn [Integer] the tool-calling round index within this run
+      # @param response [Object] the assistant response carrying this round's tool calls
+      # @param tool_results [Array<Protege::ToolResult>] the paired results
+      # @return [void]
+      def persist_tool_round(turn:, response:, tool_results:); end
+
+      # Dispatch a single tool call and emit the matching success/failure event.
+      #
+      # @param tool_call [Object] the tool call to dispatch
+      # @return [Protege::ToolResult] the call paired with its outcome
+      def invoke_tool(tool_call)
+        ToolCallStartedEvent.emit(persona:, tool_call:)
+
+        tool_result = ToolMixin.invoke(tool_call, context:)
+
+        if tool_result.result.success?
+          ToolCallCompletedEvent.emit(persona:, tool_call:, result: tool_result.result)
+        else
+          ToolCallFailedEvent.emit(persona:, tool_call:, error: tool_result.result.error)
+        end
+
+        tool_result
+      end
+
+      # Collect the vision parts for any tool result that asked to show the model a file (the
+      # +read_attachment+ tool on an image/PDF). The result carries only the blob id — never the bytes —
+      # so the part is rebuilt here by re-resolving the blob, keeping binary out of the serialized tool
+      # text. These are appended as a trailing user turn by +extend_request+.
+      #
+      # @param tool_results [Array<Protege::ToolResult>] the turn's tool results
+      # @return [Array<Object>] the vision parts to show the model
+      def review_parts_for(tool_results)
+        tool_results.filter_map do |tool_result|
+          data = tool_result.result.data
+          next unless data[:review]
+
+          file = Protege::StoredFile.find(data[:blob_id])
+          file&.to_part
+        end
+      end
+
+      # Assemble the first +Provider::Request+ from the opening user turn, the persona's effective
+      # (scoped) tool set, inference config, and any context messages contributed by resolvers.
+      #
+      # The catalogue is +persona.available_tools+ rather than the whole registry, so a persona's
+      # code-declared grant and the operator's +disabled_tool_ids+ override bound what the model is
+      # offered — on both the reply and the scheduled path, since both inherit this base method. Later
+      # turns re-use +previous.tools+ (see +Inference.extend_request+), so the scope holds for the run.
+      #
+      # @return [Object] the initial provider request
+      def build_initial_request
+        Inference.build_request(
+          user_content:,
+          tools:            persona.available_tools,
+          context_messages: resolvers.run(context)
+        )
+      end
+    end
+  end
+end

data/lib/protege/orchestrator/reply_context.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Protege
+  module Orchestrator
+    # Context for a reactive run — one driven by an inbound email. Adds the +message+ to the shared
+    # +Context+ surface so tools and resolvers can reach the email being answered (its thread, sender,
+    # body, attachments). The +#responsibility+ accessor inherited from +Context+ stays nil.
+    class ReplyContext < Context
+      # @return [Object] the inbound message being processed
+      attr_reader :message
+
+      # @param persona [Protege::Persona] the persona handling the run
+      # @param message [Object] the inbound message being processed
+      # @return [void]
+      def initialize(persona:, message:)
+        @message = message
+        super(persona:)
+      end
+    end
+  end
+end

data/lib/protege/orchestrator/reply_harness.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Protege
+  module Orchestrator
+    # The reactive run — answering one inbound email. Runs the receiving persona's +message_resolvers+
+    # chain, opens the turn with the message body (plus any viewable attachments as vision parts), and
+    # streams tokens when the message came from the console. The +Harness+ base owns the tool loop;
+    # this subclass only supplies the reply-specific hooks.
+    class ReplyHarness < Harness
+      # @param persona [Protege::Persona] the persona that received the message
+      # @param message [Object] the inbound message to respond to
+      # @return [void]
+      def initialize(persona:, message:)
+        super(persona:)
+        @message = message
+      end
+
+      private
+
+      # @return [Object] the inbound message being answered (overrides the base nil)
+      attr_reader :message
+
+      # @return [Orchestrator::ResolverChain] the persona's reply chain
+      def resolvers
+        persona.message_resolvers
+      end
+
+      # @return [String, Array<Object>] the message body, or body-plus-attachment parts
+      def user_content
+        message.content_parts
+      end
+
+      # @return [Orchestrator::ReplyContext] the shared per-run context carrying the message
+      def context
+        @context ||= ReplyContext.new(persona:, message:)
+      end
+
+      # Persist this tool-calling round as +ToolUse+ rows owned by the inbound message, so a later turn's
+      # +ThreadHistoryResolver+ can replay the agent's prior tool calls and results instead of losing
+      # them. Grouped by +correlation_id+ (this run) and +turn+; each call is paired with its result. A
+      # reply always carries a correlation id (a +Harness+ precondition), so it is not guarded here.
+      #
+      # @param turn [Integer] the tool-calling round index within this run
+      # @param response [Object] the assistant response carrying this round's tool calls
+      # @param tool_results [Array<Protege::ToolResult>] the paired results
+      # @return [void]
+      def persist_tool_round(turn:, response:, tool_results:)
+        Protege::ToolUse.record_round(
+          source:       message,
+          persona:,
+          run_id:       Protege::Current.correlation_id,
+          turn_index:   turn,
+          tool_calls:   response.tool_calls,
+          tool_results:
+        )
+      end
+
+      # Stream only for console messages — SMTP mail has no connected client. Matched against the
+      # configured console address case-insensitively, since email addresses are not case-sensitive in
+      # practice and the stored +from_address+ preserves whatever case arrived.
+      #
+      # @return [Boolean] true when the message came from the console address
+      def streaming?
+        message&.from_address.to_s.casecmp?(Protege.configuration.console_address.to_s)
+      end
+    end
+  end
+end

data/lib/protege/orchestrator/resolver_chain.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Protege
+  module Orchestrator
+    # Ordered list of resolver classes that build inference context for one persona. Configured at
+    # persona declaration time (via +Persona::Config#resolvers+) and run once per
+    # +Harness#build_initial_request+ call.
+    #
+    # Each resolver runs independently and returns +Array<ModelMessage>+ or +nil+. The chain
+    # concatenates all contributions in order — there is no wrapping or short-circuit (unlike
+    # middleware).
+    #
+    # Entries are stored as +[klass, args, kwargs, block]+ tuples rather than instances so that
+    # +remove(Klass)+ can locate and remove a specific resolver class without needing to match on
+    # constructor arguments. Each +run+ call creates fresh instances. A block passed to +use+/+prepend+
+    # is captured and forwarded to +klass.new+, so resolvers can take a loader block (e.g.
+    # +chain.use(Protege::LoadRecordResolver) { |ctx| Invoice.where(...) }+).
+    #
+    # @example
+    #   chain = ResolverChain.new
+    #   chain.use Protege::LoadFileResolver, 'app/personas/agent/PERSONA.md'
+    #   chain.use(Protege::LoadRecordResolver) { |ctx| Account.find_by(email: ctx.message.from_address) }
+    #   chain.use Protege::ThreadHistoryResolver
+    #
+    #   messages = chain.run(resolve_ctx)   # => Array<ModelMessage>
+    class ResolverChain
+      # @return [Array<Array>] read-only view of the registered +[klass, args, kwargs, block]+ entries
+      attr_reader :entries
+
+      # Initialize an empty chain.
+      #
+      # @return [void]
+      def initialize
+        @entries = []
+      end
+
+      # Append a resolver class to the end of the chain. Constructor args are stored alongside and
+      # forwarded to +klass.new+ at run time.
+      #
+      # @param klass [Class] the resolver class to register
+      # @param args [Array] positional constructor arguments forwarded at run time
+      # @param kwargs [Hash] keyword constructor arguments forwarded at run time
+      # @yield optional block forwarded to +klass.new+ (e.g. a loader for +LoadRecordResolver+)
+      # @return [self] the chain, for fluent chaining
+      def use(klass, *args, **kwargs, &block)
+        @entries << [klass, args, kwargs, block]
+        self
+      end
+
+      # Insert a resolver class at the front of the chain.
+      #
+      # @param klass [Class] the resolver class to register
+      # @param args [Array] positional constructor arguments forwarded at run time
+      # @param kwargs [Hash] keyword constructor arguments forwarded at run time
+      # @yield optional block forwarded to +klass.new+ (e.g. a loader for +LoadRecordResolver+)
+      # @return [self] the chain, for fluent chaining
+      def prepend(klass, *args, **kwargs, &block)
+        @entries.unshift([klass, args, kwargs, block])
+        self
+      end
+
+      # Remove every entry whose registered class equals +klass+.
+      #
+      # @param klass [Class] the resolver class to remove
+      # @return [self] the chain, for fluent chaining
+      def remove(klass)
+        @entries.reject! { |entry| entry.first == klass }
+        self
+      end
+
+      # Empty the chain.
+      #
+      # @return [self] the now-empty chain
+      def clear
+        @entries.clear
+        self
+      end
+
+      # Run every resolver in order, passing +context+ to each.
+      #
+      # +nil+ returns are silently skipped (coerced through +Array(...)+). Fresh resolver instances
+      # are constructed per call from the stored +[klass, args, kwargs, block]+ tuples.
+      #
+      # @param context [Protege::Orchestrator::Context] the per-delivery resolver context
+      # @return [Array<Object>] a flat array of +ModelMessage+ objects, empty when none contribute
+      def run(context)
+        @entries.flat_map do |klass, args, kwargs, block|
+          Array(klass.new(*args, **kwargs, &block).resolve(context:))
+        end
+      end
+    end
+  end
+end

data/lib/protege/orchestrator/responsibility_context.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Protege
+  module Orchestrator
+    # Context for a proactive run — one driven by a scheduled +Responsibility+ (the Loop layer). Adds
+    # the +responsibility+ to the shared +Context+ surface so tools and resolvers can reach the duty
+    # being carried out (its prompt, schedule, owning persona). The +#message+ accessor inherited from
+    # +Context+ stays nil, so reply-only tools (e.g. +send_email+ in reply mode) degrade gracefully.
+    class ResponsibilityContext < Context
+      # @return [Protege::Responsibility] the responsibility being fulfilled
+      attr_reader :responsibility
+
+      # @param persona [Protege::Persona] the persona carrying out the responsibility
+      # @param responsibility [Protege::Responsibility] the scheduled duty being run
+      # @return [void]
+      def initialize(persona:, responsibility:)
+        @responsibility = responsibility
+        super(persona:)
+      end
+    end
+  end
+end

data/lib/protege/orchestrator/responsibility_harness.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Protege
+  module Orchestrator
+    # The proactive run — carrying out one scheduled +Responsibility+ (the Loop layer). Runs the
+    # persona's +responsibility_resolvers+ chain, which assembles the *entire* message list — including
+    # the responsibility's instructions (e.g. via +LoadTextResolver(role: :user) { ctx.responsibility.instructions }+).
+    # The harness injects no user turn of its own (it inherits the base +user_content+ default of nil):
+    # context assembly is the resolver chain's job. There is no inbound message and no streaming. The
+    # +Harness+ base owns the tool loop; this subclass only supplies the responsibility-specific hooks.
+    class ResponsibilityHarness < Harness
+      # @param persona [Protege::Persona] the persona carrying out the responsibility
+      # @param responsibility [Protege::Responsibility] the scheduled duty to run
+      # @param responsibility_run [Protege::ResponsibilityRun] the run record this execution belongs to
+      # @return [void]
+      def initialize(persona:, responsibility:, responsibility_run:)
+        super(persona:)
+        @responsibility     = responsibility
+        @responsibility_run = responsibility_run
+      end
+
+      private
+
+      # @return [Protege::Responsibility] the responsibility being fulfilled
+      attr_reader :responsibility
+
+      # @return [Protege::ResponsibilityRun] the run record this execution belongs to
+      attr_reader :responsibility_run
+
+      # @return [Orchestrator::ResolverChain] the persona's scheduled-run chain
+      def resolvers
+        persona.responsibility_resolvers
+      end
+
+      # @return [Orchestrator::ResponsibilityContext] the shared per-run context carrying the responsibility
+      def context
+        @context ||= ResponsibilityContext.new(persona:, responsibility:)
+      end
+
+      # Persist this tool-calling round as +ToolUse+ rows owned by the +ResponsibilityRun+ — an audit
+      # trail of what the scheduled run did, beside the run's own status. Not replayed (a scheduled run
+      # has no thread history); grouped by +correlation_id+ (this run) and +turn+.
+      #
+      # @param turn [Integer] the tool-calling round index within this run
+      # @param response [Object] the assistant response carrying this round's tool calls
+      # @param tool_results [Array<Protege::ToolResult>] the paired results
+      # @return [void]
+      def persist_tool_round(turn:, response:, tool_results:)
+        Protege::ToolUse.record_round(
+          source:       responsibility_run,
+          persona:,
+          run_id:       Protege::Current.correlation_id,
+          turn_index:   turn,
+          tool_calls:   response.tool_calls,
+          tool_results:
+        )
+      end
+    end
+  end
+end

data/lib/protege/orchestrator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Protege
+  # LOGI "O" — the orchestrator layer. Owns the inference-running constructs that sit between the
+  # Gateway (which produces inbound messages and sends replies) and the Inference layer (which talks
+  # to providers).
+  #
+  # The +Harness+ is this layer's primary construct: given one inbound message, it builds a provider
+  # request, runs the multi-turn tool loop, and produces a final response. Supporting constructs in
+  # this namespace include the +Context+ value objects passed to extensions, the +Tool+ and
+  # +Resolver+ contracts, and the +ResolverChain+ that assembles inference context per persona.
+  #
+  # Module methods here are the cross-namespace entry points. Callers (jobs, the +Extension+ tool mixin)
+  # use these rather than reaching into +Harness+ subclasses or +ToolResult+/+Error+ directly.
+  module Orchestrator
+    extend self
+
+    # Run a reactive reply generation for an inbound message.
+    #
+    # @param persona [Protege::Persona] the receiving persona
+    # @param message [Protege::Message] the inbound message to answer
+    # @return [Object] the harness result
+    def reply(persona:, message:)
+      ReplyHarness.run(persona:, message:)
+    end
+
+    # Run a proactive generation for a scheduled responsibility.
+    #
+    # @param persona [Protege::Persona] the persona carrying out the duty
+    # @param responsibility [Protege::Responsibility] the scheduled duty
+    # @param responsibility_run [Protege::ResponsibilityRun] the run record being executed
+    # @return [Object] the harness result
+    def run_responsibility(persona:, responsibility:, responsibility_run:)
+      ResponsibilityHarness.run(persona:, responsibility:, responsibility_run:)
+    end
+  end
+end