phronomy 0.15.1 → 0.17.0

data/lib/phronomy/canonical_json.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Phronomy
+  # Phronomy Canonical JSON v1.
+  #
+  # v1 accepts JSON-native values only, orders object names by UTF-16 code
+  # units, and emits ECMAScript/JCS-compatible number forms for IEEE-754
+  # doubles. Ruby-specific and non-interoperable numeric values must be
+  # converted by a domain codec before serialization.
+  class CanonicalJSON
+    VERSION = 1
+    MAX_SAFE_INTEGER = 9_007_199_254_740_991
+
+    class << self
+      def dump(value)
+        serialize(value)
+      end
+
+      def load(bytes)
+        JSON.parse(bytes)
+      end
+
+      private
+
+      def serialize(value)
+        case value
+        when Hash
+          serialize_hash(value)
+        when Array
+          "[#{value.map { |child| serialize(child) }.join(",")}]"
+        when String
+          JSON.generate(ensure_utf8(value))
+        when Integer
+          serialize_integer(value)
+        when Float
+          serialize_float(value)
+        when TrueClass then "true"
+        when FalseClass then "false"
+        when NilClass then "null"
+        else
+          raise ArgumentError,
+            "unsupported Phronomy Canonical JSON v1 value: #{value.class}"
+        end
+      end
+
+      def serialize_hash(value)
+        normalized = {}
+        value.each do |key, child|
+          unless key.is_a?(String)
+            raise ArgumentError,
+              "canonical JSON object keys must be String, got #{key.class}"
+          end
+          canonical_key = ensure_utf8(key)
+          if normalized.key?(canonical_key)
+            raise ArgumentError,
+              "duplicate canonical JSON key: #{canonical_key.inspect}"
+          end
+          normalized[canonical_key] = child
+        end
+
+        members = normalized.sort_by { |key, _| utf16_sort_key(key) }.map do |key, child|
+          "#{JSON.generate(key)}:#{serialize(child)}"
+        end
+        "{#{members.join(",")}}"
+      end
+
+      def serialize_integer(value)
+        if value.abs > MAX_SAFE_INTEGER
+          raise ArgumentError,
+            "integer exceeds canonical JSON safe range; encode it as a String: #{value}"
+        end
+        value.to_s
+      end
+
+      def serialize_float(value)
+        raise ArgumentError, "non-finite number is not canonical JSON" unless value.finite?
+        raise ArgumentError, "-0.0 is not canonical JSON v1" if negative_zero?(value)
+        return "0" if value.zero?
+
+        raw = value.to_s.downcase
+        return normalize_plain_decimal(raw) unless raw.include?("e")
+
+        sign = raw.start_with?("-") ? "-" : ""
+        raw = raw.delete_prefix("-")
+        mantissa, exponent_text = raw.split("e", 2)
+        exponent = Integer(exponent_text, 10)
+        integer_part, fractional_part = mantissa.split(".", 2)
+        fractional_part ||= ""
+        digits = (integer_part + fractional_part).sub(/0+\z/, "")
+        digits = "0" if digits.empty?
+        decimal_position = integer_part.length + exponent
+
+        body = if decimal_position > 0 && decimal_position <= 21
+          if decimal_position >= digits.length
+            digits + ("0" * (decimal_position - digits.length))
+          else
+            "#{digits[0, decimal_position]}.#{digits[decimal_position..]}"
+          end
+        elsif decimal_position <= 0 && decimal_position > -6
+          "0.#{"0" * -decimal_position}#{digits}"
+        else
+          scientific_exponent = decimal_position - 1
+          fraction = digits[1..]
+          coefficient = (fraction.nil? || fraction.empty?) ? digits[0] : "#{digits[0]}.#{fraction}"
+          exponent_sign = scientific_exponent.negative? ? "" : "+"
+          "#{coefficient}e#{exponent_sign}#{scientific_exponent}"
+        end
+        "#{sign}#{body}"
+      end
+
+      def normalize_plain_decimal(raw)
+        raw = raw.delete_suffix(".0")
+        (raw == "-0") ? "0" : raw
+      end
+
+      def negative_zero?(value)
+        value.zero? && (1.0 / value).negative?
+      end
+
+      def utf16_sort_key(value)
+        value.encode(Encoding::UTF_16BE).bytes
+      end
+
+      def ensure_utf8(value)
+        text = value.dup.encode(Encoding::UTF_8)
+        raise ArgumentError, "invalid UTF-8 string" unless text.valid_encoding?
+
+        text
+      rescue EncodingError => error
+        raise ArgumentError, "invalid UTF-8 string: #{error.message}"
+      end
+    end
+  end
+end

data/lib/phronomy/configuration.rb

@@ -3,186 +3,36 @@
 module Phronomy
   # Holds global configuration for the entire framework.
   # Configure via the Phronomy.configure block.
-  #
-  # @example
-  #   Phronomy.configure do |config|
-  #     config.default_model    = "claude-3-5-sonnet-20241022"
-  #     config.recursion_limit  = 50
-  #   end
   class Configuration
     STREAM_CALLBACK_ERROR_POLICIES = %i[report fail_task].freeze
-    private_constant :STREAM_CALLBACK_ERROR_POLICIES
+    RUNTIME_BACKENDS = %i[thread immediate fiber].freeze
+    private_constant :STREAM_CALLBACK_ERROR_POLICIES, :RUNTIME_BACKENDS
 
-    # Default LLM model name (nil delegates to RubyLLM default)
     attr_accessor :default_model
-
-    # Default embedding model name
     attr_accessor :default_embedding_model
-
-    # Tracer instance
     attr_accessor :tracer
-
-    # Global before_completion hook callable (Proc / lambda).
-    # Called before every LLM request across all agents.
-    # Receives a {Phronomy::Agent::BeforeCompletionContext}; must return a Hash
-    # of params to merge, or nil to pass through unchanged.
-    attr_accessor :before_completion
-
-    # Recursion limit for graph execution (default: 25)
+    attr_accessor :before_llm_input
+    attr_accessor :default_output_reserve
     attr_accessor :recursion_limit
-
-    # When true, agent LLM calls use {Phronomy::MultiAgent::ParallelToolChat}
-    # for concurrent tool dispatch within a single agent turn.
-    # Defaults to false.
-    #
-    # Previously, this was automatically enabled when +event_loop+ was true.
-    # As of Phase 3, +parallel_tool_execution+ is a separate setting that must
-    # be explicitly enabled.
-    # @example
-    #   Phronomy.configure { |c| c.parallel_tool_execution = true }
-    # @return [Boolean]
     attr_accessor :parallel_tool_execution
-
-    # When true, user input and LLM output are recorded in trace spans.
-    # Defaults to false; set to true only in environments where PII capture is acceptable.
-    # Set to false in privacy-sensitive environments to prevent PII from reaching
-    # the tracing backend (OTel, Langfuse, etc.).
     attr_accessor :trace_pii
-
-    # Optional logger for framework diagnostic messages (e.g. unreachable-state warnings).
-    # Must respond to +#warn(message)+.  When nil (default), messages are written to +$stderr+
-    # via +Kernel#warn+.
-    # @example
-    #   Phronomy.configure { |c| c.logger = Rails.logger }
     attr_accessor :logger
-
-    # Grace period (in seconds) before the EventLoop background thread is force-killed
-    # after a cooperative stop request.  Applies both to the overall thread join
-    # and to the drain-and-cancel phase when +stop(drain: true)+ is used.
-    # Default: 5 seconds.
-    # @see Phronomy::EventLoop#stop
     attr_accessor :event_loop_stop_grace_seconds
-
-    # Global state store for workflow persistence.
-    # When set, WorkflowRunner routes all state reads and writes through this store.
-    # Must be an instance of a class that inherits from Phronomy::StateStore::Base.
-    # Defaults to +nil+ (no persistence — state lives only for the duration of invoke).
-    # @example
-    #   Phronomy.configure { |c| c.state_store = Phronomy::StateStore::InMemory.new }
     attr_accessor :state_store
-
-    # Maximum byte length of a tool result returned to the LLM.
-    # When a tool returns a String longer than this limit, the string is truncated
-    # and a warning is logged.  Set to +nil+ (default) to disable truncation.
-    # @example
-    #   Phronomy.configure { |c| c.tool_result_max_size = 8192 }
     attr_accessor :tool_result_max_size
-
-    # LLM adapter used by Agent::Base to perform LLM calls.
-    # Must be an instance of a class that inherits from
-    # {Phronomy::LLMAdapter::Base}.  Defaults to
-    # {Phronomy::LLMAdapter::RubyLLM} which delegates to +chat.ask+ via
-    # {BlockingAdapterPool}.
-    # Set to a custom adapter to swap in an alternative LLM client without
-    # changing any agent code.
-    # @example
-    #   Phronomy.configure { |c| c.llm_adapter = MyAsyncLLMAdapter.new }
     attr_accessor :llm_adapter
-
-    # Set to +nil+ to disable the warning.
-    # @return [Numeric, nil]
     attr_accessor :event_loop_starvation_threshold_seconds
-
-    # Warn when processing a single event on the EventLoop thread takes longer
-    # than this many seconds (long-running task / blocking-on-loop detection).
-    # Set to +nil+ to disable the warning.
-    # @return [Numeric, nil]
     attr_accessor :event_loop_dispatch_threshold_seconds
-
-    # When true, enables all blocking operation diagnostics (Issue #279).
-    # Equivalent to setting all diagnostic thresholds to their defaults.
-    # @return [Boolean]
     attr_accessor :scheduler_debug
-
-    # Wall-clock threshold (milliseconds) after which a task that has not
-    # yielded the scheduler emits a warning log.  nil disables the check.
-    # @return [Float, nil]
     attr_accessor :blocking_detect_threshold_ms
-
-    # Determines how an unhandled Application exception from a terminal stream
-    # callback affects the Task returned by Agent#stream_async or
-    # Agent#approve_async.
-    #
-    # +:report+ logs the callback failure and preserves the Agent result.
-    # +:fail_task+ logs the callback failure and fails the current Task with
-    # {Phronomy::StreamCallbackError}. Neither policy terminates EventLoop.
-    #
-    # Default: +:report+.
-    # @return [:report, :fail_task]
     attr_reader :stream_callback_error_policy
-
-    # Number of OS worker threads in the default {BlockingAdapterPool}.
-    # All LLM calls, MCP tool calls, and other blocking I/O share this pool.
-    # Increase for higher LLM/tool throughput; decrease to limit
-    # concurrency (e.g. to stay within a provider's rate limit).
-    # Default: 10.
-    # @return [Integer]
     attr_accessor :blocking_io_pool_size
-
-    # Maximum number of operations that may wait in the {BlockingAdapterPool}
-    # queue before {Phronomy::BackpressureError} is raised (on_full: :raise) or
-    # the caller blocks (on_full: :wait, the default). Default: 100.
-    # @return [Integer]
     attr_accessor :blocking_io_queue_size
-
-    # Worker count for Tool authorization evaluation. The named pool is owned
-    # by Runtime#pool(:authorization) and shares PoolRegistry lifecycle.
-    # @return [Integer]
     attr_accessor :authorization_pool_size
-
-    # Maximum queued Tool authorization evaluations.
-    # @return [Integer]
     attr_accessor :authorization_queue_size
-
-    # Operation-wide deadline for approval_facts, requires_approval callables,
-    # and Agent#tool_approval_policy. Timeout fails closed to Human approval.
-    # @return [Numeric]
     attr_accessor :authorization_timeout
-
-    # Scheduler starvation threshold (milliseconds).
-    # When a task waits more than this many milliseconds after calling
-    # +runtime.yield+ before being resumed, the wait is counted as a starvation
-    # event.  Used by the fairness regression test and by the
-    # +tasks_waiting_over_threshold+ metric on {Phronomy::Runtime}.
-    # Default: 50ms.
-    # @return [Numeric]
     attr_accessor :starvation_threshold_ms
-
-    # Scheduler backend to use for new {Phronomy::Runtime} instances.
-    #
-    # | Value | Scheduler | Typical use |
-    # |-------|-----------|-------------|
-    # | +:thread+ | {Runtime::ThreadScheduler} | **Default** — production-ready; one OS thread per task |
-    # | +:immediate+ | {Runtime::FakeScheduler} | Tests — tasks run synchronously, no extra threads |
-    # | +:fiber+ | {Runtime::DeterministicScheduler} (autorun) | **EXPERIMENTAL** — Fiber-based cooperative scheduler; do not use as production default |
-    # | +:cooperative+ | {Runtime::FakeScheduler} | **Deprecated** — alias for +:immediate+; do not use in new code |
-    #
-    # The default is +:thread+. The +:fiber+ backend remains experimental and opt-in;
-    # it will not become the default until integration test coverage is production grade
-    # and virtual-time/timeout semantics are fully resolved (see Issues #350, #347, #348).
-    #
-    # When this setting is changed, the change only takes effect on the NEXT
-    # call to {Runtime.instance} that auto-creates a new instance (i.e. after the
-    # previous instance has been replaced or reset).  To replace the current
-    # instance immediately call +Phronomy::Runtime.instance = nil+ first.
-    #
-    # @return [:thread, :immediate, :fiber]
-    attr_accessor :runtime_backend
-
-    # When +true+, calling {Agent#invoke} from inside a scheduler task
-    # raises {SchedulerReentrancyError}.  When +false+ (default), a warning
-    # is logged instead so that existing callers have time to migrate.
-    # @return [Boolean]
+    attr_reader :runtime_backend
     attr_accessor :strict_runtime_guards
 
     def stream_callback_error_policy=(value)
@@ -195,6 +45,18 @@ module Phronomy
       @stream_callback_error_policy = value
     end
 
+    # Scheduler backend used for newly-created Runtime instances.
+    # Supported values are :thread, :immediate, and :fiber.
+    def runtime_backend=(value)
+      value = value.to_sym if value.respond_to?(:to_sym)
+      unless RUNTIME_BACKENDS.include?(value)
+        allowed = RUNTIME_BACKENDS.map(&:inspect).join(", ")
+        raise Phronomy::ConfigurationError,
+          "runtime_backend must be one of: #{allowed}"
+      end
+      @runtime_backend = value
+    end
+
     def initialize
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new

data/lib/phronomy/content_store/base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  module ContentStore
+    class IntegrityError < Phronomy::Error; end
+
+    class Base
+      def put(_bytes, canonicalization_version:) = raise(NotImplementedError)
+      def fetch(_content_id) = raise(NotImplementedError)
+      def exist?(_content_id) = raise(NotImplementedError)
+
+      def put_text(text)
+        value = String(text).encode(Encoding::UTF_8)
+        raise ArgumentError, "invalid UTF-8 text" unless value.valid_encoding?
+
+        put(value, canonicalization_version: 1)
+      end
+
+      def put_json(value)
+        put(
+          Phronomy::CanonicalJSON.dump(value),
+          canonicalization_version: Phronomy::CanonicalJSON::VERSION
+        )
+      end
+
+      def fetch_text(content_id)
+        value = fetch(content_id).force_encoding(Encoding::UTF_8)
+        unless value.valid_encoding?
+          raise IntegrityError, "content is not UTF-8: #{content_id}"
+        end
+        value
+      end
+
+      def fetch_json(content_id)
+        Phronomy::CanonicalJSON.load(fetch(content_id))
+      end
+
+      def fetch_many(content_ids)
+        Array(content_ids).uniq.to_h { |content_id| [content_id, fetch(content_id)] }
+      end
+
+      private
+
+      def content_id_for(bytes)
+        "sha256:#{Digest::SHA256.hexdigest(bytes)}"
+      end
+    end
+  end
+end

data/lib/phronomy/context_budget_exceeded_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Raised when mandatory context content (system instructions, tool definitions,
+  # current input) exhausts the model's context window, leaving no room for
+  # prior conversation history.
+  class ContextBudgetExceededError < Error; end
+end

data/lib/phronomy/engine/concurrency/cancellation_token.rb

@@ -2,90 +2,33 @@
 
 module Phronomy
   module Concurrency
-    # Provides cooperative cancellation for agent invocations.
-    #
-    # Pass a token to an agent via +config: { cancellation_token: token }+.
-    # The agent checks the token before each LLM call and raises
-    # {Phronomy::CancellationError} when the token is cancelled or the
-    # optional deadline has passed.
-    #
-    # A token may be shared across multiple agent invocations and across threads;
-    # all access to internal state is protected by a Mutex.
-    #
-    # @example Explicit cancel from another thread
-    #   token = Phronomy::Concurrency::CancellationToken.new
-    #   Thread.new { sleep 5; token.cancel! }
-    #   result = agent.invoke("...", config: { cancellation_token: token })
-    #
-    # @example Hard deadline via monotonic clock (recommended)
-    #   token = Phronomy::Concurrency::CancellationToken.timeout_after(30)
-    #   result = agent.invoke("...", config: { cancellation_token: token })
-    #
-    # @example Hard deadline via wall-clock (legacy)
-    #   token = Phronomy::Concurrency::CancellationToken.new(deadline: Time.now + 30)
-    #   result = agent.invoke("...", config: { cancellation_token: token })
-    #
-    # @example Propagate to parallel workers
-    #   token = Phronomy::Concurrency::CancellationToken.new
-    #   orchestrator.dispatch_parallel(task1, task2, cancellation_token: token)
+    # Cooperative cancellation token for Agent/Tool work.
     class CancellationToken
-      # Returns a new token that will expire after +seconds+ seconds, measured
-      # with the monotonic clock (+Process::CLOCK_MONOTONIC+). Unlike constructing
-      # a token with +deadline: Time.now + seconds+, this factory is immune to NTP
-      # adjustments and DST transitions.
-      #
-      # @param seconds [Numeric] duration in seconds until the token expires.
-      # @return [CancellationToken]
+      # Creates a token that expires after +seconds+ measured with the monotonic clock.
       # @api public
       def self.timeout_after(seconds)
         monotonic_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
         new(monotonic_deadline: monotonic_deadline)
       end
 
-      # @param deadline [Time, nil] optional wall-clock deadline; the token reports
-      #   +cancelled?+ as +true+ once +Time.now >= deadline+.  Prefer
-      #   {.timeout_after} for duration-based cancellation.
-      # @param monotonic_deadline [Float, nil] internal monotonic timestamp set by
-      #   {.timeout_after}; prefer that factory method over passing this directly.
+      # @param monotonic_deadline [Float, nil] internal monotonic timestamp.
       # @api public
-      # mutant:disable - removing @cancelled = false is equivalent because nil is falsey
-      def initialize(deadline: nil, monotonic_deadline: nil)
+      def initialize(monotonic_deadline: nil)
         @cancelled = false
-        @deadline = deadline
         @monotonic_deadline = monotonic_deadline
         @mutex = Mutex.new
         @cancel_callbacks = []
       end
 
-      # @return [Time, nil] the wall-clock deadline passed to {#initialize}, or +nil+.
-      attr_reader :deadline
-
-      # Returns the remaining seconds until the monotonic deadline fires, or +nil+
-      # when no monotonic deadline is set.  Returns 0.0 if already past.
-      # @return [Float, nil]
       # @api public
       def remaining_monotonic_seconds
         return nil if @monotonic_deadline.nil?
+
         remaining = @monotonic_deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
         [remaining, 0.0].max
       end
 
-      # Registers a one-shot callback invoked when this token is explicitly
-      # cancelled via {#cancel!}.  If the token is already cancelled, the block
-      # is called immediately (still within the caller's thread).
-      #
-      # Callbacks are NOT fired for deadline-based cancellation (i.e. when
-      # {#cancelled?} returns +true+ due to +@monotonic_deadline+ expiry).  Use
-      # {Phronomy::Concurrency::CancellationScope#deadline_in}, which registers
-      # a timer via {Runtime#timer_queue} and calls {#cancel!} on expiry — this
-      # fires all +on_cancel+ callbacks automatically.  {.timeout_after} is a
-      # lightweight alternative that uses lazy clock comparison only and does
-      # NOT trigger callbacks on expiry.
-      #
-      # @yield called with no arguments when (or if) the token is cancelled
-      # @return [self]
       # @api public
-      # mutant:disable - mutex removal mutation is GVL-safe equivalent under MRI
       def on_cancel(&block)
         already_cancelled = @mutex.synchronize do
           if @cancelled
@@ -99,14 +42,11 @@ module Phronomy
         self
       end
 
-      # Mark the token as cancelled and fire any registered {#on_cancel} callbacks.
-      # Thread-safe; idempotent — calling multiple times has no additional effect.
-      # @return [self]
       # @api public
-      # mutant:disable - mutex removal and dup-vs-ref mutations are GVL-safe equivalents
       def cancel!
         callbacks = @mutex.synchronize do
           return self if @cancelled
+
           @cancelled = true
           @cancel_callbacks.dup
         end
@@ -114,28 +54,15 @@ module Phronomy
         self
       end
 
-      # Returns +true+ when the token has been explicitly cancelled via {#cancel!},
-      # when the wall-clock deadline has passed, or when the monotonic deadline
-      # (set by {.timeout_after}) has elapsed. Thread-safe.
-      # @return [Boolean]
       # @api public
-      # mutant:disable - mutex removal on @cancelled read is GVL-safe equivalent under MRI
       def cancelled?
         return true if @mutex.synchronize { @cancelled }
-        return true if !@deadline.nil? && Time.now >= @deadline
+
         !@monotonic_deadline.nil? &&
           Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_deadline
       end
 
-      # Raises {Phronomy::CancellationError} if the token is cancelled.
-      # A convenience method for cooperative cancellation checks inside tools,
-      # RAG loaders, and hooks, replacing the +if cancelled? then raise+ pattern.
-      #
-      # @param message [String] optional error message
-      # @return [nil] when the token is not cancelled
-      # @raise [Phronomy::CancellationError] when the token is cancelled
       # @api public
-      # mutant:disable - raise(CancellationError) resolves to raise(Phronomy::CancellationError) in this namespace
       def raise_if_cancelled!(message = "invocation cancelled")
         raise Phronomy::CancellationError, message if cancelled?
       end

data/lib/phronomy/engine/event_loop.rb

@@ -319,6 +319,9 @@ module Phronomy
         @fsms[session.id] = session
         @waiting[session.id] = waiter if waiter
         session.start
+      when :agent_terminal_ready
+        cmd = event.payload.fetch(:command)
+        cmd.coordinator.deliver_on_event_loop(cmd)
       end
     end