aiden-runtime 3.18.0 → 3.19.4

package/dist/core/toolRegistry.js

@@ -40,13 +40,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOOL_NAMES_ONLY = exports.TOOL_DESCRIPTIONS = exports.TOOLS = void 0;
+exports.registryMcpDestructiveList = exports.registryMcpSafeList = exports.registrySequentialOnlySet = exports.registryParallelSafeSet = exports.registryNoRetrySet = exports.registryValidTools = exports.registryAllowedTools = exports.registryTimeouts = exports.registryCategories = exports.registryTiers = exports.registryDescriptions = exports.registryNames = exports.TOOL_REGISTRY = exports.TOOL_NAMES_ONLY = exports.TOOL_DESCRIPTIONS = exports.TOOLS = exports.APP_ALIASES = void 0;
+exports.isCommandDenied = isCommandDenied;
+exports.scanCodeForDestructivePaths = scanCodeForDestructivePaths;
+exports.isCommandAllowed = isCommandAllowed;
 exports.getActiveBrowserPage = getActiveBrowserPage;
 exports.setProgressEmitter = setProgressEmitter;
+exports.resolveWritePath = resolveWritePath;
+exports.resolveLaunchCommand = resolveLaunchCommand;
 exports.registerExternalTool = registerExternalTool;
 exports.getExternalToolsMeta = getExternalToolsMeta;
+exports.isKnownTool = isKnownTool;
 exports.executeTool = executeTool;
 exports.getToolTier = getToolTier;
+exports.bumpGeneration = bumpGeneration;
+exports.getGeneration = getGeneration;
 exports.detectToolCategories = detectToolCategories;
 exports.getToolsForCategories = getToolsForCategories;
 // core/toolRegistry.ts — Centralized tool registry with real Playwright
@@ -55,6 +63,7 @@ const child_process_1 = require("child_process");
 const util_1 = require("util");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
 const paths_1 = require("./paths");
 const computerControl_1 = require("./computerControl");
 const webSearch_1 = require("./webSearch");
@@ -71,6 +80,7 @@ const permissionSystem_1 = require("./permissionSystem");
 const youtubeTranscript_1 = require("./youtubeTranscript");
 const knowledgeBase_1 = require("./knowledgeBase");
 const calendarTool_1 = require("./tools/calendarTool");
+const nowPlaying_1 = require("./tools/nowPlaying");
 const gmailTool_1 = require("./tools/gmailTool");
 const index_1 = require("../providers/index");
 const playwrightBridge_1 = require("./playwrightBridge");
@@ -134,6 +144,13 @@ const DENIED_COMMANDS = [
     /\bnet\s+user\b/i,
     /Set-ExecutionPolicy/i,
     /\bNew-Service\b/i,
+    // ── C7: path-scoped deny — Remove-Item on critical system / user paths ──────
+    // Belt-and-suspenders: Remove-Item is also removed from SHELL_ALLOWLIST so it
+    // requires explicit approval. These patterns hard-block attempts to target
+    // system-owned directories regardless of approval state.
+    /Remove-Item\b.*[Cc]:[/\\][Uu]sers[/\\]/i,
+    /Remove-Item\b.*[Cc]:[/\\][Ww]indows[/\\]/i,
+    /Remove-Item\b.*[Cc]:[/\\][Pp]rogram/i,
 ];
 function isCommandDenied(cmd) {
     return DENIED_COMMANDS.some(p => p.test(cmd));
@@ -153,6 +170,60 @@ function isShellDangerous(cmd) {
     const lower = cmd.toLowerCase();
     return SHELL_DANGEROUS_PATTERNS.some(p => lower.includes(p.toLowerCase()));
 }
+// ── C8: Code-level destructive path guard for run_node / run_python ──────────
+// Scans code strings for destructive filesystem operations targeting protected
+// system paths. Closes the bypass where the planner re-routes through run_node
+// or run_python after shell_exec is denied by DENIED_COMMANDS.
+//
+// Two-stage check: (1) code contains a destructive fs call, AND (2) code
+// references a protected path. Both must match for denial — benign code that
+// merely reads protected paths, or destructive code targeting workspace, passes.
+const PROTECTED_PATH_PATTERNS = [
+    // {1,2} so we match both real paths (C:\Users\) and string-literal escapes (C:\\Users\\)
+    /[Cc]:[/\\]{1,2}[Uu]sers[/\\]{1,2}/,
+    /[Cc]:[/\\]{1,2}[Ww]indows[/\\]{1,2}/,
+    /[Cc]:[/\\]{1,2}[Pp]rogram\s?[Ff]iles/,
+    /[Cc]:[/\\]{1,2}[Ss]ystem/,
+    /['"`]\/etc[/'"` ]/,
+    /['"`]\/home[/'"` ]/,
+    /['"`]\/usr[/'"` ]/,
+    /['"`]\/var[/'"` ]/,
+];
+const CODE_DESTRUCTIVE_NODE = [
+    /\bfs\s*\.\s*rmSync\b/,
+    /\bfs\s*\.\s*unlinkSync\b/,
+    /\bfs\s*\.\s*rmdirSync\b/,
+    /\bfs\.promises\s*\.\s*rm\b/,
+    /\bfs\.promises\s*\.\s*unlink\b/,
+    /\bfs\.promises\s*\.\s*rmdir\b/,
+    /\brimraf\b/,
+    /\bfs\s*\.\s*rm\s*\(/,
+    /\bdel\s*\(/, // fs-extra del()
+    /\bunlinkSync\s*\(/, // bare import
+];
+const CODE_DESTRUCTIVE_PYTHON = [
+    /\bos\s*\.\s*remove\b/,
+    /\bos\s*\.\s*unlink\b/,
+    /\bos\s*\.\s*rmdir\b/,
+    /\bos\s*\.\s*removedirs\b/,
+    /\bshutil\s*\.\s*rmtree\b/,
+    /\bpathlib\b.*\bunlink\b/,
+    /\bsend2trash\b/,
+];
+function scanCodeForDestructivePaths(code, lang) {
+    const destructivePatterns = lang === 'node' ? CODE_DESTRUCTIVE_NODE : CODE_DESTRUCTIVE_PYTHON;
+    const matchedOp = destructivePatterns.find(p => p.test(code));
+    if (!matchedOp)
+        return { denied: false, reason: '' };
+    const matchedPath = PROTECTED_PATH_PATTERNS.find(p => p.test(code));
+    if (!matchedPath)
+        return { denied: false, reason: '' };
+    const opStr = code.match(matchedOp)?.[0] ?? 'destructive op';
+    const pathStr = code.match(matchedPath)?.[0] ?? 'protected path';
+    const reason = `[Security] ${lang} code blocked: "${opStr}" targeting "${pathStr}" — destructive operation on protected system path`;
+    process.stderr.write(reason + '\n');
+    return { denied: true, reason };
+}
 // ── Sprint 25: Shell command allowlist ────────────────────────
 // Unknown commands (not in this list) are blocked and require explicit user approval.
 const SHELL_ALLOWLIST = [
@@ -179,7 +250,9 @@ const SHELL_ALLOWLIST = [
     // 11. Archive tools
     /^(tar|zip|unzip|7z|gzip|gunzip)\b/i,
     // 12. PowerShell safe cmdlets (read, navigate, item management, output)
-    /^(Get-|Select-|Where-|Sort-|Format-|Out-|Write-Output|Write-Host|ConvertTo-|ConvertFrom-|Measure-|Test-Path|Resolve-Path|Split-Path|Join-Path|Compare-Object|New-Item|Copy-Item|Move-Item|Rename-Item|Remove-Item|Set-Content|Add-Content|Clear-Content|Set-Location|Push-Location|Pop-Location)/i,
+    // Note: Remove-Item intentionally absent — falls through to needsApproval:true (C7).
+    // Hard-deny for Remove-Item on critical paths is in DENIED_COMMANDS above.
+    /^(Get-|Select-|Where-|Sort-|Format-|Out-|Write-Output|Write-Host|ConvertTo-|ConvertFrom-|Measure-|Test-Path|Resolve-Path|Split-Path|Join-Path|Compare-Object|New-Item|Copy-Item|Move-Item|Rename-Item|Set-Content|Add-Content|Clear-Content|Set-Location|Push-Location|Pop-Location)/i,
     // 13. Instant Actions: lock screen (rundll32) and volume one-liners (powershell -c)
     /^rundll32\b/i,
     /^powershell\s+-c\b/i,
@@ -330,6 +403,104 @@ let _emitProgress = null;
 function setProgressEmitter(fn) {
     _emitProgress = fn;
 }
+// ── resolveWritePath ──────────────────────────────────────────
+// Pure path resolver for file_write. Exported for unit tests.
+// Expands shorthands, resolves to absolute, then enforces the
+// allow-list: workspace (cwd), Desktop, Documents.
+// Throws with a clear message if the resolved path falls outside.
+function resolveWritePath(rawPath, opts) {
+    const home = opts?.home ?? os_1.default.homedir();
+    const cwd = opts?.cwd ?? process.cwd();
+    const user = process.env.USERNAME || process.env.USER || os_1.default.userInfo().username || 'User';
+    // Expand shorthands
+    let p = rawPath
+        .replace(/^~[\/\\]/, home + path_1.default.sep)
+        .replace(/^Desktop[\/\\]/i, path_1.default.join(home, 'Desktop') + path_1.default.sep)
+        .replace(/^C:\\Users\\Aiden\\/i, `C:\\Users\\${user}\\`)
+        .replace(/^C:\/Users\/Aiden\//i, `C:/Users/${user}/`);
+    // Resolve relative paths against cwd
+    const resolved = /^[A-Za-z]:[/\\]/.test(p) || p.startsWith('/')
+        ? p
+        : path_1.default.join(cwd, p);
+    // Allow-list: workspace root, Desktop, Documents
+    const allowedRoots = [
+        cwd,
+        path_1.default.join(home, 'Desktop'),
+        path_1.default.join(home, 'Documents'),
+    ];
+    const norm = (s) => s.toLowerCase().replace(/\//g, '\\').replace(/\\$/, '');
+    const nr = norm(resolved);
+    const ok = allowedRoots.some(root => {
+        const r = norm(root);
+        return nr === r || nr.startsWith(r + '\\');
+    });
+    if (!ok) {
+        throw new Error(`Path '${resolved}' is outside allowed write locations. Allowed: workspace, Desktop, Documents.`);
+    }
+    return resolved;
+}
+exports.APP_ALIASES = {
+    spotify: { win32: { type: 'uri', value: 'spotify' }, darwin: { type: 'app', value: 'Spotify' }, linux: { type: 'cmd', value: 'spotify' } },
+    chrome: { win32: { type: 'cmd', value: 'chrome' }, darwin: { type: 'app', value: 'Google Chrome' }, linux: { type: 'cmd', value: 'google-chrome' } },
+    firefox: { win32: { type: 'cmd', value: 'firefox' }, darwin: { type: 'app', value: 'Firefox' }, linux: { type: 'cmd', value: 'firefox' } },
+    edge: { win32: { type: 'cmd', value: 'msedge' }, darwin: { type: 'app', value: 'Microsoft Edge' }, linux: { type: 'cmd', value: 'microsoft-edge' } },
+    discord: { win32: { type: 'uri', value: 'discord' }, darwin: { type: 'app', value: 'Discord' }, linux: { type: 'cmd', value: 'discord' } },
+    slack: { win32: { type: 'uri', value: 'slack' }, darwin: { type: 'app', value: 'Slack' }, linux: { type: 'cmd', value: 'slack' } },
+    zoom: { win32: { type: 'uri', value: 'zoommtg' }, darwin: { type: 'app', value: 'zoom.us' }, linux: { type: 'cmd', value: 'zoom' } },
+    teams: { win32: { type: 'uri', value: 'msteams' }, darwin: { type: 'app', value: 'Microsoft Teams' }, linux: { type: 'cmd', value: 'teams' } },
+    vscode: { win32: { type: 'cmd', value: 'code' }, darwin: { type: 'app', value: 'Visual Studio Code' }, linux: { type: 'cmd', value: 'code' } },
+    notepad: { win32: { type: 'cmd', value: 'notepad.exe' }, darwin: { type: 'app', value: 'TextEdit' }, linux: { type: 'cmd', value: 'gedit' } },
+    'notepad++': { win32: { type: 'cmd', value: 'notepad++' } },
+    calculator: { win32: { type: 'cmd', value: 'calc' }, darwin: { type: 'app', value: 'Calculator' }, linux: { type: 'cmd', value: 'gnome-calculator' } },
+    paint: { win32: { type: 'cmd', value: 'mspaint' } },
+    explorer: { win32: { type: 'cmd', value: 'explorer' }, darwin: { type: 'cmd', value: 'open ~' }, linux: { type: 'cmd', value: 'nautilus' } },
+    terminal: { win32: { type: 'cmd', value: 'wt' }, darwin: { type: 'app', value: 'Terminal' }, linux: { type: 'cmd', value: 'gnome-terminal' } },
+    word: { win32: { type: 'cmd', value: 'winword' } },
+    excel: { win32: { type: 'cmd', value: 'excel' } },
+    powershell: { win32: { type: 'cmd', value: 'powershell' } },
+    cmd: { win32: { type: 'cmd', value: 'cmd' } },
+};
+// Display name aliases → canonical key in APP_ALIASES
+const DISPLAY_ALIASES = {
+    'google chrome': 'chrome', 'microsoft edge': 'edge',
+    'vs code': 'vscode', 'visual studio code': 'vscode',
+    'microsoft teams': 'teams', 'file explorer': 'explorer',
+    'windows terminal': 'terminal', 'task manager': 'calculator',
+    'calc': 'calculator',
+};
+/**
+ * C13: Resolve the shell command to launch an app on a given platform.
+ * Pure function — takes platform arg for testability.
+ * @param appName  - user-facing app name (lowercase, trimmed)
+ * @param platform - override for process.platform (for testing)
+ */
+function resolveLaunchCommand(appName, platform) {
+    const plat = (platform ?? process.platform);
+    const canonical = DISPLAY_ALIASES[appName] ?? appName;
+    const entry = exports.APP_ALIASES[canonical]?.[plat];
+    if (entry) {
+        switch (entry.type) {
+            case 'uri':
+                return plat === 'win32' ? `cmd /c start "" "${entry.value}:"`
+                    : plat === 'darwin' ? `open "${entry.value}://"`
+                        : `xdg-open "${entry.value}://"`;
+            case 'app':
+                return `open -a "${entry.value}"`;
+            case 'cmd':
+                if (plat === 'win32')
+                    return `cmd /c start "" "${entry.value}"`;
+                if (plat === 'darwin')
+                    return `open -a "${entry.value}"`;
+                return entry.value;
+        }
+    }
+    // Fallback for unknown apps
+    if (plat === 'win32')
+        return `cmd /c start "" "${appName}"`;
+    if (plat === 'darwin')
+        return `open -a "${appName}"`;
+    return `xdg-open "${appName}"`;
+}
 // ── Tool implementations ──────────────────────────────────────
 exports.TOOLS = {
     // ── respond — direct conversational reply (no external tools needed) ──
@@ -740,17 +911,7 @@ exports.TOOLS = {
             return { success: false, output: '', error: 'Access denied: protected path. Aiden cannot write credentials, SSH keys, or env files.' };
         }
         try {
-            // Expand Desktop and ~ shorthands, and fix any "Aiden" username to actual system user
-            const _user = process.env.USERNAME || process.env.USER || require('os').userInfo().username || 'User';
-            const _home = require('os').homedir();
-            filePath = filePath
-                .replace(/^~[\/\\]/i, _home + path_1.default.sep)
-                .replace(/^Desktop[\/\\]/i, path_1.default.join(_home, 'Desktop') + path_1.default.sep)
-                .replace(/^C:\\Users\\Aiden\\/i, `C:\\Users\\${_user}\\`)
-                .replace(/^C:\/Users\/Aiden\//i, `C:/Users/${_user}/`);
-            const resolved = filePath.match(/^[A-Z]:/i) || filePath.startsWith('/')
-                ? filePath
-                : path_1.default.join(process.cwd(), filePath);
+            const resolved = resolveWritePath(filePath);
             fs_1.default.mkdirSync(path_1.default.dirname(resolved), { recursive: true });
             fs_1.default.writeFileSync(resolved, content, 'utf-8');
             const written = fs_1.default.existsSync(resolved);
@@ -825,6 +986,10 @@ exports.TOOLS = {
         const script = p.script || p.code || p.command || '';
         if (!script)
             return { success: false, output: '', error: 'No script' };
+        // ── C8: Destructive path guard ─────────────────────────────────
+        const pyGuard = scanCodeForDestructivePaths(script, 'python');
+        if (pyGuard.denied)
+            return { success: false, output: '', error: pyGuard.reason };
         // ── N+34: Docker sandbox routing ───────────────────────────
         const _pyMode = process.env.AIDEN_SANDBOX_MODE || 'off';
         if (_pyMode === 'strict' || _pyMode === 'auto') {
@@ -876,6 +1041,10 @@ exports.TOOLS = {
         const script = p.script || p.code || p.command || '';
         if (!script)
             return { success: false, output: '', error: 'No script' };
+        // ── C8: Destructive path guard ─────────────────────────────────
+        const nodeGuard = scanCodeForDestructivePaths(script, 'node');
+        if (nodeGuard.denied)
+            return { success: false, output: '', error: nodeGuard.reason };
         const tmp = path_1.default.join(process.cwd(), 'workspace', `js_${Date.now()}.js`);
         fs_1.default.mkdirSync(path_1.default.dirname(tmp), { recursive: true });
         fs_1.default.writeFileSync(tmp, script);
@@ -905,6 +1074,15 @@ exports.TOOLS = {
             return { success: false, output: '', error: e.message };
         }
     },
+    now_playing: async () => {
+        try {
+            const result = await (0, nowPlaying_1.getNowPlaying)();
+            return { success: true, output: JSON.stringify(result) };
+        }
+        catch (e) {
+            return { success: false, output: '', error: e.message };
+        }
+    },
     notify: async (p) => {
         const msg = (p.message || p.command || p.title || p.body || '')
             .replace(/'/g, '').replace(/"/g, '').replace(/`/g, '').replace(/\$/g, '').trim();
@@ -1481,7 +1659,7 @@ exports.TOOLS = {
     },
     screenshot: async (_p) => {
         try {
-            const filepath = await (0, computerControl_1.takeScreenshot)();
+            const filepath = await (0, computerControl_1.takeScreenshot)(_p?.outputPath ? { outputPath: _p.outputPath } : undefined);
             const stats = require('fs').statSync(filepath);
             return { success: true, output: `Screenshot saved: ${filepath} (${Math.round(stats.size / 1024)}kb)`, path: filepath };
         }
@@ -1602,48 +1780,15 @@ exports.TOOLS = {
         const appName = (p.app_name ?? p.appName ?? p.app ?? p.path ?? p.command ?? p.name ?? p.target ?? '').toString().toLowerCase().trim();
         if (!appName)
             return { success: false, output: '', error: 'No app_name provided. Pass app_name e.g. "chrome" or "spotify".' };
-        // Map friendly display names → executable/URI names
-        const exeMap = {
-            'chrome': 'chrome',
-            'google chrome': 'chrome',
-            'firefox': 'firefox',
-            'edge': 'msedge',
-            'microsoft edge': 'msedge',
-            'spotify': 'spotify',
-            'discord': 'discord',
-            'vscode': 'code',
-            'vs code': 'code',
-            'visual studio code': 'code',
-            'notepad': 'notepad',
-            'notepad++': 'notepad++',
-            'word': 'winword',
-            'excel': 'excel',
-            'powerpoint': 'powerpnt',
-            'slack': 'slack',
-            'zoom': 'zoom',
-            'teams': 'teams',
-            'microsoft teams': 'teams',
-            'explorer': 'explorer',
-            'file explorer': 'explorer',
-            'task manager': 'taskmgr',
-            'taskmgr': 'taskmgr',
-            'calculator': 'calc',
-            'calc': 'calc',
-            'paint': 'mspaint',
-            'terminal': 'wt',
-            'windows terminal': 'wt',
-            'cmd': 'cmd',
-            'powershell': 'powershell',
-        };
-        const exe = exeMap[appName] ?? appName;
+        // C13: cross-platform launch via resolveLaunchCommand()
+        const cmd = resolveLaunchCommand(appName);
         try {
             const { execSync } = await Promise.resolve().then(() => __importStar(require('child_process')));
-            // Use cmd /c start — cmd built-in, avoids Start-Process (blocked by permissions)
-            execSync(`cmd /c start "" "${exe}"`, { timeout: 10000 });
-            return { success: true, output: `Launched: "${appName}"` };
+            execSync(cmd, { timeout: 10000 });
+            return { success: true, output: `Launched: "${appName}" via: ${cmd}` };
         }
         catch (e) {
-            return { success: false, output: '', error: e.message };
+            return { success: false, output: '', error: `Failed to launch "${appName}": ${e.message}` };
         }
     },
     app_close: async (p) => {
@@ -2572,12 +2717,18 @@ public class AidenVolSet {
 // ── Plugin-registered tools ───────────────────────────────────
 const externalTools = {};
 const externalToolsMeta = {};
+// v3.19 Phase 1 — registry generation counter (Hermes run_agent.py:113,159).
+// Incremented whenever a new external tool is registered so deriver caches
+// know to recompute.  Declared here so registerExternalTool can reference it
+// before the deriver block (which appears after TOOL_REGISTRY).
+let _generation = 0;
 function registerExternalTool(name, fn, source) {
     externalTools[name] = async (input) => {
         const r = await fn(input);
         return { success: r.success, output: r.output };
     };
     externalToolsMeta[name] = { source };
+    _generation++; // invalidate deriver caches
     if ((process.env.AIDEN_LOG_LEVEL || 'info') === 'debug') {
         console.log('[ToolRegistry] Plugin "' + source + '" registered tool: ' + name);
     }
@@ -2586,6 +2737,13 @@ function registerExternalTool(name, fn, source) {
 function getExternalToolsMeta() {
     return { ...externalToolsMeta };
 }
+/** Dynamic tool-existence check that includes both TOOLS (static) and
+ *  externalTools (registered at runtime via registerExternalTool / registerSlashMirrorTools).
+ *  Use this in the executor instead of the pre-computed ALLOWED_TOOLS constant, which
+ *  is frozen at module-load time before mirror tools are registered. */
+function isKnownTool(name) {
+    return name in exports.TOOLS || name in externalTools;
+}
 // ── Internal dispatcher — no retry, no timeout ────────────────
 async function runTool(tool, input) {
     // Build per-call context with tool-scoped progress emitter
@@ -2730,6 +2888,7 @@ exports.TOOL_DESCRIPTIONS = {
     run_python: 'Execute a Python script and return stdout/stderr',
     run_node: 'Execute Node.js/JavaScript code and return the output',
     system_info: 'Get system hardware and OS information (CPU, RAM, disk, OS)',
+    now_playing: 'Get the currently playing media (song, artist, app). Calls Windows MediaSession live — always reflects real-time state. Use whenever the user asks what is playing, whether music is paused, or what track is on.',
     notify: 'Send a desktop notification to the user',
     get_stocks: 'Get top gainers, losers, or most active stocks from NSE/BSE',
     get_market_data: 'Get real-time price, change%, and volume for a stock symbol',
@@ -2739,7 +2898,7 @@ exports.TOOL_DESCRIPTIONS = {
     mouse_click: 'Click the mouse at screen coordinates',
     keyboard_type: 'Type text using the keyboard',
     keyboard_press: 'Press a keyboard key or shortcut (e.g. ctrl+c)',
-    screenshot: 'Take a screenshot of the entire screen',
+    screenshot: 'Take a screenshot of the entire screen. Optional: outputPath (absolute path, e.g. C:\\Users\\shiva\\Desktop\\shot.png) to save to a specific location; defaults to workspace/screenshots/.',
     screen_read: 'Read and describe the current screen contents',
     vision_loop: 'Autonomously control the computer using vision to complete a goal',
     wait: 'Pause execution for a specified number of milliseconds',
@@ -2778,6 +2937,9 @@ exports.TOOL_DESCRIPTIONS = {
     swarm: 'Run N isolated subagents on the same task in parallel and aggregate their answers via voting or synthesis. Use for high-confidence research where multiple independent perspectives reduce error.',
     send_file_local: 'Send a file to another device on the local network via LocalSend (op: discover | send)',
     receive_file_local: 'Wait for an incoming LocalSend file transfer on the local network',
+    ingest_youtube: 'Download and ingest a YouTube video into memory: transcribes audio, extracts metadata, and stores as a searchable memory entry.',
+    memory_store: 'Persist a fact, preference, or note to permanent memory right now. Use when the user says "remember", "save this", "keep track of", or wants something stored. Pass { fact: "..." }.',
+    memory_forget: 'Remove a fact or preference from permanent memory. Use when the user says "forget", "remove from memory", "delete from memory". Pass { fact: "keyword to match" }.',
 };
 // ── N+28: TOOL_NAMES_ONLY ──────────────────────────────────────
 // One-liner per tool — first sentence of TOOL_DESCRIPTIONS, truncated to 60 chars.
@@ -2804,7 +2966,10 @@ const TOOL_TIERS = {
     get_company_info: 1,
     social_research: 1,
     system_info: 1,
+    now_playing: 1,
     notify: 1,
+    memory_store: 1,
+    memory_forget: 1,
     wait: 1,
     get_briefing: 1,
     get_natural_events: 1,
@@ -2920,6 +3085,7 @@ const TOOL_CATEGORIES = {
     get_natural_events: ['data'],
     notify: ['system'],
     system_info: ['system'],
+    now_playing: ['system'],
     wait: ['system', 'browser', 'screen'],
     clipboard_read: ['system', 'code'],
     clipboard_write: ['system', 'code'],
@@ -2937,6 +3103,8 @@ const TOOL_CATEGORIES = {
     analytics: ['introspection'],
     spend: ['introspection'],
     memory_show: ['introspection', 'memory'],
+    memory_store: ['memory'],
+    memory_forget: ['memory'],
     lessons: ['introspection', 'memory'],
     skills_list: ['introspection'],
     tools_list: ['introspection'],
@@ -2957,6 +3125,607 @@ const TOOL_CATEGORIES = {
     voice_clone: ['voice'],
     voice_design: ['voice'],
 };
+exports.TOOL_REGISTRY = {
+    // ── Core / response ──────────────────────────────────────────────────────────
+    respond: {
+        description: 'Send a direct conversational response to the user. Use for greetings, capability questions, clarifications, simple factual answers, and anything that does NOT require external tools. This is the default tool when no other tool is needed.',
+        tier: 1, category: ['core'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    manage_goals: {
+        description: 'Track and manage goals and projects. Use when user asks what to work on, mentions a project, deadline, or launch plan. Actions: list, add, update, complete, remove, suggest.',
+        tier: 1, category: ['core'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    compact_context: {
+        description: 'Summarize and compress the current conversation context. Saves session to disk and extracts durable memories. Call when context is getting long.',
+        tier: 1, category: ['core'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    run_agent: {
+        description: 'Spawn a sub-agent to complete a sub-goal autonomously',
+        tier: 1, category: ['core'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    lookup_skill: {
+        description: 'Search learned skills for a matching pattern. Returns the SKILL.md of the best match. Use before planning multi-step tasks to check if Aiden already knows how to do it.',
+        tier: 1, category: ['core'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    lookup_tool_schema: {
+        description: 'Get the full description for a named tool. Call before using an unfamiliar tool.',
+        tier: 1, category: ['core'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    // ── Web / research ───────────────────────────────────────────────────────────
+    web_search: {
+        description: 'Search the web for current information, news, or any topic',
+        tier: 1, category: ['web', 'data'], timeoutMs: 15000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    fetch_url: {
+        description: 'Fetch the content of any URL and return the text',
+        tier: 1, category: ['web'], timeoutMs: 20000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    fetch_page: {
+        description: 'Fetch a web page and extract its readable text content',
+        tier: 1, category: ['web'], timeoutMs: 20000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    deep_research: {
+        description: 'Conduct thorough multi-step research on a topic using multiple sources',
+        tier: 1, category: ['web'], timeoutMs: 60000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    social_research: {
+        description: 'Research a person or company across social and public sources',
+        tier: 1, category: ['web', 'data'], timeoutMs: 30000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    ingest_youtube: {
+        description: 'Ingest a YouTube video — downloads transcript or audio and extracts searchable text',
+        tier: 1, category: ['web', 'memory'],
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    // ── Browser ──────────────────────────────────────────────────────────────────
+    open_browser: {
+        description: 'Open a URL in the system browser',
+        tier: 3, category: ['browser'], timeoutMs: 15000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    browser_click: {
+        description: 'Click on an element in the browser by selector',
+        tier: 3, category: ['browser'], timeoutMs: 10000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    browser_scroll: {
+        description: 'Scroll the browser page or a specific element. Params: direction (up|down|top|bottom, default down), amount (pixels, default 500), selector (optional CSS selector to scroll a specific element)',
+        tier: 3, category: ['browser'], timeoutMs: 8000,
+        parallel: 'never', // agentLoop.ts:1965 — not in SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    browser_type: {
+        description: 'Type text into a browser input field',
+        tier: 3, category: ['browser'], timeoutMs: 10000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    browser_extract: {
+        description: 'Extract text content from the current browser page',
+        tier: 3, category: ['browser'], timeoutMs: 10000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    browser_screenshot: {
+        description: 'Take a screenshot of the current browser window',
+        tier: 3, category: ['browser'], timeoutMs: 8000,
+        parallel: 'never', // agentLoop.ts:1965 — not in SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    browser_get_url: {
+        description: 'Return the URL currently loaded in the browser',
+        tier: 3, category: ['browser'], timeoutMs: 5000,
+        parallel: 'never', // agentLoop.ts:1965 — not in SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    // ── Files ────────────────────────────────────────────────────────────────────
+    file_write: {
+        description: 'Write content to a file at the specified path',
+        tier: 2, category: ['files'],
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    file_read: {
+        description: 'Read the contents of a file at the specified path',
+        tier: 2, category: ['files'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    file_list: {
+        description: 'List files in a directory',
+        tier: 2, category: ['files'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    watch_folder: {
+        description: 'Watch a folder and react automatically when new files appear',
+        tier: 2, category: ['files', 'system'], timeoutMs: 10000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    watch_folder_list: {
+        description: 'List all currently watched folder paths',
+        tier: 2, category: ['files', 'system'], timeoutMs: 5000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    // ── Shell / code execution ───────────────────────────────────────────────────
+    shell_exec: {
+        description: 'Execute a shell/PowerShell command and return the output',
+        tier: 2, category: ['code', 'system'], timeoutMs: 30000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    run_powershell: {
+        description: 'Run a PowerShell command on Windows',
+        tier: 2, category: ['code', 'system'], timeoutMs: 30000,
+        parallel: 'never', // agentLoop.ts:1965 — not in SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    cmd: {
+        description: 'Run a Windows cmd.exe command and return stdout/stderr/exitCode',
+        tier: 2, category: ['code', 'system'], timeoutMs: 30000,
+        parallel: 'never', // agentLoop.ts:1965 — not in SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    ps: {
+        description: 'Run a PowerShell command directly (no temp file) and return stdout/stderr/exitCode',
+        tier: 2, category: ['code', 'system'], timeoutMs: 30000,
+        parallel: 'never', // agentLoop.ts:1965 — not in SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    wsl: {
+        description: 'Run a bash command inside WSL (Windows Subsystem for Linux); auto-translates C:\\ paths to /mnt/c/',
+        tier: 2, category: ['code', 'system'], timeoutMs: 30000,
+        parallel: 'never', // agentLoop.ts:1965 — not in SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    run_python: {
+        description: 'Execute a Python script and return stdout/stderr',
+        tier: 2, category: ['code'], timeoutMs: 60000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    run_node: {
+        description: 'Execute Node.js/JavaScript code and return the output',
+        tier: 2, category: ['code'], timeoutMs: 60000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    run: {
+        description: 'Run a command or script (generic alias for shell_exec)',
+        tier: 2, category: ['code'],
+        parallel: 'never', // agentLoop.ts:1965 — not in SEQUENTIAL_ONLY
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    code_interpreter_python: {
+        description: 'Run Python code in a sandboxed interpreter with data science libraries',
+        tier: 2, category: ['code'], timeoutMs: 35000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    code_interpreter_node: {
+        description: 'Run Node.js code in a sandboxed interpreter',
+        tier: 2, category: ['code'], timeoutMs: 35000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    // ── Screen / vision / input ──────────────────────────────────────────────────
+    screenshot: {
+        description: 'Take a screenshot of the entire screen. Optional param: outputPath (absolute path, e.g. C:\\Users\\shiva\\Desktop\\shot.png) — if omitted, saves to workspace/screenshots/.',
+        tier: 4, category: ['screen'], timeoutMs: 10000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    screen_read: {
+        description: 'Read and describe the current screen contents',
+        tier: 4, category: ['screen'],
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    vision_loop: {
+        description: 'Autonomously control the computer using vision to complete a goal',
+        tier: 4, category: ['screen'], timeoutMs: 120000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    vision_analyze: {
+        description: 'Analyze an image file using computer vision and return a structured description',
+        tier: 4, category: ['screen', 'data'], timeoutMs: 45000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    mouse_move: {
+        description: 'Move the mouse cursor to screen coordinates',
+        tier: 4, category: ['screen'],
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    mouse_click: {
+        description: 'Click the mouse at screen coordinates',
+        tier: 4, category: ['screen'],
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    keyboard_type: {
+        description: 'Type text using the keyboard',
+        tier: 4, category: ['screen'],
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    keyboard_press: {
+        description: 'Press a keyboard key or shortcut (e.g. ctrl+c)',
+        tier: 4, category: ['screen'],
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    // ── Data / market ────────────────────────────────────────────────────────────
+    get_stocks: {
+        description: 'Get top gainers, losers, or most active stocks from NSE/BSE',
+        tier: 1, category: ['data'], timeoutMs: 20000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    get_market_data: {
+        description: 'Get real-time price, change%, and volume for a stock symbol',
+        tier: 1, category: ['data'], timeoutMs: 15000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    get_company_info: {
+        description: 'Get company profile, sector, P/E ratio, EPS, and revenue',
+        tier: 1, category: ['data'], timeoutMs: 15000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    get_briefing: {
+        description: 'Run the morning briefing: weather, markets, news, and daily summary',
+        tier: 1, category: ['data'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    get_natural_events: {
+        description: 'Fetch active natural events from NASA EONET API. Returns current earthquakes, wildfires, storms, floods, and other natural events worldwide.',
+        tier: 1, category: ['data'],
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    // ── System / OS ──────────────────────────────────────────────────────────────
+    system_info: {
+        description: 'Get system hardware and OS information (CPU, RAM, disk, OS)',
+        tier: 1, category: ['system'],
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    now_playing: {
+        description: 'Get the currently playing media (song, artist, app). Calls Windows MediaSession live — always reflects real-time state. Use whenever the user asks what is playing, whether music is paused, or what track is on.',
+        tier: 1, category: ['system'],
+        parallel: 'safe', // read-only, no side effects
+        mcp: 'safe',
+        timeoutMs: 5000,
+    },
+    notify: {
+        description: 'Send a desktop notification to the user',
+        tier: 1, category: ['system'],
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    wait: {
+        description: 'Pause execution for a specified number of milliseconds',
+        tier: 1, category: ['system', 'browser', 'screen'], timeoutMs: 6000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    clipboard_read: {
+        description: 'Read the current contents of the system clipboard',
+        tier: 2, category: ['system', 'code'], timeoutMs: 5000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    clipboard_write: {
+        description: 'Write text to the system clipboard',
+        tier: 2, category: ['system', 'code'], timeoutMs: 5000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    window_list: {
+        description: 'List all open windows on the desktop',
+        tier: 3, category: ['browser', 'system'], timeoutMs: 10000,
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    window_focus: {
+        description: 'Bring a specific window to the foreground by title',
+        tier: 3, category: ['browser', 'system'], timeoutMs: 8000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    app_launch: {
+        description: 'Launch an application by name or executable path',
+        tier: 3, category: ['browser', 'system'], timeoutMs: 10000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    app_close: {
+        description: 'Close an application by window title or process name',
+        tier: 3, category: ['browser', 'system'], timeoutMs: 8000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        retry: false, // agentLoop.ts:1881 NO_RETRY_TOOLS
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    system_volume: {
+        description: 'Get or set Windows speaker volume (get/up/down/mute/unmute/set)',
+        tier: 2, category: ['system'], timeoutMs: 8000,
+        parallel: 'sequential', // agentLoop.ts:1965 SEQUENTIAL_ONLY
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    schedule_reminder: {
+        description: "Schedule a desktop notification reminder. Params: message (string), delaySeconds or delayMs (number), recurring ('hourly'|'daily'|'weekly', optional). op='list' to see pending reminders, op='cancel' with id to cancel one.",
+        tier: 0, category: ['system'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    // ── Git ──────────────────────────────────────────────────────────────────────
+    git_status: {
+        description: 'Show git status and recent commits for a repository. Provide path parameter for a specific directory.',
+        tier: 2, category: ['git'], timeoutMs: 15000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    git_commit: {
+        description: 'Stage and commit files to a local git repository',
+        tier: 2, category: ['git'], timeoutMs: 30000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    git_push: {
+        description: 'Push committed changes to a remote git repository',
+        tier: 2, category: ['git'], timeoutMs: 60000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    // ── Comms / calendar / email ─────────────────────────────────────────────────
+    get_calendar: {
+        description: 'Get upcoming calendar events from Google Calendar (requires iCal URL in Settings → Channels). Parameters: daysAhead (number, default 7).',
+        tier: 1, category: ['data', 'system'],
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    read_email: {
+        description: 'Read recent unread emails from Gmail (requires App Password in Settings → Channels). Parameters: count (number, default 10), folder (string, default INBOX).',
+        tier: 1, category: ['data', 'system'],
+        parallel: 'safe', // agentLoop.ts:1957 PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    send_email: {
+        description: 'Send an email via Gmail (requires App Password in Settings → Channels). Parameters: to (string), subject (string), body (string).',
+        tier: 1, category: ['data', 'system'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    send_file_local: {
+        description: 'Send a file to another device on the local network via LocalSend (op: discover | send)',
+        tier: 2, category: ['files', 'system'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    receive_file_local: {
+        description: 'Wait for an incoming LocalSend file transfer on the local network',
+        tier: 2, category: ['files', 'system'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    // ── Delegation / subagents ───────────────────────────────────────────────────
+    spawn: {
+        description: "Delegate a sub-task to an isolated subagent with its own context and half the remaining iteration budget. Returns the subagent's synthesized answer.",
+        tier: 2, category: ['delegation'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    spawn_subagent: {
+        description: "Spawn an isolated subagent to handle a parallel sub-task. The subagent runs in its own conversation context with half your remaining iteration budget. Use for: research that would bloat your context, parallel work where you need both results, sandboxed exploration. Returns the subagent's final reply text.",
+        tier: 2, category: ['delegation'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    swarm: {
+        description: 'Run N isolated subagents on the same task in parallel and aggregate their answers via voting or synthesis. Use for high-confidence research where multiple independent perspectives reduce error.',
+        tier: 2, category: ['delegation'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    // ── Voice ────────────────────────────────────────────────────────────────────
+    voice_speak: {
+        description: 'Speak text aloud using the TTS provider chain (VoxCPM → Edge TTS → ElevenLabs → SAPI). Accepts text, voice, rate, volume, provider overrides.',
+        tier: 2, category: ['voice'], timeoutMs: 60000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'destructive', // api/mcp.ts:44
+    },
+    voice_transcribe: {
+        description: 'Transcribe an audio file to text using the STT provider chain (Groq Whisper → OpenAI Whisper → Whisper.cpp). Returns { text, provider, durationMs }.',
+        tier: 2, category: ['voice'], timeoutMs: 60000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'safe', // api/mcp.ts:25
+    },
+    voice_clone: {
+        description: 'Clone a voice from a reference audio file and synthesize new text. Requires text and referenceAudioPath. Uses VoxCPM when USE_VOXCPM=1.',
+        tier: 2, category: ['voice'], timeoutMs: 120000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    voice_design: {
+        description: 'Design a custom voice from a text description and synthesize text with it. Requires text and voiceDescription. Uses VoxCPM when USE_VOXCPM=1.',
+        tier: 2, category: ['voice'], timeoutMs: 120000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    // ── Interaction / UX ─────────────────────────────────────────────────────────
+    clarify: {
+        description: 'Ask the user a clarifying question and wait for their typed response before proceeding',
+        tier: 1, category: ['interaction', 'core'], timeoutMs: 300000,
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    todo: {
+        description: 'Manage the current session todo list — add, check off, or display pending tasks',
+        tier: 1, category: ['interaction', 'core'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    memory_store: {
+        description: 'Persist a fact, preference, or observation to permanent memory right now. Use whenever the user says "remember", "save this", "keep track of", or similar. Pass { fact: "the thing to remember" }.',
+        tier: 1, category: ['memory'],
+        parallel: 'never',
+        retry: false, // write operation — don't double-write on retry
+        mcp: 'excluded',
+    },
+    memory_forget: {
+        description: 'Remove a fact or preference from permanent memory. Use when the user says "forget X", "remove X from memory", "delete X from memory". Pass { fact: "keyword to match" }.',
+        tier: 1, category: ['memory'],
+        parallel: 'never',
+        retry: false, // write operation — don't double-delete on retry
+        mcp: 'excluded',
+    },
+    search: {
+        description: 'Search workspace memory, session context, and file system for relevant stored information',
+        tier: 1, category: ['memory', 'introspection'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+    cronjob: {
+        description: 'Schedule a recurring task using cron-style timing (alias for schedule_reminder with recurring param)',
+        tier: 1, category: ['system', 'core'],
+        parallel: 'never', // agentLoop.ts:1957 — not in PARALLEL_SAFE
+        mcp: 'excluded', // api/mcp.ts — not in SAFE_TOOLS or DESTRUCTIVE_TOOLS
+    },
+};
+// ── v3.19 Phase 1, Commit 2: deriver functions ───────────────────────────────
+// Inspired by Hermes run_agent.py:113,159.  Each deriver caches its result and
+// recomputes only when _generation changes (i.e. when a new external tool is
+// registered via registerExternalTool).  Callers should use these instead of
+// reading TOOL_REGISTRY directly — Commits 4-6 will swap every hand-maintained
+// list to call the appropriate deriver.
+/** Expose the current generation for consumers that manage their own caches. */
+function bumpGeneration() { _generation++; }
+function getGeneration() { return _generation; }
+/** Build a zero-argument memoiser that recomputes whenever _generation changes. */
+function makeCache(build) {
+    let cached;
+    let cachedGen = -1;
+    return () => {
+        if (cachedGen !== _generation) {
+            cached = build();
+            cachedGen = _generation;
+        }
+        return cached;
+    };
+}
+// ── 1. Names ──────────────────────────────────────────────────────────────────
+/** All core tool names (TOOL_REGISTRY keys only, excludes slash mirrors).
+ *  Replaces TOOL_NAMES_ONLY (toolRegistry.ts). */
+exports.registryNames = makeCache(() => Object.keys(exports.TOOL_REGISTRY));
+// ── 2. Descriptions ───────────────────────────────────────────────────────────
+/** Map of name → description string.  Falls back to ''.
+ *  Replaces TOOL_DESCRIPTIONS (toolRegistry.ts). */
+exports.registryDescriptions = makeCache(() => Object.fromEntries(Object.entries(exports.TOOL_REGISTRY).map(([n, m]) => [n, m.description ?? ''])));
+// ── 3. Tiers ──────────────────────────────────────────────────────────────────
+/** Map of name → ToolTier.  Falls back to tier 1.
+ *  Replaces TOOL_TIERS (toolRegistry.ts). */
+exports.registryTiers = makeCache(() => Object.fromEntries(Object.entries(exports.TOOL_REGISTRY).map(([n, m]) => [n, m.tier ?? 1])));
+// ── 4. Categories ─────────────────────────────────────────────────────────────
+/** Map of name → ToolCategory[].  Falls back to ['core'].
+ *  Replaces TOOL_CATEGORIES (toolRegistry.ts). */
+exports.registryCategories = makeCache(() => Object.fromEntries(Object.entries(exports.TOOL_REGISTRY).map(([n, m]) => [n, m.category ?? ['core']])));
+// ── 5. Timeouts ───────────────────────────────────────────────────────────────
+/** Map of name → timeout in ms.  Falls back to 15 000 ms.
+ *  Replaces TOOL_TIMEOUTS (toolRegistry.ts). */
+exports.registryTimeouts = makeCache(() => Object.fromEntries(Object.entries(exports.TOOL_REGISTRY).map(([n, m]) => [n, m.timeoutMs ?? 15000])));
+// ── 6. Allowed / valid tools ──────────────────────────────────────────────────
+/** Complete allowed-tool list: TOOL_REGISTRY keys + registered external tools.
+ *  Replaces ALLOWED_TOOLS (agentLoop.ts:808) and VALID_TOOLS (agentLoop.ts:1521). */
+exports.registryAllowedTools = makeCache(() => [
+    ...Object.keys(exports.TOOL_REGISTRY),
+    ...Object.keys(externalTools),
+]);
+// ── 6b. Valid tools ───────────────────────────────────────────────────────────
+/** Valid-tool list for agent-loop routing: same data as registryAllowedTools,
+ *  kept as a separate deriver for independent traceability per call site.
+ *  Replaces VALID_TOOLS (agentLoop.ts:1521). */
+exports.registryValidTools = makeCache(() => [
+    ...Object.keys(exports.TOOL_REGISTRY),
+    ...Object.keys(externalTools),
+]);
+// ── 7. No-retry set ───────────────────────────────────────────────────────────
+/** Set of tools that must NOT be retried on failure (retry === false).
+ *  Replaces NO_RETRY_TOOLS (agentLoop.ts:1881). */
+exports.registryNoRetrySet = makeCache(() => new Set(Object.entries(exports.TOOL_REGISTRY)
+    .filter(([, m]) => m.retry === false)
+    .map(([n]) => n)));
+// ── 8. Parallel-safe set ──────────────────────────────────────────────────────
+/** Set of tools safe to execute in parallel (parallel === 'safe').
+ *  Replaces PARALLEL_SAFE (agentLoop.ts:1957). */
+exports.registryParallelSafeSet = makeCache(() => new Set(Object.entries(exports.TOOL_REGISTRY)
+    .filter(([, m]) => m.parallel === 'safe')
+    .map(([n]) => n)));
+// ── 9. Sequential-only set ────────────────────────────────────────────────────
+/** Set of tools that must always run sequentially (parallel === 'sequential').
+ *  Replaces SEQUENTIAL_ONLY (agentLoop.ts:1965). */
+exports.registrySequentialOnlySet = makeCache(() => new Set(Object.entries(exports.TOOL_REGISTRY)
+    .filter(([, m]) => m.parallel === 'sequential')
+    .map(([n]) => n)));
+// ── 10. MCP safe list ─────────────────────────────────────────────────────────
+/** Tools safe to expose via MCP (mcp === 'safe').
+ *  Replaces SAFE_TOOLS (api/mcp.ts:25). */
+exports.registryMcpSafeList = makeCache(() => Object.entries(exports.TOOL_REGISTRY)
+    .filter(([, m]) => m.mcp === 'safe')
+    .map(([n]) => n));
+// ── 11. MCP destructive list ──────────────────────────────────────────────────
+/** Tools exposed via MCP but flagged destructive (mcp === 'destructive').
+ *  Replaces DESTRUCTIVE_TOOLS (api/mcp.ts:44). */
+exports.registryMcpDestructiveList = makeCache(() => Object.entries(exports.TOOL_REGISTRY)
+    .filter(([, m]) => m.mcp === 'destructive')
+    .map(([n]) => n));
+// ─────────────────────────────────────────────────────────────────────────────
 function detectToolCategories(message) {
     const categories = new Set(['core']);
     const msg = message.toLowerCase();
@@ -2972,7 +3741,9 @@ function detectToolCategories(message) {
         categories.add('screen');
     if (/stock|nifty|market|price|nse|bse|sensex|reliance|trading|shares|equity|briefing|weather|natural|earthquake/i.test(msg))
         categories.add('data');
-    if (/notify|notification|remind|alert|system info|cpu|ram|disk|hardware|clipboard|launch|close app/i.test(msg))
+    if (/email|inbox|mail|gmail|unread|read_email|send_email|calendar|meetings|events/i.test(msg))
+        categories.add('data');
+    if (/notify|notification|remind|alert|system info|cpu|ram|disk|hardware|clipboard|launch|close app|now.?playing|what.*playing|what.*song|what.*music|is.*playing|music.*paused|current.*track/i.test(msg))
         categories.add('system');
     if (/voice|speak|say aloud|listen|record audio|tts|text.to.speech|transcribe|speech.to.text|clone.*voice|voice.*design|voice.*clone|design.*voice/i.test(msg))
         categories.add('voice');