@push.rocks/smartagent 1.2.7 → 1.4.0

package/ts/smartagent.classes.driveragent.ts

@@ -10,6 +10,8 @@ export interface IDriverAgentOptions {
   systemMessage?: string;
   /** Maximum history messages to pass to API (default: 20). Set to 0 for unlimited. */
   maxHistoryMessages?: number;
+  /** Callback fired for each token during LLM generation */
+  onToken?: (token: string) => void;
 }
 
 /**
@@ -22,6 +24,7 @@ export class DriverAgent {
   private maxHistoryMessages: number;
   private messageHistory: plugins.smartai.ChatMessage[] = [];
   private tools: Map<string, BaseToolWrapper> = new Map();
+  private onToken?: (token: string) => void;
 
   constructor(
     provider: plugins.smartai.MultiModalModel,
@@ -36,9 +39,18 @@ export class DriverAgent {
     } else {
       this.systemMessage = options?.systemMessage || this.getDefaultSystemMessage();
       this.maxHistoryMessages = options?.maxHistoryMessages ?? 20;
+      this.onToken = options?.onToken;
     }
   }
 
+  /**
+   * Set the token callback for streaming mode
+   * @param callback Function to call for each generated token
+   */
+  public setOnToken(callback: (token: string) => void): void {
+    this.onToken = callback;
+  }
+
   /**
    * Register a tool for use by the driver
    */
@@ -55,8 +67,10 @@ export class DriverAgent {
 
   /**
    * Initialize a new conversation for a task
+   * @param task The task description
+   * @param images Optional base64-encoded images for vision tasks
    */
-  public async startTask(task: string): Promise<interfaces.IAgentMessage> {
+  public async startTask(task: string, images?: string[]): Promise<interfaces.IAgentMessage> {
     // Reset message history
     this.messageHistory = [];
 
@@ -85,18 +99,34 @@ export class DriverAgent {
       fullSystemMessage = this.getNoToolsSystemMessage();
     }
 
-    // Get response from provider
-    const response = await this.provider.chat({
-      systemMessage: fullSystemMessage,
-      userMessage: userMessage,
-      messageHistory: [],
-    });
+    // Get response from provider - use streaming if available and callback is set
+    let response: plugins.smartai.ChatResponse;
+
+    if (this.onToken && typeof (this.provider as any).chatStreaming === 'function') {
+      // Use streaming mode with token callback
+      response = await (this.provider as any).chatStreaming({
+        systemMessage: fullSystemMessage,
+        userMessage: userMessage,
+        messageHistory: [],
+        images: images,
+        onToken: this.onToken,
+      });
+    } else {
+      // Fallback to non-streaming mode
+      response = await this.provider.chat({
+        systemMessage: fullSystemMessage,
+        userMessage: userMessage,
+        messageHistory: [],
+        images: images,
+      });
+    }
 
-    // Add assistant response to history
-    this.messageHistory.push({
+    // Add assistant response to history (store images if provided)
+    const historyMessage: plugins.smartai.ChatMessage = {
       role: 'assistant',
       content: response.message,
-    });
+    };
+    this.messageHistory.push(historyMessage);
 
     return {
       role: 'assistant',
@@ -139,11 +169,25 @@ export class DriverAgent {
       historyForChat = fullHistory;
     }
 
-    const response = await this.provider.chat({
-      systemMessage: fullSystemMessage,
-      userMessage: message,
-      messageHistory: historyForChat,
-    });
+    // Get response from provider - use streaming if available and callback is set
+    let response: plugins.smartai.ChatResponse;
+
+    if (this.onToken && typeof (this.provider as any).chatStreaming === 'function') {
+      // Use streaming mode with token callback
+      response = await (this.provider as any).chatStreaming({
+        systemMessage: fullSystemMessage,
+        userMessage: message,
+        messageHistory: historyForChat,
+        onToken: this.onToken,
+      });
+    } else {
+      // Fallback to non-streaming mode
+      response = await this.provider.chat({
+        systemMessage: fullSystemMessage,
+        userMessage: message,
+        messageHistory: historyForChat,
+      });
+    }
 
     // Add assistant response to history
     this.messageHistory.push({

package/ts/smartagent.classes.dualagent.ts

@@ -181,9 +181,15 @@ export class DualAgentOrchestrator {
       : this.driverProvider;
 
     // NOW create agents with initialized providers
+    // Set up token callback wrapper if streaming is enabled
+    const driverOnToken = this.options.onToken
+      ? (token: string) => this.options.onToken!(token, 'driver')
+      : undefined;
+
     this.driver = new DriverAgent(this.driverProvider, {
       systemMessage: this.options.driverSystemMessage,
       maxHistoryMessages: this.options.maxHistoryMessages,
+      onToken: driverOnToken,
     });
     this.guardian = new GuardianAgent(this.guardianProvider, this.options.guardianPolicyPrompt);
 
@@ -228,8 +234,10 @@ export class DualAgentOrchestrator {
 
   /**
    * Run a task through the dual-agent system
+   * @param task The task description
+   * @param options Optional task run options (e.g., images for vision tasks)
    */
-  public async run(task: string): Promise<interfaces.IDualAgentRunResult> {
+  public async run(task: string, options?: interfaces.ITaskRunOptions): Promise<interfaces.IDualAgentRunResult> {
     if (!this.isRunning) {
       throw new Error('Orchestrator not started. Call start() first.');
     }
@@ -240,14 +248,17 @@ export class DualAgentOrchestrator {
     let completed = false;
     let finalResult: string | null = null;
 
+    // Extract images from options
+    const images = options?.images;
+
     // 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);
+    // Start the driver with the task and optional images
+    let driverResponse = await this.driver.startTask(task, images);
     this.conversationHistory.push(driverResponse);
 
     // Emit task started event

package/ts/smartagent.interfaces.ts

@@ -1,5 +1,17 @@
 import * as plugins from './plugins.js';
 
+// ================================
+// Task Run Options
+// ================================
+
+/**
+ * Options for running a task with the DualAgentOrchestrator
+ */
+export interface ITaskRunOptions {
+  /** Base64-encoded images to include with the task (for vision-capable models) */
+  images?: string[];
+}
+
 // ================================
 // Agent Configuration Interfaces
 // ================================
@@ -34,6 +46,8 @@ export interface IDualAgentOptions extends plugins.smartai.ISmartAiOptions {
   onProgress?: (event: IProgressEvent) => void;
   /** Prefix for log messages (e.g., "[README]", "[Commit]"). Default: empty */
   logPrefix?: string;
+  /** Callback fired for each token during LLM generation (streaming mode) */
+  onToken?: (token: string, source: 'driver' | 'guardian') => void;
 }
 
 // ================================

package/ts/smartagent.tools.base.ts

@@ -35,6 +35,13 @@ export abstract class BaseToolWrapper implements interfaces.IAgentToolWrapper {
    */
   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
@@ -60,14 +67,10 @@ export abstract class BaseToolWrapper implements interfaces.IAgentToolWrapper {
 
   /**
    * Get the full tool description including all actions
-   * Used for Driver's tool awareness
+   * Used for Driver's tool awareness - now delegates to getToolExplanation()
    */
   public getFullDescription(): string {
-    const actionDescriptions = this.actions
-      .map((a) => `  - ${a.name}: ${a.description}`)
-      .join('\n');
-
-    return `${this.name}: ${this.description}\nActions:\n${actionDescriptions}`;
+    return this.getToolExplanation();
   }
 
   /**

package/ts/smartagent.tools.browser.ts

@@ -176,6 +176,59 @@ export class BrowserTool extends BaseToolWrapper {
     }
   }
 
+  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':

package/ts/smartagent.tools.deno.ts

@@ -164,6 +164,45 @@ export class DenoTool extends BaseToolWrapper {
     }
   }
 
+  public getToolExplanation(): string {
+    return `## Tool: deno
+Execute TypeScript/JavaScript code in a sandboxed Deno environment with fine-grained permission control.
+
+### Actions:
+
+**execute** - Execute TypeScript/JavaScript code and return stdout/stderr
+Parameters:
+  - code (required): TypeScript/JavaScript code to execute
+  - permissions (optional): Array of Deno permissions to grant. Options: "all", "env", "net", "read", "write", "run", "sys", "ffi", "hrtime". Default: none (fully sandboxed)
+
+Example - Simple execution:
+<tool_call>
+  <tool>deno</tool>
+  <action>execute</action>
+  <params>{"code": "console.log('Hello from Deno!');"}</params>
+</tool_call>
+
+Example - With network permission:
+<tool_call>
+  <tool>deno</tool>
+  <action>execute</action>
+  <params>{"code": "const resp = await fetch('https://api.example.com/data');\\nconsole.log(await resp.text());", "permissions": ["net"]}</params>
+</tool_call>
+
+**executeWithResult** - Execute code that outputs JSON on the last line of stdout
+Parameters:
+  - code (required): Code that console.logs a JSON value on the final line
+  - permissions (optional): Array of Deno permissions to grant
+
+Example:
+<tool_call>
+  <tool>deno</tool>
+  <action>executeWithResult</action>
+  <params>{"code": "const result = { sum: 1 + 2, product: 2 * 3 };\\nconsole.log(JSON.stringify(result));"}</params>
+</tool_call>
+`;
+  }
+
   public getCallSummary(action: string, params: Record<string, unknown>): string {
     const code = params.code as string;
     const permissions = (params.permissions as string[]) || [];

package/ts/smartagent.tools.filesystem.ts

@@ -666,6 +666,170 @@ export class FilesystemTool extends BaseToolWrapper {
     }
   }
 
+  public getToolExplanation(): string {
+    return `## Tool: filesystem
+Read, write, list, and delete files and directories.
+
+### Actions:
+
+**read** - Read file contents (full or specific line range)
+Parameters:
+  - path (required): Path to the file
+  - encoding (optional): File encoding - "utf8" (default), "binary", or "base64"
+  - startLine (optional): First line to read (1-indexed, inclusive)
+  - endLine (optional): Last line to read (1-indexed, inclusive)
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>read</action>
+  <params>{"path": "/path/to/file.txt"}</params>
+</tool_call>
+
+Example with line range:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>read</action>
+  <params>{"path": "/path/to/file.txt", "startLine": 10, "endLine": 20}</params>
+</tool_call>
+
+**write** - Write content to a file (creates or overwrites)
+Parameters:
+  - path (required): Absolute path to the file
+  - content (required): Content to write
+  - encoding (optional): File encoding - "utf8" (default), "binary", or "base64"
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>write</action>
+  <params>{"path": "/path/to/output.txt", "content": "Hello, World!"}</params>
+</tool_call>
+
+**list** - List files and directories in a path
+Parameters:
+  - path (required): Directory path to list
+  - recursive (optional): List recursively (default: false)
+  - filter (optional): Glob pattern to filter results (e.g., "*.ts")
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>list</action>
+  <params>{"path": "/path/to/dir", "recursive": true, "filter": "*.ts"}</params>
+</tool_call>
+
+**exists** - Check if a file or directory exists
+Parameters:
+  - path (required): Path to check
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>exists</action>
+  <params>{"path": "/path/to/check"}</params>
+</tool_call>
+
+**mkdir** - Create a directory
+Parameters:
+  - path (required): Directory path to create
+  - recursive (optional): Create parent directories if needed (default: true)
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>mkdir</action>
+  <params>{"path": "/path/to/new/dir"}</params>
+</tool_call>
+
+**delete** - Delete a file or directory
+Parameters:
+  - path (required): Path to delete
+  - recursive (optional): For directories, delete recursively (default: false)
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>delete</action>
+  <params>{"path": "/path/to/delete", "recursive": true}</params>
+</tool_call>
+
+**copy** - Copy a file to a new location
+Parameters:
+  - source (required): Source file path
+  - destination (required): Destination file path
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>copy</action>
+  <params>{"source": "/path/to/source.txt", "destination": "/path/to/dest.txt"}</params>
+</tool_call>
+
+**move** - Move a file to a new location
+Parameters:
+  - source (required): Source file path
+  - destination (required): Destination file path
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>move</action>
+  <params>{"source": "/path/to/old.txt", "destination": "/path/to/new.txt"}</params>
+</tool_call>
+
+**stat** - Get file or directory statistics (size, dates, etc.)
+Parameters:
+  - path (required): Path to get stats for
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>stat</action>
+  <params>{"path": "/path/to/file.txt"}</params>
+</tool_call>
+
+**append** - Append content to a file
+Parameters:
+  - path (required): Absolute path to the file
+  - content (required): Content to append
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>append</action>
+  <params>{"path": "/path/to/log.txt", "content": "New log entry\\n"}</params>
+</tool_call>
+
+**tree** - Show directory structure as a tree
+Parameters:
+  - path (required): Root directory path
+  - maxDepth (optional): Maximum depth to traverse (default: 3)
+  - filter (optional): Glob pattern to filter files
+  - showSizes (optional): Include file sizes in output (default: false)
+  - format (optional): Output format - "string" (default) or "json"
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>tree</action>
+  <params>{"path": "/path/to/dir", "maxDepth": 2}</params>
+</tool_call>
+
+**glob** - Find files matching a glob pattern
+Parameters:
+  - pattern (required): Glob pattern (e.g., "**/*.ts", "src/**/*.js")
+  - path (optional): Base path to search from
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>glob</action>
+  <params>{"pattern": "**/*.ts", "path": "/path/to/project"}</params>
+</tool_call>
+`;
+  }
+
   public getCallSummary(action: string, params: Record<string, unknown>): string {
     switch (action) {
       case 'read': {

package/ts/smartagent.tools.http.ts

@@ -180,6 +180,84 @@ export class HttpTool extends BaseToolWrapper {
     }
   }
 
+  public getToolExplanation(): string {
+    return `## Tool: http
+Make HTTP requests to web APIs and services.
+
+### Actions:
+
+**get** - Make a GET request
+Parameters:
+  - url (required): URL to request
+  - headers (optional): Request headers (key-value object)
+  - query (optional): Query parameters (key-value object)
+  - timeout (optional): Timeout in milliseconds
+
+Example:
+<tool_call>
+  <tool>http</tool>
+  <action>get</action>
+  <params>{"url": "https://api.example.com/data", "headers": {"Authorization": "Bearer token123"}}</params>
+</tool_call>
+
+**post** - Make a POST request with JSON body
+Parameters:
+  - url (required): URL to request
+  - body (optional): JSON body to send
+  - headers (optional): Request headers (key-value object)
+  - query (optional): Query parameters (key-value object)
+  - timeout (optional): Timeout in milliseconds
+
+Example:
+<tool_call>
+  <tool>http</tool>
+  <action>post</action>
+  <params>{"url": "https://api.example.com/submit", "body": {"name": "test", "value": 123}}</params>
+</tool_call>
+
+**put** - Make a PUT request with JSON body
+Parameters:
+  - url (required): URL to request
+  - body (required): JSON body to send
+  - headers (optional): Request headers (key-value object)
+  - timeout (optional): Timeout in milliseconds
+
+Example:
+<tool_call>
+  <tool>http</tool>
+  <action>put</action>
+  <params>{"url": "https://api.example.com/resource/1", "body": {"name": "updated"}}</params>
+</tool_call>
+
+**patch** - Make a PATCH request with JSON body
+Parameters:
+  - url (required): URL to request
+  - body (required): JSON body to send
+  - headers (optional): Request headers (key-value object)
+  - timeout (optional): Timeout in milliseconds
+
+Example:
+<tool_call>
+  <tool>http</tool>
+  <action>patch</action>
+  <params>{"url": "https://api.example.com/resource/1", "body": {"status": "active"}}</params>
+</tool_call>
+
+**delete** - Make a DELETE request
+Parameters:
+  - url (required): URL to request
+  - headers (optional): Request headers (key-value object)
+  - timeout (optional): Timeout in milliseconds
+
+Example:
+<tool_call>
+  <tool>http</tool>
+  <action>delete</action>
+  <params>{"url": "https://api.example.com/resource/1"}</params>
+</tool_call>
+`;
+  }
+
   public getCallSummary(action: string, params: Record<string, unknown>): string {
     const method = action.toUpperCase();
     let summary = `${method} request to "${params.url}"`;