feat(docs): document native tool calling support and update README to clarify standard and additional tools

changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2026-01-20 - 1.7.0 - feat(docs)
+document native tool calling support and update README to clarify standard and additional tools
+
+- Add 'Native Tool Calling' section documenting useNativeToolCalling option and behavior for providers (e.g., Ollama).
+- Explain tool name mapping when native tool calling is enabled (toolName_actionName) and streaming markers ([THINKING], [OUTPUT]).
+- Add example showing enabling useNativeToolCalling and note ollamaToken config option (Ollama endpoint).
+- Clarify that registerStandardTools() registers five tools (Filesystem, HTTP, Shell, Browser, Deno) and that JsonValidatorTool must be registered manually as an additional tool.
+- Documentation-only changes (README updates) — no code functionality changed in this diff.
+
 ## 2026-01-20 - 1.6.2 - fix(release)
 bump version to 1.6.2
 

readme.hints.md

@@ -5,18 +5,20 @@
 
 ## Architecture
 - **DualAgentOrchestrator**: Main entry point, coordinates Driver and Guardian agents
-- **DriverAgent**: Reasons about tasks, plans steps, proposes tool calls
+- **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
+## 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
-6. **JsonValidatorTool** - JSON validation and formatting
+
+## Additional Tools (must register manually)
+6. **JsonValidatorTool** - JSON validation and formatting (NOT in registerStandardTools)
 
 ## Key Features
 - Token streaming support (`onToken` callback)
@@ -25,6 +27,14 @@
 - 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

readme.md

@@ -50,7 +50,6 @@ flowchart TB
         Shell["Shell"]
         Browser["Browser"]
         Deno["Deno"]
-        JSON["JSON Validator"]
     end
 
     Task --> Orchestrator
@@ -100,7 +99,7 @@ await orchestrator.stop();
 
 ## Standard Tools
 
-SmartAgent comes with six battle-tested tools out of the box:
+SmartAgent comes with five battle-tested tools out of the box via `registerStandardTools()`:
 
 ### 🗂️ FilesystemTool
 
@@ -231,12 +230,21 @@ By default, code runs **fully sandboxed with no permissions**. Permissions must
 </tool_call>
 ```
 
+## Additional Tools
+
 ### 📋 JsonValidatorTool
 
 Validate and format JSON data. Perfect for agents to self-check their JSON output before completing tasks.
 
 **Actions**: `validate`, `format`
 
+```typescript
+import { JsonValidatorTool } from '@push.rocks/smartagent';
+
+// Register the JSON validator tool (not included in registerStandardTools)
+orchestrator.registerTool(new JsonValidatorTool());
+```
+
 ```typescript
 // Validate JSON with required field checking
 <tool_call>
@@ -330,6 +338,29 @@ const orchestrator = new DualAgentOrchestrator({
 
 **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
+
+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:
+
+```typescript
+const orchestrator = new DualAgentOrchestrator({
+  ollamaToken: 'http://localhost:11434',  // Ollama endpoint
+  defaultProvider: 'ollama',
+  guardianPolicyPrompt: '...',
+
+  // Enable native tool calling
+  useNativeToolCalling: true,
+});
+```
+
+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:
@@ -401,6 +432,7 @@ interface IDualAgentOptions {
   perplexityToken?: string;
   groqToken?: string;
   xaiToken?: string;
+  ollamaToken?: string;  // URL for Ollama endpoint
 
   // Use existing SmartAi instance (optional - avoids duplicate providers)
   smartAiInstance?: SmartAi;
@@ -415,6 +447,9 @@ interface IDualAgentOptions {
   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)
@@ -574,7 +609,7 @@ const orchestrator = new DualAgentOrchestrator({
 | `run(task, options?)` | Execute a task with optional images for vision |
 | `continueTask(input)` | Continue a task with user input |
 | `registerTool(tool)` | Register a custom tool |
-| `registerStandardTools()` | Register all built-in tools |
+| `registerStandardTools()` | Register all built-in tools (Filesystem, HTTP, Shell, Browser, Deno) |
 | `registerScopedFilesystemTool(basePath, excludePatterns?)` | Register filesystem tool with path restriction |
 | `setGuardianPolicy(policy)` | Update Guardian policy at runtime |
 | `getHistory()` | Get conversation history |

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartagent',
-  version: '1.6.2',
+  version: '1.7.0',
   description: 'an agentic framework built on top of @push.rocks/smartai'
 }