@stevederico/dotbot 0.16.0

package/tools/index.js

@@ -0,0 +1,97 @@
+/**
+ * Tool Registry
+ *
+ * Central registry for agent tools with dynamic registration API.
+ */
+
+import { memoryTools } from './memory.js';
+import { webTools } from './web.js';
+import { codeTools } from './code.js';
+import { fileTools } from './files.js';
+import { messageTools } from './messages.js';
+import { imageTools } from './images.js';
+import { weatherTools } from './weather.js';
+import { notifyTools } from './notify.js';
+import { browserTools, createBrowserTools } from './browser.js';
+import { taskTools, goalTools } from './tasks.js';
+import { triggerTools } from './triggers.js';
+import { jobTools, cronTools } from './jobs.js';
+import { eventTools } from './events.js';
+import { appgenTools } from './appgen.js';
+
+/**
+ * Core tools included in the library by default
+ */
+export const coreTools = [
+  ...memoryTools,
+  ...webTools,
+  ...codeTools,
+  ...fileTools,
+  ...messageTools,
+  ...imageTools,
+  ...weatherTools,
+  ...notifyTools,
+  ...browserTools,
+  ...taskTools,
+  ...triggerTools,
+  ...jobTools,
+  ...eventTools,
+  ...appgenTools,
+];
+
+/**
+ * Create a tool registry with dynamic registration
+ *
+ * @returns {Object} Tool registry with register/getAll methods
+ */
+export function createToolRegistry() {
+  const tools = [];
+
+  return {
+    /**
+     * Register one or more tools
+     *
+     * @param {...Object} newTools - Tool definitions to register
+     */
+    register(...newTools) {
+      tools.push(...newTools);
+    },
+
+    /**
+     * Get all registered tools
+     *
+     * @returns {Array} All registered tools
+     */
+    getAll() {
+      return tools;
+    },
+
+    /**
+     * Clear all registered tools
+     */
+    clear() {
+      tools.length = 0;
+    },
+  };
+}
+
+// Re-export individual tool arrays for direct access
+export {
+  memoryTools,
+  webTools,
+  codeTools,
+  fileTools,
+  messageTools,
+  imageTools,
+  weatherTools,
+  notifyTools,
+  browserTools,
+  createBrowserTools,
+  taskTools,
+  goalTools,   // backwards compatibility alias
+  triggerTools,
+  jobTools,
+  cronTools,   // backwards compatibility alias
+  eventTools,
+  appgenTools,
+};

package/tools/jobs.js

@@ -0,0 +1,159 @@
+/**
+ * Job Tools
+ *
+ * Agent tools for scheduling and managing jobs (time-triggered scheduled prompts).
+ * Each tool receives (input, signal, context) where context.cronStore
+ * provides the storage backend.
+ */
+
+import { parseInterval } from '../storage/cron_constants.js';
+
+/**
+ * Agent tools for scheduling and managing jobs
+ * @type {Array<{name: string, description: string, parameters: Object, execute: Function}>}
+ */
+export const jobTools = [
+  {
+    name: "schedule_job",
+    description:
+      "Schedule a job to run later or on a recurring basis. The job will send a message to you (the agent) at the scheduled time, and you will process it like a normal user message. Use this for reminders, periodic checks, daily summaries, etc.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Short name for the job. e.g. 'daily-news-summary', 'remind-standup'",
+        },
+        prompt: {
+          type: "string",
+          description:
+            "The message that will be sent to you when the job fires. Write it as if the user is asking you to do something. e.g. 'Give me a summary of today\\'s top tech news' or 'Remind me about the standup meeting in 10 minutes'",
+        },
+        run_at: {
+          type: "string",
+          description:
+            "When to run. ISO 8601 datetime string. e.g. '2025-01-15T09:00:00' for a specific time.",
+        },
+        interval: {
+          type: "string",
+          description:
+            "For recurring jobs: interval between runs. e.g. '30m' (30 minutes), '2h' (2 hours), '1d' (daily), '1w' (weekly). Omit for one-shot jobs.",
+        },
+      },
+      required: ["name", "prompt", "run_at"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.cronStore) return "Error: cron store not available";
+      try {
+        const { sessionId, userID } = context || {};
+        const intervalMs = input.interval ? parseInterval(input.interval) : null;
+        const recurring = !!intervalMs;
+
+        const task = await context.cronStore.createTask({
+          name: input.name,
+          prompt: input.prompt,
+          sessionId: sessionId || 'default',
+          userId: userID,
+          runAt: input.run_at,
+          intervalMs,
+          recurring,
+        });
+
+        const desc = recurring
+          ? `Recurring job "${input.name}" scheduled starting ${input.run_at}, repeating every ${input.interval}`
+          : `One-time job "${input.name}" scheduled for ${input.run_at}`;
+
+        return desc;
+      } catch (err) {
+        return `Error scheduling job: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "list_jobs",
+    description: "List all scheduled jobs (active and completed).",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.cronStore) return "Error: cron store not available";
+      try {
+        const tasks = await context.cronStore.listTasks();
+
+        if (tasks.length === 0) {
+          return "No scheduled jobs.";
+        }
+
+        return tasks
+          .map(
+            (t) =>
+              `- ${t.name} [${t.enabled ? "active" : "done"}]` +
+              `\n  prompt: "${t.prompt}"` +
+              `\n  next: ${t.nextRunAt?.toISOString?.() || t.nextRunAt || "n/a"}` +
+              (t.recurring ? `\n  repeats every ${t.intervalMs / 60000}m` : "") +
+              (t.lastRunAt ? `\n  last ran: ${t.lastRunAt.toISOString?.() || t.lastRunAt}` : "")
+          )
+          .join("\n\n");
+      } catch (err) {
+        return `Error listing jobs: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "toggle_job",
+    description: "Enable or disable a scheduled job without deleting it.",
+    parameters: {
+      type: "object",
+      properties: {
+        job_id: { type: "string", description: "The job ID to toggle" },
+        enabled: { type: "boolean", description: "true to enable, false to disable" },
+      },
+      required: ["job_id", "enabled"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.cronStore) return "Error: cron store not available";
+      try {
+        const task = await context.cronStore.getTask(input.job_id);
+        if (!task) return `Error: job ${input.job_id} not found.`;
+        if (task.name === 'heartbeat') return "Error: cannot modify system jobs.";
+        await context.cronStore.toggleTask(input.job_id, input.enabled);
+        return `Job ${input.job_id} ${input.enabled ? 'enabled' : 'disabled'}.`;
+      } catch (err) {
+        return `Error toggling job: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "cancel_job",
+    description: "Cancel/delete a scheduled job by its ID.",
+    parameters: {
+      type: "object",
+      properties: {
+        job_id: {
+          type: "string",
+          description: "The job ID to cancel",
+        },
+      },
+      required: ["job_id"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.cronStore) return "Error: cron store not available";
+      try {
+        const task = await context.cronStore.getTask(input.job_id);
+        if (!task) return `Error: job ${input.job_id} not found.`;
+        if (task.name === 'heartbeat') return "Error: cannot delete system jobs.";
+        await context.cronStore.deleteTask(input.job_id);
+        return `Job ${input.job_id} cancelled.`;
+      } catch (err) {
+        return `Error cancelling job: ${err.message}`;
+      }
+    },
+  },
+];
+
+// Backwards compatibility alias
+export const cronTools = jobTools;

package/tools/memory.js

@@ -0,0 +1,332 @@
+// agent/memory.js
+// Agent memory tools that write to the shared Memory collection via memoryStore.
+// Uses SQLiteMemoryStore or any compatible store implementation.
+
+/**
+ * Generate a slug-style key from content text.
+ * Takes the first ~50 characters, strips non-alphanumeric chars, and joins with underscores.
+ *
+ * @param {string} content - Raw content string
+ * @returns {string} Cleaned key like "users_favorite_color_is_blue"
+ */
+function generateMemoryKey(content) {
+  return content
+    .slice(0, 50)
+    .replace(/[^a-zA-Z0-9 ]/g, "")
+    .trim()
+    .replace(/\s+/g, "_")
+    .toLowerCase();
+}
+
+// ── Tool definitions for the agent ──
+
+export const memoryTools = [
+  {
+    name: "memory_save",
+    description:
+      "Save an important fact, preference, or piece of information to long-term memory. Use this when the user tells you something worth remembering for future conversations — their name, preferences, projects, goals, important dates, etc. Be selective: only save things that would be useful to recall later.",
+    parameters: {
+      type: "object",
+      properties: {
+        content: {
+          type: "string",
+          description:
+            "The information to remember. Write it as a clear, standalone fact. e.g. 'User's name is Steve. He is a full-stack developer based in SF.'",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Short tags for categorization. e.g. ['personal', 'name'] or ['project', 'dottie']",
+        },
+      },
+      required: ["content"],
+    },
+    /**
+     * Save a memory via memoryStore.writeMemory.
+     *
+     * @param {Object} input - Tool input with content and optional tags
+     * @param {AbortSignal} signal - Abort signal
+     * @param {Object} context - { userID, memoryStore }
+     * @returns {Promise<string>} Confirmation message
+     */
+    execute: async (input, signal, context) => {
+      try {
+        const { userID, memoryStore } = context;
+        if (!memoryStore) {
+          return "Error: memoryStore not configured. Memory features are disabled.";
+        }
+        const key = generateMemoryKey(input.content);
+        const value = {
+          content: input.content,
+          tags: input.tags || [],
+          source: "agent",
+        };
+        await memoryStore.writeMemory(userID, key, value, "agent");
+        return `Saved to memory: "${input.content}"`;
+      } catch (err) {
+        return `Error saving memory: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "memory_search",
+    description:
+      "Search long-term memory for previously saved information. Use this when the user references something from a past conversation, asks 'do you remember...', or when context from past interactions would help you give a better answer.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "What to search for in memory. Use keywords related to the topic.",
+        },
+      },
+      required: ["query"],
+    },
+    /**
+     * Search memories via memoryStore.readMemoryPattern and filter by query.
+     *
+     * @param {Object} input - Tool input with query string
+     * @param {AbortSignal} signal - Abort signal
+     * @param {Object} context - { userID, memoryStore }
+     * @returns {Promise<string>} Formatted search results or "no matches" message
+     */
+    execute: async (input, signal, context) => {
+      try {
+        const { userID, memoryStore } = context;
+        if (!memoryStore) {
+          return "Error: memoryStore not configured. Memory features are disabled.";
+        }
+        const all = await memoryStore.readMemoryPattern(userID, ".*");
+
+        const query = input.query.toLowerCase();
+        const matches = all
+          .filter((m) => {
+            const valStr =
+              typeof m.value === "object"
+                ? JSON.stringify(m.value)
+                : String(m.value);
+            return (
+              m.key.toLowerCase().includes(query) ||
+              valStr.toLowerCase().includes(query)
+            );
+          })
+          .slice(0, 5);
+
+        if (matches.length === 0) {
+          return "No matching memories found.";
+        }
+
+        return matches
+          .map((m, i) => {
+            const content =
+              typeof m.value === "object" && m.value.content
+                ? m.value.content
+                : JSON.stringify(m.value);
+            const tags =
+              typeof m.value === "object" && m.value.tags?.length
+                ? `\n   tags: ${m.value.tags.join(", ")}`
+                : "";
+            const saved = m.updated_at
+              ? `\n   saved: ${new Date(m.updated_at).toISOString()}`
+              : "";
+            return `${i + 1}. ${content}${tags}${saved}`;
+          })
+          .join("\n\n");
+      } catch (err) {
+        return `Error searching memory: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "memory_delete",
+    description:
+      "Delete a specific memory by its key. Use this when the user asks to forget something or remove outdated information.",
+    parameters: {
+      type: "object",
+      properties: {
+        key: {
+          type: "string",
+          description: "The memory key to delete. Use memory_search first to find the key.",
+        },
+      },
+      required: ["key"],
+    },
+    /**
+     * Delete a memory via memoryStore.deleteMemory.
+     *
+     * @param {Object} input - Tool input with key
+     * @param {AbortSignal} signal - Abort signal
+     * @param {Object} context - { userID, memoryStore }
+     * @returns {Promise<string>} Confirmation message
+     */
+    execute: async (input, signal, context) => {
+      try {
+        const { userID, memoryStore } = context;
+        if (!memoryStore) {
+          return "Error: memoryStore not configured. Memory features are disabled.";
+        }
+        const result = await memoryStore.deleteMemory(userID, input.key);
+        return result.deletedCount > 0 ? `Memory "${input.key}" deleted.` : "Memory not found.";
+      } catch (err) {
+        return `Error deleting memory: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "memory_list",
+    description:
+      "List all memories saved in the knowledge graph. Returns all memory keys and their content. Use this when you need to see everything that's stored, or when the user asks 'what do you remember about me' or 'show me all my memories'.",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+    /**
+     * List all memories via memoryStore.readMemoryPattern.
+     *
+     * @param {Object} input - Tool input (empty)
+     * @param {AbortSignal} signal - Abort signal
+     * @param {Object} context - { userID, memoryStore }
+     * @returns {Promise<string>} Formatted list of all memories
+     */
+    execute: async (input, signal, context) => {
+      try {
+        const { userID, memoryStore } = context;
+        if (!memoryStore) {
+          return "Error: memoryStore not configured. Memory features are disabled.";
+        }
+        const all = await memoryStore.readMemoryPattern(userID, ".*");
+
+        if (all.length === 0) {
+          return "No memories found.";
+        }
+
+        return `Found ${all.length} ${all.length === 1 ? 'memory' : 'memories'}:\n\n` +
+          all.map((m, i) => {
+            const content =
+              typeof m.value === "object" && m.value.content
+                ? m.value.content
+                : JSON.stringify(m.value);
+            const tags =
+              typeof m.value === "object" && m.value.tags?.length
+                ? `\n   tags: ${m.value.tags.join(", ")}`
+                : "";
+            const saved = m.updated_at
+              ? `\n   saved: ${new Date(m.updated_at).toISOString()}`
+              : "";
+            return `${i + 1}. [${m.key}]\n   ${content}${tags}${saved}`;
+          }).join("\n\n");
+      } catch (err) {
+        return `Error listing memories: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "memory_read",
+    description:
+      "Read a specific memory by its exact key. Use this when you know the key and want to retrieve its full content.",
+    parameters: {
+      type: "object",
+      properties: {
+        key: {
+          type: "string",
+          description: "The exact memory key to read. Use memory_list or memory_search to find keys.",
+        },
+      },
+      required: ["key"],
+    },
+    /**
+     * Read a specific memory via memoryStore.readMemory.
+     *
+     * @param {Object} input - Tool input with key
+     * @param {AbortSignal} signal - Abort signal
+     * @param {Object} context - { userID, memoryStore }
+     * @returns {Promise<string>} Memory content or not found message
+     */
+    execute: async (input, signal, context) => {
+      try {
+        const { userID, memoryStore } = context;
+        if (!memoryStore) {
+          return "Error: memoryStore not configured. Memory features are disabled.";
+        }
+        const memory = await memoryStore.readMemory(userID, input.key);
+
+        if (!memory || !memory.value) {
+          return `Memory "${input.key}" not found.`;
+        }
+
+        const content =
+          typeof memory.value === "object" && memory.value.content
+            ? memory.value.content
+            : JSON.stringify(memory.value, null, 2);
+        const tags =
+          typeof memory.value === "object" && memory.value.tags?.length
+            ? `\ntags: ${memory.value.tags.join(", ")}`
+            : "";
+        const saved = memory.updated_at
+          ? `\nsaved: ${new Date(memory.updated_at).toISOString()}`
+          : "";
+        const app = memory.app_id ? `\nwritten by: ${memory.app_id}` : "";
+
+        return `[${input.key}]\n${content}${tags}${saved}${app}`;
+      } catch (err) {
+        return `Error reading memory: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "memory_update",
+    description:
+      "Update an existing memory or create a new one with a specific key. Use this when you need to modify existing information or when you want full control over the memory key (unlike memory_save which auto-generates keys).",
+    parameters: {
+      type: "object",
+      properties: {
+        key: {
+          type: "string",
+          description: "The memory key to update or create. Use snake_case like 'user_preferences' or 'project_notes'.",
+        },
+        content: {
+          type: "string",
+          description: "The new content to store. Can be plain text, markdown, or any string.",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional tags for categorization. e.g. ['personal', 'project']",
+        },
+      },
+      required: ["key", "content"],
+    },
+    /**
+     * Update or create a memory via memoryStore.writeMemory.
+     *
+     * @param {Object} input - Tool input with key, content, and optional tags
+     * @param {AbortSignal} signal - Abort signal
+     * @param {Object} context - { userID, memoryStore }
+     * @returns {Promise<string>} Confirmation message
+     */
+    execute: async (input, signal, context) => {
+      try {
+        const { userID, memoryStore } = context;
+        if (!memoryStore) {
+          return "Error: memoryStore not configured. Memory features are disabled.";
+        }
+        const value = {
+          content: input.content,
+          tags: input.tags || [],
+          source: "agent",
+        };
+        await memoryStore.writeMemory(userID, input.key, value, "agent");
+        return `Memory "${input.key}" saved.`;
+      } catch (err) {
+        return `Error updating memory: ${err.message}`;
+      }
+    },
+  },
+];