push.rocks/smartagent
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Jürgen Kunz
2025-12-15 14:49:26 +00:00
parent 9e848045f7
commit 8662b73adb
5 changed files with 489 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
readme.md
View File

@@ -1,21 +1,31 @@
# @push.rocks/smartagent
A dual-agent agentic framework with Driver and Guardian agents for safe, policy-controlled AI task execution.
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:
SmartAgent implements a **dual-agent architecture** where AI safety isn't just an afterthought—it's baked into the core design:
- **Driver Agent**: Executes tasks, reasons about goals, and proposes tool calls
- **Guardian Agent**: Evaluates tool call proposals against a policy prompt, approving or rejecting with feedback
- **🎯 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.
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
@@ -89,8 +99,11 @@ await orchestrator.stop();
## Standard Tools
### FilesystemTool
File and directory operations using `@push.rocks/smartfs`.
SmartAgent comes with five battle-tested tools out of the box:
### 🗂️ FilesystemTool
File and directory operations powered by `@push.rocks/smartfs`.
**Actions**: `read`, `write`, `append`, `list`, `delete`, `exists`, `stat`, `copy`, `move`, `mkdir`
@@ -104,7 +117,15 @@ File and directory operations using `@push.rocks/smartfs`.
</tool_call>
```
### HttpTool
**Scoped Filesystem**: Lock file operations to a specific directory:
```typescript
// Only allow access within a specific directory
orchestrator.registerScopedFilesystemTool('/home/user/workspace');
```
### 🌐 HttpTool
HTTP requests using `@push.rocks/smartrequest`.
**Actions**: `get`, `post`, `put`, `patch`, `delete`
@@ -113,13 +134,14 @@ HTTP requests using `@push.rocks/smartrequest`.
<tool_call>
<tool>http</tool>
<action>get</action>
<params>{"url": "https://api.example.com/data"}</params>
<params>{"url": "https://api.example.com/data", "headers": {"Authorization": "Bearer token"}}</params>
<reasoning>Fetching data from the API endpoint</reasoning>
</tool_call>
```
### ShellTool
Secure shell command execution using `@push.rocks/smartshell` with `execSpawn` (no shell injection).
### 💻 ShellTool
Secure shell command execution using `@push.rocks/smartshell` with `execSpawn` (no shell injection possible).
**Actions**: `execute`, `which`
@@ -132,7 +154,10 @@ Secure shell command execution using `@push.rocks/smartshell` with `execSpawn` (
</tool_call>
```
### BrowserTool
> 🔒 **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`
@@ -146,17 +171,18 @@ Web page interaction using `@push.rocks/smartbrowser` (Puppeteer-based).
</tool_call>
```
### DenoTool
Execute TypeScript/JavaScript code in a sandboxed Deno environment using `@push.rocks/smartdeno`.
### 🦕 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.
By default, code runs **fully sandboxed with no permissions**. Permissions must be explicitly requested and are subject to Guardian approval.
```typescript
// Simple code execution
// Simple code execution (sandboxed, no permissions)
<tool_call>
<tool>deno</tool>
<action>execute</action>
@@ -188,7 +214,10 @@ By default, code runs fully sandboxed with no permissions. Permissions must be e
## Guardian Policy Examples
### Strict Security Policy
The Guardian's power comes from your policy. Here are battle-tested examples:
### 🔐 Strict Security Policy
```typescript
const securityPolicy = `
SECURITY POLICY:
@@ -204,7 +233,8 @@ When rejecting, always explain:
`;
```
### Development Environment Policy
### 🛠️ Development Environment Policy
```typescript
const devPolicy = `
DEVELOPMENT POLICY:
@@ -221,7 +251,8 @@ Always verify:
`;
```
### Deno Code Execution Policy
### 🦕 Deno Code Execution Policy
```typescript
const denoPolicy = `
DENO CODE EXECUTION POLICY:
@@ -253,6 +284,9 @@ interface IDualAgentOptions {
groqToken?: string;
xaiToken?: string;
// 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
@@ -278,6 +312,14 @@ interface IDualAgentRunResult {
history: IAgentMessage[]; // Full conversation history
status: TDualAgentRunStatus; // 'completed' | 'max_iterations_reached' | etc.
}
type TDualAgentRunStatus =
| 'completed'
| 'in_progress'
| 'max_iterations_reached'
| 'max_rejections_reached'
| 'clarification_needed'
| 'error';
```
## Custom Tools
@@ -306,10 +348,12 @@ class MyCustomTool extends BaseToolWrapper {
];
public async initialize(): Promise<void> {
// Setup your tool (called when orchestrator.start() runs)
this.isInitialized = true;
}
public async cleanup(): Promise<void> {
// Cleanup resources (called when orchestrator.stop() runs)
this.isInitialized = false;
}
@@ -327,6 +371,7 @@ class MyCustomTool extends BaseToolWrapper {
return { success: false, error: 'Unknown action' };
}
// Human-readable summary for Guardian evaluation
public getCallSummary(action: string, params: Record<string, unknown>): string {
return `Custom action "${action}" with input "${params.input}"`;
}
@@ -336,32 +381,111 @@ class MyCustomTool extends BaseToolWrapper {
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 | Yes | Yes |
| Anthropic | Yes | Yes |
| Perplexity | Yes | Yes |
| Groq | Yes | Yes |
| Ollama | Yes | Yes |
| XAI | Yes | Yes |
| 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: string)` | Execute a task and return result |
| `continueTask(input: string)` | Continue a task with user input |
| `registerTool(tool)` | Register a custom tool |
| `registerStandardTools()` | Register all built-in tools |
| `registerScopedFilesystemTool(basePath)` | Register filesystem tool with path restriction |
| `setGuardianPolicy(policy)` | Update Guardian policy at runtime |
| `getHistory()` | Get conversation history |
| `getToolNames()` | Get list of registered tool names |
| `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';
// Tools
export { BaseToolWrapper } from '@push.rocks/smartagent';
export { FilesystemTool } from '@push.rocks/smartagent';
export { HttpTool } from '@push.rocks/smartagent';
export { ShellTool } from '@push.rocks/smartagent';
export { BrowserTool } from '@push.rocks/smartagent';
export { DenoTool } from '@push.rocks/smartagent';
// Types and interfaces
export * from '@push.rocks/smartagent'; // All interfaces
```
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
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 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, and any usage must be approved in writing by Task Venture Capital GmbH.
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
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
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.