feat: Add intelligent auto-router and enhanced integrations
- Add intelligent-router.sh hook for automatic agent routing - Add AUTO-TRIGGER-SUMMARY.md documentation - Add FINAL-INTEGRATION-SUMMARY.md documentation - Complete Prometheus integration (6 commands + 4 tools) - Complete Dexto integration (12 commands + 5 tools) - Enhanced Ralph with access to all agents - Fix /clawd command (removed disable-model-invocation) - Update hooks.json to v5 with intelligent routing - 291 total skills now available - All 21 commands with automatic routing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
admin
525
dexto/CONTRIBUTING.md
Normal file
525
dexto/CONTRIBUTING.md
Normal file
@@ -0,0 +1,525 @@
|
||||
# Contributing to Dexto
|
||||
|
||||
We welcome contributions! This guide will help you get started with contributing to the Dexto project.
|
||||
|
||||
## Table of Contents
|
||||
- [Getting Started](#getting-started)
|
||||
- [Contributing MCPs and Example Agents](#contributing-mcps-and-example-agents)
|
||||
- [Development Setup](#development-setup)
|
||||
- [Making Changes](#making-changes)
|
||||
- [Submitting a Pull Request](#submitting-a-pull-request)
|
||||
- [Code Standards](#code-standards)
|
||||
- [Commit Guidelines](#commit-guidelines)
|
||||
- [Changesets](#changesets)
|
||||
|
||||
## Getting Started
|
||||
|
||||
Before contributing, please:
|
||||
1. Read our [Code of Conduct](./CODE_OF_CONDUCT.md)
|
||||
2. Check existing [issues](https://github.com/truffle-ai/dexto/issues) and [pull requests](https://github.com/truffle-ai/dexto/pulls)
|
||||
3. Open an issue for discussion on larger changes or enhancements
|
||||
|
||||
## Contributing MCPs and Example Agents
|
||||
|
||||
We especially encourage contributions that expand Dexto's ecosystem! Here are three ways you can contribute:
|
||||
|
||||
### 1. Adding New MCPs to the WebUI Registry
|
||||
|
||||
Help other users discover and use new MCP servers by adding them to our built-in registry.
|
||||
|
||||
**How to add an MCP to the registry:**
|
||||
|
||||
1. Edit `src/app/webui/lib/server-registry-data.json`
|
||||
2. Add a new entry following this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "unique-server-id",
|
||||
"name": "Display Name",
|
||||
"description": "Brief description of what this server does",
|
||||
"category": "productivity|research|creative|development|data|communication",
|
||||
"icon": "📁",
|
||||
"config": {
|
||||
"type": "stdio|http|sse",
|
||||
"command": "npx|uvx|python",
|
||||
"args": ["-y", "package-name"],
|
||||
"env": {
|
||||
"API_KEY": ""
|
||||
},
|
||||
"timeout": 30000
|
||||
},
|
||||
"tags": ["tag1", "tag2"],
|
||||
"isOfficial": false,
|
||||
"isInstalled": false,
|
||||
"requirements": {
|
||||
"platform": "all|windows|mac|linux",
|
||||
"node": ">=20.0.0",
|
||||
"python": ">=3.10"
|
||||
},
|
||||
"author": "Your Name",
|
||||
"homepage": "https://github.com/your-repo",
|
||||
"matchIds": ["server-id"]
|
||||
}
|
||||
```
|
||||
|
||||
**Categories:**
|
||||
- `productivity` - File operations, task management, workflow tools
|
||||
- `research` - Search, data analysis, information gathering
|
||||
- `creative` - Image editing, music creation, content generation
|
||||
- `development` - Code analysis, debugging, development tools
|
||||
- `data` - Data processing, analytics, databases
|
||||
- `communication` - Email, messaging, collaboration tools
|
||||
|
||||
**Configuration Types:**
|
||||
- **Stdio (Node.js)**: `{"type": "stdio", "command": "npx", "args": ["-y", "package-name"]}`
|
||||
- **Stdio (Python)**: `{"type": "stdio", "command": "uvx", "args": ["package-name"]}`
|
||||
- **HTTP**: `{"type": "http", "baseUrl": "https://api.example.com/mcp"}`
|
||||
- **SSE**: `{"type": "sse", "url": "https://api.example.com/mcp-sse"}`
|
||||
|
||||
### 2. Creating Example Agents
|
||||
|
||||
Showcase how to use MCPs by creating example agents in the `agents/` directory.
|
||||
|
||||
**How to create an example agent:**
|
||||
|
||||
1. Create a new directory: `agents/your-agent-name/`
|
||||
2. Add a `your-agent-name.yml` configuration file
|
||||
3. Include a `README.md` with setup instructions and usage examples
|
||||
4. Follow the existing agent structure (see `agents/examples/` for reference)
|
||||
|
||||
**Example agent structure:**
|
||||
```
|
||||
agents/your-agent-name/
|
||||
├── your-agent-name.yml # Main configuration
|
||||
├── README.md # Setup and usage guide
|
||||
└── data/ # Optional: sample data
|
||||
└── example.json
|
||||
```
|
||||
|
||||
**Configuration template:**
|
||||
```yaml
|
||||
# Your Agent Name
|
||||
# Brief description of what this agent does
|
||||
|
||||
systemPrompt: |
|
||||
You are a [Agent Name] specialized in [purpose]. You have access to [MCP servers] that allow you to:
|
||||
|
||||
## Your Capabilities
|
||||
- [List key capabilities]
|
||||
- [More capabilities]
|
||||
|
||||
## How You Should Behave
|
||||
- [Behavior guidelines]
|
||||
- [Usage examples]
|
||||
|
||||
mcpServers:
|
||||
your-mcp:
|
||||
type: stdio
|
||||
command: npx
|
||||
args:
|
||||
- -y
|
||||
- "package-name"
|
||||
env:
|
||||
API_KEY: $YOUR_API_KEY
|
||||
|
||||
llm:
|
||||
provider: openai
|
||||
model: gpt-5-mini
|
||||
apiKey: $OPENAI_API_KEY
|
||||
|
||||
storage:
|
||||
cache:
|
||||
type: in-memory
|
||||
database:
|
||||
type: sqlite
|
||||
path: .dexto/database/your-agent.db
|
||||
```
|
||||
|
||||
**README template:**
|
||||
```markdown
|
||||
# Your Agent Name
|
||||
|
||||
Brief description of what this agent does and why it's useful.
|
||||
|
||||
## Features
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
## Setup
|
||||
1. Install dependencies: `npm install`
|
||||
2. Set environment variables: `export YOUR_API_KEY=your-key`
|
||||
3. Run the agent: `dexto --agent your-agent-name.yml`
|
||||
|
||||
## Usage Examples
|
||||
- "Example command 1"
|
||||
- "Example command 2"
|
||||
|
||||
## Requirements
|
||||
- Node.js >= 20.0.0
|
||||
- Your API key
|
||||
```
|
||||
|
||||
### 3. Adding Agents to the Official Registry
|
||||
|
||||
Once you've created a comprehensive example agent, you can add it to the official agent registry so users can discover and install it with `dexto install`.
|
||||
|
||||
**How to add an agent to the registry:**
|
||||
|
||||
1. Create your agent in `agents/your-agent-name/` (following step 2 above)
|
||||
2. Edit `agents/agent-registry.json` and add your agent entry
|
||||
3. Edit `packages/cli/scripts/copy-agents.ts` and add your agent to the `AGENTS_TO_COPY` array
|
||||
4. Test the build to ensure your agent is properly copied
|
||||
5. Open a pull request with:
|
||||
- Link to your agent directory
|
||||
- Description of the agent's purpose and value
|
||||
- Screenshots or demos if applicable
|
||||
- Evidence of testing and documentation
|
||||
|
||||
**Registry Entry Structure (`agents/agent-registry.json`):**
|
||||
|
||||
```json
|
||||
{
|
||||
"your-agent-id": {
|
||||
"id": "your-agent-id",
|
||||
"name": "Your Agent Name",
|
||||
"description": "Brief description of what this agent does and its key capabilities",
|
||||
"author": "Your Name or Organization",
|
||||
"tags": ["category", "use-case", "technology"],
|
||||
"source": "your-agent-name/",
|
||||
"main": "your-agent-name.yml"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Field Guidelines:**
|
||||
|
||||
- **id**: Lowercase, hyphenated identifier (e.g., `database-agent`, `podcast-agent`)
|
||||
- **name**: Human-readable display name (e.g., `Database Agent`, `Podcast Agent`)
|
||||
- **description**: Clear, concise description of purpose and capabilities (1-2 sentences)
|
||||
- **author**: Your name, organization, or `Truffle AI` for official agents
|
||||
- **tags**: 3-6 relevant tags for categorization and search:
|
||||
- **Category tags**: `database`, `images`, `video`, `audio`, `coding`, `documents`, etc.
|
||||
- **Technology tags**: `gemini`, `openai`, `anthropic`, `mcp`, etc.
|
||||
- **Use case tags**: `creation`, `analysis`, `editing`, `generation`, `support`, etc.
|
||||
- **source**: Directory path relative to `agents/` folder (ends with `/` for directories)
|
||||
- **main**: Main configuration file name (e.g., `agent.yml`, `your-agent-name.yml`)
|
||||
|
||||
**Tag Examples:**
|
||||
```json
|
||||
// Content creation agent
|
||||
"tags": ["images", "generation", "editing", "ai", "gemini"]
|
||||
|
||||
// Development agent
|
||||
"tags": ["coding", "development", "software", "programming"]
|
||||
|
||||
// Data analysis agent
|
||||
"tags": ["database", "sql", "data", "queries", "analysis"]
|
||||
|
||||
// Multi-modal agent
|
||||
"tags": ["audio", "tts", "speech", "multi-speaker", "gemini"]
|
||||
```
|
||||
|
||||
**Complete Example:**
|
||||
```json
|
||||
{
|
||||
"music-agent": {
|
||||
"id": "music-agent",
|
||||
"name": "Music Agent",
|
||||
"description": "AI agent for music creation and audio processing",
|
||||
"author": "Truffle AI",
|
||||
"tags": ["music", "audio", "creation", "sound"],
|
||||
"source": "music-agent/",
|
||||
"main": "music-agent.yml"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Single-File vs Directory Agents:**
|
||||
|
||||
- **Directory agent** (with multiple files):
|
||||
```json
|
||||
{
|
||||
"source": "your-agent-name/",
|
||||
"main": "agent.yml"
|
||||
}
|
||||
```
|
||||
|
||||
- **Single-file agent** (all in one YAML):
|
||||
```json
|
||||
{
|
||||
"source": "your-agent.yml"
|
||||
}
|
||||
```
|
||||
Note: `main` field is omitted for single-file agents.
|
||||
|
||||
**Build Script Configuration (`packages/cli/scripts/copy-agents.ts`):**
|
||||
|
||||
Add your agent to the `AGENTS_TO_COPY` array:
|
||||
|
||||
```typescript
|
||||
const AGENTS_TO_COPY = [
|
||||
// Core files
|
||||
'agent-registry.json',
|
||||
'agent-template.yml',
|
||||
|
||||
// Agent directories
|
||||
'coding-agent/',
|
||||
'database-agent/',
|
||||
'your-agent-name/', // Add your agent here
|
||||
// ... other agents
|
||||
];
|
||||
```
|
||||
|
||||
**Important Notes:**
|
||||
- Directory agents should end with `/` (e.g., `'your-agent-name/'`)
|
||||
- Single-file agents should NOT have a trailing slash (e.g., `'your-agent.yml'`)
|
||||
- The script copies agents to `packages/cli/dist/agents/` during build
|
||||
- Run `pnpm run build` to test that your agent is properly copied
|
||||
|
||||
**Criteria for registry acceptance:**
|
||||
- Solves a common, well-defined problem
|
||||
- Has clear documentation and examples
|
||||
- Works reliably across different environments
|
||||
- Provides significant value to the Dexto community
|
||||
- Follows all coding standards and best practices
|
||||
- Demonstrates unique capabilities or fills a gap
|
||||
|
||||
### Documentation
|
||||
- Update relevant documentation in `/docs` folder
|
||||
- Include clear examples in your contributions
|
||||
- Follow the existing documentation structure
|
||||
|
||||
*Tip:* Check out existing examples in `agents/examples/` and `agents/database-agent/` for inspiration!
|
||||
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
- Node.js >= 20.0.0
|
||||
- Git
|
||||
|
||||
### Fork and Clone
|
||||
|
||||
1. Fork the repository to your GitHub account
|
||||
|
||||
2. Clone your fork:
|
||||
```bash
|
||||
git clone https://github.com/your-username/dexto.git
|
||||
cd dexto
|
||||
```
|
||||
|
||||
3. Add upstream remote:
|
||||
```bash
|
||||
git remote add upstream https://github.com/truffle-ai/dexto.git
|
||||
```
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
```bash
|
||||
# Enable Corepack (built into Node.js 16+)
|
||||
corepack enable
|
||||
|
||||
# Install dependencies (uses correct pnpm version automatically)
|
||||
pnpm install
|
||||
|
||||
# Build all packages
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
**Note**: Corepack ensures everyone uses the same pnpm version (10.12.4) as specified in package.json.
|
||||
|
||||
### Development Workflow
|
||||
|
||||
For detailed development workflows, see [DEVELOPMENT.md](./DEVELOPMENT.md). Quick start:
|
||||
|
||||
```bash
|
||||
# Run development server with hot reload
|
||||
pnpm run dev
|
||||
|
||||
# Or create a global symlink for CLI development
|
||||
pnpm run link-cli
|
||||
```
|
||||
|
||||
## Making Changes
|
||||
|
||||
### Create a Feature Branch
|
||||
|
||||
```bash
|
||||
# Update your fork
|
||||
git checkout main
|
||||
git pull upstream main
|
||||
|
||||
# Create a new branch
|
||||
git checkout -b feature/your-branch-name
|
||||
```
|
||||
|
||||
|
||||
### Monorepo Structure
|
||||
|
||||
Dexto is a monorepo with three main packages:
|
||||
- `packages/core` - Core business logic (@dexto/core)
|
||||
- `packages/cli` - CLI application (dexto)
|
||||
- `packages/webui` - Web interface (@dexto/webui)
|
||||
|
||||
Make changes in the appropriate package(s).
|
||||
|
||||
### Code Quality Checks
|
||||
|
||||
Before committing, ensure your code passes all checks:
|
||||
|
||||
```bash
|
||||
# Type checking
|
||||
pnpm run typecheck
|
||||
|
||||
# Run tests
|
||||
pnpm run test
|
||||
|
||||
# Fix linting issues
|
||||
pnpm run lint:fix
|
||||
|
||||
# Format code
|
||||
pnpm run format
|
||||
|
||||
# Full validation (recommended before commits)
|
||||
pnpm run build:check
|
||||
```
|
||||
|
||||
## Submitting a Pull Request
|
||||
|
||||
### 1. Create a Changeset
|
||||
|
||||
For any changes that affect functionality:
|
||||
|
||||
```bash
|
||||
pnpm changeset
|
||||
```
|
||||
|
||||
Follow the prompts to:
|
||||
- Select affected packages
|
||||
- Choose version bump type (patch/minor/major)
|
||||
- Describe your changes
|
||||
|
||||
This creates a file in `.changeset/` that must be committed with your PR.
|
||||
|
||||
### 2. Commit Your Changes
|
||||
|
||||
```bash
|
||||
# Stage your changes
|
||||
git add .
|
||||
|
||||
# Commit with a descriptive message
|
||||
git commit -m "feat(core): add new validation helper"
|
||||
```
|
||||
|
||||
## Commit Guidelines
|
||||
|
||||
#### Commit Message Format
|
||||
|
||||
We follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
type(scope): subject
|
||||
|
||||
body (optional)
|
||||
|
||||
footer (optional)
|
||||
```
|
||||
|
||||
Types:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Code style changes (formatting, semicolons, etc.)
|
||||
- `refactor`: Code refactoring
|
||||
- `perf`: Performance improvements
|
||||
- `test`: Test additions or fixes
|
||||
- `chore`: Build process or auxiliary tool changes
|
||||
|
||||
Examples:
|
||||
```bash
|
||||
feat(cli): add new agent command
|
||||
fix(core): resolve memory leak in storage manager
|
||||
docs: update installation instructions
|
||||
```
|
||||
|
||||
### 3. Push and Create PR
|
||||
|
||||
```bash
|
||||
# Push your branch
|
||||
git push origin feature/your-branch-name
|
||||
```
|
||||
|
||||
Then create a Pull Request on GitHub with:
|
||||
- Clear title following commit message format
|
||||
- Description of changes and motivation
|
||||
- Link to related issue (if applicable)
|
||||
- Screenshots (for UI changes)
|
||||
|
||||
### PR Requirements
|
||||
|
||||
Your PR must:
|
||||
- ✅ Include a changeset (for functional changes)
|
||||
- ✅ Pass all CI checks
|
||||
- ✅ Have no merge conflicts
|
||||
- ✅ Follow code standards
|
||||
- ✅ Include tests for new functionality
|
||||
|
||||
## Code Standards
|
||||
|
||||
### TypeScript
|
||||
- Use strict TypeScript settings
|
||||
- Avoid `any` types
|
||||
- Handle null/undefined cases explicitly
|
||||
- Add JSDoc comments for public APIs
|
||||
|
||||
### Error Handling
|
||||
- Use typed error classes from `packages/core/src/errors/`
|
||||
- Never use plain `Error` or `throw new Error()`
|
||||
- Include error context and helpful messages
|
||||
|
||||
### Testing
|
||||
- Unit tests: `*.test.ts`
|
||||
- Integration tests: `*.integration.test.ts`
|
||||
- Aim for high coverage of business logic
|
||||
- Test error cases and edge conditions
|
||||
|
||||
### Documentation
|
||||
- Update relevant documentation with your changes
|
||||
- Add inline comments for complex logic
|
||||
- Update README if adding new features
|
||||
|
||||
## Changesets
|
||||
|
||||
We use [Changesets](https://github.com/changesets/changesets) to manage versions and changelogs.
|
||||
|
||||
### When to Add a Changeset
|
||||
|
||||
Add a changeset when you:
|
||||
- Add a new feature
|
||||
- Fix a bug
|
||||
- Make breaking changes
|
||||
- Change public APIs
|
||||
|
||||
### When NOT to Add a Changeset
|
||||
|
||||
Don't add a changeset for:
|
||||
- Documentation updates (unless API docs)
|
||||
- Internal refactoring with no external impact
|
||||
- Test additions
|
||||
- Development tooling changes
|
||||
|
||||
### Version Bumps
|
||||
|
||||
- **Patch** (0.0.X): Bug fixes, minor improvements
|
||||
- **Minor** (0.X.0): New features, backward compatible
|
||||
- **Major** (X.0.0): Breaking changes
|
||||
|
||||
## Questions?
|
||||
|
||||
- Check [DEVELOPMENT.md](./DEVELOPMENT.md) for development workflows
|
||||
- Open an issue for bugs or feature requests
|
||||
- Join our Discord community for discussions
|
||||
- Review existing PRs for examples
|
||||
|
||||
Thank you for contributing to Dexto! 🚀
|
||||
*Tip:* Open an issue first for discussion on larger enhancements or proposals.
|
||||
Reference in New Issue
Block a user