@push.rocks/smartagent 1.6.2 → 1.8.0

package/dist_ts/smartagent.tools.expert.d.ts

@@ -0,0 +1,27 @@
+import * as plugins from './plugins.js';
+import * as interfaces from './smartagent.interfaces.js';
+import { BaseToolWrapper } from './smartagent.tools.base.js';
+/**
+ * ExpertTool - A specialized agent wrapped as a tool
+ *
+ * Enables hierarchical agent architectures where the Driver can delegate
+ * complex tasks to specialized experts with their own tools and policies.
+ */
+export declare class ExpertTool extends BaseToolWrapper {
+    name: string;
+    description: string;
+    actions: interfaces.IToolAction[];
+    private config;
+    private smartAi;
+    private inner?;
+    constructor(config: interfaces.IExpertConfig, smartAi: plugins.smartai.SmartAi);
+    initialize(): Promise<void>;
+    cleanup(): Promise<void>;
+    execute(action: string, params: Record<string, unknown>): Promise<interfaces.IToolExecutionResult>;
+    getCallSummary(action: string, params: Record<string, unknown>): string;
+    getToolExplanation(): string;
+    /**
+     * Get the expert's configuration
+     */
+    getConfig(): interfaces.IExpertConfig;
+}

package/dist_ts/smartagent.tools.expert.js

@@ -0,0 +1,126 @@
+import * as plugins from './plugins.js';
+import * as interfaces from './smartagent.interfaces.js';
+import { BaseToolWrapper } from './smartagent.tools.base.js';
+// Forward declaration to avoid circular import at module load time
+// The actual import happens lazily in initialize()
+let DualAgentOrchestrator;
+/**
+ * ExpertTool - A specialized agent wrapped as a tool
+ *
+ * Enables hierarchical agent architectures where the Driver can delegate
+ * complex tasks to specialized experts with their own tools and policies.
+ */
+export class ExpertTool extends BaseToolWrapper {
+    name;
+    description;
+    actions = [
+        {
+            name: 'consult',
+            description: 'Delegate a task or question to this expert',
+            parameters: {
+                type: 'object',
+                properties: {
+                    task: { type: 'string', description: 'The task or question for the expert' },
+                    context: { type: 'string', description: 'Additional context to help the expert' },
+                },
+                required: ['task'],
+            },
+        },
+    ];
+    config;
+    smartAi;
+    inner;
+    constructor(config, smartAi) {
+        super();
+        this.config = config;
+        this.smartAi = smartAi;
+        this.name = config.name;
+        this.description = config.description;
+    }
+    async initialize() {
+        // Lazy import to avoid circular dependency
+        if (!DualAgentOrchestrator) {
+            const module = await import('./smartagent.classes.dualagent.js');
+            DualAgentOrchestrator = module.DualAgentOrchestrator;
+        }
+        this.inner = new DualAgentOrchestrator({
+            smartAiInstance: this.smartAi, // Share SmartAi instance
+            defaultProvider: this.config.provider,
+            driverSystemMessage: this.config.systemMessage,
+            guardianPolicyPrompt: this.config.guardianPolicy,
+            maxIterations: this.config.maxIterations ?? 10,
+        });
+        // Register expert's tools
+        if (this.config.tools) {
+            for (const tool of this.config.tools) {
+                // Tools in the config are IAgentToolWrapper, but we need BaseToolWrapper
+                // Since all our tools extend BaseToolWrapper, this cast is safe
+                this.inner.registerTool(tool);
+            }
+        }
+        await this.inner.start();
+        this.isInitialized = true;
+    }
+    async cleanup() {
+        if (this.inner) {
+            await this.inner.stop();
+            this.inner = undefined;
+        }
+        this.isInitialized = false;
+    }
+    async execute(action, params) {
+        this.validateAction(action);
+        this.ensureInitialized();
+        const task = params.task;
+        const context = params.context;
+        const fullTask = context ? `Context: ${context}\n\nTask: ${task}` : task;
+        try {
+            const result = await this.inner.run(fullTask);
+            return {
+                success: result.success,
+                result: {
+                    response: result.result,
+                    iterations: result.iterations,
+                    status: result.status,
+                },
+                summary: result.success
+                    ? `Expert "${this.name}" completed (${result.iterations} iterations)`
+                    : `Expert "${this.name}" failed: ${result.status}`,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Expert error: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    getCallSummary(action, params) {
+        const task = params.task;
+        const preview = task.length > 60 ? task.substring(0, 60) + '...' : task;
+        return `Consult ${this.name}: "${preview}"`;
+    }
+    getToolExplanation() {
+        return `## Expert: ${this.name}
+${this.description}
+
+### Usage:
+Delegate tasks to this expert when you need specialized help.
+
+\`\`\`
+<tool_call>
+  <tool>${this.name}</tool>
+  <action>consult</action>
+  <params>{"task": "Your question or task", "context": "Optional background"}</params>
+</tool_call>
+\`\`\`
+`;
+    }
+    /**
+     * Get the expert's configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC50b29scy5leHBlcnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9zbWFydGFnZW50LnRvb2xzLmV4cGVydC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEtBQUssVUFBVSxNQUFNLDRCQUE0QixDQUFDO0FBQ3pELE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSw0QkFBNEIsQ0FBQztBQUU3RCxtRUFBbUU7QUFDbkUsbURBQW1EO0FBQ25ELElBQUkscUJBQStGLENBQUM7QUFFcEc7Ozs7O0dBS0c7QUFDSCxNQUFNLE9BQU8sVUFBVyxTQUFRLGVBQWU7SUFDdEMsSUFBSSxDQUFTO0lBQ2IsV0FBVyxDQUFTO0lBQ3BCLE9BQU8sR0FBNkI7UUFDekM7WUFDRSxJQUFJLEVBQUUsU0FBUztZQUNmLFdBQVcsRUFBRSw0Q0FBNEM7WUFDekQsVUFBVSxFQUFFO2dCQUNWLElBQUksRUFBRSxRQUFRO2dCQUNkLFVBQVUsRUFBRTtvQkFDVixJQUFJLEVBQUUsRUFBRSxJQUFJLEVBQUUsUUFBUSxFQUFFLFdBQVcsRUFBRSxxQ0FBcUMsRUFBRTtvQkFDNUUsT0FBTyxFQUFFLEVBQUUsSUFBSSxFQUFFLFFBQVEsRUFBRSxXQUFXLEVBQUUsdUNBQXVDLEVBQUU7aUJBQ2xGO2dCQUNELFFBQVEsRUFBRSxDQUFDLE1BQU0sQ0FBQzthQUNuQjtTQUNGO0tBQ0YsQ0FBQztJQUVNLE1BQU0sQ0FBMkI7SUFDakMsT0FBTyxDQUEwQjtJQUNqQyxLQUFLLENBQThDO0lBRTNELFlBQVksTUFBZ0MsRUFBRSxPQUFnQztRQUM1RSxLQUFLLEVBQUUsQ0FBQztRQUNSLElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDO1FBQ3JCLElBQUksQ0FBQyxPQUFPLEdBQUcsT0FBTyxDQUFDO1FBQ3ZCLElBQUksQ0FBQyxJQUFJLEdBQUcsTUFBTSxDQUFDLElBQUksQ0FBQztRQUN4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

package/dist_ts/smartagent.tools.search.d.ts

@@ -0,0 +1,29 @@
+import * as interfaces from './smartagent.interfaces.js';
+import { BaseToolWrapper } from './smartagent.tools.base.js';
+import { ToolRegistry } from './smartagent.classes.toolregistry.js';
+/**
+ * ToolSearchTool - AI-facing interface for discovering and activating tools
+ *
+ * This tool enables the Driver to:
+ * - Search for tools by capability
+ * - List all available tools
+ * - Activate on-demand tools
+ * - Get detailed information about specific tools
+ */
+export declare class ToolSearchTool extends BaseToolWrapper {
+    name: string;
+    description: string;
+    actions: interfaces.IToolAction[];
+    private registry;
+    private onToolActivated?;
+    constructor(registry: ToolRegistry, onToolActivated?: (tool: BaseToolWrapper) => void);
+    initialize(): Promise<void>;
+    cleanup(): Promise<void>;
+    execute(action: string, params: Record<string, unknown>): Promise<interfaces.IToolExecutionResult>;
+    private handleSearch;
+    private handleList;
+    private handleActivate;
+    private handleDetails;
+    getCallSummary(action: string, params: Record<string, unknown>): string;
+    getToolExplanation(): string;
+}

package/dist_ts/smartagent.tools.search.js

@@ -0,0 +1,215 @@
+import * as interfaces from './smartagent.interfaces.js';
+import { BaseToolWrapper } from './smartagent.tools.base.js';
+import { ToolRegistry } from './smartagent.classes.toolregistry.js';
+/**
+ * ToolSearchTool - AI-facing interface for discovering and activating tools
+ *
+ * This tool enables the Driver to:
+ * - Search for tools by capability
+ * - List all available tools
+ * - Activate on-demand tools
+ * - Get detailed information about specific tools
+ */
+export class ToolSearchTool extends BaseToolWrapper {
+    name = 'tools';
+    description = 'Search for and activate available tools and experts. Use this to discover specialized capabilities.';
+    actions = [
+        {
+            name: 'search',
+            description: 'Search for tools by name, description, tags, or capabilities',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search query' },
+                },
+                required: ['query'],
+            },
+        },
+        {
+            name: 'list',
+            description: 'List all available tools grouped by visibility',
+            parameters: { type: 'object', properties: {} },
+        },
+        {
+            name: 'activate',
+            description: 'Activate an on-demand tool to make it available for use',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Name of the tool to activate' },
+                },
+                required: ['name'],
+            },
+        },
+        {
+            name: 'details',
+            description: 'Get detailed information about a specific tool',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Name of the tool' },
+                },
+                required: ['name'],
+            },
+        },
+    ];
+    registry;
+    onToolActivated;
+    constructor(registry, onToolActivated) {
+        super();
+        this.registry = registry;
+        this.onToolActivated = onToolActivated;
+    }
+    async initialize() {
+        this.isInitialized = true;
+    }
+    async cleanup() {
+        this.isInitialized = false;
+    }
+    async execute(action, params) {
+        this.validateAction(action);
+        switch (action) {
+            case 'search':
+                return this.handleSearch(params.query);
+            case 'list':
+                return this.handleList();
+            case 'activate':
+                return this.handleActivate(params.name);
+            case 'details':
+                return this.handleDetails(params.name);
+            default:
+                return { success: false, error: `Unknown action: ${action}` };
+        }
+    }
+    handleSearch(query) {
+        const results = this.registry.search(query);
+        return {
+            success: true,
+            result: results.map((m) => ({
+                name: m.name,
+                description: m.description,
+                visibility: m.visibility,
+                isActivated: m.isActivated,
+                category: m.category,
+                tags: m.tags,
+                actionCount: m.actions.length,
+            })),
+            summary: `Found ${results.length} tools matching "${query}"`,
+        };
+    }
+    handleList() {
+        const all = this.registry.getAllMetadata();
+        const initial = all.filter((m) => m.visibility === 'initial');
+        const onDemand = all.filter((m) => m.visibility === 'on-demand');
+        return {
+            success: true,
+            result: {
+                initial: initial.map((m) => ({
+                    name: m.name,
+                    description: m.description,
+                    category: m.category,
+                })),
+                onDemand: onDemand.map((m) => ({
+                    name: m.name,
+                    description: m.description,
+                    category: m.category,
+                    isActivated: m.isActivated,
+                })),
+                summary: `${initial.length} initial, ${onDemand.length} on-demand`,
+            },
+        };
+    }
+    async handleActivate(name) {
+        const result = await this.registry.activate(name);
+        if (result.success && this.onToolActivated) {
+            const tool = this.registry.getTool(name);
+            if (tool) {
+                this.onToolActivated(tool);
+            }
+        }
+        return {
+            success: result.success,
+            result: result.success ? { name, message: `Tool "${name}" is now available` } : undefined,
+            error: result.error,
+            summary: result.success ? `Activated: ${name}` : result.error,
+        };
+    }
+    handleDetails(name) {
+        const tool = this.registry.getTool(name);
+        const meta = this.registry.getMetadata(name);
+        if (!tool || !meta) {
+            return { success: false, error: `Tool "${name}" not found` };
+        }
+        return {
+            success: true,
+            result: {
+                name: meta.name,
+                description: meta.description,
+                visibility: meta.visibility,
+                isActivated: meta.isActivated,
+                category: meta.category,
+                tags: meta.tags,
+                actions: meta.actions,
+                fullExplanation: tool.getToolExplanation(),
+            },
+        };
+    }
+    getCallSummary(action, params) {
+        switch (action) {
+            case 'search':
+                return `Search tools: "${params.query}"`;
+            case 'list':
+                return 'List all tools';
+            case 'activate':
+                return `Activate tool: ${params.name}`;
+            case 'details':
+                return `Get details: ${params.name}`;
+            default:
+                return `tools.${action}`;
+        }
+    }
+    getToolExplanation() {
+        return `## Tool: tools
+Search for and manage available tools and experts.
+
+### Actions:
+
+**search** - Find tools by capability
+\`\`\`
+<tool_call>
+  <tool>tools</tool>
+  <action>search</action>
+  <params>{"query": "database"}</params>
+</tool_call>
+\`\`\`
+
+**list** - List all tools grouped by visibility
+\`\`\`
+<tool_call>
+  <tool>tools</tool>
+  <action>list</action>
+  <params>{}</params>
+</tool_call>
+\`\`\`
+
+**activate** - Activate an on-demand tool
+\`\`\`
+<tool_call>
+  <tool>tools</tool>
+  <action>activate</action>
+  <params>{"name": "database_expert"}</params>
+</tool_call>
+\`\`\`
+
+**details** - Get full information about a tool
+\`\`\`
+<tool_call>
+  <tool>tools</tool>
+  <action>details</action>
+  <params>{"name": "filesystem"}</params>
+</tool_call>
+\`\`\`
+`;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC50b29scy5zZWFyY2guanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9zbWFydGFnZW50LnRvb2xzLnNlYXJjaC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssVUFBVSxNQUFNLDRCQUE0QixDQUFDO0FBQ3pELE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSw0QkFBNEIsQ0FBQztBQUM3RCxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sc0NBQXNDLENBQUM7QUFFcEU7Ozs7Ozs7O0dBUUc7QUFDSCxNQUFNLE9BQU8sY0FBZSxTQUFRLGVBQWU7SUFDMUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUNmLFdBQVcsR0FDaEIscUdBQXFHLENBQUM7SUFFakcsT0FBTyxHQUE2QjtRQUN6QztZQUNFLElBQUksRUFBRSxRQUFRO1lBQ2QsV0FBVyxFQUFFLDhEQUE4RDtZQUMzRSxVQUFVLEVBQUU7Z0JBQ1YsSUFBSSxFQUFFLFFBQVE7Z0JBQ2QsVUFBVSxFQUFFO29CQUNWLEtBQUssRUFBRSxFQUFFLElBQUksRUFBRSxRQUFRLEVBQUUsV0FBVyxFQUFFLGNBQWMsRUFBRTtpQkFDdkQ7Z0JBQ0QsUUFBUSxFQUFFLENBQUMsT0FBTyxDQUFDO2FBQ3BCO1NBQ0Y7UUFDRDtZQUNFLElBQUksRUFBRSxNQUFNO1lBQ1osV0FBVyxFQUFFLGdEQUFnRDtZQUM3RCxVQUFVLEVBQUUsRUFBRSxJQUFJLEVBQUUsUUFBUSxFQUFFLFVBQVUsRUFBRSxFQUFFLEVBQUU7U0FDL0M7UUFDRDtZQUNFLElBQUksRUFBRSxVQUFVO1lBQ2hCLFdBQVcsRUFBRSx5REFBeUQ7WUFDdEUsVUFBVSxFQUFFO2dCQUNWLElBQUksRUFBRSxRQUFRO2dCQUNkLFVBQVUsRUFBRTtvQkFDVixJQUFJLEVBQUUsRUFBRSxJQUFJLEVBQUUsUUFBUSxFQUFFLFdBQVcsRUFBRSw4QkFBOEIsRUFBRTtpQkFDdEU7Z0JBQ0QsUUFBUSxFQUFFLENBQUMsTUFBTSxD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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartagent",
-  "version": "1.6.2",
+  "version": "1.8.0",
   "private": false,
   "description": "an agentic framework built on top of @push.rocks/smartai",
   "main": "dist_ts/index.js",

package/readme.hints.md

@@ -5,18 +5,64 @@
 
 ## 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
+- **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
+## 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)
+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)
@@ -25,6 +71,17 @@
 - 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