@instaclaw/dispatch 0.4.0 → 0.5.0

package/dist/connection.js

@@ -37,13 +37,17 @@ export function connect(opts) {
             const result = await executeCommand(command);
             commandsExecuted++;
             if (result.screenshotBuffer && result.screenshotMeta) {
-                // Screenshot: send metadata text frame, then binary frame
+                // Screenshot (or batch with screenshot): send metadata text frame, then binary frame
                 const meta = {
                     id: command.id,
                     type: "screenshot_result",
                     ...result.screenshotMeta,
                     size: result.screenshotBuffer.length,
                 };
+                // For batch commands, include action results in the metadata frame
+                if (result.data) {
+                    meta.data = result.data;
+                }
                 ws?.send(JSON.stringify(meta));
                 ws?.send(result.screenshotBuffer);
             }

package/dist/executor.js

@@ -32,6 +32,8 @@ export async function executeCommand(command) {
                 return await doDrag(params);
             case "windows":
                 return await listWindows();
+            case "batch":
+                return await executeBatch(params);
             default:
                 return { success: false, error: `Unknown command type: ${type}` };
         }
@@ -40,10 +42,87 @@ export async function executeCommand(command) {
         return { success: false, error: String(err) };
     }
 }
+/**
+ * Execute multiple actions sequentially with optional per-action wait times.
+ * Returns results for all actions; stops on first failure.
+ * Optionally takes a screenshot after the batch completes.
+ */
+async function executeBatch(params) {
+    const actions = params.actions;
+    if (!Array.isArray(actions) || actions.length === 0) {
+        return { success: false, error: "batch requires a non-empty 'actions' array" };
+    }
+    if (actions.length > 20) {
+        return { success: false, error: "batch limited to 20 actions max" };
+    }
+    const results = [];
+    for (const action of actions) {
+        const cmd = {
+            id: `batch_${Date.now()}`,
+            type: action.type,
+            params: action.params || {},
+        };
+        // Don't allow nested batches or screenshots inside a batch
+        if (cmd.type === "batch") {
+            results.push({ type: "batch", success: false, error: "nested batches not allowed" });
+            break;
+        }
+        if (cmd.type === "screenshot") {
+            results.push({ type: "screenshot", success: false, error: "use screenshotAfter param instead of screenshot in batch" });
+            break;
+        }
+        const result = await executeCommand(cmd);
+        results.push({
+            type: action.type,
+            success: result.success,
+            data: result.data,
+            error: result.error,
+        });
+        if (!result.success)
+            break; // Stop batch on first failure
+        // Per-action wait time (default: 50ms between actions)
+        const waitMs = action.waitAfterMs ?? 50;
+        if (waitMs > 0) {
+            await new Promise((r) => setTimeout(r, waitMs));
+        }
+    }
+    // Optionally take a screenshot after the batch completes
+    const screenshotAfter = params.screenshotAfter !== false; // default true
+    let screenshotResult;
+    if (screenshotAfter) {
+        // Wait for screen to settle before capturing
+        const settleMs = typeof params.settleMs === "number" ? params.settleMs : 300;
+        if (settleMs > 0) {
+            await new Promise((r) => setTimeout(r, settleMs));
+        }
+        screenshotResult = await takeScreenshot({
+            format: params.screenshotFormat || "webp",
+            quality: Number(params.screenshotQuality) || 55,
+        });
+    }
+    const batchResult = {
+        success: results.every((r) => r.success),
+        data: {
+            action: "batch",
+            actionsExecuted: results.length,
+            actionsTotal: actions.length,
+            results,
+        },
+    };
+    // If we took a screenshot, attach it
+    if (screenshotResult?.screenshotBuffer && screenshotResult.screenshotMeta) {
+        batchResult.screenshotBuffer = screenshotResult.screenshotBuffer;
+        batchResult.screenshotMeta = screenshotResult.screenshotMeta;
+        // Also include batch results in the screenshot meta so the agent gets both
+        batchResult.data.screenshotIncluded = true;
+    }
+    return batchResult;
+}
 async function takeScreenshot(params) {
     const capture = await captureScreenshot({
-        format: params.format || "jpeg",
-        quality: Number(params.quality) || 80,
+        format: params.format || "webp",
+        quality: Number(params.quality) || 55,
+        maxWidth: Number(params.maxWidth) || 1280,
     });
     // Cache coordMap for subsequent click/hover/drag commands
     lastCoordMap = capture.coordMap;

package/dist/screenshot.d.ts

@@ -1,6 +1,8 @@
 export interface ScreenshotOptions {
-    format?: "jpeg" | "png";
+    format?: "jpeg" | "png" | "webp";
     quality?: number;
+    /** Max width — downscale if screen is larger (default 1280) */
+    maxWidth?: number;
 }
 export interface ScreenshotCapture {
     buffer: Buffer;

package/dist/screenshot.js

@@ -1,38 +1,70 @@
 /**
- * Screenshot — captures screen via usecomputer, converts PNG→JPEG via sharp.
- * Separated per PRD Section 5.1 package structure.
+ * Screenshot — captures screen via usecomputer, compresses via sharp.
+ * Optimized for speed: WebP format, quality 55, resolution capped at 1280x720.
  */
 import fs from "fs";
 import path from "path";
+// Pre-warm sharp at module load (avoid dynamic import per screenshot)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let sharpFn = null;
+const sharpReady = import("sharp").then((m) => { sharpFn = m.default || m; }).catch(() => { });
+// Pre-warm usecomputer at module load
+let ucMod = null;
+const ucReady = import("usecomputer").then((m) => { ucMod = m; }).catch(() => { });
 /**
  * Capture a screenshot and return it as a buffer with metadata.
  */
 export async function captureScreenshot(opts = {}) {
-    const uc = await import("usecomputer");
+    // Ensure modules are loaded
+    if (!ucMod)
+        await ucReady;
+    if (!sharpFn)
+        await sharpReady;
+    const uc = ucMod;
     const tmpPath = path.join("/tmp", `dispatch-ss-${Date.now()}.png`);
-    const format = opts.format || "jpeg";
-    const quality = opts.quality || 80;
+    const format = opts.format || "webp";
+    const quality = opts.quality || 55;
+    const maxWidth = opts.maxWidth || 1280;
     try {
         const result = await uc.screenshot({ path: tmpPath, display: null, window: null, region: null, annotate: null });
         const pngBuffer = fs.readFileSync(tmpPath);
         let outputBuffer;
-        if (format === "jpeg") {
+        let outWidth = result.imageWidth;
+        let outHeight = result.imageHeight;
+        if (sharpFn) {
             try {
-                const sharp = (await import("sharp")).default;
-                outputBuffer = await sharp(pngBuffer).jpeg({ quality }).toBuffer();
+                let pipeline = sharpFn(pngBuffer);
+                // Downscale if wider than maxWidth (HiDPI screens capture at 2x+)
+                if (result.imageWidth > maxWidth) {
+                    pipeline = pipeline.resize(maxWidth, null, { fit: "inside", withoutEnlargement: true });
+                    const ratio = maxWidth / result.imageWidth;
+                    outWidth = maxWidth;
+                    outHeight = Math.round(result.imageHeight * ratio);
+                }
+                // Encode to target format
+                if (format === "webp") {
+                    outputBuffer = await pipeline.webp({ quality, effort: 2 }).toBuffer();
+                }
+                else if (format === "jpeg") {
+                    outputBuffer = await pipeline.jpeg({ quality }).toBuffer();
+                }
+                else {
+                    outputBuffer = await pipeline.png().toBuffer();
+                }
             }
             catch {
-                // sharp not available — fall back to PNG
+                // sharp failed — fall back to raw PNG
                 outputBuffer = pngBuffer;
             }
         }
         else {
+            // No sharp available — return raw PNG
             outputBuffer = pngBuffer;
         }
         return {
             buffer: outputBuffer,
-            width: result.imageWidth,
-            height: result.imageHeight,
+            width: outWidth,
+            height: outHeight,
             format,
             coordMap: result.coordMap,
         };

package/dist/supervisor.js

@@ -85,6 +85,13 @@ function isDangerous(cmd) {
         const key = String(p.key || "").toLowerCase();
         return DANGEROUS_KEY_COMBOS.has(key);
     }
+    // Check all sub-actions in a batch
+    if (cmd.type === "batch") {
+        const actions = p.actions;
+        if (Array.isArray(actions)) {
+            return actions.some((a) => isDangerous({ id: "", type: a.type, params: a.params || {} }));
+        }
+    }
     return false;
 }
 function formatCommand(cmd) {
@@ -100,6 +107,13 @@ function formatCommand(cmd) {
             return `Scroll ${p.direction} by ${p.amount || 3}`;
         case "drag":
             return `Drag from (${p.fromX}, ${p.fromY}) to (${p.toX}, ${p.toY})`;
+        case "batch": {
+            const actions = p.actions;
+            if (!Array.isArray(actions))
+                return "Batch (empty)";
+            const summary = actions.map((a) => formatCommand({ id: "", type: a.type, params: a.params || {} })).join(" → ");
+            return `Batch (${actions.length} actions): ${summary}`;
+        }
         default:
             return `${cmd.type}: ${JSON.stringify(p).substring(0, 80)}`;
     }

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 /** Command sent from VM agent → dispatch server → local relay */
 export interface DispatchCommand {
     id: string;
-    type: "screenshot" | "click" | "type" | "press" | "scroll" | "drag" | "windows" | "status";
+    type: "screenshot" | "click" | "type" | "press" | "scroll" | "drag" | "windows" | "status" | "batch";
     params: Record<string, unknown>;
     description?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instaclaw/dispatch",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Let your InstaClaw AI agent control your computer — screenshots, clicks, typing, and more via a secure WebSocket relay",
   "bin": {
     "instaclaw-dispatch": "./dist/index.js"