squidclaw 0.1.0 → 0.2.1

package/lib/ai/prompt-builder.js

@@ -147,3 +147,10 @@ You are ${agent.name || 'an AI assistant'}.
     }
   }
 }
+
+/**
+ * Add tool descriptions to an existing system prompt
+ */
+PromptBuilder.prototype.addToolContext = function(systemPrompt, toolDescriptions) {
+  return systemPrompt + '\n\n' + toolDescriptions;
+};

package/lib/api/server.js

@@ -233,3 +233,41 @@ export function createAPIServer(engine) {
 
   return app;
 }
+
+// ── Knowledge Upload (enhanced) ──
+export function addKnowledgeRoutes(app, engine) {
+  app.post('/api/agents/:id/knowledge', async (req, res) => {
+    const { filename, fileType, content } = req.body;
+    if (!content) return res.status(400).json({ error: 'content required' });
+
+    try {
+      const result = await engine.knowledgeBase.ingest(req.params.id, filename || 'upload.' + (fileType || 'txt'), content);
+      res.json({ status: 'ingested', docId: result.docId, chunks: result.chunks });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/agents/:id/knowledge/url', async (req, res) => {
+    const { url } = req.body;
+    if (!url) return res.status(400).json({ error: 'url required' });
+
+    try {
+      const result = await engine.knowledgeBase.ingestURL(req.params.id, url);
+      res.json({ status: 'ingested', docId: result.docId, chunks: result.chunks });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // Tool test endpoint
+  app.post('/api/tools/search', async (req, res) => {
+    const { query } = req.body;
+    try {
+      const results = await engine.toolRouter.browser.search(query);
+      res.json(results);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+}

package/lib/channels/telegram/bot.js

@@ -0,0 +1,196 @@
+/**
+ * 🦑 Telegram Bot Channel
+ * Multi-agent Telegram bot support
+ */
+
+import { logger } from '../../core/logger.js';
+
+export class TelegramManager {
+  constructor(config, agentManager) {
+    this.config = config;
+    this.agentManager = agentManager;
+    this.bots = new Map(); // agentId → { bot, status }
+    this.onMessage = null;
+  }
+
+  /**
+   * Start a Telegram bot for an agent
+   */
+  async startBot(agentId, botToken) {
+    if (this.bots.has(agentId)) {
+      const existing = this.bots.get(agentId);
+      if (existing.status === 'running') return existing;
+    }
+
+    try {
+      // Dynamic import grammy
+      const { Bot } = await import('grammy');
+      const bot = new Bot(botToken);
+
+      const botInfo = { agentId, bot, status: 'starting' };
+      this.bots.set(agentId, botInfo);
+
+      // Handle text messages
+      bot.on('message:text', async (ctx) => {
+        const contactId = `tg_${ctx.from.id}`;
+        const message = ctx.message.text;
+        const metadata = {
+          pushName: ctx.from.first_name || ctx.from.username || 'User',
+          messageId: ctx.message.message_id.toString(),
+          isGroup: ctx.chat.type !== 'private',
+          platform: 'telegram',
+          chatId: ctx.chat.id,
+          _ctx: ctx,
+        };
+
+        if (this.onMessage) {
+          await this.onMessage(agentId, contactId, message, metadata);
+        }
+      });
+
+      // Handle voice messages
+      bot.on('message:voice', async (ctx) => {
+        const contactId = `tg_${ctx.from.id}`;
+        const metadata = {
+          pushName: ctx.from.first_name,
+          messageId: ctx.message.message_id.toString(),
+          mediaType: 'audio',
+          platform: 'telegram',
+          _ctx: ctx,
+        };
+
+        if (this.onMessage) {
+          await this.onMessage(agentId, contactId, '[🎤 Voice note]', metadata);
+        }
+      });
+
+      // Handle photos
+      bot.on('message:photo', async (ctx) => {
+        const contactId = `tg_${ctx.from.id}`;
+        const caption = ctx.message.caption || '';
+        const metadata = {
+          pushName: ctx.from.first_name,
+          messageId: ctx.message.message_id.toString(),
+          mediaType: 'image',
+          platform: 'telegram',
+          _ctx: ctx,
+        };
+
+        if (this.onMessage) {
+          await this.onMessage(agentId, contactId, `[📸 Image] ${caption}`, metadata);
+        }
+      });
+
+      // Handle documents
+      bot.on('message:document', async (ctx) => {
+        const contactId = `tg_${ctx.from.id}`;
+        const filename = ctx.message.document.file_name || 'file';
+        const metadata = {
+          pushName: ctx.from.first_name,
+          messageId: ctx.message.message_id.toString(),
+          mediaType: 'document',
+          platform: 'telegram',
+          _ctx: ctx,
+        };
+
+        if (this.onMessage) {
+          await this.onMessage(agentId, contactId, `[📄 Document: ${filename}]`, metadata);
+        }
+      });
+
+      // Start polling
+      bot.start({
+        onStart: () => {
+          botInfo.status = 'running';
+          logger.info('telegram', `✅ Agent ${agentId} Telegram bot started`);
+        },
+      });
+
+      bot.catch((err) => {
+        logger.error('telegram', `Bot error for ${agentId}: ${err.message}`);
+      });
+
+      return botInfo;
+    } catch (err) {
+      logger.error('telegram', `Failed to start bot for ${agentId}: ${err.message}`);
+      throw err;
+    }
+  }
+
+  /**
+   * Send a text message
+   */
+  async sendMessage(agentId, contactId, text, metadata = {}) {
+    const botInfo = this.bots.get(agentId);
+    if (!botInfo?.bot || botInfo.status !== 'running') {
+      throw new Error(`Telegram bot not running for agent ${agentId}`);
+    }
+
+    // Extract chat ID from contactId or metadata
+    const chatId = metadata.chatId || contactId.replace('tg_', '');
+    await botInfo.bot.api.sendMessage(chatId, text);
+  }
+
+  /**
+   * Send multiple messages with delays
+   */
+  async sendMessages(agentId, contactId, messages, metadata = {}, delayMs = 700) {
+    const chatId = metadata.chatId || contactId.replace('tg_', '');
+    const botInfo = this.bots.get(agentId);
+    if (!botInfo?.bot) return;
+
+    for (let i = 0; i < messages.length; i++) {
+      if (i > 0) {
+        // Show typing indicator
+        try { await botInfo.bot.api.sendChatAction(chatId, 'typing'); } catch {}
+        await new Promise(r => setTimeout(r, delayMs + Math.random() * 500 - 250));
+      }
+      await botInfo.bot.api.sendMessage(chatId, messages[i]);
+    }
+  }
+
+  /**
+   * Send a reaction
+   */
+  async sendReaction(agentId, contactId, messageId, emoji, metadata = {}) {
+    const botInfo = this.bots.get(agentId);
+    if (!botInfo?.bot) return;
+    const chatId = metadata.chatId || contactId.replace('tg_', '');
+    try {
+      await botInfo.bot.api.setMessageReaction(chatId, parseInt(messageId), [{ type: 'emoji', emoji }]);
+    } catch {} // Reactions might not be supported in all chats
+  }
+
+  /**
+   * Send voice note
+   */
+  async sendVoiceNote(agentId, contactId, audioBuffer, metadata = {}) {
+    const botInfo = this.bots.get(agentId);
+    if (!botInfo?.bot) return;
+    const chatId = metadata.chatId || contactId.replace('tg_', '');
+    const { InputFile } = await import('grammy');
+    await botInfo.bot.api.sendVoice(chatId, new InputFile(audioBuffer, 'voice.ogg'));
+  }
+
+  getStatuses() {
+    const statuses = {};
+    for (const [agentId, info] of this.bots) {
+      statuses[agentId] = { status: info.status, connected: info.status === 'running' };
+    }
+    return statuses;
+  }
+
+  async stopBot(agentId) {
+    const info = this.bots.get(agentId);
+    if (info?.bot) {
+      try { await info.bot.stop(); } catch {}
+      this.bots.delete(agentId);
+    }
+  }
+
+  async stopAll() {
+    for (const agentId of this.bots.keys()) {
+      await this.stopBot(agentId);
+    }
+  }
+}

package/lib/core/agent-tools-mixin.js

@@ -0,0 +1,109 @@
+/**
+ * 🦑 Agent Tools Mixin
+ * Enhances Agent with tool usage and knowledge base search
+ */
+
+import { logger } from './logger.js';
+
+/**
+ * Add tool support to an agent
+ */
+export function addToolSupport(agent, toolRouter, knowledgeBase) {
+  const originalProcessMessage = agent.processMessage.bind(agent);
+
+  agent.processMessage = async function(contactId, message, metadata = {}) {
+    // First, search knowledge base for relevant context
+    if (knowledgeBase) {
+      try {
+        const relevantChunks = await knowledgeBase.search(agent.id, message, 3);
+        if (relevantChunks.length > 0) {
+          metadata._knowledgeContext = relevantChunks.map(c => c.content).join('\n\n');
+        }
+      } catch (err) {
+        logger.warn('agent', `Knowledge search failed: ${err.message}`);
+      }
+    }
+
+    // Inject tool descriptions and knowledge into the prompt builder
+    const origBuild = agent.promptBuilder.build.bind(agent.promptBuilder);
+    agent.promptBuilder.build = async function(agentObj, cId, msg) {
+      let prompt = await origBuild(agentObj, cId, msg);
+      
+      // Add knowledge context
+      if (metadata._knowledgeContext) {
+        prompt += '\n\n## Relevant Knowledge\nUse this information to answer:\n\n' + metadata._knowledgeContext;
+      }
+
+      // Add tool descriptions
+      if (toolRouter) {
+        prompt += '\n\n' + toolRouter.getToolDescriptions();
+      }
+
+      return prompt;
+    };
+
+    // Call original process
+    const result = await originalProcessMessage(contactId, message, metadata);
+
+    // Restore original prompt builder
+    agent.promptBuilder.build = origBuild;
+
+    // Check if agent wants to use a tool
+    if (toolRouter && result.messages.length > 0) {
+      const fullResponse = result.messages.join('\n');
+      const toolResult = await toolRouter.processResponse(fullResponse, agent.id);
+
+      if (toolResult.toolUsed && toolResult.toolResult) {
+        // Agent used a tool — now call AI again with the tool result
+        logger.info('agent', `Tool ${toolResult.toolName} returned, calling AI again...`);
+
+        // Save the tool interaction
+        await agent.storage.saveMessage(agent.id, contactId, 'assistant', `[Using ${toolResult.toolName}...]`);
+        await agent.storage.saveMessage(agent.id, contactId, 'system', `Tool result: ${toolResult.toolResult}`);
+
+        // Call AI again with tool result context
+        const history = await agent.storage.getConversation(agent.id, contactId, 50);
+        let systemPrompt = await origBuild(agent, contactId, message);
+        if (metadata._knowledgeContext) {
+          systemPrompt += '\n\n## Relevant Knowledge\n' + metadata._knowledgeContext;
+        }
+
+        const messages = [
+          { role: 'system', content: systemPrompt },
+          ...history.map(h => ({ role: h.role === 'system' ? 'user' : h.role, content: h.content })),
+          { role: 'user', content: `[Tool result for ${toolResult.toolName}]:\n${toolResult.toolResult}\n\nNow respond to the user based on this information. Be natural, don't mention "tool" or "search results".` },
+        ];
+
+        try {
+          const aiResponse = await agent.aiGateway.chat(messages, {
+            model: agent.model,
+            fallbackChain: agent.fallbackChain,
+          });
+
+          await agent.storage.trackUsage(agent.id, aiResponse.model, aiResponse.inputTokens, aiResponse.outputTokens, aiResponse.costUsd);
+
+          const processed = agent.behaviorEngine.process(aiResponse.content);
+          const fullReply = processed.messages.join('\n');
+          if (fullReply) await agent.storage.saveMessage(agent.id, contactId, 'assistant', fullReply);
+
+          return {
+            messages: processed.messages,
+            reaction: processed.reaction || result.reaction,
+            handoff: processed.handoff || result.handoff,
+            usage: {
+              inputTokens: (result.usage?.inputTokens || 0) + aiResponse.inputTokens,
+              outputTokens: (result.usage?.outputTokens || 0) + aiResponse.outputTokens,
+              cost: (result.usage?.cost || 0) + aiResponse.costUsd,
+            },
+          };
+        } catch (err) {
+          logger.error('agent', `Tool follow-up AI call failed: ${err.message}`);
+          // Return the clean response without tool tag
+          return { ...result, messages: toolResult.cleanResponse ? [toolResult.cleanResponse] : result.messages };
+        }
+      }
+    }
+
+    return result;
+  };
+}

package/lib/engine.js

@@ -1,7 +1,10 @@
 /**
- * 🦑 Squidclaw Engine
  * Main entry point — starts all subsystems
  */
+import { KnowledgeBase } from "./memory/knowledge.js";
+import { ToolRouter } from "./tools/router.js";
+import { TelegramManager } from "./channels/telegram/bot.js";
+import { addToolSupport } from "./core/agent-tools-mixin.js";
 
 import { loadConfig, getHome, ensureHome } from './core/config.js';
 import { initLogger, logger } from './core/logger.js';
@@ -57,6 +60,21 @@ export class SquidclawEngine {
     const agents = this.agentManager.getAll();
     console.log(`  👥 Agents: ${agents.length} loaded`);
 
+    // 3b. Knowledge Base
+    this.knowledgeBase = new KnowledgeBase(this.storage, this.config);
+    console.log(`  📚 Knowledge Base: ready`);
+
+    // 3c. Tool Router
+    this.toolRouter = new ToolRouter(this.config, this.knowledgeBase);
+    const toolList = ["web search", "page reader"];
+    if (this.config.tools?.google?.oauthToken) toolList.push("calendar", "email");
+    console.log(`  🔧 Tools: ${toolList.join(", ")}`);
+
+    // 3d. Add tool support to all agents
+    for (const agent of agents) {
+      addToolSupport(agent, this.toolRouter, this.knowledgeBase);
+    }
+
     // 4. WhatsApp Manager
     this.whatsappManager = new WhatsAppManager(this.config, this.agentManager, this.home);
 

package/lib/memory/embeddings.js

@@ -0,0 +1,71 @@
+/**
+ * 🦑 Embeddings Engine
+ * Generate vector embeddings for knowledge base search
+ */
+
+import { logger } from '../core/logger.js';
+
+export class EmbeddingsEngine {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Generate embedding for a text chunk
+   * Tries providers in order: OpenAI → Google → Ollama → fallback to null
+   */
+  async embed(text) {
+    const openaiKey = this.config.ai?.providers?.openai?.key;
+    if (openaiKey) return this._openaiEmbed(text, openaiKey);
+
+    const googleKey = this.config.ai?.providers?.google?.key;
+    if (googleKey) return this._googleEmbed(text, googleKey);
+
+    // No embedding provider — use keyword search fallback
+    return null;
+  }
+
+  async embedBatch(texts) {
+    const results = [];
+    for (const text of texts) {
+      results.push(await this.embed(text));
+    }
+    return results;
+  }
+
+  async _openaiEmbed(text, apiKey) {
+    const res = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'authorization': `Bearer ${apiKey}` },
+      body: JSON.stringify({ model: 'text-embedding-3-small', input: text }),
+    });
+    if (!res.ok) throw new Error(`OpenAI embedding error: ${res.status}`);
+    const data = await res.json();
+    return new Float32Array(data.data[0].embedding);
+  }
+
+  async _googleEmbed(text, apiKey) {
+    const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=${apiKey}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ content: { parts: [{ text }] } }),
+    });
+    if (!res.ok) throw new Error(`Google embedding error: ${res.status}`);
+    const data = await res.json();
+    return new Float32Array(data.embedding.values);
+  }
+
+  /**
+   * Cosine similarity between two vectors
+   */
+  static cosineSimilarity(a, b) {
+    if (!a || !b) return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+  }
+}

package/lib/memory/knowledge.js

@@ -0,0 +1,212 @@
+/**
+ * 🦑 Knowledge Base
+ * Upload, chunk, embed, and search documents
+ */
+
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+import { logger } from '../core/logger.js';
+import { EmbeddingsEngine } from './embeddings.js';
+
+export class KnowledgeBase {
+  constructor(storage, config) {
+    this.storage = storage;
+    this.config = config;
+    this.embeddings = new EmbeddingsEngine(config);
+  }
+
+  /**
+   * Ingest a document — chunk it, embed it, store it
+   */
+  async ingest(agentId, filePath, content = null) {
+    const ext = extname(filePath).toLowerCase();
+    const filename = filePath.split('/').pop();
+
+    // Read content if not provided
+    if (!content) {
+      content = readFileSync(filePath, 'utf8');
+    }
+
+    // Parse based on file type
+    let text = content;
+    if (ext === '.pdf') {
+      text = await this._parsePDF(filePath);
+    } else if (ext === '.html' || ext === '.htm') {
+      text = this._parseHTML(content);
+    }
+    // .txt, .md, .csv — use content as-is
+
+    // Chunk the text
+    const chunks = this._chunk(text);
+    logger.info('knowledge', `Chunked "${filename}" into ${chunks.length} chunks`);
+
+    // Save document record
+    const docId = await this.storage.saveDocument(agentId, {
+      filename,
+      fileType: ext.slice(1),
+      fileSize: Buffer.byteLength(content, 'utf8'),
+    });
+
+    // Generate embeddings and save chunks
+    const chunkData = [];
+    for (const chunk of chunks) {
+      let embedding = null;
+      try {
+        embedding = await this.embeddings.embed(chunk);
+      } catch (err) {
+        logger.warn('knowledge', `Embedding failed for chunk: ${err.message}`);
+      }
+      chunkData.push({
+        content: chunk,
+        embedding: embedding ? Buffer.from(embedding.buffer) : null,
+      });
+    }
+
+    await this.storage.saveChunks(docId, agentId, chunkData);
+    logger.info('knowledge', `✅ "${filename}" ingested — ${chunks.length} chunks`);
+
+    return { docId, chunks: chunks.length };
+  }
+
+  /**
+   * Ingest from URL
+   */
+  async ingestURL(agentId, url) {
+    try {
+      const res = await fetch(url);
+      const html = await res.text();
+      const text = this._parseHTML(html);
+      const filename = new URL(url).hostname + new URL(url).pathname.replace(/\//g, '_');
+
+      const docId = await this.storage.saveDocument(agentId, {
+        filename: filename.slice(0, 100),
+        fileType: 'url',
+        fileSize: Buffer.byteLength(text, 'utf8'),
+      });
+
+      const chunks = this._chunk(text);
+      const chunkData = [];
+      for (const chunk of chunks) {
+        let embedding = null;
+        try { embedding = await this.embeddings.embed(chunk); } catch {}
+        chunkData.push({ content: chunk, embedding: embedding ? Buffer.from(embedding.buffer) : null });
+      }
+
+      await this.storage.saveChunks(docId, agentId, chunkData);
+      return { docId, chunks: chunks.length };
+    } catch (err) {
+      throw new Error(`Failed to ingest URL: ${err.message}`);
+    }
+  }
+
+  /**
+   * Search knowledge base for relevant chunks
+   */
+  async search(agentId, query, limit = 5) {
+    // Try vector search first
+    let queryEmbedding = null;
+    try {
+      queryEmbedding = await this.embeddings.embed(query);
+    } catch {}
+
+    if (queryEmbedding) {
+      return this._vectorSearch(agentId, queryEmbedding, limit);
+    }
+
+    // Fallback to keyword search
+    return this._keywordSearch(agentId, query, limit);
+  }
+
+  async _vectorSearch(agentId, queryEmbedding, limit) {
+    // Get all chunks for this agent and compute similarity
+    const allChunks = await this.storage.searchKnowledge(agentId, null, 1000);
+    const scored = [];
+
+    for (const chunk of allChunks) {
+      if (chunk.embedding) {
+        const chunkEmb = new Float32Array(chunk.embedding.buffer || chunk.embedding);
+        const score = EmbeddingsEngine.cosineSimilarity(queryEmbedding, chunkEmb);
+        scored.push({ content: chunk.content, score });
+      } else {
+        scored.push({ content: chunk.content, score: 0 });
+      }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit).filter(s => s.score > 0.3);
+  }
+
+  async _keywordSearch(agentId, query, limit) {
+    // Simple keyword matching
+    const words = query.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+    const allChunks = await this.storage.searchKnowledge(agentId, null, 1000);
+    const scored = [];
+
+    for (const chunk of allChunks) {
+      const lower = chunk.content.toLowerCase();
+      let score = 0;
+      for (const word of words) {
+        if (lower.includes(word)) score++;
+      }
+      if (score > 0) scored.push({ content: chunk.content, score: score / words.length });
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit);
+  }
+
+  /**
+   * Chunk text into ~500 char segments with overlap
+   */
+  _chunk(text, chunkSize = 500, overlap = 50) {
+    const chunks = [];
+    const paragraphs = text.split(/\n\n+/);
+    let current = '';
+
+    for (const para of paragraphs) {
+      if ((current + '\n\n' + para).length > chunkSize && current) {
+        chunks.push(current.trim());
+        // Keep overlap
+        const words = current.split(' ');
+        current = words.slice(-Math.floor(overlap / 5)).join(' ') + '\n\n' + para;
+      } else {
+        current = current ? current + '\n\n' + para : para;
+      }
+    }
+    if (current.trim()) chunks.push(current.trim());
+
+    return chunks.length > 0 ? chunks : [text.trim()];
+  }
+
+  async _parsePDF(filePath) {
+    try {
+      const pdfjsLib = await import('pdfjs-dist/legacy/build/pdf.mjs');
+      const data = new Uint8Array(readFileSync(filePath));
+      const doc = await pdfjsLib.getDocument({ data }).promise;
+      const pages = [];
+      for (let i = 1; i <= doc.numPages; i++) {
+        const page = await doc.getPage(i);
+        const content = await page.getTextContent();
+        pages.push(content.items.map(item => item.str).join(' '));
+      }
+      return pages.join('\n\n');
+    } catch (err) {
+      logger.warn('knowledge', `PDF parsing failed: ${err.message}`);
+      return readFileSync(filePath, 'utf8');
+    }
+  }
+
+  _parseHTML(html) {
+    try {
+      const { parseHTML } = require('linkedom');
+      const { document } = parseHTML(html);
+      // Remove scripts and styles
+      for (const el of document.querySelectorAll('script, style, nav, footer, header')) {
+        el.remove();
+      }
+      return document.body?.textContent?.replace(/\s+/g, ' ').trim() || html;
+    } catch {
+      return html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    }
+  }
+}

package/lib/tools/browser.js

@@ -0,0 +1,105 @@
+/**
+ * 🦑 Browser Tool
+ * Web search + page reading — no browser needed
+ */
+
+import { logger } from '../core/logger.js';
+
+export class BrowserTool {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Search the web using DuckDuckGo (no API key needed)
+   */
+  async search(query, maxResults = 5) {
+    // Use DuckDuckGo HTML (no API key required)
+    const encoded = encodeURIComponent(query);
+    const res = await fetch(`https://html.duckduckgo.com/html/?q=${encoded}`, {
+      headers: { 'User-Agent': 'Squidclaw/0.1.0' },
+    });
+
+    if (!res.ok) throw new Error(`Search failed: ${res.status}`);
+    const html = await res.text();
+
+    // Parse results from HTML
+    const results = [];
+    const regex = /<a rel="nofollow" class="result__a" href="([^"]+)"[^>]*>(.+?)<\/a>[\s\S]*?<a class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
+    let match;
+    while ((match = regex.exec(html)) && results.length < maxResults) {
+      results.push({
+        url: match[1],
+        title: match[2].replace(/<[^>]+>/g, ''),
+        snippet: match[3].replace(/<[^>]+>/g, '').trim(),
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * Fetch and extract readable content from a URL
+   */
+  async readPage(url, maxLength = 5000) {
+    try {
+      const res = await fetch(url, {
+        headers: { 'User-Agent': 'Squidclaw/0.1.0' },
+        redirect: 'follow',
+      });
+
+      if (!res.ok) throw new Error(`Fetch failed: ${res.status}`);
+      const html = await res.text();
+
+      // Try Readability
+      try {
+        const { parseHTML } = await import('linkedom');
+        const { Readability } = await import('@mozilla/readability');
+        const { document } = parseHTML(html);
+        const reader = new Readability(document);
+        const article = reader.parse();
+        if (article?.textContent) {
+          return {
+            title: article.title,
+            content: article.textContent.slice(0, maxLength),
+            length: article.textContent.length,
+          };
+        }
+      } catch {}
+
+      // Fallback: strip HTML tags
+      const text = html.replace(/<script[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[\s\S]*?<\/style>/gi, '')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+
+      return {
+        title: html.match(/<title[^>]*>(.*?)<\/title>/i)?.[1] || url,
+        content: text.slice(0, maxLength),
+        length: text.length,
+      };
+    } catch (err) {
+      throw new Error(`Failed to read ${url}: ${err.message}`);
+    }
+  }
+
+  /**
+   * Search and summarize — search then read top result
+   */
+  async searchAndRead(query) {
+    const results = await this.search(query, 3);
+    if (results.length === 0) return { results: [], content: null };
+
+    // Try to read the first result
+    let content = null;
+    for (const result of results) {
+      try {
+        content = await this.readPage(result.url, 3000);
+        break;
+      } catch {}
+    }
+
+    return { results, content };
+  }
+}

package/lib/tools/calendar.js

@@ -0,0 +1,90 @@
+/**
+ * 🦑 Calendar Tool
+ * Google Calendar integration — read/create/update events
+ */
+
+import { logger } from '../core/logger.js';
+
+export class CalendarTool {
+  constructor(config) {
+    this.apiKey = config.tools?.google?.apiKey || config.ai?.providers?.google?.key;
+    this.calendarId = config.tools?.calendar?.calendarId || 'primary';
+    this.oauthToken = config.tools?.google?.oauthToken || null;
+  }
+
+  /**
+   * Get upcoming events
+   */
+  async getEvents(timeMin, timeMax, maxResults = 10) {
+    if (!this.oauthToken) throw new Error('Google OAuth token required for calendar. Set tools.google.oauthToken in config');
+
+    const params = new URLSearchParams({
+      timeMin: timeMin || new Date().toISOString(),
+      timeMax: timeMax || new Date(Date.now() + 7 * 86400000).toISOString(),
+      maxResults: maxResults.toString(),
+      singleEvents: 'true',
+      orderBy: 'startTime',
+    });
+
+    const res = await fetch(`https://www.googleapis.com/calendar/v3/calendars/${this.calendarId}/events?${params}`, {
+      headers: { 'Authorization': `Bearer ${this.oauthToken}` },
+    });
+
+    if (!res.ok) throw new Error(`Calendar API error: ${res.status}`);
+    const data = await res.json();
+
+    return (data.items || []).map(event => ({
+      id: event.id,
+      title: event.summary,
+      start: event.start?.dateTime || event.start?.date,
+      end: event.end?.dateTime || event.end?.date,
+      location: event.location,
+      description: event.description,
+      link: event.htmlLink,
+    }));
+  }
+
+  /**
+   * Create a new event
+   */
+  async createEvent(title, start, end, description = '', location = '') {
+    if (!this.oauthToken) throw new Error('Google OAuth token required');
+
+    const event = {
+      summary: title,
+      start: { dateTime: start, timeZone: 'UTC' },
+      end: { dateTime: end, timeZone: 'UTC' },
+      description,
+      location,
+    };
+
+    const res = await fetch(`https://www.googleapis.com/calendar/v3/calendars/${this.calendarId}/events`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.oauthToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(event),
+    });
+
+    if (!res.ok) throw new Error(`Calendar API error: ${res.status}`);
+    return res.json();
+  }
+
+  /**
+   * Get today's summary (for heartbeat)
+   */
+  async getTodaySummary() {
+    const now = new Date();
+    const endOfDay = new Date(now);
+    endOfDay.setHours(23, 59, 59);
+
+    const events = await this.getEvents(now.toISOString(), endOfDay.toISOString());
+    if (events.length === 0) return 'No more events today';
+
+    return events.map(e => {
+      const time = new Date(e.start).toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' });
+      return `${time} — ${e.title}${e.location ? ' @ ' + e.location : ''}`;
+    }).join('\n');
+  }
+}

package/lib/tools/email.js

@@ -0,0 +1,113 @@
+/**
+ * 🦑 Email Tool
+ * Read and send emails — Gmail API or generic SMTP
+ */
+
+import { logger } from '../core/logger.js';
+
+export class EmailTool {
+  constructor(config) {
+    this.oauthToken = config.tools?.google?.oauthToken || null;
+    this.provider = config.tools?.email?.provider || 'gmail'; // gmail | smtp
+  }
+
+  /**
+   * Get unread emails
+   */
+  async getUnread(maxResults = 10) {
+    if (this.provider === 'gmail') return this._gmailUnread(maxResults);
+    throw new Error(`Email provider ${this.provider} not supported yet`);
+  }
+
+  async _gmailUnread(maxResults) {
+    if (!this.oauthToken) throw new Error('Google OAuth token required for email');
+
+    const res = await fetch(`https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is:unread&maxResults=${maxResults}`, {
+      headers: { 'Authorization': `Bearer ${this.oauthToken}` },
+    });
+    if (!res.ok) throw new Error(`Gmail API error: ${res.status}`);
+    const data = await res.json();
+
+    const emails = [];
+    for (const msg of (data.messages || []).slice(0, maxResults)) {
+      const detail = await fetch(`https://gmail.googleapis.com/gmail/v1/users/me/messages/${msg.id}?format=metadata&metadataHeaders=From&metadataHeaders=Subject`, {
+        headers: { 'Authorization': `Bearer ${this.oauthToken}` },
+      });
+      const d = await detail.json();
+      const headers = d.payload?.headers || [];
+      emails.push({
+        id: msg.id,
+        from: headers.find(h => h.name === 'From')?.value || 'unknown',
+        subject: headers.find(h => h.name === 'Subject')?.value || '(no subject)',
+        snippet: d.snippet,
+        date: new Date(parseInt(d.internalDate)).toISOString(),
+      });
+    }
+    return emails;
+  }
+
+  /**
+   * Read a specific email
+   */
+  async readEmail(messageId) {
+    if (!this.oauthToken) throw new Error('Google OAuth token required');
+
+    const res = await fetch(`https://gmail.googleapis.com/gmail/v1/users/me/messages/${messageId}`, {
+      headers: { 'Authorization': `Bearer ${this.oauthToken}` },
+    });
+    if (!res.ok) throw new Error(`Gmail API error: ${res.status}`);
+    const data = await res.json();
+
+    // Decode body
+    let body = data.snippet;
+    const parts = data.payload?.parts || [data.payload];
+    for (const part of parts) {
+      if (part?.mimeType === 'text/plain' && part.body?.data) {
+        body = Buffer.from(part.body.data, 'base64url').toString('utf8');
+        break;
+      }
+    }
+
+    const headers = data.payload?.headers || [];
+    return {
+      id: messageId,
+      from: headers.find(h => h.name === 'From')?.value,
+      to: headers.find(h => h.name === 'To')?.value,
+      subject: headers.find(h => h.name === 'Subject')?.value,
+      body,
+      date: new Date(parseInt(data.internalDate)).toISOString(),
+    };
+  }
+
+  /**
+   * Send an email
+   */
+  async sendEmail(to, subject, body) {
+    if (!this.oauthToken) throw new Error('Google OAuth token required');
+
+    const raw = Buffer.from(
+      `To: ${to}\r\nSubject: ${subject}\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n${body}`
+    ).toString('base64url');
+
+    const res = await fetch('https://gmail.googleapis.com/gmail/v1/users/me/messages/send', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.oauthToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ raw }),
+    });
+
+    if (!res.ok) throw new Error(`Gmail send error: ${res.status}`);
+    return res.json();
+  }
+
+  /**
+   * Get summary for heartbeat
+   */
+  async getSummary() {
+    const emails = await this.getUnread(5);
+    if (emails.length === 0) return 'No unread emails';
+    return emails.map(e => `📧 ${e.from.split('<')[0].trim()}: ${e.subject}`).join('\n');
+  }
+}

package/lib/tools/router.js

@@ -0,0 +1,134 @@
+/**
+ * 🦑 Tool Router
+ * Detects when an agent needs to use a tool and executes it
+ */
+
+import { BrowserTool } from './browser.js';
+import { CalendarTool } from './calendar.js';
+import { EmailTool } from './email.js';
+import { logger } from '../core/logger.js';
+
+export class ToolRouter {
+  constructor(config, knowledgeBase) {
+    this.config = config;
+    this.browser = new BrowserTool(config);
+    this.calendar = config.tools?.google?.oauthToken ? new CalendarTool(config) : null;
+    this.email = config.tools?.google?.oauthToken ? new EmailTool(config) : null;
+    this.knowledgeBase = knowledgeBase;
+  }
+
+  /**
+   * Get tool descriptions for the system prompt
+   */
+  getToolDescriptions() {
+    const tools = [
+      '## Available Tools',
+      'You can use tools by including special tags in your response:',
+      '',
+      '### Web Search',
+      '---TOOL:search:your search query---',
+      'Search the web for information. Use when you don\'t know something or need current info.',
+      '',
+      '### Read Web Page',
+      '---TOOL:read:https://example.com---',
+      'Read the content of a webpage.',
+      '',
+      '### Knowledge Base',
+      '---TOOL:knowledge:search query---',
+      'Search the agent\'s uploaded knowledge base for relevant information.',
+    ];
+
+    if (this.calendar) {
+      tools.push('', '### Calendar', '---TOOL:calendar:today--- or ---TOOL:calendar:week---',
+        'Check upcoming calendar events.');
+      tools.push('', '### Create Event', '---TOOL:calendar_create:title|2026-03-05T10:00:00|2026-03-05T11:00:00|description---',
+        'Create a new calendar event.');
+    }
+
+    if (this.email) {
+      tools.push('', '### Check Email', '---TOOL:email:unread---',
+        'Check for unread emails.');
+      tools.push('', '### Send Email', '---TOOL:email_send:to@example.com|Subject|Body text---',
+        'Send an email.');
+    }
+
+    tools.push('', '**Important:** Use tools when needed. The tool result will be injected into the conversation automatically. Only use one tool per response.');
+
+    return tools.join('\n');
+  }
+
+  /**
+   * Process AI response — extract and execute tool calls
+   * Returns: { toolUsed, toolResult, cleanResponse }
+   */
+  async processResponse(response, agentId) {
+    const toolMatch = response.match(/---TOOL:(\w+):(.+?)---/);
+    if (!toolMatch) return { toolUsed: false, toolResult: null, cleanResponse: response };
+
+    const [fullMatch, toolName, toolArg] = toolMatch;
+    const cleanResponse = response.replace(fullMatch, '').trim();
+
+    logger.info('tools', `Agent using tool: ${toolName} — ${toolArg}`);
+
+    let toolResult = null;
+    try {
+      switch (toolName) {
+        case 'search':
+          const results = await this.browser.search(toolArg, 5);
+          toolResult = results.map(r => `• ${r.title}\n  ${r.snippet}\n  ${r.url}`).join('\n\n');
+          break;
+
+        case 'read':
+          const page = await this.browser.readPage(toolArg, 3000);
+          toolResult = `Title: ${page.title}\n\n${page.content}`;
+          break;
+
+        case 'knowledge':
+          if (this.knowledgeBase) {
+            const chunks = await this.knowledgeBase.search(agentId, toolArg, 5);
+            toolResult = chunks.map(c => c.content).join('\n\n---\n\n');
+          } else {
+            toolResult = 'No knowledge base configured';
+          }
+          break;
+
+        case 'calendar':
+          if (!this.calendar) { toolResult = 'Calendar not configured'; break; }
+          if (toolArg === 'today') {
+            toolResult = await this.calendar.getTodaySummary();
+          } else {
+            const events = await this.calendar.getEvents();
+            toolResult = events.map(e => `${e.start} — ${e.title}`).join('\n');
+          }
+          break;
+
+        case 'calendar_create':
+          if (!this.calendar) { toolResult = 'Calendar not configured'; break; }
+          const [title, start, end, desc] = toolArg.split('|');
+          await this.calendar.createEvent(title, start, end, desc);
+          toolResult = `Event "${title}" created`;
+          break;
+
+        case 'email':
+          if (!this.email) { toolResult = 'Email not configured'; break; }
+          toolResult = await this.email.getSummary();
+          break;
+
+        case 'email_send':
+          if (!this.email) { toolResult = 'Email not configured'; break; }
+          const [to, subject, body] = toolArg.split('|');
+          await this.email.sendEmail(to, subject, body);
+          toolResult = `Email sent to ${to}`;
+          break;
+
+        default:
+          toolResult = `Unknown tool: ${toolName}`;
+      }
+    } catch (err) {
+      toolResult = `Tool error: ${err.message}`;
+      logger.error('tools', `Tool ${toolName} failed: ${err.message}`);
+    }
+
+    return { toolUsed: true, toolResult, cleanResponse, toolName };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squidclaw",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "🦑 AI agent platform — human-like agents for WhatsApp, Telegram & more",
   "main": "lib/engine.js",
   "bin": {
@@ -12,7 +12,15 @@
     "test": "vitest",
     "dev": "node --watch lib/engine.js"
   },
-  "keywords": ["ai", "agent", "whatsapp", "chatbot", "claude", "openai", "squidclaw"],
+  "keywords": [
+    "ai",
+    "agent",
+    "whatsapp",
+    "chatbot",
+    "claude",
+    "openai",
+    "squidclaw"
+  ],
   "author": "Squidclaw",
   "license": "MIT",
   "homepage": "https://squidclaw.dev",
@@ -24,10 +32,10 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@whiskeysockets/baileys": "^7.0.0-rc.9",
-    "@hapi/boom": "^10.0.1",
     "@clack/prompts": "^1.0.1",
+    "@hapi/boom": "^10.0.1",
     "@mozilla/readability": "^0.6.0",
+    "@whiskeysockets/baileys": "^7.0.0-rc.9",
     "better-sqlite3": "^11.0.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -35,6 +43,7 @@
     "dotenv": "^17.3.1",
     "express": "^5.2.1",
     "file-type": "^21.3.0",
+    "grammy": "^1.40.1",
     "linkedom": "^0.18.12",
     "node-edge-tts": "^1.2.10",
     "pdfjs-dist": "^5.4.624",