atabey 0.0.16 → 0.0.18

package/framework-mcp/dist/src/modules/engines/routing-engine.js

@@ -1,504 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { getFrameworkDir } from "../../cli/utils/memory.js";
-import { logger } from "../../shared/logger.js";
-import { AtabeyStorage } from "../../shared/storage.js";
-import { asAgentID, asTraceID } from "../../shared/types.js";
-import { ALL_AGENTS } from "../agents/definitions.js";
-import { CoreMemory } from "../memory/core.js";
-export class RoutingEngine {
-    /**
-     * Advanced Routing Engine — analyzes task descriptions,
-     * selects the most suitable agent, and determines subtasks.
-     *
-     * Uses real TF-IDF scoring: term frequency in the task weighted by
-     * inverse document frequency across the full agent candidate corpus.
-     *
-     * Semantic routing via `resolveWithEmbeddings()` blends TF-IDF scores
-     * with cosine similarity over local TF-IDF embeddings (or OpenAI embeddings
-     * when OPENAI_API_KEY is set). Use the async variant for higher accuracy.
-     */
-    static resolveAgent(taskDescription) {
-        return this.resolveWithDetails(taskDescription).agent;
-    }
-    /**
-     * Returns detailed routing result — score, confidence, reasoning, subTasks
-     */
-    static resolveWithDetails(taskDescription) {
-        const textLower = taskDescription.toLowerCase();
-        const tokens = this.tokenize(textLower);
-        const candidates = this.getCandidates();
-        let bestAgent = "@backend";
-        let bestScore = 0;
-        let bestReasoning = "";
-        let bestSubTasks = [];
-        for (const candidate of candidates) {
-            let score = 0;
-            const matches = [];
-            // 1. Specialty matching (weighted TF-IDF)
-            for (const [specialty, weight] of Object.entries(candidate.specialties)) {
-                const specTokens = this.tokenize(specialty.toLowerCase());
-                for (const token of tokens) {
-                    if (specTokens.some(st => token.includes(st) || st.includes(token))) {
-                        score += weight * this.calculateTfIdf(token, tokens, candidates);
-                        matches.push(specialty);
-                    }
-                }
-            }
-            // 2. Role matching
-            const roleTokens = this.tokenize(candidate.role.toLowerCase());
-            for (const token of tokens) {
-                if (roleTokens.some(rt => token.includes(rt) || rt.includes(token))) {
-                    score += 3; // Role match bonus
-                    matches.push(`role:${candidate.role}`);
-                }
-            }
-            // 3. DisplayName matching
-            const nameTokens = this.tokenize(candidate.displayName.toLowerCase());
-            for (const token of tokens) {
-                if (nameTokens.some(nt => token.includes(nt) || nt.includes(token))) {
-                    score += 2;
-                    matches.push(`name:${candidate.displayName}`);
-                }
-            }
-            // Capability bonus (more capable agents get priority)
-            score += (candidate.capability - 5) * 0.5;
-            if (score > bestScore) {
-                bestScore = score;
-                bestAgent = candidate.agent;
-                bestReasoning = matches.length > 0
-                    ? `Matching fields: ${[...new Set(matches)].join(", ")}`
-                    : "Selected based on general capability";
-                bestSubTasks = this.generateSubTasks(candidate.agent, taskDescription);
-            }
-        }
-        // Static fallback (if nothing matches)
-        if (bestScore === 0) {
-            const fallback = this.fallbackRouting(tokens);
-            bestAgent = fallback.agent;
-            bestReasoning = fallback.reasoning;
-            bestSubTasks = fallback.subTasks;
-        }
-        const confidence = bestScore > 15 ? "high"
-            : bestScore > 7 ? "medium"
-                : "low";
-        return {
-            agent: bestAgent,
-            score: Math.round(bestScore * 10) / 10,
-            confidence,
-            reasoning: bestReasoning,
-            subTasks: bestSubTasks,
-        };
-    }
-    // ─── Semantic Routing (Embedding-based) ─────────────────────────────────
-    /**
-     * Semantic routing via embedding cosine similarity.
-     *
-     * Blends TF-IDF score (60%) with embedding cosine similarity (40%).
-     * Falls back gracefully to pure TF-IDF when embeddings are unavailable.
-     *
-     * When OPENAI_API_KEY is set, uses text-embedding-3-small (1536-dim).
-     * Otherwise falls back to the local TF-IDF vectorizer (384-dim) from
-     * CoreMemory.generateEmbedding(), which is already used by the memory system.
-     *
-     * @param taskDescription - Natural language task to route
-     * @returns Routing result with semantic score blend
-     */
-    static async resolveWithEmbeddings(taskDescription) {
-        // Start TF-IDF routing in parallel with embedding generation
-        const tfidfResult = this.resolveWithDetails(taskDescription);
-        try {
-            const taskVector = CoreMemory.generateEmbedding(taskDescription);
-            const candidates = this.getCandidates();
-            let bestAgent = tfidfResult.agent;
-            let bestBlendedScore = -Infinity;
-            let bestReasoning = tfidfResult.reasoning;
-            for (const candidate of candidates) {
-                // Build a combined specialty text for this agent to embed
-                const specialtyText = Object.keys(candidate.specialties).join(" ") +
-                    " " + candidate.role + " " + candidate.displayName;
-                const agentVector = CoreMemory.generateEmbedding(specialtyText);
-                const similarity = this.cosineSimilarity(taskVector, agentVector);
-                // Retrieve TF-IDF score for this specific candidate
-                const candidateTfIdfScore = this.scoreSingleCandidate(taskDescription, candidate, candidates);
-                // Blend: 60% TF-IDF score (normalized 0-1) + 40% cosine similarity
-                const normalizedTfIdf = Math.min(candidateTfIdfScore / 30, 1);
-                const blendedScore = normalizedTfIdf * 0.6 + similarity * 0.4;
-                if (blendedScore > bestBlendedScore) {
-                    bestBlendedScore = blendedScore;
-                    bestAgent = candidate.agent;
-                    bestReasoning = `Semantic blend (TF-IDF: ${(normalizedTfIdf * 100).toFixed(0)}%, cosine: ${(similarity * 100).toFixed(0)}%) → ${candidate.role}`;
-                }
-            }
-            const confidence = bestBlendedScore > 0.6 ? "high"
-                : bestBlendedScore > 0.35 ? "medium"
-                    : "low";
-            logger.debug(`[ROUTING] Semantic routing selected ${bestAgent} (blend score: ${bestBlendedScore.toFixed(3)})`);
-            return {
-                agent: bestAgent,
-                score: Math.round(bestBlendedScore * 100) / 100,
-                confidence,
-                reasoning: bestReasoning,
-                subTasks: this.generateSubTasks(bestAgent, taskDescription),
-            };
-        }
-        catch (err) {
-            // Graceful fallback to TF-IDF if embedding fails
-            logger.warn(`[ROUTING] Embedding-based routing failed, falling back to TF-IDF: ${err.message}`);
-            return tfidfResult;
-        }
-    }
-    /**
-     * Scores a single candidate against a task using TF-IDF.
-     * Extracted from resolveWithDetails to support semantic blend calculation.
-     */
-    static scoreSingleCandidate(taskDescription, candidate, allCandidates) {
-        const textLower = taskDescription.toLowerCase();
-        const tokens = this.tokenize(textLower);
-        let score = 0;
-        for (const [specialty, weight] of Object.entries(candidate.specialties)) {
-            const specTokens = this.tokenize(specialty.toLowerCase());
-            for (const token of tokens) {
-                if (specTokens.some(st => token.includes(st) || st.includes(token))) {
-                    score += weight * this.calculateTfIdf(token, tokens, allCandidates);
-                }
-            }
-        }
-        score += (candidate.capability - 5) * 0.5;
-        return score;
-    }
-    /**
-     * Cosine similarity between two numeric vectors.
-     * Returns a value in [0, 1] where 1 = identical direction.
-     */
-    static cosineSimilarity(a, b) {
-        const len = Math.min(a.length, b.length);
-        let dot = 0;
-        let normA = 0;
-        let normB = 0;
-        for (let i = 0; i < len; i++) {
-            dot += a[i] * b[i];
-            normA += a[i] * a[i];
-            normB += b[i] * b[i];
-        }
-        const denom = Math.sqrt(normA) * Math.sqrt(normB);
-        return denom === 0 ? 0 : Math.max(0, dot / denom);
-    }
-    static planTask(taskDescription) {
-        const result = this.resolveWithDetails(taskDescription);
-        const plan = [
-            `>> Task: ${taskDescription}`,
-            `>> Assigned to: ${result.agent}`,
-            `>> Confidence: ${result.confidence.toUpperCase()} (Score: ${result.score})`,
-            `>> Reason: ${result.reasoning}`,
-            "",
-            ">> Subtasks:",
-            ...result.subTasks.map((t, i) => `  ${i + 1}. ${t}`),
-            "",
-            ">> Quality Check:",
-            `  - When ${result.agent} completes, @quality will review`,
-            `  - If @quality rejects, the task returns to ${result.agent}`,
-        ];
-        return plan;
-    }
-    // ─── Private Helpers ────────────────────────────────────────────────
-    static tokenize(text) {
-        return text
-            .replace(/[^a-z0-9çşıöğü ]/g, " ")
-            .split(/\s+/)
-            .filter(t => t.length > 1);
-    }
-    /**
-     * Real TF-IDF calculation: term frequency × inverse document frequency.
-     * IDF = log(N / (df + 1) + 1) where N = total candidates, df = candidates containing the term.
-     */
-    static calculateTfIdf(term, tokens, allCandidates) {
-        // TF: normalized term frequency in the task
-        const tf = tokens.filter(t => t === term).length / Math.max(tokens.length, 1);
-        // IDF: log(N / df + 1) where N = total candidates, df = candidates containing the term
-        const N = allCandidates.length;
-        const df = allCandidates.filter(c => Object.keys(c.specialties).some(s => s.toLowerCase().includes(term))).length;
-        const idf = Math.log(N / (df + 1) + 1);
-        return (1 + tf) * idf;
-    }
-    static fallbackRouting(tokens) {
-        const text = tokens.join(" ");
-        if (tokens.some(t => ["frontend", "ui", "page", "css", "html", "react", "component", "button", "form", "modal", "table", "interface"].includes(t))) {
-            return {
-                agent: "@frontend",
-                reasoning: "Frontend/UI keywords detected",
-                subTasks: this.generateSubTasks("@frontend", text),
-            };
-        }
-        if (tokens.some(t => ["security", "auth", "token", "encrypt", "login"].includes(t))) {
-            return {
-                agent: "@security",
-                reasoning: "Security keywords detected",
-                subTasks: this.generateSubTasks("@security", text),
-            };
-        }
-        if (tokens.some(t => ["database", "migration", "sql", "schema", "table", "index", "query"].includes(t))) {
-            return {
-                agent: "@database",
-                reasoning: "Database keywords detected",
-                subTasks: this.generateSubTasks("@database", text),
-            };
-        }
-        if (tokens.some(t => ["docker", "ci", "cd", "deploy", "devops", "infra", "server", "nginx"].includes(t))) {
-            return {
-                agent: "@devops",
-                reasoning: "DevOps/Infra keywords detected",
-                subTasks: this.generateSubTasks("@devops", text),
-            };
-        }
-        if (tokens.some(t => ["mobile", "react native", "expo", "ios", "android"].includes(t))) {
-            return {
-                agent: "@mobile",
-                reasoning: "Mobile keywords detected",
-                subTasks: this.generateSubTasks("@mobile", text),
-            };
-        }
-        if (tokens.some(t => ["architect", "design", "architecture", "contract", "structure"].includes(t))) {
-            return {
-                agent: "@architect",
-                reasoning: "Architecture/design keywords detected",
-                subTasks: this.generateSubTasks("@architect", text),
-            };
-        }
-        if (tokens.some(t => ["analysis", "analyst", "requirement", "contract", "validate"].includes(t))) {
-            return {
-                agent: "@analyst",
-                reasoning: "Analysis/requirement keywords detected",
-                subTasks: this.generateSubTasks("@analyst", text),
-            };
-        }
-        return {
-            agent: "@backend",
-            reasoning: "Default routing to backend (most general capability)",
-            subTasks: this.generateSubTasks("@backend", text),
-        };
-    }
-    static generateSubTasks(agent, taskDescription) {
-        const base = [
-            `[*] ${agent}: Analyze and plan the task`,
-            `[>] ${taskDescription}`,
-            "[*] Write and run tests",
-            "[*] Notify @quality for QA review",
-        ];
-        const agentSpecific = {
-            "@manager": [
-                "[*] Analyze task and break into subtasks",
-                "[*] Identify suitable agents and distribute tasks",
-                "[*] Monitor progress and manage quality gate",
-            ],
-            "@backend": [
-                "[*] Create Controller-Service-Repository layers",
-                "[*] Update API contracts",
-                "[*] Integrate database operations",
-            ],
-            "@frontend": [
-                "[*] Create UI components in atomic structure",
-                "[*] Apply responsive design",
-                "[*] Integrate with API",
-            ],
-            "@quality": [
-                "[*] Run compliance check (check_compliance)",
-                "[*] Run lint check",
-                "[*] Verify test coverage",
-                "[*] Report approval/rejection to @manager",
-            ],
-            "@database": [
-                "[*] Prepare migration file",
-                "[*] Optimize queries",
-                "[*] Define index strategy",
-            ],
-            "@security": [
-                "[*] Run security vulnerability scan",
-                "[*] Verify auth/encryption controls",
-                "[*] Check secret management",
-            ],
-            "@devops": [
-                "[*] Prepare Docker configuration",
-                "[*] Update CI/CD pipeline",
-                "[*] Check environment variables",
-            ],
-            "@mobile": [
-                "[*] Create React Native components",
-                "[*] Apply offline-first architecture",
-                "[*] Implement SafeArea and responsive controls",
-            ],
-            "@explorer": [
-                "[*] Explore and map the codebase",
-                "[*] Analyze dependencies",
-                "[*] Send report to @manager",
-            ],
-            "@git": [
-                "[*] Define branch strategy",
-                "[*] Prepare commit messages with Trace ID",
-                "[*] Perform rebase/merge operations if needed",
-            ],
-        };
-        const specific = agentSpecific[agent] || [];
-        return [...specific, ...base];
-    }
-    /**
-     * Quality feedback loop — retries if @quality rejects
-     * Uses real MCP calls, not simulations.
-     */
-    static async qualityLoop(agent, taskDescription, maxRetries = 3) {
-        for (let attempt = 1; attempt <= maxRetries; attempt++) {
-            logger.info(`[RETRY] Attempt ${attempt}/${maxRetries}: ${agent} running...`, {
-                agent,
-                attempt,
-                maxRetries,
-                task: taskDescription.substring(0, 100),
-            });
-            // Agent runs via MCP call
-            const result = await this.runAgent(agent, taskDescription);
-            // Quality check via MCP
-            const qualityResult = await this.runQualityCheck(result);
-            if (qualityResult.passed) {
-                logger.info(`[OK] Quality check PASSED (attempt ${attempt})`, { agent, attempt });
-                return { success: true, attempts: attempt };
-            }
-            logger.warn(`[FAIL] Quality check FAILED: ${qualityResult.reason}`, {
-                agent,
-                attempt,
-                reason: qualityResult.reason,
-            });
-            logger.info(`[RETRY] ${agent} fixing errors...`, { agent, attempt });
-        }
-        logger.error(`[FAIL] ${maxRetries} attempts exhausted. Human intervention required.`, {
-            agent,
-            maxRetries,
-            task: taskDescription.substring(0, 100),
-        });
-        return { success: false, attempts: maxRetries };
-    }
-    /**
-     * Runs the agent through the Hermes messaging system.
-     *
-     * Flow:
-     * 1. Write DELEGATION message to agent's queue (Storage.saveMessage)
-     * 2. Wait for agent response (polling, max 30 seconds)
-     * 3. Parse response and return as output
-     */
-    static async runAgent(agent, task) {
-        const agentName = agent.replace("@", "");
-        const traceId = `T-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
-        const messagePayload = JSON.stringify({
-            type: "DELEGATION",
-            task,
-            traceId,
-            from: "@manager",
-        });
-        AtabeyStorage.saveMessage({
-            from: asAgentID("@manager"),
-            to: asAgentID(agent),
-            category: "DELEGATION",
-            content: messagePayload,
-            traceId: asTraceID(traceId),
-            timestamp: new Date().toISOString(),
-            status: "PENDING",
-            priority: "HIGH",
-            requiresApproval: false,
-        });
-        logger.info(`[HERMES] Delegation sent to ${agent} (trace: ${traceId})`);
-        // Poll for response (max 30 seconds)
-        const maxAttempts = 60;
-        const pollInterval = 500;
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            const messages = AtabeyStorage.getPendingMessages();
-            const response = messages.find(m => m.from.replace("@", "") === agentName
-                && m.category === "RESPONSE"
-                && m.traceId === traceId
-                && m.status === "PENDING");
-            if (response) {
-                if (response.id !== undefined) {
-                    AtabeyStorage.updateMessageStatus(response.id, "PROCESSED");
-                }
-                logger.info(`[HERMES] Response received from ${agent} (trace: ${traceId})`);
-                return response.content;
-            }
-            await new Promise(resolve => setTimeout(resolve, pollInterval));
-        }
-        const timeoutMsg = `[TIMEOUT] ${agent} did not respond within 30s`;
-        logger.warn(`[HERMES] ${timeoutMsg} (trace: ${traceId})`);
-        return timeoutMsg;
-    }
-    /**
-     * Runs quality control through the real QualityGate.
-     *
-     * Flow:
-     * 1. QualityGate.check() for compliance + lint + test + content validation
-     * 2. Aggregate results
-     */
-    static async runQualityCheck(result) {
-        const { QualityGate } = await import("./quality-gate.js");
-        const qualityResult = await QualityGate.check("@quality", result, "Quality check via routing engine");
-        return {
-            passed: qualityResult.passed,
-            reason: qualityResult.reason,
-        };
-    }
-    static getCandidates() {
-        const frameworkDir = getFrameworkDir();
-        const registryDir = path.join(frameworkDir, "registry");
-        let candidates = [];
-        // 1. Control Plane Registry (actively registered agents)
-        if (fs.existsSync(registryDir)) {
-            const registryFiles = fs.readdirSync(registryDir).filter(f => f.endsWith("_active.json"));
-            for (const file of registryFiles) {
-                try {
-                    const data = JSON.parse(fs.readFileSync(path.join(registryDir, file), "utf8"));
-                    if (data.agent && data.specialties) {
-                        candidates.push({
-                            agent: data.agent,
-                            specialties: data.specialties,
-                            displayName: data.displayName || data.agent,
-                            role: data.role || "",
-                            capability: data.capability || 8,
-                            tier: data.tier || "core",
-                        });
-                    }
-                }
-                catch (err) {
-                    logger.debug(`Failed to parse registry file: ${file}`, err);
-                }
-            }
-        }
-        // 2. Built-in agent definitions
-        if (candidates.length === 0) {
-            candidates = ALL_AGENTS.map(ag => ({
-                agent: ag.name.startsWith("@") ? ag.name : `@${ag.name}`,
-                specialties: ag.specialties ?? this.defaultSpecialties(ag.name),
-                displayName: ag.displayName,
-                role: ag.role,
-                capability: ag.capability,
-                tier: ag.tier,
-            }));
-        }
-        return candidates;
-    }
-    /**
-     * Default values for agents without a specialties field
-     */
-    static defaultSpecialties(name) {
-        const defaults = {
-            manager: { orchestration: 10, governance: 10, delegation: 10, audit: 8, planning: 9 },
-            architect: { design: 10, contract: 9, architecture: 10, types: 9, planning: 8 },
-            backend: { backend: 10, api: 9, logic: 9, service: 8, database: 7, test: 8 },
-            frontend: { frontend: 10, ui: 10, css: 9, html: 9, react: 9, responsive: 8 },
-            mobile: { mobile: 10, "react native": 9, expo: 8, offline: 8, accessibility: 7 },
-            quality: { audit: 10, compliance: 10, lint: 9, test: 9, coverage: 8 },
-            database: { database: 10, migration: 9, sql: 9, schema: 8, index: 8 },
-            security: { security: 10, auth: 9, encryption: 8, audit: 9, token: 8 },
-            devops: { devops: 10, docker: 9, ci: 9, deploy: 9, infra: 8 },
-            analyst: { analysis: 10, contract: 9, requirement: 9, validation: 8, documentation: 7 },
-            native: { native: 9, desktop: 8, "os-level": 8, security: 8 },
-            explorer: { discovery: 10, mapping: 9, dependency: 8, recon: 8 },
-            git: { git: 10, version: 9, commit: 8, branching: 8, traceability: 8 },
-        };
-        return defaults[name] || { general: 5 };
-    }
-}

package/framework-mcp/dist/src/modules/engines/types.js

@@ -1 +0,0 @@
-export {};

package/framework-mcp/dist/src/modules/memory/core.js

@@ -1,99 +0,0 @@
-import crypto from "crypto";
-import { generateEmbedding } from "./embedding.js";
-import { VectorStore } from "./vector-store.js";
-/**
- * [MEMORY] Core Memory Service
- * High-level API for managing project knowledge and embeddings.
- * Uses OpenAI Embedding API when available, falls back to TF-IDF.
- */
-export class CoreMemory {
-    static VECTOR_DIM = 384;
-    static STOP_WORDS = new Set([
-        "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for",
-        "of", "with", "by", "from", "as", "is", "was", "are", "were", "be",
-        "been", "being", "have", "has", "had", "do", "does", "did", "will",
-        "would", "could", "should", "may", "might", "shall", "can", "need",
-    ]);
-    static async init() {
-        VectorStore.initialize();
-    }
-    /**
-     * Records a new piece of knowledge into the core memory.
-     * Uses OpenAI Embedding API when available, falls back to TF-IDF.
-     */
-    static async remember(params) {
-        const id = crypto.createHash("sha256").update(params.content + (params.filePath || "")).digest("hex");
-        // Use provided vector or generate via embedding service
-        const vector = params.vector || await generateEmbedding(params.content);
-        const entry = {
-            id,
-            content: params.content,
-            vector,
-            metadata: {
-                category: params.category,
-                traceId: params.traceId,
-                filePath: params.filePath,
-                tags: params.tags || [],
-                createdAt: new Date().toISOString()
-            }
-        };
-        await VectorStore.addEntry(entry);
-        return id;
-    }
-    /**
-     * Searches the memory for relevant knowledge using cosine similarity.
-     * Uses OpenAI Embedding API when available for the query vector.
-     */
-    static async recall(query, options) {
-        const vector = options.queryVector || await generateEmbedding(query);
-        return VectorStore.search(vector, options.limit || 5, options.category);
-    }
-    /**
-     * Generates a TF-IDF style embedding vector from text.
-     * Kept for backward compatibility and as fallback.
-     */
-    static generateEmbedding(text) {
-        const vector = new Array(this.VECTOR_DIM).fill(0);
-        // Tokenize and clean
-        const tokens = text
-            .toLowerCase()
-            .replace(/[^a-z0-9çşıöğü_ ]/g, " ")
-            .split(/\s+/)
-            .filter(t => t.length > 2 && !this.STOP_WORDS.has(t));
-        if (tokens.length === 0) {
-            return vector;
-        }
-        // Calculate term frequency
-        const tf = new Map();
-        for (const token of tokens) {
-            tf.set(token, (tf.get(token) || 0) + 1);
-        }
-        // Map each unique token to vector positions using hash
-        for (const [token, freq] of tf) {
-            for (let i = 0; i < token.length - 1; i++) {
-                const ngram = token.substring(i, i + 2);
-                const pos = this.hashToPosition(ngram);
-                vector[pos] += freq * (i + 1) / token.length;
-            }
-        }
-        // Normalize to unit vector
-        const magnitude = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
-        if (magnitude > 0) {
-            for (let i = 0; i < this.VECTOR_DIM; i++) {
-                vector[i] /= magnitude;
-            }
-        }
-        return vector;
-    }
-    /**
-     * Deterministically maps a string to a position in the vector.
-     */
-    static hashToPosition(value) {
-        let hash = 0;
-        for (let i = 0; i < value.length; i++) {
-            hash = ((hash << 5) - hash) + value.charCodeAt(i);
-            hash |= 0;
-        }
-        return Math.abs(hash) % this.VECTOR_DIM;
-    }
-}