collavre_openclaw 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7022c888e2fbe72f646eba7d022d489ff1458da405058638c0b15bc426076ec
-  data.tar.gz: 4b822a95fba2cba72b9ceda1d8a92f24919b8982221d8ef4ce1ed6cddea4ade0
+  metadata.gz: 47fb3ac9892c9b3c1ee7531645732dd47acdba3b7504d048cd207ff8ae4fa82e
+  data.tar.gz: e6233d85c5bff7f28ad2201b0cb84df1fe6c62827cd23666de54ef64060f41d5
 SHA512:
-  metadata.gz: 26df63f943760253bba51dd0667e06a6fdac8821a5982e49163d9d6114f94eed5ff110f47d4af58531e22a966f7efa669f3cacafb608c3446b9d025530b9806f
-  data.tar.gz: 33b8d566a78989521fe384add9bdedbdce668422c9658176c4c9cd2aa5620e31fa3fe247f7aefb82fd045ba33573bcfce391f2d3f88c8788c32a6d4737ce3cdb
+  metadata.gz: 1a8b34146dedfcec60bc2b0b78ac4f9f51448c8b2bd3ee9064e24d24ac7854271e8cb943b5083da143ec9a18e7470b869e927f2b680db1518ff6a324897a0dc9
+  data.tar.gz: 6f97da70c3443dcda6087cfa114b5f068cb952e567b90849a07b27239d6df89c55cafa07f35e76a2c864337d02e56f9cc328e5bc33f8655af4fd87ec93c4dee7

data/app/controllers/collavre_openclaw/callbacks_controller.rb

@@ -66,6 +66,7 @@ module CollavreOpenclaw
       payload[:context][:creative_id] ||= pending.creative_id
       payload[:context][:comment_id] ||= pending.comment_id
       payload[:context][:thread_id] ||= pending.thread_id
+      payload[:context][:topic_id] ||= pending.thread_id
 
       # Merge any extra context stored in pending callback
       if pending.context.present?

data/app/controllers/collavre_openclaw/health_controller.rb

@@ -3,11 +3,28 @@ module CollavreOpenclaw
     allow_unauthenticated_access only: :show
 
     def show
-      render json: {
+      payload = {
         status: "ok",
         engine: "collavre_openclaw",
         version: CollavreOpenclaw::VERSION
       }
+
+      # WebSocket details only for authenticated requests
+      if authenticated?
+        payload[:transport] = CollavreOpenclaw.config.transport
+        payload[:websocket] = ConnectionManager.status_summary
+        payload[:reactor] = { running: EmReactor.running? }
+      end
+
+      render json: payload
+    end
+
+    private
+
+    def authenticated?
+      respond_to?(:current_user, true) && current_user.present?
+    rescue
+      false
     end
   end
 end

data/app/jobs/collavre_openclaw/callback_processor_job.rb

@@ -39,6 +39,8 @@ module CollavreOpenclaw
       comment_id = context[:comment_id]
       content = payload[:content] || payload[:message]
 
+      normalize_topic_context!(context)
+
       if comment_id.present?
         # Update existing comment (streaming completion)
         comment = Collavre::Comment.find_by(id: comment_id)
@@ -56,7 +58,7 @@ module CollavreOpenclaw
     def handle_proactive(payload)
       creative_id = payload[:creative_id] || payload.dig(:context, :creative_id)
       content = payload[:content] || payload[:message]
-      thread_id = payload[:thread_id] || payload.dig(:context, :thread_id)
+      thread_id = payload[:thread_id] || payload[:topic_id] || payload.dig(:context, :thread_id) || payload.dig(:context, :topic_id)
       parent_comment_id = payload[:parent_comment_id] || payload.dig(:context, :parent_comment_id)
 
       unless creative_id.present?
@@ -94,6 +96,8 @@ module CollavreOpenclaw
     end
 
     def create_ai_comment(creative_id, content, context = {})
+      normalize_topic_context!(context)
+
       creative = Collavre::Creative.find_by(id: creative_id)
       unless creative
         Rails.logger.error("[CollavreOpenclaw] Creative not found: #{creative_id}")
@@ -135,5 +139,13 @@ module CollavreOpenclaw
       Rails.logger.error("[CollavreOpenclaw] Failed to create comment: #{e.message}")
       nil
     end
+
+    def normalize_topic_context!(context)
+      return unless context.is_a?(Hash)
+      return if context[:thread_id].present?
+
+      topic_id = context[:topic_id]
+      context[:thread_id] = topic_id if topic_id.present?
+    end
   end
 end

data/app/services/collavre_openclaw/connection_manager.rb

@@ -43,10 +43,17 @@ module CollavreOpenclaw
         client = @connections[gateway_url]
 
         if client.nil?
-          client = WebsocketClient.new(user: user)
-          client.on_proactive_message(&@proactive_handler) if @proactive_handler
-          @connections[gateway_url] = client
-          @gateway_users[gateway_url] = Set.new
+          client = create_client(user, gateway_url)
+        elsif client.user.llm_api_key != user.llm_api_key
+          # Same gateway_url but different API key. This is a configuration
+          # error: one Gateway = one API key. Log a warning so the admin
+          # notices, rather than silently ignoring the second user's key.
+          # In HTTP mode this would surface as a 401 on each request.
+          Rails.logger.warn(
+            "[CollavreOpenclaw::ConnectionManager] API key mismatch for gateway #{gateway_url}: " \
+            "user #{user.id} has a different key than connection owner #{client.user.id}. " \
+            "The connection uses the owner's key. Verify AI agent settings."
+          )
         end
 
         # Track this user as using this gateway
@@ -109,6 +116,17 @@ module CollavreOpenclaw
       end
     end
 
+    # Safe accessor: returns status without triggering singleton initialization.
+    # Use this from controllers/monitoring instead of instance_variable_get.
+    def self.status_summary
+      if instance_variable_defined?(:@singleton__instance__) && @singleton__instance__
+        instance.status
+      else
+        { total_connections: 0, total_users: 0,
+          connected: 0, connecting: 0, reconnecting: 0, disconnected: 0 }
+      end
+    end
+
     # Register a proactive message handler for all connections.
     # New connections will also get this handler.
     def on_proactive_message(&handler)
@@ -138,6 +156,35 @@ module CollavreOpenclaw
 
     private
 
+    # Create a new WebsocketClient and wire up handlers.
+    def create_client(user, gateway_url)
+      client = WebsocketClient.new(user: user)
+      client.on_proactive_message(&@proactive_handler) if @proactive_handler
+      client.on_fatal_close do |dead_client|
+        handle_fatal_close(gateway_url, dead_client)
+      end
+      @connections[gateway_url] = client
+      @gateway_users[gateway_url] ||= Set.new
+      client
+    end
+
+    # Called when a client receives a fatal close code (auth failure, etc.).
+    # Removes the dead client so the next connection_for call creates a fresh one.
+    #
+    # Guard: only deletes if the current mapping still points to dead_client.
+    # Without this, a late-arriving callback from an old client could wipe a
+    # new live connection that was already registered for the same gateway_url.
+    def handle_fatal_close(gateway_url, dead_client)
+      @mutex.synchronize do
+        return unless @connections[gateway_url].equal?(dead_client)
+
+        Rails.logger.warn("[CollavreOpenclaw::ConnectionManager] Fatal close for gateway #{gateway_url}, removing connection")
+        @connections.delete(gateway_url)
+        user_ids = @gateway_users.delete(gateway_url) || Set.new
+        user_ids.each { |uid| @user_gateways.delete(uid) }
+      end
+    end
+
     # Set up the default proactive message handler that dispatches
     # unsolicited chat events to CallbackProcessorJob.
     def setup_default_proactive_handler!

data/app/services/collavre_openclaw/openclaw_adapter.rb

@@ -37,7 +37,7 @@ module CollavreOpenclaw
       # Try WebSocket first, fall back to HTTP
       # Set OPENCLAW_TRANSPORT=http to force HTTP-only mode
       if CollavreOpenclaw.config.transport == "http"
-        Rails.logger.info("[CollavreOpenclaw] Using HTTP transport (forced by config)")
+        Rails.logger.info("[CollavreOpenclaw::WS] TRANSPORT mode=http_forced")
         chat_via_http(messages, &block)
       elsif websocket_available?
         chat_via_websocket(messages, &block)
@@ -88,13 +88,14 @@ module CollavreOpenclaw
 
       begin
         client = ConnectionManager.instance.connection_for(@user)
-        message_text = format_message_for_ws(messages)
+        payload = build_ws_chat_payload(messages)
 
         Rails.logger.info("[CollavreOpenclaw] Sending via WebSocket (session: #{session_key})")
 
         client.chat_send(
           session_key: session_key,
-          message: message_text
+          message: payload[:message],
+          attachments: payload[:attachments]
         ) do |event|
           case event[:state]
           when "delta"
@@ -119,7 +120,7 @@ module CollavreOpenclaw
         response_content.presence
       rescue CollavreOpenclaw::ConnectionError,
              CollavreOpenclaw::TimeoutError => e
-        Rails.logger.warn("[CollavreOpenclaw] WebSocket failed, falling back to HTTP: #{e.message}")
+        Rails.logger.warn("[CollavreOpenclaw::WS] FALLBACK gateway=#{@user.gateway_url} reason=#{e.class}:#{e.message}")
         chat_via_http(messages, &block)
       rescue CollavreOpenclaw::ChatError, CollavreOpenclaw::RpcError => e
         Rails.logger.error("[CollavreOpenclaw] WebSocket chat error: #{e.message}")
@@ -129,73 +130,167 @@ module CollavreOpenclaw
       rescue StandardError => e
         Rails.logger.error("[CollavreOpenclaw] WebSocket unexpected error: #{e.message}\n" \
                            "#{e.backtrace.first(5).join("\n")}")
-        Rails.logger.info("[CollavreOpenclaw] Falling back to HTTP")
+        Rails.logger.info("[CollavreOpenclaw::WS] FALLBACK gateway=#{@user.gateway_url} reason=#{e.class}:#{e.message}")
         chat_via_http(messages, &block)
       end
     end
 
-    # Format messages for WebSocket chat.send (single message string).
-    # Gateway manages session history, so we only send the latest user message
-    # with optional context prefix on the FIRST message only.
+    # Build WebSocket chat.send payload.
+    #
+    # Includes the same full text context as HTTP mode plus optional base64
+    # image attachments supported by the Gateway's chat.send.attachments field.
+    def build_ws_chat_payload(messages)
+      {
+        message: format_message_for_ws(messages),
+        attachments: extract_ws_attachments(messages).presence
+      }
+    end
+
+    # Format messages for WebSocket chat.send text payload.
+    #
+    # Includes full context on EVERY request, matching HTTP mode behavior.
+    # The Gateway's WS session may be new (no prior history), so we cannot
+    # assume context was sent before. This is consistent with how the HTTP
+    # Chat Completions API works (full history on every request).
+    #
+    # Message structure sent:
+    #   [system prompt]
+    #   [creative context messages]
+    #   [context creative messages]
+    #   [chat history]
+    #   [latest user message]
     def format_message_for_ws(messages)
       formatted = Array(messages)
+      return "" if formatted.empty?
+
+      parts = []
 
-      # Extract the last user message
-      last_user = formatted.reverse.find do |m|
+      # 1. System prompt (same as HTTP mode's build_payload)
+      parts << @system_prompt if @system_prompt.present?
+
+      # 2. All context messages (Creative:, Context Creative:, Referenced Creative:)
+      formatted.each do |m|
         role = m[:role] || m["role"]
-        role.to_s == "user"
+        next unless role.to_s == "user"
+
+        text = extract_message_text(m)
+        next unless text.present?
+        next unless text.match?(/\A(Creative|Context Creative|Referenced Creative)\s*\(/)
+
+        parts << text
       end
 
-      return "" unless last_user
+      # 3. Chat history (prior user/assistant exchanges)
+      formatted.each do |m|
+        role = (m[:role] || m["role"]).to_s
+        text = extract_message_text(m)
+        next unless text.present?
 
-      text = extract_message_text(last_user)
+        # Skip context messages (already included above)
+        next if text.match?(/\A(Creative|Context Creative|Referenced Creative)\s*\(/)
 
-      # Only prepend creative context on the first message in a session.
-      # If there are prior assistant replies, the Gateway already has context.
-      if first_message_in_session?(formatted)
-        context_prefix = build_context_prefix(formatted)
-        if context_prefix.present?
-          return "#{context_prefix}\n\n#{text}"
+        case role
+        when "user"
+          parts << text
+        when "assistant", "model"
+          parts << "[Assistant]: #{text}"
         end
       end
 
-      text.to_s
+      parts.join("\n\n")
     end
 
-    # Returns true when this looks like the first exchange in a session
-    # (no prior assistant messages in the conversation history).
-    def first_message_in_session?(messages)
-      messages.none? do |m|
-        role = (m[:role] || m["role"]).to_s
-        # "model" is used by some providers (e.g. Gemini) as an alias for "assistant"
-        role == "assistant" || role == "model"
+    def extract_message_text(message)
+      parts = message[:parts] || message["parts"]
+      if parts
+        Array(parts).filter_map { |p| p[:text] || p["text"] }.join("\n")
+      else
+        message[:text] || message["text"] || message[:content] || message["content"]
       end
     end
 
-    # Build a context prefix from system/context messages if present.
-    # This includes creative tree markdown and other context that the Gateway
-    # wouldn't have from its own agent config.
-    def build_context_prefix(messages)
-      # Find the first "user" message that looks like creative context
-      # (typically starts with "Creative:\n")
-      context_msg = messages.find do |m|
-        role = m[:role] || m["role"]
-        text = extract_message_text(m)
-        role.to_s == "user" && text&.start_with?("Creative:")
-      end
+    def extract_image_sources(message)
+      parts = message[:parts] || message["parts"]
+      return [] if parts.nil?
 
-      return nil unless context_msg
+      Array(parts).filter_map { |part| part[:image] || part["image"] }
+    end
 
-      extract_message_text(context_msg)
+    def extract_ws_attachments(messages)
+      Array(messages).flat_map do |message|
+        extract_image_sources(message).filter_map { |source| encode_image_source_for_ws(source) }
+      end
     end
 
-    def extract_message_text(message)
-      parts = message[:parts] || message["parts"]
-      if parts
-        Array(parts).filter_map { |p| p[:text] || p["text"] }.join("\n")
+    def encode_image_source(source)
+      if defined?(ActiveStorage) && source.is_a?(ActiveStorage::Blob)
+        data = Base64.strict_encode64(source.download)
+        {
+          type: "image_url",
+          image_url: { url: "data:#{source.content_type};base64,#{data}" }
+        }
+      elsif source.respond_to?(:download)
+        # ActiveStorage::Attached::One
+        blob = source.respond_to?(:blob) ? source.blob : source
+        return nil unless blob
+
+        data = Base64.strict_encode64(blob.download)
+        {
+          type: "image_url",
+          image_url: { url: "data:#{blob.content_type};base64,#{data}" }
+        }
+      elsif source.is_a?(String) && source.match?(%r{^https?://})
+        { type: "image_url", image_url: { url: source } }
+      elsif source.is_a?(String)
+        # File path
+        return nil unless File.exist?(source)
+
+        mime = Marcel::MimeType.for(Pathname.new(source))
+        data = Base64.strict_encode64(File.binread(source))
+        { type: "image_url", image_url: { url: "data:#{mime};base64,#{data}" } }
       else
-        message[:text] || message["text"] || message[:content] || message["content"]
+        nil
+      end
+    rescue StandardError => e
+      Rails.logger.warn("[CollavreOpenclaw] Failed to encode image: #{e.message}")
+      nil
+    end
+
+    def encode_image_source_for_ws(source)
+      if defined?(ActiveStorage) && source.is_a?(ActiveStorage::Blob)
+        {
+          type: "image",
+          mimeType: source.content_type,
+          fileName: source.filename.to_s,
+          content: Base64.strict_encode64(source.download)
+        }
+      elsif source.respond_to?(:download)
+        blob = source.respond_to?(:blob) ? source.blob : source
+        return nil unless blob
+
+        {
+          type: "image",
+          mimeType: blob.content_type,
+          fileName: blob.filename.to_s,
+          content: Base64.strict_encode64(blob.download)
+        }
+      elsif source.is_a?(String) && source.match?(%r{^https?://})
+        nil
+      elsif source.is_a?(String)
+        return nil unless File.exist?(source)
+
+        {
+          type: "image",
+          mimeType: Marcel::MimeType.for(Pathname.new(source)),
+          fileName: File.basename(source),
+          content: Base64.strict_encode64(File.binread(source))
+        }
+      else
+        nil
       end
+    rescue StandardError => e
+      Rails.logger.warn("[CollavreOpenclaw] Failed to encode WS image attachment: #{e.message}")
+      nil
     end
 
     # ─────────────────────────────────────────────
@@ -240,7 +335,7 @@ module CollavreOpenclaw
     # Format: agent:<agent_id>:collavre:<user_id>:creative:<id>:topic:<id>
     def build_session_key
       creative_id = extract_id(@context, :creative) || @context[:creative_id]
-      topic_id = @context[:thread_id] || @context[:topic_id]
+      topic_id = @context[:thread_id] || @context[:topic_id] || infer_topic_id
       agent_id = extract_agent_id_from_email || "main"
 
       parts = [ "agent", agent_id, "collavre", @user.id ]
@@ -277,7 +372,7 @@ module CollavreOpenclaw
 
       creative_id = extract_id(@context, :creative) || @context[:creative_id]
       comment_id = extract_id(@context, :comment) || @context[:comment_id]
-      topic_id = @context[:thread_id] || @context[:topic_id]
+      topic_id = @context[:thread_id] || @context[:topic_id] || infer_topic_id
 
       callback = callback_url
       if callback.present? && creative_id.present?
@@ -308,14 +403,25 @@ module CollavreOpenclaw
     def format_messages(messages)
       Array(messages).map do |msg|
         role = msg[:role] || msg["role"]
-        content = extract_message_text(msg)
+        text = extract_message_text(msg)
 
         sender_name = msg[:sender_name] || msg["sender_name"]
         if sender_name.present? && normalize_role(role) == "user"
-          content = "[#{sender_name}]: #{content}"
+          text = "[#{sender_name}]: #{text}"
         end
 
-        { role: normalize_role(role), content: content.to_s }
+        image_sources = extract_image_sources(msg)
+
+        if image_sources.any?
+          content_parts = [ { type: "text", text: text.to_s } ]
+          image_sources.each do |source|
+            image_data = encode_image_source(source)
+            content_parts << image_data if image_data
+          end
+          { role: normalize_role(role), content: content_parts }
+        else
+          { role: normalize_role(role), content: text.to_s }
+        end
       end
     end
 
@@ -487,6 +593,15 @@ module CollavreOpenclaw
       @user.email.split("@").first
     end
 
+    # Infer topic_id from the comment object in context when not explicitly provided.
+    # AiAgentService passes :comment (the reply or original comment) which carries topic_id.
+    def infer_topic_id
+      comment = @context[:comment]
+      return comment.topic_id if comment.respond_to?(:topic_id) && comment.topic_id.present?
+
+      nil
+    end
+
     def default_url_options
       options = Rails.application.config.action_mailer.default_url_options || {}
 

data/app/services/collavre_openclaw/websocket_client.rb

@@ -22,6 +22,20 @@ module CollavreOpenclaw
     COMPLETED_RUN_COOLDOWN = 5  # seconds to suppress late-arriving events for completed runs
     SEEN_EVENT_TTL = 30         # seconds to remember (runId, seq) pairs for dedup
 
+    # WebSocket close codes → reconnection policy
+    # :reconnect — schedule reconnect with exponential backoff
+    # :fatal     — permanent failure (auth, forbidden), don't retry, propagate error
+    # :normal    — clean shutdown, no reconnect, no error
+    CLOSE_POLICIES = {
+      1000 => :normal,      # Normal closure
+      1001 => :reconnect,   # Going away (server shutting down)
+      1006 => :reconnect,   # Abnormal closure (network issue)
+      1008 => :fatal,       # Policy violation (likely auth)
+      1011 => :reconnect,   # Internal server error
+      4001 => :fatal,       # Auth failure (OpenClaw)
+      4003 => :fatal       # Forbidden (OpenClaw)
+    }.freeze
+
     attr_reader :user, :state
 
     # States: :disconnected, :connecting, :connected, :reconnecting
@@ -39,8 +53,7 @@ module CollavreOpenclaw
       @proactive_handler = nil
       @reconnect_attempts = 0
       @last_activity_at = nil
-      @tick_interval_ms = 15_000
-      @tick_timer = nil
+      @rpc_run_registrations = {} # RPC request_id → run_queue (for EM-thread runId registration)
     end
 
     def connected?
@@ -52,7 +65,6 @@ module CollavreOpenclaw
     def connect!
       return if connected?
 
-      initiator = false
       waiter_queue = nil
 
       @connect_mutex.synchronize do
@@ -64,7 +76,6 @@ module CollavreOpenclaw
           @connect_waiters << waiter_queue
         else
           @state = :connecting
-          initiator = true
         end
       end
 
@@ -126,7 +137,6 @@ module CollavreOpenclaw
     def disconnect!
       @state = :disconnected
       EmReactor.next_tick do
-        cancel_tick_timer!
         @ws&.close
         @ws = nil
       end
@@ -135,16 +145,18 @@ module CollavreOpenclaw
       @pending_requests.clear
       @pending_runs.each_value { |q| q.push({ done: true }) }
       @pending_runs.clear
+      @rpc_run_registrations.clear
     end
 
     # Send a chat message. Blocks and yields streaming events.
     #
     # @param session_key [String]
     # @param message [String]
+    # @param attachments [Array<Hash>, nil]
     # @param idempotency_key [String]
     # @yield [Hash] chat events with :state, :text, :message keys
     # @return [String, nil] final response text
-    def chat_send(session_key:, message:, idempotency_key: nil, &block)
+    def chat_send(session_key:, message:, attachments: nil, idempotency_key: nil, &block)
       ensure_connected!
       touch_activity!
 
@@ -156,19 +168,33 @@ module CollavreOpenclaw
       # Pre-register with idempotency_key to catch early events
       @mutex.synchronize { @pending_runs[idempotency_key] = run_queue }
 
-      # Send the RPC request to get the real runId
-      response = send_rpc("chat.send", {
+      # Send the RPC request to get the real runId.
+      # IMPORTANT: We pass the run_queue via @rpc_run_registrations so that
+      # handle_response can register @pending_runs[actual_run_id] on the EM
+      # thread BEFORE any subsequent chat events arrive. This prevents a race
+      # condition where fast Gateway responses send events before the Rails
+      # thread can re-register with the actual runId.
+      rpc_request_id = SecureRandom.uuid
+      @mutex.synchronize { @rpc_run_registrations[rpc_request_id] = run_queue }
+
+      rpc_params = {
         sessionKey: session_key,
         message: message,
         idempotencyKey: idempotency_key
-      })
+      }
+      rpc_params[:attachments] = attachments if attachments.present?
+
+      response = send_rpc("chat.send", rpc_params, request_id: rpc_request_id)
 
-      # Re-register with the Gateway-assigned runId
+      # 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)
-          @pending_runs[actual_run_id] = run_queue
+          # Ensure runId is registered (may already be from handle_response)
+          @pending_runs[actual_run_id] ||= run_queue
         end
       end
 
@@ -185,14 +211,19 @@ module CollavreOpenclaw
         end
 
         # Gateway may broadcast + nodeSend the same event, causing
-        # duplicates on the same WebSocket.  Skip already-seen seqs.
+        # duplicates on the same WebSocket. Skip already-seen seqs for
+        # deltas only. Terminal events (final, error, aborted) must NEVER
+        # be skipped — they break the loop and unblock the caller.
         seq = event[:seq]
-        if seq && last_seq && seq <= last_seq
+        event_state = event[:state]
+        is_terminal = event_state == "final" || event_state == "error" || event_state == "aborted"
+
+        if !is_terminal && seq && last_seq && seq <= last_seq
           next
         end
         last_seq = seq if seq
 
-        case event[:state]
+        case event_state
         when "delta"
           text = extract_event_text(event)
           if text.present?
@@ -260,6 +291,12 @@ module CollavreOpenclaw
       @proactive_handler = handler
     end
 
+    # Register a callback invoked when the connection dies with a fatal close code
+    # (auth failure, forbidden, etc.). ConnectionManager uses this to remove dead clients.
+    def on_fatal_close(&handler)
+      @on_fatal_close = handler
+    end
+
     # Time since last activity (for idle timeout)
     def idle_seconds
       return Float::INFINITY unless @last_activity_at
@@ -272,6 +309,23 @@ module CollavreOpenclaw
       CollavreOpenclaw.config
     end
 
+    # Determine reconnection policy for a WebSocket close code.
+    # Returns :reconnect, :fatal, or :normal.
+    def close_policy(code)
+      CLOSE_POLICIES[code] || (code.to_i >= 4000 ? :fatal : :reconnect)
+    end
+
+    # Drain all pending requests and streaming runs with an error message.
+    # Called on fatal close to unblock waiting Rails threads.
+    def drain_pending_with_error!(message)
+      @mutex.synchronize do
+        @pending_requests.each_value { |pr| pr[:queue]&.push({ error: message }) }
+        @pending_requests.clear
+        @pending_runs.each_value { |q| q.push({ error: message }) }
+        @pending_runs.clear
+      end
+    end
+
     def gateway_ws_url
       url = @user.gateway_url.to_s.strip
       return nil if url.blank?
@@ -301,8 +355,7 @@ module CollavreOpenclaw
       @handshake_done = false
 
       @ws.on :open do |_event|
-        Rails.logger.info("[CollavreOpenclaw::WS] Connected to #{url}")
-        # Wait for connect.challenge from gateway
+        Rails.logger.info("[CollavreOpenclaw::WS] CONNECT gateway=#{url} state=open")
       end
 
       @ws.on :message do |event|
@@ -312,18 +365,26 @@ module CollavreOpenclaw
       @ws.on :close do |event|
         code = event.code
         reason = event.reason
-        Rails.logger.info("[CollavreOpenclaw::WS] Disconnected (code=#{code}, reason=#{reason})")
-
-        cancel_tick_timer!
+        policy = close_policy(code)
+        Rails.logger.info("[CollavreOpenclaw::WS] DISCONNECT gateway=#{url} code=#{code} reason=#{reason} policy=#{policy}")
 
         unless @handshake_done
           @handshake_done = true
           @handshake_queue&.push({ error: "Connection closed during handshake (code=#{code})" })
         end
 
-        if @state == :connected
-          @state = :reconnecting
-          schedule_reconnect!
+        case policy
+        when :reconnect
+          if @state == :connected || @state == :connecting
+            @state = :reconnecting
+            schedule_reconnect!
+          end
+        when :fatal
+          @state = :disconnected
+          drain_pending_with_error!("Connection closed with fatal code #{code}: #{reason}")
+          @on_fatal_close&.call(self)
+        when :normal
+          @state = :disconnected
         end
       end
     end
@@ -395,10 +456,8 @@ module CollavreOpenclaw
       if id == @connect_request_id && !@handshake_done
         @handshake_done = true
         if ok
-          @tick_interval_ms = payload&.dig(:policy, :tickIntervalMs) || 15_000
           @state = :connected
           @reconnect_attempts = 0
-          start_tick_timer!
           @handshake_queue&.push({ ok: true, payload: payload })
         else
           error_msg = error&.dig(:message) || error.to_s || "handshake failed"
@@ -411,6 +470,19 @@ module CollavreOpenclaw
       # Regular RPC response
       pending = @mutex.synchronize { @pending_requests.delete(id) }
       if pending
+        # If this RPC response contains a runId (chat.send response), register
+        # the run_queue under that runId NOW, on the EM thread, before any
+        # subsequent chat events arrive. This eliminates the race condition
+        # where fast events arrive before the Rails thread can re-register.
+        if ok && payload.is_a?(Hash) && payload[:runId]
+          run_queue = @mutex.synchronize { @rpc_run_registrations.delete(id) }
+          if run_queue
+            @mutex.synchronize { @pending_runs[payload[:runId]] = run_queue }
+          end
+        else
+          @mutex.synchronize { @rpc_run_registrations.delete(id) }
+        end
+
         if ok
           pending[:queue].push({ ok: true, payload: payload })
         else
@@ -425,9 +497,11 @@ module CollavreOpenclaw
       seq = payload[:seq]
 
       # Dedup: Gateway sends identical events via broadcast() + nodeSendToSession().
-      # Skip if we've already seen this (runId, seq) pair.
-      if run_id && seq && duplicate_chat_event?(run_id, seq)
-        Rails.logger.debug("[CollavreOpenclaw::WS] Skipping duplicate chat event (runId=#{run_id}, seq=#{seq})")
+      # Key includes state so that a delta and final with the same seq are NOT
+      # treated as duplicates (they are different events that share a seq number).
+      state = payload[:state]
+      if run_id && seq && duplicate_chat_event?(run_id, seq, state)
+        Rails.logger.debug("[CollavreOpenclaw::WS] CHAT run=#{run_id} seq=#{seq} state=dedup_skipped")
         return
       end
 
@@ -439,21 +513,22 @@ module CollavreOpenclaw
         run_queue.push(payload)
       elsif recently_completed_run?(run_id)
         # Late-arriving event for a run we already finished — suppress it
-        Rails.logger.info("[CollavreOpenclaw::WS] Suppressing late event for completed runId=#{run_id}")
+        Rails.logger.info("[CollavreOpenclaw::WS] CHAT run=#{run_id} state=late_suppressed")
       elsif @proactive_handler
         # Unknown run — proactive message from Gateway (cron/heartbeat)
-        Rails.logger.info("[CollavreOpenclaw::WS] Proactive message received (runId=#{run_id})")
+        Rails.logger.info("[CollavreOpenclaw::WS] CHAT run=#{run_id} state=proactive")
         @proactive_handler.call(@user, payload)
       else
-        Rails.logger.debug("[CollavreOpenclaw::WS] Ignoring chat event for unknown runId=#{run_id}")
+        Rails.logger.debug("[CollavreOpenclaw::WS] CHAT run=#{run_id} state=ignored_no_handler")
       end
     end
 
-    # Check if this (runId, seq) pair was already seen. Records it if new.
+    # Check if this (runId, seq, state) triple was already seen. Records it if new.
     # Gateway emits each event via broadcast() AND nodeSendToSession(),
-    # delivering the identical payload (same runId + seq) twice.
-    def duplicate_chat_event?(run_id, seq)
-      key = "#{run_id}:#{seq}"
+    # delivering the identical payload twice. Including state in the key
+    # ensures a delta and final with the same seq are treated as distinct events.
+    def duplicate_chat_event?(run_id, seq, state = nil)
+      key = "#{run_id}:#{seq}:#{state}"
       now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       @mutex.synchronize do
@@ -485,38 +560,21 @@ module CollavreOpenclaw
     end
 
     def handle_tick(_payload)
-      # Respond with a tick acknowledgment (poll response)
-      send_frame({
-        type: "req",
-        id: SecureRandom.uuid,
-        method: "poll",
-        params: {}
-      })
-    end
-
-    def start_tick_timer!
-      cancel_tick_timer!
-      interval = @tick_interval_ms / 1000.0
-      @tick_timer = EM.add_periodic_timer(interval) do
-        # Send keepalive poll if the server hasn't sent a tick
-        send_frame({
-          type: "req",
-          id: SecureRandom.uuid,
-          method: "poll",
-          params: {}
-        })
-      end
-    end
-
-    def cancel_tick_timer!
-      @tick_timer&.cancel
-      @tick_timer = nil
+      # The tick event from Gateway is a keepalive heartbeat.
+      # Receiving it already refreshes our activity timer (via touch_activity!
+      # in handle_raw_message). No response is needed.
     end
 
     # Send an RPC request and block until the response.
     # Returns the response payload.
-    def send_rpc(method, params)
-      request_id = SecureRandom.uuid
+    #
+    # @param method [String] RPC method name
+    # @param params [Hash] RPC parameters
+    # @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)
+      request_id ||= SecureRandom.uuid
       queue = Queue.new
 
       @mutex.synchronize do
@@ -566,7 +624,8 @@ module CollavreOpenclaw
       delay = config.ws_reconnect_base_delay * (2**(@reconnect_attempts - 1))
       delay = [ delay, 60 ].min # Cap at 60 seconds
 
-      Rails.logger.info("[CollavreOpenclaw::WS] Reconnecting in #{delay}s (attempt #{@reconnect_attempts}/#{max})")
+      url = gateway_ws_url
+      Rails.logger.info("[CollavreOpenclaw::WS] RECONNECT gateway=#{url} attempt=#{@reconnect_attempts}/#{max} delay=#{delay}s")
 
       EM.add_timer(delay) do
         next if @state == :disconnected # User explicitly disconnected
@@ -580,13 +639,13 @@ module CollavreOpenclaw
           EM.add_timer(config.ws_connect_timeout) do
             unless @handshake_done
               @handshake_done = true
-              Rails.logger.warn("[CollavreOpenclaw::WS] Reconnect handshake timed out")
+              Rails.logger.warn("[CollavreOpenclaw::WS] RECONNECT gateway=#{url} state=handshake_timeout")
               @ws&.close
               schedule_reconnect!
             end
           end
         rescue => e
-          Rails.logger.error("[CollavreOpenclaw::WS] Reconnect failed: #{e.message}")
+          Rails.logger.error("[CollavreOpenclaw::WS] RECONNECT gateway=#{url} state=fail reason=#{e.message}")
           schedule_reconnect!
         end
       end

data/lib/collavre_openclaw/configuration.rb

@@ -33,7 +33,7 @@ module CollavreOpenclaw
       @ws_reconnect_max = ENV.fetch("OPENCLAW_WS_RECONNECT_MAX", 10).to_i
       @ws_reconnect_base_delay = ENV.fetch("OPENCLAW_WS_RECONNECT_BASE", 1).to_f
       @ws_connect_timeout = ENV.fetch("OPENCLAW_WS_CONNECT_TIMEOUT", 10).to_i
-      @transport = ENV.fetch("OPENCLAW_TRANSPORT", "http")
+      @transport = ENV.fetch("OPENCLAW_TRANSPORT", "auto")
     end
 
     # Legacy accessor for backward compatibility

data/lib/collavre_openclaw/version.rb

@@ -1,3 +1,3 @@
 module CollavreOpenclaw
-  VERSION = "0.3.1"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: collavre_openclaw
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Collavre