collavre_openclaw 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55f1fde91ceaf7db785f461e7463ae966ad015006ecba5bf8be22ac57f79d834
-  data.tar.gz: 736ef6e4237b38fcc055d73a0d188d404389ed66b6ce9ed0a45e3ab0edf66b50
+  metadata.gz: ff18cc7843b54de3c5e86de861f69b9225aa47dd7e57aae94cd612d7698d1d55
+  data.tar.gz: 8b83ffc51769d3946de8660b0583ccc672079f08d80db9b93178c12c1c374279
 SHA512:
-  metadata.gz: 5b249de9cc87980cf465d513af74900fead2c8ddb0c05262d578e821afec6830391e6bf8b30c7f57da0aa277945684c654a7435dfd081ef6da059f93bb7cacf7
-  data.tar.gz: cd4f77c3f1536726ecd3d1078922c8ab3a335307fae35a34aa52352cca58376c95e6d9f8bc23a5ec8609c4935606ca803579f23e17d22ad62c5f3bc78e5405e2
+  metadata.gz: 54bf09a092ed87b269621100c55edadd8fd0591f41f25270672f27cf6837d3767dff33a3cff6bb6fe4315c90cbb5d596805b6ce6d2ec055eb5d0cd0f73e7d5d6
+  data.tar.gz: b967fc6beb11b41889b0574b937b94532910acba29e9b349e2ec40289fcb57bd9096ea4cf06756a5db05acdc5f9a13a51c1c3474fb8fe85709e1c68fafe703dc

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/ai_client_extension.rb

@@ -12,8 +12,11 @@ module CollavreOpenclaw
       end
     end
 
-    def chat(contents, tools: [], &block)
+    # @param messages_input [Hash, Array] Hash { messages:, first_message:, context_changed: }
+    #   from MessageBuilder, or a plain Array from standalone callers (e.g., CompressJob).
+    def chat(messages_input, tools: [], &block)
       normalized_vendor = vendor.to_s.downcase
+      messages_data = normalize_messages_input(messages_input)
 
       # Check if we have a custom adapter for this vendor
       adapter_class = self.class.adapter_registry[normalized_vendor]
@@ -31,13 +34,13 @@ module CollavreOpenclaw
         error_message = nil
 
         begin
-          response_content = adapter.chat(contents, &block)
+          response_content = adapter.chat(messages_data, &block)
         rescue StandardError => e
           error_message = e.message
           raise
         ensure
           log_interaction(
-            messages: Array(contents),
+            messages: messages_data[:messages],
             tools: [],
             response_content: response_content,
             error_message: error_message,
@@ -49,12 +52,24 @@ module CollavreOpenclaw
         return response_content
       end
 
-      # Fall back to original implementation
-      super
+      # Fall back to original RubyLLM implementation (expects Array)
+      super(messages_data[:messages], tools: tools, &block)
     end
 
     private
 
     attr_reader :vendor, :system_prompt, :context
+
+    # Wrap plain Array input (from standalone callers like CompressJob)
+    # into the Hash format expected by the adapter.
+    def normalize_messages_input(input)
+      return input if input.is_a?(Hash)
+
+      {
+        messages: Array(input).map { |m| m.merge(kind: :trigger) },
+        first_message: true,
+        context_changed: false
+      }
+    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

@@ -20,7 +20,10 @@ module CollavreOpenclaw
       @context = context
     end
 
-    def chat(messages, &block)
+    # @param messages_data [Hash] { messages:, first_message:, context_changed: }
+    def chat(messages_data, &block)
+      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?
@@ -37,12 +40,12 @@ 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)")
-        chat_via_http(messages, &block)
+        Rails.logger.info("[CollavreOpenclaw::WS] TRANSPORT mode=http_forced")
+        chat_via_http(&block)
       elsif websocket_available?
-        chat_via_websocket(messages, &block)
+        chat_via_websocket(&block)
       else
-        chat_via_http(messages, &block)
+        chat_via_http(&block)
       end
     end
 
@@ -69,6 +72,27 @@ module CollavreOpenclaw
 
     private
 
+    CONTEXT_KINDS = %i[creative_context context_creative referenced_creative].freeze
+
+    def parse_messages_data!(data)
+      @all_messages    = data[:messages] || []
+      @first_message   = data[:first_message]
+      @context_changed = data[:context_changed]
+    end
+
+    def context_messages
+      @all_messages.select { |m| CONTEXT_KINDS.include?(m[:kind]) }
+    end
+
+    def trigger_message
+      @all_messages.find { |m| m[:kind] == :trigger }
+    end
+
+    # Send system prompt and context on first message or when they changed.
+    def include_full_context?
+      @first_message || @context_changed
+    end
+
     # ─────────────────────────────────────────────
     # WebSocket transport
     # ─────────────────────────────────────────────
@@ -83,18 +107,19 @@ module CollavreOpenclaw
       false
     end
 
-    def chat_via_websocket(messages, &block)
+    def chat_via_websocket(&block)
       response_content = +""
 
       begin
         client = ConnectionManager.instance.connection_for(@user)
-        message_text = format_message_for_ws(messages)
+        payload = build_ws_chat_payload
 
-        Rails.logger.info("[CollavreOpenclaw] Sending via WebSocket (session: #{session_key})")
+        Rails.logger.info("[CollavreOpenclaw] Sending via WebSocket (session: #{session_key}, first: #{@first_message}, changed: #{@context_changed})")
 
         client.chat_send(
           session_key: session_key,
-          message: message_text
+          message: payload[:message],
+          attachments: payload[:attachments]
         ) do |event|
           case event[:state]
           when "delta"
@@ -119,8 +144,8 @@ module CollavreOpenclaw
         response_content.presence
       rescue CollavreOpenclaw::ConnectionError,
              CollavreOpenclaw::TimeoutError => e
-        Rails.logger.warn("[CollavreOpenclaw] WebSocket failed, falling back to HTTP: #{e.message}")
-        chat_via_http(messages, &block)
+        Rails.logger.warn("[CollavreOpenclaw::WS] FALLBACK gateway=#{@user.gateway_url} reason=#{e.class}:#{e.message}")
+        chat_via_http(&block)
       rescue CollavreOpenclaw::ChatError, CollavreOpenclaw::RpcError => e
         Rails.logger.error("[CollavreOpenclaw] WebSocket chat error: #{e.message}")
         error_msg = "OpenClaw Error: #{e.message}"
@@ -129,64 +154,48 @@ 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")
-        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.
-    def format_message_for_ws(messages)
-      formatted = Array(messages)
-
-      # Extract the last user message
-      last_user = formatted.reverse.find do |m|
-        role = m[:role] || m["role"]
-        role.to_s == "user"
-      end
-
-      return "" unless last_user
-
-      text = extract_message_text(last_user)
-
-      # 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}"
-        end
+        Rails.logger.info("[CollavreOpenclaw::WS] FALLBACK gateway=#{@user.gateway_url} reason=#{e.class}:#{e.message}")
+        chat_via_http(&block)
       end
-
-      text.to_s
     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"
-      end
+    # Build WebSocket chat.send payload.
+    #
+    # Token optimization: only includes system prompt and creative context on
+    # the first message or when context has changed. The Gateway maintains its
+    # own session history, so chat history is never sent — only the trigger.
+    def build_ws_chat_payload
+      trigger = trigger_message
+      {
+        message: format_message_for_ws,
+        attachments: trigger ? extract_ws_attachments([ trigger ]).presence : nil
+      }
     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:")
+    # Format messages for WebSocket chat.send text payload.
+    #
+    # On first message (or context change):
+    #   [system prompt] + [creative context] + [trigger]
+    # On subsequent messages:
+    #   [trigger only]
+    #
+    # Chat history is NOT included — the Gateway's SessionManager tracks
+    # conversation turns automatically.
+    def format_message_for_ws
+      parts = []
+
+      if include_full_context?
+        parts << @system_prompt if @system_prompt.present?
+        context_messages.each do |m|
+          text = extract_message_text(m)
+          parts << text if text.present?
+        end
       end
 
-      return nil unless context_msg
+      trigger = trigger_message
+      parts << extract_message_text(trigger) if trigger
 
-      extract_message_text(context_msg)
+      parts.join("\n\n")
     end
 
     def extract_message_text(message)
@@ -205,6 +214,12 @@ module CollavreOpenclaw
       Array(parts).filter_map { |part| part[:image] || part["image"] }
     end
 
+    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 encode_image_source(source)
       if defined?(ActiveStorage) && source.is_a?(ActiveStorage::Blob)
         data = Base64.strict_encode64(source.download)
@@ -239,17 +254,54 @@ module CollavreOpenclaw
       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
+
     # ─────────────────────────────────────────────
     # HTTP transport (fallback)
     # ─────────────────────────────────────────────
 
-    def chat_via_http(messages, &block)
+    def chat_via_http(&block)
       response_content = +""
 
       begin
-        payload = build_payload(messages)
+        payload = build_payload
 
-        Rails.logger.info("[CollavreOpenclaw] Sending via HTTP to #{api_endpoint} (session: #{session_key})")
+        Rails.logger.info("[CollavreOpenclaw] Sending via HTTP to #{api_endpoint} (session: #{session_key}, first: #{@first_message}, changed: #{@context_changed})")
 
         stream_response(payload) do |chunk|
           response_content << chunk
@@ -281,7 +333,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 ]
@@ -295,22 +347,35 @@ module CollavreOpenclaw
     # HTTP payload building
     # ─────────────────────────────────────────────
 
-    def build_payload(messages)
+    # Build HTTP payload with token optimization.
+    #
+    # On first message (or context change):
+    #   system prompt + creative context + trigger
+    # On subsequent messages:
+    #   trigger only
+    #
+    # Chat history is NOT included — the Gateway's SessionManager tracks
+    # conversation turns via the stable session key.
+    def build_payload
       agent_id = extract_agent_id_from_email
       model_value = agent_id.present? ? "openclaw:#{agent_id}" : "openclaw"
 
-      payload = {
-        model: model_value,
-        messages: format_messages(messages),
-        stream: true
-      }
+      formatted = []
 
-      if @system_prompt.present?
-        payload[:messages].unshift({ role: "system", content: @system_prompt })
+      if include_full_context?
+        formatted << { role: "system", content: @system_prompt } if @system_prompt.present?
+        context_messages.each { |m| formatted << format_single_message(m) }
       end
 
-      payload[:user] = build_user_context
-      payload
+      trigger = trigger_message
+      formatted << format_single_message(trigger) if trigger
+
+      {
+        model: model_value,
+        messages: formatted,
+        stream: true,
+        user: build_user_context
+      }
     end
 
     def build_user_context
@@ -318,7 +383,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?
@@ -346,28 +411,26 @@ module CollavreOpenclaw
       end
     end
 
-    def format_messages(messages)
-      Array(messages).map do |msg|
-        role = msg[:role] || msg["role"]
-        text = extract_message_text(msg)
+    def format_single_message(msg)
+      role = msg[:role] || msg["role"]
+      text = extract_message_text(msg)
 
-        sender_name = msg[:sender_name] || msg["sender_name"]
-        if sender_name.present? && normalize_role(role) == "user"
-          text = "[#{sender_name}]: #{text}"
-        end
+      sender_name = msg[:sender_name] || msg["sender_name"]
+      if sender_name.present? && normalize_role(role) == "user"
+        text = "[#{sender_name}]: #{text}"
+      end
 
-        image_sources = extract_image_sources(msg)
+      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 }
+      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
 
@@ -539,6 +602,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?
@@ -234,6 +265,21 @@ module CollavreOpenclaw
       end
     end
 
+    # Inject an assistant message into a session transcript.
+    # Useful for pre-populating context without triggering an agent run.
+    #
+    # @param session_key [String]
+    # @param message [String] content to inject
+    # @param label [String, nil] optional label for the injected message
+    def chat_inject(session_key:, message:, label: nil)
+      ensure_connected!
+      touch_activity!
+
+      params = { sessionKey: session_key, message: message }
+      params[:label] = label if label
+      send_rpc("chat.inject", params)
+    end
+
     # Fetch chat history for a session
     def chat_history(session_key:, limit: nil)
       ensure_connected!
@@ -260,6 +306,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 +324,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 +370,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 +380,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 +471,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 +485,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 +512,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 +528,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 +575,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 +639,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 +654,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.4.0"
+  VERSION = "0.6.0"
 end

metadata

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