@push.rocks/smartagent 1.6.2 → 1.8.0

package/readme.md

@@ -37,20 +37,19 @@ flowchart TB
     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["Standard Tools"]
-        FS["Filesystem"]
-        HTTP["HTTP"]
-        Shell["Shell"]
-        Browser["Browser"]
-        Deno["Deno"]
-        JSON["JSON Validator"]
+    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
@@ -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>
@@ -258,6 +266,157 @@ Validate and format JSON data. Perfect for agents to self-check their JSON outpu
 </tool_call>
 ```
 
+### 🔍 ToolSearchTool
+
+Enable the Driver to discover and activate on-demand tools at runtime.
+
+**Actions**: `search`, `list`, `activate`, `details`
+
+```typescript
+// Enable tool search (adds the 'tools' tool)
+orchestrator.enableToolSearch();
+```
+
+```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',
+});
+```
+
+```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();
+
+// The Driver can now:
+// 1. tools.search({"query": "database"}) -> finds MySpecializedTool
+// 2. tools.activate({"name": "myspecialized"}) -> enables it
+// 3. myspecialized.action({...}) -> use the tool
+```
+
+### Expert SubAgent Example
+
+```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'],
+});
+
+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 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
 
 SmartAgent supports token-by-token streaming for real-time output during LLM generation:
@@ -330,6 +489,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 +583,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 +598,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)
@@ -573,12 +759,15 @@ const orchestrator = new DualAgentOrchestrator({
 | `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)` | Register a custom tool |
-| `registerStandardTools()` | Register all built-in tools |
+| `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
@@ -589,6 +778,9 @@ 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';
@@ -597,9 +789,11 @@ 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
+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 };

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -7,6 +7,9 @@ export { DualAgentOrchestrator } from './smartagent.classes.dualagent.js';
 export { DriverAgent } from './smartagent.classes.driveragent.js';
 export { GuardianAgent } from './smartagent.classes.guardianagent.js';
 
+// Export tool registry and related classes
+export { ToolRegistry } from './smartagent.classes.toolregistry.js';
+
 // Export base tool class for custom tool creation
 export { BaseToolWrapper } from './smartagent.tools.base.js';
 
@@ -18,6 +21,10 @@ export { BrowserTool } from './smartagent.tools.browser.js';
 export { DenoTool, type TDenoPermission } from './smartagent.tools.deno.js';
 export { JsonValidatorTool } from './smartagent.tools.json.js';
 
+// Export tool search and expert tools
+export { ToolSearchTool } from './smartagent.tools.search.js';
+export { ExpertTool } from './smartagent.tools.expert.js';
+
 // Export all interfaces
 export * from './smartagent.interfaces.js';
 

package/ts/smartagent.classes.dualagent.ts

@@ -8,6 +8,9 @@ import { HttpTool } from './smartagent.tools.http.js';
 import { ShellTool } from './smartagent.tools.shell.js';
 import { BrowserTool } from './smartagent.tools.browser.js';
 import { DenoTool } from './smartagent.tools.deno.js';
+import { ToolRegistry } from './smartagent.classes.toolregistry.js';
+import { ToolSearchTool } from './smartagent.tools.search.js';
+import { ExpertTool } from './smartagent.tools.expert.js';
 
 /**
  * DualAgentOrchestrator - Coordinates Driver and Guardian agents
@@ -20,7 +23,7 @@ export class DualAgentOrchestrator {
   private guardianProvider: plugins.smartai.MultiModalModel;
   private driver: DriverAgent;
   private guardian: GuardianAgent;
-  private tools: Map<string, BaseToolWrapper> = new Map();
+  private registry: ToolRegistry = new ToolRegistry();
   private isRunning = false;
   private conversationHistory: interfaces.IAgentMessage[] = [];
   private ownsSmartAi = true; // true if we created the SmartAi instance, false if it was provided
@@ -125,19 +128,55 @@ export class DualAgentOrchestrator {
   }
 
   /**
-   * Register a custom tool
+   * Register a custom tool with optional visibility settings
    */
-  public registerTool(tool: BaseToolWrapper): void {
-    this.tools.set(tool.name, tool);
-    // Register with agents if they exist (they're created in start())
-    if (this.driver) {
-      this.driver.registerTool(tool);
-    }
-    if (this.guardian) {
-      this.guardian.registerTool(tool);
+  public registerTool(
+    tool: BaseToolWrapper,
+    options?: interfaces.IToolRegistrationOptions
+  ): void {
+    this.registry.register(tool, options);
+
+    // If initial visibility and agents exist, register with them
+    const visibility = options?.visibility ?? 'initial';
+    if (visibility === 'initial') {
+      if (this.driver) {
+        this.driver.registerTool(tool);
+      }
+      if (this.guardian) {
+        this.guardian.registerTool(tool);
+      }
     }
   }
 
+  /**
+   * Register an expert (subagent) as a tool
+   */
+  public registerExpert(config: interfaces.IExpertConfig): void {
+    const expert = new ExpertTool(config, this.smartai);
+    this.registerTool(expert, {
+      visibility: config.visibility,
+      tags: config.tags,
+      category: config.category ?? 'expert',
+    });
+  }
+
+  /**
+   * Enable tool search functionality
+   * This adds a 'tools' tool that allows the Driver to discover and activate on-demand tools
+   */
+  public enableToolSearch(): void {
+    const searchTool = new ToolSearchTool(this.registry, (tool) => {
+      // Callback when an on-demand tool is activated
+      if (this.driver) {
+        this.driver.registerTool(tool);
+      }
+      if (this.guardian) {
+        this.guardian.registerTool(tool);
+      }
+    });
+    this.registerTool(searchTool); // Always initial visibility
+  }
+
   /**
    * Register all standard tools
    */
@@ -193,19 +232,14 @@ export class DualAgentOrchestrator {
     });
     this.guardian = new GuardianAgent(this.guardianProvider, this.options.guardianPolicyPrompt);
 
-    // Register any tools that were added before start() with the agents
-    for (const tool of this.tools.values()) {
+    // Register visible tools with agents
+    for (const tool of this.registry.getVisibleTools()) {
       this.driver.registerTool(tool);
       this.guardian.registerTool(tool);
     }
 
-    // Initialize all tools
-    const initPromises: Promise<void>[] = [];
-    for (const tool of this.tools.values()) {
-      initPromises.push(tool.initialize());
-    }
-
-    await Promise.all(initPromises);
+    // Initialize visible tools
+    await this.registry.initializeVisibleTools();
     this.isRunning = true;
   }
 
@@ -213,13 +247,7 @@ export class DualAgentOrchestrator {
    * Cleanup all tools
    */
   public async stop(): Promise<void> {
-    const cleanupPromises: Promise<void>[] = [];
-
-    for (const tool of this.tools.values()) {
-      cleanupPromises.push(tool.cleanup());
-    }
-
-    await Promise.all(cleanupPromises);
+    await this.registry.cleanup();
 
     // Only stop smartai if we created it (don't stop external instances)
     if (this.ownsSmartAi) {
@@ -432,7 +460,7 @@ Please output the exact XML format above.`
         });
 
         // Execute the tool
-        const tool = this.tools.get(proposal.toolName);
+        const tool = this.registry.getTool(proposal.toolName);
         if (!tool) {
           const errorMessage = `Tool "${proposal.toolName}" not found.`;
           driverResponse = await this.driver.continueWithMessage(
@@ -652,6 +680,13 @@ Please output the exact XML format above.`
    * Get registered tool names
    */
   public getToolNames(): string[] {
-    return Array.from(this.tools.keys());
+    return this.registry.getAllMetadata().map((m) => m.name);
+  }
+
+  /**
+   * Get the tool registry for advanced operations
+   */
+  public getRegistry(): ToolRegistry {
+    return this.registry;
   }
 }

package/ts/smartagent.classes.toolregistry.ts

@@ -0,0 +1,188 @@
+import * as interfaces from './smartagent.interfaces.js';
+import { BaseToolWrapper } from './smartagent.tools.base.js';
+
+/**
+ * ToolRegistry - Manages tool registration, visibility, and lifecycle
+ *
+ * Responsibilities:
+ * - Track all registered tools with their metadata
+ * - Manage visibility (initial vs on-demand)
+ * - Handle activation of on-demand tools
+ * - Provide search functionality
+ */
+export class ToolRegistry {
+  private tools: Map<string, BaseToolWrapper> = new Map();
+  private metadata: Map<string, interfaces.IToolMetadata> = new Map();
+  private activated: Set<string> = new Set();
+
+  /**
+   * Register a tool with optional visibility settings
+   */
+  register(tool: BaseToolWrapper, options: interfaces.IToolRegistrationOptions = {}): void {
+    const visibility = options.visibility ?? 'initial';
+
+    this.tools.set(tool.name, tool);
+    this.metadata.set(tool.name, {
+      name: tool.name,
+      description: tool.description,
+      actions: tool.actions,
+      visibility,
+      isActivated: visibility === 'initial',
+      isInitialized: false,
+      tags: options.tags,
+      category: options.category,
+    });
+
+    if (visibility === 'initial') {
+      this.activated.add(tool.name);
+    }
+  }
+
+  /**
+   * Get tools visible to the Driver (initial + activated on-demand)
+   */
+  getVisibleTools(): BaseToolWrapper[] {
+    return Array.from(this.tools.entries())
+      .filter(([name]) => this.activated.has(name))
+      .map(([, tool]) => tool);
+  }
+
+  /**
+   * Get all tools (for search results)
+   */
+  getAllTools(): BaseToolWrapper[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Get a specific tool by name
+   */
+  getTool(name: string): BaseToolWrapper | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Get metadata for a tool
+   */
+  getMetadata(name: string): interfaces.IToolMetadata | undefined {
+    return this.metadata.get(name);
+  }
+
+  /**
+   * Get all metadata
+   */
+  getAllMetadata(): interfaces.IToolMetadata[] {
+    return Array.from(this.metadata.values());
+  }
+
+  /**
+   * Search tools by query (matches name, description, tags, action names)
+   */
+  search(query: string): interfaces.IToolMetadata[] {
+    const q = query.toLowerCase();
+    return this.getAllMetadata().filter((meta) => {
+      if (meta.name.toLowerCase().includes(q)) return true;
+      if (meta.description.toLowerCase().includes(q)) return true;
+      if (meta.tags?.some((t) => t.toLowerCase().includes(q))) return true;
+      if (meta.category?.toLowerCase().includes(q)) return true;
+      if (
+        meta.actions.some(
+          (a) => a.name.toLowerCase().includes(q) || a.description.toLowerCase().includes(q)
+        )
+      )
+        return true;
+      return false;
+    });
+  }
+
+  /**
+   * Activate an on-demand tool
+   */
+  async activate(name: string): Promise<{ success: boolean; error?: string }> {
+    const tool = this.tools.get(name);
+    const meta = this.metadata.get(name);
+
+    if (!tool || !meta) {
+      return { success: false, error: `Tool "${name}" not found` };
+    }
+
+    if (this.activated.has(name)) {
+      return { success: true }; // Already activated
+    }
+
+    // Initialize if not already initialized
+    if (!meta.isInitialized) {
+      await tool.initialize();
+      meta.isInitialized = true;
+    }
+
+    this.activated.add(name);
+    meta.isActivated = true;
+
+    return { success: true };
+  }
+
+  /**
+   * Check if a tool is activated
+   */
+  isActivated(name: string): boolean {
+    return this.activated.has(name);
+  }
+
+  /**
+   * Initialize all initial (visible) tools
+   */
+  async initializeVisibleTools(): Promise<void> {
+    const promises: Promise<void>[] = [];
+
+    for (const [name, tool] of this.tools) {
+      const meta = this.metadata.get(name);
+      if (meta && this.activated.has(name) && !meta.isInitialized) {
+        promises.push(
+          tool.initialize().then(() => {
+            meta.isInitialized = true;
+          })
+        );
+      }
+    }
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * Cleanup all initialized tools
+   */
+  async cleanup(): Promise<void> {
+    const promises: Promise<void>[] = [];
+
+    for (const [name, tool] of this.tools) {
+      const meta = this.metadata.get(name);
+      if (meta?.isInitialized) {
+        promises.push(tool.cleanup());
+      }
+    }
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * Check if a tool exists in the registry
+   */
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Get the number of registered tools
+   */
+  get size(): number {
+    return this.tools.size;
+  }
+
+  /**
+   * Get the number of activated tools
+   */
+  get activatedCount(): number {
+    return this.activated.size;
+  }
+}