n2-soul 4.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "n2-soul",
+    "version": "4.1.0",
+    "description": "Multi-agent session orchestrator with KV-Cache for MCP (Model Context Protocol)",
+    "main": "index.js",
+    "scripts": {
+        "start": "node index.js"
+    },
+    "keywords": [
+        "mcp", "multi-agent", "kv-cache", "session", "orchestrator",
+        "ai-agent", "model-context-protocol", "soul", "n2", "persistent-memory"
+    ],
+    "license": "Apache-2.0",
+    "homepage": "https://nton2.com",
+    "author": "N2 <lagi0730@gmail.com>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/choihyunsus/soul.git"
+    },
+    "bugs": {
+        "url": "https://github.com/choihyunsus/soul/issues"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "~1.6.1",
+        "zod": "~3.24.1",
+        "sql.js": "~1.11.0"
+    }
+}

package/sequences/boot.js

@@ -0,0 +1,81 @@
+// Soul MCP v4.1 — Boot sequence. Handoff + KV-Cache restore.
+const path = require('path');
+const fs = require('fs');
+const { readJson, today, nowISO, logError } = require('../lib/utils');
+const { detectAgentsDir, listAgents } = require('../lib/agent-registry');
+const { SoulEngine } = require('../lib/soul-engine');
+const { setAgentName, setKvChainParent } = require('../lib/context');
+
+function registerBootSequence(server, z, config) {
+    const engine = new SoulEngine(config.DATA_DIR);
+
+    server.registerTool(
+        'n2_boot',
+        {
+            title: 'Soul Boot',
+            description: 'Boot sequence — loads soul-board handoff, agent list, and KV-Cache context.',
+            inputSchema: {
+                agent: z.string().describe('Agent name'),
+                project: z.string().optional().describe('Project name to load context for'),
+            },
+        },
+        async ({ agent, project }) => {
+            const lines = [];
+
+            // -- Agent resolution --
+            const agentsDir = config.AGENTS_DIR || detectAgentsDir();
+            const agents = listAgents(agentsDir);
+            const agentName = agent || process.env.N2_AGENT_NAME || 'default';
+            setAgentName(agentName);
+
+            lines.push(`--- Soul Boot | ${agentName} | ${today()} ---`);
+            if (agents.length > 0) {
+                lines.push(`Agents: ${agents.map(a => `${a.name}[${a.model}]`).join(', ')}`);
+            }
+
+            // -- Soul Board: handoff + TODO --
+            if (project) {
+                const board = engine.readBoard(project);
+                lines.push(`\n--- ${project} | v${board.state.version || '?'} | ${board.state.health || '?'} ---`);
+
+                if (board.handoff && board.handoff.summary) {
+                    lines.push(`Handoff(${board.handoff.from}): ${board.handoff.summary}`);
+                    if (board.handoff.todo && board.handoff.todo.length > 0) {
+                        lines.push(`TODO: ${board.handoff.todo.join(' | ')}`);
+                    }
+                }
+
+                const activeEntries = Object.entries(board.activeWork).filter(([_, v]) => v);
+                if (activeEntries.length > 0) {
+                    lines.push(`Active: ${activeEntries.map(([n, i]) => `${n}:${i.task}`).join(', ')}`);
+                }
+
+                if (board.decisions && board.decisions.length > 0) {
+                    const recent = board.decisions.slice(-3);
+                    lines.push(`Decisions: ${recent.map(d => `[${d.date}] ${d.what}`).join(' | ')}`);
+                }
+            }
+
+            // -- KV-Cache auto-load --
+            if (project && config.KV_CACHE?.enabled && config.KV_CACHE?.autoLoadOnBoot) {
+                try {
+                    const { SoulKVCache } = require('../lib/kv-cache');
+                    const kvCache = new SoulKVCache(config.DATA_DIR, config.KV_CACHE);
+                    const snap = kvCache.load(project);
+                    if (snap) {
+                        setKvChainParent(project, snap.id);
+                        const level = snap._level || 'auto';
+                        const tokens = snap._promptTokens || '?';
+                        lines.push(`\nKV-Cache: ${level} | ~${tokens}t | ${snap.id.slice(0, 8)}`);
+                        if (snap._resumePrompt) lines.push(snap._resumePrompt);
+                    }
+                } catch (e) { logError('boot:kv-cache', e); }
+            }
+
+            lines.push(`\n--- Soul Boot complete ---`);
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+    );
+}
+
+module.exports = { registerBootSequence };

package/sequences/end.js

@@ -0,0 +1,132 @@
+// Soul MCP v4.1 — End sequence. Ledger + board handoff + KV-Cache snapshot.
+const path = require('path');
+const { nowISO, logError } = require('../lib/utils');
+const { SoulEngine } = require('../lib/soul-engine');
+const { popKvChainParent } = require('../lib/context');
+const { activeSessions } = require('./work');
+
+function registerEndSequence(server, z, config) {
+    const engine = new SoulEngine(config.DATA_DIR);
+
+    server.registerTool(
+        'n2_work_end',
+        {
+            title: 'Soul Work End',
+            description: 'End work sequence. Writes immutable ledger entry, updates soul-board handoff, releases file ownership.',
+            inputSchema: {
+                agent: z.string().describe('Agent name'),
+                project: z.string().describe('Project name'),
+                title: z.string().describe('Work title'),
+                summary: z.string().describe('Work summary'),
+                todo: z.array(z.string()).optional().describe('Next TODO items'),
+                decisions: z.array(z.string()).optional().describe('Key decisions made'),
+            },
+        },
+        async ({ agent, project, title, summary, todo, decisions }) => {
+            const session = activeSessions[project] || {};
+            const allDecisions = [...(session.decisions || []), ...(decisions || [])];
+
+            // 1. Write immutable ledger entry
+            let ledgerResult;
+            try {
+                ledgerResult = engine.writeLedger(project, agent, {
+                    startedAt: session.startedAt,
+                    title,
+                    summary,
+                    filesCreated: session.filesCreated || [],
+                    filesModified: session.filesModified || [],
+                    filesDeleted: session.filesDeleted || [],
+                    decisions: allDecisions,
+                });
+            } catch (e) {
+                logError('end:ledger', e);
+                return { content: [{ type: 'text', text: `❌ Ledger write failed: ${e.message}` }] };
+            }
+
+            // 2. Update soul-board handoff
+            try {
+                const board = engine.readBoard(project);
+                board.handoff = {
+                    from: agent,
+                    summary,
+                    todo: todo || [],
+                    blockers: [],
+                };
+
+                const dateStr = nowISO().split('T')[0].slice(5);
+                for (const d of allDecisions) {
+                    board.decisions.push({ date: dateStr, by: agent, what: d, why: '' });
+                }
+                if (board.decisions.length > 20) {
+                    board.decisions = board.decisions.slice(-20);
+                }
+
+                board.updatedBy = agent;
+                engine.writeBoard(project, board);
+            } catch (e) {
+                logError('end:board', e);
+            }
+
+            // 3. Release file ownership
+            engine.releaseFiles(project, agent);
+
+            // 4. Clear active work
+            engine.clearActiveWork(project, agent);
+
+            // 5. Auto-update file-index tree
+            try {
+                const projectRoot = path.resolve(config.SOUL_ROOT, '..');
+                const tree = engine.scanDirectory(projectRoot, {
+                    maxDepth: config.SEARCH?.maxDepth || 4,
+                });
+                engine.writeFileIndex(project, { updatedAt: nowISO(), tree });
+            } catch (e) {
+                logError('end:file-index', e);
+            }
+
+            // 6. Clear in-memory session
+            delete activeSessions[project];
+
+            // 7. Auto-save KV-Cache snapshot (with session chaining)
+            if (config.KV_CACHE?.enabled && config.KV_CACHE?.autoSaveOnWorkEnd) {
+                try {
+                    const { SoulKVCache } = require('../lib/kv-cache');
+                    const kvCache = new SoulKVCache(config.DATA_DIR, config.KV_CACHE);
+                    const parentId = popKvChainParent(project);
+                    kvCache.save(agent, project, {
+                        summary,
+                        decisions: allDecisions,
+                        todo: todo || [],
+                        filesCreated: session.filesCreated || [],
+                        filesModified: session.filesModified || [],
+                        filesDeleted: session.filesDeleted || [],
+                        startedAt: session.startedAt,
+                        parentSessionId: parentId,
+                    });
+                } catch (e) {
+                    logError('end:kv-cache', e);
+                }
+            }
+
+            const totalFiles = (session.filesCreated || []).length +
+                (session.filesModified || []).length +
+                (session.filesDeleted || []).length;
+
+            return {
+                content: [{
+                    type: 'text',
+                    text: [
+                        `Work ${ledgerResult.id} completed: ${title}`,
+                        `Agent: ${agent}`,
+                        `Files: ${totalFiles} changes`,
+                        `Decisions: ${allDecisions.length}`,
+                        `Ledger: ${ledgerResult.path}`,
+                        `Handoff TODO: ${(todo || []).join(' | ') || 'none'}`,
+                    ].join('\n'),
+                }],
+            };
+        }
+    );
+}
+
+module.exports = { registerEndSequence };

package/sequences/work.js

@@ -0,0 +1,257 @@
+// Soul MCP v4.1 — Work sequence. Real-time change tracking, file ownership, context search.
+const fs = require('fs');
+const path = require('path');
+const { nowISO, readJson, readFile, validateFirstLineComment, logError } = require('../lib/utils');
+const { SoulEngine } = require('../lib/soul-engine');
+
+// In-memory work session state per project
+const activeSessions = {};
+
+// ── Helper: recursively walk files in a directory ──
+function walkFiles(dir, callback, maxDepth, depth = 0) {
+    if (depth > maxDepth) return;
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walkFiles(fullPath, callback, maxDepth, depth + 1);
+            } else {
+                callback(fullPath);
+            }
+        }
+    } catch (e) {
+        logError("walkFiles", `${dir}: ${e.message}`);
+    }
+}
+
+function registerWorkSequence(server, z, config) {
+    const engine = new SoulEngine(config.DATA_DIR);
+
+    // Start a work sequence
+    server.registerTool(
+        'n2_work_start',
+        {
+            title: 'N2 Work Start',
+            description: 'Start a work sequence. Registers agent in activeWork on soul-board.',
+            inputSchema: {
+                agent: z.string().describe('Agent name'),
+                project: z.string().describe('Project name'),
+                task: z.string().describe('Task description'),
+            },
+        },
+        async ({ agent, project, task }) => {
+            engine.setActiveWork(project, agent, task, []);
+            activeSessions[project] = {
+                agent,
+                task,
+                startedAt: nowISO(),
+                filesCreated: [],
+                filesModified: [],
+                filesDeleted: [],
+                decisions: [],
+            };
+            return { content: [{ type: 'text', text: `Work started: ${agent} on ${project} — ${task}` }] };
+        }
+    );
+
+    // Claim file ownership before editing
+    server.registerTool(
+        'n2_work_claim',
+        {
+            title: 'N2 Work Claim',
+            description: 'Claim file ownership before modifying. Prevents collision with other agents.',
+            inputSchema: {
+                project: z.string().describe('Project name'),
+                agent: z.string().describe('Agent name'),
+                filePath: z.string().describe('File path relative to project root'),
+                intent: z.string().describe('Why you are modifying this file'),
+            },
+        },
+        async ({ project, agent, filePath, intent }) => {
+            const result = engine.claimFile(project, filePath, agent, intent);
+            if (!result.ok) {
+                return { content: [{ type: 'text', text: `COLLISION: ${filePath} is owned by ${result.owner} (${result.intent}). Choose a different file.` }] };
+            }
+            return { content: [{ type: 'text', text: `Claimed: ${filePath} -> ${agent} (${intent})` }] };
+        }
+    );
+
+    // Log file changes during work
+    server.registerTool(
+        'n2_work_log',
+        {
+            title: 'N2 Work Log',
+            description: 'Log file changes during work. Reports created/modified/deleted files with descriptions.',
+            inputSchema: {
+                project: z.string().describe('Project name'),
+                filesCreated: z.array(z.object({
+                    path: z.string(),
+                    desc: z.string(),
+                })).optional().describe('Files created'),
+                filesModified: z.array(z.object({
+                    path: z.string(),
+                    desc: z.string(),
+                })).optional().describe('Files modified'),
+                filesDeleted: z.array(z.object({
+                    path: z.string(),
+                    desc: z.string(),
+                })).optional().describe('Files deleted'),
+                decisions: z.array(z.string()).optional().describe('Decisions made'),
+            },
+        },
+        async ({ project, filesCreated, filesModified, filesDeleted, decisions }) => {
+            const session = activeSessions[project];
+            if (!session) {
+                return { content: [{ type: 'text', text: 'ERROR: No active work session. Call n2_work_start first.' }] };
+            }
+
+            if (filesCreated) session.filesCreated.push(...filesCreated);
+            if (filesModified) session.filesModified.push(...filesModified);
+            if (filesDeleted) session.filesDeleted.push(...filesDeleted);
+            if (decisions) session.decisions.push(...decisions);
+
+            // Validate first-line comments on created files
+            const warnings = [];
+            for (const f of (filesCreated || [])) {
+                try {
+                    const fullPath = path.resolve(f.path);
+                    if (!validateFirstLineComment(fullPath)) {
+                        warnings.push(`MISSING first-line comment: ${f.path}`);
+                    }
+                } catch (e) { logError("work:validate", e); }
+            }
+
+            const total = (session.filesCreated.length + session.filesModified.length + session.filesDeleted.length);
+            let msg = `Logged: ${total} file changes, ${session.decisions.length} decisions.`;
+            if (warnings.length > 0) {
+                msg += `\nWARNINGS:\n  ${warnings.join('\n  ')}`;
+            }
+            if ((filesCreated && filesCreated.length > 0) || (filesDeleted && filesDeleted.length > 0)) {
+                msg += `\nFile tree will auto-update at n2_work_end. Use n2_project_scan for immediate refresh.`;
+            }
+            msg += `\nTODO RULE: All TODO files go in _data/ ONLY. Always mark completed items as [x]. Never use brain memory for TODOs.`;
+            return { content: [{ type: 'text', text: msg }] };
+        }
+    );
+
+    // ── n2_context_search: Search across Brain memory and Ledger entries ──
+    server.registerTool(
+        'n2_context_search',
+        {
+            title: 'N2 Context Search',
+            description: 'Search across Brain memory and Ledger entries for relevant past context. Uses keyword matching with recency weighting. Great for finding related past work or decisions.',
+            inputSchema: {
+                query: z.string().describe('Search query (keywords, space-separated)'),
+                sources: z.array(z.string()).optional().describe('Sources to search: "brain", "ledger". Default: all.'),
+                maxResults: z.number().optional().describe('Max results (default: 10)'),
+            },
+        },
+        async ({ query, sources, maxResults }) => {
+            try {
+                const dataDir = config.DATA_DIR;
+                const searchCfg = config.SEARCH || {};
+                const minKwLen = searchCfg.minKeywordLength || 2;
+                const previewLen = searchCfg.previewLength || 200;
+                const recencyBonus = searchCfg.recencyBonus || 10;
+                const maxDepth = searchCfg.maxDepth || 6;
+                const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length >= minKwLen);
+                const max = maxResults || searchCfg.defaultMaxResults || 10;
+                const searchSources = sources || ['brain', 'ledger'];
+                const results = [];
+
+                function scoreText(text, filePath, source, meta = {}) {
+                    if (!text) return;
+                    const lower = text.toLowerCase();
+                    let score = 0;
+                    const matchedKeywords = [];
+                    for (const kw of keywords) {
+                        const escaped = kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                        const count = (lower.match(new RegExp(escaped, 'g')) || []).length;
+                        if (count > 0) { score += count; matchedKeywords.push(kw); }
+                    }
+                    if (score > 0) {
+                        if (meta.timestamp) {
+                            const age = (Date.now() - new Date(meta.timestamp).getTime()) / (1000 * 60 * 60 * 24);
+                            score += Math.max(0, recencyBonus - age);
+                        }
+                        results.push({
+                            source, path: filePath,
+                            score: Math.round(score * 100) / 100,
+                            matchedKeywords,
+                            preview: text.slice(0, previewLen).replace(/\n/g, ' '),
+                            ...meta,
+                        });
+                    }
+                }
+
+                // Search Brain memory
+                if (searchSources.includes('brain')) {
+                    const memoryDir = path.join(dataDir, 'memory');
+                    if (fs.existsSync(memoryDir)) {
+                        walkFiles(memoryDir, (fp) => {
+                            const content = readFile(fp);
+                            if (content) {
+                                const relPath = path.relative(memoryDir, fp);
+                                scoreText(content, `memory/${relPath}`, 'brain', {
+                                    timestamp: fs.statSync(fp).mtime.toISOString(),
+                                });
+                            }
+                        }, maxDepth);
+                    }
+                }
+
+                // Search Ledger entries
+                if (searchSources.includes('ledger')) {
+                    const projectsDir = path.join(dataDir, 'projects');
+                    if (fs.existsSync(projectsDir)) {
+                        for (const proj of fs.readdirSync(projectsDir)) {
+                            const ledgerBase = path.join(projectsDir, proj, 'ledger');
+                            if (!fs.existsSync(ledgerBase)) continue;
+                            walkFiles(ledgerBase, (fp) => {
+                                if (!fp.endsWith('.json')) return;
+                                const data = readJson(fp);
+                                if (!data) return;
+                                const text = [data.title, data.summary, ...(data.decisions || [])].filter(Boolean).join(' ');
+                                const relPath = path.relative(projectsDir, fp);
+                                scoreText(text, `projects/${relPath}`, 'ledger', {
+                                    timestamp: data.completedAt || data.startedAt,
+                                    agent: data.agent,
+                                    title: data.title,
+                                });
+                            }, maxDepth);
+                        }
+                    }
+                }
+
+                results.sort((a, b) => b.score - a.score);
+                const top = results.slice(0, max);
+
+                if (top.length === 0) {
+                    return { content: [{ type: 'text', text: `🔍 No results for "${query}".` }] };
+                }
+
+                const lines = top.map((r, i) => {
+                    const icon = r.source === 'brain' ? '🧠' : '📖';
+                    const meta = [
+                        r.title ? `"${r.title}"` : '',
+                        r.agent ? `by ${r.agent}` : '',
+                        `score: ${r.score}`,
+                    ].filter(Boolean).join(' | ');
+                    return `${i + 1}. ${icon} ${r.path}\n   ${meta}\n   Keywords: [${r.matchedKeywords.join(', ')}]\n   ${r.preview}`;
+                });
+
+                return {
+                    content: [{
+                        type: 'text', text:
+                            `🔍 Context search: "${query}" (${top.length} results)\n\n${lines.join('\n\n')}`
+                    }],
+                };
+            } catch (err) {
+                return { content: [{ type: 'text', text: `❌ Search error: ${err.message}` }] };
+            }
+        }
+    );
+}
+
+// Export activeSessions for end.js to access
+module.exports = { registerWorkSequence, activeSessions };

package/tools/brain.js

@@ -0,0 +1,45 @@
+// Soul MCP v4.0 — Brain tools. Shared memory read/write with path traversal protection.
+const path = require('path');
+const { readFile, writeFile, safePath } = require('../lib/utils');
+
+function registerBrainTools(server, z, config) {
+    const memoryDir = path.join(config.DATA_DIR, 'memory');
+
+    server.registerTool(
+        'n2_brain_read',
+        {
+            title: 'N2 Brain Read',
+            description: 'Read a file from shared memory (data/memory/). Agents share information here.',
+            inputSchema: {
+                filename: z.string().describe('File path relative to memory directory'),
+            },
+        },
+        async ({ filename }) => {
+            const filePath = safePath(filename, memoryDir);
+            if (!filePath) return { content: [{ type: 'text', text: `BLOCKED: Path traversal denied — "${filename}"` }] };
+            const content = readFile(filePath);
+            if (!content) return { content: [{ type: 'text', text: `NOT FOUND: ${filePath}` }] };
+            return { content: [{ type: 'text', text: content }] };
+        }
+    );
+
+    server.registerTool(
+        'n2_brain_write',
+        {
+            title: 'N2 Brain Write',
+            description: 'Write a file to shared memory (data/memory/). Share information between agents.',
+            inputSchema: {
+                filename: z.string().describe('File path relative to memory directory'),
+                content: z.string().describe('File content'),
+            },
+        },
+        async ({ filename, content }) => {
+            const filePath = safePath(filename, memoryDir);
+            if (!filePath) return { content: [{ type: 'text', text: `BLOCKED: Path traversal denied — "${filename}"` }] };
+            writeFile(filePath, content);
+            return { content: [{ type: 'text', text: `Saved: memory/${filename} (${content.length} chars)` }] };
+        }
+    );
+}
+
+module.exports = { registerBrainTools };