@xalia/agent 0.5.2 → 0.5.3

package/README.md

@@ -1,95 +1,232 @@
-# Sudobase Agent
+# Xalia Agent
 
-## Agent Setup
+A TypeScript-based AI agent system with MCP (Model Context Protocol) support, multi-user chat capabilities, and extensive tool integration.
 
-```sh
-# In the root folder
-yarn
+## Overview
+
+This agent provides two primary interfaces:
+- **Agent Mode**: Single-user conversational AI with tool support
+- **Chat Mode**: Multi-user chat server with shared AI agent sessions
+
+## Quick Start
+
+### Setup
+
+```bash
+# From project root
+yarn install
 yarn workspaces run build
 ```
 
-Run a local backend server (follow instructions in `mcppro`) because authentication against deployed backend is WIP.
+### Basic Usage
+
+Example of running agent can be found in [test script](../mcppro/scripts/test_script). 
+
+## Architecture
+
+### Core Components
+
+#### Agent (`src/agent/`)
+- **`Agent`**: Main orchestrator class managing conversations, tools, and LLM interactions
+- **`McpServerManager`**: Manages MCP tool servers, enables/disables tools dynamically  
+- **`SkillManager`**: Interfaces with SudoMCP backend to discover and connect to hosted MCP servers
+- **LLM Implementations**: 
+  - `OpenAILLM`: Standard OpenAI API integration
+  - `OpenAILLMStreaming`: Streaming response support
+  - `DummyLLM`: Mock implementation for testing
+
+#### Chat System (`src/chat/`)
+- **`ChatClient`/`runServer`**: WebSocket-based real-time communication
+- **`ConversationManager`**: Orchestrates multi-user sessions with shared AI agent
+- **`Database`**: Supabase integration for user management, sessions, and agent profiles
+- **`ApiKeyManager`**: Authentication and authorization
 
-## Usage:
+#### CLI Tools (`src/tool/`)
+- **`main.ts`**: Primary entry point with subcommands
+- **`agentMain.ts`**: Single-user agent mode implementation
+- **`chatMain.ts`**: Multi-user chat server/client implementation
 
-To enter a chat with no initial prompt and default system prompt:
+## Usage Examples
 
-```sh
-node dist/main.js
+### Agent Mode
+
+**Basic conversation:**
+```bash
+cli/agent-cli
 ```
 
-Optional arguments are `prompt` (first User message) and `systemprompt`
+**One-shot with specific prompt:**
+```bash
+echo "Explain quantum computing" > prompt.txt
+cli/agent-cli -1 --prompt prompt.txt
+```
 
-```sh
-node dist/main.js --prompt 'Who is the new pope?' --sysprompt 'You are extremely polite.'
+**With image analysis:**
+```bash
+echo "Describe this image" > prompt.txt
+cli/agent-cli --image photo.jpg --prompt prompt.txt
 ```
 
-## Features:
+**Using agent profile:**
+```bash
+cli/agent-cli --agent-profile agent/test_data/simplecalc_profile.json
+```
 
-### Conversation:
+**Auto-approve tools:**
+```bash
+echo "Calculate 15 * 23" > prompt.txt
+cli/agent-cli --approve-tools --prompt prompt.txt
+```
 
-CLI-mode is a conversation between user and LLM.
+### Chat Mode
 
-### Tool selection:
+**Start server:**
+```bash
+node dist/agent/src/tool/main.js chat server --port 5003
+```
 
-We now support MCP tool calls. Currently servers are enabled by editing the `mcpServerUrls.json` file, but this will be improved soon.
+**Connect client:**
+```bash
+node dist/agent/src/tool/main.js chat client \
+  --session "project_discussion" \
+  --agent-profile "helpful_assistant"
+```
 
-### Model selection:
+**Run scripted conversation:**
+```bash
+node dist/agent/src/tool/main.js chat client \
+  --session "test" \
+  --script conversation_script.txt
+```
 
-The CLI uses the default model (`gpt-4o-mini`) but uncomment the `agent.chooseModel` line to switch to `gpt-4.1-2025-04-14`. Right now we can use any OpenAI model that supports tool calling.
+### Interactive Commands (Agent Mode)
 
-Supporting inference providers like Together.ai is TODO.
+While in agent mode, use these commands:
 
-### Callbacks
+**Tool Management:**
+- `/ls` - List available MCP servers
+- `/lt` - List current tools (enabled marked with *)
+- `/as <server>` - Add and enable all tools from server
+- `/e <server> <tool>` - Enable specific tool
+- `/d <server> <tool>` - Disable specific tool
 
-The CLI uses an `onMessage` callback to display the Agent's messages and an `onToolCall` callback to request authorization for tool calls.
+**Media and Data:**
+- `:i image.jpg` - Include image with next message
+- `/wc conversation.json` - Save conversation to file
+- `/wa profile.json` - Save agent profile to file
 
-## Development Notes
+**General:**
+- `/h` - Show help menu
+- `/q` - Quit
 
-### Architecture
+## Configuration
 
-Frontend talks to
+### Environment Variables
 
-- Agent (for conversation, ChatCompletion)
-- McpServerManager (to enable, disable tools that have been added)
-- SudoMcpServerManager (to access catalog of SudoMCP servers, add to McpServerManager)
+```bash
+# LLM Configuration
+LLM_URL=http://localhost:5001/v1          # LLM API endpoint
+LLM_API_KEY=your_openai_key               # API key for LLM
+LLM_MODEL=gpt-4o                          # Model name
 
-SudoMcpServerManager:
+# SudoMCP Integration  
+XMCP_URL=http://localhost:5001/           # SudoMCP backend URL
+API_KEY=your_sudomcp_key                  # SudoMCP API key
 
-- track list of available mcp servers (via sdk/ApiClient)
-- get the list of tools as required by UI (via sdk/ApiClient)
-- add tools to McpServerManager
+# Database (Chat Mode)
+SUPABASE_URL=http://127.0.0.1:54321       # Supabase URL
+SUPABASE_KEY=your_supabase_key            # Supabase service key
 
-McpServerManager:
-  - manager (mcpServer, tool)
-  - enabling / disabling
-  - list of enabled / available tools per mcp server
-  - exposes tools to Agent
+# Chat Server
+CHAT_SERVER_PORT=5003                     # WebSocket server port
+```
 
-## Multi-agent Chat Setup
+### Agent Profiles
 
-With the mcppro backend and DB running locally:
+Agent profiles define the AI's behavior and available tools:
 
+```json
+{
+  "model": "gpt-4o",
+  "system_prompt": "You are a helpful coding assistant.",
+  "mcp_settings": {
+    "github": ["create_issue", "list_repos"],
+  }
+}
 ```
-$ ./scripts/test_chat
-```
 
-to set up some users.
+## Development
+
+### Project Structure
 
 ```
-$ echo "LLM_URL=http://localhost:5001/v1" >> .env
-$ echo "LLM_API_KEY=dummy_key" >> .env
-$ ./dist/agent/src/tool/main.js chat server
+src/
+├── agent/           # Core AI agent implementation
+│   ├── agent.ts           # Main Agent orchestrator
+│   ├── mcpServerManager.ts # MCP tool management
+│   ├── sudoMcpServerManager.ts # SudoMCP integration
+│   └── *LLM.ts            # LLM provider implementations
+├── chat/            # Multi-user chat system
+│   ├── server.ts          # WebSocket chat server
+│   ├── client.ts          # Chat client implementation
+│   ├── db.ts              # Database models and queries
+│   └── conversationManager.ts # Session orchestration
+├── tool/            # CLI interfaces
+│   ├── main.ts            # Primary entry point
+│   ├── agentMain.ts       # Single-user mode
+│   └── chatMain.ts        # Multi-user mode
+└── test/            # Test suites
 ```
 
-(in 2 other terminals)
+### Testing
+
+```bash
+# Run test suite
+yarn test
+
+# Test MCP server integration (requires local backend)
+yarn test -- --grep "MCP"
 
-Join as chatuser0:
+# Test database operations (requires Supabase)
+yarn test -- --grep "DB"
 ```
-$ ./dist/agent/src/tool/main.js chat client --api-key `cat _test_chat/chatuser0.apikey` --session test_session
+
+### Utility Scripts
+
+```bash
+# Git commit message generation
+./scripts/git_message
+
+# PR description generation  
+./scripts/pr_message
+
+# Code review assistance
+./scripts/pr_review
+
+# Multi-user chat testing
+./scripts/test_chat
 ```
 
-Join as chatuser1:
+## Advanced Features
+
+### Dummy LLM for Testing
+
+Use mock responses for development:
+
+```bash
+cli/agent \
+  --agent-profile test_data/test_script_profile.json \
+  --prompt "Test prompt"
 ```
-$ ./dist/agent/src/tool/main.js chat client --api-key `cat _test_chat/chatuser1.apikey` --session chatuser0/test_session
+
+### Conversation Restoration
+
+Save and restore conversation state:
+
+```bash
+# Save conversation
+cli/agent agent --conversation-output saved_conversation.json
+
+# Restore conversation  
+cli/agent --conversation saved_conversation.json
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xalia/agent",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "keywords": [],
   "author": "",
   "license": "ISC",

package/scripts/setup_chat

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+
+# Setup script for chat testing
+# Handles backend/database setup, building, user creation, and profile setup
+
+. ../mcppro/env/bin/activate
+
+set -x
+set -e
+
+function stop_mcppro_server() {
+    pushd ../mcppro
+    if [ -e sudomcp.pid ] ; then
+         kill `cat sudomcp.pid` || echo -n
+         rm sudomcp.pid
+    fi
+    popd
+}
+
+# Setup mcppro backend and database
+if [ -z ${NO_START} ] ; then
+    echo "Setting up mcppro backend and database..."
+    pushd ../mcppro
+    make supabase-up
+    stop_mcppro_server
+    make start-dev > server.log 2>&1 &
+    sleep 5
+    popd
+fi
+
+# Build agent
+echo "Building agent..."
+yarn
+yarn build
+agent=`realpath dist/agent/src/tool/main.js`
+
+# Build client
+echo "Building client..."
+pushd ../client
+yarn
+yarn build
+popd
+
+client=`realpath ../client/dist/src/tool/main.js`
+
+mkdir -p _test_chat
+pushd _test_chat
+
+  # Create admin secret
+  echo "Creating admin secret..."
+  echo "XMCP_ADMIN_SECRET=admin_secret" > .env
+
+  # Create 2 users and give them api keys
+  echo "Creating users and API keys..."
+
+  ${client} user get chatuser0 || \
+      mcppro dev add-user chatuser0 chatuser0@users.com "Europe/London"
+  ${client} user get chatuser1 || \
+      mcppro dev add-user chatuser1 chatuser1@users.com "UTC"
+
+  apikey0=`${client} admin get-api-keys chatuser0 | jq -r .default.api_key`
+  if [ "null" == "${apikey0}" ] ; then
+      apikey0=`${client} admin create-api-key chatuser0 default [] | jq -r .api_key`
+  fi
+  apikey1=`${client} admin get-api-keys chatuser1 | jq -r .default.api_key`
+  if [ "null" == "${apikey1}" ] ; then
+      apikey1=`${client} admin create-api-key chatuser1 default [] | jq -r .api_key`
+  fi
+
+  echo "${apikey0}" > chatuser0.apikey
+  echo "${apikey1}" > chatuser1.apikey
+
+  # User 0 creates an agent profile
+  echo "Creating agent profile..."
+
+  echo '{"system_prompt":"You are a helpful agent talking to multiple users.  Users put their name at the beginning of their messages, e.g. `chatuser1: <message>`.","mcp_settings":{"duckduckgo-search":[]}}' > profile0.json
+  ${client} config --force --dev --api-key ${apikey0}
+  ${client} agent-profile set profile0 --profile profile0.json
+
+popd
+
+
+echo "================================"
+echo "==   CHAT SETUP COMPLETED    =="
+echo "================================"

package/scripts/shutdown_chat_server

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+# Shutdown script for chat testing
+# Stops chat server and MCP server
+
+set -x
+set -e
+
+function stop_chat_server() {
+    echo "Stopping chat server..."
+    if [ -e chat.pid ] ; then
+         kill `cat chat.pid` || echo "Chat server was not running or already stopped"
+         rm chat.pid
+    else
+         echo "No chat.pid file found - chat server may not be running"
+    fi
+}
+
+function stop_mcppro_server() {
+    echo "Stopping MCP server..."
+    pushd ../mcppro
+    if [ -e sudomcp.pid ] ; then
+         kill `cat sudomcp.pid` || echo "MCP server was not running or already stopped"
+         rm sudomcp.pid
+    else
+         echo "No sudomcp.pid file found - MCP server may not be running"
+    fi
+    popd
+}
+
+# Stop chat server
+stop_chat_server
+
+# Stop MCP server
+stop_mcppro_server
+
+echo "=========================="
+echo "==   SHUTDOWN COMPLETE  =="
+echo "==========================" 

package/scripts/start_chat_server

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+agent=`realpath dist/agent/src/tool/main.js`
+
+function stop_chat_server() {
+    echo "Stopping any existing chat server..."
+    if [ -e chat.pid ] ; then
+         kill `cat chat.pid` || echo "Chat server was not running or already stopped"
+    else
+         echo "No existing chat server found"
+    fi
+}
+
+# Stop any existing chat server
+stop_chat_server
+
+echo "Starting chat server..."
+echo "Output will be logged to: chat_server.log"
+echo "Press Ctrl+C to stop the server"
+echo "================================"
+
+# Start chat server with logging to file and console
+# Using tee to duplicate output to both file and terminal
+LOG_LEVEL=debug ${agent} chat server --pid-file chat.pid 2>&1 | tee chat_server.log

package/scripts/test_chat

@@ -1,25 +1,48 @@
 #!/usr/bin/env bash
 
-# Assumes backend and DB are already running
-
 . ../mcppro/env/bin/activate
 
 set -x
 set -e
 
+function stop_mcppro_server() {
+    pushd ../mcppro
+    if [ -e sudomcp.pid ] ; then
+         kill `cat sudomcp.pid` || echo -n
+    fi
+    popd
+}
 
+if [ -z ${NO_START} ] ; then
+    # Start backend services from mcppro directory
+    pushd ../mcppro
+    make supabase-up
+    stop_mcppro_server
+    make start-dev > server.log 2>&1 &
+    sleep 5
+    popd
+fi
+
+# build agent
 yarn
 yarn build
 agent=`realpath dist/agent/src/tool/main.js`
+
+# build client
+pushd ../client
+yarn
+yarn build
+popd
+
 client=`realpath ../client/dist/src/tool/main.js`
 
-function stop_server() {
+function stop_chat_server() {
     if [ -e chat.pid ] ; then
          kill `cat chat.pid` || echo -n
     fi
 }
 
-stop_server
+stop_chat_server
 
 LOG_LEVEL=debug ${agent} chat server --pid-file chat.pid > chat_server.log 2>&1 &
 sleep 1
@@ -74,7 +97,10 @@ pushd _test_chat
 
 popd
 
-stop_server
+stop_chat_server
+
+# Stop backend services if we started them
+[ -z ${NO_START} ] && stop_mcppro_server
 
 set +e
 set +x