smartagent/readme.hints.md

Project Readme Hints

Overview

@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.

Architecture

• DualAgentOrchestrator: Main entry point, coordinates Driver and Guardian agents
• DriverAgent: Reasons about tasks, plans steps, proposes tool calls (supports both XML and native tool calling)
• GuardianAgent: Evaluates tool calls against configured policies
• BaseToolWrapper: Base class for creating custom tools
• plugins.ts: Imports and re-exports smartai and other dependencies

Standard Tools (via registerStandardTools)

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

Additional Tools (must register manually)

6. JsonValidatorTool - JSON validation and formatting (NOT in registerStandardTools)

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
• 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

Key Dependencies

• @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

Test Structure

• Tests use @git.zone/tstest/tapbundle
• Tests must end with export default tap.start();