@push.rocks/smartagent 1.0.2

package/ts/smartagent.classes.dualagent.ts

@@ -0,0 +1,350 @@
+import * as plugins from './plugins.js';
+import * as interfaces from './smartagent.interfaces.js';
+import { BaseToolWrapper } from './smartagent.tools.base.js';
+import { DriverAgent } from './smartagent.classes.driveragent.js';
+import { GuardianAgent } from './smartagent.classes.guardianagent.js';
+import { FilesystemTool } from './smartagent.tools.filesystem.js';
+import { HttpTool } from './smartagent.tools.http.js';
+import { ShellTool } from './smartagent.tools.shell.js';
+import { BrowserTool } from './smartagent.tools.browser.js';
+
+/**
+ * DualAgentOrchestrator - Coordinates Driver and Guardian agents
+ * Manages the complete lifecycle of task execution with tool approval
+ */
+export class DualAgentOrchestrator {
+  private options: interfaces.IDualAgentOptions;
+  private smartai: plugins.smartai.SmartAi;
+  private driverProvider: plugins.smartai.MultiModalModel;
+  private guardianProvider: plugins.smartai.MultiModalModel;
+  private driver: DriverAgent;
+  private guardian: GuardianAgent;
+  private tools: Map<string, BaseToolWrapper> = new Map();
+  private isRunning = false;
+  private conversationHistory: interfaces.IAgentMessage[] = [];
+
+  constructor(options: interfaces.IDualAgentOptions) {
+    this.options = {
+      maxIterations: 20,
+      maxConsecutiveRejections: 3,
+      defaultProvider: 'openai',
+      ...options,
+    };
+
+    // Create SmartAi instance
+    this.smartai = new plugins.smartai.SmartAi(options);
+
+    // Get providers
+    this.driverProvider = this.getProviderByName(this.options.defaultProvider!);
+    this.guardianProvider = this.options.guardianProvider
+      ? this.getProviderByName(this.options.guardianProvider)
+      : this.driverProvider;
+
+    // Create agents
+    this.driver = new DriverAgent(this.driverProvider, options.driverSystemMessage);
+    this.guardian = new GuardianAgent(this.guardianProvider, options.guardianPolicyPrompt);
+  }
+
+  /**
+   * Get provider by name
+   */
+  private getProviderByName(providerName: plugins.smartai.TProvider): plugins.smartai.MultiModalModel {
+    switch (providerName) {
+      case 'openai':
+        return this.smartai.openaiProvider;
+      case 'anthropic':
+        return this.smartai.anthropicProvider;
+      case 'perplexity':
+        return this.smartai.perplexityProvider;
+      case 'ollama':
+        return this.smartai.ollamaProvider;
+      case 'groq':
+        return this.smartai.groqProvider;
+      case 'xai':
+        return this.smartai.xaiProvider;
+      case 'exo':
+        return this.smartai.exoProvider;
+      default:
+        return this.smartai.openaiProvider;
+    }
+  }
+
+  /**
+   * Register a custom tool
+   */
+  public registerTool(tool: BaseToolWrapper): void {
+    this.tools.set(tool.name, tool);
+    this.driver.registerTool(tool);
+    this.guardian.registerTool(tool);
+  }
+
+  /**
+   * Register all standard tools
+   */
+  public registerStandardTools(): void {
+    const standardTools = [
+      new FilesystemTool(),
+      new HttpTool(),
+      new ShellTool(),
+      new BrowserTool(),
+    ];
+
+    for (const tool of standardTools) {
+      this.registerTool(tool);
+    }
+  }
+
+  /**
+   * Initialize all tools (eager loading)
+   */
+  public async start(): Promise<void> {
+    // Start smartai
+    await this.smartai.start();
+
+    // Initialize all tools
+    const initPromises: Promise<void>[] = [];
+    for (const tool of this.tools.values()) {
+      initPromises.push(tool.initialize());
+    }
+
+    await Promise.all(initPromises);
+    this.isRunning = true;
+  }
+
+  /**
+   * 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.smartai.stop();
+    this.isRunning = false;
+    this.driver.reset();
+  }
+
+  /**
+   * Run a task through the dual-agent system
+   */
+  public async run(task: string): Promise<interfaces.IDualAgentRunResult> {
+    if (!this.isRunning) {
+      throw new Error('Orchestrator not started. Call start() first.');
+    }
+
+    this.conversationHistory = [];
+    let iterations = 0;
+    let consecutiveRejections = 0;
+    let completed = false;
+    let finalResult: string | null = null;
+
+    // Add initial task to history
+    this.conversationHistory.push({
+      role: 'user',
+      content: task,
+    });
+
+    // Start the driver with the task
+    let driverResponse = await this.driver.startTask(task);
+    this.conversationHistory.push(driverResponse);
+
+    while (
+      iterations < this.options.maxIterations! &&
+      consecutiveRejections < this.options.maxConsecutiveRejections! &&
+      !completed
+    ) {
+      iterations++;
+
+      // Check if task is complete
+      if (this.driver.isTaskComplete(driverResponse.content)) {
+        completed = true;
+        finalResult = this.driver.extractTaskResult(driverResponse.content) || driverResponse.content;
+        break;
+      }
+
+      // Check if driver needs clarification
+      if (this.driver.needsClarification(driverResponse.content)) {
+        // Return with clarification needed status
+        return {
+          success: false,
+          completed: false,
+          result: driverResponse.content,
+          iterations,
+          history: this.conversationHistory,
+          status: 'clarification_needed',
+        };
+      }
+
+      // Parse tool call proposals
+      const proposals = this.driver.parseToolCallProposals(driverResponse.content);
+
+      if (proposals.length === 0) {
+        // No tool calls, continue the conversation
+        driverResponse = await this.driver.continueWithMessage(
+          'Please either use a tool to make progress on the task, or indicate that the task is complete with <task_complete>summary</task_complete>.'
+        );
+        this.conversationHistory.push(driverResponse);
+        continue;
+      }
+
+      // Process the first proposal (one at a time)
+      const proposal = proposals[0];
+
+      // Quick validation first
+      const quickDecision = this.guardian.quickValidate(proposal);
+      let decision: interfaces.IGuardianDecision;
+
+      if (quickDecision) {
+        decision = quickDecision;
+      } else {
+        // Full AI evaluation
+        decision = await this.guardian.evaluate(proposal, task);
+      }
+
+      if (decision.decision === 'approve') {
+        consecutiveRejections = 0;
+
+        // Execute the tool
+        const tool = this.tools.get(proposal.toolName);
+        if (!tool) {
+          const errorMessage = `Tool "${proposal.toolName}" not found.`;
+          driverResponse = await this.driver.continueWithMessage(
+            `TOOL ERROR: ${errorMessage}\n\nPlease try a different approach.`
+          );
+          this.conversationHistory.push(driverResponse);
+          continue;
+        }
+
+        try {
+          const result = await tool.execute(proposal.action, proposal.params);
+
+          // Send result to driver
+          const resultMessage = result.success
+            ? `TOOL RESULT (${proposal.toolName}.${proposal.action}):\n${JSON.stringify(result.result, null, 2)}`
+            : `TOOL ERROR (${proposal.toolName}.${proposal.action}):\n${result.error}`;
+
+          this.conversationHistory.push({
+            role: 'system',
+            content: resultMessage,
+            toolCall: proposal,
+            toolResult: result,
+          });
+
+          driverResponse = await this.driver.continueWithMessage(resultMessage);
+          this.conversationHistory.push(driverResponse);
+        } catch (error) {
+          const errorMessage = `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`;
+          driverResponse = await this.driver.continueWithMessage(
+            `TOOL ERROR: ${errorMessage}\n\nPlease try a different approach.`
+          );
+          this.conversationHistory.push(driverResponse);
+        }
+      } else {
+        // Rejected
+        consecutiveRejections++;
+
+        // Build rejection feedback
+        let feedback = `TOOL CALL REJECTED by Guardian:\n`;
+        feedback += `- Reason: ${decision.reason}\n`;
+
+        if (decision.concerns && decision.concerns.length > 0) {
+          feedback += `- Concerns:\n${decision.concerns.map(c => `  - ${c}`).join('\n')}\n`;
+        }
+
+        if (decision.suggestions) {
+          feedback += `- Suggestions: ${decision.suggestions}\n`;
+        }
+
+        feedback += `\nPlease adapt your approach based on this feedback.`;
+
+        this.conversationHistory.push({
+          role: 'system',
+          content: feedback,
+          toolCall: proposal,
+          guardianDecision: decision,
+        });
+
+        driverResponse = await this.driver.continueWithMessage(feedback);
+        this.conversationHistory.push(driverResponse);
+      }
+    }
+
+    // Determine final status
+    let status: interfaces.TDualAgentRunStatus = 'completed';
+    if (!completed) {
+      if (iterations >= this.options.maxIterations!) {
+        status = 'max_iterations_reached';
+      } else if (consecutiveRejections >= this.options.maxConsecutiveRejections!) {
+        status = 'max_rejections_reached';
+      }
+    }
+
+    return {
+      success: completed,
+      completed,
+      result: finalResult || driverResponse.content,
+      iterations,
+      history: this.conversationHistory,
+      status,
+    };
+  }
+
+  /**
+   * Continue an existing task with user input
+   */
+  public async continueTask(userInput: string): Promise<interfaces.IDualAgentRunResult> {
+    if (!this.isRunning) {
+      throw new Error('Orchestrator not started. Call start() first.');
+    }
+
+    this.conversationHistory.push({
+      role: 'user',
+      content: userInput,
+    });
+
+    const driverResponse = await this.driver.continueWithMessage(userInput);
+    this.conversationHistory.push(driverResponse);
+
+    // Continue the run loop
+    // For simplicity, we return the current state - full continuation would need refactoring
+    return {
+      success: false,
+      completed: false,
+      result: driverResponse.content,
+      iterations: 1,
+      history: this.conversationHistory,
+      status: 'in_progress',
+    };
+  }
+
+  /**
+   * Get the conversation history
+   */
+  public getHistory(): interfaces.IAgentMessage[] {
+    return [...this.conversationHistory];
+  }
+
+  /**
+   * Update the guardian policy
+   */
+  public setGuardianPolicy(policyPrompt: string): void {
+    this.guardian.setPolicy(policyPrompt);
+  }
+
+  /**
+   * Check if orchestrator is running
+   */
+  public isActive(): boolean {
+    return this.isRunning;
+  }
+
+  /**
+   * Get registered tool names
+   */
+  public getToolNames(): string[] {
+    return Array.from(this.tools.keys());
+  }
+}

package/ts/smartagent.classes.guardianagent.ts

@@ -0,0 +1,241 @@
+import * as plugins from './plugins.js';
+import * as interfaces from './smartagent.interfaces.js';
+import type { BaseToolWrapper } from './smartagent.tools.base.js';
+
+/**
+ * GuardianAgent - Evaluates tool call proposals against a policy
+ * Uses AI reasoning to approve or reject tool calls
+ */
+export class GuardianAgent {
+  private provider: plugins.smartai.MultiModalModel;
+  private policyPrompt: string;
+  private tools: Map<string, BaseToolWrapper> = new Map();
+
+  constructor(
+    provider: plugins.smartai.MultiModalModel,
+    policyPrompt: string
+  ) {
+    this.provider = provider;
+    this.policyPrompt = policyPrompt;
+  }
+
+  /**
+   * Register a tool for reference during evaluation
+   */
+  public registerTool(tool: BaseToolWrapper): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  /**
+   * Evaluate a tool call proposal against the policy
+   */
+  public async evaluate(
+    proposal: interfaces.IToolCallProposal,
+    taskContext: string
+  ): Promise<interfaces.IGuardianDecision> {
+    // Get the tool to generate a human-readable summary
+    const tool = this.tools.get(proposal.toolName);
+    let callSummary = `${proposal.toolName}.${proposal.action}(${JSON.stringify(proposal.params)})`;
+
+    if (tool) {
+      try {
+        callSummary = tool.getCallSummary(proposal.action, proposal.params);
+      } catch {
+        // Fallback to basic summary
+      }
+    }
+
+    // Build the evaluation prompt
+    const evaluationPrompt = this.buildEvaluationPrompt(
+      proposal,
+      callSummary,
+      taskContext
+    );
+
+    // Get response from provider
+    const response = await this.provider.chat({
+      systemMessage: this.buildGuardianSystemMessage(),
+      userMessage: evaluationPrompt,
+      messageHistory: [],
+    });
+
+    // Parse the decision from the response
+    return this.parseDecision(response.message, proposal);
+  }
+
+  /**
+   * Build the system message for the Guardian
+   */
+  private buildGuardianSystemMessage(): string {
+    return `You are a Guardian AI responsible for evaluating tool call proposals.
+
+## Your Role
+You evaluate whether proposed tool calls are safe and aligned with the policy.
+
+## Policy to Enforce
+${this.policyPrompt}
+
+## Response Format
+For EVERY evaluation, respond with a decision in this exact format:
+
+<guardian_decision>
+  <decision>approve OR reject</decision>
+  <reason>Your detailed explanation</reason>
+  <concerns>List any concerns, even if approving</concerns>
+  <suggestions>Alternative approaches if rejecting</suggestions>
+</guardian_decision>
+
+## Guidelines
+1. Carefully analyze what the tool call will do
+2. Consider security implications
+3. Check against the policy requirements
+4. If uncertain, err on the side of caution (reject)
+5. Provide actionable feedback when rejecting`;
+  }
+
+  /**
+   * Build the evaluation prompt for a specific proposal
+   */
+  private buildEvaluationPrompt(
+    proposal: interfaces.IToolCallProposal,
+    callSummary: string,
+    taskContext: string
+  ): string {
+    const toolInfo = this.tools.get(proposal.toolName);
+    const toolDescription = toolInfo ? toolInfo.getFullDescription() : 'Unknown tool';
+
+    return `## Task Context
+${taskContext}
+
+## Tool Being Used
+${toolDescription}
+
+## Proposed Tool Call
+- **Tool**: ${proposal.toolName}
+- **Action**: ${proposal.action}
+- **Parameters**: ${JSON.stringify(proposal.params, null, 2)}
+
+## Human-Readable Summary
+${callSummary}
+
+## Driver's Reasoning
+${proposal.reasoning || 'No reasoning provided'}
+
+---
+
+Evaluate this tool call against the policy. Should it be approved or rejected?`;
+  }
+
+  /**
+   * Parse the guardian decision from the response
+   */
+  private parseDecision(
+    response: string,
+    proposal: interfaces.IToolCallProposal
+  ): interfaces.IGuardianDecision {
+    // Try to extract from XML tags
+    const decisionMatch = response.match(/<decision>(.*?)<\/decision>/s);
+    const reasonMatch = response.match(/<reason>([\s\S]*?)<\/reason>/);
+    const concernsMatch = response.match(/<concerns>([\s\S]*?)<\/concerns>/);
+    const suggestionsMatch = response.match(/<suggestions>([\s\S]*?)<\/suggestions>/);
+
+    // Determine decision
+    let decision: 'approve' | 'reject' = 'reject';
+    if (decisionMatch) {
+      const decisionText = decisionMatch[1].trim().toLowerCase();
+      decision = decisionText.includes('approve') ? 'approve' : 'reject';
+    } else {
+      // Fallback: look for approval keywords in the response
+      const lowerResponse = response.toLowerCase();
+      if (
+        lowerResponse.includes('approved') ||
+        lowerResponse.includes('i approve') ||
+        lowerResponse.includes('looks safe')
+      ) {
+        decision = 'approve';
+      }
+    }
+
+    // Extract reason
+    let reason = reasonMatch ? reasonMatch[1].trim() : '';
+    if (!reason) {
+      // Use the full response as reason if no tag found
+      reason = response.substring(0, 500);
+    }
+
+    // Extract concerns
+    const concerns: string[] = [];
+    if (concernsMatch) {
+      const concernsText = concernsMatch[1].trim();
+      if (concernsText && concernsText.toLowerCase() !== 'none') {
+        // Split by newlines or bullet points
+        const concernLines = concernsText.split(/[\n\r]+/).map(l => l.trim()).filter(l => l);
+        concerns.push(...concernLines);
+      }
+    }
+
+    // Extract suggestions
+    const suggestions = suggestionsMatch ? suggestionsMatch[1].trim() : undefined;
+
+    return {
+      decision,
+      reason,
+      concerns: concerns.length > 0 ? concerns : undefined,
+      suggestions: suggestions && suggestions.toLowerCase() !== 'none' ? suggestions : undefined,
+    };
+  }
+
+  /**
+   * Quick validation without AI (for obviously safe/unsafe operations)
+   * Returns null if AI evaluation is needed
+   */
+  public quickValidate(proposal: interfaces.IToolCallProposal): interfaces.IGuardianDecision | null {
+    // Check if tool exists
+    if (!this.tools.has(proposal.toolName)) {
+      return {
+        decision: 'reject',
+        reason: `Unknown tool: ${proposal.toolName}`,
+      };
+    }
+
+    // Check if action exists
+    const tool = this.tools.get(proposal.toolName)!;
+    const validAction = tool.actions.find(a => a.name === proposal.action);
+    if (!validAction) {
+      return {
+        decision: 'reject',
+        reason: `Unknown action "${proposal.action}" for tool "${proposal.toolName}". Available actions: ${tool.actions.map(a => a.name).join(', ')}`,
+      };
+    }
+
+    // Check required parameters
+    const schema = validAction.parameters;
+    if (schema && schema.required && Array.isArray(schema.required)) {
+      for (const requiredParam of schema.required as string[]) {
+        if (!(requiredParam in proposal.params)) {
+          return {
+            decision: 'reject',
+            reason: `Missing required parameter: ${requiredParam}`,
+          };
+        }
+      }
+    }
+
+    // Needs full AI evaluation
+    return null;
+  }
+
+  /**
+   * Update the policy prompt
+   */
+  public setPolicy(policyPrompt: string): void {
+    this.policyPrompt = policyPrompt;
+  }
+
+  /**
+   * Get current policy
+   */
+  public getPolicy(): string {
+    return this.policyPrompt;
+  }
+}