@push.rocks/smartagent 1.8.0 → 3.0.0

package/readme.md

@@ -1,12 +1,10 @@
 # @push.rocks/smartagent
 
-A dual-agent agentic framework with **Driver** and **Guardian** agents for safe, policy-controlled AI task execution. 🤖🛡️
+A lightweight agentic loop built on **Vercel AI SDK v6** via `@push.rocks/smartai`. Register tools, get a model, call `runAgent()` — done. 🚀
 
 ## Install
 
 ```bash
-npm install @push.rocks/smartagent
-# or
 pnpm install @push.rocks/smartagent
 ```
 
@@ -16,788 +14,362 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ## Overview
 
-SmartAgent implements a **dual-agent architecture** where AI safety isn't just an afterthought—it's baked into the core design:
+`@push.rocks/smartagent` wraps the AI SDK's `streamText` with `stopWhen: stepCountIs(n)` for **parallel multi-step tool execution**. No classes to instantiate, no lifecycle to manage — just one async function:
 
-- **🎯 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
+```typescript
+import { runAgent, tool, z } from '@push.rocks/smartagent';
+import { getModel } from '@push.rocks/smartai';
 
-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.
+const model = getModel({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5-20250929',
+  apiKey: process.env.ANTHROPIC_TOKEN,
+});
 
-### Why Dual-Agent?
+const result = await runAgent({
+  model,
+  prompt: 'What is 7 + 35?',
+  system: 'You are a helpful assistant. Use tools when asked.',
+  tools: {
+    calculator: tool({
+      description: 'Perform arithmetic',
+      inputSchema: z.object({
+        operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+        a: z.number(),
+        b: z.number(),
+      }),
+      execute: async ({ operation, a, b }) => {
+        const ops = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b };
+        return String(ops[operation]);
+      },
+    }),
+  },
+  maxSteps: 10,
+});
 
-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.
+console.log(result.text);    // "7 + 35 = 42"
+console.log(result.steps);   // number of agentic steps taken
+console.log(result.usage);   // { promptTokens, completionTokens, totalTokens }
+```
 
 ## Architecture
 
-```mermaid
-flowchart TB
-    subgraph Input
-        Task["User Task"]
-        Policy["Guardian Policy Prompt"]
-    end
-
-    subgraph Orchestrator["DualAgentOrchestrator"]
-        Registry["ToolRegistry<br/><i>Visibility & Lifecycle</i>"]
-        Driver["Driver Agent<br/><i>Reason + Plan</i>"]
-        Guardian["Guardian Agent<br/><i>Evaluate against policy</i>"]
-
-        Driver -->|"tool call proposal"| Guardian
-        Guardian -->|"approve / reject + feedback"| Driver
-        Registry -->|"visible tools"| Driver
-    end
-
-    subgraph Tools["Tools"]
-        Initial["Initial Tools<br/><i>Always visible</i>"]
-        OnDemand["On-Demand Tools<br/><i>Discoverable via search</i>"]
-        Experts["Expert SubAgents<br/><i>Specialized agents as tools</i>"]
-    end
-
-    Task --> Orchestrator
-    Policy --> Guardian
-    Driver -->|"execute<br/>(if approved)"| Tools
-    Tools -->|"result"| Driver
 ```
-
-## Quick Start
-
-```typescript
-import { DualAgentOrchestrator } from '@push.rocks/smartagent';
-
-// Create orchestrator with Guardian policy
-const orchestrator = new DualAgentOrchestrator({
-  openaiToken: 'sk-...',
-  defaultProvider: 'openai',
-  guardianPolicyPrompt: `
-    FILE SYSTEM POLICY:
-    - ONLY allow reading/writing within /tmp or the current working directory
-    - REJECT operations on system directories or sensitive files
-
-    SHELL POLICY:
-    - Allow read-only commands (ls, cat, grep, echo)
-    - REJECT destructive commands (rm, mv, chmod) without explicit justification
-
-    FLAG any attempt to expose secrets or credentials.
-  `,
-});
-
-// Register standard tools
-orchestrator.registerStandardTools();
-
-// Start the orchestrator (initializes all tools)
-await orchestrator.start();
-
-// Run a task
-const result = await orchestrator.run('List all TypeScript files in the current directory');
-
-console.log('Success:', result.success);
-console.log('Result:', result.result);
-console.log('Iterations:', result.iterations);
-
-// Cleanup
-await orchestrator.stop();
+┌─────────────────────────────────────────────────┐
+│  runAgent({ model, prompt, tools, maxSteps })   │
+│                                                 │
+│  ┌───────────┐   ┌──────────┐   ┌───────────┐  │
+│  │ Messages   │──▶│ streamText│──▶│  Tools    │  │
+│  │ (history)  │◀──│ (AI SDK) │◀──│ (ToolSet) │  │
+│  └───────────┘   └──────────┘   └───────────┘  │
+│                                                 │
+│  stopWhen: stepCountIs(maxSteps)                │
+│  + retry with backoff on 429/529/503            │
+│  + context overflow detection & recovery        │
+│  + tool call repair (case-insensitive matching) │
+└─────────────────────────────────────────────────┘
 ```
 
-## Standard Tools
+**Key features:**
 
-SmartAgent comes with five battle-tested tools out of the box via `registerStandardTools()`:
+- 🔄 **Multi-step agentic loop** — the model calls tools, sees results, and continues reasoning until done
+- ⚡ **Parallel tool execution** — multiple tool calls in a single step are executed concurrently
+- 🔧 **Auto-retry with backoff** — handles 429/529/503 errors with header-aware retry delays
+- 🩹 **Tool call repair** — case-insensitive name matching + invalid tool sink prevents crashes
+- 📊 **Token streaming** — `onToken` and `onToolCall` callbacks for real-time progress
+- 💥 **Context overflow handling** — detects overflow and invokes your `onContextOverflow` callback
 
-### 🗂️ FilesystemTool
+## Core API
 
-File and directory operations powered by `@push.rocks/smartfs`.
+### `runAgent(options): Promise<IAgentRunResult>`
 
-**Actions**: `read`, `write`, `append`, `list`, `delete`, `exists`, `stat`, `copy`, `move`, `mkdir`
+The single entry point. Options:
 
-```typescript
-// Example tool call by Driver
-<tool_call>
-  <tool>filesystem</tool>
-  <action>read</action>
-  <params>{"path": "/tmp/config.json"}</params>
-  <reasoning>Need to read the configuration file to understand the settings</reasoning>
-</tool_call>
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `LanguageModelV3` | *required* | Model from `@push.rocks/smartai`'s `getModel()` |
+| `prompt` | `string` | *required* | The user's task/question |
+| `system` | `string` | `undefined` | System prompt |
+| `tools` | `ToolSet` | `{}` | Tools the agent can call |
+| `maxSteps` | `number` | `20` | Max agentic steps before stopping |
+| `messages` | `ModelMessage[]` | `[]` | Conversation history (for multi-turn) |
+| `maxRetries` | `number` | `5` | Max retries on rate-limit/server errors |
+| `onToken` | `(delta: string) => void` | — | Streaming token callback |
+| `onToolCall` | `(name: string) => void` | — | Called when a tool is invoked |
+| `onContextOverflow` | `(messages) => messages` | — | Handle context overflow (e.g., compact messages) |
 
-**Scoped Filesystem**: Lock file operations to a specific directory with optional exclusion patterns:
+### `IAgentRunResult`
 
 ```typescript
-// Only allow access within a specific directory
-orchestrator.registerScopedFilesystemTool('/home/user/workspace');
-
-// With exclusion patterns (glob syntax)
-orchestrator.registerScopedFilesystemTool('/home/user/workspace', [
-  '.nogit/**',
-  'node_modules/**',
-  '*.secret',
-]);
-```
-
-**Line-range Reading**: Read specific portions of large files:
-
-```typescript
-<tool_call>
-  <tool>filesystem</tool>
-  <action>read</action>
-  <params>{"path": "/var/log/app.log", "startLine": 100, "endLine": 150}</params>
-  <reasoning>Reading only the relevant log section to avoid token overload</reasoning>
-</tool_call>
+interface IAgentRunResult {
+  text: string;              // Final response text
+  finishReason: string;      // 'stop', 'tool-calls', 'length', etc.
+  steps: number;             // Number of agentic steps taken
+  messages: ModelMessage[];  // Full conversation for multi-turn
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
 ```
 
-### 🌐 HttpTool
+## Defining Tools 🛠️
 
-HTTP requests using `@push.rocks/smartrequest`.
-
-**Actions**: `get`, `post`, `put`, `patch`, `delete`
+Tools use Vercel AI SDK's `tool()` helper with Zod schemas:
 
 ```typescript
-<tool_call>
-  <tool>http</tool>
-  <action>get</action>
-  <params>{"url": "https://api.example.com/data", "headers": {"Authorization": "Bearer token"}}</params>
-  <reasoning>Fetching data from the API endpoint</reasoning>
-</tool_call>
+import { tool, z } from '@push.rocks/smartagent';
+
+const myTool = tool({
+  description: 'Describe what this tool does',
+  inputSchema: z.object({
+    param1: z.string().describe('What this parameter is for'),
+    param2: z.number().optional(),
+  }),
+  execute: async ({ param1, param2 }) => {
+    // Do work, return a string
+    return `Result: ${param1}`;
+  },
+});
 ```
 
-### 💻 ShellTool
-
-Secure shell command execution using `@push.rocks/smartshell` with `execSpawn` (no shell injection possible).
-
-**Actions**: `execute`, `which`
+Pass tools as a flat object to `runAgent()`:
 
 ```typescript
-<tool_call>
-  <tool>shell</tool>
-  <action>execute</action>
-  <params>{"command": "ls", "args": ["-la", "/tmp"]}</params>
-  <reasoning>Listing directory contents to find relevant files</reasoning>
-</tool_call>
+await runAgent({
+  model,
+  prompt: 'Do the thing',
+  tools: { myTool, anotherTool },
+  maxSteps: 10,
+});
 ```
 
-> 🔒 **Security Note**: The shell tool uses `execSpawn` with `shell: false`, meaning command and arguments are passed separately. This makes shell injection attacks impossible.
-
-### 🌍 BrowserTool
+## ToolRegistry
 
-Web page interaction using `@push.rocks/smartbrowser` (Puppeteer-based).
-
-**Actions**: `screenshot`, `pdf`, `evaluate`, `getPageContent`
+A lightweight helper for collecting tools:
 
 ```typescript
-<tool_call>
-  <tool>browser</tool>
-  <action>getPageContent</action>
-  <params>{"url": "https://example.com"}</params>
-  <reasoning>Extracting text content from the webpage</reasoning>
-</tool_call>
+import { ToolRegistry, tool, z } from '@push.rocks/smartagent';
+
+const registry = new ToolRegistry();
+
+registry.register('random_number', tool({
+  description: 'Generate a random integer between min and max',
+  inputSchema: z.object({
+    min: z.number(),
+    max: z.number(),
+  }),
+  execute: async ({ min, max }) => {
+    return String(Math.floor(Math.random() * (max - min + 1)) + min);
+  },
+}));
+
+registry.register('is_even', tool({
+  description: 'Check if a number is even',
+  inputSchema: z.object({ number: z.number() }),
+  execute: async ({ number: n }) => n % 2 === 0 ? 'Yes' : 'No',
+}));
+
+const result = await runAgent({
+  model,
+  prompt: 'Generate a random number and tell me if it is even',
+  tools: registry.getTools(),
+  maxSteps: 10,
+});
 ```
 
-### 🦕 DenoTool
-
-Execute TypeScript/JavaScript code in a **sandboxed Deno environment** with fine-grained permission control.
+## Built-in Tool Factories 🧰
 
-**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 and are subject to Guardian approval.
+Import from the `@push.rocks/smartagent/tools` subpath:
 
 ```typescript
-// Simple code execution (sandboxed, no permissions)
-<tool_call>
-  <tool>deno</tool>
-  <action>execute</action>
-  <params>{"code": "console.log('Hello from Deno!')"}</params>
-  <reasoning>Running a simple script to verify the environment</reasoning>
-</tool_call>
-
-// Code with network permission
-<tool_call>
-  <tool>deno</tool>
-  <action>execute</action>
-  <params>{
-    "code": "const resp = await fetch('https://api.example.com/data'); console.log(await resp.json());",
-    "permissions": ["net"]
-  }</params>
-  <reasoning>Fetching data from API using Deno's fetch</reasoning>
-</tool_call>
-
-// Execute and parse JSON result
-<tool_call>
-  <tool>deno</tool>
-  <action>executeWithResult</action>
-  <params>{
-    "code": "const result = { sum: 2 + 2, date: new Date().toISOString() }; console.log(JSON.stringify(result));"
-  }</params>
-  <reasoning>Computing values and returning structured data</reasoning>
-</tool_call>
+import { filesystemTool, shellTool, httpTool, jsonTool } from '@push.rocks/smartagent/tools';
 ```
 
-## Additional Tools
-
-### 📋 JsonValidatorTool
-
-Validate and format JSON data. Perfect for agents to self-check their JSON output before completing tasks.
+### `filesystemTool(options?)`
 
-**Actions**: `validate`, `format`
+Returns: `read_file`, `write_file`, `list_directory`, `delete_file`
 
 ```typescript
-import { JsonValidatorTool } from '@push.rocks/smartagent';
+const tools = filesystemTool({ rootDir: '/home/user/workspace' });
 
-// Register the JSON validator tool (not included in registerStandardTools)
-orchestrator.registerTool(new JsonValidatorTool());
-```
-
-```typescript
-// Validate JSON with required field checking
-<tool_call>
-  <tool>json</tool>
-  <action>validate</action>
-  <params>{
-    "jsonString": "{\"name\": \"test\", \"version\": \"1.0.0\"}",
-    "requiredFields": ["name", "version", "description"]
-  }</params>
-  <reasoning>Ensuring the config has all required fields before saving</reasoning>
-</tool_call>
-
-// Pretty-print JSON
-<tool_call>
-  <tool>json</tool>
-  <action>format</action>
-  <params>{"jsonString": "{\"compact\":true,\"data\":[1,2,3]}"}</params>
-  <reasoning>Formatting JSON for readable output</reasoning>
-</tool_call>
+await runAgent({
+  model,
+  prompt: 'Create a file called hello.txt with "Hello World"',
+  tools,
+  maxSteps: 5,
+});
 ```
 
-### 🔍 ToolSearchTool
+Options:
+- `rootDir` — restrict all file operations to this directory. Paths outside it throw `Access denied`.
 
-Enable the Driver to discover and activate on-demand tools at runtime.
+### `shellTool(options?)`
 
-**Actions**: `search`, `list`, `activate`, `details`
+Returns: `run_command`
 
 ```typescript
-// Enable tool search (adds the 'tools' tool)
-orchestrator.enableToolSearch();
-```
+const tools = shellTool({ cwd: '/tmp', allowedCommands: ['ls', 'echo', 'cat'] });
 
-```typescript
-// Search for tools by capability
-<tool_call>
-  <tool>tools</tool>
-  <action>search</action>
-  <params>{"query": "database"}</params>
-</tool_call>
-
-// List all available tools
-<tool_call>
-  <tool>tools</tool>
-  <action>list</action>
-  <params>{}</params>
-</tool_call>
-
-// Activate an on-demand tool
-<tool_call>
-  <tool>tools</tool>
-  <action>activate</action>
-  <params>{"name": "database_expert"}</params>
-</tool_call>
-
-// Get detailed information about a tool
-<tool_call>
-  <tool>tools</tool>
-  <action>details</action>
-  <params>{"name": "filesystem"}</params>
-</tool_call>
-```
-
-### 🧠 ExpertTool (SubAgents)
-
-Create specialized sub-agents that can be invoked as tools. Experts are complete `DualAgentOrchestrator` instances wrapped as tools, enabling hierarchical agent architectures.
-
-**Actions**: `consult`
-
-```typescript
-// Register an expert for code review
-orchestrator.registerExpert({
-  name: 'code_reviewer',
-  description: 'Reviews code for quality, bugs, and best practices',
-  systemMessage: `You are an expert code reviewer. Analyze code for:
-    - Bugs and potential issues
-    - Code style and best practices
-    - Performance concerns
-    - Security vulnerabilities`,
-  guardianPolicy: 'Allow read-only file access within the workspace',
-  tools: [new FilesystemTool()],
-  visibility: 'on-demand',  // Only available via tool search
-  tags: ['code', 'review', 'quality'],
-  category: 'expert',
+await runAgent({
+  model,
+  prompt: 'List all files in /tmp',
+  tools,
+  maxSteps: 5,
 });
 ```
 
-```typescript
-// Consult an expert
-<tool_call>
-  <tool>code_reviewer</tool>
-  <action>consult</action>
-  <params>{
-    "task": "Review this function for potential issues",
-    "context": "This is a user authentication handler"
-  }</params>
-</tool_call>
-```
-
-## 🎯 Tool Visibility System
-
-SmartAgent supports **tool visibility modes** for scalable agent architectures:
-
-- **`initial`** (default): Tool is visible to the Driver from the start, included in the system prompt
-- **`on-demand`**: Tool is hidden until explicitly activated via `tools.activate()`
-
-This enables you to have many specialized tools/experts without overwhelming the Driver's context.
-
-```typescript
-// Register a tool with on-demand visibility
-orchestrator.registerTool(new MySpecializedTool(), {
-  visibility: 'on-demand',
-  tags: ['specialized', 'database'],
-  category: 'data',
-});
-
-// Enable tool search so Driver can discover and activate on-demand tools
-orchestrator.enableToolSearch();
+Options:
+- `cwd` — working directory for commands
+- `allowedCommands` — whitelist of allowed commands (if set, others are rejected)
 
-// The Driver can now:
-// 1. tools.search({"query": "database"}) -> finds MySpecializedTool
-// 2. tools.activate({"name": "myspecialized"}) -> enables it
-// 3. myspecialized.action({...}) -> use the tool
-```
+### `httpTool()`
 
-### Expert SubAgent Example
+Returns: `http_get`, `http_post`
 
 ```typescript
-const orchestrator = new DualAgentOrchestrator({
-  openaiToken: 'sk-...',
-  defaultProvider: 'openai',
-  guardianPolicyPrompt: 'Allow safe operations...',
-});
-
-orchestrator.registerStandardTools();
-orchestrator.enableToolSearch();
-
-// Initial expert (always visible)
-orchestrator.registerExpert({
-  name: 'code_assistant',
-  description: 'Helps with coding tasks and code generation',
-  systemMessage: 'You are a helpful coding assistant...',
-  guardianPolicy: 'Allow read-only file access',
-  tools: [new FilesystemTool()],
-});
-
-// On-demand experts (discoverable via search)
-orchestrator.registerExpert({
-  name: 'database_expert',
-  description: 'Database design, optimization, and query analysis',
-  systemMessage: 'You are a database expert...',
-  guardianPolicy: 'Allow read-only operations',
-  visibility: 'on-demand',
-  tags: ['database', 'sql', 'optimization'],
-});
+const tools = httpTool();
 
-orchestrator.registerExpert({
-  name: 'security_auditor',
-  description: 'Security vulnerability assessment and best practices',
-  systemMessage: 'You are a security expert...',
-  guardianPolicy: 'Allow read-only file access',
-  visibility: 'on-demand',
-  tags: ['security', 'audit', 'vulnerabilities'],
+await runAgent({
+  model,
+  prompt: 'Fetch the data from https://api.example.com/status',
+  tools,
+  maxSteps: 5,
 });
-
-await orchestrator.start();
-
-// Now the Driver can:
-// - Use code_assistant directly
-// - Search for "database" and activate database_expert when needed
-// - Search for "security" and activate security_auditor when needed
 ```
 
-## 🎥 Streaming Support
+### `jsonTool()`
 
-SmartAgent supports token-by-token streaming for real-time output during LLM generation:
+Returns: `json_validate`, `json_transform`
 
 ```typescript
-const orchestrator = new DualAgentOrchestrator({
-  openaiToken: 'sk-...',
-  defaultProvider: 'openai',
-  guardianPolicyPrompt: '...',
-
-  // Token streaming callback
-  onToken: (token, source) => {
-    // source is 'driver' or 'guardian'
-    process.stdout.write(token);
-  },
+const tools = jsonTool();
+
+// Direct usage:
+const result = await tools.json_validate.execute({
+  jsonString: '{"name":"test","value":42}',
+  requiredFields: ['name', 'value'],
 });
+// → "Valid JSON: object with 2 keys"
 ```
 
-This is perfect for CLI applications or UIs that need to show progress as the agent thinks.
+## Streaming & Callbacks 🎥
 
-## 🖼️ Vision Support
-
-Pass images to vision-capable models for multimodal tasks:
+Monitor the agent in real-time:
 
 ```typescript
-import { readFileSync } from 'fs';
+const result = await runAgent({
+  model,
+  prompt: 'Analyze this data...',
+  tools,
+  maxSteps: 10,
 
-// Load image as base64
-const imageBase64 = readFileSync('screenshot.png').toString('base64');
+  // Token-by-token streaming
+  onToken: (delta) => process.stdout.write(delta),
 
-// Run task with images
-const result = await orchestrator.run(
-  'Analyze this UI screenshot and describe any usability issues',
-  { images: [imageBase64] }
-);
+  // Tool call notifications
+  onToolCall: (toolName) => console.log(`\n🔧 Calling: ${toolName}`),
+});
 ```
 
-## 📊 Progress Events
+## Context Overflow Handling 💥
 
-Get real-time feedback on task execution with the `onProgress` callback:
+For long-running agents that might exceed the model's context window, use the compaction subpath:
 
 ```typescript
-const orchestrator = new DualAgentOrchestrator({
-  openaiToken: 'sk-...',
-  guardianPolicyPrompt: '...',
-  logPrefix: '[MyAgent]',  // Optional prefix for log messages
-
-  onProgress: (event) => {
-    // Pre-formatted log message ready for output
-    console.log(event.logMessage);
-
-    // Or handle specific event types
-    switch (event.type) {
-      case 'tool_proposed':
-        console.log(`Proposing: ${event.toolName}.${event.action}`);
-        break;
-      case 'tool_approved':
-        console.log(`✓ Approved`);
-        break;
-      case 'tool_rejected':
-        console.log(`✗ Rejected: ${event.reason}`);
-        break;
-      case 'task_completed':
-        console.log(`Done in ${event.iteration} iterations`);
-        break;
-    }
+import { runAgent } from '@push.rocks/smartagent';
+import { compactMessages } from '@push.rocks/smartagent/compaction';
+
+const result = await runAgent({
+  model,
+  prompt: 'Process all 500 files...',
+  tools,
+  maxSteps: 100,
+
+  onContextOverflow: async (messages) => {
+    // Summarize the conversation to free up context space
+    return await compactMessages(model, messages);
   },
 });
 ```
 
-**Event Types**: `task_started`, `iteration_started`, `tool_proposed`, `guardian_evaluating`, `tool_approved`, `tool_rejected`, `tool_executing`, `tool_completed`, `task_completed`, `clarification_needed`, `max_iterations`, `max_rejections`
-
-## 🔧 Native Tool Calling
+## Output Truncation ✂️
 
-For providers that support native tool calling (like Ollama with certain models), SmartAgent can use the provider's built-in tool calling API instead of XML parsing:
+Prevent large tool outputs from consuming too much context:
 
 ```typescript
-const orchestrator = new DualAgentOrchestrator({
-  ollamaToken: 'http://localhost:11434',  // Ollama endpoint
-  defaultProvider: 'ollama',
-  guardianPolicyPrompt: '...',
+import { truncateOutput } from '@push.rocks/smartagent';
 
-  // Enable native tool calling
-  useNativeToolCalling: true,
+const { content, truncated, notice } = truncateOutput(hugeOutput, {
+  maxLines: 2000,   // default
+  maxBytes: 50_000, // default
 });
 ```
 
-When `useNativeToolCalling` is enabled:
-- Tools are converted to JSON schema format automatically
-- The provider handles tool call parsing natively
-- Streaming still works with `[THINKING]` and `[OUTPUT]` markers for supported models
-- Tool calls appear as `toolName_actionName` (e.g., `json_validate`)
-
-This is more efficient for models that support it and avoids potential XML parsing issues.
-
-## Guardian Policy Examples
-
-The Guardian's power comes from your policy. Here are battle-tested examples:
-
-### 🔐 Strict Security Policy
-
-```typescript
-const securityPolicy = `
-SECURITY POLICY:
-1. REJECT any file operations outside /home/user/workspace
-2. REJECT any shell commands that could modify system state
-3. REJECT any HTTP requests to internal/private IP ranges
-4. REJECT any attempts to read environment variables or credentials
-5. FLAG and REJECT obfuscated code execution
-
-When rejecting, always explain:
-- What policy was violated
-- What would be a safer alternative
-`;
-```
-
-### 🛠️ Development Environment Policy
-
-```typescript
-const devPolicy = `
-DEVELOPMENT POLICY:
-- Allow file operations only within the project directory
-- Allow npm/pnpm commands for package management
-- Allow git commands for version control
-- Allow HTTP requests to public APIs only
-- REJECT direct database modifications
-- REJECT commands that could affect other users
-
-Always verify:
-- File paths are relative or within project bounds
-- Commands don't have dangerous flags (--force, -rf)
-`;
-```
-
-### 🦕 Deno Code Execution Policy
-
-```typescript
-const denoPolicy = `
-DENO CODE EXECUTION POLICY:
-- ONLY allow 'read' permission for files within the workspace
-- REJECT 'all' permission unless explicitly justified for the task
-- REJECT 'run' permission (subprocess execution) without specific justification
-- REJECT code that attempts to:
-  - Access credentials or environment secrets (even with 'env' permission)
-  - Make network requests to internal/private IP ranges
-  - Write to system directories
-- FLAG obfuscated or encoded code (base64, eval with dynamic strings)
-- Prefer sandboxed execution (no permissions) when possible
-
-When evaluating code:
-- Review the actual code content, not just permissions
-- Consider what data the code could exfiltrate
-- Verify network endpoints are legitimate public APIs
-`;
-```
-
-## Configuration Options
+The built-in tool factories use `truncateOutput` internally.
 
-```typescript
-interface IDualAgentOptions {
-  // Provider tokens (from @push.rocks/smartai)
-  openaiToken?: string;
-  anthropicToken?: string;
-  perplexityToken?: string;
-  groqToken?: string;
-  xaiToken?: string;
-  ollamaToken?: string;  // URL for Ollama endpoint
-
-  // 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
-
-  // Agent configuration
-  driverSystemMessage?: string;     // Custom system message for Driver
-  guardianPolicyPrompt: string;     // REQUIRED: Policy for Guardian to enforce
-  name?: string;                    // Agent system name
-  verbose?: boolean;                // Enable verbose logging
-
-  // Native tool calling
-  useNativeToolCalling?: boolean;   // Use provider's native tool calling API (default: false)
-
-  // Limits
-  maxIterations?: number;           // Max task iterations (default: 20)
-  maxConsecutiveRejections?: number; // Abort after N rejections (default: 3)
-  maxResultChars?: number;          // Max chars for tool results before truncation (default: 15000)
-  maxHistoryMessages?: number;      // Max history messages for API (default: 20)
-
-  // Callbacks
-  onProgress?: (event: IProgressEvent) => void;  // Progress event callback
-  onToken?: (token: string, source: 'driver' | 'guardian') => void;  // Streaming callback
-  logPrefix?: string;               // Prefix for log messages
-}
-```
+## Multi-Turn Conversations 💬
 
-## Result Interface
+Pass the returned `messages` back for multi-turn interactions:
 
 ```typescript
-interface IDualAgentRunResult {
-  success: boolean;           // Whether task completed successfully
-  completed: boolean;         // Task completion status
-  result: string;             // Final result or response
-  iterations: number;         // Number of iterations taken
-  history: IAgentMessage[];   // Full conversation history
-  status: TDualAgentRunStatus; // 'completed' | 'max_iterations_reached' | etc.
-  toolCallCount?: number;     // Number of tool calls made
-  rejectionCount?: number;    // Number of Guardian rejections
-  toolLog?: IToolExecutionLog[]; // Detailed tool execution log
-  error?: string;             // Error message if status is 'error'
-}
-
-type TDualAgentRunStatus =
-  | 'completed'
-  | 'in_progress'
-  | 'max_iterations_reached'
-  | 'max_rejections_reached'
-  | 'clarification_needed'
-  | 'error';
-```
-
-## Custom Tools
-
-Create custom tools by extending `BaseToolWrapper`:
-
-```typescript
-import { BaseToolWrapper, IToolAction, IToolExecutionResult } from '@push.rocks/smartagent';
-
-class MyCustomTool extends BaseToolWrapper {
-  public name = 'custom';
-  public description = 'My custom tool for specific operations';
-
-  public actions: IToolAction[] = [
-    {
-      name: 'myAction',
-      description: 'Performs a custom action',
-      parameters: {
-        type: 'object',
-        properties: {
-          input: { type: 'string', description: 'Input for the action' },
-        },
-        required: ['input'],
-      },
-    },
-  ];
-
-  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;
-  }
-
-  public async execute(action: string, params: Record<string, unknown>): Promise<IToolExecutionResult> {
-    this.validateAction(action);
-    this.ensureInitialized();
-
-    if (action === 'myAction') {
-      return {
-        success: true,
-        result: { processed: params.input },
-        summary: `Processed input: ${params.input}`,  // Optional human-readable summary
-      };
-    }
-
-    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}"`;
-  }
-}
-
-// Register custom tool
-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();
+// First turn
+const turn1 = await runAgent({
+  model,
+  prompt: 'Create a project structure',
+  tools,
+  maxSteps: 10,
+});
 
-const orchestrator = new DualAgentOrchestrator({
-  smartAiInstance: smartai,  // Reuse existing instance
-  guardianPolicyPrompt: '...',
+// Second turn — continues the conversation
+const turn2 = await runAgent({
+  model,
+  prompt: 'Now add a README to the project',
+  tools,
+  maxSteps: 10,
+  messages: turn1.messages, // pass history
 });
+```
 
-await orchestrator.start();
-// ... use orchestrator ...
-await orchestrator.stop();
+## Exports
 
-// SmartAi instance lifecycle is managed separately
-await smartai.stop();
-```
+### Main (`@push.rocks/smartagent`)
 
-## Supported Providers
+| Export | Type | Description |
+|--------|------|-------------|
+| `runAgent` | function | Core agentic loop |
+| `ToolRegistry` | class | Tool collection helper |
+| `truncateOutput` | function | Output truncation utility |
+| `ContextOverflowError` | class | Error type for context overflow |
+| `tool` | function | Re-exported from `@push.rocks/smartai` |
+| `z` | object | Re-exported Zod for schema definitions |
+| `stepCountIs` | function | Re-exported from AI SDK |
+| `jsonSchema` | function | Re-exported from `@push.rocks/smartai` |
 
-SmartAgent supports all providers from `@push.rocks/smartai`:
+### Tools (`@push.rocks/smartagent/tools`)
 
-| Provider | Driver | Guardian |
-|----------|:------:|:--------:|
-| OpenAI | ✅ | ✅ |
-| Anthropic | ✅ | ✅ |
-| Perplexity | ✅ | ✅ |
-| Groq | ✅ | ✅ |
-| Ollama | ✅ | ✅ |
-| XAI | ✅ | ✅ |
-| Exo | ✅ | ✅ |
+| Export | Type | Description |
+|--------|------|-------------|
+| `filesystemTool` | factory | File operations (read, write, list, delete) |
+| `shellTool` | factory | Shell command execution |
+| `httpTool` | factory | HTTP GET/POST requests |
+| `jsonTool` | factory | JSON validation and transformation |
 
-**💡 Pro tip**: Use a faster/cheaper model for Guardian (like Groq) and a more capable model for Driver:
+### Compaction (`@push.rocks/smartagent/compaction`)
 
-```typescript
-const orchestrator = new DualAgentOrchestrator({
-  openaiToken: 'sk-...',
-  groqToken: 'gsk-...',
-  defaultProvider: 'openai',    // Driver uses OpenAI
-  guardianProvider: 'groq',     // Guardian uses Groq (faster, cheaper)
-  guardianPolicyPrompt: '...',
-});
-```
+| Export | Type | Description |
+|--------|------|-------------|
+| `compactMessages` | function | Summarize message history to free context |
 
-## API Reference
-
-### DualAgentOrchestrator
-
-| Method | Description |
-|--------|-------------|
-| `start()` | Initialize all tools and AI providers |
-| `stop()` | Cleanup all tools and resources |
-| `run(task, options?)` | Execute a task with optional images for vision |
-| `continueTask(input)` | Continue a task with user input |
-| `registerTool(tool, options?)` | Register a custom tool with optional visibility settings |
-| `registerStandardTools()` | Register all built-in tools (Filesystem, HTTP, Shell, Browser, Deno) |
-| `registerScopedFilesystemTool(basePath, excludePatterns?)` | Register filesystem tool with path restriction |
-| `registerExpert(config)` | Register a specialized sub-agent as a tool |
-| `enableToolSearch()` | Enable tool discovery and activation for the Driver |
-| `setGuardianPolicy(policy)` | Update Guardian policy at runtime |
-| `getHistory()` | Get conversation history |
-| `getToolNames()` | Get list of registered tool names |
-| `getRegistry()` | Get the ToolRegistry for advanced operations |
-| `isActive()` | Check if orchestrator is running |
-
-### Exports
+## Dependencies
 
-```typescript
-// Main classes
-export { DualAgentOrchestrator } from '@push.rocks/smartagent';
-export { DriverAgent } from '@push.rocks/smartagent';
-export { GuardianAgent } from '@push.rocks/smartagent';
-
-// Tool Registry
-export { ToolRegistry } from '@push.rocks/smartagent';
-
-// Tools
-export { BaseToolWrapper } from '@push.rocks/smartagent';
-export { FilesystemTool, type IFilesystemToolOptions } from '@push.rocks/smartagent';
-export { HttpTool } from '@push.rocks/smartagent';
-export { ShellTool } from '@push.rocks/smartagent';
-export { BrowserTool } from '@push.rocks/smartagent';
-export { DenoTool, type TDenoPermission } from '@push.rocks/smartagent';
-export { JsonValidatorTool } from '@push.rocks/smartagent';
-export { ToolSearchTool } from '@push.rocks/smartagent';
-export { ExpertTool } from '@push.rocks/smartagent';
-
-// Types and interfaces
-export * from '@push.rocks/smartagent';  // All interfaces (IExpertConfig, IToolMetadata, etc.)
-
-// Re-exported from @push.rocks/smartai
-export { type ISmartAiOptions, type TProvider, type ChatMessage, type ChatOptions, type ChatResponse };
-```
+- **[`@push.rocks/smartai`](https://code.foss.global/push.rocks/smartai)** — Provider registry, `getModel()`, re-exports `tool`/`jsonSchema`
+- **[`ai`](https://www.npmjs.com/package/ai)** v6 — Vercel AI SDK (`streamText`, `stepCountIs`, `ModelMessage`)
+- **[`zod`](https://www.npmjs.com/package/zod)** — Tool input schema definitions
+- **[`@push.rocks/smartfs`](https://code.foss.global/push.rocks/smartfs)** — Filesystem tool implementation
+- **[`@push.rocks/smartshell`](https://code.foss.global/push.rocks/smartshell)** — Shell tool implementation
+- **[`@push.rocks/smartrequest`](https://code.foss.global/push.rocks/smartrequest)** — HTTP tool implementation
 
 ## License and Legal Information