phronomy 0.32.0 → 0.34.0

data/lib/phronomy/agent/lifecycle/hosted_invocation.rb

@@ -37,15 +37,12 @@ module Phronomy
         unless wait && wait.approval_request_id == approval_request_id
           raise Phronomy::AgentBusyError, "No matching hosted approval wait"
         end
-        completion = Phronomy::TaskResult.deferred(name: "detach-hosted-approval")
         owner = @environment.registry.agent_execution_owner(execution_id)
         unless owner && (child ? owner.agent.persistence.equal?(@agent.persistence) : owner.agent.equal?(@agent))
           raise Phronomy::AgentBusyError, "Hosted execution has no matching local owner"
         end
-        command = ExecutionCoordinator::DetachHostedWait.new(coordinator: owner.coordinator, wait: wait,
-          task: (child && !@resumed_from) ? nil : @task, parent: child ? @agent : nil, completion: completion)
-        accepted = @environment.registry.post(command, completion: completion)
-        raise Phronomy::RuntimeShutdownError, "EventLoop rejected hosted detach" unless accepted
+        completion = owner.coordinator.request_hosted_detach(wait,
+          task: (child && !@resumed_from) ? nil : @task, parent: child ? @agent : nil)
         completion.wait_result
       end
 

data/lib/phronomy/agent/recovery/recovery_rules.rb

@@ -88,18 +88,6 @@ module Phronomy
         normalized.freeze
       end
 
-      def subject_key(subject)
-        normalized = normalize_subject(subject)
-        case normalized.fetch(:type)
-        when :llm_call
-          "llm_call:#{normalized.fetch(:llm_call_id)}"
-        when :tool_invocation
-          "tool_invocation:#{normalized.fetch(:tool_invocation_id)}"
-        when :persistence_operation
-          "persistence_operation:#{normalized.fetch(:entity)}"
-        end
-      end
-
       def subject_equal?(left, right)
         normalize_subject(left) == normalize_subject(right)
       rescue ArgumentError, KeyError

data/lib/phronomy/agent/store.rb

@@ -48,6 +48,7 @@ module Phronomy
 
       # Validate the exact requested call and project its authorized batch in
       # Provider order from one execution snapshot in the caller's transaction.
+      # Only the validated dispatch snapshot is authorization evidence.
       # 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|
@@ -58,7 +59,7 @@ module Phronomy
           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
+              requested.fetch("tool_name") == name && requested.fetch("validated_arguments") == arguments
             raise Phronomy::Persistence::StateConflictError, "Operation #{invocation_id} is not the authorized call"
           end
           batch.filter_map do |entry|
@@ -66,7 +67,7 @@ module Phronomy
             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))
+              arguments: Phronomy::Values::Immutable.copy(entry.fetch("validated_arguments"))
             )
           end.freeze
         end
@@ -286,12 +287,6 @@ module Phronomy
           Phronomy::Values::Immutable.json(contents.fetch_json(execution.result_ref)) : contents.fetch_text(execution.result_ref)
       end
 
-      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)

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

@@ -101,12 +101,13 @@ module Phronomy
       end
 
       def self.build_item(invocation)
+        display = invocation.approval_display
         Item.new(
           tool_invocation_id: invocation.id,
           tool_call_id: invocation.tool_call_id,
           tool_name: invocation.tool_name,
-          arguments: invocation.display_arguments,
-          facts: invocation.display_facts,
+          arguments: display.fetch(:arguments),
+          facts: display.fetch(:facts),
           reason: invocation.authorization_reason,
           origin: invocation.origin,
           metadata: invocation.metadata

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

@@ -333,12 +333,16 @@ module Phronomy
         @tool&.respond_to?(:parameters_schema) ? @tool.parameters_schema : {}
       end
 
-      def display_arguments
-        redact_for_display(@arguments || @raw_arguments)
-      end
+      # The approval Item snapshots these fields at its own construction boundary.
+      # @api private
+      def approval_display
+        return {arguments: {}.freeze, facts: {}.freeze}.freeze unless @tool&.respond_to?(:approval_display)
 
-      def display_facts
-        redact_value(@facts, sensitive_argument_values)
+        display = @tool.approval_display(arguments: @arguments || @raw_arguments, facts: @facts)
+        unless Hash === display && Hash === display.fetch(:arguments, nil) && Hash === display.fetch(:facts, nil)
+          raise Phronomy::ConfigurationError, "Tool approval_display must return :arguments and :facts Hashes"
+        end
+        display
       end
 
       private
@@ -544,37 +548,6 @@ module Phronomy
       def immutable_copy(value)
         Phronomy::Values::Immutable.copy(value)
       end
-
-      def redact_for_display(value)
-        if @tool&.respond_to?(:redacted_args, true)
-          immutable_copy(@tool.send(:redacted_args, value || {}))
-        else
-          immutable_copy(value || {})
-        end
-      end
-
-      def sensitive_argument_values
-        return [] unless @tool&.class&.respond_to?(:redact_params)
-        normalized = (@arguments || @raw_arguments || {}).transform_keys(&:to_sym)
-        @tool.class.redact_params.filter_map { |name| normalized[name] }
-      end
-
-      def redact_value(value, sensitive_values)
-        return "[REDACTED]" if sensitive_values.any? { |sensitive| sensitive == value }
-
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, item), result|
-            result[key] = redact_value(item, sensitive_values)
-          end.freeze
-        when Array
-          value.map { |item| redact_value(item, sensitive_values) }.freeze
-        when String
-          "[REDACTED]"
-        else
-          value
-        end
-      end
     end
   end
 end

data/lib/phronomy/context/context_policy.rb

@@ -11,6 +11,16 @@ module Phronomy
 
       protected
 
+      # Uses the same canonical representation and estimator as generated Policy
+      # items. Estimates are planning values, not a model tokenizer guarantee.
+      # @param content [Object] text or JSON-serializable content
+      # @return [Integer] estimated token count
+      # @api public
+      def estimate_tokens(content)
+        bytes = content.is_a?(String) ? content : Phronomy::CanonicalJSON.dump(content)
+        Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
+      end
+
       def instruction_item(
         content:,
         role: :system,
@@ -25,7 +35,7 @@ module Phronomy
           role: role,
           content: content,
           content_format: content_format || inferred_content_format(content),
-          estimated_tokens: estimate_content(content),
+          estimated_tokens: estimate_tokens(content),
           required: required,
           provenance: generated_provenance,
           metadata: metadata
@@ -46,7 +56,7 @@ module Phronomy
           role: role,
           content: content,
           content_format: content_format || inferred_content_format(content),
-          estimated_tokens: estimate_content(content),
+          estimated_tokens: estimate_tokens(content),
           required: required,
           provenance: generated_provenance,
           metadata: metadata
@@ -72,7 +82,7 @@ module Phronomy
           content: content,
           content_format: content_format || inferred_content_format(content),
           sequence: sequence,
-          estimated_tokens: estimate_content(content),
+          estimated_tokens: estimate_tokens(content),
           required: required,
           provenance: generated_provenance,
           tool_call_id: tool_call_id,
@@ -111,11 +121,6 @@ module Phronomy
       def inferred_content_format(content)
         content.is_a?(String) ? :text : :json
       end
-
-      def estimate_content(content)
-        bytes = content.is_a?(String) ? content : Phronomy::CanonicalJSON.dump(content)
-        Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
-      end
     end
   end
 end

data/lib/phronomy/context/context_policy_input.rb

@@ -56,6 +56,32 @@ module Phronomy
         freeze
       end
 
+      # Reports the input limit supplied to this Policy without exposing the
+      # framework's budget representation. Unknown capability remains nil.
+      # @return [Integer, nil]
+      # @api public
+      def input_token_limit
+        token_budget&.effective_input_limit
+      end
+
+      # Returns a selection input with an application limit. A known limit may
+      # only be retained or reduced. An unknown limit accepts an explicit cap
+      # without asserting that the model can accept that many tokens.
+      # @param limit [Integer] positive selection limit
+      # @return [ContextPolicyInput]
+      # @raise [ArgumentError] for an invalid limit or a known-limit increase
+      # @api public
+      def with_input_token_limit(limit)
+        unless limit.is_a?(Integer) && limit.positive?
+          raise ArgumentError, "input token limit must be a positive Integer"
+        end
+        if input_token_limit && limit > input_token_limit
+          raise ArgumentError, "input token limit must not exceed the current limit"
+        end
+
+        with(token_budget: Phronomy::LlmContextWindow::TokenBudget.new(max_input_tokens: limit))
+      end
+
       private
 
       def validate_items!(items, expected_class, label)

data/lib/phronomy/context/llm_input_manifest.rb

@@ -149,9 +149,9 @@ module Phronomy
         freeze
       end
 
-      # Current-format-only durable decoder. Historical format conversion is an
-      # explicit migration operation and is never attempted here. Unlike the
-      # Ruby construction API, this decoder never coerces durable field types.
+      # Current-format-only durable decoder. Historical versions are rejected.
+      # Unlike the Ruby construction API, this decoder never coerces durable
+      # field types.
       def self.from_h(hash)
         source = strict_source!(
           hash,

data/lib/phronomy/engine/runtime/shutdown_result.rb

@@ -52,11 +52,6 @@ module Phronomy
           %i[not_started terminated].include?(@event_loop_status) &&
           @task_registry_status == :empty
       end
-
-      # Runtime reset is safe when cleanup completed, even if execution failed.
-      def success?
-        cleanup_complete?
-      end
     end
   end
 end

data/lib/phronomy/execution/execution.rb

@@ -127,22 +127,11 @@ module Phronomy
       observed
     end
 
-    # Scope/admission hooks shared with framework-owned operations.
-    # @api private
-    def __while_open(&block)
-      @scope.__while_open(&block)
-    end
-
     # @api private
     def __open?
       @scope.__open?
     end
 
-    # @api private
-    def __cancellation_token
-      @token
-    end
-
     # @api private
     def __cancellation_error
       @scope.__cancellation_error

data/lib/phronomy/multi_agent/shared_state/binding.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    class SharedState
+      # Connects one application's shared data to the Tools offered to members.
+      # The application owns the store's shape, operations and resource lifetime.
+      # @api public
+      class Binding
+        # @param store [Object] opaque application data passed to coordination callbacks
+        # @param tools [#call] builder accepting member: (Agent class) and cycle:
+        # @api public
+        def initialize(store:, tools:)
+          raise ArgumentError, "sharing tools must respond to call" unless tools.respond_to?(:call)
+
+          @store = store
+          @tools = tools
+          freeze
+        end
+
+        # @api public
+        attr_reader :store
+
+        # Build invocation-bound Tools using the existing Agent.tools declaration shape.
+        # The builder receives the registered Agent class, not an Agent instance.
+        # @return [Hash<Class, String, nil>] Tool classes mapped to aliases or nil
+        # @api public
+        def tool_definitions(member:, cycle:)
+          definitions = @tools.call(member: member, cycle: cycle)
+          unless definitions.is_a?(Hash)
+            raise ArgumentError, "sharing tools must return a Hash of ToolClass => alias_or_nil"
+          end
+
+          definitions.to_h do |tool_class, alias_name|
+            unless tool_class.is_a?(Class) && tool_class <= Phronomy::Tool::Base
+              raise ArgumentError, "sharing tools must contain Phronomy::Tool::Base classes"
+            end
+            [tool_class, alias_name&.to_s&.dup&.freeze]
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/shared_state/member_lifecycle_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    class SharedState
+      # Keeps the member handle when invocation-scoped sharing cannot finish safely.
+      # Callers choose approval, cancellation or release through existing Agent APIs.
+      # @api public
+      class MemberLifecycleError < Phronomy::Error
+        # @api public
+        attr_reader :agent, :result, :reason, :primary_error, :release_error
+
+        # The live Agent and application resources are process-local, not a
+        # durable recipe for rebuilding the sharing provider or its Tools.
+        # @api public
+        def initialize(agent:, result:, reason:, primary_error: nil, release_error: nil)
+          @agent = agent
+          @result = result
+          @reason = reason
+          @primary_error = primary_error
+          @release_error = release_error
+          message = if reason == :suspended
+            "SharedState sharing cannot complete while a member is suspended"
+          else
+            "SharedState sharing could not release a member: #{release_error&.message}"
+          end
+          super(message)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/shared_state.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Phronomy
   module MultiAgent
-    # Implements peer coordination through an invocation-local KnowledgeStore.
+    # Coordinates members through default findings or application-defined shared data.
     # @api public
     class SharedState
       # Semantic revision of the framework-owned SharedState instrumentation
@@ -70,6 +72,29 @@ module Phronomy
           block ? @aggregator = block : @aggregator
         end
 
+        # Declare application-owned sharing for each invocation. The provider's
+        # open(input:, config:) method must synchronously yield one Binding.
+        # Its block scope owns any connection or other application resource.
+        # Increment version when the shared Tool schemas or meanings change.
+        # @param provider [#open]
+        # @param id [String] stable application sharing definition identity
+        # @param version [Integer] positive sharing definition revision
+        # @api public
+        def sharing(provider, id:, version:)
+          raise ArgumentError, "sharing provider must respond to open" unless provider.respond_to?(:open)
+          unless id.is_a?(String) && !id.strip.empty?
+            raise ArgumentError, "sharing id must be a nonempty String"
+          end
+          unless version.is_a?(Integer) && version.positive?
+            raise ArgumentError, "sharing version must be a positive Integer"
+          end
+
+          @sharing = {provider: provider, id: id.dup.freeze, version: version}.freeze
+        end
+
+        # @api private
+        def _sharing = @sharing
+
         def _members = Array(@members)
         def _coordination = @coordination
         def _max_cycles = @max_cycles
@@ -81,6 +106,8 @@ module Phronomy
       # @api public
       def invoke(input, config: {})
         validate_termination!
+        return invoke_with_sharing(input, config, self.class._sharing) if self.class._sharing
+
         store = KnowledgeStore.new
         cycles, terminated_by = coordinate_members(input, store)
 
@@ -97,7 +124,11 @@ module Phronomy
         cycle_limit = max_cycles || Float::INFINITY
 
         (1..cycle_limit).each do |cycle|
-          invoke_members(input, store, cycle)
+          if block_given?
+            yield cycle
+          else
+            invoke_members(input, store, cycle)
+          end
           completed_cycles = cycle
 
           if self.class._terminate_when&.call(store)
@@ -137,6 +168,120 @@ module Phronomy
           "max_cycles or timeout must be configured before invoking SharedState"
       end
 
+      def invoke_with_sharing(input, config, sharing)
+        unless self.class._aggregator
+          raise ArgumentError, "aggregate must be configured when sharing is configured"
+        end
+
+        open_sharing(sharing, input, config) do |binding|
+          cycles, terminated_by = coordinate_members(input, binding.store) do |cycle|
+            invoke_shared_members(input, binding, cycle, sharing)
+          end
+          {output: aggregate_findings(binding.store), cycles: cycles, terminated_by: terminated_by}
+        end
+      end
+
+      def open_sharing(sharing, input, config)
+        opening_thread = Thread.current
+        active = true
+        entered = completed = false
+        result = callback_error = nil
+
+        sharing.fetch(:provider).open(input: input, config: config) do |binding|
+          unless active && Thread.current.equal?(opening_thread)
+            raise ArgumentError, "sharing provider must yield synchronously within open"
+          end
+          raise ArgumentError, "sharing provider must yield exactly once" if entered
+
+          entered = true
+          unless binding.is_a?(Binding)
+            raise ArgumentError, "sharing provider must yield a SharedState::Binding"
+          end
+
+          result = yield binding
+          completed = true
+        rescue => error
+          callback_error = error
+          raise
+        end
+
+        raise callback_error if callback_error
+        unless entered && completed
+          raise ArgumentError, "sharing provider must yield exactly once and complete the block"
+        end
+
+        result
+      ensure
+        active = false
+      end
+
+      def invoke_shared_members(input, binding, cycle, sharing)
+        self.class._members.each do |member_config|
+          member = member_config.fetch(:klass)
+          definitions = shared_tool_definitions(member, binding, cycle)
+          instrumented = build_shared_researcher(member, definitions, sharing)
+          prompt = shared_prompt(input, member_config[:instruction])
+          invoke_shared_researcher(instrumented, prompt)
+        end
+      end
+
+      def invoke_shared_researcher(instrumented, prompt)
+        agent = instrumented.new
+        suspended = false
+        result = agent.invoke(prompt)
+        if result.is_a?(Hash) && result[:suspended]
+          suspended = true
+          raise MemberLifecycleError.new(agent: agent, result: result, reason: :suspended)
+        end
+        result
+      ensure
+        release_shared_member(agent, result, $!) if agent && !suspended
+      end
+
+      def release_shared_member(agent, result, primary_error)
+        agent.unload!
+      rescue => release_error
+        error = MemberLifecycleError.new(agent: agent, result: result, reason: :release_failed,
+          primary_error: primary_error, release_error: release_error)
+        raise error, cause: primary_error || release_error
+      end
+
+      def shared_tool_definitions(member, binding, cycle)
+        definitions = member.tools.to_h { |tool| [tool, member.tool_aliases[tool]] }
+        added = binding.tool_definitions(member: member, cycle: cycle)
+        unless (definitions.keys & added.keys).empty?
+          raise ArgumentError, "sharing Tool classes must not replace member Tools"
+        end
+
+        definitions = definitions.merge(added)
+        names = definitions.map { |tool, alias_name| (alias_name || tool.tool_name).to_s }
+        if names.any?(&:empty?) || names.uniq.length != names.length
+          raise ArgumentError, "sharing and member Tools must have distinct nonempty names or aliases"
+        end
+        definitions
+      end
+
+      def build_shared_researcher(member, definitions, sharing)
+        definition = shared_definition_for(member, sharing)
+        member.with_tools(definitions, id: definition.fetch(:id), version: definition.fetch(:version))
+      end
+
+      def shared_definition_for(member, sharing)
+        parent = member.agent_definition
+        identity = [parent.fetch(:id), parent.fetch(:version), sharing.fetch(:id), sharing.fetch(:version)]
+        digest = Digest::SHA256.hexdigest(Phronomy::CanonicalJSON.dump(identity))
+        {id: "Phronomy::MultiAgent::SharedState::Application/#{digest}", version: 1}
+      end
+
+      def shared_prompt(input, instruction)
+        guide = self.class._coordination ||
+          "Use the provided Tools to collaborate through the application's shared data."
+        parts = [guide]
+        parts << "\nYour specific focus for this session: #{instruction}" if instruction
+        parts << "\n\nTask: #{input}"
+        parts.join
+      end
+
       def invoke_researcher(
         researcher_class,
         store,
@@ -178,14 +323,11 @@ module Phronomy
         # application's definition-version namespace independent from framework
         # instrumentation.
         instrumented_def = instrumented_definition_for(researcher_class)
-        Class.new(researcher_class) do
-          model researcher_class.model
-          agent_definition(
-            id: instrumented_def.fetch(:id),
-            version: instrumented_def.fetch(:version)
-          )
-          tools(definitions)
-        end
+        researcher_class.with_tools(
+          definitions,
+          id: instrumented_def.fetch(:id),
+          version: instrumented_def.fetch(:version)
+        )
       end
 
       def build_read_tool(store)

data/lib/phronomy/tool/base.rb

@@ -363,10 +363,17 @@ module Phronomy
       # @api public
       def validate_arguments(args)
         schema = parameters_schema
-        if !@validation_schema || @validation_schema.json_schema != schema
-          @validation_schema = Schema.new(schema)
+        validator = @validation_schema
+        if !validator || validator.json_schema != schema
+          declaration = self.class.parameters_schema_definition
+          validator = if Schema === declaration && declaration.instance_of?(Schema) && declaration.json_schema.equal?(schema)
+            declaration.for_tool_instance
+          else
+            Schema.new(schema)
+          end
+          @validation_schema = validator
         end
-        values, error = @validation_schema.validate(args || {}, coerce: self.class.on_schema_error == :coerce)
+        values, error = validator.validate(args || {}, coerce: self.class.on_schema_error == :coerce)
         if values && !self.class.parameters_schema_definition
           # Legacy optional param nil means omission, preserving Ruby defaults.
           self.class.declared_parameters.each do |name, parameter|
@@ -442,6 +449,24 @@ module Phronomy
         {}
       end
 
+      # Selects the arguments and policy facts that may appear in a human approval
+      # request. Arguments may be raw or validated. This does not change either input.
+      # @api public
+      def approval_display(arguments:, facts:)
+        sensitive = arguments.transform_keys(&:to_sym).slice(*self.class.redact_params).values
+        indexed = {}
+        sensitive.each do |value|
+          if Hash === value || Array === value
+            approval_comparison_key(value) { |key| indexed[key] = true }
+          end
+        end
+        display_facts = redact_approval_fact(facts) do |value|
+          sensitive_fact_value?(value, sensitive) || (!indexed.empty? && indexed.key?(approval_comparison_key(value)))
+        end
+        # If the entire facts Hash matches a sensitive argument, hide all of its keys.
+        {arguments: redacted_args(arguments), facts: display_facts.is_a?(Hash) ? display_facts : {}}
+      end
+
       # @api public
       def execute(**_args)
         raise NotImplementedError, "#{self.class}#execute is not implemented"
@@ -536,6 +561,47 @@ module Phronomy
         end
       end
 
+      # Index each sensitive subtree and scalar once. Object member names describe
+      # structure; its member values and array elements can be copied into facts.
+      def approval_comparison_key(value, &index)
+        key = case value
+        when Hash then value.transform_values { |item| approval_comparison_key(item, &index) }
+        when Array then value.map { |item| approval_comparison_key(item, &index) }
+        when Symbol then value.to_s
+        when Float then (value.finite? && value == value.to_i) ? value.to_i : value
+        else value
+        end
+        index&.call(key)
+        key
+      end
+
+      def sensitive_fact_value?(value, sensitive_values)
+        sensitive_values.any? do |sensitive|
+          sensitive == value ||
+            (Symbol === value && value.to_s == sensitive) ||
+            (Symbol === sensitive && sensitive.to_s == value)
+        end
+      end
+
+      def redact_approval_fact(value, &sensitive)
+        return "[REDACTED]" if sensitive.call(value)
+
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), result|
+            next if sensitive.call(key)
+
+            result[key] = redact_approval_fact(item, &sensitive)
+          end.freeze
+        when Array
+          value.map { |item| redact_approval_fact(item, &sensitive) }.freeze
+        when String
+          "[REDACTED]"
+        else
+          value
+        end
+      end
+
       def nested_schema_to_json_schema(nested)
         nested.each_with_object({}) do |(prop_name, spec), result|
           type = spec[:type].to_s