@lakitu/sdk 0.1.0

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@lakitu/sdk",
+  "version": "0.1.0",
+  "description": "Self-hosted AI agent framework for Convex + E2B with code execution",
+  "type": "module",
+  "main": "./dist/sdk/index.js",
+  "types": "./dist/sdk/index.d.ts",
+  "bin": {
+    "lakitu": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js"
+    },
+    "./types": {
+      "types": "./dist/sdk/types.d.ts",
+      "import": "./dist/sdk/types.js"
+    },
+    "./builders": {
+      "types": "./dist/sdk/builders.d.ts",
+      "import": "./dist/sdk/builders.js"
+    }
+  },
+  "files": [
+    "dist",
+    "convex",
+    "ksa",
+    "runtime",
+    "template",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "dev": "convex dev",
+    "deploy": "convex deploy",
+    "generate": "convex codegen",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:convex": "convex run tests/runner:runAll",
+    "test:integration": "bun run tests/integration/run.ts",
+    "typecheck": "tsc --noEmit",
+    "template:build": "bun template/build.ts",
+    "template:push": "bun template/build.ts --push",
+    "template:base": "bun template/build.ts --base --push",
+    "template:custom": "bun template/build.ts --custom --push"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "ksa",
+    "convex",
+    "e2b",
+    "sandbox",
+    "code-execution",
+    "self-hosted"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/project-social/lakitu"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "e2b": "^2.10.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.27.0",
+    "@ai-sdk/openai": "^3.0.10",
+    "@openrouter/ai-sdk-provider": "^1.5.4",
+    "@convex-dev/agent": "^0.2.0",
+    "@types/node": "^20.0.0",
+    "@types/pdfkit": "^0.13.0",
+    "ai": "^6.0.34",
+    "convex": "^1.17.0",
+    "convex-test": "^0.0.34",
+    "loro-crdt": "^1.0.0",
+    "openapi-fetch": "^0.10.0",
+    "pdfkit": "^0.15.0",
+    "playwright": "^1.48.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0",
+    "yaml": "^2.4.5",
+    "zod-to-json-schema": "^3.23.0"
+  },
+  "peerDependencies": {
+    "convex": "^1.0.0",
+    "zod": "^3.0.0"
+  }
+}

package/runtime/browser/agent-browser.ts

@@ -0,0 +1,330 @@
+/**
+ * Agent Browser - Vercel agent-browser Wrapper
+ *
+ * Provides browser automation capabilities using the agent-browser CLI.
+ */
+
+import { spawn, execSync } from "child_process";
+
+export interface BrowserSession {
+  sessionId: string;
+  status: "idle" | "navigating" | "ready" | "error";
+  currentUrl?: string;
+  error?: string;
+}
+
+export interface ElementRef {
+  ref: string; // e.g., "@e1"
+  tag: string;
+  text?: string;
+  role?: string;
+  attributes: Record<string, string>;
+}
+
+export interface PageSnapshot {
+  url: string;
+  title: string;
+  elements: ElementRef[];
+  screenshot?: string; // Base64 encoded
+}
+
+class AgentBrowser {
+  private session: BrowserSession | null = null;
+
+  /**
+   * Start a new browser session
+   */
+  async start(): Promise<string> {
+    const sessionId = `browser_${Date.now()}`;
+
+    this.session = {
+      sessionId,
+      status: "idle",
+    };
+
+    return sessionId;
+  }
+
+  /**
+   * Navigate to a URL
+   */
+  async navigate(url: string): Promise<{ success: boolean; error?: string }> {
+    if (!this.session) {
+      return { success: false, error: "No active session" };
+    }
+
+    try {
+      this.session.status = "navigating";
+
+      const result = execSync(`agent-browser open "${url}"`, {
+        encoding: "utf8",
+        timeout: 30000,
+        env: {
+          ...process.env,
+          HOME: "/home/user",
+        },
+      });
+
+      this.session.status = "ready";
+      this.session.currentUrl = url;
+
+      return { success: true };
+    } catch (error: any) {
+      this.session.status = "error";
+      this.session.error = error.message;
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Get a snapshot of the current page with interactive elements
+   */
+  async snapshot(options?: { interactive?: boolean }): Promise<PageSnapshot | null> {
+    if (!this.session || this.session.status !== "ready") {
+      return null;
+    }
+
+    try {
+      const args = ["snapshot"];
+      if (options?.interactive !== false) {
+        args.push("--interactive");
+      }
+
+      const result = execSync(`agent-browser ${args.join(" ")}`, {
+        encoding: "utf8",
+        timeout: 15000,
+        env: {
+          ...process.env,
+          HOME: "/home/user",
+        },
+      });
+
+      // Parse the snapshot output
+      // agent-browser returns a structured format with element refs
+      return this.parseSnapshot(result);
+    } catch (error: any) {
+      console.error("[agent-browser] Snapshot failed:", error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Click an element by reference
+   */
+  async click(ref: string): Promise<{ success: boolean; error?: string }> {
+    if (!this.session || this.session.status !== "ready") {
+      return { success: false, error: "No active session or page not ready" };
+    }
+
+    try {
+      execSync(`agent-browser click "${ref}"`, {
+        encoding: "utf8",
+        timeout: 10000,
+        env: {
+          ...process.env,
+          HOME: "/home/user",
+        },
+      });
+
+      return { success: true };
+    } catch (error: any) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Type text into the focused element
+   */
+  async type(text: string): Promise<{ success: boolean; error?: string }> {
+    if (!this.session || this.session.status !== "ready") {
+      return { success: false, error: "No active session or page not ready" };
+    }
+
+    try {
+      // Escape the text for shell
+      const escaped = text.replace(/"/g, '\\"');
+      execSync(`agent-browser type "${escaped}"`, {
+        encoding: "utf8",
+        timeout: 10000,
+        env: {
+          ...process.env,
+          HOME: "/home/user",
+        },
+      });
+
+      return { success: true };
+    } catch (error: any) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Press a key (Enter, Tab, Escape, etc.)
+   */
+  async press(key: string): Promise<{ success: boolean; error?: string }> {
+    if (!this.session || this.session.status !== "ready") {
+      return { success: false, error: "No active session or page not ready" };
+    }
+
+    try {
+      execSync(`agent-browser press "${key}"`, {
+        encoding: "utf8",
+        timeout: 5000,
+        env: {
+          ...process.env,
+          HOME: "/home/user",
+        },
+      });
+
+      return { success: true };
+    } catch (error: any) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Take a screenshot
+   */
+  async screenshot(): Promise<string | null> {
+    if (!this.session || this.session.status !== "ready") {
+      return null;
+    }
+
+    try {
+      const result = execSync(`agent-browser screenshot --format base64`, {
+        encoding: "utf8",
+        timeout: 10000,
+        maxBuffer: 50 * 1024 * 1024, // 50MB for large screenshots
+        env: {
+          ...process.env,
+          HOME: "/home/user",
+        },
+      });
+
+      return result.trim();
+    } catch (error: any) {
+      console.error("[agent-browser] Screenshot failed:", error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Scroll the page
+   */
+  async scroll(direction: "up" | "down" | "top" | "bottom"): Promise<{ success: boolean }> {
+    if (!this.session || this.session.status !== "ready") {
+      return { success: false };
+    }
+
+    try {
+      execSync(`agent-browser scroll ${direction}`, {
+        encoding: "utf8",
+        timeout: 5000,
+        env: {
+          ...process.env,
+          HOME: "/home/user",
+        },
+      });
+
+      return { success: true };
+    } catch {
+      return { success: false };
+    }
+  }
+
+  /**
+   * Wait for navigation or element
+   */
+  async wait(options: { timeout?: number; selector?: string }): Promise<{ success: boolean }> {
+    const timeout = options.timeout || 5000;
+
+    try {
+      if (options.selector) {
+        execSync(`agent-browser wait "${options.selector}" --timeout ${timeout}`, {
+          encoding: "utf8",
+          timeout: timeout + 1000,
+          env: {
+            ...process.env,
+            HOME: "/home/user",
+          },
+        });
+      } else {
+        // Just wait for any pending navigation
+        await new Promise((resolve) => setTimeout(resolve, timeout));
+      }
+
+      return { success: true };
+    } catch {
+      return { success: false };
+    }
+  }
+
+  /**
+   * Close the browser session
+   */
+  async close(): Promise<void> {
+    if (!this.session) return;
+
+    try {
+      execSync("agent-browser close", {
+        encoding: "utf8",
+        timeout: 5000,
+        env: {
+          ...process.env,
+          HOME: "/home/user",
+        },
+      });
+    } catch {
+      // Ignore errors on close
+    }
+
+    this.session = null;
+  }
+
+  /**
+   * Get current session status
+   */
+  getStatus(): BrowserSession | null {
+    return this.session;
+  }
+
+  private parseSnapshot(output: string): PageSnapshot {
+    // Parse the agent-browser snapshot output
+    // This is a simplified parser - real implementation depends on actual output format
+    const lines = output.split("\n");
+    const elements: ElementRef[] = [];
+
+    let url = "";
+    let title = "";
+
+    for (const line of lines) {
+      // Parse URL
+      if (line.startsWith("URL:")) {
+        url = line.slice(4).trim();
+        continue;
+      }
+
+      // Parse title
+      if (line.startsWith("Title:")) {
+        title = line.slice(6).trim();
+        continue;
+      }
+
+      // Parse element refs like "@e1 button[Login]"
+      const refMatch = line.match(/^(@e\d+)\s+(\w+)(?:\[(.+?)\])?/);
+      if (refMatch) {
+        elements.push({
+          ref: refMatch[1],
+          tag: refMatch[2],
+          text: refMatch[3],
+          attributes: {},
+        });
+      }
+    }
+
+    return { url, title, elements };
+  }
+}
+
+// Singleton instance
+export const agentBrowser = new AgentBrowser();

package/runtime/entrypoint.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env bun
+/**
+ * Sandbox Agent Entrypoint
+ *
+ * Main startup script for the sandbox environment.
+ * Starts all required services and waits for readiness.
+ */
+
+import { spawn, type ChildProcess } from "child_process";
+
+const CONVEX_PORT = 3210;
+const CONVEX_SITE_PORT = 3211;
+
+interface ServiceStatus {
+  name: string;
+  pid?: number;
+  status: "starting" | "running" | "failed";
+  error?: string;
+}
+
+const services: Map<string, ServiceStatus> = new Map();
+
+async function startConvexBackend(): Promise<void> {
+  console.log("[entrypoint] Starting Convex backend...");
+
+  const proc = spawn("convex-backend", ["--port", String(CONVEX_PORT), "--site-port", String(CONVEX_SITE_PORT)], {
+    env: {
+      ...process.env,
+      HOME: "/home/user",
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  services.set("convex", {
+    name: "convex",
+    pid: proc.pid,
+    status: "starting",
+  });
+
+  proc.stdout?.on("data", (data) => {
+    const line = data.toString().trim();
+    if (line.includes("Listening")) {
+      services.set("convex", { ...services.get("convex")!, status: "running" });
+      console.log("[entrypoint] Convex backend ready");
+    }
+  });
+
+  proc.stderr?.on("data", (data) => {
+    console.error("[convex]", data.toString().trim());
+  });
+
+  proc.on("error", (err) => {
+    services.set("convex", { ...services.get("convex")!, status: "failed", error: err.message });
+    console.error("[entrypoint] Convex backend failed:", err.message);
+  });
+
+  // Wait for backend to be ready
+  await waitForService("convex", 30000);
+}
+
+async function startLspServers(): Promise<void> {
+  console.log("[entrypoint] Starting LSP servers...");
+
+  // TypeScript LSP is started on-demand
+  services.set("typescript-lsp", {
+    name: "typescript-lsp",
+    status: "running", // Available but not started until needed
+  });
+
+  // Python LSP is started on-demand
+  services.set("python-lsp", {
+    name: "python-lsp",
+    status: "running",
+  });
+
+  // Rust LSP is started on-demand
+  services.set("rust-lsp", {
+    name: "rust-lsp",
+    status: "running",
+  });
+
+  console.log("[entrypoint] LSP servers available (on-demand)");
+}
+
+async function startFileWatcher(): Promise<void> {
+  console.log("[entrypoint] Starting file watcher...");
+
+  const watcherPath = "/home/user/lakitu/runtime/services/file-watcher.ts";
+
+  try {
+    // Check if file exists
+    const fs = await import("fs/promises");
+    await fs.access(watcherPath);
+
+    const proc = spawn("bun", ["run", watcherPath], {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    services.set("file-watcher", {
+      name: "file-watcher",
+      pid: proc.pid,
+      status: "running",
+    });
+
+    proc.stdout?.on("data", (data) => {
+      console.log("[file-watcher]", data.toString().trim());
+    });
+
+    proc.stderr?.on("data", (data) => {
+      console.error("[file-watcher]", data.toString().trim());
+    });
+
+    console.log("[entrypoint] File watcher started");
+  } catch {
+    console.log("[entrypoint] File watcher not found, skipping");
+    services.set("file-watcher", {
+      name: "file-watcher",
+      status: "running", // Mark as running (optional service)
+    });
+  }
+}
+
+async function waitForService(name: string, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    const service = services.get(name);
+    if (service?.status === "running") {
+      return;
+    }
+    if (service?.status === "failed") {
+      throw new Error(`Service ${name} failed: ${service.error}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  throw new Error(`Service ${name} timed out after ${timeoutMs}ms`);
+}
+
+async function healthCheck(): Promise<boolean> {
+  // Check Convex backend
+  try {
+    const response = await fetch(`http://localhost:${CONVEX_PORT}/health`);
+    if (!response.ok) return false;
+  } catch {
+    return false;
+  }
+
+  return true;
+}
+
+async function main(): Promise<void> {
+  console.log("[entrypoint] ========================================");
+  console.log("[entrypoint] Sandbox Agent Starting");
+  console.log("[entrypoint] ========================================");
+
+  try {
+    // Start services in order
+    await startConvexBackend();
+    await startLspServers();
+    await startFileWatcher();
+
+    // Verify health
+    const healthy = await healthCheck();
+    if (!healthy) {
+      console.warn("[entrypoint] Health check failed, but continuing...");
+    }
+
+    console.log("[entrypoint] ========================================");
+    console.log("[entrypoint] Sandbox Ready!");
+    console.log("[entrypoint] Convex: http://localhost:" + CONVEX_PORT);
+    console.log("[entrypoint] ========================================");
+
+    // Keep process running
+    await new Promise(() => {});
+  } catch (error: any) {
+    console.error("[entrypoint] Startup failed:", error.message);
+    process.exit(1);
+  }
+}
+
+// Handle shutdown
+process.on("SIGTERM", () => {
+  console.log("[entrypoint] Received SIGTERM, shutting down...");
+  process.exit(0);
+});
+
+process.on("SIGINT", () => {
+  console.log("[entrypoint] Received SIGINT, shutting down...");
+  process.exit(0);
+});
+
+main();