phronomy 0.15.0 → 0.16.0

data/benchmark/bench_agent_invoke.rb

@@ -40,6 +40,7 @@ class BenchStubChat
   def with_cache_instructions(_) = self
   def with_output_schema(_) = self
   def on_tool_call(&) = self
+  def before_tool_call(&) = self
   def last_message = @response
 
   def ask(_)
@@ -71,12 +72,14 @@ BENCH_RESP = BenchAgentMessage.assistant("benchmark complete")
 BENCH_RESP_CHAT = BenchStubChat.new(BENCH_RESP)
 
 bench_minimal_class = Class.new(Phronomy::Agent::Base) do
+  agent_definition id: "bench-minimal", version: 1
   model "stub-model"
 
   define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end
 
 bench_tool_class = Class.new(Phronomy::Agent::Base) do
+  agent_definition id: "bench-tool", version: 1
   model "stub-model"
   tools BenchNullTool
 

data/benchmark/bench_regression.rb

@@ -88,6 +88,7 @@ end
 # Target 4: Orchestrator#dispatch_parallel overhead (10 stub agents, no LLM)
 # ---------------------------------------------------------------------------
 stub_agent_class = Class.new(Phronomy::Agent::Base) do
+  agent_definition id: "bench-stub", version: 1
   define_method(:invoke) do |_input, messages: [], thread_id: nil, config: {}|
     {output: "stub", messages: []}
   end
@@ -129,22 +130,6 @@ t6 = Benchmark.measure("CancellationToken#raise_if_cancelled! (no-op)") do
   RAISE_ITERATIONS.times { RAISE_TOKEN.raise_if_cancelled! }
 end
 
-# ---------------------------------------------------------------------------
-# Target 7: Agent::Base#trim_messages on a 2000-message history
-# ---------------------------------------------------------------------------
-BenchMsg = Struct.new(:content) unless defined?(BenchMsg)
-
-TRIM_MESSAGES = Array.new(2_000) { |i| BenchMsg.new("msg #{i}") }
-TRIM_ITERATIONS = 500
-
-bench_trim_agent = Class.new(Phronomy::Agent::Base).new
-
-t7 = Benchmark.measure("Agent::Base#trim_messages (2000-msg history)") do
-  TRIM_ITERATIONS.times do
-    bench_trim_agent.send(:trim_messages, TRIM_MESSAGES, keep: 1_800)
-  end
-end
-
 # ---------------------------------------------------------------------------
 # Print results and store in REGRESSION_RESULTS
 # ---------------------------------------------------------------------------
@@ -158,8 +143,7 @@ metrics = {
   "tool_params_schema_definition" => [t3, REGRESSION_ITERATIONS],
   "dispatch_parallel_10" => [t4, PARALLEL_ITERATIONS],
   "cancellation_token_cancelled" => [t5, 8 * CANCEL_ITERATIONS],
-  "cancellation_token_raise_if_cancelled_noop" => [t6, RAISE_ITERATIONS],
-  "trim_messages_2000" => [t7, TRIM_ITERATIONS]
+  "cancellation_token_raise_if_cancelled_noop" => [t6, RAISE_ITERATIONS]
 }
 
 REGRESSION_RESULTS = {} # rubocop:disable Style/MutableConstant

data/benchmark/bench_tool_schema.rb

@@ -54,6 +54,7 @@ class BenchKnowledgeSource < Phronomy::Agent::Context::Knowledge::Base
 end
 
 class BenchAgentWithKnowledge < Phronomy::Agent::Base
+  agent_definition id: "bench-knowledge", version: 1
   model "gpt-4o-mini"
   static_knowledge BenchKnowledgeSource.new
 end

data/docs/decisions/011-build-context-as-single-llm-input-authority.md

@@ -2,7 +2,46 @@
 
 ## Status
 
-Proposed — 2026-05-31
+Partially Superseded by ADR-012 — 2026-08-08
+
+Originally proposed — 2026-05-31.
+
+## Supersession Note
+
+ADR-012, **Canonical Complete Execution Log and Context Policy**, supersedes the architectural parts of this ADR that treat the legacy `build_context` / `LlmContextWindow::Assembler` path as the long-term single authority for LLM input.
+
+In particular, the following parts of this ADR are no longer normative for the stateful Agent architecture:
+
+* **D1 — `build_context` is the single authority for all LLM input**
+* **D2 — Assembler handles all four regions including Capability**
+* **D3 — `build_context` includes all tools**
+* **D5 — Previous context stored as an instance variable**
+
+The replacement authority model is:
+
+```text
+Canonical Journal
+      ↓
+Context Policy
+      ↓
+LLM Call Manifest
+      ↓
+Runtime Projection
+      ↓
+RubyLLM / Provider
+```
+
+Under ADR-012:
+
+* the **Journal** is authoritative for logical execution facts observed by Phronomy;
+* the **Manifest** is authoritative for the logical input fixed for one specific LLM Call;
+* Context Policy determines which canonical history is selected for that Manifest;
+* selection, pruning, and compaction do not delete or rewrite the canonical Journal;
+* Tool protocol dependencies are preserved independently from semantic Context-selection policy.
+
+The problem statements and historical analysis in this ADR remain useful as design history. Decisions or implementation notes that do not conflict with ADR-012 may still describe valid constraints, but ADR-012 is authoritative whenever the two documents differ.
+
+See: `012-canonical-execution-log-and-context-policy.md`
 
 ## Context
 

data/docs/decisions/012-canonical-execution-log-and-context-policy.md

@@ -0,0 +1,69 @@
+# 012 — Canonical Complete Execution Log and Context Policy
+
+## Status
+
+Accepted for the stateful Agent refactor. This decision supersedes the parts of ADR-011 that made the legacy `build_context`/Assembler path the long-term LLM-input authority.
+
+## Decision
+
+Phronomy records the logical execution facts it observes as an append-only Canonical Complete Execution Log. Context selection, pruning and compaction do not rewrite or delete those raw facts. They decide only which representation is materialized into one LLM Call Manifest.
+
+Journal and Manifest are separate authorities:
+
+- **Journal** is the authoritative record of logical execution facts that Phronomy observed.
+- **Manifest** is the authoritative record of the logical input fixed for one particular LLM Call.
+- Runtime Projection is derived from the Manifest and must not add semantic content that the Manifest did not select.
+
+The persistent identity axes have narrow responsibilities:
+
+- `agent_id` identifies the owning Agent.
+- `execution_id` identifies one AgentExecution. It is provenance, not a Context-selection atom.
+- `llm_call_id` identifies one runtime Provider LLM Call. It is allocated before transport starts and correlates that call's outcome. It is provenance, not a semantic-compaction boundary.
+- `tool_call_id` links an assistant message's Tool Call with the corresponding Tool execution/message.
+- Journal `sequence` is canonical chronology.
+
+No `message_group_id`, import-only source provenance ID, or synthetic imported `execution_id` / `llm_call_id` is introduced.
+
+### Message preservation
+
+A logical message that Phronomy receives is not flattened merely to make later Context assembly convenient.
+
+- A Provider assistant response is captured as one complete assistant message containing its observable `content` and all Tool Calls.
+- An imported assistant message is journaled as one assistant message with the structure supplied by the Import contract.
+- A Tool value returned by Phronomy Tool execution is an execution fact (`tool_result`).
+- The Tool-role message actually appended to the LLM conversation is a separate logical fact (`tool_message`).
+- Imported Tool-role messages are journaled directly as `tool_message` records; Phronomy does not invent a separate raw Tool execution result for an execution it did not observe.
+
+The Journal therefore does not need to infer or reconstruct a source message boundary that Phronomy already observed. Context Policy can inspect Tool Call IDs contained in an assistant message and form protocol-safe selection units with the corresponding Tool messages.
+
+### Import boundary
+
+The application supplying imported history is responsible for satisfying Phronomy's Import contract. Phronomy interprets valid input according to that contract and rejects only data that is invalid under the contract, such as unsupported roles, missing Tool Call IDs, orphan/duplicate Tool results, unresolved Tool calls, or malformed message structure.
+
+External resource acquisition is not a `ContextImporter` responsibility. Files, URLs and similar resources are obtained and interpreted by the Application or Tool that owns that capability; Phronomy journals the logical content/results it actually receives. `ContextImporter` therefore does not introduce RubyLLM-specific attachment handling or an attachment-specific reject path.
+
+Phronomy must not reject an otherwise valid input merely because an internal flattened representation would lose information. In particular, two separately supplied assistant messages remain two separate Journal messages.
+
+### Manifest boundary
+
+The Manifest fixes what one LLM Call will actually receive after Context Policy selection. A historical raw Tool return value and the Tool message produced from it are not interchangeable: the raw result belongs to the execution log, while the message selected for an LLM Call belongs to the Manifest input path.
+
+One Provider response is captured as a Phronomy-owned `ProviderCallOutcome` before Agent-owned Tool execution starts. The canonical assistant-message record is produced from that outcome, not from Application callback delivery.
+
+Context selection is expressed separately through `ContextCandidate`, dependency-aware `ContextSelectionUnit`, `ContextRequest`, `ContextPolicy`, validated `ContextPlan`, and final token-budget validation. An assistant message containing Tool Calls and the corresponding Tool messages form an atomic protocol unit. Ordinary messages in the same `execution_id` remain independently selectable.
+
+## RubyLLM boundary
+
+Agent-owned Tool execution requires RubyLLM's additive callback contract introduced in RubyLLM 1.15. Phronomy therefore requires `ruby_llm >= 1.15, < 2`.
+
+RubyLLM 1.15 adds the complete assistant message to `Chat#messages` before `before_tool_call` callbacks run. Phronomy captures the immutable Provider outcome at that boundary and raises `ToolCallIntercepted` only as an internal control transfer so approval, suspension, parallel dispatch and durable state remain Phronomy-owned.
+
+## Consequences
+
+- Canonical execution history is independent of the current Context budget or policy.
+- Import and runtime histories converge on the same canonical assistant/tool-message model without synthetic grouping identity.
+- Old optional working history may be excluded from a follow-up Manifest without being deleted.
+- Raw Tool results remain available as execution facts even when the corresponding Tool message is omitted from a later Manifest.
+- Tool protocol dependencies are validated independently from semantic selection policy.
+- Context Policy can later introduce deterministic derived/compacted records without replacing their raw sources.
+- Public custom Context Policy APIs, transaction-boundary restructuring, deterministic compaction, Manifest v2/tool subsets, and legacy Assembler removal remain later phases.

data/lib/phronomy/agent/activation_registry.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class ActivationRegistry
+      def initialize
+        @mutex = Mutex.new
+        @records = {}
+      end
+
+      def register(activation)
+        @mutex.synchronize do
+          raise ArgumentError, "activation already registered: #{activation.execution_id}" if @records.key?(activation.execution_id)
+          @records[activation.execution_id] = activation
+        end
+        activation
+      end
+
+      def fetch(execution_id)
+        @mutex.synchronize { @records[execution_id.to_s] }
+      end
+
+      def delete(execution_id)
+        @mutex.synchronize { @records.delete(execution_id.to_s) }
+      end
+    end
+  end
+end

data/lib/phronomy/agent/agent_execution.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    class AgentExecution
+      ACTIVE_STATUSES = %i[preparing active suspended].freeze
+      TERMINAL_STATUSES = %i[completed failed cancelled rejected blocked].freeze
+      TRANSITIONS = {
+        preparing: %i[preparing active failed cancelled blocked],
+        active: %i[active suspended completed failed cancelled rejected blocked],
+        suspended: %i[suspended active failed cancelled],
+        completed: %i[completed],
+        failed: %i[failed],
+        cancelled: %i[cancelled],
+        rejected: %i[rejected],
+        blocked: %i[blocked]
+      }.freeze
+
+      ATTRIBUTES = %i[
+        execution_id agent_id execution_revision status phase
+        base_agent_revision base_context_revision base_journal_position
+        working_records llm_calls approval_request result_ref error_ref
+        created_at updated_at terminal_reason metadata
+      ].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def self.start(agent_root:, input_record:, metadata: {})
+        now = Time.now.utc.iso8601(6)
+        new(
+          execution_id: SecureRandom.uuid,
+          agent_id: agent_root.agent_id,
+          execution_revision: 0,
+          status: :preparing,
+          phase: :preparing,
+          base_agent_revision: agent_root.agent_revision,
+          base_context_revision: agent_root.context_revision,
+          base_journal_position: agent_root.journal_position,
+          working_records: [input_record],
+          llm_calls: [],
+          approval_request: nil,
+          result_ref: nil,
+          error_ref: nil,
+          created_at: now,
+          updated_at: now,
+          terminal_reason: nil,
+          metadata: metadata
+        )
+      end
+
+      def initialize(**attributes)
+        ATTRIBUTES.each do |name|
+          value = attributes.fetch(name)
+          value = value.to_sym if %i[status phase].include?(name)
+          instance_variable_set("@#{name}", Immutable.copy(value))
+        end
+        raise ArgumentError, "unknown execution status: #{status.inspect}" unless TRANSITIONS.key?(status)
+        raise ArgumentError, "execution_revision must be non-negative" if execution_revision.negative?
+        Immutable.validate_canonical_json!(metadata, label: "Execution metadata")
+        if approval_request
+          Immutable.validate_canonical_json!(approval_request, label: "Approval request")
+        end
+        freeze
+      end
+
+      def active?
+        ACTIVE_STATUSES.include?(status)
+      end
+
+      def terminal?
+        TERMINAL_STATUSES.include?(status)
+      end
+
+      def with(**changes)
+        next_status = changes.fetch(:status, status).to_sym
+        unless TRANSITIONS.fetch(status).include?(next_status)
+          raise ArgumentError, "illegal AgentExecution transition: #{status} -> #{next_status}"
+        end
+        values = ATTRIBUTES.to_h { |name| [name, public_send(name)] }.merge(changes)
+        values[:execution_revision] = execution_revision + 1 unless changes.key?(:execution_revision)
+        values[:updated_at] = Time.now.utc.iso8601(6) unless changes.key?(:updated_at)
+        self.class.new(**values)
+      end
+
+      def to_h
+        ATTRIBUTES.to_h do |name|
+          value = public_send(name)
+          value = value.map(&:to_h) if name == :working_records
+          value = value.map(&:to_h) if name == :llm_calls
+          [name.to_s, value]
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/agent_execution_activation.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    class AgentExecutionActivation
+      attr_reader :execution_id, :agent, :application_listener, :coordinator,
+        :base_manifest
+      attr_accessor :invocation, :session
+
+      def initialize(
+        execution:,
+        agent:,
+        runtime_projection:,
+        coordinator:,
+        application_listener: nil
+      )
+        @execution_id = execution.execution_id
+        @execution = execution
+        @agent = agent
+        @runtime_projection = runtime_projection
+        @base_manifest = runtime_projection.manifest
+        @coordinator = coordinator
+        @application_listener = application_listener
+        @mutex = Mutex.new
+        @active_call = nil
+        @llm_results = []
+        @runtime_events = []
+        @callback_errors = []
+      end
+
+      def execution
+        @mutex.synchronize { @execution }
+      end
+
+      def replace_execution(value)
+        @mutex.synchronize { @execution = value }
+      end
+
+      def runtime_projection
+        @mutex.synchronize { @runtime_projection }
+      end
+
+      def replace_runtime_projection(value)
+        @mutex.synchronize { @runtime_projection = value }
+      end
+
+      # Allocates Provider Call identity before transport begins. This identity is
+      # provenance only; Context selection must not use it as a semantic boundary.
+      def begin_llm_call(projection)
+        call_context = {
+          llm_call_id: SecureRandom.uuid,
+          manifest_ref: projection.manifest_ref,
+          started_at: Time.now.utc.iso8601(6)
+        }.freeze
+        @mutex.synchronize do
+          if @active_call
+            raise Phronomy::Error,
+              "cannot start a Provider Call while another Provider Call is active"
+          end
+          @runtime_projection = projection
+          @active_call = call_context
+        end
+        call_context
+      end
+
+      def record_llm_result(response:, error:, streaming:)
+        @mutex.synchronize do
+          active_call = @active_call
+          unless active_call
+            raise Phronomy::Error, "LLM result arrived without an active Provider Call"
+          end
+          @llm_results << {
+            llm_call_id: active_call.fetch(:llm_call_id),
+            response: response,
+            error: error,
+            streaming: streaming,
+            manifest_ref: active_call.fetch(:manifest_ref),
+            started_at: active_call.fetch(:started_at)
+          }
+          @active_call = nil
+        end
+      end
+
+      def runtime_snapshot
+        @mutex.synchronize do
+          {
+            llm_results: @llm_results.dup,
+            runtime_events: @runtime_events.dup,
+            active_call: @active_call&.dup
+          }
+        end
+      end
+
+      def acknowledge_runtime_snapshot(snapshot)
+        @mutex.synchronize do
+          @llm_results.shift(snapshot.fetch(:llm_results).length)
+          @runtime_events.shift(snapshot.fetch(:runtime_events).length)
+          if snapshot[:active_call] && @active_call == snapshot[:active_call]
+            @active_call = nil
+          end
+        end
+      end
+
+      ApplicationCallbackFailure = Data.define(:event_type, :error) do
+        def to_stream_callback_error
+          wrapped = Phronomy::StreamCallbackError.new(
+            event_type: event_type, original_error: error, result: nil
+          )
+          begin
+            raise wrapped, cause: error
+          rescue Phronomy::StreamCallbackError => caught
+            caught.set_backtrace(error.backtrace)
+            caught
+          end
+        end
+      end
+
+      attr_reader :callback_failure
+
+      def callback_failed?
+        @mutex.synchronize { !@callback_failure.nil? }
+      end
+
+      # Canonical runtime recording is independent of Application callback health.
+      # Once an event is observed it is appended even after a listener has failed.
+      def record_event(event)
+        listener = @mutex.synchronize do
+          @runtime_events << event
+          @callback_failure ? nil : @application_listener
+        end
+        return unless listener
+
+        listener.call(event)
+      rescue => callback_error
+        failure = ApplicationCallbackFailure.new(
+          event_type: event.type, error: callback_error
+        )
+        @mutex.synchronize do
+          @callback_failure ||= failure
+          @application_listener = nil
+        end
+        notify_callback_failure(failure)
+      end
+
+      private
+
+      def notify_callback_failure(failure)
+        invocation = @mutex.synchronize { @invocation }
+        if invocation
+          accepted = Phronomy::Runtime.instance.event_loop.post_to_session(
+            Phronomy::Event.new(
+              type: :application_callback_failed,
+              target_id: invocation.id,
+              payload: {failure: failure}
+            )
+          )
+          unless accepted
+            Phronomy.configuration.logger&.warn(
+              "[Phronomy] Callback failure recorded but could not notify FSM: execution_id=#{@execution_id}"
+            )
+          end
+        end
+        Phronomy.configuration.logger&.warn(
+          "[Phronomy] Application event listener failed: #{failure.error.class}: #{failure.error.message}"
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/agent/agent_invocation.rb

@@ -26,6 +26,8 @@ module Phronomy
         llm_failed
       ].freeze
 
+      CALLBACK_FAILED_EVENTS = %i[application_callback_failed].freeze
+
       attr_accessor :input,
         :messages,
         :chat,
@@ -50,7 +52,9 @@ module Phronomy
         :tool_invocations,
         :session_id,
         :phase,
-        :mode
+        :mode,
+        :current_llm_call_id,
+        :tool_batch_llm_call_id
 
       def initialize(
         agent:,
@@ -96,9 +100,10 @@ module Phronomy
         @error = nil
         @session_id = nil
         @phase = nil
+        @current_llm_call_id = nil
+        @tool_batch_llm_call_id = nil
       end
 
-      # Compatibility aliases for existing internal callers.
       def stream_listener
         @event_listener
       end
@@ -116,6 +121,11 @@ module Phronomy
         @phase = phase
       end
 
+      def begin_llm_call!(llm_call_id)
+        @current_llm_call_id = llm_call_id.to_s
+        self
+      end
+
       def pending_tool_calls=(calls)
         @pending_tool_calls = Array(calls)
       end
@@ -128,6 +138,7 @@ module Phronomy
         @pending_tool_calls = []
         @tool_invocations = []
         @approval_request = nil
+        @tool_batch_llm_call_id = nil
       end
 
       def handle_fsm_event(event)
@@ -146,6 +157,11 @@ module Phronomy
           return true
         end
 
+        if CALLBACK_FAILED_EVENTS.include?(event.type)
+          @error ||= event.payload.fetch(:failure).to_stream_callback_error
+          return true
+        end
+
         return false unless TOOL_EVENT_TYPES.include?(event.type)
 
         invocation = tool_invocation(
@@ -164,8 +180,6 @@ module Phronomy
         true
       end
 
-      # Deprecated internal compatibility hook. FSMSession no longer calls
-      # this method; asynchronous results enter through explicit events.
       def apply_fsm_action_result(result)
         event_type =
           if result.respond_to?(:error) &&
@@ -185,15 +199,20 @@ module Phronomy
         self
       end
 
-      def accept_tool_calls!(tool_calls)
+      def accept_tool_calls!(tool_calls, llm_call_id: nil)
         @user_message_sent = true
         @pending_tool_calls = Array(tool_calls)
         @messages = @chat.messages
+        @tool_batch_llm_call_id = (llm_call_id || @current_llm_call_id)&.to_s
+        @current_llm_call_id = nil
         @pending_tool_calls.each do |tool_call|
           deliver_event(
             StreamEvent.new(
               type: :tool_call,
-              payload: {tool_call: tool_call}
+              payload: {
+                tool_call: tool_call,
+                llm_call_id: @tool_batch_llm_call_id
+              }.compact
             )
           )
         end
@@ -210,6 +229,7 @@ module Phronomy
         @usage = Phronomy::TokenUsage.from_tokens(response.tokens)
         @messages = @chat.messages
         @pending_tool_calls = []
+        @current_llm_call_id = nil
         self
       end
 
@@ -255,9 +275,10 @@ module Phronomy
 
       def record_tool_results!
         @tool_invocations.each do |invocation|
+          tool_content = invocation.result.to_s
           @chat.add_message(
             role: :tool,
-            content: invocation.result.to_s,
+            content: tool_content,
             tool_call_id: invocation.tool_call_id
           )
           deliver_event(
@@ -266,8 +287,14 @@ module Phronomy
               payload: {
                 tool_call_id: invocation.tool_call_id,
                 tool_name: invocation.tool_name,
-                tool_result: invocation.result
-              }
+                tool_result: invocation.result,
+                tool_message: {
+                  "role" => "tool",
+                  "content" => tool_content,
+                  "tool_call_id" => invocation.tool_call_id.to_s
+                },
+                llm_call_id: @tool_batch_llm_call_id
+              }.compact
             )
           )
         end
@@ -361,6 +388,7 @@ module Phronomy
         end
 
         if event.type == :llm_failed
+          @current_llm_call_id = nil
           @error = result.error ||
             Phronomy::Error.new("LLM operation failed without an error")
           return
@@ -368,8 +396,12 @@ module Phronomy
 
         if result.error
           if result.error.is_a?(ToolCallIntercepted)
-            accept_tool_calls!(result.error.tool_calls)
+            accept_tool_calls!(
+              result.error.tool_calls,
+              llm_call_id: result.error.llm_call_id
+            )
           else
+            @current_llm_call_id = nil
             @error = result.error
           end
         else