@instaclaw/dispatch 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { DispatchConfig } from "./types.js";
+export declare function loadConfig(): DispatchConfig | null;
+export declare function saveConfig(config: DispatchConfig): void;
+export declare function getConfigPath(): string;

package/dist/config.js

@@ -0,0 +1,21 @@
+import fs from "fs";
+import path from "path";
+const CONFIG_DIR = path.join(process.env.HOME || "~", ".instaclaw-dispatch");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export function loadConfig() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+        }
+    }
+    catch { }
+    return null;
+}
+export function saveConfig(config) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+export function getConfigPath() {
+    return CONFIG_FILE;
+}
+//# sourceMappingURL=config.js.map

package/dist/connection.d.ts

@@ -0,0 +1,19 @@
+interface ConnectionOptions {
+    vmAddress: string;
+    port: number;
+    gatewayToken: string;
+    mode: "supervised" | "autonomous";
+    /** Accept self-signed certs (TOFU) */
+    rejectUnauthorized: boolean;
+    certFingerprint?: string;
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+    onCertFingerprint?: (fingerprint: string) => void;
+}
+export declare function connect(opts: ConnectionOptions): void;
+export declare function disconnect(): void;
+export declare function getStats(): {
+    connected: boolean;
+    commandsExecuted: number;
+};
+export {};

package/dist/connection.js

@@ -0,0 +1,97 @@
+/**
+ * Connection — WebSocket client that connects to the VM's dispatch server.
+ * Handles reconnection, heartbeat, and message routing.
+ */
+import WebSocket from "ws";
+import { executeCommand } from "./executor.js";
+import { requestApproval } from "./supervisor.js";
+let ws = null;
+let reconnectDelay = 1000;
+let shouldReconnect = true;
+let commandsExecuted = 0;
+export function connect(opts) {
+    const proto = "wss";
+    const url = `${proto}://${opts.vmAddress}:${opts.port}?token=${opts.gatewayToken}`;
+    console.log(`  Connecting to ${opts.vmAddress}:${opts.port}...`);
+    ws = new WebSocket(url, {
+        rejectUnauthorized: false, // Accept self-signed certs (TOFU model)
+    });
+    ws.on("open", () => {
+        reconnectDelay = 1000; // Reset backoff
+        console.log(`  Connected to agent on ${opts.vmAddress}`);
+        opts.onConnect?.();
+    });
+    ws.on("message", async (data, isBinary) => {
+        if (isBinary)
+            return; // We don't expect binary from the server
+        try {
+            const command = JSON.parse(data.toString());
+            // Supervised mode: ask user for approval
+            if (opts.mode === "supervised") {
+                const approved = await requestApproval(command);
+                if (!approved) {
+                    sendResult(command.id, { success: false, error: "User denied the action" });
+                    return;
+                }
+            }
+            // Execute the command
+            const result = await executeCommand(command);
+            commandsExecuted++;
+            if (result.screenshotBuffer && result.screenshotMeta) {
+                // Screenshot: send metadata text frame, then binary frame
+                const meta = {
+                    id: command.id,
+                    type: "screenshot_result",
+                    ...result.screenshotMeta,
+                    size: result.screenshotBuffer.length,
+                };
+                ws?.send(JSON.stringify(meta));
+                ws?.send(result.screenshotBuffer);
+            }
+            else {
+                // Normal result
+                sendResult(command.id, {
+                    success: result.success,
+                    data: result.data,
+                    error: result.error,
+                });
+            }
+        }
+        catch (err) {
+            console.error("  Error processing command:", err);
+        }
+    });
+    ws.on("close", (code, reason) => {
+        console.log(`  Disconnected (code=${code}${reason.length ? `, reason=${reason}` : ""})`);
+        ws = null;
+        opts.onDisconnect?.();
+        if (shouldReconnect) {
+            console.log(`  Reconnecting in ${reconnectDelay / 1000}s...`);
+            setTimeout(() => connect(opts), reconnectDelay);
+            reconnectDelay = Math.min(reconnectDelay * 2, 30000);
+        }
+    });
+    ws.on("error", (err) => {
+        // Suppress ECONNREFUSED noise — close handler will reconnect
+        if (err.code !== "ECONNREFUSED") {
+            console.error("  WebSocket error:", err.message);
+        }
+    });
+    ws.on("ping", () => { ws?.pong(); });
+}
+function sendResult(id, result) {
+    if (ws?.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ id, type: "result", ...result }));
+    }
+}
+export function disconnect() {
+    shouldReconnect = false;
+    ws?.close();
+}
+export function getStats() {
+    return {
+        connected: ws?.readyState === WebSocket.OPEN,
+        commandsExecuted,
+    };
+}
+//# sourceMappingURL=connection.js.map

package/dist/executor.d.ts

@@ -0,0 +1,15 @@
+import type { DispatchCommand } from "./types.js";
+export interface ExecutionResult {
+    success: boolean;
+    data?: Record<string, unknown>;
+    /** For screenshots: raw JPEG buffer */
+    screenshotBuffer?: Buffer;
+    screenshotMeta?: {
+        width: number;
+        height: number;
+        format: string;
+        coordMap: string;
+    };
+    error?: string;
+}
+export declare function executeCommand(command: DispatchCommand): Promise<ExecutionResult>;

package/dist/executor.js

@@ -0,0 +1,116 @@
+/**
+ * Executor — receives dispatch commands and executes them via usecomputer.
+ * Returns results (action confirmations or screenshot data).
+ */
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+// Dynamic import for usecomputer (ESM)
+let uc = null;
+async function getUC() {
+    if (!uc) {
+        uc = await import("usecomputer");
+    }
+    return uc;
+}
+export async function executeCommand(command) {
+    const { type, params } = command;
+    try {
+        switch (type) {
+            case "screenshot":
+                return await takeScreenshot(params);
+            case "click":
+                return await doClick(params);
+            case "type":
+                return await doType(params);
+            case "press":
+                return await doPress(params);
+            case "scroll":
+                return await doScroll(params);
+            case "windows":
+                return await listWindows();
+            default:
+                return { success: false, error: `Unknown command type: ${type}` };
+        }
+    }
+    catch (err) {
+        return { success: false, error: String(err) };
+    }
+}
+async function takeScreenshot(params) {
+    const usecomputer = await getUC();
+    const tmpPath = path.join("/tmp", `dispatch-ss-${Date.now()}.png`);
+    try {
+        const result = await usecomputer.screenshot({ path: tmpPath, display: null, window: null, region: null, annotate: null });
+        // Read the PNG and convert to JPEG via sharp
+        const pngBuffer = fs.readFileSync(tmpPath);
+        let jpegBuffer;
+        try {
+            const sharp = (await import("sharp")).default;
+            jpegBuffer = await sharp(pngBuffer).jpeg({ quality: 80 }).toBuffer();
+        }
+        catch {
+            // sharp not available — send PNG
+            jpegBuffer = pngBuffer;
+        }
+        return {
+            success: true,
+            screenshotBuffer: jpegBuffer,
+            screenshotMeta: {
+                width: result.imageWidth,
+                height: result.imageHeight,
+                format: "jpeg",
+                coordMap: result.coordMap,
+            },
+        };
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { }
+    }
+}
+async function doClick(params) {
+    const usecomputer = await getUC();
+    const x = Number(params.x);
+    const y = Number(params.y);
+    await usecomputer.click({ point: { x, y }, button: "left", count: 1 });
+    return { success: true, data: { action: "click", x, y } };
+}
+async function doType(params) {
+    const usecomputer = await getUC();
+    const text = String(params.text);
+    try {
+        await usecomputer.typeText({ text, delayMs: null });
+    }
+    catch {
+        // Fallback: use xdotool on Linux if usecomputer fails (space character bug)
+        if (process.platform === "linux") {
+            execSync(`xdotool type --delay 12 -- ${JSON.stringify(text)}`, { env: { ...process.env, DISPLAY: process.env.DISPLAY || ":0" } });
+        }
+        else {
+            throw new Error("typeText failed");
+        }
+    }
+    return { success: true, data: { action: "type" } };
+}
+async function doPress(params) {
+    const usecomputer = await getUC();
+    const key = String(params.key);
+    await usecomputer.press({ key, count: null, delayMs: null });
+    return { success: true, data: { action: "press", key } };
+}
+async function doScroll(params) {
+    const usecomputer = await getUC();
+    const direction = String(params.direction);
+    const amount = Number(params.amount || 3);
+    await usecomputer.scroll({ direction, amount, at: null });
+    return { success: true, data: { action: "scroll", direction, amount } };
+}
+async function listWindows() {
+    const usecomputer = await getUC();
+    const windows = await usecomputer.windowList();
+    return { success: true, data: { windows } };
+}
+//# sourceMappingURL=executor.js.map

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * @instaclaw/dispatch — Local relay for InstaClaw agents to control your computer.
+ *
+ * Usage:
+ *   npx @instaclaw/dispatch                    # Interactive setup
+ *   npx @instaclaw/dispatch --token XXX --vm HOST  # Direct connect
+ */
+import { loadConfig, saveConfig, getConfigPath } from "./config.js";
+import { checkPermissions, printPermissionGuide } from "./permissions.js";
+import { connect, disconnect } from "./connection.js";
+import { closeSupervisor } from "./supervisor.js";
+import readline from "readline";
+async function main() {
+    console.log(`
+  InstaClaw Dispatch — Remote Computer Control
+  ─────────────────────────────────────────────
+  `);
+    // 1. Check/request permissions
+    const perms = checkPermissions();
+    if (!perms.accessibility || !perms.screenRecording) {
+        console.log("  Checking permissions...");
+        printPermissionGuide();
+        await waitForEnter();
+    }
+    // 2. Load or create config
+    let config = loadConfig();
+    const args = parseArgs();
+    if (args.token && args.vm) {
+        // CLI args override config
+        config = {
+            gatewayToken: args.token,
+            vmAddress: args.vm,
+            port: args.port || 8765,
+            mode: "supervised",
+        };
+        saveConfig(config);
+    }
+    if (!config?.gatewayToken || !config?.vmAddress) {
+        // Interactive setup
+        config = await interactiveSetup(config);
+        saveConfig(config);
+        console.log(`  Config saved to ${getConfigPath()}\n`);
+    }
+    console.log(`  VM:   ${config.vmAddress}:${config.port}`);
+    console.log(`  Mode: ${config.mode}`);
+    console.log(`  Token: ${config.gatewayToken.substring(0, 8)}...\n`);
+    // 3. Connect to VM
+    connect({
+        vmAddress: config.vmAddress,
+        port: config.port,
+        gatewayToken: config.gatewayToken,
+        mode: config.mode,
+        rejectUnauthorized: false, // Accept self-signed (TOFU)
+        certFingerprint: config.certFingerprint,
+        onConnect: () => {
+            console.log(`\n  Dispatch mode: SUPERVISED`);
+            console.log(`  Screenshots auto-approved. Actions require [Enter] to confirm.`);
+            console.log(`  Press Ctrl+C to disconnect.\n`);
+        },
+        onDisconnect: () => {
+            // Will auto-reconnect
+        },
+        onCertFingerprint: (fp) => {
+            // TOFU: save fingerprint on first connection
+            if (config && !config.certFingerprint) {
+                config.certFingerprint = fp;
+                saveConfig(config);
+                console.log(`  TLS fingerprint saved (TOFU): ${fp.substring(0, 20)}...`);
+            }
+        },
+    });
+    // 4. Handle Ctrl+C
+    process.on("SIGINT", () => {
+        console.log("\n  Disconnecting...");
+        disconnect();
+        closeSupervisor();
+        process.exit(0);
+    });
+}
+async function interactiveSetup(existing) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q, def) => new Promise((resolve) => {
+        const prompt = def ? `${q} [${def}]: ` : `${q}: `;
+        rl.question(`  ${prompt}`, (ans) => resolve(ans.trim() || def || ""));
+    });
+    console.log("  First-time setup:\n");
+    const token = await ask("Gateway token", existing?.gatewayToken);
+    const vm = await ask("VM address (IP or hostname)", existing?.vmAddress);
+    const portStr = await ask("Port", String(existing?.port || 8765));
+    rl.close();
+    return {
+        gatewayToken: token,
+        vmAddress: vm,
+        port: parseInt(portStr, 10) || 8765,
+        mode: "supervised",
+        certFingerprint: existing?.certFingerprint,
+    };
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {};
+    for (let i = 0; i < args.length; i++) {
+        if ((args[i] === "--token" || args[i] === "-t") && args[i + 1]) {
+            result.token = args[++i];
+        }
+        else if ((args[i] === "--vm" || args[i] === "-v") && args[i + 1]) {
+            result.vm = args[++i];
+        }
+        else if ((args[i] === "--port" || args[i] === "-p") && args[i + 1]) {
+            result.port = parseInt(args[++i], 10);
+        }
+    }
+    return result;
+}
+function waitForEnter() {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question("", () => { rl.close(); resolve(); });
+    });
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/permissions.d.ts

@@ -0,0 +1,8 @@
+interface PermissionStatus {
+    accessibility: boolean;
+    screenRecording: boolean;
+    platform: string;
+}
+export declare function checkPermissions(): PermissionStatus;
+export declare function printPermissionGuide(): void;
+export {};

package/dist/permissions.js

@@ -0,0 +1,44 @@
+import os from "os";
+export function checkPermissions() {
+    const platform = os.platform();
+    if (platform === "darwin") {
+        return checkMacPermissions();
+    }
+    // Linux/Windows — no special permissions needed for X11
+    return { accessibility: true, screenRecording: true, platform };
+}
+function checkMacPermissions() {
+    let accessibility = false;
+    let screenRecording = false;
+    // Check accessibility: try to create a CGEvent (will fail without permission)
+    // We can't check directly from Node — usecomputer will fail at runtime if missing
+    // For now, assume true and catch errors at execution time
+    accessibility = true; // Will validate on first command
+    // Screen recording: same — can't check from Node without native module
+    screenRecording = true;
+    return { accessibility, screenRecording, platform: "darwin" };
+}
+export function printPermissionGuide() {
+    const platform = os.platform();
+    if (platform === "darwin") {
+        console.log(`
+  To grant permissions (macOS):
+    1. System Settings → Privacy & Security → Accessibility
+       → Add your terminal app (Terminal, iTerm, Warp, etc.)
+    2. System Settings → Privacy & Security → Screen Recording
+       → Add your terminal app
+
+  Press Enter after granting permissions...`);
+    }
+    else if (platform === "linux") {
+        console.log(`
+  Linux: No special permissions needed.
+  Ensure DISPLAY is set if using X11.`);
+    }
+    else {
+        console.log(`
+  Windows: No special permissions needed.
+  Run as administrator if controlling elevated apps.`);
+    }
+}
+//# sourceMappingURL=permissions.js.map

package/dist/supervisor.d.ts

@@ -0,0 +1,3 @@
+import type { DispatchCommand } from "./types.js";
+export declare function requestApproval(command: DispatchCommand): Promise<boolean>;
+export declare function closeSupervisor(): void;

package/dist/supervisor.js

@@ -0,0 +1,57 @@
+/**
+ * Supervisor — prompts user for approval before executing commands.
+ * Screenshots are auto-approved. All other actions require Enter to proceed.
+ */
+import readline from "readline";
+const AUTO_APPROVE_TYPES = new Set(["screenshot", "windows", "status"]);
+const isTTY = process.stdin.isTTY ?? false;
+let rl = null;
+if (isTTY) {
+    rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+}
+export async function requestApproval(command) {
+    // Auto-approve passive commands
+    if (AUTO_APPROVE_TYPES.has(command.type)) {
+        return true;
+    }
+    const desc = formatCommand(command);
+    console.log(`\n  Agent wants to: ${desc}`);
+    // Non-interactive mode (no TTY) — auto-approve with log
+    if (!rl) {
+        console.log("  Auto-approved (non-interactive mode)");
+        return true;
+    }
+    return new Promise((resolve) => {
+        rl.question("  [Enter] to approve, [n] to deny: ", (answer) => {
+            const denied = answer.trim().toLowerCase() === "n";
+            if (denied) {
+                console.log("  Denied.");
+            }
+            resolve(!denied);
+        });
+    });
+}
+function formatCommand(cmd) {
+    const p = cmd.params;
+    switch (cmd.type) {
+        case "click":
+            return `Click at (${p.x}, ${p.y})${cmd.description ? ` — "${cmd.description}"` : ""}`;
+        case "type":
+            return `Type: "${String(p.text).substring(0, 50)}${String(p.text).length > 50 ? "..." : ""}"`;
+        case "press":
+            return `Press key: ${p.key}`;
+        case "scroll":
+            return `Scroll ${p.direction} by ${p.amount || 3}`;
+        case "drag":
+            return `Drag from (${p.fromX}, ${p.fromY}) to (${p.toX}, ${p.toY})`;
+        default:
+            return `${cmd.type}: ${JSON.stringify(p).substring(0, 80)}`;
+    }
+}
+export function closeSupervisor() {
+    rl?.close();
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+/** Command sent from VM agent → dispatch server → local relay */
+export interface DispatchCommand {
+    id: string;
+    type: "screenshot" | "click" | "type" | "press" | "scroll" | "drag" | "windows" | "status";
+    params: Record<string, unknown>;
+    description?: string;
+}
+/** Result sent from local relay → dispatch server → agent */
+export interface DispatchResult {
+    id: string;
+    type: "result" | "screenshot_result" | "error";
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: string;
+}
+/** Screenshot metadata (sent as text frame before binary frame) */
+export interface ScreenshotMeta {
+    id: string;
+    type: "screenshot_result";
+    width: number;
+    height: number;
+    format: "jpeg" | "png";
+    size: number;
+    coordMap: string;
+}
+/** Relay config persisted to disk */
+export interface DispatchConfig {
+    gatewayToken: string;
+    vmAddress: string;
+    port: number;
+    mode: "supervised" | "autonomous";
+    /** TLS cert fingerprint for TOFU (trust on first use) */
+    certFingerprint?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@instaclaw/dispatch",
+  "version": "0.1.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"
+  },
+  "type": "module",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "instaclaw",
+    "ai-agent",
+    "computer-use",
+    "remote-control",
+    "dispatch",
+    "usecomputer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coopergwrenn/clawlancer.git",
+    "directory": "instaclaw/packages/dispatch"
+  },
+  "homepage": "https://instaclaw.io",
+  "dependencies": {
+    "usecomputer": "^0.1.4",
+    "ws": "^8.18.0",
+    "sharp": "^0.33.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}