@push.rocks/smartagent 1.0.2

package/ts/smartagent.interfaces.ts

@@ -0,0 +1,210 @@
+import * as plugins from './plugins.js';
+
+// ================================
+// Agent Configuration Interfaces
+// ================================
+
+/**
+ * Configuration options for the DualAgentOrchestrator
+ */
+export interface IDualAgentOptions extends plugins.smartai.ISmartAiOptions {
+  /** Name of the agent system */
+  name?: string;
+  /** Default AI provider for both Driver and Guardian */
+  defaultProvider?: plugins.smartai.TProvider;
+  /** Optional separate provider for Guardian (for cost optimization) */
+  guardianProvider?: plugins.smartai.TProvider;
+  /** System message for the Driver agent */
+  driverSystemMessage?: string;
+  /** Policy prompt for the Guardian agent - REQUIRED */
+  guardianPolicyPrompt: string;
+  /** Maximum iterations for task completion (default: 20) */
+  maxIterations?: number;
+  /** Maximum consecutive rejections before aborting (default: 3) */
+  maxConsecutiveRejections?: number;
+  /** Enable verbose logging */
+  verbose?: boolean;
+}
+
+// ================================
+// Message Interfaces
+// ================================
+
+/**
+ * Represents a message in the agent's conversation history
+ */
+export interface IAgentMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool' | 'guardian';
+  content: string;
+  toolName?: string;
+  toolResult?: unknown;
+  toolCall?: IToolCallProposal;
+  guardianDecision?: IGuardianDecision;
+  timestamp?: Date;
+}
+
+// ================================
+// Tool Interfaces
+// ================================
+
+/**
+ * Represents an action that a tool can perform
+ */
+export interface IToolAction {
+  /** Action name (e.g., 'read', 'write', 'delete') */
+  name: string;
+  /** Description of what this action does */
+  description: string;
+  /** JSON schema for action parameters */
+  parameters: Record<string, unknown>;
+}
+
+/**
+ * Proposed tool call from the Driver
+ */
+export interface IToolCallProposal {
+  /** Unique ID for this proposal */
+  proposalId: string;
+  /** Name of the tool */
+  toolName: string;
+  /** Specific action to perform */
+  action: string;
+  /** Parameters for the action */
+  params: Record<string, unknown>;
+  /** Driver's reasoning for this call */
+  reasoning?: string;
+}
+
+/**
+ * Result of tool execution
+ */
+export interface IToolExecutionResult {
+  success: boolean;
+  result?: unknown;
+  error?: string;
+}
+
+/**
+ * Base interface for wrapped tools
+ */
+export interface IAgentToolWrapper {
+  /** Tool name */
+  name: string;
+  /** Tool description */
+  description: string;
+  /** Available actions */
+  actions: IToolAction[];
+  /** Initialize the tool */
+  initialize(): Promise<void>;
+  /** Cleanup resources */
+  cleanup(): Promise<void>;
+  /** Execute an action */
+  execute(action: string, params: Record<string, unknown>): Promise<IToolExecutionResult>;
+  /** Get a summary for Guardian review */
+  getCallSummary(action: string, params: Record<string, unknown>): string;
+}
+
+// ================================
+// Guardian Interfaces
+// ================================
+
+/**
+ * Request for Guardian evaluation
+ */
+export interface IGuardianEvaluationRequest {
+  /** The proposed tool call */
+  proposal: IToolCallProposal;
+  /** Current task context */
+  taskContext: string;
+  /** Recent conversation history (last N messages) */
+  recentHistory: IAgentMessage[];
+  /** Summary of what the tool call will do */
+  callSummary: string;
+}
+
+/**
+ * Guardian's decision
+ */
+export interface IGuardianDecision {
+  /** Approve or reject */
+  decision: 'approve' | 'reject';
+  /** Explanation of the decision */
+  reason: string;
+  /** Specific concerns if rejected */
+  concerns?: string[];
+  /** Suggestions for the Driver if rejected */
+  suggestions?: string;
+  /** Confidence level (0-1) */
+  confidence?: number;
+}
+
+// ================================
+// Result Interfaces
+// ================================
+
+/**
+ * Log entry for tool executions
+ */
+export interface IToolExecutionLog {
+  timestamp: Date;
+  toolName: string;
+  action: string;
+  params: Record<string, unknown>;
+  guardianDecision: 'approved' | 'rejected';
+  guardianReason: string;
+  executionResult?: unknown;
+  executionError?: string;
+}
+
+/**
+ * Status of a dual-agent run
+ */
+export type TDualAgentRunStatus =
+  | 'completed'
+  | 'in_progress'
+  | 'max_iterations_reached'
+  | 'max_rejections_reached'
+  | 'clarification_needed'
+  | 'error';
+
+/**
+ * Result of a dual-agent run
+ */
+export interface IDualAgentRunResult {
+  /** Whether the task was successful */
+  success: boolean;
+  /** Whether the task is completed */
+  completed: boolean;
+  /** Final result or response */
+  result: string;
+  /** Total iterations taken */
+  iterations: number;
+  /** Full conversation history */
+  history: IAgentMessage[];
+  /** Current status */
+  status: TDualAgentRunStatus;
+  /** Number of tool calls made */
+  toolCallCount?: number;
+  /** Number of Guardian rejections */
+  rejectionCount?: number;
+  /** Tool execution log */
+  toolLog?: IToolExecutionLog[];
+  /** Error message if status is 'error' */
+  error?: string;
+}
+
+// ================================
+// Utility Types
+// ================================
+
+/**
+ * Available tool names
+ */
+export type TToolName = 'filesystem' | 'http' | 'browser' | 'shell';
+
+/**
+ * Generate a unique proposal ID
+ */
+export function generateProposalId(): string {
+  return `proposal_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}

package/ts/smartagent.tools.base.ts

@@ -0,0 +1,80 @@
+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;
+
+  /**
+   * 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
+   */
+  public getFullDescription(): string {
+    const actionDescriptions = this.actions
+      .map((a) => `  - ${a.name}: ${a.description}`)
+      .join('\n');
+
+    return `${this.name}: ${this.description}\nActions:\n${actionDescriptions}`;
+  }
+
+  /**
+   * 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

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