muxi 0.20260211.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2a71c3de149de10344234f91e906aa9282499252f85f9d732e7e786619675ac3
+  data.tar.gz: 46903422d8696f82902658d44817332a6ba6e2f7cbe5b1591b298215b57de7b6
+SHA512:
+  metadata.gz: 5edbf6f9ef3eccec33b8d4bba841f0eab3af71714a06a7516ba4ab4c3bdbc6319b1ad2f61ebfcb2e1adc6dd841a021aab7f2fb2f87f897dd9f9437c7292d78ca
+  data.tar.gz: 512e17859b7b6349ee81d3e023ee53bcdb8982298eecbafe47c6e8c3e0bfd85fe64d8979ff2bae3568f00e714d26ef183eb85ef4da4f8ad3ecd302537ff69b7a

data/.rubocop.yml

@@ -0,0 +1,28 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 500
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Layout/LineLength:
+  Max: 150

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- `mode` parameter in `FormationConfig` for draft/live URL routing
+  - `mode="live"` (default): Uses `/api/{id}/v1` prefix
+  - `mode="draft"`: Uses `/draft/{id}/v1` prefix for local development with `muxi up`
+- SDK version update notifications (via `X-Muxi-SDK-Latest` response header)
+  - Notifies when newer SDK version available (max once per 12 hours)
+  - Disable with `MUXI_SDK_VERSION_NOTIFICATION=0`
+- Console telemetry support via internal `_app` parameter

data/README.md

@@ -0,0 +1,160 @@
+# MUXI Ruby SDK
+
+Official Ruby SDK for [MUXI](https://muxi.org) — infrastructure for AI agents.
+
+**Highlights**
+- Pure Ruby with stdlib only (no external dependencies)
+- Built-in retries, idempotency, and typed errors
+- Streaming helpers for chat/audio and deploy/log tails
+
+> Need deeper usage notes? See the [User Guide](https://github.com/muxi-ai/muxi-ruby/blob/main/USER_GUIDE.md) for streaming, retries, and auth details.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'muxi'
+```
+
+Or install directly:
+
+```bash
+gem install muxi
+```
+
+## Quick Start
+
+### Server Management (Control Plane)
+
+```ruby
+require 'muxi'
+
+# Create a server client for managing formations
+server = Muxi::ServerClient.new(
+  url: ENV['MUXI_SERVER_URL'],
+  key_id: ENV['MUXI_KEY_ID'],
+  secret_key: ENV['MUXI_SECRET_KEY']
+)
+
+# List formations
+formations = server.list_formations
+formations['formations'].each do |f|
+  puts "#{f['id']}: #{f['status']}"
+end
+
+# Get server status
+status = server.status
+puts "Uptime: #{status['uptime']}s"
+```
+
+### Formation Usage (Runtime API)
+
+```ruby
+require 'muxi'
+
+# Create a formation client
+client = Muxi::FormationClient.new(
+  formation_id: 'my-bot',
+  server_url: ENV['MUXI_SERVER_URL'],
+  admin_key: ENV['MUXI_ADMIN_KEY'],
+  client_key: ENV['MUXI_CLIENT_KEY']
+)
+
+# Or connect directly to a formation
+client = Muxi::FormationClient.new(
+  url: 'http://localhost:8001',
+  admin_key: ENV['MUXI_ADMIN_KEY'],
+  client_key: ENV['MUXI_CLIENT_KEY']
+)
+
+# Chat (non-streaming)
+response = client.chat({ message: 'Hello!' }, user_id: 'user123')
+puts response['message']
+
+# Chat (streaming)
+client.chat_stream({ message: 'Tell me a story' }, user_id: 'user123') do |event|
+  data = JSON.parse(event['data']) rescue event['data']
+  print data['text'] if data.is_a?(Hash) && data['text']
+end
+
+# Health check
+health = client.health
+puts "Status: #{health['status']}"
+```
+
+## Webhook Verification
+
+```ruby
+require 'muxi'
+
+# In your webhook handler (e.g., Rails controller)
+def webhook
+  payload = request.raw_post
+  signature = request.headers['X-Muxi-Signature']
+  
+  unless Muxi::Webhook.verify_signature(payload, signature, ENV['WEBHOOK_SECRET'])
+    render json: { error: 'Invalid signature' }, status: 401
+    return
+  end
+  
+  event = Muxi::Webhook.parse(payload)
+  
+  case event.status
+  when 'completed'
+    event.content.each do |item|
+      puts item.text if item.type == 'text'
+    end
+  when 'failed'
+    puts "Error: #{event.error.message}"
+  when 'awaiting_clarification'
+    puts "Question: #{event.clarification.question}"
+  end
+  
+  render json: { received: true }
+end
+```
+
+## Configuration
+
+### Environment Variables
+
+- `MUXI_DEBUG=1` - Enable debug logging
+
+### Client Options
+
+```ruby
+Muxi::ServerClient.new(
+  url: 'https://muxi.example.com:7890',
+  key_id: 'your-key-id',
+  secret_key: 'your-secret-key',
+  timeout: 30,        # Request timeout in seconds
+  max_retries: 3,     # Retry on 429/5xx errors
+  debug: true         # Enable debug logging
+)
+```
+
+## Error Handling
+
+```ruby
+begin
+  server.get_formation('nonexistent')
+rescue Muxi::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue Muxi::AuthenticationError => e
+  puts "Auth failed: #{e.message}"
+rescue Muxi::RateLimitError => e
+  puts "Rate limited. Retry after: #{e.retry_after}s"
+rescue Muxi::MuxiError => e
+  puts "Error: #{e.message} (#{e.status_code})"
+end
+```
+
+## Requirements
+
+- Ruby 3.0+
+- No external dependencies (uses stdlib only)
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec]

data/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this SDK, please report it by emailing security@muxi.org.
+
+Please include:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Any suggested fixes (optional)
+
+We will acknowledge receipt within 48 hours and provide a detailed response within 7 days.
+
+## Security Best Practices
+
+When using this SDK:
+
+1. **Never commit credentials** - Use environment variables or secure secret management
+2. **Validate webhook signatures** - Always verify `X-Muxi-Signature` headers
+3. **Use HTTPS** - Always connect to MUXI servers over HTTPS in production
+4. **Keep dependencies updated** - Regularly update the SDK to get security patches

data/USER_GUIDE.md

@@ -0,0 +1,151 @@
+# MUXI Ruby SDK User Guide
+
+## Installation
+
+```bash
+gem install muxi
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'muxi'
+```
+
+## Quickstart
+
+```ruby
+require 'muxi'
+
+# Server client (management, HMAC auth)
+server = Muxi::ServerClient.new(
+  url: 'https://server.example.com',
+  key_id: '<key_id>',
+  secret_key: '<secret_key>'
+)
+puts server.status
+
+# Formation client (runtime, key auth)
+formation = Muxi::FormationClient.new(
+  server_url: 'https://server.example.com',
+  formation_id: '<formation_id>',
+  client_key: '<client_key>',
+  admin_key: '<admin_key>'
+)
+puts formation.health
+```
+
+## Clients
+
+- **ServerClient** (management, HMAC): deploy/list/update formations, server health/status, server logs.
+- **FormationClient** (runtime, client/admin keys): chat/audio (streaming), agents, secrets, MCP, memory, scheduler, sessions/requests, identifiers, credentials, triggers/SOPs/audit, async/A2A/logging config, overlord/LLM settings, events/logs streaming.
+
+## Streaming
+
+```ruby
+# Chat streaming (block)
+formation.chat_stream({ message: 'Tell me a story' }, user_id: 'user-123') do |event|
+  puts event['data'] if event['event'] == 'message'
+end
+
+# Chat streaming (enumerator)
+formation.chat_stream({ message: 'Tell me a story' }, user_id: 'user-123').each do |event|
+  puts event['data']
+end
+
+# Event streaming
+formation.stream_events('user-123') do |event|
+  puts event
+end
+
+# Log streaming (admin)
+formation.stream_logs(level: 'info') do |log|
+  puts log
+end
+```
+
+## Auth & Headers
+
+- **ServerClient**: HMAC with `key_id`/`secret_key` on `/rpc` endpoints.
+- **FormationClient**: `X-MUXI-CLIENT-KEY` or `X-MUXI-ADMIN-KEY` on `/api/{formation}/v1`. Override `base_url` for direct access (e.g., `http://localhost:9012/v1`).
+- **Idempotency**: `X-Muxi-Idempotency-Key` auto-generated on every request.
+- **SDK headers**: `X-Muxi-SDK`, `X-Muxi-Client` set automatically.
+
+## Timeouts & Retries
+
+- Default timeout: 30s (no timeout for streaming).
+- Retries: `max_retries` with exponential backoff on 429/5xx/connection errors; respects `Retry-After`.
+- Debug logging: enabled when `debug: true` or `MUXI_DEBUG=1`.
+
+## Error Handling
+
+```ruby
+begin
+  formation.chat(message: 'hello')
+rescue Muxi::AuthenticationError => e
+  puts "Auth failed: #{e.message}"
+rescue Muxi::RateLimitError => e
+  puts "Rate limited. Retry after: #{e.retry_after}s"
+rescue Muxi::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue Muxi::MuxiError => e
+  puts "#{e.code}: #{e.message} (#{e.status_code})"
+end
+```
+
+Error types: `AuthenticationError`, `AuthorizationError`, `NotFoundError`, `ValidationError`, `RateLimitError`, `ServerError`, `ConnectionError`.
+
+## Notable Endpoints (FormationClient)
+
+| Category | Methods |
+|----------|---------|
+| Chat/Audio | `chat`, `chat_stream`, `audio_chat`, `audio_chat_stream` |
+| Memory | `get_memory_config`, `get_memories`, `add_memory`, `delete_memory`, `get_user_buffer`, `clear_user_buffer`, `clear_session_buffer`, `clear_all_buffers`, `get_buffer_stats` |
+| Scheduler | `get_scheduler_config`, `get_scheduler_jobs`, `get_scheduler_job`, `create_scheduler_job`, `delete_scheduler_job` |
+| Sessions | `get_sessions`, `get_session`, `get_session_messages`, `restore_session` |
+| Requests | `get_requests`, `get_request_status`, `cancel_request` |
+| Agents/MCP | `get_agents`, `get_agent`, `get_mcp_servers`, `get_mcp_server`, `get_mcp_tools` |
+| Secrets | `get_secrets`, `get_secret`, `set_secret`, `delete_secret` |
+| Credentials | `list_credential_services`, `list_credentials`, `get_credential`, `create_credential`, `delete_credential` |
+| Identifiers | `get_user_identifiers_for_user`, `link_user_identifier`, `unlink_user_identifier` |
+| Triggers/SOP | `get_triggers`, `get_trigger`, `fire_trigger`, `get_sops`, `get_sop` |
+| Audit | `get_audit_log`, `clear_audit_log` |
+| Config | `get_status`, `get_config`, `get_formation_info`, `get_async_config`, `get_a2a_config`, `get_logging_config`, `get_logging_destinations`, `get_overlord_config`, `get_overlord_persona`, `get_llm_settings` |
+| Streaming | `stream_events`, `stream_logs`, `stream_request` |
+| User | `resolve_user` |
+
+## Webhook Verification
+
+```ruby
+require 'muxi'
+
+post '/webhooks/muxi' do
+  payload = request.body.read
+  signature = request.env['HTTP_X_MUXI_SIGNATURE']
+
+  unless Muxi::Webhook.verify_signature(payload, signature, ENV['WEBHOOK_SECRET'])
+    halt 401, 'Invalid signature'
+  end
+
+  event = Muxi::Webhook.parse(payload)
+
+  case event.status
+  when 'completed'
+    event.content.each { |item| puts item.text if item.type == 'text' }
+  when 'failed'
+    puts "Error: #{event.error&.message}"
+  when 'awaiting_clarification'
+    puts "Question: #{event.clarification&.question}"
+  end
+
+  { status: 'received' }.to_json
+end
+```
+
+## Testing Locally
+
+```bash
+cd ruby
+bundle install
+rspec
+```

data/lib/muxi/auth.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Muxi
+  module Auth
+    module_function
+
+    def generate_hmac_signature(secret_key, method, path)
+      timestamp = Time.now.to_i
+      sign_path = path.split("?").first
+      message = "#{timestamp};#{method};#{sign_path}"
+      
+      digest = OpenSSL::Digest.new("sha256")
+      hmac = OpenSSL::HMAC.digest(digest, secret_key, message)
+      signature = Base64.strict_encode64(hmac)
+      
+      [signature, timestamp]
+    end
+
+    def build_auth_header(key_id, secret_key, method, path)
+      signature, timestamp = generate_hmac_signature(secret_key, method, path)
+      "MUXI-HMAC key=#{key_id}, timestamp=#{timestamp}, signature=#{signature}"
+    end
+  end
+end

data/lib/muxi/errors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Muxi
+  class MuxiError < StandardError
+    attr_reader :code, :status_code, :details
+
+    def initialize(code, message, status_code, details = nil)
+      @code = code
+      @status_code = status_code
+      @details = details || {}
+      super(code ? "#{code}: #{message}" : message)
+    end
+  end
+
+  class AuthenticationError < MuxiError; end
+  class AuthorizationError < MuxiError; end
+  class NotFoundError < MuxiError; end
+  class ConflictError < MuxiError; end
+  class ValidationError < MuxiError; end
+
+  class RateLimitError < MuxiError
+    attr_reader :retry_after
+
+    def initialize(message, status_code, retry_after: nil, details: nil)
+      super("RATE_LIMITED", message, status_code, details)
+      @retry_after = retry_after
+    end
+  end
+
+  class ServerError < MuxiError; end
+  class ConnectionError < MuxiError; end
+
+  class << self
+    def map_error(status, code, message, details = nil, retry_after = nil)
+      case status
+      when 401
+        AuthenticationError.new(code || "UNAUTHORIZED", message, status, details)
+      when 403
+        AuthorizationError.new(code || "FORBIDDEN", message, status, details)
+      when 404
+        NotFoundError.new(code || "NOT_FOUND", message, status, details)
+      when 409
+        ConflictError.new(code || "CONFLICT", message, status, details)
+      when 422
+        ValidationError.new(code || "VALIDATION_ERROR", message, status, details)
+      when 429
+        RateLimitError.new(message || "Too Many Requests", status, retry_after: retry_after, details: details)
+      when 500..599
+        ServerError.new(code || "SERVER_ERROR", message, status, details)
+      else
+        MuxiError.new(code || "ERROR", message, status, details)
+      end
+    end
+  end
+end