runtype 0.1.0 → 0.2.1

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
@@ -109,6 +113,26 @@ module Runtype
       stream("v1/dispatch", dispatch_body(params, true), request_options, &block)
     end
 
+    # Follows an execution through the execution-scoped events alias
+    # (`GET /v1/executions/{executionId}/events`) and streams what it emits.
+    # This is the reattach handle for a run that keeps going on the platform
+    # after its request returned: a durable-lane resume answers
+    # `{ executionId, status: "running" }` and expects the caller to read the
+    # rest of the turn here.
+    #
+    # @param execution_id [String]
+    # @param after [String, nil] the last event `seq` or SSE id already
+    #   consumed, so the replay starts strictly past it.
+    # @param conversation_id [String, nil]
+    # @param request_options [Hash] see {#dispatch}.
+    # @yieldparam event [Runtype::Streaming::Event]
+    # @return [Runtype::Streaming::EventStream]
+    # @raise [Runtype::APIStatusError] on a non-2xx response.
+    def execution_events_stream(execution_id, after: nil, conversation_id: nil, request_options: {}, &block)
+      query = { after: after, conversationId: conversation_id }.compact
+      stream("v1/executions/#{execution_id}/events", nil, request_options, method: "GET", query: query, &block)
+    end
+
     # Resumes a paused execution with the outputs of its client-executed tools.
     # Does not count against execution limits.
     #
@@ -188,20 +212,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 +263,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 +293,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,17 +338,31 @@ 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]
-    def stream(path, payload, request_options, &block)
-      connection = open_connection(path, payload, request_options, streaming: true)
+    def stream(path, payload, request_options, method: "POST", query: nil, &block)
+      connection = open_connection(path, payload, request_options, streaming: true, method: method, query: query)
       begin
         raise_for_status(connection, connection.read_body) unless success?(connection.status)
       rescue StandardError
@@ -325,13 +377,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/detached_follow.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Runtype
+  # Following a run that detached from its request.
+  #
+  # A saved-agent dispatch on the platform's durable lane keeps running inside
+  # its session after the request returns. Handing it tool outputs answers with
+  # an acknowledgement instead of a buffered turn:
+  #
+  #   { "executionId" => "aex_…", "pauseKind" => "client_tool", "status" => "running" }
+  #
+  # and a streamed resume closes on an `await` frame whose `awaitReason` is
+  # `detached`. Either way the rest of the turn is read back through the
+  # execution-scoped events alias ({Runtype::Client#execution_events_stream}).
+  # This module folds that replay into the shapes the local-tool loop already
+  # consumes: a buffered continuation envelope (`executionId`, `events[]`,
+  # `status`) for the JSON loop, and a live stream for the streaming loop.
+  module DetachedFollow
+    module_function
+
+    # Local-tool awaits the events alias can carry.
+    AWAIT_TYPES = %w[await flow_await step_await].freeze
+
+    # The message the buffered envelope carries when the events stream closed
+    # before a terminal frame.
+    STREAM_CLOSED_EARLY =
+      "The execution detached and its events stream closed before a terminal frame; " \
+      "reattach with the execution events route."
+
+    # A buffered resume that acknowledged a detached run rather than answering
+    # the turn: `status: "running"`, an execution id, and no `events[]`.
+    #
+    # @param response [Object]
+    # @return [Boolean]
+    def detached_ack?(response)
+      return false unless response.is_a?(Hash)
+
+      id = response["executionId"]
+      response["status"] == "running" && id.is_a?(String) && !id.empty? && !response["events"].is_a?(Array)
+    end
+
+    # The highest unified `seq` among buffered events, as the `after` cursor a
+    # follow starts past, so the replay never re-delivers the await the outputs
+    # just answered.
+    #
+    # @param events [Object]
+    # @return [String, nil]
+    def resume_cursor_of(events)
+      return nil unless events.is_a?(Array)
+
+      seqs = events.filter_map do |event|
+        data = event.respond_to?(:to_h) ? event.to_h : event
+        seq = data["seq"] if data.is_a?(Hash)
+        seq if seq.is_a?(Numeric)
+      end
+      seqs.max&.to_s
+    end
+
+    # @param data [Hash]
+    # @return [Boolean]
+    def detached_await?(data)
+      data["type"] == "await" && data["awaitReason"] == Runtype::Streaming::Event::DETACHED_AWAIT_REASON
+    end
+
+    # @param data [Hash]
+    # @return [Boolean]
+    def local_tool_await?(data)
+      AWAIT_TYPES.include?(data["type"]) && !detached_await?(data)
+    end
+
+    # One followed leg: the buffered continuation envelope a non-streaming
+    # loop expects, plus the reconnect cursor the next follow starts past.
+    Followed = Struct.new(:envelope, :cursor, keyword_init: true)
+
+    # Reads the events alias to the run's next pause or terminal frame. The
+    # alias carries its own watch lease: when a leg closes on a detached
+    # `await`, the run is still going and the next leg reopens past the last
+    # event this one delivered, exactly as a dispatch stream reattaches.
+    #
+    # @param client [Runtype::Client]
+    # @param execution_id [String]
+    # @param after [String, nil]
+    # @param request_options [Hash]
+    # @return [Followed] whose envelope carries `success`, `executionId`,
+    #   `events`, `status`, and `error` when the run failed or its stream
+    #   closed early.
+    def follow_buffered(client, execution_id, after:, request_options:)
+      events = []
+      status = nil
+      error = nil
+      cursor = after
+
+      loop do
+        detached = false
+        client.execution_events_stream(execution_id, after: cursor, request_options: request_options) do |event|
+          data = event.data
+          cursor = event.id || (data["seq"].is_a?(Numeric) ? data["seq"].to_s : cursor)
+          detached = detached_await?(data)
+          next if detached
+
+          events << data
+          case data["type"]
+          when "execution_complete"
+            status = data["success"] == false ? "failed" : "completed"
+            error = data["error"] if data["error"].is_a?(String)
+          when "execution_error"
+            status = "failed"
+            error = error_message(data["error"])
+          else
+            status = "paused" if status.nil? && local_tool_await?(data)
+          end
+        end
+        break unless status.nil? && detached
+      end
+
+      if status.nil?
+        status = "failed"
+        error = STREAM_CLOSED_EARLY
+      end
+
+      envelope = { "success" => status == "completed", "executionId" => execution_id,
+                   "events" => events, "status" => status }
+      envelope["error"] = error if error
+      Followed.new(envelope: envelope, cursor: cursor)
+    end
+
+    # @param detail [Object]
+    # @return [String]
+    def error_message(detail)
+      return detail if detail.is_a?(String)
+      return detail["message"].to_s if detail.is_a?(Hash) && detail.key?("message")
+
+      "Execution failed"
+    end
+  end
+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,222 @@
+# 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)
+      answered = AnsweredCalls.new
+      replayed = false
+      cursor = nil
+      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
+        cursor ||= Runtype::DetachedFollow.resume_cursor_of(response["events"])
+        batch = replayed ? answered.fresh(collector.batch) : answered.record(collector.batch)
+        if batch.any?
+          response = resume(
+            execution_id: collector.batch_execution_id,
+            tool_outputs: registry.execute(batch),
+            request_options: request_options
+          )
+          # A buffered continuation answers the leg in full; only a durable-lane
+          # acknowledgement needs the run's events followed instead.
+          next unless Runtype::DetachedFollow.detached_ack?(response)
+        end
+
+        # Followed events can replay the await these outputs just answered;
+        # an all-answered batch means the run is still going, so read on.
+        followed = Runtype::DetachedFollow.follow_buffered(
+          self, collector.batch_execution_id, after: cursor, request_options: request_options
+        )
+        response = followed.envelope
+        cursor = followed.cursor
+        replayed = true
+      end
+
+      response
+    end
+
+    # @return [Runtype::Streaming::EventStream] the last leg's stream.
+    def stream_with_local_tools(registry, params, max_rounds, request_options)
+      leg = StreamLeg.new
+      stream = dispatch_stream(request_options: request_options, **params) do |event|
+        leg.observe(event)
+        yield event
+      end
+      answered = AnsweredCalls.new
+      rounds = 0
+
+      loop do
+        batch = leg.replayed? ? answered.fresh(leg.collector.batch) : answered.record(leg.collector.batch)
+        if batch.any?
+          raise_local_tool_round_limit(max_rounds) if (rounds += 1) > max_rounds
+          outputs = registry.execute(batch)
+          execution_id = leg.collector.batch_execution_id
+          leg = StreamLeg.new
+          stream = resume_stream(
+            execution_id: execution_id, tool_outputs: outputs, request_options: request_options
+          ) do |event|
+            leg.observe(event)
+            yield event
+          end
+        elsif leg.follow?
+          # The leg closed on a detached `await`, or replayed only awaits this
+          # loop already answered: the run kept going on the platform, so its
+          # events are followed from where this leg stopped.
+          raise_local_tool_round_limit(max_rounds) if (rounds += 1) > max_rounds
+          execution_id = leg.execution_id || stream.execution_id
+          after = stream.last_event_id
+          leg = StreamLeg.new(replayed: true)
+          stream = execution_events_stream(execution_id, after: after, request_options: request_options) do |event|
+            leg.observe(event)
+            yield event
+          end
+        else
+          break
+        end
+      end
+
+      stream
+    end
+
+    # The local-tool calls one `run_with_local_tools` invocation has already
+    # answered. A followed replay can re-deliver an `await` whose output the
+    # server already holds; answering it again would run the handler twice.
+    class AnsweredCalls
+      def initialize
+        @keys = {}
+      end
+
+      # A leg the server answered directly (a dispatch or resume continuation)
+      # is authoritative: every call in it is new, even a repeat of a key the
+      # server re-requested.
+      #
+      # @param batch [Array<Runtype::LocalTools::PausedCall>]
+      # @return [Array<Runtype::LocalTools::PausedCall>] `batch`, recorded.
+      def record(batch)
+        batch.each { |call| @keys[call.output_key] = true }
+      end
+
+      # A followed replay can carry awaits already answered.
+      #
+      # @param batch [Array<Runtype::LocalTools::PausedCall>]
+      # @return [Array<Runtype::LocalTools::PausedCall>] the calls not yet
+      #   answered, now recorded.
+      def fresh(batch)
+        record(batch.reject { |call| @keys.key?(call.output_key) })
+      end
+    end
+    private_constant :AnsweredCalls
+
+    # One streamed leg of the loop: the local-tool pauses it carried and
+    # whether it closed on a detached await.
+    class StreamLeg
+      attr_reader :collector, :execution_id
+
+      # @param replayed [Boolean] whether this leg reads the events alias,
+      #   which can re-deliver awaits already answered.
+      def initialize(replayed: false)
+        @collector = Runtype::LocalTools::PauseCollector.new
+        @replayed = replayed
+        @detached = false
+        @execution_id = nil
+      end
+
+      # @return [Boolean]
+      def replayed?
+        @replayed
+      end
+
+      # @param event [Runtype::Streaming::Event]
+      # @return [void]
+      def observe(event)
+        @collector.observe(event)
+        @execution_id ||= event.execution_id
+        @detached = true if event.detached?
+      end
+
+      # @return [Boolean] the leg ended without a terminal frame while the run
+      #   continues: on a detached await, or on awaits already answered.
+      def follow?
+        @detached || @collector.paused?
+      end
+    end
+    private_constant :StreamLeg
+
+    # @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