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
ToolRegistry: Manages tool lifecycle, visibility, and discovery
BaseToolWrapper: Base class for creating custom tools
plugins.ts: Imports and re-exports smartai and other dependencies

Standard Tools (via registerStandardTools)

FilesystemTool - File operations with scoping and exclusion patterns
HttpTool - HTTP requests
ShellTool - Secure shell commands (no injection possible)
BrowserTool - Web page interaction via Puppeteer
DenoTool - Sandboxed TypeScript/JavaScript execution

Additional Tools (must register manually)

JsonValidatorTool - JSON validation and formatting (NOT in registerStandardTools)
ToolSearchTool - AI-facing interface for tool discovery and activation
ExpertTool - Wraps a DualAgentOrchestrator as a specialized expert tool

Tool Visibility System

Tools can be registered with visibility modes:

initial: Always visible to Driver, included in system prompt (default)
on-demand: Only discoverable via search, must be activated before use

// Register with visibility options
orchestrator.registerTool(myTool, {
  visibility: 'on-demand',
  tags: ['database', 'sql'],
  category: 'data'
});

Expert/SubAgent System

Experts are specialized agents wrapped as tools, enabling hierarchical agent architectures:

orchestrator.registerExpert({
  name: 'code_reviewer',
  description: 'Reviews code for quality and best practices',
  systemMessage: 'You are a code review expert...',
  guardianPolicy: 'Allow read-only file access',
  tools: [new FilesystemTool()],
  visibility: 'on-demand',
  tags: ['code', 'review']
});

Tool Search

Enable tool discovery for the Driver:

orchestrator.enableToolSearch();
// Driver can now use:
// - tools.search({"query": "database"})
// - tools.list({})
// - tools.activate({"name": "database_expert"})
// - tools.details({"name": "filesystem"})

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
Tool visibility system (initial vs on-demand)
Expert/SubAgent system for hierarchical agents
Tool search and discovery via ToolSearchTool

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();

3.7 KiB Raw Blame History