prompt_objects 0.5.0 → 0.7.0

data/lib/prompt_objects/execution/blocking_executor.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Execution
+    # Bounded worker pool for synchronous adapters and capabilities. Completion
+    # is signalled through an IO so an Async fiber yields instead of blocking
+    # the server reactor while a worker is occupied.
+    class BlockingExecutor
+      class RejectedError < StandardError; end
+
+      Job = Data.define(:work, :completion, :result)
+      STOP = Object.new.freeze
+
+      def initialize(size: 4, queue_capacity: size * 4)
+        raise ArgumentError, "size must be positive" unless size.positive?
+        raise ArgumentError, "queue_capacity must be positive" unless queue_capacity.positive?
+
+        @jobs = SizedQueue.new(queue_capacity)
+        @state_mutex = Mutex.new
+        @closed = false
+        @workers = Array.new(size) { start_worker }
+      end
+
+      def call(&work)
+        raise ArgumentError, "a block is required" unless work
+
+        reader, writer = IO.pipe
+        result = {}
+        enqueue(Job.new(work: work, completion: writer, result: result))
+        reader.read(1)
+        raise result[:error] if result.key?(:error)
+
+        result[:value]
+      ensure
+        reader&.close unless reader&.closed?
+        writer&.close unless writer&.closed?
+      end
+
+      def close
+        workers = @state_mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          @workers.dup
+        end
+        workers.size.times { @jobs.push(STOP) }
+        workers.each(&:join)
+      end
+
+      private
+
+      def enqueue(job)
+        @state_mutex.synchronize do
+          raise RejectedError, "blocking executor is closed" if @closed
+
+          @jobs.push(job, true)
+        end
+      rescue ThreadError
+        raise RejectedError, "blocking executor queue is full"
+      end
+
+      def start_worker
+        Thread.new do
+          Thread.current.name = "prompt-objects-worker" if Thread.current.respond_to?(:name=)
+          while (job = @jobs.pop)
+            break if job.equal?(STOP)
+
+            execute(job)
+          end
+        end
+      end
+
+      def execute(job)
+        job.result[:value] = job.work.call
+      rescue Exception => e # rubocop:disable Lint/RescueException -- propagate worker failures to the caller
+        job.result[:error] = e
+      ensure
+        begin
+          job.completion.write(".")
+        rescue IOError, Errno::EPIPE
+          # The awaiting Async task was cancelled; the work is allowed to finish.
+        ensure
+          job.completion.close unless job.completion.closed?
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/execution/context.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Execution
+    class CancelledError < StandardError; end
+
+    # Cooperative cancellation shared by a run and its attached descendants.
+    class CancellationToken
+      def initialize
+        @cancelled = false
+        @reason = nil
+        @mutex = Mutex.new
+      end
+
+      def cancel(reason = "cancelled")
+        @mutex.synchronize do
+          @cancelled = true
+          @reason = reason
+        end
+      end
+
+      def cancelled?
+        @mutex.synchronize { @cancelled }
+      end
+
+      def reason
+        @mutex.synchronize { @reason }
+      end
+
+      def check!
+        raise CancelledError, reason if cancelled?
+      end
+    end
+
+    # Immutable identity and dependencies passed to one run or tool call.
+    class Context
+      attr_reader :env, :bus, :human_queue, :workspace_session_id, :thread_id,
+                  :run_id, :caller_po, :target_po, :source_type, :source_name,
+                  :current_capability, :calling_po, :cancellation_token,
+                  :trace_id, :span_id, :deadline, :resource_lock_manager,
+                  :event_publisher, :tui_mode
+
+      def initialize(env:, workspace_session_id:, thread_id:, run_id:, target_po:,
+                     source_type:, source_name: nil, caller_po: nil,
+                     current_capability: nil, cancellation_token: CancellationToken.new,
+                     trace_id: SecureRandom.uuid, span_id: SecureRandom.uuid,
+                     deadline: nil, resource_lock_manager: nil, event_publisher: nil,
+                     tui_mode: false)
+        @env = env
+        @bus = env.bus
+        @human_queue = env.human_queue
+        @workspace_session_id = workspace_session_id
+        @thread_id = thread_id
+        @run_id = run_id
+        @caller_po = caller_po
+        @target_po = target_po
+        @source_type = source_type
+        @source_name = source_name
+        @current_capability = current_capability
+        @calling_po = caller_po
+        @cancellation_token = cancellation_token
+        @trace_id = trace_id
+        @span_id = span_id
+        @deadline = deadline
+        @resource_lock_manager = resource_lock_manager
+        @event_publisher = event_publisher
+        @tui_mode = tui_mode
+        freeze
+      end
+
+      def for_tool_call(tool_call)
+        self.class.new(
+          **shared_attributes,
+          caller_po: target_po,
+          current_capability: tool_call.name,
+          span_id: SecureRandom.uuid
+        )
+      end
+
+      def for_child_run(run_id:, thread_id:, target_po:, source_name: nil)
+        self.class.new(
+          **shared_attributes,
+          run_id: run_id,
+          thread_id: thread_id,
+          target_po: target_po,
+          caller_po: self.target_po,
+          source_type: "delegation",
+          source_name: source_name || self.target_po,
+          current_capability: nil,
+          span_id: SecureRandom.uuid
+        )
+      end
+
+      def env_data_scope
+        workspace_session_id
+      end
+
+      def check_cancelled!
+        cancellation_token.check!
+        return true unless deadline && Time.now >= deadline
+
+        raise CancelledError, "deadline exceeded"
+      end
+
+      def log_message(to:, message:)
+        bus.publish(from: current_capability || source_name || source_type, to: to, message: message)
+      end
+
+      def log_response(from:, message:)
+        bus.publish(from: from, to: current_capability || target_po, message: message)
+      end
+
+      private
+
+      def shared_attributes
+        {
+          env: env,
+          workspace_session_id: workspace_session_id,
+          thread_id: thread_id,
+          run_id: run_id,
+          target_po: target_po,
+          source_type: source_type,
+          source_name: source_name,
+          caller_po: caller_po,
+          current_capability: current_capability,
+          cancellation_token: cancellation_token,
+          trace_id: trace_id,
+          span_id: span_id,
+          deadline: deadline,
+          resource_lock_manager: resource_lock_manager,
+          event_publisher: event_publisher,
+          tui_mode: tui_mode
+        }
+      end
+    end
+  end
+end

data/lib/prompt_objects/execution/contracts.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Execution
+    # Stable names shared by the runtime protocol, persistence layer, and UI.
+    # The protocol fixtures in protocol/v1/fixtures are the wire-format examples.
+    module Contracts
+      PROTOCOL_VERSION = 1
+
+      THREAD_TYPES = %w[human autonomous artifact delegation service api].freeze
+      RUN_STATUSES = %w[queued running waiting completed failed cancelled skipped interrupted].freeze
+      TOOL_EXECUTION_STATUSES = %w[pending running completed failed cancelled timed_out].freeze
+      RUN_EVENT_KINDS = %w[
+        run_queued run_started model_started stream_delta model_completed
+        tool_batch_started tool_started tool_completed tool_failed tool_cancelled
+        delegation_started delegation_completed artifact_upserted env_data_changed
+        run_waiting run_completed run_failed run_cancelled run_skipped run_interrupted
+      ].freeze
+
+      SNAPSHOT_TYPES = %w[workspace_snapshot thread_snapshot artifact_snapshot].freeze
+      MUTATION_TYPES = %w[artifact_upserted artifact_removed env_data_changed].freeze
+      ENVELOPE_TYPES = (SNAPSHOT_TYPES + MUTATION_TYPES + ["run_event"]).freeze
+
+      module_function
+
+      def validate_envelope!(envelope)
+        data = stringify_keys(envelope)
+        version = data.fetch("version")
+        type = data.fetch("type")
+        payload = data.fetch("payload")
+
+        raise ArgumentError, "unsupported protocol version: #{version}" unless version == PROTOCOL_VERSION
+        raise ArgumentError, "unknown protocol message type: #{type}" unless ENVELOPE_TYPES.include?(type)
+        raise ArgumentError, "payload must be an object" unless payload.is_a?(Hash)
+
+        validate_run_event!(payload) if type == "run_event"
+        true
+      end
+
+      def validate_run_event!(payload)
+        %w[workspace_session_id thread_id run_id sequence workspace_cursor kind timestamp data].each do |key|
+          payload.fetch(key)
+        end
+
+        kind = payload.fetch("kind")
+        raise ArgumentError, "unknown run event kind: #{kind}" unless RUN_EVENT_KINDS.include?(kind)
+        raise ArgumentError, "run event sequence must be positive" unless payload.fetch("sequence").to_i.positive?
+        raise ArgumentError, "workspace cursor must be positive" unless payload.fetch("workspace_cursor").to_i.positive?
+      end
+
+      def stringify_keys(value)
+        return value.transform_keys(&:to_s).transform_values { |item| stringify_keys(item) } if value.is_a?(Hash)
+        return value.map { |item| stringify_keys(item) } if value.is_a?(Array)
+
+        value
+      end
+    end
+  end
+end

data/lib/prompt_objects/execution/permit_pool.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Execution
+    # A small counting semaphore used for scheduler resources that must remain
+    # distinct (workers, providers, and later resource leases).
+    class PermitPool
+      def initialize(limit)
+        raise ArgumentError, "limit must be positive" unless limit.positive?
+
+        @limit = limit
+        @available = limit
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+      end
+
+      attr_reader :limit
+
+      def with
+        acquire
+        yield
+      ensure
+        release
+      end
+
+      def acquire
+        @mutex.synchronize do
+          @condition.wait(@mutex) until @available.positive?
+          @available -= 1
+        end
+        true
+      end
+
+      def release
+        @mutex.synchronize do
+          raise ThreadError, "permit pool released without an acquisition" if @available >= @limit
+
+          @available += 1
+          @condition.signal
+        end
+        true
+      end
+
+      def available
+        @mutex.synchronize { @available }
+      end
+    end
+  end
+end

data/lib/prompt_objects/execution/policy.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Execution
+    ResolvedPolicy = Data.define(:parallel_safe, :side_effect, :workload, :resource_keys, :signature)
+
+    class Policy
+      SIDE_EFFECTS = %i[read write exclusive].freeze
+      WORKLOADS = %i[blocking cpu].freeze
+
+      def initialize(parallel_safe:, side_effect:, resource_keys: nil, workload: :blocking)
+        raise ArgumentError, "unknown side effect: #{side_effect}" unless SIDE_EFFECTS.include?(side_effect.to_sym)
+        raise ArgumentError, "unknown workload: #{workload}" unless WORKLOADS.include?(workload.to_sym)
+
+        @parallel_safe = !!parallel_safe
+        @side_effect = side_effect.to_sym
+        @workload = workload.to_sym
+        @resource_resolver = resource_keys
+        freeze
+      end
+
+      attr_reader :parallel_safe, :side_effect, :workload
+
+      def resolve(arguments:, context:, capability:)
+        keys = if @resource_resolver
+                 Array(@resource_resolver.call(arguments, context, capability))
+               elsif side_effect == :exclusive
+                 ["workspace:#{context.workspace_session_id}:exclusive"]
+               else
+                 []
+               end
+        ResolvedPolicy.new(
+          parallel_safe: parallel_safe,
+          side_effect: side_effect,
+          workload: workload,
+          resource_keys: keys.compact.map(&:to_s).uniq.sort.freeze,
+          signature: signature(capability).freeze
+        )
+      end
+
+      def signature(capability = nil)
+        resolver_location = @resource_resolver&.source_location&.join(":")
+        [capability&.class&.name, parallel_safe, side_effect, workload, resolver_location].compact.join("|")
+      end
+    end
+  end
+end

data/lib/prompt_objects/execution/resource_lock_manager.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "set"
+require "timeout"
+
+module PromptObjects
+  module Execution
+    # Atomically leases a set of resource keys. All-or-nothing acquisition
+    # avoids deadlocks when two tool calls need overlapping key sets.
+    class ResourceLockManager
+      class LockTimeoutError < Timeout::Error; end
+
+      def initialize
+        @leased = Set.new
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+      end
+
+      def with(resource_keys, timeout: 30, cancellation_token: nil)
+        keys = Array(resource_keys).compact.map(&:to_s).uniq.sort
+        return yield if keys.empty?
+
+        acquire(keys, timeout: timeout, cancellation_token: cancellation_token)
+        acquired = true
+        yield
+      ensure
+        release(keys) if acquired
+      end
+
+      def locked_keys
+        @mutex.synchronize { @leased.to_a.sort }
+      end
+
+      private
+
+      def acquire(keys, timeout:, cancellation_token:)
+        deadline = monotonic_time + timeout
+        @mutex.synchronize do
+          until (@leased & keys).empty?
+            cancellation_token&.check!
+            remaining = deadline - monotonic_time
+            raise LockTimeoutError, "timed out waiting for resources: #{keys.join(', ')}" unless remaining.positive?
+
+            @condition.wait(@mutex, [remaining, 0.05].min)
+          end
+          cancellation_token&.check!
+          @leased.merge(keys)
+        end
+      end
+
+      def release(keys)
+        @mutex.synchronize do
+          keys.each { |key| @leased.delete(key) }
+          @condition.broadcast
+        end
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end