@gotza02/smartagent 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Swarm MCP Enterprise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,422 @@
+# SmartAgent
+
+Intelligent Multi-Agent System with Sequential Thinking & Auto-Routing
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://semver.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+## Overview
+
+SmartAgent is a production-ready Model Context Protocol (MCP) Server designed for managing multi-agent swarm systems. It provides intelligent agent orchestration, sequential thinking capabilities, and automatic routing based on intent classification.
+
+### Key Features
+
+- **5 Base Agent Types**: Product Manager, Architect, Engineer, QA, Reviewer
+- **3 Operating Modes**: Plan (read-only), Edit (write), Ralph (autonomous)
+- **Sequential Thinking Engine**: Step-by-step reasoning with branching and revision
+- **Auto-Routing**: Intent classification with ≥85% accuracy
+- **Parallel Execution**: Concurrent task processing with result aggregation
+- **Context Persistence**: SQLite/libSQL database with checkpoint system
+- **Security Layer**: Path validation, command whitelisting, audit logging
+- **Health Monitoring**: Automatic health checks every 30 seconds
+
+## Installation
+
+### Via npx (Recommended)
+
+```bash
+npx @gotza02/smartagent
+```
+
+### Global Installation
+
+```bash
+npm install -g @gotza02/smartagent
+smartagent
+```
+
+### Development Setup
+
+```bash
+git clone https://github.com/gotza02/smartagent.git
+cd smartagent
+npm install
+npm run build
+npm link
+```
+
+## Quick Start
+
+### 1. Configure with Claude Code
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "swarm-enterprise": {
+      "command": "npx",
+      "args": ["-y", "@gotza02/smartagent"],
+      "env": {
+        "SWARM_DEBUG": "false",
+        "SWARM_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+### 2. Spawn Your First Agent
+
+```
+Use tool: spawn_agent
+{
+  "type": "product_manager",
+  "name": "pm_lead",
+  "mode": "plan"
+}
+```
+
+### 3. Create a Task
+
+```
+Use tool: assign_task
+{
+  "agentId": "<agent-id>",
+  "type": "requirements",
+  "description": "Define requirements for user authentication system",
+  "priority": 8
+}
+```
+
+### 4. Start Sequential Thinking
+
+```
+Use tool: thinking_create_chain
+{
+  "agentId": "<agent-id>",
+  "taskId": "<task-id>",
+  "title": "User Auth Requirements Analysis"
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      SmartAgent                            │
+├─────────────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │   Agent      │  │  Sequential  │  │    Auto      │      │
+│  │   Manager    │  │   Thinking   │  │   Router     │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+├─────────────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │   Context    │  │   Parallel   │  │    Tool      │      │
+│  │   Manager    │  │  Execution   │  │   Manager    │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+├─────────────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │   Security   │  │   Database   │  │    Logger    │      │
+│  │    Layer     │  │   (libSQL)   │  │  (Winston)   │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Available Tools
+
+### Agent Management
+
+| Tool | Description |
+|------|-------------|
+| `spawn_agent` | Create a new agent |
+| `spawn_agents_batch` | Create multiple agents (max 10) |
+| `get_agent` | Get agent details |
+| `list_agents` | List all agents with filters |
+| `terminate_agent` | Terminate an agent |
+
+### Task Management
+
+| Tool | Description |
+|------|-------------|
+| `assign_task` | Assign task to agent |
+| `get_task` | Get task details |
+| `complete_task` | Mark task as completed |
+| `fail_task` | Mark task as failed |
+
+### Sequential Thinking
+
+| Tool | Description |
+|------|-------------|
+| `thinking_create_chain` | Create thought chain |
+| `thinking_add_thought` | Add thought to chain |
+| `thinking_get_chain` | Get chain details |
+| `thinking_export` | Export as JSON/Markdown |
+
+### Auto-Routing
+
+| Tool | Description |
+|------|-------------|
+| `routing_classify_intent` | Classify input intent |
+| `routing_route` | Route to appropriate agent |
+
+### Parallel Execution
+
+| Tool | Description |
+|------|-------------|
+| `parallel_execute` | Execute tasks in parallel |
+| `parallel_get_execution` | Get execution details |
+
+### Context & Handoff
+
+| Tool | Description |
+|------|-------------|
+| `context_create` | Create agent context |
+| `context_handoff` | Handoff between agents |
+| `context_get_handoff_history` | View handoff history |
+
+### System
+
+| Tool | Description |
+|------|-------------|
+| `system_stats` | Get system statistics |
+| `system_health` | Perform health check |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SWARM_DEBUG` | Enable debug mode | `false` |
+| `SWARM_LOG_LEVEL` | Log level (debug/info/warn/error) | `info` |
+| `SWARM_MAX_AGENTS` | Maximum agents allowed | `100` |
+| `SMARTAGENT_DB_PATH` | Database file path | `~/.smartagent/smartagent.db` |
+
+### Security Policy
+
+Default security settings:
+- Path validation enabled
+- Blocked paths: `/`, `/bin`, `/etc`, `/sys`, `/proc`, `/dev`
+- Command blacklist: `rm -rf /`, `format`, `mkfs`, `dd`
+- Rate limit: 50 requests/minute, 1000/hour
+
+## Agent Types & Capabilities
+
+### Product Manager
+- Requirements gathering
+- User story creation
+- Acceptance criteria
+- Product roadmap
+- Prioritization
+
+### Architect
+- System design
+- Technology selection
+- Database schema design
+- API design
+- Pattern selection
+
+### Engineer
+- Implementation
+- Code development
+- Debugging
+- Refactoring
+- Unit testing
+
+### QA
+- Test planning
+- Test automation
+- Bug reporting
+- Quality assurance
+- Performance testing
+
+### Reviewer
+- Code review
+- Security audit
+- Performance review
+- Best practices
+- Documentation review
+
+## Operating Modes
+
+| Mode | Description | Tools Available |
+|------|-------------|-----------------|
+| `plan` | Read-only analysis | Filesystem (read), Terminal (read) |
+| `edit` | Write operations | Filesystem (read/write), Terminal (read/write) |
+| `ralph` | Autonomous execution | All tools with full permissions |
+
+## Sequential Thinking
+
+The sequential thinking engine supports:
+
+1. **Step-by-step reasoning** - Each thought builds on previous ones
+2. **Branching** - Explore multiple paths from any thought
+3. **Revision** - Update previous thoughts with new information
+4. **Confidence scoring** - 0.0 to 1.0 confidence for each thought
+5. **Export formats** - JSON and Markdown
+
+### Example Workflow
+
+```
+1. thinking_create_chain
+   → Creates new chain for analysis
+
+2. thinking_add_thought (Step 1)
+   → "Identify user requirements"
+   → Confidence: 0.9
+
+3. thinking_add_thought (Step 2)
+   → "Analyze technical constraints"
+   → Confidence: 0.85
+
+4. thinking_add_thought (Step 3, branchFrom: step2)
+   → "Alternative architecture approach"
+   → Creates branch
+
+5. thinking_export (format: "markdown")
+   → Export complete thought chain
+```
+
+## Parallel Execution
+
+Execute multiple tasks concurrently:
+
+```
+parallel_execute
+{
+  "tasks": [
+    { "agentType": "engineer", "type": "implement", "description": "API endpoint" },
+    { "agentType": "engineer", "type": "implement", "description": "Database model" },
+    { "agentType": "qa", "type": "test", "description": "Unit tests" }
+  ],
+  "maxConcurrency": 3,
+  "aggregationStrategy": "all"
+}
+```
+
+Aggregation strategies:
+- `all` - Wait for all tasks, return all results
+- `first` - Return first successful result
+- `majority` - Return majority consensus
+- `custom` - Custom aggregation logic
+
+## Monitoring & Logging
+
+### Log Files
+
+Located at `~/.smartagent/logs/`:
+- `combined.log` - All logs
+- `error.log` - Error logs only
+- `audit.log` - Security audit logs
+- `performance.log` - Performance metrics
+
+### Health Checks
+
+Automatic health checks every 30 seconds:
+- Agent timeout detection
+- Task status verification
+- Resource usage monitoring
+
+### System Stats
+
+```
+system_stats
+→ Returns:
+  - Agent counts by type/status
+  - Task statistics
+  - Database metrics
+  - Parallel execution stats
+```
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run in watch mode
+npm run test:watch
+
+# Run UI mode
+npm run test:ui
+```
+
+## Performance
+
+| Metric | Target | Actual |
+|--------|--------|--------|
+| Response Time (Local) | < 2s | ~500ms |
+| Response Time (External) | < 5s | ~2s |
+| Concurrent Agents | 10 | 10+ |
+| Memory Footprint | < 512MB | ~256MB |
+| Throughput | 50 calls/min | 100+ calls/min |
+
+## Security
+
+- ✅ Path traversal protection
+- ✅ Command validation & sanitization
+- ✅ Rate limiting
+- ✅ Audit logging
+- ✅ No plaintext credential storage
+- ✅ Input validation with Zod
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Agent not responding
+```bash
+# Check agent status
+get_agent { "agentId": "<id>" }
+
+# Perform health check
+system_health
+```
+
+**Issue**: Task timeout
+```bash
+# Check task details
+get_task { "taskId": "<id>" }
+
+# Retry with longer timeout
+assign_task { "timeout": 300 }
+```
+
+**Issue**: Database locked
+```bash
+# Restart the server
+# Database will auto-recover
+```
+
+### Debug Mode
+
+```bash
+SMARTAGENT_DEBUG=true npx @gotza02/smartagent
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open Pull Request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file
+
+## Support
+
+- Documentation: [docs/](docs/)
+- Issues: [GitHub Issues](https://github.com/gotza02/smartagent/issues)
+- Discussions: [GitHub Discussions](https://github.com/gotza02/smartagent/discussions)
+
+---
+
+**Built with ❤️ for the AI Engineering Community**

package/dist/config/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Configuration Management System
+ * Centralized configuration with environment variable support
+ */
+import type { SystemConfig } from "../types/index.js";
+/**
+ * Configuration Manager Class
+ */
+declare class ConfigManager {
+    private config;
+    private initialized;
+    constructor();
+    /**
+     * Load configuration from multiple sources
+     */
+    private loadConfig;
+    /**
+     * Apply environment variable overrides
+     */
+    private applyEnvironmentVariables;
+    /**
+     * Apply config file overrides
+     */
+    private applyConfigFile;
+    /**
+     * Deep merge two objects
+     */
+    private deepMerge;
+    /**
+     * Get current configuration
+     */
+    getConfig(): SystemConfig;
+    /**
+     * Get specific configuration value
+     */
+    get<K extends keyof SystemConfig>(key: K): SystemConfig[K];
+    /**
+     * Update configuration at runtime
+     */
+    updateConfig(updates: Partial<SystemConfig>): void;
+    /**
+     * Update specific configuration value
+     */
+    set<K extends keyof SystemConfig>(key: K, value: SystemConfig[K]): void;
+    /**
+     * Reset to default configuration
+     */
+    reset(): void;
+    /**
+     * Validate configuration
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Get configuration as JSON
+     */
+    toJSON(): string;
+    /**
+     * Initialize configuration
+     */
+    initialize(): void;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+}
+export declare const configManager: ConfigManager;
+export declare const config: SystemConfig;
+export type { SystemConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,mBAAmB,CAAC;AAkFjE;;GAEG;AACH,cAAM,aAAa;IACjB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,WAAW,CAAS;;IAM5B;;OAEG;IACH,OAAO,CAAC,UAAU;IAalB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IA2FjC;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB;;OAEG;IACH,OAAO,CAAC,SAAS;IA4BjB;;OAEG;IACH,SAAS,IAAI,YAAY;IAIzB;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,GAAG,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;IAI1D;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAKlD;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAKvE;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,QAAQ,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;IA2DhD;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,UAAU,IAAI,IAAI;IAkBlB;;OAEG;IACH,aAAa,IAAI,OAAO;CAGzB;AAGD,eAAO,MAAM,aAAa,eAAsB,CAAC;AAGjD,eAAO,MAAM,MAAM,cAA4B,CAAC;AAGhD,YAAY,EAAE,YAAY,EAAE,CAAC"}