@stevederico/dotbot 0.16.0

package/tools/triggers.js

@@ -0,0 +1,159 @@
+/**
+ * Trigger Tools
+ *
+ * Event-driven agent responses. Triggers fire when specific events occur,
+ * injecting prompts into the agent conversation for context-aware assistance.
+ */
+
+export const triggerTools = [
+  {
+    name: "trigger_create",
+    description:
+      "Create an event-driven trigger that fires when a specific event occurs. " +
+      "Use cooldownMs to prevent spam (e.g., trigger max once per hour). " +
+      "Metadata can filter events (e.g., only fire for specific app names).",
+    parameters: {
+      type: "object",
+      properties: {
+        eventType: {
+          type: "string",
+          description: "Event type (user-defined string). Examples: app_opened, goal_completed, error_occurred, data_updated, task_completed, or any custom event",
+        },
+        prompt: {
+          type: "string",
+          description: "Prompt to inject into agent conversation when event fires",
+        },
+        cooldownMs: {
+          type: "number",
+          description: "Cooldown period in milliseconds (e.g., 3600000 for 1 hour). Default: 0 (no cooldown)",
+        },
+        metadata: {
+          type: "object",
+          description: "Optional metadata for filtering events (e.g., { appName: 'Mail' } for app_opened events)",
+        },
+      },
+      required: ["eventType", "prompt"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.triggerStore) return "Error: triggerStore not available";
+      try {
+        const trigger = await context.triggerStore.createTrigger({
+          userId: context.userID,
+          eventType: input.eventType,
+          prompt: input.prompt,
+          cooldownMs: input.cooldownMs || 0,
+          metadata: input.metadata || {},
+          enabled: true,
+        });
+
+        const cooldown = input.cooldownMs
+          ? ` (cooldown: ${Math.round(input.cooldownMs / 1000)}s)`
+          : '';
+        return `Trigger created for event "${input.eventType}"${cooldown}`;
+      } catch (err) {
+        return `Error creating trigger: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "trigger_list",
+    description: "List all triggers, optionally filtered by enabled status or event type.",
+    parameters: {
+      type: "object",
+      properties: {
+        enabled: {
+          type: "boolean",
+          description: "Filter by enabled status (optional)",
+        },
+        eventType: {
+          type: "string",
+          description: "Filter by event type (optional)",
+        },
+      },
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.triggerStore) return "Error: triggerStore not available";
+      try {
+        const filters = {};
+        if (input.enabled !== undefined) filters.enabled = input.enabled;
+        if (input.eventType) filters.eventType = input.eventType;
+
+        const triggers = await context.triggerStore.listTriggers(context.userID, filters);
+
+        if (triggers.length === 0) {
+          return input.enabled !== undefined || input.eventType
+            ? "No triggers found matching filters."
+            : "No triggers yet. Create one with trigger_create.";
+        }
+
+        return triggers.map((t, i) => {
+          const status = t.enabled ? '✓' : '✗';
+          const cooldown = t.cooldownMs ? ` (cooldown: ${Math.round(t.cooldownMs / 1000)}s)` : '';
+          const fires = t.fireCount > 0 ? ` [fired ${t.fireCount}x]` : '';
+          const meta = Object.keys(t.metadata || {}).length > 0
+            ? ` {${Object.entries(t.metadata).map(([k,v]) => `${k}:${v}`).join(', ')}}`
+            : '';
+          return `${status} ${t.eventType}${meta}${cooldown}${fires}\n   → "${t.prompt.slice(0, 60)}${t.prompt.length > 60 ? '...' : ''}"`;
+        }).join('\n\n');
+      } catch (err) {
+        return `Error listing triggers: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "trigger_toggle",
+    description: "Enable or disable a trigger without deleting it.",
+    parameters: {
+      type: "object",
+      properties: {
+        trigger_id: { type: "string", description: "The trigger ID to toggle" },
+        enabled: { type: "boolean", description: "true to enable, false to disable" },
+      },
+      required: ["trigger_id", "enabled"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.triggerStore) return "Error: triggerStore not available";
+      try {
+        const result = await context.triggerStore.toggleTrigger(
+          context.userID,
+          input.trigger_id,
+          input.enabled
+        );
+        if (result.modifiedCount > 0) {
+          return `Trigger ${input.trigger_id} ${input.enabled ? 'enabled' : 'disabled'}.`;
+        }
+        return "Trigger not found.";
+      } catch (err) {
+        return `Error toggling trigger: ${err.message}`;
+      }
+    },
+  },
+
+  {
+    name: "trigger_delete",
+    description: "Delete a trigger permanently.",
+    parameters: {
+      type: "object",
+      properties: {
+        trigger_id: { type: "string", description: "The trigger ID to delete" },
+      },
+      required: ["trigger_id"],
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.triggerStore) return "Error: triggerStore not available";
+      try {
+        const result = await context.triggerStore.deleteTrigger(
+          context.userID,
+          input.trigger_id
+        );
+        return result.deletedCount > 0
+          ? `Trigger ${input.trigger_id} deleted.`
+          : "Trigger not found.";
+      } catch (err) {
+        return `Error deleting trigger: ${err.message}`;
+      }
+    },
+  },
+];

package/tools/weather.js

@@ -0,0 +1,82 @@
+/**
+ * Weather tool using Open-Meteo API (no API key required)
+ */
+
+/**
+ * Convert WMO weather code to human-readable text.
+ * @param {number} code - WMO weather condition code
+ * @returns {string} Human-readable weather condition
+ */
+function weatherCodeToText(code) {
+  const codes = {
+    0: "Clear sky",
+    1: "Mainly clear", 2: "Partly cloudy", 3: "Overcast",
+    45: "Fog", 48: "Depositing rime fog",
+    51: "Light drizzle", 53: "Moderate drizzle", 55: "Dense drizzle",
+    56: "Light freezing drizzle", 57: "Dense freezing drizzle",
+    61: "Slight rain", 63: "Moderate rain", 65: "Heavy rain",
+    66: "Light freezing rain", 67: "Heavy freezing rain",
+    71: "Slight snow", 73: "Moderate snow", 75: "Heavy snow",
+    77: "Snow grains",
+    80: "Slight rain showers", 81: "Moderate rain showers", 82: "Violent rain showers",
+    85: "Slight snow showers", 86: "Heavy snow showers",
+    95: "Thunderstorm",
+    96: "Thunderstorm with slight hail", 99: "Thunderstorm with heavy hail"
+  };
+  return codes[code] || "Unknown";
+}
+
+export const weatherTools = [
+  {
+    name: "weather_get",
+    description: "Get the current weather for a location.",
+    parameters: {
+      type: "object",
+      properties: {
+        location: { type: "string", description: "City name or location" },
+      },
+      required: ["location"],
+    },
+    execute: async (input, signal) => {
+      try {
+        // Geocode location
+        const geoRes = await fetch(
+          `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(input.location)}&count=1`,
+          { signal }
+        );
+        if (!geoRes.ok) return `Geocoding failed: ${geoRes.status}`;
+        const geo = await geoRes.json();
+        if (!geo.results?.length) return `Location not found: ${input.location}`;
+        const { latitude, longitude, name, country } = geo.results[0];
+
+        // Fetch weather
+        const wxRes = await fetch(
+          `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,relative_humidity_2m,wind_speed_10m,weather_code&temperature_unit=fahrenheit&wind_speed_unit=mph`,
+          { signal }
+        );
+        if (!wxRes.ok) return `Weather fetch failed: ${wxRes.status}`;
+        const wx = await wxRes.json();
+        const c = wx.current;
+        return JSON.stringify({
+          _ui: {
+            component: "weather",
+            version: 1,
+            data: {
+              location: `${name}, ${country}`,
+              temperature: c.temperature_2m,
+              unit: "F",
+              humidity: c.relative_humidity_2m,
+              windSpeed: c.wind_speed_10m,
+              windUnit: "mph",
+              conditionCode: c.weather_code,
+              conditionText: weatherCodeToText(c.weather_code)
+            },
+            fallback: `Weather for ${name}: ${c.temperature_2m}°F, ${weatherCodeToText(c.weather_code)}`
+          }
+        });
+      } catch (err) {
+        return `Error getting weather: ${err.message}`;
+      }
+    },
+  },
+];

package/tools/web.js

@@ -0,0 +1,283 @@
+/**
+ * Web tools: search, fetch, grokipedia
+ */
+
+export const webTools = [
+  // ── Web Search (Grok Responses API with web_search tool, fallback to DuckDuckGo) ──
+  {
+    name: "web_search",
+    description:
+      "Search the web for current information. Use ONLY ONCE per question to find the right URL — then use browser_navigate to read the actual page. Never call this tool multiple times for the same topic. For live or dynamic content (scores, dashboards), always prefer browser_navigate over repeated searches.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "The search query",
+        },
+      },
+      required: ["query"],
+    },
+    execute: async (input, signal, context) => {
+      const apiKey = context?.providers?.xai?.apiKey;
+
+      // Primary: Use Grok Responses API with web_search tool
+      if (apiKey) {
+        try {
+          const res = await fetch("https://api.x.ai/v1/responses", {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+              model: "grok-4-1-fast",
+              input: [
+                {
+                  role: "system",
+                  content: "You are a helpful search assistant. Provide concise, factual answers with sources. Format results as numbered points.",
+                },
+                { role: "user", content: input.query },
+              ],
+              tools: [{ type: "web_search" }],
+            }),
+            signal,
+          });
+
+          if (res.ok) {
+            const data = await res.json();
+            const messageItem = (data.output || []).find(item => item.type === "message");
+            const contentItems = messageItem?.content || [];
+
+            const textContent = contentItems
+              .filter(c => c.type === "output_text")
+              .map(c => c.text)
+              .join("\n");
+
+            const citations = new Set();
+            for (const c of contentItems) {
+              if (c.annotations) {
+                for (const ann of c.annotations) {
+                  if (ann.type === "url_citation" && ann.url) {
+                    citations.add(ann.url);
+                  }
+                }
+              }
+            }
+
+            let result = textContent;
+            if (citations.size > 0) {
+              result += "\n\nSources:\n" + [...citations].slice(0, 5).map((url, i) => `${i + 1}. ${url}`).join("\n");
+            }
+
+            if (context?.databaseManager) {
+              try {
+                await context.databaseManager.logAgentActivity(
+                  context.dbConfig.dbType, context.dbConfig.db, context.dbConfig.connectionString,
+                  context.userID, { type: 'web_search', query: input.query, provider: 'grok', resultPreview: result.slice(0, 300) }
+                );
+              } catch (e) { /* best effort */ }
+            }
+
+            return result || "No results found.";
+          } else {
+            const errText = await res.text();
+            console.error("[web_search] Grok API error:", res.status, errText);
+          }
+        } catch (err) {
+          console.error("[web_search] Grok search failed:", err.message);
+          // Fall through to DuckDuckGo
+        }
+      }
+
+      // Fallback: DuckDuckGo Instant Answer API
+      const url = `https://api.duckduckgo.com/?q=${encodeURIComponent(input.query)}&format=json&no_html=1`;
+      const res = await fetch(url, {
+        headers: { "User-Agent": "DotBot/1.0" },
+        signal,
+      });
+
+      if (!res.ok) {
+        return `Search failed: ${res.status} ${res.statusText}`;
+      }
+
+      const data = await res.json();
+      const parts = [];
+
+      if (data.Abstract) {
+        parts.push(`${data.Abstract}${data.AbstractSource ? ` (${data.AbstractSource})` : ""}${data.AbstractURL ? `\n   ${data.AbstractURL}` : ""}`);
+      }
+
+      const topics = (data.RelatedTopics || []).filter((t) => t.Text && t.FirstURL);
+      for (let i = 0; i < Math.min(topics.length, 5); i++) {
+        const t = topics[i];
+        parts.push(`${parts.length + 1}. ${t.Text}\n   ${t.FirstURL}`);
+      }
+
+      if (parts.length === 0) {
+        return "No results found.";
+      }
+
+      const result = parts.join("\n\n");
+
+      if (context?.databaseManager) {
+        try {
+          await context.databaseManager.logAgentActivity(
+            context.dbConfig.dbType, context.dbConfig.db, context.dbConfig.connectionString,
+            context.userID, { type: 'web_search', query: input.query, provider: 'duckduckgo', resultPreview: parts.slice(0, 2).join('\n').slice(0, 300) }
+          );
+        } catch (e) { /* best effort */ }
+      }
+
+      return result;
+    },
+  },
+
+  // ── Grokipedia Search ──
+  {
+    name: "grokipedia_search",
+    description:
+      "Look up a topic on Grokipedia, a Wikipedia-like encyclopedia. Use this when the user asks to look something up on Grokipedia or wants an encyclopedic article.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "The topic to look up (e.g. 'JavaScript', 'Quantum computing')",
+        },
+      },
+      required: ["query"],
+    },
+    execute: async (input, signal, context) => {
+      try {
+        const url = `https://grokipedia.com/search?q=${encodeURIComponent(input.query)}`;
+        const res = await fetch(url, {
+          headers: { "User-Agent": "DotBot/1.0", Accept: "text/html" },
+          signal,
+        });
+
+        if (res.status === 404) {
+          return `No Grokipedia article found for: ${input.query}`;
+        }
+        if (!res.ok) {
+          return `Grokipedia fetch failed: ${res.status} ${res.statusText}`;
+        }
+
+        let text = await res.text();
+        text = text
+          .replace(/<script[\s\S]*?<\/script>/gi, "")
+          .replace(/<style[\s\S]*?<\/style>/gi, "")
+          .replace(/<[^>]+>/g, " ")
+          .replace(/\s+/g, " ")
+          .trim();
+
+        const maxChars = 8000;
+        if (text.length > maxChars) {
+          text = text.slice(0, maxChars) + `\n\n... [truncated, ${text.length} chars total]`;
+        }
+
+        if (context?.databaseManager) {
+          try {
+            await context.databaseManager.logAgentActivity(
+              context.dbConfig.dbType, context.dbConfig.db, context.dbConfig.connectionString,
+              context.userID, { type: 'grokipedia_search', query: input.query, url }
+            );
+          } catch (e) { /* best effort */ }
+        }
+
+        return text;
+      } catch (err) {
+        return `Error looking up Grokipedia: ${err.message}`;
+      }
+    },
+  },
+
+  // ── Web Fetch ──
+  {
+    name: "web_fetch",
+    description:
+      "Make an HTTP request and return the response. Supports GET, POST, PUT, PATCH, and DELETE. Use this to read web pages, call APIs, or send data to external services.",
+    parameters: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "The URL to fetch",
+        },
+        method: {
+          type: "string",
+          enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+          description: "HTTP method (default GET)",
+        },
+        body: {
+          type: "string",
+          description: "Request body as a JSON string (for POST/PUT/PATCH)",
+        },
+        headers: {
+          type: "object",
+          description: "Additional request headers (e.g. { \"Authorization\": \"Bearer ...\" })",
+        },
+      },
+      required: ["url"],
+    },
+    execute: async (input, signal, context) => {
+      try {
+        const method = (input.method || "GET").toUpperCase();
+        const reqHeaders = {
+          "User-Agent": "DotBot/1.0",
+          Accept: "text/html,application/json,text/plain",
+          ...(input.headers || {}),
+        };
+
+        if (input.body && !reqHeaders["Content-Type"] && !reqHeaders["content-type"]) {
+          reqHeaders["Content-Type"] = "application/json";
+        }
+
+        const fetchOptions = { method, headers: reqHeaders, signal };
+        if (input.body && method !== "GET") {
+          fetchOptions.body = input.body;
+        }
+
+        const res = await fetch(input.url, fetchOptions);
+
+        if (!res.ok) {
+          return `Fetch failed: ${res.status} ${res.statusText}`;
+        }
+
+        const contentType = res.headers.get("content-type") || "";
+        let text;
+
+        if (contentType.includes("application/json")) {
+          const json = await res.json();
+          text = JSON.stringify(json, null, 2);
+        } else {
+          text = await res.text();
+          text = text
+            .replace(/<script[\s\S]*?<\/script>/gi, "")
+            .replace(/<style[\s\S]*?<\/style>/gi, "")
+            .replace(/<[^>]+>/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+        }
+
+        if (context?.databaseManager) {
+          try {
+            await context.databaseManager.logAgentActivity(
+              context.dbConfig.dbType, context.dbConfig.db, context.dbConfig.connectionString,
+              context.userID, { type: 'web_fetch', url: input.url, status: res.status }
+            );
+          } catch (e) { /* best effort */ }
+        }
+
+        const maxChars = 8000;
+        if (text.length > maxChars) {
+          return text.slice(0, maxChars) + `\n\n... [truncated, ${text.length} chars total]`;
+        }
+
+        return text;
+      } catch (err) {
+        return `Error fetching URL: ${err.message}`;
+      }
+    },
+  },
+];

package/utils/providers.js

@@ -0,0 +1,136 @@
+/**
+ * AI provider registry for the agent library
+ *
+ * Provider configuration schema without environment variable coupling.
+ * API keys and base URLs should be injected at runtime via createAgent().
+ */
+
+/**
+ * Registry of supported AI providers.
+ *
+ * Each provider defines its API URL, default model, available models,
+ * header construction, request/response formatting, and endpoint path.
+ */
+export const AI_PROVIDERS = {
+  anthropic: {
+    id: 'anthropic',
+    name: 'Anthropic',
+    envKey: 'ANTHROPIC_API_KEY',
+    apiUrl: 'https://api.anthropic.com/v1',
+    defaultModel: 'claude-sonnet-4-5',
+    models: [
+      { id: 'claude-sonnet-4-5', name: 'Claude Sonnet 4.5' },
+      { id: 'claude-opus-4-1-20250805', name: 'Claude Opus 4.1' },
+      { id: 'claude-sonnet-4-20250514', name: 'Claude Sonnet 4' },
+      { id: 'claude-3-7-sonnet-20250219', name: 'Claude Sonnet 3.7' },
+      { id: 'claude-3-5-haiku-20241022', name: 'Claude Haiku 3.5' }
+    ],
+    headers: (apiKey) => ({
+      'x-api-key': apiKey,
+      'anthropic-version': '2025-04-14',
+      'Content-Type': 'application/json'
+    }),
+    endpoint: '/messages',
+    formatRequest: (messages, model) => ({
+      model,
+      max_tokens: 4096,
+      messages
+    }),
+    formatResponse: (data) => data.content?.[0]?.text
+  },
+  openai: {
+    id: 'openai',
+    name: 'OpenAI',
+    envKey: 'OPENAI_API_KEY',
+    apiUrl: 'https://api.openai.com/v1',
+    defaultModel: 'gpt-4o',
+    models: [
+      { id: 'gpt-5', name: 'GPT-5' },
+      { id: 'gpt-5-mini', name: 'GPT-5 Mini' },
+      { id: 'gpt-5-nano', name: 'GPT-5 Nano' },
+      { id: 'gpt-4.1', name: 'GPT-4.1' },
+      { id: 'gpt-4.1-nano', name: 'GPT-4.1 Nano' },
+      { id: 'gpt-4o', name: 'GPT-4o' }
+    ],
+    headers: (apiKey) => ({
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json'
+    }),
+    endpoint: '/chat/completions',
+    formatRequest: (messages, model) => ({
+      model,
+      messages
+    }),
+    formatResponse: (data) => data.choices?.[0]?.message?.content
+  },
+  xai: {
+    id: 'xai',
+    name: 'xAI',
+    envKey: 'XAI_API_KEY',
+    apiUrl: 'https://api.x.ai/v1',
+    defaultModel: 'grok-4-1-fast-reasoning',
+    models: [
+      { id: 'grok-4-1-fast-reasoning', name: 'Grok 4.1 Fast Reasoning' },
+      { id: 'grok-4-1-fast-non-reasoning', name: 'Grok 4.1 Fast' },
+      { id: 'grok-4-fast-reasoning', name: 'Grok 4 Fast Reasoning' },
+      { id: 'grok-4-fast-non-reasoning', name: 'Grok 4 Fast' },
+      { id: 'grok-4-0709', name: 'Grok 4' },
+      { id: 'grok-code-fast-1', name: 'Grok Code Fast' },
+      { id: 'grok-3', name: 'Grok 3' },
+      { id: 'grok-3-mini', name: 'Grok 3 Mini' },
+      { id: 'grok-2-vision-1212', name: 'Grok 2 Vision' }
+    ],
+    headers: (apiKey) => ({
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json'
+    }),
+    endpoint: '/chat/completions',
+    formatRequest: (messages, model) => ({
+      model,
+      messages,
+      temperature: 0.7,
+      max_tokens: 4096
+    }),
+    formatResponse: (data) => data.choices?.[0]?.message?.content
+  },
+  cerebras: {
+    id: 'cerebras',
+    name: 'Cerebras',
+    envKey: 'CEREBRAS_API_KEY',
+    apiUrl: 'https://api.cerebras.ai/v1',
+    defaultModel: 'qwen-3-235b-a22b-instruct-2507',
+    models: [
+      { id: 'llama3.1-8b', name: 'Llama 3.1 8B' },
+      { id: 'qwen-3-235b-a22b-instruct-2507', name: 'Qwen 3 235B' },
+      { id: 'gpt-oss-120b', name: 'GPT-OSS 120B' },
+      { id: 'zai-glm-4.7', name: 'ZAI GLM 4.7' },
+    ],
+    headers: (apiKey) => ({
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json'
+    }),
+    endpoint: '/chat/completions',
+    formatRequest: (messages, model) => ({
+      model,
+      messages
+    }),
+    formatResponse: (data) => data.choices?.[0]?.message?.content
+  },
+  ollama: {
+    id: 'ollama',
+    name: 'Ollama (Local)',
+    apiUrl: 'http://localhost:11434/v1',
+    defaultModel: 'gpt-oss:20b',
+    models: [],
+    local: true,
+    headers: () => ({
+      'Content-Type': 'application/json'
+    }),
+    endpoint: '/chat/completions',
+    formatRequest: (messages, model) => ({
+      model,
+      messages
+    }),
+    formatResponse: (data) => data.choices?.[0]?.message?.content
+  },
+};