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
- **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)
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)
7. **ToolSearchTool** - AI-facing interface for tool discovery and activation
8. **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

```typescript
// 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:

```typescript
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:

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