openai 0.89.0 → 0.91.0

data/examples/realtime/browser/server.rb

@@ -0,0 +1,281 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "timeout"
+require "uri"
+
+require_relative "../../../lib/openai"
+require_relative "../sideband"
+
+module OpenAI::Examples::Realtime
+  # Single-operator, loopback-only application. This is not SDK runtime code.
+  class BrowserApp
+    class Rejected < StandardError
+      attr_reader :status
+      def initialize(status)
+        @status = status
+        super("Request rejected")
+      end
+    end
+
+    ASSETS = {
+      "/" => ["index.html", "text/html"],
+      "/direct" => ["index.html", "text/html"],
+      "/backend" => ["index.html", "text/html"],
+      "/peer.js" => ["peer.js", "text/javascript"],
+      "/page.js" => ["page.js", "text/javascript"]
+    }.freeze
+
+    def initialize(
+      client:,
+      token:,
+      port: 9292,
+      model: "gpt-realtime-2.1",
+      sideband: false,
+      manual_turns: false,
+      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
+      output: $stderr
+    )
+      raise ArgumentError, "Use an application token of at least 32 characters" if token.bytesize < 32
+      @client, @token, @model, @sideband = client, token, model, sideband
+      @manual_turns = manual_turns
+      @origin = URI::HTTP.build(host: "127.0.0.1", port: port).to_s
+      @authority = @origin.delete_prefix("http://")
+      @clock, @output = clock, output
+      @mutex = Mutex.new
+      @call = nil
+      @cancelled = {}
+      @next_create = 0
+      @closing = false
+    end
+
+    def service(request, response)
+      response["Cache-Control"] = "no-store"
+      response["Referrer-Policy"] = "no-referrer"
+      response["X-Content-Type-Options"] = "nosniff"
+      response["Cross-Origin-Resource-Policy"] = "same-origin"
+      response["Permissions-Policy"] = "microphone=(self), camera=()"
+      response["Content-Security-Policy"] = "default-src 'none'; script-src 'self'; connect-src 'self' https://api.openai.com; media-src 'self' blob:; base-uri 'none'; frame-ancestors 'none'; form-action 'none'"
+      raise Rejected.new(403) unless request["host"] == @authority
+
+      if request.request_method == "GET" && ASSETS.key?(request.path)
+        file, content_type = ASSETS.fetch(request.path)
+        response["Content-Type"] = content_type
+        response.body = File.read(File.join(__dir__, file))
+        return
+      end
+
+      authenticate!(request)
+      @mutex.synchronize do
+        raise Rejected.new(503) if @closing
+        dispatch(request, response)
+      end
+
+    rescue Rejected => e
+      response.status = e.status
+      response.body = "Request rejected."
+    rescue StandardError
+      response.status = 502
+      response.body = "Signaling failed."
+      @output.puts("[browser] signaling failed")
+    end
+
+    # Called by the server timer even when the browser disappears without Stop.
+    def reap
+      @mutex.synchronize { cleanup if @call && @clock.call >= @call.fetch(:deadline) }
+    end
+
+    def shutdown
+      @mutex.synchronize do
+        @closing = true
+        cleanup if @call
+      end
+    end
+
+    private
+
+    def authenticate!(request)
+      raise Rejected.new(405) unless request.request_method == "POST"
+      raise Rejected.new(403) unless request["origin"] == @origin
+      expected = Digest::SHA256.digest("Bearer #{@token}")
+      supplied = Digest::SHA256.digest(request["authorization"].to_s)
+      difference = expected.bytes.zip(supplied.bytes).reduce(0) { |memo, (a, b)| memo | (a ^ b) }
+      raise Rejected.new(401) unless difference.zero?
+    end
+
+    def dispatch(request, response)
+      response["Content-Type"] = "application/json"
+      case request.path
+      when "/api/secret"
+        rate_limit!
+        secret = @client.realtime.client_secrets.create(
+          expires_after: {anchor: :created_at, seconds: 30},
+          session: session,
+          request_options: creation_options
+        )
+        # No call exists on this backend. Failed delivery leaves a secret which
+        # expires; there is no public secret revocation endpoint to invent here.
+        response.body = JSON.generate({value: secret.value})
+      when "/api/calls"
+        raise Rejected.new(415) unless request["content-type"] == "application/sdp"
+        id = operation_id(request)
+        raise Rejected.new(409) if @call || @cancelled.include?(id)
+        rate_limit!
+        create_call(id, request.body.to_s, response)
+      when "/api/ack", "/api/renew"
+        owned_call!(request)
+        raise Rejected.new(409) if @call[:ending] || @clock.call >= @call[:deadline]
+        raise Rejected.new(409) if request.path == "/api/renew" && !@call[:acknowledged]
+        @call[:acknowledged] = true
+        @call[:deadline] = @clock.call + 60
+        response.body = "{}"
+      when "/api/stop"
+        # Only application operation IDs are accepted, never browser call IDs.
+        id = operation_id(request)
+        # A Stop can overtake its create on another HTTP connection. Retain the
+        # cancellation for this process lifetime; never allocate that ID later.
+        @cancelled[id] = true
+        if @call && @call[:id] == id
+          cleanup
+          raise Rejected.new(503) if @call
+        end
+
+        response.body = "{}"
+      else
+        raise Rejected.new(404)
+      end
+    end
+
+    def session
+      config = {type: :realtime, model: @model, instructions: "Keep answers short.", max_output_tokens: 128, tools: []}
+      config[:audio] = {input: {turn_detection: nil}} if @manual_turns
+      config
+    end
+
+    def creation_options
+      {
+        timeout: 15,
+        max_retries: 0,
+        extra_headers: {"OpenAI-Safety-Identifier" => Digest::SHA256.hexdigest(@token)}
+      }
+    end
+
+    def rate_limit!
+      raise Rejected.new(429) if @clock.call < @next_create
+      @next_create = @clock.call + 5
+    end
+
+    def operation_id(request)
+      id = request["x-operation-id"].to_s
+      raise Rejected.new(400) unless /\A[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}\z/.match?(id)
+      id
+    end
+
+    def owned_call!(request)
+      raise Rejected.new(404) unless @call && @call[:id] == operation_id(request)
+    end
+
+    def create_call(id, offer, response)
+      # Shipped SDK owns allocation/response buffering until this returns. Do not
+      # duplicate its interrupted-creation cleanup or retry uncertain creates.
+      result = @client.realtime.calls.create(sdp: offer, session: session, request_options: creation_options)
+      call_id = call_id_from_location(result.headers["location"])
+      raise "Creation returned no usable call identifier" unless call_id
+      @call = {id: id, call_id: call_id, deadline: @clock.call + 20}
+      begin
+        answer = result.body.to_a.join
+        if @sideband
+          Timeout.timeout(15) do
+            Sideband.run(client: @client, call_id: call_id, instructions: "Keep answers short.", output: @output)
+          end
+        end
+
+        payload = JSON.generate({sdp: answer})
+        @call[:deadline] = @clock.call + 20
+        response.chunked = true
+        response.body = proc do |socket|
+          begin
+            socket.write(payload)
+          rescue StandardError
+            @mutex.synchronize { cleanup if @call && @call[:id] == id }
+            raise
+          end
+        end
+      rescue StandardError
+        cleanup
+        raise
+      end
+    end
+
+    def call_id_from_location(location)
+      return unless location.is_a?(String)
+      url = URI.join("https://api.openai.com/v1/realtime/calls", location)
+      return unless url.scheme == "https" && url.host == "api.openai.com" && url.port == 443
+      return if url.userinfo || url.query || url.fragment
+      %r{\A/v1/realtime/calls/([A-Za-z0-9_-]+)\z}.match(url.path)&.captures&.first
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def cleanup
+      @call[:ending] = true
+      Timeout.timeout(5) do
+        @client.realtime.calls.hangup(@call.fetch(:call_id), request_options: {timeout: 5, max_retries: 0})
+      end
+
+      @call = nil
+      @output.puts("[browser] call released")
+    rescue OpenAI::Errors::NotFoundError
+      @call = nil
+      @output.puts("[browser] call released")
+    rescue StandardError
+      @call[:deadline] = @clock.call + 5
+      @output.puts("[browser] hangup failed; retry pending")
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  require "webrick"
+
+  port = Integer(ENV.fetch("PORT", "9292"))
+  app = OpenAI::Examples::Realtime::BrowserApp.new(
+    client: OpenAI::Client.new(
+      api_key: ENV.fetch("OPENAI_API_KEY"),
+      base_url: "https://api.openai.com/v1",
+      max_retries: 0
+    ),
+    token: ENV.fetch("BROWSER_APP_TOKEN"),
+    port: port,
+    model: ENV.fetch("OPENAI_REALTIME_MODEL", "gpt-realtime-2.1"),
+    sideband: ENV["BROWSER_SIDEBAND"] == "1",
+    manual_turns: ENV["BROWSER_MANUAL_TURNS"] == "1"
+  )
+  # Suppress HTTP logs: they can contain bearer credentials, SDP, or paths.
+  server = WEBrick::HTTPServer.new(
+    BindAddress: "127.0.0.1",
+    Port: port,
+    AccessLog: [],
+    Logger: WEBrick::Log.new(File::NULL),
+    RequestTimeout: 20
+  )
+  server.mount_proc("/") { |request, response| app.service(request, response) }
+  %w[INT TERM].each { |signal| Signal.trap(signal) { server.shutdown } }
+  sweeper = Thread.new do
+    loop do
+      sleep(1)
+      app.reap
+    end
+  end
+
+  begin
+    warn("[browser] ready http://127.0.0.1:#{port}/direct and /backend")
+    server.start
+  ensure
+    sweeper.kill
+    sweeper.join
+    app.shutdown
+  end
+end

data/examples/responses/websocket_workflows.rb

@@ -68,19 +68,79 @@ module OpenAI
         end
       end
 
+      def session_limits
+        # Application budgets for these short text examples, not service limits.
+        OpenAI::Responses::SessionLimits.new(
+          max_lanes: 8,
+          max_events_per_lane: 128,
+          max_events: 512,
+          max_bytes_per_lane: 16 * 1024 * 1024,
+          max_bytes: 32 * 1024 * 1024,
+          max_response_bytes: 64 * 1024 * 1024
+        )
+      end
+
       def multiplex(client:, model:)
-        client.responses.connect do |connection|
-          %w[planner critic].each do |lane|
-            connection.response.create(
+        OpenAI::Responses::Session.open(client: client, limits: session_limits) do |session|
+          lanes = %w[planner critic].to_h { |name| [name, session.lane(name)] }
+          lanes.each_value do |lane|
+            lane.send_event(
+              type: :"response.create",
               model: model,
-              input: "Say hello as the #{lane}.",
-              stream_id: lane,
+              input: "Say hello as the #{lane.stream_id}.",
               store: false
             )
           end
 
-          completed_responses(connection, lanes: %w[planner critic])
+          results = Thread::Queue.new
+          readers = []
+          begin
+            readers <<
+              Async::Task.current.async do
+                loop do
+                  event = session.default.receive
+                  next unless event.type.to_s == "error"
+
+                  results.push(OpenAI::Responses::RequestError.new(event))
+                  break
+                end
+
+              rescue StandardError
+                # Named readers report connection failure, or drain terminal
+                # responses already queued before a normal connection close.
+                nil
+              end
+            lanes.each do |name, lane|
+              readers <<
+                Async::Task.current.async do
+                  response = lane.get_final_response
+                  unless response.status.to_s == "completed"
+                    raise("Responses WebSocket operation did not complete.")
+                  end
+
+                  results.push([name, response])
+                rescue StandardError => error
+                  results.push(error)
+                end
+            end
+
+            lanes.length.times.to_h do
+              result = results.pop
+              raise result if result.is_a?(StandardError)
+
+              result
+            end
+
+          ensure
+            readers.each(&:stop)
+            readers.each(&:wait)
+          end
         end
+
+      rescue OpenAI::Responses::RequestError
+        raise "Responses WebSocket operation did not complete."
+      rescue OpenAI::Responses::SessionError
+        raise "Responses WebSocket closed with unfinished work."
       end
 
       # Deliberately rotate a healthy connection after a completed turn. This does

data/lib/openai/auth/workload_identity.rb

@@ -30,7 +30,11 @@ module OpenAI
         @identity_provider_id = identity_provider_id.to_s
         @service_account_id = service_account_id.to_s
         @provider = provider
-        @refresh_buffer_seconds = refresh_buffer_seconds.to_i
+        @refresh_buffer_seconds = if refresh_buffer_seconds.is_a?(String)
+          Integer(refresh_buffer_seconds, 10)
+        else
+          Integer(refresh_buffer_seconds)
+        end
       end
     end
   end

data/lib/openai/auth/workload_identity_auth.rb

@@ -353,7 +353,7 @@ module OpenAI
         in Net::HTTPBadRequest | Net::HTTPUnauthorized | Net::HTTPForbidden
           raise(
             OpenAI::Errors::OAuthError.new(
-              status: response.code.to_i,
+              status: Integer(response.code, 10),
               body: body,
               headers: response.each_header.to_h
             )
@@ -367,7 +367,7 @@ module OpenAI
           raise(
             OpenAI::Errors::APIError.new(
               url: @token_exchange_url,
-              status: response.code.to_i,
+              status: Integer(response.code, 10),
               headers: response.each_header.to_h,
               body: body,
               message: "Token exchange failed with status #{response.code}"

data/lib/openai/auth/x509_token_exchange.rb

@@ -149,7 +149,7 @@ module OpenAI
           raise invalid_response("expires_in must be greater than zero and at most one hour", response: response)
         end
 
-        {id: token, expires_in: expires_in.to_f}
+        {id: token, expires_in: Float(expires_in)}
       end
 
       private def raise_error(response, body)

data/lib/openai/helpers/agents/message.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Beta
+      class AgentSessionMessage
+        # Concatenate output-text blocks in message order, without fetching or
+        # filtering by phase. Reading this method does not change serialization.
+        # @return [String]
+        def output_text
+          content
+            .filter_map do |part|
+              (part[:text] || part["text"]) if (part[:type] || part["type"]).to_s == "output_text"
+            end
+            .join
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/agents/session_stream.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "tools"
+
+module OpenAI
+  module Helpers
+    module Agents
+      # Stream one turn on an idle session. The caller must be its only input writer
+      # until iteration ends, because input submission does not return a turn ID.
+      # Use a block or ensure #close when abandoning external iteration.
+      # Closing the connection does not cancel the backend turn.
+      class SessionStream
+        include Enumerable
+
+        # @api private
+        def initialize(sessions:, session_id:, input:, tool_handlers: {}, idempotency_key: nil, request_options: {})
+          messages = input.is_a?(String) ? [{role: :user, content: [{type: :input_text, text: input}]}] : input.to_a
+          raise ArgumentError, "input must not be empty" if input == "" || messages.empty?
+
+          @sessions = sessions
+          @session_id = session_id
+          @handlers = tool_handlers.to_h.dup
+          @options = request_options.to_h.dup
+          headers = {"OpenAI-Beta" => "agents=v1"}.merge(@options[:extra_headers].to_h)
+          options_key = @options.delete(:idempotency_key)
+          input_key = idempotency_key || options_key || SecureRandom.uuid
+          headers.delete_if do |key, value|
+            match = key.to_s.casecmp?("idempotency-key")
+            input_key = value if match
+            match
+          end
+
+          @options[:extra_headers] = headers
+          @recent_events = {}
+          @handled_calls = {}
+          @closed = false
+          session = @sessions.retrieve(@session_id, request_options: @options)
+          unless session.status == :idle
+            raise(
+              ArgumentError,
+              "sessions.stream requires an idle session; use sessions.events.stream_streaming to follow an active session"
+            )
+          end
+
+          @raw_stream = @sessions.events.stream_streaming(@session_id, request_options: @options)
+          begin
+            @sessions.events.create(
+              @session_id,
+              events: [{type: :"agent.session.input.message", input: messages}],
+              idempotency_key: input_key,
+              request_options: @options
+            )
+            @iterator = iterator
+            submitted = true
+          ensure
+            close unless submitted
+          end
+        end
+
+        # Yields the original typed events. Registered handlers run sequentially after
+        # their function-call event is yielded; unknown tools remain caller-managed.
+        # @yieldparam event [OpenAI::Models::Beta::AgentSessionEvent]
+        # @return [Enumerator, self]
+        def each
+          return enum_for(:each) unless block_given?
+          return self if @closed
+          begin
+            loop do
+              break if @closed
+              yield @iterator.next
+            end
+
+          ensure
+            close
+          end
+
+          self
+        end
+
+        # Consume remaining events and registered tool calls.
+        # @return [self]
+        def until_done
+          each { |_event| nil }
+          self
+        end
+
+        # Close the event connection without cancelling the backend turn.
+        # @return [void]
+        def close
+          return if @closed
+
+          @closed = true
+          @raw_stream&.close
+        end
+
+        private
+
+        def iterator
+          Enumerator.new do |yielder|
+            begin
+              @raw_stream.each do |event|
+                next unless accept?(event)
+
+                terminal = event.type == :"agent.session.failed" ||
+                  (event.type == :"agent.session.idle" && @turn_ended)
+                invocation = prepare_call(event) unless terminal
+                close if terminal
+                yielder << event
+                break if terminal || @closed
+
+                dispatch(invocation.call) if invocation
+              end
+
+              raise RuntimeError, "Session event stream ended before the turn reached idle or failed" unless @closed
+            ensure
+              close
+            end
+          end
+        end
+
+        def accept?(event)
+          return false if @recent_events.key?(event.event_id)
+
+          @recent_events.shift if @recent_events.size == 1024
+          @recent_events[event.event_id] = true
+          case event.type
+          when :"agent.session.turn.created"
+            @turn_id ||= event.turn_id.dup if event.turn.subagent_id.nil?
+          when :"agent.session.turn.completed", :"agent.session.turn.failed", :"agent.session.turn.cancelled"
+            @turn_ended = true if @turn_id && event.turn_id == @turn_id
+          end
+
+          true
+        end
+
+        def prepare_call(event)
+          return unless event.type == :"agent.session.turn.item.added" && event.item.type == :function_call
+
+          call = event.item
+          key = [call.turn_id.dup, call.call_id.dup]
+          return if @handled_calls.key?(key)
+
+          @handled_calls[key] = true
+          handler = @handlers[call.name]
+          return unless handler
+
+          Tools.prepare(call, handler)
+        end
+
+        def dispatch(result)
+          idempotency_key = SecureRandom.uuid
+          delays = [0.1, 0.3, 0.6]
+          begin
+            @sessions
+              .events
+              .create(@session_id, events: [result], idempotency_key: idempotency_key, request_options: @options)
+          rescue OpenAI::Errors::BadRequestError => error
+            delay = delays.shift
+            raise unless delay && Tools.pending_call_race?(error, result[:call_id])
+
+            sleep(delay)
+            retry
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/agents/tools.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Agents
+      # @api private
+      module Tools
+        # Capture routing and detached arguments before caller code sees the event,
+        # but defer the application callback until iteration resumes after yielding it.
+        def self.prepare(call, handler)
+          base = {type: :"agent.session.input.tool_result", turn_id: call.turn_id.dup, call_id: call.call_id.dup}
+          arguments = begin
+            JSON.parse(call.arguments.is_a?(String) ? call.arguments : JSON.generate(call.arguments))
+          rescue StandardError
+            nil
+          end
+
+          lambda do
+            begin
+              raise ArgumentError, "Function arguments must be a JSON object" unless arguments.is_a?(Hash)
+
+              output = handler.call(arguments)
+              output = JSON.generate(output) if output.is_a?(Hash)
+              unless output.nil? || output.is_a?(String) || output.is_a?(Array)
+                raise ArgumentError, "Tool output must be a string, object, content array, or nil"
+              end
+
+              serialized = JSON.generate(output)
+              if output.is_a?(Array) && !content_output?(JSON.parse(serialized))
+                raise ArgumentError, "Tool output array must contain input text or image content"
+              end
+
+              base.merge(success: true, output: output)
+            rescue StandardError
+              base.merge(success: false, error: "Tool handler failed.")
+            end
+          end
+        end
+
+        def self.content_output?(parts)
+          parts.all? do |part|
+            next false unless part.is_a?(Hash)
+
+            case part["type"]
+            when "input_text"
+              part["text"].is_a?(String)
+            when "input_image"
+              part["image_url"].is_a?(String)
+            else
+              false
+            end
+          end
+        end
+
+        def self.pending_call_race?(error, call_id)
+          body = error.body
+          body = body[:error] if body.is_a?(Hash) && body[:error].is_a?(Hash)
+          body.is_a?(Hash) &&
+            body[:code] == "invalid_request_error" &&
+            body[:message] == "Unknown pending tool call: #{call_id}"
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/local_audio/process.rb

@@ -33,7 +33,7 @@ module OpenAI
           raise ArgumentError, "#{name} must be a positive finite number of seconds"
         end
 
-        result = value.to_f
+        result = Float(value)
         raise ArgumentError, "#{name} is not representable" unless result.finite?
         result
       end

data/lib/openai/helpers/responses_websocket/connection.rb

@@ -154,7 +154,8 @@ module OpenAI
         data
       end
 
-      private def encode_client_event(event)
+      # @api private
+      def encode_client_event(event)
         validate_event_tree!(event)
         payload = if event.is_a?(Hash)
           OpenAI::Internal::Type::Unknown.dump(event, state: {can_retry: true})