@lakitu/sdk 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakitu/sdk",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Self-hosted AI agent framework for Convex + E2B with code execution",
   "type": "module",
   "main": "./dist/sdk/index.js",
@@ -42,6 +42,7 @@
     "dist",
     "convex",
     "convex.json",
+    "shared",
     "ksa",
     "runtime",
     "template",

package/shared/chain-of-thought.ts

@@ -0,0 +1,141 @@
+/**
+ * Chain of Thought Types
+ * 
+ * Structured schema for rich UI display of agent activities.
+ * Each step type maps to a specific UI component in the frontend.
+ */
+
+// ============================================
+// Step Status
+// ============================================
+
+export type StepStatus = "pending" | "active" | "complete" | "error";
+
+// ============================================
+// Base Step
+// ============================================
+
+interface BaseStep {
+  id: string;
+  timestamp: number;
+  status: StepStatus;
+}
+
+// ============================================
+// Step Types
+// ============================================
+
+/** Search with results (web_search, web_social lookups) */
+export interface SearchStep extends BaseStep {
+  type: "search";
+  label: string;
+  results?: Array<{ url: string; title?: string }>;
+}
+
+/** Image found or generated (screenshots, avatars, generated images) */
+export interface ImageStep extends BaseStep {
+  type: "image";
+  label: string;
+  src: string;
+  caption?: string;
+}
+
+/** Text insight or finding (summaries, extracted info) */
+export interface TextStep extends BaseStep {
+  type: "text";
+  label: string;
+}
+
+/** Generic tool execution (fallback for unmapped tools) */
+export interface ToolStep extends BaseStep {
+  type: "tool";
+  toolName: string;
+  label: string;
+  input?: Record<string, unknown>;
+  output?: unknown;
+}
+
+/** Agent thinking/reasoning */
+export interface ThinkingStep extends BaseStep {
+  type: "thinking";
+  label: string;
+}
+
+/** File operation (read, write, edit, artifact save) */
+export interface FileStep extends BaseStep {
+  type: "file";
+  operation: "read" | "write" | "edit" | "save";
+  path: string;
+  label: string;
+}
+
+/** Browser automation action */
+export interface BrowserStep extends BaseStep {
+  type: "browser";
+  action: "navigate" | "click" | "type" | "screenshot" | "scroll";
+  label: string;
+  url?: string;
+  screenshot?: string;
+}
+
+// ============================================
+// Union Type
+// ============================================
+
+export type ChainOfThoughtStep =
+  | SearchStep
+  | ImageStep
+  | TextStep
+  | ToolStep
+  | ThinkingStep
+  | FileStep
+  | BrowserStep;
+
+// ============================================
+// Helpers
+// ============================================
+
+let stepCounter = 0;
+
+export function createStepId(): string {
+  return `step_${Date.now()}_${++stepCounter}`;
+}
+
+export function createStep<T extends ChainOfThoughtStep>(
+  step: Omit<T, "id" | "timestamp" | "status"> & { status?: StepStatus }
+): T {
+  return {
+    id: createStepId(),
+    timestamp: Date.now(),
+    status: "active",
+    ...step,
+  } as T;
+}
+
+/** Map tool names to step types for automatic conversion */
+export const TOOL_STEP_MAP: Record<string, ChainOfThoughtStep["type"]> = {
+  // Search tools
+  web_search: "search",
+  web_social: "search",
+  web_news: "search",
+  // Browser tools
+  browser_open: "browser",
+  browser_click: "browser",
+  browser_type: "browser",
+  browser_screenshot: "browser",
+  browser_scroll: "browser",
+  browser_snapshot: "browser",
+  // File tools
+  file_read: "file",
+  file_write: "file",
+  file_edit: "file",
+  artifact_save: "file",
+  automation_saveArtifact: "file",
+  pdf_create: "file",
+  // Default fallback is "tool"
+};
+
+/** Get the step type for a tool name */
+export function getStepTypeForTool(toolName: string): ChainOfThoughtStep["type"] {
+  return TOOL_STEP_MAP[toolName] || "tool";
+}

package/shared/constants.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared Constants - Paths, limits, and defaults
+ *
+ * Configuration values used across the sandbox agent.
+ */
+
+// ============================================
+// Paths
+// ============================================
+
+export const PATHS = {
+  // Root directories
+  WORKSPACE: "/home/user/workspace",
+  ARTIFACTS: "/home/user/artifacts",
+  CONVEX_DATA: "/home/user/.convex",
+  SANDBOX_AGENT: "/home/user/sandbox-agent",
+
+  // Binary locations
+  BUN: "/home/user/.bun/bin/bun",
+  CONVEX_BACKEND: "/usr/local/bin/convex-backend",
+  AGENT_BROWSER: "/usr/local/bin/agent-browser",
+
+  // LSP binaries
+  TYPESCRIPT_LSP: "typescript-language-server",
+  PYTHON_LSP: "pylsp",
+  RUST_LSP: "rust-analyzer",
+} as const;
+
+// ============================================
+// Network
+// ============================================
+
+export const NETWORK = {
+  // Convex backend
+  CONVEX_PORT: 3210,
+  CONVEX_SITE_PORT: 3211,
+  CONVEX_URL: "http://localhost:3210",
+
+  // Health check endpoints
+  HEALTH_CHECK_INTERVAL_MS: 10000,
+  HEALTH_CHECK_TIMEOUT_MS: 5000,
+} as const;
+
+// ============================================
+// Limits
+// ============================================
+
+export const LIMITS = {
+  // File operations
+  MAX_FILE_SIZE_BYTES: 10 * 1024 * 1024, // 10MB
+  MAX_EDIT_SIZE_BYTES: 1 * 1024 * 1024,  // 1MB
+  MAX_GLOB_RESULTS: 1000,
+  MAX_GREP_MATCHES: 500,
+
+  // Output truncation
+  MAX_STDOUT_LENGTH: 50000,
+  MAX_STDERR_LENGTH: 50000,
+  MAX_DIFF_LENGTH: 100000,
+
+  // Timeouts
+  DEFAULT_COMMAND_TIMEOUT_MS: 120000,    // 2 minutes
+  MAX_COMMAND_TIMEOUT_MS: 600000,        // 10 minutes
+  LSP_REQUEST_TIMEOUT_MS: 30000,         // 30 seconds
+  BROWSER_ACTION_TIMEOUT_MS: 30000,      // 30 seconds
+
+  // Checkpointing
+  MAX_CHECKPOINT_MESSAGE_HISTORY: 50,
+  MAX_CHECKPOINT_FILE_STATE: 1000,
+
+  // Beads
+  MAX_BEADS_PER_QUERY: 100,
+  MAX_BEAD_TITLE_LENGTH: 200,
+  MAX_BEAD_DESCRIPTION_LENGTH: 10000,
+
+  // Sync queue
+  MAX_SYNC_ATTEMPTS: 3,
+  SYNC_RETRY_DELAY_MS: 5000,
+} as const;
+
+// ============================================
+// Defaults
+// ============================================
+
+export const DEFAULTS = {
+  // Beads
+  BEAD_PRIORITY: 2, // Medium
+  BEAD_TYPE: "task",
+
+  // Checkpoints
+  CHECKPOINT_CLEANUP_DAYS: 7,
+
+  // Context
+  CONTEXT_CACHE_TTL_MS: 3600000, // 1 hour
+
+  // Verification
+  TEST_COMMAND: "bun test",
+  LINT_COMMAND: "bun run lint",
+  TYPECHECK_COMMAND: "bunx tsc --noEmit",
+
+  // LSP
+  DEFAULT_LANGUAGE: "typescript",
+
+  // Browser
+  BROWSER_VIEWPORT_WIDTH: 1280,
+  BROWSER_VIEWPORT_HEIGHT: 720,
+} as const;
+
+// ============================================
+// File Extensions
+// ============================================
+
+export const FILE_EXTENSIONS = {
+  TYPESCRIPT: [".ts", ".tsx", ".mts", ".cts"],
+  JAVASCRIPT: [".js", ".jsx", ".mjs", ".cjs"],
+  PYTHON: [".py", ".pyi"],
+  RUST: [".rs"],
+  JSON: [".json", ".jsonc"],
+  YAML: [".yaml", ".yml"],
+  MARKDOWN: [".md", ".mdx"],
+  HTML: [".html", ".htm"],
+  CSS: [".css", ".scss", ".sass", ".less"],
+  CONFIG: [".toml", ".ini", ".cfg", ".conf"],
+} as const;
+
+// Helper to get language from file path
+export function getLanguageFromPath(path: string): "typescript" | "python" | "rust" | null {
+  const ext = path.slice(path.lastIndexOf(".")).toLowerCase();
+
+  if (FILE_EXTENSIONS.TYPESCRIPT.includes(ext as any) ||
+      FILE_EXTENSIONS.JAVASCRIPT.includes(ext as any)) {
+    return "typescript";
+  }
+  if (FILE_EXTENSIONS.PYTHON.includes(ext as any)) {
+    return "python";
+  }
+  if (FILE_EXTENSIONS.RUST.includes(ext as any)) {
+    return "rust";
+  }
+
+  return null;
+}
+
+// ============================================
+// Error Codes
+// ============================================
+
+export const ERROR_CODES = {
+  // File operations
+  FILE_NOT_FOUND: "FILE_NOT_FOUND",
+  FILE_TOO_LARGE: "FILE_TOO_LARGE",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  EDIT_MISMATCH: "EDIT_MISMATCH",
+
+  // Command execution
+  COMMAND_TIMEOUT: "COMMAND_TIMEOUT",
+  COMMAND_FAILED: "COMMAND_FAILED",
+  DANGEROUS_COMMAND: "DANGEROUS_COMMAND",
+
+  // LSP
+  LSP_NOT_RUNNING: "LSP_NOT_RUNNING",
+  LSP_REQUEST_FAILED: "LSP_REQUEST_FAILED",
+
+  // Browser
+  BROWSER_NOT_READY: "BROWSER_NOT_READY",
+  BROWSER_NAVIGATION_FAILED: "BROWSER_NAVIGATION_FAILED",
+
+  // Agent
+  THREAD_NOT_FOUND: "THREAD_NOT_FOUND",
+  CHECKPOINT_NOT_FOUND: "CHECKPOINT_NOT_FOUND",
+  SUBAGENT_FAILED: "SUBAGENT_FAILED",
+} as const;

package/shared/schemas/index.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared Schemas - Zod validation schemas
+ *
+ * Used for runtime validation of tool inputs and API payloads.
+ */
+
+import { z } from "zod";
+
+// ============================================
+// File Operations
+// ============================================
+
+export const filePathSchema = z.string()
+  .min(1, "Path cannot be empty")
+  .refine(
+    (p) => p.startsWith("/") || p.startsWith("./"),
+    "Path must be absolute or relative"
+  );
+
+export const fileReadArgsSchema = z.object({
+  path: filePathSchema,
+  encoding: z.enum(["utf8", "base64"]).default("utf8"),
+});
+
+export const fileWriteArgsSchema = z.object({
+  path: filePathSchema,
+  content: z.string(),
+  createDirs: z.boolean().default(true),
+});
+
+export const fileEditArgsSchema = z.object({
+  path: filePathSchema,
+  oldContent: z.string().min(1, "Old content cannot be empty"),
+  newContent: z.string(),
+});
+
+export const globArgsSchema = z.object({
+  pattern: z.string().min(1, "Pattern cannot be empty"),
+  cwd: z.string().default("/home/user/workspace"),
+  maxResults: z.number().int().positive().max(1000).default(100),
+});
+
+export const grepArgsSchema = z.object({
+  pattern: z.string().min(1, "Pattern cannot be empty"),
+  path: z.string().default("/home/user/workspace"),
+  fileGlob: z.string().optional(),
+  maxMatches: z.number().int().positive().max(500).default(50),
+});
+
+// ============================================
+// Bash Execution
+// ============================================
+
+export const bashArgsSchema = z.object({
+  command: z.string().min(1, "Command cannot be empty"),
+  cwd: z.string().optional(),
+  timeoutMs: z.number().int().positive().max(600000).default(120000),
+});
+
+// ============================================
+// Beads (Task Tracking)
+// ============================================
+
+export const beadTypeSchema = z.enum(["task", "bug", "feature", "epic", "chore"]);
+export const beadStatusSchema = z.enum(["open", "in_progress", "blocked", "closed"]);
+export const beadPrioritySchema = z.number().int().min(0).max(4);
+
+export const beadCreateArgsSchema = z.object({
+  title: z.string().min(1).max(200),
+  type: beadTypeSchema.default("task"),
+  priority: beadPrioritySchema.default(2),
+  description: z.string().max(10000).optional(),
+  labels: z.array(z.string()).optional(),
+  parentId: z.string().optional(),
+  blockedBy: z.array(z.string()).optional(),
+});
+
+export const beadUpdateArgsSchema = z.object({
+  id: z.string(),
+  status: beadStatusSchema.optional(),
+  priority: beadPrioritySchema.optional(),
+  title: z.string().min(1).max(200).optional(),
+  description: z.string().max(10000).optional(),
+  labels: z.array(z.string()).optional(),
+  blockedBy: z.array(z.string()).optional(),
+});
+
+// ============================================
+// LSP Operations
+// ============================================
+
+export const languageSchema = z.enum(["typescript", "python", "rust"]);
+
+export const lspPositionSchema = z.object({
+  line: z.number().int().min(0),
+  character: z.number().int().min(0),
+});
+
+export const lspDiagnosticsArgsSchema = z.object({
+  path: filePathSchema,
+  language: languageSchema.optional(),
+});
+
+export const lspCompletionArgsSchema = z.object({
+  path: filePathSchema,
+  line: z.number().int().min(0),
+  character: z.number().int().min(0),
+  language: languageSchema.optional(),
+});
+
+export const lspHoverArgsSchema = z.object({
+  path: filePathSchema,
+  line: z.number().int().min(0),
+  character: z.number().int().min(0),
+  language: languageSchema.optional(),
+});
+
+// ============================================
+// Browser Operations
+// ============================================
+
+export const browserOpenArgsSchema = z.object({
+  url: z.string().url(),
+});
+
+export const browserSnapshotArgsSchema = z.object({
+  interactive: z.boolean().default(true),
+});
+
+export const browserClickArgsSchema = z.object({
+  ref: z.string().regex(/^@e\d+$/, "Ref must be in format @e1, @e2, etc."),
+});
+
+export const browserTypeArgsSchema = z.object({
+  text: z.string(),
+});
+
+export const browserPressArgsSchema = z.object({
+  key: z.string(),
+});
+
+export const browserScrollArgsSchema = z.object({
+  direction: z.enum(["up", "down", "top", "bottom"]),
+});
+
+// ============================================
+// Subagent Operations
+// ============================================
+
+export const subagentSpawnArgsSchema = z.object({
+  name: z.string().min(1).max(50),
+  task: z.string().min(1).max(10000),
+  tools: z.array(z.string()).default([]),
+  model: z.string().default("gpt-4o-mini"),
+});
+
+export const subagentQueryArgsSchema = z.object({
+  subagentId: z.string(),
+});
+
+// ============================================
+// Artifacts
+// ============================================
+
+export const artifactSaveArgsSchema = z.object({
+  name: z.string().min(1).max(200),
+  type: z.string().default("text/plain"),
+  path: filePathSchema,
+  content: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+// ============================================
+// Checkpoints
+// ============================================
+
+export const checkpointReasonSchema = z.enum([
+  "timeout",
+  "token_limit",
+  "manual",
+  "error_recovery",
+]);
+
+export const checkpointCreateArgsSchema = z.object({
+  sessionId: z.string(),
+  threadId: z.string(),
+  iteration: z.number().int().min(0),
+  nextTask: z.string(),
+  reason: checkpointReasonSchema,
+  metadata: z.record(z.unknown()).optional(),
+});
+
+// Export all schemas
+export const schemas = {
+  file: {
+    read: fileReadArgsSchema,
+    write: fileWriteArgsSchema,
+    edit: fileEditArgsSchema,
+    glob: globArgsSchema,
+    grep: grepArgsSchema,
+  },
+  bash: bashArgsSchema,
+  beads: {
+    create: beadCreateArgsSchema,
+    update: beadUpdateArgsSchema,
+    type: beadTypeSchema,
+    status: beadStatusSchema,
+  },
+  lsp: {
+    diagnostics: lspDiagnosticsArgsSchema,
+    completion: lspCompletionArgsSchema,
+    hover: lspHoverArgsSchema,
+    language: languageSchema,
+  },
+  browser: {
+    open: browserOpenArgsSchema,
+    snapshot: browserSnapshotArgsSchema,
+    click: browserClickArgsSchema,
+    type: browserTypeArgsSchema,
+    press: browserPressArgsSchema,
+    scroll: browserScrollArgsSchema,
+  },
+  subagent: {
+    spawn: subagentSpawnArgsSchema,
+    query: subagentQueryArgsSchema,
+  },
+  artifact: {
+    save: artifactSaveArgsSchema,
+  },
+  checkpoint: {
+    create: checkpointCreateArgsSchema,
+  },
+};

package/shared/types.ts

@@ -0,0 +1,267 @@
+/**
+ * Shared Types - Common TypeScript definitions
+ *
+ * Types shared between Convex backend and runtime processes.
+ */
+
+// ============================================
+// Beads (Task Tracking)
+// ============================================
+
+export type BeadType = "task" | "bug" | "feature" | "epic" | "chore";
+export type BeadStatus = "open" | "in_progress" | "blocked" | "closed";
+export type BeadPriority = 0 | 1 | 2 | 3 | 4; // 0=critical, 4=backlog
+
+export interface Bead {
+  id: string;
+  title: string;
+  description?: string;
+  type: BeadType;
+  priority: BeadPriority;
+  labels: string[];
+  parentId?: string;
+  blockedBy: string[];
+  status: BeadStatus;
+  closedReason?: string;
+  assignee?: string;
+  threadId?: string;
+  createdAt: number;
+  updatedAt: number;
+  closedAt?: number;
+  relatedFiles: string[];
+}
+
+// ============================================
+// Artifacts
+// ============================================
+
+export interface Artifact {
+  name: string;
+  type: string; // MIME type
+  path: string;
+  size: number;
+  content?: string;
+  storageId?: string;
+  metadata?: Record<string, unknown>;
+  threadId?: string;
+  createdAt: number;
+  syncedToCloud: boolean;
+}
+
+// ============================================
+// File State
+// ============================================
+
+export type FileOperation = "read" | "write" | "edit";
+
+export interface FileState {
+  path: string;
+  contentHash?: string;
+  size?: number;
+  lastOperation: FileOperation;
+  lastAccessAt: number;
+  accessCount: number;
+  threadId?: string;
+}
+
+export interface EditHistoryEntry {
+  path: string;
+  oldContentHash: string;
+  newContentHash: string;
+  diff: string;
+  verified: boolean;
+  threadId?: string;
+  createdAt: number;
+  rolledBack?: boolean;
+  rollbackReason?: string;
+}
+
+// ============================================
+// Verification
+// ============================================
+
+export interface VerificationCheck {
+  name: string;
+  success: boolean;
+  output?: string;
+  durationMs?: number;
+}
+
+export interface VerificationResult {
+  success: boolean;
+  checks: VerificationCheck[];
+}
+
+export interface TestSuiteResult {
+  success: boolean;
+  exitCode: number | null;
+  output?: string;
+  errors?: string;
+  durationMs: number;
+  timedOut?: boolean;
+  testCommand: string;
+}
+
+// ============================================
+// Checkpoints
+// ============================================
+
+export type CheckpointReason = "timeout" | "token_limit" | "manual" | "error_recovery";
+export type CheckpointStatus = "active" | "restored" | "completed" | "failed" | "superseded";
+
+export interface FileSnapshot {
+  path: string;
+  contentHash: string;
+  size: number;
+  lastModified: number;
+}
+
+export interface BeadSnapshot {
+  id: string;
+  title: string;
+  status: string;
+  type: string;
+  priority: number;
+}
+
+export interface MessageSnapshot {
+  role: string;
+  content: string;
+  timestamp?: number;
+}
+
+export interface Checkpoint {
+  sessionId: string;
+  threadId: string;
+  iteration: number;
+  messageHistory: MessageSnapshot[];
+  fileState: FileSnapshot[];
+  beadsState: BeadSnapshot[];
+  artifactsProduced: string[];
+  nextTask: string;
+  reason: CheckpointReason;
+  status: CheckpointStatus;
+  metadata?: Record<string, unknown>;
+  createdAt: number;
+  restoredAt?: number;
+  completedAt?: number;
+  error?: string;
+}
+
+// ============================================
+// Agent Decisions
+// ============================================
+
+export type DecisionType =
+  | "tool_selection"
+  | "file_edit"
+  | "task_breakdown"
+  | "verification"
+  | "rollback"
+  | "checkpoint"
+  | "error_recovery";
+
+export type DecisionOutcome = "success" | "partial_success" | "failure" | "abandoned";
+
+export interface AgentDecision {
+  threadId: string;
+  task: string;
+  decisionType: DecisionType;
+  selectedTools?: string[];
+  reasoning: string;
+  expectedOutcome?: string;
+  alternatives?: Array<{ option: string; reason: string }>;
+  confidence?: number;
+  outcome?: DecisionOutcome;
+  actualResult?: string;
+  timestamp: number;
+}
+
+// ============================================
+// LSP
+// ============================================
+
+export type Language = "typescript" | "python" | "rust";
+
+export interface LspDiagnostic {
+  path: string;
+  line: number;
+  character: number;
+  severity: "error" | "warning" | "info" | "hint";
+  message: string;
+  code?: string | number;
+  source?: string;
+}
+
+export interface LspCompletion {
+  label: string;
+  kind: string;
+  detail?: string;
+  documentation?: string;
+  insertText?: string;
+}
+
+export interface LspHover {
+  contents: string;
+  range?: {
+    start: { line: number; character: number };
+    end: { line: number; character: number };
+  };
+}
+
+// ============================================
+// Browser
+// ============================================
+
+export interface BrowserElement {
+  ref: string;
+  tag: string;
+  text?: string;
+  role?: string;
+  attributes: Record<string, string>;
+}
+
+export interface BrowserSnapshot {
+  url: string;
+  title: string;
+  elements: BrowserElement[];
+  screenshot?: string;
+}
+
+// ============================================
+// Subagents
+// ============================================
+
+export type SubagentStatus = "pending" | "running" | "completed" | "failed";
+
+export interface Subagent {
+  parentThreadId: string;
+  threadId: string;
+  name: string;
+  task: string;
+  tools: string[];
+  model: string;
+  status: SubagentStatus;
+  result?: unknown;
+  error?: string;
+  createdAt: number;
+  completedAt?: number;
+}
+
+// ============================================
+// Sync Queue
+// ============================================
+
+export type SyncItemType = "artifact" | "bead" | "decision" | "checkpoint" | "result";
+export type SyncStatus = "pending" | "in_progress" | "completed" | "failed";
+
+export interface SyncQueueItem {
+  type: SyncItemType;
+  itemId: string;
+  priority: number;
+  status: SyncStatus;
+  attempts: number;
+  lastError?: string;
+  cloudId?: string;
+  createdAt: number;
+}