┌────────────────────────────────────┐
                            │       ComputerUseAgent             │
                            │                                    │
   user prompt ────────────▶│  loop:                             │
                            │    1. Anthropic.messages.create     │
                            │    2. iterate tool_use blocks       │
                            │    3. executor.execute(action)      │
                            │    4. append screenshot to context  │
                            │    5. repeat until final text turn  │
                            └────────────────────────────────────┘
                                            │
                                            ▼
                            ┌────────────────────────────────────┐
                            │  ComputerExecutor (you implement)  │
                            │                                    │
                            │   displayWidth, displayHeight       │
                            │   execute(action) -> screenshot     │
                            └────────────────────────────────────┘

import { ComputerUseAgent, type ComputerExecutor } from "@agentium/core";

const executor: ComputerExecutor = {
  displayWidth: 1920,
  displayHeight: 1080,
  displayNumber: 1, // optional X11 display
  execute: async (action) => {
    // Implement against your platform — example for macOS:
    switch (action.action) {
      case "screenshot":
        return { screenshotBase64: await screencaptureBase64() };
      case "left_click":
        if (action.coordinate) await cliclick(`c:${action.coordinate.join(",")}`);
        return { screenshotBase64: await screencaptureBase64() };
      // ... handle the other action types
      default:
        return { output: `unhandled: ${action.action}`, screenshotBase64: await screencaptureBase64() };
    }
  },
};

const agent = new ComputerUseAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: "claude-sonnet-4-20250514",
  executor,
  enableZoom: true,
  maxIterations: 50,
  systemPrompt: "You are operating a Linux desktop. Be concise and decisive.",
});

const result = await agent.run("Open Firefox and search for the latest Node.js release.");
console.log(result.text);
console.log(`Iterations used: ${result.iterations}`);
console.log(`Actions taken:    ${result.actions.length}`);

interface ComputerUseAgentConfig {
  apiKey?: string;          // defaults to ANTHROPIC_API_KEY env
  model?: string;           // default "claude-sonnet-4-20250514"
  maxTokens?: number;       // default 4096
  executor: ComputerExecutor; // required
  maxIterations?: number;   // default 50 — safety cap on the loop
  systemPrompt?: string;    // optional, prepended to every call
  enableZoom?: boolean;     // default true — sends enable_zoom to computer_20251124
}

interface ComputerExecutor {
  readonly displayWidth: number;    // pixel width of the screen
  readonly displayHeight: number;   // pixel height of the screen
  readonly displayNumber?: number;  // X11 display number, if relevant
  execute(action: ComputerAction): Promise<ComputerActionResult>;
}

interface ComputerActionResult {
  output?: string;            // optional human-readable log (errors, etc.)
  screenshotBase64?: string;  // PNG screenshot after the action
}

type ComputerAction =
  | { action: "screenshot" }
  | { action: "mouse_move"; coordinate: [number, number] }
  | { action: "left_click"; coordinate?: [number, number] }
  | { action: "right_click"; coordinate?: [number, number] }
  | { action: "double_click"; coordinate?: [number, number] }
  | { action: "left_click_drag"; coordinate: [number, number] }
  | { action: "type"; text: string }
  | { action: "key"; text: string }
  | { action: "scroll"; coordinate: [number, number]; scroll_direction: "up" | "down" | "left" | "right"; scroll_amount: number }
  | { action: "zoom"; region: [number, number, number, number] };

interface ComputerUseRunOutput {
  text: string;                // final assistant text
  actions: ComputerAction[];   // all actions taken during the run
  iterations: number;          // how many LLM round-trips
}

import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { readFile } from "node:fs/promises";

const exec = promisify(execFile);

const executor: ComputerExecutor = {
  displayWidth: 1280,
  displayHeight: 800,
  displayNumber: 99, // Xvfb :99
  execute: async (action) => {
    const env = { DISPLAY: ":99" };
    switch (action.action) {
      case "screenshot":
        break; // just snapshot below
      case "left_click":
        if (action.coordinate) await exec("xdotool", ["mousemove", String(action.coordinate[0]), String(action.coordinate[1])], { env });
        await exec("xdotool", ["click", "1"], { env });
        break;
      case "type":
        await exec("xdotool", ["type", "--delay", "10", action.text], { env });
        break;
      case "key":
        await exec("xdotool", ["key", action.text], { env });
        break;
      // ... etc
    }
    await exec("import", ["-display", ":99", "-window", "root", "/tmp/shot.png"]);
    const data = await readFile("/tmp/shot.png");
    return { screenshotBase64: data.toString("base64") };
  },
};