phronomy 0.28.0 → 0.30.0

data/lib/phronomy/workflow/runtime_binding/workflow_engine_environment.rb

@@ -9,7 +9,13 @@ module Phronomy
       @runtime = runtime
     end
 
-    def registry = WorkflowExecutionRegistry.for(@runtime.event_loop)
+    def registry
+      receiver = WorkflowExecutionRegistry.for(@runtime.event_loop)
+      @runtime.__shutdown_participant(key: WorkflowExecutionRegistry) ||
+        @runtime.__register_shutdown_participant(key: WorkflowExecutionRegistry, participant: receiver)
+      receiver
+    end
+
     def existing_registry = WorkflowExecutionRegistry.existing_for(@runtime)
     def executing? = @runtime.event_loop.current?
 
@@ -21,18 +27,35 @@ module Phronomy
       WorkflowPhaseMachineBuilder.new(**definition).build
     end
 
-    def build_session(entry_actions:, persist: nil, **options)
+    def build_session(entry_actions:, persist: nil, task_execution: nil, **options)
       # Preserve nil/scalar results: initial entry must not re-adopt metadata
       # unless the application actually returns a context.
       initial_actions = entry_actions.to_h do |state_name, callbacks|
         [state_name, callbacks.map { |callback| ->(context) { WorkflowActionRules.entry(callback, context, state_name) } }]
       end
-      Phronomy::FSMSession.new(**options, entry_actions: initial_actions, event_loop: @runtime.event_loop,
+      klass = task_execution ? Phronomy::WorkflowTaskSession : Phronomy::FSMSession
+      options = options.merge(task_execution: task_execution) if task_execution
+      klass.new(**options, entry_actions: initial_actions, event_loop: @runtime.event_loop,
         terminal_policy: persist && WorkflowTerminalPolicy.new(persist: persist))
     end
 
     def register_session(session, completion:)
       @runtime.event_loop.register(session, completion: completion, receiver: registry)
     end
+
+    def subscribe_cancellation(token, &callback)
+      subscriptions = Phronomy::Concurrency::ResultSubscriptions.new
+      subscriptions.cancellation(token, &callback)
+      remaining = token.remaining_monotonic_seconds
+      if remaining && !token.cancelled?
+        timer = @runtime.timer_queue
+        timer.schedule(seconds: remaining, &callback)
+        subscriptions.add { timer.cancel(callback) }
+      end
+      subscriptions
+    rescue
+      subscriptions&.close
+      raise
+    end
   end
 end

data/lib/phronomy/workflow/runtime_binding/workflow_phase_machine_builder.rb

@@ -47,7 +47,8 @@ module Phronomy
           :context,
           :current_event,
           :selected_transition_action,
-          :selected_transition_metadata
+          :selected_transition_metadata,
+          :workflow_task_execution
         )
 
         state_machine :phase, initial: entry do
@@ -85,6 +86,7 @@ module Phronomy
           # Both source exit callbacks and the transition action are
           # before_transition callbacks. Register exits first to preserve the
           # required exit -> transition action -> entry ordering.
+          before_transition { |machine| machine.workflow_task_execution&.leave }
           exit_actions.each do |state_name, callables|
             callables.each do |callable|
               before_transition(

data/lib/phronomy/workflow/runtime_binding/workflow_task_session.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # I07 translates C02 task-state decisions to generic FSM progression. Engine
+  # does not learn TaskResult ownership, cancellation or stale-result policy.
+  # @api private
+  class WorkflowTaskSession < FSMSession
+    def initialize(task_execution:, **options)
+      super(**options)
+      @task_execution = task_execution
+      @task_execution.bind(self)
+    end
+
+    def start
+      @task_execution.activate
+      super unless @done
+    rescue => error
+      finish_with_error(error)
+    end
+
+    def apply_task_context(context)
+      return unless @terminal_lifecycle_state == :running
+
+      @ctx = @context = context
+      apply_context_metadata!
+      @tracker.context = context
+      advance_or_halt
+    rescue => error
+      finish_with_error(error)
+    end
+
+    def fail_task_execution(error)
+      finish_with_error(error) if @terminal_lifecycle_state == :running
+    end
+
+    def handle(event)
+      return if event.type == :state_completed && !@task_execution.permits_completion?(event.payload)
+
+      super
+    end
+
+    private
+
+    def post_session_event(type, payload = nil)
+      payload = @task_execution.completion_key if type == :state_completed
+      super
+    end
+
+    def advance_or_halt
+      if @task_execution.enter(@current_state, @ctx)
+        notify_stable_state!
+      else
+        super
+      end
+    end
+
+    def build_tracker(from_state)
+      super.tap { |tracker| tracker.workflow_task_execution = @task_execution }
+    end
+
+    def request_terminal!(...)
+      @task_execution.close
+      super
+    end
+
+    def finish_with_error(error)
+      @task_execution.close
+      super
+    end
+
+    def retire_without_result!(error)
+      @task_execution.retire(error)
+      super
+    end
+  end
+end

data/lib/phronomy.rb

@@ -12,6 +12,7 @@ loader.inflector.inflect("fsm_protocol" => "FSMProtocol")
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
 loader.inflector.inflect("llm_operation_result" => "LLMOperationResult")
 loader.inflector.inflect("ruby_llm" => "RubyLLM")
+loader.inflector.inflect("lm_studio" => "LMStudio")
 loader.inflector.inflect("canonical_json" => "CanonicalJSON")
 loader.inflector.inflect("llm_call_record" => "LLMCallRecord")
 loader.inflector.inflect("llm_input_manifest" => "LLMInputManifest")
@@ -60,7 +61,6 @@ loader.ignore(
   "#{__dir__}/phronomy/runtime_composition/global_configuration.rb",
   "#{__dir__}/phronomy/agent/composition",
   "#{__dir__}/phronomy/runtime_composition/agent_defaults.rb",
-  "#{__dir__}/phronomy/runtime_composition/generation_defaults.rb",
   "#{__dir__}/phronomy/runtime_composition/evaluation_defaults.rb",
   "#{__dir__}/phronomy/runtime_composition/workflow_defaults.rb",
   "#{__dir__}/phronomy/runtime_composition/multi_agent_defaults.rb",
@@ -68,6 +68,8 @@ loader.ignore(
   "#{__dir__}/phronomy/runtime_composition/global_runtime.rb",
   "#{__dir__}/phronomy/runtime_composition/execution_defaults.rb"
 )
+# Optional application integrations are loaded explicitly by their consumers.
+loader.ignore("#{__dir__}/phronomy/integrations")
 # Persistence conformance support must never make production loading require RSpec.
 loader.ignore(
   "#{__dir__}/phronomy/testing/persistence_contract.rb",
@@ -85,6 +87,8 @@ loader.ignore("#{__dir__}/phronomy/agent/agent_purged_error.rb")
 loader.ignore("#{__dir__}/phronomy/agent/stream_callback_error.rb")
 loader.ignore("#{__dir__}/phronomy/agent/handoff_error.rb")
 loader.ignore("#{__dir__}/phronomy/agent/agent_already_exists_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/agent_not_found_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/agent_unloaded_error.rb")
 loader.setup
 require_relative "phronomy/persistence/transaction"
 require_relative "phronomy/persistence_composition/stores"
@@ -96,6 +100,8 @@ require_relative "phronomy/agent/agent_purged_error"
 require_relative "phronomy/agent/stream_callback_error"
 require_relative "phronomy/agent/handoff_error"
 require_relative "phronomy/agent/agent_already_exists_error"
+require_relative "phronomy/agent/agent_not_found_error"
+require_relative "phronomy/agent/agent_unloaded_error"
 
 require_relative "phronomy/runtime_composition/configuration_defaults"
 require_relative "phronomy/llm_adapter/token_usage"
@@ -110,7 +116,6 @@ require_relative "phronomy/agent/api/agent"
 require_relative "phronomy/runtime_composition/agent_defaults"
 require_relative "phronomy/runtime_composition/multi_agent_defaults"
 require_relative "phronomy/runtime_composition/workflow_defaults"
-require_relative "phronomy/runtime_composition/generation_defaults"
 require_relative "phronomy/runtime_composition/evaluation_defaults"
 require_relative "phronomy/agent/composition/run_once"
 

data/scripts/api_snapshot.rb

@@ -18,6 +18,17 @@ require_relative "../lib/phronomy"
 
 PUBLIC_API_ENTRIES = [
   # Stable
+  Phronomy::Error,
+  Phronomy::AgentNotFoundError,
+  Phronomy::AgentUnloadedError,
+  Phronomy::Agent,
+  Phronomy::Agent::Scope,
+  Phronomy::Agent::OutputError,
+  Phronomy::Agent::ScopeCleanupError,
+  Phronomy::MultiAgent::TeamNotFoundError,
+  Phronomy::MultiAgent::TeamBusyError,
+  Phronomy::Embeddings::AuthenticationError,
+  Phronomy::Embeddings::RateLimitError,
   Phronomy::Agent::Base,
   Phronomy::Agent::ReservedExecution,
   Phronomy::Agent::ExecutionObservation,
@@ -36,6 +47,8 @@ PUBLIC_API_ENTRIES = [
   Phronomy::InvocationContext,
   Phronomy::Tool::Base,
   Phronomy::Workflow,
+  Phronomy::Workflow::Builder,
+  Phronomy::WorkflowTaskResumeError,
   Phronomy::WorkflowContext,
   Phronomy::Runnable,
   Phronomy::Context::PromptTemplate,
@@ -45,6 +58,8 @@ PUBLIC_API_ENTRIES = [
   Phronomy::Tool::Operation,
   Phronomy::LLMAdapter::Base,
   Phronomy::LLMAdapter::Request,
+  Phronomy::LLMAdapter::StructuredOutputUnsupportedError,
+  Phronomy::OutputParser::JsonSchemaParser,
   Phronomy::LLMAdapter::Message,
   Phronomy::LLMAdapter::Response,
   Phronomy::LLMAdapter::StreamChunk,

data/scripts/check_readme_ruby.rb

@@ -1,38 +1,33 @@
 # frozen_string_literal: true
 
-# Extracts every ```ruby ... ``` block from README.md and runs `ruby -c` on each.
-# Exits non-zero if any block has a syntax error.
-
+# Check all Ruby fences, including executable examples, in the entry documents.
 require "tempfile"
 require "open3"
-
-readme_path = File.expand_path("../README.md", __dir__)
-readme = File.read(readme_path)
-blocks = readme.scan(/^```ruby\n(.*?)^```/m).map.with_index(1) { |(code), i| [i, code] }
-
-puts "Checking #{blocks.size} Ruby code blocks in README.md..."
+require_relative "check_readme_runnable"
 
 failures = []
-
-blocks.each do |index, code|
-  Tempfile.create(["readme_block_#{index}", ".rb"]) do |f|
-    f.write(code)
-    f.flush
-    stdout, status = Open3.capture2e("ruby", "-c", f.path)
-    if status.success?
-      puts "  OK   block ##{index}"
-    else
-      failures << index
-      puts "  FAIL block ##{index}"
-      puts stdout.gsub(f.path, "block ##{index}")
+count = 0
+paths = ARGV.empty? ? RunnableDocumentation::PATHS : ARGV
+paths.each do |relative|
+  text = File.read(File.expand_path(relative, RunnableDocumentation::ROOT))
+  text.to_enum(:scan, /^```ruby(?: runnable)?\n(.*?)^```/m).each do
+    match = Regexp.last_match
+    line = text[0...match.begin(1)].count("\n") + 1
+    label = "#{relative}:#{line}"
+    count += 1
+    Tempfile.create(["documentation_block", ".rb"]) do |file|
+      file.write(match[1])
+      file.flush
+      out, status = Open3.capture2e(RbConfig.ruby, "-c", file.path)
+      if status.success?
+        puts "OK   #{label}"
+      else
+        failures << label
+        puts "FAIL #{label}"
+        puts out.gsub(file.path, label)
+      end
     end
   end
 end
-
-if failures.empty?
-  puts "All #{blocks.size} Ruby code blocks passed syntax check."
-  exit 0
-else
-  puts "\n#{failures.size} block(s) failed syntax check: #{failures.join(", ")}"
-  exit 1
-end
+puts "#{count} Ruby blocks; #{failures.size} syntax failures"
+exit(failures.empty? ? 0 : 1)

data/scripts/check_readme_runnable.rb

@@ -1,101 +1,112 @@
 # frozen_string_literal: true
 
-# scripts/check_readme_runnable.rb
-#
-# Extracts ```ruby runnable blocks from README.md and executes each in an
-# isolated subprocess with a fake LLM stub to catch API drift.
-#
-# Any block that raises NoMethodError / ArgumentError / NameError causes a
-# non-zero exit, failing the CI step.
-#
-# Usage (from the phronomy/ root):
-#   bundle exec ruby scripts/check_readme_runnable.rb
-
+# Runs annotated, self-contained examples through the real public API.
+# Only the external LLM adapter is replaced. Each block has its own process,
+# configuration and Runtime; an accidental network request fails immediately.
+# Usage: bundle exec ruby scripts/check_readme_runnable.rb [markdown paths...]
 require "tempfile"
 require "open3"
 
-REPO_ROOT = File.expand_path("..", __dir__)
-README_PATH = File.join(REPO_ROOT, "README.md")
-
-# Injected before every runnable block.
-# Uses the Gemfile of this project so subprocesses can load phronomy.
-PREAMBLE = <<~RUBY
-  # frozen_string_literal: true
-  # --- CI preamble: stub LLM calls so no real network requests are made ---
-  ENV["BUNDLE_GEMFILE"] ||= "#{File.join(REPO_ROOT, "Gemfile")}"
-  require "bundler/setup"
-  require "phronomy"
+module RunnableDocumentation
+  ROOT = File.expand_path("..", __dir__)
+  PATHS = %w[README.md docs/getting-started.md docs/application-recipes.md docs/workflow-completion.md].freeze
+
+  PREAMBLE = <<~RUBY
+    require "bundler/setup"
+    require "phronomy"
+    require "webmock"
+    require "timeout"
+    WebMock.enable!
+    WebMock.disable_net_connect!
+
+    class DocumentationLLM < Phronomy::LLMAdapter::Base
+      protected
+
+      def perform_complete(request, cancellation_token:)
+        previous = request.messages.last
+        if previous&.role == :tool
+          return Phronomy::LLMAdapter::Response.new(content: previous.content)
+        end
 
-  # Patch invoke methods to return canned responses instead of calling the LLM.
-  module Phronomy
-    module Agent
-      # Prepend overrides AsyncEventApi (which is also prepended) so invoke
-      # returns a canned response without triggering the EventLoop.
-      module CiInvokeStub
-        def invoke(input = nil, **)
-          {output: "ci-stub-output", messages: []}
+        search = request.tools.find do |tool|
+          tool.fetch("parameters_schema").fetch("properties", {}).key?("query")
         end
+        if search
+          return Phronomy::LLMAdapter::Response.new(tool_calls: [
+            Phronomy::Tool::CallRequest.new(
+              id: SecureRandom.uuid, name: search.fetch("name"),
+              arguments: {"query" => "Ruby AI frameworks"}
+            )
+          ])
+        end
+
+        Phronomy::LLMAdapter::Response.new(content: "ci-stub-output")
       end
-      Base.prepend(CiInvokeStub)
 
-      class Runner
-        def invoke(input = nil, **)
-          {output: "ci-stub-output", agent: nil, messages: []}
-        end
+      def perform_stream(request, cancellation_token:)
+        response = perform_complete(request, cancellation_token: cancellation_token)
+        yield Phronomy::LLMAdapter::StreamChunk.new(content: response.content) if response.content
+        response
       end
     end
+  RUBY
 
-    module Chain
-      class LLMChain
-        def invoke(vars = {})
-          "ci-stub-chain"
-        end
-      end
+  def self.blocks(path)
+    text = File.read(path)
+    text.to_enum(:scan, /^```ruby runnable\n(.*?)^```/m).map do
+      match = Regexp.last_match
+      [text[0...match.begin(1)].count("\n") + 1, match[1]]
     end
   end
-  # --- end CI preamble ---
-
-RUBY
-
-readme = File.read(README_PATH)
 
-# Match opening fence with 'runnable' annotation: ```ruby runnable
-blocks = readme.scan(/^```ruby runnable\n(.*?)^```/m).map.with_index(1) { |(code), i| [i, code] }
-
-if blocks.empty?
-  puts "No 'ruby runnable' blocks found in README.md."
-  exit 0
-end
-
-puts "Checking #{blocks.size} runnable Ruby block(s) in README.md..."
-
-failures = []
-
-blocks.each do |index, code|
-  Tempfile.create(["readme_runnable_#{index}", ".rb"]) do |f|
-    f.write(PREAMBLE)
-    f.write(code)
-    f.flush
-
-    out, err, status = Open3.capture3(RbConfig.ruby, f.path)
-    combined = (out + err).gsub(f.path, "block ##{index}")
-
-    if status.success?
-      puts "  OK   block ##{index}"
-    else
-      failures << index
-      puts "  FAIL block ##{index}"
-      # Print at most 15 lines of output to keep CI logs readable.
-      puts combined.lines.first(15).join
+  def self.check(paths = PATHS, output: $stdout)
+    failures = []
+    count = 0
+    paths.each do |relative|
+      path = File.expand_path(relative, ROOT)
+      examples = blocks(path)
+      if examples.empty?
+        failures << relative
+        output.puts "FAIL #{relative}: no ruby runnable blocks"
+      end
+      examples.each do |line, code|
+        count += 1
+        label = "#{relative}:#{line}"
+        Tempfile.create(["phronomy_documentation", ".rb"]) do |file|
+          file.write(PREAMBLE)
+          file.write(<<~RUBY)
+            Phronomy.with_configuration do |configuration|
+              configuration.llm_adapter = DocumentationLLM.new
+              begin
+                Timeout.timeout(20) do
+                  eval(#{code.dump}, TOPLEVEL_BINDING, #{path.dump}, #{line})
+                end
+              ensure
+                Phronomy::Runtime.reset_default!(timeout: 5)
+              end
+            end
+          RUBY
+          file.flush
+          out, err, status = Open3.capture3(
+            {"BUNDLE_GEMFILE" => File.join(ROOT, "Gemfile")},
+            RbConfig.ruby, file.path, chdir: ROOT
+          )
+          if status.success?
+            output.puts "OK   #{label}"
+          else
+            failures << label
+            output.puts "FAIL #{label}"
+            output.puts (out + err).gsub(file.path, label).lines.first(15).join
+          end
+        end
+      end
     end
+    output.puts "#{count} runnable examples; #{failures.size} failures"
+    failures.empty?
   end
 end
 
-puts
-if failures.empty?
-  puts "All #{blocks.size} runnable block(s) passed."
-  exit 0
-else
-  puts "#{failures.size} block(s) failed: #{failures.join(", ")}"
-  exit 1
+if $PROGRAM_NAME == __FILE__
+  paths = ARGV.empty? ? RunnableDocumentation::PATHS : ARGV
+  exit(RunnableDocumentation.check(paths) ? 0 : 1)
 end

data/scripts/migrate_generator_verifier_result.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Explicit one-time conversion of a pre-structured-output Result JSON object.
+# Never infer old formats in the runtime reader; never overwrite the source.
+require_relative "../lib/phronomy"
+
+abort "Usage: ruby scripts/migrate_generator_verifier_result.rb OLD.json NEW.json" unless ARGV.length == 2
+source, destination = ARGV
+value = JSON.parse(File.read(source), allow_duplicate_key: false, allow_nan: false,
+  allow_comments: false, allow_invalid_escape: false, allow_control_characters: false)
+abort "Expected an old Result object without failure" unless value.is_a?(Hash) && !value.key?("failure")
+value["failure"] = nil
+result = Phronomy::GeneratorVerifier::Result.from_h(value)
+File.open(destination, File::WRONLY | File::CREAT | File::EXCL) do |file|
+  file.write(JSON.pretty_generate(result.to_h))
+  file.write("\n")
+end

data/sig/phronomy/agent/agent_not_found_error.rbs

@@ -0,0 +1,6 @@
+module Phronomy
+  class AgentNotFoundError < Phronomy::Persistence::NotFoundError
+    attr_reader agent_id: String
+    def initialize: (agent_id: untyped) -> void
+  end
+end

data/sig/phronomy/agent/agent_unloaded_error.rbs

@@ -0,0 +1,6 @@
+module Phronomy
+  class AgentUnloadedError < Phronomy::Error
+    attr_reader agent_id: String
+    def initialize: (agent_id: String) -> void
+  end
+end

data/sig/phronomy/agent/execution_contract.rbs

@@ -2,7 +2,7 @@ module Phronomy
 
   module Agent
     type execution_wiring = { ?phronomy_execution_participant: _ExecutionParticipant, ?phronomy_control_bindings: Array[_ControlCapability], ?phronomy_transfer_context: TransferContext, ?phronomy_admission: _AdmissionOwner, ?phronomy_reservation: Hash[String, json_value] }
-    type execution_result = { agent_id: String, execution_id: String, status: Symbol, result: String?, output: String?, error: Hash[String, json_value]? }
+    type execution_result = { agent_id: String, execution_id: String, status: Symbol, result: json_value, output: json_value, ?raw_output: String?, error: Hash[String, json_value]? }
 
     class ReservedExecution < Data
       attr_reader agent_id: String
@@ -15,12 +15,13 @@ module Phronomy
       attr_reader agent_id: String
       attr_reader execution_id: String
       attr_reader status: Symbol
-      attr_reader result: String?
+      attr_reader result: json_value
+      attr_reader raw_output: String?
       attr_reader error: Hash[String, json_value]?
       attr_reader reservation: ReservedExecution?
       attr_reader transfer_receipt: Hash[String, json_value]?
       attr_reader cancellation_requested: bool
-      def self.new: (agent_id: String, execution_id: String, status: Symbol, result: String?, error: Hash[String, json_value]?, reservation: ReservedExecution?, transfer_receipt: Hash[String, json_value]?, cancellation_requested: bool) -> instance
+      def self.new: (agent_id: String, execution_id: String, status: Symbol, result: json_value, ?raw_output: String?, error: Hash[String, json_value]?, reservation: ReservedExecution?, transfer_receipt: Hash[String, json_value]?, cancellation_requested: bool) -> instance
       def self.from_result: (execution_result) -> instance
       def absent?: () -> bool
       def terminal?: () -> bool

data/sig/phronomy/agent/stream_callback_error.rbs

@@ -0,0 +1,8 @@
+module Phronomy
+  class StreamCallbackError < Error
+    attr_reader event_type: Symbol
+    attr_reader original_error: Exception
+    attr_reader result: untyped
+    def initialize: (event_type: Symbol, original_error: Exception, ?result: untyped, ?code: String?) -> void
+  end
+end

data/sig/phronomy/agent.rbs

@@ -1,5 +1,34 @@
 module Phronomy
   module Agent
+    # The block's TaskResult is awaited and unwrapped; Scope itself is process-local.
+    def self.open_scope: [R] () { (Scope) -> (R | Phronomy::TaskResult[R]) } -> R
+
+    class Scope
+      def release!: () -> bool
+      def create: (singleton(Base) agent_class, **untyped options) ?{ (untyped event) -> void } -> Base
+      def create_async: (singleton(Base) agent_class, **untyped options) ?{ (untyped event) -> void } -> Phronomy::TaskResult[Base]
+      def load: (singleton(Base) agent_class, String agent_id, persistence: Store, **untyped options) ?{ (untyped event) -> void } -> Base
+      def load_async: (singleton(Base) agent_class, String agent_id, persistence: Store, **untyped options) ?{ (untyped event) -> void } -> Phronomy::TaskResult[Base]
+    end
+
+    class ScopeCleanupError < Phronomy::Error
+      attr_reader failures: Array[{ agent_id: String?, error: Exception }]
+      attr_reader result: untyped
+      attr_reader scope: Scope
+      attr_reader primary_error: Exception?
+      def initialize: (scope: Scope, failures: Array[{ agent_id: String?, error: Exception }], ?result: untyped, ?primary_error: Exception?) -> void
+    end
+
+    class OutputError < Phronomy::Error
+      attr_reader execution_id: String
+      attr_reader schema_digest: String
+      attr_reader reason: String
+      attr_reader violations: Array[Hash[String, untyped]]
+      attr_reader raw_output: untyped
+      def initialize: (execution_id: String, schema_digest: String, reason: String | Symbol,
+        ?violations: Array[Hash[String, untyped]], ?raw_output: untyped) -> void
+    end
+
     interface _BeforeLLMInputHook
       def call: (Phronomy::Context::LLMInputBuildContext context) -> Phronomy::Context::LLMInputPatch?
     end
@@ -79,7 +108,7 @@ module Phronomy
       attr_reader persistence: Store
       def knowledge_snapshot: () -> Array[KnowledgeItem]
       def event_listener: () -> (^(Object) -> void)?
-      def start_reserved_async: (reservation: ReservedExecution, input: String, ?config: Hash[Symbol, Object]) -> TaskResult[execution_result]
+      def start_reserved_async: (reservation: ReservedExecution, input: String, ?config: Hash[Symbol, Object], ?output_schema: Hash[String | Symbol, untyped]?) -> TaskResult[execution_result]
       def resume_async: (String execution_id, ?config: Hash[Symbol, Object]) -> TaskResult[execution_result]
       def resume: (String execution_id, ?config: Hash[Symbol, Object]) -> execution_result
       def cancel_async: (String execution_id) -> TaskResult[ExecutionObservation]
@@ -87,10 +116,10 @@ module Phronomy
 
       # Public operation methods no longer accept per-invocation event listeners
       # or event-listener blocks.
-      def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Hash[Symbol, untyped]
-      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> TaskResult[Hash[Symbol, untyped]]
-      def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Hash[Symbol, untyped]
-      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> TaskResult[Hash[Symbol, untyped]]
+      def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?) -> Hash[Symbol, untyped]
+      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?) -> TaskResult[Hash[Symbol, untyped]]
+      def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?) -> Hash[Symbol, untyped]
+      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?) -> TaskResult[Hash[Symbol, untyped]]
 
       def approve: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> untyped
       def approve_async: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> TaskResult[untyped]
@@ -108,6 +137,8 @@ module Phronomy
       def reset_context!: () -> untyped
       def close!: () -> untyped
       def purge!: () -> bool
+      def unload_async: () -> Phronomy::TaskResult[bool]
+      def unload!: (?timeout: Numeric?) -> bool
     end
   end
 end

data/sig/phronomy/embeddings/base.rbs

@@ -6,6 +6,12 @@ module Phronomy
     class TransportError < Phronomy::Error
     end
 
+    class AuthenticationError < TransportError
+    end
+
+    class RateLimitError < TransportError
+    end
+
     class Base
       def embed: (String text, ?_CancellationSignal? cancellation_token) -> Array[Float]
 

data/sig/phronomy/execution/execution.rbs

@@ -30,12 +30,12 @@ module Phronomy
 
   class ExecutionTimeoutError < TimeoutError
     attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
-    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
+    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]], ?code: String?) -> void
   end
 
   class ExecutionCancellationError < CancellationError
     attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
-    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
+    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]], ?code: String?) -> void
   end
 
 end