praisonai 1.7.1 → 1.7.3

package/dist/mcp/security.js

@@ -115,6 +115,32 @@ class MCPSecurity {
             return config.requests;
         return Math.max(0, config.requests - state.count);
     }
+    /**
+     * Validate credentials for a given auth method (fail closed by default)
+     */
+    async validateCredentials(auth, token) {
+        switch (auth.method) {
+            case 'none':
+                return true;
+            case 'api-key':
+            case 'bearer':
+                if (auth.validate) {
+                    return auth.validate(token);
+                }
+                if (this.apiKeys.size === 0) {
+                    return false;
+                }
+                return this.validateApiKey(token);
+            case 'basic':
+            case 'oauth':
+                if (!auth.validate) {
+                    return false;
+                }
+                return auth.validate(token);
+            default:
+                return false;
+        }
+    }
     /**
      * Match policy against request
      */
@@ -141,19 +167,16 @@ class MCPSecurity {
             case 'allow':
                 return { allowed: true };
             case 'authenticate':
-                if (!policy.auth)
-                    return { allowed: true };
+                if (!policy.auth) {
+                    return { allowed: false, reason: 'Authentication policy misconfigured' };
+                }
                 const token = request.headers ? this.extractToken(request.headers) : null;
-                if (!token) {
+                if (!token || !token.trim()) {
                     return { allowed: false, reason: 'Authentication required' };
                 }
-                if (policy.auth.method === 'api-key' || policy.auth.method === 'bearer') {
-                    const valid = policy.auth.validate
-                        ? await policy.auth.validate(token)
-                        : this.validateApiKey(token);
-                    if (!valid) {
-                        return { allowed: false, reason: 'Invalid credentials' };
-                    }
+                const valid = await this.validateCredentials(policy.auth, token);
+                if (!valid) {
+                    return { allowed: false, reason: 'Invalid credentials' };
                 }
                 return { allowed: true, context: { authenticated: true } };
             case 'rate-limit':

package/dist/mcp/server.d.ts

@@ -85,6 +85,8 @@ export interface MCPServerConfig {
     port?: number | null;
     /** Enable logging */
     logging?: boolean;
+    /** Optional bearer token for HTTP transport (or set PRAISONAI_MCP_AUTH_TOKEN) */
+    authToken?: string;
 }
 /**
  * MCP Request
@@ -121,6 +123,7 @@ export declare class MCPServer {
     private logging;
     private running;
     private httpServer;
+    private authToken?;
     constructor(config?: MCPServerConfig);
     /**
      * Register a tool
@@ -174,6 +177,10 @@ export declare class MCPServer {
      * Start stdio transport
      */
     startStdio(): Promise<void>;
+    /**
+     * Verify HTTP bearer token when authToken is configured
+     */
+    private verifyHttpAuth;
     /**
      * Start HTTP transport
      */

package/dist/mcp/server.js

@@ -65,6 +65,7 @@ class MCPServer {
         this.resources = new Map();
         this.prompts = new Map();
         this.logging = config.logging ?? false;
+        this.authToken = config.authToken ?? process.env.PRAISONAI_MCP_AUTH_TOKEN ?? undefined;
         // Register initial tools
         if (config.tools) {
             for (const tool of config.tools) {
@@ -315,6 +316,25 @@ class MCPServer {
             this.running = false;
         });
     }
+    /**
+     * Verify HTTP bearer token when authToken is configured
+     */
+    verifyHttpAuth(req) {
+        if (!this.authToken) {
+            return true;
+        }
+        const authHeader = req.headers.authorization ?? req.headers['Authorization'];
+        if (typeof authHeader === 'string') {
+            if (authHeader.startsWith('Bearer ') && authHeader.slice(7) === this.authToken) {
+                return true;
+            }
+        }
+        const xAuth = req.headers['x-auth-token'] ?? req.headers['X-Auth-Token'];
+        if (typeof xAuth === 'string' && xAuth === this.authToken) {
+            return true;
+        }
+        return false;
+    }
     /**
      * Start HTTP transport
      */
@@ -325,6 +345,11 @@ class MCPServer {
         const http = await Promise.resolve().then(() => __importStar(require('http')));
         this.httpServer = http.createServer(async (req, res) => {
             if (req.method === 'POST') {
+                if (!this.verifyHttpAuth(req)) {
+                    res.writeHead(401, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Unauthorized' }));
+                    return;
+                }
                 let body = '';
                 req.on('data', chunk => body += chunk);
                 req.on('end', async () => {

package/dist/os/agentos.js

@@ -112,6 +112,25 @@ class AgentOS {
                 next();
             });
         }
+        // Optional API key middleware (except /health)
+        if (this.config.apiKey) {
+            app.use((req, res, next) => {
+                if (req.path === '/health') {
+                    return next();
+                }
+                const authHeader = req.headers.authorization;
+                if (typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
+                    if (authHeader.slice(7) === this.config.apiKey) {
+                        return next();
+                    }
+                }
+                const xAuth = req.headers['x-auth-token'] ?? req.headers['X-Auth-Token'];
+                if (typeof xAuth === 'string' && xAuth === this.config.apiKey) {
+                    return next();
+                }
+                return res.status(401).json({ error: 'Unauthorized' });
+            });
+        }
         // Register routes
         this._registerRoutes(app);
         return app;

package/dist/os/config.d.ts

@@ -21,7 +21,7 @@
 export interface AgentOSConfig {
     /** Name of the application (default: "PraisonAI App") */
     name?: string;
-    /** Host address to bind to (default: "0.0.0.0") */
+    /** Host address to bind to (default: "127.0.0.1") */
     host?: string;
     /** Port number to listen on (default: 8000) */
     port?: number;
@@ -45,6 +45,8 @@ export interface AgentOSConfig {
     timeout?: number;
     /** Additional metadata for the app */
     metadata?: Record<string, any>;
+    /** Optional API key for route protection (or set PRAISONAI_AGENTOS_API_KEY) */
+    apiKey?: string;
 }
 /**
  * Default configuration values for AgentOS.

package/dist/os/config.js

@@ -22,7 +22,7 @@ exports.mergeConfig = mergeConfig;
  */
 exports.DEFAULT_AGENTOS_CONFIG = {
     name: 'PraisonAI App',
-    host: '0.0.0.0',
+    host: '127.0.0.1',
     port: 8000,
     reload: false,
     corsOrigins: ['*'],
@@ -33,18 +33,26 @@ exports.DEFAULT_AGENTOS_CONFIG = {
     logLevel: 'info',
     workers: 1,
     timeout: 60,
+    apiKey: '',
     metadata: {},
 };
 /**
  * Merge user config with defaults.
  */
 function mergeConfig(userConfig) {
-    return {
+    const apiKey = userConfig?.apiKey ?? process.env.PRAISONAI_AGENTOS_API_KEY ?? '';
+    const merged = {
         ...exports.DEFAULT_AGENTOS_CONFIG,
         ...userConfig,
+        apiKey,
         metadata: {
             ...exports.DEFAULT_AGENTOS_CONFIG.metadata,
             ...userConfig?.metadata,
         },
     };
+    const exposedHosts = new Set(['0.0.0.0', '::', '::0']);
+    if (exposedHosts.has(merged.host) && !merged.apiKey) {
+        throw new Error('AgentOS requires apiKey (or PRAISONAI_AGENTOS_API_KEY) when binding to a network-exposed host');
+    }
+    return merged;
 }

package/dist/tools/builtins/code-mode.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CODE_MODE_METADATA = void 0;
 exports.codeMode = codeMode;
 exports.createCodeModeTool = createCodeModeTool;
+const node_vm_1 = require("node:vm");
 exports.CODE_MODE_METADATA = {
     id: 'code-mode',
     displayName: 'Code Mode',
@@ -69,6 +70,10 @@ function codeMode(config) {
                 /import\s+.*from\s+['"]child_process['"]/,
                 /process\.exit/,
                 /eval\s*\(/,
+                /Function\s*\(/,
+                /\.constructor/,
+                /globalThis/,
+                /\bprocess\b/,
             ];
             if (!settings.allowNetwork) {
                 blockedPatterns.push(/require\s*\(\s*['"]http['"]\s*\)/, /require\s*\(\s*['"]https['"]\s*\)/, /require\s*\(\s*['"]net['"]\s*\)/, /fetch\s*\(/);
@@ -101,37 +106,32 @@ function codeMode(config) {
                 }
             }
             try {
-                // Create a sandboxed execution context
-                // In a real implementation, this would use a proper sandbox like vm2 or isolated-vm
-                // For now, we provide a safe execution wrapper
-                const sandbox = {
+                const stdout = [];
+                const stderr = [];
+                const sandboxContext = {
                     console: {
                         log: (...args) => stdout.push(args.map(String).join(' ')),
                         error: (...args) => stderr.push(args.map(String).join(' ')),
                         warn: (...args) => stderr.push(args.map(String).join(' ')),
                     },
-                    setTimeout: undefined,
-                    setInterval: undefined,
-                    setImmediate: undefined,
-                    process: undefined,
-                    require: undefined,
                     __dirname: '/sandbox',
                     __filename: '/sandbox/index.js',
                     env: env || {},
                     files: files || {},
                 };
-                const stdout = [];
-                const stderr = [];
-                // Execute with timeout
                 const timeoutPromise = new Promise((_, reject) => {
                     setTimeout(() => reject(new Error('Execution timeout')), settings.timeoutMs);
                 });
                 const executePromise = new Promise((resolve, reject) => {
                     try {
-                        // Create a function from the code
-                        const fn = new Function('sandbox', `with (sandbox) { ${code} }`);
-                        const result = fn(sandbox);
-                        resolve(String(result ?? ''));
+                        const wrappedCode = `(async function() { ${code} })()`;
+                        const result = (0, node_vm_1.runInNewContext)(wrappedCode, sandboxContext, {
+                            timeout: settings.timeoutMs,
+                            displayErrors: true,
+                        });
+                        Promise.resolve(result)
+                            .then((value) => resolve(String(value ?? '')))
+                            .catch(reject);
                     }
                     catch (error) {
                         reject(error);

package/dist/tools/index.d.ts

@@ -1,8 +1,11 @@
 export { BaseTool, ToolResult, ToolValidationError, validateTool, createTool, type ToolParameters } from './base';
-export * from './decorator';
+export { tool, FunctionTool, ToolRegistry, getRegistry, registerTool, getTool, type ToolConfig, type ToolContext, } from './decorator';
 export * from './arxivTools';
 export * from './mcpSse';
-export * from './registry';
+export { ToolsRegistry, getToolsRegistry, createToolsRegistry, resetToolsRegistry, get_registry, get_tool, register_tool, validate_tool, } from './registry';
+export type { ToolExecutionContext, ToolLimits, RedactionHooks, ToolLogger, ToolCapabilities, InstallHints, ToolMetadata, ToolExecutionResult, PraisonTool, ToolParameterSchema, ToolParameterProperty, ToolMiddleware, ToolHooks, ToolFactory, RegisteredTool, ToolInstallStatus, } from './registry';
+export { MissingDependencyError, MissingEnvVarError, BudgetExceededError } from './registry';
+export { createLoggingMiddleware, createTimeoutMiddleware, createRedactionMiddleware, createRateLimitMiddleware, createRetryMiddleware, createTracingMiddleware, createValidationMiddleware, composeMiddleware, } from './registry';
 export * from './builtins';
 export { tools, registerBuiltinTools } from './tools';
 export type { default as ToolsFacade } from './tools';

package/dist/tools/index.js

@@ -14,20 +14,47 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDelegator = exports.createSubagentTools = exports.createSubagentTool = exports.SubagentTool = exports.registerBuiltinTools = exports.tools = exports.createTool = exports.validateTool = exports.ToolValidationError = exports.BaseTool = void 0;
+exports.createDelegator = exports.createSubagentTools = exports.createSubagentTool = exports.SubagentTool = exports.registerBuiltinTools = exports.tools = exports.composeMiddleware = exports.createValidationMiddleware = exports.createTracingMiddleware = exports.createRetryMiddleware = exports.createRateLimitMiddleware = exports.createRedactionMiddleware = exports.createTimeoutMiddleware = exports.createLoggingMiddleware = exports.BudgetExceededError = exports.MissingEnvVarError = exports.MissingDependencyError = exports.validate_tool = exports.register_tool = exports.get_tool = exports.get_registry = exports.resetToolsRegistry = exports.createToolsRegistry = exports.getToolsRegistry = exports.ToolsRegistry = exports.getTool = exports.registerTool = exports.getRegistry = exports.ToolRegistry = exports.FunctionTool = exports.tool = exports.createTool = exports.validateTool = exports.ToolValidationError = exports.BaseTool = void 0;
 // Export base tool interfaces and classes
 var base_1 = require("./base");
 Object.defineProperty(exports, "BaseTool", { enumerable: true, get: function () { return base_1.BaseTool; } });
 Object.defineProperty(exports, "ToolValidationError", { enumerable: true, get: function () { return base_1.ToolValidationError; } });
 Object.defineProperty(exports, "validateTool", { enumerable: true, get: function () { return base_1.validateTool; } });
 Object.defineProperty(exports, "createTool", { enumerable: true, get: function () { return base_1.createTool; } });
-// Export decorator and registry (legacy)
-__exportStar(require("./decorator"), exports);
+// Legacy @tool decorator registry (camelCase names reserved for this API)
+var decorator_1 = require("./decorator");
+Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return decorator_1.tool; } });
+Object.defineProperty(exports, "FunctionTool", { enumerable: true, get: function () { return decorator_1.FunctionTool; } });
+Object.defineProperty(exports, "ToolRegistry", { enumerable: true, get: function () { return decorator_1.ToolRegistry; } });
+Object.defineProperty(exports, "getRegistry", { enumerable: true, get: function () { return decorator_1.getRegistry; } });
+Object.defineProperty(exports, "registerTool", { enumerable: true, get: function () { return decorator_1.registerTool; } });
+Object.defineProperty(exports, "getTool", { enumerable: true, get: function () { return decorator_1.getTool; } });
 // Export all tool modules
 __exportStar(require("./arxivTools"), exports);
 __exportStar(require("./mcpSse"), exports);
-// Export new registry system
-__exportStar(require("./registry"), exports);
+// New AI SDK tools registry — snake_case parity names (avoid camelCase clash with decorator)
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "ToolsRegistry", { enumerable: true, get: function () { return registry_1.ToolsRegistry; } });
+Object.defineProperty(exports, "getToolsRegistry", { enumerable: true, get: function () { return registry_1.getToolsRegistry; } });
+Object.defineProperty(exports, "createToolsRegistry", { enumerable: true, get: function () { return registry_1.createToolsRegistry; } });
+Object.defineProperty(exports, "resetToolsRegistry", { enumerable: true, get: function () { return registry_1.resetToolsRegistry; } });
+Object.defineProperty(exports, "get_registry", { enumerable: true, get: function () { return registry_1.get_registry; } });
+Object.defineProperty(exports, "get_tool", { enumerable: true, get: function () { return registry_1.get_tool; } });
+Object.defineProperty(exports, "register_tool", { enumerable: true, get: function () { return registry_1.register_tool; } });
+Object.defineProperty(exports, "validate_tool", { enumerable: true, get: function () { return registry_1.validate_tool; } });
+var registry_2 = require("./registry");
+Object.defineProperty(exports, "MissingDependencyError", { enumerable: true, get: function () { return registry_2.MissingDependencyError; } });
+Object.defineProperty(exports, "MissingEnvVarError", { enumerable: true, get: function () { return registry_2.MissingEnvVarError; } });
+Object.defineProperty(exports, "BudgetExceededError", { enumerable: true, get: function () { return registry_2.BudgetExceededError; } });
+var registry_3 = require("./registry");
+Object.defineProperty(exports, "createLoggingMiddleware", { enumerable: true, get: function () { return registry_3.createLoggingMiddleware; } });
+Object.defineProperty(exports, "createTimeoutMiddleware", { enumerable: true, get: function () { return registry_3.createTimeoutMiddleware; } });
+Object.defineProperty(exports, "createRedactionMiddleware", { enumerable: true, get: function () { return registry_3.createRedactionMiddleware; } });
+Object.defineProperty(exports, "createRateLimitMiddleware", { enumerable: true, get: function () { return registry_3.createRateLimitMiddleware; } });
+Object.defineProperty(exports, "createRetryMiddleware", { enumerable: true, get: function () { return registry_3.createRetryMiddleware; } });
+Object.defineProperty(exports, "createTracingMiddleware", { enumerable: true, get: function () { return registry_3.createTracingMiddleware; } });
+Object.defineProperty(exports, "createValidationMiddleware", { enumerable: true, get: function () { return registry_3.createValidationMiddleware; } });
+Object.defineProperty(exports, "composeMiddleware", { enumerable: true, get: function () { return registry_3.composeMiddleware; } });
 // Export built-in tools
 __exportStar(require("./builtins"), exports);
 // Export tools facade

package/dist/tools/registry/index.d.ts

@@ -4,6 +4,6 @@
  * Lazy-loaded exports for the tools registry system.
  */
 export type { ToolExecutionContext, ToolLimits, RedactionHooks, ToolLogger, ToolCapabilities, InstallHints, ToolMetadata, ToolExecutionResult, PraisonTool, ToolParameterSchema, ToolParameterProperty, ToolMiddleware, ToolHooks, ToolFactory, RegisteredTool, ToolInstallStatus, } from './types';
-export { MissingDependencyError, MissingEnvVarError } from './types';
-export { ToolsRegistry, getToolsRegistry, createToolsRegistry, resetToolsRegistry, } from './registry';
+export { MissingDependencyError, MissingEnvVarError, BudgetExceededError } from './types';
+export { ToolsRegistry, getToolsRegistry, createToolsRegistry, resetToolsRegistry, get_registry, getRegistry, get_tool, getTool, register_tool, registerTool, validate_tool, validateTool, } from './registry';
 export { createLoggingMiddleware, createTimeoutMiddleware, createRedactionMiddleware, createRateLimitMiddleware, createRetryMiddleware, createTracingMiddleware, createValidationMiddleware, composeMiddleware, } from './middleware';

package/dist/tools/registry/index.js

@@ -5,17 +5,26 @@
  * Lazy-loaded exports for the tools registry system.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.composeMiddleware = exports.createValidationMiddleware = exports.createTracingMiddleware = exports.createRetryMiddleware = exports.createRateLimitMiddleware = exports.createRedactionMiddleware = exports.createTimeoutMiddleware = exports.createLoggingMiddleware = exports.resetToolsRegistry = exports.createToolsRegistry = exports.getToolsRegistry = exports.ToolsRegistry = exports.MissingEnvVarError = exports.MissingDependencyError = void 0;
+exports.composeMiddleware = exports.createValidationMiddleware = exports.createTracingMiddleware = exports.createRetryMiddleware = exports.createRateLimitMiddleware = exports.createRedactionMiddleware = exports.createTimeoutMiddleware = exports.createLoggingMiddleware = exports.validateTool = exports.validate_tool = exports.registerTool = exports.register_tool = exports.getTool = exports.get_tool = exports.getRegistry = exports.get_registry = exports.resetToolsRegistry = exports.createToolsRegistry = exports.getToolsRegistry = exports.ToolsRegistry = exports.BudgetExceededError = exports.MissingEnvVarError = exports.MissingDependencyError = void 0;
 // Errors
 var types_1 = require("./types");
 Object.defineProperty(exports, "MissingDependencyError", { enumerable: true, get: function () { return types_1.MissingDependencyError; } });
 Object.defineProperty(exports, "MissingEnvVarError", { enumerable: true, get: function () { return types_1.MissingEnvVarError; } });
+Object.defineProperty(exports, "BudgetExceededError", { enumerable: true, get: function () { return types_1.BudgetExceededError; } });
 // Registry
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "ToolsRegistry", { enumerable: true, get: function () { return registry_1.ToolsRegistry; } });
 Object.defineProperty(exports, "getToolsRegistry", { enumerable: true, get: function () { return registry_1.getToolsRegistry; } });
 Object.defineProperty(exports, "createToolsRegistry", { enumerable: true, get: function () { return registry_1.createToolsRegistry; } });
 Object.defineProperty(exports, "resetToolsRegistry", { enumerable: true, get: function () { return registry_1.resetToolsRegistry; } });
+Object.defineProperty(exports, "get_registry", { enumerable: true, get: function () { return registry_1.get_registry; } });
+Object.defineProperty(exports, "getRegistry", { enumerable: true, get: function () { return registry_1.getRegistry; } });
+Object.defineProperty(exports, "get_tool", { enumerable: true, get: function () { return registry_1.get_tool; } });
+Object.defineProperty(exports, "getTool", { enumerable: true, get: function () { return registry_1.getTool; } });
+Object.defineProperty(exports, "register_tool", { enumerable: true, get: function () { return registry_1.register_tool; } });
+Object.defineProperty(exports, "registerTool", { enumerable: true, get: function () { return registry_1.registerTool; } });
+Object.defineProperty(exports, "validate_tool", { enumerable: true, get: function () { return registry_1.validate_tool; } });
+Object.defineProperty(exports, "validateTool", { enumerable: true, get: function () { return registry_1.validateTool; } });
 // Middleware
 var middleware_1 = require("./middleware");
 Object.defineProperty(exports, "createLoggingMiddleware", { enumerable: true, get: function () { return middleware_1.createLoggingMiddleware; } });

package/dist/tools/registry/registry.d.ts

@@ -90,3 +90,36 @@ export declare function createToolsRegistry(): ToolsRegistry;
  * Reset the global registry (mainly for testing)
  */
 export declare function resetToolsRegistry(): void;
+/**
+ * Get the global registry instance (alias for getToolsRegistry)
+ * For Python SDK parity: get_registry()
+ */
+export declare function get_registry(): ToolsRegistry;
+/** camelCase alias for get_registry — idiomatic TypeScript */
+export declare const getRegistry: typeof get_registry;
+/**
+ * Get a single tool by name from the global registry
+ * For Python SDK parity: get_tool()
+ */
+export declare function get_tool<TConfig = unknown, TInput = unknown, TOutput = unknown>(id: string, config?: TConfig): PraisonTool<TInput, TOutput> | null;
+/** camelCase alias for get_tool — idiomatic TypeScript */
+export declare const getTool: typeof get_tool;
+/**
+ * Register a tool with the global registry
+ * For Python SDK parity: register_tool()
+ */
+export declare function register_tool(metadata: ToolMetadata, factory: ToolFactory): void;
+/** camelCase alias for register_tool — idiomatic TypeScript */
+export declare const registerTool: typeof register_tool;
+/**
+ * Validate a tool's configuration and dependencies
+ * For Python SDK parity: validate_tool()
+ */
+export declare function validate_tool(id: string): Promise<{
+    valid: boolean;
+    installed: boolean;
+    missingEnvVars: string[];
+    errors: string[];
+}>;
+/** camelCase alias for validate_tool — idiomatic TypeScript */
+export declare const validateTool: typeof validate_tool;

package/dist/tools/registry/registry.js

@@ -39,10 +39,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolsRegistry = void 0;
+exports.validateTool = exports.registerTool = exports.getTool = exports.getRegistry = exports.ToolsRegistry = void 0;
 exports.getToolsRegistry = getToolsRegistry;
 exports.createToolsRegistry = createToolsRegistry;
 exports.resetToolsRegistry = resetToolsRegistry;
+exports.get_registry = get_registry;
+exports.get_tool = get_tool;
+exports.register_tool = register_tool;
+exports.validate_tool = validate_tool;
 /**
  * Tools Registry - Manages tool registration, lookup, and instantiation
  */
@@ -278,3 +282,77 @@ function resetToolsRegistry() {
     }
     globalRegistry = null;
 }
+/**
+ * Get the global registry instance (alias for getToolsRegistry)
+ * For Python SDK parity: get_registry()
+ */
+function get_registry() {
+    return getToolsRegistry();
+}
+/** camelCase alias for get_registry — idiomatic TypeScript */
+exports.getRegistry = get_registry;
+/**
+ * Get a single tool by name from the global registry
+ * For Python SDK parity: get_tool()
+ */
+function get_tool(id, config) {
+    try {
+        const registry = getToolsRegistry();
+        return registry.create(id, config);
+    }
+    catch {
+        return null;
+    }
+}
+/** camelCase alias for get_tool — idiomatic TypeScript */
+exports.getTool = get_tool;
+/**
+ * Register a tool with the global registry
+ * For Python SDK parity: register_tool()
+ */
+function register_tool(metadata, factory) {
+    const registry = getToolsRegistry();
+    registry.register(metadata, factory);
+}
+/** camelCase alias for register_tool — idiomatic TypeScript */
+exports.registerTool = register_tool;
+/**
+ * Validate a tool's configuration and dependencies
+ * For Python SDK parity: validate_tool()
+ */
+async function validate_tool(id) {
+    const registry = getToolsRegistry();
+    if (!registry.has(id)) {
+        return {
+            valid: false,
+            installed: false,
+            missingEnvVars: [],
+            errors: [`Tool "${id}" is not registered`]
+        };
+    }
+    const status = await registry.getInstallStatus(id);
+    if (!status) {
+        return {
+            valid: false,
+            installed: false,
+            missingEnvVars: [],
+            errors: [`Failed to get status for tool "${id}"`]
+        };
+    }
+    const errors = [];
+    if (!status.installed) {
+        const installCmd = status.installCommand ?? `npm install ${registry.getMetadata(id)?.packageName ?? id}`;
+        errors.push(`Package dependency not installed. Run: ${installCmd}`);
+    }
+    if (status.missingEnvVars.length > 0) {
+        errors.push(`Missing environment variables: ${status.missingEnvVars.join(', ')}`);
+    }
+    return {
+        valid: status.installed && status.missingEnvVars.length === 0,
+        installed: status.installed,
+        missingEnvVars: status.missingEnvVars,
+        errors
+    };
+}
+/** camelCase alias for validate_tool — idiomatic TypeScript */
+exports.validateTool = validate_tool;

package/dist/tools/registry/types.d.ts

@@ -215,3 +215,20 @@ export declare class MissingEnvVarError extends Error {
     readonly docsSlug: string;
     constructor(toolId: string, envVar: string, docsSlug: string);
 }
+/**
+ * Error thrown when an agent exceeds its budget/cost limit.
+ * Mirrors Python SDK: BudgetExceededError(agent_name, total_cost, max_budget)
+ *
+ * Usage:
+ *   try { await agent.start("..."); }
+ *   catch (e) {
+ *     if (e instanceof BudgetExceededError)
+ *       console.log(`Agent '${e.agentName}' spent $${e.totalCost} of $${e.maxBudget}`);
+ *   }
+ */
+export declare class BudgetExceededError extends Error {
+    readonly agentName: string;
+    readonly totalCost: number;
+    readonly maxBudget: number;
+    constructor(agentName: string, totalCost: number, maxBudget: number);
+}

package/dist/tools/registry/types.js

@@ -5,7 +5,7 @@
  * Standard interfaces for tool registration, execution, and middleware.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MissingEnvVarError = exports.MissingDependencyError = void 0;
+exports.BudgetExceededError = exports.MissingEnvVarError = exports.MissingDependencyError = void 0;
 /**
  * Error thrown when optional dependency is missing
  */
@@ -47,3 +47,24 @@ class MissingEnvVarError extends Error {
     }
 }
 exports.MissingEnvVarError = MissingEnvVarError;
+/**
+ * Error thrown when an agent exceeds its budget/cost limit.
+ * Mirrors Python SDK: BudgetExceededError(agent_name, total_cost, max_budget)
+ *
+ * Usage:
+ *   try { await agent.start("..."); }
+ *   catch (e) {
+ *     if (e instanceof BudgetExceededError)
+ *       console.log(`Agent '${e.agentName}' spent $${e.totalCost} of $${e.maxBudget}`);
+ *   }
+ */
+class BudgetExceededError extends Error {
+    constructor(agentName, totalCost, maxBudget) {
+        super(`Agent '${agentName}' exceeded budget: $${totalCost.toFixed(4)} >= $${maxBudget.toFixed(4)}`);
+        this.agentName = agentName;
+        this.totalCost = totalCost;
+        this.maxBudget = maxBudget;
+        this.name = 'BudgetExceededError';
+    }
+}
+exports.BudgetExceededError = BudgetExceededError;

package/dist/tools/utility-tools.js

@@ -250,22 +250,52 @@ async function scrapeUrl(url) {
 // ============================================================================
 // UTILITY TOOLS
 // ============================================================================
+/** Shell metacharacters that enable command chaining or substitution */
+const SHELL_METACHAR_PATTERN = /[;|&`><]|\$\([^)]*\)|\$\{/;
+function containsShellMetacharacters(command) {
+    return SHELL_METACHAR_PATTERN.test(command);
+}
+function parseCommandParts(command) {
+    const parts = command.trim().match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    return parts.map((part) => part.replace(/^["']|["']$/g, ''));
+}
 /**
  * Execute shell command (safe version - read-only commands)
  */
 async function shell(command) {
-    // Only allow safe read-only commands
     const safeCommands = ['ls', 'cat', 'head', 'tail', 'wc', 'grep', 'find', 'echo', 'date', 'pwd', 'which'];
-    const firstWord = command.split(/\s+/)[0];
-    if (!safeCommands.includes(firstWord)) {
-        return { success: false, error: `Command not allowed: ${firstWord}` };
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return { success: false, error: 'Empty command' };
+    }
+    if (containsShellMetacharacters(trimmed)) {
+        return { success: false, error: 'Shell metacharacters are not allowed' };
+    }
+    const parts = parseCommandParts(trimmed);
+    const cmd = parts[0];
+    if (!safeCommands.includes(cmd)) {
+        return { success: false, error: `Command not allowed: ${cmd}` };
     }
     try {
-        const { exec } = await Promise.resolve().then(() => __importStar(require('child_process')));
-        const { promisify } = await Promise.resolve().then(() => __importStar(require('util')));
-        const execAsync = promisify(exec);
-        const { stdout, stderr } = await execAsync(command, { timeout: 5000 });
-        return { success: true, data: stdout || stderr };
+        const { spawn } = await Promise.resolve().then(() => __importStar(require('child_process')));
+        const result = await new Promise((resolve, reject) => {
+            const proc = spawn(cmd, parts.slice(1), {
+                shell: false,
+                timeout: 5000,
+            });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout?.on('data', (data) => { stdout += data.toString(); });
+            proc.stderr?.on('data', (data) => { stderr += data.toString(); });
+            proc.on('close', (code) => {
+                resolve({ stdout, stderr, code: code ?? 1 });
+            });
+            proc.on('error', reject);
+        });
+        if (result.code !== 0) {
+            return { success: false, error: result.stderr || `Exit code ${result.code}` };
+        }
+        return { success: true, data: result.stdout || result.stderr };
     }
     catch (error) {
         return { success: false, error: error.message ?? String(error) };