collavre_openclaw 0.6.4 → 0.6.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '028dc9b0f4d77120602482cb67e02ccb7d54efa1ce69d850452a4fe548923e26'
-  data.tar.gz: e3caf613040f7572a727ed5abd89dcb14f5ddc336ebd962006b4ad67bffed20a
+  metadata.gz: a41340e38120813ecf6b2776dc271d533bb3f0e9eb742200a2a844b06fbf0aa4
+  data.tar.gz: 17a1c6d6cd3c69c15025a843d93c2eb65b6df91ce6d145a21e9d2159331b7b53
 SHA512:
-  metadata.gz: 69854771a368ea6200b04126e70d4939b0b70783adaae82c6ed43998879f009d3d87fed40c84c3a3f4aa0d9e90f08b350f23c84f427127e9c71236ee051744c0
-  data.tar.gz: 9f2ef5b7a2f8d3980ddcb81c878a65a760545b35374e500e319b04131886297a95dfe864b8dccf617b383a15b6b66a8f48029af2f4cad35163b5bb38168c8dee
+  metadata.gz: 7c2e5dd42f34913f03a2d82458b8df854286164fc3089657786cb0b251945c2d59772f379a2d99f51f246c1fdbaf9f6534de6517ff7cafec06acdbf7f01638f6
+  data.tar.gz: 8c2a7e4c686854841702115e9d1587fb508566e96591fb0df30673f4b9467356e2268114d92f8e0f9be72fd207e66598f5b3ed4924179873499373dad0607c59

data/app/services/collavre_openclaw/ai_client_extension.rb

@@ -15,6 +15,12 @@ module CollavreOpenclaw
     # @param messages_input [Hash, Array] Hash { messages:, first_message:, context_changed:, system_prompt: }
     #   from SessionContextResolver, or a plain Array from standalone callers (e.g., CompressJob).
     def chat(messages_input, tools: [], &block)
+      # Cleared on the way in, as the base #chat clears it — the flag describes
+      # the last request, and this branch never reaches `super`. A client is
+      # reused across a turn's calls, so a failure left standing would have
+      # every later one claiming it delivered nothing.
+      @last_handoff_failed = false
+      @handed_off = false
       normalized_vendor = vendor.to_s.downcase
       messages_data = normalize_messages_input(messages_input)
 
@@ -27,10 +33,16 @@ module CollavreOpenclaw
         # key?(:system_prompt) distinguishes "not provided" (Array input) from "explicitly nil" (incremental session).
         resolved_system_prompt = messages_data.key?(:system_prompt) ? messages_data[:system_prompt] : system_prompt
         user = context&.dig(:user)
+        # before_tool_call is the client's lifecycle checkpoint (terminal
+        # status + turn deadline). The base client fires it at RubyLLM
+        # tool-call boundaries; this path never reaches those, so the adapter
+        # gets the same callable to poll mid-stream instead.
         adapter = adapter_class.new(
           user: user,
           system_prompt: resolved_system_prompt,
-          context: context
+          context: context,
+          lifecycle_check: @before_tool_call,
+          request_timeout_seconds: @request_timeout_seconds
         )
 
         response_content = nil
@@ -42,10 +54,17 @@ module CollavreOpenclaw
           error_message = e.message
           raise
         ensure
-          # Honor no-log mode (e.g. inline typo correction on *unsubmitted* drafts).
-          # Base Collavre::AiClient#chat gates logging behind @log_interactions; this
-          # prepended adapter path bypasses super, so it must gate it too — otherwise
-          # private drafts leak to ActivityLog for OpenClaw-backed agents.
+          # The adapter can know that the gateway accepted the request before
+          # the caller's streaming block raises (notably CancelledError). Copy
+          # both answers while unwinding as well as on a normal return, so
+          # AiAgentService can persist the actual handoff rather than infer it
+          # from how #chat exited.
+          @last_handoff_failed = adapter.last_handoff_failed?
+          @handed_off = adapter.handed_off?
+
+          # Honor no-log mode. Base Collavre::AiClient#chat gates logging behind
+          # @log_interactions; this prepended adapter path bypasses super, so it
+          # must gate logging too.
           if @log_interactions
             log_interaction(
               messages: messages_data[:messages],

data/app/services/collavre_openclaw/openclaw_adapter.rb

@@ -3,6 +3,16 @@ require "json"
 
 module CollavreOpenclaw
   class OpenclawAdapter
+    class LifecycleCheckError < StandardError
+      attr_reader :original
+
+      def initialize(original)
+        @original = original
+        super(original.message)
+        set_backtrace(original.backtrace)
+      end
+    end
+
     # Pure transport adapter for OpenClaw AI Gateway.
     # Session context filtering (full vs incremental) is handled upstream
     # by SessionContextResolver — this adapter sends exactly what it receives.
@@ -16,19 +26,62 @@ module CollavreOpenclaw
     #   Same Topic, multiple users → shared context
     #   Different Topics → isolated sessions
 
-    def initialize(user:, system_prompt:, context: {})
+    # lifecycle_check: callable polled during a chat so the turn can observe
+    # an external terminal status or its wall-clock deadline. It has to be
+    # injected here because this adapter's tools run remotely on the gateway —
+    # there is no local tool-call boundary, and the caller's streaming block
+    # fires only on text, which a tool-only run never emits. A raise from it
+    # (Collavre::CancelledError or a subclass) unwinds past both transports'
+    # fallback rescues.
+    def initialize(user:, system_prompt:, context: {}, lifecycle_check: nil, request_timeout_seconds: nil)
       @user = user
       @system_prompt = system_prompt
       @context = context
+      @lifecycle_check = wrap_lifecycle_check(lifecycle_check)
+      @request_timeout_seconds = request_timeout_seconds
+      @last_handoff_failed = false
+      @handed_off = false
+    end
+
+    # Did the last #chat end without the gateway ever receiving the payload?
+    #
+    # The same question Collavre::AiClient#last_handoff_failed? answers for its
+    # own provider path, and it has to be answered here as well because
+    # AiClientExtension#chat routes past that method entirely: every failure
+    # below turns into a streamed error plus nil, and nil is also what an
+    # ordinary empty answer returns. Orchestration::DeliveryRecord needs the two
+    # apart, since a turn that handed the gateway nothing delivered nothing
+    # while AiAgentJob still marks it `done`.
+    #
+    # The proxy is the same one the base client uses: nothing streamed means
+    # nothing was handed over. An error *after* deltas is not one of these — the
+    # gateway had the payload and answered part of it, so the comments that turn
+    # swallowed did reach the agent.
+    #
+    # The question is asked of the whole #chat, not of a transport: one call can
+    # stream over the WebSocket and then fall back to HTTP, so each transport's
+    # own response buffer answers only for its own attempt. @handed_off spans
+    # both, and is reset once per #chat.
+    def last_handoff_failed?
+      @last_handoff_failed
+    end
+
+    # The same fact, asked positively — see AiClient#handed_off?. A turn the
+    # user stops mid-answer never reaches the line that sets the flag above.
+    def handed_off?
+      @handed_off
     end
 
     # @param messages_data [Hash] { messages:, first_message:, context_changed: }
     def chat(messages_data, &block)
+      @last_handoff_failed = false
+      @handed_off = false
       parse_messages_data!(messages_data)
 
       unless @user&.gateway_url.present?
         Rails.logger.error("[CollavreOpenclaw] No Gateway URL configured for user #{@user&.id}")
         yield "Error: OpenClaw Gateway URL not configured" if block_given?
+        @last_handoff_failed = true
         return nil
       end
 
@@ -36,6 +89,7 @@ module CollavreOpenclaw
         Rails.logger.error("[CollavreOpenclaw] No API key configured for user #{@user&.id}")
         yield "Error: OpenClaw API key not configured or decryption failed. " \
               "Please re-enter the API key in AI agent settings." if block_given?
+        @last_handoff_failed = true
         return nil
       end
 
@@ -96,6 +150,7 @@ module CollavreOpenclaw
 
     def chat_via_websocket(&block)
       response_content = +""
+      errored = false
 
       begin
         client = ConnectionManager.instance.connection_for(@user)
@@ -107,29 +162,55 @@ module CollavreOpenclaw
           session_key: session_key,
           message: payload[:message],
           attachments: payload[:attachments],
-          on_run_id: method(:persist_run_id_on_comment)
+          on_run_id: method(:handle_run_id),
+          lifecycle_check: @lifecycle_check
         ) do |event|
           case event[:state]
           when "delta"
             if event[:text].present?
               response_content << event[:text]
-              yield event[:text] if block_given?
+              @handed_off = true
+              emit_to_caller(event[:text], &block)
             end
           when "final"
             # If no deltas were streamed, final contains the full text
             if response_content.blank? && event[:text].present?
               response_content << event[:text]
-              yield event[:text] if block_given?
+              @handed_off = true
+              emit_to_caller(event[:text], &block)
             end
           when "error"
             error_msg = event[:text] || "Unknown error"
-            yield "OpenClaw Error: #{error_msg}" if block_given?
+            errored = true
+            emit_to_caller("OpenClaw Error: #{error_msg}", &block)
           when "aborted"
             # User or system aborted
           end
         end
 
+        # The gateway answered with an error and nothing else: see
+        # #last_handoff_failed?. Decided after the stream rather than in the
+        # branch above, so a delta that arrives either side of the error still
+        # counts as the payload having got through.
+        #
+        # Inert behind a client that surfaces a run id, since #handle_run_id has
+        # already answered by the time any event arrives. Kept for one that does
+        # not: an error event is then the only evidence either way, and reading
+        # it as a delivery would be the losing mistake.
+        @last_handoff_failed = true if errored && !@handed_off
         response_content.presence
+      rescue Collavre::CancelledError
+        # Raised out of the caller's streaming block when the task hit a
+        # terminal status or its turn deadline. The turn is already over —
+        # falling back to HTTP would issue a second provider request (and
+        # repeat tool side effects) instead of releasing this worker.
+        raise
+      rescue LifecycleCheckError => e
+        # A lifecycle poll is application control flow, not evidence that the
+        # WebSocket transport failed. In particular, falling back after the
+        # gateway acknowledged chat.send could submit the same tool-bearing
+        # payload twice. Restore the callback's original exception unchanged.
+        raise e.original
       rescue CollavreOpenclaw::ConnectionError,
              CollavreOpenclaw::TimeoutError => e
         Rails.logger.warn("[CollavreOpenclaw::WS] FALLBACK gateway=#{@user.gateway_url} reason=#{e.class}:#{e.message}")
@@ -138,6 +219,7 @@ module CollavreOpenclaw
         Rails.logger.error("[CollavreOpenclaw] WebSocket chat error: #{e.message}")
         error_msg = "OpenClaw Error: #{e.message}"
         yield error_msg if block_given?
+        @last_handoff_failed = !@handed_off
         nil
       rescue StandardError => e
         Rails.logger.error("[CollavreOpenclaw] WebSocket unexpected error: #{e.message}\n" \
@@ -147,6 +229,21 @@ module CollavreOpenclaw
       end
     end
 
+    # The gateway answered chat.send with a run id, which is the handoff: it has
+    # the whole payload and the run may already be calling tools. Everything
+    # after this — a run that goes quiet until the read timeout, an HTTP
+    # fallback that fails before yielding — costs an *answer*, not the delivery,
+    # and the comments this turn swallowed are with the agent either way.
+    #
+    # Reaching here at all is the acknowledgement: WebsocketClient#chat_send
+    # calls this straight after send_rpc returns, and send_rpc raises on a read
+    # timeout and on an RPC error. Set before persisting, because the handoff
+    # happened whether or not we can write the run id down.
+    def handle_run_id(run_id)
+      @handed_off = true
+      persist_run_id_on_comment(run_id)
+    end
+
     # Claim the run for the solicited reply so the same run's final, re-delivered
     # as "proactive" to other processes, is suppressed. This reply is canonical
     # (it carries the activity log), so it reclaims on a lost race.
@@ -289,15 +386,27 @@ module CollavreOpenclaw
 
         stream_response(payload) do |chunk|
           response_content << chunk
-          yield chunk if block_given?
+          @handed_off = true
+          emit_to_caller(chunk, &block)
         end
 
         response_content.presence
+      rescue Collavre::CancelledError
+        # Same contract as the WebSocket path: a cancelled/deadline-failed
+        # turn must release the worker, not be rewritten as a provider error.
+        raise
+      rescue LifecycleCheckError => e
+        # Do not rewrite application/lifecycle failures into provider text.
+        raise e.original
       rescue StandardError => e
         Rails.logger.error("[CollavreOpenclaw] HTTP chat error: #{e.message}\n" \
                            "#{e.backtrace.first(5).join("\n")}")
         error_msg = "OpenClaw Error: #{e.message}"
         yield error_msg if block_given?
+        # Not `response_content.blank?`: this may be the fallback behind a
+        # WebSocket that already streamed, and that content is in the caller's
+        # hands even though this method's buffer is empty.
+        @last_handoff_failed = !@handed_off
         nil
       end
     end
@@ -443,7 +552,13 @@ module CollavreOpenclaw
           req.options.on_data = proc do |chunk, _size, env|
             if env&.status.nil? || (env.status >= 200 && env.status < 300)
               buffer << chunk
+              @handed_off = true if env&.response_headers&.[]("content-type")&.include?("application/json")
               process_sse_buffer(buffer, &block)
+              # A peer can keep the socket active indefinitely by sending an
+              # event without its terminating blank line. Completed events are
+              # checked inside the parser after handoff classification; poll
+              # here only when an unterminated fragment remains.
+              @lifecycle_check&.call if buffer.present?
             else
               buffer << chunk
             end
@@ -455,9 +570,15 @@ module CollavreOpenclaw
           raise parse_error_message(response.status, error_body)
         end
 
+        json_response = response.headers["content-type"]&.include?("application/json")
+        # A completed successful JSON response proves the gateway accepted the
+        # payload just as an SSE data event does. Record that before the final
+        # lifecycle check, which may abort parsing because the task became
+        # terminal while this response was in flight.
+        @handed_off = true if json_response
         process_sse_buffer(buffer, final: true, &block)
 
-        if response.headers["content-type"]&.include?("application/json")
+        if json_response
           handle_json_response(response.body, &block)
         end
 
@@ -465,16 +586,20 @@ module CollavreOpenclaw
       rescue Faraday::TimeoutError
         retries += 1
         if retries <= max_retries
+          @lifecycle_check&.call
           Rails.logger.warn("[CollavreOpenclaw] Timed out, retrying (#{retries}/#{max_retries})...")
           sleep(1 * retries)
+          @lifecycle_check&.call
           retry
         end
         raise "OpenClaw request timed out after #{max_retries + 1} attempts"
       rescue Faraday::ConnectionFailed => e
         retries += 1
         if retries <= max_retries
+          @lifecycle_check&.call
           Rails.logger.warn("[CollavreOpenclaw] Connection failed, retrying (#{retries}/#{max_retries})...")
           sleep(1 * retries)
+          @lifecycle_check&.call
           retry
         end
         raise "Failed to connect to OpenClaw after #{max_retries + 1} attempts: #{e.message}"
@@ -510,16 +635,60 @@ module CollavreOpenclaw
 
     def process_sse_buffer(buffer, final: false, &block)
       while (idx = buffer.index("\n\n"))
+        # The HTTP transport has no event loop to poll from; this parser is
+        # its one checkpoint that runs for every received chunk, including
+        # tool/comment events that never yield text to the caller's block.
         event_data = buffer.slice!(0, idx + 2)
+        # Record delivery first for application data: receiving a successful
+        # data event proves the gateway accepted the payload and may already
+        # have run tools, even when it contains no caller-visible text. SSE
+        # comments are transport keepalives, so they cross the lifecycle check
+        # without claiming the agent received anything.
+        @handed_off = true if sse_data_event?(event_data)
+        @lifecycle_check&.call
         parse_sse_event(event_data, &block)
       end
 
       if final && buffer.present?
+        @handed_off = true if sse_data_event?(buffer)
+        @lifecycle_check&.call
         parse_sse_event(buffer, &block)
         buffer.clear
       end
     end
 
+    def wrap_lifecycle_check(check)
+      return nil unless check
+
+      lambda do |*args|
+        check.call(*args)
+      rescue Collavre::CancelledError
+        raise
+      rescue StandardError => e
+        raise LifecycleCheckError.new(e)
+      end
+    end
+
+    # Exceptions raised by the service's streaming callback are application
+    # control flow, not transport failures. Wrap them so the adapter's rescue
+    # chain cannot start an HTTP fallback after WebSocket handoff.
+    def emit_to_caller(value)
+      return unless block_given?
+
+      yield value
+    rescue Collavre::CancelledError
+      raise
+    rescue StandardError => e
+      raise LifecycleCheckError.new(e)
+    end
+
+    def sse_data_event?(event_str)
+      event_str.each_line.any? do |line|
+        stripped = line.strip
+        stripped.start_with?("data:") && stripped.delete_prefix("data:").strip.present?
+      end
+    end
+
     def parse_sse_event(event_str, &block)
       event_str.each_line do |line|
         line = line.strip
@@ -549,8 +718,15 @@ module CollavreOpenclaw
 
     def build_connection
       Faraday.new do |builder|
-        builder.options.timeout = CollavreOpenclaw.config.read_timeout
-        builder.options.open_timeout = CollavreOpenclaw.config.open_timeout
+        remaining_deadline = @request_timeout_seconds&.call
+        builder.options.timeout = [
+          CollavreOpenclaw.config.read_timeout,
+          remaining_deadline
+        ].compact.min
+        builder.options.open_timeout = [
+          CollavreOpenclaw.config.open_timeout,
+          remaining_deadline
+        ].compact.min
         builder.adapter Faraday.default_adapter
       end
     end

data/app/services/collavre_openclaw/websocket_client.rb

@@ -158,9 +158,14 @@ module CollavreOpenclaw
     #   streaming, so callers can persist it as a cross-process idempotency key.
     # @yield [Hash] chat events with :state, :text, :message keys
     # @return [String, nil] final response text
-    def chat_send(session_key:, message:, attachments: nil, idempotency_key: nil, on_run_id: nil, &block)
+    def chat_send(session_key:, message:, attachments: nil, idempotency_key: nil, on_run_id: nil,
+                  lifecycle_check: nil, &block)
       ensure_connected!
       touch_activity!
+      # Connection establishment can block after the service-level preflight.
+      # Recheck before registering queues or scheduling chat.send so a Stop
+      # that won during the handshake cannot start remote tool side effects.
+      force_lifecycle_check(lifecycle_check) if lifecycle_check
 
       idempotency_key ||= SecureRandom.uuid
       actual_run_id = nil
@@ -186,34 +191,51 @@ module CollavreOpenclaw
       }
       rpc_params[:attachments] = attachments if attachments.present?
 
-      response = send_rpc("chat.send", rpc_params, request_id: rpc_request_id)
-
-      # The EM thread already registered @pending_runs[actual_run_id] in
-      # handle_response. Clean up the idempotency_key entry if a different
-      # runId was assigned.
-      actual_run_id = response&.dig(:runId) || idempotency_key
-      if actual_run_id != idempotency_key
-        @mutex.synchronize do
-          @pending_runs.delete(idempotency_key)
-          # Ensure runId is registered (may already be from handle_response)
-          @pending_runs[actual_run_id] ||= run_queue
+      acknowledge_response = lambda do |response|
+        # The EM thread already registered @pending_runs[actual_run_id] in
+        # handle_response. Clean up the idempotency_key entry if a different
+        # runId was assigned.
+        actual_run_id = response&.dig(:runId) || idempotency_key
+        if actual_run_id != idempotency_key
+          @mutex.synchronize do
+            @pending_runs.delete(idempotency_key)
+            # Ensure runId is registered (may already be from handle_response)
+            @pending_runs[actual_run_id] ||= run_queue
+          end
         end
-      end
 
-      # Surface runId before streaming; guard so a faulty callback can't abort the stream.
-      if on_run_id
-        begin
-          on_run_id.call(actual_run_id)
-        rescue StandardError => e
-          Rails.logger.warn("[CollavreOpenclaw::WS] on_run_id callback failed: #{e.message}")
+        # Surface runId before streaming; guard so a faulty callback can't abort the stream.
+        if on_run_id
+          begin
+            on_run_id.call(actual_run_id)
+          rescue StandardError => e
+            Rails.logger.warn("[CollavreOpenclaw::WS] on_run_id callback failed: #{e.message}")
+          end
         end
       end
+      response = send_rpc(
+        "chat.send",
+        rpc_params,
+        request_id: rpc_request_id,
+        lifecycle_check: lifecycle_check,
+        &acknowledge_response
+      )
+      # Compatibility with test/custom send_rpc replacements that return a
+      # response but do not invoke the acknowledgement callback.
+      acknowledge_response.call(response) unless actual_run_id
 
       # Stream events until final/error/aborted
       last_seq = nil
 
       loop do
-        event = wait_with_timeout(run_queue, config.read_timeout, "chat response")
+        # The caller's block fires only on text deltas, and a run doing its
+        # tool work on the gateway can emit none for the whole turn. This is
+        # the checkpoint that does not depend on text: the wait below polls
+        # once before every event and once per idle slice, so both a flood of
+        # non-text events and total silence cross it. A raise unwinds through
+        # the adapter's CancelledError re-raise instead of holding this worker
+        # until read_timeout.
+        event = wait_for_chat_event(run_queue, config.read_timeout, lifecycle_check)
 
         break if event[:done]
 
@@ -268,6 +290,7 @@ module CollavreOpenclaw
         @pending_runs.delete(actual_run_id) if actual_run_id
         # Also clean up idempotency_key if send_rpc failed before we got a runId
         @pending_runs.delete(idempotency_key) if idempotency_key
+        @rpc_run_registrations.delete(rpc_request_id) if rpc_request_id
 
         # Record completed runs so late-arriving events are suppressed
         now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -599,7 +622,11 @@ module CollavreOpenclaw
     # @param request_id [String, nil] Pre-generated request ID. Used by chat_send
     #   to correlate the RPC response with the run_queue for EM-thread runId
     #   registration (see handle_response). If nil, a random UUID is generated.
-    def send_rpc(method, params, request_id: nil)
+    # @param lifecycle_check [#call, nil] Optional cooperative cancellation
+    #   check polled while waiting for an RPC response.
+    # @yield [Hash] successful response payload before a deferred lifecycle
+    #   error is re-raised, allowing chat.send to persist its acknowledged runId.
+    def send_rpc(method, params, request_id: nil, lifecycle_check: nil, &on_response)
       request_id ||= SecureRandom.uuid
       queue = Queue.new
 
@@ -616,13 +643,25 @@ module CollavreOpenclaw
         })
       end
 
-      result = wait_with_timeout(queue, config.read_timeout, method)
+      result = if lifecycle_check
+        wait_for_rpc_response(queue, config.read_timeout, method, lifecycle_check)
+      else
+        wait_with_timeout(queue, config.read_timeout, method)
+      end
       if result[:error]
         raise RpcError, "#{method} failed: #{result[:error]}"
       end
-      result[:payload]
+
+      payload = result[:payload]
+      on_response&.call(payload)
+      raise result[:deferred_lifecycle_error] if result[:deferred_lifecycle_error]
+
+      payload
     ensure
-      @mutex.synchronize { @pending_requests.delete(request_id) }
+      @mutex.synchronize do
+        @pending_requests.delete(request_id)
+        @rpc_run_registrations.delete(request_id)
+      end
     end
 
     def send_frame(frame)
@@ -697,6 +736,102 @@ module CollavreOpenclaw
       @user.email.split("@").first
     end
 
+    # Seconds between lifecycle_check invocations while waiting on a silent
+    # gateway. Matches AgentLifecycleManager::CANCEL_CHECK_INTERVAL — the
+    # check self-throttles at that interval, so polling faster buys nothing.
+    LIFECYCLE_POLL_INTERVAL = 1.0
+
+    # Wait for the next chat event. Without a lifecycle_check this is one
+    # blocking pop bounded by read_timeout, exactly as before. With one, the
+    # same total bound is kept but the wait is sliced so the check runs
+    # between slices — a run that goes quiet doing gateway-side tool work is
+    # otherwise unobservable until read_timeout (30 minutes by default).
+    def wait_for_chat_event(queue, timeout_seconds, lifecycle_check)
+      return wait_with_timeout(queue, timeout_seconds, "chat response") unless lifecycle_check
+
+      event = wait_with_lifecycle_poll(queue, timeout_seconds, "chat response", lifecycle_check)
+      force_lifecycle_check(lifecycle_check) if terminal_chat_event?(event)
+      event
+    end
+
+    # A chat.send acknowledgement is the provider handoff record: handle_response
+    # registers the Gateway runId before queueing it. If cancellation becomes
+    # visible at the same time, consume that acknowledgement first so chat_send
+    # can surface the runId and clean up its registration. The following chat
+    # event wait will still observe cancellation before consuming any run event.
+    def wait_for_rpc_response(queue, timeout_seconds, operation, lifecycle_check)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
+      loop do
+        result = pop_queue_nonblock(queue)
+        if result
+          force_lifecycle_check(lifecycle_check) unless result[:ok]
+          return result
+        end
+
+        begin
+          lifecycle_check.call
+        rescue StandardError => error
+          # Close the narrow race where the response arrived while the
+          # lifecycle check was reading terminal state from the database. This
+          # includes wrapped lifecycle infrastructure failures as well as
+          # cancellation. Only a successful response proves handoff; an RPC
+          # error must not replace the lifecycle failure that just won.
+          result = pop_queue_nonblock(queue)
+          if result&.dig(:ok)
+            result[:deferred_lifecycle_error] = error
+            return result
+          end
+          raise
+        end
+
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise TimeoutError, "#{operation} timed out after #{timeout_seconds}s" if remaining <= 0
+
+        result = queue.pop(timeout: [ LIFECYCLE_POLL_INTERVAL, remaining ].min)
+        if result
+          force_lifecycle_check(lifecycle_check) unless result[:ok]
+          return result
+        end
+      end
+    end
+
+    def wait_with_lifecycle_poll(queue, timeout_seconds, operation, lifecycle_check)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
+      loop do
+        lifecycle_check.call
+
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise TimeoutError, "#{operation} timed out after #{timeout_seconds}s" if remaining <= 0
+
+        event = queue.pop(timeout: [ LIFECYCLE_POLL_INTERVAL, remaining ].min)
+        return event if event
+      end
+    end
+
+    def terminal_chat_event?(event)
+      event[:done] || %w[final error aborted].include?(event[:state])
+    end
+
+    # Production lifecycle checks accept a force flag that bypasses their
+    # one-second database polling throttle. Keep zero-argument test/custom
+    # callables compatible while still checking at a terminal event boundary.
+    def force_lifecycle_check(lifecycle_check)
+      parameters = if lifecycle_check.respond_to?(:parameters)
+        lifecycle_check.parameters
+      else
+        lifecycle_check.method(:call).parameters
+      end
+      accepts_argument = parameters.any? { |type, _name| %i[req opt rest].include?(type) }
+
+      accepts_argument ? lifecycle_check.call(true) : lifecycle_check.call
+    end
+
+    def pop_queue_nonblock(queue)
+      queue.pop(true)
+    rescue ThreadError
+      nil
+    end
+
     def wait_with_timeout(queue, timeout_seconds, operation)
       # Use Queue#pop(timeout:) instead of Timeout.timeout to avoid Thread.raise corruption
       result = queue.pop(timeout: timeout_seconds)

data/config/initializers/ai_client_extension.rb

@@ -11,5 +11,16 @@ Rails.application.config.to_prepare do
       Collavre::AiClient.register_adapter("openclaw", CollavreOpenclaw::OpenclawAdapter)
       Rails.logger.info("[CollavreOpenclaw] Registered OpenClaw adapter")
     end
+
+    # OpenClaw uses stateful, incremental sessions and appears in the AI-agent
+    # vendor dropdown. Register both into core so core needs no OpenClaw name of
+    # its own to decide session support or list the vendor. Both registrations
+    # are idempotent, so re-running on reload is safe.
+    if Collavre::AiClient.respond_to?(:register_session_vendor)
+      Collavre::AiClient.register_session_vendor("openclaw")
+    end
+    if Collavre::AiClient.respond_to?(:register_vendor_option)
+      Collavre::AiClient.register_vendor_option("OpenClaw", "openclaw")
+    end
   end
 end

data/config/initializers/trigger_loop_patterns.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# An OpenClaw gateway error banner marks a task result the agent never actually
+# produced, so the trigger loop must retry it without consuming an iteration.
+# Register the OpenClaw-specific signature into the core trigger-loop infra-error
+# registry so core keeps only vendor-neutral patterns. Runs on boot and every
+# reload; registration is idempotent.
+Rails.application.config.to_prepare do
+  if defined?(Collavre::TriggerLoopCheckJob)
+    Collavre::TriggerLoopCheckJob.register_infrastructure_error_pattern(/OpenClaw Error/i)
+  end
+end

data/lib/collavre_openclaw/version.rb

@@ -1,3 +1,3 @@
 module CollavreOpenclaw
-  VERSION = "0.6.4"
+  VERSION = "0.6.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: collavre_openclaw
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.6.6
 platform: ruby
 authors:
 - Collavre
@@ -92,6 +92,7 @@ files:
 - config/initializers/ai_client_extension.rb
 - config/initializers/integration_settings.rb
 - config/initializers/session_abort.rb
+- config/initializers/trigger_loop_patterns.rb
 - config/locales/en.yml
 - config/locales/ko.yml
 - config/routes.rb