runtype 0.1.0 → 0.2.0

data/lib/runtype/agent_ensure.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Runtype
+  # Agent config-as-code on {Runtype::Client}: converge a repo-owned
+  # {AgentDefinition} onto the platform (`POST /v1/agents/ensure`) and pull the
+  # platform's definition back (`GET /v1/agents/pull`). Protocol:
+  # `docs/adr/0003-agent-config-as-code-ensure.md`.
+  module AgentEnsure
+    # Idempotently makes the platform's definition of this agent match
+    # `definition`. Identity is the agent name within the API key's account
+    # scope. Hash-first: probes with the local content hash and only ships the
+    # full definition when the server reports a miss. Every change appends an
+    # immutable version; nothing is ever deleted. Non-executing.
+    #
+    # @param definition [Runtype::AgentDefinition, Hash] see {Runtype.define_agent}.
+    # @param dry_run [Boolean] plan without writing (the CI drift gate).
+    # @param expect_no_changes [Boolean] implies `dry_run`; raises
+    #   {Runtype::DriftError} unless the plan is `"none"`.
+    # @param on_conflict [String, Symbol, nil] `"error"` (default: 409 when the
+    #   agent's last write came from the dashboard/API/MCP) or `"overwrite"`.
+    # @param release [String, Symbol, nil] `"publish"` also re-aims the
+    #   published-version pointer; default `"none"`.
+    # @param expected_remote_hash [String, nil] binds a dry run to its apply:
+    #   the write proceeds only if the remote still hashes to this value.
+    # @param request_options [Hash] see {Runtype::Client#dispatch}.
+    # @return [Hash] `{"result" => "unchanged"|"created"|"updated", "agentId",
+    #   "versionId", "contentHash"}`, or for a dry run `{"result" => "plan",
+    #   "changes" => "none"|"create"|"update", "changedKeys", "contentHash", ...}`.
+    #   `contentHash` is always the server-computed canonical hash.
+    # @raise [Runtype::EnsureConflictError] on a 409 (`external_modification`
+    #   or `remote_changed`).
+    # @raise [Runtype::DriftError] with `expect_no_changes:` when the plan is
+    #   not `"none"`.
+    def ensure_agent(definition, dry_run: false, expect_no_changes: false, on_conflict: nil, release: nil,
+                     expected_remote_hash: nil, request_options: {})
+      definition = Runtype::AgentDefinition.from(definition)
+      passthrough = {
+        onConflict: on_conflict&.to_s,
+        release: release&.to_s,
+        expectedRemoteHash: expected_remote_hash
+      }.compact
+
+      if dry_run || expect_no_changes
+        plan = ensure_request(
+          { name: definition.name, definition: definition.to_h, dryRun: true, **passthrough }, request_options
+        )
+        unless plan["result"] == "plan"
+          raise Runtype::Error, "Expected a plan result from dryRun, got #{plan["result"].inspect}"
+        end
+        raise Runtype::DriftError.new(plan, name: definition.name) if expect_no_changes && plan["changes"] != "none"
+
+        return plan
+      end
+
+      local_hash = definition.content_hash
+      memo_key = "#{definition.name}:#{local_hash}"
+      content_hash = ensure_memo[memo_key] || local_hash
+
+      probe = ensure_request({ name: definition.name, contentHash: content_hash, **passthrough }, request_options)
+      return memoize_ensure(memo_key, probe) unless probe["result"] == "definitionRequired"
+
+      converged = ensure_request({ name: definition.name, definition: definition.to_h, **passthrough }, request_options)
+      if converged["result"] == "definitionRequired"
+        raise Runtype::Error, "Server reported definitionRequired for a full-definition request"
+      end
+
+      memoize_ensure(memo_key, converged)
+    end
+
+    # The canonical definition and provenance of an agent by name — the
+    # absorb-drift direction. `contentHash` reflects the live agent state.
+    #
+    # @param name [String]
+    # @param request_options [Hash]
+    # @return [Hash] `{"agentId", "definition" => {...}, "contentHash",
+    #   "lastModifiedSource", "updatedAt", "versionId", "warnings"?}`.
+    # @raise [Runtype::NotFoundError] when no agent by that name is in scope.
+    def pull_agent(name, request_options: {})
+      get_json("v1/agents/pull", { name: name }, request_options)
+    end
+
+    private
+
+    # @return [Hash{String => String}] `name:localHash` => server hash, so a
+    #   hot process pays the probe once per definition.
+    def ensure_memo
+      @ensure_memo ||= {}
+    end
+
+    # @param memo_key [String]
+    # @param result [Hash]
+    # @return [Hash] the result, for chaining.
+    def memoize_ensure(memo_key, result)
+      ensure_memo[memo_key] = result["contentHash"] if result["result"] != "plan" && result["contentHash"]
+      result
+    end
+
+    # @return [Hash] the decoded response body.
+    # @raise [Runtype::EnsureConflictError] for the protocol's two 409 shapes.
+    def ensure_request(body, request_options)
+      post_json("v1/agents/ensure", body, request_options)
+    rescue Runtype::APIStatusError => e
+      raise Runtype::EnsureConflictError.from_status_error(e) if Runtype::EnsureConflictError.protocol_conflict?(e)
+
+      raise
+    end
+  end
+end

data/lib/runtype/canonical_json.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Runtype
+  # Serializes a value exactly as JavaScript's `JSON.stringify` would, so a
+  # SHA-256 over the result matches the hash the TypeScript SDK and the API
+  # compute for the same definition (the content hash is a wire contract; see
+  # `docs/adr/0003-agent-config-as-code-ensure.md`).
+  #
+  # Ruby's `JSON.generate` already agrees with `JSON.stringify` on strings,
+  # booleans, nil, arrays and objects. Numbers are the exception: Ruby prints
+  # `1.0` where JavaScript prints `1`, and switches to exponent notation at
+  # different magnitudes (`1.0e-05` vs `0.00001`). This module renders numbers
+  # with the ECMA-262 `Number::toString` rules over Ruby's shortest round-trip
+  # digits, which are the same digits V8 picks.
+  module CanonicalJSON
+    module_function
+
+    # @param value [Object] a JSON-compatible value (Hash, Array, String,
+    #   Numeric, true, false, nil).
+    # @return [String] the canonical serialization.
+    def generate(value)
+      case value
+      when Hash
+        "{#{value.map { |key, entry| "#{JSON.generate(key.to_s)}:#{generate(entry)}" }.join(",")}}"
+      when Array
+        "[#{value.map { |entry| generate(entry) }.join(",")}]"
+      when Integer
+        value.to_s
+      when Float
+        number_literal(value)
+      when String, true, false, nil
+        JSON.generate(value)
+      else
+        raise ArgumentError, "CanonicalJSON cannot serialize #{value.class}"
+      end
+    end
+
+    # Renders a Float the way `Number.prototype.toString` does.
+    #
+    # @param value [Float]
+    # @return [String]
+    def number_literal(value)
+      raise ArgumentError, "CanonicalJSON cannot serialize #{value}" unless value.finite?
+      return "0" if value.zero?
+
+      sign = value.negative? ? "-" : ""
+      digits, exponent = shortest_digits(value.abs)
+      k = digits.length
+      n = exponent # the decimal point sits after the first n digits
+
+      body =
+        if n.between?(k, 21)
+          digits + ("0" * (n - k))
+        elsif n.between?(1, 21)
+          "#{digits[0, n]}.#{digits[n..]}"
+        elsif n.between?(-5, 0)
+          "0.#{"0" * -n}#{digits}"
+        else
+          mantissa = k == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+          e = n - 1
+          "#{mantissa}e#{e.negative? ? "-" : "+"}#{e.abs}"
+        end
+      sign + body
+    end
+
+    # Splits a positive finite Float into its shortest round-trip decimal
+    # digits (no leading or trailing zeros) and the position of the decimal
+    # point relative to those digits, per ECMA-262's (s, k, n) decomposition.
+    #
+    # @param value [Float] positive, finite, non-zero.
+    # @return [Array(String, Integer)]
+    def shortest_digits(value)
+      mantissa, exponent = value.to_s.split("e")
+      exp = exponent ? Integer(exponent, 10) : 0
+      integer_part, fraction_part = mantissa.split(".")
+      fraction_part ||= ""
+      raw = integer_part + fraction_part
+      point = integer_part.length + exp
+
+      stripped = raw.sub(/\A0+/, "")
+      point -= raw.length - stripped.length
+      stripped = stripped.sub(/0+\z/, "")
+      [stripped, point]
+    end
+    private_class_method :shortest_digits
+  end
+end

data/lib/runtype/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "uri"
 
 module Runtype
   # The Runtype API client.
@@ -24,6 +25,9 @@ module Runtype
   # Configuration is per client. There is no global state to set up, so two
   # clients with different keys or base URLs can coexist in one process.
   class Client
+    include Runtype::AgentEnsure
+    include Runtype::LocalToolRunner
+
     # Per-operation socket timeout, in seconds. Generous by default: an
     # execution stream can idle between events while a model is thinking.
     DEFAULT_TIMEOUT = 600
@@ -188,20 +192,35 @@ module Runtype
     end
 
     # Forces the streaming preference the caller asked for, leaving the rest of
-    # the request body untouched. Accepts an `options` hash keyed either way.
+    # the request body untouched.
     #
     # @param params [Hash]
     # @param streaming [Boolean]
     # @return [Hash]
     def with_stream_option(params, streaming)
-      body = params.dup
-      key = body.key?(:options) ? :options : "options"
-      options = (body[key] || {}).dup
-      options.delete(:streamResponse)
-      options.delete("streamResponse")
-      options[:streamResponse] = streaming
-      body[key] = options
-      body
+      rewrite_body_key(params, :options) do |options|
+        options = (options || {}).dup
+        options.delete(:streamResponse)
+        options.delete("streamResponse")
+        options.merge(streamResponse: streaming)
+      end
+    end
+
+    # Copies `body` and replaces one top-level key with the block's result.
+    # The key is looked up as a Symbol first, then as a String, and rewritten
+    # under whichever spelling the caller used (Symbol when absent), so every
+    # dispatch-body normalization agrees on one rule.
+    #
+    # @param body [Hash]
+    # @param key [Symbol]
+    # @yieldparam current [Object, nil] the existing value.
+    # @return [Hash]
+    def rewrite_body_key(body, key)
+      found = key
+      found = key.to_s if !body.key?(key) && body.key?(key.to_s)
+      copy = body.dup
+      copy[found] = yield(copy[found])
+      copy
     end
 
     # Builds the dispatch request body: validates the target, rejects
@@ -224,7 +243,8 @@ module Runtype
                 params.key?(:agent) || params.key?("agent")
 
       raise ArgumentError,
-            "Dispatch requires either a flow or an agent target; pass flow: <id> or agent: <id>."
+            "Dispatch requires either a flow or an agent target; " \
+            "pass flow: { id: \"flow_...\" } or agent: { agentId: \"agent_...\" }."
     end
 
     # @param params [Hash]
@@ -253,24 +273,22 @@ module Runtype
       end
     end
 
-    # Copies the body so the caller's nested `record` is not mutated, then
-    # coerces `record.id` to a string to match the canonical wire contract.
+    # Coerces `record.id` to a String to match the canonical wire contract,
+    # without mutating the caller's nested `record`.
     #
     # @param body [Hash]
     # @return [Hash]
     def normalize_record_id!(body)
-      key = body.key?(:record) ? :record : "record"
-      record = body[key]
-      return body unless record.is_a?(Hash)
+      return body unless body.key?(:record) || body.key?("record")
 
-      id_key = record.key?(:id) ? :id : "id"
-      return body unless record.key?(id_key)
+      rewrite_body_key(body, :record) do |record|
+        next record unless record.is_a?(Hash)
 
-      copy = body.dup
-      record_copy = record.dup
-      record_copy[id_key] = String(record[id_key])
-      copy[key] = record_copy
-      copy
+        id_key = record.key?(:id) ? :id : "id"
+        next record unless record.key?(id_key) && !record[id_key].nil?
+
+        record.merge(id_key => record[id_key].to_s)
+      end
     end
 
     # @return [Hash]
@@ -300,12 +318,26 @@ module Runtype
 
     # @return [Hash] the decoded response body.
     def post_json(path, payload, request_options)
-      connection = open_connection(path, payload, request_options, streaming: false)
+      read_json(open_connection(path, payload, request_options, streaming: false))
+    end
+
+    # @param query [Hash] query parameters.
+    # @return [Hash] the decoded response body.
+    def get_json(path, query, request_options)
+      read_json(open_connection(path, nil, request_options, streaming: false, method: "GET", query: query))
+    end
+
+    # Reads a non-streaming response to completion, raises on a non-2xx
+    # status, and decodes the body.
+    #
+    # @param connection [Runtype::Streaming::Connection] a started connection.
+    # @return [Hash]
+    def read_json(connection)
       body = connection.read_body
       raise_for_status(connection, body)
       body.strip.empty? ? {} : parse_json(body)
     ensure
-      connection&.close
+      connection.close
     end
 
     # @return [Runtype::Streaming::EventStream]
@@ -325,13 +357,17 @@ module Runtype
       event_stream
     end
 
+    # @param query [Hash, nil] appended to the URL as a query string.
     # @return [Runtype::Streaming::Connection]
-    def open_connection(path, payload, request_options, streaming:)
+    def open_connection(path, payload, request_options, streaming:, method: "POST", query: nil)
+      url = url_for(path, request_options)
+      url = "#{url}?#{URI.encode_www_form(query)}" if query && !query.empty?
       Runtype::Streaming::Connection.new(
-        url: url_for(path, request_options),
+        url: url,
         headers: headers(streaming: streaming, request_options: request_options),
-        body: JSON.generate(payload),
-        timeout: timeout_for(request_options)
+        body: payload.nil? ? nil : JSON.generate(payload),
+        timeout: timeout_for(request_options),
+        method: method
       ).start
     end
 

data/lib/runtype/errors.rb

@@ -70,7 +70,6 @@ module Runtype
 
       "API error: #{status}"
     end
-    private_class_method :message_from
   end
 
   # An error response from the API. Raised directly for status codes without a
@@ -104,6 +103,7 @@ module Runtype
       when 401 then AuthenticationError
       when 403 then PermissionDeniedError
       when 404 then NotFoundError
+      when 409 then ConflictError
       when 422 then UnprocessableEntityError
       when 429 then RateLimitError
       else APIStatusError
@@ -125,6 +125,96 @@ module Runtype
   # 404.
   class NotFoundError < APIStatusError; end
 
+  # 409.
+  class ConflictError < APIStatusError; end
+
+  # 409 from the agent ensure protocol: the remote changed underneath the
+  # caller. `code` is `"external_modification"` (the agent's last write came
+  # from the dashboard/API/MCP; pass `on_conflict: "overwrite"` to converge
+  # over it) or `"remote_changed"` (the `expected_remote_hash` no longer
+  # matches; re-run the dry run).
+  class EnsureConflictError < ConflictError
+    PROTOCOL_CODES = %w[external_modification remote_changed].freeze
+
+    # @return [String] `"external_modification"` or `"remote_changed"`.
+    def code
+      body_field("code")
+    end
+
+    # @return [String, nil] who last wrote the agent (external_modification).
+    def last_modified_source
+      body_field("lastModifiedSource")
+    end
+
+    # @return [String, nil] ISO-8601 (external_modification).
+    def modified_at
+      body_field("modifiedAt")
+    end
+
+    # @return [String, nil] the live hash (remote_changed).
+    def current_hash
+      body_field("currentHash")
+    end
+
+    # @param error [Runtype::APIStatusError]
+    # @return [Boolean]
+    def self.protocol_conflict?(error)
+      error.status_code == 409 && error.body.is_a?(Hash) && PROTOCOL_CODES.include?(error.body["code"])
+    end
+
+    # @param error [Runtype::APIStatusError]
+    # @return [Runtype::EnsureConflictError]
+    def self.from_status_error(error)
+      new(
+        Runtype::Error.message_from(error.body, error.status_code),
+        status_code: error.status_code, body: error.body, headers: error.headers
+      )
+    end
+
+    private
+
+    # @param key [String]
+    # @return [Object, nil]
+    def body_field(key)
+      body.is_a?(Hash) ? body[key] : nil
+    end
+  end
+
+  # Raised by `ensure_agent(definition, expect_no_changes: true)` when the
+  # platform's definition no longer matches the repo's.
+  class DriftError < Error
+    # @return [Hash] the dry-run plan: `"changes"`, `"changedKeys"`,
+    #   `"contentHash"`, `"remoteHash"`, `"agentId"`.
+    attr_reader :plan
+
+    # @param plan [Hash]
+    # @param name [String, nil]
+    def initialize(plan, name: nil)
+      @plan = plan
+      changed = Array(plan["changedKeys"]).join(", ")
+      super(
+        "Agent #{(name || plan["agentId"] || "definition").inspect} drifted: plan is #{plan["changes"].inspect} " \
+        "(changed: #{changed.empty? ? "n/a" : changed}). Run client.pull_agent(name) to absorb the remote edit " \
+        "into your repo, or re-run ensure_agent to converge."
+      )
+    end
+  end
+
+  # A local tool could not be run during `run_with_local_tools`: the server
+  # paused on a tool with no handler, the handler raised (the original error is
+  # `#cause`), or the loop exceeded its round limit.
+  class LocalToolError < Error
+    # @return [String, nil] the tool the server paused on.
+    attr_reader :tool_name
+
+    # @param message [String]
+    # @param tool_name [String, nil]
+    def initialize(message, tool_name: nil)
+      @tool_name = tool_name
+      super(message)
+    end
+  end
+
   # 422.
   class UnprocessableEntityError < APIStatusError; end
 

data/lib/runtype/local_tool_runner.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Runtype
+  # The local-tool pause/resume loop on {Runtype::Client}.
+  module LocalToolRunner
+    # Upper bound on resume legs for one call, so a tool the server keeps
+    # re-requesting cannot spin forever.
+    DEFAULT_MAX_LOCAL_TOOL_ROUNDS = 50
+
+    # Dispatches, and whenever the execution pauses on a tool in `tools`, runs
+    # it here and resumes with the output — repeating until the execution ends
+    # or pauses on something this process does not own (an approval or an
+    # elicitation, for instance), which is returned to the caller as-is.
+    #
+    # Every parallel local tool call in one model turn is executed
+    # concurrently and answered in a single resume. Outputs are keyed by the
+    # server's per-call id when it sent one, else by tool name.
+    #
+    # Without a block the loop runs over JSON responses and returns the final
+    # response body. With a block it streams: every event of every leg is
+    # yielded, and the last leg's closed {Runtype::Streaming::EventStream} is
+    # returned so its reconnect handle stays readable.
+    #
+    #   result = client.run_with_local_tools(
+    #     { "save_goals" => save_goals, "lookup_order" => ->(args) { Orders.find(args["id"]) } },
+    #     agent: { agentId: "agent_01h..." },
+    #     messages: [{ role: "user", content: "I want to sleep better" }]
+    #   )
+    #
+    # @param tools [Hash{String, Symbol => Runtype::LocalTool, #call}] tool
+    #   name => handler. A {Runtype::LocalTool} carries the schema the model
+    #   sees; a bare callable relies on the saved agent already declaring the
+    #   tool as a `toolType: "local"` runtime tool.
+    # @param scope [Symbol, String] `:session` (default) sends no tool
+    #   declarations — the saved agent owns them. `:turn` derives
+    #   `clientTools[]` from every {Runtype::LocalTool} in `tools` and ships
+    #   them in the dispatch envelope for this one turn (on top of any
+    #   `clientTools:` already in `params`).
+    # @param max_rounds [Integer] see {DEFAULT_MAX_LOCAL_TOOL_ROUNDS}.
+    # @param request_options [Hash] see {Runtype::Client#dispatch}.
+    # @param params [Hash] the dispatch request body (`agent:`, `messages:`, ...).
+    # @yieldparam event [Runtype::Streaming::Event] when streaming.
+    # @return [Hash, Runtype::Streaming::EventStream]
+    # @raise [Runtype::LocalToolError] when a paused tool has no handler, a
+    #   handler raises, or `max_rounds` is exceeded.
+    def run_with_local_tools(tools, scope: :session, max_rounds: DEFAULT_MAX_LOCAL_TOOL_ROUNDS,
+                             request_options: {}, **params, &block)
+      registry = Runtype::LocalTools::Registry.new(tools)
+      params = with_turn_scoped_client_tools(params, registry) if scope.to_s == "turn"
+
+      if block
+        stream_with_local_tools(registry, params, max_rounds, request_options, &block)
+      else
+        dispatch_with_local_tools(registry, params, max_rounds, request_options)
+      end
+    end
+
+    private
+
+    # @return [Hash] the final JSON response body.
+    def dispatch_with_local_tools(registry, params, max_rounds, request_options)
+      response = dispatch(request_options: request_options, **params)
+      rounds = 0
+
+      while response["status"] == "paused"
+        collector = Runtype::LocalTools::PauseCollector.new
+        Array(response["events"]).each { |event| collector.observe(event) }
+        collector.observe_paused_reason(response["pausedReason"]) unless collector.paused?
+        return response unless collector.paused?
+
+        raise_local_tool_round_limit(max_rounds) if (rounds += 1) > max_rounds
+        response = resume(
+          execution_id: collector.batch_execution_id,
+          tool_outputs: registry.execute(collector.batch),
+          request_options: request_options
+        )
+      end
+
+      response
+    end
+
+    # @return [Runtype::Streaming::EventStream] the last leg's stream.
+    def stream_with_local_tools(registry, params, max_rounds, request_options)
+      collector = Runtype::LocalTools::PauseCollector.new
+      stream = dispatch_stream(request_options: request_options, **params) do |event|
+        collector.observe(event)
+        yield event
+      end
+      rounds = 0
+
+      while collector.paused?
+        raise_local_tool_round_limit(max_rounds) if (rounds += 1) > max_rounds
+        outputs = registry.execute(collector.batch)
+        execution_id = collector.batch_execution_id
+        collector = Runtype::LocalTools::PauseCollector.new
+        stream = resume_stream(
+          execution_id: execution_id, tool_outputs: outputs, request_options: request_options
+        ) do |event|
+          collector.observe(event)
+          yield event
+        end
+      end
+
+      stream
+    end
+
+    # @raise [Runtype::LocalToolError]
+    def raise_local_tool_round_limit(max_rounds)
+      raise Runtype::LocalToolError, "Execution kept pausing on local tools after #{max_rounds} resume rounds"
+    end
+
+    # @return [Hash] `params` with the registry's schema-carrying tools appended
+    #   to `clientTools` (keyed however the caller keyed it).
+    def with_turn_scoped_client_tools(params, registry)
+      derived = registry.client_tools
+      return params if derived.empty?
+
+      rewrite_body_key(params, :clientTools) { |existing| Array(existing) + derived }
+    end
+  end
+end