collavre_openclaw 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0cefe1bfe3e0bc5a5d810a0aea5543e468a6539ec26aa48515a1617340a1ea6b
+  data.tar.gz: 4c48629590b7b95ada9771d18c42bce1db9ea97a3532bc081e0ec3fc80115d16
+SHA512:
+  metadata.gz: ab7224c85ec72ea2d7bed38257136495a0e6fc8b74a33c558373bd822bba5b1be92c594bbdbdb22a67836afc02a6e350bcd9923b31767a454d5af279424473de
+  data.tar.gz: 0d8adb020df29a332597afbe9964b19e77cb35d79744487c935fe759e6aa75593812f9a245d9c1b462ec0f7e19a1f90d6027f7ddde0997509952b543c915942d

data/README.md

@@ -0,0 +1,285 @@
+# Collavre OpenClaw Integration
+
+This engine enables AI agents in Collavre to use [OpenClaw](https://github.com/openclaw/openclaw) as their LLM backend, with support for bidirectional communication.
+
+## Features
+
+- **OpenAI-compatible API**: Uses OpenClaw's `/v1/chat/completions` endpoint
+- **Streaming responses**: Real-time streaming of AI responses
+- **Proactive messaging**: OpenClaw can send messages to Collavre without user prompt
+- **Secure callbacks**: Nonce-based authentication for callback requests (no tokens exposed)
+- **Topic-based sessions**: Each Topic gets its own OpenClaw session (isolated context)
+- **Multi-user support**: Multiple users can share the same Topic context with sender attribution
+
+## Installation
+
+The engine is automatically loaded when placed in the `engines/` directory of a Collavre installation.
+
+### Run Migrations
+
+```bash
+bin/rails db:migrate
+```
+
+## Configuration
+
+### Environment Variables
+
+- `OPENCLAW_READ_TIMEOUT` - Read timeout for streaming responses (default: 180 seconds)
+- `OPENCLAW_OPEN_TIMEOUT` - Connection timeout (default: 10 seconds)
+- `OPENCLAW_MAX_RETRIES` - Max retries for transient failures (default: 2)
+
+### Setting up an AI Agent with OpenClaw
+
+1. Create an AI agent user in Collavre
+2. Set the `llm_vendor` to `"openclaw"`
+3. Configure the OpenClaw account with:
+   - **Gateway URL**: The URL of your OpenClaw gateway
+   - **API Token**: (Optional) For authentication to OpenClaw
+   - **Channel ID**: (Optional) Specific channel to use
+
+## Session Mapping
+
+Collavre's structure maps to OpenClaw sessions as follows:
+
+```
+Collavre                          OpenClaw
+─────────────────────────────────────────────────────
+Creative (Chat Room)
+  └── Topic A ──────────────────→ Session A
+  │     ├── [User1]: "Hello"      (shared context)
+  │     ├── [User2]: "Hi there"
+  │     └── AI: "Hello everyone!"
+  │
+  └── Topic B ──────────────────→ Session B
+        └── [User1]: "New topic"   (isolated context)
+```
+
+**Key concepts:**
+- **Topic = Session**: Each Topic gets its own OpenClaw session
+- **Shared context**: All users in the same Topic share the conversation history
+- **User attribution**: Messages include sender name: `[Username]: message`
+- **Session key**: Stable key based on `account:creative:topic` (not nonce)
+
+### Session Key Format
+
+```
+collavre:<account_id>:creative:<creative_id>:topic:<topic_id>
+```
+
+This key is sent via `x-openclaw-session-key` header to ensure stable session routing.
+
+## How it Works
+
+### Request Flow (Collavre → OpenClaw)
+
+```
+User mentions AI agent in Collavre
+    ↓
+OpenclawAdapter builds request with context
+    ↓
+Creates PendingCallback with secure nonce
+    ↓
+Sends request to OpenClaw /v1/chat/completions
+    ↓
+Streams response back to Collavre
+```
+
+### Callback Flow (OpenClaw → Collavre)
+
+```
+OpenClaw wants to send proactive message
+    ↓
+Extracts nonce from user context
+    ↓
+POST /openclaw/callback/:account_id
+    { "nonce": "...", "type": "proactive", "content": "..." }
+    ↓
+Collavre verifies nonce (one-time use)
+    ↓
+Creates comment on the creative
+```
+
+## API Endpoints
+
+### `POST /openclaw/callback/:account_id`
+
+Webhook endpoint for receiving messages from OpenClaw.
+
+**Authentication Methods** (in priority order):
+
+1. **Nonce** (recommended, most secure):
+   ```json
+   {
+     "nonce": "abc123...",
+     "type": "proactive",
+     "content": "Hello from OpenClaw!"
+   }
+   ```
+   - Nonce is provided in the `user` field when Collavre sends requests
+   - One-time use, expires after 10 minutes
+   - No token exposure
+
+2. **HMAC Signature**:
+   ```
+   X-OpenClaw-Signature: <hmac-sha256-hex>
+   ```
+   - Signature = HMAC-SHA256(api_token, request_body)
+
+3. **Bearer Token**:
+   ```
+   Authorization: Bearer <api_token>
+   ```
+
+### Payload Types
+
+**Proactive Message** (OpenClaw initiates):
+```json
+{
+  "type": "proactive",
+  "nonce": "callback_nonce_from_user_context",
+  "content": "This is a proactive message from AI!",
+  "creative_id": 123,  // Optional if using nonce
+  "thread_id": 456     // Optional
+}
+```
+
+**Response** (async response to request):
+```json
+{
+  "type": "response",
+  "nonce": "...",
+  "content": "AI response content",
+  "context": {
+    "comment_id": 789  // Updates existing comment
+  }
+}
+```
+
+**Error**:
+```json
+{
+  "type": "error",
+  "nonce": "...",
+  "error": "Rate limit exceeded"
+}
+```
+
+### `GET /openclaw/health`
+
+Health check endpoint.
+
+## Security
+
+### Nonce-based Authentication
+
+When Collavre sends a request to OpenClaw, it includes callback information in the `user` field:
+
+```json
+{
+  "model": "openclaw",
+  "messages": [...],
+  "user": "collavre:{\"callback_url\":\"https://collavre.com/openclaw/callback/1\",\"callback_nonce\":\"abc123...\",\"creative_id\":456}"
+}
+```
+
+The nonce:
+- Is unique per request
+- Expires after 10 minutes
+- Can only be used once (consumed on verification)
+- Is tied to a specific account
+
+This means:
+- **No tokens are transmitted** in the callback request
+- **Replay attacks are prevented** (nonce is consumed)
+- **Expired requests are rejected**
+- **Cross-account attacks are blocked** (nonce is bound to account)
+
+### Cleanup
+
+Expired pending callbacks are automatically cleaned up. You can also run:
+
+```ruby
+CollavreOpenclaw::PendingCallback.cleanup_expired!
+```
+
+## OpenAI API Compatibility
+
+OpenClaw Gateway provides an **OpenAI-compatible Chat Completions endpoint** at `/v1/chat/completions`.
+
+### Enabling the Endpoint
+
+In your OpenClaw Gateway config (`openclaw.config.json5`):
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        chatCompletions: { enabled: true }
+      }
+    }
+  }
+}
+```
+
+### Authentication
+
+Send a bearer token:
+```
+Authorization: Bearer <token>
+```
+
+### Example: Non-streaming Request
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/chat/completions \
+  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "openclaw:main",
+    "messages": [{"role":"user","content":"Hello!"}]
+  }'
+```
+
+### Example: Streaming Request (SSE)
+
+```bash
+curl -N http://127.0.0.1:18789/v1/chat/completions \
+  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "openclaw:main",
+    "stream": true,
+    "messages": [{"role":"user","content":"Hello!"}]
+  }'
+```
+
+## OpenClaw Callback (For OpenClaw Users)
+
+When OpenClaw receives a request from Collavre, the `user` field contains callback information:
+
+```
+collavre:{"callback_url":"https://...","callback_nonce":"...","creative_id":123}
+```
+
+To send a proactive message back:
+
+```bash
+# Parse the user field to extract callback info
+CALLBACK_URL="https://collavre.com/openclaw/callback/1"
+NONCE="abc123..."
+
+# Send proactive message (no auth header needed - nonce is the auth)
+curl -X POST "$CALLBACK_URL" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "proactive",
+    "nonce": "'"$NONCE"'",
+    "content": "Hello from OpenClaw!"
+  }'
+```
+
+## License
+
+AGPL-3.0, same as Collavre.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+
+desc "Run engine tests"
+task :test do
+  Dir.glob("test/**/*_test.rb").each { |f| require_relative f }
+end
+
+task default: :test

data/app/controllers/collavre_openclaw/application_controller.rb

@@ -0,0 +1,22 @@
+module CollavreOpenclaw
+  class ApplicationController < ::ApplicationController
+    protect_from_forgery with: :exception
+
+    private
+
+    # Helper to access this engine's routes
+    def collavre_openclaw
+      CollavreOpenclaw::Engine.routes.url_helpers
+    end
+
+    # Helper to access Collavre engine routes
+    def collavre
+      Collavre::Engine.routes.url_helpers
+    end
+
+    # Helper to access main app routes
+    def main_app
+      Rails.application.routes.url_helpers
+    end
+  end
+end

data/app/controllers/collavre_openclaw/callbacks_controller.rb

@@ -0,0 +1,78 @@
+module CollavreOpenclaw
+  class CallbacksController < ApplicationController
+    skip_forgery_protection only: :create
+    allow_unauthenticated_access only: :create
+
+    # Handle JSON parsing errors at Rails level
+    rescue_from ActionDispatch::Http::Parameters::ParseError do |_exception|
+      render json: { error: "Invalid JSON" }, status: :bad_request
+    end
+
+    def create
+      user = User.find_by(id: params[:user_id])
+
+      unless user
+        render json: { error: "User not found" }, status: :not_found
+        return
+      end
+
+      # Parse payload first
+      begin
+        payload = JSON.parse(request.raw_post, symbolize_names: true)
+      rescue JSON::ParserError
+        render json: { error: "Invalid JSON" }, status: :bad_request
+        return
+      end
+
+      # Authenticate the request via nonce
+      auth_result = authenticate_request(user, payload)
+      unless auth_result[:success]
+        render json: { error: auth_result[:error] }, status: :unauthorized
+        return
+      end
+
+      # Merge context from pending callback if nonce was used
+      if auth_result[:pending_callback]
+        payload = merge_pending_callback_context(payload, auth_result[:pending_callback])
+      end
+
+      # Process the callback payload
+      CallbackProcessorJob.perform_later(user.id, payload.deep_stringify_keys)
+
+      head :ok
+    end
+
+    private
+
+    # Authenticate using nonce verification
+    def authenticate_request(user, payload)
+      # Nonce verification (required for callbacks)
+      nonce = payload[:nonce] || payload[:callback_nonce]
+      if nonce.present?
+        pending = PendingCallback.verify_and_consume!(nonce)
+        if pending && pending.user_id == user.id
+          return { success: true, pending_callback: pending }
+        else
+          return { success: false, error: "Invalid or expired nonce" }
+        end
+      end
+
+      { success: false, error: "Nonce required for callback authentication" }
+    end
+
+    def merge_pending_callback_context(payload, pending)
+      # Add context from pending callback
+      payload[:context] ||= {}
+      payload[:context][:creative_id] ||= pending.creative_id
+      payload[:context][:comment_id] ||= pending.comment_id
+      payload[:context][:thread_id] ||= pending.thread_id
+
+      # Merge any extra context stored in pending callback
+      if pending.context.present?
+        payload[:context].merge!(pending.context.deep_symbolize_keys)
+      end
+
+      payload
+    end
+  end
+end

data/app/controllers/collavre_openclaw/health_controller.rb

@@ -0,0 +1,13 @@
+module CollavreOpenclaw
+  class HealthController < ApplicationController
+    allow_unauthenticated_access only: :show
+
+    def show
+      render json: {
+        status: "ok",
+        engine: "collavre_openclaw",
+        version: CollavreOpenclaw::VERSION
+      }
+    end
+  end
+end

data/app/jobs/collavre_openclaw/application_job.rb

@@ -0,0 +1,5 @@
+module CollavreOpenclaw
+  class ApplicationJob < ActiveJob::Base
+    queue_as :default
+  end
+end

data/app/jobs/collavre_openclaw/callback_processor_job.rb

@@ -0,0 +1,124 @@
+module CollavreOpenclaw
+  class CallbackProcessorJob < ApplicationJob
+    queue_as :default
+
+    def perform(user_id, payload)
+      @user = User.find_by(id: user_id)
+      return unless @user
+
+      # Symbolize keys for consistent access
+      payload = payload.deep_symbolize_keys
+
+      Rails.logger.info("[CollavreOpenclaw] Processing callback for user #{user_id}, type: #{payload[:type]}")
+
+      case payload[:type]&.to_s
+      when "response"
+        handle_response(payload)
+      when "proactive"
+        handle_proactive(payload)
+      when "error"
+        handle_error(payload)
+      else
+        # Default: try to handle as response for backward compatibility
+        if payload[:content].present? || payload[:message].present?
+          handle_response(payload)
+        else
+          Rails.logger.warn("[CollavreOpenclaw] Unknown callback type: #{payload[:type]}")
+        end
+      end
+    end
+
+    private
+
+    # Handle async response to a previous request
+    def handle_response(payload)
+      context = payload[:context] || {}
+      creative_id = context[:creative_id]
+      comment_id = context[:comment_id]
+      content = payload[:content] || payload[:message]
+
+      if comment_id.present?
+        # Update existing comment (streaming completion)
+        comment = Collavre::Comment.find_by(id: comment_id)
+        if comment && content.present?
+          comment.update!(content: content)
+          Rails.logger.info("[CollavreOpenclaw] Updated comment #{comment_id} with callback response")
+        end
+      elsif creative_id.present? && content.present?
+        # Create new comment on the creative
+        create_ai_comment(creative_id, content, context)
+      end
+    end
+
+    # Handle proactive message from OpenClaw (agent-initiated)
+    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)
+      parent_comment_id = payload[:parent_comment_id] || payload.dig(:context, :parent_comment_id)
+
+      unless creative_id.present?
+        Rails.logger.error("[CollavreOpenclaw] Proactive message missing creative_id")
+        return
+      end
+
+      unless content.present?
+        Rails.logger.error("[CollavreOpenclaw] Proactive message missing content")
+        return
+      end
+
+      context = {
+        thread_id: thread_id,
+        parent_comment_id: parent_comment_id,
+        proactive: true
+      }
+
+      create_ai_comment(creative_id, content, context)
+    end
+
+    def handle_error(payload)
+      error_message = payload[:error] || payload[:message] || "Unknown error"
+      Rails.logger.error("[CollavreOpenclaw] Callback error: #{error_message}")
+
+      # Optionally notify the creative if context is available
+      creative_id = payload.dig(:context, :creative_id)
+      if creative_id.present?
+        create_ai_comment(
+          creative_id,
+          "⚠️ OpenClaw Error: #{error_message}",
+          { error: true }
+        )
+      end
+    end
+
+    def create_ai_comment(creative_id, content, context = {})
+      creative = Collavre::Creative.find_by(id: creative_id)
+      unless creative
+        Rails.logger.error("[CollavreOpenclaw] Creative not found: #{creative_id}")
+        return
+      end
+
+      # Build comment attributes
+      comment_attrs = {
+        creative: creative.effective_origin,
+        user: @user,
+        content: content,
+        private: false
+      }
+
+      # Handle topic/thread if specified
+      if context[:thread_id].present?
+        topic = Collavre::Topic.find_by(id: context[:thread_id])
+        comment_attrs[:topic] = topic if topic
+      end
+
+      comment = Collavre::Comment.create!(comment_attrs)
+      Rails.logger.info("[CollavreOpenclaw] Created AI comment #{comment.id} on creative #{creative_id}")
+
+      comment
+    rescue ActiveRecord::RecordInvalid => e
+      Rails.logger.error("[CollavreOpenclaw] Failed to create comment: #{e.message}")
+      nil
+    end
+  end
+end

data/app/models/collavre_openclaw/application_record.rb

@@ -0,0 +1,5 @@
+module CollavreOpenclaw
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/collavre_openclaw/pending_callback.rb

@@ -0,0 +1,53 @@
+module CollavreOpenclaw
+  class PendingCallback < ApplicationRecord
+    self.table_name = "openclaw_pending_callbacks"
+
+    belongs_to :user, class_name: "::User"
+
+    # Serialize context as JSON for SQLite compatibility
+    serialize :context, coder: JSON
+
+    validates :nonce, presence: true, uniqueness: true
+    validates :expires_at, presence: true
+
+    scope :valid, -> { where("expires_at > ?", Time.current) }
+    scope :expired, -> { where("expires_at <= ?", Time.current) }
+
+    # Default expiration time (7 days to support scheduled callbacks like cron jobs)
+    EXPIRATION_TIME = 7.days
+
+    # Generate a new pending callback for a request
+    def self.create_for_request(user:, creative_id: nil, comment_id: nil, thread_id: nil, context: {})
+      create!(
+        user: user,
+        nonce: generate_nonce,
+        creative_id: creative_id,
+        comment_id: comment_id,
+        thread_id: thread_id,
+        context: context || {},
+        expires_at: EXPIRATION_TIME.from_now
+      )
+    end
+
+    # Verify and consume a nonce (one-time use)
+    def self.verify_and_consume!(nonce)
+      callback = valid.find_by(nonce: nonce)
+      return nil unless callback
+
+      # Consume the nonce (delete it)
+      callback.destroy!
+      callback
+    end
+
+    # Cleanup expired callbacks
+    def self.cleanup_expired!
+      expired.delete_all
+    end
+
+    private
+
+    def self.generate_nonce
+      SecureRandom.urlsafe_base64(32)
+    end
+  end
+end

data/app/services/collavre_openclaw/ai_client_extension.rb

@@ -0,0 +1,61 @@
+module CollavreOpenclaw
+  module AiClientExtension
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def adapter_registry
+        @adapter_registry ||= {}
+      end
+
+      def register_adapter(vendor, adapter_class)
+        adapter_registry[vendor.to_s.downcase] = adapter_class
+      end
+    end
+
+    def chat(contents, tools: [], &block)
+      normalized_vendor = vendor.to_s.downcase
+
+      # Check if we have a custom adapter for this vendor
+      adapter_class = self.class.adapter_registry[normalized_vendor]
+
+      if adapter_class
+        # Use the custom adapter
+        user = context&.dig(:user)
+        adapter = adapter_class.new(
+          user: user,
+          system_prompt: system_prompt,
+          context: context
+        )
+
+        response_content = nil
+        error_message = nil
+
+        begin
+          response_content = adapter.chat(contents, tools: tools, &block)
+        rescue StandardError => e
+          error_message = e.message
+          raise
+        ensure
+          # Log the interaction just like AiClient does
+          log_interaction(
+            messages: Array(contents),
+            tools: tools,
+            response_content: response_content,
+            error_message: error_message,
+            input_tokens: nil,
+            output_tokens: nil
+          )
+        end
+
+        return response_content
+      end
+
+      # Fall back to original implementation
+      super
+    end
+
+    private
+
+    attr_reader :vendor, :system_prompt, :context
+  end
+end