phronomy 0.25.0 → 0.27.0

data/lib/phronomy/agent/context/capability/tool_executor.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Capability
+        # Routes Tool work according to the Tool execution contract.
+        #
+        # Both execution modes return {Phronomy::TaskResult}; only the execution mechanism
+        # differs.
+        #
+        # :cooperative Tool calls execute inline and must return quickly. call_async
+        # wraps their result in an already-settled TaskResult and never consumes an
+        # OffloadPool worker.
+        #
+        # :offloaded Tool calls route synchronous work through OffloadPool, whose
+        # caller-facing completion handle is also a TaskResult. Phronomy does not distinguish
+        # whether the reason is blocking I/O, CPU-bound work, or another long
+        # synchronous operation.
+        #
+        # @api private
+        module ToolExecutor
+          # @api private
+          def self.call_async(
+            tool:,
+            args:,
+            cancellation_token: nil,
+            config: {},
+            runtime: nil,
+            on_full: :raise
+          )
+            mode = tool.class.execution_mode
+
+            case mode
+            when :cooperative
+              task = Phronomy::TaskResult.deferred(name: "tool-#{tool.name}")
+              begin
+                task.complete(
+                  tool.call(args, cancellation_token: cancellation_token)
+                )
+              rescue => error
+                task.fail(error)
+              end
+              task
+            when :offloaded
+              runtime ||= Phronomy::Runtime.instance
+              runtime.offload.submit(
+                cancellation_token: cancellation_token,
+                on_full: on_full
+              ) do
+                tool.call(args, cancellation_token: cancellation_token)
+              end
+            else
+              raise Phronomy::ConfigurationError,
+                "unknown Tool execution_mode: #{mode.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/{context_assembler.rb → context_assembly/context_assembler.rb}

@@ -3,7 +3,7 @@
 module Phronomy
   module Agent
     class ContextAssembler
-      ASSEMBLY_POLICY_VERSION = 8
+      ASSEMBLY_POLICY_VERSION = 9
       SEGMENT_ORIGIN_METADATA_KEY = "phronomy_origin"
       POLICY_ORIGIN_METADATA_KEY = "context_policy_origin"
       POLICY_ITEM_ID_METADATA_KEY = "context_policy_item_id"
@@ -59,81 +59,33 @@ module Phronomy
         excluded = [execution.metadata["current_input_record_id"]].compact
         handoff_context = config[:phronomy_handoff_context]
 
-        instructions = []
-        unless system_text.to_s.empty?
-          instructions << ContextPolicyInput::InstructionItem.new(
-            id: "instruction:agent:#{execution.execution_id}:1",
-            kind: :instruction,
-            role: :system,
-            content: system_text.to_s,
-            content_format: :text,
-            estimated_tokens: estimate_value(system_text.to_s),
-            required: true,
-            provenance: ContextPolicyInput::Provenance.new(origin: :agent_configuration),
-            metadata: {}
-          )
-        end
-        if handoff_context
-          instructions << ContextPolicyInput::InstructionItem.new(
-            id: "instruction:handoff:#{execution.execution_id}:1",
-            kind: :handoff_responsibility,
-            role: :user,
-            content: handoff_context.responsibility.to_s,
-            content_format: :text,
-            estimated_tokens: estimate_value(handoff_context.responsibility.to_s),
-            required: true,
-            provenance: ContextPolicyInput::Provenance.new(origin: :handoff_context),
-            metadata: {SEGMENT_ORIGIN_METADATA_KEY => HANDOFF_CONTEXT_ORIGIN}
-          )
-        end
+        instructions = initial_instruction_items(
+          system_text,
+          handoff_context,
+          execution: execution
+        )
 
-        generation = agent_root.transcript_generation
-        eligible_working = Array(execution.working_records).select do |record|
-          record.context_candidate && record.context_generation == generation
-        end
-        candidates = @candidate_resolver.resolve(
-          prior_records: projection.context_records,
-          working_records: eligible_working,
+        candidates = resolve_record_candidates(
+          projection,
+          agent_root: agent_root,
+          execution: execution,
           excluded_record_ids: excluded
         )
-        candidates = merge_hook_candidates(
+        candidates = merge_context_candidates(
           candidates,
           hook_candidates,
+          handoff_context,
           agent_root: agent_root,
           execution: execution,
           call_sequence: 1
         )
-        candidates = merge_handoff_candidates(
-          candidates,
-          handoff_context,
+        current_input = current_input_item(
+          current_input_content,
+          input_ref: input_ref,
+          candidates: candidates,
+          agent_root: agent_root,
           execution: execution
         )
-        next_sequence = Array(candidates).filter_map(&:sequence).max.to_i + 1
-        current_input = ContextPolicyInput::ConversationItem.new(
-          id: "current-input:#{execution.execution_id}",
-          kind: :current_input,
-          role: :user,
-          content: current_input_content,
-          content_format: :text,
-          sequence: next_sequence,
-          estimated_tokens: estimate_value(current_input_content),
-          required: true,
-          provenance: ContextPolicyInput::Provenance.new(
-            origin: :working,
-            content_ref: input_ref,
-            record_id: execution.metadata["current_input_record_id"],
-            agent_id: agent_root.agent_id,
-            execution_id: execution.execution_id
-          ),
-          tool_call_id: nil,
-          tool_call_ids: [],
-          delivery: :ask_argument,
-          metadata: {
-            "source_agent_id" => agent_root.agent_id,
-            "source_execution_id" => execution.execution_id,
-            "handoff_policy_category" => "current_request"
-          }
-        )
 
         prepare(
           agent_root: agent_root,
@@ -168,33 +120,23 @@ module Phronomy
           additional_tools: handoff_tool_classes(config)
         )
 
-        instructions = base_manifest.segments.filter_map do |segment|
-          next unless retained_base_instruction?(segment)
-          instruction_item_from_manifest(segment)
-        end
+        instructions = retained_instruction_items(base_manifest)
 
-        generation = agent_root.transcript_generation
-        eligible_working = Array(execution.working_records).select do |record|
-          record.context_candidate && record.context_generation == generation
-        end
-        candidates = @candidate_resolver.resolve(
-          prior_records: projection.context_records,
-          working_records: eligible_working,
+        candidates = resolve_record_candidates(
+          projection,
+          agent_root: agent_root,
+          execution: execution,
           excluded_record_ids: []
         )
         call_sequence = execution.llm_calls.length + 1
-        candidates = merge_hook_candidates(
+        candidates = merge_context_candidates(
           candidates,
           hook_candidates,
+          handoff_context,
           agent_root: agent_root,
           execution: execution,
           call_sequence: call_sequence
         )
-        candidates = merge_handoff_candidates(
-          candidates,
-          handoff_context,
-          execution: execution
-        )
 
         prepare(
           agent_root: agent_root,
@@ -274,6 +216,111 @@ module Phronomy
 
       private
 
+      def initial_instruction_items(system_text, handoff_context, execution:)
+        instructions = []
+        unless system_text.to_s.empty?
+          instructions << agent_instruction_item(system_text, execution: execution)
+        end
+        if handoff_context
+          instructions << handoff_instruction_item(handoff_context, execution: execution)
+        end
+        instructions
+      end
+
+      def agent_instruction_item(system_text, execution:)
+        ContextPolicyInput::InstructionItem.new(
+          id: "instruction:agent:#{execution.execution_id}:1",
+          kind: :instruction,
+          role: :system,
+          content: system_text.to_s,
+          content_format: :text,
+          estimated_tokens: estimate_value(system_text.to_s),
+          required: true,
+          provenance: ContextPolicyInput::Provenance.new(origin: :agent_configuration),
+          metadata: {}
+        )
+      end
+
+      def handoff_instruction_item(handoff_context, execution:)
+        ContextPolicyInput::InstructionItem.new(
+          id: "instruction:handoff:#{execution.execution_id}:1",
+          kind: :handoff_responsibility,
+          role: :user,
+          content: handoff_context.responsibility.to_s,
+          content_format: :text,
+          estimated_tokens: estimate_value(handoff_context.responsibility.to_s),
+          required: true,
+          provenance: ContextPolicyInput::Provenance.new(origin: :handoff_context),
+          metadata: {SEGMENT_ORIGIN_METADATA_KEY => HANDOFF_CONTEXT_ORIGIN}
+        )
+      end
+
+      def retained_instruction_items(base_manifest)
+        base_manifest.segments.filter_map do |segment|
+          next unless retained_base_instruction?(segment)
+          instruction_item_from_manifest(segment)
+        end
+      end
+
+      def resolve_record_candidates(projection, agent_root:, execution:, excluded_record_ids:)
+        generation = agent_root.transcript_generation
+        eligible_working = Array(execution.working_records).select do |record|
+          record.context_candidate && record.context_generation == generation
+        end
+        @candidate_resolver.resolve(
+          prior_records: projection.context_records,
+          working_records: eligible_working,
+          excluded_record_ids: excluded_record_ids
+        )
+      end
+
+      def merge_context_candidates(
+        candidates, hook_candidates, handoff_context,
+        agent_root:, execution:, call_sequence:
+      )
+        candidates = merge_hook_candidates(
+          candidates,
+          hook_candidates,
+          agent_root: agent_root,
+          execution: execution,
+          call_sequence: call_sequence
+        )
+        merge_handoff_candidates(
+          candidates,
+          handoff_context,
+          execution: execution
+        )
+      end
+
+      def current_input_item(content, input_ref:, candidates:, agent_root:, execution:)
+        next_sequence = Array(candidates).filter_map(&:sequence).max.to_i + 1
+        ContextPolicyInput::ConversationItem.new(
+          id: "current-input:#{execution.execution_id}",
+          kind: :current_input,
+          role: :user,
+          content: content,
+          content_format: :text,
+          sequence: next_sequence,
+          estimated_tokens: estimate_value(content),
+          required: true,
+          provenance: ContextPolicyInput::Provenance.new(
+            origin: :working,
+            content_ref: input_ref,
+            record_id: execution.metadata["current_input_record_id"],
+            agent_id: agent_root.agent_id,
+            execution_id: execution.execution_id
+          ),
+          tool_call_id: nil,
+          tool_call_ids: [],
+          delivery: :ask_argument,
+          metadata: {
+            "source_agent_id" => agent_root.agent_id,
+            "source_execution_id" => execution.execution_id,
+            "handoff_policy_category" => "current_request"
+          }
+        )
+      end
+
       def prepare(
         agent_root:,
         execution:,
@@ -286,7 +333,7 @@ module Phronomy
         tools:,
         current_input:
       )
-        token_budget = TokenBudgetResolver.new(agent: @agent).resolve(model_config)
+        token_budget = TokenBudgetResolver.new.resolve(model_config)
         policy_input = @input_builder.build(
           agent_id: agent_root.agent_id,
           execution_id: execution.execution_id,
@@ -438,7 +485,7 @@ module Phronomy
 
       def sanitized_item_metadata(item)
         raw = item.metadata.to_h.transform_keys(&:to_s)
-        # :working origin is Phronomy-controlled (from perform_initial_preparation),
+        # :working origin is Phronomy-controlled (from InitialPreparation),
         # so handoff routing metadata on working records is equally trusted.
         trusted_handoff = if item.provenance.origin == :handoff || item.provenance.origin == :working
           raw.slice(*TRUSTED_HANDOFF_METADATA_KEYS)
@@ -474,15 +521,23 @@ module Phronomy
           "provider" => @agent.class.provider&.to_s,
           "temperature" => @agent.class.temperature,
           "max_output_tokens" => @agent.class.max_output_tokens,
-          "context_window" => @agent.class.context_window,
-          "cache_instructions" => !!@agent.class.cache_instructions,
-          "parallel_tool_execution" => !!Phronomy.configuration.parallel_tool_execution
+          "cache_instructions" => !!@agent.class.cache_instructions
         }.compact
       end
 
       def apply_model_config_patch(base, patch)
         return base unless patch
-        base.merge(patch.to_h.transform_keys(&:to_s)).compact
+        values = patch.to_h.transform_keys(&:to_s)
+        if values.key?("context_window")
+          raise Phronomy::ConfigurationError,
+            "context_window is model metadata; configure the RubyLLM model registry"
+        end
+        if values.key?("max_output_tokens") && !values["max_output_tokens"].nil?
+          cap = Integer(values["max_output_tokens"])
+          raise ArgumentError, "max_output_tokens must be positive" unless cap.positive?
+          values["max_output_tokens"] = cap
+        end
+        base.merge(values).compact
       end
 
       def normalize_candidates(candidates)

data/lib/phronomy/agent/{context_importer.rb → context_assembly/context_importer.rb}

@@ -8,8 +8,8 @@ module Phronomy
       ) do
         def initialize(**values)
           super(**values.merge(
-            content: Immutable.copy(values[:content]),
-            metadata: Immutable.copy(values[:metadata] || {})
+            content: Phronomy::Values::Immutable.copy(values[:content]),
+            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
           ))
           freeze
         end

data/lib/phronomy/agent/{ruby_llm_materializer.rb → context_assembly/ruby_llm_materializer.rb}

@@ -43,7 +43,7 @@ module Phronomy
           messages: materialize_message_segments(message_segments).freeze,
           tool_classes: tool_set.runtime_tools,
           ask_message: ask_message,
-          model_config: Immutable.copy(model_config),
+          model_config: Phronomy::Values::Immutable.copy(model_config),
           manifest: manifest,
           manifest_ref: manifest_ref
         )
@@ -151,22 +151,19 @@ module Phronomy
         end
 
         tool_calls = materialize_tool_calls(payload["tool_calls"])
-        message = RubyLLM::Message.new(
+        RubyLLM::Message.new(
           role: role,
           content: initial_content_for(role, payload.fetch("content", nil), tool_calls),
           tool_calls: tool_calls.empty? ? nil : tool_calls,
           tool_call_id: payload["tool_call_id"],
-          model_id: payload["model_id"]
+          model: payload["model_id"]
         )
-
-        message.content = payload["content"] if payload.key?("content")
-        message
       end
 
       def initial_content_for(role, content, tool_calls)
         return "" if role == :assistant && content.nil? && !tool_calls.empty?
 
-        content.nil? ? "" : content
+        (content.is_a?(Hash) || content.is_a?(Array)) ? JSON.generate(content) : content
       end
 
       def materialize_tool_calls(payloads)

data/lib/phronomy/agent/context_assembly/runtime_chat_builder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Constructs provider chat objects from already selected model settings.
+    # Agent hooks retain projection installation and invocation-specific Tools.
+    # @api private
+    class RuntimeChatBuilder
+      def self.build(config)
+        chat = RubyLLM.chat(**chat_options(config))
+        chat.with_temperature(config["temperature"]) if config["temperature"]
+        if config["max_output_tokens"]
+          chat.with_max_output_tokens(config["max_output_tokens"])
+        end
+        chat
+      end
+
+      def self.apply_instructions(chat, text, cache:, provider:)
+        chat.with_instructions(text, cache_until_here: cache)
+      end
+
+      def self.chat_options(config)
+        opts = {}
+        model = config["model"]
+        opts[:model] = model if model
+        provider = config["provider"]
+        if provider
+          opts[:provider] = provider.to_sym
+          opts[:assume_model_exists] = true
+        end
+        opts
+      end
+      private_class_method :chat_options
+    end
+  end
+end

data/lib/phronomy/agent/context_assembly/saved_context_reader.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Reads saved manifests and Provider output for continuation preparation.
+    # Callers perform these reads before applying live state on EventLoop.
+    # @api private
+    module SavedContextReader
+      module_function
+
+      def manifest_from_ref(agent, ref)
+        raw = agent.persistence.contents.fetch_json(ref)
+        Phronomy::Agent::LLMInputManifest.from_h(raw)
+      end
+
+      def materialize_projection(agent, manifest_ref)
+        manifest = manifest_from_ref(agent, manifest_ref)
+        projection = Phronomy::Agent::RubyLLMMaterializer.new(
+          agent: agent,
+          persistence: agent.persistence
+        ).materialize(manifest: manifest, manifest_ref: manifest_ref)
+        [manifest, projection]
+      end
+
+      def latest_assistant_record(execution, llm_call_id: nil)
+        Array(execution.working_records).reverse.find do |record|
+          record.kind.to_sym == :assistant_message &&
+            (llm_call_id.nil? || record.llm_call_id.to_s == llm_call_id.to_s)
+        end
+      end
+
+      def provider_output_and_usage(agent, execution)
+        assistant = latest_assistant_record(execution)
+        payload = assistant ? agent.persistence.contents.fetch_json(assistant.content_ref) : {}
+        output = payload["content"]
+
+        call = execution.llm_calls.last
+        usage_hash = if call&.usage_ref
+          agent.persistence.contents.fetch_json(call.usage_ref)
+        else
+          {}
+        end
+        usage = Phronomy::TokenUsage.new(
+          input: usage_hash["input"] || usage_hash[:input] || usage_hash["input_tokens"] || usage_hash[:input_tokens],
+          output: usage_hash["output"] || usage_hash[:output] || usage_hash["output_tokens"] || usage_hash[:output_tokens],
+          cached: usage_hash["cached"] || usage_hash[:cached] || usage_hash["cache_read_tokens"] || usage_hash[:cache_read_tokens] || usage_hash["cached_tokens"] || usage_hash[:cached_tokens],
+          cache_creation: usage_hash["cache_creation"] || usage_hash[:cache_creation] || usage_hash["cache_write_tokens"] || usage_hash[:cache_write_tokens] || usage_hash["cache_creation_tokens"] || usage_hash[:cache_creation_tokens]
+        )
+        [output, usage]
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_assembly/state_writer.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Persists initial state and explicit idle-Agent context/lifecycle changes.
+    # Base owns live-state publication; execution commits have separate owners.
+    # @api private
+    class StateWriter
+      Update = Data.define(:root, :records)
+      private_constant :Update
+
+      def initialize(persistence:, agent_id:)
+        @persistence = persistence
+        @agent_id = agent_id
+      end
+
+      def create_root(definition:, context:, knowledge:, metadata:)
+        root = Agent::AgentRoot.create(
+          agent_id: agent_id,
+          agent_definition_id: definition.fetch(:id),
+          agent_definition_version: definition.fetch(:version),
+          metadata: metadata
+        )
+        persistence.transaction do |tx|
+          tx.agents.create(root)
+          records = initial_context_records(tx: tx, root: root, context: context)
+          records.concat(initial_knowledge_records(tx: tx, root: root, knowledge: knowledge))
+          unless records.empty?
+            appended = tx.journals.append(agent_id, expected_position: 0, records: records)
+            root = root.with(
+              agent_revision: 1,
+              context_revision: 1,
+              journal_position: appended.length
+            )
+            tx.agents.save(agent_id, expected_revision: 0, root: root)
+          end
+        end
+        root
+      end
+
+      def add_knowledge(root:, content:, metadata:)
+        current = root
+        next_root = nil
+        appended = nil
+        persistence.transaction do |tx|
+          tx.executions.assert_idle!(agent_id)
+          record = build_knowledge_record(
+            tx: tx,
+            root: current,
+            content: content,
+            metadata: metadata
+          )
+          appended = tx.journals.append(
+            agent_id,
+            expected_position: current.journal_position,
+            records: [record]
+          )
+          next_root = current.with(
+            agent_revision: current.agent_revision + 1,
+            context_revision: current.context_revision + 1,
+            journal_position: current.journal_position + appended.length
+          )
+          tx.agents.save(
+            agent_id,
+            expected_revision: current.agent_revision,
+            root: next_root
+          )
+        end
+        Update.new(root: next_root, records: appended)
+      end
+
+      def mutate_context(root:, kind:, context_affecting:)
+        current = root
+        next_root = nil
+        appended = nil
+        persistence.transaction do |tx|
+          tx.executions.assert_idle!(agent_id)
+          record = Agent::JournalRecord.new(
+            agent_id: agent_id,
+            kind: kind,
+            channel: :state,
+            context_generation: current.transcript_generation,
+            context_candidate: false
+          )
+          appended = tx.journals.append(
+            agent_id,
+            expected_position: current.journal_position,
+            records: [record]
+          )
+          proposed = yield(current)
+          next_root = proposed.with(
+            journal_position: current.journal_position + appended.length,
+            context_revision: context_affecting ?
+              yield_context_revision(current, proposed) : current.context_revision
+          )
+          tx.agents.save(
+            agent_id,
+            expected_revision: current.agent_revision,
+            root: next_root
+          )
+        end
+        Update.new(root: next_root, records: appended)
+      end
+
+      private
+
+      attr_reader :persistence, :agent_id
+
+      def initial_context_records(tx:, root:, context:)
+        return [] unless context
+
+        imported = context.respond_to?(:records) ? context :
+          Agent::ContextImporter.import_messages(context)
+        imported.records.map do |record|
+          content_ref = case record.content_format
+          when :text then tx.contents.put_text(record.content)
+          when :json then tx.contents.put_json(record.content)
+          else
+            raise ArgumentError,
+              "unsupported imported content format: #{record.content_format.inspect}"
+          end
+          Agent::JournalRecord.new(
+            agent_id: agent_id,
+            kind: record.kind,
+            channel: record.channel,
+            role: record.role,
+            content_ref: content_ref,
+            context_generation: root.transcript_generation,
+            context_candidate: true,
+            metadata: record.metadata
+          )
+        end
+      end
+
+      def initial_knowledge_records(tx:, root:, knowledge:)
+        Array(knowledge).map do |content|
+          build_knowledge_record(
+            tx: tx,
+            root: root,
+            content: content,
+            metadata: {}
+          )
+        end
+      end
+
+      def build_knowledge_record(tx:, root:, content:, metadata:)
+        Agent::JournalRecord.new(
+          agent_id: agent_id,
+          kind: :knowledge,
+          channel: :context,
+          role: :user,
+          content_ref: tx.contents.put_text(String(content)),
+          context_generation: root.transcript_generation,
+          context_candidate: true,
+          metadata: metadata || {}
+        )
+      end
+
+      def yield_context_revision(current, proposed)
+        (proposed.context_revision == current.context_revision) ?
+          current.context_revision + 1 : proposed.context_revision
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_assembly/token_budget_resolver.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Resolves the input limit from RubyLLM's authoritative model registry.
+    class TokenBudgetResolver
+      def resolve(model_config)
+        config = model_config.to_h.transform_keys(&:to_s)
+        model_name = config["model"]
+        return nil unless model_name
+
+        model = RubyLLM.models.find(model_name, provider: config["provider"])
+        limit = model&.context_window
+        return nil unless limit.is_a?(Integer) && limit.positive?
+
+        Phronomy::LlmContextWindow::TokenBudget.new(max_input_tokens: limit)
+      rescue RubyLLM::ModelNotFoundError
+        nil
+      end
+    end
+  end
+end