loki-mode 5.51.0 → 5.52.1

package/docs/certification/sample-prds/microservices-platform.md

@@ -0,0 +1,100 @@
+# Microservices Platform PRD
+
+**Complexity Tier:** Complex (10+ files, multiple services, external integrations)
+
+## Overview
+
+A multi-service e-commerce platform with independent microservices communicating via message queues. Includes user management, product catalog, order processing, payment handling, and notification delivery. Deployed on Kubernetes with monitoring and observability.
+
+## Services
+
+### User Service
+- Registration and authentication (OAuth2 + JWT)
+- User profile management
+- Role-based access control (admin, seller, buyer)
+- Rate limiting on auth endpoints
+
+### Product Service
+- CRUD operations for products
+- Category and tag management
+- Full-text search with Elasticsearch
+- Image upload to S3-compatible storage
+- Inventory tracking with optimistic locking
+
+### Order Service
+- Shopping cart management (Redis-backed)
+- Order creation with inventory reservation
+- Order status tracking (created, paid, shipped, delivered, cancelled)
+- Saga pattern for distributed transactions
+
+### Payment Service
+- Stripe integration for payment processing
+- Webhook handling for payment events
+- Refund processing
+- Payment status reconciliation
+
+### Notification Service
+- Email notifications (order confirmation, shipping updates)
+- Event-driven via message queue consumption
+- Template-based email rendering
+- Delivery status tracking
+
+## Architecture
+
+### Communication
+- Synchronous: REST APIs between services (via API gateway)
+- Asynchronous: RabbitMQ message queues for event-driven flows
+- Events: OrderCreated, PaymentCompleted, OrderShipped, UserRegistered
+
+### Data Storage
+- PostgreSQL per service (database-per-service pattern)
+- Redis for session storage and shopping cart
+- Elasticsearch for product search
+- S3-compatible object storage for images
+
+### Infrastructure
+- Docker containers for all services
+- Kubernetes manifests (Deployment, Service, Ingress, ConfigMap, Secret)
+- Helm chart for parameterized deployment
+- Health check endpoints per service (`/health`, `/ready`)
+- Horizontal Pod Autoscaler based on CPU/request metrics
+
+## Tech Stack
+
+- **Services:** Node.js with TypeScript, Express
+- **Database:** PostgreSQL with Prisma ORM
+- **Cache:** Redis
+- **Search:** Elasticsearch
+- **Queue:** RabbitMQ
+- **Payments:** Stripe SDK
+- **Container:** Docker
+- **Orchestration:** Kubernetes
+- **Monitoring:** Prometheus metrics endpoints, Grafana dashboards
+
+## Non-Functional Requirements
+
+- Service response time < 200ms (p99)
+- Message queue processing latency < 500ms
+- 99.9% uptime target
+- Zero-downtime deployments (rolling updates)
+- Unit test coverage > 80% per service
+- Integration tests for cross-service flows
+- E2E test for complete purchase flow
+- Security: OWASP Top 10, secret management via K8s Secrets, network policies
+
+## Success Criteria
+
+- All 5 services start and pass health checks
+- User can register, browse products, add to cart, and place an order
+- Payment webhook processes correctly (requires Stripe test keys)
+- Notifications are queued and sent on order events
+- Kubernetes manifests deploy all services
+- Prometheus endpoints expose metrics
+- All unit and integration tests pass
+- No Critical or High security findings
+
+## Notes
+
+- Stripe integration requires a test API key (`STRIPE_TEST_KEY`). Mark as "requires provider API key" if not available.
+- Elasticsearch and RabbitMQ require running instances. Docker Compose is provided for local development.
+- Kubernetes deployment requires a cluster (minikube, kind, or cloud provider).

package/docs/certification/sample-prds/saas-dashboard.md

@@ -0,0 +1,60 @@
+# SaaS Analytics Dashboard PRD
+
+**Complexity Tier:** Standard (3-10 files, features with auth and database)
+
+## Overview
+
+A web-based analytics dashboard for a SaaS product. Users can sign up, log in, view charts of their usage metrics, and manage their account settings.
+
+## Requirements
+
+### Authentication
+- Email/password registration with bcrypt hashing
+- Login with JWT token issuance
+- Protected routes requiring valid JWT
+- Password reset flow (email-based)
+
+### Dashboard
+- Overview page with key metrics (active users, revenue, API calls)
+- Line chart showing daily active users over 30 days
+- Bar chart showing API call volume by endpoint
+- Date range selector for filtering data
+
+### API
+- RESTful API with OpenAPI specification
+- `POST /api/auth/register` -- Create account
+- `POST /api/auth/login` -- Authenticate and receive JWT
+- `GET /api/metrics/overview` -- Key metrics summary
+- `GET /api/metrics/users?range=30d` -- User activity data
+- `GET /api/metrics/api-calls?range=30d` -- API call data
+- `GET /api/account` -- Account details
+- `PUT /api/account` -- Update account settings
+
+### Database
+- PostgreSQL for persistent storage
+- Users table (id, email, password_hash, created_at)
+- Metrics table (id, user_id, metric_type, value, recorded_at)
+- Database migrations for schema management
+
+## Tech Stack
+
+- **Frontend:** React with TypeScript, Tailwind CSS, Recharts for charts
+- **Backend:** Node.js with Express, TypeScript
+- **Database:** PostgreSQL with Knex.js for migrations
+- **Auth:** bcrypt + JWT
+
+## Non-Functional Requirements
+
+- API response time < 200ms for all endpoints
+- Frontend loads in < 3 seconds on 3G connection
+- Unit test coverage > 80%
+- Integration tests for auth flow and API endpoints
+- OWASP Top 10 compliance (SQL injection prevention, XSS protection, CSRF tokens)
+
+## Success Criteria
+
+- User can register, log in, and view dashboard
+- Charts render with sample data
+- All API endpoints match OpenAPI spec
+- Unit and integration tests pass
+- No Critical or High security findings in review

package/docs/certification/sample-prds/todo-app.md

@@ -0,0 +1,44 @@
+# Todo App PRD
+
+**Complexity Tier:** Simple (1-2 files, basic CRUD)
+
+## Overview
+
+A command-line todo application written in Node.js. No external dependencies, no database, no authentication.
+
+## Requirements
+
+### Functional
+- Add a todo item with a title (string, max 200 characters)
+- List all todo items with their status (pending/complete)
+- Mark a todo item as complete by ID
+- Delete a todo item by ID
+- Each todo has: id (auto-generated UUID), title, status, createdAt timestamp
+
+### Non-Functional
+- Store todos in a local JSON file (`todos.json`)
+- Data persists between runs
+- CLI responds in under 100ms for all operations
+- No external npm dependencies (use built-in `fs`, `crypto`, `path` modules)
+
+## Tech Stack
+
+- Node.js (built-in modules only)
+- JSON file storage
+
+## CLI Interface
+
+```bash
+todo add "Buy groceries"        # Add a new todo
+todo list                       # List all todos
+todo done <id>                  # Mark as complete
+todo delete <id>                # Delete a todo
+```
+
+## Success Criteria
+
+- All 4 CRUD operations work correctly
+- Data persists in `todos.json` between runs
+- Unit tests pass with >80% coverage
+- No external dependencies in `package.json`
+- Error handling for: missing title, invalid ID, file read/write failures

package/mcp/__init__.py

@@ -21,4 +21,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '5.51.0'
+__version__ = '5.52.1'

package/mcp/server.py

@@ -979,6 +979,236 @@ async def get_pending_tasks() -> str:
         return json.dumps({"error": "Access denied", "pending_tasks": [], "count": 0})
 
 
+# ============================================================
+# ENTERPRISE TOOLS (P0-1)
+# ============================================================
+
+@mcp.tool()
+async def loki_start_project(prd_content: str = "", prd_path: str = "") -> str:
+    """
+    Start a new Loki Mode project from a PRD.
+
+    Args:
+        prd_content: Inline PRD content (takes priority over prd_path)
+        prd_path: Path to a PRD file on disk
+
+    Returns:
+        JSON with project initialization status
+    """
+    _emit_tool_event_async('loki_start_project', 'start', parameters={'prd_path': prd_path})
+    try:
+        content = prd_content
+        if not content and prd_path:
+            resolved = safe_path_join('.', prd_path)
+            if os.path.exists(resolved):
+                with safe_open(resolved, 'r') as f:
+                    content = f.read()
+            else:
+                return json.dumps({"error": f"PRD file not found: {prd_path}"})
+
+        if not content:
+            return json.dumps({"error": "No PRD content or path provided"})
+
+        # Initialize project state
+        os.makedirs('.loki/state', exist_ok=True)
+        project = {
+            "status": "initialized",
+            "prd_length": len(content),
+            "prd_path": prd_path or "inline",
+            "created_at": datetime.now(timezone.utc).isoformat(),
+        }
+        state_path = safe_path_join('.loki', 'state', 'project.json')
+        with safe_open(state_path, 'w') as f:
+            json.dump(project, f, indent=2)
+
+        _emit_tool_event_async('loki_start_project', 'complete', result_status='success')
+        return json.dumps({"success": True, **project})
+    except PathTraversalError as e:
+        return json.dumps({"error": f"Access denied: {e}"})
+    except Exception as e:
+        logger.error(f"Start project failed: {e}")
+        _emit_tool_event_async('loki_start_project', 'complete', result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def loki_project_status() -> str:
+    """
+    Get the current project status including RARV cycle state, agent activity, and task progress.
+
+    Returns:
+        JSON with project status, phase, iteration, agents, and task counts
+    """
+    _emit_tool_event_async('loki_project_status', 'start', parameters={})
+    try:
+        status = {}
+
+        # Read orchestrator state
+        orch_path = safe_path_join('.loki', 'state', 'orchestrator.json')
+        if os.path.exists(orch_path):
+            with safe_open(orch_path, 'r') as f:
+                status["orchestrator"] = json.load(f)
+
+        # Read project state
+        proj_path = safe_path_join('.loki', 'state', 'project.json')
+        if os.path.exists(proj_path):
+            with safe_open(proj_path, 'r') as f:
+                status["project"] = json.load(f)
+
+        # Read task queue summary
+        queue_path = safe_path_join('.loki', 'state', 'task-queue.json')
+        if os.path.exists(queue_path):
+            with safe_open(queue_path, 'r') as f:
+                queue = json.load(f)
+                tasks = queue.get("tasks", [])
+                status["tasks"] = {
+                    "total": len(tasks),
+                    "pending": sum(1 for t in tasks if t.get("status") == "pending"),
+                    "in_progress": sum(1 for t in tasks if t.get("status") == "in-progress"),
+                    "completed": sum(1 for t in tasks if t.get("status") == "completed"),
+                }
+
+        if not status:
+            status = {"status": "no_project", "message": "No active project found"}
+
+        _emit_tool_event_async('loki_project_status', 'complete', result_status='success')
+        return json.dumps(status, default=str)
+    except PathTraversalError:
+        return json.dumps({"error": "Access denied"})
+    except Exception as e:
+        logger.error(f"Project status failed: {e}")
+        _emit_tool_event_async('loki_project_status', 'complete', result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def loki_agent_metrics() -> str:
+    """
+    Get agent metrics including token usage, task completion rates, and timing.
+
+    Returns:
+        JSON with per-agent metrics and aggregates
+    """
+    _emit_tool_event_async('loki_agent_metrics', 'start', parameters={})
+    try:
+        metrics = {"agents": [], "aggregate": {}}
+
+        # Read efficiency metrics
+        metrics_dir = safe_path_join('.loki', 'metrics', 'efficiency')
+        if os.path.isdir(metrics_dir):
+            for fname in os.listdir(metrics_dir):
+                if fname.endswith('.json'):
+                    fpath = os.path.join(metrics_dir, fname)
+                    with open(fpath, 'r') as f:
+                        metrics["agents"].append(json.load(f))
+
+        # Read token economics
+        econ_path = safe_path_join('.loki', 'metrics', 'token-economics.json')
+        if os.path.exists(econ_path):
+            with safe_open(econ_path, 'r') as f:
+                metrics["token_economics"] = json.load(f)
+
+        metrics["agent_count"] = len(metrics["agents"])
+        _emit_tool_event_async('loki_agent_metrics', 'complete', result_status='success')
+        return json.dumps(metrics, default=str)
+    except PathTraversalError:
+        return json.dumps({"error": "Access denied"})
+    except Exception as e:
+        logger.error(f"Agent metrics failed: {e}")
+        _emit_tool_event_async('loki_agent_metrics', 'complete', result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def loki_checkpoint_restore(checkpoint_id: str = "") -> str:
+    """
+    List available checkpoints or restore project state from a specific checkpoint.
+
+    Args:
+        checkpoint_id: ID of checkpoint to restore (empty = list all)
+
+    Returns:
+        JSON with available checkpoints or restoration result
+    """
+    _emit_tool_event_async('loki_checkpoint_restore', 'start', parameters={'checkpoint_id': checkpoint_id})
+    try:
+        cp_dir = safe_path_join('.loki', 'state', 'checkpoints')
+        if not os.path.isdir(cp_dir):
+            return json.dumps({"checkpoints": [], "message": "No checkpoints directory"})
+
+        checkpoints = []
+        for fname in sorted(os.listdir(cp_dir)):
+            if fname.endswith('.json'):
+                fpath = os.path.join(cp_dir, fname)
+                with open(fpath, 'r') as f:
+                    cp = json.load(f)
+                    cp["id"] = fname.replace('.json', '')
+                    checkpoints.append(cp)
+
+        if not checkpoint_id:
+            _emit_tool_event_async('loki_checkpoint_restore', 'complete', result_status='success')
+            return json.dumps({"checkpoints": checkpoints, "count": len(checkpoints)})
+
+        # Find and restore specific checkpoint
+        target = next((c for c in checkpoints if c["id"] == checkpoint_id), None)
+        if not target:
+            return json.dumps({"error": f"Checkpoint not found: {checkpoint_id}"})
+
+        # Write checkpoint state as current state
+        state_path = safe_path_join('.loki', 'state', 'orchestrator.json')
+        with safe_open(state_path, 'w') as f:
+            json.dump(target, f, indent=2)
+
+        _emit_tool_event_async('loki_checkpoint_restore', 'complete', result_status='success')
+        return json.dumps({"restored": True, "checkpoint_id": checkpoint_id})
+    except PathTraversalError:
+        return json.dumps({"error": "Access denied"})
+    except Exception as e:
+        logger.error(f"Checkpoint restore failed: {e}")
+        _emit_tool_event_async('loki_checkpoint_restore', 'complete', result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def loki_quality_report() -> str:
+    """
+    Get quality gate results including blind review scores, council verdicts, and test coverage.
+
+    Returns:
+        JSON with quality gate status, review results, and coverage metrics
+    """
+    _emit_tool_event_async('loki_quality_report', 'start', parameters={})
+    try:
+        report = {"gates": [], "council": None, "coverage": None}
+
+        # Read quality gate results
+        gates_path = safe_path_join('.loki', 'state', 'quality-gates.json')
+        if os.path.exists(gates_path):
+            with safe_open(gates_path, 'r') as f:
+                report["gates"] = json.load(f)
+
+        # Read council results
+        council_path = safe_path_join('.loki', 'state', 'council-results.json')
+        if os.path.exists(council_path):
+            with safe_open(council_path, 'r') as f:
+                report["council"] = json.load(f)
+
+        # Read coverage
+        coverage_path = safe_path_join('.loki', 'metrics', 'coverage.json')
+        if os.path.exists(coverage_path):
+            with safe_open(coverage_path, 'r') as f:
+                report["coverage"] = json.load(f)
+
+        _emit_tool_event_async('loki_quality_report', 'complete', result_status='success')
+        return json.dumps(report, default=str)
+    except PathTraversalError:
+        return json.dumps({"error": "Access denied"})
+    except Exception as e:
+        logger.error(f"Quality report failed: {e}")
+        _emit_tool_event_async('loki_quality_report', 'complete', result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
 # ============================================================
 # PROMPTS - Pre-built prompt templates
 # ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "5.51.0",
+  "version": "5.52.1",
   "description": "Loki Mode by Autonomi - Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "autonomi",

package/src/plugins/agent-plugin.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const { BUILTIN_AGENT_NAMES } = require('./validator');
+
+// In-memory registry for custom agent plugins
+const _registeredAgents = new Map();
+
+class AgentPlugin {
+    /**
+     * Register a custom agent plugin.
+     * Cannot override built-in agent types (additive only).
+     *
+     * @param {object} pluginConfig - Validated agent plugin config
+     * @param {object} [registry] - Optional external registry to also register into
+     * @returns {{ success: boolean, error?: string }}
+     */
+    static register(pluginConfig, registry) {
+        if (!pluginConfig || pluginConfig.type !== 'agent') {
+            return { success: false, error: 'Invalid plugin config: type must be "agent"' };
+        }
+
+        const name = pluginConfig.name;
+
+        // Prevent overriding built-in agents
+        if (BUILTIN_AGENT_NAMES.includes(name)) {
+            return {
+                success: false,
+                error: `Cannot override built-in agent type: "${name}"`,
+            };
+        }
+
+        // Check for duplicate custom registration
+        if (_registeredAgents.has(name)) {
+            return {
+                success: false,
+                error: `Agent plugin "${name}" is already registered`,
+            };
+        }
+
+        // Build agent definition compatible with swarm registry format
+        const agentDef = {
+            name: name,
+            type: 'custom',
+            category: pluginConfig.category || 'custom',
+            description: pluginConfig.description,
+            prompt_template: pluginConfig.prompt_template,
+            trigger: pluginConfig.trigger || null,
+            quality_gate: pluginConfig.quality_gate || false,
+            capabilities: pluginConfig.capabilities || [],
+            registered_at: new Date().toISOString(),
+        };
+
+        _registeredAgents.set(name, agentDef);
+
+        // If an external registry object is provided, add to its custom category
+        if (registry && typeof registry === 'object') {
+            if (registry.customAgents) {
+                registry.customAgents[name] = agentDef;
+            }
+        }
+
+        return { success: true };
+    }
+
+    /**
+     * Unregister a custom agent plugin.
+     *
+     * @param {string} pluginName - Name of the agent plugin to remove
+     * @param {object} [registry] - Optional external registry to also remove from
+     * @returns {{ success: boolean, error?: string }}
+     */
+    static unregister(pluginName, registry) {
+        if (!_registeredAgents.has(pluginName)) {
+            return { success: false, error: `Agent plugin "${pluginName}" is not registered` };
+        }
+
+        _registeredAgents.delete(pluginName);
+
+        if (registry && registry.customAgents) {
+            delete registry.customAgents[pluginName];
+        }
+
+        return { success: true };
+    }
+
+    /**
+     * List all registered custom agent plugins.
+     *
+     * @returns {object[]} Array of agent definitions
+     */
+    static listRegistered() {
+        return Array.from(_registeredAgents.values());
+    }
+
+    /**
+     * Get a specific registered agent plugin by name.
+     *
+     * @param {string} name - Agent plugin name
+     * @returns {object|null} Agent definition or null
+     */
+    static get(name) {
+        return _registeredAgents.get(name) || null;
+    }
+
+    /**
+     * Check if a custom agent is registered.
+     *
+     * @param {string} name - Agent name
+     * @returns {boolean}
+     */
+    static isRegistered(name) {
+        return _registeredAgents.has(name);
+    }
+
+    /**
+     * Clear all registered custom agents (primarily for testing).
+     */
+    static _clearAll() {
+        _registeredAgents.clear();
+    }
+}
+
+module.exports = { AgentPlugin };