phronomy 0.29.0 → 0.30.0

data/lib/phronomy/llm_adapter/backends/structured_response_capture.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # RubyLLM 2.0 drops refusal fields when creating streaming Chunk values.
+    # Use its Protocol subclass seam on this operation's Provider only; never
+    # patch global SDK classes or retain an application callback across calls.
+    # @api private
+    class StructuredResponseCapture
+      attr_reader :refusal, :raw_finish_reason
+
+      def bind(chat)
+        capture = self
+        protocols = chat.provider.protocols.transform_values do |base|
+          Class.new(base) do
+            define_method(:build_chunk) do |data|
+              capture.record(data)
+              super(data)
+            end
+          end
+        end.freeze
+        chat.provider.define_singleton_method(:protocols) { protocols }
+      end
+
+      def record(data)
+        choice = data.dig("choices", 0) || {}
+        @raw_finish_reason = choice["finish_reason"] || data.dig("delta", "stop_reason") ||
+          data.dig("candidates", 0, "finishReason") || @raw_finish_reason
+        delta = choice.dig("delta", "refusal")
+        delta ||= data["delta"] if data["type"] == "response.refusal.delta"
+        @refusal = (@refusal || "") + delta if delta.is_a?(String)
+        final = data["response"]
+        return unless final.is_a?(Hash)
+        refusals = Array(final["output"]).flat_map { |item| Array(item["content"]) }
+          .select { |item| item["type"] == "refusal" }.map { |item| item["refusal"] }
+        @refusal = refusals.join("\n") unless refusals.empty?
+        @raw_finish_reason = final.dig("incomplete_details", "reason") || final["status"] || @raw_finish_reason
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/message.rb

@@ -7,6 +7,10 @@ require_relative "../tool/call_request"
 module Phronomy
   module LLMAdapter
     # Provider-independent conversation value, with no executable capabilities.
+    # Metadata is immutable JSON. Backend-owned continuation values travel with
+    # the message through Agent persistence/import; only their owning backend
+    # interprets their format and replay compatibility. They grant no authority
+    # and are not answer content or arbitrary provider request options.
     # @api public
     class Message
       attr_reader :role, :content, :tool_calls, :tool_call_id, :metadata

data/lib/phronomy/llm_adapter/request.rb

@@ -7,10 +7,10 @@ module Phronomy
     # Immutable input for one model turn, including inert Tool definitions.
     # @api public
     class Request
-      attr_reader :model_config, :system, :messages, :tools, :message
+      attr_reader :model_config, :system, :messages, :tools, :message, :response_schema
 
       # @api public
-      def initialize(model_config: {}, system: nil, messages: [], tools: [], message: nil)
+      def initialize(model_config: {}, system: nil, messages: [], tools: [], message: nil, response_schema: nil)
         if !(model_config.is_a?(Hash) && (system.nil? || system.is_a?(String)) && (message.nil? || message.is_a?(String)))
           raise ArgumentError, "invalid LLM request configuration or text"
         end
@@ -36,6 +36,11 @@ module Phronomy
         names = normalized_tools.map { |tool| tool.fetch("name") }
         raise ArgumentError, "duplicate Tool definition name" unless names.uniq == names
         config = normalize_keys(model_config)
+        @response_schema = response_schema.nil? ? nil : Phronomy::Values::Immutable.json(response_schema)
+        if @response_schema && !@response_schema.is_a?(Hash)
+          raise ArgumentError, "response_schema must be a JSON object or nil"
+        end
+        reject_schema_options!(config) if @response_schema
         Phronomy::Values::Immutable.validate_canonical_json!(config, label: "LLM model configuration")
         max = config["max_output_tokens"]
         if !max.nil? && (!max.is_a?(Integer) || max <= 0)
@@ -64,6 +69,16 @@ module Phronomy
 
       private
 
+      def reject_schema_options!(value)
+        return unless value.is_a?(Hash)
+        value.each do |key, child|
+          if %w[schema output_schema response_schema response_format responseJsonSchema responseSchema].include?(key.to_s)
+            raise ArgumentError, "model configuration cannot override response_schema"
+          end
+          reject_schema_options!(child)
+        end
+      end
+
       def normalize_keys(value)
         value.each_with_object({}) do |(key, child), result|
           unless key.is_a?(String) || key.is_a?(Symbol)

data/lib/phronomy/llm_adapter/response.rb

@@ -8,13 +8,20 @@ module Phronomy
     # Completed assistant turn. Tool requests do not authorize execution.
     # @api public
     class Response < Message
-      attr_reader :usage
+      attr_reader :usage, :finish_reason, :refusal
 
       # @api public
-      def initialize(content: nil, tool_calls: [], usage: Phronomy::LLMAdapter::TokenUsage.new, metadata: {}, role: :assistant)
+      def initialize(content: nil, tool_calls: [], usage: Phronomy::LLMAdapter::TokenUsage.new, metadata: {}, role: :assistant,
+        finish_reason: :unknown, refusal: nil)
         raise ArgumentError, "LLM response must be an assistant message" unless role == :assistant || role == "assistant"
         raise ArgumentError, "LLM usage must be LLMAdapter::TokenUsage" unless usage.is_a?(Phronomy::LLMAdapter::TokenUsage)
         @usage = usage
+        unless %w[stop tool_calls length content_filter refusal unknown].include?(finish_reason.to_s)
+          raise ArgumentError, "invalid LLM finish reason"
+        end
+        raise ArgumentError, "refusal must be a String or nil" unless refusal.nil? || refusal.is_a?(String)
+        @finish_reason = finish_reason.to_sym
+        @refusal = refusal&.dup&.freeze
         super(role: :assistant, content: content, tool_calls: tool_calls, metadata: metadata)
       end
 
@@ -24,12 +31,12 @@ module Phronomy
         new(role: source.fetch("role", "assistant"), content: source["content"],
           tool_calls: source.fetch("tool_calls", []).map { |call| Phronomy::Tool::CallRequest.from_h(call) },
           usage: Phronomy::LLMAdapter::TokenUsage.new(**source.fetch("usage", {}).transform_keys(&:to_sym)),
-          metadata: source.fetch("metadata", {}))
+          metadata: source.fetch("metadata", {}), finish_reason: source.fetch("finish_reason", "unknown"), refusal: source["refusal"])
       end
 
       # @api public
       def to_h
-        super.merge("usage" => usage.to_h.transform_keys(&:to_s))
+        super.merge("usage" => usage.to_h.transform_keys(&:to_s), "finish_reason" => finish_reason.to_s, "refusal" => refusal)
       end
     end
   end

data/lib/phronomy/llm_adapter/structured_output_unsupported_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # The selected native schema path cannot implement the requested contract.
+    # @api public
+    class StructuredOutputUnsupportedError < Phronomy::Error
+      # @api public
+      def initialize(message = "Native structured output is unsupported")
+        super(message, code: "llm.structured_output_unsupported")
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/transport_error.rb

@@ -4,6 +4,10 @@ require_relative "../common/error"
 
 module Phronomy
   module LLMAdapter
+    # A provider communication/generation failure. Optional reason code
+    # "llm.provider_output_parse_failed" means the provider rejected its own
+    # generated output format. It is not application JSON/schema validation,
+    # does not imply a particular HTTP status, and does not authorize replay.
     class TransportError < Phronomy::Error; end
   end
 end

data/lib/phronomy/multi_agent/shared_state.rb

@@ -179,6 +179,7 @@ module Phronomy
         # instrumentation.
         instrumented_def = instrumented_definition_for(researcher_class)
         Class.new(researcher_class) do
+          model researcher_class.model
           agent_definition(
             id: instrumented_def.fetch(:id),
             version: instrumented_def.fetch(:version)

data/lib/phronomy/output_parser/json_schema_parser.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+require "json_schemer"
+require "uri"
+require_relative "../common/values/immutable"
+
+module Phronomy
+  module OutputParser
+    # Strict JSON decoding and validation, without extraction or value coercion.
+    # @api public
+    class JsonSchemaParser < Base
+      KEYWORDS = %w[$schema $defs $ref title description type enum const anyOf
+        properties required additionalProperties items minItems maxItems minimum
+        maximum exclusiveMinimum exclusiveMaximum multipleOf minLength maxLength pattern].freeze
+      private_constant :KEYWORDS
+
+      # @api public
+      attr_reader :json_schema
+
+      # @api public
+      def initialize(schema:)
+        @json_schema = Phronomy::Values::Immutable.json(schema)
+        unless @json_schema.is_a?(Hash) && @json_schema["type"] == "object"
+          raise ArgumentError, "output schema must declare a root object"
+        end
+        validate_node!(@json_schema, [])
+        options = {ref_resolver: ->(_uri) { raise ArgumentError, "external output schema reference" }}
+        unless JSONSchemer.valid_schema?(@json_schema, **options)
+          raise ArgumentError, "invalid output JSON Schema"
+        end
+        @validator = JSONSchemer.schema(@json_schema, **options)
+        freeze
+      end
+
+      # @api public
+      def parse(text)
+        value = decode(text)
+        violations = @validator.validate(value).map do |error|
+          {"pointer" => error.fetch("data_pointer", ""),
+           "schema_pointer" => error.fetch("schema_pointer", ""),
+           "keyword" => error.fetch("type", "schema")}
+        end
+        unless violations.empty?
+          raise Phronomy::ParseError.new("Output does not satisfy its JSON schema",
+            code: "output_parser.schema_mismatch", details: violations)
+        end
+        value
+      end
+
+      private
+
+      def decode(text)
+        raise JSON::ParserError, "output must be JSON text" unless text.is_a?(String)
+        Phronomy::Values::Immutable.json(JSON.parse(text, allow_duplicate_key: false, allow_nan: false, allow_comments: false, allow_invalid_escape: false, allow_control_characters: false))
+      rescue JSON::ParserError, ArgumentError
+        raise Phronomy::ParseError.new("Output is not strict JSON",
+          code: "output_parser.invalid_json", details: [{"pointer" => "", "keyword" => "json"}]), cause: nil
+      end
+
+      def validate_node!(node, ancestors)
+        return if node == true || node == false
+        raise ArgumentError, "invalid output schema node" unless node.is_a?(Hash)
+        raise ArgumentError, "cyclic output schema reference" if ancestors.include?(node.object_id)
+        ancestors += [node.object_id]
+        unknown = node.keys - KEYWORDS
+        raise ArgumentError, "unsupported output schema keywords: #{unknown.join(", ")}" unless unknown.empty?
+        if node.key?("$schema") && node["$schema"] != "https://json-schema.org/draft/2020-12/schema"
+          raise ArgumentError, "output schemas require JSON Schema 2020-12"
+        end
+        if node.key?("pattern")
+          raise ArgumentError, "pattern must be a String" unless node["pattern"].is_a?(String)
+          begin
+            Regexp.new(node["pattern"])
+          rescue RegexpError
+            raise ArgumentError, "invalid output schema pattern"
+          end
+        end
+        %w[properties $defs].each do |key|
+          next unless node.key?(key)
+          raise ArgumentError, "#{key} must be an object" unless node[key].is_a?(Hash)
+          node[key].each_value { |child| validate_node!(child, ancestors) }
+        end
+        if node.key?("anyOf")
+          raise ArgumentError, "anyOf must be an array" unless node["anyOf"].is_a?(Array)
+          node["anyOf"].each { |child| validate_node!(child, ancestors) }
+        end
+        %w[items additionalProperties].each do |key|
+          validate_node!(node[key], ancestors) if node.key?(key)
+        end
+        validate_node!(resolve_reference(node["$ref"]), ancestors) if node.key?("$ref")
+      end
+
+      def resolve_reference(reference)
+        valid = reference.is_a?(String) && (reference == "#" || reference.start_with?("#/"))
+        unless valid
+          raise ArgumentError, "output schemas support local JSON Pointer references only"
+        end
+        URI::DEFAULT_PARSER.unescape(reference.delete_prefix("#")).split("/", -1).drop(1).reduce(@json_schema) do |node, token|
+          raise ArgumentError, "invalid output schema JSON Pointer" if token.match?(/~(?![01])/)
+          key = token.gsub("~1", "/").gsub("~0", "~")
+          if node.is_a?(Hash) && node.key?(key)
+            node.fetch(key)
+          elsif node.is_a?(Array) && key.match?(/\A(?:0|[1-9][0-9]*)\z/) && key.to_i < node.length
+            node.fetch(key.to_i)
+          else
+            raise ArgumentError, "output schema reference does not exist"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/output_parser/parse_error.rb

@@ -3,5 +3,14 @@
 require_relative "../common/error"
 
 module Phronomy
-  class ParseError < Error; end
+  class ParseError < Error
+    # @api public
+    attr_reader :details
+
+    # @api public
+    def initialize(message = nil, code: nil, details: [])
+      @details = Phronomy::Values::Immutable.json(details)
+      super(message, code: code)
+    end
+  end
 end

data/lib/phronomy/runtime_composition/agent_defaults.rb

@@ -9,3 +9,7 @@ Phronomy::Agent::DefaultPersistence.install_factory(
 )
 
 Phronomy::Agent::ExecutionEnvironment.install_provider(-> { Phronomy::Agent::EngineEnvironment.new })
+
+Phronomy::Agent::OutputContract.install_factory(
+  ->(schema) { Phronomy::OutputParser::JsonSchemaParser.new(schema: schema) }
+)

data/lib/phronomy/tracing/automatic.rb

@@ -65,23 +65,23 @@ module Phronomy
         # simplecov:enable
       end
 
-      def observe_task(task, name, input: nil, **metadata)
+      def observe_task(task, name, input: nil, usage: nil, **metadata)
         handle = start(name, input: input, **metadata)
         task.on_complete do |value, error|
           finish(
             handle,
             output: value,
-            usage: task_usage(value),
+            usage: observed_usage(usage, value, handle),
             error: error
           )
         end
         task
       end
 
-      def trace(name, input: nil, **metadata)
+      def trace(name, input: nil, usage: nil, **metadata)
         handle = start(name, input: input, **metadata)
         result = yield
-        finish(handle, output: result, usage: task_usage(result))
+        finish(handle, output: result, usage: observed_usage(usage, result, handle))
         result
       rescue => operation_error
         finish(handle, error: operation_error) if defined?(handle)
@@ -122,12 +122,18 @@ module Phronomy
       end
       private_class_method :traced_error
 
-      def task_usage(value)
-        return nil unless value.is_a?(Hash)
+      # The owner of the observed result supplies its projection. Tracing never
+      # interprets Agent results or LLM value objects. Projection is diagnostic:
+      # its failure must not replace the completed operation's result/error.
+      def observed_usage(project, value, handle)
+        return nil unless handle && project
 
-        value[:usage] || value["usage"]
+        project.call(value)
+      rescue => error
+        report_failure(:usage, handle.name, error, include_message: handle.trace_pii)
+        nil
       end
-      private_class_method :task_usage
+      private_class_method :observed_usage
 
       def submit_finish(handle, attributes)
         Phronomy::Blocking.call_async do

data/lib/phronomy/tracing/base.rb

@@ -86,7 +86,8 @@ module Phronomy
       #
       # @param span [Object] the span returned by #start_span
       # @param output [Object, nil] successful output value
-      # @param usage [Phronomy::LLMAdapter::TokenUsage, nil] token usage for this span
+      # @param usage [Hash{Symbol => Integer, nil}, nil] observed token counts;
+      #   :input, :output, :cached, :cache_creation. The caller projects its domain value.
       # @param error [Exception, nil] exception if the block raised
       # @api public
       def finish_span(span, output: nil, usage: nil, error: nil)

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -71,9 +71,9 @@ module Phronomy
         body[:statusMessage] = error.message if error
         if usage
           body[:usage] = {
-            input: usage.input,
-            output: usage.output,
-            total: (usage.input || 0) + (usage.output || 0)
+            input: usage[:input],
+            output: usage[:output],
+            total: (usage[:input] || 0) + (usage[:output] || 0)
           }
         end
         ingest([{type: "span-create", body: body}])

data/lib/phronomy/tracing/observation.rb

@@ -5,7 +5,8 @@ module Phronomy
     module Observation
       # Convenience wrapper that delegates to the global tracer.
       # Yields a span; the block must return [result, usage] where usage is a
-      # Phronomy::LLMAdapter::TokenUsage or nil. Returns only the result value.
+      # Hash of observed token counts or nil. Returns only the result value.
+      # Domain objects must be projected by the caller before entering Tracing.
       #
       # When +trace_pii+ is disabled, both the input and the output (LLM response,
       # tool result) are replaced with the literal string "[REDACTED]" before being

data/lib/phronomy/tracing/open_telemetry_tracer.rb

@@ -44,9 +44,9 @@ module Phronomy
         else
           span.set_attribute("phronomy.output", output.to_s) if output
           if usage
-            span.set_attribute("llm.usage.input_tokens", usage.input)
-            span.set_attribute("llm.usage.output_tokens", usage.output)
-            total = (usage.input || 0) + (usage.output || 0)
+            span.set_attribute("llm.usage.input_tokens", usage[:input])
+            span.set_attribute("llm.usage.output_tokens", usage[:output])
+            total = (usage[:input] || 0) + (usage[:output] || 0)
             span.set_attribute("llm.usage.total_tokens", total)
           end
         end

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.29.0"
+  VERSION = "0.30.0"
 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",
@@ -116,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

@@ -23,6 +23,7 @@ PUBLIC_API_ENTRIES = [
   Phronomy::AgentUnloadedError,
   Phronomy::Agent,
   Phronomy::Agent::Scope,
+  Phronomy::Agent::OutputError,
   Phronomy::Agent::ScopeCleanupError,
   Phronomy::MultiAgent::TeamNotFoundError,
   Phronomy::MultiAgent::TeamBusyError,
@@ -57,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/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/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.rbs

@@ -4,6 +4,7 @@ module Phronomy
     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
@@ -11,9 +12,21 @@ module Phronomy
     end
 
     class ScopeCleanupError < Phronomy::Error
-      attr_reader failures: Array[{ agent_id: String, error: Exception }]
+      attr_reader failures: Array[{ agent_id: String?, error: Exception }]
       attr_reader result: untyped
-      def initialize: (failures: Array[{ agent_id: String, error: Exception }], result: untyped) -> void
+      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
@@ -95,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]
@@ -103,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]

data/sig/phronomy/extensions.rbs

@@ -6,6 +6,11 @@ module Phronomy
   end
 
   module OutputParser
+    class JsonSchemaParser < Base
+      attr_reader json_schema: Hash[String, untyped]
+      def initialize: (schema: Hash[String | Symbol, untyped]) -> void
+      def parse: (String text) -> Hash[String, json_value]
+    end
     class Base
       def parse: (String text) -> untyped
       def invoke: (untyped input, ?config: Hash[untyped, untyped]) -> untyped
@@ -14,10 +19,10 @@ module Phronomy
 
   module Tracing
     class Base
-      def self.trace_with: [A] (untyped tracer, String name, ?record_output: bool, ?attributes: Hash[Symbol, untyped]) { (untyped span) -> [A, untyped] } -> A
+      def self.trace_with: [A] (untyped tracer, String name, ?record_output: bool, ?attributes: Hash[Symbol, untyped]) { (untyped span) -> [A, Hash[Symbol, Integer?]?] } -> A
       def start_span: (String name, **untyped attributes) -> untyped
-      def finish_span: (untyped span, ?output: untyped, ?usage: untyped, ?error: Exception?) -> untyped
-      def trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, untyped] } -> A
+      def finish_span: (untyped span, ?output: untyped, ?usage: Hash[Symbol, Integer?]?, ?error: Exception?) -> untyped
+      def trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, Hash[Symbol, Integer?]?] } -> A
     end
   end