phronomy 0.27.0 → 0.28.0

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

@@ -1,124 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Concurrency
-    # Represents a bounded execution scope that owns a {CancellationToken} and
-    # optionally a {Deadline}.
-    #
-    # +CancellationScope+ replaces ad-hoc +Timeout.timeout+ calls in agent and
-    # tool code. All work performed within a scope should observe the scope's
-    # token; when the scope is cancelled (explicitly or by deadline expiry) the
-    # token is cancelled and all child tasks that check it will stop.
-    #
-    # @example Time-bounded invocation
-    #   scope = Phronomy::Concurrency::CancellationScope.new.deadline_in(30)
-    #   result = scope.pop_queue(completion_queue) do
-    #     raise Phronomy::TimeoutError, "timed out"
-    #   end
-    #
-    # @example Explicit cancellation
-    #   scope = Phronomy::Concurrency::CancellationScope.new
-    #   operation = Phronomy::Runtime.instance.offload.submit(
-    #     cancellation_token: scope.token
-    #   ) { synchronous_operation }
-    #   scope.cancel! if some_condition
-    class CancellationScope
-      # @return [CancellationToken] the token owned by this scope
-      attr_reader :token
-
-      # @return [Deadline, nil] the deadline attached to this scope, if any
-      attr_reader :deadline
-
-      # @param parent_token [CancellationToken, nil] when provided, cancellation of
-      #   the parent token is propagated to this scope's token via a callback
-      #   (for explicit cancel) and/or the Runtime timer queue (for monotonic
-      #   deadline expiry). No polling thread is spawned.
-      # @api private
-      def initialize(parent_token: nil)
-        @token = Phronomy::Concurrency::CancellationToken.new
-        @deadline = nil
-
-        if parent_token
-          # Propagate explicit cancel() from parent to child via callback.
-          parent_token.on_cancel { @token.cancel! }
-
-          # Propagate monotonic-deadline expiry from parent to child via the
-          # timer queue (avoids a polling thread).
-          remaining = parent_token.remaining_monotonic_seconds
-          if !remaining.nil?
-            if remaining <= 0
-              @token.cancel!
-            else
-              Phronomy::Runtime.instance.timer_queue.schedule(seconds: remaining) do
-                @token.cancel!
-              end
-            end
-          end
-        end
-      end
-
-      # Attaches a deadline that will cancel this scope after +seconds+.
-      #
-      # @param seconds [Numeric] timeout duration
-      # @return [self]
-      # @api private
-      def deadline_in(seconds)
-        @deadline = Phronomy::Concurrency::Deadline.in(seconds)
-        @deadline.attach_to(@token)
-        self
-      end
-
-      # Cancels this scope immediately.
-      # @return [void]
-      # @api private
-      def cancel!
-        @token.cancel!
-      end
-
-      # Returns +true+ if this scope has been cancelled.
-      # @return [Boolean]
-      # @api private
-      def cancelled?
-        @token.cancelled?
-      end
-
-      # Returns the remaining time in seconds before the deadline expires,
-      # or +nil+ when no deadline is set.
-      # @return [Float, nil]
-      # @api private
-      def remaining_seconds
-        @deadline&.remaining_seconds
-      end
-
-      # Pops from +queue+ with a timeout derived from the attached deadline (or
-      # +fallback_timeout+ seconds when no deadline is set). If the pop times out,
-      # the scope is cancelled and the block is called (or a {TimeoutError} raised).
-      #
-      # @param queue [Phronomy::Concurrency::AsyncQueue] the queue to pop from
-      # @param fallback_timeout [Numeric, nil] used when no deadline is attached
-      # @yield called when the operation times out
-      # @raise [Phronomy::TimeoutError] when no block is given and a timeout occurs
-      # @return [Object] the popped value
-      # @api private
-      def pop_queue(queue, fallback_timeout: nil)
-        timeout = @deadline&.remaining_seconds || fallback_timeout
-        result = if timeout
-          queue.pop(timeout: timeout)
-        else
-          queue.pop
-        end
-
-        if result.nil?
-          cancel!
-          if block_given?
-            yield
-          else
-            raise Phronomy::TimeoutError, "CancellationScope timed out"
-          end
-        end
-
-        result
-      end
-    end
-  end
-end

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

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Concurrency
-    # Connects explicit invocation controls before operation admission. Its token
-    # is private: cancelling it never cancels the application's shared tokens.
-    # Used by Agent, Blocking and Orchestrator admission; it owns no worker.
-    # @api private
-    class OperationBinding
-      attr_reader :token, :scope
-
-      def initialize(invocation_context:, cancellation_token:)
-        if !invocation_context.nil? && !invocation_context.is_a?(InvocationContext)
-          raise TypeError, "invocation_context must be a Phronomy::InvocationContext or nil"
-        end
-        @scope = invocation_context&.__execution_scope
-        @token = CancellationToken.new
-        @subscriptions = Subscriptions.new
-        [invocation_context&.cancellation_token, cancellation_token].compact.uniq.each do |source|
-          @subscriptions.cancellation(source) { @token.cancel! }
-        end
-        if !@scope && invocation_context&.deadline
-          @subscriptions.after(invocation_context.deadline.remaining_seconds) { @token.cancel! }
-        end
-        @token.cancel! if @scope && !@scope.__open?
-      end
-
-      def bind(result)
-        result.__bind_execution(@scope)
-        track(result)
-      end
-
-      def track(result)
-        @subscriptions.result(result) { @subscriptions.close }
-        result
-      end
-
-      def close
-        @subscriptions.close
-      end
-    end
-  end
-end

data/lib/phronomy/engine/execution_receiver.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Internal lifecycle/delivery contract for feature-owned execution state.
-  # Receivers are retained by one EventLoop, not an application callback SPI.
-  # Normal mutation and delivery run only on that loop. idle? runs with its
-  # lifecycle lock held; it must not call Runtime or acquire that lock again.
-  # shutdown runs on a failing loop, or exclusively after a clean loop joins.
-  # @api private
-  class ExecutionReceiver
-    def self.for(event_loop)
-      event_loop.__execution_receiver(key: self) ||
-        event_loop.__register_execution_receiver(key: self, receiver: new(event_loop: event_loop))
-    end
-
-    # Lookup only: neither a loop nor a receiver is created during inspection.
-    def self.existing_for(runtime)
-      runtime.__event_loop_if_initialized&.__execution_receiver(key: self)
-    end
-
-    def initialize(event_loop:)
-      @event_loop = event_loop
-    end
-
-    def __bound_to?(event_loop)
-      @event_loop.equal?(event_loop)
-    end
-
-    def idle?
-      raise NotImplementedError
-    end
-
-    def deliver(message)
-      raise NotImplementedError
-    end
-
-    def shutdown(error:)
-      raise NotImplementedError
-    end
-
-    def session_retired(fsm_session_id, reason:)
-    end
-
-    private
-
-    def synchronize(&block)
-      @event_loop.__synchronize_execution_state(&block)
-    end
-
-    def admit(&block)
-      @event_loop.__admit_execution(self, &block)
-    end
-
-    def post_message(message, admission: false, completion: nil)
-      @event_loop.__post_execution(self, message, admission: admission, completion: completion)
-    end
-
-    def assert_event_loop_thread!
-      return if @event_loop.current?
-
-      raise Phronomy::Error,
-        "Phronomy-managed live execution state may only be mutated on EventLoop"
-    end
-  end
-end

data/lib/phronomy/engine/runnable.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Base interface for executable graph components.
-  # Provides invoke / stream / batch.
-  module Runnable
-    # Synchronous execution. Must be overridden in subclasses.
-    def invoke(input, config: {})
-      raise NotImplementedError, "#{self.class}#invoke is not implemented"
-    end
-
-    # Streaming execution. Default yields the invoke result as a single chunk.
-    def stream(input, config: {}, &block)
-      result = invoke(input, config: config)
-      yield result if block
-      result
-    end
-
-    # Batch execution. Default calls invoke sequentially.
-    def batch(inputs, config: {})
-      inputs.map { |input| invoke(input, config: config) }
-    end
-
-    # Convenience wrapper that delegates to the global tracer.
-    # Yields a span; the block must return [result, usage] where usage is a
-    # Phronomy::TokenUsage or nil. Returns only the result value.
-    #
-    # When +trace_pii+ is disabled, both the input and the output (LLM response,
-    # tool result) are replaced with the literal string "[REDACTED]" before being
-    # forwarded to the tracing backend. The actual result is still returned to
-    # the caller — only the copy sent to the tracer is redacted.
-    #
-    # @example
-    #   trace("my_chain", input: input) { [invoke(input), nil] }
-    # @api public
-    def trace(name, input: nil, **meta, &block)
-      traced_input = Phronomy.configuration.trace_pii ? input : "[REDACTED]"
-
-      if Phronomy.configuration.trace_pii
-        # PII recording is allowed: pass through unchanged.
-        Phronomy.configuration.tracer.trace(name, input: traced_input, **meta, &block)
-      else
-        # Redact both input (above) and output before forwarding to the tracer.
-        # Capture the real result so callers receive the unredacted value.
-        real_result = nil
-        Phronomy.configuration.tracer.trace(name, input: traced_input, **meta) do |span|
-          real_result, usage = block.call(span)
-          ["[REDACTED]", usage]
-        end
-        real_result
-      end
-    end
-  end
-end

data/lib/phronomy/llm_adapter/ruby_llm.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module LLMAdapter
-    # Default LLMAdapter SPI implementation backed by RubyLLM.
-    #
-    # The synchronous +chat.ask+ / +chat.complete+ calls are invoked through the
-    # framework-owned async bridge in {LLMAdapter::Base}, so adapter consumers do
-    # not need to manage OffloadPool themselves.
-    #
-    # @example Explicitly configuring this adapter
-    #   Phronomy.configure do |c|
-    #     c.llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
-    #   end
-    #
-    # @api public
-    class RubyLLM < Base
-      # Delegates to +chat.ask(message)+ or +chat.complete+ when message is nil.
-      #
-      # Passing +nil+ for +message+ is used by the ReAct loop for continuation
-      # turns where the user message has already been added to the chat history
-      # (for example after a Tool result).
-      #
-      # @param chat    [Object]      RubyLLM chat session
-      # @param message [String, nil] user message, or nil to continue the chat
-      # @param config  [Hash]        invocation config (not used directly here)
-      # @return [Object] RubyLLM response
-      # @api public
-      def complete(chat, message, config: {})
-        message ? chat.ask(message) : chat.complete
-      end
-
-      # Delegates to +chat.ask(message) { |chunk| ... }+ or +chat.complete(&block)+
-      # when message is nil.
-      #
-      # @param chat    [Object]      RubyLLM chat session
-      # @param message [String, nil] user message, or nil to continue the chat
-      # @param config  [Hash]        invocation config
-      # @yield [chunk] streaming chunk forwarded from RubyLLM
-      # @return [Object] RubyLLM response
-      # @api public
-      def stream(chat, message, config: {}, &block)
-        message ? chat.ask(message, &block) : chat.complete(&block)
-      end
-    end
-  end
-end

data/lib/phronomy/llm_contract/token_usage.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Immutable value object that holds token usage counts for a single LLM call
-  # or an accumulated total across multiple calls.
-  #
-  # Fields mirror the values reported by RubyLLM::Tokens:
-  #
-  #   input          - tokens consumed by the input (prompt)
-  #   output         - tokens produced by the model (completion)
-  #   cached         - input tokens served from the provider's prompt cache
-  #   cache_creation - input tokens written into the prompt cache (Anthropic)
-  #
-  # All fields are Integer or nil (nil means the provider did not report that
-  # value for this call).
-  #
-  # @example Accumulate usage across a ReAct loop
-  #   total = Phronomy::TokenUsage.zero
-  #   chat.messages.each do |msg|
-  #     total += Phronomy::TokenUsage.from_tokens(msg.tokens)
-  #   end
-  class TokenUsage
-    attr_reader :input, :output, :cached, :cache_creation
-
-    def initialize(input: nil, output: nil, cached: nil, cache_creation: nil)
-      @input = input
-      @output = output
-      @cached = cached
-      @cache_creation = cache_creation
-    end
-
-    # Returns a zero-valued TokenUsage suitable as an accumulator seed.
-    def self.zero
-      new(input: 0, output: 0, cached: 0, cache_creation: 0)
-    end
-
-    # Builds a TokenUsage from a RubyLLM::Tokens object. Returns zero
-    # when tokens is nil (provider did not report usage).
-    # nil fields within the tokens object are coerced to 0.
-    def self.from_tokens(tokens)
-      return zero if tokens.nil?
-
-      new(
-        input: tokens.input || 0,
-        output: tokens.output || 0,
-        cached: tokens.cache_read || 0,
-        cache_creation: tokens.cache_write || 0
-      )
-    end
-
-    # Adds two TokenUsage instances. nil fields are treated as 0 so that
-    # partially-reported usage accumulates correctly.
-    # When other is nil, returns self unchanged.
-    def +(other)
-      return self if other.nil?
-
-      self.class.new(
-        input: _add(input, other.input),
-        output: _add(output, other.output),
-        cached: _add(cached, other.cached),
-        cache_creation: _add(cache_creation, other.cache_creation)
-      )
-    end
-
-    def ==(other)
-      other.is_a?(TokenUsage) &&
-        input == other.input &&
-        output == other.output &&
-        cached == other.cached &&
-        cache_creation == other.cache_creation
-    end
-
-    def to_h
-      {input: input, output: output, cached: cached, cache_creation: cache_creation}
-    end
-
-    private
-
-    def _add(a, b)
-      return nil if a.nil? && b.nil?
-
-      (a || 0) + (b || 0)
-    end
-  end
-end

data/lib/phronomy/multi_agent/persistence/queries.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module MultiAgent
-    module Persistence
-      # Read and assemble domain results; the public entry point owns the execution-thread guard.
-      # @api private
-      class Queries
-        def initialize(repositories)
-          @repositories = repositories
-        end
-
-        def team_execution_result(team_execution_id)
-          execution = @repositories.team_executions.load(team_execution_id)
-          {
-            team_execution_id: execution.team_execution_id, team_id: execution.team_id,
-            status: execution.status, phase: execution.phase,
-            result_ref: execution.result_ref, error_ref: execution.error_ref,
-            result: execution.result_ref && @repositories.contents.fetch_json(execution.result_ref),
-            error: execution.error_ref && @repositories.contents.fetch_json(execution.error_ref)
-          }.then { |value| Phronomy::Values::Immutable.copy(value) }
-        end
-
-        def list_team_executions(team_id, after: nil, limit: 100)
-          @repositories.team_executions.list(team_id, after: after, limit: limit)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/multi_agent/storage_contract/team_storage_schema.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Domain-owned Team metadata, independent of coordination runtime loading.
-  # @api private
-  module TeamStorageSchema
-    ROOTS = Phronomy::Storage::Resource.new(id: "team.roots", kind: :records,
-      guard: {resource: "team.roots", via: :key})
-    EXECUTIONS = Phronomy::Storage::Resource.new(id: "team.executions", kind: :records,
-      attributes: {owner: :string, active: :boolean}, immutable_attributes: [:owner],
-      indexes: {owner: [:owner], owner_active: [:owner, :active]},
-      unique: [{name: :one_active_owner, fields: [:owner], where: {active: true}}],
-      guard: {resource: ROOTS.id, via: :owner})
-  end
-end

data/lib/phronomy/output_parser/contract/parse_error.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../common/error"
-
-module Phronomy
-  class ParseError < Error; end
-end

data/lib/phronomy/persistence/api/persistence.rb

@@ -1,140 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Persistence
-    # Content-addressed immutable content repository. ContentStore has its own
-    # codec/canonicalization boundary and is not wrapped in DurableRecord.
-    #
-    # @return [Object]
-    # @api public
-    def contents = @repositories.contents
-
-    # Runtime/domain-facing AgentRoot repository. The injected backend is
-    # record-oriented; this facade owns encode/decode.
-    #
-    # @return [Object]
-    # @api public
-    def agents = @repositories.agents
-
-    # Runtime/domain-facing append-only Agent Journal repository.
-    #
-    # @return [Object]
-    # @api public
-    def journals = @repositories.journals
-
-    # Runtime/domain-facing AgentExecution repository.
-    #
-    # @return [Object]
-    # @api public
-    def executions = @repositories.executions
-
-    # Runtime/domain-facing durable Workflow snapshot repository.
-    #
-    # @return [Object]
-    # @api public
-    def workflow_states = @repositories.workflow_states
-
-    # Purpose-specific durable Handoff and Team repositories in atomic_all.
-    # @api public
-    def handoff_states = @repositories.handoff_states
-
-    # @api public
-    def teams = @repositories.teams
-
-    # @api public
-    def team_executions = @repositories.team_executions
-
-    # Read-only exact Agent execution result; never creates a live Agent owner.
-    # Result is nil until a result_ref exists; errors remain canonical data.
-    # @api public
-    def execution_result(execution_id)
-      assert_observation_thread!
-      Phronomy::Agent::Persistence::Queries.new(self).execution_result(execution_id)
-    end
-
-    # Follows one exact Handoff turn without constructing a live Agent or graph.
-    # A committed absent Target reservation remains active; failed reads raise.
-    # @api public
-    def handoff_result(execution_id, main_agent_id: nil)
-      assert_observation_thread!
-      Phronomy::Agent::Persistence::Queries.new(self).handoff_result(execution_id, main_agent_id: main_agent_id)
-    end
-
-    # Lists retained active and terminal executions in lexical ID order.
-    # after is an exclusive ID cursor; discovery does not imply request dedup.
-    # @api public
-    def list_executions(agent_id, after: nil, limit: 100)
-      assert_observation_thread!
-      Phronomy::Agent::Persistence::Queries.new(self).list_executions(agent_id, after: after, limit: limit)
-    end
-
-    # Read-only exact Team result, independent of current Team class/Proc wiring.
-    # @api public
-    def team_execution_result(team_execution_id)
-      assert_observation_thread!
-      Phronomy::MultiAgent::Persistence::Queries.new(self).team_execution_result(team_execution_id)
-    end
-
-    # Lists retained Team runs; no continuation or callback delivery occurs.
-    # @api public
-    def list_team_executions(team_id, after: nil, limit: 100)
-      assert_observation_thread!
-      Phronomy::MultiAgent::Persistence::Queries.new(self).list_team_executions(team_id, after: after, limit: limit)
-    end
-
-    # The selected raw storage backend, for backend-specific administration.
-    # Read and write domain records through the repository accessors above.
-    # @api public
-    attr_reader :backend
-
-    # Assembles domain repositories over one synchronous storage backend.
-    # @api public
-    def initialize(backend:)
-      Phronomy::Storage::Backend.validate_capabilities!(backend)
-      PersistenceComposition::StorageSchema.validate!(backend.view)
-      @backend = backend
-      @repositories = PersistenceComposition::Repositories.new(backend.view)
-    end
-
-    # Constructs an isolated in-memory storage domain with standard codecs.
-    # @api public
-    def self.in_memory
-      new(backend: Phronomy::Storage::Backends::InMemory.new(resources: PersistenceComposition::StorageSchema.resources))
-    end
-
-    # @api public
-    def capabilities = {atomic_all: true, atomic_admission: true, optimistic_revision: true}.freeze
-
-    # Executes a single backend transaction and exposes domain repositories
-    # bound to its raw view. Codec and caller failures remain inside the backend
-    # block so the backend can roll them back. The block result is returned.
-    # Explicit nested calls on this service use savepoint semantics: a failed
-    # inner scope rolls back and re-raises; a successful inner scope is committed
-    # only with its outer scope. See Storage::Backend#transaction.
-    # Storage failures whose commit outcome is fundamentally
-    # unknown remain backend/database failures; Phronomy does not claim
-    # exactly-once semantics for such failures.
-    # @api public
-    def transaction
-      backend.transaction do |raw_view|
-        repositories = PersistenceComposition::Repositories.new(raw_view)
-        yield repositories
-      end
-    end
-
-    # @api public
-    def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
-      @repositories.assert_agent_watermark!(
-        agent_id: agent_id, agent_revision: agent_revision, journal_position: journal_position
-      )
-    end
-
-    private
-
-    def assert_observation_thread!
-      if Phronomy::Runtime.in_event_loop_context?
-        raise Phronomy::EventLoopReentrancyError, "Persistence observation cannot block EventLoop"
-      end
-    end
-  end
-end

data/lib/phronomy/persistence_composition/repositories.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module PersistenceComposition
-    # Assemble domain repositories over one raw backend or transaction view.
-    # @api private
-    class Repositories
-      attr_reader :contents
-
-      def initialize(view)
-        @view = view
-        @contents = Phronomy::ContentStore::StoredContents.new(view)
-        @domain_repositories = {}
-        @repository_lock = Mutex.new
-      end
-
-      def agents
-        domain_repository(:agents) do
-          Phronomy::Agent::Persistence::AgentRepository.new(@view)
-        end
-      end
-
-      def journals
-        domain_repository(:journals) do
-          Phronomy::Agent::Persistence::JournalRepository.new(@view)
-        end
-      end
-
-      def executions
-        domain_repository(:executions) do
-          Phronomy::Agent::Persistence::ExecutionRepository.new(@view)
-        end
-      end
-
-      def workflow_states
-        domain_repository(:workflow_states) do
-          Phronomy::Workflow::Persistence::StateRepository.new(@view)
-        end
-      end
-
-      def handoff_states
-        domain_repository(:handoff_states) do
-          Phronomy::Agent::Persistence::HandoffStateRepository.new(@view)
-        end
-      end
-
-      def teams
-        domain_repository(:teams) do
-          Phronomy::MultiAgent::Persistence::TeamRepository.new(@view)
-        end
-      end
-
-      def team_executions
-        domain_repository(:team_executions) do
-          Phronomy::MultiAgent::Persistence::TeamExecutionRepository.new(@view)
-        end
-      end
-
-      def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
-        Phronomy::Agent::Persistence::Watermark.new(@view).check!(
-          agent_id: agent_id.to_s,
-          agent_revision: Integer(agent_revision),
-          journal_position: Integer(journal_position)
-        )
-      end
-
-      private
-
-      # Cache one wrapper per view without loading unused domain implementations.
-      def domain_repository(name)
-        @repository_lock.synchronize do
-          @domain_repositories.fetch(name) { @domain_repositories[name] = yield }
-        end
-      end
-    end
-  end
-end