@stevederico/dotbot 0.16.0

package/tools/code.js

@@ -0,0 +1,101 @@
+import { writeFile, unlink } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Code execution tool: run JavaScript in a sandboxed Node.js subprocess
+ */
+export const codeTools = [
+  {
+    name: "run_code",
+    description:
+      "Execute JavaScript code and return the output. Use this for calculations, data processing, or when the user asks you to run code. The code runs in a Node.js subprocess.",
+    parameters: {
+      type: "object",
+      properties: {
+        code: {
+          type: "string",
+          description: "JavaScript code to execute. Use console.log() for output.",
+        },
+      },
+      required: ["code"],
+    },
+    execute: async (input, signal, context) => {
+      const tmpFile = `/tmp/dotbot_code_${Date.now()}.mjs`;
+
+      try {
+        await writeFile(tmpFile, input.code, "utf-8");
+
+        // Allowlist-only env
+        const cleanEnv = {
+          PATH: process.env.PATH,
+          TMPDIR: process.env.TMPDIR || '/tmp',
+        };
+
+        // Sandboxed Node.js subprocess with permission model
+        const { stdout, stderr } = await execFileAsync(
+          "node",
+          [
+            "--experimental-permission",
+            `--allow-fs-read=${tmpFile}`,
+            `--allow-fs-write=${tmpFile}`,
+            tmpFile,
+          ],
+          {
+            timeout: 10000,
+            maxBuffer: 1024 * 1024,
+            env: cleanEnv,
+          },
+        );
+
+        await unlink(tmpFile).catch(() => {});
+
+        if (context?.databaseManager) {
+          try {
+            await context.databaseManager.logAgentActivity(
+              context.dbConfig.dbType, context.dbConfig.db, context.dbConfig.connectionString,
+              context.userID, {
+                type: 'code_execution',
+                code: input.code.slice(0, 500),
+                output: (stdout || stderr || '').slice(0, 500),
+                success: !stderr
+              }
+            );
+          } catch (e) { /* best effort */ }
+        }
+
+        if (stderr) {
+          return `Stderr:\n${stderr}\n\nStdout:\n${stdout}`;
+        }
+
+        return stdout || "(no output)";
+      } catch (err) {
+        await unlink(tmpFile).catch(() => {});
+
+        if (context?.databaseManager) {
+          try {
+            await context.databaseManager.logAgentActivity(
+              context.dbConfig.dbType, context.dbConfig.db, context.dbConfig.connectionString,
+              context.userID, {
+                type: 'code_execution',
+                code: input.code.slice(0, 500),
+                output: (err.stderr || err.message || '').slice(0, 500),
+                success: false
+              }
+            );
+          } catch (e) { /* best effort */ }
+        }
+
+        if (err.killed) {
+          return "Error: code execution timed out (10s limit)";
+        }
+        if (err.stderr) {
+          return `Exit code ${err.code}\n\nStderr:\n${err.stderr}\n\nStdout:\n${err.stdout || ""}`;
+        }
+        return `Error executing code: ${err.message}`;
+      }
+    },
+  },
+];

package/tools/events.js

@@ -0,0 +1,145 @@
+/**
+ * Event Analytics Tools
+ *
+ * Query and summarize user activity events for usage analytics.
+ * Answers questions like "how many messages did I send this week?"
+ * or "what tools do I use most?"
+ */
+
+export const eventTools = [
+  {
+    name: "event_query",
+    description:
+      "Query user activity events with filters. Returns recent events matching the criteria. " +
+      "Use this to find specific events like messages sent, tool calls, goals created, etc.",
+    parameters: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          description:
+            "Event type filter: message_sent, message_received, tool_call, task_created, task_completed, trigger_fired",
+        },
+        startDate: {
+          type: "string",
+          description: "ISO date start filter, e.g. '2026-02-01'",
+        },
+        endDate: {
+          type: "string",
+          description: "ISO date end filter, e.g. '2026-02-18'",
+        },
+        limit: {
+          type: "number",
+          description: "Maximum results to return (default: 50, max: 200)",
+        },
+      },
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.eventStore) return "Error: eventStore not available";
+      try {
+        const limit = Math.min(input.limit || 50, 200);
+        const events = await context.eventStore.query({
+          userId: context.userID,
+          type: input.type,
+          startDate: input.startDate,
+          endDate: input.endDate,
+          limit,
+        });
+
+        if (events.length === 0) {
+          const filters = [];
+          if (input.type) filters.push(`type=${input.type}`);
+          if (input.startDate) filters.push(`from ${input.startDate}`);
+          if (input.endDate) filters.push(`to ${input.endDate}`);
+          return filters.length > 0
+            ? `No events found matching: ${filters.join(", ")}`
+            : "No events recorded yet.";
+        }
+
+        // Format events for display
+        return events.map((e) => {
+          const date = new Date(e.timestamp).toISOString().split("T")[0];
+          const time = new Date(e.timestamp).toISOString().split("T")[1].slice(0, 5);
+          const dataStr = e.data && Object.keys(e.data).length > 0
+            ? ` (${JSON.stringify(e.data)})`
+            : "";
+          return `${date} ${time} - ${e.type}${dataStr}`;
+        }).join("\n");
+      } catch (err) {
+        return `Error querying events: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "events_summary",
+    description:
+      "Get aggregated usage statistics and analytics. Shows counts by event type, " +
+      "time period breakdowns, and tool usage patterns. Use this to answer questions " +
+      "like 'how many messages this week?' or 'what are my most used tools?'",
+    parameters: {
+      type: "object",
+      properties: {
+        startDate: {
+          type: "string",
+          description: "ISO date start, e.g. '2026-02-01'",
+        },
+        endDate: {
+          type: "string",
+          description: "ISO date end, e.g. '2026-02-18'",
+        },
+        groupBy: {
+          type: "string",
+          enum: ["type", "day", "week", "month"],
+          description: "How to group results: by type (default), day, week, or month",
+        },
+      },
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.eventStore) return "Error: eventStore not available";
+      try {
+        const summary = await context.eventStore.summary({
+          userId: context.userID,
+          startDate: input.startDate,
+          endDate: input.endDate,
+          groupBy: input.groupBy || "type",
+        });
+
+        if (summary.total === 0) {
+          return "No events recorded yet.";
+        }
+
+        let output = `Total Events: ${summary.total}\n\n`;
+
+        // Format breakdown based on groupBy
+        const groupBy = input.groupBy || "type";
+        if (groupBy === "type") {
+          output += "By Type:\n";
+          for (const [type, count] of Object.entries(summary.breakdown)) {
+            output += `  ${type}: ${count}\n`;
+          }
+        } else {
+          output += `By ${groupBy.charAt(0).toUpperCase() + groupBy.slice(1)}:\n`;
+          for (const item of summary.breakdown) {
+            output += `  ${item.period}: ${item.count}\n`;
+          }
+        }
+
+        // Tool usage breakdown if available
+        if (summary.toolUsage && Object.keys(summary.toolUsage).length > 0) {
+          output += "\nTool Usage:\n";
+          // Sort by count descending
+          const sorted = Object.entries(summary.toolUsage)
+            .sort((a, b) => b[1] - a[1]);
+          for (const [tool, count] of sorted) {
+            output += `  ${tool}: ${count}\n`;
+          }
+        }
+
+        return output.trim();
+      } catch (err) {
+        return `Error generating summary: ${err.message}`;
+      }
+    },
+  },
+];

package/tools/files.js

@@ -0,0 +1,201 @@
+/**
+ * File system tools for user's virtual MongoDB filesystem
+ */
+export const fileTools = [
+  // ── File Read ──
+  {
+    name: "file_read",
+    description:
+      "Read the contents of a file from the user's virtual filesystem. Use this when the user asks you to look at, review, or analyze a file they've saved.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Full file path, e.g. '/Documents/todo.md'",
+        },
+      },
+      required: ["path"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.databaseManager) return "Error: filesystem not available";
+      try {
+        const { databaseManager, dbConfig, userID } = context;
+        const file = await databaseManager.readFile(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID, input.path
+        );
+        if (!file) return `File not found: ${input.path}`;
+        if (file.type === 'folder') return `${input.path} is a folder, not a file`;
+        const content = file.content || '';
+        const maxChars = 10000;
+        if (content.length > maxChars) {
+          return content.slice(0, maxChars) + `\n\n... [truncated, file is ${content.length} chars total]`;
+        }
+        return content || '(empty file)';
+      } catch (err) {
+        return `Error reading file: ${err.message}`;
+      }
+    },
+  },
+
+  // ── File Write ──
+  {
+    name: "file_write",
+    description:
+      "Write content to a file in the user's virtual filesystem. Creates the file if it doesn't exist, or updates it if it does. Use this when the user asks you to create or save a file.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Full file path, e.g. '/Documents/todo.md'",
+        },
+        content: {
+          type: "string",
+          description: "Content to write to the file",
+        },
+      },
+      required: ["path", "content"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.databaseManager) return "Error: filesystem not available";
+      try {
+        const { databaseManager, dbConfig, userID } = context;
+        const existing = await databaseManager.readFile(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID, input.path
+        );
+        if (existing) {
+          await databaseManager.updateFile(
+            dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID, input.path, { content: input.content }
+          );
+          return `Updated ${input.path} (${input.content.length} chars)`;
+        }
+        const parts = input.path.split('/');
+        const name = parts.pop();
+        const parentPath = parts.join('/') || '/';
+        const ext = name.includes('.') ? name.split('.').pop() : null;
+        await databaseManager.createFile(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID,
+          { name, type: 'file', parentPath, content: input.content, extension: ext, source: 'agent' }
+        );
+        return `Created ${input.path} (${input.content.length} chars)`;
+      } catch (err) {
+        return `Error writing file: ${err.message}`;
+      }
+    },
+  },
+
+  // ── File List ──
+  {
+    name: "file_list",
+    description: "List files and folders in a directory of the user's virtual filesystem.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory path to list, e.g. '/' or '/Documents'. Default: '/'" },
+      },
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.databaseManager) return "Error: filesystem not available";
+      try {
+        const { databaseManager, dbConfig, userID } = context;
+        await databaseManager.seedUserFiles(dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID);
+        const files = await databaseManager.listFiles(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID, input.path || '/'
+        );
+        if (!files || files.length === 0) return `No files in ${input.path || '/'}`;
+        return files.map(f =>
+          `${f.type === 'folder' ? '📁' : '📄'} ${f.name}${f.extension ? '.' + f.extension : ''}${f.type === 'file' && f.size ? ' (' + f.size + ' bytes)' : ''}`
+        ).join('\n');
+      } catch (err) {
+        return `Error listing files: ${err.message}`;
+      }
+    },
+  },
+
+  // ── File Delete ──
+  {
+    name: "file_delete",
+    description: "Delete a file or folder from the user's virtual filesystem.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Full file path to delete, e.g. '/Documents/old.md'" },
+      },
+      required: ["path"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.databaseManager) return "Error: filesystem not available";
+      try {
+        const { databaseManager, dbConfig, userID } = context;
+        const result = await databaseManager.deleteFiles(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID, input.path
+        );
+        return result.deletedCount > 0 ? `Deleted ${input.path}` : `File not found: ${input.path}`;
+      } catch (err) {
+        return `Error deleting file: ${err.message}`;
+      }
+    },
+  },
+
+  // ── File Move/Rename ──
+  {
+    name: "file_move",
+    description: "Move or rename a file in the user's virtual filesystem.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Current file path, e.g. '/Documents/old.md'" },
+        new_name: { type: "string", description: "New file name (for rename)" },
+        new_parent: { type: "string", description: "New parent path (for move), e.g. '/Downloads'" },
+      },
+      required: ["path"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.databaseManager) return "Error: filesystem not available";
+      try {
+        const { databaseManager, dbConfig, userID } = context;
+        const updates = {};
+        if (input.new_name) updates.name = input.new_name;
+        if (input.new_parent) updates.parentPath = input.new_parent;
+        if (Object.keys(updates).length === 0) return "Provide new_name or new_parent to move/rename.";
+        await databaseManager.updateFile(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID, input.path, updates
+        );
+        const dest = input.new_parent
+          ? `${input.new_parent}/${input.new_name || input.path.split('/').pop()}`
+          : input.path.replace(/[^/]+$/, input.new_name);
+        return `Moved ${input.path} → ${dest}`;
+      } catch (err) {
+        return `Error moving file: ${err.message}`;
+      }
+    },
+  },
+
+  // ── Folder Create ──
+  {
+    name: "folder_create",
+    description: "Create a new folder in the user's virtual filesystem.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Parent path, e.g. '/Documents'" },
+        name: { type: "string", description: "Folder name to create" },
+      },
+      required: ["path", "name"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.databaseManager) return "Error: filesystem not available";
+      try {
+        const { databaseManager, dbConfig, userID } = context;
+        await databaseManager.createFile(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID,
+          { name: input.name, type: 'folder', parentPath: input.path, source: 'agent' }
+        );
+        return `Created folder ${input.path}/${input.name}`;
+      } catch (err) {
+        return `Error creating folder: ${err.message}`;
+      }
+    },
+  },
+];

package/tools/images.js

@@ -0,0 +1,253 @@
+/**
+ * Image generation and management tools
+ */
+
+/**
+ * Default model for Grok Imagine image generation
+ */
+export const GROK_IMAGINE_MODEL = 'grok-imagine-image-beta';
+
+/**
+ * Generate an image using Grok Imagine API.
+ * Shared helper that can be used by both agent tools and HTTP endpoints.
+ *
+ * @param {string} prompt - Image description
+ * @param {string} apiKey - xAI API key
+ * @param {Object} [options]
+ * @param {AbortSignal} [options.signal] - Abort signal
+ * @param {string} [options.model] - Model override (default: grok-imagine-image-beta)
+ * @returns {Promise<{ success: boolean, url?: string, prompt?: string, error?: string }>}
+ */
+export async function generateImage(prompt, apiKey, options = {}) {
+  const { signal, model = GROK_IMAGINE_MODEL } = options;
+
+  if (!prompt) {
+    return { success: false, error: 'Prompt is required' };
+  }
+
+  if (!apiKey) {
+    return { success: false, error: 'xAI API key not configured' };
+  }
+
+  try {
+    const response = await fetch('https://api.x.ai/v1/images/generations', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ prompt, model, n: 1 }),
+      signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      return { success: false, error: `Grok Imagine API error: ${response.status} - ${errorText.slice(0, 200)}` };
+    }
+
+    const data = await response.json();
+    const url = data.data?.[0]?.url;
+
+    if (!url) {
+      return { success: false, error: 'No image URL in response' };
+    }
+
+    return { success: true, url, prompt };
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      return { success: false, error: 'Request was cancelled' };
+    }
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Extract visual themes from text and generate an image prompt.
+ * Uses Grok to summarize text into a visual description.
+ *
+ * @param {string} text - Text to extract visual themes from
+ * @param {string} apiKey - xAI API key
+ * @param {Object} [options]
+ * @param {AbortSignal} [options.signal] - Abort signal
+ * @param {string} [options.model] - Chat model override (default: grok-4-1-fast-non-reasoning)
+ * @returns {Promise<{ success: boolean, prompt?: string, error?: string }>}
+ */
+export async function extractVisualPrompt(text, apiKey, options = {}) {
+  const { signal, model = 'grok-4-1-fast-non-reasoning' } = options;
+
+  if (!text) {
+    return { success: false, error: 'Text is required' };
+  }
+
+  if (!apiKey) {
+    return { success: false, error: 'xAI API key not configured' };
+  }
+
+  try {
+    const response = await fetch('https://api.x.ai/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{
+          role: 'user',
+          content: `Extract visual themes from this text for an image.
+Output ONLY a brief image prompt (1-2 sentences). No explanation.
+Style: cinematic, high quality, detailed.
+
+Text: "${text.slice(0, 500)}"`
+        }],
+        max_tokens: 100
+      }),
+      signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      return { success: false, error: `Failed to extract visual themes: ${response.status}` };
+    }
+
+    const data = await response.json();
+    const prompt = data.choices?.[0]?.message?.content;
+
+    if (!prompt) {
+      return { success: false, error: 'No visual prompt generated' };
+    }
+
+    return { success: true, prompt };
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      return { success: false, error: 'Request was cancelled' };
+    }
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Generate an image from text, optionally extracting visual themes first.
+ * Convenience wrapper combining extractVisualPrompt + generateImage.
+ *
+ * @param {Object} input
+ * @param {string} [input.prompt] - Direct image prompt (takes precedence)
+ * @param {string} [input.text] - Text to extract visual themes from
+ * @param {string} apiKey - xAI API key
+ * @param {Object} [options]
+ * @param {AbortSignal} [options.signal] - Abort signal
+ * @returns {Promise<{ success: boolean, url?: string, prompt?: string, error?: string }>}
+ */
+export async function generateImageFromText({ prompt, text }, apiKey, options = {}) {
+  let imagePrompt = prompt;
+
+  // If text provided without prompt, extract visual themes first
+  if (text && !prompt) {
+    const extracted = await extractVisualPrompt(text, apiKey, options);
+    if (!extracted.success) {
+      return extracted;
+    }
+    imagePrompt = extracted.prompt;
+  }
+
+  if (!imagePrompt) {
+    return { success: false, error: 'Either prompt or text is required' };
+  }
+
+  return generateImage(imagePrompt, apiKey, options);
+}
+
+export const imageTools = [
+  {
+    name: "image_generate",
+    description: "Generate an AI image from a text prompt.",
+    parameters: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Description of the image to generate" },
+      },
+      required: ["prompt"],
+    },
+    execute: async (input, signal, context) => {
+      const apiKey = context?.providers?.xai?.apiKey;
+      const result = await generateImage(input.prompt, apiKey, { signal });
+
+      if (!result.success) {
+        return result.error;
+      }
+
+      // Log to activity for persistence
+      if (context?.databaseManager) {
+        try {
+          await context.databaseManager.logAgentActivity(
+            context.dbConfig.dbType, context.dbConfig.db, context.dbConfig.connectionString,
+            context.userID, { type: 'image_generation', prompt: input.prompt, url: result.url, source: 'agent' }
+          );
+        } catch (e) { /* best effort */ }
+      }
+
+      return JSON.stringify({ type: 'image', url: result.url, prompt: input.prompt });
+    },
+  },
+
+  {
+    name: "image_list",
+    description: "List the user's photos and generated images. Returns the most recent images with their prompts and dates.",
+    parameters: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Max number of photos to return (default 20)" },
+      },
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.databaseManager) return "Error: database not available";
+      try {
+        const { databaseManager, dbConfig, userID } = context;
+        const activity = await databaseManager.getAgentActivity(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID,
+          { type: 'image_generation', limit: input.limit || 20 }
+        );
+        if (!activity || activity.length === 0) return "No photos found.";
+        return activity.map((entry, i) => {
+          const date = entry.timestamp ? new Date(entry.timestamp).toLocaleDateString() : '';
+          const source = entry.source || 'user';
+          return `${i + 1}. "${entry.prompt || 'Untitled'}" — ${source} — ${date}\n   ${entry.url || '(no url)'}`;
+        }).join('\n\n');
+      } catch (err) {
+        return `Error listing photos: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "image_search",
+    description: "Search the user's photos and generated images by prompt text.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search term to match against image prompts" },
+      },
+      required: ["query"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.databaseManager) return "Error: database not available";
+      try {
+        const { databaseManager, dbConfig, userID } = context;
+        const activity = await databaseManager.getAgentActivity(
+          dbConfig.dbType, dbConfig.db, dbConfig.connectionString, userID,
+          { type: 'image_generation', limit: 100 }
+        );
+        if (!activity || activity.length === 0) return "No photos found.";
+        const query = input.query.toLowerCase();
+        const matches = activity.filter(e => (e.prompt || '').toLowerCase().includes(query));
+        if (matches.length === 0) return `No photos matching "${input.query}".`;
+        return matches.map((entry, i) => {
+          const date = entry.timestamp ? new Date(entry.timestamp).toLocaleDateString() : '';
+          return `${i + 1}. "${entry.prompt || 'Untitled'}" — ${entry.source || 'user'} — ${date}\n   ${entry.url || '(no url)'}`;
+        }).join('\n\n');
+      } catch (err) {
+        return `Error searching photos: ${err.message}`;
+      }
+    },
+  },
+];