# @push.rocks/smartagent A dual-agent agentic framework with **Driver** and **Guardian** agents for safe, policy-controlled AI task execution. πŸ€–πŸ›‘οΈ ## Install ```bash npm install @push.rocks/smartagent # or pnpm install @push.rocks/smartagent ``` ## Issue Reporting and Security For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly. ## Overview SmartAgent implements a **dual-agent architecture** where AI safety isn't just an afterthoughtβ€”it's baked into the core design: - **🎯 Driver Agent**: The executor. Reasons about goals, plans steps, and proposes tool calls - **πŸ›‘οΈ Guardian Agent**: The gatekeeper. Evaluates every tool call against your policy, approving or rejecting with feedback This design ensures safe tool use through **AI-based policy evaluation** rather than rigid programmatic rules. The Guardian can understand context, nuance, and intentβ€”catching dangerous operations that simple regex or allowlists would miss. ### Why Dual-Agent? Traditional AI agents have a fundamental problem: they're given tools and expected to use them responsibly. SmartAgent adds a second AI specifically trained to evaluate whether each action is safe and appropriate. Think of it as separation of concerns, but for AI safety. ## Architecture ```mermaid flowchart TB subgraph Input Task["User Task"] Policy["Guardian Policy Prompt"] end subgraph Orchestrator["DualAgentOrchestrator"] Registry["ToolRegistry
Visibility & Lifecycle"] Driver["Driver Agent
Reason + Plan"] Guardian["Guardian Agent
Evaluate against policy"] Driver -->|"tool call proposal"| Guardian Guardian -->|"approve / reject + feedback"| Driver Registry -->|"visible tools"| Driver end subgraph Tools["Tools"] Initial["Initial Tools
Always visible"] OnDemand["On-Demand Tools
Discoverable via search"] Experts["Expert SubAgents
Specialized agents as tools"] end Task --> Orchestrator Policy --> Guardian Driver -->|"execute
(if approved)"| Tools Tools -->|"result"| Driver ``` ## Quick Start ```typescript import { DualAgentOrchestrator } from '@push.rocks/smartagent'; // Create orchestrator with Guardian policy const orchestrator = new DualAgentOrchestrator({ openaiToken: 'sk-...', defaultProvider: 'openai', guardianPolicyPrompt: ` FILE SYSTEM POLICY: - ONLY allow reading/writing within /tmp or the current working directory - REJECT operations on system directories or sensitive files SHELL POLICY: - Allow read-only commands (ls, cat, grep, echo) - REJECT destructive commands (rm, mv, chmod) without explicit justification FLAG any attempt to expose secrets or credentials. `, }); // Register standard tools orchestrator.registerStandardTools(); // Start the orchestrator (initializes all tools) await orchestrator.start(); // Run a task const result = await orchestrator.run('List all TypeScript files in the current directory'); console.log('Success:', result.success); console.log('Result:', result.result); console.log('Iterations:', result.iterations); // Cleanup await orchestrator.stop(); ``` ## Standard Tools SmartAgent comes with five battle-tested tools out of the box via `registerStandardTools()`: ### πŸ—‚οΈ FilesystemTool File and directory operations powered by `@push.rocks/smartfs`. **Actions**: `read`, `write`, `append`, `list`, `delete`, `exists`, `stat`, `copy`, `move`, `mkdir` ```typescript // Example tool call by Driver filesystem read {"path": "/tmp/config.json"} Need to read the configuration file to understand the settings ``` **Scoped Filesystem**: Lock file operations to a specific directory with optional exclusion patterns: ```typescript // Only allow access within a specific directory orchestrator.registerScopedFilesystemTool('/home/user/workspace'); // With exclusion patterns (glob syntax) orchestrator.registerScopedFilesystemTool('/home/user/workspace', [ '.nogit/**', 'node_modules/**', '*.secret', ]); ``` **Line-range Reading**: Read specific portions of large files: ```typescript filesystem read {"path": "/var/log/app.log", "startLine": 100, "endLine": 150} Reading only the relevant log section to avoid token overload ``` ### 🌐 HttpTool HTTP requests using `@push.rocks/smartrequest`. **Actions**: `get`, `post`, `put`, `patch`, `delete` ```typescript http get {"url": "https://api.example.com/data", "headers": {"Authorization": "Bearer token"}} Fetching data from the API endpoint ``` ### πŸ’» ShellTool Secure shell command execution using `@push.rocks/smartshell` with `execSpawn` (no shell injection possible). **Actions**: `execute`, `which` ```typescript shell execute {"command": "ls", "args": ["-la", "/tmp"]} Listing directory contents to find relevant files ``` > πŸ”’ **Security Note**: The shell tool uses `execSpawn` with `shell: false`, meaning command and arguments are passed separately. This makes shell injection attacks impossible. ### 🌍 BrowserTool Web page interaction using `@push.rocks/smartbrowser` (Puppeteer-based). **Actions**: `screenshot`, `pdf`, `evaluate`, `getPageContent` ```typescript browser getPageContent {"url": "https://example.com"} Extracting text content from the webpage ``` ### πŸ¦• DenoTool Execute TypeScript/JavaScript code in a **sandboxed Deno environment** with fine-grained permission control. **Actions**: `execute`, `executeWithResult` **Permissions**: `all`, `env`, `ffi`, `hrtime`, `net`, `read`, `run`, `sys`, `write` By default, code runs **fully sandboxed with no permissions**. Permissions must be explicitly requested and are subject to Guardian approval. ```typescript // Simple code execution (sandboxed, no permissions) deno execute {"code": "console.log('Hello from Deno!')"} Running a simple script to verify the environment // Code with network permission deno execute { "code": "const resp = await fetch('https://api.example.com/data'); console.log(await resp.json());", "permissions": ["net"] } Fetching data from API using Deno's fetch // Execute and parse JSON result deno executeWithResult { "code": "const result = { sum: 2 + 2, date: new Date().toISOString() }; console.log(JSON.stringify(result));" } Computing values and returning structured data ``` ## Additional Tools ### πŸ“‹ JsonValidatorTool Validate and format JSON data. Perfect for agents to self-check their JSON output before completing tasks. **Actions**: `validate`, `format` ```typescript import { JsonValidatorTool } from '@push.rocks/smartagent'; // Register the JSON validator tool (not included in registerStandardTools) orchestrator.registerTool(new JsonValidatorTool()); ``` ```typescript // Validate JSON with required field checking json validate { "jsonString": "{\"name\": \"test\", \"version\": \"1.0.0\"}", "requiredFields": ["name", "version", "description"] } Ensuring the config has all required fields before saving // Pretty-print JSON json format {"jsonString": "{\"compact\":true,\"data\":[1,2,3]}"} Formatting JSON for readable output ``` ### πŸ” ToolSearchTool Enable the Driver to discover and activate on-demand tools at runtime. **Actions**: `search`, `list`, `activate`, `details` ```typescript // Enable tool search (adds the 'tools' tool) orchestrator.enableToolSearch(); ``` ```typescript // Search for tools by capability tools search {"query": "database"} // List all available tools tools list {} // Activate an on-demand tool tools activate {"name": "database_expert"} // Get detailed information about a tool tools details {"name": "filesystem"} ``` ### 🧠 ExpertTool (SubAgents) Create specialized sub-agents that can be invoked as tools. Experts are complete `DualAgentOrchestrator` instances wrapped as tools, enabling hierarchical agent architectures. **Actions**: `consult` ```typescript // Register an expert for code review orchestrator.registerExpert({ name: 'code_reviewer', description: 'Reviews code for quality, bugs, and best practices', systemMessage: `You are an expert code reviewer. Analyze code for: - Bugs and potential issues - Code style and best practices - Performance concerns - Security vulnerabilities`, guardianPolicy: 'Allow read-only file access within the workspace', tools: [new FilesystemTool()], visibility: 'on-demand', // Only available via tool search tags: ['code', 'review', 'quality'], category: 'expert', }); ``` ```typescript // Consult an expert code_reviewer consult { "task": "Review this function for potential issues", "context": "This is a user authentication handler" } ``` ## 🎯 Tool Visibility System SmartAgent supports **tool visibility modes** for scalable agent architectures: - **`initial`** (default): Tool is visible to the Driver from the start, included in the system prompt - **`on-demand`**: Tool is hidden until explicitly activated via `tools.activate()` This enables you to have many specialized tools/experts without overwhelming the Driver's context. ```typescript // Register a tool with on-demand visibility orchestrator.registerTool(new MySpecializedTool(), { visibility: 'on-demand', tags: ['specialized', 'database'], category: 'data', }); // Enable tool search so Driver can discover and activate on-demand tools orchestrator.enableToolSearch(); // The Driver can now: // 1. tools.search({"query": "database"}) -> finds MySpecializedTool // 2. tools.activate({"name": "myspecialized"}) -> enables it // 3. myspecialized.action({...}) -> use the tool ``` ### Expert SubAgent Example ```typescript const orchestrator = new DualAgentOrchestrator({ openaiToken: 'sk-...', defaultProvider: 'openai', guardianPolicyPrompt: 'Allow safe operations...', }); orchestrator.registerStandardTools(); orchestrator.enableToolSearch(); // Initial expert (always visible) orchestrator.registerExpert({ name: 'code_assistant', description: 'Helps with coding tasks and code generation', systemMessage: 'You are a helpful coding assistant...', guardianPolicy: 'Allow read-only file access', tools: [new FilesystemTool()], }); // On-demand experts (discoverable via search) orchestrator.registerExpert({ name: 'database_expert', description: 'Database design, optimization, and query analysis', systemMessage: 'You are a database expert...', guardianPolicy: 'Allow read-only operations', visibility: 'on-demand', tags: ['database', 'sql', 'optimization'], }); orchestrator.registerExpert({ name: 'security_auditor', description: 'Security vulnerability assessment and best practices', systemMessage: 'You are a security expert...', guardianPolicy: 'Allow read-only file access', visibility: 'on-demand', tags: ['security', 'audit', 'vulnerabilities'], }); await orchestrator.start(); // Now the Driver can: // - Use code_assistant directly // - Search for "database" and activate database_expert when needed // - Search for "security" and activate security_auditor when needed ``` ## πŸŽ₯ Streaming Support SmartAgent supports token-by-token streaming for real-time output during LLM generation: ```typescript const orchestrator = new DualAgentOrchestrator({ openaiToken: 'sk-...', defaultProvider: 'openai', guardianPolicyPrompt: '...', // Token streaming callback onToken: (token, source) => { // source is 'driver' or 'guardian' process.stdout.write(token); }, }); ``` This is perfect for CLI applications or UIs that need to show progress as the agent thinks. ## πŸ–ΌοΈ Vision Support Pass images to vision-capable models for multimodal tasks: ```typescript import { readFileSync } from 'fs'; // Load image as base64 const imageBase64 = readFileSync('screenshot.png').toString('base64'); // Run task with images const result = await orchestrator.run( 'Analyze this UI screenshot and describe any usability issues', { images: [imageBase64] } ); ``` ## πŸ“Š Progress Events Get real-time feedback on task execution with the `onProgress` callback: ```typescript const orchestrator = new DualAgentOrchestrator({ openaiToken: 'sk-...', guardianPolicyPrompt: '...', logPrefix: '[MyAgent]', // Optional prefix for log messages onProgress: (event) => { // Pre-formatted log message ready for output console.log(event.logMessage); // Or handle specific event types switch (event.type) { case 'tool_proposed': console.log(`Proposing: ${event.toolName}.${event.action}`); break; case 'tool_approved': console.log(`βœ“ Approved`); break; case 'tool_rejected': console.log(`βœ— Rejected: ${event.reason}`); break; case 'task_completed': console.log(`Done in ${event.iteration} iterations`); break; } }, }); ``` **Event Types**: `task_started`, `iteration_started`, `tool_proposed`, `guardian_evaluating`, `tool_approved`, `tool_rejected`, `tool_executing`, `tool_completed`, `task_completed`, `clarification_needed`, `max_iterations`, `max_rejections` ## πŸ”§ Native Tool Calling For providers that support native tool calling (like Ollama with certain models), SmartAgent can use the provider's built-in tool calling API instead of XML parsing: ```typescript const orchestrator = new DualAgentOrchestrator({ ollamaToken: 'http://localhost:11434', // Ollama endpoint defaultProvider: 'ollama', guardianPolicyPrompt: '...', // Enable native tool calling useNativeToolCalling: true, }); ``` When `useNativeToolCalling` is enabled: - Tools are converted to JSON schema format automatically - The provider handles tool call parsing natively - Streaming still works with `[THINKING]` and `[OUTPUT]` markers for supported models - Tool calls appear as `toolName_actionName` (e.g., `json_validate`) This is more efficient for models that support it and avoids potential XML parsing issues. ## Guardian Policy Examples The Guardian's power comes from your policy. Here are battle-tested examples: ### πŸ” Strict Security Policy ```typescript const securityPolicy = ` SECURITY POLICY: 1. REJECT any file operations outside /home/user/workspace 2. REJECT any shell commands that could modify system state 3. REJECT any HTTP requests to internal/private IP ranges 4. REJECT any attempts to read environment variables or credentials 5. FLAG and REJECT obfuscated code execution When rejecting, always explain: - What policy was violated - What would be a safer alternative `; ``` ### πŸ› οΈ Development Environment Policy ```typescript const devPolicy = ` DEVELOPMENT POLICY: - Allow file operations only within the project directory - Allow npm/pnpm commands for package management - Allow git commands for version control - Allow HTTP requests to public APIs only - REJECT direct database modifications - REJECT commands that could affect other users Always verify: - File paths are relative or within project bounds - Commands don't have dangerous flags (--force, -rf) `; ``` ### πŸ¦• Deno Code Execution Policy ```typescript const denoPolicy = ` DENO CODE EXECUTION POLICY: - ONLY allow 'read' permission for files within the workspace - REJECT 'all' permission unless explicitly justified for the task - REJECT 'run' permission (subprocess execution) without specific justification - REJECT code that attempts to: - Access credentials or environment secrets (even with 'env' permission) - Make network requests to internal/private IP ranges - Write to system directories - FLAG obfuscated or encoded code (base64, eval with dynamic strings) - Prefer sandboxed execution (no permissions) when possible When evaluating code: - Review the actual code content, not just permissions - Consider what data the code could exfiltrate - Verify network endpoints are legitimate public APIs `; ``` ## Configuration Options ```typescript interface IDualAgentOptions { // Provider tokens (from @push.rocks/smartai) openaiToken?: string; anthropicToken?: string; perplexityToken?: string; groqToken?: string; xaiToken?: string; ollamaToken?: string; // URL for Ollama endpoint // Use existing SmartAi instance (optional - avoids duplicate providers) smartAiInstance?: SmartAi; // Provider selection defaultProvider?: TProvider; // For both Driver and Guardian guardianProvider?: TProvider; // Optional: separate provider for Guardian // Agent configuration driverSystemMessage?: string; // Custom system message for Driver guardianPolicyPrompt: string; // REQUIRED: Policy for Guardian to enforce name?: string; // Agent system name verbose?: boolean; // Enable verbose logging // Native tool calling useNativeToolCalling?: boolean; // Use provider's native tool calling API (default: false) // Limits maxIterations?: number; // Max task iterations (default: 20) maxConsecutiveRejections?: number; // Abort after N rejections (default: 3) maxResultChars?: number; // Max chars for tool results before truncation (default: 15000) maxHistoryMessages?: number; // Max history messages for API (default: 20) // Callbacks onProgress?: (event: IProgressEvent) => void; // Progress event callback onToken?: (token: string, source: 'driver' | 'guardian') => void; // Streaming callback logPrefix?: string; // Prefix for log messages } ``` ## Result Interface ```typescript interface IDualAgentRunResult { success: boolean; // Whether task completed successfully completed: boolean; // Task completion status result: string; // Final result or response iterations: number; // Number of iterations taken history: IAgentMessage[]; // Full conversation history status: TDualAgentRunStatus; // 'completed' | 'max_iterations_reached' | etc. toolCallCount?: number; // Number of tool calls made rejectionCount?: number; // Number of Guardian rejections toolLog?: IToolExecutionLog[]; // Detailed tool execution log error?: string; // Error message if status is 'error' } type TDualAgentRunStatus = | 'completed' | 'in_progress' | 'max_iterations_reached' | 'max_rejections_reached' | 'clarification_needed' | 'error'; ``` ## Custom Tools Create custom tools by extending `BaseToolWrapper`: ```typescript import { BaseToolWrapper, IToolAction, IToolExecutionResult } from '@push.rocks/smartagent'; class MyCustomTool extends BaseToolWrapper { public name = 'custom'; public description = 'My custom tool for specific operations'; public actions: IToolAction[] = [ { name: 'myAction', description: 'Performs a custom action', parameters: { type: 'object', properties: { input: { type: 'string', description: 'Input for the action' }, }, required: ['input'], }, }, ]; public async initialize(): Promise { // Setup your tool (called when orchestrator.start() runs) this.isInitialized = true; } public async cleanup(): Promise { // Cleanup resources (called when orchestrator.stop() runs) this.isInitialized = false; } public async execute(action: string, params: Record): Promise { this.validateAction(action); this.ensureInitialized(); if (action === 'myAction') { return { success: true, result: { processed: params.input }, summary: `Processed input: ${params.input}`, // Optional human-readable summary }; } return { success: false, error: 'Unknown action' }; } // Human-readable summary for Guardian evaluation public getCallSummary(action: string, params: Record): string { return `Custom action "${action}" with input "${params.input}"`; } } // Register custom tool orchestrator.registerTool(new MyCustomTool()); ``` ## Reusing SmartAi Instances If you already have a `@push.rocks/smartai` instance, you can share it: ```typescript import { SmartAi } from '@push.rocks/smartai'; import { DualAgentOrchestrator } from '@push.rocks/smartagent'; const smartai = new SmartAi({ openaiToken: 'sk-...' }); await smartai.start(); const orchestrator = new DualAgentOrchestrator({ smartAiInstance: smartai, // Reuse existing instance guardianPolicyPrompt: '...', }); await orchestrator.start(); // ... use orchestrator ... await orchestrator.stop(); // SmartAi instance lifecycle is managed separately await smartai.stop(); ``` ## Supported Providers SmartAgent supports all providers from `@push.rocks/smartai`: | Provider | Driver | Guardian | |----------|:------:|:--------:| | OpenAI | βœ… | βœ… | | Anthropic | βœ… | βœ… | | Perplexity | βœ… | βœ… | | Groq | βœ… | βœ… | | Ollama | βœ… | βœ… | | XAI | βœ… | βœ… | | Exo | βœ… | βœ… | **πŸ’‘ Pro tip**: Use a faster/cheaper model for Guardian (like Groq) and a more capable model for Driver: ```typescript const orchestrator = new DualAgentOrchestrator({ openaiToken: 'sk-...', groqToken: 'gsk-...', defaultProvider: 'openai', // Driver uses OpenAI guardianProvider: 'groq', // Guardian uses Groq (faster, cheaper) guardianPolicyPrompt: '...', }); ``` ## API Reference ### DualAgentOrchestrator | Method | Description | |--------|-------------| | `start()` | Initialize all tools and AI providers | | `stop()` | Cleanup all tools and resources | | `run(task, options?)` | Execute a task with optional images for vision | | `continueTask(input)` | Continue a task with user input | | `registerTool(tool, options?)` | Register a custom tool with optional visibility settings | | `registerStandardTools()` | Register all built-in tools (Filesystem, HTTP, Shell, Browser, Deno) | | `registerScopedFilesystemTool(basePath, excludePatterns?)` | Register filesystem tool with path restriction | | `registerExpert(config)` | Register a specialized sub-agent as a tool | | `enableToolSearch()` | Enable tool discovery and activation for the Driver | | `setGuardianPolicy(policy)` | Update Guardian policy at runtime | | `getHistory()` | Get conversation history | | `getToolNames()` | Get list of registered tool names | | `getRegistry()` | Get the ToolRegistry for advanced operations | | `isActive()` | Check if orchestrator is running | ### Exports ```typescript // Main classes export { DualAgentOrchestrator } from '@push.rocks/smartagent'; export { DriverAgent } from '@push.rocks/smartagent'; export { GuardianAgent } from '@push.rocks/smartagent'; // Tool Registry export { ToolRegistry } from '@push.rocks/smartagent'; // Tools export { BaseToolWrapper } from '@push.rocks/smartagent'; export { FilesystemTool, type IFilesystemToolOptions } from '@push.rocks/smartagent'; export { HttpTool } from '@push.rocks/smartagent'; export { ShellTool } from '@push.rocks/smartagent'; export { BrowserTool } from '@push.rocks/smartagent'; export { DenoTool, type TDenoPermission } from '@push.rocks/smartagent'; export { JsonValidatorTool } from '@push.rocks/smartagent'; export { ToolSearchTool } from '@push.rocks/smartagent'; export { ExpertTool } from '@push.rocks/smartagent'; // Types and interfaces export * from '@push.rocks/smartagent'; // All interfaces (IExpertConfig, IToolMetadata, etc.) // Re-exported from @push.rocks/smartai export { type ISmartAiOptions, type TProvider, type ChatMessage, type ChatOptions, type ChatResponse }; ``` ## License and Legal Information This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file. **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. ### Trademarks This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar. ### Company Information Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany For any legal inquiries or further information, please contact us via email at hello@task.vc. By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.