phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/state_writer.rb

@@ -0,0 +1,166 @@
+# 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:, retention: nil)
+        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)
+          tx.retentions.retain(retention) if retention
+          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.is_a?(KnowledgeItem) ? content.content : content,
+            metadata: content.is_a?(KnowledgeItem) ? 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/store.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent-owned durable operations and observations. An injected record
+    # adapter implements storage; this framework never selects a DB or codec.
+    # @api public
+    class Store
+      # Provider-ordered authorized calls, with no internal execution metadata.
+      AuthorizedOperation = Data.define(:invocation_id, :name, :arguments)
+
+      attr_reader :coordinator
+
+      # Record protocol for Agent-owned framework operations only.
+      # @api private
+      attr_reader :contents, :agents, :journals, :executions, :retentions
+
+      def initialize(coordinator:, records:)
+        @coordinator, @record_adapter = coordinator, records
+        @records = coordinator.bind(records)
+        @contents = @records.contents
+        @agents = @records.agents
+        @journals = @records.journals
+        @executions = @records.executions
+        @retentions = @records.retentions
+      end
+
+      # A domain operation owns this short transaction. A coordinating parent
+      # can instead call participate with its existing shared scope.
+      def transaction
+        coordinator.atomic do |scope|
+          participate(scope) { |records| yield records, scope }
+        end
+      end
+
+      def participate(scope, &operation)
+        scope.participate(persistence: coordinator, adapter: @record_adapter, &operation)
+      end
+
+      # Authoritative presence only. Failed reads propagate, never mean absent.
+      def exist?(agent_id)
+        assert_observation_thread!
+        agents.load(agent_id)
+        true
+      rescue Phronomy::Persistence::NotFoundError
+        false
+      end
+
+      # Validate the exact requested call and project its authorized batch in
+      # Provider order from one execution snapshot in the caller's transaction.
+      # The receiving domain owns application and replay of these operations.
+      def authorized_operations(scope, agent_id:, execution_id:, invocation_id:, name:, arguments:, names:)
+        participate(scope) do |records|
+          execution = records.executions.load(execution_id)
+          unless execution.agent_id == agent_id
+            raise Phronomy::Persistence::StateConflictError, "Authorized operation owner mismatch"
+          end
+          batch = Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
+          requested = batch.find { |entry| entry.fetch("tool_invocation_id") == invocation_id }
+          unless names.include?(name) && requested && requested.fetch("status") == "authorized" &&
+              requested.fetch("tool_name") == name && authorized_argument_values(requested) == arguments
+            raise Phronomy::Persistence::StateConflictError, "Operation #{invocation_id} is not the authorized call"
+          end
+          batch.filter_map do |entry|
+            next unless entry.fetch("status") == "authorized" && names.include?(entry.fetch("tool_name"))
+            AuthorizedOperation.new(
+              invocation_id: Phronomy::Values::Immutable.copy(entry.fetch("tool_invocation_id")),
+              name: Phronomy::Values::Immutable.copy(entry.fetch("tool_name")),
+              arguments: Phronomy::Values::Immutable.copy(authorized_argument_values(entry))
+            )
+          end.freeze
+        end
+      end
+
+      def result(execution_id)
+        assert_observation_thread!
+        execution = executions.load(execution_id)
+        {
+          execution_id: execution.execution_id, agent_id: execution.agent_id,
+          status: execution.status, phase: execution.phase,
+          result_ref: execution.result_ref, error_ref: execution.error_ref,
+          result: execution.result_ref && contents.fetch_text(execution.result_ref),
+          error: execution.error_ref && contents.fetch_json(execution.error_ref)
+        }.then { |value| Phronomy::Values::Immutable.copy(value) }
+      end
+
+      # Exact, immutable observation. Only authoritative NotFound means absent.
+      def observe_execution(agent_id:, execution_id:, scope: nil)
+        with_scope(scope) do |records|
+          begin
+            execution = records.executions.load(execution_id)
+          rescue Phronomy::Persistence::NotFoundError
+            next ExecutionObservation.new(agent_id: agent_id, execution_id: execution_id,
+              status: :absent, result: nil, error: nil, reservation: nil,
+              transfer_receipt: nil, cancellation_requested: false)
+          end
+          assert_execution_owner!(execution, agent_id)
+          ExecutionObservation.new(agent_id: execution.agent_id, execution_id: execution.execution_id,
+            status: execution.status,
+            result: execution.result_ref && records.contents.fetch_text(execution.result_ref),
+            error: execution.error_ref && Phronomy::Values::Immutable.copy(records.contents.fetch_json(execution.error_ref)),
+            reservation: execution.metadata["reservation"] && ReservedExecution.new(agent_id: agent_id,
+              execution_id: execution_id, correlation: execution.metadata["reservation"]),
+            transfer_receipt: Phronomy::Values::Immutable.copy(execution.metadata["transfer_receipt"]),
+            cancellation_requested: records.cancellations.requested?(agent_id, execution_id) || execution.metadata["cancellation_requested"] == true)
+        end
+      end
+
+      def active_executions(agent_id:, scope: nil)
+        with_scope(scope) do |records|
+          records.executions.list_active(agent_id).map do |execution|
+            observe_execution(agent_id: agent_id, execution_id: execution.execution_id, scope: scope)
+          end.freeze
+        end
+      end
+
+      def definition(agent_id:, scope: nil)
+        with_scope(scope) do |records|
+          root = records.agents.load(agent_id)
+          {id: root.agent_definition_id, version: root.agent_definition_version}.freeze
+        end
+      end
+
+      def knowledge_snapshot(agent_id:, scope: nil)
+        with_scope(scope) do |records|
+          root = records.agents.load(agent_id)
+          journal = records.journals.read(agent_id, limit: root.journal_position)
+          JournalProjection.new(agent_root: root, records: journal).context_records.filter_map do |record|
+            next unless record.kind == :knowledge
+            KnowledgeItem.new(content: records.contents.fetch_text(record.content_ref), metadata: record.metadata)
+          end.freeze
+        end
+      end
+
+      # Participant SPI: opaque extension state, never an AgentExecution getter.
+      def execution_extension(agent_id:, execution_id:, binding_key:, scope: nil)
+        with_scope(scope) do |records|
+          execution = records.executions.load(execution_id)
+          assert_execution_owner!(execution, agent_id)
+          raw = execution.metadata["execution_extension"]
+          next nil unless raw
+          extension = ExecutionExtensionState.from_h(raw)
+          unless extension.binding_key == binding_key
+            raise Phronomy::ConfigurationError, "Execution participant binding mismatch"
+          end
+          extension
+        end
+      end
+
+      # Coordination guards are acquired first by the participant. All Agent
+      # roots then use the same lexical order, including admission and purge.
+      def guard_agents(scope, agent_ids:)
+        participate(scope) { |records| agent_ids.map(&:to_s).uniq.sort.each { |id| records.guard_agent!(id) } }
+        nil
+      end
+
+      # History release is terminal-only and preserves execution/result identity.
+      def remove_execution_extension(agent_id:, execution_id:, binding_key:, scope:)
+        participate(scope) do |records|
+          records.guard_agent!(agent_id)
+          execution = records.executions.load(execution_id)
+          assert_execution_owner!(execution, agent_id)
+          raise Phronomy::AgentBusyError, "Active execution history cannot be released" unless execution.terminal?
+          extension = execution.metadata["execution_extension"]
+          unless extension && extension.fetch("binding_key") == binding_key
+            raise Phronomy::Persistence::StateConflictError, "Extension history identity mismatch"
+          end
+          updated = execution.with(metadata: execution.metadata.except("execution_extension"))
+          records.executions.save(execution_id, expected_revision: execution.execution_revision, execution: updated)
+        end
+        nil
+      end
+
+      def execution_identity(execution_id, scope: nil)
+        with_scope(scope) do |records|
+          execution = records.executions.load(execution_id)
+          ReservedExecution.new(agent_id: execution.agent_id, execution_id: execution.execution_id,
+            correlation: execution.metadata["reservation"])
+        end
+      end
+
+      def retained_references(agent_id:, scope: nil)
+        with_scope(scope) { |records| records.retentions.list(agent_id) }
+      end
+
+      def retain(retention, scope: nil)
+        with_scope(scope) do |records|
+          records.guard_agent!(retention.agent_id)
+          records.agents.load(retention.agent_id)
+          records.retentions.retain(retention)
+        end
+      end
+
+      def release_retention(agent_id:, owner_key:, scope:)
+        participate(scope) { |records| records.retentions.release(agent_id: agent_id, owner_key: owner_key) }
+      end
+
+      def cancellation_requested?(agent_id:, execution_id:, scope: nil)
+        with_scope(scope) { |records| records.cancellations.requested?(agent_id, execution_id) }
+      end
+
+      def request_cancellation(agent_id:, execution_id:, scope: nil)
+        with_scope(scope) do |records|
+          records.guard_agent!(agent_id)
+          begin
+            current = records.executions.load(execution_id)
+          rescue Phronomy::Persistence::NotFoundError
+            next false
+          end
+          assert_execution_owner!(current, agent_id)
+          next false if current.terminal?
+          records.cancellations.request(agent_id, execution_id)
+          true
+        end
+      end
+
+      def runs(agent_id, after: nil, limit: 100)
+        assert_observation_thread!
+        executions.list(agent_id, after: after, limit: limit)
+      end
+
+      # Agent's snapshot fence, independent of any physical schema.
+      def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
+        @records.assert_agent_watermark!(agent_id: agent_id, agent_revision: agent_revision, journal_position: journal_position)
+      end
+
+      private
+
+      def authorized_argument_values(entry)
+        # Unit 6 persists the exact validated snapshot. Older records encoded
+        # legacy raw params, whose explicit optional nil meant omission.
+        entry.key?("validated_arguments") ? entry.fetch("validated_arguments") : entry.fetch("arguments").compact
+      end
+
+      def with_scope(scope, &block)
+        assert_observation_thread!
+        scope ? participate(scope, &block) : transaction(&block)
+      end
+
+      def assert_execution_owner!(execution, agent_id)
+        unless execution.agent_id == agent_id.to_s
+          raise Phronomy::Persistence::StateConflictError, "Execution owner mismatch"
+        end
+      end
+
+      def assert_observation_thread!
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "Durable observation cannot block EventLoop"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/{stream_callback_error.rb → agent/stream_callback_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   # Raised when an Application stream callback fails and
   # +stream_callback_error_policy+ is +:fail_task+.

data/lib/phronomy/agent/{approval_evaluation_request.rb → tool_execution/approval_evaluation_request.rb}

@@ -102,18 +102,7 @@ module Phronomy
       private
 
       def immutable_copy(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, item), result|
-            result[immutable_copy(key)] = immutable_copy(item)
-          end.freeze
-        when Array
-          value.map { |item| immutable_copy(item) }.freeze
-        when String
-          value.dup.freeze
-        else
-          value
-        end
+        Phronomy::Values::Immutable.copy(value)
       end
     end
   end

data/lib/phronomy/agent/{tool_approval_request.rb → tool_execution/tool_approval_request.rb}

@@ -75,16 +75,7 @@ module Phronomy
         private
 
         def immutable_copy(value)
-          case value
-          when Hash
-            value.each_with_object({}) { |(k, v), h| h[immutable_copy(k)] = immutable_copy(v) }.freeze
-          when Array
-            value.map { |v| immutable_copy(v) }.freeze
-          when String
-            value.dup.freeze
-          else
-            value
-          end
+          Phronomy::Values::Immutable.copy(value)
         end
       end
 

data/lib/phronomy/agent/tool_execution/tool_binding.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Builds invocation-independent Tool decorators from explicit Agent settings.
+    # Authorization, execution and Orchestrator context remain with their owners.
+    # @api private
+    class ToolBinding
+      def initialize(tool_class, alias_name:)
+        @tool_class = if alias_name
+          Class.new(tool_class) do
+            tool_name alias_name
+          end
+        else
+          tool_class
+        end
+      end
+
+      def prepare(result_filters:)
+        return @tool_class if result_filters.empty?
+
+        Phronomy::Tool::Operation.with_result_transform(@tool_class) do |result, name, args|
+          result_filters.inject(result) { |value, filter|
+            filter.call(value, tool_name: name, args: args)
+          }
+        end
+      end
+    end
+  end
+end