@memoryblock/tools 0.1.0-beta → 0.1.2

package/README.md

@@ -0,0 +1,35 @@
+# @memoryblock/tools
+
+Standard tool definitions and schemas for **memoryblock**.
+
+This package handles:
+- Standardized tool execution
+- Zod JSON Schema validations
+- Tool argument type coercion
+
+## The `memoryblock` Ecosystem
+
+**memoryblock** is a highly modular system. Here are the official packages:
+
+**The Core**
+*   [**memoryblock**](https://www.npmjs.com/package/memoryblock) - The core engine interface and types.
+*   [**@memoryblock/daemon**](https://www.npmjs.com/package/@memoryblock/daemon) - Background daemon manager.
+*   [**@memoryblock/api**](https://www.npmjs.com/package/@memoryblock/api) - Core REST and WebSocket API server.
+
+**Integrations & Tooling**
+*   [**@memoryblock/adapters**](https://www.npmjs.com/package/@memoryblock/adapters) - LLM adapters (OpenAI, Anthropic, Bedrock, etc).
+*   [**@memoryblock/channels**](https://www.npmjs.com/package/@memoryblock/channels) - Communication channels (CLI, Telegram, Web).
+*   [**@memoryblock/tools**](https://www.npmjs.com/package/@memoryblock/tools) - Standard tool definitions and schemas.
+*   [**@memoryblock/locale**](https://www.npmjs.com/package/@memoryblock/locale) - Localization strings and formatting.
+*   [**@memoryblock/web**](https://www.npmjs.com/package/@memoryblock/web) - Front-end dashboard and Web UI.
+
+**Plugins**
+*   [**@memoryblock/plugin-installer**](https://www.npmjs.com/package/@memoryblock/plugin-installer) - Plugin installer and registry manager.
+*   [**@memoryblock/plugin-agents**](https://www.npmjs.com/package/@memoryblock/plugin-agents) - Secondary AI agents orchestrator.
+*   [**@memoryblock/plugin-aws**](https://www.npmjs.com/package/@memoryblock/plugin-aws) - AWS integrations.
+*   [**@memoryblock/plugin-fetch-webpage**](https://www.npmjs.com/package/@memoryblock/plugin-fetch-webpage) - Web content fetching and parsing.
+*   [**@memoryblock/plugin-web-search**](https://www.npmjs.com/package/@memoryblock/plugin-web-search) - Web search capabilities.
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.

package/package.json

@@ -1,17 +1,54 @@
 {
   "name": "@memoryblock/tools",
-  "version": "0.1.0-beta",
+  "version": "0.1.2",
   "type": "module",
+  "description": "Standard tool definitions and schemas for memoryblock.",
+  "files": [
+    "dist/"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
-  "dependencies": {
-    "memoryblock": "0.1.0-beta"
-  },
   "scripts": {
     "build": "tsc -p tsconfig.json"
-  }
+  },
+  "dependencies": {
+    "memoryblock": "^0.1.2"
+  },
+  "keywords": [
+    "memoryblock",
+    "mblk",
+    "ai-agent",
+    "assistants",
+    "agents",
+    "automation",
+    "multi-agent",
+    "agentic-framework",
+    "tools",
+    "functions",
+    "schemas",
+    "file",
+    "filesystem",
+    "command-line",
+    "command-line-tools",
+    "command-line-functions",
+    "command-line-schemas"
+  ],
+  "author": {
+    "name": "Ghazi",
+    "url": "https://mgks.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memoryblock-io/memoryblock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/memoryblock-io/memoryblock/issues"
+  },
+  "homepage": "https://memoryblock.io",
+  "funding": "https://github.com/sponsors/mgks",
+  "license": "MIT"
 }

package/src/base.ts

@@ -1,24 +0,0 @@
-import type { ToolDefinition, ToolContext, ToolExecutionResult } from 'memoryblock';
-
-/**
- * Base Tool interface. All built-in and plugin tools must implement this.
- */
-export interface Tool {
-    readonly definition: ToolDefinition;
-    execute(params: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult>;
-}
-
-/**
- * Helper to create a JSON Schema object for tool parameters.
- */
-export function createSchema(
-    properties: Record<string, { type: string; description: string; enum?: string[] }>,
-    required: string[] = [],
-): Record<string, unknown> {
-    return {
-        type: 'object',
-        properties,
-        required,
-        additionalProperties: false,
-    };
-}

package/src/core/channels.ts

@@ -1,47 +0,0 @@
-import type { ToolExecutionResult, ToolContext } from 'memoryblock';
-import type { Tool } from '../base.js';
-import { createSchema } from '../base.js';
-
-/**
- * send_channel_message tool allows the monitor to proactively dispatch
- * a message to a specific bound channel (e.g. Telegram or CLI), rather
- * than just passively replying to the channel that initiated the turn.
- */
-export const dispatchMessageTool: Tool = {
-    definition: {
-        name: 'send_channel_message',
-        description: 'Send a message proactively to a specific active channel (e.g., "telegram" or "cli"). Use this if the founder asks you to send them a message somewhere else.',
-        parameters: createSchema(
-            {
-                channel: { type: 'string', description: 'The exact name of the target channel (e.g., "telegram", "cli").' },
-                content: { type: 'string', description: 'The message content to send.' },
-            },
-            ['channel', 'content'],
-        ),
-        requiresApproval: false,
-    },
-
-    async execute(params: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
-        const target = params.channel as string;
-        const content = params.content as string;
-
-        if (!context.dispatchMessage) {
-            return { content: 'Message dispatching is not supported in the current execution context.', isError: true };
-        }
-
-        try {
-            await context.dispatchMessage(target, content);
-            return {
-                content: `Message successfully dispatched proactively to channel: ${target}`,
-                isError: false,
-            };
-        } catch (err) {
-            return {
-                content: `Failed to dispatch message to channel '${target}': ${(err as Error).message}`,
-                isError: true,
-            };
-        }
-    },
-};
-
-export const channelTools = [dispatchMessageTool];

package/src/core/identity.ts

@@ -1,125 +0,0 @@
-import { promises as fsp } from 'node:fs';
-import { join } from 'node:path';
-import type { ToolExecutionResult } from 'memoryblock';
-import type { Tool } from '../base.js';
-import { createSchema } from '../base.js';
-
-// Resolve workspace root natively without pulling in core directly to avoid cycles
-import { homedir } from 'node:os';
-function getWsRoot(): string {
-    const custom = process.env.MEMORYBLOCK_WS_DIR;
-    return custom ? custom : join(homedir(), '.memoryblock', 'ws');
-}
-
-// ===== update_monitor_identity =====
-export const updateMonitorIdentityTool: Tool = {
-    definition: {
-        name: 'update_monitor_identity',
-        description: 'Update the monitor name and emoji for this block. This changes how you are identified in the system and UI.',
-        parameters: createSchema(
-            {
-                name: { type: 'string', description: 'Your new chosen name (e.g. "Ana", "Nexus").' },
-                emoji: { type: 'string', description: 'A single emoji representing your persona (e.g. "🤖", "🦊").' },
-            },
-            ['name', 'emoji'],
-        ),
-        requiresApproval: true,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        try {
-            // 1. Update config.json
-            const configPath = join(context.blockPath, 'config.json');
-            const configRaw = await fsp.readFile(configPath, 'utf8');
-            const config = JSON.parse(configRaw);
-            
-            config.monitorName = params.name;
-            config.monitorEmoji = params.emoji;
-            
-            await fsp.writeFile(configPath, JSON.stringify(config, null, 2), 'utf8');
-
-            // 2. Update monitor.md to reflect the new identity explicitly
-            const monitorPath = join(context.blockPath, 'monitor.md');
-            let monitorContent = '';
-            try {
-                monitorContent = await fsp.readFile(monitorPath, 'utf8');
-            } catch {
-                // file doesn't exist yet, that's fine
-            }
-
-            const header = `# Identity\nName: ${params.name}\nEmoji: ${params.emoji}\n\n`;
-            
-            // Basic replacement logic if it already has an Identity header
-            if (monitorContent.includes('# Identity')) {
-                monitorContent = monitorContent.replace(/# Identity[\s\S]*?(?=\n#|$)/, header);
-            } else {
-                monitorContent = header + monitorContent;
-            }
-
-            await fsp.writeFile(monitorPath, monitorContent, 'utf8');
-
-            return { 
-                content: `Successfully updated monitor identity to ${params.emoji} ${params.name}. The system will reflect this change on the next interaction.`, 
-                isError: false 
-            };
-        } catch (err) {
-            return { content: `Failed to update monitor identity: ${(err as Error).message}`, isError: true };
-        }
-    },
-};
-
-// ===== update_founder_info =====
-export const updateFounderInfoTool: Tool = {
-    definition: {
-        name: 'update_founder_info',
-        description: 'Update the global founder profile. Use this when the user tells you about themselves (name, work, preferences). This data is globally shared across all your blocks.',
-        parameters: createSchema(
-            {
-                info: { type: 'string', description: 'The new information to append or update about the founder.' },
-                mode: { type: 'string', description: 'Either "append" (add new facts) or "rewrite" (completely rewrite the profile).' },
-            },
-            ['info', 'mode'],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, _context): Promise<ToolExecutionResult> {
-        try {
-            const wsRoot = getWsRoot();
-            const founderPath = join(wsRoot, 'founder.md');
-            
-            let content = '';
-            try {
-                content = await fsp.readFile(founderPath, 'utf8');
-            } catch {
-                // file doesn't exist yet, that's fine
-            }
-
-            const newInfo = params.info as string;
-            const mode = params.mode as string;
-
-            if (mode === 'rewrite') {
-                content = `# Founder Profile\n\n${newInfo}\n`;
-            } else {
-                // append intelligently
-                if (!content.includes('# Founder Profile')) {
-                    content = `# Founder Profile\n\n`;
-                }
-                const timestamp = new Date().toISOString().split('T')[0];
-                content += `\n- [${timestamp}]: ${newInfo}`;
-            }
-
-            await fsp.writeFile(founderPath, content.trim() + '\n', 'utf8');
-
-            return { 
-                content: `Successfully updated global founder profile at ${founderPath}.`, 
-                isError: false 
-            };
-        } catch (err) {
-            return { content: `Failed to update founder profile: ${(err as Error).message}`, isError: true };
-        }
-    },
-};
-
-export const identityTools: Tool[] = [
-    updateMonitorIdentityTool,
-    updateFounderInfoTool,
-];

package/src/dev/index.ts

@@ -1,119 +0,0 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { promises as fsp } from 'node:fs';
-import { join } from 'node:path';
-import type { ToolExecutionResult } from 'memoryblock';
-import type { Tool } from '../base.js';
-import { createSchema } from '../base.js';
-
-const execFileAsync = promisify(execFile);
-const DEV_TIMEOUT = 120_000; // 2 minutes for builds
-const MAX_OUTPUT = 50_000;
-
-/** Find the project root by looking for package.json. */
-async function findProjectRoot(startDir: string): Promise<string> {
-    let dir = startDir;
-    for (let i = 0; i < 10; i++) {
-        try {
-            await fsp.access(join(dir, 'package.json'));
-            return dir;
-        } catch {
-            const parent = join(dir, '..');
-            if (parent === dir) break;
-            dir = parent;
-        }
-    }
-    return startDir;
-}
-
-function truncateOutput(output: string): string {
-    if (output.length > MAX_OUTPUT) {
-        return output.slice(0, MAX_OUTPUT) + `\n...(truncated, ${output.length} total chars)`;
-    }
-    return output;
-}
-
-async function runCommand(command: string, cwd: string): Promise<ToolExecutionResult> {
-    try {
-        const { stdout, stderr } = await execFileAsync('/bin/sh', ['-c', command], {
-            cwd,
-            timeout: DEV_TIMEOUT,
-            maxBuffer: 2 * 1024 * 1024,
-            env: { ...process.env, HOME: process.env.HOME, FORCE_COLOR: '0' },
-        });
-        let output = '';
-        if (stdout) output += stdout;
-        if (stderr) output += (output ? '\n--- stderr ---\n' : '') + stderr;
-        return { content: truncateOutput(output || '(no output)'), isError: false };
-    } catch (err) {
-        const e = err as Error & { stdout?: string; stderr?: string };
-        let msg = e.message;
-        if (e.stdout) msg += '\n' + e.stdout.slice(0, 10_000);
-        if (e.stderr) msg += '\n' + e.stderr.slice(0, 10_000);
-        return { content: truncateOutput(`Command failed: ${msg}`), isError: true };
-    }
-}
-
-// ===== run_lint =====
-export const runLintTool: Tool = {
-    definition: {
-        name: 'run_lint',
-        description: 'Run ESLint.',
-        parameters: createSchema(
-            { path: { type: 'string', description: 'Target path.' } },
-            [],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const projectRoot = await findProjectRoot(context.workingDir || context.blockPath);
-        const target = (params.path as string) || '.';
-        return runCommand(`npx eslint ${target} --no-color 2>&1 || true`, projectRoot);
-    },
-};
-
-// ===== run_build =====
-export const runBuildTool: Tool = {
-    definition: {
-        name: 'run_build',
-        description: 'Run build command.',
-        parameters: createSchema({}, []),
-        requiresApproval: false,
-    },
-    async execute(_params, context): Promise<ToolExecutionResult> {
-        const projectRoot = await findProjectRoot(context.workingDir || context.blockPath);
-        // Try pnpm first, fall back to npm
-        try {
-            await fsp.access(join(projectRoot, 'pnpm-workspace.yaml'));
-            return runCommand('pnpm run build 2>&1', projectRoot);
-        } catch {
-            return runCommand('npm run build 2>&1', projectRoot);
-        }
-    },
-};
-
-// ===== run_test =====
-export const runTestTool: Tool = {
-    definition: {
-        name: 'run_test',
-        description: 'Run tests.',
-        parameters: createSchema(
-            { filter: { type: 'string', description: 'Test filter.' } },
-            [],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const projectRoot = await findProjectRoot(context.workingDir || context.blockPath);
-        const filter = (params.filter as string) || '';
-        try {
-            await fsp.access(join(projectRoot, 'pnpm-workspace.yaml'));
-            return runCommand(`pnpm test ${filter} 2>&1 || true`, projectRoot);
-        } catch {
-            return runCommand(`npm test ${filter} 2>&1 || true`, projectRoot);
-        }
-    },
-};
-
-/** All dev tools. */
-export const devTools: Tool[] = [runLintTool, runBuildTool, runTestTool];

package/src/fs/index.ts

@@ -1,272 +0,0 @@
-import { promises as fsp } from 'node:fs';
-import { join, resolve, relative, isAbsolute } from 'node:path';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import type { ToolExecutionResult, ToolContext } from 'memoryblock';
-import type { Tool } from '../base.js';
-import { createSchema } from '../base.js';
-
-const execFileAsync = promisify(execFile);
-
-// Security: files that must never be read
-const BLOCKED_PATTERNS = ['.env', 'auth.json', '.memoryblock/auth.json'];
-
-function isBlockedPath(filePath: string): boolean {
-    const normalized = filePath.replace(/\\/g, '/');
-    return BLOCKED_PATTERNS.some((p) => normalized.endsWith(p) || normalized.includes(`/${p}`));
-}
-
-/** Resolve a path. Scope is determined by block permissions. */
-function resolvePath(context: ToolContext, targetPath: string): string {
-    const base = context.workingDir || context.blockPath;
-    const resolved = isAbsolute(targetPath) ? targetPath : resolve(base, targetPath);
-    const scope = context.permissions?.scope || 'block';
-
-    if (scope === 'system') {
-        // Unrestricted — still block sensitive files
-        return resolved;
-    }
-
-    // Determine allowed root based on scope
-    const allowedRoot = scope === 'workspace' && context.workspacePath
-        ? context.workspacePath
-        : context.blockPath;
-
-    const rel = relative(allowedRoot, resolved);
-    if (rel.startsWith('..') || isAbsolute(rel)) {
-        const label = scope === 'workspace' ? 'workspace' : 'block directory';
-        throw new Error(`Access denied: path "${targetPath}" is outside the ${label}. Current scope: ${scope}.`);
-    }
-    return resolved;
-}
-
-// ===== read_file =====
-export const readFileTool: Tool = {
-    definition: {
-        name: 'read_file',
-        description: 'Read the contents of a file.',
-        parameters: createSchema(
-            { path: { type: 'string', description: 'Path to the file.' } },
-            ['path'],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const filePath = resolvePath(context, params.path as string);
-        if (isBlockedPath(filePath)) {
-            return { content: 'Access denied: this file is protected.', isError: true };
-        }
-        try {
-            const content = await fsp.readFile(filePath, 'utf-8');
-            // Truncate extremely large files to save tokens
-            if (content.length > 100_000) {
-                return {
-                    content: content.slice(0, 100_000) + `\n...(truncated, ${content.length} total chars. Use search_files to find specific content.)`,
-                    isError: false,
-                };
-            }
-            return { content, isError: false };
-        } catch (err) {
-            return { content: `Failed to read file: ${(err as Error).message}`, isError: true };
-        }
-    },
-};
-
-// ===== write_file =====
-export const writeFileTool: Tool = {
-    definition: {
-        name: 'write_file',
-        description: 'Write content to a file. Creates parent directories if needed.',
-        parameters: createSchema(
-            {
-                path: { type: 'string', description: 'Path to the file.' },
-                content: { type: 'string', description: 'Content to write.' },
-            },
-            ['path', 'content'],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const filePath = resolvePath(context, params.path as string);
-        if (isBlockedPath(filePath)) {
-            return { content: 'Access denied: this file is protected.', isError: true };
-        }
-        try {
-            await fsp.mkdir(join(filePath, '..'), { recursive: true });
-            await fsp.writeFile(filePath, params.content as string, 'utf-8');
-            return { content: `Written: ${params.path}`, isError: false };
-        } catch (err) {
-            return { content: `Failed to write: ${(err as Error).message}`, isError: true };
-        }
-    },
-};
-
-// ===== list_directory =====
-export const listDirectoryTool: Tool = {
-    definition: {
-        name: 'list_directory',
-        description: 'List files and directories in a path.',
-        parameters: createSchema(
-            { path: { type: 'string', description: 'Path to list. Defaults to workspace root.' } },
-            [],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const dirPath = resolvePath(context, (params.path as string) || '.');
-        try {
-            const entries = await fsp.readdir(dirPath, { withFileTypes: true });
-            const listing = entries
-                .map((e) => `${e.isDirectory() ? '📁' : '📄'} ${e.name}`)
-                .join('\n');
-            return { content: listing || '(empty directory)', isError: false };
-        } catch (err) {
-            return { content: `Failed to list: ${(err as Error).message}`, isError: true };
-        }
-    },
-};
-
-// ===== create_directory =====
-export const createDirectoryTool: Tool = {
-    definition: {
-        name: 'create_directory',
-        description: 'Create a directory.',
-        parameters: createSchema(
-            { path: { type: 'string', description: 'Path of the directory to create.' } },
-            ['path'],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const dirPath = resolvePath(context, params.path as string);
-        try {
-            await fsp.mkdir(dirPath, { recursive: true });
-            return { content: `Created: ${params.path}`, isError: false };
-        } catch (err) {
-            return { content: `Failed to create: ${(err as Error).message}`, isError: true };
-        }
-    },
-};
-
-// ===== search_files =====
-export const searchFilesTool: Tool = {
-    definition: {
-        name: 'search_files',
-        description: 'Search for text in files using grep. Returns matching lines with file paths and line numbers.',
-        parameters: createSchema(
-            {
-                query: { type: 'string', description: 'Text to search for.' },
-                path: { type: 'string', description: 'Directory to search in. Defaults to workspace root.' },
-                include: { type: 'string', description: 'File glob pattern to include, e.g. "*.ts".' },
-            },
-            ['query'],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const searchDir = resolvePath(context, (params.path as string) || '.');
-        const query = params.query as string;
-        const include = params.include as string | undefined;
-
-        try {
-            const args = ['-rnI', '--color=never', '-m', '50'];
-            if (include) args.push('--include', include);
-            args.push(query, searchDir);
-
-            const { stdout } = await execFileAsync('grep', args, {
-                timeout: 15_000,
-                maxBuffer: 512 * 1024,
-            });
-            const output = stdout.trim();
-            if (!output) return { content: 'No matches found.', isError: false };
-            // Truncate if too many results
-            if (output.length > 20_000) {
-                return { content: output.slice(0, 20_000) + '\n...(truncated)', isError: false };
-            }
-            return { content: output, isError: false };
-        } catch (err) {
-            const e = err as Error & { code?: number; stdout?: string };
-            if (e.code === 1) return { content: 'No matches found.', isError: false };
-            return { content: `Search failed: ${e.message}`, isError: true };
-        }
-    },
-};
-
-// ===== replace_in_file =====
-export const replaceInFileTool: Tool = {
-    definition: {
-        name: 'replace_in_file',
-        description: 'Find and replace text in a file.',
-        parameters: createSchema(
-            {
-                path: { type: 'string', description: 'File path.' },
-                find: { type: 'string', description: 'Text to find.' },
-                replace: { type: 'string', description: 'Replacement text.' },
-                all: { type: 'string', description: 'Replace all? "true"/"false".' },
-            },
-            ['path', 'find', 'replace'],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const filePath = resolvePath(context, params.path as string);
-        if (isBlockedPath(filePath)) {
-            return { content: 'Access denied: this file is protected.', isError: true };
-        }
-        try {
-            const content = await fsp.readFile(filePath, 'utf-8');
-            const find = params.find as string;
-            const replace = params.replace as string;
-            const replaceAll = (params.all as string) === 'true';
-
-            if (!content.includes(find)) {
-                return { content: `Text not found in ${params.path}. Check exact whitespace/formatting.`, isError: true };
-            }
-
-            const updated = replaceAll
-                ? content.split(find).join(replace)
-                : content.replace(find, replace);
-
-            await fsp.writeFile(filePath, updated, 'utf-8');
-            const count = replaceAll ? content.split(find).length - 1 : 1;
-            return { content: `Replaced ${count} occurrence(s) in ${params.path}`, isError: false };
-        } catch (err) {
-            return { content: `Failed: ${(err as Error).message}`, isError: true };
-        }
-    },
-};
-
-// ===== file_info =====
-export const fileInfoTool: Tool = {
-    definition: {
-        name: 'file_info',
-        description: 'Get file metadata: size, modified date, type.',
-        parameters: createSchema(
-            { path: { type: 'string', description: 'Path to the file or directory.' } },
-            ['path'],
-        ),
-        requiresApproval: false,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const filePath = resolvePath(context, params.path as string);
-        try {
-            const stat = await fsp.stat(filePath);
-            const info = [
-                `Path: ${params.path}`,
-                `Type: ${stat.isDirectory() ? 'directory' : 'file'}`,
-                `Size: ${stat.size} bytes (${(stat.size / 1024).toFixed(1)} KB)`,
-                `Modified: ${stat.mtime.toISOString()}`,
-                `Created: ${stat.birthtime.toISOString()}`,
-            ].join('\n');
-            return { content: info, isError: false };
-        } catch (err) {
-            return { content: `Failed: ${(err as Error).message}`, isError: true };
-        }
-    },
-};
-
-/** All built-in FS tools. */
-export const fsTools: Tool[] = [
-    readFileTool, writeFileTool, listDirectoryTool, createDirectoryTool,
-    searchFilesTool, replaceInFileTool, fileInfoTool,
-];

package/src/index.ts

@@ -1,31 +0,0 @@
-export { ToolRegistry } from './registry.js';
-export type { Tool } from './base.js';
-export { createSchema } from './base.js';
-export { fsTools } from './fs/index.js';
-export { shellTools, isSafeCommand } from './shell/index.js';
-export { devTools } from './dev/index.js';
-export { identityTools } from './core/identity.js';
-export { channelTools } from './core/channels.js';
-
-import { ToolRegistry } from './registry.js';
-import { fsTools } from './fs/index.js';
-import { shellTools } from './shell/index.js';
-import { devTools } from './dev/index.js';
-import { identityTools } from './core/identity.js';
-import { channelTools } from './core/channels.js';
-
-/**
- * Create a ToolRegistry pre-loaded with all built-in tools.
- */
-export function createDefaultRegistry(): ToolRegistry {
-    const registry = new ToolRegistry();
-    
-    // Core built-in tools
-    for (const tool of fsTools) registry.register(tool);
-    for (const tool of shellTools) registry.register(tool);
-    for (const tool of devTools) registry.register(tool);
-    for (const tool of identityTools) registry.register(tool);
-    for (const tool of channelTools) registry.register(tool);
-    
-    return registry;
-}

package/src/registry.ts

@@ -1,108 +0,0 @@
-import type { ToolDefinition, ToolContext, ToolExecutionResult } from 'memoryblock';
-import { log } from 'memoryblock';
-import type { Tool } from './base.js';
-import { ToolSandbox } from './sandbox.js';
-
-/**
- * Central tool registry. Manages built-in tools and dynamically loaded plugin tools.
- * Implements the LIST_TOOLS_AVAILABLE discovery pattern for token optimization.
- * All execution passes through ToolSandbox for permission enforcement.
- */
-export class ToolRegistry {
-    private tools = new Map<string, Tool>();
-
-    /** Register a tool. */
-    register(tool: Tool): void {
-        this.tools.set(tool.definition.name, tool);
-    }
-
-    /** Check if a tool exists. */
-    has(name: string): boolean {
-        return this.tools.has(name);
-    }
-
-    /** Get all tool definitions (for LIST_TOOLS_AVAILABLE). */
-    listTools(): ToolDefinition[] {
-        return Array.from(this.tools.values()).map((t) => t.definition);
-    }
-
-    /**
-     * Get the LIST_TOOLS_AVAILABLE meta-tool definition.
-     * This is the only tool exposed to the LLM on first contact.
-     */
-    getDiscoveryTool(): ToolDefinition {
-        return {
-            name: 'list_tools_available',
-            description: 'Discover all tools available to you. Call this first to see your capabilities.',
-            parameters: { type: 'object', properties: {}, required: [], additionalProperties: false },
-            requiresApproval: false,
-        };
-    }
-
-    /**
-     * Execute a tool by name. 
-     * All calls pass through ToolSandbox BEFORE execution.
-     * Implements graceful degradation — never throws.
-     */
-    async execute(
-        name: string,
-        params: Record<string, unknown>,
-        context: ToolContext,
-    ): Promise<ToolExecutionResult> {
-        // Handle the meta-tool
-        if (name === 'list_tools_available') {
-            const tools = this.listTools();
-            const listing = tools.map((t) => `- **${t.name}**: ${t.description}`).join('\n');
-            return {
-                content: `You have ${tools.length} tools available:\n\n${listing}\n\nCall any tool by name with the required parameters.`,
-                isError: false,
-            };
-        }
-
-        const tool = this.tools.get(name);
-        if (!tool) {
-            // Graceful degradation — never crash
-            return {
-                content: `Tool "${name}" not found. Use list_tools_available to see available tools.`,
-                isError: true,
-            };
-        }
-
-        // ===== SANDBOX GATE =====
-        // Validate BEFORE execution. If denied, the tool never runs.
-        const denied = ToolSandbox.validate(name, params, context);
-        if (denied) {
-            return denied;
-        }
-
-        try {
-            return await tool.execute(params, context);
-        } catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return {
-                content: `Tool "${name}" failed: ${message}`,
-                isError: true,
-            };
-        }
-    }
-
-    /**
-     * Load plugin tools from a dynamic import path.
-     * Uses try/catch for graceful degradation — never crashes if plugin is missing.
-     */
-    async loadPlugin(pluginPath: string): Promise<void> {
-        try {
-            const mod = await import(pluginPath);
-            if (mod.tools && Array.isArray(mod.tools)) {
-                for (const tool of mod.tools as Tool[]) {
-                    this.register(tool);
-                }
-            } else if (mod.default && typeof mod.default === 'object' && 'definition' in mod.default) {
-                this.register(mod.default as Tool);
-            }
-        } catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            log.warn(`Failed to load plugin "${pluginPath}": ${message}`);
-        }
-    }
-}

package/src/sandbox.ts

@@ -1,169 +0,0 @@
-/**
- * ToolSandbox — central enforcement layer for tool execution.
- * 
- * Every tool.execute() call passes through this gate.
- * It intercepts params, scans for file paths, validates them against
- * the block's permission scope, and blocks disallowed operations.
- * 
- * This class is designed as a drop-in replaceable module. Any future
- * enforcement backend can substitute this class as long as it exposes
- * the same static validate() and validateCommand() interface.
- */
-
-import { resolve, relative, isAbsolute } from 'node:path';
-import type { ToolContext, ToolExecutionResult, PermissionsConfig } from 'memoryblock';
-
-// Patterns that look like file paths in tool params
-const PATH_PARAM_NAMES = ['path', 'file', 'filePath', 'directory', 'dir', 'target', 'source', 'destination'];
-
-// Sensitive files that should never be accessible regardless of scope
-const SENSITIVE_PATTERNS = [
-    'auth.json',
-    '.env',
-    '.memoryblock/auth.json',
-    'id_rsa',
-    'id_ed25519',
-    '.ssh/config',
-    '.aws/credentials',
-];
-
-// Shell tools that need special handling
-const SHELL_TOOL_NAMES = ['execute_command', 'run_lint', 'run_build', 'run_test'];
-
-export class ToolSandbox {
-
-    /**
-     * Validate a tool call BEFORE execution.
-     * Returns null if allowed, or an error ToolExecutionResult if denied.
-     */
-    static validate(
-        toolName: string,
-        params: Record<string, unknown>,
-        context: ToolContext,
-    ): ToolExecutionResult | null {
-        const perms = context.permissions || { scope: 'block', allowShell: false, allowNetwork: true, maxTimeout: 120_000 };
-
-        // 1. Shell access check
-        if (SHELL_TOOL_NAMES.includes(toolName)) {
-            if (!perms.allowShell && perms.scope !== 'system') {
-                return {
-                    content: `Denied: "${toolName}" requires shell access. Current scope: "${perms.scope}". Run \`mblk permissions ${context.blockName} --allow-shell\` to grant access.`,
-                    isError: true,
-                };
-            }
-        }
-
-        // 2. Scan all params for file paths and validate
-        const pathViolation = ToolSandbox.scanPaths(params, context, perms);
-        if (pathViolation) {
-            return { content: pathViolation, isError: true };
-        }
-
-        // 3. Check for sensitive file access in any string param
-        const sensitiveHit = ToolSandbox.scanSensitive(params);
-        if (sensitiveHit) {
-            return {
-                content: `Denied: access to "${sensitiveHit}" is blocked for security.`,
-                isError: true,
-            };
-        }
-
-        return null; // Allowed
-    }
-
-    /**
-     * Scan params for file path values and validate against scope.
-     */
-    private static scanPaths(
-        params: Record<string, unknown>,
-        context: ToolContext,
-        perms: PermissionsConfig,
-    ): string | null {
-        if (perms.scope === 'system') return null; // No path restrictions
-
-        for (const [key, value] of Object.entries(params)) {
-            if (typeof value !== 'string') continue;
-
-            // Check named path params
-            const isPathParam = PATH_PARAM_NAMES.some(p =>
-                key.toLowerCase().includes(p.toLowerCase()),
-            );
-
-            // Also check any string that looks like an absolute path
-            const looksLikePath = isPathParam || value.startsWith('/') || value.startsWith('~');
-
-            if (!looksLikePath) continue;
-
-            const resolved = isAbsolute(value)
-                ? value
-                : resolve(context.workingDir || context.blockPath, value);
-
-            const allowedRoot = perms.scope === 'workspace' && context.workspacePath
-                ? context.workspacePath
-                : context.blockPath;
-
-            const rel = relative(allowedRoot, resolved);
-            if (rel.startsWith('..') || isAbsolute(rel)) {
-                const label = perms.scope === 'workspace' ? 'workspace' : 'block directory';
-                return `Denied: "${key}" points to "${value}" which is outside the ${label}. Scope: "${perms.scope}".`;
-            }
-        }
-
-        return null;
-    }
-
-    /**
-     * Check if any string param references a sensitive file.
-     */
-    private static scanSensitive(params: Record<string, unknown>): string | null {
-        for (const value of Object.values(params)) {
-            if (typeof value !== 'string') continue;
-            const normalized = value.replace(/\\/g, '/');
-            for (const pattern of SENSITIVE_PATTERNS) {
-                if (normalized.endsWith(pattern) || normalized.includes(`/${pattern}`)) {
-                    return pattern;
-                }
-            }
-        }
-        return null;
-    }
-
-    /**
-     * Scan a shell command string for path traversal attempts.
-     * Returns an error message if the command looks like it's escaping scope.
-     */
-    static validateCommand(
-        command: string,
-        context: ToolContext,
-    ): string | null {
-        const perms = context.permissions || { scope: 'block', allowShell: false, allowNetwork: true, maxTimeout: 120_000 };
-        if (perms.scope === 'system') return null;
-
-        // Check for common escape patterns in shell commands
-        const escapePatterns = [
-            /\bcd\s+\//,             // cd /absolute
-            /\bcat\s+\//,            // cat /etc/passwd
-            /\bls\s+\//,             // ls / (outside block)
-            />\s*\//,                // redirect to absolute path
-            /\|\s*tee\s+\//,         // pipe to absolute path
-        ];
-
-        // Only flag these in block scope — workspace/system allow broader access
-        if (perms.scope === 'block') {
-            for (const pattern of escapePatterns) {
-                if (pattern.test(command)) {
-                    return `Denied: command appears to access paths outside the block directory. Scope: "block".`;
-                }
-            }
-        }
-
-        // Check for sensitive file access in any scope
-        for (const sensitive of SENSITIVE_PATTERNS) {
-            if (command.includes(sensitive)) {
-                return `Denied: command references sensitive file "${sensitive}".`;
-            }
-        }
-
-        return null;
-    }
-}

package/src/shell/index.ts

@@ -1,96 +0,0 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import type { ToolExecutionResult } from 'memoryblock';
-import type { Tool } from '../base.js';
-import { createSchema } from '../base.js';
-
-const execFileAsync = promisify(execFile);
-const DEFAULT_TIMEOUT = 120_000; // 2 minutes
-const MAX_OUTPUT = 50_000;
-
-// Commands that are safe to auto-execute without approval
-const SAFE_PREFIXES = [
-    'ls', 'cat', 'head', 'tail', 'wc', 'find', 'grep', 'which', 'echo', 'pwd',
-    'node --version', 'bun --version', 'pnpm --version', 'npm --version',
-    'git status', 'git log', 'git diff', 'git branch',
-    'tsc --noEmit', 'npx eslint', 'pnpm lint', 'npm run lint',
-    'pnpm build', 'npm run build', 'pnpm test', 'npm test',
-];
-
-function isSafeCommand(command: string): boolean {
-    const trimmed = command.trim();
-    return SAFE_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
-}
-
-// ===== execute_command =====
-export const executeCommandTool: Tool = {
-    definition: {
-        name: 'execute_command',
-        description: 'Run shell command (Safe cmds run auto).',
-        parameters: createSchema(
-            {
-                command: { type: 'string', description: 'Command.' },
-                timeout: { type: 'string', description: 'Timeout (ms).' },
-            },
-            ['command'],
-        ),
-        // Dynamic approval: overridden at dispatch time based on command safety
-        requiresApproval: true,
-    },
-    async execute(params, context): Promise<ToolExecutionResult> {
-        const command = params.command as string;
-        const scope = context.permissions?.scope || 'block';
-
-        // Permission check: shell access must be explicitly granted
-        if (!context.permissions?.allowShell && scope !== 'system') {
-            return {
-                content: `Shell access denied. Current permission scope: "${scope}". Set allowShell: true or scope: "system" via \`mblk permissions ${context.blockName} --allow-shell\`.`,
-                isError: true,
-            };
-        }
-
-        const timeout = context.permissions?.maxTimeout
-            || (params.timeout ? parseInt(params.timeout as string, 10) : DEFAULT_TIMEOUT);
-
-        // Determine cwd based on scope
-        let cwd = context.workingDir || context.blockPath;
-        if (scope === 'block') {
-            cwd = context.blockPath;
-        } else if (scope === 'workspace' && context.workspacePath) {
-            // Allow commands within workspace, but default cwd to block
-            cwd = context.workingDir || context.blockPath;
-        }
-        // scope === 'system' — use whatever workingDir is set
-
-        try {
-            const { stdout, stderr } = await execFileAsync('/bin/sh', ['-c', command], {
-                cwd,
-                timeout,
-                maxBuffer: 2 * 1024 * 1024,
-                env: { ...process.env, HOME: process.env.HOME },
-            });
-
-            let output = '';
-            if (stdout) output += stdout;
-            if (stderr) output += (output ? '\n--- stderr ---\n' : '') + stderr;
-
-            if (output.length > MAX_OUTPUT) {
-                output = output.slice(0, MAX_OUTPUT) + `\n...(truncated, ${output.length} total chars)`;
-            }
-
-            return { content: output || '(no output)', isError: false };
-        } catch (err) {
-            const error = err as Error & { stdout?: string; stderr?: string; code?: number };
-            let message = error.message;
-            if (error.stdout) message += `\nstdout: ${error.stdout.slice(0, 5000)}`;
-            if (error.stderr) message += `\nstderr: ${error.stderr.slice(0, 5000)}`;
-            return { content: `Command failed: ${message}`, isError: true };
-        }
-    },
-};
-
-/** Check if a command is safe (export for use in approval logic). */
-export { isSafeCommand };
-
-/** All built-in shell tools. */
-export const shellTools: Tool[] = [executeCommandTool];

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-    "extends": "../../tsconfig.json",
-    "compilerOptions": {
-        "outDir": "dist",
-        "rootDir": "src"
-    },
-    "include": [
-        "src"
-    ]
-}