@liquidmetal-ai/precip 1.0.0

package/src/tools/registry.ts

@@ -0,0 +1,125 @@
+/**
+ * Tool Registry - Manages tool registration and execution
+ */
+
+import type { Tool, ToolContext, ToolResult, Logger } from '../types.js';
+
+export class ToolRegistry {
+  private tools = new Map<string, Tool>();
+  private logger?: Logger;
+
+  constructor(logger?: Logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Register a tool
+   */
+  register(tool: Tool): void {
+    if (this.tools.has(tool.definition.name)) {
+      throw new Error(`Tool already registered: ${tool.definition.name}`);
+    }
+
+    this.tools.set(tool.definition.name, tool);
+  }
+
+  /**
+   * Register multiple tools
+   */
+  registerAll(tools: Tool[]): void {
+    for (const tool of tools) {
+      this.register(tool);
+    }
+  }
+
+  /**
+   * Unregister a tool
+   */
+  unregister(name: string): boolean {
+    return this.tools.delete(name);
+  }
+
+  /**
+   * Get a tool by name
+   */
+  getTool(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Get all tools
+   */
+  getAllTools(): Tool[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Get tool definitions for LLM
+   * Returns OpenAI-compatible tool definitions
+   */
+  getToolDefinitions(): any[] {
+    return this.getAllTools().map(tool => ({
+      type: 'function',
+      function: {
+        name: tool.definition.name,
+        description: tool.definition.description,
+        parameters: {
+          type: 'object',
+          properties: Object.fromEntries(
+            Object.entries(tool.definition.parameters).map(([name, param]) => {
+              // Strip out 'required' field from individual parameters
+              const { required: _, ...cleanParam } = param;
+              return [name, cleanParam];
+            })
+          ),
+          required: Object.entries(tool.definition.parameters)
+            .filter(([_, param]) => param.required)
+            .map(([name, _]) => name)
+        }
+      }
+    }));
+  }
+
+  /**
+   * Execute a tool
+   */
+  async execute(toolName: string, parameters: any, context: ToolContext): Promise<ToolResult> {
+    const tool = this.getTool(toolName);
+
+    if (!tool) {
+      return {
+        success: false,
+        error: `Tool not found: ${toolName}`
+      };
+    }
+
+    try {
+      const result = await tool.execute(parameters, context);
+
+      // Validate that the result is serializable (catches circular references, etc.)
+      try {
+        JSON.stringify(result);
+      } catch {
+        this.logger?.warn?.(`Tool '${toolName}' returned non-serializable result`);
+        return {
+          success: true,
+          result: { error: 'Tool result was not serializable' }
+        };
+      }
+
+      return {
+        success: true,
+        result
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      this.logger?.error?.(`Tool execution failed: ${toolName}`, { error: errorMessage });
+
+      return {
+        success: false,
+        error: errorMessage
+      };
+    }
+  }
+}

package/src/tools/script-tools.ts

@@ -0,0 +1,145 @@
+/**
+ * Script Execution Tool - Run JavaScript scripts from mounted storage
+ *
+ * Reads a script from a mount path and executes it in the QuickJS sandbox
+ * with all the same bridges as run_code, plus an `args` global for passing arguments.
+ *
+ * Designed to work with the Agent Skills specification's scripts/ directory convention.
+ * @see https://agentskills.io/specification
+ */
+
+import type { Tool, ToolContext, SandboxGlobals } from '../types.js';
+import type { Bucket } from '@liquidmetal-ai/raindrop-framework';
+import { Sandbox } from '../sandbox/index.js';
+import type { CodeToolOptions } from './code-tools.js';
+import { formatToolOutput, createMountGlobals, createBridgeInstallers } from './code-tools.js';
+
+const DESCRIPTION = `Execute a JavaScript script stored in a mount path.
+
+The script runs in the same sandbox as run_code with all the same APIs available
+(read, write, list, remove, query, execute, search, fetch, console, etc.).
+
+Additionally, the script receives an \`args\` global object containing the arguments
+passed to this tool. Use \`args.paramName\` to access parameters.
+
+Path format: /mount-name/path/to/script.js
+
+Example: run_script({ path: "/knowledge/skills/data-cleanup/scripts/normalize.js", args: { table: "users", domain: "gmail.com" } })`;
+
+/**
+ * Options for creating a script execution tool
+ */
+export interface ScriptToolOptions extends CodeToolOptions {
+  /**
+   * Custom tool name (default: 'run_script')
+   */
+  name?: string;
+}
+
+/**
+ * Create a script execution tool
+ *
+ * Reads a script from a mount and executes it in the sandbox with args injection.
+ */
+export function createScriptExecutionTool(options: ScriptToolOptions = {}): Tool {
+  const description = options.descriptionSuffix
+    ? DESCRIPTION + options.descriptionSuffix
+    : DESCRIPTION;
+
+  return {
+    definition: {
+      name: options.name || 'run_script',
+      description,
+      parameters: {
+        path: {
+          type: 'string',
+          description:
+            'Path to the script file in a mount, e.g. /knowledge/skills/data-cleanup/scripts/normalize.js',
+          required: true
+        },
+        args: {
+          type: 'object',
+          description:
+            'Arguments to pass to the script. Available as the `args` global inside the script.',
+          required: false
+        },
+        timeout: {
+          type: 'number',
+          description: 'Execution timeout in milliseconds (default: 30000)',
+          required: false
+        }
+      }
+    },
+
+    async execute(
+      params: { path: string; args?: Record<string, any>; timeout?: number },
+      context: ToolContext
+    ) {
+      const { mounts, logger } = context;
+      const mountManager = mounts;
+
+      // 1. Read the script from the mount
+      const parsed = mountManager.parsePath(params.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}`);
+      }
+
+      if (mount.type !== 'bucket' && mount.type !== 'smartbucket') {
+        throw new Error(
+          `Scripts can only be loaded from bucket or smartbucket mounts, got: ${mount.type}`
+        );
+      }
+
+      const bucket = mount.resource as Bucket;
+      const obj = await bucket.get(parsed.path);
+
+      if (!obj) {
+        throw new Error(`Script not found: ${params.path}`);
+      }
+
+      const code = await obj.text();
+
+      // 2. Build sandbox globals: mount globals + args + custom bridge
+      const customBridge =
+        typeof options.bridge === 'function' ? options.bridge(context) : options.bridge || {};
+
+      const mountGlobals = createMountGlobals(mountManager);
+
+      // Inject args as a plain object global (not a sandbox function)
+      const argsGlobal = params.args || {};
+
+      const asyncGlobals: SandboxGlobals = {
+        ...mountGlobals,
+        ...customBridge,
+        args: argsGlobal
+      };
+
+      // 3. Build bridge installers (shared with run_code)
+      const bridgeInstallers = createBridgeInstallers(mountManager);
+
+      // 4. Execute in sandbox
+      const sandbox = await Sandbox.getInstance();
+      const result = await sandbox.execute(code, asyncGlobals, {
+        timeoutMs: params.timeout || 30000,
+        memoryLimitBytes: 64 * 1024 * 1024,
+        logger,
+        bridgeInstallers
+      });
+
+      return formatToolOutput(result);
+    }
+  };
+}
+
+/**
+ * Default script execution tool
+ */
+export const ScriptExecutionTool: Tool = createScriptExecutionTool();
+
+/**
+ * All script tools
+ */
+export const ScriptTools: Tool[] = [ScriptExecutionTool];

package/src/tools/smartbucket-tools.ts

@@ -0,0 +1,203 @@
+/**
+ * SmartBucket Tools - Semantic search and chunk search
+ * Mount-aware: operates on SmartBuckets via path prefixes
+ */
+
+import type { Tool } from '../types.js';
+import type { SmartBucket } from '@liquidmetal-ai/raindrop-framework';
+import { createPathBasedTool } from './tool-factory.js';
+
+/**
+ * Perform semantic search on a SmartBucket mount
+ *
+ * Example: semantic_search("/knowledge", "machine learning algorithms")
+ */
+export const SemanticSearchTool: Tool = createPathBasedTool<{ path: string; query: string }, any>({
+  name: 'semantic_search',
+  description: `Perform semantic search on AI-indexed content in a SmartBucket.
+
+This search uses AI embeddings to find relevant content based on meaning, not just keywords.
+
+Path format: /smartbucket-name
+
+Parameters:
+• path - The SmartBucket mount path (e.g., /knowledge)
+• query - The search query (semantic search finds similar content)
+
+Returns: {results: [{text, source, score}], pagination: {total, page, pageSize, hasMore}, requestId}
+
+Use the requestId with get_search_page to retrieve more results if hasMore is true.
+
+Example: semantic_search("/knowledge", "machine learning algorithms")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'SmartBucket mount path, e.g., /knowledge',
+      required: true
+    },
+    query: {
+      type: 'string',
+      description: 'Search query for semantic search',
+      required: true
+    }
+  },
+  allowedMountTypes: ['smartbucket'],
+  mode: 'read',
+
+  async executor(mount, parsed, params) {
+    const smartbucket = mount.resource as SmartBucket;
+    const requestId = `search-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+
+    const result = await smartbucket.search({
+      input: params.query,
+      requestId
+    });
+
+    return {
+      path: params.path,
+      query: params.query,
+      requestId,
+      results: result.results.map(r => ({
+        text: r.text,
+        source: r.source,
+        score: r.score
+      })),
+      pagination: {
+        total: result.pagination.total,
+        page: result.pagination.page,
+        pageSize: result.pagination.pageSize,
+        hasMore: result.pagination.hasMore
+      }
+    };
+  }
+});
+
+/**
+ * Perform chunk search on a SmartBucket mount
+ *
+ * Example: chunk_search("/knowledge", "neural network architecture")
+ */
+export const ChunkSearchTool: Tool = createPathBasedTool<{ path: string; query: string }, any>({
+  name: 'chunk_search',
+  description: `Perform RAG (Retrieval-Augmented Generation) chunk search on a SmartBucket.
+
+This search is optimized for finding specific chunks/sections of documents relevant to the query.
+Best for finding specific facts, code examples, or detailed information.
+
+Path format: /smartbucket-name
+
+Parameters:
+• path - The SmartBucket mount path (e.g., /knowledge)
+• query - The search query
+
+Returns: {results: [{text, source, score, chunkSignature}]}
+
+Example: chunk_search("/knowledge", "how to configure authentication")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'SmartBucket mount path, e.g., /knowledge',
+      required: true
+    },
+    query: {
+      type: 'string',
+      description: 'Search query for chunk search',
+      required: true
+    }
+  },
+  allowedMountTypes: ['smartbucket'],
+  mode: 'read',
+
+  async executor(mount, parsed, params) {
+    const smartbucket = mount.resource as SmartBucket;
+    const requestId = `chunk-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+
+    const result = await smartbucket.chunkSearch({
+      input: params.query,
+      requestId
+    });
+
+    return {
+      path: params.path,
+      query: params.query,
+      results: result.results.map(r => ({
+        text: r.text,
+        source: r.source,
+        score: r.score,
+        chunkSignature: r.chunkSignature
+      }))
+    };
+  }
+});
+
+/**
+ * Get paginated results from a previous SmartBucket search
+ *
+ * Example: get_search_page("/knowledge", "request-id-123", 2)
+ */
+export const GetSearchPageTool: Tool = createPathBasedTool<{ path: string; requestId: string; page?: number }, any>({
+  name: 'get_search_page',
+  description: `Get the next page of results from a previous semantic_search.
+
+Use this after a semantic_search when pagination.hasMore is true.
+
+Path format: /smartbucket-name
+
+Parameters:
+• path - The SmartBucket mount path (e.g., /knowledge)
+• requestId - The requestId from the previous semantic_search
+• page - Page number to retrieve (default: 2)
+
+Returns: {results: [{text, source, score}], pagination: {total, page, pageSize, hasMore}}
+
+Example: get_search_page("/knowledge", "search-123456-abc", 2)`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'SmartBucket mount path, e.g., /knowledge',
+      required: true
+    },
+    requestId: {
+      type: 'string',
+      description: 'Request ID from previous semantic_search',
+      required: true
+    },
+    page: {
+      type: 'number',
+      description: 'Page number to retrieve (default: 2)',
+      required: false
+    }
+  },
+  allowedMountTypes: ['smartbucket'],
+  mode: 'read',
+
+  async executor(mount, parsed, params) {
+    const smartbucket = mount.resource as SmartBucket;
+
+    const result = await smartbucket.getPaginatedResults({
+      requestId: params.requestId,
+      page: params.page || 2
+    });
+
+    return {
+      path: params.path,
+      requestId: params.requestId,
+      results: result.results.map(r => ({
+        text: r.text,
+        source: r.source,
+        score: r.score
+      })),
+      pagination: {
+        total: result.pagination.total,
+        page: result.pagination.page,
+        pageSize: result.pagination.pageSize,
+        hasMore: result.pagination.hasMore
+      }
+    };
+  }
+});
+
+/**
+ * All SmartBucket tools (excluding DocumentChat as requested)
+ */
+export const SmartBucketTools: Tool[] = [SemanticSearchTool, ChunkSearchTool, GetSearchPageTool];

package/src/tools/sql-tools.ts

@@ -0,0 +1,213 @@
+/**
+ * SQL Tools - Execute SQL queries on SqlDatabase
+ * Mount-aware: operates on multiple databases via sql:mount-name prefix
+ */
+
+import type { Tool } from '../types.js';
+import type { SqlDatabase } from '@liquidmetal-ai/raindrop-framework';
+import { createPathBasedTool } from './tool-factory.js';
+
+/**
+ * Execute a SQL query (SELECT, etc.)
+ *
+ * Example: sql_query("sql:analytics", "SELECT * FROM events LIMIT 10")
+ */
+export const SqlQueryTool: Tool = createPathBasedTool<{ database: string; query: string; params?: any[] }, any>({
+  name: 'sql_query',
+  description: `Execute a SQL query (SELECT) and return results.
+
+Database format: sql:mount-name
+
+Returns: {results: Array<object>, success, rowCount, meta}
+
+Example: sql_query("sql:analytics", "SELECT * FROM events LIMIT 10")
+Returns: {"results": [{"id": 1, "type": "click"}], "success": true, "rowCount": 1}
+
+With parameters: sql_query("sql:main", "SELECT * FROM users WHERE id = ?", [123])`,
+  parameters: {
+    database: {
+      type: 'string',
+      description: 'Database mount name with sql: prefix, e.g., sql:analytics',
+      required: true
+    },
+    query: {
+      type: 'string',
+      description: 'SQL query to execute',
+      required: true
+    },
+    params: {
+      type: 'array',
+      description: 'Optional query parameters for prepared statement',
+      required: false,
+      items: {
+        type: 'string',
+        description: 'Parameter value'
+      }
+    }
+  },
+  allowedMountTypes: ['database'],
+  pathParameterName: 'database',
+  // Note: This is marked as 'read' mode but does not validate SQL statement type.
+  // Database-specific write-capable queries (e.g., SELECT ... FOR UPDATE) may still
+  // execute. Use sql_execute for explicit write operations (INSERT/UPDATE/DELETE).
+  mode: 'read',
+
+  async executor(mount, parsed, params) {
+    const db = mount.resource as SqlDatabase;
+
+    // Execute query
+    const stmt = params.params
+      ? db.prepare(params.query).bind(...params.params)
+      : db.prepare(params.query);
+
+    const result = await stmt.all();
+
+    return {
+      results: result.results,
+      success: result.success,
+      rowCount: result.results?.length || 0,
+      meta: result.meta
+    };
+  }
+});
+
+/**
+ * Execute a SQL statement (INSERT, UPDATE, DELETE, etc.)
+ *
+ * Example: sql_execute("sql:main", "INSERT INTO users (name) VALUES (?)", ["Alice"])
+ */
+export const SqlExecuteTool: Tool = createPathBasedTool<{ database: string; statement: string; params?: any[] }, any>({
+  name: 'sql_execute',
+  description: `Execute a SQL statement (INSERT, UPDATE, DELETE, CREATE, etc.) that modifies data.
+
+Database format: sql:mount-name
+
+Returns: {success, changes, lastRowId, meta}
+
+Example: sql_execute("sql:main", "INSERT INTO users (name) VALUES (?)", ["Alice"])
+Returns: {"success": true, "changes": 1, "lastRowId": 42}
+
+Example: sql_execute("sql:main", "DELETE FROM users WHERE id = ?", [123])
+Returns: {"success": true, "changes": 1}`,
+  parameters: {
+    database: {
+      type: 'string',
+      description: 'Database mount name with sql: prefix, e.g., sql:main',
+      required: true
+    },
+    statement: {
+      type: 'string',
+      description: 'SQL statement to execute',
+      required: true
+    },
+    params: {
+      type: 'array',
+      description: 'Optional statement parameters for prepared statement',
+      required: false,
+      items: {
+        type: 'string',
+        description: 'Parameter value'
+      }
+    }
+  },
+  allowedMountTypes: ['database'],
+  pathParameterName: 'database',
+  mode: 'write',
+
+  async executor(mount, parsed, params) {
+    const db = mount.resource as SqlDatabase;
+
+    // Execute statement
+    const stmt = params.params
+      ? db.prepare(params.statement).bind(...params.params)
+      : db.prepare(params.statement);
+
+    const result = await stmt.run();
+
+    return {
+      success: result.success,
+      changes: result.meta?.changes || 0,
+      lastRowId: result.meta?.last_row_id,
+      meta: result.meta
+    };
+  }
+});
+
+/**
+ * Execute a batch of SQL statements
+ *
+ * Example: sql_batch("sql:main", [
+ *   { sql: "INSERT INTO users (name) VALUES (?)", params: ["Alice"] },
+ *   { sql: "INSERT INTO users (name) VALUES (?)", params: ["Bob"] }
+ * ])
+ */
+export const SqlBatchTool: Tool = createPathBasedTool<{ database: string; statements: Array<{ sql: string; params?: any[] }> }, any>({
+  name: 'sql_batch',
+  description: `Execute multiple SQL statements in a single batch transaction.
+
+Database format: sql:mount-name
+
+Returns: {success, count, results: [{success, changes, lastRowId}]}
+
+Example: sql_batch("sql:main", [
+  {"sql": "INSERT INTO users (name) VALUES (?)", "params": ["Alice"]},
+  {"sql": "INSERT INTO users (name) VALUES (?)", "params": ["Bob"]}
+])
+Returns: {"success": true, "count": 2, "results": [{"success": true, "changes": 1}, {"success": true, "changes": 1}]}`,
+  parameters: {
+    database: {
+      type: 'string',
+      description: 'Database mount name with sql: prefix, e.g., sql:main',
+      required: true
+    },
+    statements: {
+      type: 'array',
+      description: 'Array of SQL statements to execute',
+      required: true,
+      items: {
+        type: 'object',
+        description: 'SQL statement with optional parameters',
+        properties: {
+          sql: {
+            type: 'string',
+            description: 'SQL statement'
+          },
+          params: {
+            type: 'array',
+            description: 'Optional parameters'
+          }
+        }
+      }
+    }
+  },
+  allowedMountTypes: ['database'],
+  pathParameterName: 'database',
+  mode: 'write',
+
+  async executor(mount, parsed, params) {
+    const db = mount.resource as SqlDatabase;
+
+    // Prepare statements
+    const stmts = params.statements.map(({ sql, params }) => {
+      return params ? db.prepare(sql).bind(...params) : db.prepare(sql);
+    });
+
+    // Execute batch
+    const results = await db.batch(stmts);
+
+    return {
+      success: true,
+      count: results.length,
+      results: results.map((r: any) => ({
+        success: r.success,
+        changes: r.meta?.changes,
+        lastRowId: r.meta?.last_row_id
+      }))
+    };
+  }
+});
+
+/**
+ * All SQL tools
+ */
+export const SqlTools: Tool[] = [SqlQueryTool, SqlExecuteTool, SqlBatchTool];