@musashishao/agent-kit 1.2.2 → 1.4.0

package/.agent/mcp-gateway/dist/sync/debouncer.js

@@ -0,0 +1,112 @@
+/**
+ * Debouncer
+ *
+ * Prevents excessive syncing by enforcing a cooldown period
+ * between sync operations. Essential for performance when
+ * AI makes many rapid queries.
+ */
+export class Debouncer {
+    lastSync = 0;
+    cooldownMs;
+    pendingSync = null;
+    /**
+     * @param cooldownMs Minimum time between syncs (default: 30 seconds)
+     */
+    constructor(cooldownMs = 30000) {
+        this.cooldownMs = cooldownMs;
+    }
+    /**
+     * Check if enough time has passed since last sync
+     */
+    canSync() {
+        const now = Date.now();
+        return now - this.lastSync >= this.cooldownMs;
+    }
+    /**
+     * Get remaining cooldown time in milliseconds
+     */
+    getRemainingCooldown() {
+        const elapsed = Date.now() - this.lastSync;
+        const remaining = this.cooldownMs - elapsed;
+        return Math.max(0, remaining);
+    }
+    /**
+     * Get remaining cooldown time in human-readable format
+     */
+    getRemainingCooldownFormatted() {
+        const remaining = this.getRemainingCooldown();
+        if (remaining === 0)
+            return "Ready";
+        return `${Math.ceil(remaining / 1000)}s`;
+    }
+    /**
+     * Mark that a sync has occurred
+     */
+    markSynced() {
+        this.lastSync = Date.now();
+        this.pendingSync = null;
+    }
+    /**
+     * Execute a sync operation with debouncing
+     *
+     * @param syncFn The sync function to execute
+     * @returns Result of sync or null if debounced
+     */
+    async executeWithDebounce(syncFn) {
+        if (!this.canSync()) {
+            return {
+                executed: false,
+                reason: `Cooldown active. Next sync available in ${this.getRemainingCooldownFormatted()}`,
+            };
+        }
+        // Prevent concurrent syncs
+        if (this.pendingSync) {
+            return {
+                executed: false,
+                reason: "Sync already in progress",
+            };
+        }
+        try {
+            this.pendingSync = Promise.resolve();
+            const result = await syncFn();
+            this.markSynced();
+            return { executed: true, result };
+        }
+        catch (error) {
+            this.pendingSync = null;
+            return {
+                executed: false,
+                reason: `Sync failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    /**
+     * Force reset the debouncer (for manual sync commands)
+     */
+    reset() {
+        this.lastSync = 0;
+        this.pendingSync = null;
+    }
+    /**
+     * Get debouncer status
+     */
+    getStatus() {
+        return {
+            lastSync: this.lastSync > 0
+                ? new Date(this.lastSync).toISOString()
+                : "Never",
+            canSync: this.canSync(),
+            cooldownRemaining: this.getRemainingCooldownFormatted(),
+        };
+    }
+}
+/**
+ * Singleton debouncer instance for global use
+ */
+let globalDebouncer = null;
+export function getGlobalDebouncer(cooldownMs) {
+    if (!globalDebouncer) {
+        globalDebouncer = new Debouncer(cooldownMs);
+    }
+    return globalDebouncer;
+}

package/.agent/mcp-gateway/dist/sync/incremental_syncer.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Incremental Syncer
+ *
+ * Updates only the changed files in the AI infrastructure
+ * instead of regenerating everything from scratch.
+ */
+import { TimestampChecker } from "./timestamp_checker.js";
+export interface SyncResult {
+    success: boolean;
+    target: "graph" | "rag" | "all";
+    filesUpdated: string[];
+    duration: number;
+    error?: string;
+}
+export declare class IncrementalSyncer {
+    private projectRoot;
+    private kitPath;
+    private timestampChecker;
+    constructor(projectRoot: string, kitPath?: string);
+    /**
+     * Detect Agent Kit installation path
+     */
+    private detectKitPath;
+    /**
+     * Run a Python script and return output
+     */
+    private runPythonScript;
+    /**
+     * Sync dependency graph (full or incremental)
+     */
+    syncGraph(changedFiles?: string[]): Promise<SyncResult>;
+    /**
+     * Sync RAG chunks (full or incremental)
+     */
+    syncRag(changedFiles?: string[]): Promise<SyncResult>;
+    /**
+     * Sync all AI infrastructure
+     */
+    syncAll(): Promise<{
+        graph: SyncResult;
+        rag: SyncResult;
+    }>;
+    /**
+     * Check if sync is needed and perform if necessary
+     */
+    syncIfNeeded(): Promise<{
+        synced: boolean;
+        reason?: string;
+        results?: {
+            graph: SyncResult;
+            rag: SyncResult;
+        };
+    }>;
+    /**
+     * Get sync status
+     */
+    getSyncStatus(): ReturnType<TimestampChecker["getSyncStatus"]>;
+}

package/.agent/mcp-gateway/dist/sync/incremental_syncer.js

@@ -0,0 +1,172 @@
+/**
+ * Incremental Syncer
+ *
+ * Updates only the changed files in the AI infrastructure
+ * instead of regenerating everything from scratch.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { spawn } from "child_process";
+import { TimestampChecker } from "./timestamp_checker.js";
+export class IncrementalSyncer {
+    projectRoot;
+    kitPath;
+    timestampChecker;
+    constructor(projectRoot, kitPath) {
+        this.projectRoot = projectRoot;
+        this.kitPath = kitPath || this.detectKitPath();
+        this.timestampChecker = new TimestampChecker(projectRoot);
+    }
+    /**
+     * Detect Agent Kit installation path
+     */
+    detectKitPath() {
+        // Check environment variable first
+        if (process.env.AGENT_KIT_PATH) {
+            return process.env.AGENT_KIT_PATH;
+        }
+        // Check relative to this file (when running from kit)
+        const relativePath = path.join(__dirname, "..", "..", "..");
+        if (fs.existsSync(path.join(relativePath, "skills"))) {
+            return relativePath;
+        }
+        // Check in project's .agent directory
+        const projectAgentPath = path.join(this.projectRoot, ".agent");
+        if (fs.existsSync(path.join(projectAgentPath, "skills"))) {
+            return projectAgentPath;
+        }
+        // Fallback to node_modules
+        const nodeModulesPath = path.join(this.projectRoot, "node_modules", "@musashishao", "agent-kit", ".agent");
+        return nodeModulesPath;
+    }
+    /**
+     * Run a Python script and return output
+     */
+    async runPythonScript(scriptPath, args) {
+        return new Promise((resolve) => {
+            if (!fs.existsSync(scriptPath)) {
+                resolve({ success: false, output: `Script not found: ${scriptPath}` });
+                return;
+            }
+            const proc = spawn("python3", [scriptPath, ...args], {
+                cwd: this.projectRoot,
+                env: { ...process.env, PYTHONUNBUFFERED: "1" },
+            });
+            let output = "";
+            let error = "";
+            proc.stdout.on("data", (data) => {
+                output += data.toString();
+            });
+            proc.stderr.on("data", (data) => {
+                error += data.toString();
+            });
+            proc.on("close", (code) => {
+                resolve({
+                    success: code === 0,
+                    output: code === 0 ? output : error || output,
+                });
+            });
+            proc.on("error", (err) => {
+                resolve({ success: false, output: `Failed to run script: ${err.message}` });
+            });
+        });
+    }
+    /**
+     * Sync dependency graph (full or incremental)
+     */
+    async syncGraph(changedFiles) {
+        const startTime = Date.now();
+        const scriptPath = path.join(this.kitPath, "skills", "graph-mapper", "scripts", "generate_graph.py");
+        // Determine source directory
+        let sourceDir = "src";
+        if (fs.existsSync(path.join(this.projectRoot, "app"))) {
+            sourceDir = "app";
+        }
+        const args = [
+            "--src",
+            path.join(this.projectRoot, sourceDir),
+            "--output",
+            path.join(this.projectRoot, ".agent", "graph.json"),
+            "--format",
+            "both",
+        ];
+        const result = await this.runPythonScript(scriptPath, args);
+        if (result.success) {
+            // Update timestamps for synced files
+            if (changedFiles && changedFiles.length > 0) {
+                this.timestampChecker.updateFileTimestamps(changedFiles);
+            }
+            else {
+                this.timestampChecker.markAllSynced(sourceDir);
+            }
+        }
+        return {
+            success: result.success,
+            target: "graph",
+            filesUpdated: changedFiles || [],
+            duration: Date.now() - startTime,
+            error: result.success ? undefined : result.output,
+        };
+    }
+    /**
+     * Sync RAG chunks (full or incremental)
+     */
+    async syncRag(changedFiles) {
+        const startTime = Date.now();
+        const scriptPath = path.join(this.kitPath, "skills", "rag-engineering", "scripts", "chunk_code.py");
+        // Determine source directory
+        let sourceDir = "src";
+        if (fs.existsSync(path.join(this.projectRoot, "app"))) {
+            sourceDir = "app";
+        }
+        const args = [
+            "--src",
+            path.join(this.projectRoot, sourceDir),
+            "--output",
+            path.join(this.projectRoot, ".agent", "rag", "chunks.json"),
+        ];
+        const result = await this.runPythonScript(scriptPath, args);
+        return {
+            success: result.success,
+            target: "rag",
+            filesUpdated: changedFiles || [],
+            duration: Date.now() - startTime,
+            error: result.success ? undefined : result.output,
+        };
+    }
+    /**
+     * Sync all AI infrastructure
+     */
+    async syncAll() {
+        const changedFiles = this.timestampChecker.getChangedFiles();
+        const [graphResult, ragResult] = await Promise.all([
+            this.syncGraph(changedFiles),
+            this.syncRag(changedFiles),
+        ]);
+        return { graph: graphResult, rag: ragResult };
+    }
+    /**
+     * Check if sync is needed and perform if necessary
+     */
+    async syncIfNeeded() {
+        const status = this.timestampChecker.getSyncStatus();
+        if (!status.needsSync) {
+            return {
+                synced: false,
+                reason: "No changes detected since last sync",
+            };
+        }
+        const results = await this.syncAll();
+        return {
+            synced: true,
+            reason: `${status.changedFiles} files changed`,
+            results,
+        };
+    }
+    /**
+     * Get sync status
+     */
+    getSyncStatus() {
+        return this.timestampChecker.getSyncStatus();
+    }
+}

package/.agent/mcp-gateway/dist/sync/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sync Module Exports
+ */
+export { TimestampChecker } from "./timestamp_checker.js";
+export { IncrementalSyncer, type SyncResult } from "./incremental_syncer.js";
+export { Debouncer, getGlobalDebouncer } from "./debouncer.js";

package/.agent/mcp-gateway/dist/sync/index.js

@@ -0,0 +1,6 @@
+/**
+ * Sync Module Exports
+ */
+export { TimestampChecker } from "./timestamp_checker.js";
+export { IncrementalSyncer } from "./incremental_syncer.js";
+export { Debouncer, getGlobalDebouncer } from "./debouncer.js";

package/.agent/mcp-gateway/dist/sync/timestamp_checker.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Timestamp Checker
+ *
+ * Tracks file modification times to detect when source code
+ * has changed since the last sync of AI infrastructure data.
+ */
+export interface TimestampCache {
+    lastSync: number;
+    files: Record<string, number>;
+}
+export declare class TimestampChecker {
+    private cachePath;
+    private cache;
+    private projectRoot;
+    constructor(projectRoot: string);
+    /**
+     * Load timestamp cache from disk
+     */
+    private loadCache;
+    /**
+     * Save timestamp cache to disk
+     */
+    saveCache(): void;
+    /**
+     * Get modification time of a file
+     */
+    private getFileModTime;
+    /**
+     * Check if a specific file has changed since last sync
+     */
+    hasFileChanged(filePath: string): boolean;
+    /**
+     * Check if any source files have changed
+     */
+    hasAnyChanges(sourceDir?: string): boolean;
+    /**
+     * Get list of all changed files since last sync
+     */
+    getChangedFiles(sourceDir?: string): string[];
+    /**
+     * Get all source files in a directory
+     */
+    private getAllSourceFiles;
+    /**
+     * Update timestamp for a file
+     */
+    updateFileTimestamp(filePath: string): void;
+    /**
+     * Update timestamps for multiple files
+     */
+    updateFileTimestamps(files: string[]): void;
+    /**
+     * Mark all current files as synced
+     */
+    markAllSynced(sourceDir?: string): void;
+    /**
+     * Get last sync time
+     */
+    getLastSyncTime(): number;
+    /**
+     * Get human-readable sync status
+     */
+    getSyncStatus(sourceDir?: string): {
+        lastSync: string;
+        totalFiles: number;
+        changedFiles: number;
+        needsSync: boolean;
+    };
+}

package/.agent/mcp-gateway/dist/sync/timestamp_checker.js

@@ -0,0 +1,169 @@
+/**
+ * Timestamp Checker
+ *
+ * Tracks file modification times to detect when source code
+ * has changed since the last sync of AI infrastructure data.
+ */
+import * as fs from "fs";
+import * as path from "path";
+export class TimestampChecker {
+    cachePath;
+    cache;
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.cachePath = path.join(projectRoot, ".agent", ".cache", "timestamps.json");
+        this.cache = this.loadCache();
+    }
+    /**
+     * Load timestamp cache from disk
+     */
+    loadCache() {
+        try {
+            if (fs.existsSync(this.cachePath)) {
+                const data = fs.readFileSync(this.cachePath, "utf-8");
+                return JSON.parse(data);
+            }
+        }
+        catch (error) {
+            console.error("Failed to load timestamp cache:", error);
+        }
+        return { lastSync: 0, files: {} };
+    }
+    /**
+     * Save timestamp cache to disk
+     */
+    saveCache() {
+        try {
+            const cacheDir = path.dirname(this.cachePath);
+            if (!fs.existsSync(cacheDir)) {
+                fs.mkdirSync(cacheDir, { recursive: true });
+            }
+            fs.writeFileSync(this.cachePath, JSON.stringify(this.cache, null, 2));
+        }
+        catch (error) {
+            console.error("Failed to save timestamp cache:", error);
+        }
+    }
+    /**
+     * Get modification time of a file
+     */
+    getFileModTime(filePath) {
+        try {
+            const fullPath = path.resolve(this.projectRoot, filePath);
+            const stats = fs.statSync(fullPath);
+            return stats.mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Check if a specific file has changed since last sync
+     */
+    hasFileChanged(filePath) {
+        const currentMtime = this.getFileModTime(filePath);
+        const cachedMtime = this.cache.files[filePath] || 0;
+        return currentMtime > cachedMtime;
+    }
+    /**
+     * Check if any source files have changed
+     */
+    hasAnyChanges(sourceDir = "src") {
+        const files = this.getAllSourceFiles(sourceDir);
+        for (const file of files) {
+            if (this.hasFileChanged(file)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Get list of all changed files since last sync
+     */
+    getChangedFiles(sourceDir = "src") {
+        const files = this.getAllSourceFiles(sourceDir);
+        return files.filter((file) => this.hasFileChanged(file));
+    }
+    /**
+     * Get all source files in a directory
+     */
+    getAllSourceFiles(dir) {
+        const fullDir = path.resolve(this.projectRoot, dir);
+        if (!fs.existsSync(fullDir)) {
+            return [];
+        }
+        const files = [];
+        const extensions = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".go"]);
+        const excludeDirs = new Set(["node_modules", "__pycache__", ".git", "dist", "build", ".next"]);
+        const walk = (currentDir) => {
+            try {
+                const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path.join(currentDir, entry.name);
+                    const relativePath = path.relative(this.projectRoot, fullPath);
+                    if (entry.isDirectory()) {
+                        if (!excludeDirs.has(entry.name)) {
+                            walk(fullPath);
+                        }
+                    }
+                    else if (entry.isFile()) {
+                        const ext = path.extname(entry.name);
+                        if (extensions.has(ext)) {
+                            files.push(relativePath);
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                // Skip directories we can't read
+            }
+        };
+        walk(fullDir);
+        return files;
+    }
+    /**
+     * Update timestamp for a file
+     */
+    updateFileTimestamp(filePath) {
+        this.cache.files[filePath] = this.getFileModTime(filePath);
+    }
+    /**
+     * Update timestamps for multiple files
+     */
+    updateFileTimestamps(files) {
+        for (const file of files) {
+            this.updateFileTimestamp(file);
+        }
+        this.cache.lastSync = Date.now();
+        this.saveCache();
+    }
+    /**
+     * Mark all current files as synced
+     */
+    markAllSynced(sourceDir = "src") {
+        const files = this.getAllSourceFiles(sourceDir);
+        this.updateFileTimestamps(files);
+    }
+    /**
+     * Get last sync time
+     */
+    getLastSyncTime() {
+        return this.cache.lastSync;
+    }
+    /**
+     * Get human-readable sync status
+     */
+    getSyncStatus(sourceDir = "src") {
+        const allFiles = this.getAllSourceFiles(sourceDir);
+        const changedFiles = this.getChangedFiles(sourceDir);
+        return {
+            lastSync: this.cache.lastSync > 0
+                ? new Date(this.cache.lastSync).toISOString()
+                : "Never",
+            totalFiles: allFiles.length,
+            changedFiles: changedFiles.length,
+            needsSync: changedFiles.length > 0,
+        };
+    }
+}

package/.agent/mcp-gateway/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "@musashishao/agent-kit-mcp",
+    "version": "1.0.0",
+    "description": "MCP Gateway Server for Agent Kit - Live Project Cortex",
+    "type": "module",
+    "main": "dist/index.js",
+    "bin": {
+        "agent-kit-mcp": "./dist/index.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsx src/index.ts",
+        "start": "node dist/index.js",
+        "watch": "tsc --watch"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.0",
+        "zod": "^3.23.0"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "tsx": "^4.0.0",
+        "typescript": "^5.0.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}