@liquidmetal-ai/precip 1.0.0

package/src/tools/code-tools.ts

@@ -0,0 +1,444 @@
+/**
+ * Code Execution Tool - Run JavaScript in a sandboxed environment
+ * All mounts are automatically available via path-based API
+ */
+
+import type { Tool, ToolContext, MountInfo, MountProvider, SandboxGlobals } from '../types.js';
+import { sandboxAsync } from '../types.js';
+import type {
+  Bucket,
+  SmartBucket,
+  KvCache,
+  SqlDatabase,
+  ActorStorage
+} from '@liquidmetal-ai/raindrop-framework';
+import { Sandbox } from '../sandbox/index.js';
+import { installStorage, type StorageMountInfo } from '../sandbox/bridges/storage.js';
+import { installSearch, type SearchMountInfo } from '../sandbox/bridges/search.js';
+import { installActor } from '../sandbox/bridges/actor.js';
+
+/**
+ * Create bridge installers for all mounted resources.
+ * Shared by code-tools and script-tools to avoid duplication.
+ */
+export function createBridgeInstallers(
+  mountManager: MountProvider
+): Array<(ctx: any) => void> {
+  const bridgeInstallers: Array<(ctx: any) => void> = [];
+
+  const bucketMounts = mountManager.getMountsByType('bucket');
+  const smartbucketMounts = mountManager.getMountsByType('smartbucket');
+  const kvMounts = mountManager.getMountsByType('kv');
+  const actorStorageMounts = mountManager.getMountsByType('actor-storage');
+  const allStorageMounts = [
+    ...bucketMounts,
+    ...smartbucketMounts,
+    ...kvMounts,
+    ...actorStorageMounts
+  ];
+
+  if (allStorageMounts.length > 0) {
+    const storageMountMap = new Map<string, StorageMountInfo>(
+      allStorageMounts.map(m => [
+        m.name,
+        {
+          name: m.name,
+          type: m.type as 'bucket' | 'smartbucket' | 'kv' | 'actor-storage',
+          resource: m.resource as Bucket | KvCache | ActorStorage,
+          mode: m.mode
+        }
+      ])
+    );
+    bridgeInstallers.push(ctx => installStorage(ctx, storageMountMap));
+  }
+
+  if (smartbucketMounts.length > 0) {
+    const searchMountMap = new Map<string, SearchMountInfo>(
+      smartbucketMounts.map(m => [
+        m.name,
+        {
+          name: m.name,
+          smartbucket: m.resource as SmartBucket
+        }
+      ])
+    );
+    bridgeInstallers.push(ctx => installSearch(ctx, searchMountMap));
+  }
+
+  const actorMounts = mountManager.getActorMounts();
+  if (actorMounts.size > 0) {
+    bridgeInstallers.push(ctx => installActor(ctx, actorMounts));
+  }
+
+  return bridgeInstallers;
+}
+/**
+ * Options for creating a customized code execution tool
+ */
+export interface CodeToolOptions {
+  /**
+   * Custom functions/objects to expose in the sandbox.
+   * Can be a static object or a factory function that receives ToolContext.
+   * Values must be typed sandbox globals (use sandboxAsync, sandboxSync, sandboxObject helpers).
+   *
+   * @example
+   * // Static bridge
+   * bridge: {
+   *   myApi: sandboxObject({
+   *     getData: sandboxAsync(async (key) => storage.get(key)),
+   *     setData: sandboxAsync(async (key, val) => storage.set(key, val))
+   *   })
+   * }
+   *
+   * @example
+   * // Dynamic bridge with access to context
+   * bridge: (ctx) => ({
+   *   rpc: sandboxObject({
+   *     call: sandboxAsync(async (method, params) => client.call(method, params))
+   *   })
+   * })
+   */
+  bridge?: SandboxGlobals | ((ctx: ToolContext) => SandboxGlobals);
+
+  /**
+   * Custom tool name (default: 'run_code')
+   */
+  name?: string;
+
+  /**
+   * Additional description to append to the base description.
+   * Use this to document your custom bridge functions.
+   */
+  descriptionSuffix?: string;
+}
+
+/**
+ * Base description for the code execution tool
+ */
+const BASE_DESCRIPTION = `Execute JavaScript code in a secure sandbox with async/await support.
+
+IMPORTANT RULES:
+- Write plain top-level code. Do NOT wrap in an IIFE or async function wrapper.
+- Do NOT use require() or import statements. All APIs below are pre-installed globals.
+- fetch, console, TextEncoder, TextDecoder, and Response are all available as globals.
+- Use \`return\` to produce a result value. Use console.log() for intermediate output.
+- await is supported at the top level — just use it directly.
+
+All storage is accessed via paths: /<mount-name>/path/to/resource
+
+STORAGE API:
+• read(path) - Read content from any mount
+  Returns: Response-like object with .text(), .json(), .arrayBuffer() methods
+           For files: also has .size, .uploaded, .body (ReadableStream)
+           For KV: also has .metadata (if set)
+  Example: const data = await (await read("/uploads/config.json")).json();
+           const text = await (await read("/cache/user:123")).text();
+           const state = await (await read("/state/counter")).json();
+
+• write(path, content, options?) - Write content to any mount
+  Returns: { success: boolean }
+  Options vary by mount type:
+    KV cache:      { ttl: 300 }  or  { expiration: 1720000000 }  or  { metadata: {...} }
+    File storage:  { contentType: "application/json" }  or  { customMetadata: { author: "alice" } }
+    Actor state:   (no options)
+  Example: await write("/uploads/output.txt", "Hello world");
+           await write("/cache/session:abc", JSON.stringify(data), { ttl: 300 });
+           await write("/state/prefs", JSON.stringify({ theme: "dark", lang: "en" }));
+
+• list(path, options?) - List files or keys
+  Returns: { files: Array<{key, size?, uploaded?, expiration?}>, count: number }
+  Options vary by mount type:
+    Common:        { limit: 100 }
+    File storage:  { delimiter: "/", startAfter: "key" }
+    Actor state:   { start: "a", end: "z", reverse: true, limit: 50 }
+  Example: const result = await list("/uploads/images/");
+           const entries = await list("/state/", { prefix: "user:", reverse: true });
+
+• remove(path) - Delete a file or key
+  Returns: { success: boolean }
+  Example: await remove("/uploads/old-file.txt");
+           await remove("/cache/expired-key");
+
+DATABASE API:
+• query(path, sql, params?) - Execute SELECT query
+  Returns: { results: Array<object>, rowCount: number }
+  Example: const data = await query("/analytics", "SELECT * FROM users LIMIT 10");
+
+• execute(path, sql, params?) - Execute INSERT/UPDATE/DELETE
+  Returns: { success: boolean, changes: number }
+  Example: await execute("/analytics", "INSERT INTO logs (msg) VALUES (?)", ["hello"]);
+
+SEARCH API (for searchable storage):
+• search(path, query) - Semantic search with pagination
+  Returns: { results, hasMore, nextPage(), total, page, pageSize }
+  
+  Simple usage:
+    const results = await search("/knowledge", "machine learning");
+    for (const r of results.results) {
+      console.log(r.text, r.score);
+    }
+  
+  With pagination:
+    let results = await search("/knowledge", "query");
+    while (results.hasMore) {
+      results = await results.nextPage();
+      // process results.results
+    }
+  
+  Auto-pagination with for-await:
+    const results = await search("/knowledge", "query");
+    for await (const r of results) {
+      console.log(r.text);  // automatically fetches next pages
+    }
+
+• chunkSearch(path, query) - RAG chunk search for text passages
+  Returns: { results: Array<{text, source, score, chunkSignature}> }
+  Example: const results = await chunkSearch("/knowledge", "how to configure");
+
+ACTOR API:
+• actor(path, instanceId) - Get an actor stub for RPC calls
+  Returns: Actor stub with callable methods
+  Example: const session = await actor("/sessions", "user-123");
+           const state = await session.getState();
+           await session.updatePrefs({ theme: "dark" });
+
+FETCH API:
+• fetch(url, options?) - Make HTTP requests
+  Returns: Response object with json(), text(), arrayBuffer() methods
+  Example: const res = await fetch("https://api.example.com/data");
+           const data = await res.json();
+
+CONSOLE:
+• console.log(...) - Log output (shown in [stdout] section)
+• console.warn(...), console.error(...) - Log with level prefix
+
+UTILITIES:
+• new TextEncoder() / new TextDecoder() - Encode/decode text
+• new Response(body, init?) - Create Response objects
+
+TIPS:
+- All paths start with / followed by the mount name
+- Always use await with async operations
+- Always return a value so results are visible
+- Use console.log() for debugging
+- Do NOT wrap code in (async () => { })() — await works at the top level
+- Do NOT use require() or import — all APIs are globals`;
+
+/**
+ * Create a code execution tool with optional custom bridges
+ *
+ * @example
+ * // Basic usage - same as CodeExecutionTool
+ * const tool = createCodeExecutionTool();
+ *
+ * @example
+ * // With static bridge
+ * const tool = createCodeExecutionTool({
+ *   bridge: {
+ *     myApi: {
+ *       getData: async (key) => storage.get(key)
+ *     }
+ *   }
+ * });
+ *
+ * @example
+ * // With dynamic bridge (has access to ToolContext)
+ * const tool = createCodeExecutionTool({
+ *   bridge: (ctx) => ({
+ *     rpc: createConnectClient(ctx.env.RPC_BINDING)
+ *   }),
+ *   descriptionSuffix: `
+ *
+ * RPC API:
+ * • rpc.users.getUser({ id }) - Get user by ID
+ * • rpc.users.createUser({ name, email }) - Create new user`
+ * });
+ */
+export function createCodeExecutionTool(options: CodeToolOptions = {}): Tool {
+  const description = options.descriptionSuffix
+    ? BASE_DESCRIPTION + options.descriptionSuffix
+    : BASE_DESCRIPTION;
+
+  return {
+    definition: {
+      name: options.name || 'run_code',
+      description,
+      parameters: {
+        code: {
+          type: 'string',
+          description: 'JavaScript code to execute. Must use async/await for I/O operations.',
+          required: true
+        },
+        timeout: {
+          type: 'number',
+          description: 'Execution timeout in milliseconds (default: 30000)',
+          required: false
+        }
+      }
+    },
+
+    async execute(params: { code: string; timeout?: number }, context: ToolContext) {
+      const { mounts, logger } = context;
+      const mountManager = mounts;
+
+      // Resolve custom bridge - static object or dynamic factory
+      const customBridge =
+        typeof options.bridge === 'function' ? options.bridge(context) : options.bridge || {};
+
+      // Create mount globals (database functions only - storage and search handled by bridges)
+      const mountGlobals = createMountGlobals(mountManager);
+
+      // Merge mount globals with custom bridge (custom bridge takes precedence)
+      const asyncGlobals = { ...mountGlobals, ...customBridge };
+
+      // Create bridge installers for all mounted resources
+      const bridgeInstallers = createBridgeInstallers(mountManager);
+
+      // Execute in sandbox
+      const sandbox = await Sandbox.getInstance();
+      const result = await sandbox.execute(params.code, asyncGlobals, {
+        timeoutMs: params.timeout || 30000,
+        memoryLimitBytes: 64 * 1024 * 1024,
+        logger,
+        bridgeInstallers
+      });
+
+      // Format output to include console.log and result
+      return formatToolOutput(result);
+    }
+  };
+}
+
+/**
+ * Default code execution tool (backward compatible)
+ *
+ * Execute JavaScript code with access to all mounted resources
+ *
+ * Example: run_code(`
+ *   const files = await bucket.list("@user-data/");
+ *   return files.length;
+ * `)
+ */
+export const CodeExecutionTool: Tool = createCodeExecutionTool();
+
+/**
+ * Format tool output with console.log and result sections
+ * Returns a consistent string format for OpenAI chat completions
+ */
+export function formatToolOutput(result: any): any {
+  const hasConsoleOutput = result.consoleOutput && result.consoleOutput.length > 0;
+  const hasError = !result.success && result.error;
+  // Only show result section if there's a meaningful result (not undefined)
+  const hasResult = result.success && 'result' in result && result.result !== undefined;
+
+  if (!hasConsoleOutput && !hasResult && !hasError) {
+    // No output at all - return empty
+    return { output: '(no output)' };
+  }
+
+  const lines: string[] = [];
+
+  if (hasError) {
+    lines.push('[error]');
+    lines.push(result.error);
+    lines.push('');
+  }
+
+  if (hasConsoleOutput) {
+    lines.push('[stdout]');
+    lines.push(...result.consoleOutput);
+    lines.push('');
+  }
+
+  if (hasResult) {
+    lines.push('[result]');
+    const MAX_OUTPUT_LEN = 50000;
+    const resultStr =
+      typeof result.result === 'object'
+        ? (() => {
+            try {
+              const json = JSON.stringify(result.result, null, 2);
+              return json.length > MAX_OUTPUT_LEN
+                ? json.substring(0, MAX_OUTPUT_LEN) + '\n...(truncated)'
+                : json;
+            } catch {
+              return String(result.result);
+            }
+          })()
+        : String(result.result).substring(0, MAX_OUTPUT_LEN);
+    lines.push(resultStr);
+  }
+
+  return {
+    output: lines.join('\n')
+  };
+}
+
+/**
+ * Create sandbox globals from mount manager
+ * Returns database and search functions (storage is handled by the storage bridge)
+ */
+export function createMountGlobals(mountManager: MountProvider): SandboxGlobals {
+  const globals: SandboxGlobals = {};
+
+  // Helper to parse path and get mount
+  const resolvePath = (path: string): { mount: MountInfo; resourcePath: string } => {
+    const parsed = mountManager.parsePath(path);
+    const mount = mountManager.getMount(parsed.mountName);
+    if (!mount) {
+      const available = Array.from(mountManager.getAllMounts().keys()).join(', ');
+      throw new Error(`Mount not found: ${parsed.mountName}. Available: ${available}`);
+    }
+    return { mount, resourcePath: parsed.path };
+  };
+
+  // query(path, sql, params?) - Execute SELECT query
+  globals.query = sandboxAsync(async (path: string, sql: string, params?: any[]) => {
+    const { mount } = resolvePath(path);
+
+    if (mount.type !== 'database') {
+      throw new Error(`Not a database mount: ${path}`);
+    }
+
+    const db = mount.resource as SqlDatabase;
+    const stmt = params ? db.prepare(sql).bind(...params) : db.prepare(sql);
+    const result = await stmt.all();
+
+    return {
+      results: result.results,
+      rowCount: result.results?.length || 0
+    };
+  });
+
+  // execute(path, sql, params?) - Execute INSERT/UPDATE/DELETE
+  globals.execute = sandboxAsync(async (path: string, sql: string, params?: any[]) => {
+    const { mount } = resolvePath(path);
+
+    if (mount.type !== 'database') {
+      throw new Error(`Not a database mount: ${path}`);
+    }
+
+    // Check if mount allows writes (default is read-only)
+    if (mount.mode !== 'rw') {
+      throw new Error(`Cannot execute write operations on read-only mount: ${path}`);
+    }
+
+    const db = mount.resource as SqlDatabase;
+    const stmt = params ? db.prepare(sql).bind(...params) : db.prepare(sql);
+    const result = await stmt.run();
+
+    return {
+      success: result.success,
+      changes: result.meta?.changes || 0
+    };
+  });
+
+  // Note: search and chunkSearch are handled by the search bridge
+
+  return globals;
+}
+
+/**
+ * Export code tool
+ */
+export const CodeTools: Tool[] = [CodeExecutionTool];

package/src/tools/file-tools.ts

@@ -0,0 +1,206 @@
+/**
+ * File Tools - Read, write, list, delete files from Buckets and SmartBuckets
+ * Mount-aware: operates on multiple buckets via path prefixes
+ * Supports both Bucket and SmartBucket (file operations only - use SmartBucket tools for AI search)
+ */
+
+import type { Tool } from '../types.js';
+import type { Bucket } from '@liquidmetal-ai/raindrop-framework';
+import { createPathBasedTool } from './tool-factory.js';
+
+/**
+ * Read a file from a mounted bucket or SmartBucket
+ *
+ * Example: read_file("/uploads/profile.json")
+ */
+export const ReadFileTool: Tool = createPathBasedTool<{ path: string }, any>({
+  name: 'read_file',
+  description: `Read a file from storage and return its contents.
+
+Path format: /mount-name/path/to/file.ext
+
+Works with both Buckets and SmartBuckets. For AI-powered search on SmartBuckets, use semantic_search or chunk_search tools.
+
+Returns: {path, content, size, uploaded, contentType}
+
+Example: read_file("/uploads/profile.json")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'File path starting with /, e.g., /uploads/profile.json',
+      required: true
+    }
+  },
+  allowedMountTypes: ['bucket', 'smartbucket'],
+  mode: 'read',
+
+  async executor(mount, parsed, params) {
+    const bucket = mount.resource as Bucket;
+    const obj = await bucket.get(parsed.path);
+
+    if (!obj) {
+      throw new Error(`File not found: ${params.path}`);
+    }
+
+    const content = await obj.text();
+
+    return {
+      path: params.path,
+      content,
+      size: obj.size,
+      uploaded: obj.uploaded.toISOString(),
+      contentType: obj.httpMetadata?.contentType
+    };
+  }
+});
+
+/**
+ * Write a file to a mounted bucket or SmartBucket
+ *
+ * Example: write_file("/outputs/result.json", '{"status": "done"}')
+ */
+export const WriteFileTool: Tool = createPathBasedTool<{ path: string; content: string; contentType?: string }, any>({
+  name: 'write_file',
+  description: `Write content to a file in storage. Creates or overwrites the file.
+
+Path format: /mount-name/path/to/file.ext
+
+Works with both Buckets and SmartBuckets. For SmartBuckets, uploaded content is automatically indexed for AI search.
+Note: Mount must have mode 'rw' to allow writes.
+
+Returns: {path, success, size}
+
+Example: write_file("/outputs/result.txt", "Hello World")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'File path starting with /, e.g., /outputs/result.txt',
+      required: true
+    },
+    content: {
+      type: 'string',
+      description: 'Content to write to the file',
+      required: true
+    },
+    contentType: {
+      type: 'string',
+      description: 'Optional content type, e.g., application/json, text/plain',
+      required: false
+    }
+  },
+  allowedMountTypes: ['bucket', 'smartbucket'],
+  mode: 'write',
+
+  async executor(mount, parsed, params) {
+    const bucket = mount.resource as Bucket;
+
+    await bucket.put(parsed.path, params.content, {
+      httpMetadata: params.contentType
+        ? {
+            contentType: params.contentType
+          }
+        : undefined
+    });
+
+    return {
+      path: params.path,
+      success: true,
+      size: params.content.length
+    };
+  }
+});
+
+/**
+ * List files in a mounted bucket or SmartBucket
+ *
+ * Example: list_files("/uploads/") or list_files("/logs/2024/")
+ */
+export const ListFilesTool: Tool = createPathBasedTool<{ path: string; limit?: number }, any>({
+  name: 'list_files',
+  description: `List files in storage with optional prefix filtering.
+
+Path format: /mount-name/ or /mount-name/prefix/
+
+Works with both Buckets and SmartBuckets.
+
+Returns: {files: [{path, size, uploaded}], truncated, count}
+
+Example: list_files("/uploads/")
+Example with prefix: list_files("/logs/2024/")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'Mount path with optional prefix, e.g., /uploads/ or /logs/2024/',
+      required: true
+    },
+    limit: {
+      type: 'number',
+      description: 'Maximum number of files to return (default: 1000)',
+      required: false
+    }
+  },
+  allowedMountTypes: ['bucket', 'smartbucket'],
+  mode: 'read',
+
+  async executor(mount, parsed, params) {
+    const bucket = mount.resource as Bucket;
+    const listed = await bucket.list({
+      prefix: parsed.path || undefined,
+      limit: params.limit || 1000
+    });
+
+    return {
+      files: listed.objects.map(obj => ({
+        path: `/${mount.name}/${obj.key}`,
+        size: obj.size,
+        uploaded: obj.uploaded.toISOString()
+      })),
+      truncated: listed.truncated,
+      count: listed.objects.length
+    };
+  }
+});
+
+/**
+ * Delete a file from a mounted bucket or SmartBucket
+ *
+ * Example: delete_file("/logs/old-file.txt")
+ */
+export const DeleteFileTool: Tool = createPathBasedTool<{ path: string }, any>({
+  name: 'delete_file',
+  description: `Delete a file from storage.
+
+Path format: /mount-name/path/to/file.ext
+
+Works with both Buckets and SmartBuckets. Note: Deleting from SmartBucket also removes its indexed content.
+Note: Mount must have mode 'rw' to allow deletes.
+
+Returns: {path, success, deleted}
+
+Example: delete_file("/logs/old-file.txt")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'File path starting with /, e.g., /logs/old-file.txt',
+      required: true
+    }
+  },
+  allowedMountTypes: ['bucket', 'smartbucket'],
+  mode: 'write',
+
+  async executor(mount, parsed, params) {
+    const bucket = mount.resource as Bucket;
+    await bucket.delete(parsed.path);
+
+    return {
+      path: params.path,
+      success: true,
+      deleted: true
+    };
+  }
+});
+
+/**
+ * All file tools
+ */
+export const FileTools: Tool[] = [ReadFileTool, WriteFileTool, ListFilesTool, DeleteFileTool];