scrapybara-ts-template: Cursor rule for Cursor

You are working with Scrapybara, a TypeScript SDK for deploying and managing remote desktop instances for AI agents. Use this guide to properly interact with the SDK.

CORE SDK USAGE:

• Initialize client: import { ScrapybaraClient } from "scrapybara"; const client = new ScrapybaraClient({ apiKey: "KEY" });
• Instance lifecycle: const instance = await client.startUbuntu({ timeoutHours: 1 }); await instance.pause(); // Pause to save resources await instance.resume({ timeoutHours: 1 }); // Resume work await instance.stop(); // Terminate and clean up
• Instance types: const ubuntuInstance = client.startUbuntu(); // supports bash, computer, edit, browser const browserInstance = client.startBrowser(); // supports computer, browser const windowsInstance = client.startWindows(); // supports computer

TYPE IMPORTS:

• Core types: import { ScrapybaraClient, UbuntuInstance, BrowserInstance, WindowsInstance } from "scrapybara";
• Tool types: import { bashTool, computerTool, editTool } from "scrapybara/tools";
• Model types: import { anthropic } from "scrapybara/anthropic";
• Message types: import { z } from "zod";
• Error types: import { ScrapybaraError } from "scrapybara";
• Request/Response types: import { Scrapybara } from "scrapybara"; // Namespace containing all request/response types

CORE INSTANCE OPERATIONS:

• Screenshots: const base64Image = await instance.screenshot().base64Image;
• Bash commands: await instance.bash({ command: "ls -la" });
• Mouse control: await instance.computer({ action: "move_mouse", coordinates: [x, y] });
• Click actions: await instance.computer({ action: "click_mouse", button: "right", coordinates: [x, y] });
• Drag actions: await instance.computer({ action: "drag_mouse", path: [[x1, y1], [x2, y2]] });
• Scroll actions: await instance.computer({ action: "scroll", coordinates: [x, y], delta_x: 0, delta_y: 0 });
• Key actions: await instance.computer({ action: "press_key", keys: ["a", "b", "c"] });
• Type actions: await instance.computer({ action: "type_text", text: "Hello world" });
• Wait actions: await instance.computer({ action: "wait", duration: 3 });
• Get cursor position: await instance.computer({ action: "get_cursor_position" });
• File operations: await instance.file.read({ path: "/path/file" }), await instance.file.write({ path: "/path/file", content: "data" });

ACT SDK (Primary Focus):

• Purpose: Enables building computer use agents with unified tools and model interfaces
• Core components:

1. Model: Handles LLM integration (currently Anthropic) import { anthropic } from "scrapybara/anthropic"; const model = anthropic(); // Or model = anthropic({ apiKey: "KEY" }) for own key
2. Tools: Interface for computer interactions
   • bashTool: Run shell commands
   • computerTool: Mouse/keyboard control
   • editTool: File operations const tools = [ bashTool(instance), computerTool(instance), editTool(instance), ];
3. Prompt:
   • system: system prompt, recommend to use UBUNTU_SYSTEM_PROMPT, BROWSER_SYSTEM_PROMPT, WINDOWS_SYSTEM_PROMPT
   • prompt: simple user prompt
   • messages: list of messages
   • Only include either prompt or messages, not both const { messages, steps, text, output, usage } = await client.act({ model: anthropic(), tools, system: UBUNTU_SYSTEM_PROMPT, prompt: "Task", onStep: handleStep });

MESSAGE HANDLING:

• Response Structure: Messages are structured with roles (user/assistant/tool) and typed content
• Content Types:
• TextPart: Simple text content { type: "text", text: "content" }
• ImagePart: Base64 or URL images { type: "image", image: "base64...", mimeType: "image/png" }
• ReasoningPart: Model reasoning content { type: "reasoning", id: "id", reasoning: "reasoning", signature: "signature", instructions: "instructions" }
• ToolCallPart: Tool invocations { type: "tool-call", toolCallId: "id", toolName: "bash", args: { command: "ls" } }
• ToolResultPart: Tool execution results { type: "tool-result", toolCallId: "id", toolName: "bash", result: "output", isError: false }