@push.rocks/smartagent 1.7.0 → 3.0.0

package/ts/smartagent.classes.guardianagent.ts

@@ -1,241 +0,0 @@
-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;
-  }
-}

package/ts/smartagent.tools.base.ts

@@ -1,83 +0,0 @@
-import * as interfaces from './smartagent.interfaces.js';
-
-/**
- * Abstract base class for tool wrappers
- * All tool implementations should extend this class
- */
-export abstract class BaseToolWrapper implements interfaces.IAgentToolWrapper {
-  abstract name: string;
-  abstract description: string;
-  abstract actions: interfaces.IToolAction[];
-
-  protected isInitialized = false;
-
-  /**
-   * Initialize the tool and any required resources
-   */
-  abstract initialize(): Promise<void>;
-
-  /**
-   * Cleanup any resources used by the tool
-   */
-  abstract cleanup(): Promise<void>;
-
-  /**
-   * Execute an action with the given parameters
-   */
-  abstract execute(
-    action: string,
-    params: Record<string, unknown>
-  ): Promise<interfaces.IToolExecutionResult>;
-
-  /**
-   * Generate a human-readable summary of what the action will do
-   * This is used by the Guardian to understand the proposed action
-   */
-  abstract getCallSummary(action: string, params: Record<string, unknown>): string;
-
-  /**
-   * Get a comprehensive explanation of this tool for LLM consumption.
-   * Tools should implement this to provide detailed usage instructions with examples.
-   * This includes parameter schemas and concrete <tool_call> XML examples.
-   */
-  abstract getToolExplanation(): string;
-
-  /**
-   * Validate that an action exists for this tool
-   * @throws Error if the action is not valid
-   */
-  protected validateAction(action: string): void {
-    const validAction = this.actions.find((a) => a.name === action);
-    if (!validAction) {
-      const availableActions = this.actions.map((a) => a.name).join(', ');
-      throw new Error(
-        `Unknown action "${action}" for tool "${this.name}". Available actions: ${availableActions}`
-      );
-    }
-  }
-
-  /**
-   * Check if the tool is initialized
-   */
-  protected ensureInitialized(): void {
-    if (!this.isInitialized) {
-      throw new Error(`Tool "${this.name}" is not initialized. Call initialize() first.`);
-    }
-  }
-
-  /**
-   * Get the full tool description including all actions
-   * Used for Driver's tool awareness - now delegates to getToolExplanation()
-   */
-  public getFullDescription(): string {
-    return this.getToolExplanation();
-  }
-
-  /**
-   * Get the JSON schema for a specific action
-   */
-  public getActionSchema(action: string): Record<string, unknown> | undefined {
-    const actionDef = this.actions.find((a) => a.name === action);
-    return actionDef?.parameters;
-  }
-}

package/ts/smartagent.tools.browser.ts

@@ -1,253 +0,0 @@
-import * as plugins from './plugins.js';
-import * as interfaces from './smartagent.interfaces.js';
-import { BaseToolWrapper } from './smartagent.tools.base.js';
-
-/**
- * Browser tool for web page interaction
- * Wraps @push.rocks/smartbrowser (Puppeteer-based)
- */
-export class BrowserTool extends BaseToolWrapper {
-  public name = 'browser';
-  public description =
-    'Interact with web pages - take screenshots, generate PDFs, and execute JavaScript on pages';
-
-  public actions: interfaces.IToolAction[] = [
-    {
-      name: 'screenshot',
-      description: 'Take a screenshot of a webpage',
-      parameters: {
-        type: 'object',
-        properties: {
-          url: { type: 'string', description: 'URL of the page to screenshot' },
-        },
-        required: ['url'],
-      },
-    },
-    {
-      name: 'pdf',
-      description: 'Generate a PDF from a webpage',
-      parameters: {
-        type: 'object',
-        properties: {
-          url: { type: 'string', description: 'URL of the page to convert to PDF' },
-        },
-        required: ['url'],
-      },
-    },
-    {
-      name: 'evaluate',
-      description:
-        'Execute JavaScript code on a webpage and return the result. The script runs in the browser context.',
-      parameters: {
-        type: 'object',
-        properties: {
-          url: { type: 'string', description: 'URL of the page to run the script on' },
-          script: {
-            type: 'string',
-            description:
-              'JavaScript code to execute. Must be a valid expression or statements that return a value.',
-          },
-        },
-        required: ['url', 'script'],
-      },
-    },
-    {
-      name: 'getPageContent',
-      description: 'Get the text content and title of a webpage',
-      parameters: {
-        type: 'object',
-        properties: {
-          url: { type: 'string', description: 'URL of the page to get content from' },
-        },
-        required: ['url'],
-      },
-    },
-  ];
-
-  private smartbrowser!: plugins.smartbrowser.SmartBrowser;
-
-  public async initialize(): Promise<void> {
-    this.smartbrowser = new plugins.smartbrowser.SmartBrowser();
-    await this.smartbrowser.start();
-    this.isInitialized = true;
-  }
-
-  public async cleanup(): Promise<void> {
-    if (this.smartbrowser) {
-      await this.smartbrowser.stop();
-    }
-    this.isInitialized = false;
-  }
-
-  public async execute(
-    action: string,
-    params: Record<string, unknown>
-  ): Promise<interfaces.IToolExecutionResult> {
-    this.validateAction(action);
-    this.ensureInitialized();
-
-    try {
-      switch (action) {
-        case 'screenshot': {
-          const result = await this.smartbrowser.screenshotFromPage(params.url as string);
-          return {
-            success: true,
-            result: {
-              url: params.url,
-              name: result.name,
-              id: result.id,
-              bufferBase64: Buffer.from(result.buffer).toString('base64'),
-              bufferLength: result.buffer.length,
-              type: 'screenshot',
-            },
-          };
-        }
-
-        case 'pdf': {
-          const result = await this.smartbrowser.pdfFromPage(params.url as string);
-          return {
-            success: true,
-            result: {
-              url: params.url,
-              name: result.name,
-              id: result.id,
-              bufferBase64: Buffer.from(result.buffer).toString('base64'),
-              bufferLength: result.buffer.length,
-              type: 'pdf',
-            },
-          };
-        }
-
-        case 'evaluate': {
-          const script = params.script as string;
-          // Create an async function from the script
-          // The script should be valid JavaScript that returns a value
-          const result = await this.smartbrowser.evaluateOnPage(params.url as string, async () => {
-            // This runs in the browser context
-            // We need to evaluate the script string dynamically
-            // eslint-disable-next-line no-eval
-            return eval(script);
-          });
-
-          return {
-            success: true,
-            result: {
-              url: params.url,
-              script: script.substring(0, 200) + (script.length > 200 ? '...' : ''),
-              evaluationResult: result,
-            },
-          };
-        }
-
-        case 'getPageContent': {
-          const result = await this.smartbrowser.evaluateOnPage(params.url as string, async () => {
-            return {
-              title: document.title,
-              textContent: document.body?.innerText || '',
-              url: window.location.href,
-            };
-          });
-
-          return {
-            success: true,
-            result: {
-              url: params.url,
-              title: result.title,
-              textContent:
-                result.textContent.length > 10000
-                  ? result.textContent.substring(0, 10000) + '... [truncated]'
-                  : result.textContent,
-              actualUrl: result.url,
-            },
-          };
-        }
-
-        default:
-          return {
-            success: false,
-            error: `Unknown action: ${action}`,
-          };
-      }
-    } catch (error) {
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-      };
-    }
-  }
-
-  public getToolExplanation(): string {
-    return `## Tool: browser
-Interact with web pages - take screenshots, generate PDFs, and execute JavaScript on pages.
-
-### Actions:
-
-**screenshot** - Take a screenshot of a webpage
-Parameters:
-  - url (required): URL of the page to screenshot
-
-Example:
-<tool_call>
-  <tool>browser</tool>
-  <action>screenshot</action>
-  <params>{"url": "https://example.com"}</params>
-</tool_call>
-
-**pdf** - Generate a PDF from a webpage
-Parameters:
-  - url (required): URL of the page to convert to PDF
-
-Example:
-<tool_call>
-  <tool>browser</tool>
-  <action>pdf</action>
-  <params>{"url": "https://example.com/report"}</params>
-</tool_call>
-
-**evaluate** - Execute JavaScript code on a webpage and return the result
-Parameters:
-  - url (required): URL of the page to run the script on
-  - script (required): JavaScript code to execute (must return a value)
-
-Example:
-<tool_call>
-  <tool>browser</tool>
-  <action>evaluate</action>
-  <params>{"url": "https://example.com", "script": "document.querySelectorAll('a').length"}</params>
-</tool_call>
-
-**getPageContent** - Get the text content and title of a webpage
-Parameters:
-  - url (required): URL of the page to get content from
-
-Example:
-<tool_call>
-  <tool>browser</tool>
-  <action>getPageContent</action>
-  <params>{"url": "https://example.com"}</params>
-</tool_call>
-`;
-  }
-
-  public getCallSummary(action: string, params: Record<string, unknown>): string {
-    switch (action) {
-      case 'screenshot':
-        return `Take screenshot of "${params.url}"`;
-
-      case 'pdf':
-        return `Generate PDF from "${params.url}"`;
-
-      case 'evaluate': {
-        const script = params.script as string;
-        const preview = script.length > 100 ? script.substring(0, 100) + '...' : script;
-        return `Execute JavaScript on "${params.url}": "${preview}"`;
-      }
-
-      case 'getPageContent':
-        return `Get text content and title from "${params.url}"`;
-
-      default:
-        return `Unknown action: ${action}`;
-    }
-  }
-}