@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

package/mcp/dist/orchestrator.js

@@ -0,0 +1,222 @@
+import { randomUUID } from "node:crypto";
+import { createNoopOrchestrationAudit } from "./orchestration-audit.js";
+import { selectQuestionTemplate } from "./question-templates.js";
+import { routeIntent } from "./router.js";
+export function createOrchestrator(options) {
+    const sessions = new Map();
+    const audit = options.audit ?? createNoopOrchestrationAudit();
+    return {
+        orchestrate(input) {
+            const session = getOrCreateSession(sessions, options.registry, input);
+            mergeInput(session, input);
+            const missingInfo = missingRequiredQuestionIds(session.questions, session.answers);
+            const suggestions = ensureMemorySuggestions(options.memory, session);
+            const pendingSuggestions = suggestions.filter((suggestion) => session.memoryConfirmations[suggestion.key] === undefined);
+            const acceptedSuggestions = suggestions.filter((suggestion) => session.memoryConfirmations[suggestion.key] === "accepted");
+            const state = selectState(session, missingInfo, pendingSuggestions);
+            for (const [suggestionKey, decision] of Object.entries(input.memoryConfirmations ?? {})) {
+                options.memory.recordDecision({ suggestionKey, decision });
+            }
+            const verificationGate = buildVerificationGate(acceptedSuggestions);
+            const finalWorkflow = state === "ready" ? session.workflow : undefined;
+            const firstSkillToLoad = finalWorkflow?.[0]?.skill;
+            const nextAction = buildNextAction(state, session, missingInfo, pendingSuggestions, firstSkillToLoad);
+            persistSession(options.memory, session, state, verificationGate, finalWorkflow);
+            const auditRef = audit.record({
+                sessionId: session.sessionId,
+                state,
+                taskMode: session.route.taskMode,
+                message: session.message,
+                nextAction,
+            });
+            return {
+                sessionId: session.sessionId,
+                state,
+                message: session.message,
+                taskMode: session.route.taskMode,
+                questions: session.questions,
+                missingInfo,
+                route: session.route,
+                workflow: session.workflow,
+                memorySuggestions: suggestions,
+                ...(finalWorkflow ? { finalWorkflow } : {}),
+                ...(firstSkillToLoad ? { firstSkillToLoad } : {}),
+                verificationGate,
+                nextAction,
+                ...(auditRef ? { auditRef } : {}),
+            };
+        },
+    };
+}
+function getOrCreateSession(sessions, registry, input) {
+    if (input.sessionId && sessions.has(input.sessionId)) {
+        return sessions.get(input.sessionId);
+    }
+    const route = routeIntent(registry, {
+        message: input.message,
+        ...(input.context
+            ? {
+                context: {
+                    ...(input.context.files ? { files: input.context.files } : {}),
+                    ...(input.context.mode ? { mode: input.context.mode } : {}),
+                    ...(input.context.previousErrors ? { previousErrors: input.context.previousErrors } : {}),
+                },
+            }
+            : {}),
+        limit: 5,
+    });
+    const workflow = ensureBrainstormingFirst(registry, route.workflow, input);
+    const template = selectQuestionTemplate({
+        taskMode: route.taskMode,
+        workflowSkillIds: workflow.map((step) => step.skill.id),
+        recommendedSkillIds: route.recommended.map((item) => item.skill.id),
+    });
+    const session = {
+        sessionId: input.sessionId ?? randomUUID(),
+        message: input.message,
+        createdAt: new Date().toISOString(),
+        route,
+        workflow,
+        questions: template.questions,
+        answers: {},
+        memorySuggestions: [],
+        memoryConfirmations: {},
+        ...(input.context ? { context: input.context } : {}),
+    };
+    sessions.set(session.sessionId, session);
+    return session;
+}
+function persistSession(memory, session, state, verificationGate, finalWorkflow) {
+    const now = new Date().toISOString();
+    memory.recordSession({
+        id: session.sessionId,
+        state,
+        message: session.message,
+        taskMode: session.route.taskMode,
+        route: toJsonObject(session.route),
+        questions: toJsonArray(session.questions),
+        answers: { ...session.answers },
+        memorySuggestions: session.memorySuggestions.map((suggestion) => ({ ...suggestion })),
+        finalWorkflow: toJsonArray(finalWorkflow ?? []),
+        createdAt: session.createdAt,
+        updatedAt: now,
+    });
+    if (state === "ready" && finalWorkflow) {
+        memory.recordOutcome({
+            id: randomUUID(),
+            sessionId: session.sessionId,
+            taskMode: session.route.taskMode,
+            workflow: toJsonArray(finalWorkflow),
+            verification: verificationGate,
+            outcome: "workflow-released",
+            createdAt: now,
+        });
+    }
+}
+function mergeInput(session, input) {
+    session.message = input.message || session.message;
+    session.answers = { ...session.answers, ...(input.answers ?? {}) };
+    session.memoryConfirmations = { ...session.memoryConfirmations, ...(input.memoryConfirmations ?? {}) };
+    if (input.context) {
+        session.context = input.context;
+    }
+}
+function ensureMemorySuggestions(memory, session) {
+    if (session.memorySuggestions.length > 0) {
+        return session.memorySuggestions;
+    }
+    session.memorySuggestions = memory.suggest({
+        taskMode: session.route.taskMode,
+        workflowSkillIds: session.workflow.map((step) => step.skill.id),
+        ...(session.context?.projectFingerprint ? { projectFingerprint: session.context.projectFingerprint } : {}),
+    });
+    return session.memorySuggestions;
+}
+function selectState(session, missingInfo, pendingSuggestions) {
+    if (isSubstantiveWork(session) && Object.keys(session.answers).length === 0) {
+        return "brainstorming_required";
+    }
+    if (missingInfo.length > 0) {
+        return "questioning";
+    }
+    if (pendingSuggestions.length > 0) {
+        return "awaiting_memory_confirmation";
+    }
+    return "ready";
+}
+function ensureBrainstormingFirst(registry, workflow, input) {
+    const existing = workflow.filter((step) => step.skill.id !== "productivity/brainstorming");
+    const brainstorming = findSkillById(registry, "productivity/brainstorming");
+    if (!brainstorming) {
+        return workflow;
+    }
+    const step = {
+        skill: brainstorming,
+        role: "prepare",
+        reason: "C4 Brainstorming-First Gate requires design clarification before substantive work.",
+    };
+    if (input.context?.mode === "brainstorming" || /\bbrainstorm(?:ing)?\b/i.test(input.message)) {
+        return [step, ...existing];
+    }
+    if (isReadOnlyRequest(input.message)) {
+        return workflow;
+    }
+    return [step, ...existing];
+}
+function findSkillById(registry, id) {
+    const [category, skill] = id.split("/");
+    if (!category || !skill) {
+        return undefined;
+    }
+    try {
+        return registry.getSkill(category, skill);
+    }
+    catch {
+        return undefined;
+    }
+}
+function missingRequiredQuestionIds(questions, answers) {
+    return questions
+        .filter((question) => question.required)
+        .filter((question) => !answers[question.id]?.trim())
+        .map((question) => question.id);
+}
+function buildVerificationGate(acceptedSuggestions) {
+    const commands = acceptedSuggestions.flatMap((suggestion) => {
+        const commands = suggestion.value.commands;
+        return Array.isArray(commands) ? commands.filter((command) => typeof command === "string") : [];
+    });
+    return {
+        commands: commands.length > 0 ? [...new Set(commands)] : ["npm --prefix mcp test", "npm --prefix mcp run typecheck"],
+        reason: commands.length > 0
+            ? "Memory-confirmed verification commands must pass before completion."
+            : "Default MCP verification gate for C4 orchestration.",
+    };
+}
+function buildNextAction(state, session, missingInfo, pendingSuggestions, firstSkillToLoad) {
+    if (state === "brainstorming_required") {
+        return `Start with productivity/brainstorming and answer required C4 questions: ${missingInfo.join(", ")}.`;
+    }
+    if (state === "questioning") {
+        return `Answer missing C4 questions before workflow execution: ${missingInfo.join(", ")}.`;
+    }
+    if (state === "awaiting_memory_confirmation") {
+        return `Accept or reject memory suggestions before execution: ${pendingSuggestions.map((item) => item.key).join(", ")}.`;
+    }
+    if (firstSkillToLoad) {
+        return `Load ${firstSkillToLoad.id} with kilo_get_skill, then follow the final workflow.`;
+    }
+    return session.route.nextAction;
+}
+function isSubstantiveWork(session) {
+    return !isReadOnlyRequest(session.message);
+}
+function isReadOnlyRequest(message) {
+    return /\b(status|show|read|explain|what is|what's|la sao|là sao)\b/i.test(message);
+}
+function toJsonObject(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function toJsonArray(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/mcp/dist/question-templates.js

@@ -0,0 +1,249 @@
+const BASE_QUESTIONS = [
+    {
+        id: "goal",
+        prompt: "What exact outcome should this task produce?",
+        kind: "text",
+        required: true,
+    },
+    {
+        id: "scope",
+        prompt: "Which files, modules, or behavior are in scope, and what is explicitly out of scope?",
+        kind: "text",
+        required: true,
+    },
+    {
+        id: "success_criteria",
+        prompt: "What evidence will prove the task is complete and working correctly?",
+        kind: "text",
+        required: true,
+    },
+];
+const MODE_QUESTIONS = {
+    "bug-test-first": {
+        id: "engineering:bug-test-first",
+        label: "Engineering bug/TDD clarification",
+        questions: [
+            {
+                id: "failing_behavior",
+                prompt: "What is the current failing behavior, including the smallest reproducible trigger?",
+                kind: "text",
+                required: true,
+                category: "engineering",
+            },
+            {
+                id: "test_command",
+                prompt: "Which focused test or command should fail before the fix and pass after it?",
+                kind: "text",
+                required: true,
+                category: "engineering",
+                skillId: "engineering/tdd",
+            },
+        ],
+    },
+    ui: {
+        id: "design:ui",
+        label: "Design and UI clarification",
+        questions: [
+            {
+                id: "audience",
+                prompt: "Who will use this interface, and what is their most common workflow?",
+                kind: "text",
+                required: true,
+                category: "design",
+            },
+            {
+                id: "visual_constraints",
+                prompt: "Which existing design system, layout, or responsive constraints must be preserved?",
+                kind: "text",
+                required: true,
+                category: "design",
+            },
+        ],
+    },
+    review: {
+        id: "engineering:review",
+        label: "Code review clarification",
+        questions: [
+            {
+                id: "review_target",
+                prompt: "Which branch, diff, or files should be reviewed, and what risks matter most?",
+                kind: "text",
+                required: true,
+                category: "engineering",
+                skillId: "engineering/code-review",
+            },
+            {
+                id: "merge_gate",
+                prompt: "What checks must pass before this can be considered merge-ready?",
+                kind: "text",
+                required: true,
+                category: "engineering",
+            },
+        ],
+    },
+    "workflow-optimization": {
+        id: "engineering:workflow-optimization",
+        label: "Architecture and workflow clarification",
+        questions: [
+            {
+                id: "current_friction",
+                prompt: "Where is the current rule or workflow friction showing up in real use?",
+                kind: "text",
+                required: true,
+                category: "engineering",
+            },
+            {
+                id: "desired_operating_model",
+                prompt: "What should the agent do differently after this workflow change lands?",
+                kind: "text",
+                required: true,
+                category: "engineering",
+            },
+        ],
+    },
+};
+const CATEGORY_QUESTIONS = {
+    engineering: {
+        id: "engineering:general",
+        label: "Engineering clarification",
+        questions: [
+            {
+                id: "runtime",
+                prompt: "Which runtime, framework, or command environment must this work support?",
+                kind: "text",
+                required: true,
+                category: "engineering",
+            },
+        ],
+    },
+    design: MODE_QUESTIONS.ui,
+    operations: {
+        id: "operations:general",
+        label: "Operations clarification",
+        questions: [
+            {
+                id: "environment",
+                prompt: "Which environment is affected, and what rollback or safety constraint applies?",
+                kind: "text",
+                required: true,
+                category: "operations",
+            },
+        ],
+    },
+    "writing-docs": {
+        id: "writing-docs:general",
+        label: "Documentation clarification",
+        questions: [
+            {
+                id: "audience",
+                prompt: "Who is the target reader, and what should they be able to do after reading?",
+                kind: "text",
+                required: true,
+                category: "writing-docs",
+            },
+        ],
+    },
+    security: {
+        id: "security:general",
+        label: "Security clarification",
+        questions: [
+            {
+                id: "risk_boundary",
+                prompt: "What asset, permission boundary, or threat scenario must be protected?",
+                kind: "text",
+                required: true,
+                category: "security",
+            },
+        ],
+    },
+    fallback: {
+        id: "general:fallback",
+        label: "General clarification",
+        questions: [
+            {
+                id: "constraints",
+                prompt: "What constraints, deadlines, or preferences should shape this workflow?",
+                kind: "text",
+                required: true,
+            },
+        ],
+    },
+};
+const SKILL_OVERRIDES = {
+    "engineering/tdd": [
+        {
+            id: "test_command",
+            prompt: "Which exact test command should demonstrate red before green?",
+            kind: "text",
+            required: true,
+            category: "engineering",
+            skillId: "engineering/tdd",
+        },
+    ],
+    "design/frontend-design": [
+        {
+            id: "visual_constraints",
+            prompt: "Which visual style, density, and responsive breakpoints should guide the UI?",
+            kind: "text",
+            required: true,
+            category: "design",
+            skillId: "design/frontend-design",
+        },
+    ],
+    "operations/deployment-procedures": [
+        {
+            id: "rollback_plan",
+            prompt: "What rollback signal and rollback command should be ready before deployment?",
+            kind: "text",
+            required: true,
+            category: "operations",
+            skillId: "operations/deployment-procedures",
+        },
+    ],
+    "engineering/vulnerability-scanner": [
+        {
+            id: "risk_boundary",
+            prompt: "Which threat model, asset, or exploit class should this security review prioritize?",
+            kind: "text",
+            required: true,
+            category: "engineering",
+            skillId: "engineering/vulnerability-scanner",
+        },
+    ],
+    "productivity/verification-before-completion": [
+        {
+            id: "verification_commands",
+            prompt: "Which commands or manual checks must be fresh before completion is claimed?",
+            kind: "text",
+            required: false,
+            category: "productivity",
+            skillId: "productivity/verification-before-completion",
+        },
+    ],
+};
+export function selectQuestionTemplate(input) {
+    const modeTemplate = MODE_QUESTIONS[input.taskMode];
+    const categoryTemplate = modeTemplate ?? categoryTemplateFor(input);
+    const workflowSkillIds = input.workflowSkillIds.length > 0 ? input.workflowSkillIds : input.recommendedSkillIds;
+    const overrideQuestions = workflowSkillIds.flatMap((skillId) => SKILL_OVERRIDES[skillId] ?? []);
+    return {
+        id: categoryTemplate.id,
+        label: categoryTemplate.label,
+        questions: dedupeQuestions([...BASE_QUESTIONS, ...categoryTemplate.questions, ...overrideQuestions]).slice(0, 8),
+    };
+}
+function categoryTemplateFor(input) {
+    const firstSkillId = input.workflowSkillIds[0] ?? input.recommendedSkillIds[0];
+    const category = firstSkillId?.split("/")[0];
+    if (category && CATEGORY_QUESTIONS[category]) {
+        return CATEGORY_QUESTIONS[category];
+    }
+    return CATEGORY_QUESTIONS.fallback;
+}
+function dedupeQuestions(questions) {
+    const byId = new Map();
+    for (const question of questions) {
+        byId.set(question.id, question);
+    }
+    return [...byId.values()];
+}

package/mcp/dist/route-analytics.js

@@ -0,0 +1,149 @@
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+export function createInMemoryRouteAnalytics(initialEvents = []) {
+    const events = [...initialEvents];
+    return {
+        record(event) {
+            events.push(cloneEvent(event));
+        },
+        events() {
+            return events.map(cloneEvent);
+        },
+        report() {
+            return buildReport(events);
+        },
+        scoreAdjustment(skillId, taskMode) {
+            return scoreAdjustment(events, skillId, taskMode);
+        },
+    };
+}
+export function createJsonlRouteAnalytics(options) {
+    return {
+        record(event) {
+            mkdirSync(path.dirname(options.filePath), { recursive: true });
+            appendFileSync(options.filePath, `${JSON.stringify(event)}\n`, "utf8");
+        },
+        events() {
+            return readJsonlEvents(options.filePath);
+        },
+        report() {
+            return buildReport(readJsonlEvents(options.filePath));
+        },
+        scoreAdjustment(skillId, taskMode) {
+            return scoreAdjustment(readJsonlEvents(options.filePath), skillId, taskMode);
+        },
+    };
+}
+function buildReport(events) {
+    const taskModes = new Map();
+    const workflows = new Map();
+    const skills = new Map();
+    const conflicts = new Map();
+    for (const event of events) {
+        taskModes.set(event.taskMode, (taskModes.get(event.taskMode) ?? 0) + 1);
+        const workflowKey = event.workflowSkillIds.join(" -> ");
+        if (workflowKey) {
+            const current = workflows.get(workflowKey) ?? { workflow: event.workflowSkillIds, count: 0 };
+            current.count += 1;
+            workflows.set(workflowKey, current);
+        }
+        event.recommendedSkillIds.forEach((skillId) => {
+            const stats = skillStats(skills, skillId);
+            stats.timesRecommended += 1;
+        });
+        event.workflowSkillIds.forEach((skillId, index) => {
+            const stats = skillStats(skills, skillId);
+            stats.timesInWorkflow += 1;
+            if (index === 0) {
+                stats.timesPrimary += 1;
+            }
+        });
+        for (const entry of event.decisionTrail) {
+            const stats = skillStats(skills, entry.skillId);
+            stats.totalScore += entry.score;
+            stats.scoreSamples += 1;
+            const conflict = entry.scoreBreakdown.conflict ?? 0;
+            if (conflict < 0) {
+                const current = conflicts.get(entry.skillId) ?? { count: 0, totalPenalty: 0 };
+                current.count += 1;
+                current.totalPenalty += conflict;
+                conflicts.set(entry.skillId, current);
+            }
+        }
+    }
+    return {
+        totalEvents: events.length,
+        taskModes: [...taskModes.entries()]
+            .map(([taskMode, count]) => ({ taskMode, count }))
+            .sort((left, right) => right.count - left.count || left.taskMode.localeCompare(right.taskMode)),
+        workflows: [...workflows.values()].sort((left, right) => right.count - left.count || left.workflow.join(">").localeCompare(right.workflow.join(">"))),
+        topSkills: [...skills.entries()]
+            .map(([skillId, stats]) => ({
+            skillId,
+            timesRecommended: stats.timesRecommended,
+            timesInWorkflow: stats.timesInWorkflow,
+            timesPrimary: stats.timesPrimary,
+            avgScore: stats.scoreSamples === 0 ? 0 : Math.round((stats.totalScore / stats.scoreSamples) * 100) / 100,
+        }))
+            .sort((left, right) => right.timesPrimary - left.timesPrimary ||
+            right.timesRecommended + right.timesInWorkflow - (left.timesRecommended + left.timesInWorkflow) ||
+            right.avgScore - left.avgScore ||
+            left.skillId.localeCompare(right.skillId)),
+        conflictPenalties: [...conflicts.entries()]
+            .map(([skillId, stats]) => ({ skillId, count: stats.count, totalPenalty: stats.totalPenalty }))
+            .sort((left, right) => right.count - left.count || left.skillId.localeCompare(right.skillId)),
+    };
+}
+function scoreAdjustment(events, skillId, taskMode) {
+    const sameMode = events.filter((event) => event.taskMode === taskMode);
+    const recommended = sameMode.filter((event) => event.recommendedSkillIds.includes(skillId)).length;
+    const inWorkflow = sameMode.filter((event) => event.workflowSkillIds.includes(skillId)).length;
+    const primary = sameMode.filter((event) => event.workflowSkillIds[0] === skillId).length;
+    return Math.min(12, recommended * 3 + inWorkflow * 2 + primary * 3);
+}
+function skillStats(skills, skillId) {
+    const existing = skills.get(skillId);
+    if (existing) {
+        return existing;
+    }
+    const created = { timesRecommended: 0, timesInWorkflow: 0, timesPrimary: 0, totalScore: 0, scoreSamples: 0 };
+    skills.set(skillId, created);
+    return created;
+}
+function readJsonlEvents(filePath) {
+    let content = "";
+    try {
+        content = readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    return content
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => parseRouteEvent(line))
+        .filter((event) => event !== null);
+}
+function parseRouteEvent(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed.timestamp !== "string" ||
+            typeof parsed.message !== "string" ||
+            typeof parsed.taskMode !== "string" ||
+            !Array.isArray(parsed.recommendedSkillIds) ||
+            !Array.isArray(parsed.workflowSkillIds) ||
+            !Array.isArray(parsed.decisionTrail)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function cloneEvent(event) {
+    return JSON.parse(JSON.stringify(event));
+}