@lakitu/sdk 0.1.0

package/ksa/_shared/ksaProxy.ts

@@ -0,0 +1,248 @@
+/**
+ * KSA Proxy - Framework-Level Instrumentation
+ *
+ * This is the core of the local DB integration framework.
+ * Wraps KSA modules with a Proxy that automatically applies behaviors
+ * like caching, file tracking, and call logging.
+ *
+ * Usage:
+ * ```typescript
+ * import * as fileRaw from "./file";
+ * import { createKSAProxy } from "./_shared/ksaProxy";
+ *
+ * export const file = createKSAProxy("file", fileRaw);
+ * ```
+ *
+ * The proxy is transparent to agents - they import and use KSAs normally,
+ * and the framework automatically applies behaviors based on config.
+ */
+
+import { getBehavior, type HookContext, type BeforeHookResult } from "./ksaBehaviors";
+import { getFrameworkConfigForKSA } from "./configReader";
+import type { FrameworkConfig } from "./configSchemas";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Any object that can be proxied (KSA module) */
+type ProxiableModule = Record<string, unknown>;
+
+/** Options for creating a KSA proxy */
+export interface ProxyOptions {
+  /** Override framework config (for testing) */
+  config?: Partial<FrameworkConfig>;
+  /** Disable all behaviors (passthrough mode) */
+  disabled?: boolean;
+}
+
+// ============================================================================
+// Proxy Factory
+// ============================================================================
+
+/**
+ * Create a proxied version of a KSA module.
+ *
+ * The proxy wraps all exported functions and automatically applies
+ * before/after hooks based on the KSA's behavior configuration.
+ *
+ * @param ksaName - Name of the KSA (e.g., "file", "web")
+ * @param ksaModule - The raw KSA module
+ * @param options - Optional configuration overrides
+ * @returns Proxied module with automatic behaviors
+ *
+ * @example
+ * // In ksa/index.ts
+ * import * as fileRaw from "./file";
+ * export const file = createKSAProxy("file", fileRaw);
+ *
+ * // Agent code (unchanged)
+ * import { file } from "./ksa";
+ * const content = await file.read("/path/to/file.txt");
+ * // Automatically tracked in local DB!
+ */
+export function createKSAProxy<T extends ProxiableModule>(
+  ksaName: string,
+  ksaModule: T,
+  options?: ProxyOptions
+): T {
+  // In passthrough mode, return the raw module
+  if (options?.disabled) {
+    return ksaModule;
+  }
+
+  // Get framework config for this KSA
+  const config = {
+    ...getFrameworkConfigForKSA(ksaName),
+    ...options?.config,
+  };
+
+  return new Proxy(ksaModule, {
+    get(target, prop: string | symbol) {
+      const original = target[prop as keyof T];
+
+      // Only wrap functions
+      if (typeof original !== "function") {
+        return original;
+      }
+
+      // Don't wrap internal properties
+      if (typeof prop === "symbol" || prop.startsWith("_")) {
+        return original;
+      }
+
+      // Return wrapped function
+      return createWrappedFunction(ksaName, prop, original as Function, config);
+    },
+  });
+}
+
+/**
+ * Create a wrapped version of a KSA function with automatic behaviors.
+ */
+function createWrappedFunction(
+  ksaName: string,
+  funcName: string,
+  original: Function,
+  config: FrameworkConfig
+): (...args: unknown[]) => Promise<unknown> {
+  return async function wrappedFunction(...args: unknown[]): Promise<unknown> {
+    const startTime = Date.now();
+
+    // Build hook context
+    const ctx: HookContext = {
+      ksaName,
+      funcName,
+      args,
+      config,
+      startTime,
+    };
+
+    // Get behaviors for this function
+    const { before, after } = getBehavior(ksaName, funcName);
+
+    // Execute before hook (may return cached result)
+    if (before) {
+      try {
+        const beforeResult = await before(ctx);
+        if (beforeResult && beforeResult.skipExecution) {
+          // Return cached result
+          return beforeResult.cachedResult;
+        }
+      } catch (e) {
+        // Before hook failed, continue with execution
+        console.warn(`[KSA Proxy] Before hook failed for ${ksaName}.${funcName}:`, e);
+      }
+    }
+
+    // Execute original function
+    let result: unknown;
+    let error: Error | undefined;
+
+    try {
+      result = await original.apply(null, args);
+    } catch (e) {
+      error = e instanceof Error ? e : new Error(String(e));
+      throw error;
+    } finally {
+      // Execute after hook (fire-and-forget for performance)
+      if (after) {
+        try {
+          // Don't await - fire and forget
+          Promise.resolve(after(ctx, result, error)).catch((e) => {
+            console.warn(`[KSA Proxy] After hook failed for ${ksaName}.${funcName}:`, e);
+          });
+        } catch (e) {
+          console.warn(`[KSA Proxy] After hook failed for ${ksaName}.${funcName}:`, e);
+        }
+      }
+    }
+
+    return result;
+  };
+}
+
+// ============================================================================
+// Bulk Proxy Creation
+// ============================================================================
+
+/**
+ * Create proxies for multiple KSA modules at once.
+ *
+ * @param modules - Map of KSA name to raw module
+ * @param options - Optional configuration overrides
+ * @returns Map of KSA name to proxied module
+ *
+ * @example
+ * import * as file from "./file";
+ * import * as web from "./web";
+ *
+ * const proxied = createKSAProxies({ file, web });
+ * export const { file: fileProxy, web: webProxy } = proxied;
+ */
+export function createKSAProxies<T extends Record<string, ProxiableModule>>(
+  modules: T,
+  options?: ProxyOptions
+): T {
+  const result = {} as T;
+
+  for (const [name, module] of Object.entries(modules)) {
+    result[name as keyof T] = createKSAProxy(name, module, options) as T[keyof T];
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Passthrough Mode
+// ============================================================================
+
+/**
+ * Check if proxy behaviors should be disabled.
+ *
+ * Behaviors are disabled when:
+ * - LAKITU_PROXY_DISABLED=true environment variable is set
+ * - Running in test mode (NODE_ENV=test)
+ */
+export function isProxyDisabled(): boolean {
+  return (
+    process.env.LAKITU_PROXY_DISABLED === "true" ||
+    process.env.NODE_ENV === "test"
+  );
+}
+
+/**
+ * Create a KSA proxy with automatic passthrough detection.
+ * Uses isProxyDisabled() to determine if behaviors should be applied.
+ */
+export function createKSAProxyAuto<T extends ProxiableModule>(
+  ksaName: string,
+  ksaModule: T,
+  options?: Omit<ProxyOptions, "disabled">
+): T {
+  return createKSAProxy(ksaName, ksaModule, {
+    ...options,
+    disabled: isProxyDisabled(),
+  });
+}
+
+// ============================================================================
+// Debug Utilities
+// ============================================================================
+
+/**
+ * Get debug info about the proxy configuration for a KSA.
+ */
+export function getProxyDebugInfo(ksaName: string): {
+  config: FrameworkConfig;
+  isDisabled: boolean;
+  hasBehaviors: boolean;
+} {
+  const config = getFrameworkConfigForKSA(ksaName);
+
+  return {
+    config,
+    isDisabled: isProxyDisabled(),
+    hasBehaviors: true, // All KSAs have at least default behaviors
+  };
+}

package/ksa/_shared/localDb.ts

@@ -0,0 +1,302 @@
+/**
+ * Local DB Client - Sandbox Convex Integration
+ *
+ * Shared client for calling the local Convex backend running in the E2B sandbox.
+ * This is the foundation for automatic state tracking, caching, and session persistence.
+ *
+ * Key differences from gateway.ts:
+ * - Calls LOCAL Convex at http://localhost:3210 (not cloud)
+ * - No JWT required (sandbox is trusted)
+ * - Designed for high-frequency, low-latency operations
+ *
+ * @example
+ * import { localDb, getSessionId } from './_shared/localDb';
+ *
+ * // Blocking query
+ * const files = await localDb.query('state/files:getByThread', { threadId });
+ *
+ * // Blocking mutation
+ * const id = await localDb.mutate('planning/beads:create', { title: 'Task' });
+ *
+ * // Fire-and-forget (non-blocking)
+ * localDb.fire('state/files:trackFileAccess', { path, operation: 'read' });
+ */
+
+import { readFileSync, existsSync } from "fs";
+
+// ============================================================================
+// Environment Loading
+// ============================================================================
+
+function loadEnvFile(): Record<string, string> {
+  const envPath = "/home/user/.env";
+  if (!existsSync(envPath)) return {};
+
+  try {
+    const content = readFileSync(envPath, "utf-8");
+    const envVars: Record<string, string> = {};
+    for (const line of content.split("\n")) {
+      const match = line.match(/^export\s+(\w+)="([^"]*)"/);
+      if (match) {
+        envVars[match[1]] = match[2];
+      }
+    }
+    return envVars;
+  } catch {
+    return {};
+  }
+}
+
+const envFile = loadEnvFile();
+
+// Local Convex URL (sandbox backend, NOT cloud gateway)
+const LOCAL_CONVEX_URL = process.env.CONVEX_URL || envFile.CONVEX_URL || "http://localhost:3210";
+
+// Session identifiers
+export const SESSION_ID = process.env.SESSION_ID || envFile.SESSION_ID || `session_${Date.now()}`;
+export const THREAD_ID = process.env.THREAD_ID || envFile.THREAD_ID;
+export const CARD_ID = process.env.CARD_ID || envFile.CARD_ID;
+
+// ============================================================================
+// Path Conversion
+// ============================================================================
+
+/**
+ * Convert dot-notation path to Convex HTTP API format.
+ * "planning.beads.create" -> "planning/beads:create"
+ */
+function toConvexPath(dotPath: string): string {
+  const parts = dotPath.split(".");
+  const funcName = parts.pop()!;
+  const modulePath = parts.join("/");
+  return `${modulePath}:${funcName}`;
+}
+
+// ============================================================================
+// Core Client Functions
+// ============================================================================
+
+/**
+ * Execute a query on local Convex (blocking).
+ *
+ * @param path - Dot-notation path (e.g., 'state/files.getByPath')
+ * @param args - Query arguments
+ * @returns Query result
+ */
+async function query<T = unknown>(
+  path: string,
+  args: Record<string, unknown> = {}
+): Promise<T> {
+  const convexPath = toConvexPath(path);
+
+  const response = await fetch(`${LOCAL_CONVEX_URL}/api/query`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ path: convexPath, args, format: "json" }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Local Convex query error (${response.status}): ${text}`);
+  }
+
+  const result = await response.json();
+  return result.value as T;
+}
+
+/**
+ * Execute a mutation on local Convex (blocking).
+ *
+ * @param path - Dot-notation path (e.g., 'state/files.trackFileAccess')
+ * @param args - Mutation arguments
+ * @returns Mutation result
+ */
+async function mutate<T = unknown>(
+  path: string,
+  args: Record<string, unknown> = {}
+): Promise<T> {
+  const convexPath = toConvexPath(path);
+
+  const response = await fetch(`${LOCAL_CONVEX_URL}/api/mutation`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ path: convexPath, args, format: "json" }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Local Convex mutation error (${response.status}): ${text}`);
+  }
+
+  const result = await response.json();
+  return result.value as T;
+}
+
+/**
+ * Execute an action on local Convex (blocking).
+ *
+ * @param path - Dot-notation path
+ * @param args - Action arguments
+ * @returns Action result
+ */
+async function action<T = unknown>(
+  path: string,
+  args: Record<string, unknown> = {}
+): Promise<T> {
+  const convexPath = toConvexPath(path);
+
+  const response = await fetch(`${LOCAL_CONVEX_URL}/api/action`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ path: convexPath, args, format: "json" }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Local Convex action error (${response.status}): ${text}`);
+  }
+
+  const result = await response.json();
+  return result.value as T;
+}
+
+/**
+ * Fire-and-forget mutation (non-blocking).
+ * Use for non-critical tracking operations where latency matters.
+ *
+ * @param path - Dot-notation path
+ * @param args - Mutation arguments
+ */
+function fire(
+  path: string,
+  args: Record<string, unknown> = {}
+): void {
+  const convexPath = toConvexPath(path);
+
+  fetch(`${LOCAL_CONVEX_URL}/api/mutation`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ path: convexPath, args, format: "json" }),
+  }).catch(() => {
+    // Intentionally ignore errors - fire and forget
+  });
+}
+
+/**
+ * Fire-and-forget query (non-blocking).
+ * Rarely needed, but available for completeness.
+ */
+function fireQuery(
+  path: string,
+  args: Record<string, unknown> = {}
+): void {
+  const convexPath = toConvexPath(path);
+
+  fetch(`${LOCAL_CONVEX_URL}/api/query`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ path: convexPath, args, format: "json" }),
+  }).catch(() => {
+    // Intentionally ignore errors
+  });
+}
+
+// ============================================================================
+// Exported Client
+// ============================================================================
+
+/**
+ * Local Convex database client for sandbox operations.
+ *
+ * Use this for all local DB operations in the KSA framework.
+ * The fire() method is optimized for high-frequency tracking calls.
+ */
+export const localDb = {
+  query,
+  mutate,
+  action,
+  fire,
+  fireQuery,
+};
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Get the current session ID.
+ * Used for session-scoped caching and memory.
+ */
+export function getSessionId(): string {
+  return SESSION_ID;
+}
+
+/**
+ * Get the current thread ID (if available).
+ * Used for thread-scoped operations.
+ */
+export function getThreadId(): string | undefined {
+  return THREAD_ID;
+}
+
+/**
+ * Get the current card ID (if available).
+ * Used for kanban card-scoped operations.
+ */
+export function getCardId(): string | undefined {
+  return CARD_ID;
+}
+
+/**
+ * Check if local Convex is available.
+ * Useful for graceful degradation.
+ */
+export async function isLocalDbAvailable(): Promise<boolean> {
+  try {
+    const response = await fetch(`${LOCAL_CONVEX_URL}/version`, {
+      method: "GET",
+      signal: AbortSignal.timeout(1000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get local Convex connection info.
+ * Useful for debugging.
+ */
+export function getLocalDbConfig() {
+  return {
+    url: LOCAL_CONVEX_URL,
+    sessionId: SESSION_ID,
+    threadId: THREAD_ID,
+    cardId: CARD_ID,
+  };
+}
+
+// ============================================================================
+// Cache Helpers
+// ============================================================================
+
+/**
+ * Generate a cache key from function name and arguments.
+ */
+export function cacheKey(ksaName: string, funcName: string, args: unknown[]): string {
+  const argsHash = JSON.stringify(args);
+  return `${ksaName}.${funcName}:${argsHash}`;
+}
+
+/**
+ * Simple hash function for cache keys.
+ */
+export function simpleHash(str: string): string {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return hash.toString(16);
+}

package/ksa/index.ts

@@ -0,0 +1,134 @@
+/**
+ * KSA Index - Knowledge, Skills, and Abilities
+ *
+ * This module re-exports from the Lakitu SDK and definitions.
+ *
+ * ## Architecture
+ *
+ * KSAs are now defined in `convex/lakitu/definitions/` using the TypeScript SDK
+ * from `packages/lakitu/sdk/`. This file provides backward compatibility.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Import the SDK for defining custom KSAs
+ * import { defineKSA, fn, service, primitive } from '@lakitu/sdk';
+ *
+ * // Import KSA definitions
+ * import { fileKSA, webKSA } from 'convex/lakitu/definitions';
+ *
+ * // Execute KSA functions
+ * import { executeFunction, createKSAProxy } from '@lakitu/sdk';
+ * ```
+ */
+
+// ============================================================================
+// Re-export SDK
+// ============================================================================
+
+export {
+  // Types
+  type KSADef,
+  type KSADefinition,
+  type FunctionDef,
+  type ParamDef,
+  type ParamType,
+  type Implementation,
+  type ServiceImpl,
+  type PrimitiveImpl,
+  type CompositeImpl,
+  type ExecutionContext,
+  type ExecutionResult,
+
+  // Builders
+  defineKSA,
+  fn,
+  service,
+  primitive,
+  composite,
+
+  // Runtime
+  executeFunction,
+  createKSAProxy,
+  createKSAProxies,
+
+  // Primitives
+  file,
+  shell,
+  browser,
+  getPrimitive,
+  hasPrimitive,
+  PRIMITIVES,
+
+  // Gateway
+  callGateway,
+  callGatewayBatch,
+  fireAndForget,
+} from "../sdk";
+
+// ============================================================================
+// Re-export Gateway (for backward compatibility)
+// ============================================================================
+
+export {
+  callGateway as callGatewayLegacy,
+  callGatewayBatch as callGatewayBatchLegacy,
+  fireAndForget as fireAndForgetLegacy,
+  THREAD_ID,
+  CARD_ID,
+  WORKSPACE_ID,
+  getGatewayConfig,
+} from "./_shared/gateway";
+
+// ============================================================================
+// Re-export from Generated Registry (for backward compatibility)
+// ============================================================================
+
+export type { KSAInfo, KSACategory, KSAGroup } from "./_generated/registry";
+
+export {
+  KSA_REGISTRY,
+  CORE_KSAS as CORE_KSA_NAMES,
+  getAllKSAs,
+  getKSA as getKSALegacy,
+  getKSAsByCategory as getKSAsByCategoryLegacy,
+  getKSAsByNames,
+  searchKSAs,
+  getServicePathsForKSAs,
+  isServicePathAllowed,
+} from "./_generated/registry";
+
+// ============================================================================
+// Re-export Config Schemas (for backward compatibility)
+// ============================================================================
+
+export type { ConfigField, PresetDefinition } from "./_shared/configSchemas";
+
+export {
+  CONFIG_SCHEMAS,
+  CONFIG_DEFAULTS,
+  KSA_PRESETS,
+  getConfigSchema,
+  getConfigDefaults,
+  getPreset,
+  getPresetsForKSA,
+  resolvePreset,
+  FRAMEWORK_CONFIG_SCHEMA,
+  FRAMEWORK_DEFAULTS,
+  getFrameworkConfig,
+} from "./_shared/configSchemas";
+
+export type { FrameworkConfig } from "./_shared/configSchemas";
+
+// ============================================================================
+// Re-export Local DB (for backward compatibility)
+// ============================================================================
+
+export {
+  localDb,
+  getSessionId,
+  getThreadId,
+  getCardId,
+  isLocalDbAvailable,
+  getLocalDbConfig,
+} from "./_shared/localDb";