Xalia Agent

A TypeScript-based AI agent system with MCP (Model Context Protocol) support, multi-user chat capabilities, and extensive tool integration.

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

$3

``bash


From project root


yarn install
yarn workspaces run build
`

$3

Example of running agent can be found in test script.

Architecture

For a detailed explanation of the context system architecture, including how context is formed, compressed, and managed during agent execution, see:

📚 Context System Architecture Documentation

This document covers:
- Context window structure and composition
- System prompt fragment injection
- Automatic context compression
- Session file handling
- Transaction-based message flow

$3

#### 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

#### 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

Usage Examples

$3

Basic conversation:

`bash
cli/agent-cli
`

One-shot with specific prompt:

`bash
echo "Explain quantum computing" > prompt.txt
cli/agent-cli -1 --prompt prompt.txt
`

With image analysis:

`bash
echo "Describe this image" > prompt.txt
cli/agent-cli --image photo.jpg --prompt prompt.txt
`

Using agent profile:

`bash
cli/agent-cli --agent-profile agent/test_data/simplecalc_profile.json
`

Auto-approve tools:

`bash
echo "Calculate 15 * 23" > prompt.txt
cli/agent-cli --approve-tools --prompt prompt.txt
`

$3

Start server:

`bash
node dist/agent/src/tool/main.js chat server --port 5003
`

Connect client:

`bash
node dist/agent/src/tool/main.js chat client \
--session "project_discussion" \
--agent-profile "helpful_assistant"
`

Run scripted conversation:

`bash
node dist/agent/src/tool/main.js chat client \
--session "test" \
--script conversation_script.txt
`

$3

While in agent mode, use these commands:

Tool Management:

- /ls - List available MCP servers
- /lt - List current tools (enabled marked with \*)
- /as - Add and enable all tools from server
- /e - Enable specific tool
- /d - Disable specific tool

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

General:

- /h - Show help menu
- /q - Quit

Configuration

$3

`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

SudoMCP Integration

XMCP_URL=http://localhost:5001/ # SudoMCP backend URL
API_KEY=your_sudomcp_key # SudoMCP API key

Database (Chat Mode)

SUPABASE_URL=http://127.0.0.1:54321 # Supabase URL
SUPABASE_KEY=your_supabase_key # Supabase service key

Chat Server

CHAT_SERVER_PORT=5003 # WebSocket server port
`

$3

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"]
}
}
`

Development

$3

`
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
`

$3

`bash


Run test suite

yarn test

Test MCP server integration (requires local backend)

yarn test -- --grep "MCP"

Test database operations (requires Supabase)

yarn test -- --grep "DB"
`

$3

`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
`

Advanced Features

$3

Use mock responses for development:

`bash
cli/agent \
--agent-profile test_data/test_script_profile.json \
--prompt "Test prompt"
`

$3

Save and restore conversation state:

`bash


Save conversation

cli/agent agent --conversation-output saved_conversation.json

Restore conversation

cli/agent --conversation saved_conversation.json
``