language-operator 0.0.1 → 0.1.30

data/examples/oauth_callback_agent.rb

@@ -0,0 +1,296 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# OAuth Callback Agent Example
+#
+# This example shows how to create an agent that handles OAuth 2.0 callbacks
+# from various providers (GitHub, Google, etc.).
+#
+# Setup:
+# 1. Set OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET environment variables
+# 2. Configure OAuth provider redirect URI to https://<agent-url>/oauth/callback
+# 3. Set OAUTH_STATE_SECRET for state parameter verification
+#
+# OAuth 2.0 flow:
+# 1. User clicks "Login with Provider" -> redirected to provider
+# 2. User authorizes -> provider redirects to /oauth/callback with code
+# 3. Agent exchanges code for access token
+# 4. Agent fetches user info and creates session
+
+require 'bundler/setup'
+require 'language_operator'
+require 'net/http'
+require 'uri'
+
+LanguageOperator::Dsl.define_agents do
+  agent 'oauth-handler' do
+    description 'Handles OAuth callbacks and manages user authentication'
+
+    # Set to reactive mode to receive callbacks
+    mode :reactive
+
+    # GitHub OAuth callback
+    webhook '/oauth/github/callback' do
+      method :get
+
+      # Validate state parameter to prevent CSRF attacks
+      validate do |context|
+        state = context[:params]['state']
+        return 'Missing state parameter' unless state
+
+        # In production, verify state was generated by your app
+        # and hasn't been used before (store in Redis/database)
+        expected_state = ENV.fetch('OAUTH_STATE_SECRET', nil)
+        return 'Invalid state parameter' unless state == expected_state
+
+        true
+      end
+
+      on_request do |context|
+        code = context[:params]['code']
+        error = context[:params]['error']
+
+        # Handle OAuth errors
+        if error
+          return {
+            status: 'error',
+            error: error,
+            error_description: context[:params]['error_description'],
+            message: 'OAuth authorization failed'
+          }
+        end
+
+        # Exchange authorization code for access token
+        token_response = exchange_code_for_token(
+          code: code,
+          client_id: ENV.fetch('GITHUB_CLIENT_ID', nil),
+          client_secret: ENV.fetch('GITHUB_CLIENT_SECRET', nil),
+          token_url: 'https://github.com/login/oauth/access_token'
+        )
+
+        if token_response[:error]
+          return {
+            status: 'error',
+            error: token_response[:error],
+            message: 'Failed to exchange code for token'
+          }
+        end
+
+        access_token = token_response[:access_token]
+
+        # Fetch user info from GitHub
+        user_info = fetch_github_user(access_token)
+
+        {
+          status: 'success',
+          message: 'OAuth authentication successful',
+          user: {
+            id: user_info['id'],
+            username: user_info['login'],
+            email: user_info['email'],
+            name: user_info['name']
+          },
+          # In production, create session/JWT here
+          session_created: true
+        }
+      end
+    end
+
+    # Google OAuth callback
+    webhook '/oauth/google/callback' do
+      method :get
+
+      validate do |context|
+        state = context[:params]['state']
+        return 'Missing state parameter' unless state
+
+        expected_state = ENV.fetch('OAUTH_STATE_SECRET', nil)
+        return 'Invalid state parameter' unless state == expected_state
+
+        true
+      end
+
+      on_request do |context|
+        code = context[:params]['code']
+        error = context[:params]['error']
+
+        if error
+          return {
+            status: 'error',
+            error: error,
+            message: 'OAuth authorization failed'
+          }
+        end
+
+        # Exchange code for token
+        token_response = exchange_code_for_token(
+          code: code,
+          client_id: ENV.fetch('GOOGLE_CLIENT_ID', nil),
+          client_secret: ENV.fetch('GOOGLE_CLIENT_SECRET', nil),
+          token_url: 'https://oauth2.googleapis.com/token',
+          redirect_uri: ENV.fetch('GOOGLE_REDIRECT_URI', nil)
+        )
+
+        if token_response[:error]
+          return {
+            status: 'error',
+            error: token_response[:error],
+            message: 'Failed to exchange code for token'
+          }
+        end
+
+        access_token = token_response[:access_token]
+        token_response[:id_token]
+
+        # Fetch user info from Google
+        user_info = fetch_google_user(access_token)
+
+        {
+          status: 'success',
+          message: 'OAuth authentication successful',
+          user: {
+            id: user_info['id'],
+            email: user_info['email'],
+            name: user_info['name'],
+            picture: user_info['picture']
+          },
+          session_created: true
+        }
+      end
+    end
+
+    # Generic OAuth callback with bearer token auth
+    # (for testing or internal use)
+    webhook '/oauth/test/callback' do
+      method :post
+
+      # Require bearer token for security
+      authenticate do
+        verify_bearer_token(token: ENV.fetch('OAUTH_TEST_TOKEN', nil))
+      end
+
+      require_content_type 'application/json'
+
+      on_request do |context|
+        data = JSON.parse(context[:body])
+
+        {
+          status: 'success',
+          message: 'Test callback received',
+          data: data
+        }
+      end
+    end
+
+    # OAuth initiation endpoint (starts the flow)
+    webhook '/oauth/github/initiate' do
+      method :get
+
+      on_request do |_context|
+        # Generate state parameter for CSRF protection
+        SecureRandom.hex(32)
+
+        # In production, store state in Redis/database with expiration
+        # For demo purposes, we're just using a static value
+
+        # Build GitHub authorization URL
+        params = {
+          client_id: ENV.fetch('GITHUB_CLIENT_ID', nil),
+          redirect_uri: ENV.fetch('GITHUB_REDIRECT_URI', nil),
+          scope: 'user:email',
+          state: ENV.fetch('OAUTH_STATE_SECRET', nil) # Use proper state in production
+        }
+
+        auth_url = "https://github.com/login/oauth/authorize?#{URI.encode_www_form(params)}"
+
+        # Return redirect response
+        [
+          302,
+          { 'Location' => auth_url },
+          ['Redirecting to GitHub...']
+        ]
+      end
+    end
+
+    # Session verification endpoint
+    webhook '/oauth/verify' do
+      method :get
+
+      # Verify bearer token
+      authenticate do
+        verify_bearer_token(token: ENV.fetch('SESSION_TOKEN', nil))
+      end
+
+      on_request do |_context|
+        {
+          status: 'valid',
+          message: 'Session is valid',
+          authenticated: true
+        }
+      end
+    end
+  end
+end
+
+# Helper methods
+
+def exchange_code_for_token(code:, client_id:, client_secret:, token_url:, redirect_uri: nil)
+  uri = URI(token_url)
+
+  params = {
+    code: code,
+    client_id: client_id,
+    client_secret: client_secret,
+    grant_type: 'authorization_code'
+  }
+  params[:redirect_uri] = redirect_uri if redirect_uri
+
+  request = Net::HTTP::Post.new(uri)
+  request.set_form_data(params)
+  request['Accept'] = 'application/json'
+
+  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+    http.request(request)
+  end
+
+  JSON.parse(response.body, symbolize_names: true)
+rescue StandardError => e
+  { error: e.message }
+end
+
+def fetch_github_user(access_token)
+  uri = URI('https://api.github.com/user')
+
+  request = Net::HTTP::Get.new(uri)
+  request['Authorization'] = "Bearer #{access_token}"
+  request['Accept'] = 'application/vnd.github.v3+json'
+
+  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+    http.request(request)
+  end
+
+  JSON.parse(response.body)
+rescue StandardError => e
+  { error: e.message }
+end
+
+def fetch_google_user(access_token)
+  uri = URI('https://www.googleapis.com/oauth2/v2/userinfo')
+
+  request = Net::HTTP::Get.new(uri)
+  request['Authorization'] = "Bearer #{access_token}"
+
+  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+    http.request(request)
+  end
+
+  JSON.parse(response.body)
+rescue StandardError => e
+  { error: e.message }
+end
+
+# Run the agent if this file is executed directly
+if __FILE__ == $PROGRAM_NAME
+  agent = LanguageOperator::Dsl.agent_registry.get('oauth-handler')
+  agent.run!
+end

data/examples/stripe_webhook_agent.rb

@@ -0,0 +1,219 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Stripe Webhook Agent Example
+#
+# This example shows how to create an agent that receives Stripe webhook events
+# with proper signature verification for security.
+#
+# Setup:
+# 1. Set STRIPE_WEBHOOK_SECRET environment variable (from Stripe Dashboard)
+# 2. Configure Stripe webhook to send events to https://<agent-url>/stripe/events
+# 3. Select events you want to receive (e.g., payment_intent.succeeded, customer.created)
+#
+# Stripe webhook documentation:
+# https://stripe.com/docs/webhooks
+
+require 'bundler/setup'
+require 'language_operator'
+
+LanguageOperator::Dsl.define_agents do
+  agent 'stripe-payment-processor' do
+    description 'Processes Stripe payment events and triggers fulfillment'
+
+    # Set to reactive mode to receive webhooks
+    mode :reactive
+
+    # Stripe webhook endpoint
+    webhook '/stripe/events' do
+      method :post
+
+      # Verify Stripe webhook signature
+      # Stripe sends signature in Stripe-Signature header
+      # Format: "t=<timestamp>,v1=<signature>"
+      # Note: For simplicity, we're verifying the v1 signature
+      # Production should also check timestamp to prevent replay attacks
+      authenticate do
+        verify_custom do |context|
+          signature_header = context[:headers]['Stripe-Signature']
+          return false unless signature_header
+
+          # Parse signature header
+          # Format: t=1614556800,v1=abc123,v0=def456
+          sig_parts = {}
+          signature_header.split(',').each do |part|
+            key, value = part.split('=', 2)
+            sig_parts[key] = value
+          end
+
+          timestamp = sig_parts['t']
+          signature = sig_parts['v1']
+          return false unless timestamp && signature
+
+          # Construct signed payload
+          signed_payload = "#{timestamp}.#{context[:body]}"
+
+          # Compute expected signature
+          secret = ENV.fetch('STRIPE_WEBHOOK_SECRET', nil)
+          expected = OpenSSL::HMAC.hexdigest('sha256', secret, signed_payload)
+
+          # Compare signatures (constant-time)
+          signature == expected
+        end
+      end
+
+      # Validate request format
+      require_content_type 'application/json'
+
+      on_request do |context|
+        event = JSON.parse(context[:body])
+        event_type = event['type']
+        event_data = event['data']['object']
+
+        case event_type
+        when 'payment_intent.succeeded'
+          handle_payment_succeeded(event_data)
+        when 'payment_intent.payment_failed'
+          handle_payment_failed(event_data)
+        when 'customer.created'
+          handle_customer_created(event_data)
+        when 'customer.subscription.created'
+          handle_subscription_created(event_data)
+        when 'customer.subscription.deleted'
+          handle_subscription_deleted(event_data)
+        when 'invoice.payment_succeeded'
+          handle_invoice_paid(event_data)
+        when 'invoice.payment_failed'
+          handle_invoice_failed(event_data)
+        when 'charge.refunded'
+          handle_refund(event_data)
+        else
+          { status: 'ignored', event_type: event_type }
+        end
+      end
+    end
+
+    # Alternative endpoint with API key authentication
+    # Useful for testing or internal triggers
+    webhook '/stripe/manual-trigger' do
+      method :post
+
+      # Verify API key
+      authenticate do
+        verify_api_key(
+          header: 'X-API-Key',
+          key: ENV.fetch('STRIPE_INTERNAL_API_KEY', nil)
+        )
+      end
+
+      require_content_type 'application/json'
+
+      on_request do |context|
+        data = JSON.parse(context[:body])
+        action = data['action']
+
+        {
+          status: 'processed',
+          action: action,
+          message: "Manual trigger received: #{action}"
+        }
+      end
+    end
+  end
+end
+
+# Helper methods for event handling
+
+def handle_payment_succeeded(payment_intent)
+  {
+    status: 'processed',
+    event: 'payment_succeeded',
+    amount: payment_intent['amount'],
+    currency: payment_intent['currency'],
+    customer: payment_intent['customer'],
+    payment_intent_id: payment_intent['id'],
+    message: "Payment of #{payment_intent['amount']} #{payment_intent['currency']} succeeded"
+  }
+end
+
+def handle_payment_failed(payment_intent)
+  {
+    status: 'processed',
+    event: 'payment_failed',
+    amount: payment_intent['amount'],
+    currency: payment_intent['currency'],
+    customer: payment_intent['customer'],
+    error: payment_intent['last_payment_error']&.dig('message'),
+    message: 'Payment failed'
+  }
+end
+
+def handle_customer_created(customer)
+  {
+    status: 'processed',
+    event: 'customer_created',
+    customer_id: customer['id'],
+    email: customer['email'],
+    message: "New customer created: #{customer['email']}"
+  }
+end
+
+def handle_subscription_created(subscription)
+  {
+    status: 'processed',
+    event: 'subscription_created',
+    subscription_id: subscription['id'],
+    customer: subscription['customer'],
+    plan: subscription['items']['data'].first['price']['id'],
+    message: "New subscription created for customer #{subscription['customer']}"
+  }
+end
+
+def handle_subscription_deleted(subscription)
+  {
+    status: 'processed',
+    event: 'subscription_deleted',
+    subscription_id: subscription['id'],
+    customer: subscription['customer'],
+    message: "Subscription deleted for customer #{subscription['customer']}"
+  }
+end
+
+def handle_invoice_paid(invoice)
+  {
+    status: 'processed',
+    event: 'invoice_paid',
+    invoice_id: invoice['id'],
+    amount: invoice['amount_paid'],
+    customer: invoice['customer'],
+    message: "Invoice #{invoice['number']} paid"
+  }
+end
+
+def handle_invoice_failed(invoice)
+  {
+    status: 'processed',
+    event: 'invoice_failed',
+    invoice_id: invoice['id'],
+    amount: invoice['amount_due'],
+    customer: invoice['customer'],
+    message: "Invoice #{invoice['number']} payment failed"
+  }
+end
+
+def handle_refund(charge)
+  {
+    status: 'processed',
+    event: 'refund',
+    charge_id: charge['id'],
+    amount_refunded: charge['amount_refunded'],
+    customer: charge['customer'],
+    message: "Charge #{charge['id']} refunded"
+  }
+end
+
+# Run the agent if this file is executed directly
+if __FILE__ == $PROGRAM_NAME
+  agent = LanguageOperator::Dsl.agent_registry.get('stripe-payment-processor')
+  agent.run!
+end

data/examples/webhook_agent.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example webhook agent that demonstrates the reactive/HTTP server capability
+#
+# Usage:
+#   PORT=8080 ruby examples/webhook_agent.rb
+#
+# Test with curl:
+#   curl -X POST http://localhost:8080/webhook -H "Content-Type: application/json" -d '{"event": "test"}'
+#   curl http://localhost:8080/health
+
+require 'bundler/setup'
+require 'language_operator'
+require 'language_operator/dsl'
+
+# Define a webhook agent using the DSL
+# rubocop:disable Metrics/BlockLength
+LanguageOperator::Dsl.define do
+  agent 'example-webhook-handler' do
+    description 'Example agent that handles HTTP webhooks'
+    mode :reactive
+
+    # Health check endpoint (already provided by default)
+    # GET /health
+
+    # Custom webhook endpoint
+    webhook '/webhook' do
+      method :post
+      on_request do |context|
+        puts "\n=== Received Webhook ==="
+        puts "Method: #{context[:method]}"
+        puts "Path: #{context[:path]}"
+        puts "Body: #{context[:body]}"
+        puts "Params: #{context[:params].inspect}"
+        puts "========================\n"
+
+        {
+          status: 'received',
+          message: 'Webhook processed successfully',
+          received_data: context[:params]
+        }
+      end
+    end
+
+    # GitHub-style webhook endpoint
+    webhook '/github/pr' do
+      method :post
+      on_request do |_context|
+        puts "\n=== GitHub PR Webhook ==="
+        puts 'Simulating PR review...'
+        puts "============================\n"
+
+        {
+          status: 'pr_reviewed',
+          message: 'Pull request review queued'
+        }
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength
+
+# Get the agent definition and run it
+agent_def = LanguageOperator::Dsl.agent_registry.get('example-webhook-handler')
+
+if agent_def
+  puts "Starting webhook agent on port #{ENV.fetch('PORT', '8080')}"
+  puts 'Available endpoints:'
+  puts '  GET  /health        - Health check'
+  puts '  GET  /ready         - Readiness check'
+  puts '  POST /webhook       - Generic webhook'
+  puts '  POST /github/pr     - GitHub PR webhook'
+  puts "\nPress Ctrl+C to stop\n\n"
+
+  agent_def.run!
+else
+  puts 'Error: Agent definition not found'
+  exit 1
+end

data/lib/language_operator/agent/base.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative '../client'
+require_relative 'telemetry'
+require_relative 'instrumentation'
+
+module LanguageOperator
+  module Agent
+    # Base Agent Class
+    #
+    # Extends LanguageOperator::Client::Base with agent-specific functionality including:
+    # - Workspace integration
+    # - Goal-directed execution
+    # - Autonomous operation modes
+    #
+    # @example Basic agent
+    #   agent = LanguageOperator::Agent::Base.new(config)
+    #   agent.connect!
+    #   agent.execute_goal("Complete the task")
+    class Base < LanguageOperator::Client::Base
+      include Instrumentation
+
+      attr_reader :workspace_path, :mode
+
+      # Initialize the agent
+      #
+      # @param config [Hash] Configuration hash
+      def initialize(config)
+        super
+
+        # Initialize OpenTelemetry
+        LanguageOperator::Agent::Telemetry.configure
+        otel_enabled = !ENV.fetch('OTEL_EXPORTER_OTLP_ENDPOINT', nil).nil?
+        logger.info "OpenTelemetry #{otel_enabled ? 'enabled' : 'disabled'}"
+
+        @workspace_path = ENV.fetch('WORKSPACE_PATH', '/workspace')
+        @mode = ENV.fetch('AGENT_MODE', 'autonomous')
+        @executor = nil
+        @scheduler = nil
+      end
+
+      # Run the agent in its configured mode
+      #
+      # @return [void]
+      def run
+        with_span('agent.run', attributes: {
+                    'agent.name' => ENV.fetch('AGENT_NAME', nil),
+                    'agent.mode' => @mode,
+                    'agent.workspace_available' => workspace_available?
+                  }) do
+          connect!
+
+          case @mode
+          when 'autonomous', 'interactive'
+            run_autonomous
+          when 'scheduled', 'event-driven'
+            run_scheduled
+          when 'reactive', 'http', 'webhook'
+            run_reactive
+          else
+            raise "Unknown agent mode: #{@mode}"
+          end
+        end
+      end
+
+      # Execute a single goal
+      #
+      # @param goal [String] The goal to achieve
+      # @return [String] The result
+      def execute_goal(goal)
+        @executor ||= Executor.new(self)
+        @executor.execute(goal)
+      end
+
+      # Check if workspace is available
+      #
+      # @return [Boolean]
+      def workspace_available?
+        File.directory?(@workspace_path) && File.writable?(@workspace_path)
+      end
+
+      private
+
+      # Run in autonomous mode
+      #
+      # @return [void]
+      def run_autonomous
+        @executor = Executor.new(self)
+        @executor.run_loop
+      end
+
+      # Run in scheduled mode
+      #
+      # @return [void]
+      def run_scheduled
+        @scheduler = Scheduler.new(self)
+        @scheduler.start
+      end
+
+      # Run in reactive mode (HTTP server)
+      #
+      # @return [void]
+      def run_reactive
+        require_relative 'web_server'
+        @web_server = WebServer.new(self)
+        @web_server.start
+      end
+    end
+  end
+end