phronomy 0.26.0 → 0.27.0

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

data/lib/phronomy/agent/{context_plan.rb → context_contract/context_plan.rb}

@@ -21,7 +21,7 @@ module Phronomy
           knowledge: Array(knowledge).freeze,
           tools: Array(tools).freeze,
           conversation: Array(conversation).map { |group| Array(group).freeze }.freeze,
-          metadata: Immutable.copy(metadata || {})
+          metadata: Phronomy::Values::Immutable.copy(metadata || {})
         )
         freeze
       end

data/lib/phronomy/agent/{context_policy_input.rb → context_contract/context_policy_input.rb}

@@ -50,8 +50,8 @@ module Phronomy
           knowledge: normalized_knowledge,
           tools: normalized_tools,
           conversation: normalized_conversation,
-          model_config: Immutable.copy(values[:model_config] || {}),
-          metadata: Immutable.copy(values[:metadata] || {})
+          model_config: Phronomy::Values::Immutable.copy(values[:model_config] || {}),
+          metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
         ))
         freeze
       end
@@ -145,7 +145,7 @@ module Phronomy
       ) do
         def initialize(**values)
           provenance = ContextPolicyInput.send(:normalize_provenance, values[:provenance])
-          definition = Immutable.copy(values.fetch(:definition))
+          definition = Phronomy::Values::Immutable.copy(values.fetch(:definition))
           unless definition.is_a?(Hash) && definition["name"].to_s != ""
             raise ArgumentError, "ContextPolicyInput ToolItem definition requires a non-empty name"
           end
@@ -156,7 +156,7 @@ module Phronomy
             estimated_tokens: ContextPolicyInput.send(:normalize_estimated_tokens, values[:estimated_tokens]),
             required: !!values[:required],
             provenance: provenance,
-            metadata: Immutable.copy(values[:metadata] || {})
+            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
           )
           raise ArgumentError, "ContextPolicyInput ToolItem id must not be empty" if id.empty?
           freeze
@@ -212,12 +212,12 @@ module Phronomy
             id: id,
             kind: kind,
             role: role,
-            content: Immutable.copy(values[:content]),
+            content: Phronomy::Values::Immutable.copy(values[:content]),
             content_format: content_format,
             estimated_tokens: normalize_estimated_tokens(values[:estimated_tokens]),
             required: !!values[:required],
             provenance: normalize_provenance(values[:provenance]),
-            metadata: Immutable.copy(values[:metadata] || {})
+            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
           }
         end
 

data/lib/phronomy/agent/{llm_input_build_context.rb → context_contract/llm_input_build_context.rb}

@@ -9,7 +9,7 @@ module Phronomy
       :config, :call_sequence
     ) do
       def initialize(**values)
-        super(**values.merge(config: Immutable.copy(values.fetch(:config, {}))))
+        super(**values.merge(config: Phronomy::Values::Immutable.copy(values.fetch(:config, {}))))
         freeze
       end
     end

data/lib/phronomy/agent/{llm_input_manifest.rb → context_contract/llm_input_manifest.rb}

@@ -3,7 +3,7 @@
 module Phronomy
   module Agent
     # ContentStore-backed durable codec boundary for one Provider input manifest.
-    # It is intentionally separate from Persistence::DurableRecord.
+    # It is intentionally separate from Storage::DurableRecord.
     class LLMInputManifest
       VERSION = "0.1"
       CALL_MODES = %i[ask complete].freeze
@@ -18,7 +18,7 @@ module Phronomy
           if delivery.nil? || !SEGMENT_DELIVERIES.include?(delivery.to_s)
             raise ArgumentError, "unknown Segment delivery: #{delivery.inspect}"
           end
-          super(**values.merge(metadata: Immutable.copy(values[:metadata] || {})))
+          super(**values.merge(metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})))
           freeze
         end
 
@@ -62,7 +62,7 @@ module Phronomy
             label: label
           )
           unless SEGMENT_DELIVERIES.include?(delivery)
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "LLMInputManifest segment delivery must be one of #{SEGMENT_DELIVERIES.inspect}, got #{delivery.inspect}"
           end
           tool_call_id = LLMInputManifest.send(
@@ -87,10 +87,10 @@ module Phronomy
             tool_call_id: tool_call_id,
             metadata: metadata
           )
-        rescue Phronomy::Persistence::SerializationError
+        rescue Phronomy::Storage::SerializationError
           raise
         rescue => error
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "invalid LLMInputManifest segment: #{error.class}: #{error.message}"
         end
 
@@ -162,7 +162,7 @@ module Phronomy
         label = "LLMInputManifest"
         version = source.fetch("version")
         unless version.is_a?(String) && version == VERSION
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "unsupported LLMInputManifest version: #{version.inspect}; " \
             "current version is #{VERSION.inspect}"
         end
@@ -229,10 +229,10 @@ module Phronomy
           adapter_name: adapter_name,
           adapter_version: adapter_version
         )
-      rescue Phronomy::Persistence::SerializationError
+      rescue Phronomy::Storage::SerializationError
         raise
       rescue => error
-        raise Phronomy::Persistence::SerializationError,
+        raise Phronomy::Storage::SerializationError,
           "invalid LLMInputManifest: #{error.class}: #{error.message}"
       end
 
@@ -262,11 +262,11 @@ module Phronomy
 
         def strict_source!(hash, required:, optional:, label:)
           unless hash.is_a?(Hash)
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "#{label} must be a Hash"
           end
           unless hash.keys.all? { |key| key.is_a?(String) }
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "#{label} keys must all be String"
           end
 
@@ -277,13 +277,13 @@ module Phronomy
             details = []
             details << "missing=#{missing.inspect}" unless missing.empty?
             details << "unknown=#{unknown.inspect}" unless unknown.empty?
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "#{label} schema mismatch (#{details.join(", ")})"
           end
           Phronomy::CanonicalJSON.dump(hash)
           hash
         rescue ArgumentError => error
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} is not canonical JSON compatible: #{error.message}"
         end
 
@@ -291,7 +291,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Integer)
 
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} #{key} must be an Integer"
         end
 
@@ -299,7 +299,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Integer) && value.positive?
 
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} #{key} must be a positive Integer"
         end
 
@@ -307,7 +307,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Integer) && value >= 0
 
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} #{key} must be a non-negative Integer"
         end
 
@@ -315,7 +315,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(String) && !value.empty?
 
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} #{key} must be a non-empty String"
         end
 
@@ -323,7 +323,7 @@ module Phronomy
           value = hash[key]
           return value if value.nil? || value.is_a?(String)
 
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} #{key} must be a String or nil"
         end
 
@@ -331,7 +331,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(String) && allowed.include?(value)
 
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} #{key} must be one of #{allowed.inspect}"
         end
 
@@ -339,7 +339,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Array)
 
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} #{key} must be an Array"
         end
 
@@ -347,7 +347,7 @@ module Phronomy
           value = hash.fetch(key)
           return value if value.is_a?(Hash)
 
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} #{key} must be a Hash"
         end
       end

data/lib/phronomy/agent/{llm_input_patch.rb → context_contract/llm_input_patch.rb}

@@ -7,8 +7,8 @@ module Phronomy
     LLMInputPatch = Data.define(:model_config_patch, :segment_candidates) do
       def initialize(model_config_patch: nil, segment_candidates: nil)
         super(
-          model_config_patch: model_config_patch && Immutable.copy(model_config_patch),
-          segment_candidates: segment_candidates && Immutable.copy(Array(segment_candidates))
+          model_config_patch: model_config_patch && Phronomy::Values::Immutable.copy(model_config_patch),
+          segment_candidates: segment_candidates && Phronomy::Values::Immutable.copy(Array(segment_candidates))
         )
         freeze
       end

data/lib/phronomy/agent/{agent_execution.rb → execution/agent_execution.rb}

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
 require "securerandom"
 require "time"
 
 module Phronomy
   module Agent
     class AgentExecution
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       ACTIVE_STATUSES = %i[preparing active suspended].freeze
       TERMINAL_STATUSES = %i[completed handed_off failed cancelled rejected blocked].freeze
       TRANSITIONS = {
@@ -55,13 +59,13 @@ module Phronomy
         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))
+          instance_variable_set("@#{name}", Phronomy::Values::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")
+        Phronomy::Values::Immutable.validate_canonical_json!(metadata, label: "Execution metadata")
         if approval_request
-          Immutable.validate_canonical_json!(approval_request, label: "Approval request")
+          Phronomy::Values::Immutable.validate_canonical_json!(approval_request, label: "Approval request")
         end
         freeze
       end
@@ -86,7 +90,7 @@ module Phronomy
       end
 
       # Current semantic payload representation. Persistence format identity and
-      # compatibility validation are owned by Persistence::DurableCodec.
+      # compatibility validation are owned by Agent::Persistence::Codec.
       # @api public
       def to_h
         ATTRIBUTES.to_h do |name|

data/lib/phronomy/agent/{agent_invocation.rb → execution/agent_invocation.rb}

@@ -1,22 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
 require "securerandom"
 require "time"
 
 module Phronomy
   module Agent
     class AgentInvocation
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       # execution_id is the logical Agent execution parent. Concrete Runtime
       # routing identity belongs only to the owning FSMSession incarnation.
-      TOOL_EVENT_TYPES = %i[
-        tool_authorized
-        tool_approval_required
-        tool_completed
-        tool_failed
-        tool_rejected
-        tool_cancelled
-      ].freeze
-
       LLM_EVENT_TYPES = %i[llm_completed llm_failed].freeze
       CALLBACK_FAILED_EVENTS = %i[application_callback_failed].freeze
       SETUP_FAILED_EVENTS = %i[llm_setup_failed tool_setup_failed].freeze
@@ -147,11 +142,11 @@ module Phronomy
         if durable_id.nil? &&
             Phronomy::Runtime.instance.event_loop.current?
           state =
-            Phronomy::Runtime.instance.event_loop.agent_execution_state(
+            Phronomy::Agent::ExecutionRegistry.for(Phronomy::Runtime.instance.event_loop).agent_execution_state(
               execution_id
             )
           durable_id = state&.execution&.metadata&.fetch(
-            RecoverySupport::PENDING_LLM_ID_KEY,
+            ExecutionMetadata::PENDING_LLM_ID_KEY,
             nil
           )
         end
@@ -209,7 +204,7 @@ module Phronomy
           return true
         end
 
-        return false unless TOOL_EVENT_TYPES.include?(event.type)
+        return false unless InvocationTransitions::TOOL_EVENTS.include?(event.type)
 
         invocation = tool_invocation(event.payload&.fetch(:tool_invocation_id, nil))
         return true unless invocation
@@ -540,7 +535,7 @@ module Phronomy
         # listener receives the notification event separately.
         @runtime_events << StreamEvent.new(
           type: event.type,
-          payload: Immutable.copy(event.payload)
+          payload: Phronomy::Values::Immutable.copy(event.payload)
         )
         listener = @callback_failure ? nil : @event_listener
         return unless listener