@push.rocks/smartagent 1.6.2 → 1.8.0

package/ts/smartagent.interfaces.ts

@@ -1,5 +1,65 @@
 import * as plugins from './plugins.js';
 
+// ================================
+// Tool Visibility & Registry Types
+// ================================
+
+/**
+ * Tool visibility mode
+ * - 'initial': Conveyed to model in system prompt AND discoverable via search
+ * - 'on-demand': Only discoverable via search, must be activated before use
+ */
+export type TToolVisibility = 'initial' | 'on-demand';
+
+/**
+ * Tool metadata for discovery and management
+ */
+export interface IToolMetadata {
+  name: string;
+  description: string;
+  actions: IToolAction[];
+  visibility: TToolVisibility;
+  isActivated: boolean;
+  isInitialized: boolean;
+  tags?: string[];
+  category?: string;
+}
+
+/**
+ * Options when registering a tool
+ */
+export interface IToolRegistrationOptions {
+  visibility?: TToolVisibility;
+  tags?: string[];
+  category?: string;
+}
+
+/**
+ * Configuration for creating an Expert (SubAgent)
+ */
+export interface IExpertConfig {
+  /** Unique name for the expert */
+  name: string;
+  /** Description of the expert's capabilities */
+  description: string;
+  /** System message defining expert behavior */
+  systemMessage: string;
+  /** Guardian policy for the expert's inner agent */
+  guardianPolicy: string;
+  /** AI provider (defaults to parent's provider) */
+  provider?: plugins.smartai.TProvider;
+  /** Tools available to this expert */
+  tools?: IAgentToolWrapper[];
+  /** Max iterations for expert tasks (default: 10) */
+  maxIterations?: number;
+  /** Visibility mode (default: 'initial') */
+  visibility?: TToolVisibility;
+  /** Searchable tags */
+  tags?: string[];
+  /** Category for grouping */
+  category?: string;
+}
+
 // ================================
 // Task Run Options
 // ================================

package/ts/smartagent.tools.expert.ts

@@ -0,0 +1,144 @@
+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: typeof import('./smartagent.classes.dualagent.js').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 {
+  public name: string;
+  public description: string;
+  public actions: interfaces.IToolAction[] = [
+    {
+      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'],
+      },
+    },
+  ];
+
+  private config: interfaces.IExpertConfig;
+  private smartAi: plugins.smartai.SmartAi;
+  private inner?: InstanceType<typeof DualAgentOrchestrator>;
+
+  constructor(config: interfaces.IExpertConfig, smartAi: plugins.smartai.SmartAi) {
+    super();
+    this.config = config;
+    this.smartAi = smartAi;
+    this.name = config.name;
+    this.description = config.description;
+  }
+
+  async initialize(): Promise<void> {
+    // 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 as BaseToolWrapper);
+      }
+    }
+
+    await this.inner.start();
+    this.isInitialized = true;
+  }
+
+  async cleanup(): Promise<void> {
+    if (this.inner) {
+      await this.inner.stop();
+      this.inner = undefined;
+    }
+    this.isInitialized = false;
+  }
+
+  async execute(
+    action: string,
+    params: Record<string, unknown>
+  ): Promise<interfaces.IToolExecutionResult> {
+    this.validateAction(action);
+    this.ensureInitialized();
+
+    const task = params.task as string;
+    const context = params.context as string | undefined;
+
+    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: string, params: Record<string, unknown>): string {
+    const task = params.task as string;
+    const preview = task.length > 60 ? task.substring(0, 60) + '...' : task;
+    return `Consult ${this.name}: "${preview}"`;
+  }
+
+  getToolExplanation(): string {
+    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(): interfaces.IExpertConfig {
+    return this.config;
+  }
+}

package/ts/smartagent.tools.search.ts

@@ -0,0 +1,237 @@
+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 {
+  public name = 'tools';
+  public description =
+    'Search for and activate available tools and experts. Use this to discover specialized capabilities.';
+
+  public actions: interfaces.IToolAction[] = [
+    {
+      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'],
+      },
+    },
+  ];
+
+  private registry: ToolRegistry;
+  private onToolActivated?: (tool: BaseToolWrapper) => void;
+
+  constructor(registry: ToolRegistry, onToolActivated?: (tool: BaseToolWrapper) => void) {
+    super();
+    this.registry = registry;
+    this.onToolActivated = onToolActivated;
+  }
+
+  async initialize(): Promise<void> {
+    this.isInitialized = true;
+  }
+
+  async cleanup(): Promise<void> {
+    this.isInitialized = false;
+  }
+
+  async execute(
+    action: string,
+    params: Record<string, unknown>
+  ): Promise<interfaces.IToolExecutionResult> {
+    this.validateAction(action);
+
+    switch (action) {
+      case 'search':
+        return this.handleSearch(params.query as string);
+      case 'list':
+        return this.handleList();
+      case 'activate':
+        return this.handleActivate(params.name as string);
+      case 'details':
+        return this.handleDetails(params.name as string);
+      default:
+        return { success: false, error: `Unknown action: ${action}` };
+    }
+  }
+
+  private handleSearch(query: string): interfaces.IToolExecutionResult {
+    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}"`,
+    };
+  }
+
+  private handleList(): interfaces.IToolExecutionResult {
+    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`,
+      },
+    };
+  }
+
+  private async handleActivate(name: string): Promise<interfaces.IToolExecutionResult> {
+    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,
+    };
+  }
+
+  private handleDetails(name: string): interfaces.IToolExecutionResult {
+    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: string, params: Record<string, unknown>): string {
+    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(): string {
+    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>
+\`\`\`
+`;
+  }
+}