@push.rocks/smartagent 1.0.2

package/readme.md

@@ -0,0 +1,299 @@
+# @push.rocks/smartagent
+A dual-agent agentic framework with Driver and Guardian agents for safe, policy-controlled AI task execution.
+
+## Install
+```bash
+npm install @push.rocks/smartagent
+# or
+pnpm install @push.rocks/smartagent
+```
+
+## Overview
+
+SmartAgent implements a dual-agent architecture:
+
+- **Driver Agent**: Executes tasks, reasons about goals, and proposes tool calls
+- **Guardian Agent**: Evaluates tool call proposals against a policy prompt, approving or rejecting with feedback
+
+This design ensures safe tool use through AI-based policy evaluation rather than rigid programmatic rules.
+
+## Architecture
+
+```
+User Task + Guardian Policy Prompt
+              |
+    +---------------------------------------+
+    |       DualAgentOrchestrator           |
+    |                                       |
+    |  +--------+         +------------+    |
+    |  | Driver |-------> |  Guardian  |    |
+    |  | Agent  | tool    |   Agent    |    |
+    |  |        | call    |            |    |
+    |  | Reason |<--------|  Evaluate  |    |
+    |  | + Plan | approve |  against   |    |
+    |  +--------+ /reject |  policy    |    |
+    |      |      +feedback+-----------+    |
+    |      v (if approved)                  |
+    |  +-----------------------------------+|
+    |  |        Standard Tools             ||
+    |  | Filesystem | HTTP | Shell | Browser|
+    |  +-----------------------------------+|
+    +---------------------------------------+
+```
+
+## Quick Start
+
+```typescript
+import { DualAgentOrchestrator } from '@push.rocks/smartagent';
+
+// Create orchestrator with Guardian policy
+const orchestrator = new DualAgentOrchestrator({
+  openaiToken: 'sk-...',
+  defaultProvider: 'openai',
+  guardianPolicyPrompt: `
+    FILE SYSTEM POLICY:
+    - ONLY allow reading/writing within /tmp or the current working directory
+    - REJECT operations on system directories or sensitive files
+
+    SHELL POLICY:
+    - Allow read-only commands (ls, cat, grep, echo)
+    - REJECT destructive commands (rm, mv, chmod) without explicit justification
+
+    FLAG any attempt to expose secrets or credentials.
+  `,
+});
+
+// Register standard tools
+orchestrator.registerStandardTools();
+
+// Start the orchestrator (initializes all tools)
+await orchestrator.start();
+
+// Run a task
+const result = await orchestrator.run('List all TypeScript files in the current directory');
+
+console.log('Success:', result.success);
+console.log('Result:', result.result);
+console.log('Iterations:', result.iterations);
+
+// Cleanup
+await orchestrator.stop();
+```
+
+## Standard Tools
+
+### FilesystemTool
+File and directory operations using `@push.rocks/smartfs`.
+
+**Actions**: `read`, `write`, `append`, `list`, `delete`, `exists`, `stat`, `copy`, `move`, `mkdir`
+
+```typescript
+// Example tool call by Driver
+<tool_call>
+  <tool>filesystem</tool>
+  <action>read</action>
+  <params>{"path": "/tmp/config.json"}</params>
+  <reasoning>Need to read the configuration file to understand the settings</reasoning>
+</tool_call>
+```
+
+### HttpTool
+HTTP requests using `@push.rocks/smartrequest`.
+
+**Actions**: `get`, `post`, `put`, `patch`, `delete`
+
+```typescript
+<tool_call>
+  <tool>http</tool>
+  <action>get</action>
+  <params>{"url": "https://api.example.com/data"}</params>
+  <reasoning>Fetching data from the API endpoint</reasoning>
+</tool_call>
+```
+
+### ShellTool
+Secure shell command execution using `@push.rocks/smartshell` with `execSpawn` (no shell injection).
+
+**Actions**: `execute`, `which`
+
+```typescript
+<tool_call>
+  <tool>shell</tool>
+  <action>execute</action>
+  <params>{"command": "ls", "args": ["-la", "/tmp"]}</params>
+  <reasoning>Listing directory contents to find relevant files</reasoning>
+</tool_call>
+```
+
+### BrowserTool
+Web page interaction using `@push.rocks/smartbrowser` (Puppeteer-based).
+
+**Actions**: `screenshot`, `pdf`, `evaluate`, `getPageContent`
+
+```typescript
+<tool_call>
+  <tool>browser</tool>
+  <action>getPageContent</action>
+  <params>{"url": "https://example.com"}</params>
+  <reasoning>Extracting text content from the webpage</reasoning>
+</tool_call>
+```
+
+## Guardian Policy Examples
+
+### Strict Security Policy
+```typescript
+const securityPolicy = `
+SECURITY POLICY:
+1. REJECT any file operations outside /home/user/workspace
+2. REJECT any shell commands that could modify system state
+3. REJECT any HTTP requests to internal/private IP ranges
+4. REJECT any attempts to read environment variables or credentials
+5. FLAG and REJECT obfuscated code execution
+
+When rejecting, always explain:
+- What policy was violated
+- What would be a safer alternative
+`;
+```
+
+### Development Environment Policy
+```typescript
+const devPolicy = `
+DEVELOPMENT POLICY:
+- Allow file operations only within the project directory
+- Allow npm/pnpm commands for package management
+- Allow git commands for version control
+- Allow HTTP requests to public APIs only
+- REJECT direct database modifications
+- REJECT commands that could affect other users
+
+Always verify:
+- File paths are relative or within project bounds
+- Commands don't have dangerous flags (--force, -rf)
+`;
+```
+
+## Configuration Options
+
+```typescript
+interface IDualAgentOptions {
+  // Provider tokens (from @push.rocks/smartai)
+  openaiToken?: string;
+  anthropicToken?: string;
+  perplexityToken?: string;
+  groqToken?: string;
+  xaiToken?: string;
+
+  // Provider selection
+  defaultProvider?: TProvider;      // For both Driver and Guardian
+  guardianProvider?: TProvider;     // Optional: separate provider for Guardian
+
+  // Agent configuration
+  driverSystemMessage?: string;     // Custom system message for Driver
+  guardianPolicyPrompt: string;     // REQUIRED: Policy for Guardian to enforce
+
+  // Limits
+  maxIterations?: number;           // Max task iterations (default: 20)
+  maxConsecutiveRejections?: number; // Abort after N rejections (default: 3)
+}
+```
+
+## Result Interface
+
+```typescript
+interface IDualAgentRunResult {
+  success: boolean;           // Whether task completed successfully
+  completed: boolean;         // Task completion status
+  result: string;             // Final result or response
+  iterations: number;         // Number of iterations taken
+  history: IAgentMessage[];   // Full conversation history
+  status: TDualAgentRunStatus; // 'completed' | 'max_iterations_reached' | etc.
+}
+```
+
+## Custom Tools
+
+Create custom tools by extending `BaseToolWrapper`:
+
+```typescript
+import { BaseToolWrapper, IToolAction, IToolExecutionResult } from '@push.rocks/smartagent';
+
+class MyCustomTool extends BaseToolWrapper {
+  public name = 'custom';
+  public description = 'My custom tool for specific operations';
+
+  public actions: IToolAction[] = [
+    {
+      name: 'myAction',
+      description: 'Performs a custom action',
+      parameters: {
+        type: 'object',
+        properties: {
+          input: { type: 'string', description: 'Input for the action' },
+        },
+        required: ['input'],
+      },
+    },
+  ];
+
+  public async initialize(): Promise<void> {
+    this.isInitialized = true;
+  }
+
+  public async cleanup(): Promise<void> {
+    this.isInitialized = false;
+  }
+
+  public async execute(action: string, params: Record<string, unknown>): Promise<IToolExecutionResult> {
+    this.validateAction(action);
+    this.ensureInitialized();
+
+    if (action === 'myAction') {
+      return {
+        success: true,
+        result: { processed: params.input },
+      };
+    }
+
+    return { success: false, error: 'Unknown action' };
+  }
+
+  public getCallSummary(action: string, params: Record<string, unknown>): string {
+    return `Custom action "${action}" with input "${params.input}"`;
+  }
+}
+
+// Register custom tool
+orchestrator.registerTool(new MyCustomTool());
+```
+
+## Supported Providers
+
+| Provider | Driver | Guardian |
+|----------|:------:|:--------:|
+| OpenAI | Yes | Yes |
+| Anthropic | Yes | Yes |
+| Perplexity | Yes | Yes |
+| Groq | Yes | Yes |
+| Ollama | Yes | Yes |
+| XAI | Yes | Yes |
+
+## License and Legal Information
+
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+
+### Company Information
+
+Task Venture Capital GmbH
+Registered at District court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/smartagent',
+  version: '1.0.2',
+  description: 'an agentic framework built on top of @push.rocks/smartai'
+}

package/ts/index.ts

@@ -0,0 +1,29 @@
+import * as plugins from './plugins.js';
+
+// Export the dual-agent orchestrator (main entry point)
+export { DualAgentOrchestrator } from './smartagent.classes.dualagent.js';
+
+// Export individual agents
+export { DriverAgent } from './smartagent.classes.driveragent.js';
+export { GuardianAgent } from './smartagent.classes.guardianagent.js';
+
+// Export base tool class for custom tool creation
+export { BaseToolWrapper } from './smartagent.tools.base.js';
+
+// Export standard tools
+export { FilesystemTool } from './smartagent.tools.filesystem.js';
+export { HttpTool } from './smartagent.tools.http.js';
+export { ShellTool } from './smartagent.tools.shell.js';
+export { BrowserTool } from './smartagent.tools.browser.js';
+
+// Export all interfaces
+export * from './smartagent.interfaces.js';
+
+// Re-export useful types from smartai
+export {
+  type ISmartAiOptions,
+  type TProvider,
+  type ChatMessage,
+  type ChatOptions,
+  type ChatResponse,
+} from '@push.rocks/smartai';

package/ts/plugins.ts

@@ -0,0 +1,14 @@
+// @push.rocks scope
+import * as smartai from '@push.rocks/smartai';
+import * as smartfs from '@push.rocks/smartfs';
+import * as smartrequest from '@push.rocks/smartrequest';
+import * as smartbrowser from '@push.rocks/smartbrowser';
+import * as smartshell from '@push.rocks/smartshell';
+
+export {
+  smartai,
+  smartfs,
+  smartrequest,
+  smartbrowser,
+  smartshell,
+};

package/ts/smartagent.classes.driveragent.ts

@@ -0,0 +1,321 @@
+import * as plugins from './plugins.js';
+import * as interfaces from './smartagent.interfaces.js';
+import type { BaseToolWrapper } from './smartagent.tools.base.js';
+
+/**
+ * DriverAgent - Executes tasks by reasoning and proposing tool calls
+ * Works in conjunction with GuardianAgent for approval
+ */
+export class DriverAgent {
+  private provider: plugins.smartai.MultiModalModel;
+  private systemMessage: string;
+  private messageHistory: plugins.smartai.ChatMessage[] = [];
+  private tools: Map<string, BaseToolWrapper> = new Map();
+
+  constructor(
+    provider: plugins.smartai.MultiModalModel,
+    systemMessage?: string
+  ) {
+    this.provider = provider;
+    this.systemMessage = systemMessage || this.getDefaultSystemMessage();
+  }
+
+  /**
+   * Register a tool for use by the driver
+   */
+  public registerTool(tool: BaseToolWrapper): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  /**
+   * Get all registered tools
+   */
+  public getTools(): Map<string, BaseToolWrapper> {
+    return this.tools;
+  }
+
+  /**
+   * Initialize a new conversation for a task
+   */
+  public async startTask(task: string): Promise<interfaces.IAgentMessage> {
+    // Reset message history
+    this.messageHistory = [];
+
+    // Build the user message
+    const userMessage = `TASK: ${task}\n\nAnalyze this task and determine what actions are needed. If you need to use a tool, provide a tool call proposal.`;
+
+    // Add to history
+    this.messageHistory.push({
+      role: 'user',
+      content: userMessage,
+    });
+
+    // Build tool descriptions for the system message
+    const toolDescriptions = this.buildToolDescriptions();
+    const fullSystemMessage = `${this.systemMessage}\n\n## Available Tools\n${toolDescriptions}`;
+
+    // Get response from provider
+    const response = await this.provider.chat({
+      systemMessage: fullSystemMessage,
+      userMessage: userMessage,
+      messageHistory: [],
+    });
+
+    // Add assistant response to history
+    this.messageHistory.push({
+      role: 'assistant',
+      content: response.message,
+    });
+
+    return {
+      role: 'assistant',
+      content: response.message,
+    };
+  }
+
+  /**
+   * Continue the conversation with feedback or results
+   */
+  public async continueWithMessage(message: string): Promise<interfaces.IAgentMessage> {
+    // Add the new message to history
+    this.messageHistory.push({
+      role: 'user',
+      content: message,
+    });
+
+    // Build tool descriptions for the system message
+    const toolDescriptions = this.buildToolDescriptions();
+    const fullSystemMessage = `${this.systemMessage}\n\n## Available Tools\n${toolDescriptions}`;
+
+    // Get response from provider (pass all but last user message as history)
+    const historyForChat = this.messageHistory.slice(0, -1);
+
+    const response = await this.provider.chat({
+      systemMessage: fullSystemMessage,
+      userMessage: message,
+      messageHistory: historyForChat,
+    });
+
+    // Add assistant response to history
+    this.messageHistory.push({
+      role: 'assistant',
+      content: response.message,
+    });
+
+    return {
+      role: 'assistant',
+      content: response.message,
+    };
+  }
+
+  /**
+   * Parse tool call proposals from assistant response
+   */
+  public parseToolCallProposals(response: string): interfaces.IToolCallProposal[] {
+    const proposals: interfaces.IToolCallProposal[] = [];
+
+    // Match <tool_call>...</tool_call> blocks
+    const toolCallRegex = /<tool_call>([\s\S]*?)<\/tool_call>/g;
+    let match;
+
+    while ((match = toolCallRegex.exec(response)) !== null) {
+      const content = match[1];
+
+      try {
+        const proposal = this.parseToolCallContent(content);
+        if (proposal) {
+          proposals.push(proposal);
+        }
+      } catch (error) {
+        // Skip malformed tool calls
+        console.warn('Failed to parse tool call:', error);
+      }
+    }
+
+    return proposals;
+  }
+
+  /**
+   * Parse the content inside a tool_call block
+   */
+  private parseToolCallContent(content: string): interfaces.IToolCallProposal | null {
+    // Extract tool name
+    const toolMatch = content.match(/<tool>(.*?)<\/tool>/s);
+    if (!toolMatch) return null;
+    const toolName = toolMatch[1].trim();
+
+    // Extract action
+    const actionMatch = content.match(/<action>(.*?)<\/action>/s);
+    if (!actionMatch) return null;
+    const action = actionMatch[1].trim();
+
+    // Extract params (JSON)
+    const paramsMatch = content.match(/<params>([\s\S]*?)<\/params>/);
+    let params: Record<string, unknown> = {};
+    if (paramsMatch) {
+      try {
+        params = JSON.parse(paramsMatch[1].trim());
+      } catch {
+        // Try to extract individual parameters if JSON fails
+        params = this.extractParamsFromXml(paramsMatch[1]);
+      }
+    }
+
+    // Extract reasoning (optional)
+    const reasoningMatch = content.match(/<reasoning>([\s\S]*?)<\/reasoning>/);
+    const reasoning = reasoningMatch ? reasoningMatch[1].trim() : undefined;
+
+    return {
+      proposalId: this.generateProposalId(),
+      toolName,
+      action,
+      params,
+      reasoning,
+    };
+  }
+
+  /**
+   * Extract parameters from XML-like format when JSON parsing fails
+   */
+  private extractParamsFromXml(content: string): Record<string, unknown> {
+    const params: Record<string, unknown> = {};
+    const paramRegex = /<(\w+)>([\s\S]*?)<\/\1>/g;
+    let match;
+
+    while ((match = paramRegex.exec(content)) !== null) {
+      const key = match[1];
+      let value: unknown = match[2].trim();
+
+      // Try to parse as JSON for arrays/objects
+      try {
+        value = JSON.parse(value as string);
+      } catch {
+        // Keep as string if not valid JSON
+      }
+
+      params[key] = value;
+    }
+
+    return params;
+  }
+
+  /**
+   * Check if the response indicates task completion
+   */
+  public isTaskComplete(response: string): boolean {
+    // Check for explicit completion markers
+    const completionMarkers = [
+      '<task_complete>',
+      '<task_completed>',
+      'TASK COMPLETE',
+      'Task completed successfully',
+    ];
+
+    const lowerResponse = response.toLowerCase();
+    return completionMarkers.some(marker =>
+      lowerResponse.includes(marker.toLowerCase())
+    );
+  }
+
+  /**
+   * Check if the response needs clarification or user input
+   */
+  public needsClarification(response: string): boolean {
+    const clarificationMarkers = [
+      '<needs_clarification>',
+      '<question>',
+      'please clarify',
+      'could you specify',
+      'what do you mean by',
+    ];
+
+    const lowerResponse = response.toLowerCase();
+    return clarificationMarkers.some(marker =>
+      lowerResponse.includes(marker.toLowerCase())
+    );
+  }
+
+  /**
+   * Extract the final result from a completed task
+   */
+  public extractTaskResult(response: string): string | null {
+    // Try to extract from result tags
+    const resultMatch = response.match(/<task_result>([\s\S]*?)<\/task_result>/);
+    if (resultMatch) {
+      return resultMatch[1].trim();
+    }
+
+    const completeMatch = response.match(/<task_complete>([\s\S]*?)<\/task_complete>/);
+    if (completeMatch) {
+      return completeMatch[1].trim();
+    }
+
+    return null;
+  }
+
+  /**
+   * Build tool descriptions for the system message
+   */
+  private buildToolDescriptions(): string {
+    const descriptions: string[] = [];
+
+    for (const tool of this.tools.values()) {
+      descriptions.push(tool.getFullDescription());
+    }
+
+    return descriptions.join('\n\n');
+  }
+
+  /**
+   * Generate a unique proposal ID
+   */
+  private generateProposalId(): string {
+    return `prop_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+  }
+
+  /**
+   * Get the default system message for the driver
+   */
+  private getDefaultSystemMessage(): string {
+    return `You are an AI assistant that executes tasks by using available tools.
+
+## Your Role
+You analyze tasks, break them down into steps, and use tools to accomplish goals.
+
+## Tool Usage Format
+When you need to use a tool, output a tool call proposal in this format:
+
+<tool_call>
+  <tool>tool_name</tool>
+  <action>action_name</action>
+  <params>
+    {"param1": "value1", "param2": "value2"}
+  </params>
+  <reasoning>Brief explanation of why this action is needed</reasoning>
+</tool_call>
+
+## Guidelines
+1. Think step by step about what needs to be done
+2. Use only the tools that are available to you
+3. Provide clear reasoning for each tool call
+4. If a tool call is rejected, adapt your approach based on the feedback
+5. When the task is complete, indicate this clearly:
+
+<task_complete>
+  Brief summary of what was accomplished
+</task_complete>
+
+## Important
+- Only propose ONE tool call at a time
+- Wait for the result before proposing the next action
+- If you encounter an error, analyze it and try an alternative approach
+- If you need clarification, ask using <needs_clarification>your question</needs_clarification>`;
+  }
+
+  /**
+   * Reset the conversation state
+   */
+  public reset(): void {
+    this.messageHistory = [];
+  }
+}