@lakitu/sdk 0.1.0

package/convex/sandbox/context/session.ts

@@ -0,0 +1,402 @@
+/**
+ * Context - Context Window Orchestration
+ *
+ * OpenCode-inspired context management:
+ * - Session persistence across commands
+ * - Dependency graph for surgical context injection
+ * - Lazy tool loading (only inject tools needed)
+ */
+
+import { mutation, query } from "../_generated/server";
+import { v } from "convex/values";
+
+// ============================================
+// Mutations
+// ============================================
+
+/**
+ * Store session memory entry
+ */
+export const setMemory = mutation({
+  args: {
+    sessionId: v.string(),
+    key: v.string(),
+    value: v.any(),
+    ttlMs: v.optional(v.number()), // Time to live
+  },
+  handler: async (ctx, args) => {
+    // Check for existing entry
+    const existing = await ctx.db
+      .query("sessionMemory")
+      .withIndex("by_session_key", (q) =>
+        q.eq("sessionId", args.sessionId).eq("key", args.key)
+      )
+      .first();
+
+    const expiresAt = args.ttlMs ? Date.now() + args.ttlMs : undefined;
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        value: args.value,
+        updatedAt: Date.now(),
+        expiresAt,
+      });
+      return existing._id;
+    }
+
+    return await ctx.db.insert("sessionMemory", {
+      sessionId: args.sessionId,
+      key: args.key,
+      value: args.value,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      expiresAt,
+    });
+  },
+});
+
+/**
+ * Delete session memory entry
+ */
+export const deleteMemory = mutation({
+  args: {
+    sessionId: v.string(),
+    key: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("sessionMemory")
+      .withIndex("by_session_key", (q) =>
+        q.eq("sessionId", args.sessionId).eq("key", args.key)
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.delete(existing._id);
+      return true;
+    }
+    return false;
+  },
+});
+
+/**
+ * Cache context for reuse
+ */
+export const cacheContext = mutation({
+  args: {
+    sessionId: v.string(),
+    taskHash: v.string(),
+    context: v.object({
+      relevantFiles: v.array(
+        v.object({
+          path: v.string(),
+          snippet: v.optional(v.string()),
+          importance: v.number(),
+        })
+      ),
+      toolsNeeded: v.array(v.string()),
+      tokenBudget: v.number(),
+    }),
+    ttlMs: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    // Check for existing cache
+    const existing = await ctx.db
+      .query("contextCache")
+      .withIndex("by_session_task", (q) =>
+        q.eq("sessionId", args.sessionId).eq("taskHash", args.taskHash)
+      )
+      .first();
+
+    const expiresAt = args.ttlMs
+      ? Date.now() + args.ttlMs
+      : Date.now() + 3600000; // 1 hour default
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        context: args.context,
+        updatedAt: Date.now(),
+        expiresAt,
+        hitCount: existing.hitCount + 1,
+      });
+      return existing._id;
+    }
+
+    return await ctx.db.insert("contextCache", {
+      sessionId: args.sessionId,
+      taskHash: args.taskHash,
+      context: args.context,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      expiresAt,
+      hitCount: 0,
+    });
+  },
+});
+
+/**
+ * Track file dependency
+ */
+export const trackDependency = mutation({
+  args: {
+    sessionId: v.string(),
+    fromPath: v.string(),
+    toPath: v.string(),
+    type: v.union(
+      v.literal("import"),
+      v.literal("reference"),
+      v.literal("test"),
+      v.literal("config")
+    ),
+  },
+  handler: async (ctx, args) => {
+    // Check for existing dependency
+    const existing = await ctx.db
+      .query("dependencyGraph")
+      .filter((q) =>
+        q.and(
+          q.eq(q.field("sessionId"), args.sessionId),
+          q.eq(q.field("fromPath"), args.fromPath),
+          q.eq(q.field("toPath"), args.toPath)
+        )
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        type: args.type,
+        lastSeen: Date.now(),
+      });
+      return existing._id;
+    }
+
+    return await ctx.db.insert("dependencyGraph", {
+      sessionId: args.sessionId,
+      fromPath: args.fromPath,
+      toPath: args.toPath,
+      type: args.type,
+      createdAt: Date.now(),
+      lastSeen: Date.now(),
+    });
+  },
+});
+
+/**
+ * Clear expired cache entries
+ */
+export const clearExpired = mutation({
+  args: { sessionId: v.optional(v.string()) },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    let deleted = 0;
+    const { sessionId } = args;
+
+    // Clear expired session memory
+    const memory = sessionId
+      ? await ctx.db
+          .query("sessionMemory")
+          .withIndex("by_session", (q) => q.eq("sessionId", sessionId))
+          .collect()
+      : await ctx.db.query("sessionMemory").collect();
+
+    for (const entry of memory) {
+      if (entry.expiresAt && entry.expiresAt < now) {
+        await ctx.db.delete(entry._id);
+        deleted++;
+      }
+    }
+
+    // Clear expired context cache
+    const cache = sessionId
+      ? await ctx.db
+          .query("contextCache")
+          .withIndex("by_session", (q) => q.eq("sessionId", sessionId))
+          .collect()
+      : await ctx.db.query("contextCache").collect();
+
+    for (const entry of cache) {
+      if (entry.expiresAt && entry.expiresAt < now) {
+        await ctx.db.delete(entry._id);
+        deleted++;
+      }
+    }
+
+    return { deleted };
+  },
+});
+
+// ============================================
+// Queries
+// ============================================
+
+/**
+ * Get session memory value
+ */
+export const getMemory = query({
+  args: {
+    sessionId: v.string(),
+    key: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const entry = await ctx.db
+      .query("sessionMemory")
+      .withIndex("by_session_key", (q) =>
+        q.eq("sessionId", args.sessionId).eq("key", args.key)
+      )
+      .first();
+
+    if (!entry) return null;
+
+    // Check expiration
+    if (entry.expiresAt && entry.expiresAt < Date.now()) {
+      return null;
+    }
+
+    return entry.value;
+  },
+});
+
+/**
+ * Get all session memory
+ */
+export const getAllMemory = query({
+  args: { sessionId: v.string() },
+  handler: async (ctx, args) => {
+    const entries = await ctx.db
+      .query("sessionMemory")
+      .withIndex("by_session", (q) => q.eq("sessionId", args.sessionId))
+      .collect();
+
+    const now = Date.now();
+    const result: Record<string, any> = {};
+
+    for (const entry of entries) {
+      if (!entry.expiresAt || entry.expiresAt >= now) {
+        result[entry.key] = entry.value;
+      }
+    }
+
+    return result;
+  },
+});
+
+/**
+ * Get cached context
+ */
+export const getCachedContext = query({
+  args: {
+    sessionId: v.string(),
+    taskHash: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const cached = await ctx.db
+      .query("contextCache")
+      .withIndex("by_session_task", (q) =>
+        q.eq("sessionId", args.sessionId).eq("taskHash", args.taskHash)
+      )
+      .first();
+
+    if (!cached) return null;
+
+    // Check expiration
+    if (cached.expiresAt && cached.expiresAt < Date.now()) {
+      return null;
+    }
+
+    return cached.context;
+  },
+});
+
+/**
+ * Get dependencies for a file
+ */
+export const getDependencies = query({
+  args: {
+    sessionId: v.string(),
+    path: v.string(),
+  },
+  handler: async (ctx, args) => {
+    // Files this file depends on
+    const dependsOn = await ctx.db
+      .query("dependencyGraph")
+      .filter((q) =>
+        q.and(
+          q.eq(q.field("sessionId"), args.sessionId),
+          q.eq(q.field("fromPath"), args.path)
+        )
+      )
+      .collect();
+
+    // Files that depend on this file
+    const dependedBy = await ctx.db
+      .query("dependencyGraph")
+      .filter((q) =>
+        q.and(
+          q.eq(q.field("sessionId"), args.sessionId),
+          q.eq(q.field("toPath"), args.path)
+        )
+      )
+      .collect();
+
+    return {
+      dependsOn: dependsOn.map((d) => ({ path: d.toPath, type: d.type })),
+      dependedBy: dependedBy.map((d) => ({ path: d.fromPath, type: d.type })),
+    };
+  },
+});
+
+/**
+ * Query dependency graph for relevant files
+ */
+export const queryRelevantFiles = query({
+  args: {
+    sessionId: v.string(),
+    paths: v.array(v.string()),
+    depth: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const maxDepth = args.depth ?? 2;
+    const visited = new Set<string>(args.paths);
+    const result: Array<{ path: string; depth: number; type: string }> = [];
+
+    // BFS to find related files
+    let currentLevel = args.paths;
+    for (let depth = 0; depth < maxDepth && currentLevel.length > 0; depth++) {
+      const nextLevel: string[] = [];
+
+      for (const path of currentLevel) {
+        // Get all dependencies
+        const deps = await ctx.db
+          .query("dependencyGraph")
+          .filter((q) =>
+            q.and(
+              q.eq(q.field("sessionId"), args.sessionId),
+              q.or(
+                q.eq(q.field("fromPath"), path),
+                q.eq(q.field("toPath"), path)
+              )
+            )
+          )
+          .collect();
+
+        for (const dep of deps) {
+          const relatedPath =
+            dep.fromPath === path ? dep.toPath : dep.fromPath;
+          if (!visited.has(relatedPath)) {
+            visited.add(relatedPath);
+            nextLevel.push(relatedPath);
+            result.push({
+              path: relatedPath,
+              depth: depth + 1,
+              type: dep.type,
+            });
+          }
+        }
+      }
+
+      currentLevel = nextLevel;
+    }
+
+    return result;
+  },
+});

package/convex/sandbox/convex.config.ts

@@ -0,0 +1,17 @@
+/**
+ * Convex Config for Sandbox Agent
+ *
+ * This is the configuration for the self-hosted Convex backend
+ * that runs inside the E2B sandbox. It uses the Convex Agent SDK
+ * for native LLM orchestration and streaming.
+ */
+
+import { defineApp } from "convex/server";
+import agent from "@convex-dev/agent/convex.config";
+
+const app = defineApp();
+
+// Convex Agent SDK component for LLM orchestration
+app.use(agent);
+
+export default app;

package/convex/sandbox/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Sandbox Agent - Main Entry Point
+ *
+ * Re-exports all public APIs for the sandbox agent.
+ */
+
+// ============================================
+// Agent
+// ============================================
+export {
+  startThread,
+  continueThread,
+  runWithTimeout,
+  getThreadMessages,
+  getStreamDeltas,
+} from "./agent";
+export * as decisions from "./agent/decisions";
+
+// ============================================
+// State Management
+// ============================================
+export * as state from "./state";
+export * as files from "./state/files";
+export * as checkpoints from "./state/checkpoints";
+export * as verification from "./state/verification";
+export * as artifacts from "./state/artifacts";
+
+// ============================================
+// Planning
+// ============================================
+export * as planning from "./planning";
+export * as beads from "./planning/beads";
+export * as sync from "./planning/sync";
+
+// ============================================
+// Context
+// ============================================
+export * as context from "./context";
+export * as session from "./context/session";
+
+// ============================================
+// Tools (DEPRECATED - Use KSAs instead)
+// ============================================
+// Legacy tool system has been removed. Use the KSA (Knowledge, Skills, Abilities)
+// architecture with code execution mode instead. See packages/lakitu/ksa/
+
+// ============================================
+// Prompts
+// ============================================
+export * as prompts from "./prompts/system";
+export * as modes from "./prompts/modes";

package/convex/sandbox/nodeActions/codeExec.ts

@@ -0,0 +1,130 @@
+"use node";
+
+/**
+ * Code Execution Action
+ *
+ * Executes TypeScript code generated by the LLM.
+ * This is the core of the code execution model - instead of JSON tool calls,
+ * the agent writes code that imports from ksa/ and we execute it.
+ */
+
+import { internalAction } from "../_generated/server";
+import { v } from "convex/values";
+
+// Execution limits
+const MAX_TIMEOUT_MS = 120_000; // 2 minutes
+const MAX_OUTPUT_LENGTH = 50_000; // 50KB
+
+/**
+ * Execute TypeScript code in the sandbox.
+ *
+ * The code can import from /home/user/ksa/ to use available capabilities.
+ * Output is captured from stdout/stderr.
+ */
+export const execute = internalAction({
+  args: {
+    code: v.string(),
+    timeoutMs: v.optional(v.number()),
+    env: v.optional(v.object({
+      CONVEX_URL: v.optional(v.string()),
+      GATEWAY_URL: v.optional(v.string()),
+      SANDBOX_JWT: v.optional(v.string()),
+      CARD_ID: v.optional(v.string()),
+      THREAD_ID: v.optional(v.string()),
+    })),
+  },
+  handler: async (_ctx, args): Promise<{
+    success: boolean;
+    output: string;
+    error?: string;
+    exitCode: number;
+  }> => {
+    // Dynamic imports for Node.js modules (required for Convex bundling)
+    const { exec } = await import("child_process");
+    const { promisify } = await import("util");
+    const fs = await import("fs/promises");
+    const crypto = await import("crypto");
+
+    const execAsync = promisify(exec);
+    const timeout = Math.min(args.timeoutMs || 60_000, MAX_TIMEOUT_MS);
+
+    // Generate unique filename for this execution
+    // IMPORTANT: Write to /home/user/ so relative imports like './ksa/beads' resolve correctly
+    const hash = crypto.createHash("md5").update(args.code).digest("hex").slice(0, 8);
+    const filename = `/home/user/agent_exec_${Date.now()}_${hash}.ts`;
+
+    try {
+      // Write code to temp file
+      await fs.writeFile(filename, args.code, "utf-8");
+
+      // Execute with bun (use full path since PATH may not be set in Convex process)
+      const bunPath = "/home/user/.bun/bin/bun";
+      const { stdout, stderr } = await execAsync(`${bunPath} run ${filename}`, {
+        timeout,
+        cwd: "/home/user/workspace",
+        env: {
+          ...process.env,
+          // Ensure PATH includes bun
+          PATH: "/home/user/.bun/bin:/usr/local/bin:/usr/bin:/bin",
+          HOME: "/home/user",
+          // Make KSAs available via import path
+          NODE_PATH: "/home/user",
+          // Gateway config for KSAs to call cloud services
+          ...(args.env?.CONVEX_URL && { CONVEX_URL: args.env.CONVEX_URL }),
+          ...(args.env?.GATEWAY_URL && { GATEWAY_URL: args.env.GATEWAY_URL }),
+          ...(args.env?.SANDBOX_JWT && { SANDBOX_JWT: args.env.SANDBOX_JWT }),
+          ...(args.env?.CARD_ID && { CARD_ID: args.env.CARD_ID }),
+          ...(args.env?.THREAD_ID && { THREAD_ID: args.env.THREAD_ID }),
+        },
+        maxBuffer: MAX_OUTPUT_LENGTH * 2,
+      });
+
+      // Combine and truncate output
+      let output = stdout || "";
+      if (stderr) {
+        output += stderr ? `\n[stderr]\n${stderr}` : "";
+      }
+      if (output.length > MAX_OUTPUT_LENGTH) {
+        output = output.slice(0, MAX_OUTPUT_LENGTH) + "\n... (output truncated)";
+      }
+
+      return {
+        success: true,
+        output: output.trim(),
+        exitCode: 0,
+      };
+    } catch (error: unknown) {
+      const err = error as { message?: string; stdout?: string; stderr?: string; code?: number };
+      const message = err.message || String(error);
+      let output = "";
+
+      // Capture any partial output
+      if (err.stdout) output += err.stdout;
+      if (err.stderr) output += `\n[stderr]\n${err.stderr}`;
+
+      // Check for timeout
+      if (message.includes("TIMEOUT") || message.includes("timed out")) {
+        return {
+          success: false,
+          output: output.trim(),
+          error: `Execution timed out after ${timeout}ms`,
+          exitCode: 124,
+        };
+      }
+
+      return {
+        success: false,
+        output: output.trim(),
+        error: message,
+        exitCode: err.code || 1,
+      };
+    } finally {
+      // Clean up temp file
+      try {
+        await fs.unlink(filename);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  },
+});