2025-12-02 10:59:09 +00:00
# Project Readme Hints
## Overview
2026-01-20 01:30:26 +00:00
`@push.rocks/smartagent` is a dual-agent agentic framework built on top of `@push.rocks/smartai` . It implements a Driver/Guardian architecture where the Driver proposes tool calls and the Guardian evaluates them against security policies.
2025-12-02 10:59:09 +00:00
## Architecture
2026-01-20 01:30:26 +00:00
- **DualAgentOrchestrator**: Main entry point, coordinates Driver and Guardian agents
2026-01-20 12:01:07 +00:00
- **DriverAgent**: Reasons about tasks, plans steps, proposes tool calls (supports both XML and native tool calling)
2026-01-20 01:30:26 +00:00
- **GuardianAgent**: Evaluates tool calls against configured policies
- **BaseToolWrapper**: Base class for creating custom tools
- **plugins.ts**: Imports and re-exports smartai and other dependencies
2026-01-20 12:01:07 +00:00
## Standard Tools (via registerStandardTools)
2026-01-20 01:30:26 +00:00
1. **FilesystemTool ** - File operations with scoping and exclusion patterns
2. **HttpTool ** - HTTP requests
3. **ShellTool ** - Secure shell commands (no injection possible)
4. **BrowserTool ** - Web page interaction via Puppeteer
5. **DenoTool ** - Sandboxed TypeScript/JavaScript execution
2026-01-20 12:01:07 +00:00
## Additional Tools (must register manually)
6. **JsonValidatorTool ** - JSON validation and formatting (NOT in registerStandardTools)
2026-01-20 01:30:26 +00:00
## Key Features
- Token streaming support (`onToken` callback)
- Vision support (pass images as base64)
- Progress events (`onProgress` callback)
- Scoped filesystem with exclusion patterns
- Result truncation with configurable limits
- History windowing to manage token usage
2026-01-20 12:01:07 +00:00
- **Native tool calling mode** (`useNativeToolCalling: true` ) for providers like Ollama
## Native Tool Calling
When `useNativeToolCalling` is enabled:
- Uses provider's built-in tool calling API instead of XML parsing
- Tool names become `toolName_actionName` (e.g., `json_validate` )
- Streaming includes `[THINKING]` and `[OUTPUT]` markers
- More efficient for models that support it
2025-12-02 10:59:09 +00:00
## Key Dependencies
2026-01-20 01:30:26 +00:00
- `@push.rocks/smartai` : Multi-provider AI interface
- `@push.rocks/smartfs` : Filesystem operations
- `@push.rocks/smartshell` : Shell command execution
- `@push.rocks/smartbrowser` : Browser automation
- `@push.rocks/smartdeno` : Deno code execution
- `@push.rocks/smartrequest` : HTTP requests
- `minimatch` : Glob pattern matching for exclusions
2025-12-02 10:59:09 +00:00
## Test Structure
- Tests use `@git.zone/tstest/tapbundle`
- Tests must end with `export default tap.start();`
