runtype 0.1.0 → 0.2.0

data/lib/runtype/local_tools.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module Runtype
+  # A tool the model can call that executes in this process. Pair a handler
+  # with the schema the server announces to the model, then pass a map of
+  # these to {Runtype::Client#run_with_local_tools}.
+  #
+  #   save_goals = Runtype::LocalTool.new(
+  #     description: "Save the patient's stated goals",
+  #     parameters_schema: { type: "object", properties: { goals: { type: "array", items: { type: "string" } } } }
+  #   ) { |args| Goals.save(args["goals"]); { ok: true } }
+  #
+  # A bare callable (a Proc, lambda, or Method) is also accepted where a
+  # LocalTool is, when the tool is already declared on the saved agent as a
+  # `toolType: "local"` runtime tool and only the handler is needed here.
+  class LocalTool
+    # @return [String]
+    attr_reader :description
+
+    # @return [Hash] JSON Schema for the tool input; must have `type: "object"`.
+    attr_reader :parameters_schema
+
+    # @return [#call] receives the tool arguments as a Hash with String keys.
+    attr_reader :execute
+
+    # @return [String, nil] `"sdk"` (default) or `"webmcp"`.
+    attr_reader :origin
+
+    # @return [String, nil]
+    attr_reader :page_origin
+
+    # @return [Boolean] when true the server wraps this tool's output as
+    #   untrusted content before the model reads it.
+    attr_reader :untrusted_content_hint
+
+    # @param description [String]
+    # @param parameters_schema [Hash]
+    # @param execute [#call, nil] the handler; alternatively pass a block.
+    # @param origin [String, Symbol, nil]
+    # @param page_origin [String, nil]
+    # @param untrusted_content_hint [Boolean]
+    def initialize(description:, parameters_schema:, execute: nil, origin: nil, page_origin: nil,
+                   untrusted_content_hint: false, &block)
+      handler = execute || block
+      raise ArgumentError, "LocalTool needs an execute: callable or a block" unless handler.respond_to?(:call)
+
+      @description = description
+      @parameters_schema = parameters_schema
+      @execute = handler
+      @origin = origin&.to_s
+      @page_origin = page_origin
+      @untrusted_content_hint = untrusted_content_hint ? true : false
+      freeze
+    end
+
+    # The `clientTools[]` entry announcing this tool for one dispatch.
+    #
+    # @param name [String]
+    # @return [Hash]
+    def to_client_tool(name)
+      entry = { name: name, description: description, parametersSchema: parameters_schema }
+      entry[:origin] = origin if origin
+      entry[:pageOrigin] = page_origin if page_origin
+      entry[:untrustedContentHint] = true if untrusted_content_hint
+      entry
+    end
+  end
+
+  # Internals of the local-tool pause/resume loop. Not part of the public API.
+  module LocalTools
+    # The server stamps this reason on every await it expects the dispatching
+    # client to answer with a tool output. Any other reason (an approval, an
+    # MCP elicitation, an A2A input request, a detached or auto-resuming
+    # durable pause) belongs to someone else.
+    LOCAL_TOOL_REASON = "local_tool_required"
+
+    AWAIT_TYPES = %w[await flow_await step_await].freeze
+
+    # One paused local tool call.
+    PausedCall = Struct.new(:tool_name, :tool_call_id, :execution_id, :parameters, keyword_init: true) do
+      # The `toolOutputs` key the server resumes on: the per-call id when the
+      # server sent one (required to tell parallel calls to the same tool
+      # apart), else the tool name.
+      def output_key
+        tool_call_id || tool_name
+      end
+    end
+
+    # The handler map, normalized: name => {LocalTool} or bare callable.
+    class Registry
+      # @param tools [Hash{String, Symbol => Runtype::LocalTool, #call}]
+      def initialize(tools)
+        raise ArgumentError, "run_with_local_tools expects a Hash of tool name => handler" unless tools.is_a?(Hash)
+
+        @tools = tools.to_h do |name, tool|
+          unless tool.is_a?(LocalTool) || tool.respond_to?(:call)
+            raise ArgumentError, "local tool #{name.inspect} must be a Runtype::LocalTool or respond to #call"
+          end
+
+          [name.to_s, tool]
+        end
+      end
+
+      # @return [Array<Hash>] `clientTools[]` entries for every schema-carrying tool.
+      def client_tools
+        @tools.filter_map { |name, tool| tool.to_client_tool(name) if tool.is_a?(LocalTool) }
+      end
+
+      # Looks a handler up by the name the server emitted, then by the bare
+      # name (the server prefixes page-discovered tools with `webmcp:`).
+      #
+      # @param emitted_name [String]
+      # @return [#call, nil]
+      def handler_for(emitted_name)
+        tool = @tools[emitted_name] || @tools[emitted_name.delete_prefix("webmcp:")]
+        tool.is_a?(LocalTool) ? tool.execute : tool
+      end
+
+      # Runs every paused call and returns the `toolOutputs` body for one
+      # resume. A batch of several calls runs concurrently, one thread per
+      # call, as the TypeScript SDK does: the server waits for the whole batch,
+      # so the leg costs the slowest handler, not the sum.
+      #
+      # @param batch [Array<PausedCall>]
+      # @return [Hash{String => Object}]
+      # @raise [Runtype::LocalToolError]
+      def execute(batch)
+        return batch.to_h { |call| [call.output_key, run(call)] } if batch.size <= 1
+
+        threads = batch.map do |call|
+          Thread.new do
+            Thread.current.report_on_exception = false # re-raised from #value below
+            [call.output_key, run(call)]
+          end
+        end
+        threads.to_h(&:value)
+      end
+
+      private
+
+      # @param call [PausedCall]
+      # @return [Object] the handler's output.
+      # @raise [Runtype::LocalToolError]
+      def run(call)
+        handler = handler_for(call.tool_name)
+        unless handler
+          raise Runtype::LocalToolError.new(
+            "Local tool #{call.tool_name.inspect} required but not provided in the tools map",
+            tool_name: call.tool_name
+          )
+        end
+
+        handler.call(call.parameters || {})
+      rescue Runtype::LocalToolError
+        raise
+      rescue StandardError => e
+        raise Runtype::LocalToolError.new(
+          "Error executing local tool #{call.tool_name.inspect}: #{e.message}", tool_name: call.tool_name
+        )
+      end
+    end
+
+    # Folds the `await` frames of one execution leg into the batch of local
+    # tool calls the server is waiting on. A single model turn can request
+    # several parallel calls; the server emits one `await` per call and its
+    # resume endpoint accepts every output in one request.
+    #
+    # One call can arrive as more than one frame (a compatibility
+    # `flow_await` keyed by name, then the unified `await` carrying the call
+    # id), so a later frame with a call id adopts the name-keyed entry rather
+    # than opening a second one.
+    class PauseCollector
+      # @return [String, nil]
+      attr_reader :execution_id
+
+      def initialize
+        @paused = {}
+        @execution_id = nil
+      end
+
+      # @param event [Runtype::Streaming::Event, Hash]
+      # @return [void]
+      def observe(event)
+        data = event.respond_to?(:to_h) ? event.to_h : event
+        return unless data.is_a?(Hash)
+
+        @execution_id ||= present(data["executionId"])
+        return unless local_tool_await?(data)
+
+        name = data["toolName"]
+        call_id = present(data["toolCallId"]) || present(data["modelToolCallId"])
+        key = call_id && @paused.key?(call_id) ? call_id : name
+        previous = @paused.delete(key)
+        @paused[call_id || name] = PausedCall.new(
+          tool_name: name,
+          tool_call_id: call_id || previous&.tool_call_id,
+          execution_id: present(data["executionId"]) || previous&.execution_id || @execution_id,
+          parameters: data.key?("parameters") ? data["parameters"] : previous&.parameters
+        )
+      end
+
+      # Folds a non-streaming `pausedReason` (one call; its `toolId` is the
+      # call id).
+      #
+      # @param paused_reason [Hash]
+      # @return [void]
+      def observe_paused_reason(paused_reason)
+        return unless paused_reason.is_a?(Hash) && paused_reason["type"] == "local_action"
+
+        observe(paused_reason.merge("type" => "await", "toolCallId" => paused_reason["toolId"]))
+      end
+
+      # @return [Array<PausedCall>]
+      def batch
+        @paused.values
+      end
+
+      # @return [Boolean]
+      def paused?
+        !@paused.empty?
+      end
+
+      # The execution every call in the batch belongs to.
+      #
+      # @return [String]
+      # @raise [Runtype::LocalToolError] when no frame carried an execution id.
+      def batch_execution_id
+        id = @paused.values.map(&:execution_id).compact.first || @execution_id
+        raise Runtype::LocalToolError, "The execution paused on a local tool without an executionId" if id.nil?
+
+        id
+      end
+
+      private
+
+      # An await this process answers with a tool output: a named tool, no
+      # approval or elicitation attached, and either the server's explicit
+      # local-tool reason or (on compatibility frames) no reason at all.
+      #
+      # @param data [Hash]
+      # @return [Boolean]
+      def local_tool_await?(data)
+        return false unless AWAIT_TYPES.include?(data["type"])
+        return false unless present(data["toolName"])
+        return false if data["approvalId"] || data["elicitation"]
+
+        reason = present(data["awaitReason"])
+        reason.nil? || reason == LOCAL_TOOL_REASON
+      end
+
+      # @param value [Object]
+      # @return [String, nil] the value when it is a non-empty String.
+      def present(value)
+        value.is_a?(String) && !value.empty? ? value : nil
+      end
+    end
+  end
+end

data/lib/runtype/sdk_version.rb

@@ -8,7 +8,7 @@ module Runtype
   # generator). The generated barrel does not require that file, so nothing
   # collides today, but re-declaring it here would make the overlay's version
   # depend on generator require order.
-  SDK_VERSION = "0.1.0"
+  SDK_VERSION = "0.2.0"
 
   # Outbound User-Agent identifying the SDK kind, version, and language, e.g.
   # "runtype-sdk/0.1.0 (ruby)". The `runtype-sdk/` prefix is what the API's

data/lib/runtype.rb

@@ -18,7 +18,7 @@
 #   require "runtype"
 #
 #   client = Runtype::Client.new(api_key: ENV["RUNTYPE_API_KEY"])
-#   client.dispatch_stream(agent: { id: "agt_123" }, messages: [...]) do |event|
+#   client.dispatch_stream(agent: { agentId: "agent_123" }, messages: [...]) do |event|
 #     print event["delta"] if event.type == "text_delta"
 #   end
 require_relative "../generated/lib/runtype"
@@ -30,6 +30,11 @@ require_relative "runtype/streaming/line_decoder"
 require_relative "runtype/streaming/event_parser"
 require_relative "runtype/streaming/connection"
 require_relative "runtype/streaming/event_stream"
+require_relative "runtype/canonical_json"
+require_relative "runtype/agent_definition"
+require_relative "runtype/agent_ensure"
+require_relative "runtype/local_tools"
+require_relative "runtype/local_tool_runner"
 require_relative "runtype/client"
 
 module Runtype

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runtype
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Runtype Labs
@@ -1430,6 +1430,7 @@ files:
 - generated/lib/runtype/model_configs/types/post_v1model_configs_request_settings_custom_model.rb
 - generated/lib/runtype/model_configs/types/post_v1model_configs_request_settings_custom_model_executor_config.rb
 - generated/lib/runtype/model_configs/types/post_v1model_configs_request_settings_custom_model_executor_provider.rb
+- generated/lib/runtype/model_configs/types/post_v1model_configs_request_settings_custom_model_reasoning.rb
 - generated/lib/runtype/model_configs/types/post_v1model_configs_response.rb
 - generated/lib/runtype/model_configs/types/post_v1model_configs_response_configuration_status.rb
 - generated/lib/runtype/model_configs/types/post_v1model_configs_response_key_status.rb
@@ -1443,6 +1444,7 @@ files:
 - generated/lib/runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model.rb
 - generated/lib/runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model_executor_config.rb
 - generated/lib/runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model_executor_provider.rb
+- generated/lib/runtype/model_configs/types/put_v1model_configs_id_request_settings_custom_model_reasoning.rb
 - generated/lib/runtype/model_configs/types/put_v1model_configs_id_response.rb
 - generated/lib/runtype/model_configs/types/put_v1model_configs_id_response_configuration_status.rb
 - generated/lib/runtype/model_configs/types/put_v1model_configs_id_response_key_status.rb
@@ -1778,6 +1780,7 @@ files:
 - generated/lib/runtype/provider_keys/types/post_v1provider_keys_id_discover_models_response_models_item.rb
 - generated/lib/runtype/provider_keys/types/post_v1provider_keys_id_sync_models_request.rb
 - generated/lib/runtype/provider_keys/types/post_v1provider_keys_id_sync_models_request_models_item.rb
+- generated/lib/runtype/provider_keys/types/post_v1provider_keys_id_sync_models_request_models_item_reasoning.rb
 - generated/lib/runtype/provider_keys/types/post_v1provider_keys_id_sync_models_response.rb
 - generated/lib/runtype/provider_keys/types/post_v1provider_keys_request.rb
 - generated/lib/runtype/provider_keys/types/post_v1provider_keys_request_provider.rb
@@ -2732,8 +2735,13 @@ files:
 - generated/lib/runtype/webhook_management/types/put_v1products_id_surfaces_surface_id_webhook_routing_request.rb
 - generated/lib/runtype/webhook_management/types/put_v1products_id_surfaces_surface_id_webhook_routing_response.rb
 - lib/runtype.rb
+- lib/runtype/agent_definition.rb
+- lib/runtype/agent_ensure.rb
+- lib/runtype/canonical_json.rb
 - lib/runtype/client.rb
 - lib/runtype/errors.rb
+- lib/runtype/local_tool_runner.rb
+- lib/runtype/local_tools.rb
 - lib/runtype/sdk_version.rb
 - lib/runtype/streaming/connection.rb
 - lib/runtype/streaming/event.rb
@@ -2765,7 +2773,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby SDK for the Runtype AI product platform
 test_files: []