@fastino-ai/pioneer-cli 0.2.1 → 0.2.3

package/src/client/ToolExecutor.ts

@@ -0,0 +1,175 @@
+/**
+ * ToolExecutor - Executes CLI tools locally
+ *
+ * When the MLE Agent calls a CLI tool (bash, read_file, etc.), this executor
+ * runs it on the user's machine and returns the result.
+ */
+
+import { createBashTool } from "../tools/bash.js";
+import {
+  createReadFileTool,
+  createWriteFileTool,
+  createEditFileTool,
+  createListDirTool,
+  createSearchFilesTool,
+} from "../tools/filesystem.js";
+import type { Tool, ToolResult } from "../tools/types.js";
+
+export interface ToolExecutorOptions {
+  workingDirectory?: string;
+  allowedPaths?: string[];
+  maxFileSize?: number;
+  bashTimeout?: number;
+}
+
+export class ToolExecutor {
+  private tools: Map<string, Tool> = new Map();
+  private workingDirectory: string;
+
+  constructor(options: ToolExecutorOptions = {}) {
+    this.workingDirectory = options.workingDirectory || process.cwd();
+
+    const fsOptions = {
+      basePath: this.workingDirectory,
+      allowedPaths: options.allowedPaths,
+      maxFileSize: options.maxFileSize || 1024 * 1024, // 1MB default
+    };
+
+    const bashOptions = {
+      cwd: this.workingDirectory,
+      timeout: options.bashTimeout || 60000, // 60s default
+    };
+
+    // Register all CLI tools
+    this.registerTool(createBashTool(bashOptions));
+    this.registerTool(createReadFileTool(fsOptions));
+    this.registerTool(createWriteFileTool(fsOptions));
+    this.registerTool(createEditFileTool(fsOptions));
+    this.registerTool(createListDirTool(fsOptions));
+    this.registerTool(createSearchFilesTool(fsOptions));
+  }
+
+  private registerTool(tool: Tool): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  /**
+   * Execute a tool by name with the given arguments.
+   * Returns the output string on success, throws on error.
+   */
+  async execute(toolName: string, args: Record<string, unknown>): Promise<string> {
+    const tool = this.tools.get(toolName);
+
+    if (!tool) {
+      throw new Error(`Unknown tool: ${toolName}. Available tools: ${this.getToolNames().join(", ")}`);
+    }
+
+    // Map argument names if needed (server uses different names)
+    const mappedArgs = this.mapArguments(toolName, args);
+
+    const result = await tool.execute(mappedArgs);
+
+    if (!result.success) {
+      throw new Error(result.error || `Tool ${toolName} failed`);
+    }
+
+    return result.output;
+  }
+
+  /**
+   * Map server argument names to local tool argument names.
+   * The server uses slightly different naming conventions.
+   */
+  private mapArguments(toolName: string, args: Record<string, unknown>): Record<string, unknown> {
+    const mapped = { ...args };
+
+    switch (toolName) {
+      case "read_file":
+        // Server: file_path, start_line, end_line
+        // Local: path, start_line, end_line
+        if ("file_path" in args) {
+          mapped.path = args.file_path;
+          delete mapped.file_path;
+        }
+        break;
+
+      case "write_file":
+        // Server: file_path, content
+        // Local: path, content
+        if ("file_path" in args) {
+          mapped.path = args.file_path;
+          delete mapped.file_path;
+        }
+        break;
+
+      case "edit_file":
+        // Server: file_path, old_text, new_text
+        // Local: path, old_text, new_text
+        if ("file_path" in args) {
+          mapped.path = args.file_path;
+          delete mapped.file_path;
+        }
+        break;
+
+      case "list_directory":
+        // Both use: path, recursive, max_depth
+        break;
+
+      case "search_files":
+        // Server: path, pattern, search_content, max_results
+        // Local: path, pattern, type
+        if (args.search_content) {
+          mapped.type = "content";
+        } else {
+          mapped.type = "filename";
+        }
+        delete mapped.search_content;
+        delete mapped.max_results;
+        break;
+
+      case "bash":
+        // Both use: command, workdir
+        break;
+    }
+
+    return mapped;
+  }
+
+  /**
+   * Get list of available tool names.
+   */
+  getToolNames(): string[] {
+    return Array.from(this.tools.keys());
+  }
+
+  /**
+   * Get a tool by name.
+   */
+  getTool(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Check if a tool exists.
+   */
+  hasTool(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Get working directory.
+   */
+  getWorkingDirectory(): string {
+    return this.workingDirectory;
+  }
+
+  /**
+   * Set working directory for bash commands.
+   */
+  setWorkingDirectory(dir: string): void {
+    this.workingDirectory = dir;
+
+    // Recreate bash tool with new working directory
+    this.registerTool(createBashTool({ cwd: dir }));
+  }
+}

package/src/client/WebSocketClient.ts

@@ -0,0 +1,333 @@
+/**
+ * WebSocket client for Pioneer MLE Agent
+ *
+ * Connects to the /mle-agent/ws endpoint for bidirectional communication.
+ * Handles tool_call messages by executing tools locally and sending results back.
+ */
+
+import WebSocket from "ws";
+import { getApiKey, getBaseUrl } from "../config.js";
+
+export interface WebSocketMessage {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface ToolCallRequest {
+  call_id: string;
+  tool: string;
+  args: Record<string, unknown>;
+}
+
+/**
+ * Message format for conversation history.
+ * Matches the format sent by the backend on done event.
+ */
+export interface HistoryMessage {
+  role: "user" | "assistant" | "tool";
+  content: string;
+  tool_calls?: Array<{
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+  }>;
+  tool_call_id?: string;
+}
+
+export interface WebSocketClientCallbacks {
+  onStream?: (content: string) => void;
+  onToolStart?: (name: string, callId: string, args: Record<string, unknown>) => void;
+  onToolResult?: (name: string, callId: string, result: unknown) => void;
+  onToolError?: (name: string, callId: string, error: string) => void;
+  onToolCall?: (call: ToolCallRequest) => Promise<string>;
+  onAssistantMessage?: (content: string) => void;
+  onError?: (error: Error) => void;
+  onDone?: (messages?: HistoryMessage[]) => void;
+}
+
+export interface ChatOptions {
+  history?: HistoryMessage[];
+  fileReferences?: string[];
+  config?: { model?: string };
+}
+
+type ConnectionState = "disconnected" | "connecting" | "connected";
+
+export class WebSocketClient {
+  private ws: WebSocket | null = null;
+  private baseUrl: string;
+  private apiKey: string | undefined;
+  private callbacks: WebSocketClientCallbacks = {};
+  private state: ConnectionState = "disconnected";
+  private messageResolvers: Map<string, (value: void) => void> = new Map();
+  private donePromise: Promise<void> | null = null;
+  private doneResolver: (() => void) | null = null;
+  private doneCalled: boolean = false;  // Prevent duplicate onDone calls
+
+  constructor() {
+    // Convert HTTP URL to WebSocket URL
+    this.baseUrl = getBaseUrl()
+      .replace(/^https:/, "wss:")
+      .replace(/^http:/, "ws:")
+      .replace(/\/$/, "");
+    this.apiKey = getApiKey();
+  }
+
+  async connect(): Promise<void> {
+    if (this.state === "connected") return;
+    if (this.state === "connecting") {
+      // Wait for existing connection attempt
+      return new Promise((resolve) => {
+        const checkState = setInterval(() => {
+          if (this.state === "connected") {
+            clearInterval(checkState);
+            resolve();
+          }
+        }, 100);
+      });
+    }
+
+    this.state = "connecting";
+
+    // Build URL with optional auth token
+    let url = `${this.baseUrl}/mle-agent/ws`;
+    if (this.apiKey) {
+      url += `?token=${encodeURIComponent(this.apiKey)}`;
+    }
+
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(url);
+
+      this.ws.on("open", () => {
+        this.state = "connected";
+        resolve();
+      });
+
+      this.ws.on("error", (err: Error) => {
+        this.state = "disconnected";
+        reject(err);
+      });
+
+      this.ws.on("close", () => {
+        this.state = "disconnected";
+        // Only call onDone if not already called (prevents duplicate)
+        if (!this.doneCalled) {
+          this.doneCalled = true;
+          this.callbacks.onDone?.();
+        }
+        if (this.doneResolver) {
+          this.doneResolver();
+          this.doneResolver = null;
+        }
+      });
+
+      this.ws.on("message", async (data: WebSocket.RawData) => {
+        try {
+          const message = JSON.parse(data.toString()) as WebSocketMessage;
+          await this.handleMessage(message);
+        } catch (err: unknown) {
+          console.error("Failed to parse WebSocket message:", err);
+        }
+      });
+    });
+  }
+
+  private async handleMessage(message: WebSocketMessage): Promise<void> {
+    switch (message.type) {
+      case "stream":
+        this.callbacks.onStream?.(message.content as string);
+        break;
+
+      case "tool_start":
+        this.callbacks.onToolStart?.(
+          message.name as string,
+          message.call_id as string,
+          message.args as Record<string, unknown>
+        );
+        break;
+
+      case "tool_call":
+        // Server is asking client to execute a tool locally
+        if (this.callbacks.onToolCall) {
+          const call: ToolCallRequest = {
+            call_id: message.call_id as string,
+            tool: message.tool as string,
+            args: message.args as Record<string, unknown>,
+          };
+
+          try {
+            const result = await this.callbacks.onToolCall(call);
+            this.sendToolResult(call.call_id, result);
+          } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.sendToolResult(call.call_id, null, errorMsg);
+          }
+        } else {
+          // No tool executor configured, send error
+          this.sendToolResult(
+            message.call_id as string,
+            null,
+            "No tool executor configured on client"
+          );
+        }
+        break;
+
+      case "tool_result":
+        this.callbacks.onToolResult?.(
+          message.name as string,
+          message.call_id as string,
+          message.result
+        );
+        break;
+
+      case "tool_error":
+        this.callbacks.onToolError?.(
+          message.name as string,
+          message.call_id as string,
+          message.error as string
+        );
+        break;
+
+      case "assistant_message":
+        this.callbacks.onAssistantMessage?.(message.content as string);
+        break;
+
+      case "error":
+        this.callbacks.onError?.(new Error(message.message as string));
+        break;
+
+      case "done":
+        // Only call onDone once (prevents duplicate with ws.onclose)
+        if (!this.doneCalled) {
+          this.doneCalled = true;
+          // Pass the message history if provided by the backend
+          const messages = message.messages as HistoryMessage[] | undefined;
+          console.log("[DEBUG] Done event received, messages:", messages?.length, "roles:", messages?.map(m => m.role));
+          this.callbacks.onDone?.(messages);
+        }
+        if (this.doneResolver) {
+          this.doneResolver();
+          this.doneResolver = null;
+        }
+        break;
+
+      case "ping":
+        this.send({ type: "pong" });
+        break;
+
+      case "budget_warning":
+        // Could add a callback for this if needed
+        console.warn("Budget warning:", message.warnings);
+        break;
+    }
+  }
+
+  private send(message: WebSocketMessage): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(message));
+    }
+  }
+
+  private sendToolResult(callId: string, result: string | null, error?: string): void {
+    this.send({
+      type: "tool_result",
+      call_id: callId,
+      result: result || "",
+      ...(error && { error }),
+    });
+  }
+
+  /**
+   * Send a chat message and wait for completion.
+   * The onToolCall callback will be invoked for client-side tool execution.
+   */
+  async chat(
+    message: string,
+    callbacks: WebSocketClientCallbacks,
+    options: ChatOptions = {}
+  ): Promise<void> {
+    if (this.state !== "connected") {
+      await this.connect();
+    }
+
+    this.callbacks = callbacks;
+    this.doneCalled = false;  // Reset for new chat
+
+    // Create promise that resolves when "done" is received
+    this.donePromise = new Promise((resolve) => {
+      this.doneResolver = resolve;
+    });
+
+    // Send chat message
+    this.send({
+      type: "chat",
+      message,
+      client_type: "cli",
+      history: options.history || [],
+      file_references: options.fileReferences || [],
+      config: options.config,
+    });
+
+    // Wait for completion
+    await this.donePromise;
+  }
+
+  /**
+   * Disconnect from the WebSocket server.
+   */
+  disconnect(): void {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.state = "disconnected";
+  }
+
+  /**
+   * Check if currently connected.
+   */
+  isConnected(): boolean {
+    return this.state === "connected";
+  }
+
+  /**
+   * Check server health via HTTP (WebSocket doesn't have health check).
+   */
+  async health(): Promise<boolean> {
+    try {
+      const httpUrl = this.baseUrl
+        .replace(/^wss:/, "https:")
+        .replace(/^ws:/, "http:");
+      const response = await fetch(`${httpUrl}/health`);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * List available tools from the server.
+   */
+  async listTools(): Promise<Array<{ name: string; description: string }>> {
+    const httpUrl = this.baseUrl
+      .replace(/^wss:/, "https:")
+      .replace(/^ws:/, "http:");
+    const url = `${httpUrl}/mle-agent/tools?client_type=cli`;
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.apiKey) {
+      headers["X-API-Key"] = this.apiKey;
+    }
+
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+      throw new Error(`Failed to list tools: ${response.status}`);
+    }
+
+    const data = await response.json();
+    return data.tools || [];
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,2 @@
+export { WebSocketClient } from "./WebSocketClient.js";
+export { ToolExecutor } from "./ToolExecutor.js";