phronomy 0.32.0 → 0.33.0

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,

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

data/lib/phronomy/tool/schema.rb

@@ -43,19 +43,17 @@ module Phronomy
         unless @json_schema.is_a?(Hash) && @json_schema["type"] == "object"
           raise ArgumentError, "Tool schema must declare an object"
         end
+        @json_schema = Phronomy::Values::Immutable.copy(@json_schema)
         @references = []
         validate_keywords!(@json_schema)
-        options = {ref_resolver: ->(uri) { raise ArgumentError, "external Tool schema reference: #{uri}" }}
-        unless JSONSchemer.valid_schema?(@json_schema, **options)
-          raise ArgumentError, "invalid Tool JSON Schema"
-        end
-        @json_schema = Phronomy::Values::Immutable.copy(@json_schema)
-        @validator = JSONSchemer.schema(@json_schema, **options)
-        @references.each { |reference| @validator.ref(reference) }
-        @references = nil
-        freeze
-      rescue JSONSchemer::InvalidRefPointer, JSONSchemer::InvalidRefResolution => error
-        raise ArgumentError, "invalid local Tool schema reference: #{error.message}"
+        @references.freeze
+        compile_validator!
+      end
+
+      # Build an independent validator from this immutable Tool definition.
+      # @api private
+      def for_tool_instance
+        dup.compile_validator!
       end
 
       # @api public
@@ -99,6 +97,20 @@ module Phronomy
         end
       end
 
+      protected
+
+      def compile_validator!
+        options = {ref_resolver: ->(uri) { raise ArgumentError, "external Tool schema reference: #{uri}" }}
+        unless JSONSchemer.valid_schema?(@json_schema, **options)
+          raise ArgumentError, "invalid Tool JSON Schema"
+        end
+        @validator = JSONSchemer.schema(@json_schema, **options)
+        @references.each { |reference| @validator.ref(reference) }
+        freeze
+      rescue JSONSchemer::InvalidRefPointer, JSONSchemer::InvalidRefResolution => error
+        raise ArgumentError, "invalid local Tool schema reference: #{error.message}"
+      end
+
       private
 
       def error_message(error)

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.32.0"
+  VERSION = "0.33.0"
 end

data/scripts/api_snapshot.rb

@@ -106,9 +106,12 @@ def snapshot_entry(klass)
       "public_class_methods" => (klass.public_methods(false) - BASELINE_CLASS_METHODS).sort
     }
   else
-    internal_context_methods = (klass == Phronomy::InvocationContext) ?
-      %i[__bind_execution __execution_scope] : []
-    instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS - internal_context_methods).sort
+    internal_methods = case klass.name
+    when "Phronomy::InvocationContext" then %i[__bind_execution __execution_scope]
+    when "Phronomy::Tool::Schema" then %i[for_tool_instance]
+    else []
+    end
+    instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS - internal_methods).sort
     internal_class_methods = (klass == Phronomy::Storage::AsyncClient) ? %i[submit] : []
     class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS - internal_class_methods).sort
     {

data/sig/phronomy/agent.rbs

@@ -83,6 +83,7 @@ module Phronomy
       def self.instructions: (?untyped text) { (untyped) -> untyped } -> untyped
                            | (?untyped text) -> untyped
       def self.tools: (?Hash[Class, String?] definitions) -> untyped
+      def self.with_tools: (Hash[Class, String?] definitions, id: String, version: Integer) -> singleton(Base)
       def self.tool_aliases: () -> Hash[Class, String]
       def self.provider: (?Symbol name) -> Symbol?
       def self.temperature: (?Float value) -> Float?

data/sig/phronomy/context.rbs

@@ -110,6 +110,8 @@ module Phronomy
       attr_reader previous_manifest: LLMInputManifest?
       attr_reader metadata: Hash[untyped, untyped]
       def initialize: (agent_id: String, ?execution_id: String?, call_sequence: Integer, call_mode: Symbol, ?instruction: Array[InstructionItem], ?knowledge: Array[KnowledgeItem], ?tools: Array[ToolItem], ?conversation: Array[Array[ConversationItem]], token_budget: untyped, ?model_config: Hash[untyped, untyped], previous_manifest: LLMInputManifest?, ?metadata: Hash[untyped, untyped]) -> void
+      def input_token_limit: () -> Integer?
+      def with_input_token_limit: (Integer limit) -> ContextPolicyInput
     end
 
     class ContextPlan
@@ -124,6 +126,7 @@ module Phronomy
     class ContextPolicy
       def call: (ContextPolicyInput input) -> ContextPlan
 
+      def estimate_tokens: (untyped content) -> Integer
       def instruction_item: (content: untyped, ?role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?required: bool, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::InstructionItem
       def knowledge_item: (content: untyped, ?role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?required: bool, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::KnowledgeItem
       def conversation_item: (content: untyped, role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?sequence: Integer?, ?required: bool, ?tool_call_id: String?, ?tool_call_ids: Array[String], ?delivery: Symbol, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::ConversationItem

data/sig/phronomy/multi_agent.rbs

@@ -1,6 +1,29 @@
 module Phronomy
   module MultiAgent
     class SharedState
+      interface _SharingTools
+        def call: (member: singleton(::Phronomy::Agent::Base), cycle: Integer) -> Hash[singleton(::Phronomy::Tool::Base), untyped]
+      end
+
+      interface _SharingProvider
+        def open: (input: untyped, config: Hash[Symbol, untyped]) { (Binding) -> untyped } -> untyped
+      end
+
+      class Binding
+        def self.new: (store: untyped, tools: _SharingTools) -> instance
+        attr_reader store: untyped
+        def tool_definitions: (member: singleton(::Phronomy::Agent::Base), cycle: Integer) -> Hash[singleton(::Phronomy::Tool::Base), String?]
+      end
+
+      class MemberLifecycleError < ::Phronomy::Error
+        attr_reader agent: ::Phronomy::Agent::Base
+        attr_reader result: untyped
+        attr_reader reason: Symbol
+        attr_reader primary_error: Exception?
+        attr_reader release_error: Exception?
+        def self.new: (agent: ::Phronomy::Agent::Base, result: untyped, reason: Symbol, ?primary_error: Exception?, ?release_error: Exception?) -> instance
+      end
+
       class KnowledgeStore
         def self.new: () -> instance
         def read_all: () -> Array[Hash[Symbol, untyped]]
@@ -13,8 +36,9 @@ module Phronomy
       def self.coordination: (?untyped text) -> untyped
       def self.max_cycles: (?untyped value) -> Integer?
       def self.timeout: (?untyped value) -> Float?
-      def self.terminate_when: () ?{ (KnowledgeStore) -> untyped } -> untyped
-      def self.aggregate: () ?{ (KnowledgeStore) -> untyped } -> untyped
+      def self.terminate_when: () ?{ (untyped) -> untyped } -> untyped
+      def self.aggregate: () ?{ (untyped) -> untyped } -> untyped
+      def self.sharing: (_SharingProvider provider, id: String, version: Integer) -> Hash[Symbol, untyped]
       def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
     end
 

data/sig/phronomy/tool.rbs

@@ -55,6 +55,7 @@ module Phronomy
       def requires_approval?: () -> untyped
       def tool_origin: () -> Symbol
       def approval_metadata: () -> Hash[untyped, untyped]
+      def approval_display: (arguments: Hash[String | Symbol, untyped], facts: Hash[untyped, untyped]) -> { arguments: Hash[String | Symbol, untyped], facts: Hash[untyped, untyped] }
       def execute: (**untyped args) -> untyped
 
       private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.33.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-11-03 00:00:00.000000000 Z
+date: 2026-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -257,6 +257,7 @@ files:
 - docs/archive/design/historical/06_design_decisions.md
 - docs/async-composition.md
 - docs/changelog/0.14-and-earlier.md
+- docs/context-policy-budgeting.md
 - docs/decisions/001-rubyllm-as-provider-layer.md
 - docs/decisions/002-workflow-context-immutability.md
 - docs/decisions/003-event-loop-singleton.md
@@ -333,6 +334,7 @@ files:
 - docs/design/durable-semantic-coordination/IMPLEMENTATION_REPORT.md
 - docs/design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md
 - docs/design/durable-semantic-coordination/RESPONSIBILITY_BOUNDARY_REVIEW.md
+- docs/examples/shared_state_custom_sharing.rb
 - docs/execution-boundaries-preview.md
 - docs/failure-reason-codes.md
 - docs/features.md
@@ -376,6 +378,7 @@ files:
 - docs/ordered-event-delivery.md
 - docs/persistence-backends.md
 - docs/runtime-and-concurrency.md
+- docs/shared-state-sharing.md
 - docs/workflow-completion.md
 - examples/README.md
 - gemfiles/http_minimum.gemfile
@@ -616,6 +619,8 @@ files:
 - lib/phronomy/multi_agent/reserved_child_admission.rb
 - lib/phronomy/multi_agent/runtime_binding/engine_environment.rb
 - lib/phronomy/multi_agent/shared_state.rb
+- lib/phronomy/multi_agent/shared_state/binding.rb
+- lib/phronomy/multi_agent/shared_state/member_lifecycle_error.rb
 - lib/phronomy/multi_agent/store.rb
 - lib/phronomy/multi_agent/team_busy_error.rb
 - lib/phronomy/multi_agent/team_coordinator.rb