n2-soul 4.1.0

package/lib/config.example.js

@@ -0,0 +1,28 @@
+// Soul — Local config example. Copy this to config.local.js and customize.
+// config.local.js is gitignored and will override config.default.js values.
+const path = require('path');
+
+module.exports = {
+    // Language: 'en' or 'ko'
+    LANG: 'en',
+
+    // KV-Cache overrides
+    KV_CACHE: {
+        // Switch to SQLite backend for better performance with many snapshots
+        // backend: 'sqlite',
+
+        // Enable Ollama semantic search (requires: ollama pull nomic-embed-text)
+        // embedding: {
+        //     enabled: true,
+        //     model: 'nomic-embed-text',
+        //     endpoint: 'http://127.0.0.1:11434',
+        // },
+
+        // Enable automatic backups
+        // backup: {
+        //     enabled: true,
+        //     dir: path.resolve(__dirname, '..', 'backups'),
+        //     keepCount: 7,
+        // },
+    },
+};

package/lib/config.js

@@ -0,0 +1,28 @@
+// Soul MCP v4.1 — Config loader. Deep-merges config.default.js with config.local.js overrides.
+const defaults = require('./config.default.js');
+
+let local = {};
+try {
+    local = require('./config.local.js');
+} catch (e) {
+    // config.local.js is optional — only silence MODULE_NOT_FOUND
+    if (e.code !== 'MODULE_NOT_FOUND') throw e;
+}
+
+// Deep merge: local overrides default, nested objects are merged (not replaced)
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        if (
+            override[key] && typeof override[key] === 'object' && !Array.isArray(override[key]) &&
+            base[key] && typeof base[key] === 'object' && !Array.isArray(base[key])
+        ) {
+            result[key] = deepMerge(base[key], override[key]);
+        } else {
+            result[key] = override[key];
+        }
+    }
+    return result;
+}
+
+module.exports = deepMerge(defaults, local);

package/lib/context.js

@@ -0,0 +1,34 @@
+// Soul — Session context manager. Replaces global state anti-pattern.
+const _ctx = {
+    agentName: null,
+    kvChain: {},       // { projectName: parentSessionId }
+};
+
+/** Get current session context */
+function getContext() {
+    return _ctx;
+}
+
+/** Set agent name (called during n2_boot) */
+function setAgentName(name) {
+    _ctx.agentName = name;
+}
+
+/** Get agent name with fallback */
+function getAgentName() {
+    return _ctx.agentName || process.env.N2_AGENT_NAME || 'default';
+}
+
+/** Set KV chain parent (for session linking) */
+function setKvChainParent(project, sessionId) {
+    _ctx.kvChain[project] = sessionId;
+}
+
+/** Get and consume KV chain parent */
+function popKvChainParent(project) {
+    const parent = _ctx.kvChain[project] || null;
+    delete _ctx.kvChain[project];
+    return parent;
+}
+
+module.exports = { getContext, setAgentName, getAgentName, setKvChainParent, popKvChainParent };

package/lib/intercom-log.js

@@ -0,0 +1,187 @@
+// Soul — Centralized conversation log writer for inter-agent communication.
+const fs = require('fs');
+const path = require('path');
+const { detectAgentsDir } = require('./agent-registry');
+const { writeJson, readJson, nowISO, logError } = require('./utils');
+
+// ── Agent name whitelist (lazy-loaded from agent configs) ──
+
+let _validNames = null;
+
+/**
+ * Load valid agent names from agent config files.
+ * Only these names (+ defaults) can have conversation folders.
+ * @returns {Set<string>}
+ */
+function getValidAgentNames() {
+    if (_validNames) return _validNames;
+    _validNames = new Set(['master', 'owner']);
+    try {
+        const agentsDir = detectAgentsDir();
+        if (agentsDir && fs.existsSync(agentsDir)) {
+            const files = fs.readdirSync(agentsDir)
+                .filter(f => f.endsWith('.json') && f !== 'global.json');
+            for (const f of files) {
+                try {
+                    const cfg = JSON.parse(fs.readFileSync(path.join(agentsDir, f), 'utf-8'));
+                    if (cfg.name && cfg.enabled !== false) _validNames.add(cfg.name);
+                } catch (e) { logError('intercom:parse-config', `${f}: ${e.message}`); }
+            }
+        }
+    } catch (e) { logError('intercom:agents-dir', e); }
+    return _validNames;
+}
+
+/**
+ * Normalize a sender/caller name to a valid agent name.
+ * Falls back to 'master' if the name is not in the whitelist.
+ * @param {string} name
+ * @returns {string}
+ */
+function normalizeName(name) {
+    if (!name || typeof name !== 'string') return 'master';
+    const valid = getValidAgentNames();
+    if (valid.has(name)) return name;
+    for (const v of valid) {
+        if (v.toLowerCase() === name.toLowerCase()) return v;
+    }
+    return 'master';
+}
+
+// ── Path helpers ──
+
+function getConversationsDir(config) {
+    const dataDir = config?.dataDir || path.join(__dirname, '..', 'data');
+    return path.join(dataDir, 'conversations');
+}
+
+function getAgentLogDir(config, agentName, date) {
+    const [y, m, d] = (date || nowISO().split('T')[0]).split('-');
+    return path.join(getConversationsDir(config), agentName, y, m, d);
+}
+
+/**
+ * Get next sequential log ID (max existing + 1).
+ * @param {string} dir
+ * @returns {string} Zero-padded 3-digit ID (e.g. '001')
+ */
+function getNextLogId(dir) {
+    if (!fs.existsSync(dir)) return '001';
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+    const nums = files.map(f => parseInt(f.split('.')[0]) || 0);
+    const max = nums.length > 0 ? Math.max(...nums) : 0;
+    return String(max + 1).padStart(3, '0');
+}
+
+// ── Core write function ──
+
+/**
+ * Write a conversation log entry for both caller and target.
+ * Enforces folder isolation: only registered agent names can create directories.
+ *
+ * @param {object|null} config - Soul config (for dataDir)
+ * @param {string} caller - Sender name (will be normalized)
+ * @param {string|{name:string}} target - Target agent name or config object
+ * @param {string} message - User message
+ * @param {{content:string, usage?:object}} response - LLM response
+ * @param {{provider:string, model:string}} meta - Provider metadata
+ * @returns {{callerLog:string, targetLog:string}|null}
+ */
+function writeConversationLog(config, caller, target, message, response, meta) {
+    const safeCaller = normalizeName(caller);
+    const targetName = typeof target === 'object' ? (target.name || String(target)) : String(target);
+    const safeTarget = normalizeName(targetName);
+
+    const date = nowISO().split('T')[0];
+    const entry = {
+        timestamp: nowISO(),
+        type: 'call',
+        caller: safeCaller,
+        target: safeTarget,
+        provider: meta?.provider || 'unknown',
+        model: meta?.model || 'unknown',
+        message: typeof message === 'string' ? message : '',
+        response: response?.content || '',
+        usage: response?.usage || null,
+    };
+
+    const callerDir = getAgentLogDir(config, safeCaller, date);
+    const callerId = getNextLogId(callerDir);
+    writeJson(path.join(callerDir, `${callerId}.json`), entry);
+
+    const targetDir = getAgentLogDir(config, safeTarget, date);
+    const targetId = getNextLogId(targetDir);
+    writeJson(path.join(targetDir, `${targetId}.json`), { ...entry, type: 'called' });
+
+    // Signal file for live detection (best-effort)
+    try {
+        const signalPath = path.join(getConversationsDir(config), '..', 'intercom-signal.json');
+        const tmpPath = signalPath + '.tmp';
+        fs.writeFileSync(tmpPath, JSON.stringify(entry, null, 2), 'utf-8');
+        fs.renameSync(tmpPath, signalPath);
+    } catch (e) { logError('intercom:signal', e); }
+
+    return { callerLog: `${safeCaller}/${callerId}`, targetLog: `${safeTarget}/${targetId}` };
+}
+
+// ── Read functions ──
+
+/**
+ * Read conversation logs for an agent on a specific date.
+ * @param {object|null} config
+ * @param {string} agentName
+ * @param {string} date - YYYY-MM-DD
+ * @param {number} lastN - Max entries to return
+ * @returns {object[]}
+ */
+function readConversationLogs(config, agentName, date, lastN) {
+    const dir = getAgentLogDir(config, agentName, date);
+    if (!fs.existsSync(dir)) return [];
+    const files = fs.readdirSync(dir)
+        .filter(f => f.endsWith('.json'))
+        .sort()
+        .slice(-(lastN || 50));
+    return files.map(f => readJson(path.join(dir, f))).filter(Boolean);
+}
+
+/**
+ * Get recent conversation dates for an agent.
+ * @param {object|null} config
+ * @param {string} agentName
+ * @param {number} limit
+ * @returns {string[]}
+ */
+function getConversationDates(config, agentName, limit) {
+    const baseDir = path.join(getConversationsDir(config), agentName);
+    if (!fs.existsSync(baseDir)) return [];
+    const dates = [];
+    try {
+        const years = fs.readdirSync(baseDir).filter(f => /^\d{4}$/.test(f)).sort().reverse();
+        for (const y of years) {
+            const months = fs.readdirSync(path.join(baseDir, y)).filter(f => /^\d{2}$/.test(f)).sort().reverse();
+            for (const m of months) {
+                const days = fs.readdirSync(path.join(baseDir, y, m)).filter(f => /^\d{2}$/.test(f)).sort().reverse();
+                for (const d of days) {
+                    dates.push(`${y}-${m}-${d}`);
+                    if (dates.length >= (limit || 7)) return dates;
+                }
+            }
+        }
+    } catch (e) { logError('intercom:dates', e); }
+    return dates;
+}
+
+/** Invalidate cached agent names (call after agent config changes) */
+function resetNameCache() {
+    _validNames = null;
+}
+
+module.exports = {
+    writeConversationLog,
+    readConversationLogs,
+    getConversationDates,
+    getNextLogId,
+    normalizeName,
+    getValidAgentNames,
+    resetNameCache,
+};

package/lib/kv-cache/agent-adapter.js

@@ -0,0 +1,192 @@
+// Soul KV-Cache — Agent adapter. Converts browser/MCP sessions to unified KV schema.
+const { createSession } = require('./schema');
+
+/**
+ * Converts CheckpointManager's CheckpointData to KV-Cache session schema.
+ * Source: src/core/executor/checkpoint-resumption.ts
+ *
+ * @param {object} checkpoint - CheckpointData from CheckpointManager
+ * @param {string} projectName
+ * @returns {object} Normalized session
+ */
+function fromCheckpoint(checkpoint, projectName = 'default') {
+    const actions = (checkpoint.recentActions || []);
+    const decisions = actions
+        .filter(a => a.success)
+        .map(a => `Turn ${a.turn}: ${a.summary}`);
+
+    return createSession({
+        id: checkpoint.id,
+        agentName: 'browser-executor',
+        agentType: 'browser',
+        startedAt: new Date(checkpoint.timestamp).toISOString(),
+        turnCount: checkpoint.turnNumber || 0,
+        keys: extractKeywords(checkpoint.progressSummary || ''),
+        context: {
+            summary: checkpoint.progressSummary || '',
+            decisions,
+            filesChanged: [],
+            todo: checkpoint.remainingGoals || [],
+        },
+        projectName,
+    });
+}
+
+/**
+ * Converts MemoryBridge MemoryNode array to KV-Cache entries.
+ * Source: src/core/executor/memory-bridge.ts
+ *
+ * @param {object[]} nodes - MemoryNode array
+ * @param {string} owner - Agent name
+ * @param {string} projectName
+ * @returns {object} Normalized session
+ */
+function fromMemoryBridge(nodes, owner = 'browser', projectName = 'default') {
+    const allTags = [];
+    const summaries = [];
+
+    for (const node of nodes) {
+        if (node.tags) allTags.push(...node.tags);
+        if (node.content) {
+            summaries.push(node.content.slice(0, 200));
+        }
+    }
+
+    const keySet = new Set(allTags);
+
+    return createSession({
+        agentName: owner,
+        agentType: 'browser',
+        keys: Array.from(keySet),
+        context: {
+            summary: summaries.join('\n---\n'),
+            decisions: [],
+            filesChanged: [],
+            todo: [],
+        },
+        projectName,
+    });
+}
+
+/**
+ * Converts MCP n2_work_end session data to KV-Cache schema.
+ * Source: soul/sequences/end.js
+ *
+ * @param {object} workEndData - Data from n2_work_end call
+ * @returns {object} Normalized session
+ */
+function fromMcpSession(workEndData) {
+    const d = workEndData || {};
+    const filesChanged = [
+        ...(d.filesCreated || []).map(f => f.path || f),
+        ...(d.filesModified || []).map(f => f.path || f),
+        ...(d.filesDeleted || []).map(f => f.path || f),
+    ];
+
+    return createSession({
+        agentName: d.agent || 'unknown',
+        agentType: 'mcp',
+        startedAt: d.startedAt,
+        keys: extractKeywords(d.summary || ''),
+        context: {
+            summary: d.summary || '',
+            decisions: d.decisions || [],
+            filesChanged,
+            todo: d.todo || [],
+        },
+        parentSessionId: d.parentSessionId || null,
+        projectName: d.project || 'default',
+    });
+}
+
+/**
+ * Generates a resume prompt from a snapshot within a token budget.
+ * Model-agnostic: produces plain text usable by any LLM.
+ *
+ * @param {object} snapshot - KV-Cache session object
+ * @param {number} budgetTokens - Max tokens (estimated)
+ * @returns {string} Resume prompt text
+ */
+function toResumePrompt(snapshot, budgetTokens = 2000) {
+    if (!snapshot) return '';
+
+    const lines = [];
+    lines.push(`[Previous Session: ${snapshot.agentName} | ${snapshot.startedAt}]`);
+
+    if (snapshot.keys.length > 0) {
+        lines.push(`Topics: ${snapshot.keys.join(', ')}`);
+    }
+
+    if (snapshot.context.summary) {
+        lines.push(`Summary: ${snapshot.context.summary}`);
+    }
+
+    if (snapshot.context.decisions.length > 0) {
+        lines.push(`Decisions:`);
+        for (const d of snapshot.context.decisions) {
+            lines.push(`  - ${d}`);
+        }
+    }
+
+    if (snapshot.context.todo.length > 0) {
+        lines.push(`TODO:`);
+        for (const t of snapshot.context.todo) {
+            lines.push(`  - ${t}`);
+        }
+    }
+
+    let result = lines.join('\n');
+
+    // Rough trim to token budget (chars/3 as conservative estimate)
+    const maxChars = budgetTokens * 3;
+    if (result.length > maxChars) {
+        result = result.slice(0, maxChars) + '\n...(truncated)';
+    }
+
+    return result;
+}
+
+/**
+ * Simple keyword extraction from text.
+ * No LLM needed: uses frequency-based extraction.
+ *
+ * @param {string} text
+ * @param {number} maxKeywords
+ * @returns {string[]}
+ */
+function extractKeywords(text, maxKeywords = 10) {
+    if (!text) return [];
+
+    // Common stop words (English + Korean particles)
+    const stopWords = new Set([
+        'the', 'a', 'an', 'is', 'are', 'was', 'were', 'in', 'on', 'at',
+        'to', 'for', 'of', 'with', 'by', 'from', 'and', 'or', 'not',
+        'this', 'that', 'it', 'as', 'be', 'has', 'have', 'had', 'do',
+        'does', 'did', 'will', 'would', 'could', 'should', 'may', 'can',
+    ]);
+
+    const words = text
+        .toLowerCase()
+        .replace(/[^a-z0-9가-힣\s-]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length >= 3 && !stopWords.has(w));
+
+    // Frequency count
+    const freq = {};
+    for (const w of words) {
+        freq[w] = (freq[w] || 0) + 1;
+    }
+
+    return Object.entries(freq)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, maxKeywords)
+        .map(([word]) => word);
+}
+
+module.exports = {
+    fromCheckpoint,
+    fromMemoryBridge,
+    fromMcpSession,
+    toResumePrompt,
+    extractKeywords,
+};